@veloxts/router 0.7.9 → 0.8.1

package/dist/procedure/builder.js

@@ -7,12 +7,14 @@
  *
  * @module procedure/builder
  */
-import { ConfigurationError, logWarning } from '@veloxts/core';
+import { ConfigurationError, createLogger, ForbiddenError, logWarning, } from '@veloxts/core';
 import { GuardError } from '../errors.js';
 import { createMiddlewareExecutor, executeMiddlewareChain } from '../middleware/chain.js';
-import { isTaggedResourceSchema, Resource, } from '../resource/index.js';
+import { isResourceSchema, isTaggedResourceSchema, Resource, } from '../resource/index.js';
 import { deriveParentParamName } from '../utils/pluralization.js';
 import { analyzeNamingConvention, isDevelopment, normalizeWarningOption, } from '../warnings.js';
+import { executeExternalSteps, executePipeline, splitPipelineSteps } from './pipeline-executor.js';
+const log = createLogger('router');
 // ============================================================================
 // Builder Factory
 // ============================================================================
@@ -85,24 +87,41 @@ function createBuilder(state) {
             });
         },
         /**
-         * Sets the output validation schema (Zod-only)
+         * Sets the output schema.
+         *
+         * Accepts either:
+         * - A Zod schema (Level 1) — validates output after handler
+         * - A tagged resource view (Level 2) — auto-projects handler result
+         *   through the tagged level's field visibility
          */
         output(schema) {
+            // Level 2: tagged resource view — set up auto-projection
+            if (isTaggedResourceSchema(schema)) {
+                return createBuilder({
+                    ...state,
+                    resourceSchema: schema,
+                    resourceLevel: schema._level,
+                    outputSchema: undefined,
+                    branchingMode: undefined,
+                });
+            }
+            // Level 3: untagged resource schema — enables branching mode
+            if (isResourceSchema(schema)) {
+                return createBuilder({
+                    ...state,
+                    resourceSchema: schema,
+                    resourceLevel: undefined,
+                    outputSchema: undefined,
+                    branchingMode: true,
+                });
+            }
+            // Level 1: plain Zod schema — validate output
             return createBuilder({
                 ...state,
                 outputSchema: schema,
-            });
-        },
-        /**
-         * Sets field-level visibility via a resource schema
-         */
-        expose(schema) {
-            const level = isTaggedResourceSchema(schema) ? schema._level : undefined;
-            return createBuilder({
-                ...state,
-                resourceSchema: schema,
-                resourceLevel: level,
-                outputSchema: undefined,
+                resourceSchema: undefined,
+                resourceLevel: undefined,
+                branchingMode: undefined,
             });
         },
         /**
@@ -130,27 +149,33 @@ function createBuilder(state) {
             });
         },
         /**
-         * Adds an authorization guard with type narrowing (EXPERIMENTAL)
+         * Adds multiple authorization guards at once
          *
-         * Unlike `guard()`, this method narrows the context type based on
-         * what the guard guarantees after it passes.
+         * Convenience method equivalent to chaining multiple `.guard()` calls.
+         * Guards execute left-to-right. All must pass for the procedure to execute.
          */
-        guardNarrow(guardDef) {
+        guards(...guardDefs) {
             return createBuilder({
                 ...state,
-                guards: [...state.guards, guardDef],
+                guards: [...state.guards, ...guardDefs],
             });
         },
         /**
-         * Adds multiple authorization guards at once
-         *
-         * Convenience method equivalent to chaining multiple `.guard()` calls.
-         * Guards execute left-to-right. All must pass for the procedure to execute.
+         * Adds a policy action check to the procedure
          */
-        guards(...guardDefs) {
+        policy(action) {
             return createBuilder({
                 ...state,
-                guards: [...state.guards, ...guardDefs],
+                policyAction: action,
+            });
+        },
+        /**
+         * Declares domain error classes this procedure may throw
+         */
+        throws(...errorClasses) {
+            return createBuilder({
+                ...state,
+                errorClasses: [...(state.errorClasses ?? []), ...errorClasses],
             });
         },
         /**
@@ -209,31 +234,87 @@ function createBuilder(state) {
             });
         },
         /**
-         * Finalizes as a query procedure
+         * Declares a domain event to emit after successful handler execution
          */
-        query(handler) {
-            return compileProcedure('query', handler, state);
+        emits(eventClass, mapper) {
+            // Cast is safe: the typed TEventData and TOutput are erased at runtime.
+            // BuilderRuntimeState stores the widened types for uniform handling.
+            const entry = { eventClass, mapper };
+            return createBuilder({
+                ...state,
+                emittedEvents: [...(state.emittedEvents ?? []), entry],
+            });
         },
         /**
-         * Finalizes as a mutation procedure
+         * Wraps the handler in a database transaction
          */
-        mutation(handler) {
-            return compileProcedure('mutation', handler, state);
+        transactional(options) {
+            return createBuilder({
+                ...state,
+                transactional: true,
+                transactionalOptions: options,
+            });
         },
         /**
-         * @deprecated Use `.expose()` instead. `.resource()` will be removed in v1.0.
+         * Adds pipeline steps that execute before the handler
          */
-        resource(schema) {
-            const level = isTaggedResourceSchema(schema) ? schema._level : undefined;
+        through(...steps) {
             return createBuilder({
                 ...state,
-                resourceSchema: schema,
-                resourceLevel: level,
-                outputSchema: undefined,
+                pipelineSteps: [...(state.pipelineSteps ?? []), ...steps],
             });
         },
+        /**
+         * Finalizes as a query procedure
+         *
+         * In branching mode (Level 3), accepts a handler map keyed by schema level keys.
+         */
+        query(handlerOrMap) {
+            return compileProcedureOrBranching('query', handlerOrMap, state);
+        },
+        /**
+         * Finalizes as a mutation procedure
+         *
+         * In branching mode (Level 3), accepts a handler map keyed by schema level keys.
+         */
+        mutation(handlerOrMap) {
+            return compileProcedureOrBranching('mutation', handlerOrMap, state);
+        },
     };
 }
+/**
+ * Routes to the correct compile strategy based on branching mode
+ *
+ * In branching mode (Level 3), validates the handler map and synthesizes
+ * a dispatch handler. In normal mode, delegates to compileProcedure.
+ *
+ * @internal
+ */
+function compileProcedureOrBranching(type, handlerOrMap, state) {
+    if (state.branchingMode) {
+        // Level 3: handler map required
+        if (typeof handlerOrMap === 'function') {
+            throw new ConfigurationError('Handler map required when .output() receives a resource schema. ' +
+                'Use { [Schema.level.key]: handler } syntax.');
+        }
+        if (state.guards.length > 0) {
+            throw new ConfigurationError('Cannot use handler map with .guard(). ' +
+                'Guards come from defineAccessLevels() in Level 3 branching mode.');
+        }
+        // Synthesize a dispatch handler so CompiledProcedure.handler is always defined.
+        // The real branch selection happens in executeProcedure.
+        const dispatchHandler = async () => {
+            throw new ConfigurationError('Level 3 branched procedures must be executed via executeProcedure(). ' +
+                'Direct handler invocation is not supported.');
+        };
+        return compileProcedureWithHandlerMap(type, dispatchHandler, handlerOrMap, state);
+    }
+    // Not in branching mode: handler map is not allowed
+    if (typeof handlerOrMap !== 'function') {
+        throw new ConfigurationError('Handler map can only be used when .output() receives an untagged resource schema.');
+    }
+    return compileProcedure(type, handlerOrMap, state);
+}
 /**
  * Compiles a procedure from the builder state
  *
@@ -248,8 +329,8 @@ function compileProcedure(type, handler, state) {
     // Pre-compile the middleware chain executor if middlewares exist
     // This avoids rebuilding the chain on every request
     const precompiledExecutor = typedMiddlewares.length > 0 ? createMiddlewareExecutor(typedMiddlewares, handler) : undefined;
-    // Create the final procedure object
-    return {
+    // Create the final procedure object with .useAfter() support
+    return createPostHandlerBuilder({
         type,
         handler,
         inputSchema: state.inputSchema,
@@ -268,6 +349,85 @@ function compileProcedure(type, handler, state) {
         _resourceSchema: state.resourceSchema,
         // Store explicit resource level from tagged schema (e.g., UserSchema.authenticated)
         _resourceLevel: state.resourceLevel,
+        // Store error classes declared via .throws()
+        errorClasses: state.errorClasses,
+        // Store transactional configuration
+        transactional: state.transactional,
+        transactionalOptions: state.transactionalOptions,
+        // Store emitted events declared via .emits()
+        emittedEvents: state.emittedEvents,
+        // Store pipeline steps declared via .through()
+        pipelineSteps: state.pipelineSteps,
+        // Store policy action declared via .policy()
+        policyAction: state.policyAction,
+    });
+}
+/**
+ * Compiles a Level 3 branched procedure with a handler map
+ *
+ * Creates a CompiledProcedure with both a synthesized dispatch handler
+ * (so .handler is always defined) and the _handlerMap for branch selection.
+ *
+ * @internal
+ */
+function compileProcedureWithHandlerMap(type, dispatchHandler, handlerMap, state) {
+    const typedMiddlewares = state.middlewares;
+    return createPostHandlerBuilder({
+        type,
+        handler: dispatchHandler,
+        inputSchema: state.inputSchema,
+        outputSchema: undefined, // Level 3 uses resource schema projection, not Zod output validation
+        middlewares: typedMiddlewares,
+        guards: [], // Guards come from access level config
+        restOverride: state.restOverride,
+        deprecated: state.deprecated,
+        deprecationMessage: state.deprecationMessage,
+        isWebhook: state.isWebhook,
+        parentResource: state.parentResource,
+        parentResources: state.parentResources,
+        _precompiledExecutor: undefined, // Branched procedures don't use precompiled chains
+        _resourceSchema: state.resourceSchema,
+        _resourceLevel: undefined, // No fixed level — determined at runtime by branch selection
+        _handlerMap: handlerMap,
+        // Store error classes declared via .throws()
+        errorClasses: state.errorClasses,
+        // Store transactional configuration
+        transactional: state.transactional,
+        transactionalOptions: state.transactionalOptions,
+        // Store pipeline steps declared via .through()
+        pipelineSteps: state.pipelineSteps,
+        // Store policy action declared via .policy()
+        policyAction: state.policyAction,
+    });
+}
+// ============================================================================
+// PostHandlerBuilder Factory
+// ============================================================================
+/**
+ * Creates a PostHandlerBuilder from a CompiledProcedure's fields
+ *
+ * Wraps a compiled procedure object with a `.useAfter()` method that
+ * appends after-handler hooks. Each call returns a new PostHandlerBuilder
+ * with the hook added, preserving immutability.
+ *
+ * The resulting object passes `isCompiledProcedure` because it retains
+ * all required fields (type, handler, middlewares, guards).
+ *
+ * @internal
+ */
+function createPostHandlerBuilder(compiled) {
+    return {
+        ...compiled,
+        useAfter(handler) {
+            const afterHandlers = [
+                ...(compiled.afterHandlers ?? []),
+                handler,
+            ];
+            return createPostHandlerBuilder({
+                ...compiled,
+                afterHandlers,
+            });
+        },
     };
 }
 /**
@@ -437,7 +597,7 @@ export async function executeProcedure(procedure, rawInput, ctx) {
             // IMPORTANT: last guard's accessLevel wins. With custom levels that
             // have no inherent hierarchy, ordering of guards matters.
             // Guards without accessLevel (e.g. plain `authenticated`) do NOT
-            // update the level — it stays at 'public' for .expose() projection.
+            // update the level — it stays at 'public' for .output() projection.
             const guardWithLevel = guard;
             if (guardWithLevel.accessLevel) {
                 accessLevel = guardWithLevel.accessLevel;
@@ -451,21 +611,101 @@ export async function executeProcedure(procedure, rawInput, ctx) {
     const input = procedure.inputSchema
         ? procedure.inputSchema.parse(rawInput)
         : rawInput;
+    // Step 2.3: Policy check — if .policy() was used
+    if (procedure.policyAction) {
+        const ctxRecord = ctxWithLevel;
+        const user = ctxRecord.user;
+        if (user == null) {
+            throw new ForbiddenError('Policy check failed: no authenticated user');
+        }
+        const resourceNameRaw = procedure.policyAction.resourceName;
+        const resourceName = resourceNameRaw.charAt(0).toLowerCase() + resourceNameRaw.slice(1);
+        const policyResource = ctxRecord[resourceName];
+        const allowed = await procedure.policyAction.check(user, policyResource);
+        if (!allowed) {
+            throw new ForbiddenError(`Policy check failed: cannot ${procedure.policyAction.actionName} ${procedure.policyAction.resourceName}`);
+        }
+    }
+    // Step 2.5: Level 3 branch selection — if handler map is present
+    if (procedure._handlerMap) {
+        return executeBranchedProcedure(procedure, input, ctxWithLevel);
+    }
+    // Step 2.7: Execute pipeline steps if .through() was used
+    // Pipeline transforms input before the handler. Runs inside transaction when applicable.
+    const pipelineSteps = procedure.pipelineSteps;
+    const hasPipeline = pipelineSteps !== undefined && pipelineSteps.length > 0;
     // Step 3: Execute handler (with or without middleware)
+    // Helper that runs a given set of pipeline steps + middleware chain + handler
+    const executeWithSteps = async (steps, execCtx) => {
+        const hasSteps = steps !== undefined && steps.length > 0;
+        // Run pipeline to transform input before handler
+        const handlerInput = hasSteps
+            ? (await executePipeline(steps, input, execCtx))
+            : input;
+        enrichedInput = handlerInput;
+        if (procedure._precompiledExecutor) {
+            // PERFORMANCE: Use pre-compiled middleware chain executor
+            return procedure._precompiledExecutor(handlerInput, execCtx);
+        }
+        if (procedure.middlewares.length === 0) {
+            // No middleware - execute handler directly
+            return procedure.handler({ input: handlerInput, ctx: execCtx });
+        }
+        // Fallback: Build middleware chain dynamically (should not normally happen)
+        return executeMiddlewareChain(procedure.middlewares, handlerInput, execCtx, async () => procedure.handler({ input: handlerInput, ctx: execCtx }));
+    };
     let result;
-    if (procedure._precompiledExecutor) {
-        // PERFORMANCE: Use pre-compiled middleware chain executor
-        result = await procedure._precompiledExecutor(input, ctxWithLevel);
-    }
-    else if (procedure.middlewares.length === 0) {
-        // No middleware - execute handler directly
-        result = await procedure.handler({ input, ctx: ctxWithLevel });
+    let enrichedInput = input;
+    // Wrap in transaction if .transactional() was called and ctx.db.$transaction exists
+    const ctxRecord = ctxWithLevel;
+    const db = ctxRecord.db;
+    const isTransactional = procedure.transactional && db && typeof db.$transaction === 'function';
+    if (isTransactional) {
+        const $transaction = db.$transaction;
+        if (hasPipeline) {
+            // Two-phase model: split steps into DB (inside tx) and external (after commit)
+            const { dbSteps, externalSteps } = splitPipelineSteps(pipelineSteps);
+            // Phase A: Run DB steps + handler inside transaction
+            result = await $transaction(async (tx) => {
+                const txCtx = { ...ctxWithLevel, db: tx };
+                return executeWithSteps(dbSteps.length > 0 ? dbSteps : undefined, txCtx);
+            }, procedure.transactionalOptions);
+            // Phase B: Run external steps after commit (outside transaction)
+            if (externalSteps.length > 0) {
+                await executeExternalSteps(externalSteps, input, ctxWithLevel);
+            }
+        }
+        else {
+            // Transactional, no pipeline — wrap handler in $transaction (current behavior)
+            result = await $transaction(async (tx) => {
+                const txCtx = { ...ctxWithLevel, db: tx };
+                return executeWithSteps(undefined, txCtx);
+            }, procedure.transactionalOptions);
+        }
     }
     else {
-        // Fallback: Build middleware chain dynamically (should not normally happen)
-        result = await executeMiddlewareChain(procedure.middlewares, input, ctxWithLevel, async () => procedure.handler({ input, ctx: ctxWithLevel }));
+        // Not transactional — run all steps in declaration order (regardless of external flag)
+        result = await executeWithSteps(hasPipeline ? pipelineSteps : undefined, ctxWithLevel);
+    }
+    // Step 4: Emit domain events if .emits() was used
+    if (procedure.emittedEvents) {
+        const ctxEvents = ctxRecord
+            .events;
+        if (ctxEvents?.emit) {
+            for (const { eventClass, mapper } of procedure.emittedEvents) {
+                try {
+                    const eventData = mapper
+                        ? mapper(result)
+                        : result;
+                    await ctxEvents.emit(new eventClass(eventData));
+                }
+                catch (error) {
+                    log.error('Event emission error:', error);
+                }
+            }
+        }
     }
-    // Step 4: Auto-project if resource schema is set
+    // Step 5: Auto-project if resource schema is set
     if (procedure._resourceSchema) {
         const schema = procedure._resourceSchema;
         // Prefer explicit level from tagged schema over guard-derived level
@@ -480,9 +720,99 @@ export async function executeProcedure(procedure, rawInput, ctx) {
             result = projectOne(result);
         }
     }
-    // Step 5: Validate output if schema provided
+    // Step 6: Validate output if schema provided
     if (procedure.outputSchema) {
-        return procedure.outputSchema.parse(result);
+        result = procedure.outputSchema.parse(result);
+    }
+    // Step 7: Execute after-handler hooks if .useAfter() was used
+    if (procedure.afterHandlers?.length) {
+        for (const afterHandler of procedure.afterHandlers) {
+            try {
+                await afterHandler({ input: enrichedInput, result, ctx: ctxWithLevel });
+            }
+            catch (error) {
+                log.error('useAfter hook error:', error);
+            }
+        }
+    }
+    // Return the ORIGINAL result (hooks cannot modify it)
+    return result;
+}
+// ============================================================================
+// Level 3 Branch Selection
+// ============================================================================
+/**
+ * Executes a Level 3 branched procedure
+ *
+ * Evaluates guards from the resource schema's access level config
+ * most-privileged-first to select the matching branch handler, then
+ * auto-projects the result through that level's field visibility.
+ *
+ * @internal
+ */
+async function executeBranchedProcedure(procedure, input, ctx) {
+    const handlerMap = procedure._handlerMap;
+    const schema = procedure._resourceSchema;
+    const levelConfig = schema?._levelConfig;
+    if (!levelConfig) {
+        throw new ConfigurationError('Resource schema must be built with defineAccessLevels() containing guards for Level 3 branching.');
+    }
+    // Evaluate guards most-privileged-first (reverse level order)
+    const levels = [...levelConfig.levels];
+    const reversedLevels = [...levels].reverse();
+    let selectedLevel;
+    let selectedHandler;
+    for (const level of reversedLevels) {
+        const guard = levelConfig.guards[level];
+        if (!guard) {
+            // No guard = public/fallback level — only select if handler exists
+            const key = `__velox_level_${level}`;
+            if (handlerMap[key]) {
+                // Don't select yet — keep looking for a higher-privilege match.
+                // This fallback is used if no guarded level matches.
+                if (!selectedHandler) {
+                    selectedLevel = level;
+                    selectedHandler = handlerMap[key];
+                }
+            }
+            continue;
+        }
+        const passed = await guard(ctx);
+        if (passed) {
+            // Guard passed — find the best handler at or below this level
+            const levelIndex = levels.indexOf(level);
+            for (let i = levelIndex; i >= 0; i--) {
+                const candidateLevel = levels[i];
+                const key = `__velox_level_${candidateLevel}`;
+                if (handlerMap[key]) {
+                    selectedHandler = handlerMap[key];
+                    selectedLevel = candidateLevel;
+                    break;
+                }
+            }
+            break;
+        }
+    }
+    if (!selectedHandler || !selectedLevel) {
+        throw new GuardError('access', 'No matching branch for this access level', 403);
+    }
+    // Execute middleware chain if any, then the selected handler
+    let result;
+    if (procedure.middlewares.length > 0) {
+        result = await executeMiddlewareChain(procedure.middlewares, input, ctx, async () => selectedHandler({ input, ctx }));
+    }
+    else {
+        result = await selectedHandler({ input, ctx });
+    }
+    // Auto-project through the selected level's visibility
+    const projectOne = (item) => {
+        return new Resource(item, schema).forLevel(selectedLevel);
+    };
+    if (Array.isArray(result)) {
+        result = result.map((item) => projectOne(item));
+    }
+    else {
+        result = projectOne(result);
     }
     return result;
 }

package/dist/procedure/pipeline-executor.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Pipeline executor for .through() steps
+ *
+ * Executes pipeline steps in declaration order. Each step's output becomes
+ * the next step's input. On failure, runs revert actions for completed
+ * steps in reverse order (compensation pattern).
+ *
+ * When `.transactional()` is combined with `.through()`, the executor
+ * implements a two-phase model:
+ * - Phase A: DB steps (non-external) run inside the transaction
+ * - Phase B: External steps run after the transaction commits
+ *
+ * @module procedure/pipeline-executor
+ */
+import type { BaseContext } from '@veloxts/core';
+import type { PipelineStep } from './pipeline.js';
+/**
+ * Result of splitting pipeline steps into DB and external phases
+ */
+export interface SplitPipelineSteps {
+    /** Steps that run inside the DB transaction (external === false) */
+    readonly dbSteps: ReadonlyArray<PipelineStep>;
+    /** Steps that run after transaction commit (external === true) */
+    readonly externalSteps: ReadonlyArray<PipelineStep>;
+}
+/**
+ * Splits pipeline steps into DB (non-external) and external phases
+ *
+ * Validates the ordering constraint: when transactional, all external steps
+ * must come AFTER all DB steps. If an external step appears before a DB step,
+ * a ConfigurationError is thrown.
+ *
+ * @param steps - Pipeline steps to split
+ * @returns Object with `dbSteps` and `externalSteps` arrays
+ * @throws ConfigurationError if an external step precedes a DB step
+ */
+export declare function splitPipelineSteps(steps: ReadonlyArray<PipelineStep>): SplitPipelineSteps;
+/**
+ * Executes a sequence of pipeline steps
+ *
+ * Steps run in declaration order. Each step receives the previous step's
+ * output as its input (the first step receives the original validated input).
+ *
+ * If a step fails:
+ * 1. Collects all completed steps that have a revertAction
+ * 2. Runs their revert handlers in REVERSE order
+ * 3. Each revert receives the output of the step being reverted
+ * 4. Revert errors are logged but do not suppress the original error
+ * 5. Rethrows the original error
+ *
+ * @param steps - Pipeline steps to execute in order
+ * @param input - Initial input (typically the validated procedure input)
+ * @param ctx - Request context
+ * @returns The output of the last step
+ */
+export declare function executePipeline(steps: ReadonlyArray<PipelineStep>, input: unknown, ctx: BaseContext): Promise<unknown>;
+/**
+ * Executes external pipeline steps after a transaction has committed
+ *
+ * External steps run in declaration order. If a step fails, revert actions
+ * are run for all previously completed EXTERNAL steps in reverse order.
+ * The DB transaction is already committed — DB changes persist.
+ *
+ * @param steps - External pipeline steps to execute in order
+ * @param input - Input for the first external step (output of last DB step, or original input)
+ * @param ctx - Request context (with the ORIGINAL db, not the transactional client)
+ * @returns The output of the last external step (ignored by the caller, since handler already ran)
+ */
+export declare function executeExternalSteps(steps: ReadonlyArray<PipelineStep>, input: unknown, ctx: BaseContext): Promise<void>;