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 } }
 
export const pub /** public access */ = os.context<Context>()
 
const authMiddleware = pub.middleware(async (input, context, meta) => {
    if (!context.user) {
        throw new ORPCError({
            code: 'UNAUTHORIZED',
            message: 'You need to log in first',
        })
    }
 
    const result = await meta.next({
        context: {
            user: context.user,
        }
    })
 
    // Do something on success
 
    return result
})
 
// Now every procedure or router defined in this oRPC will be protected by authMiddleware
export const authed /** require authed */ = pub.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
        return meta.next({})
    })
 
os
    .input(z.object({ postId: z.string() }))
    .use(canEditPostMiddleware) // ❗ mismatched input typeArgument of type 'DecoratedMiddleware<Record<string, unknown> | undefined, undefined, { id: string; }, any>' 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) => meta.next({}))
const can = os.middleware(async (input, context, meta) => meta.next({}))
 
const authAndCan = auth.concat(can) // Merge middleware
 
const authAndCan2 = auth.concat((input, context, meta) => meta.next({})) // 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
    }
}
 
export const pub = os.context<Context>()
 
// Any procedure using this middleware will infer context.user as NonNullable<typeof context['user']>
const authMiddleware = pub
    .middleware(async (input, context, meta) => {
        if (!context.user) {
            throw new ORPCError({ code: 'UNAUTHORIZED' })
        }
 
        return meta.next({
            context: {
                user: context.user
            }
        })
    })
 
export const authed = pub
    .use(authMiddleware)
    .use((input, context, meta) => {
 
        const _expect: NonNullable<typeof context['user']> = context.user
 
        return meta.next({
            context: {
                say: 'hi'
            }
        })
    })
    .func(async (input, context, meta) => {
        
        const _expect1: NonNullable<typeof context['user']> = context.user
        const _expect2: string = context.say
 
    })

Middleware can directly output data to the client without invoking the handler. This is particularly useful for scenarios such as caching responses or pre-processing the output before sending it to the client.

import { os } from '@orpc/server'
 
const fakeCache = new Map<string, unknown>()
 
const cacheMid = os.middleware(async (input, context, meta) => {
    const cacheKey = meta.path.join('/') + JSON.stringify(input) /* stringify is not ideal, but it's just an example */
 
    if (fakeCache.has(cacheKey)) {
        return meta.output(fakeCache.get(cacheKey))
    }
 
    const result = await meta.next({})
    fakeCache.set(cacheKey, result.output)
    return result
})

Introduction

Typed Input

Concatenation

Extra Context

Output

On this page