@nice-code/action 0.1.0 → 0.1.2

package/README.md

@@ -0,0 +1,410 @@
+# @nice-code/action
+
+A fully-typed action-based RPC framework for TypeScript. Define actions once, execute them locally or over HTTP/WebSocket — same code, same types, everywhere.
+
+## Why?
+
+Modern apps split logic across server, client, and workers. Typed RPC frameworks help, but most still require separate client/server type definitions, custom serialization glue, and ad-hoc error handling. `@nice-code/action` solves this with:
+
+- **One definition, every environment** — same action works locally, over HTTP, or WebSocket
+- **Custom serialization baked in** — `Date`, `Map`, `Buffer` — define it once, it works across the wire automatically
+- **Typed error unions** — declare which errors an action throws; TypeScript enforces handling them
+- **Observable** — attach listeners for logging, analytics, or tracing with zero boilerplate
+
+---
+
+## Install
+
+```bash
+bun add @nice-code/action @nice-code/error valibot
+```
+
+---
+
+## Core Concepts
+
+Actions flow through three states:
+
+```
+NiceAction (definition) → NiceActionPrimed (input attached) → NiceActionResponse (result)
+```
+
+You mostly work with `NiceAction` and let the framework handle the rest.
+
+---
+
+## Quick Start
+
+### 1. Define a domain and its actions
+
+```typescript
+import { createActionRootDomain, action } from "@nice-code/action";
+import * as v from "valibot";
+
+const root = createActionRootDomain({ domain: "app" });
+
+const orderDomain = root.createChildDomain({
+  domain: "order",
+  actions: {
+    placeOrder: action()
+      .input({ schema: v.object({ items: v.array(v.string()), total: v.number() }) })
+      .output({ schema: v.object({ orderId: v.string(), estimatedDelivery: v.string() }) }),
+
+    cancelOrder: action()
+      .input({ schema: v.object({ orderId: v.string(), reason: v.string() }) })
+      .output({ schema: v.object({ refundAmount: v.number() }) }),
+  },
+});
+```
+
+### 2. Register handlers
+
+```typescript
+import { ActionHandler, createActionRuntime } from "@nice-code/action";
+
+const handler = new ActionHandler()
+  .forAction(orderDomain, "placeOrder", {
+    execution: async (primed) => {
+      const { items, total } = primed.input; // fully typed
+      const order = await db.orders.create({ items, total });
+      return primed.setResponse({
+        orderId: order.id,
+        estimatedDelivery: "2-3 business days",
+      });
+    },
+  })
+  .forAction(orderDomain, "cancelOrder", {
+    execution: async (primed) => {
+      const refund = await payments.refund(primed.input.orderId);
+      return primed.setResponse({ refundAmount: refund.amount });
+    },
+  });
+
+root.setRuntimeEnvironment(
+  createActionRuntime({ envId: "server" }).addHandlers([handler])
+);
+```
+
+### 3. Execute
+
+```typescript
+const result = await orderDomain.action("placeOrder").execute({
+  items: ["SKU-001", "SKU-002"],
+  total: 49.99,
+});
+// result: { orderId: "ord_abc123", estimatedDelivery: "2-3 business days" }
+```
+
+---
+
+## Typed Error Handling
+
+Declare errors your action can throw — TypeScript tracks them through `executeSafe()`.
+
+```typescript
+import { err_auth, err_payment } from "@nice-code/common-errors";
+
+const checkoutDomain = root.createChildDomain({
+  domain: "checkout",
+  actions: {
+    pay: action()
+      .input({ schema: v.object({ cartId: v.string(), cardToken: v.string() }) })
+      .output({ schema: v.object({ receiptId: v.string() }) })
+      .throws(err_auth, ["unauthenticated"])        // only this error from auth domain
+      .throws(err_payment),                         // all payment errors
+  },
+});
+```
+
+```typescript
+const result = await checkoutDomain.action("pay").executeSafe({
+  cartId: "cart_xyz",
+  cardToken: "tok_...",
+});
+
+if (!result.ok) {
+  // result.error is a fully typed NiceError union
+  result.error.handleWithSync([
+    forId(err_auth, "unauthenticated", () => res.status(401).json({ error: "Login required" })),
+    forId(err_payment, "card_declined", (err) => {
+      const { last4 } = err.getContext();
+      res.status(402).json({ error: `Card ending in ${last4} was declined` });
+    }),
+    forDomain(err_payment, () => res.status(402).json({ error: "Payment failed" })),
+  ]);
+  return;
+}
+
+// result.output: { receiptId: string }
+res.json({ receiptId: result.output.receiptId });
+```
+
+---
+
+## Custom Serialization
+
+Non-JSON types — `Date`, `Map`, binary — need serialization for transport. Define it once on the schema; the framework handles it on both ends.
+
+```typescript
+const eventDomain = root.createChildDomain({
+  domain: "event",
+  actions: {
+    schedule: action()
+      .input(
+        { schema: v.object({ name: v.string(), scheduledAt: v.date() }) },
+        // serialize: Date → ISO string for the wire
+        ({ name, scheduledAt }) => ({ name, iso: scheduledAt.toISOString() }),
+        // deserialize: ISO string → Date on the other end
+        ({ name, iso }) => ({ name, scheduledAt: new Date(iso) })
+      )
+      .output({ schema: v.object({ eventId: v.string() }) }),
+  },
+});
+```
+
+```typescript
+// Client sends this:
+await eventDomain.action("schedule").execute({
+  name: "Team meeting",
+  scheduledAt: new Date("2025-03-15T14:00:00Z"), // ← native Date
+});
+
+// Wire format (what actually travels over HTTP):
+// { name: "Team meeting", iso: "2025-03-15T14:00:00.000Z" }
+
+// Server receives native Date automatically — no manual parsing
+handler.forAction(eventDomain, "schedule", {
+  execution: async (primed) => {
+    console.log(primed.input.scheduledAt instanceof Date); // true
+    await calendar.create(primed.input.scheduledAt);
+    return primed.setResponse({ eventId: "evt_..." });
+  },
+});
+```
+
+---
+
+## Same Actions, Different Environments
+
+The same domain definition works on both server (with handlers) and client (with remote transport). No code duplication.
+
+### Server
+
+```typescript
+// server.ts
+const handler = new ActionHandler().forDomain(orderDomain, {
+  execution: async (primed) => {
+    /* ... real DB logic ... */
+  },
+});
+
+root.setRuntimeEnvironment(
+  createActionRuntime({ envId: "server" }).addHandlers([handler])
+);
+
+// One endpoint handles all actions
+app.post("/actions", async (req, res) => {
+  const result = await handler.handleWire(req.body);
+  if (!result.handled) return res.status(404).end();
+  res.json(result.response.toJsonObject());
+});
+```
+
+### Client
+
+```typescript
+// client.ts — exact same domain, different runtime
+import { ActionConnect, ConnectionConfig, createActionRuntime } from "@nice-code/action";
+
+const connect = new ActionConnect(
+  [new ConnectionConfig({ transports: [{ type: "http", url: "/actions" }] })],
+  { requestTimeout: 30_000 }
+).routeDomain(orderDomain);
+
+root.setRuntimeEnvironment(
+  createActionRuntime({ envId: "browser" }).addHandlers([connect])
+);
+
+// Works exactly like local execution — goes over HTTP transparently
+const result = await orderDomain.action("placeOrder").execute({
+  items: ["SKU-001"],
+  total: 29.99,
+});
+```
+
+### WebSocket for real-time
+
+```typescript
+new ConnectionConfig({
+  transports: [
+    { type: "ws", url: "wss://api.example.com/ws" }, // persistent connection, no reconnect overhead
+    { type: "http", url: "/actions" },               // fallback
+  ],
+})
+```
+
+---
+
+## Observability
+
+Attach listeners to any domain — fire for every action without modifying handlers.
+
+```typescript
+const unsubscribe = orderDomain.addActionListener({
+  execution: (primed, { runtime }) => {
+    logger.info(`[${runtime.name}] → ${primed.domain}::${primed.id}`, primed.input);
+  },
+  response: (response, { runtime }) => {
+    const { result } = response;
+    if (result.ok) {
+      metrics.increment(`action.success`, { action: response.id });
+    } else {
+      metrics.increment(`action.error`, { action: response.id, error: result.error.id });
+    }
+  },
+});
+
+// Clean up when done
+unsubscribe();
+```
+
+---
+
+## Pattern Matching
+
+When you receive an action and need to branch on its identity:
+
+```typescript
+import { matchAction } from "@nice-code/action";
+
+await matchAction(incomingAction)
+  .with({
+    domain: orderDomain,
+    id: "placeOrder",
+    handler: async (action) => {
+      // action narrowed to NiceAction<OrderDomain, "placeOrder">
+      await notifyWarehouse(action.input);
+    },
+  })
+  .with({
+    domain: orderDomain,
+    id: "cancelOrder",
+    handler: async (action) => {
+      await notifyCustomer(action.input.orderId);
+    },
+  })
+  .otherwise(async (action) => {
+    logger.warn(`Unhandled action: ${action.domain}::${action.id}`);
+  })
+  .runAsync();
+```
+
+---
+
+## Wire Format
+
+Every action state serializes to JSON — useful for logging, queuing, or replay:
+
+```typescript
+const primed = orderDomain.action("placeOrder").prime({ items: ["SKU-001"], total: 29.99 });
+
+const wire = primed.toJsonObject();
+// {
+//   type: "primed",
+//   domain: "order",
+//   allDomains: ["order", "app"],
+//   id: "placeOrder",
+//   cuid: "abc123...",
+//   timeCreated: 1704067200000,
+//   timePrimed: 1704067201000,
+//   input: { items: ["SKU-001"], total: 29.99 }
+// }
+
+// Reconstruct anywhere
+const rehydrated = orderDomain.hydratePrimed(wire);
+await rehydrated.execute(); // executes with original input
+```
+
+Store actions in a queue, ship them to a worker, execute on the other side — full round-trip with validation.
+
+---
+
+## Named Handlers (Tags)
+
+Route different action types to different handlers — useful for auth tiers, feature flags, or test overrides.
+
+```typescript
+const adminHandler = new ActionHandler({ tag: "admin" })
+  .forAction(userDomain, "deleteUser", {
+    execution: async (primed) => { /* admin-only logic */ },
+  });
+
+const publicHandler = new ActionHandler()
+  .forDomain(userDomain, { execution: handlePublicActions });
+
+root.setRuntimeEnvironment(
+  createActionRuntime({ envId: "server" })
+    .addHandlers([adminHandler, publicHandler])
+);
+
+// Use the tagged handler explicitly
+await userDomain.action("deleteUser").execute(input, { tag: "admin" });
+```
+
+---
+
+## API Reference
+
+### Domain
+
+| Method | Description |
+|---|---|
+| `createActionRootDomain({ domain })` | Create root domain |
+| `root.createChildDomain({ domain, actions })` | Create child domain |
+| `domain.action(id)` | Get action definition |
+| `domain.addActionListener({ execution?, response? })` | Observe all actions; returns unsubscribe fn |
+| `domain.hydratePrimed(wire)` | Reconstruct primed action from JSON |
+| `domain.hydrateResponse(wire)` | Reconstruct response from JSON |
+
+### Action
+
+| Method | Description |
+|---|---|
+| `action.execute(input, meta?)` | Execute; throws on error |
+| `action.executeSafe(input, meta?)` | Execute; returns `{ ok, output }` or `{ ok, error }` |
+| `action.prime(input)` | Attach and validate input |
+| `action.is(other)` | Type guard — check if action matches this definition |
+
+### Schema Builder (`action()`)
+
+| Method | Description |
+|---|---|
+| `.input({ schema }, serialize?, deserialize?)` | Declare input schema + optional serde |
+| `.output({ schema }, serialize?, deserialize?)` | Declare output schema + optional serde |
+| `.throws(errorDomain, [ids]?)` | Declare throwable errors (all or subset) |
+
+### Handlers
+
+| Class | Use case |
+|---|---|
+| `ActionHandler` | Local/same-process execution |
+| `ActionConnect` | Remote execution over HTTP or WebSocket |
+
+### ActionHandler
+
+| Method | Description |
+|---|---|
+| `.forAction(domain, id, { execution, response? })` | Handle one action |
+| `.forActionIds(domain, ids, { execution, response? })` | Handle a subset |
+| `.forDomain(domain, { execution, response? })` | Handle all actions in domain |
+| `.forDomainActionCases(domain, cases)` | Handle actions via case map |
+| `.handleWire(body)` | Parse and dispatch raw JSON (for HTTP endpoints) |
+
+### ActionConnect
+
+| Method | Description |
+|---|---|
+| `.routeDomain(domain, route?)` | Route all domain actions remotely |
+| `.routeAction(domain, id, route?)` | Route one action remotely |
+| `.routeActionIds(domain, ids, route?)` | Route a subset remotely |
+| `.disconnect()` | Close connections |

package/build/index.js

@@ -3393,6 +3393,7 @@ var EErrId_NiceTransport;
 ((EErrId_NiceTransport2) => {
   EErrId_NiceTransport2["timeout"] = "timeout";
   EErrId_NiceTransport2["not_found"] = "not_found";
+  EErrId_NiceTransport2["not_available"] = "not_available";
   EErrId_NiceTransport2["initialization_failed"] = "initialization_failed";
   EErrId_NiceTransport2["send_failed"] = "send_failed";
   EErrId_NiceTransport2["invalid_action_response"] = "invalid_action_response";
@@ -3406,6 +3407,9 @@ var err_nice_transport = err_nice_connect.createChildDomain({
     ["not_found" /* not_found */]: err({
       message: ({ actionId, routeKey, tag }) => `No connected transport found for action "${actionId}"${routeKey ? ` with route key "${routeKey}"` : ``}${tag ? ` and action tag "${tag}"` : ""}.`
     }),
+    ["not_available" /* not_available */]: err({
+      message: ({ transportCount }) => `${transportCount} Transport(s) found but were filtered out via filterUsage().`
+    }),
     ["initialization_failed" /* initialization_failed */]: err({
       message: ({ actionId, routeKey, tag }) => `Transports found for action "${actionId}"${routeKey ? ` with route key "${routeKey}"` : ""}${tag ? ` and action tag "${tag}"` : ""}, but none are ready.`
     }),
@@ -3487,13 +3491,21 @@ class Transport {
   def;
   type;
   requestResolvers = new Map;
+  _filterUsage;
   constructor(def) {
     this.def = def;
     this.type = def.type;
+    this._filterUsage = def.filterUsage;
   }
   get status() {
     return this._status;
   }
+  filterUsage(primed) {
+    if (this._filterUsage == null) {
+      return true;
+    }
+    return this._filterUsage(primed);
+  }
   checkAndPrepare() {
     return this._status;
   }
@@ -3528,6 +3540,21 @@ class Transport {
   }
 }
 
+// src/ActionRuntimeEnvironment/ActionConnect/Transport/Transport.types.ts
+var ETransportType;
+((ETransportType2) => {
+  ETransportType2["ws"] = "ws";
+  ETransportType2["http"] = "http";
+  ETransportType2["custom"] = "custom";
+})(ETransportType ||= {});
+var ETransportStatus;
+((ETransportStatus2) => {
+  ETransportStatus2["uninitialized"] = "uninitialized";
+  ETransportStatus2["initializing"] = "initializing";
+  ETransportStatus2["ready"] = "ready";
+  ETransportStatus2["failed"] = "failed";
+})(ETransportStatus ||= {});
+
 // src/ActionRuntimeEnvironment/ActionConnect/Transport/TransportHttp.ts
 class TransportHttp extends Transport {
   abortControllers = new Map;
@@ -3607,6 +3634,7 @@ var err_nice_transport_ws = err_nice_transport.createChildDomain({
 class TransportWebSocket extends Transport {
   websocket;
   _status = { status: "uninitialized" /* uninitialized */ };
+  _customMessageSerde;
   constructor(def) {
     super(def);
   }
@@ -3628,21 +3656,24 @@ class TransportWebSocket extends Transport {
       waitForInitialization
     };
   }
-  handleMessage(data) {
+  handlePureActionResponseMessage(message) {
     let json;
     try {
-      json = JSON.parse(data);
+      json = JSON.parse(message);
     } catch {
       return;
     }
     if (!isActionResponseJsonObject(json)) {
       return;
     }
-    const pending = this.requestResolvers.get(json.cuid);
+    return json;
+  }
+  handleResponse(response) {
+    const pending = this.requestResolvers.get(response.cuid);
     if (pending == null) {
       return;
     }
-    this.respond(pending.primed.coreAction.actionDomain.hydrateResponse(json));
+    this.respond(pending.primed.coreAction.actionDomain.hydrateResponse(response));
   }
   rejectPendingWebSocketRequests(error) {
     for (const [, pending] of this.requestResolvers) {
@@ -3662,7 +3693,9 @@ class TransportWebSocket extends Transport {
       }
     };
     try {
-      this.websocket = await this.def.createWebSocket();
+      const { ws, customMessageSerde } = await this.def.createWebSocket();
+      this.websocket = ws;
+      this._customMessageSerde = customMessageSerde;
     } catch (e2) {
       console.error("Failed to create WebSocket:", e2);
       const error = err_nice_transport_ws.fromId("ws_create_failed" /* ws_create_failed */, {
@@ -3687,7 +3720,10 @@ class TransportWebSocket extends Transport {
     });
     this.websocket.addEventListener("message", (event) => {
       if (typeof event.data === "string") {
-        this.handleMessage(event.data);
+        const response = this._customMessageSerde?.deserialize?.(event.data) ?? this.handlePureActionResponseMessage(event.data);
+        if (response) {
+          this.handleResponse(response);
+        }
       }
     });
     this.websocket.addEventListener("close", (event) => {
@@ -3759,7 +3795,23 @@ class ConnectionConfig {
   async dispatch(primed, defaultTimeout) {
     const timeout = this.config.defaultTimeout ?? defaultTimeout;
     const initializingWaiters = [];
+    const unavailableTransports = [];
     for (const transport of this._transports) {
+      const isAvailable = transport.filterUsage(primed);
+      if (isAvailable instanceof Promise) {
+        try {
+          if (!await isAvailable) {
+            unavailableTransports.push(transport);
+            continue;
+          }
+        } catch {
+          unavailableTransports.push(transport);
+          continue;
+        }
+      } else if (!isAvailable) {
+        unavailableTransports.push(transport);
+        continue;
+      }
       const statusInfo = transport.checkAndPrepare();
       if (statusInfo.status === "ready" /* ready */) {
         return transport.makeRequest(primed, timeout);
@@ -3774,6 +3826,11 @@ class ConnectionConfig {
       }
     }
     if (initializingWaiters.length === 0) {
+      if (unavailableTransports.length > 0) {
+        throw err_nice_transport.fromId("not_available" /* not_available */, {
+          transportCount: unavailableTransports.length
+        });
+      }
       throw err_nice_transport.fromId("not_found" /* not_found */, {
         actionId: primed.id
       });
@@ -4200,16 +4257,22 @@ export {
   createActionRuntime,
   createActionRootDomain,
   action,
-  ConnectionConfig as Transport,
+  TransportWebSocket,
+  TransportHttp,
+  Transport,
   NiceActionSchema,
+  NiceActionRootDomain,
   NiceActionResponse,
   NiceActionPrimed,
   NiceActionDomain,
   NiceAction,
+  ETransportType,
+  ETransportStatus,
   EErrId_NiceTransport_WebSocket,
   EErrId_NiceTransport,
   EErrId_NiceAction,
   EActionState,
+  ConnectionConfig,
   ActionRuntimeEnvironment,
   ActionHandler,
   ActionConnect

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

@@ -1,6 +1,5 @@
 import type { NiceActionSchema } from "../ActionSchema/NiceActionSchema";
 import type { INiceActionErrorDeclaration, TTransportedValue } from "../ActionSchema/NiceActionSchema.types";
-export type MaybePromise<T> = T | Promise<T>;
 export type TPossibleDomainId = string;
 export type TPossibleDomainIdList = [TPossibleDomainId, ...TPossibleDomainId[]];
 export type TNiceActionDomainSchema = Record<string, NiceActionSchema<TTransportedValue<any, any>, TTransportedValue<any, any>, readonly INiceActionErrorDeclaration<any, any>[]>>;

package/build/types/ActionRuntimeEnvironment/ActionConnect/Transport/Transport.d.ts

@@ -1,3 +1,4 @@
+import type { MaybePromise } from "../../..";
 import type { NiceActionPrimed } from "../../../NiceAction/NiceActionPrimed";
 import type { NiceActionResponse } from "../../../NiceAction/NiceActionResponse";
 import { type ITransportPendingRequest, type TActionTransportDef, type TTransportStatusInfo } from "./Transport.types";
@@ -6,8 +7,10 @@ export declare abstract class Transport<DEF extends TActionTransportDef> {
     readonly type: DEF["type"];
     readonly requestResolvers: Map<string, ITransportPendingRequest>;
     protected abstract _status: TTransportStatusInfo;
+    protected _filterUsage?: (primed: NiceActionPrimed<any>) => MaybePromise<boolean>;
     constructor(def: DEF);
     get status(): TTransportStatusInfo;
+    filterUsage(primed: NiceActionPrimed<any>): MaybePromise<boolean>;
     checkAndPrepare(): TTransportStatusInfo;
     protected abstract send(primed: NiceActionPrimed<any>): Promise<void>;
     abstract disconnect(): void;

package/build/types/ActionRuntimeEnvironment/ActionConnect/Transport/Transport.types.d.ts

@@ -1,10 +1,12 @@
-import type { NiceError } from "@nice-code/error";
+import type { MaybePromise, NiceError } from "@nice-code/error";
+import type { INiceActionPrimed_JsonObject, TNiceActionResponse_JsonObject } from "../../../NiceAction/NiceAction.types";
 import type { NiceActionPrimed } from "../../../NiceAction/NiceActionPrimed";
 import type { NiceActionResponse } from "../../../NiceAction/NiceActionResponse";
 import type { Transport } from "./Transport";
 export declare enum ETransportType {
     ws = "ws",
-    http = "http"
+    http = "http",
+    custom = "custom"
 }
 export declare enum ETransportStatus {
     uninitialized = "uninitialized",
@@ -31,16 +33,34 @@ export type TTransportStatusInfo = ITransportStatusInfo_Base<ETransportStatus.un
 export interface IActionTransport_Base {
     /** Per-transport timeout override (ms) */
     timeout?: number;
+    filterUsage?: (primed: NiceActionPrimed<any>) => MaybePromise<boolean>;
+}
+export interface ICustomWebsocketMessageSerde {
+    serialize?: (primedJson: INiceActionPrimed_JsonObject<any>) => string;
+    deserialize?: (message: string) => TNiceActionResponse_JsonObject<any>;
 }
 export interface IActionTransportDef_Ws extends IActionTransport_Base {
     type: ETransportType.ws;
-    createWebSocket: () => Promise<WebSocket>;
+    createWebSocket: () => Promise<{
+        ws: WebSocket;
+        customMessageSerde?: ICustomWebsocketMessageSerde;
+    }>;
 }
 export interface IActionTransportDef_Http extends IActionTransport_Base {
     type: ETransportType.http;
     url: string;
 }
-export type TActionTransportDef = IActionTransportDef_Ws | IActionTransportDef_Http;
+export interface ICustomActionTransport {
+    checkAndPrepare: () => TTransportStatusInfo;
+    handleAction: (primed: NiceActionPrimed<any>, onResponse: (response: NiceActionResponse<any>) => void) => Promise<void>;
+    onDisconnect: () => void;
+}
+export interface IActionTransportDef_Custom extends IActionTransport_Base {
+    type: ETransportType.custom;
+    initialStatus: TTransportStatusInfo;
+    createTransport: () => ICustomActionTransport;
+}
+export type TActionTransportDef = IActionTransportDef_Ws | IActionTransportDef_Http | IActionTransportDef_Custom;
 export interface ITransportPendingRequest {
     type: ETransportType;
     resolve: (response: NiceActionResponse<any>) => void;

package/build/types/ActionRuntimeEnvironment/ActionConnect/Transport/TransportCustom.d.ts

@@ -0,0 +1,12 @@
+import type { NiceActionPrimed } from "../../../NiceAction/NiceActionPrimed";
+import { Transport } from "./Transport";
+import { type IActionTransportDef_Custom, type TTransportStatusInfo } from "./Transport.types";
+export declare class TransportCustom extends Transport<IActionTransportDef_Custom> {
+    readonly abortControllers: Map<string, AbortController>;
+    protected _status: TTransportStatusInfo;
+    private _customTransport;
+    constructor(def: IActionTransportDef_Custom);
+    checkAndPrepare(): TTransportStatusInfo;
+    send(primed: NiceActionPrimed<any>): Promise<void>;
+    disconnect(): void;
+}

package/build/types/ActionRuntimeEnvironment/ActionConnect/Transport/TransportWebSocket.d.ts

@@ -4,10 +4,12 @@ import { type IActionTransportDef_Ws, type TTransportStatusInfo } from "./Transp
 export declare class TransportWebSocket extends Transport<IActionTransportDef_Ws> {
     websocket?: WebSocket;
     protected _status: TTransportStatusInfo;
+    private _customMessageSerde?;
     constructor(def: IActionTransportDef_Ws);
     checkAndPrepare(): TTransportStatusInfo;
     private startInitializing;
-    private handleMessage;
+    private handlePureActionResponseMessage;
+    private handleResponse;
     private rejectPendingWebSocketRequests;
     private _connect;
     protected send(primed: NiceActionPrimed<any>): Promise<void>;

package/build/types/ActionRuntimeEnvironment/ActionConnect/Transport/err_nice_transport.d.ts

@@ -1,6 +1,7 @@
 export declare enum EErrId_NiceTransport {
     timeout = "timeout",
     not_found = "not_found",
+    not_available = "not_available",
     initialization_failed = "initialization_failed",
     send_failed = "send_failed",
     invalid_action_response = "invalid_action_response"
@@ -17,6 +18,9 @@ export declare const err_nice_transport: import("@nice-code/error").NiceErrorDom
             routeKey?: string;
             tag?: string;
         }, import("@nice-code/error").JSONSerializableValue>;
+        not_available: import("@nice-code/error").INiceErrorIdMetadata<{
+            transportCount: number;
+        }, import("@nice-code/error").JSONSerializableValue>;
         initialization_failed: import("@nice-code/error").INiceErrorIdMetadata<{
             actionId: string;
             routeKey?: string;

package/build/types/ActionRuntimeEnvironment/ActionHandler/ActionHandler.d.ts

@@ -15,7 +15,7 @@ export declare class ActionHandler implements IActionHandler {
     private getHandlersForAction;
     /**
      * Register a handler for all actions in a domain.
-     * Receives the full primed action — use `domain.matchAction()` to narrow by id.
+     * Receives the full primed action — use `matchAction()` to narrow to a specific action id.
      * Useful for forwarding all domain actions to a remote endpoint.
      * Lower priority than `forAction`.
      */

package/build/types/ActionRuntimeEnvironment/ActionHandler/ActionHandler.types.d.ts

@@ -1,8 +1,9 @@
-import type { INiceActionDomain, MaybePromise, TInferOutputFromSchema } from "../../ActionDomain/NiceActionDomain.types";
+import type { INiceActionDomain, TInferOutputFromSchema } from "../../ActionDomain/NiceActionDomain.types";
 import type { INiceAction, TNiceActionResponse_JsonObject } from "../../NiceAction/NiceAction.types";
 import type { TDistributedDomainActions } from "../../NiceAction/NiceActionCombined.types";
 import type { NiceActionPrimed } from "../../NiceAction/NiceActionPrimed";
 import type { NiceActionResponse } from "../../NiceAction/NiceActionResponse";
+import type { MaybePromise } from "../../utils/maybePromise";
 import type { IRuntimeEnvironmentMeta } from "../ActionRuntimeEnvironment.types";
 export type TAtLeastOne<T extends object> = {
     [K in keyof T]-?: Required<Pick<T, K>> & Partial<Omit<T, K>>;

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

@@ -1,4 +1,5 @@
-import type { INiceActionDomain, MaybePromise } from "../../ActionDomain/NiceActionDomain.types";
+import type { INiceActionDomain } from "../../ActionDomain/NiceActionDomain.types";
+import type { MaybePromise } from "../../utils/maybePromise";
 import type { INiceAction } from "../NiceAction.types";
 import type { TNarrowActionType } from "../NiceActionCombined.types";
 type TMatchHandler<A extends INiceAction<any>> = (action: A) => MaybePromise<void>;

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

@@ -39,7 +39,7 @@ export declare class NiceAction<DOM extends INiceActionDomain, ID extends keyof
      * ```ts
      * const result = await domain.action("getUser").executeSafe({ userId: "123" });
      * if (!result.ok) {
-     *   result.error.handleWith([
+     *   result.error.handleWithSync([
      *     forDomain(err_auth, (h) => res.status(401).end()),
      *   ]);
      *   return;

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

@@ -39,7 +39,7 @@ export type INiceActionPrimed_JsonObject<DOM extends INiceActionDomain = INiceAc
  * ```ts
  * const result = await domain.action("getUser").executeSafe({ userId: "123" });
  * if (!result.ok) {
- *   result.error.handleWith([
+ *   result.error.handleWithSync([
  *     forDomain(err_auth, (h) => res.status(401).end()),
  *   ]);
  *   return;

package/build/types/index.d.ts

@@ -1,12 +1,18 @@
 export { createActionRootDomain } from "./ActionDomain/helpers/createRootActionDomain";
 export { NiceActionDomain } from "./ActionDomain/NiceActionDomain";
-export type { INiceActionDomain, INiceActionDomainChildOptions, MaybePromise, TDomainActionId, TInferInputFromSchema, TInferOutputFromSchema, TNiceActionDomainChildDef, TNiceActionDomainSchema, TPossibleDomainId, TPossibleDomainIdList, } from "./ActionDomain/NiceActionDomain.types";
+export type { INiceActionDomain, INiceActionDomainChildOptions, INiceActionRootDomain, TDomainActionId, TInferInputFromSchema, TInferOutputFromSchema, TNiceActionDomainChildDef, TNiceActionDomainSchema, TPossibleDomainId, TPossibleDomainIdList, } from "./ActionDomain/NiceActionDomain.types";
+export { NiceActionRootDomain } from "./ActionDomain/RootDomain/NiceActionRootDomain";
 export { ActionConnect } from "./ActionRuntimeEnvironment/ActionConnect/ActionConnect";
 export * from "./ActionRuntimeEnvironment/ActionConnect/ActionConnect.types";
-export { ConnectionConfig as Transport } from "./ActionRuntimeEnvironment/ActionConnect/ConnectionConfig/ConnectionConfig";
+export { ConnectionConfig } from "./ActionRuntimeEnvironment/ActionConnect/ConnectionConfig/ConnectionConfig";
+export * from "./ActionRuntimeEnvironment/ActionConnect/ConnectionConfig/ConnectionConfig.types";
 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 * from "./ActionRuntimeEnvironment/ActionConnect/Transport/Transport";
+export * from "./ActionRuntimeEnvironment/ActionConnect/Transport/Transport.types";
+export * from "./ActionRuntimeEnvironment/ActionConnect/Transport/TransportHttp";
+export * from "./ActionRuntimeEnvironment/ActionConnect/Transport/TransportWebSocket";
 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";
@@ -24,3 +30,4 @@ export { NiceActionPrimed } from "./NiceAction/NiceActionPrimed";
 export { NiceActionResponse } from "./NiceAction/NiceActionResponse";
 export * from "./utils/isActionResponseJsonObject";
 export * from "./utils/isPrimedActionJsonObject";
+export * from "./utils/maybePromise";

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

@@ -37,7 +37,7 @@ export type TUseNiceMutationOptions<DOM extends INiceActionDomain, ID extends ke
  * 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.
+ * 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.
@@ -59,7 +59,7 @@ export declare function useNiceQuery<DOM extends INiceActionDomain, ID extends k
  * 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.
+ * The `tag` option targets a specific named handler registered on the runtime environment.
  *
  * @example
  * const mutation = useNiceMutation(domain.action("createUser"));

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

@@ -0,0 +1 @@
+export type MaybePromise<T> = T | Promise<T>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nice-code/action",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "private": false,
   "type": "module",
   "exports": {
@@ -32,8 +32,8 @@
     "build-types": "tsc --project tsconfig.build.json"
   },
   "dependencies": {
-    "@nice-code/error": "0.1.0",
-    "@nice-code/common-errors": "0.1.0",
+    "@nice-code/error": "0.1.2",
+    "@nice-code/common-errors": "0.1.2",
     "@standard-schema/spec": "^1.1.0",
     "http-status-codes": "^2.3.0",
     "nanoid": "^5.1.9",