@kellanjs/actioncraft 0.1.0 → 0.2.1

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/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/{config.d.ts → builder.d.ts}

@@ -3,32 +3,40 @@ 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.
+ * Custom logging interface for Actioncraft.
  */
-export type CrafterLogger = {
+export type Logger = {
     /** Called when callback functions fail */
     error?: (message: string, error: unknown) => void;
-    /** Called when ActionCraft detects internal bugs */
+    /** Called when Actioncraft detects internal bugs */
     warn?: (message: string, details?: unknown) => void;
 };
 /**
- * Configuration options for building actions.
+ * Configuration options for crafting actions.
  */
-export type CrafterConfig = {
+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;
     /**
@@ -37,14 +45,14 @@ export type CrafterConfig = {
      */
     handleThrownError?: (error: unknown) => UserDefinedError;
     /**
-     * Logger for ActionCraft internal events.
+     * Logger for Actioncraft internal events.
      */
-    logger?: CrafterLogger;
+    logger?: Logger;
 };
 /**
  * Schema definitions for validating inputs and outputs.
  */
-export type CrafterSchemas = {
+export type Schemas = {
     /** Validates input values passed to the action */
     inputSchema?: StandardSchemaV1;
     /** Validates success data returned from the action */
@@ -56,12 +64,12 @@ export type CrafterSchemas = {
  * Custom error types that actions can return.
  * Each property is a function that creates a typed error object.
  */
-export type CrafterErrors = Record<string, ErrorDefinition>;
+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 CrafterCallbacks<TConfig extends CrafterConfig, TSchemas extends CrafterSchemas, TErrors extends CrafterErrors, TData> = {
+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>;

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/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"]> : [];