Middleware

Introduction

Middleware in oRPC is both powerful and flexible, enabling you to accomplish many tasks efficiently.

import { os, ORPCError } from '@orpc/server'
 
export type Context = { user?: { id: string } }
 
// global osw completely optional, needed when you want to use context
export const osw /** os with ... */ = os.context<Context>()
 
const authMiddleware = osw.middleware(async (input, context, meta) => {
    meta.onSuccess(async (output) => {
        // Invoked after successful handler execution
        // Other callbacks: onError, onFinish
    })
 
    if (!context.user) {
        throw new ORPCError({
            code: 'UNAUTHORIZED',
            message: 'You need to log in first',
        })
    }
 
    return {
        context: {
            user: context.user,
        }
    }
})
 
// Now every procedure or router defined in this oRPC will be protected by authMiddleware
const authOS = osw.use(authMiddleware)

Typed Input

Middleware can expect specific input types, opening up many possibilities:

import { os, ORPCError } from '@orpc/server'
import { z } from 'zod' 
 
const canEditPostMiddleware = os
    .middleware(async (input: {id: string}, context, meta) => { 
        // Now you can specify the input type for middleware
    })
 
os
    .input(z.object({ postId: z.string() }))
    .use(canEditPostMiddleware) // ❗ mismatched input typeArgument of type 'DecoratedMiddleware<Record<string, unknown> | undefined, undefined, { id: string; }, unknown>' is not assignable to parameter of type 'Middleware<Record<string, unknown> | undefined, undefined, { postId: string; }, unknown>'.
  Types of parameters 'input' and 'input' are incompatible.
    Property 'id' is missing in type '{ postId: string; }' but required in type '{ id: string; }'.
    .use(canEditPostMiddleware, (input) => ({ id: input.postId })) // ✅ map the input to match expected type

Concatenation

You can merge or extend middlewares using concatenation:

import { os } from '@orpc/server'
 
const auth = os.middleware(async (input, context, meta) => {})
const can = os.middleware(async (input, context, meta) => {})
 
const authAndCan = auth.concat(can) // Merge middleware
 
const authAndCan2 = auth.concat((input, context, meta) => {}) // Extend middleware

Extra Context

Extra context is created by middlewares and automatically merges with the global context, enhancing developer experience:

import { os, ORPCError } from '@orpc/server'
 
type Context = {
    user?: {
        id: string
    }
}
 
const osw = os.context<Context>()
 
// Any procedure using this middleware will infer context.user as NonNullable<typeof context['user']>
const authMiddleware = osw
    .middleware(async (input, context, meta) => {
        if (!context.user) {
            throw new ORPCError({ code: 'UNAUTHORIZED' })
        }
 
        return {
            context: {
                user: context.user
            }
        }
    })
 
const procedure = osw
    .use(authMiddleware)
    .use((input, context, meta) => {
 
        const _expect: NonNullable<typeof context['user']> = context.user
 
        return {
            context: {
                say: 'hi'
            }
        }
    })
    .handler(async (input, context, meta) => {
        
        const _expect1: NonNullable<typeof context['user']> = context.user
        const _expect2: string = context.say
 
    })

Fundamentals

In oRPC, middleware is simply a JavaScript function, making it easy to customize:

import { Meta, os } from '@orpc/server'
 
export type Context = { user?: { id: string } }
 
const mid = os.context<Context>().middleware(async (input, context, meta) => {})
 
// This is equivalent to:
 
const mid2 = async (input: unknown, context: Context, meta: Meta<unknown>): Promise<void> => {
 
}