@cccteam/resource-firestore 0.0.1

package/README.md

@@ -0,0 +1,99 @@
+# @cccteam/resource-firestore
+
+The Firestore change feed for live pages over [`@cccteam/resource`](../resource/README.md).
+A page that asks for a live list or a live row stays current without polling: the server
+writes one change document per subscribed user into that user's change set, and this feed
+is the one listener per tab that reads it and hands each change to the client's live
+session, which refetches the row or list the change names. It is the only package of the
+three that depends on the firebase JS SDK; the client stays free of it.
+
+What a page opts into, what it costs, and what it never does are in the client's README
+under "Live pages". This package adds nothing to that contract; it is one way of delivering
+the changes, and the client is written so another could replace it.
+
+```bash
+npm install @cccteam/resource @cccteam/resource-firestore firebase
+```
+
+`firebase` is a peer dependency: the application installs it once, so one copy of the SDK
+serves the feed and anything else the application does with Firebase.
+
+## Use
+
+Build the feed and hand it to the client's live session once the session is authenticated;
+stop the session at logout, before the session itself is logged out.
+
+```ts
+import { firestoreChangeFeed } from '@cccteam/resource-firestore';
+
+const api = createApi({ baseUrl: '/api' });
+await api.live.start(firestoreChangeFeed());
+// ...
+await api.live.stop();
+```
+
+An Angular application provides it instead, and `AuthService` starts and stops it:
+
+```ts
+import { CHANGE_FEED } from '@cccteam/resource-angular/types';
+import { firestoreChangeFeed } from '@cccteam/resource-firestore';
+
+providers: [{ provide: CHANGE_FEED, useFactory: () => firestoreChangeFeed() }];
+```
+
+## What the feed does
+
+`start(identity)` receives what the server minted for the session's principal at
+`GET <prefix>/live/token`: the GCP project, the Firestore database, and either the emulator
+or a custom token. It initializes a Firebase app of its own for the project (and the web API
+key, in production), opens the database, and connects as the user: against the emulator,
+with the SDK's mock user token for the uid (`connectFirestoreEmulator(db, host, port,
+{ mockUserToken: { sub: uid, user_id: uid } })`); in production, by signing the custom token
+in through Firebase Auth. Then it listens to `users/{uid}/changes`, ordered by `at` and, once
+a change has been seen, bounded to the ones after it.
+
+The first snapshot of a listener primes the last change seen and emits nothing. At start, the
+documents already there predate the page's own first fetch; after an error, the resync the
+recovery emits already refetches everything. Each later document becomes one `ChangeEvent`:
+its `kind` (`row`, `list`, or `resource`), `resource`, `key`, `domain`, and `deleted` as the
+document carries them, and `at` as unix microseconds in decimal, the version the refetch
+carries. A document rewritten within its second (the server coalesces writes to one target
+per second) moves forward and is one more event; a document expiring out of the result set
+is not.
+
+A quiet stretch is not evidence that anything was missed: the listener keeps its connection
+and resumes after a drop, and the change documents live ten minutes, so a change is lost only
+when the listener was down or suspended for longer than that. The feed therefore emits
+`resync` on two occasions and no other. When a listener reports an error it delivers nothing
+more, so the feed starts another after a wait that doubles with each failure (one second, up
+to thirty), bounded by the last change seen, and the first snapshot of that listener is a
+resync. And when the page becomes visible again (`visibilitychange` to visible, or `pageshow`
+from the back-forward cache) after having been hidden longer than the change documents live,
+since browsers throttle or drop a background page's connection, the feed emits a resync. The
+live session refetches every live row and list by a fresh seed either way, and does the same
+itself when it starts.
+
+`stop()` releases the listener and deletes the app it initialized. Nothing is remembered
+across a stop: a later start listens from the beginning again.
+
+The security rules the server leg ships let a user read their own change set and nothing
+else, and let no client write; the feed never writes.
+
+## What is configurable
+
+`firestoreChangeFeed(options)` takes `resyncAfterHidden` (how long a page may be hidden before
+its return is a resync; the change document's life by default), `retryDelay` and
+`maxRetryDelay` (the restart wait), `now` (the clock), and `visibility` and `page` (where the
+document's visibility and the page's hide and show are heard; the document and the window by
+default). Every one has a default, and a spec is the usual reason to turn one.
+
+## Testing
+
+The specs are written against `bun:test` and run with `bun test projects/resource-firestore/`
+(the trailing slash keeps bun off the Angular library beside it); `bun run typecheck:firestore`
+compiles them with tsc over `projects/resource-firestore/tsconfig.spec.json`.
+`bun run test:firestore` runs both. The specs replace the three SDK modules (`firebase/app`,
+`firebase/auth`, `firebase/firestore`) with recording stand-ins through `mock.module`, drive
+the listener's snapshots and errors by hand, stand in for the document and the window to hide
+and show the page, and read the events and resyncs back; no Firestore, emulated or real, is
+involved.

package/fesm2022/cccteam-resource-firestore.mjs

@@ -0,0 +1,307 @@
+import { liveChangeTtl } from '@cccteam/resource';
+import { initializeApp, deleteApp } from 'firebase/app';
+import { signInWithCustomToken, getAuth } from 'firebase/auth';
+import { getFirestore, connectFirestoreEmulator, collection, query, where, orderBy, onSnapshot } from 'firebase/firestore';
+
+let instances = 0;
+/**
+ * The Firestore change feed: one listener per tab over the user's change set,
+ * `users/{uid}/changes`, ordered by `at` and bounded below by the last change seen. It
+ * connects with the identity the server minted (`GET <prefix>/live/token`): the project,
+ * the database, and either the emulator with a mock user token for the uid, or a custom
+ * token signed in through Firebase Auth. Each document becomes one ChangeEvent with `at`
+ * as unix microseconds.
+ *
+ * The first snapshot of a listener primes the last change seen and emits nothing: at
+ * start the backlog predates the page's own first fetch, and after an error the
+ * `resync` the recovery emits already refetches everything. The listener keeps its
+ * connection and resumes after a drop, so a quiet stretch is not evidence of anything
+ * missed; a change is lost only when the listener was down or suspended longer than the
+ * change documents live. So the feed emits `resync` in two cases and no other: a failed
+ * listener (which delivers nothing more) is started again with a growing wait and its
+ * first snapshot is a resync, and a page that becomes visible again after being hidden
+ * longer than the change document's life is a resync, since browsers throttle or drop a
+ * background page's connection. The live session's own start refetches everything too.
+ */
+class FirestoreChangeFeed {
+    resyncAfterHidden;
+    retryDelay;
+    maxRetryDelay;
+    now;
+    visibility;
+    page;
+    changeListeners = new Set();
+    resyncListeners = new Set();
+    app;
+    db;
+    uid = '';
+    unsubscribe;
+    retry;
+    failures = 0;
+    lastSeen;
+    /**
+     * The ids of the documents already delivered (or primed) at the `lastSeen` instant,
+     * replaced whenever it advances. One commit writes its row and list documents with one
+     * server timestamp, and a listener may deliver them in two snapshots, so a document at
+     * the last instant seen is new unless its id is here.
+     */
+    seenAtLastSeen = new Set();
+    /** When the page went hidden, while it is; undefined while visible. */
+    hiddenSince;
+    onVisibilityChange = () => {
+        if (this.visibility?.visibilityState === 'hidden') {
+            this.hidden();
+            return;
+        }
+        this.visible();
+    };
+    onPageHide = () => this.hidden();
+    onPageShow = (event) => {
+        if (event.persisted) {
+            this.visible();
+        }
+    };
+    constructor(options = {}) {
+        this.resyncAfterHidden = options.resyncAfterHidden ?? liveChangeTtl;
+        this.retryDelay = options.retryDelay ?? 1_000;
+        this.maxRetryDelay = options.maxRetryDelay ?? 30_000;
+        this.now = options.now ?? Date.now;
+        this.visibility = options.visibility ?? (typeof document === 'undefined' ? undefined : document);
+        this.page = options.page ?? (typeof window === 'undefined' ? undefined : window);
+    }
+    /** Whether a listener is held: the feed is between start and stop. */
+    get started() {
+        return this.app !== undefined;
+    }
+    async start(identity) {
+        if (this.app) {
+            await this.stop();
+        }
+        const app = initializeApp({ projectId: identity.project, apiKey: identity.apiKey || undefined }, `cccteam-resource-live-${++instances}`);
+        const db = identity.database ? getFirestore(app, identity.database) : getFirestore(app);
+        if (identity.emulator) {
+            const { host, port } = hostAndPort(identity.emulator);
+            connectFirestoreEmulator(db, host, port, { mockUserToken: { sub: identity.uid, user_id: identity.uid } });
+        }
+        else {
+            await signInWithCustomToken(getAuth(app), identity.token);
+        }
+        this.app = app;
+        this.db = db;
+        this.uid = identity.uid;
+        this.lastSeen = undefined;
+        this.seenAtLastSeen = new Set();
+        this.failures = 0;
+        this.hiddenSince = this.visibility?.visibilityState === 'hidden' ? this.now() : undefined;
+        this.visibility?.addEventListener('visibilitychange', this.onVisibilityChange);
+        this.page?.addEventListener('pagehide', this.onPageHide);
+        this.page?.addEventListener('pageshow', this.onPageShow);
+        this.listen(false);
+    }
+    async stop() {
+        if (this.retry !== undefined) {
+            clearTimeout(this.retry);
+            this.retry = undefined;
+        }
+        this.visibility?.removeEventListener('visibilitychange', this.onVisibilityChange);
+        this.page?.removeEventListener('pagehide', this.onPageHide);
+        this.page?.removeEventListener('pageshow', this.onPageShow);
+        this.hiddenSince = undefined;
+        this.unsubscribe?.();
+        this.unsubscribe = undefined;
+        const app = this.app;
+        this.app = undefined;
+        this.db = undefined;
+        this.uid = '';
+        this.lastSeen = undefined;
+        this.seenAtLastSeen = new Set();
+        if (app) {
+            try {
+                await deleteApp(app);
+            }
+            catch {
+                // The app is being discarded either way.
+            }
+        }
+    }
+    onChange(listener) {
+        this.changeListeners.add(listener);
+        return () => {
+            this.changeListeners.delete(listener);
+        };
+    }
+    onResync(listener) {
+        this.resyncListeners.add(listener);
+        return () => {
+            this.resyncListeners.delete(listener);
+        };
+    }
+    /** The page went hidden: the clock starts, once. */
+    hidden() {
+        this.hiddenSince ??= this.now();
+    }
+    /** The page is visible again: hidden longer than the change documents live, everything is refetched. */
+    visible() {
+        const since = this.hiddenSince;
+        this.hiddenSince = undefined;
+        if (since !== undefined && this.app && this.now() - since > this.resyncAfterHidden) {
+            this.emitResync();
+        }
+    }
+    /** Starts the listener over the change set from the last change seen; `recovering` says an error ended the one before. */
+    listen(recovering) {
+        const db = this.db;
+        if (!db) {
+            return;
+        }
+        const changes = collection(db, 'users', this.uid, 'changes');
+        const bounded = this.lastSeen
+            ? query(changes, where('at', '>', this.lastSeen), orderBy('at'))
+            : query(changes, orderBy('at'));
+        let primed = false;
+        this.unsubscribe = onSnapshot(bounded, (snapshot) => {
+            this.failures = 0;
+            if (!primed) {
+                primed = true;
+                this.prime(snapshot);
+                if (recovering) {
+                    this.emitResync();
+                }
+                return;
+            }
+            this.deliver(snapshot);
+        }, () => {
+            // A listener that reported an error delivers nothing more: start another after a wait.
+            this.unsubscribe = undefined;
+            this.scheduleRestart();
+        });
+    }
+    scheduleRestart() {
+        if (!this.app || this.retry !== undefined) {
+            return;
+        }
+        const delay = Math.min(this.maxRetryDelay, this.retryDelay * 2 ** this.failures);
+        this.failures++;
+        this.retry = setTimeout(() => {
+            this.retry = undefined;
+            this.listen(true);
+        }, delay);
+    }
+    /** The first snapshot of a listener: the latest change in it is the last seen, its documents at that instant are seen, and nothing is emitted. */
+    prime(snapshot) {
+        for (const doc of snapshot.docs) {
+            const change = toChange(doc.data());
+            if (change) {
+                this.advance(doc.id, change.at);
+            }
+        }
+    }
+    /**
+     * A later snapshot: the documents added or moved past the last change seen are events,
+     * in `at` order, and so is a document at that very instant not delivered yet.
+     */
+    deliver(snapshot) {
+        const changes = [];
+        for (const entry of snapshot.docChanges()) {
+            if (entry.type === 'removed') {
+                continue;
+            }
+            const change = toChange(entry.doc.data());
+            if (change && this.unseen(entry.doc.id, change.at)) {
+                changes.push({ id: entry.doc.id, change });
+            }
+        }
+        changes.sort((a, b) => compare(a.change.at, b.change.at));
+        for (const { id, change } of changes) {
+            this.advance(id, change.at);
+            for (const listener of [...this.changeListeners]) {
+                listener(change.event);
+            }
+        }
+    }
+    /** Whether a document at `at` has not been delivered: later than the last seen, or at that instant with an id not yet seen. */
+    unseen(id, at) {
+        if (this.lastSeen === undefined) {
+            return true;
+        }
+        const order = compare(at, this.lastSeen);
+        return order > 0 || (order === 0 && !this.seenAtLastSeen.has(id));
+    }
+    /** Marks a document seen: a later instant replaces the last seen and its set of ids; the same instant adds the id. */
+    advance(id, at) {
+        const order = this.lastSeen === undefined ? 1 : compare(at, this.lastSeen);
+        if (order > 0) {
+            this.lastSeen = at;
+            this.seenAtLastSeen = new Set([id]);
+        }
+        else if (order === 0) {
+            this.seenAtLastSeen.add(id);
+        }
+    }
+    emitResync() {
+        for (const listener of [...this.resyncListeners]) {
+            listener();
+        }
+    }
+}
+/** The Firestore change feed over the firebase JS SDK. Hand it to `client.live.start`. */
+function firestoreChangeFeed(options) {
+    return new FirestoreChangeFeed(options);
+}
+/** `host:port` as the identity carries the emulator, the host bracketed when it is an IPv6 address. */
+function hostAndPort(address) {
+    const mark = address.lastIndexOf(':');
+    if (mark === -1) {
+        throw new Error(`the emulator address "${address}" has no port`);
+    }
+    const host = address.slice(0, mark).replace(/^\[(.*)\]$/, '$1');
+    const port = Number(address.slice(mark + 1));
+    if (host === '' || !Number.isInteger(port) || port <= 0) {
+        throw new Error(`the emulator address "${address}" is not host:port`);
+    }
+    return { host, port };
+}
+/** A Firestore timestamp as unix microseconds in decimal: the version a refetch carries. */
+function microseconds(at) {
+    return (BigInt(at.seconds) * 1000000n + BigInt(Math.floor(at.nanoseconds / 1_000))).toString();
+}
+function isTimestamp(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        typeof value.seconds === 'number' &&
+        typeof value.nanoseconds === 'number');
+}
+function compare(a, b) {
+    return a.seconds === b.seconds ? a.nanoseconds - b.nanoseconds : a.seconds - b.seconds;
+}
+/**
+ * One change document as an event: `kind`, `resource`, and a resolved `at` are required
+ * (a document whose server timestamp has not resolved, or of a shape this feed does not
+ * know, is skipped); `key`, `domain`, and `deleted` ride along when present.
+ */
+function toChange(data) {
+    const kind = data['kind'];
+    const resource = data['resource'];
+    const at = data['at'];
+    if ((kind !== 'row' && kind !== 'list' && kind !== 'resource') || typeof resource !== 'string' || !isTimestamp(at)) {
+        return undefined;
+    }
+    const event = { kind, resource, at: microseconds(at) };
+    if (typeof data['key'] === 'string') {
+        event.key = data['key'];
+    }
+    if (typeof data['domain'] === 'string') {
+        event.domain = data['domain'];
+    }
+    if (typeof data['deleted'] === 'boolean') {
+        event.deleted = data['deleted'];
+    }
+    return { event, at };
+}
+
+/**
+ * Generated bundle index. Do not edit.
+ */
+
+export { FirestoreChangeFeed, firestoreChangeFeed, hostAndPort, microseconds };
+//# sourceMappingURL=cccteam-resource-firestore.mjs.map

package/fesm2022/cccteam-resource-firestore.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"cccteam-resource-firestore.mjs","sources":["../../../projects/resource-firestore/src/firestore-feed.ts","../../../projects/resource-firestore/cccteam-resource-firestore.ts"],"sourcesContent":["import { ChangeEvent, ChangeFeed, LiveIdentity, liveChangeTtl, PageEvents } from '@cccteam/resource';\nimport { deleteApp, FirebaseApp, initializeApp } from 'firebase/app';\nimport { getAuth, signInWithCustomToken } from 'firebase/auth';\nimport {\n  collection,\n  connectFirestoreEmulator,\n  DocumentData,\n  Firestore,\n  getFirestore,\n  onSnapshot,\n  orderBy,\n  query,\n  QuerySnapshot,\n  Unsubscribe,\n  where,\n} from 'firebase/firestore';\n\n/** The document's visibility as the feed reads it; the document, in a browser. */\nexport interface VisibilityEvents {\n  readonly visibilityState: string;\n  addEventListener(type: string, listener: () => void): void;\n  removeEventListener(type: string, listener: () => void): void;\n}\n\n/** The knobs of the feed an application or a spec may turn. Every one has a default. */\nexport interface FirestoreFeedOptions {\n  /**\n   * A page that was hidden longer than this resyncs when it becomes visible again, since\n   * a browser throttles or drops a background page's connection and the change documents\n   * from that time may have expired unseen; the change document's life (liveChangeTtl) by\n   * default.\n   */\n  resyncAfterHidden?: number;\n  /** The wait before a failed listener is started again; doubles each failure up to maxRetryDelay. */\n  retryDelay?: number;\n  maxRetryDelay?: number;\n  /** The clock, in milliseconds; Date.now by default. */\n  now?: () => number;\n  /** Where visibilitychange is heard; the document by default, nothing outside a browser. */\n  visibility?: VisibilityEvents;\n  /** Where pagehide and pageshow are heard; the window by default, nothing outside a browser. */\n  page?: PageEvents;\n}\n\n/** A Firestore timestamp as the change document carries it; read structurally, so a spec needs no SDK class. */\ninterface TimestampLike {\n  seconds: number;\n  nanoseconds: number;\n}\n\ninterface Change {\n  event: ChangeEvent;\n  at: TimestampLike;\n}\n\nlet instances = 0;\n\n/**\n * The Firestore change feed: one listener per tab over the user's change set,\n * `users/{uid}/changes`, ordered by `at` and bounded below by the last change seen. It\n * connects with the identity the server minted (`GET <prefix>/live/token`): the project,\n * the database, and either the emulator with a mock user token for the uid, or a custom\n * token signed in through Firebase Auth. Each document becomes one ChangeEvent with `at`\n * as unix microseconds.\n *\n * The first snapshot of a listener primes the last change seen and emits nothing: at\n * start the backlog predates the page's own first fetch, and after an error the\n * `resync` the recovery emits already refetches everything. The listener keeps its\n * connection and resumes after a drop, so a quiet stretch is not evidence of anything\n * missed; a change is lost only when the listener was down or suspended longer than the\n * change documents live. So the feed emits `resync` in two cases and no other: a failed\n * listener (which delivers nothing more) is started again with a growing wait and its\n * first snapshot is a resync, and a page that becomes visible again after being hidden\n * longer than the change document's life is a resync, since browsers throttle or drop a\n * background page's connection. The live session's own start refetches everything too.\n */\nexport class FirestoreChangeFeed implements ChangeFeed {\n  private readonly resyncAfterHidden: number;\n  private readonly retryDelay: number;\n  private readonly maxRetryDelay: number;\n  private readonly now: () => number;\n  private readonly visibility: VisibilityEvents | undefined;\n  private readonly page: PageEvents | undefined;\n  private readonly changeListeners = new Set<(event: ChangeEvent) => void>();\n  private readonly resyncListeners = new Set<() => void>();\n  private app: FirebaseApp | undefined;\n  private db: Firestore | undefined;\n  private uid = '';\n  private unsubscribe: Unsubscribe | undefined;\n  private retry: ReturnType<typeof setTimeout> | undefined;\n  private failures = 0;\n  private lastSeen: TimestampLike | undefined;\n  /**\n   * The ids of the documents already delivered (or primed) at the `lastSeen` instant,\n   * replaced whenever it advances. One commit writes its row and list documents with one\n   * server timestamp, and a listener may deliver them in two snapshots, so a document at\n   * the last instant seen is new unless its id is here.\n   */\n  private seenAtLastSeen = new Set<string>();\n  /** When the page went hidden, while it is; undefined while visible. */\n  private hiddenSince: number | undefined;\n  private readonly onVisibilityChange = (): void => {\n    if (this.visibility?.visibilityState === 'hidden') {\n      this.hidden();\n      return;\n    }\n    this.visible();\n  };\n  private readonly onPageHide = (): void => this.hidden();\n  private readonly onPageShow = (event: { persisted?: boolean }): void => {\n    if (event.persisted) {\n      this.visible();\n    }\n  };\n\n  constructor(options: FirestoreFeedOptions = {}) {\n    this.resyncAfterHidden = options.resyncAfterHidden ?? liveChangeTtl;\n    this.retryDelay = options.retryDelay ?? 1_000;\n    this.maxRetryDelay = options.maxRetryDelay ?? 30_000;\n    this.now = options.now ?? Date.now;\n    this.visibility = options.visibility ?? (typeof document === 'undefined' ? undefined : document);\n    this.page = options.page ?? (typeof window === 'undefined' ? undefined : window);\n  }\n\n  /** Whether a listener is held: the feed is between start and stop. */\n  get started(): boolean {\n    return this.app !== undefined;\n  }\n\n  async start(identity: LiveIdentity): Promise<void> {\n    if (this.app) {\n      await this.stop();\n    }\n    const app = initializeApp(\n      { projectId: identity.project, apiKey: identity.apiKey || undefined },\n      `cccteam-resource-live-${++instances}`,\n    );\n    const db = identity.database ? getFirestore(app, identity.database) : getFirestore(app);\n    if (identity.emulator) {\n      const { host, port } = hostAndPort(identity.emulator);\n      connectFirestoreEmulator(db, host, port, { mockUserToken: { sub: identity.uid, user_id: identity.uid } });\n    } else {\n      await signInWithCustomToken(getAuth(app), identity.token);\n    }\n    this.app = app;\n    this.db = db;\n    this.uid = identity.uid;\n    this.lastSeen = undefined;\n    this.seenAtLastSeen = new Set();\n    this.failures = 0;\n    this.hiddenSince = this.visibility?.visibilityState === 'hidden' ? this.now() : undefined;\n    this.visibility?.addEventListener('visibilitychange', this.onVisibilityChange);\n    this.page?.addEventListener('pagehide', this.onPageHide);\n    this.page?.addEventListener('pageshow', this.onPageShow);\n    this.listen(false);\n  }\n\n  async stop(): Promise<void> {\n    if (this.retry !== undefined) {\n      clearTimeout(this.retry);\n      this.retry = undefined;\n    }\n    this.visibility?.removeEventListener('visibilitychange', this.onVisibilityChange);\n    this.page?.removeEventListener('pagehide', this.onPageHide);\n    this.page?.removeEventListener('pageshow', this.onPageShow);\n    this.hiddenSince = undefined;\n    this.unsubscribe?.();\n    this.unsubscribe = undefined;\n    const app = this.app;\n    this.app = undefined;\n    this.db = undefined;\n    this.uid = '';\n    this.lastSeen = undefined;\n    this.seenAtLastSeen = new Set();\n    if (app) {\n      try {\n        await deleteApp(app);\n      } catch {\n        // The app is being discarded either way.\n      }\n    }\n  }\n\n  onChange(listener: (event: ChangeEvent) => void): () => void {\n    this.changeListeners.add(listener);\n    return () => {\n      this.changeListeners.delete(listener);\n    };\n  }\n\n  onResync(listener: () => void): () => void {\n    this.resyncListeners.add(listener);\n    return () => {\n      this.resyncListeners.delete(listener);\n    };\n  }\n\n  /** The page went hidden: the clock starts, once. */\n  private hidden(): void {\n    this.hiddenSince ??= this.now();\n  }\n\n  /** The page is visible again: hidden longer than the change documents live, everything is refetched. */\n  private visible(): void {\n    const since = this.hiddenSince;\n    this.hiddenSince = undefined;\n    if (since !== undefined && this.app && this.now() - since > this.resyncAfterHidden) {\n      this.emitResync();\n    }\n  }\n\n  /** Starts the listener over the change set from the last change seen; `recovering` says an error ended the one before. */\n  private listen(recovering: boolean): void {\n    const db = this.db;\n    if (!db) {\n      return;\n    }\n    const changes = collection(db, 'users', this.uid, 'changes');\n    const bounded = this.lastSeen\n      ? query(changes, where('at', '>', this.lastSeen), orderBy('at'))\n      : query(changes, orderBy('at'));\n    let primed = false;\n    this.unsubscribe = onSnapshot(\n      bounded,\n      (snapshot) => {\n        this.failures = 0;\n        if (!primed) {\n          primed = true;\n          this.prime(snapshot);\n          if (recovering) {\n            this.emitResync();\n          }\n          return;\n        }\n        this.deliver(snapshot);\n      },\n      () => {\n        // A listener that reported an error delivers nothing more: start another after a wait.\n        this.unsubscribe = undefined;\n        this.scheduleRestart();\n      },\n    );\n  }\n\n  private scheduleRestart(): void {\n    if (!this.app || this.retry !== undefined) {\n      return;\n    }\n    const delay = Math.min(this.maxRetryDelay, this.retryDelay * 2 ** this.failures);\n    this.failures++;\n    this.retry = setTimeout(() => {\n      this.retry = undefined;\n      this.listen(true);\n    }, delay);\n  }\n\n  /** The first snapshot of a listener: the latest change in it is the last seen, its documents at that instant are seen, and nothing is emitted. */\n  private prime(snapshot: QuerySnapshot<DocumentData>): void {\n    for (const doc of snapshot.docs) {\n      const change = toChange(doc.data());\n      if (change) {\n        this.advance(doc.id, change.at);\n      }\n    }\n  }\n\n  /**\n   * A later snapshot: the documents added or moved past the last change seen are events,\n   * in `at` order, and so is a document at that very instant not delivered yet.\n   */\n  private deliver(snapshot: QuerySnapshot<DocumentData>): void {\n    const changes: { id: string; change: Change }[] = [];\n    for (const entry of snapshot.docChanges()) {\n      if (entry.type === 'removed') {\n        continue;\n      }\n      const change = toChange(entry.doc.data());\n      if (change && this.unseen(entry.doc.id, change.at)) {\n        changes.push({ id: entry.doc.id, change });\n      }\n    }\n    changes.sort((a, b) => compare(a.change.at, b.change.at));\n    for (const { id, change } of changes) {\n      this.advance(id, change.at);\n      for (const listener of [...this.changeListeners]) {\n        listener(change.event);\n      }\n    }\n  }\n\n  /** Whether a document at `at` has not been delivered: later than the last seen, or at that instant with an id not yet seen. */\n  private unseen(id: string, at: TimestampLike): boolean {\n    if (this.lastSeen === undefined) {\n      return true;\n    }\n    const order = compare(at, this.lastSeen);\n    return order > 0 || (order === 0 && !this.seenAtLastSeen.has(id));\n  }\n\n  /** Marks a document seen: a later instant replaces the last seen and its set of ids; the same instant adds the id. */\n  private advance(id: string, at: TimestampLike): void {\n    const order = this.lastSeen === undefined ? 1 : compare(at, this.lastSeen);\n    if (order > 0) {\n      this.lastSeen = at;\n      this.seenAtLastSeen = new Set([id]);\n    } else if (order === 0) {\n      this.seenAtLastSeen.add(id);\n    }\n  }\n\n  private emitResync(): void {\n    for (const listener of [...this.resyncListeners]) {\n      listener();\n    }\n  }\n}\n\n/** The Firestore change feed over the firebase JS SDK. Hand it to `client.live.start`. */\nexport function firestoreChangeFeed(options?: FirestoreFeedOptions): ChangeFeed {\n  return new FirestoreChangeFeed(options);\n}\n\n/** `host:port` as the identity carries the emulator, the host bracketed when it is an IPv6 address. */\nexport function hostAndPort(address: string): { host: string; port: number } {\n  const mark = address.lastIndexOf(':');\n  if (mark === -1) {\n    throw new Error(`the emulator address \"${address}\" has no port`);\n  }\n  const host = address.slice(0, mark).replace(/^\\[(.*)\\]$/, '$1');\n  const port = Number(address.slice(mark + 1));\n  if (host === '' || !Number.isInteger(port) || port <= 0) {\n    throw new Error(`the emulator address \"${address}\" is not host:port`);\n  }\n  return { host, port };\n}\n\n/** A Firestore timestamp as unix microseconds in decimal: the version a refetch carries. */\nexport function microseconds(at: TimestampLike): string {\n  return (BigInt(at.seconds) * 1_000_000n + BigInt(Math.floor(at.nanoseconds / 1_000))).toString();\n}\n\nfunction isTimestamp(value: unknown): value is TimestampLike {\n  return (\n    typeof value === 'object' &&\n    value !== null &&\n    typeof (value as TimestampLike).seconds === 'number' &&\n    typeof (value as TimestampLike).nanoseconds === 'number'\n  );\n}\n\nfunction compare(a: TimestampLike, b: TimestampLike): number {\n  return a.seconds === b.seconds ? a.nanoseconds - b.nanoseconds : a.seconds - b.seconds;\n}\n\n/**\n * One change document as an event: `kind`, `resource`, and a resolved `at` are required\n * (a document whose server timestamp has not resolved, or of a shape this feed does not\n * know, is skipped); `key`, `domain`, and `deleted` ride along when present.\n */\nfunction toChange(data: DocumentData): Change | undefined {\n  const kind = data['kind'];\n  const resource = data['resource'];\n  const at = data['at'];\n  if ((kind !== 'row' && kind !== 'list' && kind !== 'resource') || typeof resource !== 'string' || !isTimestamp(at)) {\n    return undefined;\n  }\n  const event: ChangeEvent = { kind, resource, at: microseconds(at) };\n  if (typeof data['key'] === 'string') {\n    event.key = data['key'];\n  }\n  if (typeof data['domain'] === 'string') {\n    event.domain = data['domain'];\n  }\n  if (typeof data['deleted'] === 'boolean') {\n    event.deleted = data['deleted'];\n  }\n  return { event, at };\n}\n","/**\n * Generated bundle index. Do not edit.\n */\n\nexport * from './index';\n"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@cccteam/resource-firestore",
+  "version": "0.0.1",
+  "description": "The Firestore change feed for live pages over @cccteam/resource",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cccteam/ccc-lib.git",
+    "directory": "projects/resource-firestore"
+  },
+  "peerDependencies": {
+    "@cccteam/resource": "^0.0.3",
+    "firebase": "^12.19.0"
+  },
+  "dependencies": {
+    "tslib": "^2.3.0"
+  },
+  "sideEffects": false,
+  "module": "fesm2022/cccteam-resource-firestore.mjs",
+  "typings": "types/cccteam-resource-firestore.d.ts",
+  "exports": {
+    "./package.json": {
+      "default": "./package.json"
+    },
+    ".": {
+      "types": "./types/cccteam-resource-firestore.d.ts",
+      "default": "./fesm2022/cccteam-resource-firestore.mjs"
+    }
+  },
+  "type": "module"
+}

package/types/cccteam-resource-firestore.d.ts

@@ -0,0 +1,118 @@
+import { ChangeFeed, PageEvents, LiveIdentity, ChangeEvent } from '@cccteam/resource';
+
+/** The document's visibility as the feed reads it; the document, in a browser. */
+interface VisibilityEvents {
+    readonly visibilityState: string;
+    addEventListener(type: string, listener: () => void): void;
+    removeEventListener(type: string, listener: () => void): void;
+}
+/** The knobs of the feed an application or a spec may turn. Every one has a default. */
+interface FirestoreFeedOptions {
+    /**
+     * A page that was hidden longer than this resyncs when it becomes visible again, since
+     * a browser throttles or drops a background page's connection and the change documents
+     * from that time may have expired unseen; the change document's life (liveChangeTtl) by
+     * default.
+     */
+    resyncAfterHidden?: number;
+    /** The wait before a failed listener is started again; doubles each failure up to maxRetryDelay. */
+    retryDelay?: number;
+    maxRetryDelay?: number;
+    /** The clock, in milliseconds; Date.now by default. */
+    now?: () => number;
+    /** Where visibilitychange is heard; the document by default, nothing outside a browser. */
+    visibility?: VisibilityEvents;
+    /** Where pagehide and pageshow are heard; the window by default, nothing outside a browser. */
+    page?: PageEvents;
+}
+/** A Firestore timestamp as the change document carries it; read structurally, so a spec needs no SDK class. */
+interface TimestampLike {
+    seconds: number;
+    nanoseconds: number;
+}
+/**
+ * The Firestore change feed: one listener per tab over the user's change set,
+ * `users/{uid}/changes`, ordered by `at` and bounded below by the last change seen. It
+ * connects with the identity the server minted (`GET <prefix>/live/token`): the project,
+ * the database, and either the emulator with a mock user token for the uid, or a custom
+ * token signed in through Firebase Auth. Each document becomes one ChangeEvent with `at`
+ * as unix microseconds.
+ *
+ * The first snapshot of a listener primes the last change seen and emits nothing: at
+ * start the backlog predates the page's own first fetch, and after an error the
+ * `resync` the recovery emits already refetches everything. The listener keeps its
+ * connection and resumes after a drop, so a quiet stretch is not evidence of anything
+ * missed; a change is lost only when the listener was down or suspended longer than the
+ * change documents live. So the feed emits `resync` in two cases and no other: a failed
+ * listener (which delivers nothing more) is started again with a growing wait and its
+ * first snapshot is a resync, and a page that becomes visible again after being hidden
+ * longer than the change document's life is a resync, since browsers throttle or drop a
+ * background page's connection. The live session's own start refetches everything too.
+ */
+declare class FirestoreChangeFeed implements ChangeFeed {
+    private readonly resyncAfterHidden;
+    private readonly retryDelay;
+    private readonly maxRetryDelay;
+    private readonly now;
+    private readonly visibility;
+    private readonly page;
+    private readonly changeListeners;
+    private readonly resyncListeners;
+    private app;
+    private db;
+    private uid;
+    private unsubscribe;
+    private retry;
+    private failures;
+    private lastSeen;
+    /**
+     * The ids of the documents already delivered (or primed) at the `lastSeen` instant,
+     * replaced whenever it advances. One commit writes its row and list documents with one
+     * server timestamp, and a listener may deliver them in two snapshots, so a document at
+     * the last instant seen is new unless its id is here.
+     */
+    private seenAtLastSeen;
+    /** When the page went hidden, while it is; undefined while visible. */
+    private hiddenSince;
+    private readonly onVisibilityChange;
+    private readonly onPageHide;
+    private readonly onPageShow;
+    constructor(options?: FirestoreFeedOptions);
+    /** Whether a listener is held: the feed is between start and stop. */
+    get started(): boolean;
+    start(identity: LiveIdentity): Promise<void>;
+    stop(): Promise<void>;
+    onChange(listener: (event: ChangeEvent) => void): () => void;
+    onResync(listener: () => void): () => void;
+    /** The page went hidden: the clock starts, once. */
+    private hidden;
+    /** The page is visible again: hidden longer than the change documents live, everything is refetched. */
+    private visible;
+    /** Starts the listener over the change set from the last change seen; `recovering` says an error ended the one before. */
+    private listen;
+    private scheduleRestart;
+    /** The first snapshot of a listener: the latest change in it is the last seen, its documents at that instant are seen, and nothing is emitted. */
+    private prime;
+    /**
+     * A later snapshot: the documents added or moved past the last change seen are events,
+     * in `at` order, and so is a document at that very instant not delivered yet.
+     */
+    private deliver;
+    /** Whether a document at `at` has not been delivered: later than the last seen, or at that instant with an id not yet seen. */
+    private unseen;
+    /** Marks a document seen: a later instant replaces the last seen and its set of ids; the same instant adds the id. */
+    private advance;
+    private emitResync;
+}
+/** The Firestore change feed over the firebase JS SDK. Hand it to `client.live.start`. */
+declare function firestoreChangeFeed(options?: FirestoreFeedOptions): ChangeFeed;
+/** `host:port` as the identity carries the emulator, the host bracketed when it is an IPv6 address. */
+declare function hostAndPort(address: string): {
+    host: string;
+    port: number;
+};
+/** A Firestore timestamp as unix microseconds in decimal: the version a refetch carries. */
+declare function microseconds(at: TimestampLike): string;
+
+export { FirestoreChangeFeed, firestoreChangeFeed, hostAndPort, microseconds };
+export type { FirestoreFeedOptions, VisibilityEvents };