durablews 1.0.1 → 2.0.0-alpha.1

package/README.md

@@ -1,122 +1,92 @@
-# DurableWS (Durable Web Sockets)
-
-DurableWS is a resilient, TypeScript-based WebSocket client designed for modern web applications. It offers robust connection handling, automatic reconnection with exponential backoff, idle detection, message queueing, and easy subscription management, ensuring your application maintains a reliable real-time connection under varying network conditions.
-
-## Features
-
--   **Automatic Reconnection**: Implements exponential backoff strategy to handle disconnections gracefully.
--   **Idle Detection**: Automatically detects idle states and triggers custom handlers.
--   **Message Queueing**: Outgoing messages are queued when the connection is down and sent when it's restored.
--   **TypeScript Support**: Fully typed interfaces for a better development experience.
+# DurableWS
+
+> The WebSocket client that survives the real world — automatic reconnection,
+> bounded queueing, and typed messages. Zero dependencies, every modern
+> runtime, durable by default.
+
+> ⚠️ **v2 is in alpha** (`npm install durablews@alpha`). The features below
+> are built and tested (unit, integration, real-browser e2e); the API may
+> still shift before 2.0. The
+> [architecture RFC](https://github.com/imnsco/DurableWS/blob/main/rfcs/0001-v2-architecture.md)
+> tracks design and status. The `1.x` release predates this rewrite — don't
+> use it.
+
+## What you get
+
+- **Automatic reconnection, on by default** — full-jitter exponential
+  backoff, unlimited retries, a `shouldReconnect` veto, and `reconnecting`
+  events for your UI.
+- **Message queueing while disconnected, on by default** — bounded,
+  drop-oldest, flushed in order on open. Every dropped message fires a `drop`
+  event; nothing is silently lost.
+- **Opt-in heartbeat / idle detection** — quietly-dead links are closed (code
+  `4408`) and recovered through the normal reconnect machinery.
+- **Typed + validated messages** — pass any
+  [Standard Schema](https://standardschema.dev) (zod, valibot, arktype, …)
+  and inbound messages are type-inferred *and* runtime-validated.
+- **Middleware, inbound and outbound** — an onion pipeline with async-safe,
+  ordered outbound execution (auth/token-refresh ready).
+- **Pluggable codec** — JSON by default; swap in msgpack or anything else.
+- **Vue & React bindings in the box** — `durablews/vue` (composable) and
+  `durablews/react` (hook); the frameworks are optional peers.
+- **A drop-in `WebSocket` class** — `durablews/compat` for one-line migration
+  or `webSocketImpl` injection, with a published known-deviations table.
+- **Zero runtime dependencies**, built on the standard global `WebSocket`.
+
+## Requirements
+
+- **Node.js ≥ 22** — the first release where the global `WebSocket` is
+  available unflagged. (There is no `ws` dependency, by design.)
+- Any modern runtime with a global `WebSocket`: current browsers, Deno, Bun,
+  and Cloudflare Workers.
 
 ## Installation
 
 ```bash
-npm install durablews
-```
-
-or
-
-```bash
-yarn add durablews
+npm install durablews@alpha
 ```
 
-## Basic Usage
-
-To get started with DurableWS, first import the client in your project:
+## Quick start
 
 ```ts
 import { defineClient } from "durablews";
-```
 
-Create a new WebSocket client instance by specifying the configuration:
+const client = defineClient({ url: "wss://example.com/socket" });
 
-```ts
-const client = await defineClient({
-    url: "wss://your.websocket.server",
-    autoConnect: true, // Automatically connects
-    maxReconnectAttempts: 5,
-    maxQueueSize: 50,
-    idleTimeout: 300000, // 5 minutes
-    getToken: async () => {
-        const response = await fetch("/my/token/issuer");
-        const data = await response.json();
-        return data.token;
-    }
+client.on("message", (data) => {
+    console.log("received:", data);
 });
-```
 
-### Sending Messages
+await client.connect();
+client.send({ type: "hello", message: "world" });
 
-```typescript
-client.send({
-    action: "greet",
-    data: {
-        message: "Hello, World!"
-    }
-});
+// later
+client.close();
 ```
 
-### Handling Events
+Typed and validated, with any Standard Schema:
 
-```typescript
-client.onMessage((message) => {
-    console.log("Received message:", message);
-});
-
-client.onOpen(() => {
-    console.log("Connection opened");
-});
-
-client.onError((error) => {
-    console.error("Connection error:", error);
-});
+```ts
+import { z } from "zod";
 
-client.onClose(() => {
-    console.log("Connection closed");
-});
+const Message = z.object({ type: z.string(), body: z.string() });
+const client = defineClient({ url, schema: Message });
 
-client.onIdle(() => {
-    console.log("Client is idle");
+client.on("message", (msg) => {
+    // msg: { type: string; body: string } — validated at runtime
 });
 ```
 
-## API Reference
+## Documentation
 
-### `defineClient(config: WebSocketClientConfig): Promise<WebSocketClient>`
-
-Initializes and returns a WebSocket client instance.
-
-#### Config Options
-
--   `url`: WebSocket server URL.
--   `autoConnect` (optional): Whether to connect immediately upon instantiation.
--   `maxReconnectAttempts` (optional): Maximum number of reconnection attempts.
--   `maxQueueSize` (optional): Maximum size of the message queue.
--   `idleTimeout` (optional): Duration in milliseconds before the client is considered idle.
--   `authTokenURL` (optional): A URL for token issuance.
--   `getToken (optional): Function that returns a token for authentication. Can be synchronous or asynchronous.
-
-### WebSocketClient Methods
-
--   `send(message: Record<string, unknown>)`: Send a message through the WebSocket connection.
--   `subscribe(channelName: string)`: Subscribe to a channel.
--   `connect()`: Manually initiate the connection.
--   `disconnect()`: Disconnect the WebSocket connection.
--   `isReady()`: Returns a promise that resolves when the connection is ready.
--   `getStatus()`: Returns the current connection status.
--   `onMessage(listener: OnMessageHandler)`: Register a message event listener.
--   `onError(listener: OnErrorHandler)`: Register an error event listener.
--   `onOpen(listener: OnOpenHandler)`: Register an open event listener.
--   `onClose(listener: OnCloseHandler)`: Register a close event listener.
--   `onIdle(listener: OnIdleHandler)`: Register an idle event listener.
+**[durablews.imns.co](https://durablews.imns.co)** — getting started, guides
+(durability tuning, middleware, codecs, drop-in compat), framework pages, the
+API reference, and an honest comparison with the alternatives.
 
 ## Contributing
 
-We welcome contributions! If you'd like to contribute, please fork the repository and use a feature branch. Pull requests are warmly welcome.
-
-For major changes, please open an issue first to discuss what you would like to change.
+Contributions are welcome — see [CONTRIBUTING](https://github.com/imnsco/DurableWS/blob/main/CONTRIBUTING.md).
 
 ## License
 
-[Mozilla Public License 2.0](https://www.mozilla.org/en-US/MPL/2.0/)
+[MPL-2.0](./LICENSE) © Nate Smith

package/dist/binding-bZNBe2Bz.d.cts

@@ -0,0 +1,11 @@
+import { a as WebSocketClientConfig, W as WebSocketClient } from './types-BDvztGcG.cjs';
+
+/**
+ * What a framework binding accepts: either a config (the binding creates and
+ * **owns** the client — connecting it and closing it with the component) or an
+ * existing client (the binding only **observes** it — sharing one connection
+ * across many components without any binding taking over its lifecycle).
+ */
+type UseWebSocketSource<TIn = unknown, TOut = unknown> = WebSocketClientConfig | WebSocketClient<TIn, TOut>;
+
+export type { UseWebSocketSource as U };

package/dist/binding-gyPQiK9i.d.ts

@@ -0,0 +1,11 @@
+import { a as WebSocketClientConfig, W as WebSocketClient } from './types-BDvztGcG.js';
+
+/**
+ * What a framework binding accepts: either a config (the binding creates and
+ * **owns** the client — connecting it and closing it with the component) or an
+ * existing client (the binding only **observes** it — sharing one connection
+ * across many components without any binding taking over its lifecycle).
+ */
+type UseWebSocketSource<TIn = unknown, TOut = unknown> = WebSocketClientConfig | WebSocketClient<TIn, TOut>;
+
+export type { UseWebSocketSource as U };

package/dist/chunk-GIDTCSPD.js

@@ -0,0 +1,22 @@
+import { client } from './chunk-MG4TK53H.js';
+
+// src/helpers/binding.ts
+function resolveSource(source) {
+  if (isClient(source)) {
+    return { client: source, owned: false };
+  }
+  return {
+    client: client(source),
+    owned: true
+  };
+}
+function isClient(source) {
+  return typeof source.subscribe === "function";
+}
+function canConnect() {
+  return typeof WebSocket !== "undefined";
+}
+
+export { canConnect, resolveSource };
+//# sourceMappingURL=chunk-GIDTCSPD.js.map
+//# sourceMappingURL=chunk-GIDTCSPD.js.map

package/dist/chunk-GIDTCSPD.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/helpers/binding.ts"],"names":[],"mappings":";;;AAuBO,SAAS,cACZ,MAAA,EACyB;AACzB,EAAA,IAAI,QAAA,CAAS,MAAM,CAAA,EAAG;AAClB,IAAA,OAAO,EAAE,MAAA,EAAQ,MAAA,EAAQ,KAAA,EAAO,KAAA,EAAM;AAAA,EAC1C;AACA,EAAA,OAAO;AAAA,IACH,MAAA,EAAQ,OAAO,MAAM,CAAA;AAAA,IACrB,KAAA,EAAO;AAAA,GACX;AACJ;AAEA,SAAS,SACL,MAAA,EACoC;AACpC,EAAA,OAAO,OAAQ,OAA2B,SAAA,KAAc,UAAA;AAC5D;AAOO,SAAS,UAAA,GAAsB;AAClC,EAAA,OAAO,OAAO,SAAA,KAAc,WAAA;AAChC","file":"chunk-GIDTCSPD.js","sourcesContent":["import { client } from \"@/client\";\nimport type { WebSocketClient, WebSocketClientConfig } from \"@/types\";\n\n/**\n * What a framework binding accepts: either a config (the binding creates and\n * **owns** the client — connecting it and closing it with the component) or an\n * existing client (the binding only **observes** it — sharing one connection\n * across many components without any binding taking over its lifecycle).\n */\nexport type UseWebSocketSource<TIn = unknown, TOut = unknown> =\n    | WebSocketClientConfig\n    | WebSocketClient<TIn, TOut>;\n\nexport interface ResolvedSource<TIn = unknown, TOut = unknown> {\n    readonly client: WebSocketClient<TIn, TOut>;\n    /** Whether the binding created the client and therefore owns its lifecycle. */\n    readonly owned: boolean;\n}\n\n/**\n * Resolves a binding source into a client plus ownership. A config produces a\n * fresh, owned client; a passed-in client is borrowed as-is.\n */\nexport function resolveSource<TIn = unknown, TOut = unknown>(\n    source: UseWebSocketSource<TIn, TOut>\n): ResolvedSource<TIn, TOut> {\n    if (isClient(source)) {\n        return { client: source, owned: false };\n    }\n    return {\n        client: client(source) as WebSocketClient<TIn, TOut>,\n        owned: true\n    };\n}\n\nfunction isClient<TIn, TOut>(\n    source: UseWebSocketSource<TIn, TOut>\n): source is WebSocketClient<TIn, TOut> {\n    return typeof (source as WebSocketClient).subscribe === \"function\";\n}\n\n/**\n * Whether a standard `WebSocket` global exists. Bindings skip auto-connect in\n * its absence (e.g. SSR), so creating a component server-side never throws —\n * the client connects when setup runs again in the browser.\n */\nexport function canConnect(): boolean {\n    return typeof WebSocket !== \"undefined\";\n}\n"]}