@kellanjs/actioncraft 0.1.0 → 0.2.0

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.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Executes a callback function safely.
+ * Any error thrown by the callback is caught and logged (if a logFn is supplied)
+ * so that it never interrupts the main action flow.
+ */
+export declare function safeExecuteCallback(callback: (() => Promise<void> | void) | undefined, callbackName: string, logFn?: (level: "error" | "warn", message: string, details?: unknown) => void): Promise<void>;

package/dist/classes/executor/callbacks.js

@@ -0,0 +1,20 @@
+/**
+ * Executes a callback function safely.
+ * Any error thrown by the callback is caught and logged (if a logFn is supplied)
+ * so that it never interrupts the main action flow.
+ */
+export async function safeExecuteCallback(callback, callbackName, 
+// Logger accepts (level, message, details?)
+logFn) {
+    if (!callback)
+        return;
+    try {
+        await callback();
+    }
+    catch (error) {
+        if (logFn) {
+            logFn("error", `Error in ${callbackName} callback`, error);
+        }
+    }
+}
+//# sourceMappingURL=callbacks.js.map

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/classes/executor/errors.d.ts

@@ -0,0 +1,29 @@
+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.
+ */
+export declare const createInternalLogicError: (message: string) => InternalLogicError;
+/**
+ * Creates Result objects for unhandled errors.
+ */
+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>(actionId: string, actionName?: string): Result<TData, TError>;
+/**
+ * Formats validation issues into structured error objects based on the configured format.
+ */
+export declare function formatValidationIssues(issues: readonly StandardSchemaV1.Issue[], format: "flattened" | "nested"): ValidationErrorFormat;
+type ValidationErrorType = typeof EXTERNAL_ERROR_TYPES.INPUT_VALIDATION | typeof EXTERNAL_ERROR_TYPES.BIND_ARGS_VALIDATION | typeof INTERNAL_ERROR_TYPES.OUTPUT_VALIDATION;
+/**
+ * Creates validation error objects.
+ */
+export declare function createValidationError<TError>(type: ValidationErrorType, message: string, errorStructure: ValidationErrorFormat, actionName?: string): TError;
+export {};

package/dist/classes/executor/errors.js

@@ -0,0 +1,114 @@
+import { EXTERNAL_ERROR_TYPES, INTERNAL_ERROR_TYPES, } from "../../types/errors.js";
+import { err } from "../../types/result.js";
+// ===========================================================================
+// CONSTANTS
+// ===========================================================================
+export const UNHANDLED_ERROR = {
+    type: EXTERNAL_ERROR_TYPES.UNHANDLED,
+    message: "An unhandled error occurred",
+};
+export const IMPLICIT_RETURN_ERROR = {
+    type: INTERNAL_ERROR_TYPES.IMPLICIT_RETURN,
+    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
+// ===========================================================================
+/**
+ * Creates internal logic errors with custom messages.
+ */
+export const createInternalLogicError = (message) => ({
+    type: INTERNAL_ERROR_TYPES.INTERNAL_LOGIC,
+    message,
+});
+/**
+ * Creates Result objects for unhandled errors.
+ */
+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(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
+// ===========================================================================
+/**
+ * Normalises Standard Schema path segments to string|number for serialization.
+ */
+function _normalisePath(path) {
+    if (!path)
+        return [];
+    return path
+        .map((segment) => {
+        if (typeof segment === "symbol")
+            return undefined;
+        if (typeof segment === "object" && segment !== null && "key" in segment) {
+            const key = segment.key;
+            return typeof key === "symbol" ? undefined : key;
+        }
+        return segment;
+    })
+        .filter((p) => p !== undefined);
+}
+/**
+ * Formats validation issues into structured error objects based on the configured format.
+ */
+export function formatValidationIssues(issues, format) {
+    if (format === "nested") {
+        const formErrors = [];
+        const fieldErrors = {};
+        for (const issue of issues) {
+            const currentPath = _normalisePath(issue.path);
+            if (currentPath.length === 0) {
+                formErrors.push(issue.message);
+            }
+            else {
+                const pathKey = currentPath.join(".");
+                if (!fieldErrors[pathKey])
+                    fieldErrors[pathKey] = [];
+                fieldErrors[pathKey].push(issue.message);
+            }
+        }
+        return { formErrors, fieldErrors };
+    }
+    // Default to 'flattened'
+    return {
+        issues: issues.map(({ path, message }) => ({
+            path: _normalisePath(path),
+            message,
+        })),
+    };
+}
+function _buildFlattenedValidationError(type, message, issues) {
+    return { type, message, issues };
+}
+function _buildNestedValidationError(type, message, formErrors, fieldErrors) {
+    return { type, message, formErrors, fieldErrors };
+}
+/**
+ * Creates validation error objects.
+ */
+export function createValidationError(type, message, errorStructure, actionName) {
+    const enhancedMessage = actionName
+        ? `${message} in action "${actionName}"`
+        : message;
+    if ("issues" in errorStructure) {
+        return _buildFlattenedValidationError(type, enhancedMessage, errorStructure.issues);
+    }
+    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":"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"}

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;
+}