@nice-code/action 0.0.20 → 0.0.21

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

@@ -46,12 +46,13 @@ export declare class NiceActionDomain<ACT_DOM extends INiceActionDomain = INiceA
      * execution environments (e.g. worker, main thread) share the same domain definition.
      * Named requesters are targeted by passing the same `envId` to `action.execute(input, envId)`.
      *
-     * Omit `envId` to register the default requester, used when no `envId` is passed to `execute`.
+     * Omit `options` (or pass `undefined`) to register the default requester.
+     * Pass an existing `NiceActionRequester` as `handler` to reuse a shared instance.
      * Throws `environment_already_registered` / `domain_action_requester_conflict` if already taken.
      */
-    setActionRequester(handler?: NiceActionRequester, options?: {
+    setActionRequester(options?: {
         envId?: string;
-    }): NiceActionRequester;
+    }, handler?: NiceActionRequester): NiceActionRequester;
     /**
      * Register a resolver as the fallback execution path for this domain.
      *

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

@@ -1,4 +1,3 @@
-import type { NiceActionRequester } from "../ActionRequestResponse/ActionRequester/NiceActionRequester";
 import type { NiceActionSchema } from "../ActionSchema/NiceActionSchema";
 import type { INiceActionErrorDeclaration, TTransportedValue } from "../ActionSchema/NiceActionSchema.types";
 import type { NiceActionPrimed } from "../NiceAction/NiceActionPrimed";
@@ -72,8 +71,4 @@ export interface IActionCase<P extends NiceActionPrimed<any, any, any> = NiceAct
     readonly _matcher: (action: P) => boolean;
     readonly _requester: TBroadActionRequester<P>;
 }
-export interface IActionHandlerWithId {
-    id: string;
-    handler: NiceActionRequester;
-}
 export type TDomainActionId<DOM extends INiceActionDomain> = keyof DOM["actions"] & string;

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

@@ -1,4 +1,4 @@
-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 []> {
@@ -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

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];
@@ -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/ActionSchema/NiceActionSchema.d.ts

@@ -1,4 +1,4 @@
-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 []> {
@@ -39,12 +39,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

package/build/types/NiceAction/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 TTransportedValue<RAW_VAL = never, SERDE_VAL extends JSONSerializableValue = never> = RAW_VAL extends JSONSerializableValue ? [RAW_VAL] | [RAW_VAL, SERDE_VAL] : [RAW_VAL, SERDE_VAL];
 export type TNiceActionSerializationDefinition<RAW_VAL = any, SERDE_VAL extends JSONSerializableValue = JSONSerializableValue> = {
@@ -19,8 +19,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/NiceAction.d.ts

@@ -21,6 +21,8 @@ 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>;
+    toJsonString(): string;
+    toHttpResponse(): Response;
     toValidationSchema(): StandardSchemaV1;
     is(action: unknown): action is NiceActionPrimed<DOM, ID, SCH>;
     prime(input: TInferInputFromSchema<SCH>["Input"], hydrationData?: Pick<INiceActionPrimed_JsonObject<DOM, ID>, "timePrimed">): NiceActionPrimed<DOM, ID, SCH>;

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

@@ -19,6 +19,7 @@ export declare class NiceActionPrimed<DOM extends INiceActionDomain, ID extends
      */
     toJsonObject(): INiceActionPrimed_JsonObject<DOM, ID>;
     toJsonString(): string;
+    toHttpResponse(): Response;
     setOutput(output: TInferOutputFromSchema<SCH>["Output"]): NiceActionResponse<DOM, ID, SCH>;
     /**
      * Process a wire response returned by a remote `NiceActionResponderEnvironment`.

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

@@ -21,6 +21,7 @@ export declare class NiceActionResponse<DOM extends INiceActionDomain, ID extend
      */
     toJsonObject(): TNiceActionResponse_JsonObject;
     toJsonString(): string;
+    toHttpResponse(): Response;
 }
 /**
  * Reconstruct a loosely-typed NiceActionResponse from its wire format.

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

@@ -12,7 +12,7 @@ export declare enum EErrId_NiceAction {
     environment_already_registered = "environment_already_registered",
     action_input_validation_failed = "action_input_validation_failed"
 }
-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: {

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

@@ -0,0 +1,75 @@
+import type { QueryKey, UseMutationOptions, UseMutationResult, UseQueryOptions, UseQueryResult } from "@tanstack/react-query";
+import type { INiceActionDomain, TInferInputFromSchema, TInferOutputFromSchema } from "../ActionDomain/NiceActionDomain.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"]): readonly [
+    "nice-action",
+    DOM["domain"],
+    DOM["allDomains"],
+    ID,
+    TInferInputFromSchema<DOM["actions"][ID]>["Input"]
+];
+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;
+};
+/**
+ * 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>;

package/package.json

@@ -1,12 +1,16 @@
 {
   "name": "@nice-code/action",
-  "version": "0.0.20",
+  "version": "0.0.21",
   "private": false,
   "type": "module",
   "exports": {
     ".": {
       "types": "./build/types/index.d.ts",
       "import": "./build/index.js"
+    },
+    "./react-query": {
+      "types": "./build/types/react-query/index.d.ts",
+      "import": "./build/react-query/index.js"
     }
   },
   "files": [
@@ -28,14 +32,18 @@
     "build-types": "tsc --project tsconfig.build.json"
   },
   "dependencies": {
-    "@nice-code/error": "0.0.20",
-    "@nice-code/common-errors": "0.0.20",
+    "@nice-code/error": "0.0.21",
+    "@nice-code/common-errors": "0.0.21",
     "@standard-schema/spec": "^1.1.0",
     "http-status-codes": "^2.3.0",
     "nanoid": "^5.1.9"
   },
-  "devDependencies": {},
+  "devDependencies": {
+    "@tanstack/react-query": "^5.99.0"
+  },
   "peerDependencies": {
+    "@tanstack/react-query": "^5.99.0",
+    "react": ">=18",
     "valibot": "^1.3.1"
   }
 }