durablews 1.0.0 → 2.0.0-alpha.0

package/dist/types-BDvztGcG.d.ts

@@ -0,0 +1,410 @@
+/**
+ * The Standard Schema v1 interface (https://standardschema.dev), vendored as
+ * types-only per the spec's guidance — implementing libraries (zod, valibot,
+ * arktype, …) conform to this shape, so DurableWS can accept any of them
+ * without depending on any of them. Keeps core zero-dependency.
+ */
+interface StandardSchemaV1<Input = unknown, Output = Input> {
+    readonly "~standard": StandardSchemaV1.Props<Input, Output>;
+}
+declare namespace StandardSchemaV1 {
+    interface Props<Input = unknown, Output = Input> {
+        readonly version: 1;
+        readonly vendor: string;
+        readonly validate: (value: unknown) => Result<Output> | Promise<Result<Output>>;
+        readonly types?: Types<Input, Output> | undefined;
+    }
+    type Result<Output> = SuccessResult<Output> | FailureResult;
+    interface SuccessResult<Output> {
+        readonly value: Output;
+        readonly issues?: undefined;
+    }
+    interface FailureResult {
+        readonly issues: ReadonlyArray<Issue>;
+    }
+    interface Issue {
+        readonly message: string;
+        readonly path?: ReadonlyArray<PropertyKey | PathSegment> | undefined;
+    }
+    interface PathSegment {
+        readonly key: PropertyKey;
+    }
+    interface Types<Input = unknown, Output = Input> {
+        readonly input: Input;
+        readonly output: Output;
+    }
+    type InferInput<Schema extends StandardSchemaV1> = NonNullable<Schema["~standard"]["types"]>["input"];
+    type InferOutput<Schema extends StandardSchemaV1> = NonNullable<Schema["~standard"]["types"]>["output"];
+}
+/**
+ * Thrown (as an `error` event payload) when an inbound message fails the
+ * configured schema. The message is **not** emitted — handlers only ever see
+ * data that passed validation.
+ */
+declare class SchemaValidationError extends Error {
+    readonly issues: ReadonlyArray<StandardSchemaV1.Issue>;
+    constructor(issues: ReadonlyArray<StandardSchemaV1.Issue>);
+}
+
+/**
+ * Translates between application values and WebSocket wire frames.
+ *
+ * The codec is the single seam where serialization lives: `send()` runs values
+ * through `encode`, and incoming frames are run through `decode` before being
+ * emitted as `message`. The default is JSON (see `codec.ts`); supply your own
+ * for binary protocols, schema-based formats, etc.
+ */
+interface Codec {
+    /**
+     * Encode an outgoing value into a WebSocket-sendable frame.
+     *
+     * The return type deliberately mirrors `WebSocket.send`'s parameter
+     * (`BufferSource` is its exact alias), so the codec contract can never
+     * drift looser than what the socket accepts — e.g. TS 6's lib excludes
+     * `SharedArrayBuffer`-backed views from `send`, and this excludes them too.
+     */
+    encode(data: unknown): string | BufferSource | Blob;
+    /** Decode an incoming frame (`string` for text, `ArrayBuffer`/`Blob` for binary). */
+    decode(data: unknown): unknown;
+}
+/**
+ * Tuning for automatic reconnection. All fields optional — the defaults give
+ * full-jitter exponential backoff with unlimited retries.
+ */
+interface ReconnectOptions {
+    /** First-retry delay ceiling in ms. Default `500`. */
+    readonly baseDelay?: number;
+    /** Exponential growth factor. Default `2`. */
+    readonly factor?: number;
+    /** Delay ceiling in ms. Default `30_000`. */
+    readonly maxDelay?: number;
+    /**
+     * Full jitter: each delay is drawn uniformly from `[0, computed]`, so a
+     * fleet of clients dropped at once doesn't retry in synchronized waves.
+     * Default `true`; set `false` for exact exponential delays.
+     */
+    readonly jitter?: boolean;
+    /** Retries per disconnection before giving up. Default `Infinity`. */
+    readonly maxRetries?: number;
+    /**
+     * Decide per-close whether to reconnect (e.g. skip auth rejections by
+     * close code). Default: always reconnect. User-initiated `close()` never
+     * reconnects, regardless of this.
+     */
+    readonly shouldReconnect?: (event: CloseEvent) => boolean;
+}
+/**
+ * Opt-in liveness checking. When configured, the client sends `message` every
+ * `interval` ms while open; if **no inbound frame of any kind** arrives within
+ * `timeout` ms of a ping, the link is declared dead and force-closed (code
+ * `4408`), which flows into the normal reconnect machinery.
+ *
+ * Requires a server that responds to the heartbeat message (or talks
+ * regularly for other reasons) — that app-level contract is why heartbeat is
+ * opt-in rather than on by default.
+ */
+interface HeartbeatOptions {
+    /** Milliseconds between pings. */
+    readonly interval: number;
+    /** The ping payload, run through the codec. Default `"ping"`. */
+    readonly message?: unknown;
+    /**
+     * Milliseconds after a ping to wait for inbound traffic before declaring
+     * the link dead. Default: `interval`.
+     */
+    readonly timeout?: number;
+}
+/**
+ * Tuning for the outbound message queue.
+ */
+interface QueueOptions {
+    /**
+     * Maximum queued messages. When full, the **oldest** is dropped and a
+     * `drop` event fires — never silently unbounded, never silently lossy.
+     * Default `256`.
+     */
+    readonly maxSize?: number;
+}
+/**
+ * Configuration options for the WebSocket client.
+ */
+interface WebSocketClientConfig {
+    /** The URL to connect to. */
+    readonly url: string | URL;
+    /** Optional subprotocol(s) passed to the underlying `WebSocket`. */
+    readonly protocols?: string | string[];
+    /**
+     * `binaryType` applied to the underlying socket on every (re)connect:
+     * `"arraybuffer"` delivers binary frames as `ArrayBuffer` instead of the
+     * browser default `Blob`.
+     */
+    readonly binaryType?: BinaryType;
+    /** Wire-format codec. Defaults to JSON (`jsonCodec`). */
+    readonly codec?: Codec;
+    /**
+     * Automatic reconnection — **on by default** (durable by default). Pass
+     * `false` to disable, or options to tune the backoff.
+     */
+    readonly reconnect?: false | ReconnectOptions;
+    /**
+     * Outbound queueing while disconnected — **on by default**. `send()`
+     * during `connecting`/`reconnecting` queues and flushes in order on open.
+     * Pass `false` to make `send()` throw whenever the socket isn't open.
+     */
+    readonly queue?: false | QueueOptions;
+    /**
+     * Liveness checking — **opt-in** (off unless configured). See
+     * {@link HeartbeatOptions}.
+     */
+    readonly heartbeat?: HeartbeatOptions;
+    /**
+     * A [Standard Schema](https://standardschema.dev) (zod, valibot, arktype,
+     * …) validating every **inbound** message after `codec.decode` and before
+     * middleware. Valid messages flow on with the schema's output value;
+     * invalid ones surface as an `error` event (`SchemaValidationError`) and
+     * are never emitted as `message`. When passed to `defineClient`, the
+     * message type is **inferred from the schema** — no generics needed.
+     */
+    readonly schema?: StandardSchemaV1;
+}
+/**
+ * The states a connection can occupy. This is the public, observable lifecycle.
+ *
+ * - `idle` — created but never connected.
+ * - `connecting` — a socket is open-in-progress, awaiting the first `open`.
+ * - `open` — connected and ready to send/receive.
+ * - `closing` — a close has been requested, awaiting the socket to finish.
+ * - `reconnecting` — the connection dropped; waiting out the backoff delay
+ *   before the next attempt.
+ * - `closed` — the socket is closed; the client may `connect()` again.
+ */
+type ConnectionState = "idle" | "connecting" | "open" | "closing" | "reconnecting" | "closed";
+/**
+ * A read-only snapshot of the client's observable state. Bounded by design —
+ * it holds lifecycle, never message history.
+ */
+interface ClientState {
+    /** The current connection state. */
+    readonly state: ConnectionState;
+    /**
+     * The most recent failure, if any: a transport error (`Event`) or a
+     * client-detected one like a heartbeat timeout (`Error`).
+     */
+    readonly lastError: Event | Error | null;
+    /**
+     * Retries used in the current disconnection episode. `0` while healthy;
+     * resets on a successful open or a user `close()`.
+     */
+    readonly retryAttempt: number;
+    /** Messages currently waiting in the outbound queue. */
+    readonly queueLength: number;
+}
+/**
+ * Payload emitted on every `drop` event — a queued outbound message that will
+ * never be sent.
+ */
+interface DropEvent<TOut = unknown> {
+    /** The original (un-encoded) value passed to `send()`. */
+    readonly data: TOut;
+    /**
+     * Why it was dropped: `overflow` — the queue was full and this was the
+     * oldest entry; `close` — the connection ended (user `close()` or terminal
+     * failure) with messages still queued.
+     */
+    readonly reason: "overflow" | "close";
+}
+/**
+ * Payload emitted on every `reconnecting` event (one per scheduled retry).
+ */
+interface ReconnectingEvent {
+    /** 1-based retry number within this disconnection episode. */
+    readonly attempt: number;
+    /** The backoff delay (ms) before this attempt fires. */
+    readonly delay: number;
+}
+/**
+ * The context handed to each message middleware.
+ */
+interface MessageContext<TIn = unknown> {
+    /**
+     * The decoded (and, if a schema is configured, validated) inbound message.
+     * Middleware may reassign this to transform what later middleware — and
+     * the `message` event — receive.
+     */
+    data: TIn;
+    /** The client, e.g. for sending a reply from within the pipeline. */
+    readonly client: WebSocketClient<TIn>;
+}
+/**
+ * Message middleware, run in registration order for each inbound message.
+ *
+ * Call `next()` to pass control to the next middleware; the message is emitted
+ * as a `message` event only if the whole chain calls through. Return without
+ * calling `next()` to short-circuit (e.g. an auto-reply that shouldn't bubble).
+ * May be async.
+ */
+type Middleware<TIn = unknown> = (ctx: MessageContext<TIn>, next: () => void | Promise<void>) => void | Promise<void>;
+/**
+ * The context handed to each outbound middleware.
+ */
+interface OutboundContext<TOut = unknown> {
+    /**
+     * The outbound message, exactly as passed to `send()`. Middleware may
+     * reassign this to transform what later middleware — and ultimately
+     * `codec.encode` — receive.
+     */
+    data: TOut;
+    /** The client, e.g. to read `getState()` from within the pipeline. */
+    readonly client: WebSocketClient<unknown, TOut>;
+}
+/**
+ * Outbound middleware, run in registration order for each outgoing message at
+ * **transmission time** — after dequeue, before `codec.encode` — so a message
+ * queued across a reconnect sees middleware (e.g. a token refresh) that is
+ * fresh when it actually goes out.
+ *
+ * May be async: the outbound path is serialized, so messages reach the socket
+ * in `send()` order even while an earlier message's middleware awaits (a
+ * delaying middleware therefore delays everything behind it — head-of-line,
+ * by design). Return without calling `next()` to deliberately not send the
+ * message (no `drop` event — `drop` means durability loss, not policy).
+ * A throw/rejection surfaces as an `error` event and skips only that message.
+ *
+ * Heartbeat pings bypass outbound middleware entirely.
+ */
+type OutboundMiddleware<TOut = unknown> = (ctx: OutboundContext<TOut>, next: () => void | Promise<void>) => void | Promise<void>;
+/**
+ * The object form accepted by `use()`: register middleware per direction, so
+ * one logical middleware (auth, logging, metrics) has a single registration
+ * site. Either side may be omitted.
+ */
+interface DirectionalMiddleware<TIn = unknown, TOut = unknown> {
+    readonly inbound?: Middleware<TIn>;
+    readonly outbound?: OutboundMiddleware<TOut>;
+}
+/**
+ * Payload emitted on every `statechange`.
+ */
+interface StateChange {
+    /** The state being left. */
+    readonly previous: ConnectionState;
+    /** The state being entered. */
+    readonly current: ConnectionState;
+}
+/**
+ * The events a client emits, mapped to their payload types. Used to give
+ * `on()` precise, per-event payload typing.
+ */
+interface ClientEventMap<TIn = unknown, TOut = unknown> {
+    /** The socket opened. */
+    open: undefined;
+    /** A message was received, decoded, and (if configured) validated. */
+    message: TIn;
+    /** The socket closed (clean or otherwise). */
+    close: CloseEvent;
+    /**
+     * Something failed: a transport error (an `Event` from the socket) or a
+     * middleware that threw/rejected (an `Error`).
+     */
+    error: Event | Error;
+    /** The connection state changed. */
+    statechange: StateChange;
+    /** A reconnect attempt was scheduled (fires once per retry). */
+    reconnecting: ReconnectingEvent;
+    /** A queued outbound message was dropped and will never be sent. */
+    drop: DropEvent<TOut>;
+}
+/**
+ * A resilient, zero-dependency WebSocket client.
+ *
+ * @typeParam TIn - The type of inbound messages (what `on("message")`
+ * handlers receive). Inferred from `config.schema` when one is given.
+ * @typeParam TOut - The type accepted by `send()`.
+ */
+interface WebSocketClient<TIn = unknown, TOut = unknown> {
+    /** The current connection state. */
+    readonly state: ConnectionState;
+    /**
+     * Opens the connection.
+     *
+     * Resolves the first time the socket opens — including when that open is
+     * a successful *retry* (the promise survives failed attempts while
+     * reconnection is active). Calling it while already `open` resolves
+     * immediately; calling it while `connecting` returns the same in-flight
+     * promise (idempotent); calling it while `reconnecting` skips the backoff
+     * wait and attempts immediately.
+     *
+     * Rejects only on **terminal** failure: retries exhausted
+     * (`reconnect.maxRetries`), a `shouldReconnect` veto, `close()` before the
+     * first open, or — with `reconnect: false` — any close before opening.
+     *
+     * **Under the default `maxRetries: Infinity`, this promise never rejects**:
+     * against a down host it stays pending while the client keeps retrying.
+     * That is the durable-by-default contract, by design. If you need a
+     * deadline, set a finite `maxRetries` or race it:
+     * `Promise.race([client.connect(), timeout(10_000)])`.
+     *
+     * Failures *after* the first open surface via the `error` / `close` /
+     * `reconnecting` events, not this promise. For fire-and-forget use, attach
+     * a `.catch` or listen for `error` to avoid an unhandled rejection.
+     */
+    connect(): Promise<void>;
+    /**
+     * Sends data over the connection. Non-string data is encoded (JSON by
+     * default).
+     *
+     * While `connecting` or `reconnecting`, the message is **queued** (bounded,
+     * drop-oldest — see `queue` config) and flushed in order when the socket
+     * opens; queued messages that will never send surface as `drop` events.
+     * Throws when the client is `idle`, `closing`, or `closed` — states where
+     * no open is coming — or whenever the socket isn't open if `queue: false`.
+     */
+    send(data: TOut): void;
+    /**
+     * Closes the connection.
+     * @param code - Optional close code (see `error.ts`).
+     * @param reason - Optional human-readable close reason.
+     */
+    close(code?: number, reason?: string): void;
+    /**
+     * Subscribes to a client event.
+     * @returns an unsubscribe function.
+     */
+    on<K extends keyof ClientEventMap<TIn, TOut>>(event: K, handler: (payload: ClientEventMap<TIn, TOut>[K]) => void): () => void;
+    /**
+     * Registers message middleware.
+     *
+     * A bare function registers **inbound** middleware (run in order for each
+     * inbound message — unchanged). The object form registers per direction:
+     * `use({ outbound })`, `use({ inbound, outbound })`. See
+     * {@link OutboundMiddleware} for the outbound contract (transmission-time
+     * execution, ordered async, silent short-circuit, per-message errors).
+     *
+     * @returns the client, for chaining.
+     */
+    use(middleware: Middleware<TIn> | DirectionalMiddleware<TIn, TOut>): WebSocketClient<TIn, TOut>;
+    /**
+     * Returns a read-only snapshot of the client's observable state.
+     *
+     * The snapshot is **referentially stable**: repeated calls return the same
+     * frozen object until something actually changes. Together with
+     * {@link subscribe} this is exactly the `subscribe`/`getSnapshot` pair
+     * React's `useSyncExternalStore` requires, and it drives Vue/Svelte
+     * reactivity equally well.
+     */
+    getState(): ClientState;
+    /**
+     * Subscribes to **any** change of the observable snapshot — connection
+     * state, `lastError`, `retryAttempt`, or `queueLength`. Unlike
+     * `on("statechange")` (which fires only on FSM transitions), this also
+     * fires when, e.g., the queue grows on a `send()` while disconnected.
+     *
+     * The listener receives no arguments; read `getState()` for the new
+     * snapshot.
+     *
+     * @returns an unsubscribe function.
+     */
+    subscribe(listener: () => void): () => void;
+}
+
+export { type Codec as C, type DirectionalMiddleware as D, type HeartbeatOptions as H, type Middleware as M, type OutboundContext as O, type QueueOptions as Q, type ReconnectOptions as R, StandardSchemaV1 as S, type WebSocketClient as W, type WebSocketClientConfig as a, type ClientEventMap as b, type ClientState as c, type ConnectionState as d, type DropEvent as e, type MessageContext as f, type OutboundMiddleware as g, type ReconnectingEvent as h, SchemaValidationError as i, type StateChange as j };