durablews 2.0.0-alpha.0 → 2.0.0

package/README.md

@@ -1,44 +1,48 @@
 # DurableWS
 
-> A resilient, modern, zero-dependency WebSocket **client** for TypeScript — built on the standard `WebSocket`, durable by default, and the same in every modern runtime.
-
-> ⚠️ **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.
-
-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).
-
-## Status
-
-DurableWS v2 is being built in the open. To be accurate about what exists today vs. what's planned:
-
-**Working now**
-
-- 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
-
-**Planned for v2 (not yet implemented)**
-
-- 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
-
-Until these land, treat the durability features as a roadmap, not a guarantee.
+> 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
 
-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.
+- **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
-# v2 is not yet published; once the alpha ships it will be:
 npm install durablews@alpha
 ```
 
@@ -60,10 +64,24 @@ client.send({ type: "hello", message: "world" });
 client.close();
 ```
 
+Typed and validated, with any Standard Schema:
+
+```ts
+import { z } from "zod";
+
+const Message = z.object({ type: z.string(), body: z.string() });
+const client = defineClient({ url, schema: Message });
+
+client.on("message", (msg) => {
+    // msg: { type: string; body: string } — validated at runtime
+});
+```
+
 ## Documentation
 
-- [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.
+**[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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "durablews",
-  "version": "2.0.0-alpha.0",
+  "version": "2.0.0",
   "description": "A resilient, TypeScript-based WebSocket client",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -104,6 +104,7 @@
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.3",
     "@playwright/test": "^1.60.0",
+    "@size-limit/preset-small-lib": "^12.1.0",
     "@testing-library/react": "^16.3.2",
     "@types/node": "^22.19.20",
     "@types/react": "^19.2.17",
@@ -113,6 +114,7 @@
     "publint": "^0.3.21",
     "react": "^19.2.7",
     "react-dom": "^19.2.7",
+    "size-limit": "^12.1.0",
     "tsup": "^8.5.1",
     "typescript": "^5.3.3",
     "vitest": "^1.2.2",
@@ -120,6 +122,38 @@
     "vue": "^3.5.35",
     "ws": "^8.21.0"
   },
+  "size-limit": [
+    {
+      "name": "core (durablews)",
+      "path": "dist/index.js",
+      "limit": "3 KB",
+      "brotli": true
+    },
+    {
+      "name": "durablews/vue",
+      "path": "dist/vue.js",
+      "limit": "3.5 KB",
+      "brotli": true,
+      "ignore": [
+        "vue"
+      ]
+    },
+    {
+      "name": "durablews/react",
+      "path": "dist/react.js",
+      "limit": "3.5 KB",
+      "brotli": true,
+      "ignore": [
+        "react"
+      ]
+    },
+    {
+      "name": "durablews/compat",
+      "path": "dist/compat.js",
+      "limit": "4 KB",
+      "brotli": true
+    }
+  ],
   "scripts": {
     "build": "tsup",
     "test": "vitest",
@@ -128,6 +162,7 @@
     "e2e:install": "playwright install --with-deps chromium",
     "typecheck": "tsc --noEmit",
     "typecheck:next": "pnpm --package=typescript@next dlx tsc --noEmit",
-    "check:publish": "publint && attw --pack . --profile node16"
+    "check:publish": "publint && attw --pack . --profile node16",
+    "size": "size-limit"
   }
 }