@marianmeres/ws 0.2.0

package/dist/mod.d.ts

@@ -0,0 +1,30 @@
+/**
+ * `@marianmeres/ws` — a WebSocket client with namespaces, rooms, presence and
+ * auto-reconnect.
+ *
+ * The client is dependency-light and runs in browsers, Deno, Node 22+, Bun and
+ * Workers — `WebSocket` is a global in all of them, so there is no polyfill and
+ * no transport dependency.
+ *
+ * The reference server lives behind a separate entry point,
+ * `@marianmeres/ws/server`, so `demino` never lands in a browser bundle.
+ *
+ * @example
+ * ```ts
+ * import { createWSClient } from "@marianmeres/ws";
+ *
+ * const ws = createWSClient({ url: "/ws", namespace: "org-123" });
+ *
+ * const unsub = await ws.subscribe("chat", (msg) => {
+ *     console.log(msg.from, msg.payload);
+ * });
+ *
+ * await ws.publish("chat", { text: "hello" });
+ * ```
+ *
+ * @module
+ */
+export { createWSClient, type SubscribeOptions, WSClient, type WSClientOptions, type WSConnectionState, type WSEvents, type WSState, } from "./client/ws-client.js";
+export type { MessageHandler, PresenceHandler } from "./client/rooms.js";
+export { backoffDelay } from "./client/backoff.js";
+export * from "./protocol/mod.js";

package/dist/mod.js

@@ -0,0 +1,29 @@
+/**
+ * `@marianmeres/ws` — a WebSocket client with namespaces, rooms, presence and
+ * auto-reconnect.
+ *
+ * The client is dependency-light and runs in browsers, Deno, Node 22+, Bun and
+ * Workers — `WebSocket` is a global in all of them, so there is no polyfill and
+ * no transport dependency.
+ *
+ * The reference server lives behind a separate entry point,
+ * `@marianmeres/ws/server`, so `demino` never lands in a browser bundle.
+ *
+ * @example
+ * ```ts
+ * import { createWSClient } from "@marianmeres/ws";
+ *
+ * const ws = createWSClient({ url: "/ws", namespace: "org-123" });
+ *
+ * const unsub = await ws.subscribe("chat", (msg) => {
+ *     console.log(msg.from, msg.payload);
+ * });
+ *
+ * await ws.publish("chat", { text: "hello" });
+ * ```
+ *
+ * @module
+ */
+export { createWSClient, WSClient, } from "./client/ws-client.js";
+export { backoffDelay } from "./client/backoff.js";
+export * from "./protocol/mod.js";

package/dist/protocol/constants.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Wire protocol constants shared by client and server.
+ *
+ * This module is intentionally dependency free — it is the single source of
+ * truth both sides import, which is what keeps them from drifting apart.
+ *
+ * @module
+ */
+/**
+ * Protocol version, announced by the server in its `hello` frame.
+ *
+ * It costs nothing today and it is the only thing that makes a breaking
+ * protocol change survivable later.
+ */
+export declare const PROTOCOL_VERSION = 1;
+/** Namespace used when the client does not specify one. */
+export declare const DEFAULT_NAMESPACE = "default";
+/**
+ * Frame type discriminators.
+ *
+ * Note these are *protocol* types and have nothing to do with whatever the
+ * application puts inside `payload` — the payload is opaque and is never
+ * inspected nor mutated by this library.
+ */
+export declare const FRAME: {
+    /** Handshake. Always the first frame; carries the auth payload. */
+    readonly AUTH: "auth";
+    /** Join one or more rooms, optionally with presence. */
+    readonly SUB: "sub";
+    /** Leave one or more rooms. */
+    readonly UNSUB: "unsub";
+    /** Publish into a room within the connection's own namespace. */
+    readonly PUB: "pub";
+    /** Publish into a room across every namespace. Gated server-side. */
+    readonly BROADCAST: "broadcast";
+    /** Liveness probe. Answered with `pong`. */
+    readonly PING: "ping";
+    /** Handshake accepted; carries the assigned id, namespace and version. */
+    readonly HELLO: "hello";
+    /** Positive acknowledgement of a correlated request. */
+    readonly ACK: "ack";
+    /** Negative acknowledgement; carries a `WSErrorInfo`. */
+    readonly NACK: "nack";
+    /** A message delivered to a subscribed room. */
+    readonly MSG: "msg";
+    /** A membership change in a presence-enabled room. */
+    readonly PRESENCE: "presence";
+    /** Reply to `ping`. */
+    readonly PONG: "pong";
+    /** Uncorrelated error — not tied to any request id. */
+    readonly ERROR: "error";
+};
+/**
+ * WebSocket close codes.
+ *
+ * The `4xxx` range is reserved for application use by RFC 6455.
+ */
+export declare const CLOSE: {
+    /** Normal closure. Server-sent means "restarting" — the client reconnects. */
+    readonly NORMAL: 1000;
+    /** Endpoint going away (shutdown, navigation). Recoverable. */
+    readonly GOING_AWAY: 1001;
+    /** No close frame received. The everyday network drop. */
+    readonly ABNORMAL: 1006;
+    /** Unexpected server-side condition. Recoverable. */
+    readonly INTERNAL_ERROR: 1011;
+    /** Authentication rejected. Terminal — retrying cannot help. */
+    readonly AUTH_FAILED: 4001;
+    /** Client did not send an `auth` frame in time. Recoverable. */
+    readonly AUTH_TIMEOUT: 4002;
+    /** Authenticated but not permitted. Terminal. */
+    readonly FORBIDDEN: 4003;
+    /** Connection went silent and was reaped. Recoverable. */
+    readonly IDLE_TIMEOUT: 4008;
+    /** Too many frames per second. Recoverable, with a longer backoff floor. */
+    readonly RATE_LIMITED: 4009;
+    /** Frame exceeded `maxFrameSize`. Recoverable. */
+    readonly FRAME_TOO_LARGE: 4013;
+    /** Malformed frame or codec mismatch. Recoverable (but likely a config bug). */
+    readonly PROTOCOL_ERROR: 4400;
+    /** Local, client-initiated teardown. Never reconnects by definition. */
+    readonly CLIENT_GONE: 4900;
+};
+/**
+ * Close codes after which reconnecting is pointless.
+ *
+ * Everything *not* in this list reconnects — including a server-sent `1000`,
+ * because a graceful shutdown or rolling deploy is exactly when clients must
+ * come back.
+ */
+export declare const DEFAULT_TERMINAL_CLOSE_CODES: readonly number[];
+/** Application-level error codes carried in `nack`/`error` frames. */
+export declare const ERROR_CODE: {
+    /** Operation attempted before the handshake completed. */
+    readonly UNAUTHORIZED: "unauthorized";
+    /** Authenticated, but not permitted — e.g. a denied broadcast. */
+    readonly FORBIDDEN: "forbidden";
+    /** Malformed or nonsensical frame. */
+    readonly BAD_REQUEST: "bad_request";
+    /** Frame rate cap exceeded. */
+    readonly RATE_LIMITED: "rate_limited";
+    /** Unexpected server-side failure. */
+    readonly INTERNAL: "internal";
+};
+/** Presence event kinds. */
+export declare const PRESENCE: {
+    /** Full membership snapshot, sent on every (re)subscribe. */
+    readonly SYNC: "sync";
+    /** A client joined the room. Delta — `clientId` is the joiner. */
+    readonly JOIN: "join";
+    /** A client left the room. Delta — `clientId` is the leaver. */
+    readonly LEAVE: "leave";
+};

package/dist/protocol/constants.js

@@ -0,0 +1,118 @@
+/**
+ * Wire protocol constants shared by client and server.
+ *
+ * This module is intentionally dependency free — it is the single source of
+ * truth both sides import, which is what keeps them from drifting apart.
+ *
+ * @module
+ */
+/**
+ * Protocol version, announced by the server in its `hello` frame.
+ *
+ * It costs nothing today and it is the only thing that makes a breaking
+ * protocol change survivable later.
+ */
+export const PROTOCOL_VERSION = 1;
+/** Namespace used when the client does not specify one. */
+export const DEFAULT_NAMESPACE = "default";
+/**
+ * Frame type discriminators.
+ *
+ * Note these are *protocol* types and have nothing to do with whatever the
+ * application puts inside `payload` — the payload is opaque and is never
+ * inspected nor mutated by this library.
+ */
+export const FRAME = {
+    // client -> server
+    /** Handshake. Always the first frame; carries the auth payload. */
+    AUTH: "auth",
+    /** Join one or more rooms, optionally with presence. */
+    SUB: "sub",
+    /** Leave one or more rooms. */
+    UNSUB: "unsub",
+    /** Publish into a room within the connection's own namespace. */
+    PUB: "pub",
+    /** Publish into a room across every namespace. Gated server-side. */
+    BROADCAST: "broadcast",
+    /** Liveness probe. Answered with `pong`. */
+    PING: "ping",
+    // server -> client
+    /** Handshake accepted; carries the assigned id, namespace and version. */
+    HELLO: "hello",
+    /** Positive acknowledgement of a correlated request. */
+    ACK: "ack",
+    /** Negative acknowledgement; carries a `WSErrorInfo`. */
+    NACK: "nack",
+    /** A message delivered to a subscribed room. */
+    MSG: "msg",
+    /** A membership change in a presence-enabled room. */
+    PRESENCE: "presence",
+    /** Reply to `ping`. */
+    PONG: "pong",
+    /** Uncorrelated error — not tied to any request id. */
+    ERROR: "error",
+};
+/**
+ * WebSocket close codes.
+ *
+ * The `4xxx` range is reserved for application use by RFC 6455.
+ */
+export const CLOSE = {
+    /** Normal closure. Server-sent means "restarting" — the client reconnects. */
+    NORMAL: 1000,
+    /** Endpoint going away (shutdown, navigation). Recoverable. */
+    GOING_AWAY: 1001,
+    /** No close frame received. The everyday network drop. */
+    ABNORMAL: 1006,
+    /** Unexpected server-side condition. Recoverable. */
+    INTERNAL_ERROR: 1011,
+    /** Authentication rejected. Terminal — retrying cannot help. */
+    AUTH_FAILED: 4001,
+    /** Client did not send an `auth` frame in time. Recoverable. */
+    AUTH_TIMEOUT: 4002,
+    /** Authenticated but not permitted. Terminal. */
+    FORBIDDEN: 4003,
+    /** Connection went silent and was reaped. Recoverable. */
+    IDLE_TIMEOUT: 4008,
+    /** Too many frames per second. Recoverable, with a longer backoff floor. */
+    RATE_LIMITED: 4009,
+    /** Frame exceeded `maxFrameSize`. Recoverable. */
+    FRAME_TOO_LARGE: 4013,
+    /** Malformed frame or codec mismatch. Recoverable (but likely a config bug). */
+    PROTOCOL_ERROR: 4400,
+    /** Local, client-initiated teardown. Never reconnects by definition. */
+    CLIENT_GONE: 4900,
+};
+/**
+ * Close codes after which reconnecting is pointless.
+ *
+ * Everything *not* in this list reconnects — including a server-sent `1000`,
+ * because a graceful shutdown or rolling deploy is exactly when clients must
+ * come back.
+ */
+export const DEFAULT_TERMINAL_CLOSE_CODES = [
+    CLOSE.AUTH_FAILED,
+    CLOSE.FORBIDDEN,
+];
+/** Application-level error codes carried in `nack`/`error` frames. */
+export const ERROR_CODE = {
+    /** Operation attempted before the handshake completed. */
+    UNAUTHORIZED: "unauthorized",
+    /** Authenticated, but not permitted — e.g. a denied broadcast. */
+    FORBIDDEN: "forbidden",
+    /** Malformed or nonsensical frame. */
+    BAD_REQUEST: "bad_request",
+    /** Frame rate cap exceeded. */
+    RATE_LIMITED: "rate_limited",
+    /** Unexpected server-side failure. */
+    INTERNAL: "internal",
+};
+/** Presence event kinds. */
+export const PRESENCE = {
+    /** Full membership snapshot, sent on every (re)subscribe. */
+    SYNC: "sync",
+    /** A client joined the room. Delta — `clientId` is the joiner. */
+    JOIN: "join",
+    /** A client left the room. Delta — `clientId` is the leaver. */
+    LEAVE: "leave",
+};

package/dist/protocol/errors.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Typed errors.
+ *
+ * Every rejection this library produces is one of these, so callers can branch
+ * on `instanceof` rather than string-matching messages.
+ *
+ * @module
+ */
+import type { WSErrorInfo } from "./frames.js";
+/**
+ * Base class for everything thrown by this library.
+ *
+ * `name` is set from the concrete subclass, so it survives bundling and reads
+ * correctly in logs.
+ */
+export declare class WSError extends Error {
+    /**
+     * Creates the error and stamps `name` from the concrete subclass.
+     *
+     * @param message - human-readable description
+     */
+    constructor(message: string);
+}
+/**
+ * The connection reached a terminal state and will not retry.
+ *
+ * The only path by which an infinitely-retrying client gives up, which is why
+ * it is logged at error level and rejects any pending `connect()`.
+ */
+export declare class WSTerminatedError extends WSError {
+    /** WebSocket close code that caused the termination. */
+    readonly code: number;
+    /** Close reason as sent by the peer. May be an empty string. */
+    readonly reason: string;
+    /**
+     * Built from the close event that ended the connection.
+     *
+     * @param code - the close code that ended it
+     * @param reason - the close reason, possibly empty
+     */
+    constructor(
+    /** WebSocket close code that caused the termination. */
+    code: number, 
+    /** Close reason as sent by the peer. May be an empty string. */
+    reason: string);
+}
+/**
+ * `connectTimeout` elapsed before the first successful connect.
+ *
+ * Note the client keeps retrying in the background — this rejection bounds
+ * *your await*, not the connection attempt.
+ */
+export declare class WSConnectTimeoutError extends WSError {
+    /**
+     * Reports the deadline that was exceeded.
+     *
+     * @param ms - the elapsed `connectTimeout`
+     */
+    constructor(ms: number);
+}
+/** `sendTimeout` elapsed while queued, in flight, or awaiting an ack. */
+export declare class WSTimeoutError extends WSError {
+    /**
+     * Reports the deadline that was exceeded.
+     *
+     * @param ms - the elapsed `sendTimeout`
+     */
+    constructor(ms: number);
+}
+/** The frame was evicted from a full outbox before it could be sent. */
+export declare class WSOutboxDropError extends WSError {
+    constructor();
+}
+/** The server rejected the operation with a `nack`. */
+export declare class WSRemoteError extends WSError {
+    /** Machine-readable code from the server — see `ERROR_CODE`. */
+    readonly code: string;
+    /**
+     * Lifts a wire-level error detail into a throwable.
+     *
+     * @param info - the error detail carried by the `nack` frame
+     */
+    constructor(info: WSErrorInfo);
+}
+/** The client was disposed while the operation was pending. */
+export declare class WSDisposedError extends WSError {
+    constructor();
+}
+/** Sending was attempted while disconnected with buffering disabled. */
+export declare class WSNotConnectedError extends WSError {
+    constructor();
+}

package/dist/protocol/errors.js

@@ -0,0 +1,109 @@
+/**
+ * Typed errors.
+ *
+ * Every rejection this library produces is one of these, so callers can branch
+ * on `instanceof` rather than string-matching messages.
+ *
+ * @module
+ */
+/**
+ * Base class for everything thrown by this library.
+ *
+ * `name` is set from the concrete subclass, so it survives bundling and reads
+ * correctly in logs.
+ */
+export class WSError extends Error {
+    /**
+     * Creates the error and stamps `name` from the concrete subclass.
+     *
+     * @param message - human-readable description
+     */
+    constructor(message) {
+        super(message);
+        this.name = new.target.name;
+    }
+}
+/**
+ * The connection reached a terminal state and will not retry.
+ *
+ * The only path by which an infinitely-retrying client gives up, which is why
+ * it is logged at error level and rejects any pending `connect()`.
+ */
+export class WSTerminatedError extends WSError {
+    code;
+    reason;
+    /**
+     * Built from the close event that ended the connection.
+     *
+     * @param code - the close code that ended it
+     * @param reason - the close reason, possibly empty
+     */
+    constructor(
+    /** WebSocket close code that caused the termination. */
+    code, 
+    /** Close reason as sent by the peer. May be an empty string. */
+    reason) {
+        super(`Connection terminated (${code})${reason ? `: ${reason}` : ""}`);
+        this.code = code;
+        this.reason = reason;
+    }
+}
+/**
+ * `connectTimeout` elapsed before the first successful connect.
+ *
+ * Note the client keeps retrying in the background — this rejection bounds
+ * *your await*, not the connection attempt.
+ */
+export class WSConnectTimeoutError extends WSError {
+    /**
+     * Reports the deadline that was exceeded.
+     *
+     * @param ms - the elapsed `connectTimeout`
+     */
+    constructor(ms) {
+        super(`Not connected within ${ms}ms (still retrying in background)`);
+    }
+}
+/** `sendTimeout` elapsed while queued, in flight, or awaiting an ack. */
+export class WSTimeoutError extends WSError {
+    /**
+     * Reports the deadline that was exceeded.
+     *
+     * @param ms - the elapsed `sendTimeout`
+     */
+    constructor(ms) {
+        super(`No acknowledgement within ${ms}ms`);
+    }
+}
+/** The frame was evicted from a full outbox before it could be sent. */
+export class WSOutboxDropError extends WSError {
+    constructor() {
+        super("Dropped from outbox (capacity reached while disconnected)");
+    }
+}
+/** The server rejected the operation with a `nack`. */
+export class WSRemoteError extends WSError {
+    /** Machine-readable code from the server — see `ERROR_CODE`. */
+    code;
+    /**
+     * Lifts a wire-level error detail into a throwable.
+     *
+     * @param info - the error detail carried by the `nack` frame
+     */
+    constructor(info) {
+        super(info.message);
+        this.code = info.code;
+    }
+}
+/** The client was disposed while the operation was pending. */
+export class WSDisposedError extends WSError {
+    constructor() {
+        super("Client disposed");
+    }
+}
+/** Sending was attempted while disconnected with buffering disabled. */
+export class WSNotConnectedError extends WSError {
+    constructor() {
+        super("Not connected (outbox buffering is disabled)");
+    }
+}

package/dist/protocol/frames.d.ts

@@ -0,0 +1,151 @@
+/**
+ * Wire frame definitions.
+ *
+ * The central rule of this protocol: **the protocol frame type and the
+ * application message type are separate things.** The protocol owns a small
+ * closed set of frame types; `payload` is opaque and belongs entirely to the
+ * application. Your payload may contain its own `type` field and nothing will
+ * collide.
+ *
+ * @module
+ */
+import type { FRAME, PRESENCE } from "./constants.js";
+/** Structured error detail carried by `nack` and `error` frames. */
+export interface WSErrorInfo {
+    /** Machine-readable code — see `ERROR_CODE`. */
+    code: string;
+    /** Human-readable explanation. Never parse this. */
+    message: string;
+}
+/**
+ * A message as delivered to application code.
+ *
+ * A `msg` frame minus its `type` field *is* a `WSMessage` — there is no
+ * translation layer and no divergence between wire names and API names.
+ */
+export interface WSMessage<T = unknown> {
+    /** Room the message was published to. */
+    room: string;
+    /** Namespace the message belongs to. */
+    namespace: string;
+    /**
+     * Originating client id, or `null` when the message was injected
+     * server-side (via the service API or the HTTP routes).
+     */
+    from: string | null;
+    /** Opaque application payload. */
+    payload: T;
+    /** Server-assigned epoch milliseconds. */
+    timestamp: number;
+}
+/** Kind of presence change. */
+export type PresenceEventType = (typeof PRESENCE)[keyof typeof PRESENCE];
+/**
+ * A membership change in a room the client subscribed to with presence
+ * enabled.
+ *
+ * `sync` carries the full snapshot and is emitted on every (re)subscribe —
+ * crucially including after a reconnect, when membership may have changed
+ * completely while the client was away.
+ */
+export interface WSPresenceEvent {
+    /** Whether this is a full snapshot or a join/leave delta. */
+    event: PresenceEventType;
+    /** Room the membership change happened in. */
+    room: string;
+    /** Namespace the room belongs to. */
+    namespace: string;
+    /** The client that joined or left. `null` for `sync`. */
+    clientId: string | null;
+    /** Full membership after applying this event. */
+    members: string[];
+    /** Server-assigned epoch milliseconds. */
+    timestamp: number;
+}
+/** A single room subscription request. */
+export interface SubRequest {
+    /** Room name to join. */
+    room: string;
+    /** Track membership and deliver `presence` frames for this room. */
+    presence?: boolean;
+}
+/** Frames sent by the client. */
+export type ClientFrame = {
+    type: typeof FRAME.AUTH;
+    id: string;
+    protocol: number;
+    payload: unknown;
+    /** Preferred client id — the server may override it. */
+    clientId?: string;
+    namespace?: string;
+} | {
+    type: typeof FRAME.SUB;
+    id: string;
+    rooms: SubRequest[];
+} | {
+    type: typeof FRAME.UNSUB;
+    id: string;
+    rooms: string[];
+} | {
+    type: typeof FRAME.PUB;
+    id: string;
+    room: string;
+    namespace?: string;
+    payload: unknown;
+} | {
+    type: typeof FRAME.BROADCAST;
+    id: string;
+    room: string;
+    payload: unknown;
+} | {
+    type: typeof FRAME.PING;
+};
+/** Frames sent by the server. */
+export type ServerFrame = {
+    type: typeof FRAME.HELLO;
+    clientId: string;
+    namespace: string;
+    protocol: number;
+} | {
+    type: typeof FRAME.ACK;
+    id: string;
+    recipients?: number;
+} | {
+    type: typeof FRAME.NACK;
+    id: string;
+    error: WSErrorInfo;
+} | ({
+    type: typeof FRAME.MSG;
+} & WSMessage) | ({
+    type: typeof FRAME.PRESENCE;
+} & WSPresenceEvent) | {
+    type: typeof FRAME.PONG;
+} | {
+    type: typeof FRAME.ERROR;
+    error: WSErrorInfo;
+};
+/** Any frame, in either direction. */
+export type WSFrame = ClientFrame | ServerFrame;
+/** Result of a successful `publish()` / `broadcast()`. */
+export interface WSPublishResult {
+    /**
+     * Sockets the message was handed to **on the receiving server instance**.
+     *
+     * Best-effort telemetry, never a delivery guarantee — and it stays
+     * instance-local once a distributed adapter is in play.
+     */
+    recipients: number;
+}
+/** Outcome of the server's `verify()` hook. */
+export interface AuthResult {
+    /** Assign a specific client id. Defaults to a generated one. */
+    clientId?: string;
+    /** Force the connection's namespace, overriding the client's request. */
+    namespace?: string;
+    /** Arbitrary data to associate with the connection (available to hooks). */
+    meta?: Record<string, unknown>;
+}
+/** Encodes an outgoing frame for the wire. */
+export type WSEncoder = (frame: WSFrame) => string | ArrayBufferView | ArrayBuffer;
+/** Decodes an inbound wire message into a frame. */
+export type WSDecoder = (raw: string | ArrayBuffer) => WSFrame;

package/dist/protocol/frames.js

@@ -0,0 +1,12 @@
+/**
+ * Wire frame definitions.
+ *
+ * The central rule of this protocol: **the protocol frame type and the
+ * application message type are separate things.** The protocol owns a small
+ * closed set of frame types; `payload` is opaque and belongs entirely to the
+ * application. Your payload may contain its own `type` field and nothing will
+ * collide.
+ *
+ * @module
+ */
+export {};

package/dist/protocol/mod.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Dependency-free wire protocol definitions, imported by both the client and
+ * the server. Keeping them in one place is what prevents the two sides from
+ * drifting apart.
+ *
+ * @module
+ */
+export * from "./constants.js";
+export * from "./errors.js";
+export * from "./frames.js";

package/dist/protocol/mod.js

@@ -0,0 +1,10 @@
+/**
+ * Dependency-free wire protocol definitions, imported by both the client and
+ * the server. Keeping them in one place is what prevents the two sides from
+ * drifting apart.
+ *
+ * @module
+ */
+export * from "./constants.js";
+export * from "./errors.js";
+export * from "./frames.js";

package/dist/protocol.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Entry point for `@marianmeres/ws/protocol`.
+ *
+ * The dependency-free wire definitions, for anyone implementing this protocol
+ * against a different server or client.
+ *
+ * @module
+ */
+export * from "./protocol/mod.js";