@dojo-ng/websocket 0.1.2 → 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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@dojo-ng/websocket",
-  "version": "0.1.2",
-  "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.2"
+    "@dojo-ng/pubsub": "^0.1.3"
   },
   "devDependencies": {
     "ajv": "^8.20.0",