@kellanjs/actioncraft 0.1.0 → 0.2.0

package/dist/types/crafter.js.map

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

package/dist/types/errors.d.ts

@@ -1,5 +1,5 @@
 import type { StandardSchemaV1 } from "../standard-schema.js";
-import type { CrafterConfig, CrafterSchemas, CrafterErrors } from "./config.js";
+import type { Config, Schemas, Errors } from "./builder.js";
 import type { Result } from "./result.js";
 import type { Prettify } from "./shared.js";
 /**
@@ -28,7 +28,7 @@ export declare const EXTERNAL_ERROR_TYPES: {
  */
 export type ExternalErrorType = (typeof EXTERNAL_ERROR_TYPES)[keyof typeof EXTERNAL_ERROR_TYPES];
 /**
- * Base structure for all ActionCraft error objects.
+ * Base structure for all Actioncraft error objects.
  */
 export type BaseError = {
     type: string;
@@ -47,14 +47,14 @@ export type ErrorDefinition = (...args: any[]) => UserDefinedError;
  */
 export type ErrorDefToResult<T> = T extends (...args: infer P) => any ? (...args: P) => Result<never, ReturnType<T>> : never;
 /**
- * Error when action implementation returns undefined.
+ * Error when action handler returns undefined.
  */
 export type ImplicitReturnError = BaseError & {
     type: typeof INTERNAL_ERROR_TYPES.IMPLICIT_RETURN;
-    message: "Action implementation must return a value";
+    message: "Action handler must return a value";
 };
 /**
- * Error indicating a bug in the ActionCraft library.
+ * Error indicating a bug in the Actioncraft library.
  */
 export type InternalLogicError = BaseError & {
     type: typeof INTERNAL_ERROR_TYPES.INTERNAL_LOGIC;
@@ -74,6 +74,14 @@ export type UnhandledError = BaseError & {
     type: typeof EXTERNAL_ERROR_TYPES.UNHANDLED;
     message: "An unhandled error occurred";
 };
+/**
+ * Error when no input schema is defined for an action.
+ * Used by `$validate` for client-side data validation.
+ */
+export type NoInputSchemaError = BaseError & {
+    type: "NO_INPUT_SCHEMA";
+    message: "Cannot validate input: no input schema defined for this action";
+};
 /**
  * Base structure for validation errors with nested field organization.
  */
@@ -149,59 +157,59 @@ export type ValidationErrorFormat = {
     }[];
 };
 /**
- * Error functions object provided to action implementations.
+ * Error functions object provided to action handlers.
  */
-export type ErrorFunctions<TErrors extends CrafterErrors> = Prettify<{
+export type ErrorFunctions<TErrors extends Errors> = Prettify<{
     [K in keyof TErrors]: ErrorDefToResult<TErrors[K]>;
 }>;
 /**
  * Input validation error format based on configuration.
  */
-export type InferInputValidationErrorFormat<TConfig extends CrafterConfig> = TConfig["validationErrorFormat"] extends "nested" ? NestedInputValidationError : FlattenedInputValidationError;
+export type InferInputValidationErrorFormat<TConfig extends Config> = TConfig["validationErrorFormat"] extends "nested" ? NestedInputValidationError : FlattenedInputValidationError;
 /**
  * Output validation error format based on configuration.
  */
-export type InferOutputValidationErrorFormat<TConfig extends CrafterConfig> = TConfig["validationErrorFormat"] extends "nested" ? NestedOutputValidationError : FlattenedOutputValidationError;
+export type InferOutputValidationErrorFormat<TConfig extends Config> = TConfig["validationErrorFormat"] extends "nested" ? NestedOutputValidationError : FlattenedOutputValidationError;
 /**
  * Bind arguments validation error format based on configuration.
  */
-export type InferBindArgsValidationErrorFormat<TConfig extends CrafterConfig> = TConfig["validationErrorFormat"] extends "nested" ? NestedBindArgsValidationError : FlattenedBindArgsValidationError;
+export type InferBindArgsValidationErrorFormat<TConfig extends Config> = TConfig["validationErrorFormat"] extends "nested" ? NestedBindArgsValidationError : FlattenedBindArgsValidationError;
 /**
  * All error types from user-defined error functions.
  */
-export type InferUserDefinedErrorTypes<TErrors extends CrafterErrors> = {
+export type InferUserDefinedErrorTypes<TErrors extends Errors> = {
     [K in keyof TErrors]: ReturnType<TErrors[K]>;
 }[keyof TErrors];
 /**
  * Error type for thrown exceptions based on custom handler configuration.
  */
-export type InferThrownErrorType<TConfig extends CrafterConfig> = TConfig extends {
+export type InferThrownErrorType<TConfig extends Config> = TConfig extends {
     handleThrownError: (error: unknown) => infer R;
 } ? R : UnhandledError;
 /**
  * Input validation error type when input schema is present.
  */
-type InferInputValidationErrorType<TConfig extends CrafterConfig, TSchemas extends CrafterSchemas> = TSchemas extends {
+type InferInputValidationErrorType<TConfig extends Config, TSchemas extends Schemas> = TSchemas extends {
     inputSchema: StandardSchemaV1;
 } ? InferInputValidationErrorFormat<TConfig> : never;
 /**
  * Bind arguments validation error type when bind schemas are present.
  */
-type InferBindArgsValidationErrorType<TConfig extends CrafterConfig, TSchemas extends CrafterSchemas> = TSchemas extends {
+type InferBindArgsValidationErrorType<TConfig extends Config, TSchemas extends Schemas> = TSchemas extends {
     bindSchemas: readonly StandardSchemaV1[];
 } ? InferBindArgsValidationErrorFormat<TConfig> : never;
 /**
  * Possible errors that clients should expect when calling an action.
  */
-export type PossibleErrors<TErrors extends CrafterErrors, TConfig extends CrafterConfig, TSchemas extends CrafterSchemas> = InitialStateMarker | InferThrownErrorType<TConfig> | InferInputValidationErrorType<TConfig, TSchemas> | InferBindArgsValidationErrorType<TConfig, TSchemas> | InferUserDefinedErrorTypes<TErrors>;
+export type PossibleErrors<TErrors extends Errors, TConfig extends Config, TSchemas extends Schemas> = InitialStateMarker | InferThrownErrorType<TConfig> | InferInputValidationErrorType<TConfig, TSchemas> | InferBindArgsValidationErrorType<TConfig, TSchemas> | InferUserDefinedErrorTypes<TErrors>;
 /**
  * Output validation error type when output schema is present.
  */
-type InferOutputValidationErrorType<TConfig extends CrafterConfig, TSchemas extends CrafterSchemas> = TSchemas extends {
+type InferOutputValidationErrorType<TConfig extends Config, TSchemas extends Schemas> = TSchemas extends {
     outputSchema: StandardSchemaV1;
 } ? InferOutputValidationErrorFormat<TConfig> : never;
 /**
  * All possible errors, both internal and external.
  */
-export type AllPossibleErrors<TErrors extends CrafterErrors, TConfig extends CrafterConfig, TSchemas extends CrafterSchemas> = PossibleErrors<TErrors, TConfig, TSchemas> | ImplicitReturnError | InternalLogicError | InferOutputValidationErrorType<TConfig, TSchemas>;
+export type AllPossibleErrors<TErrors extends Errors, TConfig extends Config, TSchemas extends Schemas> = PossibleErrors<TErrors, TConfig, TSchemas> | ImplicitReturnError | InternalLogicError | InferOutputValidationErrorType<TConfig, TSchemas>;
 export {};

package/dist/types/inference.d.ts

@@ -1,20 +1,53 @@
-import type { CraftedAction, InferCraftedActionResult } from "./actions.js";
-import type { PossibleErrors } from "./errors.js";
-import type { InferRawInput } from "./schemas.js";
+import type { CraftedAction, CraftedActionInfer } from "./actions.js";
 /**
  * Extracts the raw input type from a crafted action.
+ *
+ * @example
+ * ```typescript
+ * // Traditional approach
+ * type MyInput = InferInput<typeof myAction>
+ *
+ * // Alternative using $Infer (recommended)
+ * type MyInput = typeof myAction.$Infer.Input
+ * ```
  */
-export type InferInput<T> = T extends CraftedAction<infer _TConfig, infer TSchemas, any, // eslint-disable-line @typescript-eslint/no-explicit-any
-any> ? InferRawInput<TSchemas> : never;
+export type InferInput<T> = T extends CraftedAction<infer TConfig, infer TSchemas, infer TErrors, infer TData> ? CraftedActionInfer<TConfig, TSchemas, TErrors, TData>["Input"] : never;
 /**
  * Extracts the complete result type from a crafted action.
+ *
+ * @example
+ * ```typescript
+ * // Traditional approach
+ * type MyResult = InferResult<typeof myAction>
+ *
+ * // Alternative using $Infer (recommended)
+ * type MyResult = typeof myAction.$Infer.Result
+ * ```
  */
-export type InferResult<T> = T extends CraftedAction<infer TConfig, infer TSchemas, infer TErrors, infer TData> ? InferCraftedActionResult<TConfig, TSchemas, TErrors, TData> : never;
+export type InferResult<T> = T extends CraftedAction<infer TConfig, infer TSchemas, infer TErrors, infer TData> ? CraftedActionInfer<TConfig, TSchemas, TErrors, TData>["Result"] : never;
 /**
  * Extracts the success data type from a crafted action.
+ *
+ * @example
+ * ```typescript
+ * // Traditional approach
+ * type MyData = InferData<typeof myAction>
+ *
+ * // Alternative using $Infer (recommended)
+ * type MyData = typeof myAction.$Infer.Data
+ * ```
  */
-export type InferData<T> = T extends CraftedAction<any, any, any, infer TData> ? TData : never;
+export type InferData<T> = T extends CraftedAction<infer TConfig, infer TSchemas, infer TErrors, infer TData> ? CraftedActionInfer<TConfig, TSchemas, TErrors, TData>["Data"] : never;
 /**
  * Extracts possible error types from a crafted action.
+ *
+ * @example
+ * ```typescript
+ * // Traditional approach
+ * type MyErrors = InferErrors<typeof myAction>
+ *
+ * // Alternative using $Infer (recommended)
+ * type MyErrors = typeof myAction.$Infer.Errors
+ * ```
  */
-export type InferErrors<T> = T extends CraftedAction<infer TConfig, infer TSchemas, infer TErrors, any> ? PossibleErrors<TErrors, TConfig, TSchemas> : never;
+export type InferErrors<T> = T extends CraftedAction<infer TConfig, infer TSchemas, infer TErrors, infer TData> ? CraftedActionInfer<TConfig, TSchemas, TErrors, TData>["Errors"] : never;

package/dist/types/result.d.ts

@@ -7,11 +7,13 @@
 export type Ok<T> = {
     readonly type: "ok";
     readonly value: T;
+    readonly __ac_id: string;
 };
 /** A failed result containing an error of type E */
 export type Err<E> = {
     readonly type: "err";
     readonly error: E;
+    readonly __ac_id: string;
 };
 /**
  * A Result represents an operation that can either succeed (Ok) or fail (Err).
@@ -20,26 +22,18 @@ export type Err<E> = {
 export type Result<T, E> = Ok<T> | Err<E>;
 /**
  * Creates a successful result.
- * @param value The success value
+ * @param value The success value (optional)
+ * @param actionId The action ID that created this result (optional, will be set to "unknown" if not provided)
  * @returns Ok result containing the value
  */
-export declare function ok<T>(value: T): Ok<T>;
-/**
- * Creates a successful result with no value.
- * @returns Ok result with void
- */
-export declare function ok(): Ok<void>;
+export declare function ok<T>(value?: T, actionId?: string): Ok<T>;
 /**
  * Creates a failed result.
- * @param error The error value
+ * @param error The error value (optional)
+ * @param actionId The action ID that created this result (optional, will be set to "unknown" if not provided)
  * @returns Err result containing the error
  */
-export declare function err<E>(error: E): Err<E>;
-/**
- * Creates a failed result with no error value.
- * @returns Err result with void
- */
-export declare function err(): Err<void>;
+export declare function err<E>(error?: E, actionId?: string): Err<E>;
 /**
  * Tests if a Result is successful.
  * @param result The Result to check

package/dist/types/result.js

@@ -1,11 +1,43 @@
 // ============================================================================
 // Core Result Type
 // ============================================================================
-export function ok(value) {
-    return { type: "ok", value: value };
+export function ok(valueOrActionId, actionId) {
+    // Handle overloads: ok() vs ok(value) vs ok(value, actionId)
+    if (arguments.length === 0) {
+        // ok() - no arguments
+        return { type: "ok", value: undefined, __ac_id: "unknown" };
+    }
+    else if (arguments.length === 1) {
+        // ok(value) - single argument treated as value (including strings)
+        return { type: "ok", value: valueOrActionId, __ac_id: "unknown" };
+    }
+    else {
+        // ok(value, actionId) - two arguments
+        return {
+            type: "ok",
+            value: valueOrActionId,
+            __ac_id: actionId || "unknown",
+        };
+    }
 }
-export function err(error) {
-    return { type: "err", error: error };
+export function err(errorOrActionId, actionId) {
+    // Handle overloads: err() vs err(error) vs err(error, actionId)
+    if (arguments.length === 0) {
+        // err() - no arguments
+        return { type: "err", error: undefined, __ac_id: "unknown" };
+    }
+    else if (arguments.length === 1) {
+        // err(error) - single argument treated as error (including strings)
+        return { type: "err", error: errorOrActionId, __ac_id: "unknown" };
+    }
+    else {
+        // err(error, actionId) - two arguments
+        return {
+            type: "err",
+            error: errorOrActionId,
+            __ac_id: actionId || "unknown",
+        };
+    }
 }
 /**
  * Tests if a Result is successful.

package/dist/types/result.js.map

@@ -1 +1 @@
-{"version":3,"file":"result.js","sourceRoot":"","sources":["../../src/types/result.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,mBAAmB;AACnB,+EAA+E;AA6B/E,MAAM,UAAU,EAAE,CAAW,KAAS;IACpC,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAmC,CAAC;AACvE,CAAC;AAaD,MAAM,UAAU,GAAG,CAAW,KAAS;IACrC,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAoC,CAAC;AACzE,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,IAAI,CAAO,MAAoB;IAC7C,OAAO,MAAM,CAAC,IAAI,KAAK,IAAI,CAAC;AAC9B,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,KAAK,CAAO,MAAoB;IAC9C,OAAO,MAAM,CAAC,IAAI,KAAK,KAAK,CAAC;AAC/B,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,QAAQ,CACtB,KAAc;IAEd,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACd,MAAM,IAAI,KAAK;QACf,CAAC,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,IAAI,OAAO,IAAI,KAAK,CAAC;YACxC,CAAC,KAAK,CAAC,IAAI,KAAK,KAAK,IAAI,OAAO,IAAI,KAAK,CAAC,CAAC,CAC9C,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,UAAU,CACxB,KAAc;IAEd,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACd,MAAM,IAAI,KAAK;QACf,KAAK,CAAC,IAAI,KAAK,IAAI;QACnB,OAAO,IAAI,KAAK,CACjB,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,WAAW,CACzB,KAAc;IAEd,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACd,MAAM,IAAI,KAAK;QACf,KAAK,CAAC,IAAI,KAAK,KAAK;QACpB,OAAO,IAAI,KAAK,CACjB,CAAC;AACJ,CAAC"}
+{"version":3,"file":"result.js","sourceRoot":"","sources":["../../src/types/result.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,mBAAmB;AACnB,+EAA+E;AAiC/E,MAAM,UAAU,EAAE,CAChB,eAA4B,EAC5B,QAAiB;IAEjB,6DAA6D;IAC7D,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC3B,sBAAsB;QACtB,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,SAAS,EAExD,CAAC;IACJ,CAAC;SAAM,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAClC,mEAAmE;QACnE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,eAAe,EAAE,OAAO,EAAE,SAAS,EAE9D,CAAC;IACJ,CAAC;SAAM,CAAC;QACN,sCAAsC;QACtC,OAAO;YACL,IAAI,EAAE,IAAI;YACV,KAAK,EAAE,eAAe;YACtB,OAAO,EAAE,QAAQ,IAAI,SAAS;SACE,CAAC;IACrC,CAAC;AACH,CAAC;AASD,MAAM,UAAU,GAAG,CACjB,eAA4B,EAC5B,QAAiB;IAEjB,gEAAgE;IAChE,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC3B,uBAAuB;QACvB,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,SAAS,EAEzD,CAAC;IACJ,CAAC;SAAM,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAClC,oEAAoE;QACpE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,eAAe,EAAE,OAAO,EAAE,SAAS,EAE/D,CAAC;IACJ,CAAC;SAAM,CAAC;QACN,uCAAuC;QACvC,OAAO;YACL,IAAI,EAAE,KAAK;YACX,KAAK,EAAE,eAAe;YACtB,OAAO,EAAE,QAAQ,IAAI,SAAS;SACG,CAAC;IACtC,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,IAAI,CAAO,MAAoB;IAC7C,OAAO,MAAM,CAAC,IAAI,KAAK,IAAI,CAAC;AAC9B,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,KAAK,CAAO,MAAoB;IAC9C,OAAO,MAAM,CAAC,IAAI,KAAK,KAAK,CAAC;AAC/B,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,QAAQ,CACtB,KAAc;IAEd,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACd,MAAM,IAAI,KAAK;QACf,CAAC,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,IAAI,OAAO,IAAI,KAAK,CAAC;YACxC,CAAC,KAAK,CAAC,IAAI,KAAK,KAAK,IAAI,OAAO,IAAI,KAAK,CAAC,CAAC,CAC9C,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,UAAU,CACxB,KAAc;IAEd,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACd,MAAM,IAAI,KAAK;QACf,KAAK,CAAC,IAAI,KAAK,IAAI;QACnB,OAAO,IAAI,KAAK,CACjB,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,WAAW,CACzB,KAAc;IAEd,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACd,MAAM,IAAI,KAAK;QACf,KAAK,CAAC,IAAI,KAAK,KAAK;QACpB,OAAO,IAAI,KAAK,CACjB,CAAC;AACJ,CAAC"}

package/dist/types/schemas.d.ts

@@ -1,33 +1,33 @@
 import type { StandardSchemaV1 } from "../standard-schema.js";
-import type { CrafterSchemas } from "./config.js";
+import type { Schemas } from "./builder.js";
 import type { MapSchemasToRawInput, MapSchemasToValidatedOutput } from "./shared.js";
 /**
  * Converts input schema to function parameter tuple for the crafted action.
  */
-export type InferRawInputTuple<TSchemas extends CrafterSchemas> = TSchemas extends {
+export type InferRawInputTuple<TSchemas extends Schemas> = TSchemas extends {
     inputSchema: StandardSchemaV1;
 } ? [InferRawInput<TSchemas>] : [InferRawInput<TSchemas>?];
 /**
  * Raw input type that users pass to the action before validation.
  */
-export type InferRawInput<TSchemas extends CrafterSchemas> = TSchemas extends {
+export type InferRawInput<TSchemas extends Schemas> = TSchemas extends {
     inputSchema: StandardSchemaV1;
 } ? StandardSchemaV1.InferInput<TSchemas["inputSchema"]> : unknown;
 /**
- * Validated input type that action implementations receive.
+ * Validated input type that action handlers receive.
  */
-export type InferValidatedInput<TSchemas extends CrafterSchemas> = TSchemas extends {
+export type InferValidatedInput<TSchemas extends Schemas> = TSchemas extends {
     inputSchema: StandardSchemaV1;
 } ? StandardSchemaV1.InferOutput<TSchemas["inputSchema"]> : undefined;
 /**
  * Raw input types for bound arguments before validation.
  */
-export type InferRawBindArgs<TSchemas extends CrafterSchemas> = TSchemas extends {
+export type InferRawBindArgs<TSchemas extends Schemas> = TSchemas extends {
     bindSchemas: readonly StandardSchemaV1[];
 } ? MapSchemasToRawInput<TSchemas["bindSchemas"]> : [];
 /**
  * Validated output types for bound arguments after validation.
  */
-export type InferValidatedBindArgs<TSchemas extends CrafterSchemas> = TSchemas extends {
+export type InferValidatedBindArgs<TSchemas extends Schemas> = TSchemas extends {
     bindSchemas: readonly StandardSchemaV1[];
 } ? MapSchemasToValidatedOutput<TSchemas["bindSchemas"]> : [];

package/dist/types/shared.d.ts

@@ -1,6 +1,6 @@
 import type { StandardSchemaV1 } from "../standard-schema.js";
 import type { InferPrevStateArg } from "./actions.js";
-import type { CrafterConfig, CrafterErrors, CrafterSchemas } from "./config.js";
+import type { Config, Errors, Schemas } from "./builder.js";
 import type { InferData } from "./inference.js";
 import type { InferValidatedInput, InferValidatedBindArgs, InferRawInput, InferRawBindArgs } from "./schemas.js";
 /**
@@ -15,9 +15,11 @@ export type Prettify<T> = {
 export type ApiResult<TData, TError> = {
     success: true;
     data: TData;
+    __ac_id: string;
 } | {
     success: false;
     error: TError;
+    __ac_id: string;
 };
 /**
  * Result format for actions using useActionState.
@@ -27,10 +29,12 @@ export type StatefulApiResult<TData, TError, TSuccessValues = unknown, TErrorVal
     success: true;
     data: TData;
     values?: TSuccessValues;
+    __ac_id: string;
 } | {
     success: false;
     error: TError;
     values?: TErrorValues;
+    __ac_id: string;
 };
 /**
  * Maps schema array to tuple of raw input types.
@@ -47,9 +51,13 @@ export type MapSchemasToValidatedOutput<T> = T extends readonly [
     ...infer Tail
 ] ? Head extends StandardSchemaV1 ? [StandardSchemaV1.InferOutput<Head>, ...MapSchemasToValidatedOutput<Tail>] : [] : [];
 /**
- * Base metadata available in action implementations and callbacks.
+ * Base metadata available in action handlers and callbacks.
  */
-export type BaseMetadata<TConfig extends CrafterConfig, TSchemas extends CrafterSchemas, TErrors extends CrafterErrors, TData> = {
+export type BaseMetadata<TConfig extends Config, TSchemas extends Schemas, TErrors extends Errors, TData> = {
+    /** Unique identifier for this action instance */
+    actionId: string;
+    /** Optional user-provided name for this action */
+    actionName?: string;
     /** Original input before validation */
     rawInput?: InferRawInput<TSchemas>;
     /** Original bind arguments before validation */
@@ -58,13 +66,13 @@ export type BaseMetadata<TConfig extends CrafterConfig, TSchemas extends Crafter
     prevState?: InferPrevStateArg<TConfig, TSchemas, TErrors, TData>;
 };
 /**
- * Metadata passed to action implementation functions.
+ * Metadata passed to action handler functions.
  */
-export type ActionImplMetadata<TConfig extends CrafterConfig, TSchemas extends CrafterSchemas, TErrors extends CrafterErrors, TData> = BaseMetadata<TConfig, TSchemas, TErrors, TData>;
+export type HandlerMetadata<TConfig extends Config, TSchemas extends Schemas, TErrors extends Errors, TData> = BaseMetadata<TConfig, TSchemas, TErrors, TData>;
 /**
  * Enhanced metadata passed to lifecycle callbacks.
  */
-export type CallbackMetadata<TConfig extends CrafterConfig, TSchemas extends CrafterSchemas, TErrors extends CrafterErrors, TData> = BaseMetadata<TConfig, TSchemas, TErrors, TData> & {
+export type CallbackMetadata<TConfig extends Config, TSchemas extends Schemas, TErrors extends Errors, TData> = BaseMetadata<TConfig, TSchemas, TErrors, TData> & {
     /** Input data after validation */
     validatedInput?: InferValidatedInput<TSchemas>;
     /** Bind arguments after validation */

package/dist/utils.d.ts

@@ -1,15 +1,39 @@
 import type { CraftedAction } from "./types/actions.js";
 import type { BaseError } from "./types/errors.js";
+import type { InferResult } from "./types/inference.js";
 import type { Result } from "./types/result.js";
-import type { ApiResult, ThrowableAction } from "./types/shared.js";
+import type { ApiResult, StatefulApiResult, ThrowableAction } from "./types/shared.js";
 /**
- * Unwraps an ActionCraft result, returning the data or throwing an error.
+ * Unwraps an Actioncraft result, returning the data or throwing an error.
  * Supports both async and sync usage patterns.
+ * Thrown errors automatically include action ID for verification when available.
  */
-export declare function unwrap<TData, TError extends BaseError>(promiseResult: Promise<ApiResult<TData, TError> | Result<TData, TError>>): Promise<TData>;
-export declare function unwrap<TData, TError extends BaseError>(result: ApiResult<TData, TError> | Result<TData, TError>): TData;
+export declare function unwrap<TData, TError extends BaseError>(promiseResult: Promise<ApiResult<TData, TError> | StatefulApiResult<TData, TError> | Result<TData, TError>>): Promise<TData>;
+export declare function unwrap<TData, TError extends BaseError>(result: ApiResult<TData, TError> | StatefulApiResult<TData, TError> | Result<TData, TError>): TData;
 /**
- * Creates a throwable version of an ActionCraft action.
- * The returned function throws on error instead of returning Result objects.
+ * Creates a throwable version of an Actioncraft action.
+ * The returned function throws ActioncraftErrors with automatic action ID verification support.
+ * Errors thrown by this function can be verified with isActioncraftError(error, action).
  */
 export declare function throwable<TAction extends CraftedAction<any, any, any, any>>(action: TAction): ThrowableAction<TAction>;
+/**
+ * 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>;
+/**
+ * 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/utils.js

@@ -1,4 +1,6 @@
-import { ActionCraftError } from "./error.js";
+import { ActioncraftError } from "./classes/error.js";
+import { EXTERNAL_ERROR_TYPES } from "./types/errors.js";
+import { err } from "./types/result.js";
 export function unwrap(resultOrPromise) {
     // Handle Promise case
     if (resultOrPromise instanceof Promise) {
@@ -8,16 +10,18 @@ export function unwrap(resultOrPromise) {
     return _unwrapSync(resultOrPromise);
 }
 /**
- * Synchronously unwraps a result, throwing on error.
+ * Synchronously unwraps a result, throwing on error with embedded action ID.
  */
 function _unwrapSync(result) {
-    // Handle api-style results ({ success: true/false })
+    // Extract action ID from result if present
+    const actionId = "__ac_id" in result ? result.__ac_id : undefined;
+    // Handle api-style results ({ success: true/false }) - includes both ApiResult and StatefulApiResult
     if (typeof result === "object" && result !== null && "success" in result) {
         const apiResult = result;
         if (apiResult.success) {
             return apiResult.data;
         }
-        throw new ActionCraftError(apiResult.error);
+        throw new ActioncraftError(apiResult.error, actionId);
     }
     // Handle functional-style results ({ type: "ok"/"err" })
     if (typeof result === "object" && result !== null && "type" in result) {
@@ -25,13 +29,14 @@ function _unwrapSync(result) {
         if (functionalResult.type === "ok") {
             return functionalResult.value;
         }
-        throw new ActionCraftError(functionalResult.error);
+        throw new ActioncraftError(functionalResult.error, actionId);
     }
-    throw new Error("Invalid result format from ActionCraft action");
+    throw new Error("Invalid result format from Actioncraft action");
 }
 /**
- * Creates a throwable version of an ActionCraft action.
- * The returned function throws on error instead of returning Result objects.
+ * Creates a throwable version of an Actioncraft action.
+ * The returned function throws ActioncraftErrors with automatic action ID verification support.
+ * Errors thrown by this function can be verified with isActioncraftError(error, action).
  */
 export function throwable(action) {
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -41,4 +46,59 @@ export function throwable(action) {
         return unwrap(result);
     });
 }
+/**
+ * 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,
+    };
+}
+/**
+ * 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=utils.js.map

package/dist/utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"utils.js","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAkB9C,MAAM,UAAU,MAAM,CACpB,eAG6D;IAE7D,sBAAsB;IACtB,IAAI,eAAe,YAAY,OAAO,EAAE,CAAC;QACvC,OAAO,eAAe,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC;IAC/D,CAAC;IAED,4BAA4B;IAC5B,OAAO,WAAW,CAAC,eAAe,CAAC,CAAC;AACtC,CAAC;AAED;;GAEG;AACH,SAAS,WAAW,CAClB,MAAwD;IAExD,qDAAqD;IACrD,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI,IAAI,SAAS,IAAI,MAAM,EAAE,CAAC;QACzE,MAAM,SAAS,GAAG,MAAkC,CAAC;QACrD,IAAI,SAAS,CAAC,OAAO,EAAE,CAAC;YACtB,OAAO,SAAS,CAAC,IAAI,CAAC;QACxB,CAAC;QACD,MAAM,IAAI,gBAAgB,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAC9C,CAAC;IAED,yDAAyD;IACzD,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI,IAAI,MAAM,IAAI,MAAM,EAAE,CAAC;QACtE,MAAM,gBAAgB,GAAG,MAA+B,CAAC;QACzD,IAAI,gBAAgB,CAAC,IAAI,KAAK,IAAI,EAAE,CAAC;YACnC,OAAO,gBAAgB,CAAC,KAAK,CAAC;QAChC,CAAC;QACD,MAAM,IAAI,gBAAgB,CAAC,gBAAgB,CAAC,KAAK,CAAC,CAAC;IACrD,CAAC;IAED,MAAM,IAAI,KAAK,CAAC,+CAA+C,CAAC,CAAC;AACnE,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,SAAS,CAGvB,MAAe;IACf,8DAA8D;IAC9D,OAAO,CAAC,KAAK,EAAE,GAAG,IAAW,EAAE,EAAE;QAC/B,8DAA8D;QAC9D,MAAM,MAAM,GAAG,MAAO,MAAc,CAAC,GAAG,IAAI,CAAC,CAAC;QAC9C,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC;IACxB,CAAC,CAA6B,CAAC;AACjC,CAAC"}
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kellanjs/actioncraft",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Fluent, type-safe builder for Next.js server actions.",
   "keywords": [
     "next.js",
@@ -68,7 +68,7 @@
     "typescript": "^5.8.3",
     "typescript-eslint": "^8.35.1",
     "vitest": "^3.2.4",
-    "zod": "^3.25.74",
-    "zod-form-data": "^3.0.0"
+    "zod": "^4.1.5",
+    "zod-form-data": "^3.0.1"
   }
 }