v10.23.0 - experimental FormData handling

[KATT]

In 10.23.0, we've added a new experimental API to handle FormData in mutations and we would looooove some feedback and people playing around with it.

We're still not entirely satisfied with the API, but you can see a POC of it working in https://github.com/trpc/trpc/tree/main/examples/.experimental/next-formdata

We'd love some critical eyes on how we've approached it and thoughts on how we could make the API the best it can be:

• The multipart spec is quite limiting and you have to process the full request body before you can validate any of it
• There a few parts to configure: config on API handler + adding a client-side link + a middleware for where you want to handle the FormData. This should probably be simplified.
• [...]

[Nick-Lucas]

I've been doing some work on this, which I actually feel pretty confident to just action and move forward with, but I have a few proposals to improve the maturity and barrier to entry of these APIs:

1. Get rid of the .use.input chain with experimental_isMultipartFormDataRequest experimental_parseMultipartFormData. Replace this with "Input Strategies" (I am not sure about the name yet), a new type of tRPC Validator which is able to provide lower level behaviours for arbitrary Request loading, and for FormData plug in an UploadHandler and Validator/Parser. I have implemented this here: https://github.com/trpc/trpc/pull/4286/files
   

2. Have a default array of contentTypeHandlers (json, formdata, etc) so that users don't need to set this array themselves, but keep the option in tRPC to extend it, because combined with Input Strategies this would actually allow people to implement novel data types in userland

3. Expose req: unknown (or even not unknown if possible) directly to middlewares at the root level. The experimental_isMultipartFormDataRequest->experimental_parseMultipartFormData pattern could be used quite safely against an unknown type and prevent some annoying user setup, plus it's quite a common need for users to attach the req and doing it in context seems a hack by comparison

4. Remove the need for a splitLink to send formData from the client, we should be able to handle this internally in all links with typeof/instanceof checks or some similar method. Batch links should recognise that they need to un-batch these calls on their own.

[jussisaurio]

I've written #4946 simply to satisfy a personal use case, but also happy to discuss where we are wrt. stabilizing this API; will happily contribute to that effort if necessary

[jussisaurio]

Kinda tooting my own horn but experimental_standaloneMiddleware could easily be used for some of this stuff as well:

const memoryUploadHandler = (uploadOpts?: MemoryUploadHandlerOptions) => experimental_standaloneMiddleware<{ ctx: { req: NodeHTTPRequest }}>().create(async (opts) => {
  if (!experimental_isMultipartFormDataRequest(opts.ctx.req)) {
    return opts.next();
  }
  const formData = await experimental_parseMultipartFormData(
    opts.ctx.req,
    experimental_createMemoryUploadHandler(uploadOpts),
  );

  return opts.next({
    rawInput: formData,
  });
})

...

const appRouter = t.router({
  polymorphic: t.procedure
    .use(memoryUploadHandler({ maxPartSize: 666 }))
    .input(
      formDataOrObject({
        text: z.string(),
      }),
    )
    .mutation((opts) => {
      return opts.input;
    })
});

tRPC could already then expose memoryUploadHandler as part of the public API. I for one would find this immediately useful even if it meant I'd have to configure splitLinks and contentTypeHandlers

[Nick-Lucas]

I like the direction your PR is going in by adding this functionality. My original work on this went on hold due to a combination of life stuff, and us realising we needed a small breaking change to the public API to make it work, but it's something I hope to revisit after the v11 release as tRPC really isn't going to feel "done" until there's a good solution to content types.

I'm not best placed to approve that PR, but it looks pretty tidy, and given the experimental nature I imagine we can merge it