@kellanjs/actioncraft/dist/actioncraft.d.ts

Fluent, type-safe builder for Next.js server actions.

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 the onStart callback if defined.
     */
    private _executeOnStartCallback;
    /**
     * Executes result-based lifecycle callbacks (onSuccess, onError, onSettled).
     */
    private _executeResultCallbacks;
    /**
     * 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 {};