@koolbase/core 12.5.1 → 12.7.0

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

@@ -38,6 +38,7 @@ export declare class KoolbaseCollectionController {
     private pageOne;
     private laterPages;
     private nextOffset;
+    private unregister;
     constructor(db: QueryReader, collection: string, query?: CollectionQuery);
     getState(): CollectionState;
     /** Called on every change. Returns the unsubscribe. */
@@ -46,6 +47,12 @@ export declare class KoolbaseCollectionController {
     load(): Promise<void>;
     /** Page one again, from the server. What is shown stays while it runs, and stays if it fails. */
     refresh(): Promise<void>;
+    /**
+     * After a write to this collection: page one again from the server,
+     * SILENTLY -- no `refreshing`, which is the user's pull-to-refresh. What is
+     * shown stays while it runs, and stays if it fails.
+     */
+    private refreshAfterWrite;
     /**
      * 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 query_refresh_js_1 = require("./query-refresh.js");
 exports.initialCollectionState = Object.freeze({
     status: 'loading',
     records: Object.freeze([]),
@@ -73,6 +74,8 @@ class KoolbaseCollectionController {
         // Where the next page starts on the server. Not records.length: once rows
         // are de-duplicated, a shifted page could otherwise be requested forever.
         this.nextOffset = 0;
+        // A write to this collection re-runs this query (query-refresh.ts).
+        this.unregister = null;
         this.db = db;
         this.collection = collection;
         this.spec = query;
@@ -93,6 +96,7 @@ class KoolbaseCollectionController {
     async load() {
         if (this.disposed)
             return;
+        this.unregister ?? (this.unregister = (0, query_refresh_js_1.registerQueryRefresher)(this.collection, () => this.refreshAfterWrite()));
         await this.firstPage('default');
     }
     /** Page one again, from the server. What is shown stays while it runs, and stays if it fails. */
@@ -104,6 +108,16 @@ class KoolbaseCollectionController {
         if (!this.isStale(gen))
             this.set({ refreshing: false });
     }
+    /**
+     * After a write to this collection: page one again from the server,
+     * SILENTLY -- no `refreshing`, which is the user's pull-to-refresh. What is
+     * shown stays while it runs, and stays if it fails.
+     */
+    async refreshAfterWrite() {
+        if (this.disposed)
+            return;
+        await this.firstPage('network-only');
+    }
     /**
      * 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
@@ -137,6 +151,8 @@ class KoolbaseCollectionController {
     /** Stops all updates. Results still in flight are dropped when they land. */
     dispose() {
         this.disposed = true;
+        this.unregister?.();
+        this.unregister = null;
         this.listeners.clear();
     }
     async firstPage(cache) {

package/dist/cjs/database.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.KoolbaseDatabase = void 0;
 const network_js_1 = require("./network.js");
+const query_refresh_js_1 = require("./query-refresh.js");
 const errors_js_1 = require("./errors.js");
 const cache_store_js_1 = require("./cache-store.js");
 const offline_state_js_1 = require("./offline-state.js");
@@ -229,6 +230,7 @@ class KoolbaseDatabase {
      */
     async invalidate(collection) {
         await (0, cache_store_js_2.invalidateCache)(this.getUserId() ?? 'anonymous', collection);
+        await (0, query_refresh_js_1.refreshCollectionQueries)(collection);
     }
     // ─── Insert (online-first with offline fallback) ───────────────────────────
     /**
@@ -252,6 +254,7 @@ class KoolbaseDatabase {
             const raw = await this.request('POST', '/v1/sdk/db/insert', { collection, data });
             const record = (0, record_js_1.recordFromWire)(raw);
             await (0, cache_store_js_2.invalidateCache)(userId, collection);
+            await (0, query_refresh_js_1.refreshCollectionQueries)(collection);
             // The response carries a fresh revision, so caching it keeps the
             // baseline current for whatever edits this record next.
             await (0, cache_store_js_1.cacheRecord)(userId, collection, record.id, record.data, record.revision);
@@ -326,6 +329,7 @@ class KoolbaseDatabase {
         // Keep the cache fresh, same intent as insert's post-success invalidate.
         const userId = this.getUserId() ?? 'anonymous';
         await (0, cache_store_js_2.invalidateCache)(userId, collection);
+        await (0, query_refresh_js_1.refreshCollectionQueries)(collection);
         await (0, cache_store_js_1.cacheRecord)(userId, collection, record.id, record.data, record.revision);
         return { record, created };
     }
@@ -345,6 +349,7 @@ class KoolbaseDatabase {
         const body = await this.request('POST', '/v1/sdk/db/delete-where', { collection, filters });
         const userId = this.getUserId() ?? 'anonymous';
         await (0, cache_store_js_2.invalidateCache)(userId, collection);
+        await (0, query_refresh_js_1.refreshCollectionQueries)(collection);
         return body.deleted ?? 0;
     }
     // ─── Batch (atomic, online-only) ────────────────────────────────────────────
@@ -408,6 +413,7 @@ class KoolbaseDatabase {
         }
         for (const col of touched) {
             await (0, cache_store_js_2.invalidateCache)(userId, col);
+            await (0, query_refresh_js_1.refreshCollectionQueries)(col);
         }
         return results;
     }
@@ -599,6 +605,7 @@ class KoolbaseDatabase {
         }
         await this.dropConflict(c.id);
         await (0, cache_store_js_2.invalidateCache)(this.getUserId() ?? 'anonymous', c.collection);
+        await (0, query_refresh_js_1.refreshCollectionQueries)(c.collection);
     }
     // ─── Update (online-first with offline fallback) ───────────────────────────
     /**
@@ -662,9 +669,13 @@ class KoolbaseDatabase {
         try {
             const raw = await this.request('PATCH', `/v1/sdk/db/records/${recordId}`, { data });
             const updated = (0, record_js_1.recordFromWire)(raw);
+            // Its collection's live queries re-run (every one, if the record's
+            // collection is not known).
+            const refreshed = updated.collection;
             if (updated.collection) {
                 await (0, cache_store_js_1.cacheRecord)(userId, updated.collection, updated.id, updated.data, updated.revision);
             }
+            await (0, query_refresh_js_1.refreshCollectionQueries)(refreshed);
             return updated;
         }
         catch (e) {
@@ -711,6 +722,9 @@ class KoolbaseDatabase {
         try {
             await this.request('DELETE', `/v1/sdk/db/records/${recordId}`);
             await (0, cache_store_js_1.removeCachedRecord)(userId, recordId);
+            // Its collection is known from the baseline when the record was seen;
+            // otherwise every live query re-runs, rather than a guess.
+            await (0, query_refresh_js_1.refreshCollectionQueries)(base?.collection);
         }
         catch (e) {
             // A server that answered has refused: a permission denial or a missing

package/dist/cjs/index.d.ts

@@ -12,6 +12,8 @@ export { KoolbaseAuth } from './auth.js';
 export { KoolbaseDatabase } from './database.js';
 export { KoolbaseCollectionController, collectionQueryKey, initialCollectionState, } from './collection-controller.js';
 export type { CollectionQuery, CollectionState, CollectionStatus } from './collection-controller.js';
+export { KoolbaseRecordController, initialRecordState } from './record-controller.js';
+export type { RecordState, RecordStatus } from './record-controller.js';
 export { KoolbaseFlags } from './flags.js';
 export { KoolbaseFunctions } from './functions.js';
 export { KoolbaseRealtime } from './realtime.js';

package/dist/cjs/index.js

@@ -19,7 +19,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.memoryPlatform = exports.getPlatform = exports.setPlatform = exports.RestoreResult = exports.koolbaseSdkVersion = exports.getOrCreateDeviceId = exports.KoolbaseMessaging = exports.isPending = exports.isFiscalized = exports.decodeFiscalResponse = exports.KoolbaseFiscalError = exports.KoolbaseFiscal = exports.disabledAnalytics = exports.KoolbaseAnalytics = exports.KoolbaseStorage = exports.KoolbaseRealtime = exports.KoolbaseFunctions = exports.KoolbaseFlags = exports.initialCollectionState = exports.collectionQueryKey = exports.KoolbaseCollectionController = exports.KoolbaseDatabase = exports.KoolbaseAuth = void 0;
+exports.memoryPlatform = exports.getPlatform = exports.setPlatform = exports.RestoreResult = exports.koolbaseSdkVersion = exports.getOrCreateDeviceId = exports.KoolbaseMessaging = exports.isPending = exports.isFiscalized = exports.decodeFiscalResponse = exports.KoolbaseFiscalError = exports.KoolbaseFiscal = exports.disabledAnalytics = exports.KoolbaseAnalytics = exports.KoolbaseStorage = exports.KoolbaseRealtime = exports.KoolbaseFunctions = exports.KoolbaseFlags = exports.initialRecordState = exports.KoolbaseRecordController = exports.initialCollectionState = exports.collectionQueryKey = exports.KoolbaseCollectionController = exports.KoolbaseDatabase = exports.KoolbaseAuth = void 0;
 __exportStar(require("./types.js"), exports);
 __exportStar(require("./errors.js"), exports);
 __exportStar(require("./network.js"), exports);
@@ -38,6 +38,9 @@ var collection_controller_js_1 = require("./collection-controller.js");
 Object.defineProperty(exports, "KoolbaseCollectionController", { enumerable: true, get: function () { return collection_controller_js_1.KoolbaseCollectionController; } });
 Object.defineProperty(exports, "collectionQueryKey", { enumerable: true, get: function () { return collection_controller_js_1.collectionQueryKey; } });
 Object.defineProperty(exports, "initialCollectionState", { enumerable: true, get: function () { return collection_controller_js_1.initialCollectionState; } });
+var record_controller_js_1 = require("./record-controller.js");
+Object.defineProperty(exports, "KoolbaseRecordController", { enumerable: true, get: function () { return record_controller_js_1.KoolbaseRecordController; } });
+Object.defineProperty(exports, "initialRecordState", { enumerable: true, get: function () { return record_controller_js_1.initialRecordState; } });
 var flags_js_1 = require("./flags.js");
 Object.defineProperty(exports, "KoolbaseFlags", { enumerable: true, get: function () { return flags_js_1.KoolbaseFlags; } });
 var functions_js_1 = require("./functions.js");

package/dist/cjs/query-refresh.d.ts

@@ -0,0 +1,10 @@
+/** Registers one live query's refresher; returns the unregister. */
+export declare function registerQueryRefresher(collection: string, refresh: () => Promise<void>): () => void;
+/**
+ * Re-runs every live query on a collection, after a write -- or every live
+ * query when the collection is not known (a delete of a record never read on
+ * this device). One after another; a failure in one never stops the others.
+ */
+export declare function refreshCollectionQueries(collection?: string): Promise<void>;
+/** Tests only. */
+export declare function clearQueryRefreshers(): void;

package/dist/cjs/query-refresh.js

@@ -0,0 +1,41 @@
+"use strict";
+// Live queries refreshed after a write -- the Flutter SDK's _refreshers and
+// refreshCollectionStreams, mirrored. A query refreshes ITSELF: a key carries
+// the collection and filters but not the ordering, limit or paging, so a
+// refresh rebuilt from a key alone would be a different query.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerQueryRefresher = registerQueryRefresher;
+exports.refreshCollectionQueries = refreshCollectionQueries;
+exports.clearQueryRefreshers = clearQueryRefreshers;
+const refreshers = new Map();
+let next = 0;
+/** Registers one live query's refresher; returns the unregister. */
+function registerQueryRefresher(collection, refresh) {
+    const key = `${collection}:${++next}`;
+    refreshers.set(key, refresh);
+    return () => {
+        refreshers.delete(key);
+    };
+}
+/**
+ * Re-runs every live query on a collection, after a write -- or every live
+ * query when the collection is not known (a delete of a record never read on
+ * this device). One after another; a failure in one never stops the others.
+ */
+async function refreshCollectionQueries(collection) {
+    const prefix = collection === undefined ? null : `${collection}:`;
+    const due = [...refreshers.entries()].filter(([k]) => prefix === null || k.startsWith(prefix)).map(([, f]) => f);
+    for (const refresh of due) {
+        try {
+            await refresh();
+        }
+        catch (e) {
+            // eslint-disable-next-line no-console
+            console.warn('[Koolbase] A live query failed to refresh after a write:', e);
+        }
+    }
+}
+/** Tests only. */
+function clearQueryRefreshers() {
+    refreshers.clear();
+}

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

@@ -0,0 +1,36 @@
+import type { KoolbaseDatabase } from './database.js';
+import type { KoolbaseRecord } from './types.js';
+export type RecordStatus = 'loading' | 'loaded' | 'notFound' | 'error';
+export interface RecordState {
+    readonly status: RecordStatus;
+    readonly record: KoolbaseRecord | null;
+    /** Why the first load failed, while status is 'error'. */
+    readonly error: unknown;
+    /** True while refresh() runs. */
+    readonly refreshing: boolean;
+}
+export declare const initialRecordState: RecordState;
+type RecordReader = Pick<KoolbaseDatabase, 'get'>;
+export declare class KoolbaseRecordController {
+    readonly collection: string;
+    readonly id: string;
+    private readonly db;
+    private state;
+    private readonly listeners;
+    private generation;
+    private disposed;
+    constructor(db: RecordReader, collection: string, id: string);
+    getState(): RecordState;
+    /** Called on every change. Returns the unsubscribe. */
+    subscribe(listener: () => void): () => void;
+    /** The first load. Call once; refresh() for later loads. */
+    load(): Promise<void>;
+    /** The record again, from the server. What is shown stays while it runs, and stays if it fails. */
+    refresh(): Promise<void>;
+    /** Stops all updates. A result still in flight is dropped when it lands. */
+    dispose(): void;
+    private fetch;
+    private isStale;
+    private set;
+}
+export {};

package/dist/cjs/record-controller.js

@@ -0,0 +1,110 @@
+"use strict";
+// One record, read by id, framework-free: the detail-screen counterpart of
+// KoolbaseCollectionController. @koolbase/react-native's useRecord wraps it.
+//
+//  - loading, loaded, notFound or error. notFound is its own state because
+//    the API answers a denied read as "not found" too (it does not reveal
+//    whether a record exists): a detail screen says "not available", not
+//    "something went wrong".
+//  - an empty id is notFound with no request: a screen opened without one.
+//  - a record from a different collection is notFound: the API names each
+//    record's collection, and a mistyped or crafted id must not put another
+//    collection's record on this screen.
+//  - 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.
+// 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");
+exports.initialRecordState = Object.freeze({
+    status: 'loading',
+    record: null,
+    error: null,
+    refreshing: false,
+});
+class KoolbaseRecordController {
+    constructor(db, collection, id) {
+        this.state = exports.initialRecordState;
+        this.listeners = new Set();
+        this.generation = 0;
+        this.disposed = false;
+        this.db = db;
+        this.collection = collection;
+        this.id = id;
+    }
+    getState() {
+        return this.state;
+    }
+    /** Called on every change. Returns the unsubscribe. */
+    subscribe(listener) {
+        if (this.disposed)
+            return () => { };
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    /** The first load. Call once; refresh() for later loads. */
+    async load() {
+        if (this.disposed)
+            return;
+        await this.fetch();
+    }
+    /** The record again, from the server. What is shown stays while it runs, and stays if it fails. */
+    async refresh() {
+        if (this.disposed)
+            return;
+        this.set({ refreshing: true });
+        const gen = await this.fetch();
+        if (!this.isStale(gen))
+            this.set({ refreshing: false });
+    }
+    /** Stops all updates. A result still in flight is dropped when it lands. */
+    dispose() {
+        this.disposed = true;
+        this.listeners.clear();
+    }
+    async fetch() {
+        const gen = ++this.generation;
+        if (!this.id) {
+            this.set({ status: 'notFound', record: null, error: null });
+            return gen;
+        }
+        try {
+            const record = await this.db.get(this.id);
+            if (this.isStale(gen))
+                return gen;
+            if (record.collection !== undefined && record.collection !== this.collection) {
+                this.set({ status: 'notFound', record: null, error: null });
+            }
+            else {
+                this.set({ status: 'loaded', record, error: null });
+            }
+        }
+        catch (error) {
+            if (this.isStale(gen))
+                return gen;
+            if (error instanceof database_errors_js_1.KoolbaseNotFoundError) {
+                this.set({ status: 'notFound', record: null, error: null });
+            }
+            else if (this.state.record === null) {
+                this.set({ status: 'error', error });
+            }
+            // Otherwise keep the record shown: stale beats blank.
+        }
+        return gen;
+    }
+    isStale(gen) {
+        return this.disposed || gen !== this.generation;
+    }
+    set(patch) {
+        if (this.disposed)
+            return;
+        this.state = Object.freeze({ ...this.state, ...patch });
+        for (const listener of [...this.listeners])
+            listener();
+    }
+}
+exports.KoolbaseRecordController = KoolbaseRecordController;

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

@@ -38,6 +38,7 @@ export declare class KoolbaseCollectionController {
     private pageOne;
     private laterPages;
     private nextOffset;
+    private unregister;
     constructor(db: QueryReader, collection: string, query?: CollectionQuery);
     getState(): CollectionState;
     /** Called on every change. Returns the unsubscribe. */
@@ -46,6 +47,12 @@ export declare class KoolbaseCollectionController {
     load(): Promise<void>;
     /** Page one again, from the server. What is shown stays while it runs, and stays if it fails. */
     refresh(): Promise<void>;
+    /**
+     * After a write to this collection: page one again from the server,
+     * SILENTLY -- no `refreshing`, which is the user's pull-to-refresh. What is
+     * shown stays while it runs, and stays if it fails.
+     */
+    private refreshAfterWrite;
     /**
      * 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 { registerQueryRefresher } from './query-refresh.js';
 export const initialCollectionState = Object.freeze({
     status: 'loading',
     records: Object.freeze([]),
@@ -69,6 +70,8 @@ export class KoolbaseCollectionController {
         // Where the next page starts on the server. Not records.length: once rows
         // are de-duplicated, a shifted page could otherwise be requested forever.
         this.nextOffset = 0;
+        // A write to this collection re-runs this query (query-refresh.ts).
+        this.unregister = null;
         this.db = db;
         this.collection = collection;
         this.spec = query;
@@ -89,6 +92,7 @@ export class KoolbaseCollectionController {
     async load() {
         if (this.disposed)
             return;
+        this.unregister ?? (this.unregister = registerQueryRefresher(this.collection, () => this.refreshAfterWrite()));
         await this.firstPage('default');
     }
     /** Page one again, from the server. What is shown stays while it runs, and stays if it fails. */
@@ -100,6 +104,16 @@ export class KoolbaseCollectionController {
         if (!this.isStale(gen))
             this.set({ refreshing: false });
     }
+    /**
+     * After a write to this collection: page one again from the server,
+     * SILENTLY -- no `refreshing`, which is the user's pull-to-refresh. What is
+     * shown stays while it runs, and stays if it fails.
+     */
+    async refreshAfterWrite() {
+        if (this.disposed)
+            return;
+        await this.firstPage('network-only');
+    }
     /**
      * 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
@@ -133,6 +147,8 @@ export class KoolbaseCollectionController {
     /** Stops all updates. Results still in flight are dropped when they land. */
     dispose() {
         this.disposed = true;
+        this.unregister?.();
+        this.unregister = null;
         this.listeners.clear();
     }
     async firstPage(cache) {

package/dist/esm/database.js

@@ -1,4 +1,5 @@
 import { koolbaseFetch } from './network.js';
+import { refreshCollectionQueries } from './query-refresh.js';
 import { KoolbaseError, KoolbaseOfflineBaselineUnavailableError, KoolbaseUnauthenticatedError, } from './errors.js';
 import { cacheRecord, getCachedRecord, removeCachedRecord } from './cache-store.js';
 import { readOfflineState, mutateOfflineState, queueWrite, } from './offline-state.js';
@@ -226,6 +227,7 @@ export class KoolbaseDatabase {
      */
     async invalidate(collection) {
         await invalidateCache(this.getUserId() ?? 'anonymous', collection);
+        await refreshCollectionQueries(collection);
     }
     // ─── Insert (online-first with offline fallback) ───────────────────────────
     /**
@@ -249,6 +251,7 @@ export class KoolbaseDatabase {
             const raw = await this.request('POST', '/v1/sdk/db/insert', { collection, data });
             const record = recordFromWire(raw);
             await invalidateCache(userId, collection);
+            await refreshCollectionQueries(collection);
             // The response carries a fresh revision, so caching it keeps the
             // baseline current for whatever edits this record next.
             await cacheRecord(userId, collection, record.id, record.data, record.revision);
@@ -323,6 +326,7 @@ export class KoolbaseDatabase {
         // Keep the cache fresh, same intent as insert's post-success invalidate.
         const userId = this.getUserId() ?? 'anonymous';
         await invalidateCache(userId, collection);
+        await refreshCollectionQueries(collection);
         await cacheRecord(userId, collection, record.id, record.data, record.revision);
         return { record, created };
     }
@@ -342,6 +346,7 @@ export class KoolbaseDatabase {
         const body = await this.request('POST', '/v1/sdk/db/delete-where', { collection, filters });
         const userId = this.getUserId() ?? 'anonymous';
         await invalidateCache(userId, collection);
+        await refreshCollectionQueries(collection);
         return body.deleted ?? 0;
     }
     // ─── Batch (atomic, online-only) ────────────────────────────────────────────
@@ -405,6 +410,7 @@ export class KoolbaseDatabase {
         }
         for (const col of touched) {
             await invalidateCache(userId, col);
+            await refreshCollectionQueries(col);
         }
         return results;
     }
@@ -596,6 +602,7 @@ export class KoolbaseDatabase {
         }
         await this.dropConflict(c.id);
         await invalidateCache(this.getUserId() ?? 'anonymous', c.collection);
+        await refreshCollectionQueries(c.collection);
     }
     // ─── Update (online-first with offline fallback) ───────────────────────────
     /**
@@ -659,9 +666,13 @@ export class KoolbaseDatabase {
         try {
             const raw = await this.request('PATCH', `/v1/sdk/db/records/${recordId}`, { data });
             const updated = recordFromWire(raw);
+            // Its collection's live queries re-run (every one, if the record's
+            // collection is not known).
+            const refreshed = updated.collection;
             if (updated.collection) {
                 await cacheRecord(userId, updated.collection, updated.id, updated.data, updated.revision);
             }
+            await refreshCollectionQueries(refreshed);
             return updated;
         }
         catch (e) {
@@ -708,6 +719,9 @@ export class KoolbaseDatabase {
         try {
             await this.request('DELETE', `/v1/sdk/db/records/${recordId}`);
             await removeCachedRecord(userId, recordId);
+            // Its collection is known from the baseline when the record was seen;
+            // otherwise every live query re-runs, rather than a guess.
+            await refreshCollectionQueries(base?.collection);
         }
         catch (e) {
             // A server that answered has refused: a permission denial or a missing

package/dist/esm/index.d.ts

@@ -12,6 +12,8 @@ export { KoolbaseAuth } from './auth.js';
 export { KoolbaseDatabase } from './database.js';
 export { KoolbaseCollectionController, collectionQueryKey, initialCollectionState, } from './collection-controller.js';
 export type { CollectionQuery, CollectionState, CollectionStatus } from './collection-controller.js';
+export { KoolbaseRecordController, initialRecordState } from './record-controller.js';
+export type { RecordState, RecordStatus } from './record-controller.js';
 export { KoolbaseFlags } from './flags.js';
 export { KoolbaseFunctions } from './functions.js';
 export { KoolbaseRealtime } from './realtime.js';

package/dist/esm/index.js

@@ -16,6 +16,7 @@ export * from './storage-errors.js';
 export { KoolbaseAuth } from './auth.js';
 export { KoolbaseDatabase } from './database.js';
 export { KoolbaseCollectionController, collectionQueryKey, initialCollectionState, } from './collection-controller.js';
+export { KoolbaseRecordController, initialRecordState } from './record-controller.js';
 export { KoolbaseFlags } from './flags.js';
 export { KoolbaseFunctions } from './functions.js';
 export { KoolbaseRealtime } from './realtime.js';

package/dist/esm/query-refresh.d.ts

@@ -0,0 +1,10 @@
+/** Registers one live query's refresher; returns the unregister. */
+export declare function registerQueryRefresher(collection: string, refresh: () => Promise<void>): () => void;
+/**
+ * Re-runs every live query on a collection, after a write -- or every live
+ * query when the collection is not known (a delete of a record never read on
+ * this device). One after another; a failure in one never stops the others.
+ */
+export declare function refreshCollectionQueries(collection?: string): Promise<void>;
+/** Tests only. */
+export declare function clearQueryRefreshers(): void;

package/dist/esm/query-refresh.js

@@ -0,0 +1,36 @@
+// Live queries refreshed after a write -- the Flutter SDK's _refreshers and
+// refreshCollectionStreams, mirrored. A query refreshes ITSELF: a key carries
+// the collection and filters but not the ordering, limit or paging, so a
+// refresh rebuilt from a key alone would be a different query.
+const refreshers = new Map();
+let next = 0;
+/** Registers one live query's refresher; returns the unregister. */
+export function registerQueryRefresher(collection, refresh) {
+    const key = `${collection}:${++next}`;
+    refreshers.set(key, refresh);
+    return () => {
+        refreshers.delete(key);
+    };
+}
+/**
+ * Re-runs every live query on a collection, after a write -- or every live
+ * query when the collection is not known (a delete of a record never read on
+ * this device). One after another; a failure in one never stops the others.
+ */
+export async function refreshCollectionQueries(collection) {
+    const prefix = collection === undefined ? null : `${collection}:`;
+    const due = [...refreshers.entries()].filter(([k]) => prefix === null || k.startsWith(prefix)).map(([, f]) => f);
+    for (const refresh of due) {
+        try {
+            await refresh();
+        }
+        catch (e) {
+            // eslint-disable-next-line no-console
+            console.warn('[Koolbase] A live query failed to refresh after a write:', e);
+        }
+    }
+}
+/** Tests only. */
+export function clearQueryRefreshers() {
+    refreshers.clear();
+}

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

@@ -0,0 +1,36 @@
+import type { KoolbaseDatabase } from './database.js';
+import type { KoolbaseRecord } from './types.js';
+export type RecordStatus = 'loading' | 'loaded' | 'notFound' | 'error';
+export interface RecordState {
+    readonly status: RecordStatus;
+    readonly record: KoolbaseRecord | null;
+    /** Why the first load failed, while status is 'error'. */
+    readonly error: unknown;
+    /** True while refresh() runs. */
+    readonly refreshing: boolean;
+}
+export declare const initialRecordState: RecordState;
+type RecordReader = Pick<KoolbaseDatabase, 'get'>;
+export declare class KoolbaseRecordController {
+    readonly collection: string;
+    readonly id: string;
+    private readonly db;
+    private state;
+    private readonly listeners;
+    private generation;
+    private disposed;
+    constructor(db: RecordReader, collection: string, id: string);
+    getState(): RecordState;
+    /** Called on every change. Returns the unsubscribe. */
+    subscribe(listener: () => void): () => void;
+    /** The first load. Call once; refresh() for later loads. */
+    load(): Promise<void>;
+    /** The record again, from the server. What is shown stays while it runs, and stays if it fails. */
+    refresh(): Promise<void>;
+    /** Stops all updates. A result still in flight is dropped when it lands. */
+    dispose(): void;
+    private fetch;
+    private isStale;
+    private set;
+}
+export {};

package/dist/esm/record-controller.js

@@ -0,0 +1,106 @@
+// One record, read by id, framework-free: the detail-screen counterpart of
+// KoolbaseCollectionController. @koolbase/react-native's useRecord wraps it.
+//
+//  - loading, loaded, notFound or error. notFound is its own state because
+//    the API answers a denied read as "not found" too (it does not reveal
+//    whether a record exists): a detail screen says "not available", not
+//    "something went wrong".
+//  - an empty id is notFound with no request: a screen opened without one.
+//  - a record from a different collection is notFound: the API names each
+//    record's collection, and a mistyped or crafted id must not put another
+//    collection's record on this screen.
+//  - 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.
+// 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';
+export const initialRecordState = Object.freeze({
+    status: 'loading',
+    record: null,
+    error: null,
+    refreshing: false,
+});
+export class KoolbaseRecordController {
+    constructor(db, collection, id) {
+        this.state = initialRecordState;
+        this.listeners = new Set();
+        this.generation = 0;
+        this.disposed = false;
+        this.db = db;
+        this.collection = collection;
+        this.id = id;
+    }
+    getState() {
+        return this.state;
+    }
+    /** Called on every change. Returns the unsubscribe. */
+    subscribe(listener) {
+        if (this.disposed)
+            return () => { };
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    /** The first load. Call once; refresh() for later loads. */
+    async load() {
+        if (this.disposed)
+            return;
+        await this.fetch();
+    }
+    /** The record again, from the server. What is shown stays while it runs, and stays if it fails. */
+    async refresh() {
+        if (this.disposed)
+            return;
+        this.set({ refreshing: true });
+        const gen = await this.fetch();
+        if (!this.isStale(gen))
+            this.set({ refreshing: false });
+    }
+    /** Stops all updates. A result still in flight is dropped when it lands. */
+    dispose() {
+        this.disposed = true;
+        this.listeners.clear();
+    }
+    async fetch() {
+        const gen = ++this.generation;
+        if (!this.id) {
+            this.set({ status: 'notFound', record: null, error: null });
+            return gen;
+        }
+        try {
+            const record = await this.db.get(this.id);
+            if (this.isStale(gen))
+                return gen;
+            if (record.collection !== undefined && record.collection !== this.collection) {
+                this.set({ status: 'notFound', record: null, error: null });
+            }
+            else {
+                this.set({ status: 'loaded', record, error: null });
+            }
+        }
+        catch (error) {
+            if (this.isStale(gen))
+                return gen;
+            if (error instanceof KoolbaseNotFoundError) {
+                this.set({ status: 'notFound', record: null, error: null });
+            }
+            else if (this.state.record === null) {
+                this.set({ status: 'error', error });
+            }
+            // Otherwise keep the record shown: stale beats blank.
+        }
+        return gen;
+    }
+    isStale(gen) {
+        return this.disposed || gen !== this.generation;
+    }
+    set(patch) {
+        if (this.disposed)
+            return;
+        this.state = Object.freeze({ ...this.state, ...patch });
+        for (const listener of [...this.listeners])
+            listener();
+    }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@koolbase/core",
-  "version": "12.5.1",
-  "description": "Koolbase SDK core \u2014 shared behaviour behind @koolbase/react-native and @koolbase/js. Install one of those, not this.",
+  "version": "12.7.0",
+  "description": "Koolbase SDK core — 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",
   "files": [