@nice-code/action 0.0.15

package/build/types/ActionDomain/NiceActionDomain.d.ts

@@ -0,0 +1,67 @@
+import { NiceActionRequester } from "../ActionRequestResponse/ActionRequester/NiceActionRequester";
+import type { NiceActionDomainResponder } from "../ActionRequestResponse/ActionResponder/NiceActionResponder";
+import { NiceAction } from "../NiceAction/NiceAction";
+import { type INiceAction_JsonObject, type INiceActionPrimed_JsonObject, type TNiceActionResponse_JsonObject } from "../NiceAction/NiceAction.types";
+import { NiceActionPrimed } from "../NiceAction/NiceActionPrimed";
+import { NiceActionResponse } from "../NiceAction/NiceActionResponse";
+import type { INiceActionDomain, INiceActionDomainChildOptions, TActionListener, TInferInputFromSchema, TNiceActionDomainChildDef } from "./NiceActionDomain.types";
+export declare class NiceActionDomain<ACT_DOM extends INiceActionDomain = INiceActionDomain> implements INiceActionDomain<ACT_DOM["allDomains"], ACT_DOM["actions"]> {
+    readonly domain: ACT_DOM["domain"];
+    readonly allDomains: ACT_DOM["allDomains"];
+    readonly actions: ACT_DOM["actions"];
+    private _listeners;
+    private _requesters;
+    private _responders;
+    constructor(definition: ACT_DOM);
+    createChildDomain<SUB_DOM extends INiceActionDomainChildOptions>(subDomainDef: SUB_DOM & {
+        [K in Exclude<keyof SUB_DOM, keyof INiceActionDomainChildOptions>]: never;
+    }): NiceActionDomain<TNiceActionDomainChildDef<ACT_DOM, SUB_DOM>>;
+    primeUnknown(actionId: ACT_DOM["allDomains"][number], input: unknown): NiceActionPrimed<ACT_DOM, string, ACT_DOM["actions"][string]>;
+    primeAction<ID extends keyof ACT_DOM["actions"] & string>(id: ID, input: TInferInputFromSchema<ACT_DOM["actions"][ID]>["Input"]): NiceActionPrimed<ACT_DOM, ID, ACT_DOM["actions"][ID]>;
+    action<ID extends keyof ACT_DOM["actions"] & string>(id: ID, hydrationData?: Pick<INiceAction_JsonObject<ACT_DOM, ID>, "cuid" | "timeCreated">): NiceAction<ACT_DOM, ID, ACT_DOM["actions"][ID]>;
+    isExactActionDomain<ID extends keyof ACT_DOM["actions"] & string>(action: unknown): action is NiceActionPrimed<ACT_DOM, ID, ACT_DOM["actions"][ID]>;
+    matchAction<ID extends keyof ACT_DOM["actions"] & string>(action: unknown, id: ID): NiceActionPrimed<ACT_DOM, ID, ACT_DOM["actions"][ID]> | null;
+    /**
+     * Add an observer that is called after every action dispatched through this domain.
+     * Returns an unsubscribe function — call it to remove the listener.
+     */
+    addActionListener(listener: TActionListener): () => void;
+    _dispatchAction<P extends NiceActionPrimed<ACT_DOM, string, ACT_DOM["actions"][string]>>(primed: P, envId?: string): Promise<unknown>;
+    private _withValidatedInput;
+    /**
+     * Reconstruct a NiceActionPrimed from its serialized wire format.
+     * Runs the schema's deserializeInput if a custom serialization was defined.
+     */
+    hydratePrimed<P extends INiceActionPrimed_JsonObject>(serialized: P): NiceActionPrimed<ACT_DOM, keyof ACT_DOM["actions"] & string, ACT_DOM["actions"][P["id"] & keyof ACT_DOM["actions"]]>;
+    /**
+     * Reconstruct a NiceActionResponse from its serialized wire format.
+     * The result is loosely typed — `result.error` is `NiceError<TUnknownNiceErrorDef>`.
+     * Use `handleWith` / `forDomain` / `isExact` to route errors on the receiving end.
+     */
+    hydrateResponse<R extends TNiceActionResponse_JsonObject>(serialized: R): NiceActionResponse<ACT_DOM, keyof ACT_DOM["actions"] & string, ACT_DOM["actions"][R["id"] & keyof ACT_DOM["actions"]]>;
+    /**
+     * Register a `NiceActionRequester` on this domain.
+     *
+     * Pass `options.envId` to register under a named environment — useful when multiple
+     * execution environments (e.g. worker, main thread) share the same domain definition.
+     * Named requesters are targeted by passing the same `envId` to `action.execute(input, envId)`.
+     *
+     * Omit `envId` to register the default requester, used when no `envId` is passed to `execute`.
+     * Throws `environment_already_registered` / `domain_action_requester_conflict` if already taken.
+     */
+    setActionRequester(handler?: NiceActionRequester, options?: {
+        envId?: string;
+    }): NiceActionRequester;
+    /**
+     * Register a resolver as the fallback execution path for this domain.
+     *
+     * When no handler is set (or no envId-matching handler), the domain falls back to the
+     * resolver — calling `_resolvePrimed` directly, without re-serializing the input.
+     *
+     * Pass `options.envId` to register under a named environment.
+     * Throws `environment_already_registered` if the envId (or default) is already taken.
+     */
+    registerResponder(resolver: NiceActionDomainResponder<ACT_DOM>, options?: {
+        envId?: string;
+    }): this;
+}

package/build/types/ActionDomain/NiceActionDomain.types.d.ts

@@ -0,0 +1,79 @@
+import type { NiceActionRequester } from "../ActionRequestResponse/ActionRequester/NiceActionRequester";
+import type { NiceActionSchema } from "../ActionSchema/NiceActionSchema";
+import type { INiceActionErrorDeclaration, TTransportedValue } from "../ActionSchema/NiceActionSchema.types";
+import type { NiceActionPrimed } from "../NiceAction/NiceActionPrimed";
+export type MaybePromise<T> = T | Promise<T>;
+export type TPossibleDomainId = string;
+export type TPossibleDomainIdList = [TPossibleDomainId, ...TPossibleDomainId[]];
+export type TNiceActionDomainSchema = Record<string, NiceActionSchema<TTransportedValue<any, any>, TTransportedValue<any, any>, readonly INiceActionErrorDeclaration<any, any>[]>>;
+/**
+ * Data shape for a domain — used for construction and as the type-level schema carrier.
+ * Does NOT include class methods.
+ */
+export interface INiceActionDomain<IDS extends TPossibleDomainIdList = TPossibleDomainIdList, SCH extends TNiceActionDomainSchema = TNiceActionDomainSchema> {
+    domain: IDS[0];
+    allDomains: IDS;
+    actions: SCH;
+}
+/**
+ * Structural interface implemented by `NiceActionDomainResolver`.
+ * Used by `NiceActionDomain` to avoid a circular import with the concrete class.
+ *
+ * `_resolvePrimed` is the inline dispatch path — calls the registered fn directly
+ * without re-serializing/deserializing. Errors from the fn propagate naturally.
+ */
+export interface INiceActionDomainChildOptions<ERR_DOMAIN extends string = string, SCHEMA extends TNiceActionDomainSchema = TNiceActionDomainSchema> {
+    domain: ERR_DOMAIN;
+    actions: SCHEMA;
+}
+export type TNiceActionDomainChildDef<PARENT_DEF extends INiceActionDomain, SUB extends INiceActionDomainChildOptions> = {
+    domain: SUB["domain"];
+    allDomains: [SUB["domain"], ...PARENT_DEF["allDomains"]];
+    actions: SUB["actions"];
+};
+export type TInferInputFromSchema<SCH> = SCH extends NiceActionSchema<infer IN, any, any> ? {
+    Input: IN[0];
+    SerdeInput: IN[1];
+} : never;
+export type TInferOutputFromSchema<SCH> = SCH extends NiceActionSchema<any, infer OUT, any> ? {
+    Output: OUT[0];
+    SerdeOutput: OUT[1];
+} : never;
+/**
+ * Handler registered via forDomain.
+ *
+ * `act.input` is typed as the union of input types for every action in `ACT_DOM`,
+ * and `act.coreAction` carries the matching schema — the same narrowing you get
+ * from `forActionIds` over all action IDs in the domain.
+ */
+export type TActionHandlerForDomain<ACT_DOM extends INiceActionDomain> = (action: NiceActionPrimed<ACT_DOM, keyof ACT_DOM["actions"] & string, ACT_DOM["actions"][keyof ACT_DOM["actions"] & string]>) => MaybePromise<unknown>;
+/**
+ * Handler registered via forActionId — receives a specific action ID, with
+ * the primed action's input narrowed to that ID's schema.
+ */
+export type TActionIdHandlerForDomain<ACT_DOM extends INiceActionDomain, ID extends keyof ACT_DOM["actions"] & string> = (action: NiceActionPrimed<ACT_DOM, ID, ACT_DOM["actions"][ID]>) => MaybePromise<unknown>;
+/**
+ * Observer called after each action is dispatched.
+ * Return value is ignored. Use for logging, metrics, tracing, etc.
+ */
+export type TActionListener = (action: NiceActionPrimed<any, any, any>) => MaybePromise<void>;
+/**
+ * Broad handler signature used internally for storage and dispatch.
+ * Public-facing registration methods use narrower types (`TActionHandlerForDomain`,
+ * `TActionIdHandlerForDomain`); they are cast to this for storage.
+ */
+export type TBroadActionRequester<P extends NiceActionPrimed<any, any, any>> = (action: P) => MaybePromise<unknown>;
+/**
+ * A single case in a `NiceActionRequester`.
+ *
+ * Construct via `forDomain` / `forActionId` / `forActionIds` — do not build directly.
+ */
+export interface IActionCase<P extends NiceActionPrimed<any, any, any> = NiceActionPrimed<any, any, any>> {
+    readonly _matcher: (action: P) => boolean;
+    readonly _requester: TBroadActionRequester<P>;
+}
+export interface IActionHandlerWithId {
+    id: string;
+    handler: NiceActionRequester;
+}
+export type TDomainActionId<DOM extends INiceActionDomain> = keyof DOM["actions"] & string;

package/build/types/ActionDomain/createActionDomain.d.ts

@@ -0,0 +1,5 @@
+import { NiceActionDomain } from "./NiceActionDomain";
+import type { INiceActionDomain } from "./NiceActionDomain.types";
+export declare const createActionDomain: <ACT_DOM extends Omit<INiceActionDomain, "allDomains">>(definition: ACT_DOM) => NiceActionDomain<ACT_DOM & {
+    allDomains: [string];
+}>;

package/build/types/ActionRequestResponse/ActionRequester/NiceActionRequester.d.ts

@@ -0,0 +1,31 @@
+import type { NiceActionDomain } from "../../ActionDomain/NiceActionDomain";
+import type { INiceActionDomain, TActionHandlerForDomain, TActionIdHandlerForDomain, TBroadActionRequester } from "../../ActionDomain/NiceActionDomain.types";
+import type { NiceActionPrimed } from "../../NiceAction/NiceActionPrimed";
+export declare class NiceActionRequester {
+    private cases;
+    private _defaultRequester?;
+    handleAction(action: NiceActionPrimed<any, any, any>): Promise<unknown>;
+    /**
+     * Register a handler that fires for **any** action whose domain matches `domain`.
+     * `act.input` is typed as the union of input types for all actions in `domain`.
+     * First matching case wins.
+     */
+    forDomain<FOR_DOM extends INiceActionDomain>(domain: NiceActionDomain<FOR_DOM>, handler: TActionHandlerForDomain<FOR_DOM>): this;
+    /**
+     * Register a handler that fires only for the specific action `id`.
+     * The handler's `action.input` is narrowed to the schema for that ID.
+     * First matching case wins.
+     */
+    forActionId<ACT_DOM extends INiceActionDomain, ID extends keyof ACT_DOM["actions"] & string>(domain: NiceActionDomain<ACT_DOM>, id: ID, handler: TActionIdHandlerForDomain<ACT_DOM, ID>): this;
+    /**
+     * Register a handler that fires for any action whose id is in `ids`.
+     * The handler's `action.input` is narrowed to the union of those IDs' schemas.
+     * First matching case wins.
+     */
+    forActionIds<ACT_DOM extends INiceActionDomain, IDS extends ReadonlyArray<keyof ACT_DOM["actions"] & string>>(domain: NiceActionDomain<ACT_DOM>, ids: IDS, handler: TActionIdHandlerForDomain<ACT_DOM, IDS[number]>): this;
+    /**
+     * Register a fallback handler that fires when no other case matches.
+     * Only one default handler can be registered — calling this twice replaces the previous one.
+     */
+    setDefaultHandler(handler: TBroadActionRequester<NiceActionPrimed<any, any, any>>): this;
+}

package/build/types/ActionRequestResponse/ActionResponder/NiceActionResponder.d.ts

@@ -0,0 +1,49 @@
+import type { NiceActionDomain } from "../../ActionDomain/NiceActionDomain";
+import type { INiceActionDomain } from "../../ActionDomain/NiceActionDomain.types";
+import type { INiceActionPrimed_JsonObject } from "../../NiceAction/NiceAction.types";
+import type { NiceActionPrimed } from "../../NiceAction/NiceActionPrimed";
+import { NiceActionResponse } from "../../NiceAction/NiceActionResponse";
+import type { TActionResponderFn } from "./NiceActionResponder.types";
+export declare class NiceActionDomainResponder<DOM extends INiceActionDomain> {
+    private _domain;
+    private _responders;
+    constructor(domain: NiceActionDomain<DOM>);
+    get domainId(): DOM["domain"];
+    /**
+     * Register a responder function for a specific action ID in this domain.
+     * The input and output types are inferred from the domain's schema for that action ID.
+     *
+     * @example
+     * ```ts
+     * createDomainResponder(myDomain)
+     *   .resolve("myAction", async (input) => {
+     *     return { result: await db.query(input.id) };
+     *   });
+     * ```
+     */
+    resolveAction<ID extends keyof DOM["actions"] & string>(actionId: ID, fn: TActionResponderFn<DOM["actions"][ID]>): this;
+    /**
+     * Internal: called by `NiceActionDomain._dispatchAction` when this resolver is registered
+     * as the domain's fallback. Calls the registered fn directly — no re-serialization.
+     * Errors from the fn propagate naturally (consistent with handler dispatch).
+     *
+     * Throws `resolver_action_not_registered` if no fn was registered for the action ID.
+     */
+    _resolvePrimed(primed: NiceActionPrimed<any, any, any>): Promise<unknown>;
+    /**
+     * Internal: hydrate the wire action, call the registered resolver fn, and return a
+     * `NiceActionResponse`. Any error thrown by the resolver fn is caught and wrapped in the
+     * response as `{ ok: false }` via `castNiceError`.
+     *
+     * Throws `resolver_action_not_registered` if no fn was registered for the action ID.
+     * Throws `hydration_*` errors (from `NiceActionDomain.hydrateAction`) if the action ID
+     * is not part of this domain's schema.
+     */
+    _dispatch<P extends INiceActionPrimed_JsonObject<DOM, string>>(wire: P): Promise<NiceActionResponse<DOM, P["id"], DOM["actions"][P["id"]]>>;
+}
+/**
+ * Create a `NiceActionDomainResolver` for `domain`.
+ * Chain `.resolve(actionId, fn)` calls to register typed resolver functions,
+ * then pass the resolver to `createResolverEnvironment`.
+ */
+export declare function createDomainResolver<DOM extends INiceActionDomain>(domain: NiceActionDomain<DOM>): NiceActionDomainResponder<DOM>;

package/build/types/ActionRequestResponse/ActionResponder/NiceActionResponder.types.d.ts

@@ -0,0 +1,7 @@
+import type { MaybePromise, TInferInputFromSchema, TInferOutputFromSchema } from "../../ActionDomain/NiceActionDomain.types";
+import type { NiceActionSchema } from "../../ActionSchema/NiceActionSchema";
+/**
+ * A resolver function for a specific action.
+ * Receives the deserialized input and must return (or resolve to) the deserialized output.
+ */
+export type TActionResponderFn<SCH extends NiceActionSchema<any, any, any>> = (input: TInferInputFromSchema<SCH>["Input"]) => MaybePromise<TInferOutputFromSchema<SCH>["Output"]>;

package/build/types/ActionRequestResponse/ActionResponder/NiceActionResponderEnvironment.d.ts

@@ -0,0 +1,42 @@
+import type { INiceActionDomain } from "../../ActionDomain/NiceActionDomain.types";
+import type { INiceActionPrimed_JsonObject, TNiceActionResponse_JsonObject } from "../../NiceAction/NiceAction.types";
+import type { NiceActionDomainResponder } from "./NiceActionResponder";
+export declare class NiceActionResponderEnvironment {
+    private _resolvers;
+    constructor(resolvers: NiceActionDomainResponder<INiceActionDomain>[]);
+    /**
+     * Dispatch a serialized action to the matching domain resolver.
+     *
+     * Finds the resolver by `wire.domain`, hydrates the action, calls the registered fn,
+     * and returns the serialized response as `ISerializedNiceActionResponse`.
+     *
+     * Throws `resolver_domain_not_registered` if no resolver was registered for the domain.
+     *
+     * @example
+     * ```ts
+     * // server handler
+     * app.post("/actions", async (req, res) => {
+     *   const response = await env.dispatch(req.body);
+     *   res.json(response);
+     * });
+     * ```
+     */
+    dispatch(wire: INiceActionPrimed_JsonObject<INiceActionDomain, string>): Promise<TNiceActionResponse_JsonObject>;
+}
+/**
+ * Create a `NiceActionResponderEnvironment` from one or more domain resolvers.
+ * The environment routes incoming serialized actions to the correct resolver by domain ID.
+ *
+ * @example
+ * ```ts
+ * const env = createResponderEnvironment([
+ *   createDomainResolver(paymentDomain)
+ *     .resolve("chargeCard", async (input) => { ... }),
+ *   createDomainResolver(authDomain)
+ *     .resolve("login", async (input) => { ... }),
+ * ]);
+ *
+ * const serializedResponse = await env.dispatch(incomingWire);
+ * ```
+ */
+export declare function createResponderEnvironment(resolvers: NiceActionDomainResponder<INiceActionDomain<any, any>>[]): NiceActionResponderEnvironment;

package/build/types/ActionSchema/NiceActionSchema.d.ts

@@ -0,0 +1,101 @@
+import { err_cast_not_nice, type INiceErrorDefinedProps, type InferNiceError, type JSONSerializableValue, type NiceErrorDefined } from "@nice-code/error";
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+import type { INiceActionErrorDeclaration, TInferDeclaredErrors, TNiceActonSchemaInputOptions, TTransportedValue } from "./NiceActionSchema.types";
+export declare class NiceActionSchema<INPUT extends TTransportedValue<any, any> = TTransportedValue<any, any>, OUTPUT extends TTransportedValue<any, any> = TTransportedValue<any>, ERRORS extends readonly INiceActionErrorDeclaration<any, any>[] = readonly []> {
+    private _errorDeclarations;
+    private inputOptions;
+    private outputOptions;
+    get inputSchema(): StandardSchemaV1;
+    get outputSchema(): StandardSchemaV1;
+    /**
+     * Declare the input schema (JSON-native or with explicit SERDE type param).
+     * For non-JSON-native inputs, prefer the 3-argument form below to avoid
+     * needing explicit type parameters.
+     */
+    input<VS extends StandardSchemaV1 = StandardSchemaV1, SERDE_IN extends JSONSerializableValue = never>(options: TNiceActonSchemaInputOptions<VS, SERDE_IN>): NiceActionSchema<TTransportedValue<StandardSchemaV1.InferInput<VS>, SERDE_IN>, OUTPUT, ERRORS>;
+    /**
+     * Declare the input schema with serialization via sequential parameters.
+     * TypeScript infers SERDE_IN from `serialize`'s return type (left-to-right),
+     * then provides it as the contextual type for `deserialize`'s parameter —
+     * no explicit type parameters or casts needed.
+     */
+    input<VS extends StandardSchemaV1, SERDE_IN extends JSONSerializableValue>(options: {
+        schema: VS;
+    }, serialize: (raw: StandardSchemaV1.InferInput<VS>) => SERDE_IN, deserialize: (serde: SERDE_IN) => StandardSchemaV1.InferInput<VS>): NiceActionSchema<TTransportedValue<StandardSchemaV1.InferInput<VS>, SERDE_IN>, OUTPUT, ERRORS>;
+    /**
+     * Declare the output schema (JSON-native or with explicit SERDE type param).
+     * For non-JSON-native outputs, prefer the 3-argument form below to avoid
+     * needing explicit type parameters.
+     */
+    output<VS extends StandardSchemaV1 = StandardSchemaV1, SERDE_OUT extends JSONSerializableValue = JSONSerializableValue>(options: TNiceActonSchemaInputOptions<VS, SERDE_OUT>): NiceActionSchema<INPUT, TTransportedValue<StandardSchemaV1.InferInput<VS>, SERDE_OUT>, ERRORS>;
+    /**
+     * Declare the output schema with serialization via sequential parameters.
+     * TypeScript infers SERDE_OUT from `serialize`'s return type (left-to-right),
+     * then provides it as the contextual type for `deserialize`'s parameter —
+     * no explicit type parameters or casts needed.
+     */
+    output<VS extends StandardSchemaV1, SERDE_OUT extends JSONSerializableValue>(options: {
+        schema: VS;
+    }, serialize: (raw: StandardSchemaV1.InferInput<VS>) => SERDE_OUT, deserialize: (serde: SERDE_OUT) => StandardSchemaV1.InferInput<VS>): NiceActionSchema<INPUT, TTransportedValue<StandardSchemaV1.InferInput<VS>, SERDE_OUT>, ERRORS>;
+    /**
+     * Declare that this action may throw any error from `domain`.
+     * `TInferActionError` will include `NiceError<DEF, keyof schema>` in its union.
+     */
+    throws<ERR_DEF extends INiceErrorDefinedProps>(domain: NiceErrorDefined<ERR_DEF>): NiceActionSchema<INPUT, OUTPUT, readonly [...ERRORS, INiceActionErrorDeclaration<ERR_DEF, keyof ERR_DEF["schema"] & string>]>;
+    /**
+     * Declare that this action may throw only the listed `ids` from `domain`.
+     * `TInferActionError` will include `NiceError<DEF, IDS[number]>` narrowed to those IDs.
+     */
+    throws<ERR_DEF extends INiceErrorDefinedProps, IDS extends ReadonlyArray<keyof ERR_DEF["schema"] & string>>(domain: NiceErrorDefined<ERR_DEF>, ids: IDS): NiceActionSchema<INPUT, OUTPUT, readonly [...ERRORS, INiceActionErrorDeclaration<ERR_DEF, IDS[number] & string>]>;
+    /**
+     * Serialize raw input to a JSON-serializable form.
+     * Uses the schema's serialization.serialize if defined; otherwise the input
+     * is already JSON-native and is returned as-is.
+     */
+    serializeInput(rawInput: INPUT[0]): JSONSerializableValue;
+    /**
+     * Deserialize a JSON value back into the raw input type.
+     * Uses serialization.deserialize if defined; otherwise the value is cast
+     * directly (it's already in the correct shape).
+     */
+    deserializeInput(serialized: JSONSerializableValue): INPUT[0];
+    /**
+     * Validate raw input against the schema defined via `.input({ schema })`.
+     * Throws `action_input_validation_failed` if validation fails.
+     * Returns the validated (and possibly coerced) value on success.
+     * If no input schema was declared, the value is passed through as-is.
+     */
+    validateInput(value: unknown, meta: {
+        domain: string;
+        actionId: string;
+    }): Promise<INPUT[0]>;
+    /**
+     * Serialize raw output to a JSON-serializable form.
+     */
+    serializeOutput(rawOutput: OUTPUT[0]): OUTPUT[1];
+    /**
+     * Deserialize a JSON value back into the raw output type.
+     */
+    deserializeOutput(serialized: OUTPUT[1]): OUTPUT[0];
+}
+/**
+ * Infers the full error union that a `NiceActionSchema` may throw.
+ *
+ * Includes every declared `NiceError<DEF, IDS>` from `.throws()` calls, plus
+ * `InferNiceError<typeof err_cast_not_nice>` as the always-present fallback
+ * for any unrecognized thrown value.
+ *
+ * @example
+ * ```ts
+ * const payAction = action()
+ *   .input({ schema: v.object({ amount: v.number() }) })
+ *   .throws(err_payment)
+ *   .throws(err_auth, ["unauthenticated"] as const);
+ *
+ * type PayError = TInferActionError<typeof payAction>;
+ * // → NiceError<ErrPaymentDef, keyof ErrPaymentSchema>
+ * //   | NiceError<ErrAuthDef, "unauthenticated">
+ * //   | NiceError<ErrCastNotNiceDef, keyof ErrCastNotNiceSchema>
+ * ```
+ */
+export type TInferActionError<SCH> = SCH extends NiceActionSchema<any, any, infer DECLS> ? DECLS extends readonly INiceActionErrorDeclaration[] ? TInferDeclaredErrors<DECLS> | InferNiceError<typeof err_cast_not_nice> : InferNiceError<typeof err_cast_not_nice> : never;

package/build/types/ActionSchema/NiceActionSchema.types.d.ts

@@ -0,0 +1,32 @@
+import { type INiceErrorDefinedProps, type JSONSerializableValue, type NiceErrorDefined } from "@nice-code/error";
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+export type TNiceActionJsonSerializableValue = JSONSerializableValue;
+export type TTransportedValue<RAW_VAL = never, SERDE_VAL extends TNiceActionJsonSerializableValue = never> = RAW_VAL extends TNiceActionJsonSerializableValue ? [RAW_VAL] | [RAW_VAL, SERDE_VAL] : [RAW_VAL, SERDE_VAL];
+export type TNiceActionSerializationDefinition<RAW_VAL = any, SERDE_VAL extends TNiceActionJsonSerializableValue = TNiceActionJsonSerializableValue> = {
+    serialize: (value: RAW_VAL) => SERDE_VAL;
+    deserialize: (value: SERDE_VAL) => RAW_VAL;
+};
+export type TNiceActonSchemaInputOptions<VS extends StandardSchemaV1 = StandardSchemaV1, SERDE_IN extends TNiceActionJsonSerializableValue = TNiceActionJsonSerializableValue> = StandardSchemaV1.InferInput<VS> extends TNiceActionJsonSerializableValue ? {
+    schema: VS;
+    serialization?: TNiceActionSerializationDefinition<StandardSchemaV1.InferInput<VS>, SERDE_IN>;
+} : {
+    schema: VS;
+    serialization: TNiceActionSerializationDefinition<StandardSchemaV1.InferInput<VS>, SERDE_IN>;
+};
+/**
+ * One error declaration on an action schema.
+ * `IDS` is the subset of error IDs that may be thrown. When the full
+ * `keyof schema` union is used it means any ID from the domain can be thrown.
+ *
+ * Build via `action().throws(domain)` or `action().throws(domain, ids)`.
+ */
+export interface INiceActionErrorDeclaration<ERR_DEF extends INiceErrorDefinedProps = INiceErrorDefinedProps, IDS extends keyof ERR_DEF["schema"] & string = keyof ERR_DEF["schema"] & string> {
+    readonly _domain: NiceErrorDefined<ERR_DEF>;
+    /** The specific IDs constrained for this declaration, or `undefined` meaning the full domain. */
+    readonly _ids: ReadonlyArray<IDS & string> | undefined;
+}
+/**
+ * Union of all `NiceError` types that can be thrown from a tuple of error declarations.
+ * Distributes over each declaration and unions the results.
+ */
+export type TInferDeclaredErrors<DECLS extends readonly INiceActionErrorDeclaration[]> = TInferErrorFromDeclaration<DECLS[number]>;

package/build/types/ActionSchema/action.d.ts

@@ -0,0 +1,2 @@
+import { NiceActionSchema } from "./NiceActionSchema";
+export declare const action: () => NiceActionSchema;

package/build/types/NiceAction/ActionSchema/NiceActionSchema.d.ts

@@ -0,0 +1,99 @@
+import { err_cast_not_nice, type INiceErrorDefinedProps, type InferNiceError, type JSONSerializableValue, type NiceErrorDefined } from "@nice-code/error";
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+import type { INiceActionErrorDeclaration, TInferDeclaredErrors, TNiceActonSchemaInputOptions, TTransportedValue } from "./NiceActionSchema.types";
+export declare class NiceActionSchema<INPUT extends TTransportedValue<any, any> = TTransportedValue<any, any>, OUTPUT extends TTransportedValue<any, any> = TTransportedValue<any>, ERRORS extends readonly INiceActionErrorDeclaration<any, any>[] = readonly []> {
+    private _errorDeclarations;
+    private inputOptions;
+    private outputOptions;
+    /**
+     * Declare the input schema (JSON-native or with explicit SERDE type param).
+     * For non-JSON-native inputs, prefer the 3-argument form below to avoid
+     * needing explicit type parameters.
+     */
+    input<VS extends StandardSchemaV1 = StandardSchemaV1, SERDE_IN extends JSONSerializableValue = never>(options: TNiceActonSchemaInputOptions<VS, SERDE_IN>): NiceActionSchema<TTransportedValue<StandardSchemaV1.InferInput<VS>, SERDE_IN>, OUTPUT, ERRORS>;
+    /**
+     * Declare the input schema with serialization via sequential parameters.
+     * TypeScript infers SERDE_IN from `serialize`'s return type (left-to-right),
+     * then provides it as the contextual type for `deserialize`'s parameter —
+     * no explicit type parameters or casts needed.
+     */
+    input<VS extends StandardSchemaV1, SERDE_IN extends JSONSerializableValue>(options: {
+        schema: VS;
+    }, serialize: (raw: StandardSchemaV1.InferInput<VS>) => SERDE_IN, deserialize: (serde: SERDE_IN) => StandardSchemaV1.InferInput<VS>): NiceActionSchema<TTransportedValue<StandardSchemaV1.InferInput<VS>, SERDE_IN>, OUTPUT, ERRORS>;
+    /**
+     * Declare the output schema (JSON-native or with explicit SERDE type param).
+     * For non-JSON-native outputs, prefer the 3-argument form below to avoid
+     * needing explicit type parameters.
+     */
+    output<VS extends StandardSchemaV1 = StandardSchemaV1, SERDE_OUT extends JSONSerializableValue = JSONSerializableValue>(options: TNiceActonSchemaInputOptions<VS, SERDE_OUT>): NiceActionSchema<INPUT, TTransportedValue<StandardSchemaV1.InferInput<VS>, SERDE_OUT>, ERRORS>;
+    /**
+     * Declare the output schema with serialization via sequential parameters.
+     * TypeScript infers SERDE_OUT from `serialize`'s return type (left-to-right),
+     * then provides it as the contextual type for `deserialize`'s parameter —
+     * no explicit type parameters or casts needed.
+     */
+    output<VS extends StandardSchemaV1, SERDE_OUT extends JSONSerializableValue>(options: {
+        schema: VS;
+    }, serialize: (raw: StandardSchemaV1.InferInput<VS>) => SERDE_OUT, deserialize: (serde: SERDE_OUT) => StandardSchemaV1.InferInput<VS>): NiceActionSchema<INPUT, TTransportedValue<StandardSchemaV1.InferInput<VS>, SERDE_OUT>, ERRORS>;
+    /**
+     * Declare that this action may throw any error from `domain`.
+     * `TInferActionError` will include `NiceError<DEF, keyof schema>` in its union.
+     */
+    throws<ERR_DEF extends INiceErrorDefinedProps>(domain: NiceErrorDefined<ERR_DEF>): NiceActionSchema<INPUT, OUTPUT, readonly [...ERRORS, INiceActionErrorDeclaration<ERR_DEF, keyof ERR_DEF["schema"] & string>]>;
+    /**
+     * Declare that this action may throw only the listed `ids` from `domain`.
+     * `TInferActionError` will include `NiceError<DEF, IDS[number]>` narrowed to those IDs.
+     */
+    throws<ERR_DEF extends INiceErrorDefinedProps, IDS extends ReadonlyArray<keyof ERR_DEF["schema"] & string>>(domain: NiceErrorDefined<ERR_DEF>, ids: IDS): NiceActionSchema<INPUT, OUTPUT, readonly [...ERRORS, INiceActionErrorDeclaration<ERR_DEF, IDS[number] & string>]>;
+    /**
+     * Serialize raw input to a JSON-serializable form.
+     * Uses the schema's serialization.serialize if defined; otherwise the input
+     * is already JSON-native and is returned as-is.
+     */
+    serializeInput(rawInput: INPUT[0]): JSONSerializableValue;
+    /**
+     * Deserialize a JSON value back into the raw input type.
+     * Uses serialization.deserialize if defined; otherwise the value is cast
+     * directly (it's already in the correct shape).
+     */
+    deserializeInput(serialized: JSONSerializableValue): INPUT[0];
+    /**
+     * Validate raw input against the schema defined via `.input({ schema })`.
+     * Throws `action_input_validation_failed` if validation fails.
+     * Returns the validated (and possibly coerced) value on success.
+     * If no input schema was declared, the value is passed through as-is.
+     */
+    validateInput(value: unknown, meta: {
+        domain: string;
+        actionId: string;
+    }): Promise<INPUT[0]>;
+    /**
+     * Serialize raw output to a JSON-serializable form.
+     */
+    serializeOutput(rawOutput: OUTPUT[0]): OUTPUT[1];
+    /**
+     * Deserialize a JSON value back into the raw output type.
+     */
+    deserializeOutput(serialized: OUTPUT[1]): OUTPUT[0];
+}
+/**
+ * Infers the full error union that a `NiceActionSchema` may throw.
+ *
+ * Includes every declared `NiceError<DEF, IDS>` from `.throws()` calls, plus
+ * `InferNiceError<typeof err_cast_not_nice>` as the always-present fallback
+ * for any unrecognized thrown value.
+ *
+ * @example
+ * ```ts
+ * const payAction = action()
+ *   .input({ schema: v.object({ amount: v.number() }) })
+ *   .throws(err_payment)
+ *   .throws(err_auth, ["unauthenticated"] as const);
+ *
+ * type PayError = TInferActionError<typeof payAction>;
+ * // → NiceError<ErrPaymentDef, keyof ErrPaymentSchema>
+ * //   | NiceError<ErrAuthDef, "unauthenticated">
+ * //   | NiceError<ErrCastNotNiceDef, keyof ErrCastNotNiceSchema>
+ * ```
+ */
+export type TInferActionError<SCH> = SCH extends NiceActionSchema<any, any, infer DECLS> ? DECLS extends readonly INiceActionErrorDeclaration[] ? TInferDeclaredErrors<DECLS> | InferNiceError<typeof err_cast_not_nice> : InferNiceError<typeof err_cast_not_nice> : never;

package/build/types/NiceAction/ActionSchema/NiceActionSchema.types.d.ts

@@ -0,0 +1,31 @@
+import { type INiceErrorDefinedProps, type JSONSerializableValue, type NiceErrorDefined } from "@nice-code/error";
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+export type TTransportedValue<RAW_VAL = never, SERDE_VAL extends JSONSerializableValue = never> = RAW_VAL extends JSONSerializableValue ? [RAW_VAL] | [RAW_VAL, SERDE_VAL] : [RAW_VAL, SERDE_VAL];
+export type TNiceActionSerializationDefinition<RAW_VAL = any, SERDE_VAL extends JSONSerializableValue = JSONSerializableValue> = {
+    serialize: (value: RAW_VAL) => SERDE_VAL;
+    deserialize: (value: SERDE_VAL) => RAW_VAL;
+};
+export type TNiceActonSchemaInputOptions<VS extends StandardSchemaV1 = StandardSchemaV1, SERDE_IN extends JSONSerializableValue = JSONSerializableValue> = StandardSchemaV1.InferInput<VS> extends JSONSerializableValue ? {
+    schema: VS;
+    serialization?: TNiceActionSerializationDefinition<StandardSchemaV1.InferInput<VS>, SERDE_IN>;
+} : {
+    schema: VS;
+    serialization: TNiceActionSerializationDefinition<StandardSchemaV1.InferInput<VS>, SERDE_IN>;
+};
+/**
+ * One error declaration on an action schema.
+ * `IDS` is the subset of error IDs that may be thrown. When the full
+ * `keyof schema` union is used it means any ID from the domain can be thrown.
+ *
+ * Build via `action().throws(domain)` or `action().throws(domain, ids)`.
+ */
+export interface INiceActionErrorDeclaration<ERR_DEF extends INiceErrorDefinedProps = INiceErrorDefinedProps, IDS extends keyof ERR_DEF["schema"] & string = keyof ERR_DEF["schema"] & string> {
+    readonly _domain: NiceErrorDefined<ERR_DEF>;
+    /** The specific IDs constrained for this declaration, or `undefined` meaning the full domain. */
+    readonly _ids: ReadonlyArray<IDS & string> | undefined;
+}
+/**
+ * Union of all `NiceError` types that can be thrown from a tuple of error declarations.
+ * Distributes over each declaration and unions the results.
+ */
+export type TInferDeclaredErrors<DECLS extends readonly INiceActionErrorDeclaration[]> = TInferErrorFromDeclaration<DECLS[number]>;

package/build/types/NiceAction/ActionSchema/NiceActionSchemaBuilder.d.ts

@@ -0,0 +1 @@
+export {};

package/build/types/NiceAction/ActionSchema/action.d.ts

@@ -0,0 +1,2 @@
+import { NiceActionSchema } from "./NiceActionSchema";
+export declare const action: () => NiceActionSchema;

package/build/types/NiceAction/NiceAction.d.ts

@@ -0,0 +1,64 @@
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+import type { NiceActionDomain } from "../ActionDomain/NiceActionDomain";
+import type { INiceActionDomain, TInferInputFromSchema, TInferOutputFromSchema } from "../ActionDomain/NiceActionDomain.types";
+import type { TInferActionError } from "../ActionSchema/NiceActionSchema";
+import { EActionState, type INiceAction, type INiceAction_JsonObject, type INiceActionPrimed_JsonObject, type NiceActionResult } from "./NiceAction.types";
+import { NiceActionPrimed } from "./NiceActionPrimed";
+import { NiceActionResponse } from "./NiceActionResponse";
+export declare class NiceAction<DOM extends INiceActionDomain, ID extends keyof DOM["actions"] & string, SCH extends DOM["actions"][ID]> implements INiceAction<DOM, ID> {
+    readonly actionDomain: NiceActionDomain<DOM>;
+    readonly schema: SCH;
+    readonly id: ID;
+    readonly type = EActionState.empty;
+    readonly domain: DOM["domain"];
+    readonly allDomains: DOM["allDomains"];
+    readonly _actionDomain: NiceActionDomain<DOM>;
+    readonly timeCreated: number;
+    readonly cuid: string;
+    constructor(actionDomain: NiceActionDomain<DOM>, schema: SCH, id: ID, hydrationData?: Pick<INiceAction_JsonObject<DOM, ID>, "cuid" | "timeCreated">);
+    /**
+     * Serialize this action definition (without input) to a JSON-safe object.
+     * Useful for describing which action will be invoked without yet having input.
+     */
+    toJsonObject(): INiceAction_JsonObject<DOM, ID>;
+    toValidationSchema(): StandardSchemaV1;
+    is(action: unknown): action is NiceActionPrimed<DOM, ID, SCH>;
+    prime(input: TInferInputFromSchema<SCH>["Input"], hydrationData?: Pick<INiceActionPrimed_JsonObject<DOM, ID>, "timePrimed">): NiceActionPrimed<DOM, ID, SCH>;
+    /**
+     * Prime this action with input and immediately execute it through the domain handler or resolver.
+     *
+     * Pass `envId` to target a specific named handler/resolver registered on the domain via
+     * `setActionHandler(h, { envId })` or `registerResolver(r, { envId })`.
+     * Throws `action_environment_not_found` if no handler or resolver with that id exists.
+     */
+    execute(input: TInferInputFromSchema<SCH>["Input"], envId?: string): Promise<TInferOutputFromSchema<SCH>["Output"]>;
+    /**
+     * Like `execute`, but catches thrown errors and returns a `NiceActionResult` discriminated union
+     * instead of propagating. On success: `{ ok: true, value }`. On failure: `{ ok: false, error }`.
+     *
+     * The `error` type is the union of all `NiceError` types declared via `.throws()` on the schema,
+     * plus `InferNiceError<typeof err_cast_not_nice>` as the always-present fallback.
+     *
+     * @example
+     * ```ts
+     * const result = await domain.action("getUser").executeSafe({ userId: "123" });
+     * if (!result.ok) {
+     *   result.error.handleWith([
+     *     forDomain(err_auth, (h) => res.status(401).end()),
+     *   ]);
+     *   return;
+     * }
+     * console.log(result.value);
+     * ```
+     */
+    executeSafe(input: TInferInputFromSchema<SCH>["Input"], envId?: string): Promise<NiceActionResult<TInferOutputFromSchema<SCH>["Output"], TInferActionError<SCH>>>;
+    /**
+     * Prime this action with input, execute it, and return a `NiceActionResponse`
+     * that carries both the original primed action (domain + actionId + input) and
+     * the result (`{ ok: true, value }` or `{ ok: false, error }`).
+     *
+     * The response can be serialized for cross-boundary transport via `toJsonObject()`.
+     * Reconstruct on the receiving end with `domain.hydrateResponse(wire)`.
+     */
+    executeToResponse(input: TInferInputFromSchema<SCH>["Input"], envId?: string): Promise<NiceActionResponse<DOM, ID, SCH>>;
+}