@koolbase/core 12.11.0 → 12.12.0

package/dist/cjs/react/use-record.d.ts

@@ -3,4 +3,6 @@ export interface UseRecordResult extends RecordState {
     /** The record again, from the server. What is shown stays while it runs, and stays if it fails. */
     refresh: () => Promise<void>;
 }
-export declare function createUseRecord(getDb: () => Pick<KoolbaseDatabase, 'get'>): (collection: string, id: string | null | undefined) => UseRecordResult;
+export declare function createUseRecord(getDb: () => Pick<KoolbaseDatabase, 'get'>): (collection: string, id: string | null | undefined, options?: {
+    live?: boolean;
+}) => UseRecordResult;

package/dist/cjs/react/use-record.js

@@ -11,13 +11,15 @@ const index_js_1 = require("../index.js");
 const noop = () => { };
 const done = () => Promise.resolve();
 function createUseRecord(getDb) {
-    return function useRecord(collection, id) {
-        const key = JSON.stringify([collection, id ?? '']);
+    return function useRecord(collection, id, options = {}) {
+        // live is part of the key: switching it starts a fresh controller.
+        const live = options.live === true;
+        const key = JSON.stringify([collection, id ?? '', ...(live ? ['live'] : [])]);
         const [current, setCurrent] = (0, react_1.useState)(null);
         (0, react_1.useEffect)(() => {
             // Created here, not during render: under React strict mode an effect
             // runs, cleans up and runs again, and each run gets its own controller.
-            const controller = new index_js_1.KoolbaseRecordController(getDb(), collection, id ?? '');
+            const controller = new index_js_1.KoolbaseRecordController(getDb(), collection, id ?? '', { live });
             setCurrent({ key, controller });
             void controller.load();
             return () => controller.dispose();

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

@@ -41,6 +41,9 @@ 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;
@@ -61,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);
@@ -71,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();
             }
         };
     }
@@ -86,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;
@@ -187,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;
@@ -199,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/cjs/record-controller.d.ts

@@ -19,7 +19,13 @@ export declare class KoolbaseRecordController {
     private readonly listeners;
     private generation;
     private disposed;
-    constructor(db: RecordReader, collection: string, id: string);
+    /** Follow this record through Koolbase realtime (see onLive). */
+    private readonly live;
+    private unlive;
+    private liveTimer;
+    constructor(db: RecordReader, collection: string, id: string, options?: {
+        live?: boolean;
+    });
     getState(): RecordState;
     /** Called on every change. Returns the unsubscribe. */
     subscribe(listener: () => void): () => void;
@@ -29,6 +35,13 @@ export declare class KoolbaseRecordController {
     refresh(): Promise<void>;
     /** Stops all updates. A result still in flight is dropped when it lands. */
     dispose(): void;
+    /**
+     * A realtime event in this record's collection. Only one naming THIS record
+     * counts: an update (or a create, for an id that reappears) re-reads it,
+     * silently -- no `refreshing` -- and once per burst (250 ms); a delete is
+     * notFound at once, and a read still in flight is dropped.
+     */
+    private onLive;
     private fetch;
     private isStale;
     private set;

package/dist/cjs/record-controller.js

@@ -13,11 +13,14 @@
 //  - refresh() keeps the record shown while it runs, and if it fails.
 //  - every fetch has a generation: a result superseded by a later refresh,
 //    or landing after dispose(), is dropped.
+//  - live (the option): realtime events for THIS record only. An update
+//    re-reads it silently, once per burst; a delete is notFound at once.
 // Not yet: an offline fallback from the record cache, which keeps data and
 // revision but not createdAt or createdBy.
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.KoolbaseRecordController = exports.initialRecordState = void 0;
 const database_errors_js_1 = require("./database-errors.js");
+const live_source_js_1 = require("./live-source.js");
 exports.initialRecordState = Object.freeze({
     status: 'loading',
     record: null,
@@ -25,14 +28,18 @@ exports.initialRecordState = Object.freeze({
     refreshing: false,
 });
 class KoolbaseRecordController {
-    constructor(db, collection, id) {
+    constructor(db, collection, id, options = {}) {
         this.state = exports.initialRecordState;
         this.listeners = new Set();
         this.generation = 0;
         this.disposed = false;
+        // The realtime subscription, and its pending debounced re-read.
+        this.unlive = null;
+        this.liveTimer = null;
         this.db = db;
         this.collection = collection;
         this.id = id;
+        this.live = options.live === true;
     }
     getState() {
         return this.state;
@@ -50,6 +57,10 @@ class KoolbaseRecordController {
     async load() {
         if (this.disposed)
             return;
+        // Live needs an id: with none there is nothing to follow.
+        if (this.live && this.id) {
+            this.unlive ?? (this.unlive = (0, live_source_js_1.liveSource)()?.subscribe(this.collection, (event) => this.onLive(event)) ?? null);
+        }
         await this.fetch();
     }
     /** The record again, from the server. What is shown stays while it runs, and stays if it fails. */
@@ -64,8 +75,45 @@ class KoolbaseRecordController {
     /** Stops all updates. A result still in flight is dropped when it lands. */
     dispose() {
         this.disposed = true;
+        this.unlive?.();
+        this.unlive = null;
+        if (this.liveTimer) {
+            clearTimeout(this.liveTimer);
+            this.liveTimer = null;
+        }
         this.listeners.clear();
     }
+    /**
+     * A realtime event in this record's collection. Only one naming THIS record
+     * counts: an update (or a create, for an id that reappears) re-reads it,
+     * silently -- no `refreshing` -- and once per burst (250 ms); a delete is
+     * notFound at once, and a read still in flight is dropped.
+     */
+    onLive(event) {
+        if (this.disposed)
+            return;
+        const e = (event ?? {});
+        const target = e.type === 'deleted' ? e.recordId : e.record?.id;
+        if (target !== this.id)
+            return;
+        if (e.type === 'deleted') {
+            if (this.liveTimer) {
+                clearTimeout(this.liveTimer);
+                this.liveTimer = null;
+            }
+            this.generation += 1;
+            this.set({ status: 'notFound', record: null, error: null, refreshing: false });
+            return;
+        }
+        if (this.liveTimer)
+            return;
+        this.liveTimer = setTimeout(() => {
+            this.liveTimer = null;
+            void this.fetch();
+        }, 250);
+        // A pending re-read must not be what keeps a Node process alive.
+        this.liveTimer.unref?.();
+    }
     async fetch() {
         const gen = ++this.generation;
         if (!this.id) {

package/dist/esm/react/use-record.d.ts

@@ -3,4 +3,6 @@ export interface UseRecordResult extends RecordState {
     /** The record again, from the server. What is shown stays while it runs, and stays if it fails. */
     refresh: () => Promise<void>;
 }
-export declare function createUseRecord(getDb: () => Pick<KoolbaseDatabase, 'get'>): (collection: string, id: string | null | undefined) => UseRecordResult;
+export declare function createUseRecord(getDb: () => Pick<KoolbaseDatabase, 'get'>): (collection: string, id: string | null | undefined, options?: {
+    live?: boolean;
+}) => UseRecordResult;

package/dist/esm/react/use-record.js

@@ -8,13 +8,15 @@ import { KoolbaseRecordController, initialRecordState, } from '../index.js';
 const noop = () => { };
 const done = () => Promise.resolve();
 export function createUseRecord(getDb) {
-    return function useRecord(collection, id) {
-        const key = JSON.stringify([collection, id ?? '']);
+    return function useRecord(collection, id, options = {}) {
+        // live is part of the key: switching it starts a fresh controller.
+        const live = options.live === true;
+        const key = JSON.stringify([collection, id ?? '', ...(live ? ['live'] : [])]);
         const [current, setCurrent] = useState(null);
         useEffect(() => {
             // Created here, not during render: under React strict mode an effect
             // runs, cleans up and runs again, and each run gets its own controller.
-            const controller = new KoolbaseRecordController(getDb(), collection, id ?? '');
+            const controller = new KoolbaseRecordController(getDb(), collection, id ?? '', { live });
             setCurrent({ key, controller });
             void controller.load();
             return () => controller.dispose();

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

@@ -38,6 +38,9 @@ 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;
@@ -58,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);
@@ -68,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();
             }
         };
     }
@@ -83,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;
@@ -184,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/dist/esm/record-controller.d.ts

@@ -19,7 +19,13 @@ export declare class KoolbaseRecordController {
     private readonly listeners;
     private generation;
     private disposed;
-    constructor(db: RecordReader, collection: string, id: string);
+    /** Follow this record through Koolbase realtime (see onLive). */
+    private readonly live;
+    private unlive;
+    private liveTimer;
+    constructor(db: RecordReader, collection: string, id: string, options?: {
+        live?: boolean;
+    });
     getState(): RecordState;
     /** Called on every change. Returns the unsubscribe. */
     subscribe(listener: () => void): () => void;
@@ -29,6 +35,13 @@ export declare class KoolbaseRecordController {
     refresh(): Promise<void>;
     /** Stops all updates. A result still in flight is dropped when it lands. */
     dispose(): void;
+    /**
+     * A realtime event in this record's collection. Only one naming THIS record
+     * counts: an update (or a create, for an id that reappears) re-reads it,
+     * silently -- no `refreshing` -- and once per burst (250 ms); a delete is
+     * notFound at once, and a read still in flight is dropped.
+     */
+    private onLive;
     private fetch;
     private isStale;
     private set;

package/dist/esm/record-controller.js

@@ -12,9 +12,12 @@
 //  - refresh() keeps the record shown while it runs, and if it fails.
 //  - every fetch has a generation: a result superseded by a later refresh,
 //    or landing after dispose(), is dropped.
+//  - live (the option): realtime events for THIS record only. An update
+//    re-reads it silently, once per burst; a delete is notFound at once.
 // Not yet: an offline fallback from the record cache, which keeps data and
 // revision but not createdAt or createdBy.
 import { KoolbaseNotFoundError } from './database-errors.js';
+import { liveSource } from './live-source.js';
 export const initialRecordState = Object.freeze({
     status: 'loading',
     record: null,
@@ -22,14 +25,18 @@ export const initialRecordState = Object.freeze({
     refreshing: false,
 });
 export class KoolbaseRecordController {
-    constructor(db, collection, id) {
+    constructor(db, collection, id, options = {}) {
         this.state = initialRecordState;
         this.listeners = new Set();
         this.generation = 0;
         this.disposed = false;
+        // The realtime subscription, and its pending debounced re-read.
+        this.unlive = null;
+        this.liveTimer = null;
         this.db = db;
         this.collection = collection;
         this.id = id;
+        this.live = options.live === true;
     }
     getState() {
         return this.state;
@@ -47,6 +54,10 @@ export class KoolbaseRecordController {
     async load() {
         if (this.disposed)
             return;
+        // Live needs an id: with none there is nothing to follow.
+        if (this.live && this.id) {
+            this.unlive ?? (this.unlive = liveSource()?.subscribe(this.collection, (event) => this.onLive(event)) ?? null);
+        }
         await this.fetch();
     }
     /** The record again, from the server. What is shown stays while it runs, and stays if it fails. */
@@ -61,8 +72,45 @@ export class KoolbaseRecordController {
     /** Stops all updates. A result still in flight is dropped when it lands. */
     dispose() {
         this.disposed = true;
+        this.unlive?.();
+        this.unlive = null;
+        if (this.liveTimer) {
+            clearTimeout(this.liveTimer);
+            this.liveTimer = null;
+        }
         this.listeners.clear();
     }
+    /**
+     * A realtime event in this record's collection. Only one naming THIS record
+     * counts: an update (or a create, for an id that reappears) re-reads it,
+     * silently -- no `refreshing` -- and once per burst (250 ms); a delete is
+     * notFound at once, and a read still in flight is dropped.
+     */
+    onLive(event) {
+        if (this.disposed)
+            return;
+        const e = (event ?? {});
+        const target = e.type === 'deleted' ? e.recordId : e.record?.id;
+        if (target !== this.id)
+            return;
+        if (e.type === 'deleted') {
+            if (this.liveTimer) {
+                clearTimeout(this.liveTimer);
+                this.liveTimer = null;
+            }
+            this.generation += 1;
+            this.set({ status: 'notFound', record: null, error: null, refreshing: false });
+            return;
+        }
+        if (this.liveTimer)
+            return;
+        this.liveTimer = setTimeout(() => {
+            this.liveTimer = null;
+            void this.fetch();
+        }, 250);
+        // A pending re-read must not be what keeps a Node process alive.
+        this.liveTimer.unref?.();
+    }
     async fetch() {
         const gen = ++this.generation;
         if (!this.id) {

package/package.json

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