@shadow-js/realtime 0.0.0-stage → 1.0.1

package/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+## 1.0.1
+
+### Changed
+
+- Released at 1.0.1 with the other packages, which share one version. No change to this package.
+
+## 1.0.0
+
+### Added
+
+- Typed channels with rules that deny by default, per-channel numbering, resume with replay and gap detection, acknowledged and
+  idempotent publishes, request and reply, presence with heartbeats and exactly-once leave, rate limits, slow-consumer protection and
+  revocation.
+- WebSocket and server-sent-events transports with an HTTP post route, a client with jittered reconnect, an offline queue and
+  automatic fallback, and signal-based hooks.
+- Adapters: in memory, Redis (6.2+ and Valkey) and Cloudflare Durable Objects, all passing one conformance suite
+  (`adapterConformance`), plus `connectTest` and `memoryWebSocket` for tests.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ShadowJS contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,115 @@
-# Temporary Holding Version
+<p align="center"><img src="https://raw.githubusercontent.com/shadowjs-dev/realtime/main/.github/banner.png" alt="ShadowJS" width="100%"></p>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @shadow-js/realtime
+
+[![npm](https://img.shields.io/npm/v/@shadow-js/realtime.svg)](https://www.npmjs.com/package/@shadow-js/realtime)
+[![CI](https://github.com/shadowjs-dev/realtime/actions/workflows/ci.yml/badge.svg)](https://github.com/shadowjs-dev/realtime/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-yellow.svg)](https://github.com/shadowjs-dev/realtime/blob/main/LICENSE)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D22.12-brightgreen.svg)](https://nodejs.org/)
+[![TypeScript](https://img.shields.io/badge/TypeScript-ready-blue.svg)](https://www.typescriptlang.org/)
+
+Typed channels, presence and resumable delivery over WebSocket or server-sent events.
+
+- **Typed channels.** One schema gives every channel its events, presence state and requests, checked at compile time.
+- **Resumable.** Every message has a number. A client that drops and reconnects resumes from its last number: no loss and no duplicates inside the retention window, and a clear signal when the window was exceeded.
+- **Closed by default.** A channel nobody wrote a rule for cannot be subscribed to or published to.
+- **Scales out.** The in-memory adapter serves one process; the Redis adapter (Redis 6.2+ and Valkey) and the Cloudflare Durable Objects adapter serve many.
+- **Runs where Dusk runs.** WebSocket where the host holds sockets, server-sent events plus HTTP posts where it does not (Vercel, Netlify).
+
+## Install
+
+```sh
+npm install @shadow-js/realtime
+```
+
+## Quick start
+
+A hub is the server. Rules say who may do what; `connectTest` talks to it with no network.
+
+```ts title="chat.test.ts" test
+import { createHub } from "@shadow-js/realtime/server";
+import { connectTest } from "@shadow-js/realtime/testing";
+import { expect, it } from "vitest";
+
+it("delivers a message to a subscriber, in order, with an acknowledgment", async () => {
+  const hub = createHub({
+    channels: {
+      "chat:{room}": { subscribe: true, publish: ({ identity }) => identity.user !== undefined },
+    },
+  });
+  const ann = connectTest(hub, { user: "ann" });
+  const bob = connectTest(hub, { user: "bob" });
+  bob.send({ t: "sub", n: 1, c: "chat:lobby" });
+  await bob.settled();
+  ann.send({ t: "pub", c: "chat:lobby", e: "message", d: { text: "hi" }, n: 2 });
+  await ann.settled();
+
+  expect(bob.frames.find((frame) => frame.t === "msg")).toMatchObject({ s: 1, d: { text: "hi" } });
+  expect(ann.frames.find((frame) => frame.t === "ack")).toEqual({ t: "ack", n: 2, s: 1 });
+  await hub.close();
+});
+```
+
+In a Dusk app the hub is route exports. `routes/rt.ts` takes WebSockets and server-sent events; `routes/rt/send.ts` exports `POST = hub.post()` for what an SSE client sends:
+
+```ts title="routes/rt.ts" typecheck
+import { createHub } from "@shadow-js/realtime/server";
+
+export const hub = createHub({
+  channels: {
+    "chat:{room}": { subscribe: true, publish: ({ identity }) => identity.user !== undefined },
+  },
+});
+
+export const WS = hub.websocket();
+export const SSE = hub.sse();
+```
+
+The browser opens one typed connection:
+
+```ts title="client.ts" typecheck
+import { createRealtime } from "@shadow-js/realtime/client";
+
+type Schema = {
+  [name: `chat:${string}`]: { events: { message: { text: string } } };
+};
+
+const rt = createRealtime<Schema>({ url: "/rt" });
+const lobby = rt.channel("chat:lobby");
+lobby.on("message", (data, meta) => console.log(meta.seq, data.text));
+await lobby.publish("message", { text: "hello" });
+```
+
+## API
+
+Root, `@shadow-js/realtime`: the wire protocol and shared types.
+
+- `RealtimeError` and `ErrorCode`: an error with a protocol code.
+- `PROTOCOL_VERSION`, `decodeClientFrame`, `decodeServerFrame`, `isChannelName`, `isEventName`: the frame codecs and name validators.
+
+`@shadow-js/realtime/server`:
+
+- `createHub(options)`: the server. `hub.channel(pattern, rule)`, `hub.publish(channel, event, data)`, `hub.revoke(target)`, `hub.stats()`, `hub.close()`; the routes `hub.websocket()`, `hub.sse()`, `hub.post()`.
+- `memoryAdapter()`: the single-process adapter (the default). `DEFAULT_HUB_LIMITS`: every limit and its default.
+
+`@shadow-js/realtime/client`:
+
+- `createRealtime(options)`: the client. `rt.channel(name, options)` returns a channel with `on`, `onAny`, `onGap`, `publish`, `request`, `presence` and `close`.
+
+`@shadow-js/realtime/hooks`:
+
+- `useChannel`, `useChannelEvent`, `useChannelPresence`, `useRealtimeStatus`: signal-based hooks that release their channel with the component.
+
+`@shadow-js/realtime/redis`: `redisAdapter`, `fromIoredis`, `fromNodeRedis`.
+`@shadow-js/realtime/cloudflare`: `cloudflareAdapter`, `RealtimeChannelObject`.
+`@shadow-js/realtime/testing`: `connectTest`, `adapterConformance`.
+
+## Learn more
+
+See the ShadowJS documentation at https://shadowjs.net, and the realtime guide at https://realtime.shadowjs.net.
+
+## Using, changing and contributing
+
+- **Use the package** (a person or a coding agent that builds with it): this README, and [SKILL.md](SKILL.md), the short page an agent reads first.
+- **Change the package** (fix a bug, add a feature): [AGENTS.md](AGENTS.md) says how the repository is laid out, how to implement and test a change, and how a pull request is reviewed. It is written for people and coding agents alike.
+- **Take part**: [CONTRIBUTING.md](CONTRIBUTING.md) is the short guide; [SECURITY.md](SECURITY.md) is for vulnerabilities.

package/dist/dev/adapter.d.ts

@@ -0,0 +1,73 @@
+import { Member, PresenceEvent, StoredEntry, StoredMessage } from "./protocol.js";
+/** How a publish is retained and deduplicated. @since 1.0.0 */
+export interface PublishOptions {
+  /** Messages kept per channel (0 keeps none). */
+  readonly history: number;
+  /** Milliseconds a message is kept. */
+  readonly historyTtlMs: number;
+  /** An idempotency key: a second publish with it inside `idempotencyTtlMs` returns the first seq. */
+  readonly key?: string;
+  /** Milliseconds a key is remembered. */
+  readonly idempotencyTtlMs: number;
+}
+/** What a publish returns. @since 1.0.0 */
+export interface PublishResult {
+  readonly seq: number;
+  /** True when the idempotency key was already accepted and nothing was stored. */
+  readonly duplicate: boolean;
+}
+/** What the history of a channel holds. @since 1.0.0 */
+export interface HistoryResult {
+  /** Retained messages with `seq > after`, in order, at most `limit`. */
+  readonly messages: readonly StoredMessage[];
+  /** The channel's head seq (0 for a channel that never had a message). */
+  readonly head: number;
+  /** The oldest retained seq (0 when nothing is retained). */
+  readonly oldest: number;
+}
+/** A member of a channel's presence set, by id. @since 1.0.0 */
+export interface PresenceRef {
+  readonly channel: string;
+  readonly id: string;
+}
+/** A way to stop listening. @since 1.0.0 */
+export type Unsubscribe = () => Promise<void>;
+/**
+ * Storage and fan-out between servers. The adapter rules are in the realtime protocol reference (https://realtime.shadowjs.net/guides/realtime-protocol/); `adapterConformance` from
+ * `@shadow-js/realtime/testing` checks an implementation against it.
+ *
+ * @example
+ * import { memoryAdapter } from "@shadow-js/realtime/server";
+ *
+ * const adapter = memoryAdapter();
+ * const { seq } = await adapter.publish(
+ *   "chat:lobby",
+ *   { event: "message", data: '"hi"' },
+ *   { history: 100, historyTtlMs: 60_000, idempotencyTtlMs: 60_000 },
+ * );
+ * seq; // 1
+ * @since 1.0.0
+ */
+export interface Adapter {
+  /** Assigns the next seq, retains the message, delivers it to every subscriber on every server. */
+  publish(channel: string, entry: StoredEntry, options: PublishOptions): Promise<PublishResult>;
+  /** Listens to a channel's live messages (in increasing seq order). */
+  subscribe(channel: string, listener: (message: StoredMessage) => void): Promise<Unsubscribe>;
+  /** Reads retained messages after a seq. */
+  history(channel: string, after: number, limit: number): Promise<HistoryResult>;
+  /** Adds or updates a presence member, with an expiry. Emits `join` for a new member and `set` for a newer version. */
+  presenceSet(channel: string, member: Member, ttlMs: number): Promise<void>;
+  /** Removes a member. Resolves true (and emits `leave`) only for the call that removed it. */
+  presenceRemove(channel: string, id: string): Promise<boolean>;
+  /** The live members of a channel. */
+  presenceList(channel: string): Promise<readonly Member[]>;
+  /** Refreshes the expiry of members; returns the entries that no longer exist (the caller sets them again). */
+  presenceTouch(entries: readonly PresenceRef[], ttlMs: number): Promise<readonly PresenceRef[]>;
+  /** Removes the expired members of a channel, emitting one `leave` for each; returns them. */
+  presenceReap(channel: string): Promise<readonly Member[]>;
+  /** Listens to a channel's presence changes. */
+  presenceSubscribe(channel: string, listener: (event: PresenceEvent) => void): Promise<Unsubscribe>;
+  /** Releases connections and timers. */
+  close(): Promise<void>;
+}
+//# sourceMappingURL=adapter.d.ts.map

package/dist/dev/client/core.d.ts

@@ -0,0 +1,22 @@
+import { ChannelSchema, Realtime, RealtimeOptions } from "./types.js";
+/**
+ * Creates the realtime client: one transport (WebSocket, falling back to server-sent ev), reconnects with backoff, a
+ * bounded offline queue, resume from the last sequence number and typed channels. It connects when the first channel
+ * listens or the first message is sent, never earlier.
+ *
+ * @param options The stream URL and the policy.
+ * @returns The client.
+ * @example
+ * import { createRealtime } from "@shadow-js/realtime/client";
+ *
+ * type Schema = { [name: `chat:${string}`]: { ev: { message: { text: string } } } };
+ * const rt = createRealtime<Schema>({ url: "/rt" });
+ * const lobby = rt.channel("chat:lobby");
+ * const stop = lobby.on("message", (data) => console.log(data.text));
+ * await lobby.publish("message", { text: "hello" });
+ * stop();
+ * rt.close();
+ * @since 1.0.0
+ */
+export declare function createRealtime<Schema extends ChannelSchema = ChannelSchema>(options: RealtimeOptions): Realtime<Schema>;
+//# sourceMappingURL=core.d.ts.map