@nice-code/action 0.0.20 → 0.1.0

package/build/types/ActionRuntimeEnvironment/utils/getAssumedRuntimeEnvironment.d.ts

@@ -0,0 +1,2 @@
+import type { IRuntimeMeta } from "../ActionRuntimeEnvironment.types";
+export declare const getAssumedRuntimeInfo: () => IRuntimeMeta;

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

@@ -1,18 +1,18 @@
-import { err_cast_not_nice, type INiceErrorDefinedProps, type InferNiceError, type JSONSerializableValue, type NiceErrorDefined } from "@nice-code/error";
+import { err_cast_not_nice, type INiceErrorDomainProps, type InferNiceError, type JSONSerializableValue, type NiceErrorDomain } 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 []> {
+import type { INiceActionErrorDeclaration, TInferDeclaredErrors, TNiceActonSchemaOptions, TTransportedValue } from "./NiceActionSchema.types";
+export declare class NiceActionSchema<INPUT extends TTransportedValue<any, any> = never, OUTPUT extends TTransportedValue<any, any> = never, ERRORS extends readonly INiceActionErrorDeclaration<any, any>[] = readonly []> {
     private _errorDeclarations;
     private inputOptions;
     private outputOptions;
-    get inputSchema(): StandardSchemaV1;
-    get outputSchema(): StandardSchemaV1;
+    get inputSchema(): StandardSchemaV1 | undefined;
+    get outputSchema(): StandardSchemaV1 | undefined;
     /**
      * 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>;
+    input<VS extends StandardSchemaV1 = StandardSchemaV1, SERDE_IN extends JSONSerializableValue = never>(options: TNiceActonSchemaOptions<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),
@@ -27,7 +27,7 @@ export declare class NiceActionSchema<INPUT extends TTransportedValue<any, any>
      * 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>;
+    output<VS extends StandardSchemaV1 = StandardSchemaV1, SERDE_OUT extends JSONSerializableValue = JSONSerializableValue>(options: TNiceActonSchemaOptions<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),
@@ -41,12 +41,12 @@ export declare class NiceActionSchema<INPUT extends TTransportedValue<any, any>
      * 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>]>;
+    throws<ERR_DEF extends INiceErrorDomainProps>(domain: NiceErrorDomain<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>]>;
+    throws<ERR_DEF extends INiceErrorDomainProps, IDS extends ReadonlyArray<keyof ERR_DEF["schema"] & string>>(domain: NiceErrorDomain<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
@@ -68,7 +68,11 @@ export declare class NiceActionSchema<INPUT extends TTransportedValue<any, any>
     validateInput(value: unknown, meta: {
         domain: string;
         actionId: string;
-    }): Promise<INPUT[0]>;
+    }): INPUT[0];
+    validateOutput(value: unknown, meta: {
+        domain: string;
+        actionId: string;
+    }): OUTPUT[0];
     /**
      * Serialize raw output to a JSON-serializable form.
      */

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

@@ -1,4 +1,4 @@
-import { type INiceErrorDefinedProps, type JSONSerializableValue, type NiceErrorDefined } from "@nice-code/error";
+import { type INiceErrorDomainProps, type JSONSerializableValue, type NiceErrorDomain } 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];
@@ -6,7 +6,7 @@ export type TNiceActionSerializationDefinition<RAW_VAL = any, SERDE_VAL extends
     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 ? {
+export type TNiceActonSchemaOptions<VS extends StandardSchemaV1 = StandardSchemaV1, SERDE_IN extends TNiceActionJsonSerializableValue = TNiceActionJsonSerializableValue> = StandardSchemaV1.InferInput<VS> extends TNiceActionJsonSerializableValue ? {
     schema: VS;
     serialization?: TNiceActionSerializationDefinition<StandardSchemaV1.InferInput<VS>, SERDE_IN>;
 } : {
@@ -20,8 +20,8 @@ export type TNiceActonSchemaInputOptions<VS extends StandardSchemaV1 = StandardS
  *
  * 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>;
+export interface INiceActionErrorDeclaration<ERR_DEF extends INiceErrorDomainProps = INiceErrorDomainProps, IDS extends keyof ERR_DEF["schema"] & string = keyof ERR_DEF["schema"] & string> {
+    readonly _domain: NiceErrorDomain<ERR_DEF>;
     /** The specific IDs constrained for this declaration, or `undefined` meaning the full domain. */
     readonly _ids: ReadonlyArray<IDS & string> | undefined;
 }

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

@@ -0,0 +1,26 @@
+import type { INiceActionDomain, MaybePromise } from "../../ActionDomain/NiceActionDomain.types";
+import type { INiceAction } from "../NiceAction.types";
+import type { TNarrowActionType } from "../NiceActionCombined.types";
+type TMatchHandler<A extends INiceAction<any>> = (action: A) => MaybePromise<void>;
+type THandlerForId<ACT extends INiceAction<any>> = (action: ACT) => MaybePromise<void>;
+declare class MatchAction<ACT extends INiceAction<any>> {
+    readonly action: ACT;
+    private _entries;
+    private _otherwise?;
+    constructor(action: ACT);
+    with<D extends INiceActionDomain, ID extends keyof D["actions"] & string>(opts: {
+        domain: D;
+        id: ID;
+        handler: THandlerForId<TNarrowActionType<ACT, D, ID>>;
+    }): this;
+    with<D extends INiceActionDomain>(opts: {
+        domain: D;
+        handler: TMatchHandler<TNarrowActionType<ACT, D, keyof D["actions"] & string>>;
+    }): this;
+    otherwise(handler: TMatchHandler<ACT>): this;
+    private _findMatch;
+    run(): boolean;
+    runAsync(): Promise<boolean>;
+}
+export declare const matchAction: <ACT extends INiceAction<any>>(action: ACT) => MatchAction<ACT>;
+export {};

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

@@ -1,18 +1,20 @@
-import type { StandardSchemaV1 } from "@standard-schema/spec";
+import type { JSONSerializableValue } from "@nice-code/error";
 import type { NiceActionDomain } from "../ActionDomain/NiceActionDomain";
 import type { INiceActionDomain, TInferInputFromSchema, TInferOutputFromSchema } from "../ActionDomain/NiceActionDomain.types";
+import type { IActionMetaInputs } from "../ActionRuntimeEnvironment/ActionHandler/ActionHandler.types";
 import type { TInferActionError } from "../ActionSchema/NiceActionSchema";
-import { EActionState, type INiceAction, type INiceAction_JsonObject, type INiceActionPrimed_JsonObject, type NiceActionResult } from "./NiceAction.types";
+import { EActionState } from "./NiceAction.enums";
+import { type INiceAction, type INiceAction_JsonObject, type INiceActionPrimed_JsonObject, type TNiceActionResult } from "./NiceAction.types";
+import type { TNarrowActionType } from "./NiceActionCombined.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> {
+export declare class NiceAction<DOM extends INiceActionDomain, ID extends keyof DOM["actions"] & string = keyof DOM["actions"] & string, SCH extends DOM["actions"][ID] = DOM["actions"][ID]> implements INiceAction<DOM, ID> {
     readonly actionDomain: NiceActionDomain<DOM>;
     readonly schema: SCH;
-    readonly id: ID;
     readonly type = EActionState.empty;
+    readonly id: ID;
     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">);
@@ -21,20 +23,14 @@ export declare class NiceAction<DOM extends INiceActionDomain, ID extends keyof
      * 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>;
+    toJsonString(): string;
+    toHttpResponse(): Response;
+    is<ACT extends INiceAction<any>>(action: ACT | unknown | null | undefined): action is TNarrowActionType<ACT, DOM, ID>;
     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"]>;
+    execute(input: TInferInputFromSchema<SCH>["Input"], meta?: IActionMetaInputs): 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 }`.
+     * instead of propagating. On success: `{ ok: true, output }`. 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.
@@ -48,17 +44,21 @@ export declare class NiceAction<DOM extends INiceActionDomain, ID extends keyof
      *   ]);
      *   return;
      * }
-     * console.log(result.value);
+     * console.log(result.output); // typed as the action's OUTPUT
      * ```
      */
-    executeSafe(input: TInferInputFromSchema<SCH>["Input"], envId?: string): Promise<NiceActionResult<TInferOutputFromSchema<SCH>["Output"], TInferActionError<SCH>>>;
+    executeSafe(input: TInferInputFromSchema<SCH>["Input"], meta?: IActionMetaInputs): Promise<TNiceActionResult<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 result (`{ ok: true, output }` 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>>;
+    executeToResponse(input: TInferInputFromSchema<SCH>["Input"], meta?: IActionMetaInputs): Promise<NiceActionResponse<DOM, ID, SCH>>;
+    deserializeInput(serialized: JSONSerializableValue): TInferInputFromSchema<SCH>["Input"];
+    serializeInput(raw: TInferInputFromSchema<SCH>["Input"]): JSONSerializableValue;
+    validateInput(input: unknown): TInferInputFromSchema<SCH>["Input"];
+    validateOutput(output: unknown): TInferOutputFromSchema<SCH>["Output"];
 }

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

@@ -0,0 +1,5 @@
+export declare enum EActionState {
+    empty = "empty",
+    primed = "primed",
+    resolved = "resolved"
+}

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

@@ -1,12 +1,9 @@
 import type { INiceErrorJsonObject } from "@nice-code/error";
 import type { INiceActionDomain, TInferInputFromSchema, TInferOutputFromSchema } from "../ActionDomain/NiceActionDomain.types";
-export declare enum EActionState {
-    empty = "empty",
-    primed = "primed",
-    response = "response"
-}
-export interface INiceAction<DOM extends INiceActionDomain, ID extends keyof DOM["actions"] & string> {
+import type { EActionState } from "./NiceAction.enums";
+export interface INiceAction<DOM extends INiceActionDomain, ID extends keyof DOM["actions"] & string = keyof DOM["actions"] & string> {
     id: ID;
+    type: EActionState;
     domain: DOM["domain"];
     allDomains: DOM["allDomains"];
     schema: DOM["actions"][ID];
@@ -35,7 +32,7 @@ export type INiceActionPrimed_JsonObject<DOM extends INiceActionDomain = INiceAc
 /**
  * Return type of `executeSafe` — a discriminated union of success and failure.
  *
- * - `{ ok: true; value: OUT }` — the action completed and returned `OUT`
+ * - `{ ok: true; output: OUT }` — the action completed and returned `OUT`
  * - `{ ok: false; error: ERR }` — the action threw; `ERR` is the declared error union
  *
  * @example
@@ -47,10 +44,10 @@ export type INiceActionPrimed_JsonObject<DOM extends INiceActionDomain = INiceAc
  *   ]);
  *   return;
  * }
- * console.log(result.value); // typed as the action's OUTPUT
+ * console.log(result.output); // typed as the action's OUTPUT
  * ```
  */
-export type NiceActionResult<OUT, ERR> = {
+export type TNiceActionResult<OUT, ERR> = {
     ok: true;
     output: OUT;
 } | {
@@ -67,7 +64,7 @@ export type NiceActionResult<OUT, ERR> = {
  * Reconstructed by `NiceActionDomain.hydrateResponse()`.
  */
 export interface INiceActionResponse_JsonObject_Base<DOM extends INiceActionDomain, ID extends keyof DOM["actions"] & string> extends Omit<INiceActionPrimed_JsonObject<DOM, ID>, "type"> {
-    type: EActionState.response;
+    type: EActionState.resolved;
     timeResponded: number;
 }
 export type INiceActionResponse_JsonObject_Success<DOM extends INiceActionDomain = INiceActionDomain, ID extends keyof DOM["actions"] & string = keyof DOM["actions"] & string> = INiceActionResponse_JsonObject_Base<DOM, ID> & {

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

@@ -0,0 +1,10 @@
+import type { INiceActionDomain } from "../ActionDomain/NiceActionDomain.types";
+import type { NiceAction } from "./NiceAction";
+import type { INiceAction } from "./NiceAction.types";
+import type { NiceActionPrimed } from "./NiceActionPrimed";
+import type { NiceActionResponse } from "./NiceActionResponse";
+export type TNiceActionInstanceAny<DOM extends INiceActionDomain, ID extends keyof DOM["actions"] & string = keyof DOM["actions"] & string> = NiceAction<DOM, ID, DOM["actions"][ID]> | NiceActionPrimed<DOM, ID, DOM["actions"][ID]> | NiceActionResponse<DOM, ID, DOM["actions"][ID]>;
+export type TNarrowActionType<ACT extends INiceAction<any>, D extends INiceActionDomain, ID extends keyof D["actions"] & string = keyof D["actions"] & string> = ACT extends NiceActionResponse<any> ? NiceActionResponse<D, ID> : ACT extends NiceActionPrimed<any> ? NiceActionPrimed<D, ID> : ACT extends NiceAction<any> ? NiceAction<D, ID> : INiceAction<D, ID>;
+export type TDistributedDomainActions<ACT extends INiceAction<any>, DOM extends INiceActionDomain> = {
+    [ID in keyof DOM["actions"] & string]: TNarrowActionType<ACT, DOM, ID>;
+}[keyof DOM["actions"] & string];

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

@@ -1,17 +1,25 @@
 import type { INiceActionDomain, TInferInputFromSchema, TInferOutputFromSchema } from "../ActionDomain/NiceActionDomain.types";
+import type { IActionMetaInputs } from "../ActionRuntimeEnvironment/ActionHandler/ActionHandler.types";
+import type { IRuntimeEnvironmentMeta } from "../ActionRuntimeEnvironment/ActionRuntimeEnvironment.types";
 import type { TInferActionError } from "../ActionSchema/NiceActionSchema";
 import type { NiceAction } from "./NiceAction";
-import { EActionState, type INiceAction, type INiceActionPrimed_JsonObject, type NiceActionResult, type TNiceActionResponse_JsonObject } from "./NiceAction.types";
+import { EActionState } from "./NiceAction.enums";
+import { type INiceAction, type INiceActionPrimed_JsonObject, type TNiceActionResponse_JsonObject, type TNiceActionResult } from "./NiceAction.types";
 import { NiceActionResponse } from "./NiceActionResponse";
-export declare class NiceActionPrimed<DOM extends INiceActionDomain, ID extends keyof DOM["actions"] & string, SCH extends DOM["actions"][ID]> implements Omit<INiceAction<DOM, ID>, "schema" | "cuid" | "timeCreated"> {
+export declare class NiceActionPrimed<DOM extends INiceActionDomain, ID extends keyof DOM["actions"] & string = keyof DOM["actions"] & string, SCH extends DOM["actions"][ID] = DOM["actions"][ID]> implements INiceAction<DOM, ID> {
     readonly coreAction: NiceAction<DOM, ID, SCH>;
-    readonly input: TInferInputFromSchema<SCH>["Input"];
+    private _input;
     readonly type = EActionState.primed;
     readonly domain: DOM["domain"];
     readonly allDomains: DOM["allDomains"];
     readonly id: ID;
     readonly timePrimed: number;
-    constructor(coreAction: NiceAction<DOM, ID, SCH>, input: TInferInputFromSchema<SCH>["Input"], hydrationData?: Pick<INiceActionPrimed_JsonObject<DOM, ID>, "timePrimed">);
+    readonly cuid: string;
+    readonly schema: SCH;
+    readonly timeCreated: number;
+    constructor(coreAction: NiceAction<DOM, ID, SCH>, _input: TInferInputFromSchema<SCH>["Input"], hydrationData?: Pick<INiceActionPrimed_JsonObject<DOM, ID>, "timePrimed">);
+    get input(): TInferInputFromSchema<SCH>["Input"];
+    getEnvironmentMeta(): IRuntimeEnvironmentMeta;
     /**
      * Serialize this primed action to a JSON-safe wire format.
      * The input is passed through the schema's serialize function if one is defined,
@@ -19,41 +27,17 @@ export declare class NiceActionPrimed<DOM extends INiceActionDomain, ID extends
      */
     toJsonObject(): INiceActionPrimed_JsonObject<DOM, ID>;
     toJsonString(): string;
-    setOutput(output: TInferOutputFromSchema<SCH>["Output"]): NiceActionResponse<DOM, ID, SCH>;
-    /**
-     * Process a wire response returned by a remote `NiceActionResponderEnvironment`.
-     *
-     * Deserializes the output using the schema's deserialization if defined, and throws
-     * the error (via `castNiceError`) if the response indicates failure.
-     *
-     * Intended for use inside `NiceActionRequester` handlers that receive a
-     * `TNiceActionResponse_JsonObject` from a network call, so the caller of `execute()`
-     * always gets the raw output type without manually deserializing.
-     *
-     * @example
-     * ```ts
-     * dom.setActionRequester().forDomain(dom, async (act) => {
-     *   const wire = await fetch("/api/actions", {
-     *     method: "POST",
-     *     body: JSON.stringify(act.toJsonObject()),
-     *   }).then((r) => r.json());
-     *   return act.processResponse(wire);
-     * });
-     * ```
-     */
-    processResponse(wire: TNiceActionResponse_JsonObject): TInferOutputFromSchema<SCH>["Output"];
-    /**
-     * Re-execute this primed action through the domain handler or resolver.
-     * Useful for deferred or cross-environment execution of a hydrated action.
-     *
-     * Pass `envId` to target a specific named handler/resolver on the domain.
-     */
-    execute(envId?: string): Promise<TInferOutputFromSchema<SCH>["Output"]>;
+    hydratePrimeJson(wire: INiceActionPrimed_JsonObject<DOM, ID>): NiceActionPrimed<DOM, ID, SCH>;
+    hydrateResponseJson(wire: TNiceActionResponse_JsonObject<DOM, ID>): NiceActionResponse<DOM, ID, SCH>;
+    errorResponse(err: TInferActionError<SCH>): NiceActionResponse<DOM, ID, SCH>;
+    toHttpResponse(): Response;
+    setResponse(...args: [TInferOutputFromSchema<SCH>["Output"]] extends [never] ? [] : [output: TInferOutputFromSchema<SCH>["Output"]]): NiceActionResponse<DOM, ID, SCH>;
+    execute(meta?: IActionMetaInputs): 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 }`.
+     * instead of propagating. On success: `{ ok: true, output }`. On failure: `{ ok: false, error }`.
      *
      * Mirrors `NiceAction.executeSafe` — useful when re-executing a hydrated primed action.
      */
-    executeSafe(envId?: string): Promise<NiceActionResult<TInferOutputFromSchema<SCH>["Output"], TInferActionError<SCH>>>;
+    executeSafe(meta?: IActionMetaInputs): Promise<TNiceActionResult<TInferOutputFromSchema<SCH>["Output"], TInferActionError<SCH>>>;
 }

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

@@ -1,17 +1,23 @@
 import type { INiceActionDomain, TInferOutputFromSchema } from "../ActionDomain/NiceActionDomain.types";
+import type { IRuntimeEnvironmentMeta } from "../ActionRuntimeEnvironment/ActionRuntimeEnvironment.types";
 import type { TInferActionError } from "../ActionSchema/NiceActionSchema";
 import type { NiceAction } from "./NiceAction";
-import { EActionState, type INiceAction, type NiceActionResult, type TNiceActionResponse_JsonObject } from "./NiceAction.types";
+import { EActionState } from "./NiceAction.enums";
+import { type INiceAction, type TNiceActionResponse_JsonObject, type TNiceActionResult } from "./NiceAction.types";
 import { NiceActionPrimed } from "./NiceActionPrimed";
-export declare class NiceActionResponse<DOM extends INiceActionDomain, ID extends keyof DOM["actions"] & string, SCH extends DOM["actions"][ID]> implements Omit<INiceAction<DOM, ID>, "schema" | "cuid" | "timeCreated"> {
-    readonly type = EActionState.response;
+export declare class NiceActionResponse<DOM extends INiceActionDomain, ID extends keyof DOM["actions"] & string = keyof DOM["actions"] & string, SCH extends DOM["actions"][ID] = DOM["actions"][ID]> implements INiceAction<DOM, ID> {
+    readonly type = EActionState.resolved;
     readonly domain: DOM["domain"];
     readonly allDomains: DOM["allDomains"];
     readonly id: ID;
     readonly primed: NiceActionPrimed<DOM, ID, SCH>;
-    readonly result: NiceActionResult<TInferOutputFromSchema<SCH>["Output"], TInferActionError<SCH>>;
+    readonly result: TNiceActionResult<TInferOutputFromSchema<SCH>["Output"], TInferActionError<SCH>>;
     readonly timeResponded: number;
-    constructor(primed: NiceActionPrimed<DOM, ID, SCH>, result: NiceActionResult<TInferOutputFromSchema<SCH>["Output"], TInferActionError<SCH>>, hydrationData?: Pick<TNiceActionResponse_JsonObject<DOM, ID>, "timeResponded">);
+    readonly cuid: string;
+    readonly schema: SCH;
+    readonly timeCreated: number;
+    constructor(primed: NiceActionPrimed<DOM, ID, SCH>, result: TNiceActionResult<TInferOutputFromSchema<SCH>["Output"], TInferActionError<SCH>>, hydrationData?: Pick<TNiceActionResponse_JsonObject<DOM, ID>, "timeResponded">);
+    getEnvironmentMeta(): IRuntimeEnvironmentMeta;
     /**
      * Serialize this response to a JSON-safe wire format.
      *
@@ -21,6 +27,10 @@ export declare class NiceActionResponse<DOM extends INiceActionDomain, ID extend
      */
     toJsonObject(): TNiceActionResponse_JsonObject;
     toJsonString(): string;
+    hydrateResponseJson(wire: TNiceActionResponse_JsonObject<DOM, ID>): NiceActionResponse<DOM, ID, SCH>;
+    toHttpResponse({ useErrorStatus }?: {
+        useErrorStatus?: boolean;
+    }): Response;
 }
 /**
  * Reconstruct a loosely-typed NiceActionResponse from its wire format.

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

@@ -0,0 +1,3 @@
+import type { INiceAction } from "../NiceAction.types";
+import type { TNarrowActionType } from "../NiceActionCombined.types";
+export declare function isNiceActionInstance<ACT extends INiceAction<any>>(value: unknown | ACT): value is TNarrowActionType<ACT, any, any>;

package/build/types/errors/err_nice_action.d.ts

@@ -1,18 +1,22 @@
-import type { EActionState } from "../NiceAction/NiceAction.types";
+import type { EActionState } from "../NiceAction/NiceAction.enums";
 export declare enum EErrId_NiceAction {
     action_id_not_in_domain = "action_id_not_in_domain",
-    domain_action_requester_conflict = "domain_action_handler_conflict",
+    domain_already_exists_in_hierarchy = "domain_already_exists_in_hierarchy",
     domain_no_handler = "domain_no_handler",
     hydration_domain_mismatch = "hydration_domain_mismatch",
     hydration_action_state_mismatch = "hydration_action_state_mismatch",
     hydration_action_id_not_found = "hydration_action_id_not_found",
-    resolver_domain_not_registered = "resolver_domain_not_registered",
-    resolver_action_not_registered = "resolver_action_not_registered",
-    action_environment_not_found = "action_environment_not_found",
+    no_action_execution_handler = "no_action_execution_handler",
+    wire_action_not_primed_or_response = "wire_action_not_primed_or_response",
+    wire_not_action_data = "wire_not_action_data",
+    action_tag_handler_not_found = "action_tag_handler_not_found",
     environment_already_registered = "environment_already_registered",
-    action_input_validation_failed = "action_input_validation_failed"
+    action_input_validation_failed = "action_input_validation_failed",
+    action_input_validation_promise = "action_input_validation_promise",
+    action_output_validation_failed = "action_output_validation_failed",
+    action_output_validation_promise = "action_output_validation_promise"
 }
-export declare const err_nice_action: import("@nice-code/error").NiceErrorDefined<{
+export declare const err_nice_action: import("@nice-code/error").NiceErrorDomain<{
     domain: string;
     allDomains: [string, "err_nice"];
     schema: {
@@ -20,8 +24,10 @@ export declare const err_nice_action: import("@nice-code/error").NiceErrorDefine
             domain: string;
             actionId: string;
         }, import("@nice-code/error").JSONSerializableValue>;
-        domain_action_handler_conflict: import("@nice-code/error").INiceErrorIdMetadata<{
+        domain_already_exists_in_hierarchy: import("@nice-code/error").INiceErrorIdMetadata<{
             domain: string;
+            allParentDomains: string[];
+            parentDomain: string;
         }, import("@nice-code/error").JSONSerializableValue>;
         domain_no_handler: import("@nice-code/error").INiceErrorIdMetadata<{
             domain: string;
@@ -38,25 +44,41 @@ export declare const err_nice_action: import("@nice-code/error").NiceErrorDefine
             domain: string;
             actionId: string;
         }, import("@nice-code/error").JSONSerializableValue>;
-        resolver_domain_not_registered: import("@nice-code/error").INiceErrorIdMetadata<{
+        no_action_execution_handler: import("@nice-code/error").INiceErrorIdMetadata<{
             domain: string;
+            actionId: string;
         }, import("@nice-code/error").JSONSerializableValue>;
-        resolver_action_not_registered: import("@nice-code/error").INiceErrorIdMetadata<{
+        wire_action_not_primed_or_response: import("@nice-code/error").INiceErrorIdMetadata<{
             domain: string;
             actionId: string;
+            actionState: EActionState | undefined;
         }, import("@nice-code/error").JSONSerializableValue>;
-        action_environment_not_found: import("@nice-code/error").INiceErrorIdMetadata<{
+        wire_not_action_data: import("@nice-code/error").INiceErrorIdMetadata<any, import("@nice-code/error").JSONSerializableValue>;
+        action_tag_handler_not_found: import("@nice-code/error").INiceErrorIdMetadata<{
             domain: string;
-            envId: string;
+            matchTag: string;
         }, import("@nice-code/error").JSONSerializableValue>;
         environment_already_registered: import("@nice-code/error").INiceErrorIdMetadata<{
             domain: string;
-            envId: string;
+            matchTag: string;
         }, import("@nice-code/error").JSONSerializableValue>;
         action_input_validation_failed: import("@nice-code/error").INiceErrorIdMetadata<{
             domain: string;
             actionId: string;
             validationMessage: string;
         }, import("@nice-code/error").JSONSerializableValue>;
+        action_input_validation_promise: import("@nice-code/error").INiceErrorIdMetadata<{
+            domain: string;
+            actionId: string;
+        }, import("@nice-code/error").JSONSerializableValue>;
+        action_output_validation_failed: import("@nice-code/error").INiceErrorIdMetadata<{
+            domain: string;
+            actionId: string;
+            validationMessage: string;
+        }, import("@nice-code/error").JSONSerializableValue>;
+        action_output_validation_promise: import("@nice-code/error").INiceErrorIdMetadata<{
+            domain: string;
+            actionId: string;
+        }, import("@nice-code/error").JSONSerializableValue>;
     };
 }>;

package/build/types/index.d.ts

@@ -1,17 +1,25 @@
-export { createActionDomain } from "./ActionDomain/createActionDomain";
+export { createActionRootDomain } from "./ActionDomain/helpers/createRootActionDomain";
 export { NiceActionDomain } from "./ActionDomain/NiceActionDomain";
-export type { INiceActionDomain, INiceActionDomainChildOptions, MaybePromise, TActionHandlerForDomain, TActionIdHandlerForDomain, TActionListener, TDomainActionId, TInferInputFromSchema, TInferOutputFromSchema, TNiceActionDomainChildDef, TNiceActionDomainSchema, TPossibleDomainId, TPossibleDomainIdList, } from "./ActionDomain/NiceActionDomain.types";
-export { NiceActionRequester } from "./ActionRequestResponse/ActionRequester/NiceActionRequester";
-export { createDomainResolver, NiceActionDomainResponder, } from "./ActionRequestResponse/ActionResponder/NiceActionResponder";
-export type { TActionResponderFn } from "./ActionRequestResponse/ActionResponder/NiceActionResponder.types";
-export { createResponderEnvironment, NiceActionResponderEnvironment, } from "./ActionRequestResponse/ActionResponder/NiceActionResponderEnvironment";
+export type { INiceActionDomain, INiceActionDomainChildOptions, MaybePromise, TDomainActionId, TInferInputFromSchema, TInferOutputFromSchema, TNiceActionDomainChildDef, TNiceActionDomainSchema, TPossibleDomainId, TPossibleDomainIdList, } from "./ActionDomain/NiceActionDomain.types";
+export { ActionConnect } from "./ActionRuntimeEnvironment/ActionConnect/ActionConnect";
+export * from "./ActionRuntimeEnvironment/ActionConnect/ActionConnect.types";
+export { ConnectionConfig as Transport } from "./ActionRuntimeEnvironment/ActionConnect/ConnectionConfig/ConnectionConfig";
+export * from "./ActionRuntimeEnvironment/ActionConnect/err_nice_connect";
+export * from "./ActionRuntimeEnvironment/ActionConnect/Transport/err_nice_transport";
+export * from "./ActionRuntimeEnvironment/ActionConnect/Transport/err_nice_transport_ws";
+export { ActionHandler, createHandler, } from "./ActionRuntimeEnvironment/ActionHandler/ActionHandler";
+export type { IActionHandlerInputs, TAtLeastOne, TExecutionAndResponseHandlers, THandleActionExecutionFn, THandleActionResponseFn, THandleActionResult, } from "./ActionRuntimeEnvironment/ActionHandler/ActionHandler.types";
+export { ActionRuntimeEnvironment, createActionRuntime, } from "./ActionRuntimeEnvironment/ActionRuntimeEnvironment";
+export type { IActionRuntimeEnvironment_JsonObject } from "./ActionRuntimeEnvironment/ActionRuntimeEnvironment.types";
 export { action } from "./ActionSchema/action";
 export type { TInferActionError } from "./ActionSchema/NiceActionSchema";
 export { NiceActionSchema } from "./ActionSchema/NiceActionSchema";
-export type { TNiceActionSerializationDefinition, TNiceActonSchemaInputOptions, TTransportedValue, } from "./ActionSchema/NiceActionSchema.types";
+export type { TNiceActionSerializationDefinition, TNiceActonSchemaOptions as TNiceActonSchemaInputOptions, TTransportedValue, } from "./ActionSchema/NiceActionSchema.types";
 export { EErrId_NiceAction, err_nice_action } from "./errors/err_nice_action";
+export { matchAction } from "./NiceAction/MatchAction/MatchAction";
 export { NiceAction } from "./NiceAction/NiceAction";
-export type { INiceAction, INiceAction_JsonObject, INiceActionPrimed_JsonObject, NiceActionResult, TNiceActionResponse_JsonObject, } from "./NiceAction/NiceAction.types";
+export { EActionState } from "./NiceAction/NiceAction.enums";
+export type { INiceAction, INiceAction_JsonObject, INiceActionPrimed_JsonObject, TNiceActionResponse_JsonObject, TNiceActionResult as NiceActionResult, } from "./NiceAction/NiceAction.types";
 export { NiceActionPrimed } from "./NiceAction/NiceActionPrimed";
 export { NiceActionResponse } from "./NiceAction/NiceActionResponse";
 export * from "./utils/isActionResponseJsonObject";

package/build/types/react-query/index.d.ts

@@ -0,0 +1,73 @@
+import type { QueryKey, UseMutationOptions, UseMutationResult, UseQueryOptions, UseQueryResult } from "@tanstack/react-query";
+import type { INiceActionDomain, TInferInputFromSchema, TInferOutputFromSchema } from "../ActionDomain/NiceActionDomain.types";
+import type { IActionMetaInputs } from "../ActionRuntimeEnvironment/ActionHandler/ActionHandler.types";
+import type { TInferActionError } from "../ActionSchema/NiceActionSchema";
+import type { NiceAction } from "../NiceAction/NiceAction";
+/**
+ * Builds a stable TanStack Query key for a Nice Action.
+ *
+ * Overload 1 (no input) — returns a prefix key suitable for `queryClient.invalidateQueries`,
+ * which will match every cached query for this action regardless of input.
+ *
+ * Overload 2 (with input) — returns the exact key used by `useNiceQuery` for the given input.
+ * Use this when you need to read or invalidate a single cached result.
+ *
+ * @example
+ * // Invalidate all cached results for an action
+ * queryClient.invalidateQueries({ queryKey: niceActionQueryKey(domain.action("getUser")) });
+ *
+ * // Invalidate a specific cached result
+ * queryClient.invalidateQueries({ queryKey: niceActionQueryKey(domain.action("getUser"), { userId: "123" }) });
+ */
+export declare function niceActionQueryKey<DOM extends INiceActionDomain, ID extends keyof DOM["actions"] & string>(action: NiceAction<DOM, ID, DOM["actions"][ID]>): readonly ["nice-action", DOM["domain"], DOM["allDomains"], ID];
+export declare function niceActionQueryKey<DOM extends INiceActionDomain, ID extends keyof DOM["actions"] & string>(action: NiceAction<DOM, ID, DOM["actions"][ID]>, input: TInferInputFromSchema<DOM["actions"][ID]>["Input"], meta?: IActionMetaInputs): readonly [
+    "nice-action",
+    DOM["domain"],
+    DOM["allDomains"],
+    ID,
+    TInferInputFromSchema<DOM["actions"][ID]>["Input"],
+    string | undefined
+];
+export type TUseNiceQueryOptions<DOM extends INiceActionDomain, ID extends keyof DOM["actions"] & string, SCH extends DOM["actions"][ID] = DOM["actions"][ID], TSelect = TInferOutputFromSchema<SCH>["Output"]> = Omit<UseQueryOptions<TInferOutputFromSchema<SCH>["Output"], TInferActionError<SCH>, TSelect, QueryKey>, "queryKey" | "queryFn"> & IActionMetaInputs;
+export type TUseNiceMutationOptions<DOM extends INiceActionDomain, ID extends keyof DOM["actions"] & string, SCH extends DOM["actions"][ID] = DOM["actions"][ID], TContext = unknown> = Omit<UseMutationOptions<TInferOutputFromSchema<SCH>["Output"], TInferActionError<SCH>, TInferInputFromSchema<SCH>["Input"], TContext>, "mutationFn"> & IActionMetaInputs;
+/**
+ * Execute a Nice Action as a TanStack Query.
+ *
+ * Automatically constructs a stable query key from the action's domain, id, and input.
+ * Passing `null` or `undefined` as `input` disables the query (sets `enabled: false`),
+ * which allows conditional execution while respecting React's rules of hooks.
+ *
+ * The `envId` option targets a specific named handler/resolver registered on the domain.
+ *
+ * Supports TanStack Query's `select` option with full type inference — if you pass a
+ * `select` transformer, `data` will be typed as the transformer's return type.
+ *
+ * @example
+ * const { data, isPending, error } = useNiceQuery(
+ *   domain.action("getUser"),
+ *   { userId: "123" },
+ * );
+ *
+ * @example
+ * // Conditionally enabled
+ * const { data } = useNiceQuery(domain.action("getUser"), userId ? { userId } : null);
+ */
+export declare function useNiceQuery<DOM extends INiceActionDomain, ID extends keyof DOM["actions"] & string, SCH extends DOM["actions"][ID], TSelect = TInferOutputFromSchema<SCH>["Output"]>(action: NiceAction<DOM, ID, SCH>, input: TInferInputFromSchema<SCH>["Input"] | null | undefined, options?: TUseNiceQueryOptions<DOM, ID, SCH, TSelect>): UseQueryResult<TSelect, TInferActionError<SCH>>;
+/**
+ * Execute a Nice Action as a TanStack Mutation.
+ *
+ * Ideal for actions that change server state — form submissions, updates, deletes, etc.
+ * The input is provided at call time via `mutation.mutate(input)` or `mutation.mutateAsync(input)`.
+ *
+ * The `envId` option targets a specific named handler/resolver registered on the domain.
+ *
+ * @example
+ * const mutation = useNiceMutation(domain.action("createUser"));
+ *
+ * function handleSubmit(data: CreateUserInput) {
+ *   mutation.mutate(data, {
+ *     onSuccess: (user) => router.push(`/users/${user.id}`),
+ *   });
+ * }
+ */
+export declare function useNiceMutation<DOM extends INiceActionDomain, ID extends keyof DOM["actions"] & string, SCH extends DOM["actions"][ID], TContext = unknown>(action: NiceAction<DOM, ID, SCH>, options?: TUseNiceMutationOptions<DOM, ID, SCH, TContext>): UseMutationResult<TInferOutputFromSchema<SCH>["Output"], TInferActionError<SCH>, TInferInputFromSchema<SCH>["Input"], TContext>;