@koolbase/core 12.10.0 → 12.11.0

package/dist/cjs/collection-controller.d.ts

@@ -8,6 +8,13 @@ export interface CollectionQuery {
     orderDesc?: boolean;
     /** Page size; the server's default (20) when absent. */
     limit?: number;
+    /**
+     * Re-read page one, silently, when Koolbase realtime reports a record
+     * created, updated or deleted in this collection (debounced: a burst is one
+     * read). Realtime needs a signed-in user; until there is one, the list
+     * behaves as a normal list and goes live once the session exists.
+     */
+    live?: boolean;
 }
 export interface CollectionState {
     readonly status: CollectionStatus;
@@ -39,6 +46,8 @@ export declare class KoolbaseCollectionController {
     private laterPages;
     private nextOffset;
     private unregister;
+    private unlive;
+    private liveTimer;
     constructor(db: QueryReader, collection: string, query?: CollectionQuery);
     getState(): CollectionState;
     /** Called on every change. Returns the unsubscribe. */
@@ -53,6 +62,11 @@ export declare class KoolbaseCollectionController {
      * shown stays while it runs, and stays if it fails.
      */
     private refreshAfterWrite;
+    /**
+     * A change someone made, reported by realtime: page one again, silently, as
+     * after a write -- once per burst (250 ms), not once per event.
+     */
+    private scheduleLiveRefresh;
     /**
      * The next page, appended. Does nothing unless loaded with more to load.
      * If rows are added or removed on the server between pages, one can be

package/dist/cjs/collection-controller.js

@@ -25,6 +25,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.KoolbaseCollectionController = exports.initialCollectionState = void 0;
 exports.collectionQueryKey = collectionQueryKey;
+const live_source_js_1 = require("./live-source.js");
 const query_refresh_js_1 = require("./query-refresh.js");
 exports.initialCollectionState = Object.freeze({
     status: 'loading',
@@ -49,6 +50,8 @@ function collectionQueryKey(collection, query = {}) {
         query.orderBy ?? null,
         query.orderDesc === true,
         query.limit ?? null,
+        // Only when live: every other query keeps the key it always had.
+        ...(query.live === true ? ['live'] : []),
     ]);
 }
 /** Page one, then the later pages without any record already shown. */
@@ -76,6 +79,9 @@ class KoolbaseCollectionController {
         this.nextOffset = 0;
         // A write to this collection re-runs this query (query-refresh.ts).
         this.unregister = null;
+        // A live list's realtime subscription, and its pending debounced re-read.
+        this.unlive = null;
+        this.liveTimer = null;
         this.db = db;
         this.collection = collection;
         this.spec = query;
@@ -97,6 +103,9 @@ class KoolbaseCollectionController {
         if (this.disposed)
             return;
         this.unregister ?? (this.unregister = (0, query_refresh_js_1.registerQueryRefresher)(this.collection, () => this.refreshAfterWrite()));
+        if (this.spec.live === true) {
+            this.unlive ?? (this.unlive = (0, live_source_js_1.liveSource)()?.subscribe(this.collection, () => this.scheduleLiveRefresh()) ?? null);
+        }
         await this.firstPage('default');
     }
     /** Page one again, from the server. What is shown stays while it runs, and stays if it fails. */
@@ -118,6 +127,20 @@ class KoolbaseCollectionController {
             return;
         await this.firstPage('network-only');
     }
+    /**
+     * A change someone made, reported by realtime: page one again, silently, as
+     * after a write -- once per burst (250 ms), not once per event.
+     */
+    scheduleLiveRefresh() {
+        if (this.disposed || this.liveTimer)
+            return;
+        this.liveTimer = setTimeout(() => {
+            this.liveTimer = null;
+            void this.refreshAfterWrite();
+        }, 250);
+        // A pending re-read must not be what keeps a Node process alive.
+        this.liveTimer.unref?.();
+    }
     /**
      * The next page, appended. Does nothing unless loaded with more to load.
      * If rows are added or removed on the server between pages, one can be
@@ -153,6 +176,12 @@ class KoolbaseCollectionController {
         this.disposed = true;
         this.unregister?.();
         this.unregister = null;
+        this.unlive?.();
+        this.unlive = null;
+        if (this.liveTimer) {
+            clearTimeout(this.liveTimer);
+            this.liveTimer = null;
+        }
         this.listeners.clear();
     }
     async firstPage(cache) {

package/dist/cjs/live-source.d.ts

@@ -0,0 +1,6 @@
+export interface LiveSource {
+    /** Calls back on every record event in the collection; returns the unsubscribe. */
+    subscribe(collection: string, callback: (event: unknown) => void): () => void;
+}
+export declare function setLiveSource(source: LiveSource | null): void;
+export declare function liveSource(): LiveSource | null;

package/dist/cjs/live-source.js

@@ -0,0 +1,16 @@
+"use strict";
+// The realtime client a live list subscribes through. KoolbaseRealtime
+// registers itself when it is created, as query-refresh.ts registers the
+// refreshers writes run: a list reaches realtime without the host packages
+// passing it in. None registered (realtime never created): a live list is
+// simply a list.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setLiveSource = setLiveSource;
+exports.liveSource = liveSource;
+let active = null;
+function setLiveSource(source) {
+    active = source;
+}
+function liveSource() {
+    return active;
+}

package/dist/cjs/realtime.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.KoolbaseRealtime = void 0;
 const cache_store_js_1 = require("./cache-store.js");
 const record_js_1 = require("./record.js");
+const live_source_js_1 = require("./live-source.js");
 const EVENT_TYPE_MAP = {
     'db.record.created': 'created',
     'db.record.updated': 'updated',
@@ -43,6 +44,8 @@ class KoolbaseRealtime {
         this.config = config;
         this.getToken = getToken;
         this.getUserId = getUserId;
+        // Live lists (CollectionQuery.live) subscribe through this client.
+        (0, live_source_js_1.setLiveSource)(this);
     }
     /** Files a record seen over the socket, if we know whose it is. */
     async cacheSeenRecord(collection, record) {

package/dist/esm/collection-controller.d.ts

@@ -8,6 +8,13 @@ export interface CollectionQuery {
     orderDesc?: boolean;
     /** Page size; the server's default (20) when absent. */
     limit?: number;
+    /**
+     * Re-read page one, silently, when Koolbase realtime reports a record
+     * created, updated or deleted in this collection (debounced: a burst is one
+     * read). Realtime needs a signed-in user; until there is one, the list
+     * behaves as a normal list and goes live once the session exists.
+     */
+    live?: boolean;
 }
 export interface CollectionState {
     readonly status: CollectionStatus;
@@ -39,6 +46,8 @@ export declare class KoolbaseCollectionController {
     private laterPages;
     private nextOffset;
     private unregister;
+    private unlive;
+    private liveTimer;
     constructor(db: QueryReader, collection: string, query?: CollectionQuery);
     getState(): CollectionState;
     /** Called on every change. Returns the unsubscribe. */
@@ -53,6 +62,11 @@ export declare class KoolbaseCollectionController {
      * shown stays while it runs, and stays if it fails.
      */
     private refreshAfterWrite;
+    /**
+     * A change someone made, reported by realtime: page one again, silently, as
+     * after a write -- once per burst (250 ms), not once per event.
+     */
+    private scheduleLiveRefresh;
     /**
      * The next page, appended. Does nothing unless loaded with more to load.
      * If rows are added or removed on the server between pages, one can be

package/dist/esm/collection-controller.js

@@ -21,6 +21,7 @@
 // Known limit: if rows are added or removed on the server between pages,
 // the pages shift and a row can be skipped until refresh(), which reloads
 // from page one. Duplicates are removed; a skipped row cannot be detected.
+import { liveSource } from './live-source.js';
 import { registerQueryRefresher } from './query-refresh.js';
 export const initialCollectionState = Object.freeze({
     status: 'loading',
@@ -45,6 +46,8 @@ export function collectionQueryKey(collection, query = {}) {
         query.orderBy ?? null,
         query.orderDesc === true,
         query.limit ?? null,
+        // Only when live: every other query keeps the key it always had.
+        ...(query.live === true ? ['live'] : []),
     ]);
 }
 /** Page one, then the later pages without any record already shown. */
@@ -72,6 +75,9 @@ export class KoolbaseCollectionController {
         this.nextOffset = 0;
         // A write to this collection re-runs this query (query-refresh.ts).
         this.unregister = null;
+        // A live list's realtime subscription, and its pending debounced re-read.
+        this.unlive = null;
+        this.liveTimer = null;
         this.db = db;
         this.collection = collection;
         this.spec = query;
@@ -93,6 +99,9 @@ export class KoolbaseCollectionController {
         if (this.disposed)
             return;
         this.unregister ?? (this.unregister = registerQueryRefresher(this.collection, () => this.refreshAfterWrite()));
+        if (this.spec.live === true) {
+            this.unlive ?? (this.unlive = liveSource()?.subscribe(this.collection, () => this.scheduleLiveRefresh()) ?? null);
+        }
         await this.firstPage('default');
     }
     /** Page one again, from the server. What is shown stays while it runs, and stays if it fails. */
@@ -114,6 +123,20 @@ export class KoolbaseCollectionController {
             return;
         await this.firstPage('network-only');
     }
+    /**
+     * A change someone made, reported by realtime: page one again, silently, as
+     * after a write -- once per burst (250 ms), not once per event.
+     */
+    scheduleLiveRefresh() {
+        if (this.disposed || this.liveTimer)
+            return;
+        this.liveTimer = setTimeout(() => {
+            this.liveTimer = null;
+            void this.refreshAfterWrite();
+        }, 250);
+        // A pending re-read must not be what keeps a Node process alive.
+        this.liveTimer.unref?.();
+    }
     /**
      * The next page, appended. Does nothing unless loaded with more to load.
      * If rows are added or removed on the server between pages, one can be
@@ -149,6 +172,12 @@ export class KoolbaseCollectionController {
         this.disposed = true;
         this.unregister?.();
         this.unregister = null;
+        this.unlive?.();
+        this.unlive = null;
+        if (this.liveTimer) {
+            clearTimeout(this.liveTimer);
+            this.liveTimer = null;
+        }
         this.listeners.clear();
     }
     async firstPage(cache) {

package/dist/esm/live-source.d.ts

@@ -0,0 +1,6 @@
+export interface LiveSource {
+    /** Calls back on every record event in the collection; returns the unsubscribe. */
+    subscribe(collection: string, callback: (event: unknown) => void): () => void;
+}
+export declare function setLiveSource(source: LiveSource | null): void;
+export declare function liveSource(): LiveSource | null;

package/dist/esm/live-source.js

@@ -0,0 +1,12 @@
+// The realtime client a live list subscribes through. KoolbaseRealtime
+// registers itself when it is created, as query-refresh.ts registers the
+// refreshers writes run: a list reaches realtime without the host packages
+// passing it in. None registered (realtime never created): a live list is
+// simply a list.
+let active = null;
+export function setLiveSource(source) {
+    active = source;
+}
+export function liveSource() {
+    return active;
+}

package/dist/esm/realtime.js

@@ -1,5 +1,6 @@
 import { cacheRecord, removeCachedRecord } from './cache-store.js';
 import { recordFromWire } from './record.js';
+import { setLiveSource } from './live-source.js';
 const EVENT_TYPE_MAP = {
     'db.record.created': 'created',
     'db.record.updated': 'updated',
@@ -40,6 +41,8 @@ export class KoolbaseRealtime {
         this.config = config;
         this.getToken = getToken;
         this.getUserId = getUserId;
+        // Live lists (CollectionQuery.live) subscribe through this client.
+        setLiveSource(this);
     }
     /** Files a record seen over the socket, if we know whose it is. */
     async cacheSeenRecord(collection, record) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@koolbase/core",
-  "version": "12.10.0",
+  "version": "12.11.0",
   "description": "Koolbase SDK core \u2014 shared behaviour behind @koolbase/react-native and @koolbase/js. Install one of those, not this.",
   "main": "./dist/cjs/index.js",
   "types": "./dist/esm/index.d.ts",