@kellanjs/actioncraft 0.1.0 → 0.2.1

package/dist/classes/action-builder.d.ts

@@ -0,0 +1,59 @@
+import type { Handler, CraftedAction, InferDataFromHandler, HandlerParams } from "../types/actions.js";
+import type { Config, Schemas, Errors, Callbacks } from "../types/builder.js";
+export declare class ActionBuilder<TConfig extends Config, TSchemas extends Schemas, TErrors extends Errors, TCallbacks extends Callbacks<TConfig, TSchemas, TErrors, TData>, TData> {
+    private readonly _config;
+    private readonly _schemas;
+    private readonly _errors;
+    private readonly _callbacks;
+    private readonly _handler?;
+    constructor(config: TConfig, schemas: TSchemas, errors: TErrors, callbacks: TCallbacks, handler?: Handler<TConfig, TSchemas, TErrors, TData>);
+    /**
+     * Defines configuration options for the action.
+     * Resets previously defined handler and callbacks.
+     */
+    config<TNewConfig extends Config>(config: TNewConfig): ActionBuilder<TNewConfig, TSchemas, TErrors, Record<string, never>, unknown>;
+    /**
+     * Defines validation schemas for input, output, and bind arguments.
+     * Resets previously defined handler and callbacks.
+     */
+    schemas<TNewSchemas extends Schemas>(schemas: TNewSchemas): ActionBuilder<TConfig, TNewSchemas, TErrors, Record<string, never>, unknown>;
+    /**
+     * Defines error functions for returning typed errors from the handler.
+     * Resets previously defined handler and callbacks.
+     */
+    errors<const TNewErrors extends Errors>(errors: TNewErrors): ActionBuilder<TConfig, TSchemas, TNewErrors, Record<string, never>, unknown>;
+    /**
+     * Defines the handler function containing the server action's business logic.
+     * Resets previously defined callbacks.
+     */
+    handler<TFn extends (params: HandlerParams<TConfig, TSchemas, TErrors, TData>) => Promise<unknown>>(fn: TFn): ActionBuilder<TConfig, TSchemas, TErrors, Record<string, never>, InferDataFromHandler<TFn>>;
+    /**
+     * Defines lifecycle callbacks to be triggered during the exection of an action.
+     * Must be called after handler() for correct type inference.
+     */
+    callbacks<TNewCallbacks extends Callbacks<TConfig, TSchemas, TErrors, TData>>(callbacks: TNewCallbacks): ActionBuilder<TConfig, TSchemas, TErrors, TNewCallbacks, TData>;
+    /**
+     * Builds and returns the final executable server action.
+     * This is the terminal method for the ActionBuilder fluent API.
+     */
+    craft(): CraftedAction<TConfig, TSchemas, TErrors, TData>;
+}
+/**
+ * One of two entry points to the Actioncraft system.
+ * Creates a new ActionBuilder instance for the fluent API that ends with craft().
+ * This provides an alternative syntax for building your server actions.
+ *
+ * Example Usage:
+ * ```ts
+ * const myAction = action()
+ *   .config(...)
+ *   .schemas(...)
+ *   .errors(...)
+ *   .handler(...)
+ *   .callbacks(...)
+ *   .craft();
+ * ```
+ *
+ * @returns A new ActionBuilder instance to start building your action.
+ */
+export declare function action(): ActionBuilder<Record<string, never>, Record<string, never>, Record<string, never>, Record<string, never>, unknown>;

package/dist/classes/action-builder.js

@@ -0,0 +1,95 @@
+import { CraftBuilder } from "./craft-builder.js";
+import { Executor } from "./executor/executor.js";
+// ============================================================================
+// ACTION BUILDER CLASS - Alternative fluent API syntax ending with craft()
+// ============================================================================
+export class ActionBuilder {
+    _config;
+    _schemas;
+    _errors;
+    _callbacks;
+    _handler;
+    constructor(config, schemas, errors, callbacks, handler) {
+        this._config = config;
+        this._schemas = schemas;
+        this._errors = errors;
+        this._callbacks = callbacks;
+        this._handler = handler;
+    }
+    // --------------------------------------------------------------------------
+    // FLUENT API METHODS (same as CraftBuilder)
+    // --------------------------------------------------------------------------
+    /**
+     * Defines configuration options for the action.
+     * Resets previously defined handler and callbacks.
+     */
+    config(config) {
+        return new ActionBuilder(config, this._schemas, this._errors, {}, undefined);
+    }
+    /**
+     * Defines validation schemas for input, output, and bind arguments.
+     * Resets previously defined handler and callbacks.
+     */
+    schemas(schemas) {
+        return new ActionBuilder(this._config, schemas, this._errors, {}, undefined);
+    }
+    /**
+     * Defines error functions for returning typed errors from the handler.
+     * Resets previously defined handler and callbacks.
+     */
+    errors(errors) {
+        return new ActionBuilder(this._config, this._schemas, errors, {}, undefined);
+    }
+    /**
+     * Defines the handler function containing the server action's business logic.
+     * Resets previously defined callbacks.
+     */
+    handler(fn) {
+        return new ActionBuilder(this._config, this._schemas, this._errors, {}, fn);
+    }
+    /**
+     * Defines lifecycle callbacks to be triggered during the exection of an action.
+     * Must be called after handler() for correct type inference.
+     */
+    callbacks(callbacks) {
+        return new ActionBuilder(this._config, this._schemas, this._errors, callbacks, this._handler);
+    }
+    // --------------------------------------------------------------------------
+    // CRAFT METHOD - Final step to create the action
+    // --------------------------------------------------------------------------
+    /**
+     * Builds and returns the final executable server action.
+     * This is the terminal method for the ActionBuilder fluent API.
+     */
+    craft() {
+        // Convert ActionBuilder to CraftBuilder and use existing Executor logic
+        const builder = new CraftBuilder(this._config, this._schemas, this._errors, this._callbacks, this._handler);
+        const executor = new Executor(builder);
+        return executor.craft();
+    }
+}
+// ============================================================================
+// PUBLIC API FUNCTION
+// ============================================================================
+/**
+ * One of two entry points to the Actioncraft system.
+ * Creates a new ActionBuilder instance for the fluent API that ends with craft().
+ * This provides an alternative syntax for building your server actions.
+ *
+ * Example Usage:
+ * ```ts
+ * const myAction = action()
+ *   .config(...)
+ *   .schemas(...)
+ *   .errors(...)
+ *   .handler(...)
+ *   .callbacks(...)
+ *   .craft();
+ * ```
+ *
+ * @returns A new ActionBuilder instance to start building your action.
+ */
+export function action() {
+    return new ActionBuilder({}, {}, {}, {}, undefined);
+}
+//# sourceMappingURL=action-builder.js.map

package/dist/classes/action-builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"action-builder.js","sourceRoot":"","sources":["../../src/classes/action-builder.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAElD,+EAA+E;AAC/E,2EAA2E;AAC3E,+EAA+E;AAE/E,MAAM,OAAO,aAAa;IAOP,OAAO,CAAU;IACjB,QAAQ,CAAW;IACnB,OAAO,CAAU;IACjB,UAAU,CAAa;IACvB,QAAQ,CAA8C;IAEvE,YACE,MAAe,EACf,OAAiB,EACjB,MAAe,EACf,SAAqB,EACrB,OAAoD;QAEpD,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC;QACtB,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC;QACxB,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC;QACtB,IAAI,CAAC,UAAU,GAAG,SAAS,CAAC;QAC5B,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC;IAC1B,CAAC;IAED,6EAA6E;IAC7E,4CAA4C;IAC5C,6EAA6E;IAE7E;;;OAGG;IACH,MAAM,CACJ,MAAkB;QAQlB,OAAO,IAAI,aAAa,CACtB,MAAM,EACN,IAAI,CAAC,QAAQ,EACb,IAAI,CAAC,OAAO,EACZ,EAA2B,EAC3B,SAAS,CACV,CAAC;IACJ,CAAC;IAED;;;OAGG;IACH,OAAO,CACL,OAAoB;QAQpB,OAAO,IAAI,aAAa,CACtB,IAAI,CAAC,OAAO,EACZ,OAAO,EACP,IAAI,CAAC,OAAO,EACZ,EAA2B,EAC3B,SAAS,CACV,CAAC;IACJ,CAAC;IAED;;;OAGG;IACH,MAAM,CACJ,MAAkB;QAQlB,OAAO,IAAI,aAAa,CACtB,IAAI,CAAC,OAAO,EACZ,IAAI,CAAC,QAAQ,EACb,MAAM,EACN,EAA2B,EAC3B,SAAS,CACV,CAAC;IACJ,CAAC;IAED;;;OAGG;IACH,OAAO,CAKL,EAAO;QAQP,OAAO,IAAI,aAAa,CACtB,IAAI,CAAC,OAAO,EACZ,IAAI,CAAC,QAAQ,EACb,IAAI,CAAC,OAAO,EACZ,EAA2B,EAC3B,EAAoE,CACrE,CAAC;IACJ,CAAC;IAED;;;OAGG;IACH,SAAS,CACP,SAAwB;QAExB,OAAO,IAAI,aAAa,CACtB,IAAI,CAAC,OAAO,EACZ,IAAI,CAAC,QAAQ,EACb,IAAI,CAAC,OAAO,EACZ,SAAS,EACT,IAAI,CAAC,QAAQ,CACd,CAAC;IACJ,CAAC;IAED,6EAA6E;IAC7E,iDAAiD;IACjD,6EAA6E;IAE7E;;;OAGG;IACH,KAAK;QACH,wEAAwE;QACxE,MAAM,OAAO,GAAG,IAAI,YAAY,CAC9B,IAAI,CAAC,OAAO,EACZ,IAAI,CAAC,QAAQ,EACb,IAAI,CAAC,OAAO,EACZ,IAAI,CAAC,UAAU,EACf,IAAI,CAAC,QAAQ,CACd,CAAC;QAEF,MAAM,QAAQ,GAAG,IAAI,QAAQ,CAAC,OAAO,CAAC,CAAC;QACvC,OAAO,QAAQ,CAAC,KAAK,EAAE,CAAC;IAC1B,CAAC;CACF;AAED,+EAA+E;AAC/E,sBAAsB;AACtB,+EAA+E;AAE/E;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,MAAM;IAOpB,OAAO,IAAI,aAAa,CACtB,EAA2B,EAC3B,EAA2B,EAC3B,EAA2B,EAC3B,EAA2B,EAC3B,SAAS,CACV,CAAC;AACJ,CAAC"}

package/dist/classes/craft-builder.d.ts

@@ -0,0 +1,66 @@
+import type { Handler, InferDataFromHandler, HandlerParams, CraftedAction } from "../types/actions.js";
+import type { Config, Schemas, Errors, Callbacks } from "../types/builder.js";
+import { INTERNAL, type CrafterInternals } from "./internal.js";
+export declare class CraftBuilder<TConfig extends Config, TSchemas extends Schemas, TErrors extends Errors, TCallbacks extends Callbacks<TConfig, TSchemas, TErrors, TData>, TData> {
+    private readonly _config;
+    private readonly _schemas;
+    private readonly _errors;
+    private readonly _callbacks;
+    private readonly _handler?;
+    constructor(config: TConfig, schemas: TSchemas, errors: TErrors, callbacks: TCallbacks, handler?: Handler<TConfig, TSchemas, TErrors, TData>);
+    /**
+     * Defines configuration options for the action.
+     * Resets previously defined handler and callbacks.
+     */
+    config<TNewConfig extends Config>(config: TNewConfig): CraftBuilder<TNewConfig, TSchemas, TErrors, Record<string, never>, unknown>;
+    /**
+     * Defines validation schemas for input, output, and bind arguments.
+     * Resets previously defined handler and callbacks.
+     */
+    schemas<TNewSchemas extends Schemas>(schemas: TNewSchemas): CraftBuilder<TConfig, TNewSchemas, TErrors, Record<string, never>, unknown>;
+    /**
+     * Defines error functions for returning typed errors from the handler.
+     * Resets previously defined handler and callbacks.
+     */
+    errors<const TNewErrors extends Errors>(errors: TNewErrors): CraftBuilder<TConfig, TSchemas, TNewErrors, Record<string, never>, unknown>;
+    /**
+     * Defines the handler function containing the server action's business logic.
+     * Resets previously defined callbacks.
+     */
+    handler<TFn extends (params: HandlerParams<TConfig, TSchemas, TErrors, TData>) => Promise<unknown>>(fn: TFn): CraftBuilder<TConfig, TSchemas, TErrors, Record<string, never>, InferDataFromHandler<TFn>>;
+    /**
+     * Defines lifecycle callbacks to be triggered during the exection of an action.
+     * Must be called after handler() for correct type inference.
+     */
+    callbacks<TNewCallbacks extends Callbacks<TConfig, TSchemas, TErrors, TData>>(callbacks: TNewCallbacks): CraftBuilder<TConfig, TSchemas, TErrors, TNewCallbacks, TData>;
+    /**
+     * @returns Internal properties of the CraftBuilder instance
+     */
+    [INTERNAL](): CrafterInternals<TConfig, TSchemas, TErrors, TCallbacks, TData>;
+}
+/**
+ * Represents the function that the user passes to `craft()` in order to build an action.
+ */
+type CraftFn<TConfig extends Config, TSchemas extends Schemas, TErrors extends Errors, TCallbacks extends Callbacks<TConfig, TSchemas, TErrors, TData>, TData> = (builder: CraftBuilder<Config, Record<string, never>, Record<string, never>, Record<string, never>, unknown>) => CraftBuilder<TConfig, TSchemas, TErrors, TCallbacks, TData> | Promise<CraftBuilder<TConfig, TSchemas, TErrors, TCallbacks, TData>>;
+/**
+ * One of two entry points to the Actioncraft system.
+ * It provides you with an empty CraftBuilder instance on which you can call any of the fluent
+ * CraftBuilder methods to configure and define your action.
+ *
+ * Example Usage:
+ * ```ts
+ * const myAction = craft(async (action) => {
+ *   return action
+ *     .config(...)
+ *     .schemas(...)
+ *     .errors(...)
+ *     .handler(...)
+ *     .callbacks(...)
+ * });
+ * ```
+ *
+ * @param craftFn - The function that the user passes to `craft()` in order to build an action.
+ * @returns The fully-typed server action function that can be used in your app.
+ */
+export declare function craft<TConfig extends Config, TSchemas extends Schemas, TErrors extends Errors, TCallbacks extends Callbacks<TConfig, TSchemas, TErrors, TData>, TData>(craftFn: CraftFn<TConfig, TSchemas, TErrors, TCallbacks, TData>): CraftedAction<TConfig, TSchemas, TErrors, TData>;
+export {};

package/dist/classes/craft-builder.js

@@ -0,0 +1,129 @@
+import { Executor } from "./executor/executor.js";
+import { INTERNAL } from "./internal.js";
+// ============================================================================
+// CRAFT BUILDER CLASS - Configure and define your action
+// ============================================================================
+export class CraftBuilder {
+    _config;
+    _schemas;
+    _errors;
+    _callbacks;
+    _handler;
+    constructor(config, schemas, errors, callbacks, handler) {
+        this._config = config;
+        this._schemas = schemas;
+        this._errors = errors;
+        this._callbacks = callbacks;
+        this._handler = handler;
+    }
+    // --------------------------------------------------------------------------
+    // FLUENT API METHODS
+    // --------------------------------------------------------------------------
+    /**
+     * Defines configuration options for the action.
+     * Resets previously defined handler and callbacks.
+     */
+    config(config) {
+        return new CraftBuilder(config, this._schemas, this._errors, {}, undefined);
+    }
+    /**
+     * Defines validation schemas for input, output, and bind arguments.
+     * Resets previously defined handler and callbacks.
+     */
+    schemas(schemas) {
+        return new CraftBuilder(this._config, schemas, this._errors, {}, undefined);
+    }
+    /**
+     * Defines error functions for returning typed errors from the handler.
+     * Resets previously defined handler and callbacks.
+     */
+    errors(errors) {
+        return new CraftBuilder(this._config, this._schemas, errors, {}, undefined);
+    }
+    /**
+     * Defines the handler function containing the server action's business logic.
+     * Resets previously defined callbacks.
+     */
+    handler(fn) {
+        return new CraftBuilder(this._config, this._schemas, this._errors, {}, fn);
+    }
+    /**
+     * Defines lifecycle callbacks to be triggered during the exection of an action.
+     * Must be called after handler() for correct type inference.
+     */
+    callbacks(callbacks) {
+        return new CraftBuilder(this._config, this._schemas, this._errors, callbacks, this._handler);
+    }
+    /**
+     * @returns Internal properties of the CraftBuilder instance
+     */
+    [INTERNAL]() {
+        return {
+            config: this._config,
+            schemas: this._schemas,
+            errors: this._errors,
+            callbacks: this._callbacks,
+            handler: this._handler,
+        };
+    }
+}
+/**
+ * One of two entry points to the Actioncraft system.
+ * It provides you with an empty CraftBuilder instance on which you can call any of the fluent
+ * CraftBuilder methods to configure and define your action.
+ *
+ * Example Usage:
+ * ```ts
+ * const myAction = craft(async (action) => {
+ *   return action
+ *     .config(...)
+ *     .schemas(...)
+ *     .errors(...)
+ *     .handler(...)
+ *     .callbacks(...)
+ * });
+ * ```
+ *
+ * @param craftFn - The function that the user passes to `craft()` in order to build an action.
+ * @returns The fully-typed server action function that can be used in your app.
+ */
+export function craft(craftFn) {
+    const builder = craftFn(new CraftBuilder({}, {}, {}, {}, undefined));
+    // Handle async builder functions
+    if (builder instanceof Promise) {
+        return _craftAsync(builder);
+    }
+    // Handle sync builder functions
+    const executor = new Executor(builder);
+    const craftedAction = executor.craft();
+    return craftedAction;
+}
+/**
+ * Internal helper function to handle async craft functions.
+ * Encapsulates the logic for creating async actions and preserving metadata.
+ */
+function _craftAsync(builderPromise) {
+    // Resolve the builder once and cache the resulting action to ensure consistent IDs
+    const actionPromise = builderPromise.then((resolvedBuilder) => {
+        const executor = new Executor(resolvedBuilder);
+        return executor.craft();
+    });
+    // For async craft functions, we need to return an async action
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const asyncAction = (async (...args) => {
+        // Wait for the cached action to be ready
+        const craftedAction = await actionPromise;
+        // Call the action with the user's arguments
+        return craftedAction(...args);
+    });
+    // We need to preserve the config and ID for the initial() function to work
+    // We'll use the same cached action to ensure consistent metadata
+    actionPromise.then((craftedAction) => {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        asyncAction.__ac_config = craftedAction.__ac_config;
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        asyncAction.__ac_id = craftedAction.__ac_id;
+    });
+    return asyncAction;
+}
+//# sourceMappingURL=craft-builder.js.map

package/dist/classes/craft-builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"craft-builder.js","sourceRoot":"","sources":["../../src/classes/craft-builder.ts"],"names":[],"mappings":"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"}

package/dist/classes/error.d.ts

@@ -0,0 +1,23 @@
+import type { CraftedAction } from "../types/actions.js";
+import type { BaseError } from "../types/errors.js";
+import type { InferErrors } from "../types/inference.js";
+/**
+ * Error wrapper that provides standard Error semantics while preserving
+ * the original Actioncraft error data in the cause property.
+ */
+export declare class ActioncraftError<TErrorData extends BaseError = BaseError> extends Error {
+    readonly cause: TErrorData;
+    readonly actionId?: string;
+    constructor(errorData: TErrorData, actionId?: string);
+}
+/**
+ * Type guard to check if an error is an ActioncraftError.
+ *
+ * When called with just an error, performs basic structural validation.
+ * When called with an error and action, performs verified action ID checking.
+ *
+ * @param error - The unknown error to check
+ * @param action - Optional action for verified checking and type inference
+ * @returns Type predicate indicating if error is ActioncraftError
+ */
+export declare function isActioncraftError<TAction extends CraftedAction<any, any, any, any>>(error: unknown, action?: TAction): error is ActioncraftError<TAction extends undefined ? BaseError : InferErrors<TAction>>;

package/dist/classes/error.js

@@ -0,0 +1,60 @@
+/**
+ * Error wrapper that provides standard Error semantics while preserving
+ * the original Actioncraft error data in the cause property.
+ */
+export class ActioncraftError extends Error {
+    cause;
+    actionId;
+    constructor(errorData, actionId) {
+        super(`Actioncraft Error: ${errorData.type}${"message" in errorData ? ` - ${errorData.message}` : ""}`);
+        this.name = "ActioncraftError";
+        this.cause = errorData;
+        this.actionId = actionId;
+        // Ensure proper prototype chain for instanceof checks
+        Object.setPrototypeOf(this, ActioncraftError.prototype);
+    }
+}
+/**
+ * Type guard to check if an error is an ActioncraftError.
+ *
+ * When called with just an error, performs basic structural validation.
+ * When called with an error and action, performs verified action ID checking.
+ *
+ * @param error - The unknown error to check
+ * @param action - Optional action for verified checking and type inference
+ * @returns Type predicate indicating if error is ActioncraftError
+ */
+export function isActioncraftError(error, action) {
+    if (!(error instanceof ActioncraftError)) {
+        return false;
+    }
+    // Verify the cause property exists and has the expected BaseError structure
+    const cause = error.cause;
+    if (!cause || typeof cause !== "object") {
+        return false;
+    }
+    // Verify the cause has a type property that's a string (required by BaseError)
+    if (!("type" in cause) || typeof cause.type !== "string") {
+        return false;
+    }
+    // If message exists, it should be a string (optional in BaseError)
+    if ("message" in cause &&
+        cause.message !== undefined &&
+        typeof cause.message !== "string") {
+        return false;
+    }
+    // If no action provided, just do structural validation
+    if (!action) {
+        return true;
+    }
+    // If action provided, verify the action ID matches
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const actionId = action.__ac_id;
+    // Both action and error must have IDs for verification to be possible
+    if (!actionId || !error.actionId) {
+        return false;
+    }
+    // Check if the error's action ID matches the action's ID
+    return error.actionId === actionId;
+}
+//# sourceMappingURL=error.js.map

package/dist/classes/error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error.js","sourceRoot":"","sources":["../../src/classes/error.ts"],"names":[],"mappings":"AAIA;;;GAGG;AACH,MAAM,OAAO,gBAEX,SAAQ,KAAK;IACY,KAAK,CAAa;IAC3B,QAAQ,CAAU;IAElC,YAAY,SAAqB,EAAE,QAAiB;QAClD,KAAK,CACH,sBAAsB,SAAS,CAAC,IAAI,GAClC,SAAS,IAAI,SAAS,CAAC,CAAC,CAAC,MAAM,SAAS,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EACvD,EAAE,CACH,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;QAC/B,IAAI,CAAC,KAAK,GAAG,SAAS,CAAC;QACvB,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QAEzB,sDAAsD;QACtD,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,gBAAgB,CAAC,SAAS,CAAC,CAAC;IAC1D,CAAC;CACF;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,kBAAkB,CAIhC,KAAc,EACd,MAAgB;IAIhB,IAAI,CAAC,CAAC,KAAK,YAAY,gBAAgB,CAAC,EAAE,CAAC;QACzC,OAAO,KAAK,CAAC;IACf,CAAC;IAED,4EAA4E;IAC5E,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC;IAC1B,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QACxC,OAAO,KAAK,CAAC;IACf,CAAC;IAED,+EAA+E;IAC/E,IAAI,CAAC,CAAC,MAAM,IAAI,KAAK,CAAC,IAAI,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QACzD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,mEAAmE;IACnE,IACE,SAAS,IAAI,KAAK;QAClB,KAAK,CAAC,OAAO,KAAK,SAAS;QAC3B,OAAO,KAAK,CAAC,OAAO,KAAK,QAAQ,EACjC,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,uDAAuD;IACvD,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,OAAO,IAAI,CAAC;IACd,CAAC;IAED,mDAAmD;IACnD,8DAA8D;IAC9D,MAAM,QAAQ,GAAI,MAAc,CAAC,OAA6B,CAAC;IAE/D,sEAAsE;IACtE,IAAI,CAAC,QAAQ,IAAI,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC;QACjC,OAAO,KAAK,CAAC;IACf,CAAC;IAED,yDAAyD;IACzD,OAAO,KAAK,CAAC,QAAQ,KAAK,QAAQ,CAAC;AACrC,CAAC"}

package/dist/classes/executor/callbacks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"callbacks.js","sourceRoot":"","sources":["../../../src/classes/executor/callbacks.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,QAAkD,EAClD,YAAoB;AACpB,4CAA4C;AAC5C,KAA6E;IAE7E,IAAI,CAAC,QAAQ;QAAE,OAAO;IAEtB,IAAI,CAAC;QACH,MAAM,QAAQ,EAAE,CAAC;IACnB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,KAAK,EAAE,CAAC;YACV,KAAK,CAAC,OAAO,EAAE,YAAY,YAAY,WAAW,EAAE,KAAK,CAAC,CAAC;QAC7D,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/{core → classes/executor}/errors.d.ts

@@ -1,9 +1,10 @@
-import type { StandardSchemaV1 } from "../standard-schema.js";
-import { EXTERNAL_ERROR_TYPES, INTERNAL_ERROR_TYPES } from "../types/errors.js";
-import type { UnhandledError, ImplicitReturnError, InternalLogicError, ValidationErrorFormat } from "../types/errors.js";
-import type { Result } from "../types/result.js";
+import type { StandardSchemaV1 } from "../../standard-schema.js";
+import { EXTERNAL_ERROR_TYPES, INTERNAL_ERROR_TYPES } from "../../types/errors.js";
+import type { UnhandledError, ImplicitReturnError, InternalLogicError, ValidationErrorFormat, NoInputSchemaError } from "../../types/errors.js";
+import type { Result } from "../../types/result.js";
 export declare const UNHANDLED_ERROR: UnhandledError;
 export declare const IMPLICIT_RETURN_ERROR: ImplicitReturnError;
+export declare const NO_INPUT_SCHEMA_ERROR: NoInputSchemaError;
 /**
  * Creates internal logic errors with custom messages.
  */
@@ -11,11 +12,11 @@ export declare const createInternalLogicError: (message: string) => InternalLogi
 /**
  * Creates Result objects for unhandled errors.
  */
-export declare function createUnhandledErrorResult<TData = never, TError = UnhandledError>(): Result<TData, TError>;
+export declare function createUnhandledErrorResult<TData = never, TError = UnhandledError>(actionId: string, actionName?: string): Result<TData, TError>;
 /**
  * Creates Result objects for implicit return errors.
  */
-export declare function createImplicitReturnErrorResult<TData = never, TError = ImplicitReturnError>(): Result<TData, TError>;
+export declare function createImplicitReturnErrorResult<TData = never, TError = ImplicitReturnError>(actionId: string, actionName?: string): Result<TData, TError>;
 /**
  * Formats validation issues into structured error objects based on the configured format.
  */
@@ -24,5 +25,5 @@ type ValidationErrorType = typeof EXTERNAL_ERROR_TYPES.INPUT_VALIDATION | typeof
 /**
  * Creates validation error objects.
  */
-export declare function createValidationError<TError>(type: ValidationErrorType, message: string, errorStructure: ValidationErrorFormat): TError;
+export declare function createValidationError<TError>(type: ValidationErrorType, message: string, errorStructure: ValidationErrorFormat, actionName?: string): TError;
 export {};

package/dist/{core → classes/executor}/errors.js

@@ -1,5 +1,5 @@
-import { EXTERNAL_ERROR_TYPES, INTERNAL_ERROR_TYPES } from "../types/errors.js";
-import { err } from "../types/result.js";
+import { EXTERNAL_ERROR_TYPES, INTERNAL_ERROR_TYPES, } from "../../types/errors.js";
+import { err } from "../../types/result.js";
 // ===========================================================================
 // CONSTANTS
 // ===========================================================================
@@ -9,7 +9,11 @@ export const UNHANDLED_ERROR = {
 };
 export const IMPLICIT_RETURN_ERROR = {
     type: INTERNAL_ERROR_TYPES.IMPLICIT_RETURN,
-    message: "Action implementation must return a value",
+    message: "Action handler must return a value",
+};
+export const NO_INPUT_SCHEMA_ERROR = {
+    type: "NO_INPUT_SCHEMA",
+    message: "Cannot validate input: no input schema defined for this action",
 };
 // ===========================================================================
 // FACTORY HELPERS
@@ -24,14 +28,20 @@ export const createInternalLogicError = (message) => ({
 /**
  * Creates Result objects for unhandled errors.
  */
-export function createUnhandledErrorResult() {
-    return err({ ...UNHANDLED_ERROR });
+export function createUnhandledErrorResult(actionId, actionName) {
+    const message = actionName
+        ? `An unhandled error occurred in action "${actionName}"`
+        : "An unhandled error occurred";
+    return err({ ...UNHANDLED_ERROR, message }, actionId);
 }
 /**
  * Creates Result objects for implicit return errors.
  */
-export function createImplicitReturnErrorResult() {
-    return err({ ...IMPLICIT_RETURN_ERROR });
+export function createImplicitReturnErrorResult(actionId, actionName) {
+    const message = actionName
+        ? `Action handler "${actionName}" must return a value`
+        : "Action handler must return a value";
+    return err({ ...IMPLICIT_RETURN_ERROR, message }, actionId);
 }
 // ===========================================================================
 // VALIDATION-ERROR STRUCTURING HELPERS
@@ -92,10 +102,13 @@ function _buildNestedValidationError(type, message, formErrors, fieldErrors) {
 /**
  * Creates validation error objects.
  */
-export function createValidationError(type, message, errorStructure) {
+export function createValidationError(type, message, errorStructure, actionName) {
+    const enhancedMessage = actionName
+        ? `${message} in action "${actionName}"`
+        : message;
     if ("issues" in errorStructure) {
-        return _buildFlattenedValidationError(type, message, errorStructure.issues);
+        return _buildFlattenedValidationError(type, enhancedMessage, errorStructure.issues);
     }
-    return _buildNestedValidationError(type, message, errorStructure.formErrors, errorStructure.fieldErrors);
+    return _buildNestedValidationError(type, enhancedMessage, errorStructure.formErrors, errorStructure.fieldErrors);
 }
 //# sourceMappingURL=errors.js.map

package/dist/classes/executor/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../../src/classes/executor/errors.ts"],"names":[],"mappings":"AACA,OAAO,EACL,oBAAoB,EACpB,oBAAoB,GACrB,MAAM,uBAAuB,CAAC;AAS/B,OAAO,EAAE,GAAG,EAAE,MAAM,uBAAuB,CAAC;AAE5C,8EAA8E;AAC9E,YAAY;AACZ,8EAA8E;AAE9E,MAAM,CAAC,MAAM,eAAe,GAAmB;IAC7C,IAAI,EAAE,oBAAoB,CAAC,SAAS;IACpC,OAAO,EAAE,6BAA6B;CAC9B,CAAC;AAEX,MAAM,CAAC,MAAM,qBAAqB,GAAwB;IACxD,IAAI,EAAE,oBAAoB,CAAC,eAAe;IAC1C,OAAO,EAAE,oCAAoC;CACrC,CAAC;AAEX,MAAM,CAAC,MAAM,qBAAqB,GAAuB;IACvD,IAAI,EAAE,iBAAiB;IACvB,OAAO,EAAE,gEAAgE;CACjE,CAAC;AAEX,8EAA8E;AAC9E,kBAAkB;AAClB,8EAA8E;AAE9E;;GAEG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,CACtC,OAAe,EACK,EAAE,CAAC,CAAC;IACxB,IAAI,EAAE,oBAAoB,CAAC,cAAc;IACzC,OAAO;CACR,CAAC,CAAC;AAEH;;GAEG;AACH,MAAM,UAAU,0BAA0B,CAGxC,QAAgB,EAAE,UAAmB;IACrC,MAAM,OAAO,GAAG,UAAU;QACxB,CAAC,CAAC,0CAA0C,UAAU,GAAG;QACzD,CAAC,CAAC,6BAA6B,CAAC;IAElC,OAAO,GAAG,CAAC,EAAE,GAAG,eAAe,EAAE,OAAO,EAAE,EAAE,QAAQ,CAGnD,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,+BAA+B,CAG7C,QAAgB,EAAE,UAAmB;IACrC,MAAM,OAAO,GAAG,UAAU;QACxB,CAAC,CAAC,mBAAmB,UAAU,uBAAuB;QACtD,CAAC,CAAC,oCAAoC,CAAC;IAEzC,OAAO,GAAG,CAAC,EAAE,GAAG,qBAAqB,EAAE,OAAO,EAAE,EAAE,QAAQ,CAGzD,CAAC;AACJ,CAAC;AAED,8EAA8E;AAC9E,uCAAuC;AACvC,8EAA8E;AAE9E;;GAEG;AACH,SAAS,cAAc,CACrB,IAAgE;IAEhE,IAAI,CAAC,IAAI;QAAE,OAAO,EAAE,CAAC;IAErB,OAAO,IAAI;SACR,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE;QACf,IAAI,OAAO,OAAO,KAAK,QAAQ;YAAE,OAAO,SAAS,CAAC;QAElD,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,IAAI,IAAI,KAAK,IAAI,OAAO,EAAE,CAAC;YACxE,MAAM,GAAG,GAAI,OAAwC,CAAC,GAAG,CAAC;YAC1D,OAAO,OAAO,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAE,GAAuB,CAAC;QACxE,CAAC;QAED,OAAO,OAA0B,CAAC;IACpC,CAAC,CAAC;SACD,MAAM,CAAC,CAAC,CAAC,EAAwB,EAAE,CAAC,CAAC,KAAK,SAAS,CAAC,CAAC;AAC1D,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,sBAAsB,CACpC,MAAyC,EACzC,MAA8B;IAE9B,IAAI,MAAM,KAAK,QAAQ,EAAE,CAAC;QACxB,MAAM,UAAU,GAAa,EAAE,CAAC;QAChC,MAAM,WAAW,GAAiC,EAAE,CAAC;QAErD,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;YAC3B,MAAM,WAAW,GAAG,cAAc,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YAE/C,IAAI,WAAW,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBAC7B,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;YACjC,CAAC;iBAAM,CAAC;gBACN,MAAM,OAAO,GAAG,WAAW,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;gBACtC,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC;oBAAE,WAAW,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC;gBACrD,WAAW,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;YAC3C,CAAC;QACH,CAAC;QACD,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,CAAC;IACrC,CAAC;IAED,yBAAyB;IACzB,OAAO;QACL,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC,CAAC;YACzC,IAAI,EAAE,cAAc,CAAC,IAAI,CAAC;YAC1B,OAAO;SACR,CAAC,CAAC;KACJ,CAAC;AACJ,CAAC;AAWD,SAAS,8BAA8B,CACrC,IAAyB,EACzB,OAAe,EACf,MAAwD;IAExD,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAY,CAAC;AAC7C,CAAC;AAED,SAAS,2BAA2B,CAClC,IAAyB,EACzB,OAAe,EACf,UAAoB,EACpB,WAAqC;IAErC,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,UAAU,EAAE,WAAW,EAAY,CAAC;AAC9D,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,qBAAqB,CACnC,IAAyB,EACzB,OAAe,EACf,cAAqC,EACrC,UAAmB;IAEnB,MAAM,eAAe,GAAG,UAAU;QAChC,CAAC,CAAC,GAAG,OAAO,eAAe,UAAU,GAAG;QACxC,CAAC,CAAC,OAAO,CAAC;IAEZ,IAAI,QAAQ,IAAI,cAAc,EAAE,CAAC;QAC/B,OAAO,8BAA8B,CACnC,IAAI,EACJ,eAAe,EACf,cAAc,CAAC,MAAM,CACtB,CAAC;IACJ,CAAC;IAED,OAAO,2BAA2B,CAChC,IAAI,EACJ,eAAe,EACf,cAAc,CAAC,UAAU,EACzB,cAAc,CAAC,WAAW,CAC3B,CAAC;AACJ,CAAC"}

package/dist/classes/executor/executor.d.ts

@@ -0,0 +1,68 @@
+import type { CraftedAction } from "../../types/actions.js";
+import type { Config, Schemas, Errors, Callbacks } from "../../types/builder.js";
+import type { CraftBuilder } from "../craft-builder.js";
+export declare class Executor<TConfig extends Config, TSchemas extends Schemas, TErrors extends Errors, TCallbacks extends Callbacks<TConfig, TSchemas, TErrors, TData>, TData> {
+    private readonly _config;
+    private readonly _schemas;
+    private readonly _errors;
+    private readonly _callbacks;
+    private readonly _handler?;
+    private _actionId?;
+    constructor(builder: CraftBuilder<TConfig, TSchemas, TErrors, TCallbacks, TData>);
+    /**
+     * Builds and returns the final executable server action.
+     */
+    craft(): CraftedAction<TConfig, TSchemas, TErrors, TData>;
+    /**
+     * Generates a unique identifier for this action instance.
+     */
+    private _generateActionId;
+    /**
+     * Orchestrates action execution (validation, business logic, callbacks, and result formatting.)
+     */
+    private _runAction;
+    /**
+     * Extracts bind arguments, previous state, and input from raw action arguments.
+     */
+    private _extractActionArgs;
+    /**
+     * Transforms internal Result objects to client-facing action result format.
+     */
+    private _toActionResult;
+    /**
+     * Handles uncaught exceptions during action execution.
+     */
+    private _handleThrownError;
+    /**
+     * Validates input using the shared helper.
+     */
+    private _validateInput;
+    /**
+     * Validates bound arguments using the configured bind schemas.
+     */
+    private _validateBindArgs;
+    /**
+     * Validates output data using the configured output schema.
+     */
+    private _validateOutput;
+    /**
+     * Validates input data only (used by the $validate method).
+     */
+    private _validateInputOnly;
+    /**
+     * Executes the onStart callback if defined.
+     */
+    private _executeOnStartCallback;
+    /**
+     * Executes result-based lifecycle callbacks (onSuccess, onError, onSettled).
+     */
+    private _executeResultCallbacks;
+    /**
+     * Ensures a Result object has the correct action ID.
+     */
+    private _ensureResultActionId;
+    /**
+     * Creates error functions that return a Result object when called by the action handler.
+     */
+    private _buildErrorFunctions;
+}