diz6157
diz615714mo ago

Best practices in naming and defining procedures when they don't fit into standard buckets?

I am loving TRPC and its type safety, but I feel like I'm struggling with the naming of procedures. I'm pretty confused with why I need to fit my procedures into one of the 3 buckets: query, mutation, or subscription. For example, I have items. They can be queried, mutated and subscribed to. And maybe a few more things - items can be generated, created, pulled from a remote source, deleted, renamed, aliased, etc. But let's try to fit this into these prescribed buckets. I felt inclined to define items as a publicProcedure with all 3 verbs. But I have to choose only one, not all three. The api does not support chaining on multiple verbs. If I want to support all 3, I have to differentiate them as separate procedure definitions such as getItems, updateItems, and subscribeToItems... but then, what's the point of query/mutate/subscribe if I am already differentiating them as separate procedure names? Now the client api surface is weird: I wanted the client code to read: client.items.query(), or client.items.mutate(...) I'm fine with it if I can just have client.getItems() or client.updateItems(...) Instead I have redundancy in the naming: client.getItems.query(), client.updateItems.mutate(...) To make things more confusing, some procedures just don't fit into these buckets. I can have procedures which read nothing, write nothing, but perform some action like open a file in vscode. None of the above conventions work in this case. My expectation when using it was simply to have an execute call, and let the author decide their naming conventions. If there is nothing special about a query or mutation, why introduce weird things that mess with the naming conventions and don't work in every case?
13 Replies
Nick
Nick14mo ago
Name procedures like you would name the function that does a thing So client.users.giveAccountAccess.mutate() or client.users.list or .getList It’s very much a case of naming is hard (in general) and you should do what feels best at the time
diz6157
diz615714mo ago
right, but my question is, why the need to have "mutate()" or "query()" at the end of the function? (or rather, is there a way to avoid using a category, so that my client is just client.giveAccountAccess() which is nice and predictable?)
Nick
Nick14mo ago
This is a tRPC thing for sure Not really a way to avoid it
diz6157
diz615714mo ago
I can have a wrapper that abstracts the client returned from createTRPCProxyClient which removes the extra category, that's all i could come up with
Nick
Nick14mo ago
Under the hood it controls things like the HTTP verb to use, so it does matter
diz6157
diz615714mo ago
that's a good point. So I'm assuming query=get, mutation=post
Nick
Nick14mo ago
Essentially yes It can change how you frame your semantics too I often write my procedures in terms of resources, so prefer .list.query rather than .getList.query But it’s preference
diz6157
diz615714mo ago
in that case: what if your list can be queried and mutated and subscribed? is there a way to provide all 3 for a single resource? (i'm guessing that in that case "list" is a procedure) so that we could have client.list.query(...), client.list.mutate(...)
Nick
Nick14mo ago
I actually don’t think that would be impossible to build Feel free to open a GitHub issue on it, but it’s not a current feature no
diz6157
diz615714mo ago
Sure thing. Thanks for the help Nick!
Sandvich
Sandvich14mo ago
Sorry to hijack this thread but this looks like a cool idea. I scaffolded out how that might look to create many procedures and this just looks really nice
const test = router({
greeting: {
query: publicProcedure
.input(z.string())
.query(({ input }) => {
return `Hello ${input}!`;
}),
mutation: publicProcedure
.input(z.object())
.mutation(() => {}),
subscription: publicProcedure.subscription(() => {
// ...
}),
}
});
const test = router({
greeting: {
query: publicProcedure
.input(z.string())
.query(({ input }) => {
return `Hello ${input}!`;
}),
mutation: publicProcedure
.input(z.object())
.mutation(() => {}),
subscription: publicProcedure.subscription(() => {
// ...
}),
}
});
You could argue there's some duplication in key name and method name but I think it's fine
Nick
Nick14mo ago
Go ahead and create a GitHub issue! Can’t promise we’ll tackle it soon or at all, but PRs are especially welcome if they prove the concept
diz6157
diz615714mo ago
i'll post one