@nice-code/action 0.0.20 → 0.1.0

package/package.json

@@ -1,12 +1,16 @@
 {
   "name": "@nice-code/action",
-  "version": "0.0.20",
+  "version": "0.1.0",
   "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,20 @@
     "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.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.100.3",
+    "msw": "^2.13.6"
   },
-  "devDependencies": {},
   "peerDependencies": {
+    "@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 INiceErrorDefinedProps, type InferNiceError, type JSONSerializableValue, type NiceErrorDefined } 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 INiceErrorDefinedProps>(domain: NiceErrorDefined<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>]>;
-    /**
-     * 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;

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

@@ -1,31 +0,0 @@
-import { type INiceErrorDefinedProps, type JSONSerializableValue, type NiceErrorDefined } 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> = {
-    serialize: (value: RAW_VAL) => SERDE_VAL;
-    deserialize: (value: SERDE_VAL) => RAW_VAL;
-};
-export type TNiceActonSchemaInputOptions<VS extends StandardSchemaV1 = StandardSchemaV1, SERDE_IN extends JSONSerializableValue = JSONSerializableValue> = StandardSchemaV1.InferInput<VS> extends JSONSerializableValue ? {
-    schema: VS;
-    serialization?: TNiceActionSerializationDefinition<StandardSchemaV1.InferInput<VS>, SERDE_IN>;
-} : {
-    schema: VS;
-    serialization: TNiceActionSerializationDefinition<StandardSchemaV1.InferInput<VS>, SERDE_IN>;
-};
-/**
- * One error declaration on an action schema.
- * `IDS` is the subset of error IDs that may be thrown. When the full
- * `keyof schema` union is used it means any ID from the domain can be thrown.
- *
- * 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>;
-    /** The specific IDs constrained for this declaration, or `undefined` meaning the full domain. */
-    readonly _ids: ReadonlyArray<IDS & string> | undefined;
-}
-/**
- * Union of all `NiceError` types that can be thrown from a tuple of error declarations.
- * Distributes over each declaration and unions the results.
- */
-export type TInferDeclaredErrors<DECLS extends readonly INiceActionErrorDeclaration[]> = TInferErrorFromDeclaration<DECLS[number]>;

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

@@ -1 +0,0 @@
-export {};

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

@@ -1,2 +0,0 @@
-import { NiceActionSchema } from "./NiceActionSchema";
-export declare const action: () => NiceActionSchema;

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

@@ -1,8 +0,0 @@
-import type { JSONSerializableValue } from "@nice-code/error";
-import * as v from "valibot";
-export declare const vNiceActionPrimedJsonObject: v.ObjectSchema<{
-    readonly id: v.StringSchema<undefined>;
-    readonly domain: v.StringSchema<undefined>;
-    readonly allDomains: v.ArraySchema<v.StringSchema<undefined>, undefined>;
-    readonly input: v.CustomSchema<JSONSerializableValue, undefined>;
-}, undefined>;

package/build/types/test/nice_action_test_schema.d.ts

@@ -1,30 +0,0 @@
-import type { JSONSerializableValue } from "@nice-code/error";
-export declare const demo_domain: import("..").NiceActionDomain<{
-    domain: string;
-    actions: {
-        action1: import("..").NiceActionSchema<[{
-            a: string;
-            cust: JSONSerializableValue;
-        }] | [{
-            a: string;
-            cust: JSONSerializableValue;
-        }, any], [any] | [any, never], readonly []>;
-        action2: import("..").NiceActionSchema<[{
-            b: string;
-            custBad: Omit<import("..").INiceAction_JsonObject<import("..").INiceActionDomain<import("..").TPossibleDomainIdList, import("..").TNiceActionDomainSchema>, string>, "type"> & {
-                type: import("../NiceAction/NiceAction.types").EActionState.primed;
-                input: any;
-                timePrimed: number;
-            };
-        }] | [{
-            b: string;
-            custBad: Omit<import("..").INiceAction_JsonObject<import("..").INiceActionDomain<import("..").TPossibleDomainIdList, import("..").TNiceActionDomainSchema>, string>, "type"> & {
-                type: import("../NiceAction/NiceAction.types").EActionState.primed;
-                input: any;
-                timePrimed: number;
-            };
-        }, any], [any] | [any, never], readonly []>;
-    };
-} & {
-    allDomains: [string];
-}>;