wenay-common2 1.0.56 → 1.0.58

package/lib/Common/ObserveAll2/reactive2.js

@@ -33,7 +33,9 @@ function reactive(root, opts = {}) {
     const { drain = 'immediate', depth = Infinity, eager = false } = opts;
     const fire = scheduler(drain);
     const eng = {
-        live: 0, pathLive: 0, dirty: new Set(), dirtyPaths: [], scheduled: false, waiters: new Set(), depth,
+        live: 0, pathLive: 0, dirty: new Set(), dirtyPaths: [],
+        dirtyPathKeys: new Set(), pathKey: createPathKeyer(),
+        scheduled: false, waiters: new Set(), depth,
         schedule() {
             if (eng.scheduled)
                 return;
@@ -44,6 +46,8 @@ function reactive(root, opts = {}) {
                 eng.dirty.clear();
                 const dirtyPaths = eng.dirtyPaths;
                 eng.dirtyPaths = [];
+                eng.dirtyPathKeys = new Set();
+                eng.pathKey = createPathKeyer();
                 let err;
                 for (const n of batch) {
                     for (const cb of [...n.subs]) {
@@ -112,7 +116,6 @@ function makeNode(target, parent, path, level, eng) {
             v = toRaw(v);
             if (Object.is(node.target[k], v))
                 return true;
-            const dirtyPath = dirtyPathFor(node, k);
             node.target[k] = v;
             if (Array.isArray(proxyTarget) && k == "length")
                 proxyTarget.length = v;
@@ -120,7 +123,7 @@ function makeNode(target, parent, path, level, eng) {
             if (kid)
                 rebind(kid, v);
             if (eng.live > 0)
-                bubble(node, dirtyPath);
+                bubble(node, k);
             return true;
         },
         defineProperty(_, k, d) {
@@ -136,7 +139,6 @@ function makeNode(target, parent, path, level, eng) {
             }
             const v = node.target[k];
             if (!Object.is(old, v)) {
-                const dirtyPath = dirtyPathFor(node, k);
                 const kid = node.kids.get(k);
                 if (kid) {
                     if (isReactiveObj(v))
@@ -148,14 +150,13 @@ function makeNode(target, parent, path, level, eng) {
                     }
                 }
                 if (eng.live > 0)
-                    bubble(node, dirtyPath);
+                    bubble(node, k);
             }
             return true;
         },
         deleteProperty(_, k) {
             if (!(k in node.target))
                 return true;
-            const dirtyPath = dirtyPathFor(node, k);
             delete node.target[k];
             const kid = node.kids.get(k);
             if (kid) {
@@ -164,7 +165,7 @@ function makeNode(target, parent, path, level, eng) {
                 detachTree(kid);
             }
             if (eng.live > 0)
-                bubble(node, dirtyPath);
+                bubble(node, k);
             return true;
         },
         has(_, k) { return k in node.target; },
@@ -191,10 +192,10 @@ function makeNode(target, parent, path, level, eng) {
     });
     return node;
 }
-function bubble(from, dirtyPath) {
+function bubble(from, key) {
     const eng = from.eng;
-    if (eng.pathLive > 0 && dirtyPath)
-        addDirtyPath(eng, dirtyPath);
+    if (eng.pathLive > 0)
+        addDirtyPath(eng, dirtyPathFor(from, key));
     for (let n = from; n && n.active; n = n.parent)
         if (n.subs.size || n.pathSubs.size)
             eng.dirty.add(n);
@@ -224,26 +225,55 @@ function markChanged(node) {
 function dirtyPathFor(node, key) {
     return Array.isArray(node.target) ? [...node.path] : [...node.path, key];
 }
-function addDirtyPath(eng, path) {
-    if (!eng.dirtyPaths.some(p => samePath(p, path)))
-        eng.dirtyPaths.push([...path]);
+function createPathKeyer() {
+    let symIds = null;
+    return function pathKey(path) {
+        let out = '';
+        for (const p of path) {
+            if (typeof p == 'symbol') {
+                symIds ??= new Map();
+                let id = symIds.get(p);
+                if (id == null) {
+                    id = symIds.size;
+                    symIds.set(p, id);
+                }
+                out += 'y' + id + '|';
+            }
+            else {
+                const s = String(p);
+                out += (typeof p)[0] + s.length + ':' + s + '|';
+            }
+        }
+        return out;
+    };
 }
-function samePath(a, b) {
-    return a.length == b.length && a.every((k, i) => Object.is(k, b[i]));
+function addDirtyPath(eng, path) {
+    const k = eng.pathKey(path);
+    if (eng.dirtyPathKeys.has(k))
+        return;
+    eng.dirtyPathKeys.add(k);
+    eng.dirtyPaths.push(path);
 }
 function startsWithPath(path, prefix) {
     return prefix.length <= path.length && prefix.every((k, i) => Object.is(k, path[i]));
 }
 function pathsForNode(node, dirtyPaths) {
     const out = [];
+    const seen = new Set();
+    const pathKey = createPathKeyer();
     for (const path of dirtyPaths) {
         let next = null;
         if (startsWithPath(path, node.path))
             next = path.slice(node.path.length);
         else if (startsWithPath(node.path, path))
             next = [];
-        if (next && !out.some(p => samePath(p, next)))
-            out.push(next);
+        if (next == null)
+            continue;
+        const k = pathKey(next);
+        if (seen.has(k))
+            continue;
+        seen.add(k);
+        out.push(next);
     }
     return out;
 }

package/lib/Common/ObserveAll2/store-replay.d.ts

@@ -1,36 +1,12 @@
 import { Store, StorePatch } from './store';
-import { ReplayListenOptions } from '../events/replay-listen';
+import { ReplayListenOptions, ReplayEvent } from '../events/replay-listen';
 import { ReplayRemote, ReplaySubscribeOpts } from '../events/replay-wire';
 import { ReplayStorage } from '../events/replay-history';
 export type StoreReplayOpts = Pick<ReplayListenOptions<[StorePatch]>, 'history' | 'getSince' | 'onJournal' | 'now'>;
 export declare function storePatchKey(patch: StorePatch): string | null;
 export declare function exposeStoreReplay<T extends object>(store: Store<T>, opts?: StoreReplayOpts): {
     api: {
-        replay: {
-            line: {
-                func: import("../..").Listener<[import("../events/replay-listen").ReplayEvent<[StorePatch]>]>;
-                isRun: () => boolean;
-                run: () => void;
-                close: () => void;
-                eventClose: (cb: () => void) => () => void;
-                onClose: (cb: () => void) => () => void;
-                removeEventClose: (cb: () => void) => void;
-                on: import("../..").ListenOn<[import("../events/replay-listen").ReplayEvent<[StorePatch]>]>;
-                off: (k: (string | symbol) | import("../..").Listener<[import("../events/replay-listen").ReplayEvent<[StorePatch]>]> | null) => void;
-                addListen: (cb: import("../..").Listener<[import("../events/replay-listen").ReplayEvent<[StorePatch]>]>, opts?: {
-                    cbClose?: () => void;
-                    key?: string | symbol;
-                }) => () => void;
-                removeListen: (k: (string | symbol) | import("../..").Listener<[import("../events/replay-listen").ReplayEvent<[StorePatch]>]> | null) => void;
-                once: (cb: import("../..").Listener<[import("../events/replay-listen").ReplayEvent<[StorePatch]>]>, opts?: {
-                    key?: string | symbol;
-                }) => () => void;
-                count: () => number;
-                readonly getAllKeys: (string | symbol)[];
-            };
-            since: (seq: number) => import("../events/replay-listen").ReplayEvent<[StorePatch]>[] | null;
-            keyframe: () => import("../events/replay-listen").ReplayEvent<[StorePatch]> | null;
-        };
+        replay: import("../events/replay-wire").ReplayExpose<[StorePatch]>;
         get(): T;
         get<M extends import("./store").StoreMask<T>>(mask: M): import("./store").StorePick<T, M>;
         set(path: import("./store").StorePath, value: any): void;
@@ -43,30 +19,34 @@ export declare function exposeStoreReplay<T extends object>(store: Store<T>, opt
     replay: {
         func: import("../..").Listener<[StorePatch]>;
         head: () => number;
-        getSince: (seq: number) => import("../events/replay-listen").ReplayEvent<[StorePatch]>[] | undefined;
+        isStale: () => boolean;
+        lastTs: () => number;
+        close: () => void;
+        getSince: (seq: number) => ReplayEvent<[StorePatch]>[] | undefined;
         line: {
-            func: import("../..").Listener<[import("../events/replay-listen").ReplayEvent<[StorePatch]>]>;
+            func: import("../..").Listener<[ReplayEvent<[StorePatch]>]>;
             isRun: () => boolean;
             run: () => void;
             close: () => void;
             eventClose: (cb: () => void) => () => void;
             onClose: (cb: () => void) => () => void;
             removeEventClose: (cb: () => void) => void;
-            on: import("../..").ListenOn<[import("../events/replay-listen").ReplayEvent<[StorePatch]>]>;
-            off: (k: (string | symbol) | import("../..").Listener<[import("../events/replay-listen").ReplayEvent<[StorePatch]>]> | null) => void;
-            addListen: (cb: import("../..").Listener<[import("../events/replay-listen").ReplayEvent<[StorePatch]>]>, opts?: {
+            on: import("../..").ListenOn<[ReplayEvent<[StorePatch]>]>;
+            off: (k: (string | symbol) | import("../..").Listener<[ReplayEvent<[StorePatch]>]> | null) => void;
+            addListen: (cb: import("../..").Listener<[ReplayEvent<[StorePatch]>]>, opts?: {
                 cbClose?: () => void;
                 key?: string | symbol;
             }) => () => void;
-            removeListen: (k: (string | symbol) | import("../..").Listener<[import("../events/replay-listen").ReplayEvent<[StorePatch]>]> | null) => void;
-            once: (cb: import("../..").Listener<[import("../events/replay-listen").ReplayEvent<[StorePatch]>]>, opts?: {
+            removeListen: (k: (string | symbol) | import("../..").Listener<[ReplayEvent<[StorePatch]>]> | null) => void;
+            once: (cb: import("../..").Listener<[ReplayEvent<[StorePatch]>]>, opts?: {
                 key?: string | symbol;
             }) => () => void;
             count: () => number;
             readonly getAllKeys: (string | symbol)[];
         };
         hasKeyframe: boolean;
-        keyframe: () => import("../events/replay-listen").ReplayEvent<[StorePatch]> | undefined;
+        keyframe: () => ReplayEvent<[StorePatch]> | undefined;
+        frame: (sinceSeq: number, hint?: unknown) => ReplayEvent<[StorePatch]>[];
         on: import("../events/replay-listen").ListenOnReplay<[StorePatch]>;
         addListen: (cb: import("../..").Listener<[StorePatch]>, opts?: {
             cbClose?: () => void;
@@ -75,7 +55,7 @@ export declare function exposeStoreReplay<T extends object>(store: Store<T>, opt
             since?: number;
             onSeq?: (seq: number) => void;
         }) => () => void;
-        removeListen: (k: import("../..").Listener<[StorePatch]> | (string | symbol) | null) => void;
+        removeListen: (k: (string | symbol) | import("../..").Listener<[StorePatch]> | null) => void;
         once: (cb: import("../..").Listener<[StorePatch]>, opts?: {
             key?: string | symbol;
             current?: import("../..").ListenCurrent<[StorePatch]> | undefined;
@@ -83,7 +63,6 @@ export declare function exposeStoreReplay<T extends object>(store: Store<T>, opt
         getAllKeys: (string | symbol)[];
         isRun: () => boolean;
         run: () => void;
-        close: () => void;
         eventClose: (cb: () => void) => () => void;
         onClose: (cb: () => void) => () => void;
         removeEventClose: (cb: () => void) => void;
@@ -95,6 +74,8 @@ export declare function exposeStoreReplay<T extends object>(store: Store<T>, opt
 export declare function syncStoreReplay<T extends object>(store: Store<T>, remote: ReplayRemote<[StorePatch]>, opts?: ReplaySubscribeOpts): (() => void) & {
     ready: Promise<void>;
     seq: () => number;
+    isStale: () => boolean;
+    lastTs: () => number;
 };
 export declare function storeReplayAt<T extends object>(storage: ReplayStorage<[StorePatch]>, at?: {
     seq?: number;

package/lib/Common/ObserveAll2/store-replay.js

@@ -21,9 +21,21 @@ function storePatchKey(patch) {
             return null;
     return JSON.stringify(patch.path);
 }
+function condensePatchTail(tail) {
+    const held = new Map();
+    for (const ev of tail) {
+        const k = storePatchKey(ev.event[0]);
+        if (k == null)
+            return tail;
+        held.delete(k);
+        held.set(k, ev);
+    }
+    return [...held.values()];
+}
 function exposeStoreReplay(store, opts = {}) {
     const [emitPatch, lineApi] = (0, replay_listen_1.UseReplayListen)({
         current: () => [{ path: [], exists: true, value: store.snapshot() }],
+        frame: condensePatchTail,
         history: opts.getSince ? undefined : (opts.history ?? 1024),
         getSince: opts.getSince,
         onJournal: opts.onJournal,

package/lib/Common/events/replay-conflate.d.ts

@@ -33,6 +33,7 @@ export declare function conflateReplay<T>(replay: ListenReplayApi<T>, opts: Conf
         };
         since: (seq: number) => ReplayEvent<NormalizeTuple<T>>[] | null;
         keyframe: () => ReplayEvent<NormalizeTuple<T>> | null;
+        frame: (seq: number, hint?: unknown) => ReplayEvent<NormalizeTuple<T>>[];
     };
     close: () => void;
     stats: () => {

package/lib/Common/events/replay-conflate.js

@@ -2,7 +2,6 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.conflateReplay = conflateReplay;
 const Listen3_1 = require("./Listen3");
-const replay_wire_1 = require("./replay-wire");
 function conflateReplay(replay, opts) {
     const { pending, highWater, lowWater = 0, pollMs = 25, keyOf, maxKeys = 1024 } = opts;
     if (!replay.hasKeyframe)
@@ -92,7 +91,12 @@ function conflateReplay(replay, opts) {
         gate.close();
     }
     return {
-        api: { ...(0, replay_wire_1.exposeReplay)(replay), line: gate },
+        api: {
+            line: gate,
+            since: (seq) => replay.getSince(seq) ?? null,
+            keyframe: () => replay.keyframe() ?? null,
+            frame: (seq, hint) => replay.frame(seq, hint),
+        },
         close,
         stats: () => ({ conflating, dropped, keyframes, coalesced, flushes }),
     };

package/lib/Common/events/replay-listen.d.ts

@@ -1,17 +1,27 @@
 import { Listener, ListenApi, ListenCurrent, ListenCurrentProvider, ListenOnBrand, ListenOptions, NormalizeTuple } from './Listen3';
 type key = string | symbol;
 type cbClose = () => void;
+export declare const IS_REPLAY_LISTEN: unique symbol;
+export declare function isReplayListen(obj: any): obj is ListenReplayApi<any>;
 export type ReplayEvent<Z extends any[] = any[]> = {
     seq: number;
     ts: number;
     event: Z;
 };
+export type StaleInfo = {
+    stale: boolean;
+    lastTs: number;
+    age: number;
+};
 export type ReplayListenOptions<Z extends any[]> = {
-    current?: ListenCurrentProvider<Z>;
+    current?: ListenCurrentProvider<Z> | 'last';
+    frame?: (tail: ReplayEvent<Z>[], hint?: unknown) => ReplayEvent<Z>[];
     history?: number;
     getSince?: (seq: number) => ReplayEvent<Z>[] | undefined;
     onJournal?: (ev: ReplayEvent<Z>) => void;
     now?: () => number;
+    staleMs?: number;
+    onStale?: (info: StaleInfo) => void;
 };
 type ReplayOnOptions<Z extends any[]> = {
     cbClose?: cbClose;
@@ -24,6 +34,9 @@ export type ListenOnReplay<Z extends any[] = any[]> = ((cb: Listener<Z>, opts?:
 export declare function withReplayListen<T>(base: ListenApi<T>, options?: ReplayListenOptions<NormalizeTuple<T>>): {
     func: Listener<NormalizeTuple<T>>;
     head: () => number;
+    isStale: () => boolean;
+    lastTs: () => number;
+    close: () => void;
     getSince: (seq: number) => ReplayEvent<NormalizeTuple<T>>[] | undefined;
     line: {
         func: Listener<[ReplayEvent<NormalizeTuple<T>>]>;
@@ -48,6 +61,7 @@ export declare function withReplayListen<T>(base: ListenApi<T>, options?: Replay
     };
     hasKeyframe: boolean;
     keyframe: () => ReplayEvent<NormalizeTuple<T>> | undefined;
+    frame: (sinceSeq: number, hint?: unknown) => ReplayEvent<NormalizeTuple<T>>[];
     on: ListenOnReplay<NormalizeTuple<T>>;
     addListen: (cb: Listener<NormalizeTuple<T>>, opts?: ReplayOnOptions<NormalizeTuple<T>>) => () => void;
     removeListen: (k: Listener<NormalizeTuple<T>> | null | key) => void;
@@ -58,7 +72,6 @@ export declare function withReplayListen<T>(base: ListenApi<T>, options?: Replay
     getAllKeys: key[];
     isRun: () => boolean;
     run: () => void;
-    close: () => void;
     eventClose: (cb: () => void) => () => void;
     onClose: (cb: () => void) => () => void;
     removeEventClose: (cb: () => void) => void;
@@ -70,6 +83,9 @@ export type ReplayListenUseOptions<T> = ListenOptions<T> & ReplayListenOptions<N
 export declare function UseReplayListen<T>(options?: ReplayListenUseOptions<T>): readonly [(...a: NormalizeTuple<T>) => void, {
     func: Listener<NormalizeTuple<T>>;
     head: () => number;
+    isStale: () => boolean;
+    lastTs: () => number;
+    close: () => void;
     getSince: (seq: number) => ReplayEvent<NormalizeTuple<T>>[] | undefined;
     line: {
         func: Listener<[ReplayEvent<NormalizeTuple<T>>]>;
@@ -94,6 +110,7 @@ export declare function UseReplayListen<T>(options?: ReplayListenUseOptions<T>):
     };
     hasKeyframe: boolean;
     keyframe: () => ReplayEvent<NormalizeTuple<T>> | undefined;
+    frame: (sinceSeq: number, hint?: unknown) => ReplayEvent<NormalizeTuple<T>>[];
     on: ListenOnReplay<NormalizeTuple<T>>;
     addListen: (cb: Listener<NormalizeTuple<T>>, opts?: ReplayOnOptions<NormalizeTuple<T>>) => () => void;
     removeListen: (k: key | Listener<NormalizeTuple<T>> | null) => void;
@@ -104,7 +121,6 @@ export declare function UseReplayListen<T>(options?: ReplayListenUseOptions<T>):
     getAllKeys: key[];
     isRun: () => boolean;
     run: () => void;
-    close: () => void;
     eventClose: (cb: () => void) => () => void;
     onClose: (cb: () => void) => () => void;
     removeEventClose: (cb: () => void) => void;

package/lib/Common/events/replay-listen.js

@@ -1,10 +1,18 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.IS_REPLAY_LISTEN = void 0;
+exports.isReplayListen = isReplayListen;
 exports.withReplayListen = withReplayListen;
 exports.UseReplayListen = UseReplayListen;
 const Listen3_1 = require("./Listen3");
+exports.IS_REPLAY_LISTEN = Symbol.for('isReplayListen');
+function isReplayListen(obj) {
+    return !!obj && typeof obj == 'object' && Object.prototype.hasOwnProperty.call(obj, exports.IS_REPLAY_LISTEN);
+}
 function withReplayListen(base, options = {}) {
-    const { current, history = 0, getSince, onJournal, now = Date.now } = options;
+    const { current: currentOpt, frame: condense, history = 0, getSince, onJournal, now = Date.now, staleMs, onStale } = options;
+    let lastEv;
+    const current = currentOpt == 'last' ? () => lastEv?.event : currentOpt;
     let head = 0;
     const ring = [];
     let emitting = null;
@@ -30,13 +38,54 @@ function withReplayListen(base, options = {}) {
             return c();
         return c ? current?.() : undefined;
     }
+    let lastTs = 0;
+    let staleFlag = false;
+    let staleTimer = null;
+    function stopStaleTimer() {
+        if (staleTimer) {
+            clearTimeout(staleTimer);
+            staleTimer = null;
+        }
+    }
+    function reportStale(stale) {
+        staleFlag = stale;
+        try {
+            onStale({ stale, lastTs, age: now() - lastTs });
+        }
+        catch (e) {
+            setTimeout(function rethrowOnStale() { throw e; }, 0);
+        }
+    }
+    function checkStale() {
+        staleTimer = null;
+        const age = now() - lastTs;
+        if (age >= staleMs)
+            reportStale(true);
+        else
+            armStaleTimer(staleMs - age);
+    }
+    function armStaleTimer(delay) {
+        if (staleTimer || !onStale || staleMs == null)
+            return;
+        staleTimer = setTimeout(checkStale, delay);
+        staleTimer.unref?.();
+    }
+    function touchStale(ts) {
+        lastTs = ts;
+        if (staleFlag)
+            reportStale(false);
+        armStaleTimer(staleMs);
+    }
     const api = {
         ...base,
         func: function emitJournaled(...e) {
             const ev = { seq: ++head, ts: now(), event: e };
             if (history > 0)
                 ring[(ev.seq - 1) % history] = ev;
+            if (currentOpt == 'last')
+                lastEv = ev;
             onJournal?.(ev);
+            touchStale(ev.ts);
             line.func(ev);
             const prev = emitting;
             emitting = ev;
@@ -48,6 +97,9 @@ function withReplayListen(base, options = {}) {
             }
         },
         head: () => head,
+        isStale: () => staleMs != null && head > 0 && now() - lastTs >= staleMs,
+        lastTs: () => lastTs,
+        close: function closeReplay() { stopStaleTimer(); base.close(); },
         getSince: journalSince,
         line,
         hasKeyframe: current != null,
@@ -55,6 +107,15 @@ function withReplayListen(base, options = {}) {
             const m = current?.();
             return m ? { seq: head, ts: now(), event: m } : undefined;
         },
+        frame: function frameSince(sinceSeq, hint) {
+            const tail = journalSince(sinceSeq);
+            if (tail)
+                return condense ? condense(tail, hint) : tail;
+            const m = current?.();
+            if (m)
+                return [{ seq: head, ts: now(), event: m }];
+            throw new Error(`replay frame(${sinceSeq}): journal evicted and no keyframe (sacred line)`);
+        },
         on: ((cb, { cbClose, key, current: cur, since, onSeq } = {}) => {
             if (since == null) {
                 const off = base.on(cb, { cbClose, key });
@@ -120,14 +181,15 @@ function withReplayListen(base, options = {}) {
         },
         get getAllKeys() { return base.getAllKeys; },
     };
+    Object.defineProperty(api, exports.IS_REPLAY_LISTEN, { value: true });
     (0, Listen3_1.registerListenOn)(api.on, api);
     return api;
 }
 function UseReplayListen(options = {}) {
-    const { current, history, getSince, onJournal, now, ...listenOptions } = options;
+    const { current, frame, history, getSince, onJournal, now, staleMs, onStale, ...listenOptions } = options;
     let t;
     const base = (0, Listen3_1.funcListenCallbackBase)((e) => { t = e; }, { fast: true, ...listenOptions });
-    const listen = withReplayListen(base, { current, history, getSince, onJournal, now });
+    const listen = withReplayListen(base, { current, frame, history, getSince, onJournal, now, staleMs, onStale });
     base.run();
     t = listen.func;
     return [t, listen];

package/lib/Common/events/replay-wire.d.ts

@@ -1,29 +1,18 @@
-import { Listener } from './Listen3';
-import { ListenReplayApi, ReplayEvent } from './replay-listen';
-export declare function exposeReplay<T>(replay: ListenReplayApi<T>): {
-    line: {
-        func: Listener<[ReplayEvent<import("./Listen3").NormalizeTuple<T>>]>;
-        isRun: () => boolean;
-        run: () => void;
-        close: () => void;
-        eventClose: (cb: () => void) => () => void;
-        onClose: (cb: () => void) => () => void;
-        removeEventClose: (cb: () => void) => void;
-        on: import("./Listen3").ListenOn<[ReplayEvent<import("./Listen3").NormalizeTuple<T>>]>;
-        off: (k: (string | symbol) | Listener<[ReplayEvent<import("./Listen3").NormalizeTuple<T>>]> | null) => void;
-        addListen: (cb: Listener<[ReplayEvent<import("./Listen3").NormalizeTuple<T>>]>, opts?: {
-            cbClose?: () => void;
-            key?: string | symbol;
-        }) => () => void;
-        removeListen: (k: (string | symbol) | Listener<[ReplayEvent<import("./Listen3").NormalizeTuple<T>>]> | null) => void;
-        once: (cb: Listener<[ReplayEvent<import("./Listen3").NormalizeTuple<T>>]>, opts?: {
-            key?: string | symbol;
-        }) => () => void;
-        count: () => number;
-        readonly getAllKeys: (string | symbol)[];
-    };
-    since: (seq: number) => ReplayEvent<import("./Listen3").NormalizeTuple<T>>[] | null;
-    keyframe: () => ReplayEvent<import("./Listen3").NormalizeTuple<T>> | null;
+import { Listener, NormalizeTuple } from './Listen3';
+import { ListenReplayApi, ReplayEvent, StaleInfo } from './replay-listen';
+import { conflateReplay, ConflateOpts } from './replay-conflate';
+export type ReplayExpose<T> = {
+    line: ListenReplayApi<T>['line'];
+    since: (seq: number) => ReplayEvent<NormalizeTuple<T>>[] | null;
+    keyframe: () => ReplayEvent<NormalizeTuple<T>> | null;
+    frame: ListenReplayApi<T>['frame'];
+};
+export declare function exposeReplay<T>(replay: ListenReplayApi<T>): ReplayExpose<T>;
+export declare function exposeReplay<T>(replay: ListenReplayApi<T>, opts: {
+    conflate: ConflateOpts<NormalizeTuple<T>>;
+}): ReplayExpose<T> & {
+    close: () => void;
+    stats: ReturnType<typeof conflateReplay<T>>['stats'];
 };
 export type ReplayRemote<Z extends any[] = any[]> = {
     line: {
@@ -31,13 +20,25 @@ export type ReplayRemote<Z extends any[] = any[]> = {
     };
     since: (seq: number) => Promise<ReplayEvent<Z>[] | null | undefined> | ReplayEvent<Z>[] | null | undefined;
     keyframe: () => Promise<ReplayEvent<Z> | null | undefined> | ReplayEvent<Z> | null | undefined;
+    frame?: (seq: number, hint?: unknown) => Promise<ReplayEvent<Z>[] | null | undefined> | ReplayEvent<Z>[] | null | undefined;
+    frameLine?: {
+        on: (cb: (ev: ReplayEvent<Z>) => void) => any;
+    };
 };
 export type ReplaySubscribeOpts = {
     since?: number;
     onSeq?: (seq: number) => void;
     onError?: (e: any) => void;
+    staleMs?: number;
+    onStale?: (info: StaleInfo) => void;
+    skewMs?: number;
+    now?: () => number;
+    policy?: 'queue' | 'frame';
+    hint?: unknown;
 };
 export declare function replaySubscribe<Z extends any[]>(remote: ReplayRemote<Z>, cb: Listener<Z>, opts?: ReplaySubscribeOpts): (() => void) & {
     ready: Promise<void>;
     seq: () => number;
+    isStale: () => boolean;
+    lastTs: () => number;
 };

package/lib/Common/events/replay-wire.js

@@ -2,13 +2,21 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.exposeReplay = exposeReplay;
 exports.replaySubscribe = replaySubscribe;
-function exposeReplay(replay) {
+const replay_conflate_1 = require("./replay-conflate");
+function exposeReplayPlain(replay) {
     return {
         line: replay.line,
         since: (seq) => replay.getSince(seq) ?? null,
         keyframe: () => replay.keyframe() ?? null,
+        frame: (seq, hint) => replay.frame(seq, hint),
     };
 }
+function exposeReplay(replay, opts) {
+    if (!opts?.conflate)
+        return exposeReplayPlain(replay);
+    const gated = (0, replay_conflate_1.conflateReplay)(replay, opts.conflate);
+    return { ...gated.api, close: gated.close, stats: gated.stats };
+}
 function unsubscribeHandle(handle) {
     if (typeof handle == 'function') {
         handle();
@@ -20,19 +28,87 @@ function unsubscribeHandle(handle) {
         handle.unsubscribe();
 }
 function replaySubscribe(remote, cb, opts = {}) {
-    const { since = -1, onSeq, onError } = opts;
+    const { since = -1, onSeq, onError, staleMs, onStale, skewMs = 0, now = Date.now, policy = 'queue', hint } = opts;
     let lastDelivered = since;
     let replaying = true;
     let closed = false;
     const queue = [];
+    let lastTs = 0;
+    let lastArrival = now();
+    let staleFlag = false;
+    let staleTimer = null;
+    function stopStaleTimer() {
+        if (staleTimer) {
+            clearTimeout(staleTimer);
+            staleTimer = null;
+        }
+    }
+    function reportStale(stale) {
+        staleFlag = stale;
+        if (!onStale)
+            return;
+        try {
+            onStale({ stale, lastTs, age: now() - (lastTs || lastArrival) });
+        }
+        catch (e) {
+            setTimeout(function rethrowOnStale() { throw e; }, 0);
+        }
+    }
+    function checkArrivalGap() {
+        staleTimer = null;
+        if (closed)
+            return;
+        const gap = now() - lastArrival;
+        if (gap >= staleMs) {
+            if (!staleFlag)
+                reportStale(true);
+        }
+        else
+            armStaleTimer(staleMs - gap);
+    }
+    function armStaleTimer(delay) {
+        if (staleTimer || !onStale || staleMs == null || closed)
+            return;
+        staleTimer = setTimeout(checkArrivalGap, delay);
+        staleTimer.unref?.();
+    }
+    function assessStale() {
+        if (staleMs == null || closed)
+            return;
+        const tsStale = lastTs > 0 && now() - lastTs > staleMs + skewMs;
+        if (tsStale != staleFlag)
+            reportStale(tsStale);
+        if (tsStale)
+            stopStaleTimer();
+        else
+            armStaleTimer(staleMs);
+    }
+    armStaleTimer(staleMs);
     function deliver(ev) {
         if (closed || ev.seq <= lastDelivered)
             return;
         lastDelivered = ev.seq;
+        lastTs = ev.ts;
+        lastArrival = now();
         cb(...ev.event);
         onSeq?.(ev.seq);
+        if (!replaying)
+            assessStale();
     }
-    const handle = remote.line.on(function liveTap(ev) {
+    const liveLine = policy == 'frame' && remote.frameLine ? remote.frameLine : remote.line;
+    const handle = liveLine.on(function liveTap(ev) {
+        if (ev == null || typeof ev.seq != 'number') {
+            if (closed)
+                return;
+            const err = new Error('replaySubscribe: line ended by server (' + String(ev) + ')');
+            off();
+            if (onError)
+                onError(err);
+            else
+                setTimeout(function rethrowLineEnd() { throw err; }, 0);
+            return;
+        }
+        lastArrival = now();
         if (replaying)
             queue.push(ev);
         else
@@ -40,21 +116,39 @@ function replaySubscribe(remote, cb, opts = {}) {
     });
     async function catchUp() {
         try {
-            const tail = since >= 0 ? await remote.since(since) : null;
-            if (closed)
-                return;
-            if (tail) {
-                for (const ev of tail)
-                    deliver(ev);
+            let done = false;
+            if (since >= 0 && remote.frame) {
+                const envs = await remote.frame(since, hint);
+                if (closed)
+                    return;
+                if (envs) {
+                    if (envs.length) {
+                        lastDelivered = envs[0].seq - 1;
+                        for (const ev of envs)
+                            deliver(ev);
+                    }
+                    done = true;
+                }
             }
-            else {
-                const kf = await remote.keyframe();
+            if (!done) {
+                const tail = since >= 0 ? await remote.since(since) : null;
                 if (closed)
                     return;
-                if (kf) {
-                    lastDelivered = kf.seq;
-                    cb(...kf.event);
-                    onSeq?.(kf.seq);
+                if (tail) {
+                    for (const ev of tail)
+                        deliver(ev);
+                }
+                else {
+                    const kf = await remote.keyframe();
+                    if (closed)
+                        return;
+                    if (kf) {
+                        lastDelivered = kf.seq;
+                        lastTs = kf.ts;
+                        lastArrival = now();
+                        cb(...kf.event);
+                        onSeq?.(kf.seq);
+                    }
                 }
             }
         }
@@ -68,6 +162,7 @@ function replaySubscribe(remote, cb, opts = {}) {
             while (queue.length)
                 deliver(queue.shift());
             replaying = false;
+            assessStale();
         }
     }
     const ready = catchUp();
@@ -75,10 +170,13 @@ function replaySubscribe(remote, cb, opts = {}) {
         if (closed)
             return;
         closed = true;
+        stopStaleTimer();
         unsubscribeHandle(handle);
     }
     return Object.assign(off, {
         ready,
         seq: () => lastDelivered,
+        isStale: () => staleFlag || (staleMs != null && now() - lastArrival >= staleMs),
+        lastTs: () => lastTs,
     });
 }

package/lib/Common/rcp/listen-deep.d.ts

@@ -1,4 +1,5 @@
 import { type ListenOn } from "../events/Listen";
+import type { ReplayEvent } from "../events/replay-listen";
 import { listenSocket, listenSocketFirst, listenSocketAll, listenSocketSmart, type tSubHandle } from "./listen-socket";
 type WithSubHandle<R> = R extends {
     callback: (...a: infer A) => any;
@@ -11,8 +12,21 @@ type Obj = Record<string, any>;
 type InferArgs<T> = T extends {
     addListen: (cb: (...args: infer R) => void, ...rest: any[]) => any;
 } ? R : never;
+export type ReplaySocketListen<Z extends any[]> = WithSubHandle<ReturnType<typeof listenSocket<Z>>> & {
+    line: WithSubHandle<ReturnType<typeof listenSocket<[ReplayEvent<Z>]>>>;
+    frameLine: WithSubHandle<ReturnType<typeof listenSocket<[ReplayEvent<Z>]>>>;
+    since: (seq: number) => Promise<ReplayEvent<Z>[] | null>;
+    keyframe: () => Promise<ReplayEvent<Z> | null>;
+    frame: (seq: number, hint?: unknown) => Promise<ReplayEvent<Z>[]>;
+};
+type IsReplayMember<V> = V extends {
+    addListen: Function;
+    getSince: Function;
+    keyframe: Function;
+    line: object;
+} ? true : false;
 export type DeepSocketListen<T> = {
-    [K in keyof T]: T[K] extends {
+    [K in keyof T]: IsReplayMember<T[K]> extends true ? ReplaySocketListen<InferArgs<T[K]>> : T[K] extends {
         addListen: Function;
     } ? WithSubHandle<ReturnType<typeof listenSocket<InferArgs<T[K]>>>> : T[K] extends ListenOn<infer Z> ? WithSubHandle<ReturnType<typeof listenSocket<Z>>> : T[K] extends (...a: any[]) => any ? T[K] : T[K] extends Promise<any> ? T[K] : T[K] extends typeof Promise ? T[K] : T[K] extends object ? DeepSocketListen<T[K]> : T[K];
 };
@@ -27,7 +41,7 @@ export type DeepSocketListenAll<T> = {
     } ? ReturnType<typeof listenSocketAll<InferArgs<T[K]>>> : T[K] extends ListenOn<infer Z> ? ReturnType<typeof listenSocketAll<Z>> : T[K] extends (...a: any[]) => any ? T[K] : T[K] extends Promise<any> ? T[K] : T[K] extends typeof Promise ? T[K] : T[K] extends object ? DeepSocketListenAll<T[K]> : T[K];
 };
 export type DeepSocketListenSmart<T> = {
-    [K in keyof T]: NonNullable<T[K]> extends {
+    [K in keyof T]: IsReplayMember<NonNullable<T[K]>> extends true ? ReplaySocketListen<InferArgs<NonNullable<T[K]>>> | Extract<T[K], undefined | null> : NonNullable<T[K]> extends {
         addListen: Function;
     } ? ReturnType<typeof listenSocketSmart<InferArgs<NonNullable<T[K]>>>> | Extract<T[K], undefined | null> : NonNullable<T[K]> extends ListenOn<infer Z> ? ReturnType<typeof listenSocketSmart<Z>> : NonNullable<T[K]> extends (...a: any[]) => any ? T[K] : NonNullable<T[K]> extends Promise<any> ? T[K] : NonNullable<T[K]> extends typeof Promise ? T[K] : NonNullable<T[K]> extends object ? DeepSocketListenSmart<T[K]> : T[K];
 };

package/lib/Common/rcp/rpc-client.d.ts

@@ -3,7 +3,9 @@ import { type RpcLimits } from "./rpc-limits";
 import { makeOff } from "./rpc-off";
 import { type RpcOpt } from "./rpc-caps";
 type UnwrapPromise<T> = T extends Promise<infer R> ? R : T;
-export type DeepDataOnly<T> = T extends Function ? never : T extends Array<infer U> ? Array<DeepDataOnly<U>> : T extends object ? {
+export type DeepDataOnly<T> = T extends Function ? never : T extends readonly any[] ? {
+    [I in keyof T]: DeepDataOnly<T[I]>;
+} : T extends object ? {
     [K in keyof T as T[K] extends Function ? never : K]: DeepDataOnly<T[K]>;
 } : T;
 export type ClientAPIAll<T> = {

package/lib/Common/rcp/rpc-server-auto.d.ts

@@ -3,7 +3,13 @@ import { type PromiseServerHooks, type RpcLimits, type RpcServerAuth, type RpcOp
 import { DeepSocketListen } from "./listen-deep";
 import { SocketTmpl } from "./rpc-protocol";
 type ListenCallbackBase<T extends any[] = any[]> = ReturnType<typeof funcListenCallbackBase<T>>;
-export declare function createRpcServerAuto<T extends object>({ socket, object: target, socketKey: key, debug, hooks, disconnectListen, limits, auth, maxPerListen, throttle, opt }: {
+export type RpcReplayOpts = {
+    pending?: () => number;
+    highWater?: number;
+    lowWater?: number;
+    pollMs?: number;
+};
+export declare function createRpcServerAuto<T extends object>({ socket, object: target, socketKey: key, debug, hooks, disconnectListen, limits, auth, maxPerListen, throttle, opt, replay, replayOpts }: {
     socket: SocketTmpl;
     object: T;
     socketKey: string;
@@ -15,6 +21,8 @@ export declare function createRpcServerAuto<T extends object>({ socket, object:
     maxPerListen?: number;
     throttle?: number;
     opt?: RpcOpt;
+    replay?: false | "auto" | "force";
+    replayOpts?: RpcReplayOpts;
 }): {
     api: {
         subscriptions: () => {

package/lib/Common/rcp/rpc-server-auto.js

@@ -2,10 +2,11 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createRpcServerAuto = createRpcServerAuto;
 const Listen_1 = require("../events/Listen");
+const replay_listen_1 = require("../events/replay-listen");
 const listen_socket_1 = require("./listen-socket");
 const rpc_server_1 = require("./rpc-server");
 const rpc_protocol_1 = require("./rpc-protocol");
-function createRpcServerAuto({ socket, object: target, socketKey: key, debug, hooks, disconnectListen, limits, auth, maxPerListen, throttle, opt }) {
+function createRpcServerAuto({ socket, object: target, socketKey: key, debug, hooks, disconnectListen, limits, auth, maxPerListen, throttle, opt, replay = "auto", replayOpts }) {
     const cache = new WeakMap();
     const registry = new Map();
     function unsubscribeAllActive() {
@@ -15,7 +16,8 @@ function createRpcServerAuto({ socket, object: target, socketKey: key, debug, ho
         }
         registry.clear();
     }
-    function getListenSocket(parent, disconnectListen) {
+    function getListenSocket(parent, disconnectListen, nodeOpt) {
+        const nodeThrottle = nodeOpt ? nodeOpt.throttle : throttle;
         let result = cache.get(parent);
         if (!result) {
             const subs = new Map();
@@ -27,7 +29,7 @@ function createRpcServerAuto({ socket, object: target, socketKey: key, debug, ho
                 if (!registry.has(parent))
                     registry.set(parent, { subs });
                 subs.get(z)?.off();
-                const w = (0, listen_socket_1.listenSocket)(parent, { addListenClose: disconnectListen, throttle });
+                const w = (0, listen_socket_1.listenSocket)(parent, { addListenClose: disconnectListen, throttle: nodeThrottle });
                 subs.set(z, w);
                 const done = w.on(z);
                 done.then(() => {
@@ -46,7 +48,7 @@ function createRpcServerAuto({ socket, object: target, socketKey: key, debug, ho
                 if (!registry.has(parent))
                     registry.set(parent, { subs });
                 subs.get(z)?.off();
-                const w = (0, listen_socket_1.listenSocket)(parent, { addListenClose: disconnectListen, throttle });
+                const w = (0, listen_socket_1.listenSocket)(parent, { addListenClose: disconnectListen, throttle: nodeThrottle });
                 let fired = false;
                 const oneShot = (...a) => {
                     if (fired)
@@ -79,6 +81,137 @@ function createRpcServerAuto({ socket, object: target, socketKey: key, debug, ho
         }
         return result;
     }
+    function isReplayNode(obj) {
+        if (replay == false || obj == null || typeof obj != "object")
+            return false;
+        if (Object.prototype.hasOwnProperty.call(obj, replay_listen_1.IS_REPLAY_LISTEN))
+            return true;
+        return replay == "force"
+            && (0, Listen_1.isListenCallback)(obj)
+            && typeof obj.getSince == "function"
+            && typeof obj.keyframe == "function"
+            && !!obj.line && typeof obj.line == "object";
+    }
+    function lineFrame(parent, seq, hint) {
+        if (typeof parent.frame == "function")
+            return parent.frame(seq, hint);
+        const tail = parent.getSince(seq);
+        if (tail)
+            return tail;
+        const kf = parent.keyframe();
+        if (kf)
+            return [kf];
+        throw new Error(`replay frame(${seq}): journal evicted and no keyframe (sacred line)`);
+    }
+    const gateClosers = new Set();
+    function closeAllGates() { for (const c of [...gateClosers])
+        c(); }
+    let gatesHooked = false;
+    function hookGateTeardown() {
+        if (gatesHooked || !disconnectListen)
+            return;
+        gatesHooked = true;
+        const dl = disconnectListen;
+        if (typeof dl.on == "function")
+            dl.on(closeAllGates);
+        else
+            dl.addListen(closeAllGates);
+    }
+    function gatedLineNode(parent) {
+        const { pending: pendingOpt, highWater = Infinity, lowWater = 0, pollMs = 25 } = replayOpts ?? {};
+        const pending = pendingOpt ?? (() => socket?.conn?.writeBuffer?.length ?? 0);
+        const out = (0, Listen_1.funcListenCallbackBase)(() => { });
+        out.run();
+        let lastSent = typeof parent.head == "function" ? parent.head() : 0;
+        let gated = false;
+        let closed = false;
+        let timer = null;
+        function stopPoll() { if (timer) {
+            clearInterval(timer);
+            timer = null;
+        } }
+        function startPoll() {
+            if (timer || closed)
+                return;
+            timer = setInterval(recoverIfDrained, pollMs);
+            timer.unref?.();
+        }
+        function close() {
+            if (closed)
+                return;
+            closed = true;
+            stopPoll();
+            offLine();
+            gateClosers.delete(close);
+        }
+        function fail(e) {
+            if (debug)
+                console.error("[rpc replay gate] frame recovery failed:", e);
+            const emitStop = !closed;
+            close();
+            if (emitStop)
+                out.func(rpc_protocol_1.RPC_STOP);
+            out.close?.();
+        }
+        function recoverIfDrained() {
+            if (!gated || closed)
+                return;
+            if (pending() > lowWater)
+                return;
+            gated = false;
+            stopPoll();
+            let envs;
+            try {
+                envs = lineFrame(parent, lastSent);
+            }
+            catch (e) {
+                fail(e);
+                return;
+            }
+            for (const ev of envs) {
+                if (ev.seq > lastSent)
+                    lastSent = ev.seq;
+                out.func(ev);
+            }
+        }
+        const offLine = parent.line.on(function gateForward(ev) {
+            if (closed)
+                return;
+            if (!gated && pending() > highWater) {
+                gated = true;
+                startPoll();
+            }
+            if (gated) {
+                recoverIfDrained();
+                return;
+            }
+            lastSent = ev.seq;
+            out.func(ev);
+        });
+        gateClosers.add(close);
+        hookGateTeardown();
+        return getListenSocket(out, disconnectListen, { throttle: undefined });
+    }
+    const replayCache = new WeakMap();
+    function getReplayExpose(parent) {
+        let node = replayCache.get(parent);
+        if (node)
+            return node;
+        const legacy = getListenSocket(parent, disconnectListen);
+        const lineNode = getListenSocket(parent.line, disconnectListen, { throttle: undefined });
+        const frameLineNode = replayOpts?.highWater != null ? gatedLineNode(parent) : lineNode;
+        node = {
+            ...legacy,
+            line: lineNode,
+            frameLine: frameLineNode,
+            since: (seq) => parent.getSince(seq) ?? null,
+            keyframe: () => parent.keyframe() ?? null,
+            frame: (seq, hint) => lineFrame(parent, seq, hint),
+        };
+        node[rpc_protocol_1.IS_RPC_LISTEN] = true;
+        replayCache.set(parent, node);
+        return node;
+    }
     const api = {
         subscriptions: () => Array.from(registry, ([parent, e], i) => ({
             key: parent?.constructor?.name ? `${parent.constructor.name}#${i}` : `listen#${i}`,
@@ -89,12 +222,16 @@ function createRpcServerAuto({ socket, object: target, socketKey: key, debug, ho
         socket, object: target, socketKey: key, debug, limits, auth, opt,
         hooks: {
             ...hooks,
-            onDispose: () => { unsubscribeAllActive(); hooks?.onDispose?.(); },
+            onDispose: () => { closeAllGates(); unsubscribeAllActive(); hooks?.onDispose?.(); },
             resolveTransform: (obj) => {
+                if (isReplayNode(obj))
+                    return getReplayExpose(obj);
                 if ((0, Listen_1.isListenCallback)(obj))
                     return getListenSocket(obj, disconnectListen);
-                if ((0, Listen_1.isListenOn)(obj))
-                    return getListenSocket((0, Listen_1.getListenByOn)(obj), disconnectListen);
+                if ((0, Listen_1.isListenOn)(obj)) {
+                    const byOn = (0, Listen_1.getListenByOn)(obj);
+                    return isReplayNode(byOn) ? getReplayExpose(byOn) : getListenSocket(byOn, disconnectListen);
+                }
                 return obj;
             },
         },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wenay-common2",
-  "version": "1.0.56",
+  "version": "1.0.58",
   "description": "Common library",
   "strict": true,
   "main": "lib/index.js",