@alpamayo-solutions/colca-client 0.36.2 → 0.36.4

package/README.md

@@ -27,6 +27,11 @@ for await (const record of panels.follow({ bell })) {
 }
 ```
 
+`follow()` also reads from its cursor when the bell stayed silent for
+`idleDrainMs` (five minutes by default), so a ring that was lost does not stall
+the consumer for good. That is a recovery read, not a polling cadence: keep it
+long. `idleDrainMs: null` waits for a ring alone.
+
 ## A producer
 
 ```ts

package/dist/doorbell.d.ts

@@ -6,16 +6,44 @@
  * takes `generation` before it drains and afterwards waits for a newer one, so
  * a ring that arrives while it drains is never lost. Rings are coalesced: many
  * rings during one drain cost one more drain.
+ *
+ * A ring can still go missing before it reaches the bell: a subscription the
+ * broker dropped, a `/watch` connection that died without an error, a wiring
+ * mistake in the caller. So a consumer bounds its wait (`timeoutMs`) and reads
+ * from its cursor again when the bound passes. One lost ring then costs a
+ * delay, not a consumer that stands still until it is restarted.
+ */
+/**
+ * How long a consumer waits on a silent bell before it reads from its cursor
+ * anyway: five minutes, the value the Python SDK uses. It is a recovery read
+ * for a ring that never arrived, not a polling cadence — the bell is what
+ * keeps a consumer current, and this must stay long enough to say so.
  */
+export declare const IDLE_DRAIN_MS = 300000;
+/** Why a wait on the bell ended. */
+export type Wake = "rang" | "timeout" | "aborted";
+export interface AfterOptions {
+    /** Ends the wait with `"aborted"`. */
+    signal?: AbortSignal;
+    /**
+     * Ends the wait with `"timeout"` when nothing rang for this long. Greater
+     * than zero; without it the wait has no bound.
+     */
+    timeoutMs?: number;
+}
 export declare class Doorbell {
     #private;
     /** Increases with every ring. */
     get generation(): number;
     ring(): void;
     /**
-     * Resolves once the bell rang after `since` was taken — at once when it
-     * already has — or when `signal` aborts.
+     * Resolves with why the wait ended: `"rang"` once the bell rang after
+     * `since` was taken — at once when it already has —, `"aborted"` when
+     * `signal` aborts, `"timeout"` when `timeoutMs` passed without a ring. The
+     * caller reads from its cursor again on `"rang"` and on `"timeout"` alike.
+     *
+     * The options may also be the signal alone.
      */
-    after(since: number, signal?: AbortSignal): Promise<void>;
+    after(since: number, options?: AbortSignal | AfterOptions): Promise<Wake>;
 }
 //# sourceMappingURL=doorbell.d.ts.map

package/dist/doorbell.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"doorbell.d.ts","sourceRoot":"","sources":["../src/doorbell.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,qBAAa,QAAQ;;IAInB,iCAAiC;IACjC,IAAI,UAAU,IAAI,MAAM,CAEvB;IAED,IAAI,IAAI,IAAI;IAOZ;;;OAGG;IACG,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;CAahE"}
+{"version":3,"file":"doorbell.d.ts","sourceRoot":"","sources":["../src/doorbell.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;;;;;GAKG;AACH,eAAO,MAAM,aAAa,SAAU,CAAC;AAErC,oCAAoC;AACpC,MAAM,MAAM,IAAI,GAAG,MAAM,GAAG,SAAS,GAAG,SAAS,CAAC;AAElD,MAAM,WAAW,YAAY;IAC3B,sCAAsC;IACtC,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAKD,qBAAa,QAAQ;;IAInB,iCAAiC;IACjC,IAAI,UAAU,IAAI,MAAM,CAEvB;IAED,IAAI,IAAI,IAAI;IAOZ;;;;;;;OAOG;IACH,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,WAAW,GAAG,YAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;CAoC9E"}

package/dist/doorbell.js

@@ -6,7 +6,22 @@
  * takes `generation` before it drains and afterwards waits for a newer one, so
  * a ring that arrives while it drains is never lost. Rings are coalesced: many
  * rings during one drain cost one more drain.
+ *
+ * A ring can still go missing before it reaches the bell: a subscription the
+ * broker dropped, a `/watch` connection that died without an error, a wiring
+ * mistake in the caller. So a consumer bounds its wait (`timeoutMs`) and reads
+ * from its cursor again when the bound passes. One lost ring then costs a
+ * delay, not a consumer that stands still until it is restarted.
+ */
+/**
+ * How long a consumer waits on a silent bell before it reads from its cursor
+ * anyway: five minutes, the value the Python SDK uses. It is a recovery read
+ * for a ring that never arrived, not a polling cadence — the bell is what
+ * keeps a consumer current, and this must stay long enough to say so.
  */
+export const IDLE_DRAIN_MS = 300_000;
+/** The longest delay a timer takes; a longer one would fire at once. */
+const MAX_TIMER_MS = 2 ** 31 - 1;
 export class Doorbell {
     #generation = 0;
     #waiters = new Set();
@@ -22,21 +37,46 @@ export class Doorbell {
             wake();
     }
     /**
-     * Resolves once the bell rang after `since` was taken — at once when it
-     * already has — or when `signal` aborts.
+     * Resolves with why the wait ended: `"rang"` once the bell rang after
+     * `since` was taken — at once when it already has —, `"aborted"` when
+     * `signal` aborts, `"timeout"` when `timeoutMs` passed without a ring. The
+     * caller reads from its cursor again on `"rang"` and on `"timeout"` alike.
+     *
+     * The options may also be the signal alone.
      */
-    async after(since, signal) {
-        while (this.#generation === since && !signal?.aborted) {
-            await new Promise((resolve) => {
-                const done = () => {
-                    this.#waiters.delete(done);
-                    signal?.removeEventListener("abort", done);
-                    resolve();
-                };
-                this.#waiters.add(done);
-                signal?.addEventListener("abort", done, { once: true });
-            });
+    after(since, options = {}) {
+        const { signal, timeoutMs } = "aborted" in options ? { signal: options } : options;
+        if (timeoutMs !== undefined && !(timeoutMs > 0)) {
+            return Promise.reject(new RangeError(`timeoutMs must be greater than zero, got ${String(timeoutMs)}`));
         }
+        if (this.#generation !== since)
+            return Promise.resolve("rang");
+        if (signal?.aborted)
+            return Promise.resolve("aborted");
+        return new Promise((resolve) => {
+            let timer;
+            // Whatever ends the wait takes the other two with it, so a consumer that
+            // waits for days leaves no timer and no listener behind per wait.
+            const end = (why) => {
+                this.#waiters.delete(rang);
+                signal?.removeEventListener("abort", aborted);
+                clearTimeout(timer);
+                resolve(why);
+            };
+            const rang = () => {
+                end("rang");
+            };
+            const aborted = () => {
+                end("aborted");
+            };
+            this.#waiters.add(rang);
+            signal?.addEventListener("abort", aborted, { once: true });
+            if (timeoutMs !== undefined) {
+                timer = setTimeout(() => {
+                    end("timeout");
+                }, Math.min(timeoutMs, MAX_TIMER_MS));
+            }
+        });
     }
 }
 //# sourceMappingURL=doorbell.js.map

package/dist/doorbell.js.map

@@ -1 +1 @@
-{"version":3,"file":"doorbell.js","sourceRoot":"","sources":["../src/doorbell.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,MAAM,OAAO,QAAQ;IACnB,WAAW,GAAG,CAAC,CAAC;IAChB,QAAQ,GAAG,IAAI,GAAG,EAAc,CAAC;IAEjC,iCAAiC;IACjC,IAAI,UAAU;QACZ,OAAO,IAAI,CAAC,WAAW,CAAC;IAC1B,CAAC;IAED,IAAI;QACF,IAAI,CAAC,WAAW,IAAI,CAAC,CAAC;QACtB,MAAM,OAAO,GAAG,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,CAAC;QACnC,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAC;QACtB,KAAK,MAAM,IAAI,IAAI,OAAO;YAAE,IAAI,EAAE,CAAC;IACrC,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,KAAK,CAAC,KAAa,EAAE,MAAoB;QAC7C,OAAO,IAAI,CAAC,WAAW,KAAK,KAAK,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC;YACtD,MAAM,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;gBAClC,MAAM,IAAI,GAAG,GAAS,EAAE;oBACtB,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;oBAC3B,MAAM,EAAE,mBAAmB,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;oBAC3C,OAAO,EAAE,CAAC;gBACZ,CAAC,CAAC;gBACF,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;gBACxB,MAAM,EAAE,gBAAgB,CAAC,OAAO,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;YAC1D,CAAC,CAAC,CAAC;QACL,CAAC;IACH,CAAC;CACF"}
+{"version":3,"file":"doorbell.js","sourceRoot":"","sources":["../src/doorbell.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,OAAO,CAAC;AAerC,wEAAwE;AACxE,MAAM,YAAY,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;AAEjC,MAAM,OAAO,QAAQ;IACnB,WAAW,GAAG,CAAC,CAAC;IAChB,QAAQ,GAAG,IAAI,GAAG,EAAc,CAAC;IAEjC,iCAAiC;IACjC,IAAI,UAAU;QACZ,OAAO,IAAI,CAAC,WAAW,CAAC;IAC1B,CAAC;IAED,IAAI;QACF,IAAI,CAAC,WAAW,IAAI,CAAC,CAAC;QACtB,MAAM,OAAO,GAAG,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,CAAC;QACnC,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAC;QACtB,KAAK,MAAM,IAAI,IAAI,OAAO;YAAE,IAAI,EAAE,CAAC;IACrC,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,KAAa,EAAE,UAAsC,EAAE;QAC3D,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,GAAiB,SAAS,IAAI,OAAO,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC;QACjG,IAAI,SAAS,KAAK,SAAS,IAAI,CAAC,CAAC,SAAS,GAAG,CAAC,CAAC,EAAE,CAAC;YAChD,OAAO,OAAO,CAAC,MAAM,CAAC,IAAI,UAAU,CAAC,4CAA4C,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC,CAAC;QACzG,CAAC;QACD,IAAI,IAAI,CAAC,WAAW,KAAK,KAAK;YAAE,OAAO,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QAC/D,IAAI,MAAM,EAAE,OAAO;YAAE,OAAO,OAAO,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;QAEvD,OAAO,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;YACnC,IAAI,KAAgD,CAAC;YACrD,yEAAyE;YACzE,kEAAkE;YAClE,MAAM,GAAG,GAAG,CAAC,GAAS,EAAQ,EAAE;gBAC9B,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;gBAC3B,MAAM,EAAE,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;gBAC9C,YAAY,CAAC,KAAK,CAAC,CAAC;gBACpB,OAAO,CAAC,GAAG,CAAC,CAAC;YACf,CAAC,CAAC;YACF,MAAM,IAAI,GAAG,GAAS,EAAE;gBACtB,GAAG,CAAC,MAAM,CAAC,CAAC;YACd,CAAC,CAAC;YACF,MAAM,OAAO,GAAG,GAAS,EAAE;gBACzB,GAAG,CAAC,SAAS,CAAC,CAAC;YACjB,CAAC,CAAC;YACF,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YACxB,MAAM,EAAE,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;YAC3D,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;gBAC5B,KAAK,GAAG,UAAU,CAChB,GAAG,EAAE;oBACH,GAAG,CAAC,SAAS,CAAC,CAAC;gBACjB,CAAC,EACD,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,YAAY,CAAC,CAClC,CAAC;YACJ,CAAC;QACH,CAAC,CAAC,CAAC;IACL,CAAC;CACF"}

package/dist/index.d.ts

@@ -4,14 +4,16 @@
  * ```ts
  * const door = new Door({ baseUrl: "http://colca", service: "my-app" });
  * const stream = new Stream(door, "annotations", door.cursorName("panels"));
- * for await (const record of stream.follow()) {
+ * const bell = new Doorbell(); // rung whenever the stream may have grown
+ * for await (const record of stream.follow({ bell })) {
  *   console.log(record.topic, record.payload);
  * }
  * ```
  */
 export { Door, DoorError } from "./door.js";
 export type { Attribution, DoorOptions, DoorRecord, FetchOptions, Gap, KvEntry, KvLevel, KvOptions, Page, PublishResult, SelfInfo, } from "./door.js";
-export { Doorbell } from "./doorbell.js";
+export { Doorbell, IDLE_DRAIN_MS } from "./doorbell.js";
+export type { AfterOptions, Wake } from "./doorbell.js";
 export { Stream } from "./stream.js";
 export type { FollowOptions, StreamOptions } from "./stream.js";
 export { DEFAULT_ROOT, TOPIC_VERSION, parseTopic, topic, topicMatches, topicPrefix } from "./topics.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAC5C,YAAY,EACV,WAAW,EACX,WAAW,EACX,UAAU,EACV,YAAY,EACZ,GAAG,EACH,OAAO,EACP,OAAO,EACP,SAAS,EACT,IAAI,EACJ,aAAa,EACb,QAAQ,GACT,MAAM,WAAW,CAAC;AAEnB,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEhE,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,UAAU,EAAE,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AACxG,YAAY,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE5D,OAAO,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAC5F,YAAY,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAElD,OAAO,EACL,gBAAgB,EAChB,sBAAsB,EACtB,eAAe,EACf,qBAAqB,GACtB,MAAM,cAAc,CAAC;AACtB,YAAY,EACV,cAAc,EACd,mBAAmB,EACnB,iBAAiB,EACjB,aAAa,EACb,kBAAkB,GACnB,MAAM,cAAc,CAAC;AAGtB,cAAc,0BAA0B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAC5C,YAAY,EACV,WAAW,EACX,WAAW,EACX,UAAU,EACV,YAAY,EACZ,GAAG,EACH,OAAO,EACP,OAAO,EACP,SAAS,EACT,IAAI,EACJ,aAAa,EACb,QAAQ,GACT,MAAM,WAAW,CAAC;AAEnB,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AACxD,YAAY,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,eAAe,CAAC;AACxD,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEhE,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,UAAU,EAAE,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AACxG,YAAY,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE5D,OAAO,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAC5F,YAAY,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAElD,OAAO,EACL,gBAAgB,EAChB,sBAAsB,EACtB,eAAe,EACf,qBAAqB,GACtB,MAAM,cAAc,CAAC;AACtB,YAAY,EACV,cAAc,EACd,mBAAmB,EACnB,iBAAiB,EACjB,aAAa,EACb,kBAAkB,GACnB,MAAM,cAAc,CAAC;AAGtB,cAAc,0BAA0B,CAAC"}

package/dist/index.js

@@ -4,13 +4,14 @@
  * ```ts
  * const door = new Door({ baseUrl: "http://colca", service: "my-app" });
  * const stream = new Stream(door, "annotations", door.cursorName("panels"));
- * for await (const record of stream.follow()) {
+ * const bell = new Doorbell(); // rung whenever the stream may have grown
+ * for await (const record of stream.follow({ bell })) {
  *   console.log(record.topic, record.payload);
  * }
  * ```
  */
 export { Door, DoorError } from "./door.js";
-export { Doorbell } from "./doorbell.js";
+export { Doorbell, IDLE_DRAIN_MS } from "./doorbell.js";
 export { Stream } from "./stream.js";
 export { DEFAULT_ROOT, TOPIC_VERSION, parseTopic, topic, topicMatches, topicPrefix } from "./topics.js";
 export { annotationIdMaterial, deriveAnnotationId, newUlid, ulidFromBytes } from "./ids.js";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAe5C,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAGrC,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,UAAU,EAAE,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAGxG,OAAO,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAG5F,OAAO,EACL,gBAAgB,EAChB,sBAAsB,EACtB,eAAe,EACf,qBAAqB,GACtB,MAAM,cAAc,CAAC;AAStB,yEAAyE;AACzE,cAAc,0BAA0B,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAe5C,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAExD,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAGrC,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,UAAU,EAAE,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAGxG,OAAO,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAG5F,OAAO,EACL,gBAAgB,EAChB,sBAAsB,EACtB,eAAe,EACf,qBAAqB,GACtB,MAAM,cAAc,CAAC;AAStB,yEAAyE;AACzE,cAAc,0BAA0B,CAAC"}

package/dist/stream.d.ts

@@ -10,7 +10,7 @@
  * must be able to run twice on the same record.
  */
 import type { Door, DoorRecord, Gap, Page } from "./door.js";
-import type { Doorbell } from "./doorbell.js";
+import { type Doorbell } from "./doorbell.js";
 export interface StreamOptions {
     /** Records per page, 1…1000. */
     max?: number;
@@ -37,6 +37,14 @@ export interface FollowOptions {
      */
     bell: Doorbell;
     signal?: AbortSignal;
+    /**
+     * How long to wait on a silent bell before reading from the cursor anyway,
+     * `IDLE_DRAIN_MS` (five minutes) when omitted. It recovers from a ring that
+     * never arrived and is not a polling cadence: keep it long, and ring the
+     * bell for everything that can grow the stream. `null` waits for a ring
+     * alone — then a lost ring stalls the consumer until `signal` aborts.
+     */
+    idleDrainMs?: number | null;
 }
 export declare class Stream {
     #private;
@@ -60,9 +68,16 @@ export declare class Stream {
     drain(signal?: AbortSignal): AsyncGenerator<DoorRecord>;
     /**
      * Drain now, then again after every ring of `bell`, until `signal` aborts.
-     * Nothing is read on a timer: a ring during a drain leads to one more drain,
-     * and a consumer rings the bell on reconnect so what arrived meanwhile is read.
+     * A ring during a drain leads to one more drain, and a consumer rings the
+     * bell on reconnect so what arrived meanwhile is read.
+     *
+     * The wait on the bell is bounded by `idleDrainMs`: when nothing rang for
+     * that long, the stream is read from its cursor once more. That read is the
+     * recovery for a ring that was lost on its way to the bell, which would
+     * otherwise leave the consumer waiting forever beside a growing stream. It
+     * is not how a consumer learns of new records, and an idle stream costs one
+     * empty page per bound.
      */
-    follow({ bell, signal }: FollowOptions): AsyncGenerator<DoorRecord>;
+    follow({ bell, signal, idleDrainMs }: FollowOptions): AsyncGenerator<DoorRecord>;
 }
 //# sourceMappingURL=stream.d.ts.map

package/dist/stream.d.ts.map

@@ -1 +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;AAC3E,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9C,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;;;;OAIG;IACH,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B;;;OAGG;IACH,KAAK,CAAC,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,IAAI,CAAC;CAC5B;AAED,MAAM,WAAW,aAAa;IAC5B;;;OAGG;IACH,IAAI,EAAE,QAAQ,CAAC;IACf,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;IAY9D;;;;OAIG;IACI,MAAM,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,aAAa,GAAG,cAAc,CAAC,UAAU,CAAC;CAiB3E"}
+{"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;AAC3E,OAAO,EAAiB,KAAK,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE7D,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;;;;OAIG;IACH,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B;;;OAGG;IACH,KAAK,CAAC,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,IAAI,CAAC;CAC5B;AAED,MAAM,WAAW,aAAa;IAC5B;;;OAGG;IACH,IAAI,EAAE,QAAQ,CAAC;IACf,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;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;IAY9D;;;;;;;;;;;OAWG;IACI,MAAM,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,WAA2B,EAAE,EAAE,aAAa,GAAG,cAAc,CAAC,UAAU,CAAC;CAoBxG"}

package/dist/stream.js

@@ -9,6 +9,7 @@
  * 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 { IDLE_DRAIN_MS } from "./doorbell.js";
 export class Stream {
     door;
     name;
@@ -59,14 +60,24 @@ export class Stream {
     }
     /**
      * Drain now, then again after every ring of `bell`, until `signal` aborts.
-     * Nothing is read on a timer: a ring during a drain leads to one more drain,
-     * and a consumer rings the bell on reconnect so what arrived meanwhile is read.
+     * A ring during a drain leads to one more drain, and a consumer rings the
+     * bell on reconnect so what arrived meanwhile is read.
+     *
+     * The wait on the bell is bounded by `idleDrainMs`: when nothing rang for
+     * that long, the stream is read from its cursor once more. That read is the
+     * recovery for a ring that was lost on its way to the bell, which would
+     * otherwise leave the consumer waiting forever beside a growing stream. It
+     * is not how a consumer learns of new records, and an idle stream costs one
+     * empty page per bound.
      */
-    async *follow({ bell, signal }) {
+    async *follow({ bell, signal, idleDrainMs = IDLE_DRAIN_MS }) {
+        if (idleDrainMs !== null && !(idleDrainMs > 0)) {
+            throw new RangeError(`idleDrainMs must be greater than zero, or null, got ${String(idleDrainMs)}`);
+        }
         while (!signal?.aborted) {
             const seen = bell.generation;
             yield* this.drain(signal);
-            await bell.after(seen, signal);
+            await bell.after(seen, { signal, timeoutMs: idleDrainMs ?? undefined });
         }
     }
     #fetchOptions(signal) {

package/dist/stream.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alpamayo-solutions/colca-client",
-  "version": "0.36.2",
+  "version": "0.36.4",
   "description": "Client for a Colca node's door: fetch, ack, publish, kv, self.",
   "keywords": [
     "colca",