@kellanjs/actioncraft 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Lanny Kenneth Lung
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1 @@
+⚠️ Under Construction

package/dist/actioncraft.d.ts

@@ -0,0 +1,89 @@
+import type { ActionImpl, CraftedAction, InferDataFromActionImpl, ActionImplParams } from "./types/actions.js";
+import type { CrafterConfig, CrafterSchemas, CrafterErrors, CrafterCallbacks } from "./types/config.js";
+import type { InferResult } from "./types/inference.js";
+/**
+ * Builder class for creating type-safe server actions with validation, error handling, and callbacks.
+ */
+declare class Crafter<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 _actionImpl?;
+    constructor(config: TConfig, schemas: TSchemas, errors: TErrors, callbacks: TCallbacks, actionImpl?: ActionImpl<TConfig, TSchemas, TErrors, TData>);
+    /**
+     * Defines validation schemas for input, output, and bind arguments.
+     * Resets previously defined actions and callbacks.
+     */
+    schemas<TNewSchemas extends CrafterSchemas>(schemas: TNewSchemas): Crafter<TConfig, TNewSchemas, TErrors, Record<string, never>, unknown>;
+    /**
+     * Defines error functions for returning typed errors from actions.
+     * Resets previously defined actions and callbacks.
+     */
+    errors<const TNewErrors extends CrafterErrors>(errors: TNewErrors): Crafter<TConfig, TSchemas, TNewErrors, Record<string, never>, unknown>;
+    /**
+     * Defines the action implementation function containing business logic.
+     * Resets previously defined callbacks.
+     */
+    action<TFn extends (params: ActionImplParams<TConfig, TSchemas, TErrors, TData>) => Promise<unknown>>(fn: TFn): Crafter<TConfig, TSchemas, TErrors, Record<string, never>, InferDataFromActionImpl<TFn>>;
+    /**
+     * Defines lifecycle callbacks for action execution.
+     * Must be called after action() for correct type inference.
+     */
+    callbacks<TNewCallbacks extends CrafterCallbacks<TConfig, TSchemas, TErrors, TData>>(callbacks: TNewCallbacks): Crafter<TConfig, TSchemas, TErrors, TNewCallbacks, TData>;
+    /**
+     * Builds and returns the final executable action function.
+     */
+    craft(): CraftedAction<TConfig, TSchemas, TErrors, TData>;
+    /** Orchestrates action execution including 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 appropriate lifecycle callbacks based on the action result.
+     */
+    private _executeCallbacks;
+    /**
+     * Creates error functions that return Result objects when called by action implementations.
+     */
+    private _buildErrorFunctions;
+}
+/**
+ * Creates a new Crafter instance for building type-safe server actions.
+ */
+export declare function create<TConfig extends CrafterConfig = CrafterConfig>(config?: TConfig): Crafter<TConfig, Record<string, never>, Record<string, never>, Record<string, never>, unknown>;
+/**
+ * Creates an appropriate initial state for any action based on its configuration.
+ *
+ * For useActionState actions: returns StatefulApiResult with error and values
+ * For functional format actions: returns Result.err() with error
+ * For regular actions: returns ApiResult with error
+ *
+ * Usage:
+ * - useActionState: const [state, action] = useActionState(myAction, initial(myAction))
+ * - useState: const [state, setState] = useState(initial(myAction))
+ */
+export declare function initial<TAction>(action: TAction): InferResult<TAction>;
+export {};

package/dist/actioncraft.js

@@ -0,0 +1,344 @@
+import { safeExecuteCallback } from "./core/callbacks.js";
+import { createUnhandledErrorResult, createImplicitReturnErrorResult, } from "./core/errors.js";
+import { log } from "./core/logging.js";
+import { serializeRawInput, convertToClientError, } from "./core/transformation.js";
+import { validateInput, validateBindArgs, validateOutput, } from "./core/validation.js";
+import { EXTERNAL_ERROR_TYPES, } from "./types/errors.js";
+import { err, isOk, isResultOk, isResultErr, isErr } from "./types/result.js";
+import { unstable_rethrow } from "next/navigation.js";
+// ============================================================================
+// CRAFTER CLASS - TYPE-SAFE ACTION BUILDER
+// ============================================================================
+/**
+ * Builder class for creating type-safe server actions with validation, error handling, and callbacks.
+ */
+class Crafter {
+    _config;
+    _schemas;
+    _errors;
+    _callbacks;
+    _actionImpl;
+    constructor(config, schemas, errors, callbacks, actionImpl) {
+        this._config = config;
+        this._schemas = schemas;
+        this._errors = errors;
+        this._callbacks = callbacks;
+        this._actionImpl = actionImpl;
+    }
+    // --------------------------------------------------------------------------
+    // FLUENT API METHODS
+    // --------------------------------------------------------------------------
+    /**
+     * Defines validation schemas for input, output, and bind arguments.
+     * Resets previously defined actions and callbacks.
+     */
+    schemas(schemas) {
+        return new Crafter(this._config, schemas, this._errors, {}, undefined);
+    }
+    /**
+     * Defines error functions for returning typed errors from actions.
+     * Resets previously defined actions and callbacks.
+     */
+    errors(errors) {
+        return new Crafter(this._config, this._schemas, errors, {}, undefined);
+    }
+    /**
+     * Defines the action implementation function containing business logic.
+     * Resets previously defined callbacks.
+     */
+    action(fn) {
+        return new Crafter(this._config, this._schemas, this._errors, {}, fn);
+    }
+    /**
+     * Defines lifecycle callbacks for action execution.
+     * Must be called after action() for correct type inference.
+     */
+    callbacks(callbacks) {
+        return new Crafter(this._config, this._schemas, this._errors, callbacks, this._actionImpl);
+    }
+    /**
+     * Builds and returns the final executable action function.
+     */
+    craft() {
+        if (!this._actionImpl) {
+            throw new Error("Action implementation is not defined. Call .action() before calling .craft().");
+        }
+        const craftedAction = (...args) => {
+            return this._runAction(args);
+        };
+        // Attach the action's config for runtime inspection (used by `initial()`)
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        craftedAction.__ac_config = this._config;
+        return craftedAction;
+    }
+    // --------------------------------------------------------------------------
+    // ACTION EXECUTION
+    // --------------------------------------------------------------------------
+    /** Orchestrates action execution including validation, business logic, callbacks, and result formatting. */
+    async _runAction(args) {
+        // We know this exists because craft() verifies it
+        const actionImpl = this._actionImpl;
+        // Extract bindArgs, prevState, and input from the raw args
+        const { bindArgs, prevState, input: rawInput, } = this._extractActionArgs(args);
+        // Check for custom error handler
+        const handleThrownErrorFn = this._config.handleThrownError
+            ? (error) => err(this._config.handleThrownError(error))
+            : null;
+        // Create callback metadata passed to all callbacks
+        const callbackMetadata = {
+            rawInput,
+            prevState,
+            validatedInput: undefined, // Set after validation
+            validatedBindArgs: undefined, // Set after validation
+        };
+        try {
+            // Validate input and return on failure
+            const inputValidation = await this._validateInput(rawInput);
+            if (!isOk(inputValidation)) {
+                await this._executeCallbacks(inputValidation, callbackMetadata);
+                return this._toActionResult(inputValidation, rawInput);
+            }
+            // Update metadata with validated input
+            callbackMetadata.validatedInput = inputValidation.value;
+            // Validate bound arguments and return on failure
+            const bindArgsValidation = await this._validateBindArgs(bindArgs);
+            if (!isOk(bindArgsValidation)) {
+                await this._executeCallbacks(bindArgsValidation, callbackMetadata);
+                return this._toActionResult(bindArgsValidation, rawInput);
+            }
+            // Update metadata with validated bind args
+            callbackMetadata.validatedBindArgs = bindArgsValidation.value;
+            // Execute the user's action implementation
+            const actionImplResult = await actionImpl({
+                input: inputValidation.value,
+                bindArgs: bindArgsValidation.value,
+                errors: this._buildErrorFunctions(),
+                metadata: { rawInput, prevState },
+            });
+            // Return on `undefined` (implicit return error)
+            if (actionImplResult === undefined) {
+                const implicitReturnError = createImplicitReturnErrorResult();
+                await this._executeCallbacks(implicitReturnError, callbackMetadata);
+                return this._toActionResult(implicitReturnError, rawInput);
+            }
+            let finalResult;
+            // Process different return types from the action
+            if (isResultErr(actionImplResult)) {
+                finalResult = actionImplResult;
+            }
+            else {
+                const outputData = isResultOk(actionImplResult)
+                    ? actionImplResult.value
+                    : actionImplResult;
+                finalResult = await this._validateOutput(outputData);
+            }
+            // Execute callbacks and return final result
+            await this._executeCallbacks(finalResult, callbackMetadata);
+            // 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._executeCallbacks(errorResult, callbackMetadata);
+                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(), 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],
+            };
+        }
+        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));
+        // 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,
+                };
+            }
+            return {
+                success: false,
+                error: clientResult.error,
+                values: serializeRawInput(inputForValues),
+            };
+        }
+        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,
+            };
+        }
+        return {
+            success: false,
+            error: clientResult.error,
+        };
+    }
+    // --------------------------------------------------------------------------
+    // ERROR HANDLING
+    // --------------------------------------------------------------------------
+    /**
+     * Handles uncaught exceptions during action execution.
+     */
+    _handleThrownError(error, customHandler) {
+        const caughtErrorResult = customHandler
+            ? customHandler(error)
+            : createUnhandledErrorResult();
+        return caughtErrorResult;
+    }
+    // --------------------------------------------------------------------------
+    // VALIDATION
+    // --------------------------------------------------------------------------
+    /**
+     * Validates input using the shared helper.
+     */
+    _validateInput(rawInput) {
+        return validateInput(this._schemas, this._config, rawInput);
+    }
+    /**
+     * Validates bound arguments using the configured bind schemas.
+     */
+    _validateBindArgs(bindArgs) {
+        return validateBindArgs(this._schemas, this._config, bindArgs);
+    }
+    /**
+     * Validates output data using the configured output schema.
+     */
+    _validateOutput(data) {
+        return validateOutput(this._schemas, this._config, data);
+    }
+    // --------------------------------------------------------------------------
+    // CALLBACKS
+    // --------------------------------------------------------------------------
+    /**
+     * Executes appropriate lifecycle callbacks based on the action result.
+     */
+    async _executeCallbacks(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
+    // --------------------------------------------------------------------------
+    /**
+     * Creates error functions that return Result objects when called by action implementations.
+     */
+    _buildErrorFunctions() {
+        const errorFns = {};
+        for (const [key, errorDefFn] of Object.entries(this._errors)) {
+            errorFns[key] = ((...args) => err(errorDefFn(...args)));
+        }
+        return errorFns;
+    }
+}
+// ============================================================================
+// PUBLIC API EXPORTS
+// ============================================================================
+/**
+ * Creates a new Crafter instance for building type-safe server actions.
+ */
+export function create(config) {
+    return new Crafter(config ?? {}, {}, {}, {}, undefined);
+}
+/**
+ * Creates an appropriate initial state for any action based on its configuration.
+ *
+ * For useActionState actions: returns StatefulApiResult with error and values
+ * For functional format actions: returns Result.err() with error
+ * For regular actions: returns ApiResult with error
+ *
+ * Usage:
+ * - useActionState: const [state, action] = useActionState(myAction, initial(myAction))
+ * - useState: const [state, setState] = useState(initial(myAction))
+ */
+export function initial(action) {
+    const error = {
+        type: EXTERNAL_ERROR_TYPES.INITIAL_STATE,
+        message: "No action has been executed yet",
+    };
+    // Attempt to read the ActionCraft config attached during craft()
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const cfg = action?.__ac_config;
+    // Functional format -> Result<_, _>
+    if (cfg?.resultFormat === "functional") {
+        return err(error);
+    }
+    // useActionState enabled -> StatefulApiResult
+    if (cfg?.useActionState) {
+        return {
+            success: false,
+            error,
+            values: undefined,
+        };
+    }
+    // Default ApiResult shape
+    return {
+        success: false,
+        error,
+    };
+}
+//# sourceMappingURL=actioncraft.js.map

package/dist/actioncraft.js.map

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

package/dist/core/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/core/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/core/callbacks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"callbacks.js","sourceRoot":"","sources":["../../src/core/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/errors.d.ts

@@ -0,0 +1,28 @@
+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";
+export declare const UNHANDLED_ERROR: UnhandledError;
+export declare const IMPLICIT_RETURN_ERROR: ImplicitReturnError;
+/**
+ * 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>(): Result<TData, TError>;
+/**
+ * Creates Result objects for implicit return errors.
+ */
+export declare function createImplicitReturnErrorResult<TData = never, TError = ImplicitReturnError>(): 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): TError;
+export {};

package/dist/core/errors.js

@@ -0,0 +1,101 @@
+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 implementation must return a value",
+};
+// ===========================================================================
+// 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() {
+    return err({ ...UNHANDLED_ERROR });
+}
+/**
+ * Creates Result objects for implicit return errors.
+ */
+export function createImplicitReturnErrorResult() {
+    return err({ ...IMPLICIT_RETURN_ERROR });
+}
+// ===========================================================================
+// 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) {
+    if ("issues" in errorStructure) {
+        return _buildFlattenedValidationError(type, message, errorStructure.issues);
+    }
+    return _buildNestedValidationError(type, message, errorStructure.formErrors, errorStructure.fieldErrors);
+}
+//# sourceMappingURL=errors.js.map

package/dist/core/errors.js.map

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

package/dist/core/logging.d.ts

@@ -0,0 +1,6 @@
+import type { CrafterConfig } from "../types/config.js";
+/**
+ * Lightweight wrapper around the optional logger in `CrafterConfig`.
+ */
+export type Logger = NonNullable<CrafterConfig["logger"]>;
+export declare function log(logger: CrafterConfig["logger"], level: "error" | "warn", message: string, details?: unknown): void;

package/dist/core/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