ts-procedures 8.5.0 → 9.0.0

package/src/{index.test.ts → core/procedures.test.ts}

@@ -1,7 +1,6 @@
- 
 import { describe, expect, it, test } from 'vitest'
-import { Procedures } from './index.js'
-import { v } from 'suretype'
+import { Procedures } from './procedures.js'
+import { ProcedureRegistrationError } from './errors.js'
 import { Type } from 'typebox'
 
 describe('Procedures', () => {
@@ -26,8 +25,8 @@ describe('Procedures', () => {
       'test-docs',
       {
         schema: {
-          params: v.object({ name: v.string().required() }),
-          returnType: v.string(),
+          params: Type.Object({ name: Type.String() }),
+          returnType: Type.String(),
         },
       },
       async () => {
@@ -62,6 +61,9 @@ describe('Procedures', () => {
     expect(() => {
       Create('DuplicateTest', {}, async () => 'second')
     }).toThrow('Procedure with name DuplicateTest is already registered')
+    expect(() => {
+      Create('DuplicateTest', {}, async () => 'second')
+    }).toThrow(ProcedureRegistrationError)
   })
 
   test('Procedures - getProcedure returns specific procedure', () => {
@@ -122,11 +124,11 @@ describe('Procedures', () => {
   })
 })
 
-describe('builder.config.noRuntimeValidation', () => {
-  test('noRuntimeValidation does not interfere with onCreate callback', async () => {
+describe('Procedures({ validation: false })', () => {
+  test('validation: false does not interfere with onCreate callback', async () => {
     const seen: string[] = []
     const { Create } = Procedures({
-      config: { noRuntimeValidation: true },
+      validation: false,
       onCreate: (proc) => {
         seen.push(proc.name)
       },
@@ -141,9 +143,9 @@ describe('builder.config.noRuntimeValidation', () => {
     expect(seen).toEqual(['Registered'])
   })
 
-  test('noRuntimeValidation: false is rejected by the type system', () => {
-    // @ts-expect-error - only `true` (or omitted) is allowed for noRuntimeValidation
-    void Procedures({ config: { noRuntimeValidation: false } })
+  test('validation: true is rejected by the type system', () => {
+    // @ts-expect-error - only `false` or `{ ajv }` (or omitted) is allowed for validation
+    void Procedures({ validation: true })
   })
 })
 

package/src/core/procedures.ts

@@ -0,0 +1,75 @@
+import { makeCreate } from './create.js'
+import { makeCreateStream } from './create-stream.js'
+import { makeCreateHttp } from './create-http.js'
+import { makeCreateHttpStream } from './create-http-stream.js'
+import { createValidatorCompiler } from '../schema/compile.js'
+import { typeboxAdapter } from '../schema/typebox.js'
+import type { FactoryRuntime } from './internal.js'
+import type { AnyProcedureRegistration, ProceduresOptions, TNoContextProvided } from './types.js'
+
+/**
+ * Creates a procedure factory.
+ *
+ * ```ts
+ * type Ctx = { db: Db }
+ * const { Create, CreateStream, CreateHttp, CreateHttpStream, getProcedures } =
+ *   Procedures<Ctx>({
+ *     validation: { ajv: { coerceTypes: false } }, // or `false` to skip per-call validation
+ *     schema: { adapters: [myZodAdapter] },        // TypeBox is built in
+ *     http: { pathPrefix: '/v1', scope: 'billing' }, // CreateHttp* defaults
+ *     onCreate: (procedure) => log(procedure.kind, procedure.name),
+ *   })
+ * ```
+ *
+ * - `TContext` — the context every handler receives (plus injected `error()`
+ *   and `signal`).
+ * - `TExtendedConfig` — extra per-procedure config fields (e.g. `scope`,
+ *   `version`, auth flags) carried through to registrations, `info`, and
+ *   `onCreate`.
+ */
+export function Procedures<TContext = TNoContextProvided, TExtendedConfig = unknown>(
+  options?: ProceduresOptions<TContext, TExtendedConfig>,
+) {
+  const registry = new Map<string, AnyProcedureRegistration<TContext, TExtendedConfig>>()
+
+  const runtime: FactoryRuntime<TContext, TExtendedConfig> = {
+    registry,
+    onCreate: options?.onCreate,
+    skipValidation: options?.validation === false,
+    adapters: [...(options?.schema?.adapters ?? []), typeboxAdapter],
+    compile: createValidatorCompiler(options?.validation === false ? undefined : options?.validation),
+    httpDefaults: options?.http,
+  }
+
+  const Create = makeCreate<TContext, TExtendedConfig>(runtime)
+  const CreateStream = makeCreateStream<TContext, TExtendedConfig>(runtime)
+  const CreateHttp = makeCreateHttp<TContext>(runtime)
+  const CreateHttpStream = makeCreateHttpStream<TContext>(runtime)
+
+  return {
+    /** All registered procedures, in registration order. */
+    getProcedures: () => {
+      return Array.from(registry.values())
+    },
+
+    /** A specific procedure by name. */
+    getProcedure: (name: string) => {
+      return registry.get(name)
+    },
+
+    /** Removes a procedure by name. Returns whether it existed. */
+    removeProcedure: (name: string) => {
+      return registry.delete(name)
+    },
+
+    /** Clears all registered procedures. */
+    clear: () => {
+      registry.clear()
+    },
+
+    Create,
+    CreateStream,
+    CreateHttp,
+    CreateHttpStream,
+  }
+}

package/src/core/types.ts

@@ -0,0 +1,195 @@
+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 { Validate } from '../schema/compile.js'
+
+export type TNoContextProvided = unknown
+
+/**
+ * Context the framework injects into every handler on top of the
+ * factory-level `TContext`.
+ */
+export type TLocalContext = {
+  /** Creates a `ProcedureError` carrying this procedure's name + definition site. */
+  error: (message: string, meta?: object) => ProcedureError
+  /** Present when the server implementation provides one (HonoAppBuilder does). */
+  signal?: AbortSignal
+}
+
+/** Stream handlers always get a signal (aborts on client disconnect or completion). */
+export type TStreamContext = TLocalContext & {
+  signal: AbortSignal
+}
+
+/**
+ * Discriminant on every procedure registration that drives builder routing.
+ *
+ * - `'rpc'` — Create() registration
+ * - `'rpc-stream'` — CreateStream() registration
+ * - `'http'` — CreateHttp() registration
+ * - `'http-stream'` — CreateHttpStream() registration
+ */
+export type ProcedureKind = 'rpc' | 'rpc-stream' | 'http' | 'http-stream'
+
+export type TProcedureRegistration<TContext = unknown, TExtendedConfig = unknown> = {
+  name: string
+  kind: 'rpc'
+  config: {
+    description?: string
+    schema?: {
+      params?: TJSONSchema
+      returnType?: TJSONSchema
+    }
+    validation?: {
+      params?: Validate
+    }
+  } & TExtendedConfig
+  handler: (ctx: TContext, params?: any) => Promise<any>
+}
+
+export type TStreamProcedureRegistration<TContext = unknown, TExtendedConfig = unknown> = {
+  name: string
+  kind: 'rpc-stream'
+  config: {
+    description?: string
+    schema?: {
+      params?: TJSONSchema
+      yieldType?: TJSONSchema
+      returnType?: TJSONSchema
+    }
+    validation?: {
+      params?: Validate
+      yield?: Validate
+    }
+    validateYields?: boolean
+  } & TExtendedConfig
+  handler: (ctx: TContext, params?: any) => AsyncGenerator<any, any, unknown>
+}
+
+export type HttpMethod = 'get' | 'post' | 'put' | 'delete' | 'patch' | 'head'
+
+export type TCreateHttpConfig<TReq, TRes, TErrorKey extends string = string> = {
+  path: string
+  method: HttpMethod
+  successStatus?: number
+  scope?: string
+  errors?: TErrorKey[]
+  description?: string
+  schema: {
+    req?: TReq
+    res?: TRes
+  }
+}
+
+export type THttpProcedureRegistration<TContext = unknown> = {
+  name: string
+  kind: 'http'
+  config: {
+    path: string
+    method: HttpMethod
+    successStatus?: number
+    scope?: string
+    errors?: string[]
+    description?: string
+    schema?: {
+      req?: Record<string, TJSONSchema>
+      res?: { body?: TJSONSchema; headers?: TJSONSchema }
+    }
+    validation?: {
+      req?: Record<string, Validate>
+    }
+  }
+  handler: (ctx: TContext, req?: any) => Promise<any>
+}
+
+export type THttpStreamProcedureRegistration<TContext = unknown> = {
+  name: string
+  kind: 'http-stream'
+  config: {
+    path: string
+    method: HttpMethod
+    scope?: string
+    errors?: string[]
+    description?: string
+    schema?: {
+      req?: Record<string, TJSONSchema>
+      res?: { headers?: TJSONSchema }
+      yield?: TJSONSchema
+      returnType?: TJSONSchema
+    }
+    validation?: {
+      req?: Record<string, Validate>
+      yield?: Validate
+    }
+    validateYields?: boolean
+  }
+  handler: (
+    ctx: TContext,
+    req?: any,
+  ) => Promise<{ stream: AsyncGenerator<any, any, unknown>; initialHeaders?: Record<string, string> }>
+}
+
+/**
+ * The shape every creator returns: the handler under its own name (so
+ * `const { GetUser } = Create('GetUser', ...)` works), the same handler as
+ * `procedure`, and the introspectable `info`.
+ */
+export type ProcedureResult<TName extends string, THandler, TInfo> = {
+  [K in TName]: THandler
+} & {
+  procedure: THandler
+  info: TInfo
+}
+
+/** Union of all four registration shapes a factory can hold. */
+export type AnyProcedureRegistration<TContext = unknown, TExtendedConfig = unknown> =
+  | TProcedureRegistration<TContext, TExtendedConfig>
+  | TStreamProcedureRegistration<TContext, TExtendedConfig>
+  | THttpProcedureRegistration<TContext>
+  | THttpStreamProcedureRegistration<TContext>
+
+/**
+ * Options for `Procedures()`.
+ */
+export type ProceduresOptions<TContext = unknown, TExtendedConfig = unknown> = {
+  /**
+   * Called once per registered procedure with the full registration object.
+   * Use the `kind` discriminant to narrow to the specific shape. This is the
+   * seam for custom framework integration (Fastify, Koa, raw http, ...).
+   */
+  onCreate?: (procedure: AnyProcedureRegistration<TContext, TExtendedConfig>) => void
+
+  /**
+   * Runtime validation behavior:
+   * - omitted — validate every call with the default AJV configuration
+   *   (`allErrors`, `coerceTypes`, `removeAdditional`)
+   * - `false` — skip per-call validation for the whole factory. JSON Schema
+   *   and validators are still computed at registration time (bad schemas
+   *   still fail fast); only the per-call runs are skipped. For trusted
+   *   internal factories whose callers are type-checked at build time.
+   * - `{ ajv }` — AJV options merged over the defaults, or a configured
+   *   `Ajv` instance used as-is.
+   */
+  validation?: false | { ajv?: AJV.Ajv | AJV.Options }
+
+  /**
+   * Schema-library integration. TypeBox is built in; prepend adapters here to
+   * register procedures with other schema libraries (see `SchemaAdapter`).
+   */
+  schema?: {
+    adapters?: SchemaAdapter[]
+  }
+
+  /**
+   * Factory-level defaults for `CreateHttp` / `CreateHttpStream` routes:
+   * - `pathPrefix` — prepended to every route's `path` at registration time
+   *   (this is part of the route's identity, unlike a server adapter's mount
+   *   prefix)
+   * - `scope` — default codegen scope for routes that don't set one
+   */
+  http?: {
+    pathPrefix?: string
+    scope?: string
+  }
+}

package/src/exports.ts

@@ -1,11 +1,60 @@
-export * from './index.js'
-export * from './errors.js'
-export * from './stack-utils.js'
-export * from './schema/extract-json-schema.js'
-export * from './schema/parser.js'
-export * from './schema/resolve-schema-lib.js'
-export * from './schema/types.js'
-export type { HttpReturn } from './create-http.js'
-export type { TCreateHttpConfig } from './types.js'
-export { writeDocEnvelope, type DocEnvelopeSource } from './doc-envelope.js'
-export type { DocEnvelope } from './implementations/types.js'
+/**
+ * ts-procedures — root entry point.
+ *
+ * Subpath exports:
+ * - `ts-procedures/hono` — HonoAppBuilder server adapter
+ * - `ts-procedures/astro` — Astro catch-all adapter (delegates to Hono apps)
+ * - `ts-procedures/server` — transport-agnostic server layer (build your own adapter)
+ * - `ts-procedures/http` — HTTP doc/config types (types only)
+ * - `ts-procedures/http-docs` — DocRegistry (multi-app envelope aggregation)
+ * - `ts-procedures/http-errors` — error taxonomy helpers
+ * - `ts-procedures/client` — runtime client for generated code
+ * - `ts-procedures/codegen` — client code generation (also: npx ts-procedures-codegen)
+ */
+
+// Core — the Procedures factory and everything handlers touch
+export { Procedures } from './core/procedures.js'
+export type {
+  ProceduresOptions,
+  ProcedureKind,
+  AnyProcedureRegistration,
+  TProcedureRegistration,
+  TStreamProcedureRegistration,
+  THttpProcedureRegistration,
+  THttpStreamProcedureRegistration,
+  TCreateHttpConfig,
+  TLocalContext,
+  TStreamContext,
+  TNoContextProvided,
+  HttpMethod,
+} from './core/types.js'
+export type { HttpReturn } from './core/create-http.js'
+export {
+  ProcedureError,
+  ProcedureValidationError,
+  ProcedureRegistrationError,
+  ProcedureYieldValidationError,
+} from './core/errors.js'
+export type { ProcedureErrorKind } from './core/errors.js'
+export { captureDefinitionInfo, formatDefinitionInfo } from './core/definition-site.js'
+export type { DefinitionInfo, DefinitionLocation } from './core/definition-site.js'
+
+// Schema — adapters, inference, validation
+export type { SchemaAdapter } from './schema/adapter.js'
+export { extractJsonSchema } from './schema/adapter.js'
+export { typeboxAdapter, isTypeboxSchema } from './schema/typebox.js'
+export { computeSchema } from './schema/compute-schema.js'
+export type { ComputedSchema } from './schema/compute-schema.js'
+export { createValidatorCompiler, DEFAULT_AJV_OPTIONS } from './schema/compile.js'
+export type {
+  Validate,
+  ValidatorCompiler,
+  ValidationOptions,
+  TSchemaValidationError,
+} from './schema/compile.js'
+export type { Infer, TSchemaLib, TJSONSchema, Prettify } from './schema/json-schema.js'
+
+// Doc envelope — offline codegen input
+export { writeDocEnvelope } from './server/doc-envelope.js'
+export type { DocEnvelopeSource } from './server/doc-envelope.js'
+export type { DocEnvelope } from './server/types.js'

package/src/schema/adapter.test.ts

@@ -0,0 +1,58 @@
+import { describe, expect, test } from 'vitest'
+import { Type } from 'typebox'
+import { extractJsonSchema } from './adapter.js'
+import type { SchemaAdapter } from './adapter.js'
+import { typeboxAdapter } from './typebox.js'
+
+describe('extractJsonSchema()', () => {
+  const typebox = Type.Object({ name: Type.String() })
+
+  test('it extracts TypeBox json-schema', () => {
+    expect(extractJsonSchema(typebox, [typeboxAdapter])).toMatchObject({
+      type: 'object',
+      properties: { name: { type: 'string' } },
+      required: ['name'],
+    })
+  })
+
+  test('it returns undefined when no adapter recognizes the value', () => {
+    expect(extractJsonSchema({ type: 'object' }, [typeboxAdapter])).toBeUndefined()
+    expect(extractJsonSchema('string value', [typeboxAdapter])).toBeUndefined()
+    expect(extractJsonSchema(null, [typeboxAdapter])).toBeUndefined()
+    expect(extractJsonSchema(undefined, [typeboxAdapter])).toBeUndefined()
+  })
+
+  test('it returns undefined when the adapter list is empty', () => {
+    expect(extractJsonSchema(typebox, [])).toBeUndefined()
+  })
+
+  test('it runs the adapter chain in order — first match wins', () => {
+    const everything: SchemaAdapter = {
+      name: 'everything',
+      detect: () => true,
+      toJsonSchema: () => ({ type: 'string' }),
+    }
+
+    // typeboxAdapter first: TypeBox schema goes through identity conversion
+    expect(extractJsonSchema(typebox, [typeboxAdapter, everything])).toBe(typebox)
+    // everything first: it claims the value before typeboxAdapter sees it
+    expect(extractJsonSchema(typebox, [everything, typeboxAdapter])).toEqual({ type: 'string' })
+  })
+
+  test('it supports custom adapters for non-TypeBox schema objects', () => {
+    class FakeZodType {
+      constructor(readonly jsonSchema: Record<string, any>) {}
+    }
+    const fakeZodAdapter: SchemaAdapter = {
+      name: 'fake-zod',
+      detect: (s) => s instanceof FakeZodType,
+      toJsonSchema: (s) => (s as FakeZodType).jsonSchema,
+    }
+
+    const schema = new FakeZodType({ type: 'object', properties: { id: { type: 'number' } } })
+    expect(extractJsonSchema(schema, [typeboxAdapter, fakeZodAdapter])).toEqual({
+      type: 'object',
+      properties: { id: { type: 'number' } },
+    })
+  })
+})

package/src/schema/adapter.ts

@@ -0,0 +1,45 @@
+import type { TJSONSchema } from './json-schema.js'
+
+/**
+ * Bridges a schema library to the framework.
+ *
+ * The framework only ever needs one thing from a schema object: its JSON
+ * Schema. Everything downstream (AJV validation, route docs, codegen) works on
+ * JSON Schema. Implement this interface to plug in any schema library:
+ *
+ * ```ts
+ * const zodAdapter: SchemaAdapter = {
+ *   name: 'zod',
+ *   detect: (s) => s instanceof z.ZodType,
+ *   toJsonSchema: (s) => z.toJSONSchema(s as z.ZodType),
+ * }
+ * const { Create } = Procedures({ schema: { adapters: [zodAdapter] } })
+ * ```
+ *
+ * Note: compile-time type inference (`Infer<T>`) is only built in for TypeBox;
+ * custom adapters get runtime validation and docs, with params inferred as
+ * `unknown` unless you annotate handler types yourself.
+ */
+export interface SchemaAdapter {
+  /** Short identifier used in registration error messages. */
+  name: string
+  /** Whether this adapter recognizes the given schema object. */
+  detect(schema: unknown): boolean
+  /** Converts a recognized schema object to JSON Schema. */
+  toJsonSchema(schema: unknown): TJSONSchema
+}
+
+/**
+ * Runs the adapter chain against a schema value. Returns the JSON Schema from
+ * the first adapter whose `detect` matches, or `undefined` when no adapter
+ * recognizes the value (the caller reports the registration error).
+ */
+export function extractJsonSchema(
+  schema: unknown,
+  adapters: readonly SchemaAdapter[],
+): TJSONSchema | undefined {
+  for (const adapter of adapters) {
+    if (adapter.detect(schema)) return adapter.toJsonSchema(schema)
+  }
+  return undefined
+}

package/src/schema/compile.test.ts

@@ -0,0 +1,95 @@
+import { describe, expect, test } from 'vitest'
+import { Type } from 'typebox'
+import * as AJV from 'ajv'
+import { createValidatorCompiler, DEFAULT_AJV_OPTIONS } from './compile.js'
+
+describe('createValidatorCompiler', () => {
+  describe('default configuration', () => {
+    const compile = createValidatorCompiler()
+
+    test('validator returns {} on success', () => {
+      const validate = compile(Type.Object({ name: Type.String(), age: Type.Number() }))
+      const result = validate({ name: 'John', age: 30 })
+      expect(result).toEqual({})
+      expect(result.errors).toBeUndefined()
+    })
+
+    test('validator returns { errors } on failure', () => {
+      const validate = compile(Type.Object({ name: Type.String() }))
+      const result = validate({})
+      expect(result.errors).toBeDefined()
+      expect(result.errors?.[0]?.message).toMatch(/must have required property 'name'/)
+    })
+
+    test('allErrors: reports every failure, not just the first', () => {
+      const validate = compile(
+        Type.Object({ name: Type.String(), age: Type.Number() }),
+      )
+      const result = validate({ name: { nested: '' }, age: 'not-a-number' })
+      expect(result.errors?.length).toEqual(2)
+    })
+
+    test('coerceTypes: coerces primitive types in place', () => {
+      const validate = compile(Type.Object({ age: Type.Number() }))
+      const value: Record<string, unknown> = { age: '30' }
+      expect(validate(value).errors).toBeUndefined()
+      expect(value.age).toBe(30)
+    })
+
+    test('removeAdditional: strips unknown properties in place', () => {
+      const validate = compile(
+        Type.Object({ name: Type.String() }, { additionalProperties: false }),
+      )
+      const value: Record<string, unknown> = { name: 'John', extra: 'gone' }
+      expect(validate(value).errors).toBeUndefined()
+      expect(value).toEqual({ name: 'John' })
+    })
+
+    test('ajv-formats is wired in (format keywords validate)', () => {
+      const validate = compile(Type.Object({ email: Type.String({ format: 'email' }) }))
+      expect(validate({ email: 'john@example.com' }).errors).toBeUndefined()
+      expect(validate({ email: 'not-an-email' }).errors).toBeDefined()
+    })
+
+    test('compile throws on an invalid JSON schema', () => {
+      expect(() => compile({ type: 'invalid-schema-type' })).toThrow()
+    })
+
+    test('DEFAULT_AJV_OPTIONS matches the documented v8 behavior', () => {
+      expect(DEFAULT_AJV_OPTIONS).toEqual({
+        allErrors: true,
+        coerceTypes: true,
+        removeAdditional: true,
+      })
+    })
+  })
+
+  describe('custom AJV options merge over the defaults', () => {
+    test('coerceTypes: false disables coercion while keeping other defaults', () => {
+      const compile = createValidatorCompiler({ ajv: { coerceTypes: false } })
+      const validate = compile(Type.Object({ age: Type.Number(), name: Type.String() }))
+
+      // No coercion: a string is no longer accepted for a number
+      expect(validate({ age: '30', name: 'John' }).errors).toBeDefined()
+      expect(validate({ age: 30, name: 'John' }).errors).toBeUndefined()
+
+      // allErrors default still applies (both bad fields reported)
+      expect(validate({ age: 'x', name: 42 }).errors?.length).toEqual(2)
+    })
+  })
+
+  describe('preconfigured Ajv instance', () => {
+    test('uses the instance as-is (no default options applied)', () => {
+      const ajv = new AJV.Ajv() // no coerceTypes, no allErrors, no formats
+      const compile = createValidatorCompiler({ ajv })
+      const validate = compile(Type.Object({ age: Type.Number(), name: Type.String() }))
+
+      // No coercion from the default config
+      expect(validate({ age: '30', name: 'John' }).errors).toBeDefined()
+      // No allErrors: only the first failure is reported
+      expect(validate({ age: 'x', name: 42 }).errors?.length).toEqual(1)
+      // Valid input still passes
+      expect(validate({ age: 30, name: 'John' }).errors).toBeUndefined()
+    })
+  })
+})

package/src/schema/compile.ts

@@ -0,0 +1,64 @@
+import { default as addFormats } from 'ajv-formats'
+import * as AJV from 'ajv'
+import type { TJSONSchema } from './json-schema.js'
+
+export type TSchemaValidationError = AJV.ErrorObject
+
+/**
+ * A compiled validator. Returns `{}` on success, `{ errors }` on failure —
+ * the same shape AJV-based validators have carried since v1, and the shape
+ * every registration's `config.validation.*` function exposes.
+ */
+export type Validate = (value?: any) => { errors?: TSchemaValidationError[] }
+
+/** Compiles a JSON Schema into a {@link Validate} function. */
+export type ValidatorCompiler = (jsonSchema: TJSONSchema) => Validate
+
+/**
+ * `Procedures({ validation })` shape:
+ * - omitted — validate with the default AJV configuration
+ * - `false` — skip per-call validation entirely (schemas/validators are still
+ *   computed at registration time so bad schemas fail fast)
+ * - `{ ajv }` — custom AJV options merged over the defaults, or a fully
+ *   configured `Ajv` instance to use as-is
+ */
+export type ValidationOptions = false | { ajv?: AJV.Ajv | AJV.Options }
+
+/**
+ * Default AJV configuration — unchanged from every prior major version:
+ * report all errors, coerce primitive types, strip unknown properties.
+ */
+export const DEFAULT_AJV_OPTIONS: AJV.Options = {
+  allErrors: true,
+  coerceTypes: true,
+  removeAdditional: true,
+}
+
+function isAjvInstance(value: AJV.Ajv | AJV.Options | undefined): value is AJV.Ajv {
+  return typeof (value as { compile?: unknown } | undefined)?.compile === 'function'
+}
+
+/**
+ * Creates a {@link ValidatorCompiler} backed by AJV. Each `Procedures()`
+ * factory owns one compiler, so AJV configuration is per-factory instead of
+ * a module-level singleton.
+ */
+export function createValidatorCompiler(options?: { ajv?: AJV.Ajv | AJV.Options }): ValidatorCompiler {
+  const ajv = isAjvInstance(options?.ajv)
+    ? options.ajv
+    : // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+      // @ts-expect-error ajv-formats' types lag behind ajv's
+      (addFormats(new AJV.Ajv({ ...DEFAULT_AJV_OPTIONS, ...options?.ajv })) as AJV.Ajv)
+
+  return function compile(jsonSchema: TJSONSchema): Validate {
+    const validator = ajv.compile(jsonSchema)
+    return (value?: any) => {
+      const valid = validator(value)
+      if (!valid) {
+        const errors = validator.errors
+        return { errors: errors?.length ? [...errors] : undefined }
+      }
+      return {}
+    }
+  }
+}