@kellanjs/actioncraft 0.0.1

package/dist/types/errors.d.ts

@@ -0,0 +1,207 @@
+import type { StandardSchemaV1 } from "../standard-schema.js";
+import type { CrafterConfig, CrafterSchemas, CrafterErrors } from "./config.js";
+import type { Result } from "./result.js";
+import type { Prettify } from "./shared.js";
+/**
+ * Map of error identifiers that should never be surfaced to clients.
+ */
+export declare const INTERNAL_ERROR_TYPES: {
+    readonly IMPLICIT_RETURN: "IMPLICIT_RETURN";
+    readonly INTERNAL_LOGIC: "INTERNAL_LOGIC";
+    readonly OUTPUT_VALIDATION: "OUTPUT_VALIDATION";
+};
+/**
+ * Literal union of the keys of `INTERNAL_ERROR_TYPES`
+ */
+export type InternalErrorType = (typeof INTERNAL_ERROR_TYPES)[keyof typeof INTERNAL_ERROR_TYPES];
+/**
+ * Map of error identifiers that can be surfaced to clients.
+ */
+export declare const EXTERNAL_ERROR_TYPES: {
+    readonly INITIAL_STATE: "INITIAL_STATE";
+    readonly UNHANDLED: "UNHANDLED";
+    readonly INPUT_VALIDATION: "INPUT_VALIDATION";
+    readonly BIND_ARGS_VALIDATION: "BIND_ARGS_VALIDATION";
+};
+/**
+ * Literal union of the keys of `EXTERNAL_ERROR_TYPES`
+ */
+export type ExternalErrorType = (typeof EXTERNAL_ERROR_TYPES)[keyof typeof EXTERNAL_ERROR_TYPES];
+/**
+ * Base structure for all ActionCraft error objects.
+ */
+export type BaseError = {
+    type: string;
+    message?: string;
+};
+/**
+ * Type constraint for custom error objects defined by users.
+ */
+export type UserDefinedError = BaseError & Record<string, any>;
+/**
+ * Function signature for custom error definitions in .errors() method.
+ */
+export type ErrorDefinition = (...args: any[]) => UserDefinedError;
+/**
+ * Transforms error definition functions into Result-returning functions.
+ */
+export type ErrorDefToResult<T> = T extends (...args: infer P) => any ? (...args: P) => Result<never, ReturnType<T>> : never;
+/**
+ * Error when action implementation returns undefined.
+ */
+export type ImplicitReturnError = BaseError & {
+    type: typeof INTERNAL_ERROR_TYPES.IMPLICIT_RETURN;
+    message: "Action implementation must return a value";
+};
+/**
+ * Error indicating a bug in the ActionCraft library.
+ */
+export type InternalLogicError = BaseError & {
+    type: typeof INTERNAL_ERROR_TYPES.INTERNAL_LOGIC;
+    message: string;
+};
+/**
+ * Marker for initial state in useActionState before any action executes.
+ */
+export type InitialStateMarker = BaseError & {
+    type: typeof EXTERNAL_ERROR_TYPES.INITIAL_STATE;
+    message: "No action has been executed yet";
+};
+/**
+ * Error for uncaught exceptions when no custom handler is provided.
+ */
+export type UnhandledError = BaseError & {
+    type: typeof EXTERNAL_ERROR_TYPES.UNHANDLED;
+    message: "An unhandled error occurred";
+};
+/**
+ * Base structure for validation errors with nested field organization.
+ */
+type NestedValidationError<TType extends string> = BaseError & {
+    type: TType;
+    message: string;
+    formErrors: string[];
+    fieldErrors: {
+        [path: string]: string[];
+    };
+};
+/**
+ * Base structure for validation errors with flat issue array.
+ */
+type FlattenedValidationError<TType extends string> = BaseError & {
+    type: TType;
+    message: string;
+    issues: {
+        path: (string | number)[];
+        message: string;
+    }[];
+};
+/**
+ * Input validation error with nested field structure.
+ */
+export type NestedInputValidationError = NestedValidationError<typeof EXTERNAL_ERROR_TYPES.INPUT_VALIDATION>;
+/**
+ * Input validation error with flat issue array.
+ */
+export type FlattenedInputValidationError = FlattenedValidationError<typeof EXTERNAL_ERROR_TYPES.INPUT_VALIDATION>;
+/**
+ * Output validation error with nested field structure.
+ */
+export type NestedOutputValidationError = NestedValidationError<typeof INTERNAL_ERROR_TYPES.OUTPUT_VALIDATION>;
+/**
+ * Output validation error with flat issue array.
+ */
+export type FlattenedOutputValidationError = FlattenedValidationError<typeof INTERNAL_ERROR_TYPES.OUTPUT_VALIDATION>;
+/**
+ * Bind arguments validation error with nested field structure.
+ */
+export type NestedBindArgsValidationError = NestedValidationError<typeof EXTERNAL_ERROR_TYPES.BIND_ARGS_VALIDATION>;
+/**
+ * Bind arguments validation error with flat issue array.
+ */
+export type FlattenedBindArgsValidationError = FlattenedValidationError<typeof EXTERNAL_ERROR_TYPES.BIND_ARGS_VALIDATION>;
+/**
+ * All possible input validation error formats.
+ */
+export type InputValidationError = NestedInputValidationError | FlattenedInputValidationError;
+/**
+ * All possible output validation error formats.
+ */
+export type OutputValidationError = NestedOutputValidationError | FlattenedOutputValidationError;
+/**
+ * All possible bind arguments validation error formats.
+ */
+export type BindArgsValidationError = NestedBindArgsValidationError | FlattenedBindArgsValidationError;
+/**
+ * All validation error types combined.
+ */
+export type ValidationError = InputValidationError | OutputValidationError | BindArgsValidationError;
+/**
+ * Base structure for validation errors before type-specific fields.
+ */
+export type ValidationErrorFormat = {
+    formErrors: string[];
+    fieldErrors: Record<string, string[]>;
+} | {
+    issues: {
+        path: (string | number)[];
+        message: string;
+    }[];
+};
+/**
+ * Error functions object provided to action implementations.
+ */
+export type ErrorFunctions<TErrors extends CrafterErrors> = 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;
+/**
+ * Output validation error format based on configuration.
+ */
+export type InferOutputValidationErrorFormat<TConfig extends CrafterConfig> = 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;
+/**
+ * All error types from user-defined error functions.
+ */
+export type InferUserDefinedErrorTypes<TErrors extends CrafterErrors> = {
+    [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 {
+    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 {
+    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 {
+    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>;
+/**
+ * Output validation error type when output schema is present.
+ */
+type InferOutputValidationErrorType<TConfig extends CrafterConfig, TSchemas extends CrafterSchemas> = 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 {};

package/dist/types/errors.js

@@ -0,0 +1,21 @@
+// ============================================================================
+// CONSTANTS
+// ============================================================================
+/**
+ * Map of error identifiers that should never be surfaced to clients.
+ */
+export const INTERNAL_ERROR_TYPES = {
+    IMPLICIT_RETURN: "IMPLICIT_RETURN",
+    INTERNAL_LOGIC: "INTERNAL_LOGIC",
+    OUTPUT_VALIDATION: "OUTPUT_VALIDATION",
+};
+/**
+ * Map of error identifiers that can be surfaced to clients.
+ */
+export const EXTERNAL_ERROR_TYPES = {
+    INITIAL_STATE: "INITIAL_STATE",
+    UNHANDLED: "UNHANDLED",
+    INPUT_VALIDATION: "INPUT_VALIDATION",
+    BIND_ARGS_VALIDATION: "BIND_ARGS_VALIDATION",
+};
+//# sourceMappingURL=errors.js.map

package/dist/types/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/types/errors.ts"],"names":[],"mappings":"AAKA,+EAA+E;AAC/E,YAAY;AACZ,+EAA+E;AAE/E;;GAEG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC,eAAe,EAAE,iBAAiB;IAClC,cAAc,EAAE,gBAAgB;IAChC,iBAAiB,EAAE,mBAAmB;CAC9B,CAAC;AAQX;;GAEG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC,aAAa,EAAE,eAAe;IAC9B,SAAS,EAAE,WAAW;IACtB,gBAAgB,EAAE,kBAAkB;IACpC,oBAAoB,EAAE,sBAAsB;CACpC,CAAC"}

package/dist/types/inference.d.ts

@@ -0,0 +1,20 @@
+import type { CraftedAction, InferCraftedActionResult } from "./actions.js";
+import type { PossibleErrors } from "./errors.js";
+import type { InferRawInput } from "./schemas.js";
+/**
+ * Extracts the raw input type from a crafted action.
+ */
+export type InferInput<T> = T extends CraftedAction<infer _TConfig, infer TSchemas, any, // eslint-disable-line @typescript-eslint/no-explicit-any
+any> ? InferRawInput<TSchemas> : never;
+/**
+ * Extracts the complete result type from a crafted action.
+ */
+export type InferResult<T> = T extends CraftedAction<infer TConfig, infer TSchemas, infer TErrors, infer TData> ? InferCraftedActionResult<TConfig, TSchemas, TErrors, TData> : never;
+/**
+ * Extracts the success data type from a crafted action.
+ */
+export type InferData<T> = T extends CraftedAction<any, any, any, infer TData> ? TData : never;
+/**
+ * Extracts possible error types from a crafted action.
+ */
+export type InferErrors<T> = T extends CraftedAction<infer TConfig, infer TSchemas, infer TErrors, any> ? PossibleErrors<TErrors, TConfig, TSchemas> : never;

package/dist/types/inference.js

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

package/dist/types/inference.js.map

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

package/dist/types/result.d.ts

@@ -0,0 +1,72 @@
+/**
+ * This is the functional Result type that the library uses for all internal logic.
+ * The ApiResult format is returned to the client by default, but the action can be
+ * configured to return the functional Result type if desired.
+ */
+/** A successful result containing a value of type T */
+export type Ok<T> = {
+    readonly type: "ok";
+    readonly value: T;
+};
+/** A failed result containing an error of type E */
+export type Err<E> = {
+    readonly type: "err";
+    readonly error: E;
+};
+/**
+ * A Result represents an operation that can either succeed (Ok) or fail (Err).
+ * This is a serializable alternative to throwing exceptions.
+ */
+export type Result<T, E> = Ok<T> | Err<E>;
+/**
+ * Creates a successful result.
+ * @param value The success value
+ * @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>;
+/**
+ * Creates a failed result.
+ * @param error The error value
+ * @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>;
+/**
+ * Tests if a Result is successful.
+ * @param result The Result to check
+ * @returns true if result is Ok, false if Err
+ */
+export declare function isOk<T, E>(result: Result<T, E>): result is Ok<T>;
+/**
+ * Tests if a Result is failed.
+ * @param result The Result to check
+ * @returns true if result is Err, false if Ok
+ */
+export declare function isErr<T, E>(result: Result<T, E>): result is Err<E>;
+/**
+ * Tests if an unknown value is a valid Result.
+ * @param value The value to check
+ * @returns true if value is a Result (Ok or Err), false otherwise
+ */
+export declare function isResult<T = unknown, E = unknown>(value: unknown): value is Result<T, E>;
+/**
+ * Tests if an unknown value is a valid Ok Result.
+ * @param value The value to check
+ * @returns true if value is an Ok Result, false otherwise
+ */
+export declare function isResultOk<_T = unknown, _E = unknown>(value: unknown): value is Ok<_T>;
+/**
+ * Tests if an unknown value is a valid Err Result.
+ * @param value The value to check
+ * @returns true if value is an Err Result, false otherwise
+ */
+export declare function isResultErr<_T = unknown, E = unknown>(value: unknown): value is Err<E>;

package/dist/types/result.js

@@ -0,0 +1,62 @@
+// ============================================================================
+// Core Result Type
+// ============================================================================
+export function ok(value) {
+    return { type: "ok", value: value };
+}
+export function err(error) {
+    return { type: "err", error: error };
+}
+/**
+ * Tests if a Result is successful.
+ * @param result The Result to check
+ * @returns true if result is Ok, false if Err
+ */
+export function isOk(result) {
+    return result.type === "ok";
+}
+/**
+ * Tests if a Result is failed.
+ * @param result The Result to check
+ * @returns true if result is Err, false if Ok
+ */
+export function isErr(result) {
+    return result.type === "err";
+}
+/**
+ * Tests if an unknown value is a valid Result.
+ * @param value The value to check
+ * @returns true if value is a Result (Ok or Err), false otherwise
+ */
+export function isResult(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        "type" in value &&
+        ((value.type === "ok" && "value" in value) ||
+            (value.type === "err" && "error" in value)));
+}
+/**
+ * Tests if an unknown value is a valid Ok Result.
+ * @param value The value to check
+ * @returns true if value is an Ok Result, false otherwise
+ */
+export function isResultOk(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        "type" in value &&
+        value.type === "ok" &&
+        "value" in value);
+}
+/**
+ * Tests if an unknown value is a valid Err Result.
+ * @param value The value to check
+ * @returns true if value is an Err Result, false otherwise
+ */
+export function isResultErr(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        "type" in value &&
+        value.type === "err" &&
+        "error" in value);
+}
+//# sourceMappingURL=result.js.map

package/dist/types/result.js.map

@@ -0,0 +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"}

package/dist/types/schemas.d.ts

@@ -0,0 +1,33 @@
+import type { StandardSchemaV1 } from "../standard-schema.js";
+import type { CrafterSchemas } from "./config.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 {
+    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 {
+    inputSchema: StandardSchemaV1;
+} ? StandardSchemaV1.InferInput<TSchemas["inputSchema"]> : unknown;
+/**
+ * Validated input type that action implementations receive.
+ */
+export type InferValidatedInput<TSchemas extends CrafterSchemas> = 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 {
+    bindSchemas: readonly StandardSchemaV1[];
+} ? MapSchemasToRawInput<TSchemas["bindSchemas"]> : [];
+/**
+ * Validated output types for bound arguments after validation.
+ */
+export type InferValidatedBindArgs<TSchemas extends CrafterSchemas> = TSchemas extends {
+    bindSchemas: readonly StandardSchemaV1[];
+} ? MapSchemasToValidatedOutput<TSchemas["bindSchemas"]> : [];

package/dist/types/schemas.js

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

package/dist/types/schemas.js.map

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

package/dist/types/shared.d.ts

@@ -0,0 +1,75 @@
+import type { StandardSchemaV1 } from "../standard-schema.js";
+import type { InferPrevStateArg } from "./actions.js";
+import type { CrafterConfig, CrafterErrors, CrafterSchemas } from "./config.js";
+import type { InferData } from "./inference.js";
+import type { InferValidatedInput, InferValidatedBindArgs, InferRawInput } from "./schemas.js";
+/**
+ * Expands type aliases for better IDE display.
+ */
+export type Prettify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+/**
+ * Standard success/error result format for actions.
+ */
+export type ApiResult<TData, TError> = {
+    success: true;
+    data: TData;
+} | {
+    success: false;
+    error: TError;
+};
+/**
+ * Result format for actions using useActionState.
+ * Includes form values for success and error states.
+ */
+export type StatefulApiResult<TData, TError, TSuccessValues = unknown, TErrorValues = TSuccessValues> = {
+    success: true;
+    data: TData;
+    values?: TSuccessValues;
+} | {
+    success: false;
+    error: TError;
+    values?: TErrorValues;
+};
+/**
+ * Maps schema array to tuple of raw input types.
+ */
+export type MapSchemasToRawInput<T> = T extends readonly [
+    infer Head,
+    ...infer Tail
+] ? Head extends StandardSchemaV1 ? [StandardSchemaV1.InferInput<Head>, ...MapSchemasToRawInput<Tail>] : [] : [];
+/**
+ * Maps schema array to tuple of validated output types.
+ */
+export type MapSchemasToValidatedOutput<T> = T extends readonly [
+    infer Head,
+    ...infer Tail
+] ? Head extends StandardSchemaV1 ? [StandardSchemaV1.InferOutput<Head>, ...MapSchemasToValidatedOutput<Tail>] : [] : [];
+/**
+ * Base metadata available in action implementations and callbacks.
+ */
+export type BaseMetadata<TConfig extends CrafterConfig, TSchemas extends CrafterSchemas, TErrors extends CrafterErrors, TData> = {
+    /** Original input before validation */
+    rawInput?: InferRawInput<TSchemas>;
+    /** Previous result when using useActionState */
+    prevState?: InferPrevStateArg<TConfig, TSchemas, TErrors, TData>;
+};
+/**
+ * Metadata passed to action implementation functions.
+ */
+export type ActionImplMetadata<TConfig extends CrafterConfig, TSchemas extends CrafterSchemas, TErrors extends CrafterErrors, 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> & {
+    /** Input data after validation */
+    validatedInput?: InferValidatedInput<TSchemas>;
+    /** Bind arguments after validation */
+    validatedBindArgs?: InferValidatedBindArgs<TSchemas>;
+};
+/**
+ * Converts Result-based action to Exception-based action.
+ * Used by the throwable() utility function.
+ */
+export type ThrowableAction<TAction> = TAction extends (...args: infer TArgs) => Promise<any> ? (...args: TArgs) => Promise<InferData<TAction>> : never;

package/dist/types/shared.js

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

package/dist/types/shared.js.map

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

package/dist/utils.d.ts

@@ -0,0 +1,15 @@
+import type { CraftedAction } from "./types/actions.js";
+import type { BaseError } from "./types/errors.js";
+import type { Result } from "./types/result.js";
+import type { ApiResult, ThrowableAction } from "./types/shared.js";
+/**
+ * Unwraps an ActionCraft result, returning the data or throwing an error.
+ * Supports both async and sync usage patterns.
+ */
+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;
+/**
+ * Creates a throwable version of an ActionCraft action.
+ * The returned function throws on error instead of returning Result objects.
+ */
+export declare function throwable<TAction extends CraftedAction<any, any, any, any>>(action: TAction): ThrowableAction<TAction>;

package/dist/utils.js

@@ -0,0 +1,44 @@
+import { ActionCraftError } from "./error.js";
+export function unwrap(resultOrPromise) {
+    // Handle Promise case
+    if (resultOrPromise instanceof Promise) {
+        return resultOrPromise.then((result) => _unwrapSync(result));
+    }
+    // Handle direct result case
+    return _unwrapSync(resultOrPromise);
+}
+/**
+ * Synchronously unwraps a result, throwing on error.
+ */
+function _unwrapSync(result) {
+    // Handle api-style results ({ success: true/false })
+    if (typeof result === "object" && result !== null && "success" in result) {
+        const apiResult = result;
+        if (apiResult.success) {
+            return apiResult.data;
+        }
+        throw new ActionCraftError(apiResult.error);
+    }
+    // Handle functional-style results ({ type: "ok"/"err" })
+    if (typeof result === "object" && result !== null && "type" in result) {
+        const functionalResult = result;
+        if (functionalResult.type === "ok") {
+            return functionalResult.value;
+        }
+        throw new ActionCraftError(functionalResult.error);
+    }
+    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.
+ */
+export function throwable(action) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    return (async (...args) => {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const result = await action(...args);
+        return unwrap(result);
+    });
+}
+//# sourceMappingURL=utils.js.map

package/dist/utils.js.map

@@ -0,0 +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"}

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "@kellanjs/actioncraft",
+  "version": "0.0.1",
+  "description": "Fluent, type-safe builder for Next.js server actions.",
+  "keywords": [
+    "next.js",
+    "react",
+    "server-actions",
+    "server-side",
+    "useactionstate",
+    "typescript",
+    "type-safety",
+    "type-inference",
+    "fluent-api",
+    "builder-pattern",
+    "schema-validation",
+    "validation",
+    "error-handling",
+    "form-handling",
+    "progressive-enhancement",
+    "full-stack"
+  ],
+  "author": "kellanjs",
+  "license": "MIT",
+  "homepage": "https://github.com/kellanjs/actioncraft",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kellanjs/actioncraft.git"
+  },
+  "bugs": {
+    "url": "https://github.com/kellanjs/actioncraft/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "dev": "vitest",
+    "build": "tsc",
+    "lint": "eslint .",
+    "test": "vitest run",
+    "format": "prettier --write .",
+    "check-format": "prettier --check .",
+    "check-exports": "attw --pack . --ignore-rules=cjs-resolves-to-esm",
+    "ci": "npm run lint && npm run build && npm run check-format && npm run check-exports && npm run test"
+  },
+  "peerDependencies": {
+    "next": "^15.0.0",
+    "react": "^19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "^0.18.2",
+    "@eslint/js": "^9.30.1",
+    "@trivago/prettier-plugin-sort-imports": "^5.2.2",
+    "eslint": "^9.30.1",
+    "next": "^15.0.0",
+    "prettier": "^3.6.2",
+    "react": "^19.0.0",
+    "typescript": "^5.8.3",
+    "typescript-eslint": "^8.35.1",
+    "vitest": "^3.2.4",
+    "zod": "^3.25.74",
+    "zod-form-data": "^3.0.0"
+  }
+}