@alpamayo-solutions/colca-client 0.0.0 → 0.1.9

package/dist/live.js

@@ -0,0 +1,500 @@
+/**
+ * Live values over MQTT, for a page or a service that wants them pushed.
+ *
+ * Colca retains the current value of every data and entity path, so a
+ * subscription brings the present state first and the changes after it. There
+ * is no snapshot to fetch and nothing to merge. What this module adds is what a
+ * long-lived client needs around that:
+ *
+ * - one connection, however many parts of a page subscribe, and an unsubscribe
+ *   that ends only its own subscription;
+ * - the last value of every topic, so a second subscriber to a topic gets it at
+ *   once instead of waiting for the next change;
+ * - a fresh token before the old one runs out — the node ends a session when
+ *   its token expires — and every subscription sent again on the new connection;
+ * - growing, jittered waits between attempts after a drop, each with a fresh
+ *   token;
+ * - commands that wait for their acknowledgement.
+ *
+ * These are values, not a log: a change that happens while the connection is
+ * being replaced is superseded by the retained value that follows. Anything that
+ * must see every record reads a stream through the door instead.
+ *
+ * mqtt.js is loaded on first use and is an optional dependency of this package.
+ */
+import { newUlid } from "./ids.js";
+import { parseTopic, topicMatches } from "./topics.js";
+/** Nobody answered a command before it expired. */
+export class CommandTimeout extends Error {
+    topic;
+    correlationId;
+    constructor(topic, correlationId) {
+        super(`nobody acknowledged ${topic} (${correlationId}) before it expired`);
+        this.topic = topic;
+        this.correlationId = correlationId;
+        this.name = "CommandTimeout";
+    }
+}
+/** A token lifetime shorter than this does not make the client reconnect any faster. */
+const MIN_RENEW_MS = 5_000;
+export class Live {
+    #options;
+    #filters = new Map();
+    #qos = new Map();
+    #values = new Map();
+    /** Per filter, the topics whose retained value its listeners already have on this connection. */
+    #retainedSent = new Map();
+    /** Filters the node has confirmed on this connection, and who waits for that. */
+    #granted = new Set();
+    #grantWaiters = new Map();
+    #ackFilters = new Set();
+    #pending = new Map();
+    #stateListeners = new Set();
+    #state = "connecting";
+    #client;
+    #generation = 0;
+    #attempt = 0;
+    #renewTimer;
+    #retryTimer;
+    constructor(options) {
+        this.#options = options;
+        void this.#open();
+    }
+    get state() {
+        return this.#state;
+    }
+    /**
+     * Values under `filter` (MQTT wildcards allowed), the current ones first. Returns
+     * the function that ends this subscription and no other.
+     */
+    subscribe(filter, listener, options = {}) {
+        if (this.#state === "closed")
+            throw new Error("this Live client is closed");
+        const qos = options.qos ?? 0;
+        // A wrapper per call, so the same function subscribed twice is two subscriptions.
+        const own = (value) => {
+            listener(value);
+        };
+        let listeners = this.#filters.get(filter);
+        if (listeners === undefined) {
+            listeners = new Set([own]);
+            this.#filters.set(filter, listeners);
+            this.#qos.set(filter, qos);
+            // Offline, the filter goes out with the others once the connection is up.
+            if (this.#state === "online")
+                this.#subscribe([filter]);
+        }
+        else {
+            listeners.add(own);
+            if (qos > (this.#qos.get(filter) ?? 0)) {
+                // Subscribing again replaces the node's subscription with the stronger one.
+                this.#qos.set(filter, qos);
+                if (this.#state === "online")
+                    this.#subscribe([filter]);
+            }
+            // The node sends retained values once per subscription, and this filter's
+            // went to whoever subscribed first. The newcomer gets them from here.
+            const current = this.values(filter);
+            queueMicrotask(() => {
+                if (!this.#filters.get(filter)?.has(own))
+                    return;
+                for (const value of current)
+                    this.#deliver(own, value);
+            });
+        }
+        return () => {
+            const set = this.#filters.get(filter);
+            if (!set?.delete(own) || set.size > 0)
+                return;
+            this.#filters.delete(filter);
+            this.#qos.delete(filter);
+            this.#retainedSent.delete(filter);
+            this.#granted.delete(filter);
+            if (this.#state === "online")
+                this.#client?.unsubscribe([filter]);
+            this.#forget(filter);
+        };
+    }
+    /** The last value seen on a topic, if anyone is subscribed to it. */
+    latest(topic) {
+        return this.#values.get(topic);
+    }
+    /** Every last value under a filter. */
+    values(filter) {
+        return [...this.#values.values()].filter((value) => topicMatches(filter, value.topic));
+    }
+    /**
+     * One record, as JSON, under this caller's identity. Nothing is queued: offline
+     * it fails at once, because a command sent minutes later is a different command.
+     * A person's session may only send commands; the node refuses anything else.
+     */
+    publish(topic, payload, options = {}) {
+        const client = this.#client;
+        if (this.#state !== "online" || client === undefined) {
+            return Promise.reject(new Error(`not connected: ${topic} was not sent`));
+        }
+        return new Promise((resolve, reject) => {
+            client.publish(topic, JSON.stringify(payload), { qos: options.qos ?? 1, retain: false }, (error) => {
+                if (error)
+                    reject(error);
+                else
+                    resolve();
+            });
+        });
+    }
+    /**
+     * Send a command and wait for its acknowledgement.
+     *
+     * `body` is the command's own fields — `params` for a `_CmdParam`, say. The
+     * correlation id and the expiry are added here, and the answer is matched by
+     * the id, wherever in the tree the executor publishes it. The promise settles
+     * with the `_Ack`, whatever its `result_code`; it rejects when nothing answers
+     * in `timeoutMs`, when the node refuses the publish, or when the client closes.
+     */
+    command(topic, body = {}, options = {}) {
+        const parts = parseTopic(topic);
+        if (!parts?.contract.startsWith("_Cmd")) {
+            return Promise.reject(new Error(`a command goes to a _Cmd… topic, got ${topic}`));
+        }
+        const timeoutMs = options.timeoutMs ?? 30_000;
+        const ackFilter = options.ackFilter ?? `${parts.root}/${parts.version}/_Ack/#`;
+        const correlationId = typeof body.correlation_id === "string" ? body.correlation_id : newUlid();
+        this.#listenForAcks(ackFilter);
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                if (this.#pending.delete(correlationId))
+                    reject(new CommandTimeout(topic, correlationId));
+            }, timeoutMs);
+            this.#pending.set(correlationId, { resolve, reject, timer });
+            // Only once the node confirmed the subscription to the answers: an executor
+            // that answers at once must not answer into nothing.
+            this.#whenGranted(ackFilter)
+                .then(() => this.publish(topic, { ...body, correlation_id: correlationId, expires_at: Date.now() + timeoutMs }))
+                .catch((error) => {
+                const pending = this.#pending.get(correlationId);
+                if (!pending)
+                    return;
+                this.#pending.delete(correlationId);
+                clearTimeout(pending.timer);
+                pending.reject(error instanceof Error ? error : new Error(String(error)));
+            });
+        });
+    }
+    /** Called on every change of the connection state; returns the function that stops it. */
+    onState(listener) {
+        this.#stateListeners.add(listener);
+        return () => this.#stateListeners.delete(listener);
+    }
+    close() {
+        if (this.#state === "closed")
+            return;
+        this.#generation += 1;
+        clearTimeout(this.#renewTimer);
+        clearTimeout(this.#retryTimer);
+        this.#client?.end();
+        this.#client = undefined;
+        this.#filters.clear();
+        this.#qos.clear();
+        this.#values.clear();
+        this.#granted.clear();
+        this.#grantWaiters.clear();
+        this.#ackFilters.clear();
+        for (const [id, pending] of this.#pending) {
+            clearTimeout(pending.timer);
+            pending.reject(new Error(`this Live client closed before ${id} was acknowledged`));
+        }
+        this.#pending.clear();
+        this.#setState("closed");
+    }
+    /** Connect, with `token` when the renewal already fetched one. */
+    async #open(token) {
+        const generation = ++this.#generation;
+        const current = () => generation === this.#generation && this.#state !== "closed";
+        // A planned renewal keeps saying online; the page has nothing to show for it.
+        if (this.#state !== "online")
+            this.#setState("connecting");
+        let client;
+        let expiresAt;
+        try {
+            token ??= await this.#options.token();
+            const claims = readClaims(token);
+            const username = this.#options.username ?? claims?.sub;
+            if (!username) {
+                throw new Error("the token carries no sub: pass `username` for a token that is not a JWT");
+            }
+            expiresAt = claims?.exp === undefined ? undefined : claims.exp * 1000;
+            const connect = this.#options.connect ?? connectWithMqttJs;
+            client = await connect(this.#options.url, {
+                ...this.#options.mqttOptions,
+                clientId: `${this.#options.clientIdPrefix ?? "colca-client"}-${crypto.randomUUID()}`,
+                username,
+                password: token,
+                protocolVersion: 5,
+                clean: true,
+                keepalive: 30,
+                reconnectPeriod: 0,
+                connectTimeout: 10_000,
+            });
+        }
+        catch (error) {
+            if (!current())
+                return;
+            this.#report(error);
+            if (error instanceof MissingMqtt) {
+                this.close();
+                return;
+            }
+            this.#setState("offline");
+            this.#retry();
+            return;
+        }
+        if (!current()) {
+            client.end(true);
+            return;
+        }
+        this.#client = client;
+        client.on("connect", () => {
+            if (!current())
+                return;
+            this.#attempt = 0;
+            this.#setState("online");
+            this.#retainedSent.clear();
+            this.#granted.clear();
+            this.#subscribe([...this.#filters.keys()]);
+            this.#scheduleRenewal(expiresAt);
+        });
+        client.on("message", (topic, payload, packet) => {
+            if (current())
+                this.#receive(topic, payload, packet.retain);
+        });
+        client.on("error", (error) => {
+            if (current())
+                this.#report(error);
+        });
+        client.on("close", () => {
+            if (!current())
+                return;
+            this.#setState("offline");
+            this.#retry();
+        });
+    }
+    /** End the connection in hand and open the next one. */
+    #replace(token) {
+        clearTimeout(this.#renewTimer);
+        this.#renewTimer = undefined;
+        this.#generation += 1;
+        this.#client?.end(true);
+        this.#client = undefined;
+        void this.#open(token);
+    }
+    #retry() {
+        if (this.#retryTimer !== undefined)
+            return;
+        const ceiling = Math.min(this.#options.maxRetryMs ?? 30_000, (this.#options.retryMs ?? 1_000) * 2 ** this.#attempt);
+        this.#attempt += 1;
+        // Full jitter: a hundred pages that lost the same node do not come back in step.
+        this.#retryTimer = setTimeout(() => {
+            this.#retryTimer = undefined;
+            this.#replace();
+        }, Math.random() * ceiling);
+    }
+    #scheduleRenewal(expiresAt) {
+        clearTimeout(this.#renewTimer);
+        // A token without an expiry, such as a personal access token, is not renewed on a clock.
+        if (expiresAt === undefined)
+            return;
+        const due = expiresAt - (this.#options.renewBeforeMs ?? 30_000) - Date.now();
+        this.#renewTimer = setTimeout(() => {
+            this.#renewTimer = undefined;
+            void this.#renew(expiresAt);
+        }, Math.max(MIN_RENEW_MS, due));
+    }
+    /**
+     * Replace the connection only with a token that outlives it. An identity proxy
+     * can keep handing out the token it holds until its own refresh is due, and
+     * reconnecting with that one gains nothing and costs a gap in the values.
+     */
+    async #renew(expiresAt) {
+        const generation = this.#generation;
+        let token;
+        try {
+            token = await this.#options.token();
+        }
+        catch (error) {
+            if (generation === this.#generation)
+                this.#report(error);
+        }
+        if (generation !== this.#generation || this.#state === "closed")
+            return;
+        const exp = token === undefined ? undefined : readClaims(token)?.exp;
+        if (token !== undefined && (exp === undefined || exp * 1000 > expiresAt)) {
+            this.#replace(token);
+            return;
+        }
+        // Ask again shortly; once the token has run out, the node ends the session and
+        // reconnecting takes over.
+        if (Date.now() + MIN_RENEW_MS >= expiresAt)
+            return;
+        this.#renewTimer = setTimeout(() => {
+            this.#renewTimer = undefined;
+            void this.#renew(expiresAt);
+        }, MIN_RENEW_MS);
+    }
+    #subscribe(filters) {
+        const generation = this.#generation;
+        for (const qos of [0, 1]) {
+            const group = filters.filter((filter) => (this.#qos.get(filter) ?? 0) === qos);
+            if (group.length === 0)
+                continue;
+            this.#client?.subscribe(group, { qos }, (error, granted) => {
+                if (generation !== this.#generation)
+                    return;
+                if (error) {
+                    this.#report(error);
+                    return;
+                }
+                for (const grant of granted ?? []) {
+                    // 128 and up is a refusal: MQTT 3's failure code, or an MQTT 5 reason code.
+                    if (grant.qos >= 128) {
+                        this.#report(new Error(`the node refused the subscription to ${grant.topic}`));
+                        continue;
+                    }
+                    this.#granted.add(grant.topic);
+                    for (const wake of this.#grantWaiters.get(grant.topic) ?? [])
+                        wake();
+                    this.#grantWaiters.delete(grant.topic);
+                }
+            });
+        }
+    }
+    #whenGranted(filter) {
+        if (this.#granted.has(filter))
+            return Promise.resolve();
+        return new Promise((resolve) => {
+            this.#grantWaiters.set(filter, [...(this.#grantWaiters.get(filter) ?? []), resolve]);
+        });
+    }
+    /** One subscription per acknowledgement filter, kept for as long as the client lives. */
+    #listenForAcks(filter) {
+        if (this.#ackFilters.has(filter))
+            return;
+        this.#ackFilters.add(filter);
+        this.subscribe(filter, (value) => {
+            const ack = value.payload;
+            if (typeof ack !== "object" || ack === null)
+                return;
+            const id = ack.correlation_id;
+            const pending = typeof id === "string" ? this.#pending.get(id) : undefined;
+            // Somebody else's command, or one that already timed out.
+            if (pending === undefined || typeof id !== "string")
+                return;
+            this.#pending.delete(id);
+            clearTimeout(pending.timer);
+            pending.resolve(ack);
+        }, { qos: 1 });
+    }
+    #receive(topic, payload, retained) {
+        let decoded;
+        if (payload.length > 0) {
+            try {
+                decoded = JSON.parse(new TextDecoder().decode(payload));
+            }
+            catch {
+                this.#report(new Error(`unreadable payload on ${topic}`));
+                return;
+            }
+        }
+        const value = { topic, payload: decoded, retained, receivedAt: Date.now() };
+        if (decoded === undefined)
+            this.#values.delete(topic);
+        else
+            this.#values.set(topic, value);
+        for (const [filter, listeners] of this.#filters) {
+            if (!topicMatches(filter, topic))
+                continue;
+            if (retained && !this.#firstRetained(filter, topic))
+                continue;
+            for (const listener of listeners)
+                this.#deliver(listener, value);
+        }
+    }
+    /**
+     * The node answers every subscription with the retained values under it, so a
+     * topic covered by two filters arrives retained twice when the second filter is
+     * subscribed. Each filter's listeners get it once per connection.
+     */
+    #firstRetained(filter, topic) {
+        let sent = this.#retainedSent.get(filter);
+        if (sent === undefined) {
+            sent = new Set();
+            this.#retainedSent.set(filter, sent);
+        }
+        if (sent.has(topic))
+            return false;
+        sent.add(topic);
+        return true;
+    }
+    #deliver(listener, value) {
+        try {
+            listener(value);
+        }
+        catch (error) {
+            this.#report(error);
+        }
+    }
+    /** Drop the values no remaining filter covers, so a later subscriber is not handed stale ones. */
+    #forget(filter) {
+        for (const topic of this.#values.keys()) {
+            if (!topicMatches(filter, topic))
+                continue;
+            if (![...this.#filters.keys()].some((other) => topicMatches(other, topic)))
+                this.#values.delete(topic);
+        }
+    }
+    #setState(state) {
+        if (state === this.#state)
+            return;
+        this.#state = state;
+        for (const listener of this.#stateListeners)
+            listener(state);
+    }
+    #report(error) {
+        this.#options.onError?.(error instanceof Error ? error : new Error(String(error)));
+    }
+}
+class MissingMqtt extends Error {
+}
+async function connectWithMqttJs(url, options) {
+    let mqtt;
+    try {
+        mqtt = await import("mqtt");
+    }
+    catch (cause) {
+        throw new MissingMqtt("colca-client/live needs the mqtt package: npm install mqtt", { cause });
+    }
+    // A bundler hands a browser mqtt.js's ESM build, which exports only a default;
+    // Node gets the CommonJS build, where connect is also a named export.
+    const connect = mqtt.connect ?? mqtt.default?.connect;
+    if (connect === undefined)
+        throw new MissingMqtt("the mqtt package in use has no connect()");
+    return connect(url, options);
+}
+/** `sub` and `exp` from a JWT, without checking it — the node does that. */
+function readClaims(token) {
+    const parts = token.split(".");
+    if (parts.length !== 3)
+        return undefined;
+    try {
+        const base64 = parts[1].replace(/-/g, "+").replace(/_/g, "/");
+        const bytes = Uint8Array.from(atob(base64), (char) => char.charCodeAt(0));
+        const claims = JSON.parse(new TextDecoder().decode(bytes));
+        return {
+            sub: typeof claims.sub === "string" ? claims.sub : undefined,
+            exp: typeof claims.exp === "number" ? claims.exp : undefined,
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=live.js.map

package/dist/live.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"live.js","sourceRoot":"","sources":["../src/live.ts"],"names":[],"mappings":"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"}

package/dist/stream.d.ts

@@ -0,0 +1,54 @@
+/**
+ * A named cursor over one stream.
+ *
+ * The cursor lives at the node: `fetch` reads from its stored position and
+ * only `ack` moves it. Reopening the same name resumes where it was acked; a
+ * new name starts at the first record still retained.
+ *
+ * `drain()` acks a page once the consumer has asked for the record after its
+ * last one. A consumer that throws mid-page sees that page again, so handlers
+ * must be able to run twice on the same record.
+ */
+import type { Door, DoorRecord, Gap, Page } from "./door.js";
+export interface StreamOptions {
+    /** Records per page, 1…1000. */
+    max?: number;
+    /** Narrows to a subtree of the UNS path. */
+    prefix?: string;
+    /** Only for the `metrics` stream. */
+    signalIds?: readonly string[];
+    /**
+     * Called when a page reports pruned records. Nothing else announces it — a
+     * consumer that cares about completeness should say so here.
+     */
+    onGap?: (gap: Gap) => void;
+}
+export interface FollowOptions {
+    /** How long to wait after an empty page. */
+    pollMs?: number;
+    signal?: AbortSignal;
+}
+export declare class Stream {
+    #private;
+    private readonly door;
+    readonly name: string;
+    readonly cursor: string;
+    private readonly options;
+    constructor(door: Door, name: string, cursor: string, options?: StreamOptions);
+    /** One page from the cursor's position. Never moves the cursor. */
+    page(signal?: AbortSignal): Promise<Page>;
+    /** Ack `upto` — a record or its offset — as the last processed position. */
+    ack(upto: DoorRecord | number): Promise<boolean>;
+    /** Delete this cursor at the node. Fine when it never existed. */
+    retire(): Promise<void>;
+    /**
+     * The newest records on the stream, without touching the cursor — what a
+     * view wants when it opens. A consumer and a view can share a cursor name.
+     */
+    tail(max?: number): Promise<DoorRecord[]>;
+    /** Every record from the cursor to the head, acking page by page. Ends at the first empty page. */
+    drain(signal?: AbortSignal): AsyncGenerator<DoorRecord>;
+    /** `drain()` without an end: after an empty page, wait and drain again. */
+    follow({ pollMs, signal }?: FollowOptions): AsyncGenerator<DoorRecord>;
+}
+//# sourceMappingURL=stream.d.ts.map

package/dist/stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream.d.ts","sourceRoot":"","sources":["../src/stream.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,UAAU,EAAgB,GAAG,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAE3E,MAAM,WAAW,aAAa;IAC5B,gCAAgC;IAChC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,4CAA4C;IAC5C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qCAAqC;IACrC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9B;;;OAGG;IACH,KAAK,CAAC,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,IAAI,CAAC;CAC5B;AAED,MAAM,WAAW,aAAa;IAC5B,4CAA4C;IAC5C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,qBAAa,MAAM;;IAEf,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAHP,IAAI,EAAE,IAAI,EAClB,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACN,OAAO,GAAE,aAAkB;IAG9C,mEAAmE;IAC7D,IAAI,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAI/C,4EAA4E;IACtE,GAAG,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAItD,kEAAkE;IAC5D,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAI7B;;;OAGG;IACG,IAAI,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAS/C,mGAAmG;IAC5F,KAAK,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,cAAc,CAAC,UAAU,CAAC;IAc9D,2EAA2E;IACpE,MAAM,CAAC,EAAE,MAAa,EAAE,MAAM,EAAE,GAAE,aAAkB,GAAG,cAAc,CAAC,UAAU,CAAC;CAUzF"}

package/dist/stream.js

@@ -0,0 +1,85 @@
+/**
+ * A named cursor over one stream.
+ *
+ * The cursor lives at the node: `fetch` reads from its stored position and
+ * only `ack` moves it. Reopening the same name resumes where it was acked; a
+ * new name starts at the first record still retained.
+ *
+ * `drain()` acks a page once the consumer has asked for the record after its
+ * last one. A consumer that throws mid-page sees that page again, so handlers
+ * must be able to run twice on the same record.
+ */
+export class Stream {
+    door;
+    name;
+    cursor;
+    options;
+    constructor(door, name, cursor, options = {}) {
+        this.door = door;
+        this.name = name;
+        this.cursor = cursor;
+        this.options = options;
+    }
+    /** One page from the cursor's position. Never moves the cursor. */
+    async page(signal) {
+        return this.door.fetchPage(this.name, this.cursor, this.#fetchOptions(signal));
+    }
+    /** Ack `upto` — a record or its offset — as the last processed position. */
+    async ack(upto) {
+        return this.door.ack(this.name, this.cursor, typeof upto === "number" ? upto : upto.offset);
+    }
+    /** Delete this cursor at the node. Fine when it never existed. */
+    async retire() {
+        await this.door.deleteCursor(this.name, this.cursor);
+    }
+    /**
+     * The newest records on the stream, without touching the cursor — what a
+     * view wants when it opens. A consumer and a view can share a cursor name.
+     */
+    async tail(max) {
+        const page = await this.door.fetchPage(this.name, this.cursor, {
+            ...this.#fetchOptions(),
+            max: max ?? this.options.max,
+            tail: true,
+        });
+        return page.records;
+    }
+    /** Every record from the cursor to the head, acking page by page. Ends at the first empty page. */
+    async *drain(signal) {
+        for (;;) {
+            const page = await this.page(signal);
+            if (page.gap)
+                this.options.onGap?.(page.gap);
+            yield* page.records;
+            // The gap's bound when the hole swallowed the whole page, so the same
+            // gap is not reported forever.
+            const offset = page.records.at(-1)?.offset ?? page.gap?.toOffset;
+            if (offset === undefined)
+                return;
+            await this.ack(offset);
+        }
+    }
+    /** `drain()` without an end: after an empty page, wait and drain again. */
+    async *follow({ pollMs = 1000, signal } = {}) {
+        while (!signal?.aborted) {
+            yield* this.drain(signal);
+            await sleep(pollMs, signal);
+        }
+    }
+    #fetchOptions(signal) {
+        return { max: this.options.max, prefix: this.options.prefix, signalIds: this.options.signalIds, signal };
+    }
+}
+/** Resolves early when the signal aborts, so `follow()` stops within a poll. */
+function sleep(ms, signal) {
+    return new Promise((resolve) => {
+        const timer = setTimeout(done, ms);
+        signal?.addEventListener("abort", done, { once: true });
+        function done() {
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", done);
+            resolve();
+        }
+    });
+}
+//# sourceMappingURL=stream.js.map