@veloxts/router 0.8.0 → 0.8.2

package/dist/procedure/pipeline.js

@@ -0,0 +1,50 @@
+/**
+ * Pipeline step and revert action factories
+ *
+ * Provides `defineStep` and `defineRevert` for building pipeline steps
+ * that execute in sequence via `.through()` on the procedure builder.
+ * Each step's output becomes the next step's input. External steps run
+ * outside DB transactions and can have revert actions for compensation.
+ *
+ * @module procedure/pipeline
+ */
+/** @internal */
+export function defineStep(nameOrOptions, handler) {
+    const resolved = typeof nameOrOptions === 'string'
+        ? { name: nameOrOptions, external: false }
+        : { name: nameOrOptions.name, external: nameOrOptions.external ?? false };
+    return createStep(resolved.name, resolved.external, handler, undefined);
+}
+// ============================================================================
+// defineRevert
+// ============================================================================
+/**
+ * Define a revert action for compensating an external pipeline step
+ *
+ * Revert handlers receive the same `{ input, ctx }` shape but return void.
+ *
+ * @example
+ * ```typescript
+ * const refund = defineRevert('refundPayment', async ({ input, ctx }) => {
+ *   await gateway.refund(input.chargeId);
+ * });
+ * ```
+ */
+export function defineRevert(name, handler) {
+    return { name, handler };
+}
+// ============================================================================
+// Internal helpers
+// ============================================================================
+/** @internal Create a PipelineStep object with onRevert method */
+function createStep(name, external, handler, revertAction) {
+    return {
+        name,
+        external,
+        handler,
+        revertAction,
+        onRevert(revert) {
+            return createStep(name, external, handler, revert);
+        },
+    };
+}

package/dist/procedure/types.d.ts

@@ -9,10 +9,11 @@
  *
  * @module procedure/types
  */
-import type { BaseContext } from '@veloxts/core';
+import type { BaseContext, DomainError } from '@veloxts/core';
 import type { ZodType } from 'zod';
 import type { OutputForLevel, ResourceSchema, TaggedResourceSchema } from '../resource/index.js';
-import type { CompiledProcedure, GuardLike, MiddlewareFunction, ParentResourceConfig, ProcedureHandler, RestRouteOverride } from '../types.js';
+import type { AfterHandler, CompiledProcedure, GuardLike, MiddlewareFunction, ParentResourceConfig, PolicyActionLike, ProcedureHandler, RestRouteOverride, TransactionalOptions } from '../types.js';
+import type { PipelineStep } from './pipeline.js';
 /**
  * Internal state type that accumulates type information through the builder chain
  *
@@ -22,14 +23,16 @@ import type { CompiledProcedure, GuardLike, MiddlewareFunction, ParentResourceCo
  * @template TInput - The validated input type (unknown if no input schema)
  * @template TOutput - The validated output type (unknown if no output schema)
  * @template TContext - The context type (starts as BaseContext, extended by middleware)
+ * @template TErrors - Union of domain error types (defaults to never)
  */
-export interface ProcedureBuilderState<TInput = unknown, TOutput = unknown, TContext extends BaseContext = BaseContext> {
+export interface ProcedureBuilderState<TInput = unknown, TOutput = unknown, TContext extends BaseContext = BaseContext, TErrors = never> {
     /** Marker for state identification */
     readonly _brand: 'ProcedureBuilderState';
     /** Phantom type holders - not used at runtime */
     readonly _input: TInput;
     readonly _output: TOutput;
     readonly _context: TContext;
+    readonly _errors: TErrors;
 }
 /**
  * Constraint for valid input/output schemas
@@ -73,6 +76,7 @@ export type InferOutputSchema<T> = T extends TaggedResourceSchema ? OutputForLev
  * @template TInput - Current input type
  * @template TOutput - Current output type
  * @template TContext - Current context type
+ * @template TErrors - Union of domain error types (defaults to never)
  *
  * @example
  * ```typescript
@@ -84,7 +88,7 @@ export type InferOutputSchema<T> = T extends TaggedResourceSchema ? OutputForLev
  *   })
  * ```
  */
-export interface ProcedureBuilder<TInput = unknown, TOutput = unknown, TContext extends BaseContext = BaseContext> {
+export interface ProcedureBuilder<TInput = unknown, TOutput = unknown, TContext extends BaseContext = BaseContext, TErrors = never> {
     /**
      * Defines the input validation schema for the procedure
      *
@@ -105,7 +109,7 @@ export interface ProcedureBuilder<TInput = unknown, TOutput = unknown, TContext
      *   // input is now typed as { id: string; name?: string }
      * ```
      */
-    input<TSchema extends ValidSchema>(schema: TSchema): ProcedureBuilder<InferSchemaOutput<TSchema>, TOutput, TContext>;
+    input<TSchema extends ValidSchema>(schema: TSchema): ProcedureBuilder<InferSchemaOutput<TSchema>, TOutput, TContext, TErrors>;
     /**
      * Defines the output schema for the procedure
      *
@@ -131,7 +135,7 @@ export interface ProcedureBuilder<TInput = unknown, TOutput = unknown, TContext
      *   .query(handler)
      * ```
      */
-    output<TSchema extends ValidOutputSchema>(schema: TSchema): ProcedureBuilder<TInput, InferOutputSchema<TSchema>, TContext>;
+    output<TSchema extends ValidOutputSchema>(schema: TSchema): ProcedureBuilder<TInput, InferOutputSchema<TSchema>, TContext, TErrors>;
     /**
      * Adds middleware to the procedure chain
      *
@@ -161,7 +165,7 @@ export interface ProcedureBuilder<TInput = unknown, TOutput = unknown, TContext
      *   })
      * ```
      */
-    use<TNewContext extends BaseContext = TContext>(middleware: MiddlewareFunction<TInput, TContext, TNewContext, TOutput>): ProcedureBuilder<TInput, TOutput, TNewContext>;
+    use<TNewContext extends BaseContext = TContext>(middleware: MiddlewareFunction<TInput, TContext, TNewContext, TOutput>): ProcedureBuilder<TInput, TOutput, TNewContext, TErrors>;
     /**
      * Adds an authorization guard to the procedure
      *
@@ -194,7 +198,7 @@ export interface ProcedureBuilder<TInput = unknown, TOutput = unknown, TContext
      *   .mutation(async ({ input, ctx }) => { ... });
      * ```
      */
-    guard<TGuardContext extends Partial<TContext>>(guard: GuardLike<TGuardContext>): ProcedureBuilder<TInput, TOutput, TContext>;
+    guard<TGuardContext extends Partial<TContext>>(guard: GuardLike<TGuardContext>): ProcedureBuilder<TInput, TOutput, TContext, TErrors>;
     /**
      * Adds multiple authorization guards at once
      *
@@ -221,7 +225,62 @@ export interface ProcedureBuilder<TInput = unknown, TOutput = unknown, TContext
      *   .mutation(async ({ input, ctx }) => { ... });
      * ```
      */
-    guards<TGuards extends GuardLike<Partial<TContext>>[]>(...guards: TGuards): ProcedureBuilder<TInput, TOutput, TContext>;
+    guards<TGuards extends GuardLike<Partial<TContext>>[]>(...guards: TGuards): ProcedureBuilder<TInput, TOutput, TContext, TErrors>;
+    /**
+     * Adds a policy action check to the procedure
+     *
+     * Policy actions are checked during execution after guards but before
+     * the pipeline and handler. The policy looks up the resource on the
+     * context by lowercase resource name (e.g., `PostPolicy` → `ctx.post`).
+     *
+     * If the policy check fails, a ForbiddenError is thrown.
+     *
+     * **Compile-time safety:** When the resource name is a string literal
+     * (e.g., from `definePolicy('Post', ...)`), TypeScript enforces that the
+     * context contains the resource key. Forgetting `.use(loadPost)` before
+     * `.policy(PostPolicy.update)` produces a type error.
+     *
+     * @param action - Policy action reference (from definePolicy)
+     * @returns Same builder (no type changes)
+     *
+     * @example
+     * ```typescript
+     * import { PostPolicy } from './policies';
+     *
+     * procedure()
+     *   .guard(authenticated)
+     *   .use(loadPost) // adds { post: Post } to context
+     *   .policy(PostPolicy.update) // ✓ context has 'post'
+     *   .mutation(async ({ input, ctx }) => { ... });
+     * ```
+     */
+    policy<TResourceName extends string>(action: string extends TResourceName ? PolicyActionLike<unknown, unknown, TResourceName> : Uncapitalize<TResourceName> extends keyof TContext ? PolicyActionLike<unknown, unknown, TResourceName> : PolicyActionLike<unknown, unknown, TResourceName> & {
+        _contextMissing: `Add .use() middleware to provide '${Uncapitalize<TResourceName>}' in context before .policy()`;
+    }): ProcedureBuilder<TInput, TOutput, TContext, TErrors>;
+    /**
+     * Declares domain error classes that this procedure may throw
+     *
+     * Stores error class references on the compiled procedure for:
+     * - OpenAPI error response generation (per-endpoint error schemas)
+     * - Client-side error type narrowing (`InferProcedureErrors<T>`)
+     *
+     * Can be called multiple times — error classes accumulate across calls.
+     *
+     * @template TDomainErrors - Union of domain error types declared
+     * @param errorClasses - Domain error constructors this procedure may throw
+     * @returns New builder with updated TErrors union
+     *
+     * @example
+     * ```typescript
+     * procedure()
+     *   .input(z.object({ sku: z.string(), qty: z.number() }))
+     *   .throws(InsufficientStock, PaymentFailed)
+     *   .mutation(async ({ input }) => {
+     *     // handler may throw InsufficientStock or PaymentFailed
+     *   })
+     * ```
+     */
+    throws<TDomainErrors extends DomainError<Record<string, unknown>>>(...errorClasses: Array<new (data: Record<string, unknown>) => TDomainErrors>): ProcedureBuilder<TInput, TOutput, TContext, TErrors | TDomainErrors>;
     /**
      * Configures REST route override
      *
@@ -237,7 +296,7 @@ export interface ProcedureBuilder<TInput = unknown, TOutput = unknown, TContext
      *   .rest({ method: 'POST', path: '/users/:id/activate' })
      * ```
      */
-    rest(config: RestRouteOverride): ProcedureBuilder<TInput, TOutput, TContext>;
+    rest(config: RestRouteOverride): ProcedureBuilder<TInput, TOutput, TContext, TErrors>;
     /**
      * Configures the procedure as a webhook endpoint
      *
@@ -257,7 +316,7 @@ export interface ProcedureBuilder<TInput = unknown, TOutput = unknown, TContext
      *   })
      * ```
      */
-    webhook(path: string): ProcedureBuilder<TInput, TOutput, TContext>;
+    webhook(path: string): ProcedureBuilder<TInput, TOutput, TContext, TErrors>;
     /**
      * Marks the procedure as deprecated
      *
@@ -280,7 +339,7 @@ export interface ProcedureBuilder<TInput = unknown, TOutput = unknown, TContext
      *   .query(handler);
      * ```
      */
-    deprecated(message?: string): ProcedureBuilder<TInput, TOutput, TContext>;
+    deprecated(message?: string): ProcedureBuilder<TInput, TOutput, TContext, TErrors>;
     /**
      * Declares a parent resource for nested routes (single level)
      *
@@ -309,7 +368,7 @@ export interface ProcedureBuilder<TInput = unknown, TOutput = unknown, TContext
      *   .query(async ({ input }) => { ... });
      * ```
      */
-    parent(resource: string, param?: string): ProcedureBuilder<TInput, TOutput, TContext>;
+    parent(resource: string, param?: string): ProcedureBuilder<TInput, TOutput, TContext, TErrors>;
     /**
      * Declares multiple parent resources for deeply nested routes
      *
@@ -340,7 +399,94 @@ export interface ProcedureBuilder<TInput = unknown, TOutput = unknown, TContext
     parents(config: Array<{
         resource: string;
         param?: string;
-    }>): ProcedureBuilder<TInput, TOutput, TContext>;
+    }>): ProcedureBuilder<TInput, TOutput, TContext, TErrors>;
+    /**
+     * Declares a domain event to emit after successful handler execution
+     *
+     * Events fire AFTER the handler returns its result (and AFTER transaction
+     * commit when `.transactional()` is used). Multiple `.emits()` calls
+     * accumulate — all declared events are emitted in order.
+     *
+     * Emission errors are caught and logged; they never fail the request.
+     *
+     * @template TEventData - The event's data payload type
+     * @param eventClass - Domain event class constructor
+     * @param mapper - Optional function to transform the handler result into event data.
+     *   When omitted, the handler result is used directly as event data.
+     * @returns Same builder (no type changes)
+     *
+     * @example With mapper (recommended)
+     * ```typescript
+     * procedure()
+     *   .emits(OrderCreated, (result) => ({ orderId: result.id, total: result.total }))
+     *   .mutation(handler)
+     * ```
+     *
+     * @example Without mapper (result type must match event data type)
+     * ```typescript
+     * procedure()
+     *   .emits(OrderCreated)
+     *   .mutation(handler)
+     * ```
+     */
+    emits<TEventData extends Record<string, unknown>>(eventClass: {
+        new (data: TEventData, options?: {
+            correlationId?: string;
+        }): unknown;
+        readonly name: string;
+    }, mapper?: (result: TOutput) => TEventData): ProcedureBuilder<TInput, TOutput, TContext, TErrors>;
+    /**
+     * Wraps the handler in a database transaction via `ctx.db.$transaction()`
+     *
+     * When set, `executeProcedure` replaces `ctx.db` with the transactional
+     * client inside the handler. On throw the transaction auto-rollbacks;
+     * on return it auto-commits.
+     *
+     * Gracefully degrades: if `ctx.db` or `ctx.db.$transaction` is missing,
+     * the handler runs without transaction wrapping.
+     *
+     * @param options - Optional isolation level and timeout
+     * @returns Same builder (no type changes)
+     *
+     * @example
+     * ```typescript
+     * procedure()
+     *   .input(CreateOrderSchema)
+     *   .transactional({ isolationLevel: 'Serializable', timeout: 10000 })
+     *   .mutation(async ({ input, ctx }) => {
+     *     // ctx.db is the transactional client — all queries share the same tx
+     *     const order = await ctx.db.order.create({ data: input });
+     *     await ctx.db.inventory.update({ ... });
+     *     return order; // auto-commit on success
+     *   })
+     * ```
+     */
+    transactional(options?: TransactionalOptions): ProcedureBuilder<TInput, TOutput, TContext, TErrors>;
+    /**
+     * Adds pipeline steps that execute BEFORE the handler
+     *
+     * Steps run in declaration order. Each step's output becomes the next
+     * step's input, and the final step's output is passed to the handler
+     * as its `input`. If a step fails, revert actions for previously
+     * completed steps run in reverse order (compensation pattern).
+     *
+     * Can be called multiple times — steps accumulate across calls.
+     *
+     * @param steps - Pipeline steps to execute before the handler
+     * @returns Same builder (no type changes)
+     *
+     * @example
+     * ```typescript
+     * procedure()
+     *   .input(CreateOrderSchema)
+     *   .through(validateInventory, chargePayment.onRevert(refund))
+     *   .mutation(async ({ input, ctx }) => {
+     *     // input has been transformed by pipeline steps
+     *     return ctx.db.order.create({ data: input });
+     *   })
+     * ```
+     */
+    through(...steps: PipelineStep[]): ProcedureBuilder<TInput, TOutput, TContext, TErrors>;
     /**
      * Finalizes the procedure as a query (read-only operation)
      *
@@ -348,7 +494,7 @@ export interface ProcedureBuilder<TInput = unknown, TOutput = unknown, TContext
      * The handler receives the validated input and context.
      *
      * @param handler - The query handler function
-     * @returns Compiled procedure ready for registration
+     * @returns PostHandlerBuilder with all CompiledProcedure fields plus .useAfter()
      *
      * @example
      * ```typescript
@@ -359,7 +505,7 @@ export interface ProcedureBuilder<TInput = unknown, TOutput = unknown, TContext
      *   })
      * ```
      */
-    query(handler: ProcedureHandler<TInput, TOutput, TContext> | Record<string, ProcedureHandler<TInput, TOutput, TContext>>): CompiledProcedure<TInput, TOutput, TContext, 'query'>;
+    query(handler: ProcedureHandler<TInput, TOutput, TContext> | Record<string, ProcedureHandler<TInput, TOutput, TContext>>): PostHandlerBuilder<TInput, TOutput, TContext, 'query', TErrors>;
     /**
      * Finalizes the procedure as a mutation (write operation)
      *
@@ -370,7 +516,7 @@ export interface ProcedureBuilder<TInput = unknown, TOutput = unknown, TContext
      * accepts a handler map keyed by `[Schema.level.key]` instead of a single handler.
      *
      * @param handler - The mutation handler function or handler map
-     * @returns Compiled procedure ready for registration
+     * @returns PostHandlerBuilder with all CompiledProcedure fields plus .useAfter()
      *
      * @example
      * ```typescript
@@ -381,7 +527,52 @@ export interface ProcedureBuilder<TInput = unknown, TOutput = unknown, TContext
      *   })
      * ```
      */
-    mutation(handler: ProcedureHandler<TInput, TOutput, TContext> | Record<string, ProcedureHandler<TInput, TOutput, TContext>>): CompiledProcedure<TInput, TOutput, TContext, 'mutation'>;
+    mutation(handler: ProcedureHandler<TInput, TOutput, TContext> | Record<string, ProcedureHandler<TInput, TOutput, TContext>>): PostHandlerBuilder<TInput, TOutput, TContext, 'mutation', TErrors>;
+}
+/**
+ * Returned by `.query()` and `.mutation()` — extends CompiledProcedure with `.useAfter()`
+ *
+ * PostHandlerBuilder has all CompiledProcedure fields (so it's assignable to
+ * CompiledProcedure and passes `isCompiledProcedure` checks) plus a `.useAfter()`
+ * method for registering post-handler hooks.
+ *
+ * `.useAfter()` returns another PostHandlerBuilder so hooks can be chained.
+ *
+ * @template TInput - The validated input type
+ * @template TOutput - The handler output type
+ * @template TContext - The context type
+ * @template TType - The procedure type literal ('query' or 'mutation')
+ * @template TErrors - Union of domain error types (defaults to never)
+ *
+ * @example
+ * ```typescript
+ * procedure()
+ *   .input(z.object({ id: z.string() }))
+ *   .mutation(async ({ input, ctx }) => {
+ *     return ctx.db.user.delete({ where: { id: input.id } });
+ *   })
+ *   .useAfter(({ input, result, ctx }) => {
+ *     console.log(`Deleted user ${input.id}`);
+ *   })
+ *   .useAfter(({ result }) => {
+ *     invalidateCache(result.id);
+ *   })
+ * ```
+ */
+export interface PostHandlerBuilder<TInput = unknown, TOutput = unknown, TContext extends BaseContext = BaseContext, TType extends 'query' | 'mutation' = 'query' | 'mutation', TErrors = never> extends CompiledProcedure<TInput, TOutput, TContext, TType, TErrors> {
+    /**
+     * Registers a post-handler hook that runs after successful handler execution
+     *
+     * Hooks run after events are emitted (if any) and auto-projection is applied.
+     * Errors in hooks are caught and logged — they never fail the request.
+     * The return value is ignored: hooks cannot modify the result.
+     *
+     * Multiple `.useAfter()` calls chain in registration order.
+     *
+     * @param handler - Post-handler hook function
+     * @returns New PostHandlerBuilder with the hook appended
+     */
+    useAfter(handler: AfterHandler<TInput, TOutput, TContext>): PostHandlerBuilder<TInput, TOutput, TContext, TType, TErrors>;
 }
 /**
  * Internal runtime state for the procedure builder
@@ -416,6 +607,26 @@ export interface BuilderRuntimeState {
     isWebhook?: boolean;
     /** Whether .output() received an untagged resource schema (Level 3 branching mode) */
     branchingMode?: boolean;
+    /** Error classes declared via .throws() */
+    errorClasses?: Array<new (data: Record<string, unknown>) => unknown>;
+    /** Whether the handler should be wrapped in a database transaction */
+    transactional?: boolean;
+    /** Options for the database transaction (isolation level, timeout) */
+    transactionalOptions?: TransactionalOptions;
+    /** Domain events to emit after successful handler execution */
+    emittedEvents?: Array<{
+        eventClass: {
+            new (data: Record<string, unknown>, options?: {
+                correlationId?: string;
+            }): unknown;
+            readonly name: string;
+        };
+        mapper?: (result: unknown) => Record<string, unknown>;
+    }>;
+    /** Pipeline steps declared via .through() */
+    pipelineSteps?: PipelineStep[];
+    /** Policy action reference for declarative authorization */
+    policyAction?: PolicyActionLike;
 }
 /**
  * Type for the procedures object passed to defineProcedures
@@ -430,7 +641,7 @@ export interface BuilderRuntimeState {
  * The actual type safety is preserved through InferProcedures<T> which captures
  * the concrete types at definition time. This `any` only allows the assignment.
  */
-export type ProcedureDefinitions = Record<string, CompiledProcedure<any, any, any, any>>;
+export type ProcedureDefinitions = Record<string, CompiledProcedure<any, any, any, any, any>>;
 /**
  * Type helper to preserve procedure types in a collection
  *

package/dist/rest/adapter.js

@@ -218,25 +218,20 @@ function gatherInput(request, route) {
     const params = isPlainObject(request.params) ? request.params : {};
     const query = isPlainObject(request.query) ? request.query : {};
     const body = isPlainObject(request.body) ? request.body : {};
-    // Check if this is a nested route (has single parent or multiple parents)
-    const hasParentResource = route.procedure.parentResource !== undefined ||
-        (route.procedure.parentResources !== undefined && route.procedure.parentResources.length > 0);
     switch (route.method) {
         case 'GET':
         case 'DELETE':
             // GET/DELETE: params (for :id and all parent params) + query (for filters/pagination/options)
             return { ...params, ...query };
+        case 'POST':
         case 'PUT':
         case 'PATCH':
-            // PUT/PATCH: params (for :id and all parent params) + body (for data)
+            // POST/PUT/PATCH: params (for :id and all parent params) + body (for data).
+            // POST must merge params unconditionally — flat conventional creates have
+            // empty params (no-op spread), but RPC-style .rest() overrides such as
+            // POST /retro/phase/:sessionId/next rely on this merge to surface path
+            // params to the input schema.
             return { ...params, ...body };
-        case 'POST':
-            // POST: For nested routes, merge params (for all parent IDs) with body
-            // For flat routes, use body only (no ID in params for creates)
-            if (hasParentResource) {
-                return { ...params, ...body };
-            }
-            return request.body;
         default:
             return request.body;
     }