@koolbase/core 12.11.1 → 12.13.0

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

@@ -11,8 +11,9 @@ export interface CollectionQuery {
     /**
      * 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.
+     * read). Signed out, only a collection anyone can read (read rule
+     * "public") is live; any other behaves as a normal list until a user signs
+     * in, and goes live then.
      */
     live?: boolean;
 }

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,9 @@ export declare class KoolbaseRealtime {
     private reconnectAttempts;
     private reconnectTimer;
     private connecting;
+    private anonymous;
+    private connectedAs;
+    private generation;
     private idleTimer;
     /** How long an unused connection stays open, in ms: a screen that comes
      *  straight back (navigating back, React's development double start)
@@ -30,6 +33,9 @@ export declare class KoolbaseRealtime {
     private connect;
     private sendSubscribe;
     private sendUnsubscribe;
+    /** A signed-out visitor's message leaves project_id out: it has none to
+     *  give, and the server uses the public key's project. */
+    private send;
     /**
      * Reconnects with backoff, rather than every three seconds forever.
      *
@@ -51,6 +57,16 @@ export declare class KoolbaseRealtime {
      * it: reconnecting needs a subscriber.
      */
     private scheduleIdleClose;
+    /**
+     * The signed-in user changed: signed in, signed out, or another user. The
+     * open connection was made for the previous session -- signed out it sees
+     * only public collections, signed in it carries that user's access -- so it
+     * is replaced by one for the new session, resubscribing every collection.
+     * The same user again (a token refresh) changes nothing, and with nothing
+     * open there is nothing to do: the next subscribe connects as whoever is
+     * signed in then.
+     */
+    sessionChanged(): void;
     disconnect(): void;
 }
 export {};

package/dist/cjs/realtime.js

@@ -41,6 +41,15 @@ class KoolbaseRealtime {
         this.reconnectAttempts = 0;
         this.reconnectTimer = null;
         this.connecting = false;
+        // The open connection is a signed-out visitor's (the public key): its
+        // messages leave project_id out.
+        this.anonymous = false;
+        // Whose session the open connection was made for: the user id, or null
+        // when signed out. sessionChanged compares against it.
+        this.connectedAs = null;
+        // Bumped by sessionChanged: a connect still waiting for its token gives up
+        // rather than open a connection for the old session.
+        this.generation = 0;
         // Pending close of an unused connection (scheduleIdleClose); null while
         // anyone is subscribed.
         this.idleTimer = null;
@@ -101,28 +110,49 @@ class KoolbaseRealtime {
         // 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;
+        const generation = this.generation;
         let token;
         try {
             token = await this.getToken();
         }
         catch {
-            token = null;
+            // A session that could not be refreshed is still a session: try again
+            // later, never as a signed-out visitor.
+            if (generation !== this.generation)
+                return;
+            this.connecting = false;
+            this.scheduleReconnect();
+            return;
         }
+        // The session changed while the token was on its way: sessionChanged
+        // has started the connection for the new one.
+        if (generation !== this.generation)
+            return;
         if (this.listeners.size === 0) {
             // Everyone left while the token was on its way: nothing to connect for.
             this.connecting = false;
             return;
         }
-        if (!token) {
+        const userId = this.getUserId?.() ?? null;
+        if (!token && userId) {
+            // Signed in, but no usable token right now: try again later rather
+            // than drop to public-only.
             this.connecting = false;
-            this.scheduleReconnect(); // sign-in may be in flight
+            this.scheduleReconnect();
             return;
         }
-        this.projectId = projectIdFromToken(token);
+        // Signed out: the project's public key, and only collections anyone can
+        // read. The server pins the connection to the key's project.
+        this.anonymous = !token;
+        this.connectedAs = token ? userId : null;
+        this.projectId = token ? projectIdFromToken(token) : null;
+        const credential = token
+            ? `token=${encodeURIComponent(token)}`
+            : `public_key=${encodeURIComponent(this.config.publicKey)}`;
         const wsUrl = this.config.baseUrl.replace('https://', 'wss://').replace('http://', 'ws://');
         let ws;
         try {
-            ws = new WebSocket(`${wsUrl}/v1/realtime/ws?token=${encodeURIComponent(token)}`);
+            ws = new WebSocket(`${wsUrl}/v1/realtime/ws?${credential}`);
         }
         catch {
             this.connecting = false;
@@ -186,14 +216,22 @@ class KoolbaseRealtime {
         ws.onerror = () => { };
     }
     sendSubscribe(collection) {
-        if (!this.projectId || !this.ws || this.ws.readyState !== WebSocket.OPEN)
-            return;
-        this.ws.send(JSON.stringify({ action: 'subscribe', project_id: this.projectId, collection }));
+        this.send('subscribe', collection);
     }
     sendUnsubscribe(collection) {
-        if (!this.projectId || !this.ws || this.ws.readyState !== WebSocket.OPEN)
+        this.send('unsubscribe', collection);
+    }
+    /** A signed-out visitor's message leaves project_id out: it has none to
+     *  give, and the server uses the public key's project. */
+    send(action, collection) {
+        if (!this.ws || this.ws.readyState !== WebSocket.OPEN)
             return;
-        this.ws.send(JSON.stringify({ action: 'unsubscribe', project_id: this.projectId, collection }));
+        if (this.anonymous) {
+            this.ws.send(JSON.stringify({ action, collection }));
+        }
+        else if (this.projectId) {
+            this.ws.send(JSON.stringify({ action, project_id: this.projectId, collection }));
+        }
     }
     /**
      * Reconnects with backoff, rather than every three seconds forever.
@@ -252,6 +290,42 @@ class KoolbaseRealtime {
         }, KoolbaseRealtime.idleGraceMs);
         this.idleTimer.unref?.();
     }
+    /**
+     * The signed-in user changed: signed in, signed out, or another user. The
+     * open connection was made for the previous session -- signed out it sees
+     * only public collections, signed in it carries that user's access -- so it
+     * is replaced by one for the new session, resubscribing every collection.
+     * The same user again (a token refresh) changes nothing, and with nothing
+     * open there is nothing to do: the next subscribe connects as whoever is
+     * signed in then.
+     */
+    sessionChanged() {
+        if (!this.ws && !this.connecting && !this.reconnectTimer)
+            return;
+        if (this.ws && !this.connecting && (this.getUserId?.() ?? null) === this.connectedAs)
+            return;
+        this.generation += 1;
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+        const ws = this.ws;
+        this.ws = null;
+        this.connecting = false;
+        this.anonymous = false;
+        this.projectId = null;
+        this.reconnectAttempts = 0;
+        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();
+        }
+        if (this.listeners.size > 0)
+            void this.connect();
+    }
     disconnect() {
         if (this.idleTimer) {
             clearTimeout(this.idleTimer);

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/collection-controller.d.ts

@@ -11,8 +11,9 @@ export interface CollectionQuery {
     /**
      * 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.
+     * read). Signed out, only a collection anyone can read (read rule
+     * "public") is live; any other behaves as a normal list until a user signs
+     * in, and goes live then.
      */
     live?: boolean;
 }

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,9 @@ export declare class KoolbaseRealtime {
     private reconnectAttempts;
     private reconnectTimer;
     private connecting;
+    private anonymous;
+    private connectedAs;
+    private generation;
     private idleTimer;
     /** How long an unused connection stays open, in ms: a screen that comes
      *  straight back (navigating back, React's development double start)
@@ -30,6 +33,9 @@ export declare class KoolbaseRealtime {
     private connect;
     private sendSubscribe;
     private sendUnsubscribe;
+    /** A signed-out visitor's message leaves project_id out: it has none to
+     *  give, and the server uses the public key's project. */
+    private send;
     /**
      * Reconnects with backoff, rather than every three seconds forever.
      *
@@ -51,6 +57,16 @@ export declare class KoolbaseRealtime {
      * it: reconnecting needs a subscriber.
      */
     private scheduleIdleClose;
+    /**
+     * The signed-in user changed: signed in, signed out, or another user. The
+     * open connection was made for the previous session -- signed out it sees
+     * only public collections, signed in it carries that user's access -- so it
+     * is replaced by one for the new session, resubscribing every collection.
+     * The same user again (a token refresh) changes nothing, and with nothing
+     * open there is nothing to do: the next subscribe connects as whoever is
+     * signed in then.
+     */
+    sessionChanged(): void;
     disconnect(): void;
 }
 export {};

package/dist/esm/realtime.js

@@ -38,6 +38,15 @@ export class KoolbaseRealtime {
         this.reconnectAttempts = 0;
         this.reconnectTimer = null;
         this.connecting = false;
+        // The open connection is a signed-out visitor's (the public key): its
+        // messages leave project_id out.
+        this.anonymous = false;
+        // Whose session the open connection was made for: the user id, or null
+        // when signed out. sessionChanged compares against it.
+        this.connectedAs = null;
+        // Bumped by sessionChanged: a connect still waiting for its token gives up
+        // rather than open a connection for the old session.
+        this.generation = 0;
         // Pending close of an unused connection (scheduleIdleClose); null while
         // anyone is subscribed.
         this.idleTimer = null;
@@ -98,28 +107,49 @@ export class KoolbaseRealtime {
         // 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;
+        const generation = this.generation;
         let token;
         try {
             token = await this.getToken();
         }
         catch {
-            token = null;
+            // A session that could not be refreshed is still a session: try again
+            // later, never as a signed-out visitor.
+            if (generation !== this.generation)
+                return;
+            this.connecting = false;
+            this.scheduleReconnect();
+            return;
         }
+        // The session changed while the token was on its way: sessionChanged
+        // has started the connection for the new one.
+        if (generation !== this.generation)
+            return;
         if (this.listeners.size === 0) {
             // Everyone left while the token was on its way: nothing to connect for.
             this.connecting = false;
             return;
         }
-        if (!token) {
+        const userId = this.getUserId?.() ?? null;
+        if (!token && userId) {
+            // Signed in, but no usable token right now: try again later rather
+            // than drop to public-only.
             this.connecting = false;
-            this.scheduleReconnect(); // sign-in may be in flight
+            this.scheduleReconnect();
             return;
         }
-        this.projectId = projectIdFromToken(token);
+        // Signed out: the project's public key, and only collections anyone can
+        // read. The server pins the connection to the key's project.
+        this.anonymous = !token;
+        this.connectedAs = token ? userId : null;
+        this.projectId = token ? projectIdFromToken(token) : null;
+        const credential = token
+            ? `token=${encodeURIComponent(token)}`
+            : `public_key=${encodeURIComponent(this.config.publicKey)}`;
         const wsUrl = this.config.baseUrl.replace('https://', 'wss://').replace('http://', 'ws://');
         let ws;
         try {
-            ws = new WebSocket(`${wsUrl}/v1/realtime/ws?token=${encodeURIComponent(token)}`);
+            ws = new WebSocket(`${wsUrl}/v1/realtime/ws?${credential}`);
         }
         catch {
             this.connecting = false;
@@ -183,14 +213,22 @@ export class KoolbaseRealtime {
         ws.onerror = () => { };
     }
     sendSubscribe(collection) {
-        if (!this.projectId || !this.ws || this.ws.readyState !== WebSocket.OPEN)
-            return;
-        this.ws.send(JSON.stringify({ action: 'subscribe', project_id: this.projectId, collection }));
+        this.send('subscribe', collection);
     }
     sendUnsubscribe(collection) {
-        if (!this.projectId || !this.ws || this.ws.readyState !== WebSocket.OPEN)
+        this.send('unsubscribe', collection);
+    }
+    /** A signed-out visitor's message leaves project_id out: it has none to
+     *  give, and the server uses the public key's project. */
+    send(action, collection) {
+        if (!this.ws || this.ws.readyState !== WebSocket.OPEN)
             return;
-        this.ws.send(JSON.stringify({ action: 'unsubscribe', project_id: this.projectId, collection }));
+        if (this.anonymous) {
+            this.ws.send(JSON.stringify({ action, collection }));
+        }
+        else if (this.projectId) {
+            this.ws.send(JSON.stringify({ action, project_id: this.projectId, collection }));
+        }
     }
     /**
      * Reconnects with backoff, rather than every three seconds forever.
@@ -249,6 +287,42 @@ export class KoolbaseRealtime {
         }, KoolbaseRealtime.idleGraceMs);
         this.idleTimer.unref?.();
     }
+    /**
+     * The signed-in user changed: signed in, signed out, or another user. The
+     * open connection was made for the previous session -- signed out it sees
+     * only public collections, signed in it carries that user's access -- so it
+     * is replaced by one for the new session, resubscribing every collection.
+     * The same user again (a token refresh) changes nothing, and with nothing
+     * open there is nothing to do: the next subscribe connects as whoever is
+     * signed in then.
+     */
+    sessionChanged() {
+        if (!this.ws && !this.connecting && !this.reconnectTimer)
+            return;
+        if (this.ws && !this.connecting && (this.getUserId?.() ?? null) === this.connectedAs)
+            return;
+        this.generation += 1;
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+        const ws = this.ws;
+        this.ws = null;
+        this.connecting = false;
+        this.anonymous = false;
+        this.projectId = null;
+        this.reconnectAttempts = 0;
+        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();
+        }
+        if (this.listeners.size > 0)
+            void this.connect();
+    }
     disconnect() {
         if (this.idleTimer) {
             clearTimeout(this.idleTimer);

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.13.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",