@koolbase/core 12.11.1 → 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/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/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.1",
+  "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",