doover-js 0.6.9 → 0.7.0

package/dist/react/messageRangeStore.d.ts

@@ -0,0 +1,87 @@
+import type { MessageStructure } from "../types/common";
+/**
+ * A per-channel cache of *proven-complete* id ranges.
+ *
+ * `useChannelMessages` models history as a chain of cursors: each page's oldest
+ * id is the next page's `before`. That chain is anchored at its first cursor, so
+ * two windows over the same channel are two unrelated chains — re-anchoring
+ * always refetches, even over data already held.
+ *
+ * This store keeps the fact the chain throws away. A response to
+ * `before=X, limit=N` is "the N newest messages strictly older than X", so a
+ * full page proves that *every* message in `[oldest.id, X)` is in hand. History
+ * is append-only, so that stays true forever. Overlapping windows then merge
+ * into one segment instead of duplicating, and revisiting a range costs nothing.
+ *
+ * The store sits under the query, not beside it: the chains stay as they are and
+ * remain the cache React Query sees, while this layer removes the network calls
+ * underneath them.
+ *
+ * Ids are decimal snowflakes of varying length, so every comparison goes through
+ * `BigInt` — string ordering would put "500" after "4000".
+ */
+/** A contiguous range of history we can prove we hold in full. */
+export interface RangeSegment {
+    /** Id of the oldest message held. Meaningless when `atStart` (coverage runs to -inf). */
+    lo: bigint;
+    /** Exclusive upper bound of proven coverage. */
+    hi: bigint;
+    /** No messages exist below `lo` — the channel (or its retention window) starts here. */
+    atStart: boolean;
+    /**
+     * `hi` tracks the live feed. Only true while a fetch has proven coverage up to
+     * roughly now AND the socket has not dropped since — see `sealTips`.
+     */
+    live: boolean;
+    /** Ascending by id. */
+    messages: MessageStructure[];
+}
+export declare class ChannelRangeStore {
+    /** Disjoint, ascending by `lo`. */
+    private segments;
+    /**
+     * Answer "the newest `limit` messages strictly older than `before`" from cache,
+     * or `undefined` when the range isn't proven and the caller must fetch.
+     *
+     * Returns ascending by id, matching `listMessages({ order: "asc" })`.
+     */
+    read(before: bigint, limit: number): MessageStructure[] | undefined;
+    /**
+     * Record a fetched page. `before` is the cursor actually sent and `limit` the
+     * one actually requested — a short page proves the range bottoms out, which is
+     * only sound because the server rejects an over-cap `limit` rather than
+     * silently clamping it.
+     */
+    record(params: {
+        before: bigint;
+        limit: number;
+        page: MessageStructure[];
+        /** Epoch ms the request was issued, for deciding whether this segment is live. */
+        at?: number;
+    }): void;
+    /**
+     * Extend the live segment with a pushed message. Ignored unless a segment is
+     * currently live: outside that, the message and the segment may have a gap
+     * between them, and claiming coverage across it would hide messages forever.
+     */
+    recordLive(message: MessageStructure): void;
+    /**
+     * Stop trusting the live feed to extend coverage — call when the socket drops.
+     * Messages sent while disconnected would leave a hole, so segments go back to
+     * proving coverage by fetching.
+     */
+    sealTips(): void;
+    /** Test/debug view. */
+    snapshot(): RangeSegment[];
+    clear(): void;
+    /** Union `incoming` with every segment it overlaps or merely touches. */
+    private merge;
+}
+/**
+ * Stores are per *stream* — agent, channel, and any `fields` filter, which
+ * returns a different set of messages. Deliberately NOT per anchor: sharing
+ * across anchors is the entire point.
+ */
+export declare function getChannelRangeStore(key: string): ChannelRangeStore;
+/** Drop every store. Tests only — there is no eviction in normal operation. */
+export declare function resetChannelRangeStores(): void;

package/dist/react/messageRangeStore.js

@@ -0,0 +1,134 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ChannelRangeStore = void 0;
+exports.getChannelRangeStore = getChannelRangeStore;
+exports.resetChannelRangeStores = resetChannelRangeStores;
+/**
+ * How close to "now" a fetch's `before` must be for its segment to accept live
+ * pushes. Beyond this the feed and the segment may not be contiguous.
+ */
+const LIVE_PROOF_TOLERANCE_MS = 60000;
+const idOf = (message) => BigInt(message.id);
+function sortById(messages) {
+    return [...messages].sort((a, b) => (idOf(a) < idOf(b) ? -1 : idOf(a) > idOf(b) ? 1 : 0));
+}
+function dedupeById(messages) {
+    const seen = new Map();
+    // Later wins: a live push or a refetch supersedes an older copy
+    for (const message of messages)
+        seen.set(message.id, message);
+    return sortById([...seen.values()]);
+}
+class ChannelRangeStore {
+    constructor() {
+        /** Disjoint, ascending by `lo`. */
+        this.segments = [];
+    }
+    /**
+     * Answer "the newest `limit` messages strictly older than `before`" from cache,
+     * or `undefined` when the range isn't proven and the caller must fetch.
+     *
+     * Returns ascending by id, matching `listMessages({ order: "asc" })`.
+     */
+    read(before, limit) {
+        const segment = this.segments.find((s) => before <= s.hi && (s.atStart || before >= s.lo));
+        if (!segment)
+            return undefined;
+        const older = segment.messages.filter((m) => idOf(m) < before);
+        if (older.length >= limit)
+            return older.slice(older.length - limit);
+        // Short of `limit` only tells us the range is exhausted if nothing precedes it
+        return segment.atStart ? older : undefined;
+    }
+    /**
+     * Record a fetched page. `before` is the cursor actually sent and `limit` the
+     * one actually requested — a short page proves the range bottoms out, which is
+     * only sound because the server rejects an over-cap `limit` rather than
+     * silently clamping it.
+     */
+    record(params) {
+        const { before, limit, page } = params;
+        const at = params.at ?? Date.now();
+        const messages = sortById(page);
+        const atStart = messages.length < limit;
+        const lo = messages.length > 0 ? idOf(messages[0]) : before;
+        const live = timestampOf(before) >= at - LIVE_PROOF_TOLERANCE_MS;
+        this.merge({ lo, hi: before, atStart, live, messages });
+    }
+    /**
+     * Extend the live segment with a pushed message. Ignored unless a segment is
+     * currently live: outside that, the message and the segment may have a gap
+     * between them, and claiming coverage across it would hide messages forever.
+     */
+    recordLive(message) {
+        const id = idOf(message);
+        const tip = this.segments.find((s) => s.live);
+        if (!tip || id < tip.lo)
+            return;
+        tip.messages = dedupeById([...tip.messages, message]);
+        if (id >= tip.hi)
+            tip.hi = id + 1n;
+    }
+    /**
+     * Stop trusting the live feed to extend coverage — call when the socket drops.
+     * Messages sent while disconnected would leave a hole, so segments go back to
+     * proving coverage by fetching.
+     */
+    sealTips() {
+        for (const segment of this.segments)
+            segment.live = false;
+    }
+    /** Test/debug view. */
+    snapshot() {
+        return this.segments.map((s) => ({ ...s, messages: [...s.messages] }));
+    }
+    clear() {
+        this.segments = [];
+    }
+    /** Union `incoming` with every segment it overlaps or merely touches. */
+    merge(incoming) {
+        const overlapping = [];
+        const rest = [];
+        for (const segment of this.segments) {
+            // Touching counts: [a,b) and [b,c) are both proven, so [a,c) is too
+            const disjoint = segment.hi < incoming.lo || segment.lo > incoming.hi;
+            (disjoint ? rest : overlapping).push(segment);
+        }
+        const merged = overlapping.reduce((acc, s) => ({
+            lo: s.lo < acc.lo ? s.lo : acc.lo,
+            hi: s.hi > acc.hi ? s.hi : acc.hi,
+            atStart: acc.atStart || s.atStart,
+            live: acc.live || s.live,
+            messages: [...acc.messages, ...s.messages],
+        }), incoming);
+        merged.messages = dedupeById(merged.messages);
+        if (merged.atStart && merged.messages.length > 0) {
+            merged.lo = idOf(merged.messages[0]);
+        }
+        this.segments = [...rest, merged].sort((a, b) => (a.lo < b.lo ? -1 : a.lo > b.lo ? 1 : 0));
+    }
+}
+exports.ChannelRangeStore = ChannelRangeStore;
+const SNOWFLAKE_EPOCH_MS = 1735689600000n;
+/** Epoch ms encoded in a snowflake, without going through the string round-trip. */
+function timestampOf(id) {
+    return Number((id >> 22n) + SNOWFLAKE_EPOCH_MS);
+}
+const stores = new Map();
+/**
+ * Stores are per *stream* — agent, channel, and any `fields` filter, which
+ * returns a different set of messages. Deliberately NOT per anchor: sharing
+ * across anchors is the entire point.
+ */
+function getChannelRangeStore(key) {
+    let store = stores.get(key);
+    if (!store) {
+        store = new ChannelRangeStore();
+        stores.set(key, store);
+    }
+    return store;
+}
+/** Drop every store. Tests only — there is no eviction in normal operation. */
+function resetChannelRangeStores() {
+    stores.clear();
+}

package/dist/react/useChannelMessages.d.ts

@@ -2,7 +2,13 @@ import { type InfiniteData, type UseInfiniteQueryResult } from "@tanstack/react-
 import type { MessageStructure } from "../types/common";
 import type { ChannelIdentifier } from "../types/viewer";
 import { type OfflineStatusSnapshot } from "./useOfflineStatus";
-export declare function channelMessagesQueryKey(agentId: string | undefined, channelName: string | undefined, fields?: readonly string[], sources?: string[]): readonly ["doover", "agent", string | undefined, "channel", string | undefined, "messages", "src", string] | readonly ["doover", "agent", string | undefined, "channel", string | undefined, "messages", "src", string, {
+export declare function channelMessagesQueryKey(agentId: string | undefined, channelName: string | undefined, fields?: readonly string[], sources?: string[], anchor?: string): readonly ["doover", "agent", string | undefined, "channel", string | undefined, "messages", "src", string] | readonly ["doover", "agent", string | undefined, "channel", string | undefined, "messages", "src", string, {
+    readonly anchor: string;
+}] | readonly ["doover", "agent", string | undefined, "channel", string | undefined, "messages", "src", string, {
+    readonly fields: string[];
+}] | readonly ["doover", "agent", string | undefined, "channel", string | undefined, "messages", "src", string, {
+    readonly anchor: string;
+}, {
     readonly fields: string[];
 }];
 export interface UseChannelMessagesOptions {
@@ -22,6 +28,20 @@ export interface UseChannelMessagesOptions {
      * snowflake so server-stamped messages don't get missed).
      */
     initialBefore?: string;
+    /**
+     * Pin the window to a point in history (snowflake id), for "jump to this
+     * date" navigation. Changing it re-anchors and refetches.
+     *
+     * Distinct from `initialBefore`, which is a clock-skew seed regenerated per
+     * mount and therefore must NOT dimension the cache key. An anchor identifies
+     * a stream the caller means to look at, so it does. Pass a stable value — a
+     * per-render `now` would refetch on every render.
+     *
+     * Cheaper than it looks: anchored windows share the range cache with every
+     * other window on the channel, so re-anchoring over already-fetched history
+     * costs no requests.
+     */
+    anchor?: string;
     /**
      * Optional lower-bound snowflake id. The server only returns messages
      * newer than this on every page, so paginating older eventually returns

package/dist/react/useChannelMessages.js

@@ -4,14 +4,21 @@ exports.channelMessagesQueryKey = channelMessagesQueryKey;
 exports.useChannelMessages = useChannelMessages;
 const react_1 = require("react");
 const react_query_1 = require("@tanstack/react-query");
+const snowflake_1 = require("../utils/snowflake");
+const messageRangeStore_1 = require("./messageRangeStore");
 const context_1 = require("./context");
 const useChannelSubscription_1 = require("./useChannelSubscription");
 const useOfflineStatus_1 = require("./useOfflineStatus");
-function channelMessagesQueryKey(agentId, channelName, fields, sources) {
+function channelMessagesQueryKey(agentId, channelName, fields, sources, anchor) {
     // Source-dimension the key (multiplex source subsets cache independently);
     // "*" means "all/unspecified" for a plain DooverClient/LocalAgentClient.
     const sourceDim = sources && sources.length ? [...sources].sort().join(",") : "*";
-    const key = ["doover", "agent", agentId, "channel", channelName, "messages", "src", sourceDim];
+    const base = ["doover", "agent", agentId, "channel", channelName, "messages", "src", sourceDim];
+    // An anchored window is its own chain of cursors, so it must not share a cache
+    // entry with the live one — same reasoning as `fields` below. Note this is
+    // deliberately absent from the range store's key: sharing ranges across
+    // anchors is the point of it.
+    const key = anchor ? [...base, { anchor }] : base;
     if (!fields || fields.length === 0)
         return key;
     // A `field_name`-filtered request returns a different message stream than
@@ -22,6 +29,8 @@ function channelMessagesQueryKey(agentId, channelName, fields, sources) {
     // order doesn't fragment the cache.
     return [...key, { fields: [...fields].sort() }];
 }
+/** Mirrors `MessagesApi.listMessages`'s own default. */
+const DEFAULT_PAGE_LIMIT = 10;
 /**
  * Paginated infinite query over `DooverDataProvider.getMessages`, with live
  * `messageCreate` pushes prepended/appended to the newest page. The "next"
@@ -36,10 +45,27 @@ function useChannelMessages(identifier, options) {
     const liveUpdates = options?.liveUpdates ?? true;
     const fields = options?.fields;
     const initialBefore = options?.initialBefore;
+    const anchor = options?.anchor;
     const after = options?.after;
     const autoPaginate = options?.autoPaginate ?? false;
     const sources = options?.sources;
-    const key = channelMessagesQueryKey(agentId, channelName, fields, sources);
+    const key = channelMessagesQueryKey(agentId, channelName, fields, sources, anchor);
+    // Keyed per stream, NOT per anchor — every window on this channel shares it.
+    const storeKey = JSON.stringify(channelMessagesQueryKey(agentId, channelName, fields, sources));
+    const store = (0, messageRangeStore_1.getChannelRangeStore)(storeKey);
+    // `after`/`sources` change what a page means (a short page proves a bound was
+    // hit, not that history ran out; multiplex merges several streams), so those
+    // requests bypass the range cache rather than record unsound coverage.
+    const rangeCacheable = after === undefined && !sources;
+    // A dropped socket may have swallowed messages, so the live feed stops being
+    // proof of coverage until a fetch re-establishes it.
+    (0, react_1.useEffect)(() => {
+        const onClose = () => store.sealTips();
+        client.gateway.on("close", onClose);
+        return () => {
+            client.gateway.off("close", onClose);
+        };
+    }, [client, store]);
     const onMessage = (0, react_1.useCallback)((message) => {
         // This cache entry is scoped to `fields`; the gateway delivers every
         // message on the channel, so drop live pushes whose payload doesn't
@@ -52,6 +78,8 @@ function useChannelMessages(identifier, options) {
                 return;
             }
         }
+        if (rangeCacheable)
+            store.recordLive(message);
         queryClient.setQueryData(key, (current) => {
             if (!current)
                 return current;
@@ -71,14 +99,27 @@ function useChannelMessages(identifier, options) {
         queryKey: key,
         enabled: !!agentId && !!channelName,
         staleTime: Infinity,
-        initialPageParam: initialBefore,
+        initialPageParam: (anchor ?? initialBefore),
         getNextPageParam: (lastPage) => lastPage && lastPage.length > 0 ? lastPage[0]?.id : undefined,
         queryFn: async ({ pageParam }) => {
             if (!agentId || !channelName)
                 return [];
             const id = { agentId, channelName };
+            // Resolve `before` here rather than letting the API default it, so the
+            // range store records the exact bound the request proved.
+            const before = typeof pageParam === "string"
+                ? pageParam
+                : (0, snowflake_1.generateSnowflakeIdAtTime)(new Date());
+            // Mirrors the API's own default; the store needs the limit actually applied
+            const effectiveLimit = limit ?? DEFAULT_PAGE_LIMIT;
+            if (rangeCacheable) {
+                const cached = store.read(BigInt(before), effectiveLimit);
+                if (cached)
+                    return cached;
+            }
+            const requestedAt = Date.now();
             const params = {
-                ...(typeof pageParam === "string" ? { before: pageParam } : {}),
+                before,
                 ...(limit !== undefined ? { limit } : {}),
                 ...(fields && fields.length > 0 ? { field_name: fields } : {}),
                 ...(after !== undefined ? { after } : {}),
@@ -90,6 +131,14 @@ function useChannelMessages(identifier, options) {
             const page = sourcesArg
                 ? await client.messages.listMessages(id, params, sourcesArg)
                 : await client.messages.listMessages(id, params);
+            if (rangeCacheable) {
+                store.record({
+                    before: BigInt(before),
+                    limit: effectiveLimit,
+                    page: page,
+                    at: requestedAt,
+                });
+            }
             return page;
         },
     });

package/dist/test/message-range-store.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/message-range-store.test.js

@@ -0,0 +1,167 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const chai_1 = require("chai");
+const mocha_1 = require("mocha");
+const messageRangeStore_1 = require("../react/messageRangeStore");
+const snowflake_1 = require("../utils/snowflake");
+/** Frozen so a cursor built twice is the same cursor — real clocks make these flaky. */
+const NOW = Date.now();
+/** Messages at 1-minute spacing, oldest first, ending `minutesAgo` before NOW. */
+function makeMessages(count, startMinutesAgo) {
+    return Array.from({ length: count }, (_, i) => {
+        const at = new Date(NOW - (startMinutesAgo - i) * 60000);
+        return {
+            id: (0, snowflake_1.generateSnowflakeIdAtTime)(at),
+            data: { i },
+            attachments: [],
+            author_id: "a",
+            channel: { agentId: "agent", channelName: "chan" },
+            timestamp: at.getTime(),
+        };
+    });
+}
+const idAt = (minutesAgo) => BigInt((0, snowflake_1.generateSnowflakeIdAtTime)(new Date(NOW - minutesAgo * 60000)));
+const ids = (messages) => (messages ?? []).map((m) => m.id);
+(0, mocha_1.describe)("ChannelRangeStore", () => {
+    let store;
+    (0, mocha_1.beforeEach)(() => {
+        store = new messageRangeStore_1.ChannelRangeStore();
+    });
+    (0, mocha_1.it)("returns undefined for a range it has never seen", () => {
+        (0, chai_1.expect)(store.read(idAt(0), 10)).to.equal(undefined);
+    });
+    (0, mocha_1.it)("serves a full page back from cache", () => {
+        const page = makeMessages(10, 20);
+        store.record({ before: idAt(0), limit: 10, page });
+        const read = store.read(idAt(0), 10);
+        (0, chai_1.expect)(ids(read)).to.deep.equal(ids(page));
+    });
+    (0, mocha_1.it)("returns messages ascending, matching order:asc", () => {
+        const page = makeMessages(5, 20);
+        store.record({ before: idAt(0), limit: 5, page });
+        const read = store.read(idAt(0), 5);
+        for (let i = 1; i < read.length; i++) {
+            (0, chai_1.expect)(BigInt(read[i].id) > BigInt(read[i - 1].id)).to.equal(true);
+        }
+    });
+    (0, mocha_1.it)("serves the NEWEST `limit` older than the cursor, not the first", () => {
+        const page = makeMessages(10, 20); // 20..11 minutes ago
+        store.record({ before: idAt(0), limit: 10, page });
+        const read = store.read(idAt(0), 3);
+        (0, chai_1.expect)(ids(read)).to.deep.equal(ids(page.slice(7)));
+    });
+    (0, mocha_1.it)("excludes the cursor message itself (`before` is exclusive)", () => {
+        const page = makeMessages(5, 20);
+        store.record({ before: idAt(0), limit: 5, page });
+        // Only 2 messages sit below page[2], so asking for more would (rightly) be
+        // unanswerable — nothing proves what lies below the segment's `lo`.
+        const cursor = BigInt(page[2].id);
+        const read = store.read(cursor, 2);
+        (0, chai_1.expect)(read.every((m) => BigInt(m.id) < cursor)).to.equal(true);
+        (0, chai_1.expect)(ids(read)).to.deep.equal(ids(page.slice(0, 2)));
+    });
+    (0, mocha_1.it)("will not answer beyond what it has proven", () => {
+        const page = makeMessages(10, 20);
+        store.record({ before: idAt(0), limit: 10, page });
+        // Holds 10, asked for 20, and nothing says the range bottoms out here
+        (0, chai_1.expect)(store.read(idAt(0), 20)).to.equal(undefined);
+    });
+    (0, mocha_1.it)("answers short when a short page proved the range bottoms out", () => {
+        const page = makeMessages(3, 20);
+        store.record({ before: idAt(0), limit: 10, page }); // 3 < 10 => atStart
+        const read = store.read(idAt(0), 10);
+        (0, chai_1.expect)(ids(read)).to.deep.equal(ids(page));
+    });
+    (0, mocha_1.it)("will not answer a cursor above its proven upper bound", () => {
+        const page = makeMessages(10, 20);
+        store.record({ before: idAt(10), limit: 10, page });
+        // Nothing proves what sits between 10 minutes ago and now
+        (0, chai_1.expect)(store.read(idAt(0), 5)).to.equal(undefined);
+    });
+    (0, mocha_1.it)("merges touching ranges so a later read spans both", () => {
+        const older = makeMessages(10, 40); // 40..31
+        const newer = makeMessages(10, 20); // 20..11
+        store.record({ before: idAt(0), limit: 10, page: newer });
+        // Paging older: cursor is the oldest we held
+        store.record({ before: BigInt(newer[0].id), limit: 10, page: older, at: NOW });
+        (0, chai_1.expect)(store.snapshot()).to.have.length(1);
+        const read = store.read(idAt(0), 20);
+        (0, chai_1.expect)(ids(read)).to.deep.equal([...ids(older), ...ids(newer)]);
+    });
+    (0, mocha_1.it)("merges overlapping ranges without duplicating", () => {
+        const page = makeMessages(10, 20);
+        store.record({ before: idAt(0), limit: 10, page });
+        store.record({ before: idAt(0), limit: 10, page }); // same window again
+        (0, chai_1.expect)(store.snapshot()).to.have.length(1);
+        (0, chai_1.expect)(ids(store.read(idAt(0), 10))).to.deep.equal(ids(page));
+    });
+    (0, mocha_1.it)("keeps disjoint ranges apart rather than claiming the gap", () => {
+        const ancient = makeMessages(5, 500);
+        const recent = makeMessages(5, 20);
+        store.record({ before: idAt(0), limit: 5, page: recent });
+        store.record({ before: idAt(400), limit: 5, page: ancient });
+        (0, chai_1.expect)(store.snapshot()).to.have.length(2);
+        // The hole between them is not covered, so a span across it must refetch
+        (0, chai_1.expect)(store.read(idAt(0), 10)).to.equal(undefined);
+    });
+    (0, mocha_1.it)("serves an anchored read from a range fetched for a different anchor", () => {
+        const page = makeMessages(30, 60);
+        store.record({ before: idAt(0), limit: 30, page });
+        // Jumping to 30 minutes ago costs nothing: already proven
+        const read = store.read(idAt(30), 5);
+        (0, chai_1.expect)(read).to.not.equal(undefined);
+        (0, chai_1.expect)(read.every((m) => m.timestamp < Date.now() - 30 * 60000)).to.equal(true);
+    });
+    (0, mocha_1.it)("orders by numeric id, not string (500 sorts before 4000)", () => {
+        const short = { id: "500", timestamp: 1 };
+        const long = { id: "4000", timestamp: 2 };
+        store.record({ before: 5000n, limit: 10, page: [long, short], at: NOW });
+        (0, chai_1.expect)(ids(store.read(5000n, 10))).to.deep.equal(["500", "4000"]);
+    });
+    (0, mocha_1.it)("records an empty page as a proven-empty range", () => {
+        store.record({ before: idAt(0), limit: 10, page: [] });
+        (0, chai_1.expect)(store.read(idAt(0), 10)).to.deep.equal([]);
+    });
+    (0, mocha_1.describe)("live tip", () => {
+        (0, mocha_1.it)("extends coverage with pushes when proven up to now", () => {
+            const page = makeMessages(5, 20);
+            store.record({ before: idAt(0), limit: 5, page });
+            const [live] = makeMessages(1, -1); // one minute into the future
+            store.recordLive(live);
+            const read = store.read(BigInt(live.id) + 1n, 6);
+            (0, chai_1.expect)(ids(read)).to.deep.equal([...ids(page), live.id]);
+        });
+        (0, mocha_1.it)("ignores pushes for a stale window, which may not be contiguous", () => {
+            const page = makeMessages(5, 500);
+            // Proven only up to ~8 hours ago, so a push now leaves a hole
+            store.record({ before: idAt(480), limit: 5, page });
+            const [live] = makeMessages(1, 0);
+            store.recordLive(live);
+            (0, chai_1.expect)(store.read(BigInt(live.id) + 1n, 6)).to.equal(undefined);
+        });
+        (0, mocha_1.it)("stops extending once the socket drops", () => {
+            const page = makeMessages(5, 20);
+            store.record({ before: idAt(0), limit: 5, page });
+            store.sealTips(); // gateway "close"
+            const [live] = makeMessages(1, -1);
+            store.recordLive(live);
+            // The push is not trusted to prove the range, so the gap must be refetched
+            (0, chai_1.expect)(store.read(BigInt(live.id) + 1n, 6)).to.equal(undefined);
+        });
+        (0, mocha_1.it)("does not duplicate a push already fetched", () => {
+            const page = makeMessages(5, 20);
+            store.record({ before: idAt(0), limit: 5, page });
+            store.recordLive(page[4]);
+            (0, chai_1.expect)(ids(store.read(idAt(0), 5))).to.deep.equal(ids(page));
+        });
+    });
+});
+(0, mocha_1.describe)("getChannelRangeStore", () => {
+    (0, mocha_1.beforeEach)(() => (0, messageRangeStore_1.resetChannelRangeStores)());
+    (0, mocha_1.it)("shares one store per stream key", () => {
+        (0, chai_1.expect)((0, messageRangeStore_1.getChannelRangeStore)("a|c")).to.equal((0, messageRangeStore_1.getChannelRangeStore)("a|c"));
+    });
+    (0, mocha_1.it)("keeps different streams apart", () => {
+        (0, chai_1.expect)((0, messageRangeStore_1.getChannelRangeStore)("a|c")).to.not.equal((0, messageRangeStore_1.getChannelRangeStore)("a|d"));
+    });
+});

package/dist/test/react-channel-messages-range.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/react-channel-messages-range.test.js

@@ -0,0 +1,109 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const jsx_runtime_1 = require("react/jsx-runtime");
+const chai_1 = require("chai");
+const mocha_1 = require("mocha");
+const react_1 = require("@testing-library/react");
+const react_query_1 = require("@tanstack/react-query");
+const sinon_1 = __importDefault(require("sinon"));
+const doover_client_1 = require("../client/doover-client");
+const react_2 = require("../react");
+const messageRangeStore_1 = require("../react/messageRangeStore");
+const snowflake_1 = require("../utils/snowflake");
+const helpers_1 = require("./helpers");
+const AGENT = "agent-1";
+const CHANNEL = "camera_1";
+const NOW = Date.now();
+/** Newest-first, as the bare REST route returns it. */
+function messagesDesc(count, startMinutesAgo) {
+    return Array.from({ length: count }, (_, i) => {
+        const at = new Date(NOW - (startMinutesAgo + i) * 60000);
+        return {
+            id: (0, snowflake_1.generateSnowflakeIdAtTime)(at),
+            data: { i },
+            attachments: [],
+            author_id: "author",
+            channel: { agent_id: AGENT, name: CHANNEL },
+        };
+    });
+}
+function makeClient(page) {
+    const calls = [];
+    const fetchMock = sinon_1.default.stub().callsFake(async (input) => {
+        const url = typeof input === "string" ? input : input instanceof URL ? input.toString() : input.url;
+        if (url.includes("/messages")) {
+            const parsed = new URL(url);
+            calls.push({
+                before: parsed.searchParams.get("before"),
+                limit: parsed.searchParams.get("limit"),
+            });
+            return (0, helpers_1.createJsonResponse)(page);
+        }
+        return (0, helpers_1.createJsonResponse)({});
+    });
+    const client = new doover_client_1.DooverClient({
+        dataRestUrl: "https://api.example.com",
+        controlApiUrl: "https://control.example.com",
+        dataWssUrl: "wss://ws.example.com",
+        fetchImpl: fetchMock,
+        webSocketImpl: helpers_1.MockWebSocket,
+        disableBrowserLifecycleHooks: true,
+    });
+    return { client, calls };
+}
+/** One QueryClient per test, shared by both hooks, as a real app would have. */
+function wrapper(client, queryClient) {
+    return function Wrapper({ children }) {
+        return ((0, jsx_runtime_1.jsx)(react_query_1.QueryClientProvider, { client: queryClient, children: (0, jsx_runtime_1.jsx)(react_2.DooverProvider, { client: client, children: children }) }));
+    };
+}
+const newQueryClient = () => new react_query_1.QueryClient({ defaultOptions: { queries: { retry: false } } });
+(0, mocha_1.describe)("useChannelMessages range cache", () => {
+    (0, mocha_1.beforeEach)(() => {
+        (0, helpers_1.installSessionStorageMock)();
+        (0, messageRangeStore_1.resetChannelRangeStores)();
+    });
+    (0, mocha_1.afterEach)(() => {
+        sinon_1.default.restore();
+    });
+    (0, mocha_1.it)("serves an anchored window from history already fetched, without refetching", async () => {
+        const page = messagesDesc(30, 1); // 1..30 minutes ago
+        const { client, calls } = makeClient(page);
+        const qc = newQueryClient();
+        const live = (0, react_1.renderHook)(() => (0, react_2.useChannelMessages)({ agentId: AGENT, channelName: CHANNEL }, { limit: 30 }), { wrapper: wrapper(client, qc) });
+        await (0, react_1.waitFor)(() => (0, chai_1.expect)(live.result.current.messages).to.have.length(30));
+        (0, chai_1.expect)(calls).to.have.length(1);
+        // Anchor inside the range just proven — a different chain, same store
+        const anchor = (0, snowflake_1.generateSnowflakeIdAtTime)(new Date(NOW - 10 * 60000));
+        const anchored = (0, react_1.renderHook)(() => (0, react_2.useChannelMessages)({ agentId: AGENT, channelName: CHANNEL }, { limit: 5, anchor }), { wrapper: wrapper(client, qc) });
+        await (0, react_1.waitFor)(() => (0, chai_1.expect)(anchored.result.current.messages).to.have.length(5));
+        (0, chai_1.expect)(calls, "anchoring over covered history should not hit the network").to.have.length(1);
+        (0, chai_1.expect)(anchored.result.current.messages.every((m) => BigInt(m.id) < BigInt(anchor))).to.equal(true);
+    });
+    (0, mocha_1.it)("fetches when the anchor lands outside anything proven", async () => {
+        const page = messagesDesc(30, 1);
+        const { client, calls } = makeClient(page);
+        const qc = newQueryClient();
+        const live = (0, react_1.renderHook)(() => (0, react_2.useChannelMessages)({ agentId: AGENT, channelName: CHANNEL }, { limit: 30 }), { wrapper: wrapper(client, qc) });
+        await (0, react_1.waitFor)(() => (0, chai_1.expect)(live.result.current.messages).to.have.length(30));
+        // A year back is nowhere near the covered range
+        const anchor = (0, snowflake_1.generateSnowflakeIdAtTime)(new Date(NOW - 365 * 24 * 60 * 60000));
+        (0, react_1.renderHook)(() => (0, react_2.useChannelMessages)({ agentId: AGENT, channelName: CHANNEL }, { limit: 5, anchor }), { wrapper: wrapper(client, qc) });
+        await (0, react_1.waitFor)(() => (0, chai_1.expect)(calls).to.have.length(2));
+        (0, chai_1.expect)(calls[1].before).to.equal(anchor);
+    });
+    (0, mocha_1.it)("keeps the unanchored key untouched, so existing consumers are unaffected", async () => {
+        const page = messagesDesc(10, 1);
+        const { client, calls } = makeClient(page);
+        const qc = newQueryClient();
+        const first = (0, react_1.renderHook)(() => (0, react_2.useChannelMessages)({ agentId: AGENT, channelName: CHANNEL }, { limit: 10 }), { wrapper: wrapper(client, qc) });
+        await (0, react_1.waitFor)(() => (0, chai_1.expect)(first.result.current.messages).to.have.length(10));
+        // Same options => same query key => React Query serves it, no second request
+        const second = (0, react_1.renderHook)(() => (0, react_2.useChannelMessages)({ agentId: AGENT, channelName: CHANNEL }, { limit: 10 }), { wrapper: wrapper(client, qc) });
+        await (0, react_1.waitFor)(() => (0, chai_1.expect)(second.result.current.messages).to.have.length(10));
+        (0, chai_1.expect)(calls).to.have.length(1);
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "doover-js",
-  "version": "0.6.9",
+  "version": "0.7.0",
   "description": "TypeScript client for Doover.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",