durablews 1.0.0 → 2.0.0-alpha.0

package/README.md

@@ -1,118 +1,74 @@
-# DurableWS (Durable Web Sockets)
+# DurableWS
 
-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.
+> A resilient, modern, zero-dependency WebSocket **client** for TypeScript — built on the standard `WebSocket`, durable by default, and the same in every modern runtime.
 
-## Features
+> ⚠️ **v2 is under active development (`2.0.0-alpha`).** The API is changing and several headline features below are still being built. See the [v2 architecture RFC](https://github.com/imnsco/DurableWS/blob/main/rfcs/0001-v2-architecture.md) for the design and live status. The current npm release (`1.x`) predates this redesign.
 
--   **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.
--   **Subscription Management**: Simplifies subscribing to topics/channels with ease.
--   **TypeScript Support**: Fully typed interfaces for a better development experience.
+DurableWS aims to be "the Hono of WebSockets": tiny, ergonomic, Web-Standards-based, and **durable by default** — automatic reconnection, message queueing, and idle detection out of the box — with a middleware + codec pipeline for extensibility (custom wire formats, auth, a socket.io-compatibility layer, and more).
 
-## Installation
+## Status
 
-```bash
-npm install durablews
-```
+DurableWS v2 is being built in the open. To be accurate about what exists today vs. what's planned:
 
-or
+**Working now**
 
-```bash
-yarn add durablews
-```
+- Connect / send / close and incoming-message handling over the standard `WebSocket`
+- Event subscriptions (`on` / `off`)
+- A middleware pipeline (`use`)
+- Built-in JSON-safe message parsing and a ping/pong middleware
 
-## Basic Usage
+**Planned for v2 (not yet implemented)**
 
-To get started with DurableWS, first import the client in your project:
+- Automatic reconnection with exponential backoff
+- Message queueing while disconnected, flushed on reconnect
+- Idle detection
+- A typed connection state machine
+- Pluggable codecs (msgpack, socket.io framing, …) and an authentication helper
+- Channels / subscriptions
 
-```ts
-import { createClient } from "durablews";
-```
+Until these land, treat the durability features as a roadmap, not a guarantee.
 
-Create a new WebSocket client instance by specifying the configuration:
+## Requirements
 
-```ts
-const client = await createClient({
-    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").then((r) => r.json());
-        return response.token;
-    },
-});
-```
+DurableWS targets the **standard global `WebSocket`** and ships **zero runtime dependencies**. That means:
+
+- **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.
 
-### Sending Messages
+## Installation
 
-```typescript
-client.send({ action: "greet", data: { message: "Hello, World!" } });
+```bash
+# v2 is not yet published; once the alpha ships it will be:
+npm install durablews@alpha
 ```
 
-### Handling Events
+## Quick start
 
-```typescript
-client.onMessage((message) => {
-    console.log("Received message:", message);
-});
+```ts
+import { defineClient } from "durablews";
 
-client.onOpen(() => {
-    console.log("Connection opened");
-});
+const client = defineClient({ url: "wss://example.com/socket" });
 
-client.onError((error) => {
-    console.error("Connection error:", error);
+client.on("message", (data) => {
+    console.log("received:", data);
 });
 
-client.onClose(() => {
-    console.log("Connection closed");
-});
+await client.connect();
+client.send({ type: "hello", message: "world" });
 
-client.onIdle(() => {
-    console.log("Client is idle");
-});
+// later
+client.close();
 ```
 
-## API Reference
+## Documentation
 
-### `createClient(config: WebSocketClientConfig): Promise<WebSocketClient>`
-
-Initializes and returns a WebSocket client instance.
-
-#### Config Options
-
--   `url`: WebSocket server URL.
--   `accessToken` (optional): Token for authentication.
--   `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.
+- [v2 architecture RFC](https://github.com/imnsco/DurableWS/blob/main/rfcs/0001-v2-architecture.md)
+- A full documentation site (Astro + Starlight) is coming as part of v2.
 
 ## 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"]}