@dojo-ng/websocket 0.1.1 → 0.1.3

package/README.md

@@ -1,12 +1,11 @@
 # @dojo-ng/websocket
 
-A framework-agnostic WebSocket client: a raw-socket wrapper (`WSocket`) and a convenience
-dispatcher on top of it (`WSDispatcher`) with request/response correlation, an offline send
-queue, reconnect with backoff, and a heartbeat watchdog. The reasoning behind each non-obvious
-behavior below is in the header comments of `src/wsocket.ts` and `src/wsdispatcher.ts`.
+A WebSocket client that reconnects, queues messages while offline, and matches each response to
+its request. Events flow through a [`@dojo-ng/pubsub`](https://www.npmjs.com/package/@dojo-ng/pubsub)
+bus in both directions.
 
-Part of the [Dojo NG framework](../../README.md) monorepo (the non-Lit runtime that complements
-`components`). BSD-3-Clause.
+Part of the [Dojo NG framework](https://foss.heptapod.net/dojo-ng/framework) packages: plain ESM
+and no Lit. BSD-3-Clause.
 
 ## Install
 
@@ -14,97 +13,101 @@ Part of the [Dojo NG framework](../../README.md) monorepo (the non-Lit runtime t
 npm install @dojo-ng/websocket
 ```
 
-## `WSocket`
+## Usage
 
-Canonicalizes differences across `WebSocket` implementations: out-of-sync detection (a live
-re-check of `socket.readyState` on every send, since the browser's own state can move before its
-event fires), backpressure (`bufferedAmount > 0` returns `BUFFERING` instead of sending),
-listener teardown before close (the reconnect-storm fix), and `open(force)` semantics.
+```js
+import { createPubSub } from "@dojo-ng/pubsub";
+import { WSDispatcher } from "@dojo-ng/websocket";
 
-```ts
-import { WSocket, SendState } from "@dojo-ng/websocket";
+const bus = createPubSub();
+const server = new WSDispatcher({
+  url: "wss://example.com/ws",
+  pubsub: bus,                   // share the app's bus; without this you get a private one
+  onConnect: () => [{ action: "event", id: 0, data: { event: "hello", params: { user: 7 } } }],
+});
 
-const ws = new WSocket("wss://example.test");
-ws.addEventListener("open", () => console.log("open"));
-ws.addEventListener("message", (e) => console.log(e.detail.data));
-ws.open();
+server.open();
 
-const state = ws.send("hello"); // SendState.OKAY | NOT_READY | BUFFERING | SEND_ERROR
-```
+// Request and response. Sent now if the socket is open, otherwise queued.
+const user = await server.call({ method: "getUser", args: [7] });
 
-Most apps want `WSDispatcher`, below, rather than `WSocket` directly — it's the layer that
-carries the actual value (queueing, correlation, reconnect, heartbeat). `WSocket` is exported
-because it's a complete, independently useful primitive on its own, not because most callers need
-to reach for it.
+// Events from the server arrive on the bus under their own name.
+bus.subscribe("chat:message", (msg) => console.log(msg), { replay: false });
 
-## `WSDispatcher`
+// Publishing to the outbound topic sends an event to the server.
+bus.publish("notify:event", { event: "chat:message", params: { text: "Hi" } });
+```
 
-```ts
-import { WSDispatcher } from "@dojo-ng/websocket";
+## What WSDispatcher handles
+
+- `onConnect` returns messages to send first on every connect and reconnect, before the queue.
+  Use it to tell the server who the user is.
+- Messages sent while the connection is down wait in a queue. A message leaves the queue only
+  after it is sent, so a failed send does not lose it.
+- After a lost connection, the client waits longer before each new try (Fibonacci backoff). A
+  successful connect resets the delay. After `close()`, it does not reconnect.
+- When the server sends `ping` messages, the client expects one at least every 40 seconds. If
+  none arrives, it closes and reconnects through the same backoff. A server that never sends a
+  ping turns this check off.
+- `call()` has no timeout. If the server never answers, the promise never settles. Use
+  `Promise.race` with a timer if you need a limit.
+- Publishing to `outboundTopic` sends an event to the server. The default topic is
+  `"notify:event"`.
+- `simulate("disconnect")` and `simulate("connect")` let you test your reconnect handling without
+  a real outage.
 
-const dispatcher = new WSDispatcher({
-	url: "wss://example.test/ws",
-	// Sent on every (re)connect, before the offline queue flushes. The app owns what identity
-	// means here — this package has no opinion beyond "send these frames first."
-	onConnect: () => [{ action: "event", id: 0, data: { event: "identify", params: { sessionId } } }],
-});
-
-dispatcher.open();
+## The wire format
 
-// A correlated request/response, queued if the socket isn't open yet and flushed on connect.
-const result = await dispatcher.call({ method: "getUser", args: [42] });
+Every message is one JSON object with `action`, `id`, and `data`. A `call` response sends back the
+same `id`, and its `data` becomes the value of the promise. An `event` carries the topic name and
+the payload.
 
-// Events flow through pub/sub in both directions — dispatcher.pubsub is a @dojo-ng/pubsub
-// instance (the caller's own, if one was passed via options.pubsub, otherwise a private one).
-// Inbound "event" frames publish under their own name; publishing to options.outboundTopic
-// (default "notify:event") sends one outbound. No new subscription concept invented.
-dispatcher.pubsub.subscribe("chat:message", (payload) => render(payload));
-dispatcher.pubsub.publish("notify:event", { event: "chat:message", params: { text: "hi" } });
+```json
+{ "action": "call",  "id": 12, "data": { "method": "getUser", "args": [7] } }
+{ "action": "event", "id": 0,  "data": { "event": "chat:message", "params": { "text": "Hi" } } }
+{ "action": "ping",  "id": 0,  "data": null }
 ```
 
-What it carries, and why each exists, is documented at length in the header comment of
-`src/wsdispatcher.ts` — request/response correlation via `Promise.withResolvers()`, an offline
-send queue that peeks and dequeues only on a confirmed send, Fibonacci-backoff reconnect (reset
-only on a successful open, suppressed entirely by an explicit `close()`), and a heartbeat
-watchdog that closes and reopens — through the same backoff path, not a bypass — if the server
-goes quiet for 40s. `dispatcher.simulate("disconnect" | "connect")` is a deliberate testing
-affordance; the playground (below) uses it.
+The full rules are in
+[the JSON Schema](https://foss.heptapod.net/dojo-ng/framework/-/blob/branch/default/packages/websocket/schema/envelope.schema.json).
+The object form was chosen after measuring: with compression, a typical session is only about
+3% larger than with a positional array.
 
-## The wire format
+## WSocket, the thinner layer
 
-`schema/envelope.schema.json` (JSON Schema draft-07) specifies the `{action, id, data}` frame
-`WSDispatcher` sends and receives, independently of the TypeScript `Envelope` type that binds it
-— the schema is the source of truth, the type is one binding of it. The object form was chosen
-over a positional-array form (`[action, id, data]`) by measurement, not argument: compressed (raw
-DEFLATE, context carried across a session — the realistic case), the object form is only 3.4%
-larger than positional over a representative session. `spike/measure-envelope.mjs` reproduces
-the measurement.
+Most apps want `WSDispatcher`. If you only want a thin wrapper, the package also exports `WSocket`.
 
-## Playground
+- It smooths over differences between WebSocket implementations.
+- `send()` returns a `SendState`: `OKAY`, `NOT_READY`, `BUFFERING`, or `SEND_ERROR`. It reports
+  `BUFFERING` instead of sending while the browser still has unsent data.
+- It removes its listeners before closing, so a reconnect does not stack old handlers.
 
-A live connection against a local echo server, demonstrating queued sends while disconnected, a
-real reconnect with Fibonacci backoff, and the heartbeat watchdog — each one driven by a control
-a real client can't perform on itself (the server dropping the connection with no handshake;
-the server going silent without closing the socket), because `simulate("disconnect")` alone
-proves the opposite case: an explicit close schedules no reconnect at all.
+```js
+import { WSocket, SendState } from "@dojo-ng/websocket";
 
-```bash
-npm run playground
-# → http://localhost:8901/packages/websocket/playground/index.html
+const ws = new WSocket("wss://example.com");
+ws.addEventListener("open", () => console.log("open"));
+ws.addEventListener("message", (e) => console.log(e.detail.data));
+ws.open();
+
+const state = ws.send("hello"); // SendState.OKAY, NOT_READY, BUFFERING, or SEND_ERROR
 ```
 
-See the comment at the top of `playground/index.html` for exactly what each button demonstrates.
+## Learn more
 
-## Testing
+The [framework runtime guide](https://dojo-ng.com/docs/framework/) shows the client together with
+[`@dojo-ng/framework`](https://www.npmjs.com/package/@dojo-ng/framework) and
+[`@dojo-ng/pubsub`](https://www.npmjs.com/package/@dojo-ng/pubsub).
 
-| Command | What it runs |
-|---|---|
-| `npm test` | `node --test` over `test/*.test.mjs` — `Queue`, `WSocket`, `WSDispatcher`, and the envelope schema, against fake sockets and (for the reconnect/heartbeat cases) `node:test`'s built-in fake timers |
-| `npm run typecheck` | `tsc --noEmit` |
+## Development
 
-No real network in any test — `test/helpers/fake-websocket.mjs` is a synchronous fake shared
-across the `WSocket` and `WSDispatcher` suites.
+- `npm test` runs the unit tests with `node --test`, against a fake socket and fake timers. No
+  test uses the network.
+- `npm run typecheck` runs `tsc --noEmit`.
+- `npm run playground` starts a local echo server and a demo page at
+  `http://localhost:8901/packages/websocket/playground/index.html`. Its buttons show the offline
+  queue, a real reconnect with backoff, and the heartbeat check.
 
 ## License
 
-BSD-3-Clause. See [LICENSE](../../LICENSE).
+BSD-3-Clause. See [LICENSE](https://foss.heptapod.net/dojo-ng/framework/-/blob/branch/default/LICENSE).

package/dist/index.js

@@ -1,4 +1,4 @@
 // Public entry point for @dojo-ng/websocket. `queue.ts`'s Queue is deliberately not re-exported
-// from this file (websocket-spec.md T2) — everything else built here is meant to be used directly.
+// from this file — everything else built here is meant to be used directly.
 export { WSocket, ReadyState, SendState } from "./wsocket.js";
 export { WSDispatcher } from "./wsdispatcher.js";

package/dist/queue.d.ts

@@ -5,7 +5,7 @@ export declare class Queue<T> {
     private length;
     /** Inserts the element at the end of the queue. Returns false if `elem` is undefined. */
     enqueue(elem: T): boolean;
-    /** Same as `enqueue` — kept because app3 call sites use both names. */
+    /** Same as `enqueue`. */
     add(elem: T): boolean;
     /** Inserts the element at the front of the queue. Returns false if `elem` is undefined. */
     pushfront(elem: T): boolean;

package/dist/queue.js

@@ -1,8 +1,6 @@
-// Internal module. Ported from app3/core/collections/src/Queue.ts (websocket-spec.md T2), as a
-// self-contained singly linked list rather than importing LinkedList.ts — LinkedList has no other
-// consumer in this tree, and the T2 decision is to port only what Queue itself needs, not the rest
-// of app3's collections module (lodash-es included). Never re-export this module from index.ts:
-// that is the whole of the T2 decision (framework-monorepo-spec.md B3, websocket-spec.md T2).
+// Internal module: a self-contained singly linked list, with only what the dispatcher's send
+// queue needs and no dependencies. Never re-export this module from index.ts: it is an
+// implementation detail, not public API.
 /** A FIFO queue backed by a singly linked list: enqueue, dequeue, and pushfront are all O(1). */
 export class Queue {
     constructor() {
@@ -14,7 +12,7 @@ export class Queue {
     enqueue(elem) {
         return this.add(elem);
     }
-    /** Same as `enqueue` — kept because app3 call sites use both names. */
+    /** Same as `enqueue`. */
     add(elem) {
         if (elem === undefined)
             return false;

package/dist/wsdispatcher.js

@@ -1,12 +1,9 @@
-// Ported from app3/core/socket/src/socket.ts (350 lines, websocket-spec.md T4). This is the task
-// that carries the value — everything in the proposal's carry list lands here except the
-// transport/envelope registries (Phase 2, deliberately unwritten until Phase 1 meets a real
-// backend). Carried behaviors, each with its own reason:
+// WebSocket message dispatch on top of `WSocket`. Behaviors, each with its own reason:
 //
 // - Request/response correlation (`call`): `#nextId++` into a callback map, resolved by id on the
-//   matching inbound frame. No timeout/reject path — app3 never had one either, and it's not on
-//   the carry list, so a pending call can wait forever on a connection that never responds. Not a
-//   bug to "fix" here; a deliberate fidelity choice, revisit only if Bill asks for it.
+//   matching inbound frame. There is no timeout/reject path, so a pending call can wait forever
+//   on a connection that never responds. This is deliberate and documented; a caller that needs a
+//   limit races the promise against a timer.
 // - Offline send queue (`#drain`): peeks and sends, dequeuing only on a confirmed OKAY send, so a
 //   failed send never drops the message. BUFFERING retries at 50ms; a confirmed send immediately
 //   tries the next one.
@@ -17,30 +14,23 @@
 //   not a bypass. `TIMEOUT_STEP`'s reset-only-on-success rule means a heartbeat failure right after
 //   a fresh open still reopens promptly, but a string of them backs off like any other flapping
 //   connection.
-// - Identity handshake (`onConnect`): app3 hardcoded a SESSID frame built from
-//   `window.hcstatic.sessionid`. Generalized into a caller-supplied hook returning frames to send
-//   first, before the queue flush — the app owns what identity means (DYNLS separation lesson),
-//   this package doesn't know what "who this is" means for any given backend.
+// - Identity handshake (`onConnect`): a caller-supplied hook returning frames to send first on
+//   every (re)connect, before the queue flush. The app owns what identity means; this package
+//   does not know what "who this is" means for any given backend.
 // - Events over pub/sub, not a bespoke API: an inbound "event" frame publishes under its own name;
 //   publishing to `outboundTopic` sends an "event" frame. No new subscription concept invented —
 //   pub/sub is the whole app-facing surface, in both directions.
 // - `simulate("disconnect" | "connect")`: a deliberate testing affordance. Reconnect logic is
 //   otherwise nearly untestable against a real backend.
 //
-// Dropped, not carried: the `queue_available` Defer-based gate around the send queue. It only ever
-// guarded synchronous code (`Queue`'s ops don't await anything), so in single-threaded JS it
-// serialized nothing that wasn't already serial — every method here runs to completion before the
-// next scheduled one starts, so there's no reentrancy hazard for it to guard against. Also dropped:
-// `createDefer` (→ `Promise.withResolvers()`), the `WeakMap` private-props pattern (→ `#private`
-// fields), `Evented`/`ws.on()` (→ `WSocket`'s `EventTarget`, from T3), lodash-es `defer`/`delay` (→
-// native `setTimeout`), all `window.hcstatic.*` coupling, and the MANHOLE/CDPPUSH actions
-// (Holmes-specific). JSON-RPC's header/response-object wrapping is also dropped — that's `core/rpc`
-// territory, out of scope for this package per the proposal's layering.
+// There is no lock around the send queue. `Queue`'s operations are synchronous, so in
+// single-threaded JS every method here runs to completion before the next scheduled one starts,
+// and there is no reentrancy hazard to guard against. Request/response wrapping such as JSON-RPC
+// headers is out of scope; that belongs in a layer above this package.
 //
-// The envelope shape below (`{ action, id, data }`) is a T4-local working assumption, not T5's
-// decision. websocket-spec.md T5 measures compressed bytes on the wire and picks the shape for
-// real; until then this object form (matching the proposal's standing lean) is what dispatch and
-// the tests here operate on.
+// The envelope shape (`{ action, id, data }`) is specified in schema/envelope.schema.json. It was
+// chosen over a positional array by measuring compressed bytes on the wire
+// (spike/measure-envelope.mjs).
 var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
     if (kind === "m") throw new TypeError("Private method is not writable");
     if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");

package/dist/wsocket.js

@@ -1,16 +1,15 @@
-// Ported from app3/core/socket/src/WebSocket.ts (216 lines, websocket-spec.md T3), de-Holmesed:
-// `logSystem` calls dropped, `Evented` replaced with `EventTarget`, and `getWS.ts`'s
-// `MozWebSocket` fallback dropped entirely (dead for over a decade). `WebSocket` is read as the
+// A thin wrapper over the browser `WebSocket`, exposed as an `EventTarget`. There is no
+// `MozWebSocket` fallback (dead for over a decade). `WebSocket` is read as the
 // global, at call time rather than a module-scope import — that's also what lets a test substitute
 // a fake one via `globalThis.WebSocket` with no constructor injection seam to design around.
 //
 // Four behaviors carried forward on purpose. Each is a real bug someone would otherwise
 // reintroduce by "simplifying" this file once it looks like it's just wrapping `new WebSocket()`:
 //
-// - Out-of-sync detection (`send`, below): app3's `is_open()` re-checked `socket.readyState` on
-//   every call, which made its own out-of-sync check in `send()` unreachable dead code — `is_open`
-//   already returned false for the same reason before `send()` ever got there. Fixed here by
-//   making `isOpen()` reflect only OUR tracked state (set on `onopen`, cleared by `#handleClose`),
+// - Out-of-sync detection (`send`, below): if `isOpen()` re-checked `socket.readyState` on every
+//   call, the out-of-sync check in `send()` would be unreachable dead code — `isOpen` would
+//   already return false for the same reason before `send()` got there. So `isOpen()` reflects
+//   only OUR tracked state (set on `onopen`, cleared by `#handleClose`),
 //   so `send()`'s live re-check of `socket.readyState` is the one thing that actually catches a
 //   socket whose `readyState` moved to CLOSING/CLOSED before its own `onclose`/`onerror` fired —
 //   which is legal per the WebSocket spec and is exactly the state this check exists to catch.
@@ -23,7 +22,7 @@
 // - `open(force)` semantics and handler wiring inside `onopen`: with no existing socket, or with
 //   `force: true`, any prior socket is torn down and a fresh one opened. `message`/`error`/`close`
 //   handlers are wired only once `onopen` fires, which is also why a pre-open error goes straight
-//   to `#handleClose` with no `error` event — the original's asymmetry, preserved because a caller
+//   to `#handleClose` with no `error` event — an asymmetry kept on purpose, because a caller
 //   distinguishing "never connected" from "connected, then errored" depends on it.
 var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
     if (kind === "m") throw new TypeError("Private method is not writable");

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@dojo-ng/websocket",
-  "version": "0.1.1",
-  "description": "Dojo NG websocket client",
+  "version": "0.1.3",
+  "description": "Dojo NG WebSocket client that reconnects, queues messages while offline, and matches responses to requests",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -12,7 +12,7 @@
   ],
   "license": "BSD-3-Clause",
   "dependencies": {
-    "@dojo-ng/pubsub": "^0.1.1"
+    "@dojo-ng/pubsub": "^0.1.3"
   },
   "devDependencies": {
     "ajv": "^8.20.0",