@koolbase/core 12.10.0 → 12.11.1

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.d.ts

@@ -9,6 +9,11 @@ export declare class KoolbaseRealtime {
     private reconnectAttempts;
     private reconnectTimer;
     private connecting;
+    private idleTimer;
+    /** How long an unused connection stays open, in ms: a screen that comes
+     *  straight back (navigating back, React's development double start)
+     *  reuses it instead of opening another. */
+    static idleGraceMs: number;
     /**
      * Identifies whose cache a seen record belongs in.
      *
@@ -39,6 +44,13 @@ export declare class KoolbaseRealtime {
      * does not accumulate delay.
      */
     private scheduleReconnect;
+    /**
+     * Closes the connection once nobody is subscribed -- after a moment, not at
+     * once: a screen that unmounts and mounts again keeps the connection it had.
+     * A subscribe within the moment cancels the close. Nothing reconnects after
+     * it: reconnecting needs a subscriber.
+     */
+    private scheduleIdleClose;
     disconnect(): void;
 }
 export {};

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',
@@ -40,9 +41,14 @@ class KoolbaseRealtime {
         this.reconnectAttempts = 0;
         this.reconnectTimer = null;
         this.connecting = false;
+        // Pending close of an unused connection (scheduleIdleClose); null while
+        // anyone is subscribed.
+        this.idleTimer = null;
         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) {
@@ -58,6 +64,10 @@ class KoolbaseRealtime {
         await (0, cache_store_js_1.removeCachedRecord)(userId, recordId);
     }
     subscribe(collection, callback) {
+        if (this.idleTimer) {
+            clearTimeout(this.idleTimer);
+            this.idleTimer = null;
+        }
         if (!this.listeners.has(collection))
             this.listeners.set(collection, []);
         this.listeners.get(collection).push(callback);
@@ -68,13 +78,16 @@ class KoolbaseRealtime {
             void this.connect();
         }
         return () => {
-            const callbacks = this.listeners.get(collection) ?? [];
-            const i = callbacks.indexOf(callback);
-            if (i > -1)
-                callbacks.splice(i, 1);
+            const callbacks = this.listeners.get(collection);
+            const i = callbacks ? callbacks.indexOf(callback) : -1;
+            if (!callbacks || i === -1)
+                return; // already unsubscribed: a second call does nothing
+            callbacks.splice(i, 1);
             if (callbacks.length === 0) {
                 this.listeners.delete(collection);
                 this.sendUnsubscribe(collection);
+                if (this.listeners.size === 0)
+                    this.scheduleIdleClose();
             }
         };
     }
@@ -83,15 +96,39 @@ class KoolbaseRealtime {
             return;
         if (this.ws && (this.ws.readyState === WebSocket.OPEN || this.ws.readyState === WebSocket.CONNECTING))
             return;
-        const token = await this.getToken();
+        // Claimed BEFORE the token is awaited. Claimed after it, every subscribe
+        // arriving meanwhile -- two live lists on one screen, React's development
+        // double start -- found nobody connecting and opened its own socket; only
+        // the last was remembered, and the others stayed open for good.
+        this.connecting = true;
+        let token;
+        try {
+            token = await this.getToken();
+        }
+        catch {
+            token = null;
+        }
+        if (this.listeners.size === 0) {
+            // Everyone left while the token was on its way: nothing to connect for.
+            this.connecting = false;
+            return;
+        }
         if (!token) {
+            this.connecting = false;
             this.scheduleReconnect(); // sign-in may be in flight
             return;
         }
         this.projectId = projectIdFromToken(token);
-        this.connecting = true;
         const wsUrl = this.config.baseUrl.replace('https://', 'wss://').replace('http://', 'ws://');
-        const ws = new WebSocket(`${wsUrl}/v1/realtime/ws?token=${encodeURIComponent(token)}`);
+        let ws;
+        try {
+            ws = new WebSocket(`${wsUrl}/v1/realtime/ws?token=${encodeURIComponent(token)}`);
+        }
+        catch {
+            this.connecting = false;
+            this.scheduleReconnect();
+            return;
+        }
         this.ws = ws;
         ws.onopen = () => {
             this.connecting = false;
@@ -184,11 +221,47 @@ class KoolbaseRealtime {
         }, delay);
         this.reconnectTimer.unref?.();
     }
+    /**
+     * Closes the connection once nobody is subscribed -- after a moment, not at
+     * once: a screen that unmounts and mounts again keeps the connection it had.
+     * A subscribe within the moment cancels the close. Nothing reconnects after
+     * it: reconnecting needs a subscriber.
+     */
+    scheduleIdleClose() {
+        if (this.idleTimer)
+            clearTimeout(this.idleTimer);
+        this.idleTimer = setTimeout(() => {
+            this.idleTimer = null;
+            if (this.listeners.size > 0)
+                return;
+            if (this.reconnectTimer) {
+                clearTimeout(this.reconnectTimer);
+                this.reconnectTimer = null;
+            }
+            const ws = this.ws;
+            this.ws = null;
+            this.connecting = false;
+            if (ws) {
+                // Detached first: this close is ours, not a dropped connection.
+                ws.onopen = null;
+                ws.onmessage = null;
+                ws.onclose = null;
+                ws.onerror = null;
+                ws.close();
+            }
+        }, KoolbaseRealtime.idleGraceMs);
+        this.idleTimer.unref?.();
+    }
     disconnect() {
+        if (this.idleTimer) {
+            clearTimeout(this.idleTimer);
+            this.idleTimer = null;
+        }
         if (this.reconnectTimer) {
             clearTimeout(this.reconnectTimer);
             this.reconnectTimer = null;
         }
+        this.connecting = false;
         this.ws?.close();
         this.ws = null;
         this.projectId = null;
@@ -196,3 +269,7 @@ class KoolbaseRealtime {
     }
 }
 exports.KoolbaseRealtime = KoolbaseRealtime;
+/** How long an unused connection stays open, in ms: a screen that comes
+ *  straight back (navigating back, React's development double start)
+ *  reuses it instead of opening another. */
+KoolbaseRealtime.idleGraceMs = 1000;

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.d.ts

@@ -9,6 +9,11 @@ export declare class KoolbaseRealtime {
     private reconnectAttempts;
     private reconnectTimer;
     private connecting;
+    private idleTimer;
+    /** How long an unused connection stays open, in ms: a screen that comes
+     *  straight back (navigating back, React's development double start)
+     *  reuses it instead of opening another. */
+    static idleGraceMs: number;
     /**
      * Identifies whose cache a seen record belongs in.
      *
@@ -39,6 +44,13 @@ export declare class KoolbaseRealtime {
      * does not accumulate delay.
      */
     private scheduleReconnect;
+    /**
+     * Closes the connection once nobody is subscribed -- after a moment, not at
+     * once: a screen that unmounts and mounts again keeps the connection it had.
+     * A subscribe within the moment cancels the close. Nothing reconnects after
+     * it: reconnecting needs a subscriber.
+     */
+    private scheduleIdleClose;
     disconnect(): void;
 }
 export {};

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',
@@ -37,9 +38,14 @@ export class KoolbaseRealtime {
         this.reconnectAttempts = 0;
         this.reconnectTimer = null;
         this.connecting = false;
+        // Pending close of an unused connection (scheduleIdleClose); null while
+        // anyone is subscribed.
+        this.idleTimer = null;
         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) {
@@ -55,6 +61,10 @@ export class KoolbaseRealtime {
         await removeCachedRecord(userId, recordId);
     }
     subscribe(collection, callback) {
+        if (this.idleTimer) {
+            clearTimeout(this.idleTimer);
+            this.idleTimer = null;
+        }
         if (!this.listeners.has(collection))
             this.listeners.set(collection, []);
         this.listeners.get(collection).push(callback);
@@ -65,13 +75,16 @@ export class KoolbaseRealtime {
             void this.connect();
         }
         return () => {
-            const callbacks = this.listeners.get(collection) ?? [];
-            const i = callbacks.indexOf(callback);
-            if (i > -1)
-                callbacks.splice(i, 1);
+            const callbacks = this.listeners.get(collection);
+            const i = callbacks ? callbacks.indexOf(callback) : -1;
+            if (!callbacks || i === -1)
+                return; // already unsubscribed: a second call does nothing
+            callbacks.splice(i, 1);
             if (callbacks.length === 0) {
                 this.listeners.delete(collection);
                 this.sendUnsubscribe(collection);
+                if (this.listeners.size === 0)
+                    this.scheduleIdleClose();
             }
         };
     }
@@ -80,15 +93,39 @@ export class KoolbaseRealtime {
             return;
         if (this.ws && (this.ws.readyState === WebSocket.OPEN || this.ws.readyState === WebSocket.CONNECTING))
             return;
-        const token = await this.getToken();
+        // Claimed BEFORE the token is awaited. Claimed after it, every subscribe
+        // arriving meanwhile -- two live lists on one screen, React's development
+        // double start -- found nobody connecting and opened its own socket; only
+        // the last was remembered, and the others stayed open for good.
+        this.connecting = true;
+        let token;
+        try {
+            token = await this.getToken();
+        }
+        catch {
+            token = null;
+        }
+        if (this.listeners.size === 0) {
+            // Everyone left while the token was on its way: nothing to connect for.
+            this.connecting = false;
+            return;
+        }
         if (!token) {
+            this.connecting = false;
             this.scheduleReconnect(); // sign-in may be in flight
             return;
         }
         this.projectId = projectIdFromToken(token);
-        this.connecting = true;
         const wsUrl = this.config.baseUrl.replace('https://', 'wss://').replace('http://', 'ws://');
-        const ws = new WebSocket(`${wsUrl}/v1/realtime/ws?token=${encodeURIComponent(token)}`);
+        let ws;
+        try {
+            ws = new WebSocket(`${wsUrl}/v1/realtime/ws?token=${encodeURIComponent(token)}`);
+        }
+        catch {
+            this.connecting = false;
+            this.scheduleReconnect();
+            return;
+        }
         this.ws = ws;
         ws.onopen = () => {
             this.connecting = false;
@@ -181,14 +218,54 @@ export class KoolbaseRealtime {
         }, delay);
         this.reconnectTimer.unref?.();
     }
+    /**
+     * Closes the connection once nobody is subscribed -- after a moment, not at
+     * once: a screen that unmounts and mounts again keeps the connection it had.
+     * A subscribe within the moment cancels the close. Nothing reconnects after
+     * it: reconnecting needs a subscriber.
+     */
+    scheduleIdleClose() {
+        if (this.idleTimer)
+            clearTimeout(this.idleTimer);
+        this.idleTimer = setTimeout(() => {
+            this.idleTimer = null;
+            if (this.listeners.size > 0)
+                return;
+            if (this.reconnectTimer) {
+                clearTimeout(this.reconnectTimer);
+                this.reconnectTimer = null;
+            }
+            const ws = this.ws;
+            this.ws = null;
+            this.connecting = false;
+            if (ws) {
+                // Detached first: this close is ours, not a dropped connection.
+                ws.onopen = null;
+                ws.onmessage = null;
+                ws.onclose = null;
+                ws.onerror = null;
+                ws.close();
+            }
+        }, KoolbaseRealtime.idleGraceMs);
+        this.idleTimer.unref?.();
+    }
     disconnect() {
+        if (this.idleTimer) {
+            clearTimeout(this.idleTimer);
+            this.idleTimer = null;
+        }
         if (this.reconnectTimer) {
             clearTimeout(this.reconnectTimer);
             this.reconnectTimer = null;
         }
+        this.connecting = false;
         this.ws?.close();
         this.ws = null;
         this.projectId = null;
         this.listeners.clear();
     }
 }
+/** How long an unused connection stays open, in ms: a screen that comes
+ *  straight back (navigating back, React's development double start)
+ *  reuses it instead of opening another. */
+KoolbaseRealtime.idleGraceMs = 1000;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@koolbase/core",
-  "version": "12.10.0",
+  "version": "12.11.1",
   "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",