@kellanjs/actioncraft 0.1.0 → 0.2.0

package/dist/actioncraft.d.ts

@@ -1,85 +1,135 @@
-import type { ActionImpl, CraftedAction, InferDataFromActionImpl, ActionImplParams } from "./types/actions.js";
-import type { CrafterConfig, CrafterSchemas, CrafterErrors, CrafterCallbacks } from "./types/config.js";
+import type { Handler, CraftedAction, InferDataFromHandler, HandlerParams } from "./types/actions.js";
+import type { CrafterConfig, CrafterSchemas, CrafterErrors, CrafterCallbacks } from "./types/crafter.js";
 import type { InferResult } from "./types/inference.js";
-/**
- * Builder class for creating type-safe server actions with validation, error handling, and callbacks.
- */
+declare const INTERNAL: unique symbol;
 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>);
+    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 CrafterConfig>(config: TNewConfig): Crafter<TNewConfig, TSchemas, TErrors, Record<string, never>, unknown>;
     /**
      * Defines validation schemas for input, output, and bind arguments.
-     * Resets previously defined actions and callbacks.
+     * Resets previously defined handler 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.
+     * Defines error functions for returning typed errors from the handler.
+     * Resets previously defined handler 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.
+     * Defines the handler function containing the server action's 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>>;
+    handler<TFn extends (params: HandlerParams<TConfig, TSchemas, TErrors, TData>) => Promise<unknown>>(fn: TFn): Crafter<TConfig, TSchemas, TErrors, Record<string, never>, InferDataFromHandler<TFn>>;
     /**
-     * Defines lifecycle callbacks for action execution.
-     * Must be called after action() for correct type inference.
+     * Defines lifecycle callbacks to be triggered during the exection of an action.
+     * Must be called after handler() 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.
+     * @returns Internal properties of the Crafter instance
      */
-    private _extractActionArgs;
-    /**
-     * Transforms internal Result objects to client-facing action result format.
-     */
-    private _toActionResult;
-    /**
-     * Handles uncaught exceptions during action execution.
-     */
-    private _handleThrownError;
+    [INTERNAL](): {
+        config: TConfig;
+        schemas: TSchemas;
+        errors: TErrors;
+        callbacks: TCallbacks;
+        handler: Handler<TConfig, TSchemas, TErrors, TData> | undefined;
+    };
+}
+declare class ActionBuilder<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?;
+    constructor(config: TConfig, schemas: TSchemas, errors: TErrors, callbacks: TCallbacks, handler?: Handler<TConfig, TSchemas, TErrors, TData>);
     /**
-     * Validates input using the shared helper.
+     * Defines configuration options for the action.
+     * Resets previously defined handler and callbacks.
      */
-    private _validateInput;
+    config<TNewConfig extends CrafterConfig>(config: TNewConfig): ActionBuilder<TNewConfig, TSchemas, TErrors, Record<string, never>, unknown>;
     /**
-     * Validates bound arguments using the configured bind schemas.
+     * Defines validation schemas for input, output, and bind arguments.
+     * Resets previously defined handler and callbacks.
      */
-    private _validateBindArgs;
+    schemas<TNewSchemas extends CrafterSchemas>(schemas: TNewSchemas): ActionBuilder<TConfig, TNewSchemas, TErrors, Record<string, never>, unknown>;
     /**
-     * Validates output data using the configured output schema.
+     * Defines error functions for returning typed errors from the handler.
+     * Resets previously defined handler and callbacks.
      */
-    private _validateOutput;
+    errors<const TNewErrors extends CrafterErrors>(errors: TNewErrors): ActionBuilder<TConfig, TSchemas, TNewErrors, Record<string, never>, unknown>;
     /**
-     * Executes the onStart callback if defined.
+     * Defines the handler function containing the server action's business logic.
+     * Resets previously defined callbacks.
      */
-    private _executeOnStartCallback;
+    handler<TFn extends (params: HandlerParams<TConfig, TSchemas, TErrors, TData>) => Promise<unknown>>(fn: TFn): ActionBuilder<TConfig, TSchemas, TErrors, Record<string, never>, InferDataFromHandler<TFn>>;
     /**
-     * Executes result-based lifecycle callbacks (onSuccess, onError, onSettled).
+     * Defines lifecycle callbacks to be triggered during the exection of an action.
+     * Must be called after handler() for correct type inference.
      */
-    private _executeResultCallbacks;
+    callbacks<TNewCallbacks extends CrafterCallbacks<TConfig, TSchemas, TErrors, TData>>(callbacks: TNewCallbacks): ActionBuilder<TConfig, TSchemas, TErrors, TNewCallbacks, TData>;
     /**
-     * Creates error functions that return Result objects when called by action implementations.
+     * Builds and returns the final executable server action.
+     * This is the terminal method for the ActionBuilder fluent API.
      */
-    private _buildErrorFunctions;
+    craft(): CraftedAction<TConfig, TSchemas, TErrors, TData>;
 }
 /**
- * Creates a new Crafter instance for building type-safe server actions.
+ * Represents the function that the user passes to `craft()` in order to build an action.
+ */
+type CraftFn<TConfig extends CrafterConfig, TSchemas extends CrafterSchemas, TErrors extends CrafterErrors, TCallbacks extends CrafterCallbacks<TConfig, TSchemas, TErrors, TData>, TData> = (crafter: Crafter<CrafterConfig, Record<string, never>, Record<string, never>, Record<string, never>, unknown>) => Crafter<TConfig, TSchemas, TErrors, TCallbacks, TData> | Promise<Crafter<TConfig, TSchemas, TErrors, TCallbacks, TData>>;
+/**
+ * One of two entry points to the Actioncraft system.
+ * It provides you with an empty Crafter instance on which you can call any of the fluent
+ * Crafter 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 CrafterConfig, TSchemas extends CrafterSchemas, TErrors extends CrafterErrors, TCallbacks extends CrafterCallbacks<TConfig, TSchemas, TErrors, TData>, TData>(craftFn: CraftFn<TConfig, TSchemas, TErrors, TCallbacks, TData>): 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 create<TConfig extends CrafterConfig = CrafterConfig>(config?: TConfig): Crafter<TConfig, Record<string, never>, Record<string, never>, Record<string, never>, unknown>;
+export declare function action(): ActionBuilder<Record<string, never>, Record<string, never>, Record<string, never>, Record<string, never>, unknown>;
 /**
  * Creates an appropriate initial state for any action based on its configuration.
+ * The initial state uses the action's real ID for consistency with actual results.
  *
  * For useActionState actions: returns StatefulApiResult with error and values
  * For functional format actions: returns Result.err() with error