@nice-code/action 0.0.21 → 0.1.1

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">);
@@ -23,20 +25,12 @@ export declare class NiceAction<DOM extends INiceActionDomain, ID extends keyof
     toJsonObject(): INiceAction_JsonObject<DOM, ID>;
     toJsonString(): string;
     toHttpResponse(): Response;
-    toValidationSchema(): StandardSchemaV1;
-    is(action: unknown): action is NiceActionPrimed<DOM, ID, SCH>;
+    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.
@@ -45,22 +39,26 @@ export declare class NiceAction<DOM extends INiceActionDomain, ID extends keyof
      * ```ts
      * const result = await domain.action("getUser").executeSafe({ userId: "123" });
      * if (!result.ok) {
-     *   result.error.handleWith([
+     *   result.error.handleWithSync([
      *     forDomain(err_auth, (h) => res.status(401).end()),
      *   ]);
      *   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,22 +32,22 @@ 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
  * ```ts
  * const result = await domain.action("getUser").executeSafe({ userId: "123" });
  * if (!result.ok) {
- *   result.error.handleWith([
+ *   result.error.handleWithSync([
  *     forDomain(err_auth, (h) => res.status(401).end()),
  *   ]);
  *   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,42 +27,17 @@ export declare class NiceActionPrimed<DOM extends INiceActionDomain, ID extends
      */
     toJsonObject(): INiceActionPrimed_JsonObject<DOM, ID>;
     toJsonString(): string;
+    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;
-    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"]>;
+    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,7 +27,10 @@ export declare class NiceActionResponse<DOM extends INiceActionDomain, ID extend
      */
     toJsonObject(): TNiceActionResponse_JsonObject;
     toJsonString(): string;
-    toHttpResponse(): Response;
+    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,16 +1,20 @@
-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").NiceErrorDomain<{
     domain: string;
@@ -20,8 +24,10 @@ export declare const err_nice_action: import("@nice-code/error").NiceErrorDomain
             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").NiceErrorDomain
             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,31 @@
-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, INiceActionRootDomain, MaybePromise, TDomainActionId, TInferInputFromSchema, TInferOutputFromSchema, TNiceActionDomainChildDef, TNiceActionDomainSchema, TPossibleDomainId, TPossibleDomainIdList, } from "./ActionDomain/NiceActionDomain.types";
+export { NiceActionRootDomain } from "./ActionDomain/RootDomain/NiceActionRootDomain";
+export { ActionConnect } from "./ActionRuntimeEnvironment/ActionConnect/ActionConnect";
+export * from "./ActionRuntimeEnvironment/ActionConnect/ActionConnect.types";
+export { ConnectionConfig } from "./ActionRuntimeEnvironment/ActionConnect/ConnectionConfig/ConnectionConfig";
+export * from "./ActionRuntimeEnvironment/ActionConnect/ConnectionConfig/ConnectionConfig.types";
+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 * from "./ActionRuntimeEnvironment/ActionConnect/Transport/Transport";
+export * from "./ActionRuntimeEnvironment/ActionConnect/Transport/Transport.types";
+export * from "./ActionRuntimeEnvironment/ActionConnect/Transport/TransportHttp";
+export * from "./ActionRuntimeEnvironment/ActionConnect/Transport/TransportWebSocket";
+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

@@ -1,5 +1,6 @@
 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";
 /**
@@ -19,19 +20,16 @@ import type { NiceAction } from "../NiceAction/NiceAction";
  * 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"]): readonly [
+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"]
+    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"> & {
-    envId?: string;
-};
-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"> & {
-    envId?: string;
-};
+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.
  *
@@ -39,7 +37,7 @@ export type TUseNiceMutationOptions<DOM extends INiceActionDomain, ID extends ke
  * 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.
+ * The `tag` option targets a specific named handler registered on the runtime environment.
  *
  * 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.
@@ -61,7 +59,7 @@ export declare function useNiceQuery<DOM extends INiceActionDomain, ID extends k
  * 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.
+ * The `tag` option targets a specific named handler registered on the runtime environment.
  *
  * @example
  * const mutation = useNiceMutation(domain.action("createUser"));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nice-code/action",
-  "version": "0.0.21",
+  "version": "0.1.1",
   "private": false,
   "type": "module",
   "exports": {
@@ -32,17 +32,19 @@
     "build-types": "tsc --project tsconfig.build.json"
   },
   "dependencies": {
-    "@nice-code/error": "0.0.21",
-    "@nice-code/common-errors": "0.0.21",
+    "@nice-code/error": "0.1.1",
+    "@nice-code/common-errors": "0.1.1",
     "@standard-schema/spec": "^1.1.0",
     "http-status-codes": "^2.3.0",
-    "nanoid": "^5.1.9"
+    "nanoid": "^5.1.9",
+    "std-env": "^4.1.0"
   },
   "devDependencies": {
-    "@tanstack/react-query": "^5.99.0"
+    "@tanstack/react-query": "^5.100.3",
+    "msw": "^2.13.6"
   },
   "peerDependencies": {
-    "@tanstack/react-query": "^5.99.0",
+    "@tanstack/react-query": "^5.100.3",
     "react": ">=18",
     "valibot": "^1.3.1"
   }

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

@@ -1,5 +0,0 @@
-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

@@ -1,31 +0,0 @@
-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

@@ -1,49 +0,0 @@
-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

@@ -1,7 +0,0 @@
-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"]>;