pipework 0.251.0 → 0.252.1

package/src/request/di/resolve.ts

@@ -0,0 +1,271 @@
+import type { Schema } from '../../data/schema/types.js'
+import { DEFAULT_DB } from './types.js'
+import type { Handler, HandlerMeta, CheckpointFn, BinaryUpload, MultipartUpload } from './types.js'
+import type { DB } from '../../data/db/types.js'
+import type { Flow } from '../context/types.js'
+import type { Manifold } from '../../core/pipework.js'
+import type { TenantConfig } from '../../auth/tenant/types.js'
+import { executeInTransaction } from '../context/run-in-transaction.js'
+import type { HttpRequest, HttpResponse } from '../http/types.js'
+import { requireContext } from '../context/store.js'
+import { verifyTransactionBinding } from '../context/guard.js'
+import { UnauthorizedError, ValidationError } from '../../core/errors/index.js'
+import { parse } from '../../data/schema/parse.js'
+import { unboundDb } from '../../data/db/unbound.js'
+import { createScopedDb, createTenantGuardDb } from '../../auth/tenant/scoped-db.js'
+
+export interface ResolveOptions {
+  readonly request?: HttpRequest
+  readonly response?: HttpResponse
+  readonly rawBody?: Buffer
+  readonly upload?: BinaryUpload | MultipartUpload
+  /**
+   * The `checkpoint` primitive for a manual-transaction handler — a job or a
+   * route. Injected as the `checkpoint` dep; the top-level database deps are
+   * then NOT injected, since a non-transactional handle outside a checkpoint
+   * would be a footgun.
+   */
+  readonly checkpoint?: CheckpointFn
+  /** A job's own signal, injected as the `signal` dep. */
+  readonly signal?: AbortSignal
+}
+
+/**
+ * Resolves the database deps a handler declared with `.use()` into the deps
+ * record keyed as the handler sees them ('db' for the default database, the
+ * name otherwise). Each handle is the context's bound transaction when one is
+ * active (request/job/checkpoint), otherwise a pooled connection.
+ *
+ * `scoped` (default `true`) wraps each handle in the tenant scope/guard proxy —
+ * the safe builder surface used for request and auto-mode job deps. The
+ * manual-mode `checkpoint` primitive passes `scoped: false` to hand the handler
+ * the raw bound transaction: a checkpointed job owns its own boundaries and runs
+ * arbitrary SQL, with tenant isolation enforced by the RLS session vars the
+ * checkpoint sets (`SET LOCAL pipework.tenant_id`), exactly as `pipe.transaction`
+ * already exposes a raw `tx`. Shared by both paths so they cannot drift.
+ */
+export function resolveDatabaseDeps(
+  databases: readonly string[],
+  ctx: Flow,
+  options?: { readonly scoped?: boolean },
+): Record<string, DB> {
+  const scoped = options?.scoped ?? true
+  const deps: Record<string, DB> = {}
+  for (const dbName of databases) {
+    const isDefault = dbName === DEFAULT_DB
+    const resolvedName = isDefault ? ctx.instance.config.defaultDatabaseName() : dbName
+    const depKey = isDefault ? 'db' : dbName
+
+    const dbConfig = ctx.instance.config.database(resolvedName)
+    const bound = ctx.transactions.get(resolvedName)
+    let rawDb: DB
+    if (bound) {
+      verifyTransactionBinding(ctx, bound, resolvedName)
+      rawDb = bound.drizzle
+    } else {
+      rawDb = unboundDb(ctx, resolvedName, dbConfig, 'A handler\'s database dependency')
+    }
+    if (!scoped) {
+      deps[depKey] = rawDb
+    } else {
+      deps[depKey] = ctx.tenant !== null ? createScopedDb(rawDb, ctx.tenant) : createTenantGuardDb(rawDb)
+    }
+  }
+  return deps
+}
+
+/** A route's query as its handler gets it: parsed by its schema, or the raw value when it has none. Throws when it fails the schema. */
+export function parseRouteQuery(meta: { readonly querySchema: Schema | null }, raw: unknown): unknown {
+  return meta.querySchema ? parse(meta.querySchema as Schema, raw, 'query') : raw
+}
+
+/** A route's params as its handler gets them: parsed by its schema, or the raw value when it has none. Throws when they fail the schema. */
+export function parseRouteParams(meta: { readonly paramsSchema: Schema | null }, raw: unknown): unknown {
+  return meta.paramsSchema ? parse(meta.paramsSchema as Schema, raw, 'params') : raw
+}
+
+/**
+ * A route's params and query as its handler gets them, for a hook that reports on a request:
+ * the parsed value, the raw one when the route has no schema, null when it fails its schema
+ * or when `meta` is null (no route known).
+ */
+export function parseRouteInputs(
+  meta: HandlerMeta | null,
+  rawQuery: unknown,
+  rawParams: unknown,
+): { readonly params: unknown; readonly query: unknown } {
+  if (meta === null) return { params: null, query: null }
+  const orNull = (read: () => unknown): unknown => { try { return read() } catch { return null } }
+  return { params: orNull(() => parseRouteParams(meta, rawParams)), query: orNull(() => parseRouteQuery(meta, rawQuery)) }
+}
+
+export async function resolveAndExecute<TDeps extends Record<string, unknown>, TReturn>(
+  handler: Handler<TDeps, TReturn>,
+  rawInput?: unknown,
+  rawQuery?: unknown,
+  rawParams?: unknown,
+  options?: ResolveOptions,
+): Promise<TReturn> {
+  const ctx = requireContext()
+  const deps: Record<string, unknown> = {}
+
+  // Manual-transaction handlers take no top-level database handle — they reach
+  // the database only inside checkpoint(), which binds a fresh tenant-scoped
+  // transaction. Inject that primitive in place of the db deps.
+  if (handler.meta.jobTransaction === 'manual') {
+    if (options?.checkpoint === undefined) {
+      throw new ValidationError(
+        'Handler declares .transaction("manual") but no checkpoint primitive was provided.\n\n' +
+        '  checkpoint() is supplied by the surface that runs the handler — jobs.execute\n' +
+        '  for a job, the HTTP server for a route. Reaching here without one means the\n' +
+        '  handler was executed directly rather than through a surface.\n',
+      )
+    }
+    deps['checkpoint'] = options.checkpoint
+  } else {
+    Object.assign(deps, resolveDatabaseDeps(handler.meta.databases, ctx))
+  }
+
+  // A job handler's type promises `signal`; one run outside executeJob gets a signal that never aborts.
+  if (options?.signal !== undefined) deps['signal'] = options.signal
+  else if (handler.meta.isJob) deps['signal'] = new AbortController().signal
+
+  if (handler.meta.requiresAuth) {
+    if (ctx.auth === null) {
+      throw new UnauthorizedError()
+    }
+    deps['auth'] = ctx.auth
+  } else if (handler.meta.authRequirement === 'optional') {
+    deps['auth'] = ctx.auth
+  }
+
+  if (handler.meta.inputSchema) {
+    deps['input'] = parse(handler.meta.inputSchema as Schema, rawInput, 'body')
+  }
+
+  if (handler.meta.querySchema) {
+    deps['query'] = parseRouteQuery(handler.meta, rawQuery)
+  }
+
+  if (handler.meta.paramsSchema) {
+    deps['params'] = parseRouteParams(handler.meta, rawParams)
+  }
+
+  if (handler.meta.wantsRequest) {
+    if (options?.request === undefined) {
+      throw new ValidationError(
+        'Handler declared .request() but no HTTP request is available.\n\n' +
+        '  This handler requires an HTTP context. It cannot be invoked as a background job\n' +
+        '  or via direct resolveAndExecute() without providing a request object.\n',
+      )
+    }
+    deps['request'] = options.request
+  }
+
+  if (handler.meta.wantsResponse) {
+    if (options?.response === undefined) {
+      throw new ValidationError(
+        'Handler declared .response() but no HTTP response is available.\n\n' +
+        '  This handler requires an HTTP context. It cannot be invoked as a background job\n' +
+        '  or via direct resolveAndExecute() without providing a response object.\n',
+      )
+    }
+    deps['response'] = options.response
+  }
+
+  if (handler.meta.wantsRawBody) {
+    if (options?.rawBody === undefined) {
+      throw new ValidationError(
+        'Handler declared .rawBody() but no raw body is available.\n\n' +
+        '  Raw body capture requires an HTTP context with body content.\n' +
+        '  This handler cannot be invoked as a background job or via GET requests\n' +
+        '  without providing a raw body buffer.\n',
+      )
+    }
+    deps['rawBody'] = options.rawBody
+  }
+
+  if (handler.meta.upload) {
+    if (options?.upload === undefined) {
+      throw new ValidationError(
+        'Handler declared .upload() but no uploaded file is available.\n\n' +
+        '  An upload is supplied by the HTTP server for a route. This handler cannot be\n' +
+        '  invoked as a background job or via direct resolveAndExecute() without one.\n',
+      )
+    }
+    deps['upload'] = options.upload
+  }
+
+  const result = await handler.execute(deps as TDeps)
+
+  if (handler.meta.outputSchemas.size > 0) {
+    if (isHandlerResponse(result)) {
+      const response = result as { status: number; body?: unknown }
+      const bodySchema = handler.meta.outputSchemas.get(response.status)
+      if (bodySchema) {
+        return { status: response.status, body: parse(bodySchema as Schema, response.body, 'response') } as TReturn
+      }
+      return result
+    }
+    const defaultSchema = handler.meta.outputSchemas.get(200)
+    if (defaultSchema) {
+      return parse(defaultSchema as Schema, result, 'response') as TReturn
+    }
+  }
+
+  return result
+}
+
+function isHandlerResponse(value: unknown): boolean {
+  return value !== null && typeof value === 'object' && 'status' in value && typeof (value as Record<string, unknown>)['status'] === 'number'
+}
+
+
+/**
+ * The databases a handler's checkpoints run against: what it declared with
+ * `.use()`, with the default-database placeholder resolved to its real name.
+ */
+export function resolveHandlerDatabases<TDeps extends Record<string, unknown>, TReturn>(
+  handler: Handler<TDeps, TReturn>,
+  instance: Manifold,
+): string[] {
+  const names = new Set<string>()
+  for (const dbName of handler.meta.databases) {
+    names.add(dbName === DEFAULT_DB ? instance.config.defaultDatabaseName() : dbName)
+  }
+  return [...names]
+}
+
+/**
+ * Builds the `checkpoint` primitive for one manual-transaction run.
+ *
+ * Every call opens a fresh top-level transaction on the handler's databases,
+ * re-establishing the context's session variables so database-side RLS sees the
+ * tenant, and commits it independently of every other checkpoint. The handler
+ * gets the raw bound transactions: it owns its own boundaries, and tenant
+ * isolation is enforced by the session vars rather than by a scoped wrapper.
+ *
+ * Shared by the job surface and the HTTP surface so the two cannot drift in
+ * what a checkpoint is.
+ */
+export function buildCheckpoint<TDeps extends Record<string, unknown>, TReturn>(
+  handler: Handler<TDeps, TReturn>,
+  ctx: Flow,
+  databases: readonly string[],
+  tenant: TenantConfig | null,
+  timeoutMs: number,
+  signal?: AbortSignal,
+  refuseWhenAborted?: AbortSignal,
+): CheckpointFn {
+  return (fn) =>
+    refuseWhenAborted?.aborted === true
+      ? Promise.reject(refuseWhenAborted.reason)
+      : executeInTransaction(
+        ctx,
+        databases,
+        tenant,
+        timeoutMs,
+        () => fn(resolveDatabaseDeps(handler.meta.databases, requireContext(), { scoped: false })),
+        signal,
+      )
+}

package/src/request/di/types.ts

@@ -0,0 +1,262 @@
+import type { CorsConfig } from '../http/types.js'
+import type { Schema } from '../../data/schema/types.js'
+import type { DB } from '../../data/db/index.js'
+import type { Readable } from 'node:stream'
+import type { BackoffConfig } from '../../async/jobs/queue.js'
+
+/** The default database name constant ('default') used when pipe() is called without a name argument. */
+export const DEFAULT_DB = '__pipework_default__' as const
+
+/** Auth requirement level for a handler — 'required', 'optional', or 'public'. */
+export type AuthRequirement = 'required' | 'optional' | 'none'
+
+/** Permission requirement attached to a handler — resource, action, scope. */
+export interface PermissionMeta {
+  readonly resource: string
+  readonly action: string
+  readonly scope?: string
+}
+
+/** Retry configuration for job handlers — maxAttempts, backoff strategy, delay. */
+export interface JobRetryConfig {
+  readonly attempts: number
+  readonly backoff?: BackoffConfig
+}
+
+/**
+ * How a job's database transaction(s) are managed.
+ *
+ * - `'auto'` (default): the framework wraps the whole `.fit` run in one outer,
+ *   tenant-scoped transaction — atomic / all-or-nothing.
+ * - `'manual'`: the framework propagates the job context but opens no outer
+ *   transaction. The handler receives a `checkpoint(fn)` primitive and owns its
+ *   own transaction boundaries, committing incrementally within a single warm
+ *   run. The contract shifts from atomic to at-least-once / idempotent-on-resume.
+ */
+export type JobTransactionMode = 'auto' | 'manual'
+
+/**
+ * The `checkpoint` primitive injected into a manual-transaction job's deps.
+ * Each call opens a fresh top-level, tenant-scoped transaction (re-establishing
+ * the tenant `SET LOCAL` session vars so database-side RLS sees the tenant),
+ * runs `fn` with the participating databases bound, and commits durably and
+ * independently of any other checkpoint. `TDb` is the record of databases the
+ * handler declared with `.use()`.
+ */
+export type Checkpoint<TDb> = <R>(fn: (dbs: TDb) => Promise<R>) => Promise<R>
+
+/** The erased runtime shape of {@link Checkpoint}, used where the db-deps type is not tracked. */
+export type CheckpointFn = <R>(fn: (dbs: Record<string, DB>) => Promise<R>) => Promise<R>
+
+/** Metadata attached to a handler — route info, auth requirements, input/output schemas, database names. */
+export interface HandlerMeta {
+  readonly databases: readonly string[]
+  readonly requiresAuth: boolean
+  readonly authRequirement: AuthRequirement
+  readonly inputSchema: Schema | null
+  readonly outputSchemas: ReadonlyMap<number, Schema>
+  readonly querySchema: Schema | null
+  readonly paramsSchema: Schema | null
+  readonly route: RouteMeta | null
+  /** This route's own CORS grant (replaces the server default); `false` closes it. */
+  readonly cors?: CorsConfig | false | null
+  /** The named rate limit class this route is in; `false` exempts it; null follows the auth requirement. */
+  readonly rateLimit?: string | false | null
+  readonly isJob: boolean
+  readonly jobType: string | null
+  readonly jobRetry: JobRetryConfig | null
+  readonly jobTimeout: number | null
+  readonly jobTransaction: JobTransactionMode
+  readonly permission: PermissionMeta | null
+  readonly wantsRequest: boolean
+  readonly wantsResponse: boolean
+  readonly wantsRawBody: boolean
+  readonly ignoresBody?: boolean
+  readonly upload?: UploadConfig | null
+  readonly file?: FileConfig | null
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  readonly onRefused?: RouteRefusedHook<any, any, any> | null
+}
+
+/** A route's file response, declared by `.file()`. */
+export interface FileConfig {
+  /** Media types the route may answer with; `type/*` wildcards allowed. */
+  readonly mediaTypes: readonly string[]
+  /** Status of the file response (default 200). */
+  readonly status: number
+}
+
+/** What pipework tells an upload route's `onRefuse` hook about a file it refused. */
+export interface UploadRefusal<TParams = unknown, TQuery = unknown> {
+  readonly status: 413 | 415
+  /** The error code in the response body. */
+  readonly code: string
+  /** Type found in the file's first bytes; null when none matched or the head was not read. */
+  readonly detectedType: string | null
+  /** Content-Type the sender declared for the file; '' when none. */
+  readonly declaredType: string
+  /** Lowercase filename extension; null without a filename or a dot. */
+  readonly extension: string | null
+  readonly filename: string | null
+  /** The request's Content-Length; null when chunked. */
+  readonly declaredLength: number | null
+  /** File bytes pipework had read when it refused. */
+  readonly bytesRead: number
+  readonly accepted: readonly string[]
+  /** The request's auth (null on a public route). */
+  readonly auth: unknown
+  readonly requestId: string
+  /**
+   * The route's params parsed by its schema exactly as the handler receives them
+   * (transforms and coercions applied); the raw params when the route declares no
+   * schema; null when they fail the schema (the request would be refused too, but
+   * a refusal of the file can win the race).
+   */
+  readonly params: TParams | null
+  /** The route's query, on the same terms as `params`. */
+  readonly query: TQuery | null
+}
+
+/**
+ * Runs once for each 413 or 415 pipework answers for a file, inside the
+ * request's context. A returned non-empty string replaces the error message;
+ * status and code stay. A throw is logged and the default message is sent.
+ */
+export type UploadRefuseHook<TParams = unknown, TQuery = unknown> = (refusal: UploadRefusal<TParams, TQuery>) => string | void | Promise<string | void>
+
+/** What pipework tells a route's `onRefused` hook about a 4xx it is answering. */
+export interface RouteRefusal<TAuth = unknown, TParams = unknown, TQuery = unknown> {
+  /** The response status, 400-499. */
+  readonly status: number
+  /** The error code in the response body. */
+  readonly code: string
+  readonly message: string
+  /** The body's `fields`; set only for VALIDATION_ERROR. */
+  readonly fields: Record<string, readonly string[]> | null
+  /** The body's `retryAfterSeconds` on a 429 that has one; else null. */
+  readonly retryAfterSeconds: number | null
+  /** The request's auth; null when auth itself refused or the request has no context. */
+  readonly auth: TAuth | null
+  /** The route's params as the handler would get them; null when they fail the schema. */
+  readonly params: TParams | null
+  /** The route's query, on the same terms as `params`. */
+  readonly query: TQuery | null
+  readonly request: { readonly headers: Record<string, string | undefined>; readonly ip: string; readonly ips: readonly string[] }
+  readonly requestId: string
+}
+
+/**
+ * Runs once for each 4xx a route answers, inside the request's context. A returned
+ * plain object is merged into the response's `error`; `code`, `message`, `fields`
+ * and `details` always keep pipework's values.
+ */
+export type RouteRefusedHook<TAuth = unknown, TParams = unknown, TQuery = unknown> =
+  (refusal: RouteRefusal<TAuth, TParams, TQuery>) => Record<string, unknown> | void | Promise<Record<string, unknown> | void>
+
+/** Upload whose whole request body is the file's bytes. */
+export interface BinaryUploadConfig<TParams = unknown, TQuery = unknown> {
+  readonly kind: 'binary'
+  /** Accepted media types, matched against the type detected from the first bytes; `type/*` wildcards allowed, and a star on each side of the slash for any type. Others get 415. */
+  readonly mediaTypes: readonly string[]
+  /** Largest accepted body in bytes. Over it gets 413. */
+  readonly maxBytes: number
+  readonly onRefuse?: UploadRefuseHook<TParams, TQuery>
+}
+
+/** Upload whose file is one part of a `multipart/form-data` body. */
+export interface MultipartUploadConfig<TParams = unknown, TQuery = unknown> {
+  readonly kind: 'multipart'
+  /** Name of the form field carrying the file. */
+  readonly file: string
+  /** Accepted media types of the file, matched against the type detected from its first bytes; `type/*` wildcards allowed, and a star on each side of the slash for any type. Others get 415. */
+  readonly mediaTypes: readonly string[]
+  /** Largest accepted file in bytes. Over it gets 413. */
+  readonly maxBytes: number
+  /** Text field names accepted ahead of the file part; any other field gets 422. */
+  readonly fields?: readonly string[]
+  readonly onRefuse?: UploadRefuseHook<TParams, TQuery>
+}
+
+export type UploadConfig = BinaryUploadConfig | MultipartUploadConfig
+
+/** The type fields shared by both upload deps. */
+interface UploadTypes {
+  /** The type the file is treated as, and what `mediaTypes` was matched against. */
+  readonly mediaType: string
+  /** Type found in the first bytes; null when no signature matched. */
+  readonly detectedType: string | null
+  /** Content-Type the sender declared for the file; '' when none. */
+  readonly declaredType: string
+  /** Lowercase filename extension; null when there is no filename or no dot. */
+  readonly extension: string | null
+}
+
+/** The `upload` dep of a binary upload route. */
+export interface BinaryUpload extends UploadTypes {
+  readonly stream: Readable
+  /** Declared Content-Length, or null for a chunked body. */
+  readonly length: number | null
+}
+
+/** The `upload` dep of a multipart upload route. */
+export interface MultipartUpload extends UploadTypes {
+  readonly stream: Readable
+  readonly filename: string | null
+  /** Text fields that came before the file part. */
+  readonly fields: Readonly<Record<string, string>>
+}
+
+/**
+ * What a route screen is shown: the request line and headers, plus the declared
+ * body size. The body has not been read — nothing here forces it to be buffered.
+ */
+export interface ScreenedRequest {
+  readonly method: string
+  readonly url: string
+  readonly headers: Readonly<Record<string, string | undefined>>
+  /** Parsed `content-length`, or null when the header is absent or unparseable. */
+  readonly contentLength: number | null
+  /** The route's params parsed by its schema as the handler gets them; the raw params with no schema; null when they fail it. */
+  readonly params: unknown
+}
+
+/** A screen's refusal — the status and named reason sent instead of reading the body. */
+export interface ScreenRefusal {
+  readonly status: number
+  readonly reason: string
+  /** Extra fields merged into the response body alongside `reason`. */
+  readonly body?: Readonly<Record<string, unknown>>
+}
+
+/**
+ * Runs before the body is parsed and before the body limit applies. Return a
+ * refusal to answer the request there and then; return nothing to let it through.
+ */
+export type RouteScreen = (request: ScreenedRequest) => ScreenRefusal | null | undefined | void | Promise<ScreenRefusal | null | undefined | void>
+
+/** HTTP route metadata — method, path, and registered middleware. */
+export interface RouteMeta {
+  readonly method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'
+  readonly path: string
+  /** Per-route max request body size in bytes — overrides the server-level bodyLimit for this route. */
+  readonly bodyLimit?: number
+  /** Pre-parse screen — inspects headers before the body is read, and may refuse. */
+  readonly screen?: RouteScreen
+}
+
+/** HTTP method literal type — 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'. */
+export type HttpMethod = RouteMeta['method']
+
+/** A resolved handler produced by fitting().fit() — carries metadata, dependencies, and the handler function. */
+export interface Handler<TDeps extends Record<string, unknown>, TReturn> {
+  execute(deps: TDeps): Promise<TReturn>
+  readonly meta: HandlerMeta
+}
+
+/** Extracts the dependency type from a Handler — InferDeps<typeof myHandler> gives you the deps object shape. */
+export type InferDeps<H> = H extends Handler<infer D, unknown> ? D : never
+/** Extracts the return type from a Handler — InferReturn<typeof myHandler> gives you the resolved return type. */
+export type InferReturn<H> = H extends Handler<Record<string, unknown>, infer R> ? R : never
+
+/** Map of database names to their resolved DB instances for a handler. */
+export type DatabaseDeps<N extends string> = Record<N, DB>

package/src/request/fitting/namespace.ts

@@ -0,0 +1,7 @@
+import { createBuilder } from '../di/builder.js'
+
+/** DI handler builder — chain .use(), .auth(), .input(), .route(), .fit() to build type-safe handlers with automatic dependency injection. */
+export const fitting = Object.assign(
+  () => createBuilder(),
+  {},
+)

package/src/request/fixture/batch.ts

@@ -0,0 +1,71 @@
+import type { DB } from '../../data/db/index.js'
+import type { PermissionMeta } from '../di/types.js'
+import { ValidationError } from '../../core/errors/index.js'
+
+export interface BatchTargets {
+  readonly ids?: string[]
+  readonly filters?: Record<string, unknown>
+}
+
+export interface BatchAction<TAuth> {
+  readonly permission?: PermissionMeta
+  readonly preview?: (db: DB, auth: TAuth, tenant: string | null, targets: BatchTargets) => Promise<unknown>
+  readonly execute: (db: DB, auth: TAuth, tenant: string | null, targets: BatchTargets) => Promise<unknown>
+}
+
+export interface BatchRequest {
+  readonly action: string
+  readonly targets: BatchTargets
+}
+
+export function validateBatchRequest(body: unknown, validActions: readonly string[]): BatchRequest {
+  if (body === null || typeof body !== 'object') {
+    throw new ValidationError('Batch request body must be an object')
+  }
+  const obj = body as Record<string, unknown>
+
+  const action = obj['action']
+  if (typeof action !== 'string' || action.length === 0) {
+    throw new ValidationError({ action: ['action is required and must be a non-empty string'] })
+  }
+  if (!validActions.includes(action)) {
+    throw new ValidationError({
+      action: [`Unknown batch action "${action}". Valid actions: ${validActions.join(', ')}`],
+    })
+  }
+
+  const targets = obj['targets']
+  if (targets === null || targets === undefined || typeof targets !== 'object') {
+    throw new ValidationError({ targets: ['targets is required and must be an object'] })
+  }
+  const t = targets as Record<string, unknown>
+
+  const hasIds = Array.isArray(t['ids'])
+  const hasFilters = t['filters'] !== undefined && t['filters'] !== null && typeof t['filters'] === 'object'
+
+  if (!hasIds && !hasFilters) {
+    throw new ValidationError({ targets: ['targets must contain exactly one of "ids" or "filters"'] })
+  }
+  if (hasIds && hasFilters) {
+    throw new ValidationError({ targets: ['targets must contain exactly one of "ids" or "filters", not both'] })
+  }
+
+  if (hasIds) {
+    const ids = t['ids'] as unknown[]
+    if (ids.length === 0) {
+      throw new ValidationError({ 'targets.ids': ['ids array must not be empty'] })
+    }
+    for (const id of ids) {
+      if (typeof id !== 'string') {
+        throw new ValidationError({ 'targets.ids': ['all ids must be strings'] })
+      }
+    }
+  }
+
+  return {
+    action,
+    targets: hasIds
+      ? { ids: t['ids'] as string[] }
+      : { filters: t['filters'] as Record<string, unknown> },
+  }
+}

package/src/request/fixture/builder.ts

@@ -0,0 +1,26 @@
+import type { ResourceOperations, Resource, ResourceMeta, PaginationConfig } from './types.js'
+import type { AuthRequirement, PermissionMeta } from '../di/types.js'
+
+interface ResourceBuilderState {
+  database: string
+  authRequirement: AuthRequirement
+  permission: PermissionMeta | null
+  pagination: PaginationConfig | null
+}
+
+export function buildResource<TAuth>(
+  name: string,
+  operations: ResourceOperations<TAuth>,
+  state: ResourceBuilderState,
+): Resource<TAuth> {
+  const meta: ResourceMeta = {
+    name,
+    database: state.database,
+    authRequirement: state.authRequirement,
+    permission: state.permission,
+    pagination: state.pagination,
+  }
+  return { meta, operations }
+}
+
+export { type ResourceBuilderState }

package/src/request/fixture/errors.ts

@@ -0,0 +1,10 @@
+import { PipeworkError } from '../../core/errors/base.js'
+
+export class MethodNotAllowedError extends PipeworkError {
+  readonly code = 'METHOD_NOT_ALLOWED' as const
+  readonly httpStatus = 405 as const
+
+  constructor(method: string, resource: string) {
+    super(`${method} not supported on ${resource}`)
+  }
+}

package/src/request/fixture/index.ts

@@ -0,0 +1,8 @@
+export type { Resource, ResourceOperations, ResourceMeta, ResourceId, ResourceListOp, ResourceListPaginatedOp, ResourceListCursorOp, ResourceGetOp, ResourceCreateOp, ResourceUpdateOp, ResourceDeleteOp, PaginationConfig, PaginationParams, PaginatedResponse } from './types.js'
+export { buildResource } from './builder.js'
+export { resourceToHandlers } from './to-handlers.js'
+export { MethodNotAllowedError } from './errors.js'
+export { encodeCursor, decodeCursor, buildPage } from './paginate.js'
+export type { PageResult, CursorPaginationParams } from './paginate.js'
+export { validateBatchRequest } from './batch.js'
+export type { BatchAction, BatchTargets, BatchRequest } from './batch.js'