@nice-code/action 0.0.15

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

@@ -0,0 +1,81 @@
+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> {
+    id: ID;
+    domain: DOM["domain"];
+    allDomains: DOM["allDomains"];
+    schema: DOM["actions"][ID];
+    cuid: string;
+    timeCreated: number;
+}
+/**
+ * Wire format for a serialized NiceActionPrimed — safe to JSON.stringify / transmit.
+ */
+export type INiceAction_JsonObject<DOM extends INiceActionDomain = INiceActionDomain, ID extends keyof DOM["actions"] & string = keyof DOM["actions"] & string> = {
+    type: EActionState.empty;
+    domain: DOM["domain"];
+    allDomains: DOM["allDomains"];
+    id: ID;
+    cuid: string;
+    timeCreated: number;
+};
+/**
+ * Wire format for a serialized NiceActionPrimed — safe to JSON.stringify / transmit.
+ */
+export type INiceActionPrimed_JsonObject<DOM extends INiceActionDomain = INiceActionDomain, ID extends keyof DOM["actions"] & string = keyof DOM["actions"] & string> = Omit<INiceAction_JsonObject<DOM, ID>, "type"> & {
+    type: EActionState.primed;
+    input: TInferInputFromSchema<DOM["actions"][ID]>["SerdeInput"];
+    timePrimed: number;
+};
+/**
+ * Return type of `executeSafe` — a discriminated union of success and failure.
+ *
+ * - `{ ok: true; value: OUT }` — the action completed and returned `OUT`
+ * - `{ ok: false; error: ERR }` — the action threw; `ERR` is the declared error union
+ *
+ * @example
+ * ```ts
+ * const result = await domain.action("getUser").executeSafe({ userId: "123" });
+ * if (!result.ok) {
+ *   result.error.handleWith([
+ *     forDomain(err_auth, (h) => res.status(401).end()),
+ *   ]);
+ *   return;
+ * }
+ * console.log(result.value); // typed as the action's OUTPUT
+ * ```
+ */
+export type NiceActionResult<OUT, ERR> = {
+    ok: true;
+    output: OUT;
+} | {
+    ok: false;
+    error: ERR;
+};
+/**
+ * Wire format for a serialized NiceActionResponse — safe to JSON.stringify / transmit.
+ *
+ * Carries the original action identity (domain + actionId + serialized input) alongside
+ * either the serialized output value or a serialized NiceError.
+ *
+ * Produced by `NiceActionResponse.toJsonObject()`.
+ * 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;
+    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> & {
+    ok: true;
+    output: TInferOutputFromSchema<DOM["actions"][ID]>["SerdeOutput"];
+};
+export type INiceActionResponse_JsonObject_Failure<DOM extends INiceActionDomain = INiceActionDomain, ID extends keyof DOM["actions"] & string = keyof DOM["actions"] & string> = INiceActionResponse_JsonObject_Base<DOM, ID> & {
+    ok: false;
+    error: INiceErrorJsonObject;
+};
+export type TNiceActionResponse_JsonObject<DOM extends INiceActionDomain = INiceActionDomain, ID extends keyof DOM["actions"] & string = keyof DOM["actions"] & string> = INiceActionResponse_JsonObject_Success<DOM, ID> | INiceActionResponse_JsonObject_Failure<DOM, ID>;

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

@@ -0,0 +1,59 @@
+import type { INiceActionDomain, TInferInputFromSchema, TInferOutputFromSchema } from "../ActionDomain/NiceActionDomain.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 { 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"> {
+    readonly coreAction: NiceAction<DOM, ID, SCH>;
+    readonly input: TInferInputFromSchema<SCH>["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">);
+    /**
+     * Serialize this primed action to a JSON-safe wire format.
+     * The input is passed through the schema's serialize function if one is defined,
+     * otherwise the (already JSON-native) input is used as-is.
+     */
+    toJsonObject(): INiceActionPrimed_JsonObject<DOM, ID>;
+    toJsonString(): string;
+    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"]>;
+    /**
+     * 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 }`.
+     *
+     * Mirrors `NiceAction.executeSafe` — useful when re-executing a hydrated primed action.
+     */
+    executeSafe(envId?: string): Promise<NiceActionResult<TInferOutputFromSchema<SCH>["Output"], TInferActionError<SCH>>>;
+}

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

@@ -0,0 +1,8 @@
+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/NiceAction/NiceActionResponse.d.ts

@@ -0,0 +1,32 @@
+import type { INiceActionDomain, TInferOutputFromSchema } from "../ActionDomain/NiceActionDomain.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 { 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;
+    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 timeResponded: number;
+    constructor(primed: NiceActionPrimed<DOM, ID, SCH>, result: NiceActionResult<TInferOutputFromSchema<SCH>["Output"], TInferActionError<SCH>>, hydrationData?: Pick<TNiceActionResponse_JsonObject<DOM, ID>, "timeResponded">);
+    /**
+     * Serialize this response to a JSON-safe wire format.
+     *
+     * On success, the output is passed through the schema's serialize function
+     * if one is defined, otherwise used as-is.
+     * On failure, the error is serialized via `NiceError.toJsonObject()`.
+     */
+    toJsonObject(): TNiceActionResponse_JsonObject;
+    toJsonString(): string;
+}
+/**
+ * Reconstruct a loosely-typed NiceActionResponse from its wire format.
+ * Called by `NiceActionDomain.hydrateResponse` — not part of the public API.
+ *
+ * The result's error type is `NiceError<TUnknownNiceErrorDef>` (from `castNiceError`).
+ * Use `handleWith` / `forDomain` / `isExact` to narrow on the receiving end.
+ */
+export declare function hydrateNiceActionResponse<DOM extends INiceActionDomain>(wire: TNiceActionResponse_JsonObject, coreAction: NiceAction<DOM, keyof DOM["actions"] & string, DOM["actions"][keyof DOM["actions"] & string]>): NiceActionResponse<DOM, keyof DOM["actions"] & string, DOM["actions"][keyof DOM["actions"] & string]>;

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

@@ -0,0 +1,62 @@
+import type { EActionState } from "../NiceAction/NiceAction.types";
+export declare enum EErrId_NiceAction {
+    action_id_not_in_domain = "action_id_not_in_domain",
+    domain_action_requester_conflict = "domain_action_handler_conflict",
+    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",
+    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<{
+    domain: string;
+    allDomains: [string, "err_nice"];
+    schema: {
+        action_id_not_in_domain: import("@nice-code/error").INiceErrorIdMetadata<{
+            domain: string;
+            actionId: string;
+        }, import("@nice-code/error").JSONSerializableValue>;
+        domain_action_handler_conflict: import("@nice-code/error").INiceErrorIdMetadata<{
+            domain: string;
+        }, import("@nice-code/error").JSONSerializableValue>;
+        domain_no_handler: import("@nice-code/error").INiceErrorIdMetadata<{
+            domain: string;
+        }, import("@nice-code/error").JSONSerializableValue>;
+        hydration_domain_mismatch: import("@nice-code/error").INiceErrorIdMetadata<{
+            expected: string;
+            received: string;
+        }, import("@nice-code/error").JSONSerializableValue>;
+        hydration_action_state_mismatch: import("@nice-code/error").INiceErrorIdMetadata<{
+            expected: EActionState;
+            received: EActionState;
+        }, import("@nice-code/error").JSONSerializableValue>;
+        hydration_action_id_not_found: import("@nice-code/error").INiceErrorIdMetadata<{
+            domain: string;
+            actionId: string;
+        }, import("@nice-code/error").JSONSerializableValue>;
+        resolver_domain_not_registered: import("@nice-code/error").INiceErrorIdMetadata<{
+            domain: string;
+        }, import("@nice-code/error").JSONSerializableValue>;
+        resolver_action_not_registered: import("@nice-code/error").INiceErrorIdMetadata<{
+            domain: string;
+            actionId: string;
+        }, import("@nice-code/error").JSONSerializableValue>;
+        action_environment_not_found: import("@nice-code/error").INiceErrorIdMetadata<{
+            domain: string;
+            envId: string;
+        }, import("@nice-code/error").JSONSerializableValue>;
+        environment_already_registered: import("@nice-code/error").INiceErrorIdMetadata<{
+            domain: string;
+            envId: 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>;
+    };
+}>;

package/build/types/index.d.ts

@@ -0,0 +1,18 @@
+export { createActionDomain } from "./ActionDomain/createActionDomain";
+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 { 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 { EErrId_NiceAction, err_nice_action } from "./errors/err_nice_action";
+export { NiceAction } from "./NiceAction/NiceAction";
+export type { INiceAction, INiceAction_JsonObject, INiceActionPrimed_JsonObject, NiceActionResult, TNiceActionResponse_JsonObject, } from "./NiceAction/NiceAction.types";
+export { NiceActionPrimed } from "./NiceAction/NiceActionPrimed";
+export { NiceActionResponse } from "./NiceAction/NiceActionResponse";
+export * from "./utils/isActionResponseJsonObject";
+export * from "./utils/isPrimedActionJsonObject";

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

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

package/build/types/utils/isActionResponseJsonObject.d.ts

@@ -0,0 +1,2 @@
+import type { TNiceActionResponse_JsonObject } from "../NiceAction/NiceAction.types";
+export declare const isActionResponseJsonObject: (obj: unknown) => obj is TNiceActionResponse_JsonObject;

package/build/types/utils/isPrimedActionJsonObject.d.ts

@@ -0,0 +1,2 @@
+import type { INiceActionPrimed_JsonObject } from "../NiceAction/NiceAction.types";
+export declare const isPrimedActionJsonObject: (obj: unknown) => obj is INiceActionPrimed_JsonObject;

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@nice-code/action",
+  "version": "0.0.15",
+  "private": false,
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./build/types/index.d.ts",
+      "import": "./build/index.js"
+    }
+  },
+  "files": [
+    "build",
+    "package.json",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "type-check": "bunx tsc --noEmit",
+    "type-check-watch": "bunx tsc --noEmit --watch",
+    "clean-build": "bunx rimraf build",
+    "vitest": "vitest --typecheck",
+    "vitest-agent": "vitest --typecheck --reporter=agent",
+    "build": "bun run clean-build && bun run build.ts && bun run build-types",
+    "build-watch": "bun run clean-build && bun run build.ts --watch && bun run build-types --watch",
+    "build-types": "tsc --project tsconfig.build.json"
+  },
+  "dependencies": {
+    "@nice-code/error": "0.0.14",
+    "@nice-code/common-errors": "0.0.14",
+    "@standard-schema/spec": "^1.1.0",
+    "http-status-codes": "^2.3.0",
+    "nanoid": "^5.1.9"
+  },
+  "devDependencies": {},
+  "peerDependencies": {
+    "valibot": "^1.3.1"
+  }
+}