@nice-code/action 0.2.1 → 0.2.3

package/build/types/ActionRuntime/Handler/ActionHandler.types.d.ts

@@ -24,7 +24,7 @@ export interface IHandleActionOptions {
     targetExternalClient?: ActionClientSpecifier;
     targetLocalRuntime?: ActionRuntime;
 }
-export interface IExecuteActionOptions<DOM extends IActionDomain = IActionDomain, ID extends keyof DOM["actions"] & string = keyof DOM["actions"] & string> extends IHandleActionOptions {
+export interface IExecuteActionOptions<DOM extends IActionDomain = IActionDomain, ID extends keyof DOM["actionSchema"] & string = keyof DOM["actionSchema"] & string> extends IHandleActionOptions {
     listeners?: TRunningActionUpdateListener<DOM, ID>[];
 }
 export type TAtLeastOne<T extends object> = {
@@ -35,9 +35,6 @@ export interface IActionHandler_Base<T extends EActionHandlerType> {
     handlerType: T;
     getActionRouter: () => ActionRouter<any>;
 }
-export interface IHandleActionPrimed_Input_Base<DOM extends IActionDomain = IActionDomain, ID extends keyof DOM["actions"] & string = keyof DOM["actions"] & string> {
-    action: ActionPayload_Request<DOM, ID>;
-}
 /**
  *
  *  LOCAL ACTION HANDLER
@@ -46,7 +43,7 @@ export interface IHandleActionPrimed_Input_Base<DOM extends IActionDomain = IAct
 export interface IHandleActionOptions_Local extends IHandleActionOptions {
 }
 export interface IActionHandler_Local extends IActionHandler_Base<EActionHandlerType.local> {
-    handleActionRequest: <DOM extends IActionDomain, ID extends keyof DOM["actions"] & string>(action: ActionPayload_Request<DOM, ID>, config?: IHandleActionOptions_Local) => Promise<RunningAction<DOM, ID>>;
+    handleActionRequest: <DOM extends IActionDomain, ID extends keyof DOM["actionSchema"] & string>(action: ActionPayload_Request<DOM, ID>, config?: IHandleActionOptions_Local) => Promise<RunningAction<DOM, ID>>;
 }
 /**
  *
@@ -57,7 +54,7 @@ export interface IHandleActionOptions_External extends IHandleActionOptions {
 }
 export interface IActionHandler_ExternalClient extends IActionHandler_Base<EActionHandlerType.external> {
     externalClient: ActionClientSpecifier;
-    handleActionRequest: <DOM extends IActionDomain, ID extends keyof DOM["actions"] & string>(action: ActionPayload_Request<DOM, ID>, config?: IHandleActionOptions_External) => Promise<RunningAction<DOM, ID>>;
+    handleActionRequest: <DOM extends IActionDomain, ID extends keyof DOM["actionSchema"] & string>(action: ActionPayload_Request<DOM, ID>, config?: IHandleActionOptions_External) => Promise<RunningAction<DOM, ID>>;
     _setIncomingActionDataListener(listener: (json: TActionPayload_Any_JsonObject<any>) => void): void;
 }
 /**

package/build/types/ActionRuntime/Handler/ExternalClient/ActionExternalClientHandler.d.ts

@@ -22,10 +22,10 @@ export declare class ActionExternalClientHandler extends ActionHandler<EActionHa
     readonly actionRouter: ActionRouter<true>;
     constructor({ externalClientSpecifier, transports, defaultTimeout, }: IActionExternalClientRequestHandlerConfig);
     forDomain<FOR_DOM extends IActionDomain>(domain: ActionDomain<FOR_DOM>): this;
-    forAction<ACT_DOM extends IActionDomain, ID extends keyof ACT_DOM["actions"] & string>(action: ActionCore<ACT_DOM, ID>): this;
-    forActionIds<ACT_DOM extends IActionDomain, IDS extends ReadonlyArray<keyof ACT_DOM["actions"] & string>>(domain: ActionDomain<ACT_DOM>, ids: IDS): this;
+    forAction<ACT_DOM extends IActionDomain, ID extends keyof ACT_DOM["actionSchema"] & string>(action: ActionCore<ACT_DOM, ID>): this;
+    forActionIds<ACT_DOM extends IActionDomain, IDS extends ReadonlyArray<keyof ACT_DOM["actionSchema"] & string>>(domain: ActionDomain<ACT_DOM>, ids: IDS): this;
     _setIncomingActionDataListener(listener: (json: TActionPayload_Any_JsonObject<any, any>) => void): void;
-    handleActionRequest<DOM extends IActionDomain, ID extends keyof DOM["actions"] & string>(action: ActionPayload_Request<DOM, ID>, config?: IHandleActionOptions): Promise<RunningAction<DOM, ID>>;
+    handleActionRequest<DOM extends IActionDomain, ID extends keyof DOM["actionSchema"] & string>(action: ActionPayload_Request<DOM, ID>, config?: IHandleActionOptions): Promise<RunningAction<DOM, ID>>;
     /**
      * Dispatch a result or progress payload directly back to the external client via the best
      * available bidirectional transport (WebSocket / Custom). Used for return-path routing when the

package/build/types/ActionRuntime/Handler/Local/ActionLocalHandler.d.ts

@@ -24,13 +24,13 @@ export declare class ActionLocalHandler extends ActionHandler<EActionHandlerType
      * Receives the full primed action with narrowed input type.
      * Useful for handling specific actions locally while forwarding the rest of the domain. For example, a local "ping" action that checks connectivity without needing a round trip.
      */
-    forAction<ACT_DOM extends IActionDomain, ID extends keyof ACT_DOM["actions"] & string>(action: ActionCore<ACT_DOM, ID>, handler: THandleActionExecutionFn<ACT_DOM, ID>): this;
+    forAction<ACT_DOM extends IActionDomain, ID extends keyof ACT_DOM["actionSchema"] & string>(action: ActionCore<ACT_DOM, ID>, handler: THandleActionExecutionFn<ACT_DOM, ID>): this;
     /**
      * Register a handler for multiple action IDs (first-match-wins among cases).
      * Receives the full primed action narrowed to the union of those IDs.
      * Use `act.coreAction.id` to branch on which action was dispatched.
      */
-    forActionIds<ACT_DOM extends IActionDomain, IDS extends ReadonlyArray<keyof ACT_DOM["actions"] & string>>(domain: ActionDomain<ACT_DOM>, ids: IDS, handler: THandleActionExecutionFn<ACT_DOM, IDS[number]>): this;
+    forActionIds<ACT_DOM extends IActionDomain, IDS extends ReadonlyArray<keyof ACT_DOM["actionSchema"] & string>>(domain: ActionDomain<ACT_DOM>, ids: IDS, handler: THandleActionExecutionFn<ACT_DOM, IDS[number]>): this;
     /**
      * Register per-action handlers for a domain using a single map, without needing
      * separate `forAction` calls. Unregistered action IDs are unaffected.
@@ -44,9 +44,9 @@ export declare class ActionLocalHandler extends ActionHandler<EActionHandlerType
      * ```
      */
     forDomainActionCases<FOR_DOM extends IActionDomain>(domain: ActionDomain<FOR_DOM>, cases: {
-        [ID in keyof FOR_DOM["actions"] & string]?: THandleActionExecutionFn<FOR_DOM, ID>;
+        [ID in keyof FOR_DOM["actionSchema"] & string]?: THandleActionExecutionFn<FOR_DOM, ID>;
     }): this;
-    handleActionRequest<DOM extends IActionDomain, ID extends keyof DOM["actions"] & string>(action: ActionPayload_Request<DOM, ID>, config?: IHandleActionOptions): Promise<RunningAction<DOM, ID>>;
+    handleActionRequest<DOM extends IActionDomain, ID extends keyof DOM["actionSchema"] & string>(action: ActionPayload_Request<DOM, ID>, config?: IHandleActionOptions): Promise<RunningAction<DOM, ID>>;
     private _handleRunningAction;
     handlePayloadWireOrThrow(wire: unknown, config?: IHandleActionOptions): Promise<RunningAction<any, any>>;
     toJsonObject(): IActionHandler_Local_Json;

package/build/types/ActionRuntime/Handler/Local/ActionLocalHandler.types.d.ts

@@ -4,4 +4,4 @@ import type { IActionPayload_Result_JsonObject } from "../../../ActionDefinition
 import type { ActionPayload_Result } from "../../../ActionDefinition/Action/Payload/ActionPayload_Result";
 import type { IActionDomain, TInferOutputFromSchema } from "../../../ActionDefinition/Domain/ActionDomain.types";
 export type { TDistributeActionPayload_Request };
-export type THandleActionExecutionFn<DOM extends IActionDomain, ID extends keyof DOM["actions"] & string = keyof DOM["actions"] & string> = (action: TDistributeActionPayload_Request<DOM, ID>) => MaybePromise<ActionPayload_Result<DOM, ID> | IActionPayload_Result_JsonObject<DOM, ID> | TInferOutputFromSchema<DOM["actions"][ID]>["Output"] | undefined>;
+export type THandleActionExecutionFn<DOM extends IActionDomain, ID extends keyof DOM["actionSchema"] & string = keyof DOM["actionSchema"] & string> = (action: TDistributeActionPayload_Request<DOM, ID>) => MaybePromise<ActionPayload_Result<DOM, ID> | IActionPayload_Result_JsonObject<DOM, ID> | TInferOutputFromSchema<DOM["actionSchema"][ID]>["Output"] | undefined>;

package/build/types/ActionRuntime/Routing/ActionRouter.d.ts

@@ -30,24 +30,24 @@ export declare class ActionRouter<DATA> {
     getDomains(): ActionDomain[];
     /** Register a handler for all actions in a domain, replacing any existing one. */
     forDomain<FOR_DOM extends IActionDomain>(domain: ActionDomain<FOR_DOM>, routeData: DATA): this;
-    forAction<ACT_DOM extends IActionDomain, ID extends keyof ACT_DOM["actions"] & string>(action: ActionCore<ACT_DOM, ID>, routeData: DATA): this;
+    forAction<ACT_DOM extends IActionDomain, ID extends keyof ACT_DOM["actionSchema"] & string>(action: ActionCore<ACT_DOM, ID>, routeData: DATA): this;
     /** Register a handler for a specific action, replacing any existing one. */
-    forActionId<ACT_DOM extends IActionDomain, ID extends keyof ACT_DOM["actions"] & string>(domain: ActionDomain<ACT_DOM>, id: ID, routeData: DATA): this;
+    forActionId<ACT_DOM extends IActionDomain, ID extends keyof ACT_DOM["actionSchema"] & string>(domain: ActionDomain<ACT_DOM>, id: ID, routeData: DATA): this;
     /** Register one handler for several action IDs, replacing any existing ones. */
-    forActionIds<ACT_DOM extends IActionDomain, IDS extends ReadonlyArray<keyof ACT_DOM["actions"] & string>>(domain: ActionDomain<ACT_DOM>, ids: IDS, routeData: DATA): this;
+    forActionIds<ACT_DOM extends IActionDomain, IDS extends ReadonlyArray<keyof ACT_DOM["actionSchema"] & string>>(domain: ActionDomain<ACT_DOM>, ids: IDS, routeData: DATA): this;
     /** Register per-action handlers from a cases map, replacing any existing ones. */
     forDomainActionCases<FOR_DOM extends IActionDomain>(domain: ActionDomain<FOR_DOM>, cases: {
-        [ID in keyof FOR_DOM["actions"] & string]?: DATA;
+        [ID in keyof FOR_DOM["actionSchema"] & string]?: DATA;
     }): this;
     /** Append a handler for all actions in a domain (accumulates alongside existing). */
     addForDomain<FOR_DOM extends IActionDomain>(domain: ActionDomain<FOR_DOM>, routeData: DATA): this;
     /** Append a handler for a specific action (accumulates alongside existing). */
-    addForAction<ACT_DOM extends IActionDomain, ID extends keyof ACT_DOM["actions"] & string>(domain: ActionDomain<ACT_DOM>, id: ID, routeData: DATA): this;
+    addForAction<ACT_DOM extends IActionDomain, ID extends keyof ACT_DOM["actionSchema"] & string>(domain: ActionDomain<ACT_DOM>, id: ID, routeData: DATA): this;
     /** Append one handler for several action IDs (accumulates alongside existing). */
-    addForActionIds<ACT_DOM extends IActionDomain, IDS extends ReadonlyArray<keyof ACT_DOM["actions"] & string>>(domain: ActionDomain<ACT_DOM>, ids: IDS, routeData: DATA): this;
+    addForActionIds<ACT_DOM extends IActionDomain, IDS extends ReadonlyArray<keyof ACT_DOM["actionSchema"] & string>>(domain: ActionDomain<ACT_DOM>, ids: IDS, routeData: DATA): this;
     /** Append per-action handlers from a cases map (accumulates alongside existing). */
     addForDomainActionCases<FOR_DOM extends IActionDomain>(domain: ActionDomain<FOR_DOM>, cases: {
-        [ID in keyof FOR_DOM["actions"] & string]?: DATA;
+        [ID in keyof FOR_DOM["actionSchema"] & string]?: DATA;
     }): this;
     /** Append a handler directly by its raw match key (used when the key is known ahead of time). */
     addForKey(key: TMatchHandlerKey, routeData: DATA): this;

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

@@ -9,7 +9,7 @@ export declare enum EErrId_NiceAction {
     hydration_action_state_mismatch = "hydration_action_state_mismatch",
     hydration_action_id_not_found = "hydration_action_id_not_found",
     no_action_execution_handler = "no_action_execution_handler",
-    wire_action_not_primed_or_response = "wire_action_not_primed_or_response",
+    wire_action_not_payload = "wire_action_not_payload",
     wire_not_action_data = "wire_not_action_data",
     client_runtime_already_registered = "client_runtime_already_registered",
     client_runtime_not_registered = "client_runtime_not_registered",
@@ -55,7 +55,7 @@ export declare const err_nice_action: import("@nice-code/error").NiceErrorDomain
             actionId: string;
             specifiedClient?: ActionClientSpecifier;
         }, import("@nice-code/error").JSONSerializableValue>;
-        wire_action_not_primed_or_response: import("@nice-code/error").INiceErrorIdMetadata<{
+        wire_action_not_payload: import("@nice-code/error").INiceErrorIdMetadata<{
             domain: string;
             actionId: string;
             actionState: string | undefined;

package/build/types/react-query/hooks/useActionMutation.d.ts

@@ -0,0 +1,6 @@
+import { type UseMutationOptions, type UseMutationResult } from "@tanstack/react-query";
+import type { ActionCore } from "../../ActionDefinition/Action/Core/ActionCore";
+import type { IActionDomain, TInferInputFromSchema, TInferOutputFromSchema } from "../../ActionDefinition/Domain/ActionDomain.types";
+import type { TInferActionError } from "../../ActionDefinition/Schema/ActionSchema";
+export type TUseNiceMutationOptions<DOM extends IActionDomain, ID extends keyof DOM["actionSchema"] & string, SCH extends DOM["actionSchema"][ID] = DOM["actionSchema"][ID], TContext = unknown> = Omit<UseMutationOptions<TInferOutputFromSchema<SCH>["Output"], TInferActionError<SCH>, TInferInputFromSchema<SCH>["Input"], TContext>, "mutationFn">;
+export declare function useActionMutation<DOM extends IActionDomain, ID extends keyof DOM["actionSchema"] & string, SCH extends DOM["actionSchema"][ID], TContext = unknown>(action: ActionCore<DOM, ID>, options?: TUseNiceMutationOptions<DOM, ID, SCH, TContext>): UseMutationResult<TInferOutputFromSchema<SCH>["Output"], TInferActionError<SCH>, TInferInputFromSchema<SCH>["Input"], TContext>;

package/build/types/react-query/hooks/useActionQuery.d.ts

@@ -0,0 +1,15 @@
+import { type QueryKey, type UseQueryOptions, type UseQueryResult } from "@tanstack/react-query";
+import type { ActionCore } from "../../ActionDefinition/Action/Core/ActionCore";
+import type { IActionDomain, TInferInputFromSchema, TInferOutputFromSchema } from "../../ActionDefinition/Domain/ActionDomain.types";
+import type { TInferActionError } from "../../ActionDefinition/Schema/ActionSchema";
+export declare function niceActionQueryKey<DOM extends IActionDomain, ID extends keyof DOM["actionSchema"] & string>(action: ActionCore<DOM, ID>): readonly ["nice-action", DOM["domain"], DOM["allDomains"], ID];
+export declare function niceActionQueryKey<DOM extends IActionDomain, ID extends keyof DOM["actionSchema"] & string>(action: ActionCore<DOM, ID>, input: TInferInputFromSchema<DOM["actionSchema"][ID]>["Input"]): readonly [
+    "nice-action",
+    DOM["domain"],
+    DOM["allDomains"],
+    ID,
+    TInferInputFromSchema<DOM["actionSchema"][ID]>["Input"],
+    string | undefined
+];
+export type TUseNiceQueryOptions<DOM extends IActionDomain, ID extends keyof DOM["actionSchema"] & string, SCH extends DOM["actionSchema"][ID] = DOM["actionSchema"][ID], TSelect = TInferOutputFromSchema<SCH>["Output"]> = Omit<UseQueryOptions<TInferOutputFromSchema<SCH>["Output"], TInferActionError<SCH>, TSelect, QueryKey>, "queryKey" | "queryFn">;
+export declare function useNiceQuery<DOM extends IActionDomain, ID extends keyof DOM["actionSchema"] & string, SCH extends DOM["actionSchema"][ID], TSelect = TInferOutputFromSchema<SCH>["Output"]>(action: ActionCore<DOM, ID>, input: TInferInputFromSchema<SCH>["Input"] | null | undefined, options?: TUseNiceQueryOptions<DOM, ID, SCH, TSelect>): UseQueryResult<TSelect, TInferActionError<SCH>>;

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

@@ -1,72 +1,2 @@
-import type { QueryKey, UseMutationOptions, UseMutationResult, UseQueryOptions, UseQueryResult } from "@tanstack/react-query";
-import type { ActionCore } from "../ActionDefinition/Action/Core/ActionCore";
-import type { IActionDomain, TInferInputFromSchema, TInferOutputFromSchema } from "../ActionDefinition/Domain/ActionDomain.types";
-import type { TInferActionError } from "../ActionDefinition/Schema/ActionSchema";
-/**
- * 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 IActionDomain, ID extends keyof DOM["actions"] & string>(action: ActionCore<DOM, ID>): readonly ["nice-action", DOM["domain"], DOM["allDomains"], ID];
-export declare function niceActionQueryKey<DOM extends IActionDomain, ID extends keyof DOM["actions"] & string>(action: ActionCore<DOM, ID>, input: TInferInputFromSchema<DOM["actions"][ID]>["Input"]): readonly [
-    "nice-action",
-    DOM["domain"],
-    DOM["allDomains"],
-    ID,
-    TInferInputFromSchema<DOM["actions"][ID]>["Input"],
-    string | undefined
-];
-export type TUseNiceQueryOptions<DOM extends IActionDomain, 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">;
-export type TUseNiceMutationOptions<DOM extends IActionDomain, 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">;
-/**
- * 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 `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.
- *
- * @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 IActionDomain, ID extends keyof DOM["actions"] & string, SCH extends DOM["actions"][ID], TSelect = TInferOutputFromSchema<SCH>["Output"]>(action: ActionCore<DOM, ID>, 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 `tag` option targets a specific named handler registered on the runtime environment.
- *
- * @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 IActionDomain, ID extends keyof DOM["actions"] & string, SCH extends DOM["actions"][ID], TContext = unknown>(action: ActionCore<DOM, ID>, options?: TUseNiceMutationOptions<DOM, ID, SCH, TContext>): UseMutationResult<TInferOutputFromSchema<SCH>["Output"], TInferActionError<SCH>, TInferInputFromSchema<SCH>["Input"], TContext>;
+export * from "./hooks/useActionMutation";
+export * from "./hooks/useActionQuery";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nice-code/action",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "private": false,
   "type": "module",
   "exports": {