@nice-code/action 0.0.21 → 0.1.0

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,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,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

@@ -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.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nice-code/action",
-  "version": "0.0.21",
+  "version": "0.1.0",
   "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.0",
+    "@nice-code/common-errors": "0.1.0",
     "@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"]>;

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

@@ -1,42 +0,0 @@
-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/NiceAction/ActionSchema/NiceActionSchema.d.ts

@@ -1,99 +0,0 @@
-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 []> {
-    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 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 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
-     * 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;