@veloxts/router 0.8.0 → 0.8.2

package/dist/types.d.ts

@@ -8,6 +8,7 @@
  */
 import type { BaseContext } from '@veloxts/core';
 import type { HttpMethod } from '@veloxts/validation';
+import type { PipelineStep } from './procedure/pipeline.js';
 import type { ResourceSchema } from './resource/schema.js';
 /**
  * Procedure operation types
@@ -16,14 +17,6 @@ import type { ResourceSchema } from './resource/schema.js';
  * - mutation: Write operations (maps to POST/PUT/DELETE in REST)
  */
 export type ProcedureType = 'query' | 'mutation';
-/**
- * HTTP methods supported by the REST adapter
- *
- * Full REST support: GET, POST, PUT, PATCH, DELETE
- *
- * @see {@link PROCEDURE_METHOD_MAP} for naming convention mapping
- */
-export type { HttpMethod };
 /**
  * Maps procedure naming conventions to HTTP methods
  *
@@ -40,6 +33,14 @@ export type { HttpMethod };
  * - deleteUser -> DELETE
  */
 export { PROCEDURE_METHOD_MAP } from '@veloxts/validation';
+/**
+ * HTTP methods supported by the REST adapter
+ *
+ * Full REST support: GET, POST, PUT, PATCH, DELETE
+ *
+ * @see {@link PROCEDURE_METHOD_MAP} for naming convention mapping
+ */
+export type { HttpMethod };
 /**
  * Extended context type that can be augmented by middleware
  *
@@ -106,6 +107,24 @@ export interface GuardLike<TContext = unknown> {
     /** HTTP status code on failure (default: 403) */
     statusCode?: number;
 }
+/**
+ * Policy action reference interface for declarative authorization
+ *
+ * This interface is compatible with @veloxts/auth's PolicyActionRef but doesn't
+ * create a hard dependency. Any object matching this shape can be used as a policy
+ * action in the procedure builder.
+ *
+ * @template TUser - The user type the policy operates on
+ * @template TResource - The resource type the policy checks against
+ */
+export interface PolicyActionLike<TUser = unknown, TResource = unknown, TResourceName extends string = string> {
+    /** The name of the action (e.g., 'update', 'delete') */
+    readonly actionName: string;
+    /** The name of the resource this policy applies to (e.g., 'Post') */
+    readonly resourceName: TResourceName;
+    /** Execute the policy check for this action */
+    readonly check: (user: TUser, resource?: TResource) => boolean | Promise<boolean>;
+}
 /**
  * Result returned by the next() function in middleware
  *
@@ -264,6 +283,19 @@ export interface ParentResourceChain {
      */
     readonly parents: readonly ParentResourceConfig[];
 }
+/**
+ * Options for database transaction wrapping
+ *
+ * Controls isolation level and timeout when `.transactional()` is used
+ * on a procedure. These options are forwarded directly to Prisma's
+ * `$transaction()` method.
+ */
+export interface TransactionalOptions {
+    /** Transaction isolation level (forwarded to Prisma) */
+    isolationLevel?: 'ReadUncommitted' | 'ReadCommitted' | 'RepeatableRead' | 'Serializable' | 'Snapshot';
+    /** Transaction timeout in milliseconds */
+    timeout?: number;
+}
 /**
  * Compiled procedure with all metadata and handlers
  *
@@ -274,8 +306,9 @@ export interface ParentResourceChain {
  * @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 this procedure can throw (defaults to never)
  */
-export interface CompiledProcedure<TInput = unknown, TOutput = unknown, TContext extends BaseContext = BaseContext, TType extends ProcedureType = ProcedureType> {
+export interface CompiledProcedure<TInput = unknown, TOutput = unknown, TContext extends BaseContext = BaseContext, TType extends ProcedureType = ProcedureType, TErrors = never> {
     /** Whether this is a query or mutation */
     readonly type: TType;
     /** The procedure handler function */
@@ -383,13 +416,119 @@ export interface CompiledProcedure<TInput = unknown, TOutput = unknown, TContext
      * @internal
      */
     readonly _handlerMap?: Readonly<Record<string, ProcedureHandler<TInput, TOutput, TContext>>>;
+    /**
+     * Error classes that this procedure declares it may throw
+     *
+     * Populated by `.throws()` on the procedure builder. Used for OpenAPI
+     * error response generation and client-side error narrowing.
+     *
+     * @internal
+     */
+    readonly errorClasses?: ReadonlyArray<new (data: Record<string, unknown>) => unknown>;
+    /**
+     * Whether the handler should be wrapped in a database transaction
+     *
+     * Set by `.transactional()` on the procedure builder. When true,
+     * `executeProcedure` wraps the handler in `ctx.db.$transaction()`.
+     */
+    readonly transactional?: boolean;
+    /**
+     * Options for the database transaction (isolation level, timeout)
+     *
+     * Forwarded to `ctx.db.$transaction()` as the second argument.
+     */
+    readonly transactionalOptions?: TransactionalOptions;
+    /**
+     * Domain events to emit after successful handler execution
+     *
+     * Populated by `.emits()` on the procedure builder. Each entry holds
+     * the event class constructor and an optional mapper that transforms
+     * the handler result into the event's data payload.
+     *
+     * Events fire AFTER the handler returns (post-commit when transactional).
+     * Emission errors are caught and logged — they never fail the request.
+     */
+    readonly emittedEvents?: ReadonlyArray<{
+        eventClass: {
+            new (data: Record<string, unknown>, options?: {
+                correlationId?: string;
+            }): unknown;
+            readonly name: string;
+        };
+        mapper?: (result: unknown) => Record<string, unknown>;
+    }>;
+    /**
+     * Pipeline steps declared via .through()
+     *
+     * When present, the pipeline executor runs these steps in order
+     * BEFORE the handler. Each step's output becomes the next step's
+     * input, and the final step's output is passed to the handler.
+     *
+     * If a step fails, revert actions for completed steps run in
+     * reverse order (compensation pattern).
+     */
+    readonly pipelineSteps?: ReadonlyArray<PipelineStep>;
+    /**
+     * Policy action reference for declarative authorization
+     *
+     * When set via `.policy()`, the procedure executor checks the policy
+     * action against the current user and (optionally) a resource from
+     * the context. The resource is looked up by lowercase resource name
+     * (e.g., `PostPolicy` → `ctx.post`).
+     *
+     * If the check fails, a ForbiddenError is thrown.
+     *
+     * @example
+     * ```typescript
+     * procedure()
+     *   .guard(authenticated)
+     *   .policy(PostPolicy.update)
+     *   .mutation(handler)
+     * ```
+     */
+    readonly policyAction?: PolicyActionLike;
+    /**
+     * Post-handler hooks registered via `.useAfter()`
+     *
+     * When present, these hooks run after the handler succeeds (and after
+     * event emission). Errors in hooks are caught and logged — they never
+     * fail the request. Hooks cannot modify the result.
+     */
+    readonly afterHandlers?: ReadonlyArray<AfterHandler>;
+    /**
+     * Phantom type holder for error types — not used at runtime
+     *
+     * Preserves the TErrors union through the type system so that
+     * `InferProcedureErrors<T>` can extract it. Never set at runtime.
+     *
+     * @internal
+     */
+    readonly _errors?: TErrors;
 }
+/**
+ * Post-handler hook function signature
+ *
+ * Runs after the handler returns successfully. Receives the validated
+ * input, the handler result, and the request context. Return value
+ * is ignored — hooks cannot modify the result.
+ *
+ * Useful for side effects like audit logging, cache invalidation, and metrics.
+ *
+ * @template TInput - The validated input type
+ * @template TOutput - The handler result type
+ * @template TContext - The context type
+ */
+export type AfterHandler<TInput = unknown, TOutput = unknown, TContext = unknown> = (params: {
+    input: TInput;
+    result: TOutput;
+    ctx: TContext;
+}) => void | Promise<void>;
 /**
  * Record of named procedures
  *
  * NOTE: Uses `any` for variance compatibility - see ProcedureDefinitions for explanation.
  */
-export type ProcedureRecord = Record<string, CompiledProcedure<any, any, any, any>>;
+export type ProcedureRecord = Record<string, CompiledProcedure<any, any, any, any, any>>;
 /**
  * Procedure collection with namespace
  *
@@ -420,6 +559,13 @@ export type InferProcedureContext<T> = T extends CompiledProcedure<unknown, unkn
  * Extracts the type (query/mutation) from a compiled procedure
  */
 export type InferProcedureType<T> = T extends CompiledProcedure<unknown, unknown, BaseContext, infer TType> ? TType : never;
+/**
+ * Extracts the error types from a compiled procedure
+ *
+ * Returns the union of domain error types declared via `.throws()`.
+ * Returns `never` if no errors are declared.
+ */
+export type InferProcedureErrors<T> = T extends CompiledProcedure<unknown, unknown, BaseContext, ProcedureType, infer E> ? E : never;
 /**
  * Extracts procedure types from a collection
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@veloxts/router",
-  "version": "0.8.0",
+  "version": "0.8.2",
   "description": "Procedure definitions with tRPC and REST routing for VeloxTS framework",
   "type": "module",
   "main": "dist/index.js",
@@ -37,17 +37,17 @@
     }
   },
   "dependencies": {
-    "@trpc/server": "11.10.0",
-    "fastify": "5.7.4",
-    "@veloxts/validation": "0.8.0",
-    "@veloxts/core": "0.8.0"
+    "@trpc/server": "11.12.0",
+    "fastify": "5.8.2",
+    "@veloxts/core": "0.8.2",
+    "@veloxts/validation": "0.8.2"
   },
   "devDependencies": {
-    "@vitest/coverage-v8": "4.0.18",
-    "esbuild": "0.27.3",
+    "@vitest/coverage-v8": "4.1.0",
+    "esbuild": "0.27.4",
     "typescript": "5.9.3",
     "vite": "7.3.1",
-    "vitest": "4.0.18",
+    "vitest": "4.1.0",
     "zod": "4.3.6"
   },
   "peerDependencies": {