@seedprotocol/sdk 0.7.8-next.1071.g2a141c1 → 0.7.8

package/dist/{tabEvents-BuorBItJ.js → changeFeed-DcsZ7deG.js}

@@ -1,5 +1,132 @@
 import debug from 'debug';
-import { am as isBrowser, I as eventEmitter, N as BaseFileManager, ah as EAS_SEED_DATA_SYNCED_TO_DB_EVENT } from './index-s73wD_LC.js';
+import { au as isBrowser, J as eventEmitter, Q as BaseFileManager, ai as EAS_SEED_DATA_SYNCED_TO_DB_EVENT, o as entityChanges } from './index-C0SetTd1.js';
+import { sql, gt, lt } from 'drizzle-orm';
+
+/**
+ * Phase timings for item creates, finds and property saves, and ready waits that timed out but
+ * were allowed to continue, under `DEBUG=seedSdk:timing`. Timing lines are `<label> <ms>ms` plus
+ * any details, so an app can report where a slow call spent its time.
+ */
+const timingLogger = debug('seedSdk:timing');
+const now = () => (typeof performance !== 'undefined' ? performance.now() : Date.now());
+/** Runs `fn` and logs how long it took (also when it throws). Costs nothing when the namespace is off. */
+async function timed(label, fn, details) {
+    if (!timingLogger.enabled)
+        return fn();
+    const start = now();
+    let failed = false;
+    try {
+        return await fn();
+    }
+    catch (error) {
+        failed = true;
+        throw error;
+    }
+    finally {
+        const extra = details?.();
+        timingLogger(`${label} ${Math.round(now() - start)}ms${failed ? ' (failed)' : ''}${extra ? ` ${extra}` : ''}`);
+    }
+}
+/**
+ * Database work counted while the namespace is on, so a timing line can say how much of its time
+ * was the SQLite worker. Statements are the ones the SDK sends through the driver; their time runs
+ * from send to result, so it includes the wait behind everything queued before them on the one
+ * worker. Live-query runs are SQLocal reactive-query results (the first run and every re-run after
+ * a write to a watched table), which go through the same worker but not through the driver.
+ */
+const dbTimingCounters = {
+    statements: 0,
+    statementMs: 0,
+    inFlight: 0,
+    liveQueryRuns: 0,
+    liveQueryFirstRuns: 0,
+    liveQueryFirstRunMs: 0,
+};
+const snapshotCounters = () => ({ ...dbTimingCounters });
+/** Wraps a driver function so each call is counted while timing is on. */
+function countDbStatements(driver) {
+    return async (...args) => {
+        if (!timingLogger.enabled)
+            return driver(...args);
+        const start = now();
+        dbTimingCounters.inFlight += 1;
+        try {
+            return await driver(...args);
+        }
+        finally {
+            dbTimingCounters.inFlight -= 1;
+            dbTimingCounters.statements += 1;
+            dbTimingCounters.statementMs += now() - start;
+        }
+    };
+}
+/** Starts the clock for one live query; call the result on each of its runs. */
+function countLiveQueryRuns() {
+    if (!timingLogger.enabled)
+        return () => { };
+    const start = now();
+    let first = true;
+    return () => {
+        dbTimingCounters.liveQueryRuns += 1;
+        if (!first)
+            return;
+        first = false;
+        dbTimingCounters.liveQueryFirstRuns += 1;
+        dbTimingCounters.liveQueryFirstRunMs += now() - start;
+    };
+}
+const describeDbDelta = (before) => {
+    const after = dbTimingCounters;
+    const statements = after.statements - before.statements;
+    const statementMs = after.statementMs - before.statementMs;
+    const liveRuns = after.liveQueryRuns - before.liveQueryRuns;
+    const firstRuns = after.liveQueryFirstRuns - before.liveQueryFirstRuns;
+    const firstMs = after.liveQueryFirstRunMs - before.liveQueryFirstRunMs;
+    const parts = [`queued ${before.inFlight}`];
+    if (statements)
+        parts.push(`${statements} stmts avg ${Math.round(statementMs / statements)}ms`);
+    if (liveRuns)
+        parts.push(`${liveRuns} live runs`);
+    if (firstRuns)
+        parts.push(`${firstRuns} new live queries, first run avg ${Math.round(firstMs / firstRuns)}ms`);
+    return `[db: ${parts.join(', ')}]`;
+};
+/**
+ * Like `timed`, and the line also says how many statements and live-query runs went through the
+ * worker meanwhile (from any caller, since they share the queue) and how many statements were
+ * already queued when it started.
+ */
+async function timedDb(label, fn, details) {
+    if (!timingLogger.enabled)
+        return fn();
+    const before = snapshotCounters();
+    return timed(label, fn, () => [details?.(), describeDbDelta(before)].filter(Boolean).join(' '));
+}
+/** Milliseconds since `start` (a `timingNow()` value), rounded. */
+const timingSince = (start) => Math.round(now() - start);
+const timingNow = now;
+/**
+ * Split timer for one multi-step call: `mark(step)` records the time since the previous mark, and
+ * `log(label)` writes one line with the total and every step. Does nothing when timing is off.
+ */
+function timingMarks() {
+    if (!timingLogger.enabled)
+        return { mark: () => { }, log: () => { } };
+    const start = now();
+    const before = snapshotCounters();
+    let last = start;
+    const steps = [];
+    return {
+        mark: (step) => {
+            const t = now();
+            steps.push(`${step} ${Math.round(t - last)}`);
+            last = t;
+        },
+        log: (label) => {
+            timingLogger(`${label} ${Math.round(now() - start)}ms: ${steps.join(', ')} ${describeDbDelta(before)}`);
+        },
+    };
+}
 
 /**
  * Cross-tab exclusive sections, using the Web Locks API. All tabs of an origin share one SQLite
@@ -101,7 +228,7 @@ function waitForTurn(previous, name, timeoutMs) {
     return Promise.race([previous, timedOut]).finally(() => clearTimeout(timer));
 }
 
-const logger$1 = debug('seedSdk:helpers:tabCoordinator');
+const logger$2 = debug('seedSdk:helpers:tabCoordinator');
 /** Identifies this tab (this page's SDK instance) in the messages it sends. */
 const TAB_ID = typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function'
     ? crypto.randomUUID()
@@ -148,7 +275,7 @@ function becomeLeader() {
     if (leader)
         return;
     leader = true;
-    logger$1(`this tab leads ${state?.dbKey}`);
+    logger$2(`this tab leads ${state?.dbKey}`);
     const waiters = leaderWaiters;
     leaderWaiters = [];
     for (const resolve of waiters)
@@ -215,7 +342,7 @@ function parseAddressesPersistedPayload(value) {
     return { owned, watched };
 }
 
-const logger = debug('seedSdk:helpers:tabEvents');
+const logger$1 = debug('seedSdk:helpers:tabEvents');
 /**
  * Keeps other tabs current (docs/MULTI_TAB.md). The event bus is per tab, so events that mean "the
  * shared database or OPFS changed" are also posted to the other tabs, which refresh their caches
@@ -303,14 +430,14 @@ function flushFilesChangedNotices() {
 /** Refreshes this tab's in-memory state for an event another tab emitted, before re-emitting it. */
 async function catchUpOn(name, payload) {
     if (name === EAS_SEED_DATA_SYNCED_TO_DB_EVENT) {
-        const _mod_0 = await import('./Item-tX3kpbj4.js');
+        const _mod_0 = await import('./Item-CjTEShfk.js');
         const _ns_0 = _mod_0.av;
         const { Item } = _ns_0;
         await Item.rehydrateCachedItemsFromDbAfterEasSync();
     }
     else if (name === LOCAL_COPIES_REMOVED_EVENT) {
         const { removedSeedLocalIds = [], removedSeedUids = [] } = (payload ?? {});
-        const _mod_1 = await import('./Item-tX3kpbj4.js');
+        const _mod_1 = await import('./Item-CjTEShfk.js');
         const _ns_1 = _mod_1.av;
         const { Item } = _ns_1;
         Item.dropCachedInstancesForSeedIds([...removedSeedLocalIds, ...removedSeedUids]);
@@ -330,7 +457,7 @@ function listenForOtherTabsEvents() {
     onTabMessage((message) => {
         if (message.type === 'event' && RELAYED_EVENTS.has(message.name)) {
             void catchUpOn(message.name, message.payload)
-                .catch((error) => logger(`catching up on ${message.name} failed`, error))
+                .catch((error) => logger$1(`catching up on ${message.name} failed`, error))
                 .then(() => {
                 if (message.payload === undefined) {
                     eventEmitter.emit(message.name);
@@ -343,7 +470,7 @@ function listenForOtherTabsEvents() {
         else if (message.type === 'files-changed') {
             // Only refreshes caches: never writes, so never sends files-changed back.
             void BaseFileManager.invalidateCachedPaths(message.paths)
-                .catch((error) => logger('refreshing changed files failed', error))
+                .catch((error) => logger$1('refreshing changed files failed', error))
                 .then(() => eventEmitter.emit(FILES_CHANGED_EVENT, message.paths));
         }
     });
@@ -362,5 +489,237 @@ var tabEvents = /*#__PURE__*/Object.freeze({
     queueFilesChangedNotice: queueFilesChangedNotice
 });
 
-export { ADDRESSES_PERSISTED_EVENT as A, FILES_CHANGED_EVENT as F, LOCAL_COPIES_REMOVED_EVENT as L, TabLockTimeoutError as T, withDbTabLock as a, withSeedDbLock as b, createSessionObjectUrl as c, postTabMessage as d, emitAcrossTabs as e, withTabLock as f, notifyFileSaved as g, TAB_ID as h, isLeaderTab as i, isSessionObjectUrl as j, tabEvents as k, listenForOtherTabsEvents as l, notifyFilesWrittenOutsideCache as n, onTabMessage as o, parseAddressesPersistedPayload as p, revokeSessionObjectUrl as r, startTabCoordination as s, tryWithTabLock as t, whenLeaderTab as w };
-//# sourceMappingURL=tabEvents-BuorBItJ.js.map
+const logger = debug('seedSdk:browser:db:changeFeed');
+/** Log rows older than this are pruned by the leader tab. */
+const ENTITY_CHANGES_RETENTION_MS = 10 * 60000;
+/** The leader prunes at most this often. */
+const ENTITY_CHANGES_PRUNE_EVERY_MS = 60000;
+const byLocalId = new Map();
+const byUid = new Map();
+const registrations = new Set();
+let feed;
+let cursor = 0;
+let reading;
+let readAgain = false;
+let lastPrunedAt = 0;
+const addTo = (map, key, registration) => {
+    let set = map.get(key);
+    if (!set)
+        map.set(key, (set = new Set()));
+    set.add(registration);
+};
+const removeFrom = (map, key, registration) => {
+    const set = map.get(key);
+    if (!set)
+        return;
+    set.delete(registration);
+    if (set.size === 0)
+        map.delete(key);
+};
+/**
+ * Calls `listener` after a committed write to one of `watch.tables` for the watched seed, matched
+ * by local id or (case-insensitively) by uid. A read of the log that has several matching rows
+ * calls it once. When the tab missed rows (its cursor is older than the oldest kept row), every
+ * listener is called once. Returns the unregister function.
+ */
+function watchEntityChanges(watch, listener) {
+    const registration = {
+        watch,
+        tables: new Set(watch.tables),
+        propertyNames: watch.propertyNames ? new Set(watch.propertyNames) : undefined,
+        listener,
+    };
+    const localId = watch.seedLocalId || undefined;
+    const uid = watch.seedUid ? watch.seedUid.toLowerCase() : undefined;
+    registrations.add(registration);
+    if (localId)
+        addTo(byLocalId, localId, registration);
+    if (uid)
+        addTo(byUid, uid, registration);
+    return () => {
+        registrations.delete(registration);
+        if (localId)
+            removeFrom(byLocalId, localId, registration);
+        if (uid)
+            removeFrom(byUid, uid, registration);
+    };
+}
+/**
+ * Watches `watch` and runs `read` once per dispatch, handing its result to `onRows` when it differs
+ * from the last one handed over. A read that finishes after a newer one started is dropped, so an
+ * older result never replaces a newer one.
+ *
+ * Pass `since` (the `changeFeedCursor()` taken before the caller's own initial read) to run `read`
+ * once right away when the feed moved on in between: a change dispatched before this watch was
+ * registered would otherwise be missed. Pass `immediate` to run it once right away regardless, as
+ * a liveQuery's first emission does.
+ */
+function watchEntityRows(watch, read, onRows, options = {}) {
+    let latest = 0;
+    let closed = false;
+    let lastJson;
+    const run = () => {
+        const token = ++latest;
+        read().then((rows) => {
+            if (closed || token !== latest)
+                return;
+            // Like BaseDb.liveQuery's distinctUntilChanged: a write that left these rows as they were
+            // (this entity's own write, read back) doesn't reach the handler again.
+            const json = JSON.stringify(rows);
+            if (json === lastJson)
+                return;
+            lastJson = json;
+            onRows(rows);
+        }, (error) => {
+            if (closed || token !== latest)
+                return;
+            if (options.onError)
+                options.onError(error);
+            else
+                logger('entity read failed', error);
+        });
+    };
+    const unregister = watchEntityChanges(watch, run);
+    if (options.immediate || (options.since !== undefined && cursor > options.since))
+        run();
+    return {
+        unsubscribe: () => {
+            closed = true;
+            unregister();
+        },
+    };
+}
+/**
+ * Runs an SQL-tag query once, the way BaseDb.liveQuery's query function is written
+ * (`(sql) => sql\`SELECT ...\``), so an entity can keep its liveQuery's text for its feed reads.
+ */
+async function queryEntityRows(query) {
+    if (!feed)
+        throw new Error('The change feed has not started');
+    return (await query(feed.sql));
+}
+/** Whether this tab's feed runs (a browser database is open); Node has none. */
+function isChangeFeedRunning() {
+    return feed !== undefined;
+}
+const callAll = (targets) => {
+    for (const registration of targets) {
+        try {
+            registration.listener();
+        }
+        catch (error) {
+            logger('listener threw', error);
+        }
+    }
+};
+const dispatch = (rows) => {
+    const targets = new Set();
+    for (const row of rows) {
+        const candidates = [
+            ...(row.seedLocalId ? byLocalId.get(row.seedLocalId) ?? [] : []),
+            ...(row.seedUid ? byUid.get(row.seedUid.toLowerCase()) ?? [] : []),
+        ];
+        for (const registration of candidates) {
+            if (!registration.tables.has(row.tbl))
+                continue;
+            if (row.tbl === 'metadata' &&
+                registration.propertyNames &&
+                row.propertyName != null &&
+                !registration.propertyNames.has(row.propertyName)) {
+                continue;
+            }
+            targets.add(registration);
+        }
+    }
+    callAll(targets);
+};
+const readNewRows = async (db) => {
+    const rows = await db
+        .select({
+        seq: entityChanges.seq,
+        tbl: entityChanges.tbl,
+        seedLocalId: entityChanges.seedLocalId,
+        seedUid: entityChanges.seedUid,
+        propertyName: entityChanges.propertyName,
+    })
+        .from(entityChanges)
+        .where(gt(entityChanges.seq, cursor))
+        .orderBy(entityChanges.seq);
+    if (feed?.db !== db || rows.length === 0)
+        return;
+    // Writers are serialized, so committed seqs have no holes: a missing first row was pruned.
+    const missed = rows[0].seq > cursor + 1;
+    cursor = rows[rows.length - 1].seq;
+    if (missed) {
+        logger(`cursor fell behind the log; notifying all ${registrations.size} watches`);
+        callAll([...registrations]);
+    }
+    else {
+        dispatch(rows);
+    }
+    await maybePrune(db);
+};
+const maybePrune = async (db) => {
+    const now = Date.now();
+    if (!isLeaderTab() || now - lastPrunedAt < ENTITY_CHANGES_PRUNE_EVERY_MS)
+        return;
+    lastPrunedAt = now;
+    try {
+        await pruneEntityChanges(db, now);
+    }
+    catch (error) {
+        logger('prune failed', error);
+    }
+};
+/** Deletes log rows older than ENTITY_CHANGES_RETENTION_MS. Deleting doesn't raise max(seq), so it dispatches nothing. */
+async function pruneEntityChanges(db, now = Date.now()) {
+    await db.delete(entityChanges).where(lt(entityChanges.at, now - ENTITY_CHANGES_RETENTION_MS));
+}
+/** Reads once at a time; an emission during a read makes it read once more. */
+const scheduleRead = (db) => {
+    if (reading) {
+        readAgain = true;
+        return;
+    }
+    reading = (async () => {
+        try {
+            do {
+                readAgain = false;
+                await readNewRows(db);
+            } while (readAgain && feed?.db === db);
+        }
+        catch (error) {
+            logger('read failed', error);
+        }
+        finally {
+            reading = undefined;
+        }
+    })();
+};
+/**
+ * Starts this tab's feed on `db` (once its migrations ran), at the newest seq allocated so far:
+ * entities do their own initial read. A second call replaces the first feed.
+ */
+async function startChangeFeed(db, { liveQuery, sql: sqlTag }) {
+    stopChangeFeed();
+    // sqlite_sequence keeps the last seq even when pruning emptied the table.
+    const [row] = await db.all(sql `SELECT seq FROM sqlite_sequence WHERE name = 'entity_changes'`);
+    cursor = Number(row?.seq ?? 0);
+    const subscription = liveQuery((tag) => tag `SELECT max(seq) AS seq FROM entity_changes`).subscribe({
+        next: ([latest]) => {
+            if (latest?.seq != null && Number(latest.seq) > cursor)
+                scheduleRead(db);
+        },
+        error: (error) => logger('feed query failed', error),
+    });
+    feed = { db, sql: sqlTag, unsubscribe: () => subscription.unsubscribe() };
+    logger(`started at seq ${cursor}`);
+}
+function stopChangeFeed() {
+    feed?.unsubscribe();
+    feed = undefined;
+    readAgain = false;
+}
+
+export { ADDRESSES_PERSISTED_EVENT as A, timed as B, revokeSessionObjectUrl as C, queryEntityRows as D, isSessionObjectUrl as E, FILES_CHANGED_EVENT as F, timedDb as G, tabEvents as H, LOCAL_COPIES_REMOVED_EVENT as L, TabLockTimeoutError as T, isLeaderTab as a, watchEntityRows as b, whenLeaderTab as c, withDbTabLock as d, emitAcrossTabs as e, createSessionObjectUrl as f, withSeedDbLock as g, countDbStatements as h, isChangeFeedRunning as i, countLiveQueryRuns as j, postTabMessage as k, listenForOtherTabsEvents as l, startTabCoordination as m, notifyFilesWrittenOutsideCache as n, onTabMessage as o, parseAddressesPersistedPayload as p, tryWithTabLock as q, withTabLock as r, startChangeFeed as s, timingMarks as t, notifyFileSaved as u, timingNow as v, watchEntityChanges as w, timingSince as x, timingLogger as y, TAB_ID as z };
+//# sourceMappingURL=changeFeed-DcsZ7deG.js.map