@nice-code/action 0.21.0 → 0.23.0

package/README.md

@@ -45,6 +45,10 @@ The high-level entry points — `connectChannel` (dial out) and `serveChannel` (
 reach for 95% of the time. The lower-level handler/carrier/transport objects they desugar to are
 documented at the end under [Lower-level building blocks](#lower-level-building-blocks).
 
+> **Code blocks below are labelled by where they run:** `// shared.ts` (imported by both ends),
+> `// server.ts` (the acceptor), `// client.ts` (the connector). A typical app is exactly these three
+> files.
+
 ---
 
 ## Defining actions
@@ -52,6 +56,7 @@ documented at the end under [Lower-level building blocks](#lower-level-building-
 ### 1. Create a root domain (shared between both ends)
 
 ```ts
+// shared.ts
 import { createActionRootDomain, actionSchema } from "@nice-code/action";
 import * as v from "valibot";
 
@@ -159,6 +164,7 @@ A **local handler** runs actions in the current process. Build one and register
 is what answers incoming requests.
 
 ```ts
+// server.ts
 import { ActionRuntime, createLocalHandler, RuntimeCoordinate } from "@nice-code/action";
 
 export const serverCoord = RuntimeCoordinate.env("backend");
@@ -194,9 +200,10 @@ for local-first clients that resolve a few actions themselves and forward the re
 
 `serveChannel` is the one call that stands up an acceptor: it builds the crypto identity **once**, fans it
 across every carrier, registers your handlers, wires hibernation, and returns a server object whose
-`fetch` / `duplex` / `pushToClient` you forward straight to the host.
+`fetch` / `receive` / `drop` / `pushToClient` you forward straight to the host.
 
 ```ts
+// server.ts
 import {
   ActionRuntime,
   RuntimeCoordinate,
@@ -217,29 +224,35 @@ const server = serveChannel(runtime, appChannel, {
   ],
 });
 
-// Wire the host's events to the server:
+// Wire the host's events to the server — `receive`/`drop` are the universal forwarding seam:
 //   fetch(req)                     => server.fetch(req)
-//   webSocketMessage(ws, msg)      => server.duplex?.receive(ws, msg)
-//   webSocketClose/Error(ws)       => server.duplex?.drop(ws)
+//   webSocketMessage(ws, msg)      => server.receive(ws, msg)
+//   webSocketClose/Error(ws)       => server.drop(ws)
 ```
 
-`serveChannel(runtime, channel, options)` returns `{ handlers, fetch, duplex?, pushToClient }`:
+`serveChannel(runtime, channel, options)` returns `{ handlers, fetch, receive, drop, pushToClient, broadcast }`:
 
 - **`fetch`** — a web-standard handler that does the WS upgrade, the (secure or plain) HTTP action POST,
   CORS preflight, and a `404` fallback. Forward the host's `fetch` straight to it.
-- **`duplex`** — the `{ receive, drop }` lifecycle for the *sole* duplex carrier (a shortcut for the
-  common single-WebSocket case; `undefined` when there are zero or several — then feed each carrier
-  handle directly).
-- **`pushToClient(target, request, opts?)`** — push a server-initiated action to one connected client
-  (see [Bi-directional](#bi-directional-communication-acceptor--connector)).
+- **`receive(conn, frame)` / `drop(conn)`** — the universal connection lifecycle; forward your host's
+  message and close/error events here. Routes to the sole duplex carrier (the common single-WebSocket
+  case); with several duplex carriers, feed each carrier handle directly.
+- **`pushToClient(target, request, opts?)`** / **`broadcast(makeRequest, opts?)`** — push a
+  server-initiated action to one / every connected client (see
+  [Bi-directional](#bi-directional-communication-acceptor--connector)).
 - **`handlers`** — the acceptor handlers it built, one per duplex carrier (reach for these for per-handler
   `broadcast`).
 
 Key options: `clientEnv` (required), `storage` (required only when a carrier is secure — the default),
-`carriers`, `handlers`, plus `securityLevel` / `link` / `verifyKeyResolver` / `defaultTimeout`.
+`carriers`, `handlers`, `channelCases` (connection-aware cases — see below), plus `securityLevel` /
+`link` / `verifyKeyResolver` / `defaultTimeout`.
 
 > On Cloudflare, [`@nice-code/action/platform/cloudflare`](#cloudflare-durable-objects) collapses the
-> Durable Object carrier + storage boilerplate to one-liners.
+> Durable Object carrier + storage + lifecycle boilerplate into a single `serveDurableObject` call.
+>
+> Serving in another environment (Bun, Node, …)? `serveChannel`'s carriers are environment-neutral, and
+> `serveHost(runtime, channel, hostAdapter, options)` folds a reusable `{ carriers, storage, onServed }`
+> host adapter into it — the same seam `serveDurableObject` is built on.
 
 ### Connecting — `connectChannel`
 
@@ -251,6 +264,7 @@ from `onPush` — all derived from the channel, no restated lists. It's the exac
 `serveChannel`.
 
 ```ts
+// client.ts
 import {
   ActionRuntime,
   RuntimeCoordinate,
@@ -267,7 +281,7 @@ connectChannel(clientRuntime, appChannel, {
   storage,                            // one crypto identity, fanned across every secure transport
   securityLevel: ESecurityLevel.encrypted,
   transports: [
-    { carrier: wsCarrier("wss://api.example.com/resolve_action/ws") }, // secure WS, preferred
+    { carrier: wsCarrier(() => ({ url: "wss://api.example.com/resolve_action/ws" })) }, // secure WS, preferred
     { carrier: httpCarrier(() => ({ url: "https://api.example.com/resolve_action" })), secure: false }, // plain HTTP fallback
   ],
   // onPush: { ... }  // handlers for the channel's toConnector pushes (see below)
@@ -292,10 +306,11 @@ connectChannel(clientRuntime, appChannel, {
 
 ## Calling actions
 
-Once a runtime is wired, calling an action looks the same regardless of where it resolves (locally or
-over a carrier):
+Once a runtime is wired, calling an action looks the same on **any** side — client or server — and
+regardless of where it resolves (locally or over a carrier):
 
 ```ts
+// any runtime with the domain wired
 // Run and get the output directly (throws on a declared/transport error)
 const output = await userDomain.action.getUser
   .request({ userId: "u_123" })
@@ -325,7 +340,7 @@ connection — no second channel, no polling. The shape:
 ### Shared channel
 
 ```ts
-// Bidirectional: client sends `start_feed`; server pushes `position_update` back.
+// shared.ts — bidirectional: client sends `start_feed`; server pushes `position_update` back.
 export const lobbyDomain = appRoot.createChildDomain({
   domain: "lobby",
   actions: {
@@ -347,10 +362,11 @@ export const appChannel = defineSecureChannel({
 ### Connector side — handle pushes with `onPush`
 
 ```ts
+// client.ts
 connectChannel(clientRuntime, appChannel, {
   peer: serverCoord,
   storage,
-  transports: [{ carrier: wsCarrier(wsUrl) }, { carrier: httpCarrier(httpUrl), secure: false }],
+  transports: [{ carrier: wsCarrier(() => ({ url: wsUrl })) }, { carrier: httpCarrier(() => ({ url: httpUrl })), secure: false }],
   onPush: {
     // Keyed by the toConnector action id; input + output typed from the channel.
     position_update: async ({ player, x, y }) => {
@@ -366,6 +382,7 @@ connectChannel(clientRuntime, appChannel, {
 The local handler reads `action.context.originClient` to know who asked, then pushes to them:
 
 ```ts
+// server.ts
 const lobbyHandler = createLocalHandler().forDomainActionCases(lobbyDomain, {
   start_feed: async (action) => {
     let delivered = 0;
@@ -392,26 +409,28 @@ server.broadcast(
 );
 ```
 
-> **When a handler needs the originating connection itself** (to register it in a room, etc.) rather than
-> just the client coordinate, pass `channelCases` to `serveChannel` — each case receives the request *and*
-> that client's live connection. With several duplex carriers (no sole handler), reach for a specific
-> `server.handlers[i].broadcast(...)` and `acceptChannelConnections(handler, channel, { ... })` directly
-> (see [Lower-level building blocks](#lower-level-building-blocks)).
+> **When a handler needs the originating connection itself** (to register it in a room, track per-socket
+> state, etc.) rather than just the client coordinate, pass `channelCases` to `serveChannel` /
+> `serveDurableObject` — each case receives the request *and* an `IConnectionContext` (`conn.state` /
+> `conn.setState` / `conn.broadcast({ exceptSelf }) ` / `conn.pushBack` / `conn.connection`). With several
+> duplex carriers (no sole handler), reach for a specific `server.handlers[i].broadcast(...)` and
+> `acceptChannelConnections(handler, channel, { ... })` directly (see
+> [Lower-level building blocks](#lower-level-building-blocks)).
 
 ---
 
 ## Cloudflare Durable Objects
 
-`@nice-code/action/platform/cloudflare` collapses the DO boilerplate (the `WebSocketPair` upgrade, the
-hibernation attachment wiring, and the DO-storage adapter) into one-liners you hand to `serveChannel`.
-The core library stays platform-agnostic — nothing here is reachable from the main entry.
+`@nice-code/action/platform/cloudflare` collapses the *entire* DO transport stack — the hibernatable
+secure WebSocket, an HTTP fallback, the DO-storage crypto identity, and the `ping`/`pong` keepalive —
+into a single `serveDurableObject` call, leaving the DO to forward its four socket lifecycle methods. The
+core library stays platform-agnostic — nothing here is reachable from the main entry.
 
 ```ts
 import { DurableObject } from "cloudflare:workers";
-import { ActionRuntime, serveChannel, httpAcceptorCarrier } from "@nice-code/action";
+import { ActionRuntime } from "@nice-code/action";
 import {
-  durableObjectWsCarrier,
-  durableObjectStorage,
+  serveDurableObject,
   type TDurableObjectChannelServer,
 } from "@nice-code/action/platform/cloudflare";
 
@@ -422,13 +441,12 @@ export class MyDurableObject extends DurableObject {
     if (this._server != null) return this._server;
     const runtime = new ActionRuntime(serverCoord);
 
-    // One WS carrier (duplex — pushes + hibernation persistence) + a secure HTTP fallback (exchange),
-    // both sharing one crypto identity built from this DO's storage, surviving eviction.
-    this._server = serveChannel(runtime, appChannel, {
+    // Hibernatable secure WS + plain HTTP fallback + DO-storage crypto identity + keepalive, all folded in.
+    this._server = serveDurableObject(this.ctx, appChannel, {
+      runtime,
       clientEnv: RuntimeCoordinate.env("frontend"),
-      storage: durableObjectStorage(this.ctx, { keyPrefix: "ws:" }),
+      keyPrefix: "ws:",
       handlers: [userHandler],
-      carriers: [durableObjectWsCarrier(this.ctx), httpAcceptorCarrier()],
     });
     return this._server;
   }
@@ -437,40 +455,53 @@ export class MyDurableObject extends DurableObject {
     return this.getServer().fetch(request);
   }
   async webSocketMessage(ws: WebSocket, msg: string | ArrayBuffer) {
-    this.getServer().duplex?.receive(ws, msg);
+    this.getServer().receive(ws, msg);
   }
-  async webSocketClose(ws: WebSocket) { this.getServer().duplex?.drop(ws); }
-  async webSocketError(ws: WebSocket) { this.getServer().duplex?.drop(ws); }
+  async webSocketClose(ws: WebSocket) { this.getServer().drop(ws); }
+  async webSocketError(ws: WebSocket) { this.getServer().drop(ws); }
 }
 ```
 
-- **`durableObjectWsCarrier(ctx, { secure? })`** — a hibernatable-WebSocket acceptor carrier with `send`,
-  the `WebSocketPair` upgrade, and the socket-attachment access all derived from the DO's `ctx`. Pass
-  `secure: false` for a plain WS endpoint (then no `storage` is needed for it). It exposes the attachment to
-  `serveChannel`, which owns the layout: it persists the routing binding there and (when `connectionState`
-  is requested) co-stores per-connection app state in the *same* slot, so both survive eviction.
-- **`durableObjectStorage(ctx, { keyPrefix? })`** — wraps the DO's storage as a `StorageAdapter` for
-  `serveChannel`'s `storage`.
+`serveDurableObject(ctx, channel, options)` takes the same `serveChannel` surface (`clientEnv`,
+`handlers`, `channelCases`, `connectionState`, …) plus the host knobs:
+
+- **`runtime`** — this DO's runtime.
+- **`keyPrefix`** — namespace for the DO-storage crypto-identity keys.
+- **`httpFallback`** — `"plain"` (default), `"secure"` (handshake-protected exchange sharing the WS
+  identity), or `false` (WebSocket only).
+- **`secure`** — whether the WebSocket itself runs the handshake (default `true`).
+
+For finer control the lower-level pieces are still exported: `cloudflareDurableObjectHost(ctx, opts)`
+builds just the `{ carriers, storage, onServed }` host adapter (hand it to `serveHost`), and
+`durableObjectWsCarrier` / `durableObjectStorage` build the individual carrier / storage adapter.
 
 ### Per-connection state + broadcast (stateful DOs)
 
-A presence/room DO that tracks who's on each socket and fans messages out adds two `serveChannel` knobs —
-no `handlers[0]`, no hand-wired attachment store:
+A presence/room DO that tracks who's on each socket and fans messages out adds two knobs —
+`connectionState` (typed per-socket app state, co-stored with the routing binding so both survive a wake)
+and `channelCases`. Each case gets an **`IConnectionContext`** as its second argument — the originating
+connection plus everything a case reaches for, so it never threads `ws` through `server.connections` /
+`server.broadcast` by hand:
 
 ```ts
-const server = serveChannel(runtime, lobbyChannel, {
+const server = serveDurableObject(this.ctx, lobbyChannel, {
+  runtime,
   clientEnv: RuntimeCoordinate.env("web"),
-  storage: durableObjectStorage(this.ctx, { keyPrefix: "lobby-ws:" }),
-  carriers: [durableObjectWsCarrier(this.ctx), httpAcceptorCarrier({ secure: false })],
-  // Co-store each player's identity with the routing binding in the socket attachment (survives a wake).
+  keyPrefix: "lobby-ws:",
   connectionState: { schema: vs_player },
-  // Connection-aware cases: each gets the request + the originating socket.
   channelCases: {
-    join: (action, ws) => {
-      if (ws) server.connections.set(ws, action.input); // typed by the schema
-      server.broadcast(() => lobbyPush.action.player_joined.request(action.input), { except: ws });
+    join: (action, conn) => {
+      conn.setState(action.input); // typed by the schema; co-stored with the binding
+      conn.broadcast(() => lobbyPush.action.player_joined.request(action.input), { exceptSelf: true });
       return { players: this.roster() };
     },
+    move: (action, conn) => {
+      const player = conn.state;          // this socket's typed app state (or null)
+      if (!player) return;                // a move before join is dropped
+      conn.broadcast(() => lobbyPush.action.player_moved.request({ id: player.id, ...action.input }), {
+        exceptSelf: true,
+      });
+    },
   },
 });
 
@@ -478,12 +509,12 @@ const server = serveChannel(runtime, lobbyChannel, {
 for (const [, player] of server.connections.entries()) this.players.set(player.id, player);
 ```
 
-`connectionState` narrows the return so `server.connections` is non-optional, and `server.broadcast`
-fans out over the sole duplex carrier. The store's `read`/`write` are pluggable, so a DO that prefers to
-keep state in its SQLite/KV storage rather than the socket attachment can supply its own.
-
-Because the WS carrier persists each connection's binding on bind and replays it on construction, results
-and pushes still route to the right socket after the object wakes from eviction.
+The `IConnectionContext` (`conn`) gives a case: `conn.state` / `conn.setState(x)` / `conn.clearState()`
+(the typed app state), `conn.broadcast(makeRequest, { exceptSelf })`, `conn.pushBack(request)` (push down
+this same socket), and `conn.connection` (the raw socket, `null` on the HTTP-exchange path). Passing
+`connectionState` narrows the return so `server.connections` is non-optional. Because the WS carrier
+persists each connection's binding on bind and replays it on construction, results and pushes still route
+to the right socket after the object wakes from eviction.
 
 ---
 
@@ -514,7 +545,8 @@ plain HTTP fallback by giving the acceptor a `httpAcceptorCarrier({ secure: fals
 `serveChannel` accepts **any number of duplex carriers** (e.g. WebSocket + WebRTC) plus at most one
 exchange carrier. They all share one crypto identity and one runtime, and each result/push routes back
 over the carrier its client actually connected on (connection-aware return routing). With several duplex
-carriers, `server.duplex` is `undefined` — feed each carrier handle's own `receive`/`drop` directly.
+carriers, `server.receive`/`server.drop` throw (they can't pick a carrier) — feed each carrier handle's
+own `receive`/`drop` directly.
 
 ```ts
 const ws  = wsAcceptorCarrier({ send: wsSend, upgrade, attachmentStore });
@@ -541,19 +573,19 @@ predicate is re-evaluated per action dispatch, so the transport switches on the
 holds, with no reconnect.
 
 ```ts
-// Prefer the secure socket, but only once a session id exists; fall back to HTTP meanwhile.
+// client.ts — prefer the secure socket, but only once a session id exists; fall back to HTTP meanwhile.
 connectChannel(runtime, appChannel, {
   peer: serverCoord,
   storage,
   transports: [
     {
-      carrier: wsCarrier(`${url}/ws`, {
+      carrier: wsCarrier(() => ({ url: `${url}/ws` }), {
         // Only ever called once `available` passes, so no need for a placeholder cache key.
         getTransportCacheKey: () => [sessionId],
       }),
       available: () => sessionId != null, // ws preferred; HTTP serves while ws is gated off
     },
-    { carrier: httpCarrier(httpUrl), secure: false },
+    { carrier: httpCarrier(() => ({ url: httpUrl })), secure: false },
   ],
 });
 ```

package/build/{ActionDevtoolsCore-baIHExfj.d.mts → ActionDevtoolsCore-BjbhFqc0.d.mts}

@@ -1,4 +1,4 @@
-import { Pr as IRuntimeCoordinate, _ as TActionProgress } from "./ActionPayload.types-DXGiw1SF.mjs";
+import { _ as TActionProgress, zr as IRuntimeCoordinate } from "./ActionPayload.types-B-OSg09t.mjs";
 //#region ../nice-devtools-shared/src/components/PanelChrome.d.ts
 /** Where a devtools panel is docked. */
 type TDevtoolsPosition = "dock-bottom" | "dock-top" | "dock-left" | "dock-right";
@@ -76,4 +76,4 @@ declare class ActionDevtoolsCore {
 }
 //#endregion
 export { TDevtoolsActionStatus as a, IDevtoolsObservableDomain as i, IActionDevtoolsCoreOptions as n, TDevtoolsListener as o, IDevtoolsActionEntry as r, TDevtoolsPosition as s, ActionDevtoolsCore as t };
-//# sourceMappingURL=ActionDevtoolsCore-baIHExfj.d.mts.map
+//# sourceMappingURL=ActionDevtoolsCore-BjbhFqc0.d.mts.map

package/build/{ActionDevtoolsCore-dApyYvTS.d.cts → ActionDevtoolsCore-kk7oZBv9.d.cts}

@@ -1,4 +1,4 @@
-import { Pr as IRuntimeCoordinate, _ as TActionProgress } from "./ActionPayload.types-CQM1HRw_.cjs";
+import { _ as TActionProgress, zr as IRuntimeCoordinate } from "./ActionPayload.types-DIOeVapm.cjs";
 //#region ../nice-devtools-shared/src/components/PanelChrome.d.ts
 /** Where a devtools panel is docked. */
 type TDevtoolsPosition = "dock-bottom" | "dock-top" | "dock-left" | "dock-right";
@@ -76,4 +76,4 @@ declare class ActionDevtoolsCore {
 }
 //#endregion
 export { TDevtoolsActionStatus as a, IDevtoolsObservableDomain as i, IActionDevtoolsCoreOptions as n, TDevtoolsListener as o, IDevtoolsActionEntry as r, TDevtoolsPosition as s, ActionDevtoolsCore as t };
-//# sourceMappingURL=ActionDevtoolsCore-dApyYvTS.d.cts.map
+//# sourceMappingURL=ActionDevtoolsCore-kk7oZBv9.d.cts.map