@nice-code/action 0.1.0 → 0.1.1

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

@@ -3528,6 +3528,20 @@ class Transport {
   }
 }
 
+// src/ActionRuntimeEnvironment/ActionConnect/Transport/Transport.types.ts
+var ETransportType;
+((ETransportType2) => {
+  ETransportType2["ws"] = "ws";
+  ETransportType2["http"] = "http";
+})(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;
@@ -4200,16 +4214,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/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/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, MaybePromise, 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";

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nice-code/action",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "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.1",
+    "@nice-code/common-errors": "0.1.1",
     "@standard-schema/spec": "^1.1.0",
     "http-status-codes": "^2.3.0",
     "nanoid": "^5.1.9",