[RFC] Chainable resolvers #33

KATT · 2022-03-31T21:28:10Z

I've let this marinate, and I think chaining for the resolver API could be nicer. I've here created a POC that you can compare side-by-side with the main branch. Closes #25 & Closes #24.

Notes

I have decided to not ship inferrable errors for the first iteration.
You will be able to CMD+Click from the client/React component and jump straight to your backend definition
Ignore that it's throw Error below; imagine throw TRPCError({ code: '..'})
You can now define input before or after your middlewares run, it's up to you!
Considerable performance improvements of the TypeScript compilation - compiling a router with 3,000 procedures with inlined Zod-schemas takes ~10 seconds in CI.
Playground 👉 https://stackblitz.com/github/trpc/v10-playground/tree/katt/procedure-chains?file=src%2Fserver.ts (note that it's only TypeScript ergonomics, no actual implementation yet)

§1 Basics

§1.0 Setting up tRPC

type Context = {
  user?: {
    id: string;
    memberships: {
      organizationId: string;
    }[];
  };
};

const trpc = initTRPC<Context>();

const {
  /**
   * Builder object for creating procedures
   */
  procedure,
  /**
   * Create reusable middlewares
   */
  middleware,
  /**
   * Create a router
   */
  router,
  /**
   * Merge Routers
   */
  mergeRouters,
} = trpc;

§1.1 Creating a router

export const appRouter = trpc.router({
  queries: {
    // [...]
  },
  mutations: {
    // [...]
  },
})

§1.2 Defining a procedure

export const appRouter = trpc.router({
  queries: {
    // simple procedure without args avialable at postAll`
    postList: procedure.resolve(() => postsDb),
  }
});

Details about the procedure builder

Simplified to be more readable - see full implementation in https://github.com/trpc/v10-playground/blob/katt/procedure-chains/src/trpc/server/procedure.ts

interface ProcedureBuilder {
  /**
   * Add an input parser to the procedure.
   */
  input(
    schema: $TParser,
  ): ProcedureBuilder;
  /**
   * Add an output parser to the procedure.
   */
  output(
    schema: $TParser,
  ): ProcedureBuilder;
  /**
   * Add a middleware to the procedure.
   */
  use(
    fn: MiddlewareFunction<TParams, $TParams>,
  ): ProcedureBuilder
  /**
   * Extend the procedure with another procedure
   */
  concat(
    proc: ProcedureBuilder,
  ): ProcedureBuilder;
  resolve(
    resolver: (
      opts: ResolveOptions<TParams>,
    ) => $TOutput,
  ): Procedure;
}

§1.3 Adding input parser

Note that I'll skip the trpc.router({ queries: /*...*/}) below here

// get post by id or 404 if it's not found
const postById = procedure
  .input(
    z.object({
      id: z.string(),
    }),
  )
  .resolve(({ input }) => {
    const post = postsDb.find((post) => post.id === input.id);
    if (!post) {
      throw new Error('NOT_FOUND');
    }
    return {
      data: postsDb,
    };
  });

§1.4 Procedure with middleware

const whoami = procedure
  .use((params) => {
    if (!params.ctx.user) {
      throw new Error('UNAUTHORIZED');
    }
    return params.next({
      ctx: {
        // User is now set on the ctx object
        user: params.ctx.user,
      },
    });
  })
  .resolve(({ ctx }) => {
    // `isAuthed()` will propagate new `ctx`
    // `ctx.user` is now `NonNullable`
    return `your id is ${ctx.user.id}`;
  });

§2 Intermediate 🍿

§2.1 Define a reusable middleware

const isAuthed = trpc.middleware((params) => {
  if (!params.ctx.user) {
    throw new Error('zup');
  }
  return params.next({
    ctx: {
      user: params.ctx.user,
    },
  });
});

// Use in procedure:
const whoami = procedure
  .use(isAuthed)
  .resolve(({ ctx }) => {
    // `isAuthed()` will propagate new `ctx`
    // `ctx.user` is now `NonNullable`
    return `your id is ${ctx.user.id}`;
  });

§2.2 Create a bunch of procedures that are all protected

const protectedProcedure = procedure.use(isAuthed);

export const appRouter = trpc.router({
  queries: {
    postList: protectedProcedure.resolve(() => postsDb),
    postById: protectedProcedure
      .input(
        z.object({
          id: z.string(),
        }),
      )
      .resolve(({ input }) => {
        const post = postsDb.find((post) => post.id === input.id);
        if (!post) {
          throw new Error('NOT_FOUND');
        }
        return {
          data: postsDb,
        };
      })
 }
})

§2.3 Define an `output` schema

procedure
      .output(z.void())
      // This will fail because we've explicitly said this procedure is `void`
      .resolve(({ input }) => {
        return'hello';
      })

§2.4 Merging routers

const postRouter = trpc.router({
  queries: {
    postList: protectedProcedure.resolve(() => postsDb),
    postById: protectedProcedure
      .input(
        z.object({
          id: z.string(),
        }),
      )
      .resolve(({ input }) => {
        const post = postsDb.find((post) => post.id === input.id);
        if (!post) {
          throw new Error('NOT_FOUND');
        }
        return {
          data: postsDb,
        };
      })
  }
})

const health = trpc.router({
  query: {
    healthz: trpc.resolve(() => 'I am alive')
  }
})

export const appRouter = trpc.mergeRouters(
  postRouter,
  health
);

§3 Advanced 🧙

Compose dynamic combos of middlewares/input parsers

/**
 * A reusable combination of an input + middleware that can be reused.
 * Accepts a Zod-schema as a generic.
 */
function isPartOfOrg<
  TSchema extends z.ZodObject<{ organizationId: z.ZodString }>,
>(schema: TSchema) {
  return procedure.input(schema).use((params) => {
    const { ctx, input } = params;
    const { user } = ctx;
    if (!user) {
      throw new Error('UNAUTHORIZED');
    }

    if (
      !user.memberships.some(
        (membership) => membership.organizationId !== input.organizationId,
      )
    ) {
      throw new Error('FORBIDDEN');
    }

    return params.next({
      ctx: {
        user,
      },
    });
  });
}



const editOrganization = procedure
  .concat(
    isPartOfOrg(
      z.object({
        organizationId: z.string(),
        data: z.object({
          name: z.string(),
        }),
      }),
    ),
  )
  .resolve(({ ctx, input }) => {
    // - User is guaranteed to be part of the organization queried
    // - `input` is of type:
      // {
      //   data: {
      //       name: string;
      //   };
      //   organizationId: string;
      // }

    // [.... insert logic here]
  });

KATT

Some minor naming things I'd like input on.

src/server.ts

KATT · 2022-03-31T22:09:18Z

src/trpc/server/initTRPC.ts

    /**
-     * Create procedure resolver
+     * Builder object for creating procedures
     */
-    resolver: pipedResolver<TContext>(),
+    procedure: createProcedure<TContext>(),


Should this be called builder or something else perhaps?

I think procedure is fine, maybe procedureBuilder if you want to be more clear about what it is, although I think it's clear enough already.

KATT · 2022-04-11T08:12:05Z

src/trpc/server/Params.ts

+/**
+ * @internal
+ */
+export interface Params<
+  TContextIn = unknown,
+  TContextOut = unknown,
+  TInputIn = unknown,
+  TInputOut = unknown,
+  TOutputIn = unknown,
+  TOutputOut = unknown,
+> {
+  /**
+   * @internal
+   */
+  _ctx_in: TContextIn;
+  /**
+   * @internal
+   */
+  _ctx_out: TContextOut;
+  /**
+   * @internal
+   */
+  _output_in: TOutputIn;
+  /**
+   * @internal
+   */
+  _output_out: TOutputOut;
+  /**
+   * @internal
+   */
+  _input_in: TInputIn;
+  /**
+   * @internal
+   */
+  _input_out: TInputOut;
+}


@mmkal I guess this is what you referred to as an options-bag? :)

Tried to write a reply to this on my phone but too hard! Yes this is pretty much what I was thinking. A couple of ways it could be simplified even further occur to me tho:

No linear generics at all. This might prove impossible if the compiler loses track of property types somewhere along the way, but here's a simplified example:

interface Params { input: unknown output: unknown context: unknown } const getClientThatUsesSpecificParams = <P extends Params>(params: P) => { return { useInput: (input: P['input']) => 123, getOutput: () => params.output, } } const specific = getClientThatUsesSpecificParams({ input: {foo: 'abc'}, output: [123, 456], context: {bar: 987}, })

TypeScript doesn't need specific typeargs for TInput, TOutput, TContext to keep track of them:

Maybe there could be an IO type to generalise the _in and _out suffixes?

interface IO<I, O> { in: I out: O } interface Params< TContextIn = unknown, TContextOut = unknown, TInputIn = unknown, TInputOut = unknown, TOutputIn = unknown, TOutputOut = unknown, > { ctx: IO<TContextIn, TContextOut> input: IO<TInputIn, TInputOut> output: IO<TOutputIn, TOutputOut> }

Both together!?!!?

interface IO { input: unknown output: unknown } interface Params { ctx: IO input: IO output: IO }

Made #35. Feel free to do PR, I have some decent testing and it's easy to run with yarn dev.

These are all internal types so easy to refactor later too, but would be nice to have it clean

mmkal · 2022-04-11T21:46:56Z

I love this

yume-chan · 2022-05-31T04:33:55Z

It looks so good! I only have two minor questions:

Will mergeRouters accept prefix like it does now, like

export const appRouter = trpc.mergeRouters({
  post: postRouter
}, health);

Is it possible to concat mutliple inputs? For example maybe I have another isPartOfTeam input + middleware, and I want to use it with isPartOfOrg? If yes, will the order of input and use affect the actual validation? Say in procedure.input(a).use(b).input(c).resolve(d), both b and c will fail, what error would be returned?

squash procedure chains

8698ffd

KATT mentioned this pull request Mar 31, 2022

[RFC] Chainable resolvers on server #32

Closed

KATT requested review from colinhacks, danielyogel, darioielardi, esamattis, MarcGuiselin and sachinraja March 31, 2022 21:51

KATT added the ❕ RFC Request for comments - please comment! label Mar 31, 2022

KATT commented Mar 31, 2022

View reviewed changes

tweaks - procedure has Params

d8990d6

KATT mentioned this pull request Apr 10, 2022

[RFC] Next major overview trpc/trpc#887

Closed

60 tasks

KATT added 6 commits April 10, 2022 18:07

input: {}

20e7efc

seems to work

a303ae0

input

aea8237

tweak

5cbcf5c

use

53b6045

input

28d4c7c

KATT marked this pull request as ready for review April 10, 2022 16:32

_ctx_in params

68814c0

KATT commented Apr 11, 2022

View reviewed changes

KATT added 9 commits April 11, 2022 10:19

concat

80b0d78

namespace folder

182abd1

project structure

83a9999

structure

0bae381

structure more

0f9be09

merge

e413ca1

wippy

19044a5

wip

e21574c

awesomeeee

664353c

KATT added 7 commits April 11, 2022 20:19

tweaky tweaks

1444aa0

update

db88ea2

fix

5257977

fix

793278e

tweak

c7aa50d

tweak

f7919d4

tweak

980ead7

KATT enabled auto-merge (squash) April 11, 2022 21:16

KATT merged commit 5dfa832 into main Apr 11, 2022

KATT deleted the katt/procedure-chains branch April 11, 2022 21:17

KATT mentioned this pull request Apr 11, 2022

Chapter 1) The Router API #24

Closed

KATT mentioned this pull request Apr 11, 2022

Consider this #35

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[RFC] Chainable resolvers #33

[RFC] Chainable resolvers #33

KATT commented Mar 31, 2022 •

edited

Loading

KATT left a comment

KATT Mar 31, 2022

sachinraja Apr 1, 2022 •

edited

Loading

KATT Apr 11, 2022

mmkal Apr 11, 2022

KATT Apr 11, 2022

mmkal commented Apr 11, 2022

yume-chan commented May 31, 2022

[RFC] Chainable resolvers #33

[RFC] Chainable resolvers #33

Conversation

KATT commented Mar 31, 2022 • edited Loading

Notes

§1 Basics

§1.0 Setting up tRPC

§1.1 Creating a router

§1.2 Defining a procedure

Details about the procedure builder

§1.3 Adding input parser

§1.4 Procedure with middleware

§2 Intermediate 🍿

§2.1 Define a reusable middleware

§2.2 Create a bunch of procedures that are all protected

§2.3 Define an output schema

§2.4 Merging routers

§3 Advanced 🧙

Compose dynamic combos of middlewares/input parsers

KATT left a comment

Choose a reason for hiding this comment

KATT Mar 31, 2022

Choose a reason for hiding this comment

sachinraja Apr 1, 2022 • edited Loading

Choose a reason for hiding this comment

KATT Apr 11, 2022

Choose a reason for hiding this comment

mmkal Apr 11, 2022

Choose a reason for hiding this comment

KATT Apr 11, 2022

Choose a reason for hiding this comment

mmkal commented Apr 11, 2022

yume-chan commented May 31, 2022

KATT commented Mar 31, 2022 •

edited

Loading

§2.3 Define an `output` schema

sachinraja Apr 1, 2022 •

edited

Loading