API recommendations

[colinhacks]

Some recommendations for improvements to the API:

• I don't really see any reason to split up @trpc/server and @trpc/client. I think they should be merged into a single trpc module. It makes the out-of-the-box experience so much cleaner.
• Then the @trpc scope can be used for specific plugins/adapters etc. You could publish the Express adapter as @trpc/express for instance. That would also let you properly specify all the requisite peerDependencies (which I don't believe are specified using the current @trpc/server/adapters/express approach since it doesn't have its own package.json.
• I think import * as imports are a bad user experience. I submitted a PR with a solution.
• Simplify the function names: createTRPCClient => createClient, createNextApiHandler => createHandler, CreateNextContextOptions => ContextOptions. It should be standard across adapters. It's obvious that a function called createHandler imported from "@trpc/server/adapters/next" is creating a Next.js API handler. It doesn't need to be in the name.
• The adapters should export a createContext function that can automatically type opts with the necessary types.
• I think all requests (queries and mutations) should get served from a single URL. The path can be added as an additional query parameter for queries and in the body for mutations. This would also simplify the Next/Express adapters (no need for a catchall API route).

Less important:

I think there should be a way of manually typing the input of a resolver without passing a validator into input. This is easy to do if the resolver functions had two parameters instead of one. I have this working on a local branch (type inference still works the same).

I propose this syntax/convention:

const router = trpc.router<Context>().query('test', {
    resolve(input: number, req) {
      return input;
    },
  });

The req variable above if of type { ctx: TContext, type: ProcedureType }. This leaves the door open to future API expansion, as req can act like a catchall for any additional properties we want to pass into resolvers.

[KATT]

Just saw this! Thanks so much for the ideas.

• I don't really see any reason to split up @trpc/server and @trpc/client. I think they should be merged into a single trpc module. It makes the out-of-the-box experience so much cleaner.
• Then the @trpc scope can be used for specific plugins/adapters etc. You could publish the Express adapter as @trpc/express for instance. That would also let you properly specify all the requisite peerDependencies (which I don't believe are specified using the current @trpc/server/adapters/express approach since it doesn't have its own package.json.

Prone to agree, the only con is that @trpc/client requires a lot more polyfilling, @trpc/server is a very clean target of node 12

• I think import * as imports are a bad user experience. I submitted a PR with a solution.

Let's keep that discussion in #210

• Simplify the function names: createTRPCClient => createClient, createNextApiHandler => createHandler,
• CreateNextContextOptions => ContextOptions. It should be standard across adapters. It's obvious that a function called createHandler imported from "@trpc/server/adapters/next" is creating a Next.js API handler. It doesn't need to be in the name.

I actually disagree, I don't like when libraries occupy "generic" namespaces as I just keep on importing the wrong ones. Also for the next adapter it's easier to find it by autocompletion if it's named since we have several adapters.

• The adapters should export a createContext function that can automatically type opts with the necessary types:

There is already CreateExpressContextFn etc, I don't use them in the examples as I prefer being able to infer the Context object from the function than to explicitly declare it. Example

trpc/examples/next-prisma-todomvc/pages/api/trpc/[trpc].ts

Line 18 in ffda2f7

export type Context = trpc.inferAsyncReturnType<typeof createContext>;

• I think all requests (queries and mutations) should get served from a single URL. The path can be added as an additional query parameter for queries and in the body for mutations. This would also simplify the Next/Express adapters (no need for a catchall API route).

Strongly disagree, it's much cleaner to read as it is now when working with it (which I've done a lot the last few months) aaand I have some plans on how we would eventually do batching etc using the current structure as well.

---

Appreciate the input!

[colinhacks]

All seems reasonable!

A few followups:

the only con is that @trpc/client requires a lot more polyfilling

What are the polyfills for client? Does that have anything to do with the @babel/runtime dependency? Might be worth standardizing on trpc for the core library even if that means a few polyfills end up in the package.

I actually disagree, I don't like when libraries occupy "generic" namespaces as I just keep on importing the wrong ones.

That's understandable. A lot of these recommendations stem from the fact that the sample code in the docs just seems to complicated to me. The v0.x syntax was super clean and understandable, no function names to remember. I feel like it's gotten a lot more intimidating. Some of this was unavoidable due to the addition of more features, but in general I think you should prioritize clean, understandable code over collision avoidance. That's why I like the idea of merging @trpc/client and @trpc/server, enabling import { trpc } from 'trpc'; syntax, making it easier to define a typed endpoint without input, etc. It's all about simplifying usage and syntax.

There is already CreateExpressContextFn

Sorry, I forgot to put in a code example. What I'd like to see is a createCreateContext function (though hopefully you can think of a better name!) that types the inputs and infers the outputs:

const createContext = createCreateContext(opts => {
  return {};
});

type Context = ReturnType<typeof createContext>

The point of this is to avoid having to remember the name "CreateNextContextOptions".

Strongly disagree, it's much cleaner to read as it is now when working with it

You mean in the Requests devtools or something? Hadn't thought of that...makes sense.