@kellanjs/actioncraft 0.0.1

package/dist/core/logging.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logging.js","sourceRoot":"","sources":["../../src/core/logging.ts"],"names":[],"mappings":"AAOA,MAAM,UAAU,GAAG,CACjB,MAA+B,EAC/B,KAAuB,EACvB,OAAe,EACf,OAAiB;IAEjB,IAAI,CAAC,MAAM;QAAE,OAAO;IACpB,MAAM,EAAE,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;IACzB,IAAI,EAAE;QAAE,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;AAC/B,CAAC"}

package/dist/core/transformation.d.ts

@@ -0,0 +1,17 @@
+import type { InferSerializedErrorValues } from "../types/actions.js";
+import type { CrafterSchemas } from "../types/config.js";
+import type { CrafterConfig, CrafterErrors } from "../types/config.js";
+import type { PossibleErrors, AllPossibleErrors } from "../types/errors.js";
+import type { InferRawInput, InferValidatedInput } from "../types/schemas.js";
+/**
+ * Converts input to a serializable format for the `values` field in action results.
+ *
+ * If the input is `FormData`, it is flattened into a plain object so that it can
+ * be safely JSON-serialized. Otherwise, the input is returned as-is.
+ */
+export declare function serializeRawInput<TSchemas extends CrafterSchemas>(input: InferRawInput<TSchemas> | InferValidatedInput<TSchemas> | undefined): InferSerializedErrorValues<TSchemas>;
+/**
+ * Converts internal error objects into client-facing errors, hiding
+ * implementation details that should not leak outside the server.
+ */
+export declare function convertToClientError<TErrors extends CrafterErrors, TConfig extends CrafterConfig, TSchemas extends CrafterSchemas>(internalError: AllPossibleErrors<TErrors, TConfig, TSchemas>): PossibleErrors<TErrors, TConfig, TSchemas>;

package/dist/core/transformation.js

@@ -0,0 +1,43 @@
+import { INTERNAL_ERROR_TYPES } from "../types/errors.js";
+import { UNHANDLED_ERROR } from "./errors.js";
+/**
+ * Converts input to a serializable format for the `values` field in action results.
+ *
+ * If the input is `FormData`, it is flattened into a plain object so that it can
+ * be safely JSON-serialized. Otherwise, the input is returned as-is.
+ */
+export function serializeRawInput(input) {
+    if (input instanceof FormData) {
+        const valueMap = new Map();
+        for (const [key, value] of input.entries()) {
+            // Ignore React server-action meta-fields
+            if (key.startsWith("$ACTION"))
+                continue;
+            const stringValue = typeof value === "string" ? value : value.name || "[File]";
+            if (!valueMap.has(key))
+                valueMap.set(key, []);
+            valueMap.get(key).push(stringValue);
+        }
+        // Collapse single-item arrays
+        const serialized = {};
+        for (const [key, values] of valueMap.entries()) {
+            serialized[key] = values.length === 1 ? values[0] : values;
+        }
+        return serialized;
+    }
+    // Non-FormData inputs are assumed to already be serialisable
+    return input;
+}
+/**
+ * Converts internal error objects into client-facing errors, hiding
+ * implementation details that should not leak outside the server.
+ */
+export function convertToClientError(internalError) {
+    if (internalError.type === INTERNAL_ERROR_TYPES.IMPLICIT_RETURN ||
+        internalError.type === INTERNAL_ERROR_TYPES.OUTPUT_VALIDATION ||
+        internalError.type === INTERNAL_ERROR_TYPES.INTERNAL_LOGIC) {
+        return UNHANDLED_ERROR;
+    }
+    return internalError;
+}
+//# sourceMappingURL=transformation.js.map

package/dist/core/transformation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transformation.js","sourceRoot":"","sources":["../../src/core/transformation.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAE1D,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE9C;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAC/B,KAA0E;IAE1E,IAAI,KAAK,YAAY,QAAQ,EAAE,CAAC;QAC9B,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAoB,CAAC;QAE7C,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,KAAK,CAAC,OAAO,EAAE,EAAE,CAAC;YAC3C,yCAAyC;YACzC,IAAI,GAAG,CAAC,UAAU,CAAC,SAAS,CAAC;gBAAE,SAAS;YAExC,MAAM,WAAW,GACf,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,IAAI,QAAQ,CAAC;YAE7D,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC;gBAAE,QAAQ,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;YAC9C,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAE,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;QACvC,CAAC;QAED,8BAA8B;QAC9B,MAAM,UAAU,GAAsC,EAAE,CAAC;QACzD,KAAK,MAAM,CAAC,GAAG,EAAE,MAAM,CAAC,IAAI,QAAQ,CAAC,OAAO,EAAE,EAAE,CAAC;YAC/C,UAAU,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAE,CAAC,CAAC,CAAC,MAAM,CAAC;QAC9D,CAAC;QAED,OAAO,UAAkD,CAAC;IAC5D,CAAC;IAED,6DAA6D;IAC7D,OAAO,KAA6C,CAAC;AACvD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,oBAAoB,CAKlC,aAA4D;IAE5D,IACE,aAAa,CAAC,IAAI,KAAK,oBAAoB,CAAC,eAAe;QAC3D,aAAa,CAAC,IAAI,KAAK,oBAAoB,CAAC,iBAAiB;QAC7D,aAAa,CAAC,IAAI,KAAK,oBAAoB,CAAC,cAAc,EAC1D,CAAC;QACD,OAAO,eAA6D,CAAC;IACvE,CAAC;IACD,OAAO,aAA2D,CAAC;AACrE,CAAC"}

package/dist/core/validation.d.ts

@@ -0,0 +1,16 @@
+import type { CrafterConfig, CrafterSchemas, CrafterErrors } from "../types/config.js";
+import type { AllPossibleErrors } from "../types/errors.js";
+import type { Result } from "../types/result.js";
+import type { InferValidatedInput, InferRawInput, InferValidatedBindArgs, InferRawBindArgs } from "../types/schemas.js";
+/**
+ * Validate input using the configured input schema.
+ */
+export declare function validateInput<TConfig extends CrafterConfig, TSchemas extends CrafterSchemas, TErrors extends CrafterErrors>(schemas: TSchemas, config: TConfig, rawInput: InferRawInput<TSchemas> | undefined): Promise<Result<InferValidatedInput<TSchemas>, AllPossibleErrors<TErrors, TConfig, TSchemas>>>;
+/**
+ * Validate bound arguments using configured bind schemas.
+ */
+export declare function validateBindArgs<TConfig extends CrafterConfig, TSchemas extends CrafterSchemas, TErrors extends CrafterErrors>(schemas: TSchemas, config: TConfig, bindArgs: InferRawBindArgs<TSchemas>): Promise<Result<InferValidatedBindArgs<TSchemas>, AllPossibleErrors<TErrors, TConfig, TSchemas>>>;
+/**
+ * Validate action output using configured output schema.
+ */
+export declare function validateOutput<TConfig extends CrafterConfig, TSchemas extends CrafterSchemas, TErrors extends CrafterErrors, TData>(schemas: TSchemas, config: TConfig, data: TData): Promise<Result<TData, AllPossibleErrors<TErrors, TConfig, TSchemas>>>;

package/dist/core/validation.js

@@ -0,0 +1,70 @@
+import { standardParse } from "../standard-schema.js";
+import { INTERNAL_ERROR_TYPES, EXTERNAL_ERROR_TYPES } from "../types/errors.js";
+import { ok, err } from "../types/result.js";
+import { createValidationError, createInternalLogicError, formatValidationIssues, } from "./errors.js";
+/**
+ * Validate input using the configured input schema.
+ */
+export async function validateInput(schemas, config, rawInput) {
+    if (!schemas.inputSchema) {
+        return ok(undefined);
+    }
+    const result = await standardParse(schemas.inputSchema, rawInput);
+    if (Array.isArray(result.issues) && result.issues.length > 0) {
+        const format = config.validationErrorFormat ?? "flattened";
+        const baseError = formatValidationIssues(result.issues, format);
+        const inputValidationError = createValidationError(EXTERNAL_ERROR_TYPES.INPUT_VALIDATION, "Input validation failed", baseError);
+        return err(inputValidationError);
+    }
+    if (!result.issues && "value" in result) {
+        return ok(result.value);
+    }
+    // Should never happen
+    const logicErr = createInternalLogicError("Unexpected validation state in input validation: neither success nor failure");
+    return err(logicErr);
+}
+/**
+ * Validate bound arguments using configured bind schemas.
+ */
+export async function validateBindArgs(schemas, config, bindArgs) {
+    if (!schemas.bindSchemas) {
+        return ok([]);
+    }
+    const validated = [];
+    for (let i = 0; i < schemas.bindSchemas.length; i++) {
+        const schema = schemas.bindSchemas[i];
+        const arg = bindArgs[i];
+        const result = await standardParse(schema, arg);
+        if (Array.isArray(result.issues) && result.issues.length > 0) {
+            const format = config.validationErrorFormat ?? "flattened";
+            const baseError = formatValidationIssues(result.issues, format);
+            const bindError = createValidationError(EXTERNAL_ERROR_TYPES.BIND_ARGS_VALIDATION, "Bind arguments validation failed", baseError);
+            return err(bindError);
+        }
+        if ("value" in result) {
+            validated.push(result.value);
+        }
+    }
+    return ok(validated);
+}
+/**
+ * Validate action output using configured output schema.
+ */
+export async function validateOutput(schemas, config, data) {
+    if (!schemas.outputSchema) {
+        return ok(data);
+    }
+    const result = await standardParse(schemas.outputSchema, data);
+    if (Array.isArray(result.issues) && result.issues.length > 0) {
+        const format = config.validationErrorFormat ?? "flattened";
+        const baseError = formatValidationIssues(result.issues, format);
+        const outputError = createValidationError(INTERNAL_ERROR_TYPES.OUTPUT_VALIDATION, "Output validation failed", baseError);
+        return err(outputError);
+    }
+    if (!result.issues && "value" in result) {
+        return ok(result.value);
+    }
+    const logicErr = createInternalLogicError("Unexpected validation state in output validation: neither success nor failure");
+    return err(logicErr);
+}
+//# sourceMappingURL=validation.js.map

package/dist/core/validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.js","sourceRoot":"","sources":["../../src/core/validation.ts"],"names":[],"mappings":"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"}

package/dist/error.d.ts

@@ -0,0 +1,16 @@
+import type { CraftedAction } from "./types/actions.js";
+import type { BaseError } from "./types/errors.js";
+import type { InferErrors } from "./types/inference.js";
+/**
+ * Error wrapper that provides standard Error semantics while preserving
+ * the original ActionCraft error data in the cause property.
+ */
+export declare class ActionCraftError<TErrorData extends BaseError = BaseError> extends Error {
+    readonly cause: TErrorData;
+    constructor(errorData: TErrorData);
+}
+/**
+ * Type guard to check if an error is an ActionCraftError with the action's error types.
+ * The action parameter is used purely for type inference.
+ */
+export declare function isActionCraftError<TAction extends CraftedAction<any, any, any, any>>(error: unknown, _action: TAction): error is ActionCraftError<InferErrors<TAction>>;

package/dist/error.js

@@ -0,0 +1,22 @@
+/**
+ * Error wrapper that provides standard Error semantics while preserving
+ * the original ActionCraft error data in the cause property.
+ */
+export class ActionCraftError extends Error {
+    cause;
+    constructor(errorData) {
+        super(`ActionCraft Error: ${errorData.type}${"message" in errorData ? ` - ${errorData.message}` : ""}`);
+        this.name = "ActionCraftError";
+        this.cause = errorData;
+        // Ensure proper prototype chain for instanceof checks
+        Object.setPrototypeOf(this, ActionCraftError.prototype);
+    }
+}
+/**
+ * Type guard to check if an error is an ActionCraftError with the action's error types.
+ * The action parameter is used purely for type inference.
+ */
+export function isActionCraftError(error, _action) {
+    return error instanceof ActionCraftError;
+}
+//# sourceMappingURL=error.js.map

package/dist/error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error.js","sourceRoot":"","sources":["../src/error.ts"],"names":[],"mappings":"AAIA;;;GAGG;AACH,MAAM,OAAO,gBAEX,SAAQ,KAAK;IACY,KAAK,CAAa;IAE3C,YAAY,SAAqB;QAC/B,KAAK,CACH,sBAAsB,SAAS,CAAC,IAAI,GAClC,SAAS,IAAI,SAAS,CAAC,CAAC,CAAC,MAAM,SAAS,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EACvD,EAAE,CACH,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;QAC/B,IAAI,CAAC,KAAK,GAAG,SAAS,CAAC;QAEvB,sDAAsD;QACtD,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,gBAAgB,CAAC,SAAS,CAAC,CAAC;IAC1D,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAIhC,KAAc,EACd,OAAgB;IAEhB,OAAO,KAAK,YAAY,gBAAgB,CAAC;AAC3C,CAAC"}

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,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 { isOk, isErr, ok, err } from "./types/result.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/dist/standard-schema.d.ts

@@ -0,0 +1,71 @@
+/** The Standard Schema interface. */
+export interface StandardSchemaV1<Input = unknown, Output = Input> {
+    /** The Standard Schema properties. */
+    readonly "~standard": StandardSchemaV1.Props<Input, Output>;
+}
+export declare namespace StandardSchemaV1 {
+    /** The Standard Schema properties interface. */
+    interface Props<Input = unknown, Output = Input> {
+        /** The version number of the standard. */
+        readonly version: 1;
+        /** The vendor name of the schema library. */
+        readonly vendor: string;
+        /** Validates unknown input values. */
+        readonly validate: (value: unknown) => Result<Output> | Promise<Result<Output>>;
+        /** Inferred types associated with the schema. */
+        readonly types?: Types<Input, Output> | undefined;
+    }
+    /** The result interface of the validate function. */
+    type Result<Output> = SuccessResult<Output> | FailureResult;
+    /** The result interface if validation succeeds. */
+    interface SuccessResult<Output> {
+        /** The typed output value. */
+        readonly value: Output;
+        /** The non-existent issues. */
+        readonly issues?: undefined;
+    }
+    /** The result interface if validation fails. */
+    interface FailureResult {
+        /** The issues of failed validation. */
+        readonly issues: ReadonlyArray<Issue>;
+    }
+    /** The issue interface of the failure output. */
+    interface Issue {
+        /** The error message of the issue. */
+        readonly message: string;
+        /** The path of the issue, if any. */
+        readonly path?: ReadonlyArray<PropertyKey | PathSegment> | undefined;
+    }
+    /** The path segment interface of the issue. */
+    interface PathSegment {
+        /** The key representing a path segment. */
+        readonly key: PropertyKey;
+    }
+    /** The Standard Schema types interface. */
+    interface Types<Input = unknown, Output = Input> {
+        /** The input type of the schema. */
+        readonly input: Input;
+        /** The output type of the schema. */
+        readonly output: Output;
+    }
+    /** Infers the input type of a Standard Schema. */
+    type InferInput<Schema extends StandardSchemaV1> = NonNullable<Schema["~standard"]["types"]>["input"];
+    /** Infers the output type of a Standard Schema. */
+    type InferOutput<Schema extends StandardSchemaV1> = NonNullable<Schema["~standard"]["types"]>["output"];
+}
+/** Infer the input type of a Standard Schema, or a default type if the schema is undefined. */
+export type InferInputOrDefault<MaybeSchema, Default> = MaybeSchema extends StandardSchemaV1 ? StandardSchemaV1.InferInput<MaybeSchema> : Default;
+/** Infer the output type of a Standard Schema, or a default type if the schema is undefined. */
+export type InferOutputOrDefault<MaybeSchema, Default> = MaybeSchema extends StandardSchemaV1 ? StandardSchemaV1.InferOutput<MaybeSchema> : Default;
+/** Infer the input type of an array of Standard Schemas. */
+export type InferInputArray<Schemas extends readonly StandardSchemaV1[]> = {
+    [K in keyof Schemas]: StandardSchemaV1.InferInput<Schemas[K]>;
+};
+/** Infer the output type of an array of Standard Schemas. */
+export type InferOutputArray<Schemas extends readonly StandardSchemaV1[]> = {
+    [K in keyof Schemas]: StandardSchemaV1.InferOutput<Schemas[K]>;
+};
+/** Helper function to validate input using a Standard Schema. */
+export declare function standardParse<Output>(schema: StandardSchemaV1<unknown, Output>, value: unknown): Promise<StandardSchemaV1.Result<Output>>;
+/** Type guard to check if a value is a Standard Schema. */
+export declare function isStandardSchema(value: unknown): value is StandardSchemaV1;

package/dist/standard-schema.js

@@ -0,0 +1,16 @@
+// ============================================================================
+// RUNTIME HELPERS
+// ============================================================================
+/** Helper function to validate input using a Standard Schema. */
+export async function standardParse(schema, value) {
+    return schema["~standard"].validate(value);
+}
+/** Type guard to check if a value is a Standard Schema. */
+export function isStandardSchema(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        "~standard" in value &&
+        typeof value["~standard"] === "object" &&
+        value["~standard"].version === 1);
+}
+//# sourceMappingURL=standard-schema.js.map

package/dist/standard-schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"standard-schema.js","sourceRoot":"","sources":["../src/standard-schema.ts"],"names":[],"mappings":"AAkGA,+EAA+E;AAC/E,kBAAkB;AAClB,+EAA+E;AAE/E,iEAAiE;AACjE,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,MAAyC,EACzC,KAAc;IAEd,OAAO,MAAM,CAAC,WAAW,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AAC7C,CAAC;AAED,2DAA2D;AAC3D,MAAM,UAAU,gBAAgB,CAAC,KAAc;IAC7C,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACd,WAAW,IAAI,KAAK;QACpB,OAAQ,KAA0B,CAAC,WAAW,CAAC,KAAK,QAAQ;QAC3D,KAA0B,CAAC,WAAW,CAAC,CAAC,OAAO,KAAK,CAAC,CACvD,CAAC;AACJ,CAAC"}

package/dist/types/actions.d.ts

@@ -0,0 +1,120 @@
+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 { Result, Ok, Err } from "./result.js";
+import type { InferValidatedInput, InferRawBindArgs, InferValidatedBindArgs, InferRawInputTuple } from "./schemas.js";
+import type { ApiResult, ActionImplMetadata, StatefulApiResult } from "./shared.js";
+/**
+ * Extracts the success data type from an action implementation 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;
+/**
+ * Parameters passed to action implementation functions.
+ */
+export type ActionImplParams<TConfig extends CrafterConfig, TSchemas extends CrafterSchemas, TErrors extends CrafterErrors, 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>;
+};
+/**
+ * Action implementation 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>;
+/**
+ * Arguments that the action implementation accepts.
+ * Differs based on useActionState configuration.
+ */
+export type InferActionImplArgs<TConfig extends CrafterConfig, TSchemas extends CrafterSchemas, TErrors extends CrafterErrors, 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>>;
+/**
+ * Arguments for stateful actions: bind args, previous state, then input.
+ */
+export type StatefulActionArgs<TConfig extends CrafterConfig, TSchemas extends CrafterSchemas, TErrors extends CrafterErrors, TData> = [
+    ...InferRawBindArgs<TSchemas>,
+    InferPrevStateArg<TConfig, TSchemas, TErrors, TData>,
+    ...InferRawInputTuple<TSchemas>
+];
+/**
+ * Previous state parameter for useActionState.
+ */
+export type InferPrevStateArg<TConfig extends CrafterConfig, TSchemas extends CrafterSchemas, TErrors extends CrafterErrors, TData> = TConfig extends {
+    useActionState: true;
+} ? StatefulApiResult<TData, PossibleErrors<TErrors, TConfig, TSchemas>, InferSerializedSuccessValues<TSchemas>, InferSerializedErrorValues<TSchemas>> : never;
+/**
+ * Extracts object-like types from a union, excluding primitives
+ */
+type _UnionObjectLike<T> = Extract<T, Record<string, unknown>>;
+/**
+ * Excludes iterable types like arrays and FormData
+ */
+type _ExcludeIterable<T> = T extends {
+    [Symbol.iterator](): Iterator<unknown>;
+} ? never : T;
+/**
+ * Gets plain objects only, excluding arrays and iterables
+ */
+type _PlainObjectLike<T> = _ExcludeIterable<_UnionObjectLike<T>>;
+/**
+ * Ensures never types fall back to empty object
+ */
+type _SafePlainObjectLike<T> = [_PlainObjectLike<T>] extends [never] ? Record<string, never> : _PlainObjectLike<T>;
+/**
+ * Checks if a type is exactly unknown
+ */
+type _IsExactlyUnknown<T> = unknown extends T ? [T] extends [unknown] ? true : false : false;
+/**
+ * Converts unknown fields to serialized form values.
+ */
+type _ValuesWithFallback<T> = {
+    [K in keyof T]: _IsExactlyUnknown<T[K]> extends true ? string | string[] | undefined : T[K];
+};
+/**
+ * Form values available when an action succeeds.
+ */
+export type InferSerializedSuccessValues<TSchemas extends CrafterSchemas> = 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 {
+    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>>;
+/**
+ * Arguments for stateless actions: bind args followed by input.
+ */
+export type StatelessActionArgs<TSchemas extends CrafterSchemas> = [
+    ...InferRawBindArgs<TSchemas>,
+    ...InferRawInputTuple<TSchemas>
+];
+/**
+ * Final action function returned by .craft().
+ */
+export type CraftedAction<TConfig extends CrafterConfig, TSchemas extends CrafterSchemas, TErrors extends CrafterErrors, TData> = TConfig extends {
+    useActionState: true;
+} ? StatefulAction<TConfig, TSchemas, TErrors, TData> : StatelessAction<TConfig, TSchemas, TErrors, TData>;
+/**
+ * Result returned when calling a crafted action.
+ */
+export type InferCraftedActionResult<TConfig extends CrafterConfig, TSchemas extends CrafterSchemas, TErrors extends CrafterErrors, TData> = TConfig extends {
+    useActionState: true;
+} ? StatefulApiResult<TData, PossibleErrors<TErrors, TConfig, TSchemas>, InferSerializedSuccessValues<TSchemas>, InferSerializedErrorValues<TSchemas>> : TConfig extends {
+    resultFormat: "functional";
+} ? Result<TData, PossibleErrors<TErrors, TConfig, TSchemas>> : ApiResult<TData, PossibleErrors<TErrors, TConfig, TSchemas>>;
+export {};

package/dist/types/actions.js

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

package/dist/types/actions.js.map

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

package/dist/types/config.d.ts

@@ -0,0 +1,80 @@
+import type { StandardSchemaV1 } from "../standard-schema.js";
+import type { InferCraftedActionResult } from "./actions.js";
+import type { AllPossibleErrors, BaseError, ErrorDefinition } from "./errors.js";
+import type { CallbackMetadata } from "./shared.js";
+/**
+ * Custom logging interface for ActionCraft.
+ */
+export type CrafterLogger = {
+    /** Called when callback functions fail */
+    error?: (message: string, error: unknown) => void;
+    /** Called when ActionCraft detects internal bugs */
+    warn?: (message: string, details?: unknown) => void;
+};
+/**
+ * Configuration options for building actions.
+ */
+export type CrafterConfig = {
+    /**
+     * Result format returned by actions.
+     * "api" returns {success, data/error}, "functional" returns {type, value/error}.
+     * Ignored when useActionState is enabled.
+     */
+    resultFormat?: "api" | "functional";
+    /**
+     * Validation error structure.
+     * "flattened" returns array of {path, message}, "nested" groups by field.
+     */
+    validationErrorFormat?: "flattened" | "nested";
+    /**
+     * Enables React useActionState compatibility.
+     * Action accepts prevState parameter and returns a stateful result.
+     */
+    useActionState?: boolean;
+    /**
+     * Custom handler for unexpected thrown errors.
+     * Transforms exceptions into structured error objects.
+     */
+    handleThrownError?: (error: unknown) => BaseError;
+    /**
+     * Logger for ActionCraft internal events.
+     */
+    logger?: CrafterLogger;
+};
+/**
+ * Schema definitions for validating inputs and outputs.
+ */
+export type CrafterSchemas = {
+    /** Validates input values passed to the action */
+    inputSchema?: StandardSchemaV1;
+    /** Validates success data returned from the action */
+    outputSchema?: StandardSchemaV1;
+    /** Array of schemas for validating bound arguments */
+    bindSchemas?: readonly StandardSchemaV1[];
+};
+/**
+ * Custom error types that actions can return.
+ * Each property is a function that creates a typed error object.
+ */
+export type CrafterErrors = 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> = {
+    /** Called when action fails. */
+    onError?: (params: {
+        error: AllPossibleErrors<TErrors, TConfig, TSchemas>;
+        metadata: CallbackMetadata<TConfig, TSchemas, TErrors, TData>;
+    }) => Promise<void> | void;
+    /** Called when action succeeds. */
+    onSuccess?: (params: {
+        data: TData;
+        metadata: CallbackMetadata<TConfig, TSchemas, TErrors, TData>;
+    }) => Promise<void> | void;
+    /** Called after action finishes, regardless of success or failure. */
+    onSettled?: (params: {
+        result: InferCraftedActionResult<TConfig, TSchemas, TErrors, TData>;
+        metadata: CallbackMetadata<TConfig, TSchemas, TErrors, TData>;
+    }) => Promise<void> | void;
+};

package/dist/types/config.js

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

package/dist/types/config.js.map

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