@warlock.js/core 4.0.135 → 4.0.137

package/esm/use-cases/types.d.ts

@@ -0,0 +1,267 @@
+import { type ObjectValidator } from "@warlock.js/seal";
+import { BenchmarkOptions } from "../benchmark";
+import { RetryOptions } from "../retry";
+/**
+ * Shared context object passed through the entire use case pipeline.
+ * Contains the optional schema and can be enriched by guards/middleware
+ * with arbitrary data (e.g., currentUser, permissions, request metadata).
+ */
+export type UseCaseContext = {
+    schema?: ObjectValidator;
+} & Record<string, any>;
+/**
+ * Guard function that runs **before** schema validation.
+ *
+ * Guards are authorization/precondition checks. They receive a read-only
+ * view of the input data and can enrich the context, but **must not** mutate
+ * the input. Throw an error to abort the entire pipeline.
+ *
+ * @example
+ * ```ts
+ * const authGuard: UseCaseGuard<LoginInput> = async (data, ctx) => {
+ *   const user = await getSession(ctx.token);
+ *   if (!user) throw new UnauthorizedError();
+ *   ctx.currentUser = user;
+ * };
+ * ```
+ *
+ * @template Input - The shape of the use case input data
+ */
+export type UseCaseGuard<Input> = (data: Readonly<Input>, ctx: UseCaseContext) => void | Promise<void>;
+/**
+ * Before middleware that runs **after** schema validation.
+ *
+ * Receives validated data and must return the (optionally transformed) data.
+ * Multiple before middlewares form a chain: output of one becomes input of next.
+ * Can also enrich the context.
+ *
+ * @example
+ * ```ts
+ * const normalizeEmail: UseCaseBeforeMiddleware<SignupInput> = async (data, ctx) => {
+ *   return { ...data, email: data.email.toLowerCase().trim() };
+ * };
+ * ```
+ *
+ * @template Input - The shape of the use case input data
+ */
+export type UseCaseBeforeMiddleware<Input> = (data: Input, ctx: UseCaseContext) => Input | Promise<Input>;
+/**
+ * After middleware that runs **after** the handler succeeds.
+ *
+ * Fire-and-forget side effects: errors are caught and logged, never thrown.
+ * Does **not** affect the returned output. Use for analytics, notifications,
+ * cache invalidation, webhooks, etc.
+ *
+ * @example
+ * ```ts
+ * const notifySlack: UseCaseAfterMiddleware<OrderOutput> = async (output, ctx) => {
+ *   await slack.send(`New order #${output.orderId} placed`);
+ * };
+ * ```
+ *
+ * @template Output - The shape of the use case output data
+ */
+export type UseCaseAfterMiddleware<Output> = (output: Output, ctx: UseCaseContext) => void | Promise<void>;
+/**
+ * Context passed to `onExecuting` lifecycle event callbacks.
+ * Fired at the start of each use case execution, before guards run.
+ */
+export type UseCaseOnExecutingContext = {
+    /** The shared pipeline context */
+    ctx: UseCaseContext;
+    /** Unique execution ID */
+    id: string;
+    /** Use case name */
+    name: string;
+    /** Raw input data */
+    data: any;
+    /** Schema validator (if defined) */
+    schema: ObjectValidator;
+    /** Timestamp when execution started */
+    startedAt: Date;
+};
+/**
+ * Use case definition.
+ *
+ * Defines the full execution pipeline: guards → validation → before → handler → after.
+ * All fields except `name` and `handler` are optional.
+ *
+ * @example
+ * ```ts
+ * const createOrder = await useCase<OrderOutput, OrderInput>({
+ *   name: "create-order",
+ *   guards: [authGuard, rateLimitGuard],
+ *   schema: v.object({ productId: v.string().required(), quantity: v.number().min(1) }),
+ *   before: [normalizeInput, enrichWithPricing],
+ *   handler: async (data, ctx) => orderService.create(data, ctx.currentUser),
+ *   after: [sendConfirmationEmail, invalidateCache],
+ *   retries: { count: 3, delay: 1000 },
+ *   benchmark: true,
+ * });
+ * ```
+ *
+ * @template Output - The shape of the handler's return value
+ * @template Input - The shape of the input data (before transformation)
+ */
+export type UseCase<Output = any, Input = any> = {
+    /** Unique use case identifier, used for registration, logging, and cache keys */
+    name: string;
+    /** Core business logic handler. Receives validated + transformed data and context */
+    handler: (filteredData: Input, ctx: UseCaseContext) => Promise<Output>;
+    /** Optional schema validator (from @warlock.js/seal). Runs after guards */
+    schema?: ObjectValidator;
+    /** Guards to run before validation. Sequential, can enrich ctx, cannot mutate data */
+    guards?: UseCaseGuard<Input>[];
+    /** Before middleware to run after validation. Sequential, can transform data */
+    before?: UseCaseBeforeMiddleware<Input>[];
+    /** After middleware to run on success. Fire-and-forget, errors are logged not thrown */
+    after?: UseCaseAfterMiddleware<Output>[];
+    /** Lifecycle callback: fires when execution starts (before guards) */
+    onExecuting?: (ctx: UseCaseOnExecutingContext) => void;
+    /** Lifecycle callback: fires on successful completion with full result snapshot */
+    onCompleted?: (result: UseCaseResult<Output>) => void;
+    /** Lifecycle callback: fires on error with error details and execution context */
+    onError?: (ctx: UseCaseErrorResult) => void;
+    /**
+     * Retry configuration. When set, the handler is retried on failure
+     * up to `count` times with an optional `delay` between attempts.
+     */
+    retryOptions?: RetryOptions;
+    /**
+     * Benchmark configuration. Set to `true` for default thresholds,
+     * or provide an object to customize latency classification.
+     */
+    benchmarkOptions?: BenchmarkOptions | false;
+};
+/**
+ * A registered use case with call tracking metadata.
+ * Created internally when a use case is registered via `useCase()`.
+ */
+export type RegisteredUseCase<Output = any, Input = any> = UseCase<Output, Input> & {
+    /** Execution call counters */
+    calls: {
+        /** Number of successful executions */
+        success: number;
+        /** Number of failed executions */
+        failed: number;
+        /** Total executions (success + failed) */
+        total: number;
+    };
+};
+/**
+ * Runtime options passed at invocation time (second argument to the executor).
+ * These override or supplement the use case definition for a single execution.
+ *
+ * @example
+ * ```ts
+ * await createOrder(orderData, {
+ *   id: "order-123",
+ *   ctx: { currentUser },
+ *   onCompleted: (result) => console.log("Order created:", result.output),
+ * });
+ * ```
+ *
+ * @template Output - The shape of the use case output data
+ */
+export type UseCaseRuntimeOptions<Output = any> = {
+    /** Override the auto-generated execution ID */
+    id?: string;
+    /** Provide a pre-populated context object */
+    ctx?: UseCaseContext;
+    /** Invocation-level lifecycle callback: fires first, before use case and global */
+    onExecuting?: (ctx: UseCaseOnExecutingContext) => void;
+    /** Invocation-level lifecycle callback: fires first on success */
+    onCompleted?: (result: UseCaseResult<Output>) => void;
+    /** Invocation-level lifecycle callback: fires first on error */
+    onError?: (ctx: UseCaseErrorResult) => void;
+};
+/**
+ * Error result snapshot, emitted via `onError` lifecycle callbacks.
+ * Contains all fields from `UseCaseResult` except `output`, plus the thrown error.
+ */
+export type UseCaseErrorResult = Omit<UseCaseResult, "output"> & {
+    /** The error that caused the failure */
+    error: Error;
+};
+/**
+ * Success result snapshot, emitted via `onCompleted` lifecycle callbacks
+ * and stored in execution history cache.
+ *
+ * @template Output - The shape of the handler's return value
+ */
+export type UseCaseResult<Output = any> = {
+    /** Handler return value (undefined if execution failed) */
+    output?: Output;
+    /** The pipeline context at time of completion */
+    ctx: UseCaseContext;
+    /** Timestamp when execution started */
+    startedAt: Date;
+    /** Timestamp when execution ended */
+    endedAt: Date;
+    /** Unique execution ID */
+    id: string;
+    /** Use case name */
+    name: string;
+    /** Number of successful calls at time of completion */
+    calls: number;
+    /** Retry state (present only if retries were configured) */
+    retries?: {
+        /** Total allowed retries */
+        count: number;
+        /** Actual attempt number that succeeded/failed (if tracked) */
+        currentRetry?: number;
+        /** Delay between retries in ms */
+        delay?: number;
+    };
+    /** Benchmark result (present only if benchmark was enabled) */
+    benchmarkResult?: {
+        /** Execution time in milliseconds */
+        latency: number;
+        /** Performance classification */
+        state: "poor" | "good" | "excellent";
+    };
+};
+/**
+ * Internal registry of global lifecycle event callback arrays.
+ * Used by `globalUseCasesEvents` to manage subscriptions.
+ */
+export type UseCaseEventsCallbacksMap = {
+    onExecuting: ((ctx: UseCaseOnExecutingContext) => void)[];
+    onCompleted: ((result: UseCaseResult<any>) => void)[];
+    onError: ((ctx: UseCaseErrorResult) => void)[];
+};
+/**
+ * App-level configuration for use cases, resolved via `config.get("use-cases")`.
+ * Provides default values that can be overridden per use case.
+ *
+ * @example
+ * ```ts
+ * // In your app config file:
+ * export default {
+ *   "use-cases": {
+ *     benchmark: { enabled: true, latencyRange: { up: 100, down: 500 } },
+ *     retries: { count: 3, delay: 1000 },
+ *     history: { enabled: true, ttl: 7200 },
+ *   },
+ * };
+ * ```
+ */
+export type UseCaseConfigurations = {
+    /**
+     * Default benchmark settings for all use cases.
+     * For standalone benchmark usage, use `config.get("benchmark")` instead.
+     */
+    benchmarkOptions?: BenchmarkOptions | false;
+    /** Default retry settings for all use cases */
+    retryOptions?: RetryOptions;
+    /** Execution history cache settings */
+    history?: {
+        /** Enable/disable history storage (default: true) */
+        enabled?: boolean;
+        /** Cache TTL in seconds (default: 3600)
+         * Setting it to false will use default cache ttl value
+         */
+        ttl?: number | false;
+    };
+};
+//# sourceMappingURL=types.d.ts.map

package/esm/use-cases/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/use-cases/types.ts"],"names":[],"mappings":"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"}

package/esm/use-cases/use-case-events.d.ts

@@ -0,0 +1,33 @@
+import type { UseCaseErrorResult, UseCaseEventsCallbacksMap, UseCaseOnExecutingContext, UseCaseResult } from "./types";
+/**
+ * Global event callbacks — shared across all use case instances.
+ */
+export declare const globalEventsCallbacksMap: UseCaseEventsCallbacksMap;
+/**
+ * Subscribe to lifecycle events fired by any use case.
+ *
+ * @example
+ * globalUseCasesEvents.onCompleted((result) => metrics.track(result.name, result.benchmarkResult));
+ * globalUseCasesEvents.onError((ctx) => logger.error(ctx.name, ctx.error));
+ */
+export declare const globalUseCasesEvents: {
+    onExecuting(callback: (ctx: UseCaseOnExecutingContext) => void): {
+        unsubscribe: () => void;
+    };
+    onCompleted<Output>(callback: (result: UseCaseResult<Output>) => void): {
+        unsubscribe: () => void;
+    };
+    onError(callback: (ctx: UseCaseErrorResult) => void): {
+        unsubscribe: () => void;
+    };
+};
+/**
+ * Dispatches a lifecycle event to invocation → use-case → global observers, in that order.
+ * All observers are awaited sequentially.
+ */
+export declare function fireLifecycleEvent<EventCtx>(ctx: EventCtx, observers: {
+    invocation?: ((ctx: EventCtx) => void | Promise<void>)[];
+    useCase?: ((ctx: EventCtx) => void | Promise<void>)[];
+    global?: ((ctx: EventCtx) => void | Promise<void>)[];
+}): Promise<void>;
+//# sourceMappingURL=use-case-events.d.ts.map

package/esm/use-cases/use-case-events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-case-events.d.ts","sourceRoot":"","sources":["../../src/use-cases/use-case-events.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,kBAAkB,EAClB,yBAAyB,EACzB,yBAAyB,EACzB,aAAa,EACd,MAAM,SAAS,CAAC;AAEjB;;GAEG;AACH,eAAO,MAAM,wBAAwB,EAAE,yBAItC,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB;gCACH,yBAAyB,KAAK,IAAI;;;qEASG,IAAI;;;4BAS7C,kBAAkB,KAAK,IAAI;;;CASpD,CAAC;AAEF;;;GAGG;AACH,wBAAsB,kBAAkB,CAAC,QAAQ,EAC/C,GAAG,EAAE,QAAQ,EACb,SAAS,EAAE;IACT,UAAU,CAAC,EAAE,CAAC,CAAC,GAAG,EAAE,QAAQ,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC;IACzD,OAAO,CAAC,EAAE,CAAC,CAAC,GAAG,EAAE,QAAQ,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC;IACtD,MAAM,CAAC,EAAE,CAAC,CAAC,GAAG,EAAE,QAAQ,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC;CACtD,iBAaF"}

package/esm/use-cases/use-case-events.js

@@ -0,0 +1,65 @@
+/**
+ * Global event callbacks — shared across all use case instances.
+ */
+const globalEventsCallbacksMap = {
+    onExecuting: [],
+    onCompleted: [],
+    onError: [],
+};
+/**
+ * Subscribe to lifecycle events fired by any use case.
+ *
+ * @example
+ * globalUseCasesEvents.onCompleted((result) => metrics.track(result.name, result.benchmarkResult));
+ * globalUseCasesEvents.onError((ctx) => logger.error(ctx.name, ctx.error));
+ */
+const globalUseCasesEvents = {
+    onExecuting(callback) {
+        globalEventsCallbacksMap.onExecuting.push(callback);
+        return {
+            unsubscribe: () => {
+                const idx = globalEventsCallbacksMap.onExecuting.indexOf(callback);
+                if (idx !== -1)
+                    globalEventsCallbacksMap.onExecuting.splice(idx, 1);
+            },
+        };
+    },
+    onCompleted(callback) {
+        globalEventsCallbacksMap.onCompleted.push(callback);
+        return {
+            unsubscribe: () => {
+                const idx = globalEventsCallbacksMap.onCompleted.indexOf(callback);
+                if (idx !== -1)
+                    globalEventsCallbacksMap.onCompleted.splice(idx, 1);
+            },
+        };
+    },
+    onError(callback) {
+        globalEventsCallbacksMap.onError.push(callback);
+        return {
+            unsubscribe: () => {
+                const idx = globalEventsCallbacksMap.onError.indexOf(callback);
+                if (idx !== -1)
+                    globalEventsCallbacksMap.onError.splice(idx, 1);
+            },
+        };
+    },
+};
+/**
+ * Dispatches a lifecycle event to invocation → use-case → global observers, in that order.
+ * All observers are awaited sequentially.
+ */
+async function fireLifecycleEvent(ctx, observers) {
+    if (observers.invocation) {
+        for (const obs of observers.invocation)
+            await obs(ctx);
+    }
+    if (observers.useCase) {
+        for (const obs of observers.useCase)
+            await obs(ctx);
+    }
+    if (observers.global) {
+        for (const obs of observers.global)
+            await obs(ctx);
+    }
+}export{fireLifecycleEvent,globalEventsCallbacksMap,globalUseCasesEvents};//# sourceMappingURL=use-case-events.js.map

package/esm/use-cases/use-case-events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-case-events.js","sources":["../../src/use-cases/use-case-events.ts"],"sourcesContent":[null],"names":[],"mappings":"AAOA;;AAEG;AACU,MAAA,wBAAwB,GAA8B;AACjE,IAAA,WAAW,EAAE,EAAE;AACf,IAAA,WAAW,EAAE,EAAE;AACf,IAAA,OAAO,EAAE,EAAE;EACX;AAEF;;;;;;AAMG;AACU,MAAA,oBAAoB,GAAG;AAClC,IAAA,WAAW,CAAC,QAAkD,EAAA;AAC5D,QAAA,wBAAwB,CAAC,WAAW,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACpD,OAAO;YACL,WAAW,EAAE,MAAK;gBAChB,MAAM,GAAG,GAAG,wBAAwB,CAAC,WAAW,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;gBACnE,IAAI,GAAG,KAAK,CAAC,CAAC;oBAAE,wBAAwB,CAAC,WAAW,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;aACrE;SACF,CAAC;KACH;AACD,IAAA,WAAW,CAAS,QAAiD,EAAA;AACnE,QAAA,wBAAwB,CAAC,WAAW,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACpD,OAAO;YACL,WAAW,EAAE,MAAK;gBAChB,MAAM,GAAG,GAAG,wBAAwB,CAAC,WAAW,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;gBACnE,IAAI,GAAG,KAAK,CAAC,CAAC;oBAAE,wBAAwB,CAAC,WAAW,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;aACrE;SACF,CAAC;KACH;AACD,IAAA,OAAO,CAAC,QAA2C,EAAA;AACjD,QAAA,wBAAwB,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAChD,OAAO;YACL,WAAW,EAAE,MAAK;gBAChB,MAAM,GAAG,GAAG,wBAAwB,CAAC,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;gBAC/D,IAAI,GAAG,KAAK,CAAC,CAAC;oBAAE,wBAAwB,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;aACjE;SACF,CAAC;KACH;EACD;AAEF;;;AAGG;AACI,eAAe,kBAAkB,CACtC,GAAa,EACb,SAIC,EAAA;IAED,IAAI,SAAS,CAAC,UAAU,EAAE;AACxB,QAAA,KAAK,MAAM,GAAG,IAAI,SAAS,CAAC,UAAU;AAAE,YAAA,MAAM,GAAG,CAAC,GAAG,CAAC,CAAC;AACxD,KAAA;IAED,IAAI,SAAS,CAAC,OAAO,EAAE;AACrB,QAAA,KAAK,MAAM,GAAG,IAAI,SAAS,CAAC,OAAO;AAAE,YAAA,MAAM,GAAG,CAAC,GAAG,CAAC,CAAC;AACrD,KAAA;IAED,IAAI,SAAS,CAAC,MAAM,EAAE;AACpB,QAAA,KAAK,MAAM,GAAG,IAAI,SAAS,CAAC,MAAM;AAAE,YAAA,MAAM,GAAG,CAAC,GAAG,CAAC,CAAC;AACpD,KAAA;AACH"}

package/esm/use-cases/use-case-pipeline.d.ts

@@ -0,0 +1,29 @@
+import type { ObjectValidator } from "@warlock.js/seal";
+import type { UseCaseBeforeMiddleware, UseCaseContext, UseCaseGuard, UseCaseOnExecutingContext } from "./types";
+export type PipelineOptions<Input, Output> = {
+    name: string;
+    id: string;
+    data: Input;
+    ctx: UseCaseContext;
+    startedAt: Date;
+    schema?: ObjectValidator;
+    guards?: UseCaseGuard<Input>[];
+    before?: UseCaseBeforeMiddleware<Input>[];
+    handler: (data: Input, ctx: UseCaseContext) => Promise<Output>;
+    /** Invocation-level onExecuting override */
+    onExecuting?: (ctx: UseCaseOnExecutingContext) => void;
+    /** Use-case-level onExecuting */
+    ucOnExecuting?: (ctx: UseCaseOnExecutingContext) => void;
+};
+/**
+ * Runs the full use-case pipeline in order:
+ * onExecuting event → guards → validation → before middleware → handler
+ *
+ * Throws on guard failure, validation failure, or handler failure.
+ * Callers are responsible for retry and benchmarking wrapping.
+ *
+ * @example
+ * const output = await runPipeline({ name, id, data, ctx, schema, guards, before, handler, ... });
+ */
+export declare function runPipeline<Input, Output>(opts: PipelineOptions<Input, Output>): Promise<Output>;
+//# sourceMappingURL=use-case-pipeline.d.ts.map

package/esm/use-cases/use-case-pipeline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-case-pipeline.d.ts","sourceRoot":"","sources":["../../src/use-cases/use-case-pipeline.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAExD,OAAO,KAAK,EACV,uBAAuB,EACvB,cAAc,EACd,YAAY,EACZ,yBAAyB,EAC1B,MAAM,SAAS,CAAC;AAIjB,MAAM,MAAM,eAAe,CAAC,KAAK,EAAE,MAAM,IAAI;IAC3C,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,KAAK,CAAC;IACZ,GAAG,EAAE,cAAc,CAAC;IACpB,SAAS,EAAE,IAAI,CAAC;IAChB,MAAM,CAAC,EAAE,eAAe,CAAC;IACzB,MAAM,CAAC,EAAE,YAAY,CAAC,KAAK,CAAC,EAAE,CAAC;IAC/B,MAAM,CAAC,EAAE,uBAAuB,CAAC,KAAK,CAAC,EAAE,CAAC;IAC1C,OAAO,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,cAAc,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAC/D,4CAA4C;IAC5C,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,yBAAyB,KAAK,IAAI,CAAC;IACvD,iCAAiC;IACjC,aAAa,CAAC,EAAE,CAAC,GAAG,EAAE,yBAAyB,KAAK,IAAI,CAAC;CAC1D,CAAC;AAEF;;;;;;;;;GASG;AACH,wBAAsB,WAAW,CAAC,KAAK,EAAE,MAAM,EAC7C,IAAI,EAAE,eAAe,CAAC,KAAK,EAAE,MAAM,CAAC,GACnC,OAAO,CAAC,MAAM,CAAC,CA6CjB"}

package/esm/use-cases/use-case-pipeline.js

@@ -0,0 +1,45 @@
+import {v}from'@warlock.js/seal';import {fireLifecycleEvent,globalEventsCallbacksMap}from'./use-case-events.js';import {BadSchemaUseCaseError}from'./use-case.errors.js';/**
+ * Runs the full use-case pipeline in order:
+ * onExecuting event → guards → validation → before middleware → handler
+ *
+ * Throws on guard failure, validation failure, or handler failure.
+ * Callers are responsible for retry and benchmarking wrapping.
+ *
+ * @example
+ * const output = await runPipeline({ name, id, data, ctx, schema, guards, before, handler, ... });
+ */
+async function runPipeline(opts) {
+    const { name, id, ctx, startedAt, schema, guards, before, handler, onExecuting, ucOnExecuting } = opts;
+    let data = opts.data;
+    // 1. Fire onExecuting lifecycle event
+    await fireLifecycleEvent({ name, id, data, schema: schema, ctx, startedAt }, {
+        invocation: onExecuting ? [onExecuting] : undefined,
+        useCase: ucOnExecuting ? [ucOnExecuting] : undefined,
+        global: globalEventsCallbacksMap.onExecuting.length
+            ? globalEventsCallbacksMap.onExecuting
+            : undefined,
+    });
+    // 2. Guards — authorization/precondition checks, run before validation
+    if (guards) {
+        for (const guard of guards) {
+            await guard(Object.freeze(data), ctx);
+        }
+    }
+    // 3. Schema validation
+    if (schema) {
+        const result = await v.validate(schema, data);
+        if (!result.isValid) {
+            throw new BadSchemaUseCaseError(result);
+        }
+        data = result.data;
+    }
+    // 4. Before middleware — sequential data transformation chain
+    let transformed = data;
+    if (before) {
+        for (const mw of before) {
+            transformed = await mw(transformed, ctx);
+        }
+    }
+    // 5. Core handler
+    return handler(transformed, ctx);
+}export{runPipeline};//# sourceMappingURL=use-case-pipeline.js.map

package/esm/use-cases/use-case-pipeline.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-case-pipeline.js","sources":["../../src/use-cases/use-case-pipeline.ts"],"sourcesContent":[null],"names":[],"mappings":"yKA2BA;;;;;;;;;AASG;AACI,eAAe,WAAW,CAC/B,IAAoC,EAAA;IAEpC,MAAM,EAAE,IAAI,EAAE,EAAE,EAAE,GAAG,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,GAC7F,IAAI,CAAC;AACP,IAAA,IAAI,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;;AAGrB,IAAA,MAAM,kBAAkB,CACtB,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,MAAO,EAAE,GAAG,EAAE,SAAS,EAAE,EACnD;QACE,UAAU,EAAE,WAAW,GAAG,CAAC,WAAW,CAAC,GAAG,SAAS;QACnD,OAAO,EAAE,aAAa,GAAG,CAAC,aAAa,CAAC,GAAG,SAAS;AACpD,QAAA,MAAM,EAAE,wBAAwB,CAAC,WAAW,CAAC,MAAM;cAC/C,wBAAwB,CAAC,WAAW;AACtC,cAAE,SAAS;AACd,KAAA,CACF,CAAC;;AAGF,IAAA,IAAI,MAAM,EAAE;AACV,QAAA,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE;YAC1B,MAAM,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAoB,EAAE,GAAG,CAAC,CAAC;AAC1D,SAAA;AACF,KAAA;;AAGD,IAAA,IAAI,MAAM,EAAE;QACV,MAAM,MAAM,GAAG,MAAM,CAAC,CAAC,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;AAE9C,QAAA,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE;AACnB,YAAA,MAAM,IAAI,qBAAqB,CAAC,MAAM,CAAC,CAAC;AACzC,SAAA;AAED,QAAA,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC;AACpB,KAAA;;IAGD,IAAI,WAAW,GAAG,IAAI,CAAC;AACvB,IAAA,IAAI,MAAM,EAAE;AACV,QAAA,KAAK,MAAM,EAAE,IAAI,MAAM,EAAE;YACvB,WAAW,GAAG,MAAM,EAAE,CAAC,WAAW,EAAE,GAAG,CAAC,CAAC;AAC1C,SAAA;AACF,KAAA;;AAGD,IAAA,OAAO,OAAO,CAAC,WAAW,EAAE,GAAG,CAAC,CAAC;AACnC"}

package/esm/use-cases/use-case.d.ts

@@ -0,0 +1,27 @@
+import type { UseCase, UseCaseRuntimeOptions } from "./types";
+/**
+ * Defines and registers a use case.
+ *
+ * A use case is a named, observable, optionally benchmarked unit of business logic.
+ * The returned handler is a typed async function you call with the input data.
+ *
+ * Execution order: onExecuting → guards → validation → before → handler → after → onCompleted
+ *
+ * @example
+ * export const createOrderUseCase = useCase<OrderOutput, OrderInput>({
+ *   name: "create_order",
+ *   schema: createOrderSchema,
+ *   guards: [authGuard],
+ *   handler: async (data, ctx) => orderService.create(data),
+ *   after: [sendConfirmationEmail],
+ *   retries: { count: 2, delay: 500 },
+ * });
+ *
+ * // In a controller:
+ * const output = await createOrderUseCase({ ...validated, user_id: req.user.id });
+ */
+export declare function useCase<Output, Input = any>(options: UseCase<Output, Input>): {
+    (data: Input, { ctx, id, onExecuting: invocationOnExecuting, onCompleted: invocationOnCompleted, onError: invocationOnError, }?: UseCaseRuntimeOptions): Promise<Output>;
+    $cleanup(): void;
+};
+//# sourceMappingURL=use-case.d.ts.map

package/esm/use-cases/use-case.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-case.d.ts","sourceRoot":"","sources":["../../src/use-cases/use-case.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,OAAO,EAIP,qBAAqB,EACtB,MAAM,SAAS,CAAC;AAyBjB;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,OAAO,CAAC,MAAM,EAAE,KAAK,GAAG,GAAG,EAAE,OAAO,EAAE,OAAO,CAAC,MAAM,EAAE,KAAK,CAAC;WAelE,KAAK,qHAOR,qBAAqB,GACvB,QAAQ,MAAM,CAAC;;EAgHnB"}

package/esm/use-cases/use-case.errors.d.ts

@@ -0,0 +1,6 @@
+import type { ValidationResult } from "@warlock.js/seal";
+import { HttpError } from "../http/errors/errors";
+export declare class BadSchemaUseCaseError extends HttpError {
+    constructor(result: ValidationResult);
+}
+//# sourceMappingURL=use-case.errors.d.ts.map

package/esm/use-cases/use-case.errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-case.errors.d.ts","sourceRoot":"","sources":["../../src/use-cases/use-case.errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACzD,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAElD,qBAAa,qBAAsB,SAAQ,SAAS;gBAC/B,MAAM,EAAE,gBAAgB;CAM5C"}

package/esm/use-cases/use-case.errors.js

@@ -0,0 +1,8 @@
+import {HttpError}from'../http/errors/errors.js';class BadSchemaUseCaseError extends HttpError {
+    constructor(result) {
+        super(400, `Invalid input data`, {
+            code: "BAD_SCHEMA_USE_CASE",
+            errors: result.errors,
+        });
+    }
+}export{BadSchemaUseCaseError};//# sourceMappingURL=use-case.errors.js.map

package/esm/use-cases/use-case.errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-case.errors.js","sources":["../../src/use-cases/use-case.errors.ts"],"sourcesContent":[null],"names":[],"mappings":"iDAGM,MAAO,qBAAsB,SAAQ,SAAS,CAAA;AAClD,IAAA,WAAA,CAAmB,MAAwB,EAAA;AACzC,QAAA,KAAK,CAAC,GAAG,EAAE,CAAA,kBAAA,CAAoB,EAAE;AAC/B,YAAA,IAAI,EAAE,qBAAqB;YAC3B,MAAM,EAAE,MAAM,CAAC,MAAM;AACtB,SAAA,CAAC,CAAC;KACJ;AACF"}

package/esm/use-cases/use-case.js

@@ -0,0 +1,138 @@
+import {except,Random}from'@mongez/reinforcements';import {measure}from'../benchmark/benchmark.js';import {config}from'../config/config-getter.js';import'../config/config-handlers.js';import {retry}from'../retry/retry.js';import {fireLifecycleEvent,globalEventsCallbacksMap}from'./use-case-events.js';import {runPipeline}from'./use-case-pipeline.js';import {$registerUseCase,$unregisterUseCase,increaseUseCaseSuccessCalls,increaseUseCaseFailedCalls,addUseCaseHistory}from'./use-cases-registry.js';const defaultUseCaseOptions = {
+    benchmarkOptions: {
+        enabled: true,
+        latencyRange: {
+            excellent: 100,
+            poor: 200,
+        },
+    },
+    retryOptions: {
+        count: 0,
+        delay: 0,
+    },
+};
+/**
+ * Defines and registers a use case.
+ *
+ * A use case is a named, observable, optionally benchmarked unit of business logic.
+ * The returned handler is a typed async function you call with the input data.
+ *
+ * Execution order: onExecuting → guards → validation → before → handler → after → onCompleted
+ *
+ * @example
+ * export const createOrderUseCase = useCase<OrderOutput, OrderInput>({
+ *   name: "create_order",
+ *   schema: createOrderSchema,
+ *   guards: [authGuard],
+ *   handler: async (data, ctx) => orderService.create(data),
+ *   after: [sendConfirmationEmail],
+ *   retries: { count: 2, delay: 500 },
+ * });
+ *
+ * // In a controller:
+ * const output = await createOrderUseCase({ ...validated, user_id: req.user.id });
+ */
+function useCase(options) {
+    const { name, handler, schema, guards, before, after, onExecuting, onCompleted, onError } = options;
+    // Merge per-use-case options with global config defaults
+    const useCaseConfig = config.get("use-cases", defaultUseCaseOptions);
+    const benchmarkOptions = options.benchmarkOptions ?? useCaseConfig?.benchmarkOptions;
+    const retryOptions = options.retryOptions ?? useCaseConfig?.retryOptions;
+    $registerUseCase(name, {
+        ...options,
+        calls: { success: 0, failed: 0, total: 0 },
+    });
+    const useCaseHandler = async (data, { ctx = {}, id = `uc-${name}-` + Random.string(), onExecuting: invocationOnExecuting, onCompleted: invocationOnCompleted, onError: invocationOnError, } = {}) => {
+        ctx.schema = schema;
+        ctx.id = id;
+        const startedAt = new Date();
+        let output;
+        let error;
+        let benchmarkResult;
+        // The core pipeline — wrapped by retry and/or benchmark below
+        const execute = () => runPipeline({
+            name,
+            id,
+            data,
+            ctx,
+            startedAt,
+            schema,
+            guards,
+            before,
+            handler,
+            onExecuting: invocationOnExecuting,
+            ucOnExecuting: onExecuting,
+        });
+        // Apply retry if configured, otherwise execute once
+        const run = () => retryOptions?.count && retryOptions.count > 0 ? retry(execute, retryOptions) : execute();
+        try {
+            if (benchmarkOptions) {
+                // measure() catches errors internally and returns a result object.
+                // Re-throw on failure so the outer catch handles it uniformly.
+                const result = await measure(name, run, typeof benchmarkOptions === "boolean" ? undefined : benchmarkOptions);
+                if (result.success) {
+                    output = result.value;
+                    benchmarkResult = except(result, ["value", "success"]);
+                }
+                else {
+                    benchmarkResult = except(result, ["error", "success"]);
+                    throw result.error;
+                }
+            }
+            else {
+                output = await run();
+            }
+        }
+        catch (err) {
+            error = err;
+        }
+        const endedAt = new Date();
+        // After middleware — fire-and-forget side effects, only on success
+        if (!error && after && output !== undefined) {
+            for (const middleware of after) {
+                try {
+                    await middleware(output, ctx);
+                }
+                catch (err) {
+                    console.error(`[use-case] After middleware error in "${name}":`, err);
+                }
+            }
+        }
+        const snapshot = {
+            output,
+            ctx,
+            startedAt,
+            endedAt,
+            id,
+            name,
+            retries: retryOptions?.count
+                ? { count: retryOptions.count, delay: retryOptions.delay }
+                : undefined,
+            benchmarkResult,
+            calls: increaseUseCaseSuccessCalls(name),
+        };
+        if (error) {
+            await fireLifecycleEvent({ ...except(snapshot, ["output"]), error, calls: increaseUseCaseFailedCalls(name) }, {
+                invocation: invocationOnError ? [invocationOnError] : undefined,
+                useCase: onError ? [onError] : undefined,
+                global: globalEventsCallbacksMap.onError.length
+                    ? globalEventsCallbacksMap.onError
+                    : undefined,
+            });
+            throw error;
+        }
+        await addUseCaseHistory(name, snapshot);
+        await fireLifecycleEvent(snapshot, {
+            invocation: invocationOnCompleted ? [invocationOnCompleted] : undefined,
+            useCase: onCompleted ? [onCompleted] : undefined,
+            global: globalEventsCallbacksMap.onCompleted.length
+                ? globalEventsCallbacksMap.onCompleted
+                : undefined,
+        });
+        return output;
+    };
+    useCaseHandler.$cleanup = () => {
+        $unregisterUseCase(name);
+    };
+    return useCaseHandler;
+}export{useCase};//# sourceMappingURL=use-case.js.map