#Why is calling Convex queries/mutations directly an anti-pattern?

1 messages · Page 1 of 1 (latest)

lusty vault
#

I'm currently working through refactoring my Convex queries and mutations to allow upgrading to 1.21, which throws a type error when you call Convex functions from other Convex functions.

The docs recommend relocating your functions into a model/ directory, and then importing and calling those functions from your Convex mutations and queries.

I have a few questions:

  1. Why is calling Convex functions from other functions an anti-pattern, specifically?
  2. The examples in the docs take the logic from the original query/mutation and relocate it to a new function in a directory called model/, and then import and call that function from the original mutation/query. I don't fully understand the rationale behind this, since now there are two separate files with similar/identical function names, and two places to test instead of one.
  3. For maintainability, is the recommendation to relocate all query and mutation logic into a separate function within model/? My first intuition was to only relocate the shared logic, but the docs seem to suggest otherwise?
Best Practices | Convex Developer Hub

This is a list of best practices and common anti-patterns around using Convex.

whole marshBOT
#

Thanks for posting in #1088161997662724167.
Reminder: If you have a Convex Pro account, use the Convex Dashboard to file support tickets.

    - Provide context: What are you trying to achieve, what is the end-user interaction, what are you seeing? (full error message, command output, etc.)
    - Use [search.convex.dev](https://search.convex.dev) to search Docs, Stack, and Discord all at once.
    - Additionally, you can post your questions in the Convex Community's #1228095053885476985 channel to receive a response from AI.
    - Avoid tagging staff unless specifically instructed.

    Thank you!
glass frigate
#

Others will likely have more insight, but imo, it's about helping folks understand convex directory exports as api endpoints, rather than serverless functions that also happen to be endpoints. So the code in all convex directory files should be entirely focused on exposure of functionality, while the model directory is where all of the inner workings of your backend lives. The separation, and having a clear handle on what is and is not exposed to the public, is important. For a new/small project, this will feel like an annoyance, but at scale it's almost a requirement from a security and auditability standpoint.

keen spruce
#

i agree on @glass frigate 's definitions and where the abstraction boundaries should be. in most frameworks I've used, once you expose an endpoint you probably won't call it internally; you'll refactor out a function. e.g. in flask https://stackoverflow.com/questions/43305658/proper-way-to-make-a-call-to-an-endpoint-from-the-api-using-flask

additionally, if you want more reasons why it's an antipattern, it's because when you wrap something in query() or mutation(), we want that to mean it runs argument validation and runs as a transaction. And if you run such a function with useQuery, useMutation, ctx.runQuery, ctx.runMutation, ctx.scheduler.runAfter, etc. all of that is true. But if you call it directly, it doesn't run argument validation or run in an isolated environment.

lusty vault
#

helping folks understand convex directory exports as api endpoints, rather than serverless functions that also happen to be endpoints
I knew this was a thing but it definitely wasn't the primary way I was conceptualizing /convex. That's helpful!

#

the code in all convex directory files should be entirely focused on exposure of functionality, while the model directory is where all of the inner workings of your backend lives
Tbh I'm not entirely sure where to draw that line between internal / external. It feels a little hazy, which is maybe part of what's leading to my confusion

#

Probably a consequence of having spent most of my time as a frontend engineer and not a backend one. But slowly getting more familiar with how to build things for the backend, too!

glass frigate
#

If you need to access a given Convex function from a client, you'll need a public Convex function for it. If you need access from something other than a client, like a webhook or via scheduler from another function, but never from a client, then it should be internal. And if it's only run directly (not scheduled) by a Convex function and nothing more, then it should be a function in the model directory.

#

Probably a consequence of having spent most of my time as a frontend engineer and not a backend one.
Precisely my perspective/experience as well

lusty vault
lusty vault
#

Followup q: is the /model directory supposed to generate API routes?

CleanShot_2025-03-18_at_12.32.342x.png
sturdy chasm
#

Most of the handiness of convex comes from thinking of mutation and actions as server actions, convex even pushes this with all their react-centric marketing.

They should allow running other functions from functions instead of you having to define same function name in 2 separate files.

lusty vault
#

@sturdy chasm This was my initial hurdle too. I think the intent of this change is that the model functions can be different from the API endpoints you expose. So it makes things more maintainable over time, because you don't have endpoints calling other endpoints.

#

I do think it would be helpful to make note of this in more places in the docs, especially for new users who are just getting familiar with Convex. The way that the tutorial is set up could make this clearer.

glass frigate
glass frigate
sturdy chasm
#

Then why not have a dependency injected or some other solution for the ctx param? Passing it as an argument doesn't seem like the best solution.

sturdy chasm
#

Changing functionality but having the same name on client makes for bad maintainability

#

The convex team should focus on expanding on this feature and possibly, making it less tasking to run

#

For mutations specifically they should have errors bubble up to the top mutation so acid compliancy is maintained

glass frigate
sturdy chasm
#

Depends on what you call typesafe, you still have to annotate it

#

ctx: ActionCtx for instance

glass frigate
#

That's actually a feature of the typesafety, I can say what kind of context my function expects, so I don't end up trying to run a mutation from a query context, or call an api without using an action context.

I'm curious on your viewpoint - is there something you've used in the past that you feel models the kind of ergonomics you expect?

sturdy chasm
#

with other backend oop focused frameworks ( not that im advocating for it, i find convex a joy because its not that ) Property Injection would achieve something similar, or a global importable ( much like the api )

#

But other than that ctx is fine, currently using it with a wrapper so my functions defined in model dont all have to expect a ctx

#

so something like

#

getCurrentUser = withQueryContext((ctx, ...args) => {});

#

where with query context is a function that returns another function

#

but i do feel that calling convex functions is more ergonomic

#

the import * is what hurts me the most tbh

#

just doesnt feel like ts to me

#

but its fine honestly, if yall know it to be better than im sure its better

glass frigate
#

Gotcha, that makes sense. A lot of folks have mentioned this, definitely not just you. I think I'm kind of in the middle at this point - I used to want to just call functions from other functions, but having a distinct api definition layer is starting to feel like a strength. But yeah, mileage varies.

lusty vault
#

It would be nice to have a Stack article! A primer on API/model organization like “here’s why to put your functions in a separate model layer, here are the benefits and drawbacks of this approach, here’s what Convex does to support this, here’s what we recommend”

#

I really appreciate the other Stack primer articles like this, they go a long way toward educating people about best practices

#

Another question I have is where to put my tests? For example, previously I had written unit tests for all my queries and mutations using convex-test. I can relocate the innards of the function into /model, and the tests still pass like before, but the actual logic being tested is elsewhere. Should I relocate the tests too, or is it still good to test the actual endpoint?

sturdy chasm
#

@glass frigate what do you guys suggest about params, with having things in separate files, you do lose the type inference from the validator, should we create validators and export them from model/ files so we can Infer<typeof validator> and have total type equality?

glass frigate
#

I personally reuse validators from my schema, but otherwise I allow shared helper functions and Convex functions to be independently typed to reduce brittleness, eg., a Convex query may map directly to a single model function today, but if I change anything I have to update both. But yeah, you could definitely create and share validators if you prefer it.

#

In my experience the relationship between api endpoints and underlying functions can be pretty fluid over time.

sturdy chasm
#

yeah i also have a schemas folder that i use which also includes common validators so i don't have to explicitly type things out, but yeah its still a bit of a miss

#

and its equivalent in ts function form