@koolbase/core 12.3.0 → 12.5.0

package/dist/cjs/analytics.d.ts

@@ -36,3 +36,9 @@ export declare class KoolbaseAnalytics {
     flush(): Promise<void>;
     dispose(): Promise<void>;
 }
+/**
+ * What Koolbase.analytics is while analytics is off (the default since 12.4.0).
+ * Every call does nothing, and the first says once how to turn it on, so an app
+ * that tracks events without opting in keeps working instead of crashing.
+ */
+export declare function disabledAnalytics(): KoolbaseAnalytics;

package/dist/cjs/analytics.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.KoolbaseAnalytics = void 0;
+exports.disabledAnalytics = disabledAnalytics;
 const network_js_1 = require("./network.js");
 const platform_js_1 = require("./platform.js");
 const device_id_js_1 = require("./device-id.js");
@@ -129,3 +130,20 @@ class KoolbaseAnalytics {
     }
 }
 exports.KoolbaseAnalytics = KoolbaseAnalytics;
+/**
+ * What Koolbase.analytics is while analytics is off (the default since 12.4.0).
+ * Every call does nothing, and the first says once how to turn it on, so an app
+ * that tracks events without opting in keeps working instead of crashing.
+ */
+function disabledAnalytics() {
+    let told = false;
+    const noop = () => {
+        if (!told) {
+            told = true;
+            // eslint-disable-next-line no-console
+            console.info('[Koolbase] Analytics is off: it is opt-in since 12.4.0. Pass analyticsEnabled: true to Koolbase.initialize to send events.');
+        }
+        return Promise.resolve();
+    };
+    return new Proxy({}, { get: (_t, prop) => (prop === 'then' ? undefined : noop) });
+}

package/dist/cjs/cache-store.d.ts

@@ -1,4 +1,14 @@
 import { KoolbaseRecord, LegacyPendingWrite, QueryResult } from './types.js';
+/**
+ * A query's identity in the cache. Keys are sorted at every depth, so options
+ * that differ only in key order ({ a, b } and { b, a }) share one entry.
+ * Array order is kept: it can matter. Undefined values and functions are left
+ * out, as JSON.stringify does.
+ *
+ * Changing this only strands earlier entries, which are fetched again and
+ * removed by the next invalidateCache for their collection. CACHE_VERSION is
+ * not the tool for a clean start: the write queue's key carries it too.
+ */
 export declare function hashQuery(collection: string, options: Record<string, unknown>): string;
 export declare function getCached(userId: string, collection: string, queryHash: string): Promise<QueryResult | null>;
 export declare function setCached(userId: string, collection: string, queryHash: string, result: QueryResult): Promise<void>;

package/dist/cjs/cache-store.js

@@ -21,8 +21,27 @@ function cacheKey(userId, collection, queryHash) {
 function writeQueueKey(userId) {
     return `koolbase:${CACHE_VERSION}:${userId}:write_queue`;
 }
+/**
+ * A query's identity in the cache. Keys are sorted at every depth, so options
+ * that differ only in key order ({ a, b } and { b, a }) share one entry.
+ * Array order is kept: it can matter. Undefined values and functions are left
+ * out, as JSON.stringify does.
+ *
+ * Changing this only strands earlier entries, which are fetched again and
+ * removed by the next invalidateCache for their collection. CACHE_VERSION is
+ * not the tool for a clean start: the write queue's key carries it too.
+ */
 function hashQuery(collection, options) {
-    return `${collection}:${JSON.stringify(options)}`;
+    return `${collection}:${JSON.stringify(options, sortKeys)}`;
+}
+function sortKeys(_key, value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return value;
+    const source = value;
+    const sorted = {};
+    for (const key of Object.keys(source).sort())
+        sorted[key] = source[key];
+    return sorted;
 }
 // ─── Cache ──────────────────────────────────────────────────────────────────
 async function getCached(userId, collection, queryHash) {

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

@@ -0,0 +1,64 @@
+import type { KoolbaseDatabase } from './database.js';
+import type { KoolbaseRecord } from './types.js';
+export type CollectionStatus = 'loading' | 'loaded' | 'error';
+/** What to read. Equality only: each `where` entry is field = literal value. */
+export interface CollectionQuery {
+    where?: Record<string, unknown>;
+    orderBy?: string;
+    orderDesc?: boolean;
+    /** Page size; the server's default (20) when absent. */
+    limit?: number;
+}
+export interface CollectionState {
+    readonly status: CollectionStatus;
+    readonly records: readonly KoolbaseRecord[];
+    /** Why the first load failed, while status is 'error'. */
+    readonly error: unknown;
+    /** True while the records shown came from cache and the server has not answered yet. */
+    readonly isFromCache: boolean;
+    /** True while refresh() runs. */
+    readonly refreshing: boolean;
+    /** True while loadMore() runs. */
+    readonly loadingMore: boolean;
+    /** Whether the server has rows past the last page loaded. True before the first load. */
+    readonly hasMore: boolean;
+}
+export declare const initialCollectionState: CollectionState;
+/** One string per distinct query, whatever the order of its `where` keys. */
+export declare function collectionQueryKey(collection: string, query?: CollectionQuery): string;
+type QueryReader = Pick<KoolbaseDatabase, 'query'>;
+export declare class KoolbaseCollectionController {
+    readonly collection: string;
+    private readonly db;
+    private readonly spec;
+    private state;
+    private readonly listeners;
+    private generation;
+    private disposed;
+    private pageOne;
+    private laterPages;
+    private nextOffset;
+    constructor(db: QueryReader, collection: string, query?: CollectionQuery);
+    getState(): CollectionState;
+    /** Called on every change. Returns the unsubscribe. */
+    subscribe(listener: () => void): () => void;
+    /** The first load. Call once; refresh() for later loads. */
+    load(): Promise<void>;
+    /** Page one again, from the server. What is shown stays while it runs, and stays if it fails. */
+    refresh(): Promise<void>;
+    /**
+     * 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
+     * skipped until refresh(); none is ever shown twice.
+     */
+    loadMore(): Promise<void>;
+    /** Stops all updates. Results still in flight are dropped when they land. */
+    dispose(): void;
+    private firstPage;
+    private showPageOne;
+    private publish;
+    private options;
+    private isStale;
+    private set;
+}
+export {};

package/dist/cjs/collection-controller.js

@@ -0,0 +1,204 @@
+"use strict";
+// A collection read as a list, framework-free.
+//
+// The data half of a list screen: loading, loaded or error, refresh, and
+// paging. No React here, so it is tested in this package and any host can
+// drive it; @koolbase/react-native's useCollection is a thin wrapper.
+//
+// Mirrors the Flutter SDK's KoolbaseCollectionController:
+//  - the first load is cache-first, and when the cache answered, the
+//    server's answer replaces it as soon as it lands (query's onRefresh)
+//  - only a first load with nothing to show is the error state; a failed
+//    refresh or loadMore keeps what is shown (stale beats blank)
+//  - loadMore appends the next page while there is more
+// Deliberate differences:
+//  - refresh() waits for the server (network-only), so `refreshing` ends
+//    when fresh records are in, not when the cache answered
+//  - a background refresh replaces page one only; pages loadMore appended
+//    after it stay, merged by record id so no row is shown twice
+//  - every fetch belongs to a generation: a result from a fetch a later
+//    refresh superseded, or one landing after dispose(), is dropped
+//
+// 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.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KoolbaseCollectionController = exports.initialCollectionState = void 0;
+exports.collectionQueryKey = collectionQueryKey;
+exports.initialCollectionState = Object.freeze({
+    status: 'loading',
+    records: Object.freeze([]),
+    error: null,
+    isFromCache: false,
+    refreshing: false,
+    loadingMore: false,
+    hasMore: true,
+});
+function sortedWhere(where) {
+    const out = {};
+    for (const key of Object.keys(where ?? {}).sort())
+        out[key] = where[key];
+    return out;
+}
+/** One string per distinct query, whatever the order of its `where` keys. */
+function collectionQueryKey(collection, query = {}) {
+    return JSON.stringify([
+        collection,
+        sortedWhere(query.where),
+        query.orderBy ?? null,
+        query.orderDesc === true,
+        query.limit ?? null,
+    ]);
+}
+/** Page one, then the later pages without any record already shown. */
+function mergeById(first, rest) {
+    const seen = new Set(first.map((r) => r.id));
+    const out = [...first];
+    for (const record of rest) {
+        if (seen.has(record.id))
+            continue;
+        seen.add(record.id);
+        out.push(record);
+    }
+    return out;
+}
+class KoolbaseCollectionController {
+    constructor(db, collection, query = {}) {
+        this.state = exports.initialCollectionState;
+        this.listeners = new Set();
+        this.generation = 0;
+        this.disposed = false;
+        this.pageOne = [];
+        this.laterPages = [];
+        // 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;
+        this.db = db;
+        this.collection = collection;
+        this.spec = query;
+    }
+    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.firstPage('default');
+    }
+    /** Page one 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.firstPage('network-only');
+        if (!this.isStale(gen))
+            this.set({ refreshing: false });
+    }
+    /**
+     * 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
+     * skipped until refresh(); none is ever shown twice.
+     */
+    async loadMore() {
+        const s = this.state;
+        if (this.disposed || s.loadingMore || !s.hasMore || s.status !== 'loaded')
+            return;
+        const gen = this.generation;
+        const offset = this.nextOffset;
+        this.set({ loadingMore: true });
+        try {
+            const result = await this.db.query(this.collection, this.options(offset, 'default'));
+            if (this.isStale(gen))
+                return;
+            this.laterPages = [...this.laterPages, ...result.records];
+            this.nextOffset = offset + result.records.length;
+            // An empty page is the end, whatever total says: rows were removed.
+            const total = result.records.length === 0 ? this.nextOffset : result.total;
+            this.publish({}, total);
+        }
+        catch {
+            // Keep what is shown; the caller can try again.
+        }
+        finally {
+            if (!this.isStale(gen))
+                this.set({ loadingMore: false });
+        }
+    }
+    /** Stops all updates. Results still in flight are dropped when they land. */
+    dispose() {
+        this.disposed = true;
+        this.listeners.clear();
+    }
+    async firstPage(cache) {
+        const gen = ++this.generation;
+        // A loadMore still in flight now belongs to an older generation and
+        // will not clear its own flag.
+        if (this.state.loadingMore)
+            this.set({ loadingMore: false });
+        try {
+            const result = await this.db.query(this.collection, this.options(0, cache, (fresh) => {
+                if (!this.isStale(gen))
+                    this.showPageOne(fresh, false, true);
+            }));
+            if (!this.isStale(gen))
+                this.showPageOne(result, result.isFromCache === true, false);
+        }
+        catch (error) {
+            if (!this.isStale(gen) && this.state.records.length === 0) {
+                this.set({ status: 'error', error });
+            }
+        }
+        return gen;
+    }
+    showPageOne(result, isFromCache, keepLaterPages) {
+        this.pageOne = result.records;
+        if (keepLaterPages && this.laterPages.length > 0) {
+            this.nextOffset = Math.max(this.nextOffset, result.records.length);
+        }
+        else {
+            this.laterPages = [];
+            this.nextOffset = result.records.length;
+        }
+        this.publish({ status: 'loaded', error: null, isFromCache }, result.total);
+    }
+    publish(patch, total) {
+        this.set({
+            ...patch,
+            records: mergeById(this.pageOne, this.laterPages),
+            hasMore: this.nextOffset < total,
+        });
+    }
+    // Key order does not matter: the SDK's cache key sorts keys (hashQuery).
+    options(offset, cache, onRefresh) {
+        return {
+            filters: this.spec.where ?? {},
+            limit: this.spec.limit,
+            offset,
+            orderBy: this.spec.orderBy,
+            orderDesc: this.spec.orderDesc,
+            cache,
+            onRefresh,
+        };
+    }
+    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.KoolbaseCollectionController = KoolbaseCollectionController;

package/dist/cjs/database.js

@@ -199,13 +199,20 @@ class KoolbaseDatabase {
     async query(collection, options = {}) {
         const userId = this.getUserId() ?? 'anonymous';
         // The cache policy is how to read, not what to read: it stays out of the
-        // query's identity, so both policies share one cache entry.
-        const { cache: cachePolicy, ...queryOptions } = options;
+        // query's identity, so both policies share one cache entry. onRefresh is
+        // who to tell, not what to read, so it stays out the same way.
+        const { cache: cachePolicy, onRefresh, ...queryOptions } = options;
         const queryHash = (0, cache_store_js_2.hashQuery)(collection, queryOptions);
         const cached = cachePolicy === 'network-only' ? null : await (0, cache_store_js_2.getCached)(userId, collection, queryHash);
         if (cached) {
             this.runQuery(collection, queryOptions)
-                .then(result => (0, cache_store_js_2.setCached)(userId, collection, queryHash, result))
+                .then(async (result) => {
+                await (0, cache_store_js_2.setCached)(userId, collection, queryHash, result);
+                // Told outside the catch below, which is for the network: an
+                // exception from the caller's callback is the caller's to see.
+                if (onRefresh)
+                    queueMicrotask(() => onRefresh({ ...result, isFromCache: false }));
+            })
                 .catch(() => {
                 // Network unavailable — cached data already returned
             });

package/dist/cjs/index.d.ts

@@ -10,11 +10,13 @@ export * from './database-errors.js';
 export * from './storage-errors.js';
 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 { KoolbaseFlags } from './flags.js';
 export { KoolbaseFunctions } from './functions.js';
 export { KoolbaseRealtime } from './realtime.js';
 export { KoolbaseStorage } from './storage.js';
-export { KoolbaseAnalytics } from './analytics.js';
+export { KoolbaseAnalytics, disabledAnalytics } from './analytics.js';
 export { KoolbaseFiscal, KoolbaseFiscalError, decodeFiscalResponse, isFiscalized, isPending } from './fiscal.js';
 export type { FiscalIntentResult, FiscalStatus } from './fiscal.js';
 export { KoolbaseMessaging } from './messaging.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.KoolbaseAnalytics = exports.KoolbaseStorage = exports.KoolbaseRealtime = exports.KoolbaseFunctions = exports.KoolbaseFlags = 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.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);
@@ -34,6 +34,10 @@ var auth_js_1 = require("./auth.js");
 Object.defineProperty(exports, "KoolbaseAuth", { enumerable: true, get: function () { return auth_js_1.KoolbaseAuth; } });
 var database_js_1 = require("./database.js");
 Object.defineProperty(exports, "KoolbaseDatabase", { enumerable: true, get: function () { return database_js_1.KoolbaseDatabase; } });
+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 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");
@@ -44,6 +48,7 @@ var storage_js_1 = require("./storage.js");
 Object.defineProperty(exports, "KoolbaseStorage", { enumerable: true, get: function () { return storage_js_1.KoolbaseStorage; } });
 var analytics_js_1 = require("./analytics.js");
 Object.defineProperty(exports, "KoolbaseAnalytics", { enumerable: true, get: function () { return analytics_js_1.KoolbaseAnalytics; } });
+Object.defineProperty(exports, "disabledAnalytics", { enumerable: true, get: function () { return analytics_js_1.disabledAnalytics; } });
 var fiscal_js_1 = require("./fiscal.js");
 Object.defineProperty(exports, "KoolbaseFiscal", { enumerable: true, get: function () { return fiscal_js_1.KoolbaseFiscal; } });
 Object.defineProperty(exports, "KoolbaseFiscalError", { enumerable: true, get: function () { return fiscal_js_1.KoolbaseFiscalError; } });

package/dist/cjs/network.d.ts

@@ -11,6 +11,8 @@
  */
 export declare class KoolbaseNetworkError extends TypeError {
     code: string;
+    /** A short message that is safe to show to people; `message` is for developers. */
+    readonly userMessage = "We can't connect right now. Check your connection and try again.";
     readonly url: string;
     readonly origin?: string;
     constructor(url: string, cause: unknown);

package/dist/cjs/network.js

@@ -31,6 +31,8 @@ class KoolbaseNetworkError extends TypeError {
             : ' Check the network connection and the configured base URL.';
         super(message);
         this.code = 'network_error';
+        /** A short message that is safe to show to people; `message` is for developers. */
+        this.userMessage = "We can't connect right now. Check your connection and try again.";
         this.name = 'KoolbaseNetworkError';
         this.url = url;
         this.origin = origin;

package/dist/cjs/types.d.ts

@@ -246,6 +246,13 @@ export interface QueryOptions {
      * make, by a Function or another user, when you need the server's state now.
      */
     cache?: 'default' | 'network-only';
+    /**
+     * Called once with the server's result when a cache hit's background
+     * refresh lands, so a screen showing the cached result can show the fresh
+     * one. Not called on a cache miss (the awaited result is already the
+     * server's) or when the refresh fails. Not part of the query's identity.
+     */
+    onRefresh?: (result: QueryResult) => void;
 }
 export interface QueryResult {
     records: KoolbaseRecord[];

package/dist/esm/analytics.d.ts

@@ -36,3 +36,9 @@ export declare class KoolbaseAnalytics {
     flush(): Promise<void>;
     dispose(): Promise<void>;
 }
+/**
+ * What Koolbase.analytics is while analytics is off (the default since 12.4.0).
+ * Every call does nothing, and the first says once how to turn it on, so an app
+ * that tracks events without opting in keeps working instead of crashing.
+ */
+export declare function disabledAnalytics(): KoolbaseAnalytics;

package/dist/esm/analytics.js

@@ -125,3 +125,20 @@ export class KoolbaseAnalytics {
         await this.flush();
     }
 }
+/**
+ * What Koolbase.analytics is while analytics is off (the default since 12.4.0).
+ * Every call does nothing, and the first says once how to turn it on, so an app
+ * that tracks events without opting in keeps working instead of crashing.
+ */
+export function disabledAnalytics() {
+    let told = false;
+    const noop = () => {
+        if (!told) {
+            told = true;
+            // eslint-disable-next-line no-console
+            console.info('[Koolbase] Analytics is off: it is opt-in since 12.4.0. Pass analyticsEnabled: true to Koolbase.initialize to send events.');
+        }
+        return Promise.resolve();
+    };
+    return new Proxy({}, { get: (_t, prop) => (prop === 'then' ? undefined : noop) });
+}

package/dist/esm/cache-store.d.ts

@@ -1,4 +1,14 @@
 import { KoolbaseRecord, LegacyPendingWrite, QueryResult } from './types.js';
+/**
+ * A query's identity in the cache. Keys are sorted at every depth, so options
+ * that differ only in key order ({ a, b } and { b, a }) share one entry.
+ * Array order is kept: it can matter. Undefined values and functions are left
+ * out, as JSON.stringify does.
+ *
+ * Changing this only strands earlier entries, which are fetched again and
+ * removed by the next invalidateCache for their collection. CACHE_VERSION is
+ * not the tool for a clean start: the write queue's key carries it too.
+ */
 export declare function hashQuery(collection: string, options: Record<string, unknown>): string;
 export declare function getCached(userId: string, collection: string, queryHash: string): Promise<QueryResult | null>;
 export declare function setCached(userId: string, collection: string, queryHash: string, result: QueryResult): Promise<void>;

package/dist/esm/cache-store.js

@@ -6,8 +6,27 @@ function cacheKey(userId, collection, queryHash) {
 function writeQueueKey(userId) {
     return `koolbase:${CACHE_VERSION}:${userId}:write_queue`;
 }
+/**
+ * A query's identity in the cache. Keys are sorted at every depth, so options
+ * that differ only in key order ({ a, b } and { b, a }) share one entry.
+ * Array order is kept: it can matter. Undefined values and functions are left
+ * out, as JSON.stringify does.
+ *
+ * Changing this only strands earlier entries, which are fetched again and
+ * removed by the next invalidateCache for their collection. CACHE_VERSION is
+ * not the tool for a clean start: the write queue's key carries it too.
+ */
 export function hashQuery(collection, options) {
-    return `${collection}:${JSON.stringify(options)}`;
+    return `${collection}:${JSON.stringify(options, sortKeys)}`;
+}
+function sortKeys(_key, value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return value;
+    const source = value;
+    const sorted = {};
+    for (const key of Object.keys(source).sort())
+        sorted[key] = source[key];
+    return sorted;
 }
 // ─── Cache ──────────────────────────────────────────────────────────────────
 export async function getCached(userId, collection, queryHash) {

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

@@ -0,0 +1,64 @@
+import type { KoolbaseDatabase } from './database.js';
+import type { KoolbaseRecord } from './types.js';
+export type CollectionStatus = 'loading' | 'loaded' | 'error';
+/** What to read. Equality only: each `where` entry is field = literal value. */
+export interface CollectionQuery {
+    where?: Record<string, unknown>;
+    orderBy?: string;
+    orderDesc?: boolean;
+    /** Page size; the server's default (20) when absent. */
+    limit?: number;
+}
+export interface CollectionState {
+    readonly status: CollectionStatus;
+    readonly records: readonly KoolbaseRecord[];
+    /** Why the first load failed, while status is 'error'. */
+    readonly error: unknown;
+    /** True while the records shown came from cache and the server has not answered yet. */
+    readonly isFromCache: boolean;
+    /** True while refresh() runs. */
+    readonly refreshing: boolean;
+    /** True while loadMore() runs. */
+    readonly loadingMore: boolean;
+    /** Whether the server has rows past the last page loaded. True before the first load. */
+    readonly hasMore: boolean;
+}
+export declare const initialCollectionState: CollectionState;
+/** One string per distinct query, whatever the order of its `where` keys. */
+export declare function collectionQueryKey(collection: string, query?: CollectionQuery): string;
+type QueryReader = Pick<KoolbaseDatabase, 'query'>;
+export declare class KoolbaseCollectionController {
+    readonly collection: string;
+    private readonly db;
+    private readonly spec;
+    private state;
+    private readonly listeners;
+    private generation;
+    private disposed;
+    private pageOne;
+    private laterPages;
+    private nextOffset;
+    constructor(db: QueryReader, collection: string, query?: CollectionQuery);
+    getState(): CollectionState;
+    /** Called on every change. Returns the unsubscribe. */
+    subscribe(listener: () => void): () => void;
+    /** The first load. Call once; refresh() for later loads. */
+    load(): Promise<void>;
+    /** Page one again, from the server. What is shown stays while it runs, and stays if it fails. */
+    refresh(): Promise<void>;
+    /**
+     * 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
+     * skipped until refresh(); none is ever shown twice.
+     */
+    loadMore(): Promise<void>;
+    /** Stops all updates. Results still in flight are dropped when they land. */
+    dispose(): void;
+    private firstPage;
+    private showPageOne;
+    private publish;
+    private options;
+    private isStale;
+    private set;
+}
+export {};

package/dist/esm/collection-controller.js

@@ -0,0 +1,199 @@
+// A collection read as a list, framework-free.
+//
+// The data half of a list screen: loading, loaded or error, refresh, and
+// paging. No React here, so it is tested in this package and any host can
+// drive it; @koolbase/react-native's useCollection is a thin wrapper.
+//
+// Mirrors the Flutter SDK's KoolbaseCollectionController:
+//  - the first load is cache-first, and when the cache answered, the
+//    server's answer replaces it as soon as it lands (query's onRefresh)
+//  - only a first load with nothing to show is the error state; a failed
+//    refresh or loadMore keeps what is shown (stale beats blank)
+//  - loadMore appends the next page while there is more
+// Deliberate differences:
+//  - refresh() waits for the server (network-only), so `refreshing` ends
+//    when fresh records are in, not when the cache answered
+//  - a background refresh replaces page one only; pages loadMore appended
+//    after it stay, merged by record id so no row is shown twice
+//  - every fetch belongs to a generation: a result from a fetch a later
+//    refresh superseded, or one landing after dispose(), is dropped
+//
+// 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.
+export const initialCollectionState = Object.freeze({
+    status: 'loading',
+    records: Object.freeze([]),
+    error: null,
+    isFromCache: false,
+    refreshing: false,
+    loadingMore: false,
+    hasMore: true,
+});
+function sortedWhere(where) {
+    const out = {};
+    for (const key of Object.keys(where ?? {}).sort())
+        out[key] = where[key];
+    return out;
+}
+/** One string per distinct query, whatever the order of its `where` keys. */
+export function collectionQueryKey(collection, query = {}) {
+    return JSON.stringify([
+        collection,
+        sortedWhere(query.where),
+        query.orderBy ?? null,
+        query.orderDesc === true,
+        query.limit ?? null,
+    ]);
+}
+/** Page one, then the later pages without any record already shown. */
+function mergeById(first, rest) {
+    const seen = new Set(first.map((r) => r.id));
+    const out = [...first];
+    for (const record of rest) {
+        if (seen.has(record.id))
+            continue;
+        seen.add(record.id);
+        out.push(record);
+    }
+    return out;
+}
+export class KoolbaseCollectionController {
+    constructor(db, collection, query = {}) {
+        this.state = initialCollectionState;
+        this.listeners = new Set();
+        this.generation = 0;
+        this.disposed = false;
+        this.pageOne = [];
+        this.laterPages = [];
+        // 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;
+        this.db = db;
+        this.collection = collection;
+        this.spec = query;
+    }
+    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.firstPage('default');
+    }
+    /** Page one 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.firstPage('network-only');
+        if (!this.isStale(gen))
+            this.set({ refreshing: false });
+    }
+    /**
+     * 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
+     * skipped until refresh(); none is ever shown twice.
+     */
+    async loadMore() {
+        const s = this.state;
+        if (this.disposed || s.loadingMore || !s.hasMore || s.status !== 'loaded')
+            return;
+        const gen = this.generation;
+        const offset = this.nextOffset;
+        this.set({ loadingMore: true });
+        try {
+            const result = await this.db.query(this.collection, this.options(offset, 'default'));
+            if (this.isStale(gen))
+                return;
+            this.laterPages = [...this.laterPages, ...result.records];
+            this.nextOffset = offset + result.records.length;
+            // An empty page is the end, whatever total says: rows were removed.
+            const total = result.records.length === 0 ? this.nextOffset : result.total;
+            this.publish({}, total);
+        }
+        catch {
+            // Keep what is shown; the caller can try again.
+        }
+        finally {
+            if (!this.isStale(gen))
+                this.set({ loadingMore: false });
+        }
+    }
+    /** Stops all updates. Results still in flight are dropped when they land. */
+    dispose() {
+        this.disposed = true;
+        this.listeners.clear();
+    }
+    async firstPage(cache) {
+        const gen = ++this.generation;
+        // A loadMore still in flight now belongs to an older generation and
+        // will not clear its own flag.
+        if (this.state.loadingMore)
+            this.set({ loadingMore: false });
+        try {
+            const result = await this.db.query(this.collection, this.options(0, cache, (fresh) => {
+                if (!this.isStale(gen))
+                    this.showPageOne(fresh, false, true);
+            }));
+            if (!this.isStale(gen))
+                this.showPageOne(result, result.isFromCache === true, false);
+        }
+        catch (error) {
+            if (!this.isStale(gen) && this.state.records.length === 0) {
+                this.set({ status: 'error', error });
+            }
+        }
+        return gen;
+    }
+    showPageOne(result, isFromCache, keepLaterPages) {
+        this.pageOne = result.records;
+        if (keepLaterPages && this.laterPages.length > 0) {
+            this.nextOffset = Math.max(this.nextOffset, result.records.length);
+        }
+        else {
+            this.laterPages = [];
+            this.nextOffset = result.records.length;
+        }
+        this.publish({ status: 'loaded', error: null, isFromCache }, result.total);
+    }
+    publish(patch, total) {
+        this.set({
+            ...patch,
+            records: mergeById(this.pageOne, this.laterPages),
+            hasMore: this.nextOffset < total,
+        });
+    }
+    // Key order does not matter: the SDK's cache key sorts keys (hashQuery).
+    options(offset, cache, onRefresh) {
+        return {
+            filters: this.spec.where ?? {},
+            limit: this.spec.limit,
+            offset,
+            orderBy: this.spec.orderBy,
+            orderDesc: this.spec.orderDesc,
+            cache,
+            onRefresh,
+        };
+    }
+    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/dist/esm/database.js

@@ -196,13 +196,20 @@ export class KoolbaseDatabase {
     async query(collection, options = {}) {
         const userId = this.getUserId() ?? 'anonymous';
         // The cache policy is how to read, not what to read: it stays out of the
-        // query's identity, so both policies share one cache entry.
-        const { cache: cachePolicy, ...queryOptions } = options;
+        // query's identity, so both policies share one cache entry. onRefresh is
+        // who to tell, not what to read, so it stays out the same way.
+        const { cache: cachePolicy, onRefresh, ...queryOptions } = options;
         const queryHash = hashQuery(collection, queryOptions);
         const cached = cachePolicy === 'network-only' ? null : await getCached(userId, collection, queryHash);
         if (cached) {
             this.runQuery(collection, queryOptions)
-                .then(result => setCached(userId, collection, queryHash, result))
+                .then(async (result) => {
+                await setCached(userId, collection, queryHash, result);
+                // Told outside the catch below, which is for the network: an
+                // exception from the caller's callback is the caller's to see.
+                if (onRefresh)
+                    queueMicrotask(() => onRefresh({ ...result, isFromCache: false }));
+            })
                 .catch(() => {
                 // Network unavailable — cached data already returned
             });

package/dist/esm/index.d.ts

@@ -10,11 +10,13 @@ export * from './database-errors.js';
 export * from './storage-errors.js';
 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 { KoolbaseFlags } from './flags.js';
 export { KoolbaseFunctions } from './functions.js';
 export { KoolbaseRealtime } from './realtime.js';
 export { KoolbaseStorage } from './storage.js';
-export { KoolbaseAnalytics } from './analytics.js';
+export { KoolbaseAnalytics, disabledAnalytics } from './analytics.js';
 export { KoolbaseFiscal, KoolbaseFiscalError, decodeFiscalResponse, isFiscalized, isPending } from './fiscal.js';
 export type { FiscalIntentResult, FiscalStatus } from './fiscal.js';
 export { KoolbaseMessaging } from './messaging.js';

package/dist/esm/index.js

@@ -15,11 +15,12 @@ export * from './database-errors.js';
 export * from './storage-errors.js';
 export { KoolbaseAuth } from './auth.js';
 export { KoolbaseDatabase } from './database.js';
+export { KoolbaseCollectionController, collectionQueryKey, initialCollectionState, } from './collection-controller.js';
 export { KoolbaseFlags } from './flags.js';
 export { KoolbaseFunctions } from './functions.js';
 export { KoolbaseRealtime } from './realtime.js';
 export { KoolbaseStorage } from './storage.js';
-export { KoolbaseAnalytics } from './analytics.js';
+export { KoolbaseAnalytics, disabledAnalytics } from './analytics.js';
 export { KoolbaseFiscal, KoolbaseFiscalError, decodeFiscalResponse, isFiscalized, isPending } from './fiscal.js';
 export { KoolbaseMessaging } from './messaging.js';
 export { getOrCreateDeviceId } from './device-id.js';

package/dist/esm/network.d.ts

@@ -11,6 +11,8 @@
  */
 export declare class KoolbaseNetworkError extends TypeError {
     code: string;
+    /** A short message that is safe to show to people; `message` is for developers. */
+    readonly userMessage = "We can't connect right now. Check your connection and try again.";
     readonly url: string;
     readonly origin?: string;
     constructor(url: string, cause: unknown);

package/dist/esm/network.js

@@ -27,6 +27,8 @@ export class KoolbaseNetworkError extends TypeError {
             : ' Check the network connection and the configured base URL.';
         super(message);
         this.code = 'network_error';
+        /** A short message that is safe to show to people; `message` is for developers. */
+        this.userMessage = "We can't connect right now. Check your connection and try again.";
         this.name = 'KoolbaseNetworkError';
         this.url = url;
         this.origin = origin;

package/dist/esm/types.d.ts

@@ -246,6 +246,13 @@ export interface QueryOptions {
      * make, by a Function or another user, when you need the server's state now.
      */
     cache?: 'default' | 'network-only';
+    /**
+     * Called once with the server's result when a cache hit's background
+     * refresh lands, so a screen showing the cached result can show the fresh
+     * one. Not called on a cache miss (the awaited result is already the
+     * server's) or when the refresh fails. Not part of the query's identity.
+     */
+    onRefresh?: (result: QueryResult) => void;
 }
 export interface QueryResult {
     records: KoolbaseRecord[];

package/package.json

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