@kellanjs/actioncraft 0.0.2 → 0.2.0

package/dist/classes/executor/executor.js

@@ -0,0 +1,391 @@
+import {} from "../../types/errors.js";
+import { err, isOk, isResultOk, isResultErr, isErr, } from "../../types/result.js";
+import { INTERNAL } from "../internal.js";
+import { safeExecuteCallback } from "./callbacks.js";
+import { createUnhandledErrorResult, createImplicitReturnErrorResult, NO_INPUT_SCHEMA_ERROR, } from "./errors.js";
+import { log } from "./logging.js";
+import { serializeRawInput, convertToClientError } from "./transformation.js";
+import { validateInput, validateBindArgs, validateOutput, } from "./validation.js";
+import { unstable_rethrow } from "next/navigation.js";
+// ============================================================================
+// EXECUTOR CLASS - Build and execute your action
+// ============================================================================
+export class Executor {
+    _config;
+    _schemas;
+    _errors;
+    _callbacks;
+    _handler;
+    _actionId;
+    constructor(builder) {
+        this._config = builder[INTERNAL]().config;
+        this._schemas = builder[INTERNAL]().schemas;
+        this._errors = builder[INTERNAL]().errors;
+        this._callbacks = builder[INTERNAL]().callbacks;
+        this._handler = builder[INTERNAL]().handler;
+    }
+    /**
+     * Builds and returns the final executable server action.
+     */
+    craft() {
+        if (!this._handler) {
+            throw new Error("A handler implementation is required");
+        }
+        // Generate a unique ID for this action instance
+        this._actionId = this._generateActionId();
+        const craftedAction = (...args) => {
+            return this._runAction(args);
+        };
+        // Attach $validate method to the action for simple client-side validation
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        craftedAction.$validate = async (input) => {
+            return this._validateInputOnly(input);
+        };
+        // Attach the action's config and ID for runtime inspection
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        craftedAction.__ac_config = this._config;
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        craftedAction.__ac_id = this._actionId;
+        return craftedAction;
+    }
+    /**
+     * Generates a unique identifier for this action instance.
+     */
+    _generateActionId() {
+        return crypto.randomUUID();
+    }
+    // --------------------------------------------------------------------------
+    // ACTION EXECUTION
+    // --------------------------------------------------------------------------
+    /**
+     * Orchestrates action execution (validation, business logic, callbacks, and result formatting.)
+     */
+    async _runAction(args) {
+        // We know these exist because craft() creates/verifies them
+        const handler = this._handler;
+        const actionId = this._actionId;
+        const actionName = this._config.actionName;
+        // Extract bindArgs, prevState, and input from the raw args
+        const { bindArgs: rawBindArgs, prevState, input: rawInput, } = this._extractActionArgs(args);
+        // Check for custom error handler
+        const handleThrownErrorFn = this._config.handleThrownError
+            ? (error) => err(this._config.handleThrownError(error), actionId)
+            : null;
+        // Track validation state for error handling
+        let validatedInput = undefined;
+        let validatedBindArgs = undefined;
+        try {
+            // Execute onStart callback before any processing
+            await this._executeOnStartCallback({
+                actionId,
+                actionName,
+                rawInput,
+                rawBindArgs,
+                prevState,
+                validatedInput: undefined,
+                validatedBindArgs: undefined,
+            });
+            // Validate input and return on failure
+            const inputValidation = await this._validateInput(rawInput);
+            if (!isOk(inputValidation)) {
+                await this._executeResultCallbacks(inputValidation, {
+                    actionId,
+                    actionName,
+                    rawInput,
+                    rawBindArgs,
+                    prevState,
+                    validatedInput,
+                    validatedBindArgs,
+                });
+                return this._toActionResult(inputValidation, rawInput);
+            }
+            // Update validation state
+            validatedInput = inputValidation.value;
+            // Validate bound arguments and return on failure
+            const bindArgsValidation = await this._validateBindArgs(rawBindArgs);
+            if (!isOk(bindArgsValidation)) {
+                await this._executeResultCallbacks(bindArgsValidation, {
+                    actionId,
+                    actionName,
+                    rawInput,
+                    rawBindArgs,
+                    prevState,
+                    validatedInput,
+                    validatedBindArgs,
+                });
+                return this._toActionResult(bindArgsValidation, rawInput);
+            }
+            // Update validation state
+            validatedBindArgs = bindArgsValidation.value;
+            // Execute the user's action handler
+            const handlerResult = await handler({
+                input: inputValidation.value,
+                bindArgs: bindArgsValidation.value,
+                errors: this._buildErrorFunctions(),
+                metadata: {
+                    actionId,
+                    actionName,
+                    rawInput,
+                    rawBindArgs,
+                    prevState,
+                },
+            });
+            // Return on `undefined` (implicit return error)
+            if (handlerResult === undefined) {
+                const implicitReturnError = createImplicitReturnErrorResult(actionId, actionName);
+                await this._executeResultCallbacks(implicitReturnError, {
+                    actionId,
+                    actionName,
+                    rawInput,
+                    rawBindArgs,
+                    prevState,
+                    validatedInput,
+                    validatedBindArgs,
+                });
+                return this._toActionResult(implicitReturnError, rawInput);
+            }
+            let finalResult;
+            // Process different return types from the action
+            if (isResultErr(handlerResult)) {
+                // Ensure error result has correct action ID
+                finalResult = this._ensureResultActionId(handlerResult);
+            }
+            else {
+                const outputData = isResultOk(handlerResult)
+                    ? handlerResult.value
+                    : handlerResult;
+                finalResult = await this._validateOutput(outputData);
+            }
+            // Execute callbacks and return final result
+            await this._executeResultCallbacks(finalResult, {
+                actionId,
+                actionName,
+                rawInput,
+                rawBindArgs,
+                prevState,
+                validatedInput,
+                validatedBindArgs,
+            });
+            // Use validated input for the values field on a successful run
+            const inputForValues = isOk(finalResult)
+                ? this._schemas.inputSchema
+                    ? inputValidation.value
+                    : rawInput
+                : rawInput;
+            return this._toActionResult(finalResult, inputForValues);
+        }
+        catch (error) {
+            // Re-throw Next.js framework errors
+            unstable_rethrow(error);
+            // Handle unexpected thrown errors
+            try {
+                const errorResult = this._handleThrownError(error, handleThrownErrorFn);
+                await this._executeResultCallbacks(errorResult, {
+                    actionId,
+                    actionName,
+                    rawInput,
+                    rawBindArgs,
+                    prevState,
+                    validatedInput,
+                    validatedBindArgs,
+                });
+                return this._toActionResult(errorResult, rawInput);
+            }
+            catch (handlerError) {
+                // If we catch another error here, then we're done
+                log(this._config.logger, "warn", "Error handling failure - both primary error and error handler threw", { primaryError: error, handlerError });
+                return this._toActionResult(createUnhandledErrorResult(actionId, actionName), rawInput);
+            }
+        }
+    }
+    /**
+     * Extracts bind arguments, previous state, and input from raw action arguments.
+     */
+    _extractActionArgs(args) {
+        const numBindSchemas = this._schemas.bindSchemas?.length ?? 0;
+        if (this._config.useActionState) {
+            return {
+                bindArgs: args.slice(0, numBindSchemas),
+                prevState: args[numBindSchemas],
+                input: args[numBindSchemas + 1],
+            };
+        }
+        // For regular actions (non-useActionState), the input is the first argument after bind args
+        // If there are no bind schemas, the input is the first argument (args[0])
+        return {
+            bindArgs: args.slice(0, numBindSchemas),
+            // When useActionState is disabled the prevState parameter is never
+            // present, so we cast to never (or undefined) to satisfy the type.
+            prevState: undefined,
+            input: args[numBindSchemas],
+        };
+    }
+    // --------------------------------------------------------------------------
+    // RESULT TRANSFORMATION
+    // --------------------------------------------------------------------------
+    /**
+     * Transforms internal Result objects to client-facing action result format.
+     */
+    _toActionResult(result, inputForValues) {
+        // Convert internal errors to client-facing errors
+        const clientResult = isOk(result)
+            ? result
+            : err(convertToClientError(result.error), this._actionId);
+        // Handle useActionState format (always returns StatefulApiResult)
+        if (this._config.useActionState) {
+            if (isOk(clientResult)) {
+                const successValues = this._schemas.inputSchema
+                    ? inputForValues
+                    : serializeRawInput(inputForValues);
+                return {
+                    success: true,
+                    data: clientResult.value,
+                    values: successValues,
+                    __ac_id: this._actionId,
+                };
+            }
+            return {
+                success: false,
+                error: clientResult.error,
+                values: serializeRawInput(inputForValues),
+                __ac_id: this._actionId,
+            };
+        }
+        const format = this._config.resultFormat ?? "api";
+        // Return functional format if configured
+        if (format === "functional") {
+            return clientResult;
+        }
+        // Default API format
+        if (isOk(clientResult)) {
+            return {
+                success: true,
+                data: clientResult.value,
+                __ac_id: this._actionId,
+            };
+        }
+        return {
+            success: false,
+            error: clientResult.error,
+            __ac_id: this._actionId,
+        };
+    }
+    // --------------------------------------------------------------------------
+    // ERROR HANDLING
+    // --------------------------------------------------------------------------
+    /**
+     * Handles uncaught exceptions during action execution.
+     */
+    _handleThrownError(error, customHandler) {
+        const caughtErrorResult = customHandler
+            ? customHandler(error)
+            : createUnhandledErrorResult(this._actionId, this._config.actionName);
+        return caughtErrorResult;
+    }
+    // --------------------------------------------------------------------------
+    // VALIDATION
+    // --------------------------------------------------------------------------
+    /**
+     * Validates input using the shared helper.
+     */
+    _validateInput(rawInput) {
+        return validateInput(this._schemas, this._config, rawInput, this._actionId, this._config.actionName);
+    }
+    /**
+     * Validates bound arguments using the configured bind schemas.
+     */
+    _validateBindArgs(bindArgs) {
+        return validateBindArgs(this._schemas, this._config, bindArgs, this._actionId, this._config.actionName);
+    }
+    /**
+     * Validates output data using the configured output schema.
+     */
+    _validateOutput(data) {
+        return validateOutput(this._schemas, this._config, data, this._actionId, this._config.actionName);
+    }
+    /**
+     * Validates input data only (used by the $validate method).
+     */
+    async _validateInputOnly(input) {
+        // If no input schema, return error indicating validation cannot be performed
+        if (!this._schemas.inputSchema) {
+            return {
+                success: false,
+                error: NO_INPUT_SCHEMA_ERROR,
+            };
+        }
+        const validationResult = await this._validateInput(input);
+        if (isOk(validationResult)) {
+            return {
+                success: true,
+                data: validationResult.value,
+            };
+        }
+        else {
+            // Convert internal error to client-facing error
+            const clientError = convertToClientError(validationResult.error);
+            return { success: false, error: clientError };
+        }
+    }
+    // --------------------------------------------------------------------------
+    // CALLBACKS
+    // --------------------------------------------------------------------------
+    /**
+     * Executes the onStart callback if defined.
+     */
+    async _executeOnStartCallback(metadata) {
+        const callbacks = this._callbacks;
+        if (callbacks.onStart) {
+            await safeExecuteCallback(() => callbacks.onStart({ metadata }), "onStart", (level, msg, details) => log(this._config.logger, level, msg, details));
+        }
+    }
+    /**
+     * Executes result-based lifecycle callbacks (onSuccess, onError, onSettled).
+     */
+    async _executeResultCallbacks(result, metadata) {
+        const callbacks = this._callbacks;
+        // Success path
+        if (isOk(result)) {
+            await safeExecuteCallback(callbacks.onSuccess
+                ? () => callbacks.onSuccess({ data: result.value, metadata })
+                : undefined, "onSuccess", (level, msg, details) => log(this._config.logger, level, msg, details));
+        }
+        // Error path
+        if (isErr(result)) {
+            await safeExecuteCallback(callbacks.onError
+                ? () => callbacks.onError({ error: result.error, metadata })
+                : undefined, "onError", (level, msg, details) => log(this._config.logger, level, msg, details));
+        }
+        // onSettled always runs, regardless of result
+        const finalResult = this._toActionResult(result);
+        await safeExecuteCallback(callbacks.onSettled
+            ? () => callbacks.onSettled({ result: finalResult, metadata })
+            : undefined, "onSettled", (level, msg, details) => log(this._config.logger, level, msg, details));
+    }
+    // --------------------------------------------------------------------------
+    // UTILITY METHODS
+    // --------------------------------------------------------------------------
+    /**
+     * Ensures a Result object has the correct action ID.
+     */
+    _ensureResultActionId(result) {
+        if (!result.__ac_id || result.__ac_id === "unknown") {
+            return {
+                ...result,
+                __ac_id: this._actionId,
+            };
+        }
+        return result;
+    }
+    /**
+     * Creates error functions that return a Result object when called by the action handler.
+     */
+    _buildErrorFunctions() {
+        const errorFns = {};
+        for (const [key, errorDefFn] of Object.entries(this._errors)) {
+            errorFns[key] = ((...args) => err(errorDefFn(...args), this._actionId));
+        }
+        return errorFns;
+    }
+}
+//# sourceMappingURL=executor.js.map

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

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

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

@@ -0,0 +1,2 @@
+import type { Config } from "../../types/builder.js";
+export declare function log(logger: Config["logger"], level: "error" | "warn", message: string, details?: unknown): void;

package/dist/classes/executor/logging.js

@@ -0,0 +1,8 @@
+export function log(logger, level, message, details) {
+    if (!logger)
+        return;
+    const fn = logger[level];
+    if (fn)
+        fn(message, details);
+}
+//# sourceMappingURL=logging.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"logging.js","sourceRoot":"","sources":["../../../src/classes/executor/logging.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,GAAG,CACjB,MAAwB,EACxB,KAAuB,EACvB,OAAe,EACf,OAAiB;IAEjB,IAAI,CAAC,MAAM;QAAE,OAAO;IACpB,MAAM,EAAE,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;IACzB,IAAI,EAAE;QAAE,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;AAC/B,CAAC"}

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

@@ -0,0 +1,17 @@
+import type { InferSerializedErrorValues } from "../../types/actions.js";
+import type { Schemas } from "../../types/builder.js";
+import type { Config, Errors } from "../../types/builder.js";
+import type { PossibleErrors, AllPossibleErrors } from "../../types/errors.js";
+import type { InferRawInput, InferValidatedInput } from "../../types/schemas.js";
+/**
+ * Converts input to a serializable format for the `values` field in action results.
+ *
+ * If the input is `FormData`, it is flattened into a plain object so that it can
+ * be safely JSON-serialized. Otherwise, the input is returned as-is.
+ */
+export declare function serializeRawInput<TSchemas extends Schemas>(input: InferRawInput<TSchemas> | InferValidatedInput<TSchemas> | undefined): InferSerializedErrorValues<TSchemas>;
+/**
+ * Converts internal error objects into client-facing errors, hiding
+ * implementation details that should not leak outside the server.
+ */
+export declare function convertToClientError<TErrors extends Errors, TConfig extends Config, TSchemas extends Schemas>(internalError: AllPossibleErrors<TErrors, TConfig, TSchemas>): PossibleErrors<TErrors, TConfig, TSchemas>;

package/dist/classes/executor/transformation.js

@@ -0,0 +1,43 @@
+import { INTERNAL_ERROR_TYPES } from "../../types/errors.js";
+import { UNHANDLED_ERROR } from "./errors.js";
+/**
+ * Converts input to a serializable format for the `values` field in action results.
+ *
+ * If the input is `FormData`, it is flattened into a plain object so that it can
+ * be safely JSON-serialized. Otherwise, the input is returned as-is.
+ */
+export function serializeRawInput(input) {
+    if (input instanceof FormData) {
+        const valueMap = new Map();
+        for (const [key, value] of input.entries()) {
+            // Ignore React server-action meta-fields
+            if (key.startsWith("$ACTION"))
+                continue;
+            const stringValue = typeof value === "string" ? value : value.name || "[File]";
+            if (!valueMap.has(key))
+                valueMap.set(key, []);
+            valueMap.get(key).push(stringValue);
+        }
+        // Collapse single-item arrays
+        const serialized = {};
+        for (const [key, values] of valueMap.entries()) {
+            serialized[key] = values.length === 1 ? values[0] : values;
+        }
+        return serialized;
+    }
+    // Non-FormData inputs are assumed to already be serialisable
+    return input;
+}
+/**
+ * Converts internal error objects into client-facing errors, hiding
+ * implementation details that should not leak outside the server.
+ */
+export function convertToClientError(internalError) {
+    if (internalError.type === INTERNAL_ERROR_TYPES.IMPLICIT_RETURN ||
+        internalError.type === INTERNAL_ERROR_TYPES.OUTPUT_VALIDATION ||
+        internalError.type === INTERNAL_ERROR_TYPES.INTERNAL_LOGIC) {
+        return UNHANDLED_ERROR;
+    }
+    return internalError;
+}
+//# sourceMappingURL=transformation.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"transformation.js","sourceRoot":"","sources":["../../../src/classes/executor/transformation.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAK7D,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE9C;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAC/B,KAA0E;IAE1E,IAAI,KAAK,YAAY,QAAQ,EAAE,CAAC;QAC9B,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAoB,CAAC;QAE7C,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,KAAK,CAAC,OAAO,EAAE,EAAE,CAAC;YAC3C,yCAAyC;YACzC,IAAI,GAAG,CAAC,UAAU,CAAC,SAAS,CAAC;gBAAE,SAAS;YAExC,MAAM,WAAW,GACf,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,IAAI,QAAQ,CAAC;YAE7D,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC;gBAAE,QAAQ,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;YAC9C,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAE,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;QACvC,CAAC;QAED,8BAA8B;QAC9B,MAAM,UAAU,GAAsC,EAAE,CAAC;QACzD,KAAK,MAAM,CAAC,GAAG,EAAE,MAAM,CAAC,IAAI,QAAQ,CAAC,OAAO,EAAE,EAAE,CAAC;YAC/C,UAAU,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAE,CAAC,CAAC,CAAC,MAAM,CAAC;QAC9D,CAAC;QAED,OAAO,UAAkD,CAAC;IAC5D,CAAC;IAED,6DAA6D;IAC7D,OAAO,KAA6C,CAAC;AACvD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,oBAAoB,CAKlC,aAA4D;IAE5D,IACE,aAAa,CAAC,IAAI,KAAK,oBAAoB,CAAC,eAAe;QAC3D,aAAa,CAAC,IAAI,KAAK,oBAAoB,CAAC,iBAAiB;QAC7D,aAAa,CAAC,IAAI,KAAK,oBAAoB,CAAC,cAAc,EAC1D,CAAC;QACD,OAAO,eAA6D,CAAC;IACvE,CAAC;IACD,OAAO,aAA2D,CAAC;AACrE,CAAC"}

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

@@ -0,0 +1,16 @@
+import type { Config, Schemas, Errors } from "../../types/builder.js";
+import type { AllPossibleErrors } from "../../types/errors.js";
+import type { Result } from "../../types/result.js";
+import type { InferValidatedInput, InferRawInput, InferValidatedBindArgs, InferRawBindArgs } from "../../types/schemas.js";
+/**
+ * Validate input using the configured input schema.
+ */
+export declare function validateInput<TConfig extends Config, TSchemas extends Schemas, TErrors extends Errors>(schemas: TSchemas, config: TConfig, rawInput: InferRawInput<TSchemas> | undefined, actionId: string, actionName?: string): Promise<Result<InferValidatedInput<TSchemas>, AllPossibleErrors<TErrors, TConfig, TSchemas>>>;
+/**
+ * Validate bound arguments using configured bind schemas.
+ */
+export declare function validateBindArgs<TConfig extends Config, TSchemas extends Schemas, TErrors extends Errors>(schemas: TSchemas, config: TConfig, bindArgs: InferRawBindArgs<TSchemas>, actionId: string, actionName?: string): Promise<Result<InferValidatedBindArgs<TSchemas>, AllPossibleErrors<TErrors, TConfig, TSchemas>>>;
+/**
+ * Validate action output using configured output schema.
+ */
+export declare function validateOutput<TConfig extends Config, TSchemas extends Schemas, TErrors extends Errors, TData>(schemas: TSchemas, config: TConfig, data: TData, actionId: string, actionName?: string): Promise<Result<TData, AllPossibleErrors<TErrors, TConfig, TSchemas>>>;

package/dist/classes/executor/validation.js

@@ -0,0 +1,70 @@
+import { standardParse } from "../../standard-schema.js";
+import { INTERNAL_ERROR_TYPES, EXTERNAL_ERROR_TYPES, } from "../../types/errors.js";
+import { ok, err } from "../../types/result.js";
+import { createValidationError, createInternalLogicError, formatValidationIssues, } from "./errors.js";
+/**
+ * Validate input using the configured input schema.
+ */
+export async function validateInput(schemas, config, rawInput, actionId, actionName) {
+    if (!schemas.inputSchema) {
+        return ok(undefined, actionId);
+    }
+    const result = await standardParse(schemas.inputSchema, rawInput);
+    if (Array.isArray(result.issues) && result.issues.length > 0) {
+        const format = config.validationErrorFormat ?? "flattened";
+        const baseError = formatValidationIssues(result.issues, format);
+        const inputValidationError = createValidationError(EXTERNAL_ERROR_TYPES.INPUT_VALIDATION, "Input validation failed", baseError, actionName);
+        return err(inputValidationError, actionId);
+    }
+    if (!result.issues && "value" in result) {
+        return ok(result.value, actionId);
+    }
+    // Should never happen
+    const logicErr = createInternalLogicError("Unexpected validation state in input validation: neither success nor failure");
+    return err(logicErr, actionId);
+}
+/**
+ * Validate bound arguments using configured bind schemas.
+ */
+export async function validateBindArgs(schemas, config, bindArgs, actionId, actionName) {
+    if (!schemas.bindSchemas) {
+        return ok([], actionId);
+    }
+    const validated = [];
+    for (let i = 0; i < schemas.bindSchemas.length; i++) {
+        const schema = schemas.bindSchemas[i];
+        const arg = bindArgs[i];
+        const result = await standardParse(schema, arg);
+        if (Array.isArray(result.issues) && result.issues.length > 0) {
+            const format = config.validationErrorFormat ?? "flattened";
+            const baseError = formatValidationIssues(result.issues, format);
+            const bindError = createValidationError(EXTERNAL_ERROR_TYPES.BIND_ARGS_VALIDATION, "Bind arguments validation failed", baseError, actionName);
+            return err(bindError, actionId);
+        }
+        if ("value" in result) {
+            validated.push(result.value);
+        }
+    }
+    return ok(validated, actionId);
+}
+/**
+ * Validate action output using configured output schema.
+ */
+export async function validateOutput(schemas, config, data, actionId, actionName) {
+    if (!schemas.outputSchema) {
+        return ok(data, actionId);
+    }
+    const result = await standardParse(schemas.outputSchema, data);
+    if (Array.isArray(result.issues) && result.issues.length > 0) {
+        const format = config.validationErrorFormat ?? "flattened";
+        const baseError = formatValidationIssues(result.issues, format);
+        const outputError = createValidationError(INTERNAL_ERROR_TYPES.OUTPUT_VALIDATION, "Output validation failed", baseError, actionName);
+        return err(outputError, actionId);
+    }
+    if (!result.issues && "value" in result) {
+        return ok(result.value, actionId);
+    }
+    const logicErr = createInternalLogicError("Unexpected validation state in output validation: neither success nor failure");
+    return err(logicErr, actionId);
+}
+//# sourceMappingURL=validation.js.map

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

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

package/dist/classes/executor.d.ts

@@ -0,0 +1,64 @@
+import type { CraftedAction } from "../types/actions.js";
+import type { CrafterConfig, CrafterSchemas, CrafterErrors, CrafterCallbacks } from "../types/crafter.js";
+import type { Crafter } from "./crafter.js";
+export declare class Executor<TConfig extends CrafterConfig, TSchemas extends CrafterSchemas, TErrors extends CrafterErrors, TCallbacks extends CrafterCallbacks<TConfig, TSchemas, TErrors, TData>, TData> {
+    private readonly _config;
+    private readonly _schemas;
+    private readonly _errors;
+    private readonly _callbacks;
+    private readonly _handler?;
+    private _actionId?;
+    constructor(crafter: Crafter<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;
+    /**
+     * 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;
+}