@kellanjs/actioncraft 0.1.0 → 0.2.0

package/dist/craft.js

@@ -0,0 +1,62 @@
+import { Crafter } from "./classes/crafter.js";
+import { Executor } from "./classes/executor.js";
+/**
+ * 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 function craft(craftFn) {
+    const crafter = craftFn(new Crafter({}, {}, {}, {}, undefined));
+    // Handle async crafter functions
+    if (crafter instanceof Promise) {
+        return _craftAsync(crafter);
+    }
+    // Handle sync crafter functions
+    const executor = new Executor(crafter);
+    const craftedAction = executor.craft();
+    return craftedAction;
+}
+/**
+ * Internal helper function to handle async craft functions.
+ * Encapsulates the logic for creating async actions and preserving metadata.
+ */
+function _craftAsync(crafterPromise) {
+    // Resolve the crafter once and cache the resulting action to ensure consistent IDs
+    const actionPromise = crafterPromise.then((resolvedCrafter) => {
+        const executor = new Executor(resolvedCrafter);
+        return executor.craft();
+    });
+    // For async craft functions, we need to return an async action
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const asyncAction = (async (...args) => {
+        // Wait for the cached action to be ready
+        const craftedAction = await actionPromise;
+        // Call the action with the user's arguments
+        return craftedAction(...args);
+    });
+    // We need to preserve the config and ID for the initial() function to work
+    // We'll use the same cached action to ensure consistent metadata
+    actionPromise.then((craftedAction) => {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        asyncAction.__ac_config = craftedAction.__ac_config;
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        asyncAction.__ac_id = craftedAction.__ac_id;
+    });
+    return asyncAction;
+}
+//# sourceMappingURL=craft.js.map

package/dist/craft.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"craft.js","sourceRoot":"","sources":["../src/craft.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAC/C,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAkCjD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,KAAK,CAOnB,OAA+D;IAE/D,MAAM,OAAO,GAAG,OAAO,CACrB,IAAI,OAAO,CACT,EAAmB,EACnB,EAA2B,EAC3B,EAA2B,EAC3B,EAA2B,EAC3B,SAAS,CACV,CACF,CAAC;IAEF,iCAAiC;IACjC,IAAI,OAAO,YAAY,OAAO,EAAE,CAAC;QAC/B,OAAO,WAAW,CAAC,OAAO,CAAC,CAAC;IAC9B,CAAC;IAED,gCAAgC;IAChC,MAAM,QAAQ,GAAG,IAAI,QAAQ,CAAC,OAAO,CAAC,CAAC;IACvC,MAAM,aAAa,GAAG,QAAQ,CAAC,KAAK,EAAE,CAAC;IAEvC,OAAO,aAAa,CAAC;AACvB,CAAC;AAED;;;GAGG;AACH,SAAS,WAAW,CAOlB,cAEC;IAED,mFAAmF;IACnF,MAAM,aAAa,GAAG,cAAc,CAAC,IAAI,CAAC,CAAC,eAAe,EAAE,EAAE;QAC5D,MAAM,QAAQ,GAAG,IAAI,QAAQ,CAAC,eAAe,CAAC,CAAC;QAC/C,OAAO,QAAQ,CAAC,KAAK,EAAE,CAAC;IAC1B,CAAC,CAAC,CAAC;IAEH,+DAA+D;IAC/D,8DAA8D;IAC9D,MAAM,WAAW,GAAG,CAAC,KAAK,EAAE,GAAG,IAAW,EAAE,EAAE;QAC5C,yCAAyC;QACzC,MAAM,aAAa,GAAG,MAAM,aAAa,CAAC;QAE1C,4CAA4C;QAC5C,OAAO,aAAa,CAAC,GAAG,IAAI,CAAC,CAAC;IAChC,CAAC,CAAqD,CAAC;IAEvD,2EAA2E;IAC3E,iEAAiE;IACjE,aAAa,CAAC,IAAI,CAAC,CAAC,aAAa,EAAE,EAAE;QACnC,8DAA8D;QAC7D,WAAmB,CAAC,WAAW,GAAI,aAAqB,CAAC,WAAW,CAAC;QACtE,8DAA8D;QAC7D,WAAmB,CAAC,OAAO,GAAI,aAAqB,CAAC,OAAO,CAAC;IAChE,CAAC,CAAC,CAAC;IAEH,OAAO,WAAW,CAAC;AACrB,CAAC"}

package/dist/error.d.ts

@@ -3,14 +3,29 @@ 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.
+ * the original Actioncraft error data in the cause property.
  */
-export declare class ActionCraftError<TErrorData extends BaseError = BaseError> extends Error {
+export declare class ActioncraftError<TErrorData extends BaseError = BaseError> extends Error {
     readonly cause: TErrorData;
-    constructor(errorData: TErrorData);
+    readonly actionId?: string;
+    constructor(errorData: TErrorData, actionId?: string);
 }
 /**
- * Type guard to check if an error is an ActionCraftError with the action's error types.
- * The action parameter is used purely for type inference.
+ * 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<InferErrors<TAction>>;
+export declare function isActioncraftError<TAction extends CraftedAction<any, any, any, any>>(error: unknown, action?: TAction): error is ActioncraftError<TAction extends undefined ? BaseError : InferErrors<TAction>>;
+/**
+ * Utility to extract the action ID from a crafted action.
+ * Useful for debugging and logging purposes.
+ *
+ * @param action - The crafted action
+ * @returns The action ID if available, undefined otherwise
+ */
+export declare function getActionId<TAction extends CraftedAction<any, any, any, any>>(action: TAction): string | undefined;

package/dist/error.js

@@ -1,22 +1,71 @@
 /**
  * Error wrapper that provides standard Error semantics while preserving
- * the original ActionCraft error data in the cause property.
+ * the original Actioncraft error data in the cause property.
  */
-export class ActionCraftError extends Error {
+export class ActioncraftError extends Error {
     cause;
-    constructor(errorData) {
-        super(`ActionCraft Error: ${errorData.type}${"message" in errorData ? ` - ${errorData.message}` : ""}`);
-        this.name = "ActionCraftError";
+    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);
+        Object.setPrototypeOf(this, ActioncraftError.prototype);
     }
 }
 /**
- * Type guard to check if an error is an ActionCraftError with the action's error types.
- * The action parameter is used purely for type inference.
+ * 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) {
-    return error instanceof 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;
+}
+/**
+ * Utility to extract the action ID from a crafted action.
+ * Useful for debugging and logging purposes.
+ *
+ * @param action - The crafted action
+ * @returns The action ID if available, undefined otherwise
+ */
+export function getActionId(action) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    return action.__ac_id;
 }
 //# sourceMappingURL=error.js.map

package/dist/error.js.map

@@ -1 +1 @@
-{"version":3,"file":"error.js","sourceRoot":"","sources":["../src/error.ts"],"names":[],"mappings":"AAIA;;;GAGG;AACH,MAAM,OAAO,gBAEX,SAAQ,KAAK;IACY,KAAK,CAAa;IAE3C,YAAY,SAAqB;QAC/B,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;QAEvB,sDAAsD;QACtD,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,gBAAgB,CAAC,SAAS,CAAC,CAAC;IAC1D,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAIhC,KAAc,EACd,OAAgB;IAEhB,OAAO,KAAK,YAAY,gBAAgB,CAAC;AAC3C,CAAC"}
+{"version":3,"file":"error.js","sourceRoot":"","sources":["../src/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;AAED;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CAGzB,MAAe;IACf,8DAA8D;IAC9D,OAAQ,MAAc,CAAC,OAA6B,CAAC;AACvD,CAAC"}

package/dist/index.d.ts

@@ -1,6 +1,7 @@
-export { create, initial } from "./actioncraft.js";
-export { unwrap, throwable } from "./utils.js";
-export { ActionCraftError, isActionCraftError } from "./error.js";
+export { craft } from "./classes/craft-builder.js";
+export { action } from "./classes/action-builder.js";
+export { unwrap, throwable, initial, getActionId } from "./utils.js";
+export { ActioncraftError, isActioncraftError } from "./classes/error.js";
 export type { Result, Ok, Err } from "./types/result.js";
 export { isOk, isErr, ok, err } from "./types/result.js";
 export type { InferInput, InferResult, InferData, InferErrors, } from "./types/inference.js";

package/dist/index.js

@@ -2,8 +2,9 @@
 // PUBLIC API EXPORTS
 // ============================================================================
 // Core Functions
-export { create, initial } from "./actioncraft.js";
-export { unwrap, throwable } from "./utils.js";
-export { ActionCraftError, isActionCraftError } from "./error.js";
+export { craft } from "./classes/craft-builder.js";
+export { action } from "./classes/action-builder.js";
+export { unwrap, throwable, initial, getActionId } from "./utils.js";
+export { ActioncraftError, isActioncraftError } from "./classes/error.js";
 export { isOk, isErr, ok, err } from "./types/result.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,qBAAqB;AACrB,+EAA+E;AAE/E,iBAAiB;AACjB,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAIlE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,EAAE,GAAG,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,qBAAqB;AACrB,+EAA+E;AAE/E,iBAAiB;AACjB,OAAO,EAAE,KAAK,EAAE,MAAM,4BAA4B,CAAC;AACnD,OAAO,EAAE,MAAM,EAAE,MAAM,6BAA6B,CAAC;AACrD,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACrE,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAI1E,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,EAAE,GAAG,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/initial.d.ts

@@ -0,0 +1,14 @@
+import type { InferResult } from "./types/inference.js";
+/**
+ * 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
+ * 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>;

package/dist/initial.js

@@ -0,0 +1,47 @@
+import { EXTERNAL_ERROR_TYPES } from "./types/errors.js";
+import { err } from "./types/result.js";
+/**
+ * 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
+ * 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: "Action has not been executed yet",
+    };
+    // Attempt to read the action ID created during craft()
+    const actionId = 
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    action?.__ac_id ?? "unknown";
+    // 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, actionId);
+    }
+    // useActionState enabled -> StatefulApiResult
+    if (cfg?.useActionState) {
+        return {
+            success: false,
+            error,
+            values: undefined,
+            __ac_id: actionId,
+        };
+    }
+    // Default ApiResult shape
+    return {
+        success: false,
+        error,
+        __ac_id: actionId,
+    };
+}
+//# sourceMappingURL=initial.js.map

package/dist/initial.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"initial.js","sourceRoot":"","sources":["../src/initial.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAEzD,OAAO,EAAE,GAAG,EAAE,MAAM,mBAAmB,CAAC;AAExC;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,OAAO,CAAU,MAAe;IAC9C,MAAM,KAAK,GAAG;QACZ,IAAI,EAAE,oBAAoB,CAAC,aAAa;QACxC,OAAO,EAAE,kCAAkC;KACnC,CAAC;IAEX,uDAAuD;IACvD,MAAM,QAAQ;IACZ,8DAA8D;IAC5D,MAAc,EAAE,OAA8B,IAAI,SAAS,CAAC;IAEhE,iEAAiE;IACjE,8DAA8D;IAC9D,MAAM,GAAG,GAAI,MAAc,EAAE,WAEhB,CAAC;IAEd,oCAAoC;IACpC,IAAI,GAAG,EAAE,YAAY,KAAK,YAAY,EAAE,CAAC;QACvC,OAAO,GAAG,CAAC,KAAK,EAAE,QAAQ,CAAoC,CAAC;IACjE,CAAC;IAED,8CAA8C;IAC9C,IAAI,GAAG,EAAE,cAAc,EAAE,CAAC;QACxB,OAAO;YACL,OAAO,EAAE,KAAc;YACvB,KAAK;YACL,MAAM,EAAE,SAAS;YACjB,OAAO,EAAE,QAAQ;SACiB,CAAC;IACvC,CAAC;IAED,0BAA0B;IAC1B,OAAO;QACL,OAAO,EAAE,KAAc;QACvB,KAAK;QACL,OAAO,EAAE,QAAQ;KACiB,CAAC;AACvC,CAAC"}

package/dist/types/actions.d.ts

@@ -1,47 +1,47 @@
 import type { StandardSchemaV1 } from "../standard-schema.js";
-import type { CrafterConfig, CrafterSchemas, CrafterErrors } from "./config.js";
-import type { ErrorFunctions, InferUserDefinedErrorTypes, PossibleErrors } from "./errors.js";
+import type { Config, Schemas, Errors } from "./builder.js";
+import type { ErrorFunctions, InferUserDefinedErrorTypes, PossibleErrors, InferInputValidationErrorFormat, NoInputSchemaError } from "./errors.js";
 import type { Result, Ok, Err } from "./result.js";
-import type { InferValidatedInput, InferRawBindArgs, InferValidatedBindArgs, InferRawInputTuple } from "./schemas.js";
-import type { ApiResult, ActionImplMetadata, StatefulApiResult } from "./shared.js";
+import type { InferValidatedInput, InferRawBindArgs, InferValidatedBindArgs, InferRawInputTuple, InferRawInput } from "./schemas.js";
+import type { ApiResult, HandlerMetadata, StatefulApiResult } from "./shared.js";
 /**
- * Extracts the success data type from an action implementation function.
+ * Extracts the success data type from a handler function.
  */
-export type InferDataFromActionImpl<TFn> = TFn extends (...args: any[]) => any ? Awaited<ReturnType<TFn>> extends infer TReturn ? TReturn extends Ok<infer U> ? U : TReturn extends Err<unknown> | undefined ? never : TReturn : never : never;
+export type InferDataFromHandler<TFn> = TFn extends (...args: any[]) => any ? Awaited<ReturnType<TFn>> extends infer TReturn ? TReturn extends Ok<infer U> ? U : TReturn extends Err<unknown> | undefined ? never : TReturn : never : never;
 /**
- * Parameters passed to action implementation functions.
+ * Parameters passed to handler functions.
  */
-export type ActionImplParams<TConfig extends CrafterConfig, TSchemas extends CrafterSchemas, TErrors extends CrafterErrors, TData> = {
+export type HandlerParams<TConfig extends Config, TSchemas extends Schemas, TErrors extends Errors, TData> = {
     /** Validated input data after schema validation */
     input: InferValidatedInput<TSchemas>;
     /** Validated bind arguments after schema validation */
     bindArgs: InferValidatedBindArgs<TSchemas>;
     /** Helper functions for returning typed errors */
     errors: ErrorFunctions<TErrors>;
-    /** Action metadata for debugging and logging */
-    metadata: ActionImplMetadata<TConfig, TSchemas, TErrors, TData>;
+    /** Handler metadata for debugging and logging */
+    metadata: HandlerMetadata<TConfig, TSchemas, TErrors, TData>;
 };
 /**
- * Action implementation function signature.
+ * Handler function signature.
  * Can return ok(data), errors.yourError(), raw data, or null.
  * Returning undefined is treated as an error.
  */
-export type ActionImpl<TConfig extends CrafterConfig, TSchemas extends CrafterSchemas, TErrors extends CrafterErrors, TData> = (params: ActionImplParams<TConfig, TSchemas, TErrors, TData>) => Promise<Result<TData, InferUserDefinedErrorTypes<TErrors>> | TData | undefined>;
+export type Handler<TConfig extends Config, TSchemas extends Schemas, TErrors extends Errors, TData> = (params: HandlerParams<TConfig, TSchemas, TErrors, TData>) => Promise<Result<TData, InferUserDefinedErrorTypes<TErrors>> | TData | undefined>;
 /**
- * Arguments that the action implementation accepts.
+ * Arguments that the handler accepts.
  * Differs based on useActionState configuration.
  */
-export type InferActionImplArgs<TConfig extends CrafterConfig, TSchemas extends CrafterSchemas, TErrors extends CrafterErrors, TData> = TConfig extends {
+export type InferHandlerArgs<TConfig extends Config, TSchemas extends Schemas, TErrors extends Errors, TData> = TConfig extends {
     useActionState: true;
 } ? StatefulActionArgs<TConfig, TSchemas, TErrors, TData> : StatelessActionArgs<TSchemas>;
 /**
  * Action compatible with React's useActionState hook.
  */
-export type StatefulAction<TConfig extends CrafterConfig, TSchemas extends CrafterSchemas, TErrors extends CrafterErrors, TData> = (...args: StatefulActionArgs<TConfig, TSchemas, TErrors, TData>) => Promise<InferCraftedActionResult<TConfig, TSchemas, TErrors, TData>>;
+export type StatefulAction<TConfig extends Config, TSchemas extends Schemas, TErrors extends Errors, TData> = (...args: StatefulActionArgs<TConfig, TSchemas, TErrors, TData>) => Promise<InferCraftedActionResult<TConfig, TSchemas, TErrors, TData>>;
 /**
  * Arguments for stateful actions: bind args, previous state, then input.
  */
-export type StatefulActionArgs<TConfig extends CrafterConfig, TSchemas extends CrafterSchemas, TErrors extends CrafterErrors, TData> = [
+export type StatefulActionArgs<TConfig extends Config, TSchemas extends Schemas, TErrors extends Errors, TData> = [
     ...InferRawBindArgs<TSchemas>,
     InferPrevStateArg<TConfig, TSchemas, TErrors, TData>,
     ...InferRawInputTuple<TSchemas>
@@ -49,7 +49,7 @@ export type StatefulActionArgs<TConfig extends CrafterConfig, TSchemas extends C
 /**
  * Previous state parameter for useActionState.
  */
-export type InferPrevStateArg<TConfig extends CrafterConfig, TSchemas extends CrafterSchemas, TErrors extends CrafterErrors, TData> = TConfig extends {
+export type InferPrevStateArg<TConfig extends Config, TSchemas extends Schemas, TErrors extends Errors, TData> = TConfig extends {
     useActionState: true;
 } ? StatefulApiResult<TData, PossibleErrors<TErrors, TConfig, TSchemas>, InferSerializedSuccessValues<TSchemas>, InferSerializedErrorValues<TSchemas>> : never;
 /**
@@ -83,36 +83,78 @@ type _ValuesWithFallback<T> = {
 /**
  * Form values available when an action succeeds.
  */
-export type InferSerializedSuccessValues<TSchemas extends CrafterSchemas> = TSchemas extends {
+export type InferSerializedSuccessValues<TSchemas extends Schemas> = TSchemas extends {
     inputSchema: StandardSchemaV1;
 } ? StandardSchemaV1.InferOutput<TSchemas["inputSchema"]> extends Record<string, unknown> ? Record<string, string | string[]> & _ValuesWithFallback<_SafePlainObjectLike<StandardSchemaV1.InferOutput<TSchemas["inputSchema"]>>> : StandardSchemaV1.InferOutput<TSchemas["inputSchema"]> : unknown;
 /**
  * Form values available when an action fails.
  */
-export type InferSerializedErrorValues<TSchemas extends CrafterSchemas> = TSchemas extends {
+export type InferSerializedErrorValues<TSchemas extends Schemas> = TSchemas extends {
     inputSchema: StandardSchemaV1;
 } ? Record<string, string | string[]> & _ValuesWithFallback<_SafePlainObjectLike<StandardSchemaV1.InferInput<TSchemas["inputSchema"]>>> : Record<string, string | string[]>;
 /**
  * Regular server action that doesn't use useActionState.
  */
-export type StatelessAction<TConfig extends CrafterConfig, TSchemas extends CrafterSchemas, TErrors extends CrafterErrors, TData> = (...args: StatelessActionArgs<TSchemas>) => Promise<InferCraftedActionResult<TConfig, TSchemas, TErrors, TData>>;
+export type StatelessAction<TConfig extends Config, TSchemas extends Schemas, TErrors extends Errors, TData> = (...args: StatelessActionArgs<TSchemas>) => Promise<InferCraftedActionResult<TConfig, TSchemas, TErrors, TData>>;
 /**
  * Arguments for stateless actions: bind args followed by input.
  */
-export type StatelessActionArgs<TSchemas extends CrafterSchemas> = [
+export type StatelessActionArgs<TSchemas extends Schemas> = [
     ...InferRawBindArgs<TSchemas>,
     ...InferRawInputTuple<TSchemas>
 ];
 /**
- * Final action function returned by .craft().
+ * Type inference utilities available on crafted actions.
+ */
+export type CraftedActionInfer<TConfig extends Config, TSchemas extends Schemas, TErrors extends Errors, TData> = {
+    /** The raw input type expected by this action */
+    Input: InferRawInput<TSchemas>;
+    /** The success data type returned by this action's handler */
+    Data: TData;
+    /** The complete result type returned when calling this action */
+    Result: InferCraftedActionResult<TConfig, TSchemas, TErrors, TData>;
+    /** The possible error types that can be returned by this action */
+    Errors: PossibleErrors<TErrors, TConfig, TSchemas>;
+};
+/**
+ * Schema validation result for the $validate method.
+ */
+export type ValidationResult<TConfig extends Config, TSchemas extends Schemas> = TSchemas extends {
+    inputSchema: unknown;
+} ? {
+    success: true;
+    data: InferValidatedInput<TSchemas>;
+} | {
+    success: false;
+    error: InferInputValidationErrorFormat<TConfig>;
+} : {
+    success: false;
+    error: NoInputSchemaError;
+};
+/**
+ * The fully-typed server action function returned by the `craft()` method.
  */
-export type CraftedAction<TConfig extends CrafterConfig, TSchemas extends CrafterSchemas, TErrors extends CrafterErrors, TData> = TConfig extends {
+export type CraftedAction<TConfig extends Config, TSchemas extends Schemas, TErrors extends Errors, TData> = (TConfig extends {
     useActionState: true;
-} ? StatefulAction<TConfig, TSchemas, TErrors, TData> : StatelessAction<TConfig, TSchemas, TErrors, TData>;
+} ? StatefulAction<TConfig, TSchemas, TErrors, TData> : StatelessAction<TConfig, TSchemas, TErrors, TData>) & {
+    /**
+     * Type inference utilities for extracting types from this action.
+     * Use with `typeof action.$Infer.Input` etc.
+     */
+    $Infer: CraftedActionInfer<TConfig, TSchemas, TErrors, TData>;
+    /**
+     * Validates input data against this action's input schema without executing the action.
+     * Returns a result object indicating success/failure with typed data or errors.
+     *
+     * @param input - The input data to validate
+     * @returns Promise resolving to validation result with success flag and data/error
+     */
+    $validate(input: InferRawInput<TSchemas>): Promise<ValidationResult<TConfig, TSchemas>>;
+};
 /**
  * Result returned when calling a crafted action.
  */
-export type InferCraftedActionResult<TConfig extends CrafterConfig, TSchemas extends CrafterSchemas, TErrors extends CrafterErrors, TData> = TConfig extends {
+export type InferCraftedActionResult<TConfig extends Config, TSchemas extends Schemas, TErrors extends Errors, TData> = TConfig extends {
     useActionState: true;
 } ? StatefulApiResult<TData, PossibleErrors<TErrors, TConfig, TSchemas>, InferSerializedSuccessValues<TSchemas>, InferSerializedErrorValues<TSchemas>> : TConfig extends {
     resultFormat: "functional";

package/dist/types/builder.d.ts

@@ -0,0 +1,92 @@
+import type { StandardSchemaV1 } from "../standard-schema.js";
+import type { InferCraftedActionResult } from "./actions.js";
+import type { AllPossibleErrors, ErrorDefinition, UserDefinedError } from "./errors.js";
+import type { CallbackMetadata } from "./shared.js";
+/**
+ * Custom logging interface for Actioncraft.
+ */
+export type Logger = {
+    /** Called when callback functions fail */
+    error?: (message: string, error: unknown) => void;
+    /** Called when Actioncraft detects internal bugs */
+    warn?: (message: string, details?: unknown) => void;
+};
+/**
+ * Configuration options for crafting actions.
+ */
+export type Config = {
+    /**
+     * Optional name for this action.
+     * When provided, error messages will include this identifier to help with debugging.
+     */
+    actionName?: string;
+    /**
+     * Result format returned by actions.
+     * "api" returns {success, data/error}, "functional" returns {type, value/error}.
+     * Ignored when useActionState is enabled.
+     * @default "api"
+     */
+    resultFormat?: "api" | "functional";
+    /**
+     * Validation error structure.
+     * "flattened" returns array of {path, message}, "nested" groups by field.
+     * @default "flattened"
+     */
+    validationErrorFormat?: "flattened" | "nested";
+    /**
+     * Enables React useActionState compatibility.
+     * Action accepts prevState parameter and returns a stateful result.
+     * @default false
+     */
+    useActionState?: boolean;
+    /**
+     * Custom handler for unexpected thrown errors.
+     * Transforms exceptions into structured error objects.
+     */
+    handleThrownError?: (error: unknown) => UserDefinedError;
+    /**
+     * Logger for Actioncraft internal events.
+     */
+    logger?: Logger;
+};
+/**
+ * Schema definitions for validating inputs and outputs.
+ */
+export type Schemas = {
+    /** Validates input values passed to the action */
+    inputSchema?: StandardSchemaV1;
+    /** Validates success data returned from the action */
+    outputSchema?: StandardSchemaV1;
+    /** Array of schemas for validating bound arguments */
+    bindSchemas?: readonly StandardSchemaV1[];
+};
+/**
+ * Custom error types that actions can return.
+ * Each property is a function that creates a typed error object.
+ */
+export type Errors = Record<string, ErrorDefinition>;
+/**
+ * Lifecycle hooks that run during action execution.
+ * Callback errors are logged but do not affect action results.
+ */
+export type Callbacks<TConfig extends Config, TSchemas extends Schemas, TErrors extends Errors, TData> = {
+    /** Called when action starts executing, before any validation. */
+    onStart?: (params: {
+        metadata: CallbackMetadata<TConfig, TSchemas, TErrors, TData>;
+    }) => Promise<void> | void;
+    /** Called when action fails. */
+    onError?: (params: {
+        error: AllPossibleErrors<TErrors, TConfig, TSchemas>;
+        metadata: CallbackMetadata<TConfig, TSchemas, TErrors, TData>;
+    }) => Promise<void> | void;
+    /** Called when action succeeds. */
+    onSuccess?: (params: {
+        data: TData;
+        metadata: CallbackMetadata<TConfig, TSchemas, TErrors, TData>;
+    }) => Promise<void> | void;
+    /** Called after action finishes, regardless of success or failure. */
+    onSettled?: (params: {
+        result: InferCraftedActionResult<TConfig, TSchemas, TErrors, TData>;
+        metadata: CallbackMetadata<TConfig, TSchemas, TErrors, TData>;
+    }) => Promise<void> | void;
+};

package/dist/types/builder.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=builder.js.map

package/dist/types/builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"builder.js","sourceRoot":"","sources":["../../src/types/builder.ts"],"names":[],"mappings":""}

package/dist/types/crafter.d.ts

@@ -0,0 +1,87 @@
+import type { StandardSchemaV1 } from "../standard-schema.js";
+import type { InferCraftedActionResult } from "./actions.js";
+import type { AllPossibleErrors, ErrorDefinition, UserDefinedError } from "./errors.js";
+import type { CallbackMetadata } from "./shared.js";
+/**
+ * Custom logging interface for Actioncraft.
+ */
+export type Logger = {
+    /** Called when callback functions fail */
+    error?: (message: string, error: unknown) => void;
+    /** Called when Actioncraft detects internal bugs */
+    warn?: (message: string, details?: unknown) => void;
+};
+/**
+ * Configuration options for crafting actions.
+ */
+export type Config = {
+    /**
+     * Result format returned by actions.
+     * "api" returns {success, data/error}, "functional" returns {type, value/error}.
+     * Ignored when useActionState is enabled.
+     * @default "api"
+     */
+    resultFormat?: "api" | "functional";
+    /**
+     * Validation error structure.
+     * "flattened" returns array of {path, message}, "nested" groups by field.
+     * @default "flattened"
+     */
+    validationErrorFormat?: "flattened" | "nested";
+    /**
+     * Enables React useActionState compatibility.
+     * Action accepts prevState parameter and returns a stateful result.
+     * @default false
+     */
+    useActionState?: boolean;
+    /**
+     * Custom handler for unexpected thrown errors.
+     * Transforms exceptions into structured error objects.
+     */
+    handleThrownError?: (error: unknown) => UserDefinedError;
+    /**
+     * Logger for Actioncraft internal events.
+     */
+    logger?: Logger;
+};
+/**
+ * Schema definitions for validating inputs and outputs.
+ */
+export type Schemas = {
+    /** Validates input values passed to the action */
+    inputSchema?: StandardSchemaV1;
+    /** Validates success data returned from the action */
+    outputSchema?: StandardSchemaV1;
+    /** Array of schemas for validating bound arguments */
+    bindSchemas?: readonly StandardSchemaV1[];
+};
+/**
+ * Custom error types that actions can return.
+ * Each property is a function that creates a typed error object.
+ */
+export type Errors = Record<string, ErrorDefinition>;
+/**
+ * Lifecycle hooks that run during action execution.
+ * Callback errors are logged but do not affect action results.
+ */
+export type Callbacks<TConfig extends Config, TSchemas extends Schemas, TErrors extends Errors, TData> = {
+    /** Called when action starts executing, before any validation. */
+    onStart?: (params: {
+        metadata: CallbackMetadata<TConfig, TSchemas, TErrors, TData>;
+    }) => Promise<void> | void;
+    /** Called when action fails. */
+    onError?: (params: {
+        error: AllPossibleErrors<TErrors, TConfig, TSchemas>;
+        metadata: CallbackMetadata<TConfig, TSchemas, TErrors, TData>;
+    }) => Promise<void> | void;
+    /** Called when action succeeds. */
+    onSuccess?: (params: {
+        data: TData;
+        metadata: CallbackMetadata<TConfig, TSchemas, TErrors, TData>;
+    }) => Promise<void> | void;
+    /** Called after action finishes, regardless of success or failure. */
+    onSettled?: (params: {
+        result: InferCraftedActionResult<TConfig, TSchemas, TErrors, TData>;
+        metadata: CallbackMetadata<TConfig, TSchemas, TErrors, TData>;
+    }) => Promise<void> | void;
+};

package/dist/types/crafter.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=crafter.js.map