ts-procedures 10.1.2 → 10.2.1

package/src/core/create-http.ts

@@ -5,12 +5,21 @@ import { captureDefinitionInfo } from './definition-site.js'
 import { applyPathPrefix, checkPathParamConsistency } from './http-route.js'
 import {
   assertNotDuplicate,
+  runWithMiddlewares,
   shouldSkipValidation,
   toProcedureError,
   validateReqChannels,
 } from './internal.js'
 import type { FactoryRuntime } from './internal.js'
-import type { ProcedureResult, TCreateHttpConfig, TLocalContext, THttpProcedureRegistration } from './types.js'
+import type {
+  HttpReq,
+  ProcedureResult,
+  TCreateHttpConfig,
+  THttpProcedureRegistration,
+  THttpReqInput,
+  THttpResInput,
+  TLocalContext,
+} from './types.js'
 
 /**
  * The handler return shape is gated by the DECLARED response schema, not by
@@ -26,10 +35,6 @@ export type HttpReturn<TRes> =
   : TRes extends { body: infer B }                 ? Infer<B>
   : void
 
-type HttpReq<TReq> = TReq extends Record<string, unknown>
-  ? Prettify<{ [K in keyof TReq]: Infer<TReq[K]> }>
-  : undefined
-
 export function makeCreateHttp<TContext>(runtime: FactoryRuntime<TContext, any>) {
   /**
    * Defines a REST-shaped HTTP procedure with per-channel input validation
@@ -40,8 +45,8 @@ export function makeCreateHttp<TContext>(runtime: FactoryRuntime<TContext, any>)
    */
   return function CreateHttp<
     TName extends string,
-    TReq extends Record<string, unknown> | undefined = undefined,
-    TRes extends { body?: unknown; headers?: unknown } | undefined = undefined,
+    TReq extends THttpReqInput | undefined = undefined,
+    TRes extends THttpResInput | undefined = undefined,
     TErrorKey extends string = string,
   >(
     name: TName,
@@ -103,7 +108,13 @@ export function makeCreateHttp<TContext>(runtime: FactoryRuntime<TContext, any>)
           }
 
           const localCtx: TLocalContext = { error: errorFactory }
-          return await handler({ ...ctx, ...localCtx } as any, req)
+          const fullCtx = { ...ctx, ...localCtx } as any
+          return await runWithMiddlewares(
+            runtime.middlewares,
+            fullCtx,
+            req,
+            (c, r) => handler(c, r as any)
+          )
         } catch (error: any) {
           throw toProcedureError(name, definitionInfo, error)
         }

package/src/core/create-stream.ts

@@ -7,6 +7,7 @@ import {
   assertNotDuplicate,
   combineSignals,
   iterateWithGuards,
+  runWithMiddlewares,
   shouldSkipValidation,
   validateParams,
 } from './internal.js'
@@ -89,10 +90,17 @@ export function makeCreateStream<TContext, TExtendedConfig>(runtime: FactoryRunt
 
         // params is correctly typed at the public API boundary via conditional
         // type; cast here because TS cannot narrow generics inside implementations
-        const userGenerator = handler(
-          { ...ctx, ...streamCtx } as Prettify<TContext & TStreamContext>,
-          params as any,
-        )
+        const fullCtx = { ...ctx, ...streamCtx } as Prettify<TContext & TStreamContext>
+
+        // Apply factory middleware around obtaining the user generator.
+        // Middlewares can short-circuit (return a different generator or throw)
+        // or augment before the stream starts.
+        const userGenerator = runWithMiddlewares(
+          runtime.middlewares,
+          fullCtx,
+          params,
+          (c, p) => handler(c as any, p as any)
+        ) as AsyncGenerator<any, any, unknown>
 
         return yield* iterateWithGuards(userGenerator[Symbol.asyncIterator](), {
           name,

package/src/core/create.test.ts

@@ -364,6 +364,80 @@ describe('Procedures', () => {
   })
 })
 
+describe('Procedures({ middleware }) - factory level, ctx + input aware', () => {
+  test('middleware runs with same ctx the handler sees and can inspect input', async () => {
+    const calls: any[] = []
+
+    const { Create } = Procedures<{ userId: string }>({
+      middleware: [
+        ({ ctx, input, next }) => {
+          calls.push({ userId: ctx.userId, input })
+          // "parse the incoming call" using ctx + input
+          if ((input as any)?.orgId === 'evil') {
+            throw ctx.error('tenant violation')
+          }
+          return next()
+        },
+      ],
+    })
+
+    const { GetThing } = Create('GetThing', { schema: { params: Type.Object({ orgId: Type.String() }) } }, async (ctx, p) => {
+      return { seenByHandler: ctx.userId, org: (p as any).orgId }
+    })
+
+    await GetThing({ userId: 'u1' }, { orgId: 'acme' })
+    expect(calls).toHaveLength(1)
+    expect(calls[0]).toEqual({ userId: 'u1', input: { orgId: 'acme' } })
+  })
+
+  test('middleware can augment ctx and transform input for the handler', async () => {
+    const { Create } = Procedures<{ base: string }>({
+      middleware: [
+        ({ ctx, input, next }) => {
+          return next({
+            ctx: { ...ctx, extra: 'added' },
+            input: { ...(input as any), injected: true },
+          })
+        },
+      ],
+    })
+
+    const { Echo } = Create('Echo', { schema: { params: Type.Object({ n: Type.Number() }) } }, async (ctx, p: any) => {
+      return { base: ctx.base, extra: (ctx as any).extra, received: p }
+    })
+
+    const result = await Echo({ base: 'b' }, { n: 42 })
+    expect(result).toEqual({
+      base: 'b',
+      extra: 'added',
+      received: { n: 42, injected: true },
+    })
+  })
+
+  test('middleware error uses the factory ctx.error and is wrapped as ProcedureError', async () => {
+    const { Create } = Procedures<{}>({
+      middleware: [({ ctx }) => { throw ctx.error('from factory mw') }],
+    })
+
+    const { Fail } = Create('Fail', {}, async () => 'no')
+    await expect(Fail({}, {})).rejects.toThrow('from factory mw')
+  })
+
+  test('multiple factory middlewares compose (order + next)', async () => {
+    const order: string[] = []
+    const { Create } = Procedures({
+      middleware: [
+        async ({ next }) => { order.push('mw1'); return next() },
+        async ({ next }) => { order.push('mw2'); return next() },
+      ],
+    })
+
+    const { Ok } = Create('Ok', {}, async () => 'ok')
+    await Ok({}, {})
+    expect(order).toEqual(['mw1', 'mw2'])
+  })
+})
+
 describe('Procedures - Definition Location in Errors', () => {
   test('ProcedureValidationError includes definition location', async () => {
     const { Create } = Procedures()

package/src/core/create.ts

@@ -5,6 +5,7 @@ import { captureDefinitionInfo } from './definition-site.js'
 import {
   assertNoHttpFields,
   assertNotDuplicate,
+  runWithMiddlewares,
   shouldSkipValidation,
   toProcedureError,
   validateParams,
@@ -76,11 +77,15 @@ export function makeCreate<TContext, TExtendedConfig>(runtime: FactoryRuntime<TC
             error: errorFactory,
           }
 
-          // params is correctly typed at the public API boundary;
-          // cast here because TS cannot narrow generics inside implementations
-          return await handler(
-            { ...ctx, ...localCtx } as Prettify<TContext & TLocalContext>,
-            params as any,
+          const fullCtx = { ...ctx, ...localCtx } as Prettify<TContext & TLocalContext>
+
+          // Factory middleware sees the exact same ctx + validated input as the
+          // user handler. Supports next({ ctx?, input? }) augmentation.
+          return await runWithMiddlewares(
+            runtime.middlewares,
+            fullCtx,
+            params,
+            (c, p) => handler(c as any, p as any)
           )
         } catch (error: any) {
           throw toProcedureError(name, definitionInfo, error)

package/src/core/internal.ts

@@ -20,6 +20,8 @@ export type FactoryRuntime<TContext, TExtendedConfig> = {
   adapters: readonly SchemaAdapter[]
   compile: ValidatorCompiler
   httpDefaults?: { pathPrefix?: string; scope?: string }
+  /** Factory-level middleware applied to every procedure from this factory. */
+  middlewares: Array<(opts: { ctx: any; input: unknown; next: (o?: any) => any }) => any>
 }
 
 const HTTP_FIELDS = ['path', 'method', 'req', 'res', 'successStatus'] as const
@@ -142,6 +144,39 @@ export function combineSignals(incoming: AbortSignal | undefined, own: AbortSign
   return incoming ? AbortSignal.any([incoming, own]) : own
 }
 
+/**
+ * Apply factory-defined middlewares around a core invocation.
+ * Middlewares run from first to last; each sees the (possibly augmented) ctx + input.
+ * Supports both unary results and async generators (for streams).
+ */
+export function runWithMiddlewares(
+  middlewares: Array<(opts: { ctx: any; input: unknown; next: (o?: any) => any }) => any>,
+  ctx: any,
+  input: unknown,
+  core: (c: any, i: unknown) => any
+): any {
+  if (!middlewares.length) {
+    return core(ctx, input)
+  }
+
+  // Build the chain from the inside out
+  let current = core
+
+  for (let i = middlewares.length - 1; i >= 0; i--) {
+    const mw = middlewares[i]!
+    const previous = current
+    current = (c: any, i: unknown) =>
+      mw({
+        ctx: c,
+        input: i,
+        next: (o: any = {}) => previous(o.ctx ?? c, o.input ?? i),
+      })
+  }
+
+  return current(ctx, input)
+}
+
+
 /**
  * Drives a user stream iterator with the framework guarantees shared by
  * CreateStream and CreateHttpStream:

package/src/core/procedures.ts

@@ -18,6 +18,7 @@ import type { AnyProcedureRegistration, ProceduresOptions, TNoContextProvided }
  *     schema: { adapters: [myZodAdapter] },        // TypeBox is built in
  *     http: { pathPrefix: '/v1', scope: 'billing' }, // CreateHttp* defaults
  *     onCreate: (procedure) => log(procedure.kind, procedure.name),
+ *     // middleware: [ myFactoryGuard ],   // runs with final ctx + input for every proc
  *   })
  * ```
  *
@@ -26,6 +27,8 @@ import type { AnyProcedureRegistration, ProceduresOptions, TNoContextProvided }
  * - `TExtendedConfig` — extra per-procedure config fields (e.g. `scope`,
  *   `version`, auth flags) carried through to registrations, `info`, and
  *   `onCreate`.
+ * - `middleware` — factory-level middleware with access to the final ctx + input
+ *   ("parse the incoming call") for authz, enrichment, etc. See `FactoryMiddleware`.
  */
 export function Procedures<TContext = TNoContextProvided, TExtendedConfig = unknown>(
   options?: ProceduresOptions<TContext, TExtendedConfig>,
@@ -39,6 +42,7 @@ export function Procedures<TContext = TNoContextProvided, TExtendedConfig = unkn
     adapters: [...(options?.schema?.adapters ?? []), typeboxAdapter],
     compile: createValidatorCompiler(options?.validation === false ? undefined : options?.validation),
     httpDefaults: options?.http,
+    middlewares: options?.middleware ?? [],
   }
 
   const Create = makeCreate<TContext, TExtendedConfig>(runtime)

package/src/core/types.ts

@@ -1,7 +1,7 @@
 import type * as AJV from 'ajv'
 import type { ProcedureError } from './errors.js'
 import type { SchemaAdapter } from '../schema/adapter.js'
-import type { TJSONSchema } from '../schema/json-schema.js'
+import type { Infer, Prettify, TJSONSchema } from '../schema/json-schema.js'
 import type { Validate } from '../schema/compile.js'
 
 export type TNoContextProvided = unknown
@@ -69,7 +69,64 @@ export type TStreamProcedureRegistration<TContext = unknown, TExtendedConfig = u
 
 export type HttpMethod = 'get' | 'post' | 'put' | 'delete' | 'patch' | 'head'
 
-export type TCreateHttpConfig<TReq, TRes, TErrorKey extends string = string> = {
+/**
+ * Canonical shape for `schema.req` channels.
+ * Used both to constrain generics and to provide autocomplete when writing
+ * `CreateHttp` / `CreateHttpStream` config objects.
+ *
+ * Note: RPC `Create` / `CreateStream` use a flatter `schema: { params?, yieldType?, returnType? }`
+ * directly (no extra container generic), so they don't need an equivalent named input shape.
+ */
+export type THttpReqInput = {
+  pathParams?: unknown
+  query?: unknown
+  body?: unknown
+  headers?: unknown
+}
+
+/**
+ * Canonical shape for `schema.res` on CreateHttp (CreateHttpStream only supports `headers`).
+ */
+export type THttpResInput = {
+  body?: unknown
+  headers?: unknown
+}
+
+/**
+ * @internal Helper to surface literal channel keys for autocomplete
+ * while still threading the user's concrete generic schemas through for inference.
+ */
+export type HttpSchemaInput<Base, T> = Base & (T extends undefined ? {} : T)
+
+/**
+ * @internal Shared helper for typing the destructured `req` argument passed to
+ * CreateHttp / CreateHttpStream handlers. Mirrors the per-channel Infer.
+ */
+export type HttpReq<TReq> = TReq extends Record<string, unknown>
+  ? Prettify<{ [K in keyof TReq]: Infer<TReq[K]> }>
+  : undefined
+
+/**
+ * Shape used for the `schema` option of `CreateHttpStream`.
+ * Reuses the same req input shape as CreateHttp for autocomplete consistency.
+ */
+export type THttpStreamSchema<
+  TReq extends THttpReqInput | undefined = undefined,
+  TYield = unknown,
+  TReturn = void,
+  TResHeaders = undefined,
+> = {
+  req?: HttpSchemaInput<THttpReqInput, TReq>
+  yield?: TYield
+  returnType?: TReturn
+  res?: TResHeaders extends undefined ? undefined : { headers: TResHeaders }
+}
+
+export type TCreateHttpConfig<
+  TReq extends THttpReqInput | undefined = undefined,
+  TRes extends THttpResInput | undefined = undefined,
+  TErrorKey extends string = string,
+> = {
   path: string
   method: HttpMethod
   successStatus?: number
@@ -78,8 +135,10 @@ export type TCreateHttpConfig<TReq, TRes, TErrorKey extends string = string> = {
   description?: string
   /** Optional — a no-input, no-output route (e.g. a 204 logout) may omit it. */
   schema?: {
-    req?: TReq
-    res?: TRes
+    // HttpSchemaInput surfaces the channel keys for IDE autocomplete / excess-property checking
+    // while the generic part carries the caller's concrete schema (for Infer + handler typing).
+    req?: HttpSchemaInput<THttpReqInput, TReq>
+    res?: HttpSchemaInput<THttpResInput, TRes>
   }
 }
 
@@ -193,4 +252,40 @@ export type ProceduresOptions<TContext = unknown, TExtendedConfig = unknown> = {
     pathPrefix?: string
     scope?: string
   }
+
+  /**
+   * Optional middleware that runs for *every* procedure defined via this factory.
+   * Runs after schema validation but before the user handler, with the *same*
+   * context the handler receives (including injected `error()` and `signal`).
+   *
+   * Use this for cross-cutting logic that needs the resolved `TContext` + the
+   * incoming call data ("parse the incoming call"):
+   * - Authorization / tenancy checks using `ctx.user` + `input`
+   * - Enriching ctx for all procedures on the factory
+   * - Auditing, feature flags, etc.
+   *
+   * The middleware receives a `next` function. Call `await next({ ctx?, input? })`
+   * to continue (optionally with augmented ctx or transformed input). You may
+   * also return/throw early.
+   *
+   * Works for both direct calls and all adapters. Complements (runs after)
+   * builder-level middleware on HonoAppBuilder.
+   */
+  middleware?: FactoryMiddleware<TContext>[]
 }
+
+/**
+ * Middleware defined on a Procedures factory.
+ *
+ * - `ctx` is the fully resolved context (your TContext + `error()` + `signal`).
+ * - `input` is the (already schema-validated) call argument:
+ *   - For Create / CreateStream: the `params` object
+ *   - For CreateHttp / CreateHttpStream: the `{ pathParams?, query?, body?, headers? }`
+ * - Call `next()` (or `next({ ctx: augmented, input: transformed })`) to proceed.
+ */
+export type FactoryMiddleware<TContext = unknown> = (opts: {
+  ctx: Prettify<TContext & TLocalContext>
+  input: unknown
+  next: (opts?: { ctx?: any; input?: unknown }) => Promise<any> | AsyncGenerator<any, any, unknown>
+}) => Promise<any> | AsyncGenerator<any, any, unknown> | void
+

package/src/exports.ts

@@ -23,10 +23,16 @@ export type {
   THttpProcedureRegistration,
   THttpStreamProcedureRegistration,
   TCreateHttpConfig,
+  THttpReqInput,
+  THttpResInput,
+  THttpStreamSchema,
+  HttpSchemaInput,
+  HttpReq,
   TLocalContext,
   TStreamContext,
   TNoContextProvided,
   HttpMethod,
+  FactoryMiddleware,
 } from './core/types.js'
 export type { HttpReturn } from './core/create-http.js'
 export {
@@ -56,9 +62,5 @@ export type { Infer, TSchemaLib, TJSONSchema, Prettify } from './schema/json-sch
 
 // Doc envelope — offline codegen input
 export { writeDocEnvelope } from './server/doc-envelope.js'
-// `generatorVersion` metadata lives on `ts-procedures/server`
-// (DOC_ENVELOPE_GENERATOR_VERSION) — it's niche telemetry. The spec version is
-// the one consumers branch on, so it gets the prominent top-level export.
-export { DOC_ENVELOPE_SPEC_VERSION } from './server/spec-version.js'
 export type { DocEnvelopeSource } from './server/doc-envelope.js'
 export type { DocEnvelope } from './server/types.js'

package/src/schema/compute-schema.test.ts

@@ -245,22 +245,6 @@ describe('computeSchema', () => {
       ).toThrow(/Error extracting json schema schema\.req\.query/)
     })
 
-    it('handles Type.Optional(Type.Unsafe(...)) without leaking ~markers into strict AJV or output', () => {
-      // typebox >= 1.2.0: this composition emits `~unsafe`/`~optional` as
-      // enumerable props, which crashed strict AJV and polluted the JSON Schema.
-      const schema = {
-        params: Type.Object({ x: Type.Optional(Type.Unsafe({ type: 'string' })) }),
-      }
-
-      const result = computeSchema('test-procedure', schema, options)
-
-      // No registration crash, and the stored JSON Schema is clean.
-      expect(JSON.stringify(result.jsonSchema.params)).not.toMatch(/~/)
-      expect((result.jsonSchema.params as any).properties.x).toEqual({ type: 'string' })
-      // Validator works against the cleaned schema.
-      expect(result.validations.params!({ x: 'hello' })).toEqual({})
-    })
-
     it('throws a compile error when the schema is recognized but invalid JSON Schema', () => {
       // Looks like a TypeBox schema (has ~kind) but AJV rejects it at compile time
       const recognizedButInvalid = { '~kind': 'Object', type: 'not-a-real-type' }

package/src/schema/compute-schema.ts

@@ -2,7 +2,6 @@ import { ProcedureRegistrationError } from '../core/errors.js'
 import type { DefinitionInfo } from '../core/definition-site.js'
 import { extractJsonSchema } from './adapter.js'
 import type { SchemaAdapter } from './adapter.js'
-import { stripInternalKeywords } from './strip-internal-keywords.js'
 import type { TJSONSchema } from './json-schema.js'
 import type { TSchemaValidationError, Validate, ValidatorCompiler } from './compile.js'
 
@@ -68,10 +67,7 @@ function extractChannel(ctx: ComputeContext, channel: string, raw: unknown): TJS
       `Error extracting json schema ${channel} - it might be empty or not recognized by any schema adapter (registered: ${known})`,
     )
   }
-  // Strip TypeBox internal markers (`~unsafe`/`~optional`/…) that some
-  // compositions leak as enumerable properties — they break strict AJV and
-  // pollute serialized docs/codegen. See strip-internal-keywords.ts.
-  return stripInternalKeywords(extracted)
+  return extracted
 }
 
 /** Extracts and compiles one validated channel. */

package/src/schema/typebox.test.ts

@@ -9,18 +9,6 @@ describe('typebox schema detection', () => {
     expect(isTypeboxSchema(typebox)).toBe(true)
   })
 
-  test('it recognizes a top-level Type.Unsafe schema (~unsafe marker, no ~kind)', () => {
-    // typebox >= 1.2.0: Type.Unsafe carries `~unsafe` INSTEAD of `~kind`.
-    expect(isTypeboxSchema(Type.Unsafe({ type: 'string' }))).toBe(true)
-  })
-
-  test('it recognizes any future ~-prefixed marker (convention, not a name list)', () => {
-    // Detection keys off TypeBox's `~` namespace convention, so a marker that
-    // doesn't exist yet is still recognized without a code change.
-    const futureMarker = { '~somethingNew': true, type: 'object' }
-    expect(isTypeboxSchema(futureMarker)).toBe(true)
-  })
-
   test('it rejects non-TypeBox values', () => {
     expect(isTypeboxSchema({ type: 'object' })).toBe(false)
     expect(isTypeboxSchema('string value')).toBe(false)

package/src/schema/typebox.ts

@@ -3,29 +3,10 @@ import type { TJSONSchema } from './json-schema.js'
 
 const TYPEBOX_KIND = Symbol.for('TypeBox.Kind')
 
-/** TypeBox v1 prefixes every internal marker key with `~`. */
-const TILDE = '~'.charCodeAt(0)
-
-/**
- * TypeBox v1 namespaces all of its internal markers under a `~` prefix
- * (`~kind`, `~unsafe`, `~optional`, ...) — non-enumerable own properties that
- * stay out of the serialized JSON Schema. Detecting the *convention* rather
- * than specific marker names means new markers (e.g. `~unsafe`, added in
- * typebox 1.2.0 and used by `Type.Unsafe(...)` *instead of* `~kind`) are
- * recognized without a code change. Reflect.ownKeys is required because these
- * markers are non-enumerable.
- */
-function hasTypeBoxV1Marker(schema: object): boolean {
-  for (const key of Reflect.ownKeys(schema)) {
-    if (typeof key === 'string' && key.charCodeAt(0) === TILDE) return true
-  }
-  return false
-}
-
 /**
  * Built-in adapter for TypeBox (`import { Type } from 'typebox'`).
  *
- * Detection covers both typebox v1 (any `~`-prefixed marker) and legacy
+ * Detection covers both typebox v1 (`~kind` property) and legacy
  * `@sinclair/typebox` 0.3x (`Symbol.for('TypeBox.Kind')`). TypeBox schemas
  * already ARE JSON Schema, so conversion is the identity.
  */
@@ -33,7 +14,7 @@ export const typeboxAdapter: SchemaAdapter = {
   name: 'typebox',
   detect(schema: unknown): boolean {
     if (typeof schema !== 'object' || schema === null) return false
-    return hasTypeBoxV1Marker(schema) || TYPEBOX_KIND in schema
+    return '~kind' in schema || TYPEBOX_KIND in schema
   },
   toJsonSchema(schema: unknown): TJSONSchema {
     return schema as TJSONSchema

package/src/server/context.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest'
-import { resolveFactoryContext } from './context.js'
+import { resolveFactoryContext, composeContextInits } from './context.js'
 
 describe('resolveFactoryContext', () => {
   it('returns a plain value as-is', async () => {
@@ -19,4 +19,42 @@ describe('resolveFactoryContext', () => {
       resolveFactoryContext(async () => ({ ready: true }), null),
     ).resolves.toEqual({ ready: true })
   })
+
+  it('resolves an array of inits with shallow merge (later wins)', async () => {
+    const raw = { id: 'r1' }
+    const composed = [
+      { a: 1 },
+      (r: any) => ({ b: r.id }),
+      async () => ({ c: 3 }),
+    ]
+    await expect(resolveFactoryContext(composed as any, raw)).resolves.toEqual({
+      a: 1,
+      b: 'r1',
+      c: 3,
+    })
+  })
+
+  it('later layers override earlier keys', async () => {
+    const layers = [{ tenant: 't1' }, { tenant: 't2', extra: true }]
+    await expect(resolveFactoryContext(layers as any, {})).resolves.toEqual({
+      tenant: 't2',
+      extra: true,
+    })
+  })
+})
+
+describe('composeContextInits', () => {
+  it('returns a reusable composed initializer', async () => {
+    const init = composeContextInits<{ token: string | undefined }, { token?: string }>(
+      { base: true } as any,
+      (r: { token?: string }) => ({ token: r.token }),
+    )
+    const out = await resolveFactoryContext(init, { token: 'abc' })
+    expect(out).toEqual({ base: true, token: 'abc' })
+  })
+
+  it('handles empty compose as empty object', async () => {
+    const init = composeContextInits()
+    await expect(resolveFactoryContext(init, {})).resolves.toEqual({})
+  })
 })

package/src/server/context.ts

@@ -2,17 +2,67 @@
  * A factory context as accepted by server adapters' `register()`: either the
  * context value itself, or a function deriving it from the adapter's request
  * context per request (sync or async).
+ *
+ * Arrays are supported for composition (resolved left-to-right with shallow
+ * merge of object results). Use `composeContextInits` for a reusable composed
+ * initializer.
  */
 export type FactoryContextInit<TContext, TRaw> =
   | TContext
   | ((raw: TRaw) => TContext | Promise<TContext>)
+  | Array<FactoryContextInit<TContext, TRaw>>
 
-/** Resolves a {@link FactoryContextInit} for one request. */
+/**
+ * Compose multiple context initializers (values or functions) into one.
+ * Later initializers shallow-merge over earlier results (object case).
+ * Functions are resolved in order against the raw + the accumulating context.
+ */
+export function composeContextInits<TContext, TRaw>(
+  ...inits: FactoryContextInit<TContext, TRaw>[]
+): FactoryContextInit<TContext, TRaw> {
+  const flat = inits.flat() as FactoryContextInit<TContext, TRaw>[]
+  if (flat.length === 0) return {} as TContext
+  if (flat.length === 1) return flat[0]!
+
+  return async (raw: TRaw): Promise<TContext> => {
+    let acc: any = {}
+    for (const init of flat) {
+      const part = typeof init === 'function'
+        ? await (init as (r: TRaw) => TContext | Promise<TContext>)(raw)
+        : init
+      if (part && typeof part === 'object') {
+        acc = { ...acc, ...part }
+      } else if (part !== undefined) {
+        // Non-object last-wins (rare, but supported)
+        acc = part
+      }
+    }
+    return acc as TContext
+  }
+}
+
+/** Resolves a {@link FactoryContextInit} (or array) for one request. */
 export async function resolveFactoryContext<TContext, TRaw>(
   init: FactoryContextInit<TContext, TRaw>,
   raw: TRaw,
 ): Promise<TContext> {
-  return typeof init === 'function'
-    ? await (init as (raw: TRaw) => TContext | Promise<TContext>)(raw)
-    : init
+  if (Array.isArray(init)) {
+    // Use the same merge loop here to avoid calling a potentially non-fn value.
+    let acc: any = {}
+    for (const i of init) {
+      const part = typeof i === 'function'
+        ? await (i as (r: TRaw) => TContext | Promise<TContext>)(raw)
+        : i
+      if (part && typeof part === 'object') {
+        acc = { ...acc, ...part }
+      } else if (part !== undefined) {
+        acc = part
+      }
+    }
+    return acc as TContext
+  }
+  if (typeof init === 'function') {
+    return await (init as (raw: TRaw) => TContext | Promise<TContext>)(raw)
+  }
+  return init
 }