@sovaria/sdk 0.0.0-stage → 0.4.0

package/dist/offline.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Offline-first documents (plan C4): keep working with no connection, sync when it comes back.
+ *
+ * ```ts
+ * const sov = new SovariaSDK({ projectUrl, anonKey })
+ * const offline = sov.enableOffline({ storage: indexedDbStorage() })   // browsers; memoryStorage() by default
+ * await sov.collection('todos').add({ title: 'works on a plane' })      // queued while offline, shown at once
+ * offline.pendingWrites()                                                // what still has to reach the server
+ * ```
+ *
+ * How it works: every document request goes through this transport. Reads that reach the server
+ * refresh a local cache; when the network is down, single reads and queries are answered from that
+ * cache (queries are evaluated locally with the server's operators, ordering and cursors) and live
+ * listeners keep firing from it. Writes made offline are applied to the cache straight away
+ * (listeners see them, flagged `pending`) and kept in an ordered queue; when the connection is back
+ * the queue is sent one commit at a time in the original order. A write the server refuses
+ * (a rule, a precondition) is dropped from the queue and reported to `onSyncError`, and the cache
+ * is refreshed from the server so it never keeps the refused change. Transactions need the server
+ * (their reads must be current), so they fail fast offline, as in Firebase.
+ *
+ * Storage is pluggable: `memoryStorage()` (default; tests, servers), `indexedDbStorage()` (browsers),
+ * and `keyValueStorage(AsyncStorage)` for React Native or any `getItem/setItem/removeItem/getAllKeys`
+ * store. Each project gets its own key prefix.
+ */
+import type { DocumentsTransport } from './collections.js';
+type Json = string | number | boolean | null | Json[] | {
+    [key: string]: Json;
+};
+type JsonObject = {
+    [key: string]: Json;
+};
+export interface OfflineStorage {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string): Promise<void>;
+    delete(key: string): Promise<void>;
+    /** Keys starting with `prefix`. */
+    keys(prefix: string): Promise<string[]>;
+}
+export declare function memoryStorage(): OfflineStorage;
+/** React Native AsyncStorage (or any store with getItem/setItem/removeItem/getAllKeys). */
+export declare function keyValueStorage(store: {
+    getItem(k: string): Promise<string | null>;
+    setItem(k: string, v: string): Promise<void>;
+    removeItem(k: string): Promise<void>;
+    getAllKeys(): Promise<readonly string[]>;
+}): OfflineStorage;
+/** IndexedDB (browsers): one object store, values as JSON strings. */
+export declare function indexedDbStorage(dbName?: string): OfflineStorage;
+type Doc = {
+    id: string;
+    path: string;
+    data: JsonObject | null;
+    version: number;
+    exists: boolean;
+    update_time?: string;
+    pending?: boolean;
+};
+export declare function compareValues(a: unknown, b: unknown): number;
+/** The query's documents from `docs` (one collection's cached documents). */
+export declare function evaluateQuery(docs: Doc[], body: JsonObject): {
+    documents: Doc[];
+    has_more: boolean;
+};
+/** The document after `write`, or null when it is deleted (throws for an update of a missing one). */
+export declare function applyWrite(current: Doc | null, write: JsonObject): JsonObject | null;
+export interface OfflineOptions {
+    storage?: OfflineStorage;
+    /** Key prefix (one per project; default from the project id). */
+    namespace?: string;
+    /** A queued write the server refused when it came back (a rule, a precondition). */
+    onSyncError?: (error: unknown, writes: JsonObject[]) => void;
+    /** Called after the queue was sent (online again). */
+    onSynced?: (count: number) => void;
+}
+export interface OfflineController {
+    /** False after a request failed for lack of network, true after one reached the server. */
+    readonly online: boolean;
+    /** Writes made offline that haven't reached the server yet, oldest first. */
+    pendingWrites(): Promise<JsonObject[][]>;
+    /** Send queued writes now (also runs on reconnect and every 30 s while some are pending). */
+    flush(): Promise<number>;
+    /** Forget the cache and the queue (e.g. on sign-out). */
+    clear(): Promise<void>;
+    /** Stop the background sync timer and listeners. */
+    close(): void;
+}
+export declare function createOfflineTransport(inner: DocumentsTransport, options?: OfflineOptions): DocumentsTransport & {
+    controller: OfflineController;
+};
+export {};

package/dist/offline.js

@@ -0,0 +1,528 @@
+/**
+ * Offline-first documents (plan C4): keep working with no connection, sync when it comes back.
+ *
+ * ```ts
+ * const sov = new SovariaSDK({ projectUrl, anonKey })
+ * const offline = sov.enableOffline({ storage: indexedDbStorage() })   // browsers; memoryStorage() by default
+ * await sov.collection('todos').add({ title: 'works on a plane' })      // queued while offline, shown at once
+ * offline.pendingWrites()                                                // what still has to reach the server
+ * ```
+ *
+ * How it works: every document request goes through this transport. Reads that reach the server
+ * refresh a local cache; when the network is down, single reads and queries are answered from that
+ * cache (queries are evaluated locally with the server's operators, ordering and cursors) and live
+ * listeners keep firing from it. Writes made offline are applied to the cache straight away
+ * (listeners see them, flagged `pending`) and kept in an ordered queue; when the connection is back
+ * the queue is sent one commit at a time in the original order. A write the server refuses
+ * (a rule, a precondition) is dropped from the queue and reported to `onSyncError`, and the cache
+ * is refreshed from the server so it never keeps the refused change. Transactions need the server
+ * (their reads must be current), so they fail fast offline, as in Firebase.
+ *
+ * Storage is pluggable: `memoryStorage()` (default; tests, servers), `indexedDbStorage()` (browsers),
+ * and `keyValueStorage(AsyncStorage)` for React Native or any `getItem/setItem/removeItem/getAllKeys`
+ * store. Each project gets its own key prefix.
+ */
+import { SovariaError } from './errors.js';
+const BASE = '/api/v1/data/doc';
+export function memoryStorage() {
+    const data = new Map();
+    return {
+        get: async (k) => data.get(k) ?? null,
+        set: async (k, v) => void data.set(k, v),
+        delete: async (k) => void data.delete(k),
+        keys: async (p) => [...data.keys()].filter((k) => k.startsWith(p)),
+    };
+}
+/** React Native AsyncStorage (or any store with getItem/setItem/removeItem/getAllKeys). */
+export function keyValueStorage(store) {
+    return {
+        get: (k) => store.getItem(k),
+        set: (k, v) => store.setItem(k, v),
+        delete: (k) => store.removeItem(k),
+        keys: async (p) => (await store.getAllKeys()).filter((k) => k.startsWith(p)),
+    };
+}
+/** IndexedDB (browsers): one object store, values as JSON strings. */
+export function indexedDbStorage(dbName = 'sovaria-offline') {
+    const idb = globalThis.indexedDB;
+    if (!idb)
+        throw SovariaError.config('indexedDbStorage needs a browser with IndexedDB; use memoryStorage() or keyValueStorage()');
+    const open = new Promise((resolve, reject) => {
+        const req = idb.open(dbName, 1);
+        req.onupgradeneeded = () => req.result.createObjectStore('kv');
+        req.onsuccess = () => resolve(req.result);
+        req.onerror = () => reject(req.error);
+    });
+    const run = (mode, fn) => open.then((db) => new Promise((resolve, reject) => {
+        const req = fn(db.transaction('kv', mode).objectStore('kv'));
+        req.onsuccess = () => resolve(req.result);
+        req.onerror = () => reject(req.error);
+    }));
+    return {
+        get: async (k) => (await run('readonly', (s) => s.get(k))) ?? null,
+        set: async (k, v) => void (await run('readwrite', (s) => s.put(v, k))),
+        delete: async (k) => void (await run('readwrite', (s) => s.delete(k))),
+        keys: async (p) => (await run('readonly', (s) => s.getAllKeys(IDBKeyRange.bound(p, p + '￿')))),
+    };
+}
+function fieldValue(doc, field) {
+    if (field === '__key__' || field === '__name__')
+        return doc.id;
+    let value = doc.data;
+    for (const part of field.split('.')) {
+        if (value === null || typeof value !== 'object')
+            return undefined;
+        value = value[part.replace(/^`|`$/g, '')];
+    }
+    return value;
+}
+function typeRank(v) {
+    if (v === null || v === undefined)
+        return 0;
+    if (typeof v === 'boolean')
+        return 1;
+    if (typeof v === 'number')
+        return 2;
+    if (typeof v === 'string')
+        return 3;
+    if (Array.isArray(v))
+        return 4;
+    return 5;
+}
+export function compareValues(a, b) {
+    const ra = typeRank(a);
+    const rb = typeRank(b);
+    if (ra !== rb)
+        return ra - rb;
+    if (ra === 0)
+        return 0;
+    if (ra === 4) {
+        const aa = a;
+        const bb = b;
+        for (let i = 0; i < Math.min(aa.length, bb.length); i++) {
+            const c = compareValues(aa[i], bb[i]);
+            if (c)
+                return c;
+        }
+        return aa.length - bb.length;
+    }
+    if (ra === 5)
+        return JSON.stringify(a) < JSON.stringify(b) ? -1 : JSON.stringify(a) > JSON.stringify(b) ? 1 : 0;
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+const equal = (a, b) => typeRank(a) === typeRank(b) && compareValues(a, b) === 0;
+function matches(doc, [field, op, value]) {
+    const v = fieldValue(doc, field);
+    switch (op) {
+        case '==': return v !== undefined && equal(v, value);
+        case '!=': return v !== undefined && v !== null && !equal(v, value);
+        case '<': return v !== undefined && typeRank(v) === typeRank(value) && compareValues(v, value) < 0;
+        case '<=': return v !== undefined && typeRank(v) === typeRank(value) && compareValues(v, value) <= 0;
+        case '>': return v !== undefined && typeRank(v) === typeRank(value) && compareValues(v, value) > 0;
+        case '>=': return v !== undefined && typeRank(v) === typeRank(value) && compareValues(v, value) >= 0;
+        case 'in': return Array.isArray(value) && value.some((x) => equal(v, x));
+        case 'not-in': return v !== undefined && v !== null && Array.isArray(value) && !value.some((x) => equal(v, x));
+        case 'array-contains': return Array.isArray(v) && v.some((x) => equal(x, value));
+        case 'array-contains-any': return Array.isArray(v) && Array.isArray(value) && v.some((x) => value.some((y) => equal(x, y)));
+        default: return false;
+    }
+}
+/** The query's documents from `docs` (one collection's cached documents). */
+export function evaluateQuery(docs, body) {
+    const where = body.where ?? [];
+    const order = (body.order_by ?? []).slice();
+    // Implicit ordering, like the server: inequality fields first, then the document id.
+    for (const [field, op] of where) {
+        if (['<', '<=', '>', '>=', '!=', 'not-in'].includes(op) && !order.some(([f]) => f === field))
+            order.push([field, 'asc']);
+    }
+    if (!order.some(([f]) => f === '__key__'))
+        order.push(['__key__', order.length ? order[order.length - 1][1] : 'asc']);
+    let out = docs.filter((d) => d.exists && where.every((w) => matches(d, w)));
+    // Ordering by a field leaves out documents that don't have it (server semantics).
+    out = out.filter((d) => order.every(([f]) => f === '__key__' || fieldValue(d, f) !== undefined));
+    const cmp = (a, b) => {
+        for (const [f, dir] of order) {
+            const c = compareValues(fieldValue(a, f), fieldValue(b, f));
+            if (c)
+                return dir === 'desc' ? -c : c;
+        }
+        return 0;
+    };
+    out.sort(cmp);
+    const cursorCmp = (d, cursor) => {
+        const anchor = cursor.key !== undefined ? out.find((x) => x.id === cursor.key) ?? docs.find((x) => x.id === cursor.key) : undefined;
+        for (let i = 0; i < order.length; i++) {
+            const [f, dir] = order[i];
+            const target = anchor ? fieldValue(anchor, f) : cursor.values?.[i];
+            if (target === undefined)
+                return 0;
+            const c = compareValues(fieldValue(d, f), target);
+            if (c)
+                return dir === 'desc' ? -c : c;
+        }
+        return 0;
+    };
+    const sa = body.start_at;
+    const sf = body.start_after;
+    const ea = body.end_at;
+    const eb = body.end_before;
+    if (sa)
+        out = out.filter((d) => cursorCmp(d, sa) >= 0);
+    if (sf)
+        out = out.filter((d) => cursorCmp(d, sf) > 0);
+    if (ea)
+        out = out.filter((d) => cursorCmp(d, ea) <= 0);
+    if (eb)
+        out = out.filter((d) => cursorCmp(d, eb) < 0);
+    const limit = body.limit;
+    const last = body.limit_to_last;
+    if (limit !== undefined)
+        return { documents: out.slice(0, limit), has_more: out.length > limit };
+    if (last !== undefined)
+        return { documents: out.slice(Math.max(0, out.length - last)), has_more: out.length > last };
+    return { documents: out, has_more: false };
+}
+// ── applying writes locally ───────────────────────────────────────────────────
+function splitPath(field) {
+    const parts = [];
+    const re = /`((?:[^`\\]|\\.)*)`|([^.]+)/g;
+    let m;
+    while ((m = re.exec(field)))
+        parts.push(m[1] !== undefined ? m[1].replace(/\\(.)/g, '$1') : m[2]);
+    return parts;
+}
+function setPath(obj, parts, value, remove = false) {
+    let node = obj;
+    for (const part of parts.slice(0, -1)) {
+        if (!node[part] || typeof node[part] !== 'object' || Array.isArray(node[part]))
+            node[part] = {};
+        node = node[part];
+    }
+    const last = parts[parts.length - 1];
+    if (remove)
+        delete node[last];
+    else
+        node[last] = value;
+}
+function getPath(obj, parts) {
+    let node = obj;
+    for (const part of parts) {
+        if (!node || typeof node !== 'object')
+            return undefined;
+        node = node[part];
+    }
+    return node;
+}
+function deepMerge(base, patch) {
+    const out = { ...base };
+    for (const [k, v] of Object.entries(patch)) {
+        out[k] = v && typeof v === 'object' && !Array.isArray(v) && out[k] && typeof out[k] === 'object' && !Array.isArray(out[k])
+            ? deepMerge(out[k], v) : v;
+    }
+    return out;
+}
+/** The document after `write`, or null when it is deleted (throws for an update of a missing one). */
+export function applyWrite(current, write) {
+    const op = String(write.op);
+    if (op === 'delete')
+        return null;
+    const before = current?.exists ? JSON.parse(JSON.stringify(current.data ?? {})) : null;
+    const data = write.data ?? {};
+    let next;
+    if (op === 'update') {
+        if (!before)
+            throw new SovariaError(404, { code: 'NOT_FOUND', message: `No document to update at ${write.path}` });
+        next = before;
+        for (const [field, value] of Object.entries(data))
+            setPath(next, splitPath(field), value);
+    }
+    else if (op === 'create' && before) {
+        throw new SovariaError(409, { code: 'ALREADY_EXISTS', message: `${write.path} already exists` });
+    }
+    else if (write.merge || write.merge_fields?.length) {
+        next = before ?? {};
+        const fields = write.merge_fields;
+        if (fields?.length)
+            for (const f of fields)
+                setPath(next, splitPath(f), getPath(data, splitPath(f)));
+        else
+            next = deepMerge(next, data);
+    }
+    else {
+        next = JSON.parse(JSON.stringify(data));
+    }
+    for (const t of write.transforms ?? []) {
+        const parts = splitPath(String(t.field));
+        const cur = getPath(next, parts);
+        const v = t.value;
+        switch (t.op) {
+            case 'increment':
+                setPath(next, parts, (typeof cur === 'number' ? cur : 0) + Number(v));
+                break;
+            case 'maximum':
+                setPath(next, parts, typeof cur === 'number' ? Math.max(cur, Number(v)) : v);
+                break;
+            case 'minimum':
+                setPath(next, parts, typeof cur === 'number' ? Math.min(cur, Number(v)) : v);
+                break;
+            case 'array_union': {
+                const arr = Array.isArray(cur) ? [...cur] : [];
+                for (const x of v ?? [])
+                    if (!arr.some((y) => equal(x, y)))
+                        arr.push(x);
+                setPath(next, parts, arr);
+                break;
+            }
+            case 'array_remove':
+                setPath(next, parts, Array.isArray(cur) ? cur.filter((y) => !v.some((x) => equal(x, y))) : []);
+                break;
+            case 'server_timestamp':
+                setPath(next, parts, new Date().toISOString());
+                break;
+            case 'delete':
+                setPath(next, parts, undefined, true);
+                break;
+        }
+    }
+    return next;
+}
+const isNetwork = (e) => e instanceof SovariaError && e.code === 'NETWORK_ERROR';
+export function createOfflineTransport(inner, options = {}) {
+    const store = options.storage ?? memoryStorage();
+    const ns = `sov:${options.namespace ?? 'default'}:`;
+    const docKey = (path) => `${ns}doc:${path}`;
+    const queuePrefix = `${ns}q:`;
+    let online = true;
+    let seq = Date.now() * 1000;
+    let flushing = null;
+    const channels = new Map();
+    let localListeners = 0;
+    const readDoc = async (path) => {
+        const raw = await store.get(docKey(path));
+        return raw ? JSON.parse(raw) : null;
+    };
+    const writeDoc = (d) => store.set(docKey(d.path), JSON.stringify(d));
+    const cacheServerDoc = async (raw) => {
+        const path = String(raw.path ?? '');
+        if (!path)
+            return;
+        const existing = await readDoc(path);
+        if (existing?.pending)
+            return; // a local write is waiting; keep it visible until it syncs
+        const exists = raw.exists !== false && raw.data !== null && raw.data !== undefined;
+        await writeDoc({ id: String(raw.id ?? path.split('/').pop()), path, data: exists ? raw.data : null,
+            version: Number(raw.version ?? 0), exists, update_time: raw.update_time });
+    };
+    const collectionDocs = async (collection) => {
+        const depth = collection.split('/').length + 1;
+        const keys = await store.keys(docKey(collection + '/'));
+        const docs = await Promise.all(keys.map((k) => store.get(k)));
+        return docs.filter((r) => !!r).map((r) => JSON.parse(r)).filter((d) => d.path.split('/').length === depth);
+    };
+    const notifyListeners = () => {
+        for (const { listenerId, handlers } of channels.values())
+            handlers.onMessage?.({ type: 'local_resync', listener_id: listenerId });
+    };
+    const pathFrom = (path, verb) => decodeURIComponent(path.slice(`${BASE}/${verb}/`.length)).split('/').map(decodeURIComponent).join('/');
+    const applyLocally = async (writes) => {
+        // All or nothing, like a commit: compute every result first, then store.
+        const results = [];
+        const seen = new Map();
+        for (const w of writes) {
+            const path = String(w.path);
+            const current = seen.has(path) ? seen.get(path) : await readDoc(path);
+            const data = applyWrite(current, w);
+            const doc = { id: path.split('/').pop(), path, data, exists: data !== null, version: (current?.version ?? 0) + 1,
+                update_time: new Date().toISOString(), pending: true };
+            seen.set(path, doc);
+            results.push(doc);
+        }
+        for (const d of results)
+            await writeDoc(d);
+        return results;
+    };
+    const flush = async () => {
+        if (flushing)
+            return flushing;
+        flushing = (async () => {
+            let sent = 0;
+            const keys = (await store.keys(queuePrefix)).sort();
+            for (const key of keys) {
+                const raw = await store.get(key);
+                if (!raw)
+                    continue;
+                const writes = JSON.parse(raw);
+                try {
+                    const out = await inner.request('POST', `${BASE}/_commit`, { body: { writes, reads: [] } });
+                    online = true;
+                    await store.delete(key);
+                    sent++;
+                    const results = out.results ?? [];
+                    for (let i = 0; i < writes.length; i++) {
+                        const d = await readDoc(String(writes[i].path));
+                        if (d)
+                            await writeDoc({ ...d, pending: false, version: Number(results[i]?.version ?? d.version) });
+                    }
+                }
+                catch (error) {
+                    if (isNetwork(error)) {
+                        online = false;
+                        break;
+                    }
+                    // Refused by the server: drop it, tell the app, and put back the server's view.
+                    await store.delete(key);
+                    options.onSyncError?.(error, writes);
+                    for (const w of writes) {
+                        const path = String(w.path);
+                        const d = await readDoc(path);
+                        if (d)
+                            await writeDoc({ ...d, pending: false });
+                        try {
+                            await cacheServerDoc({ ...(await inner.request('GET', `${BASE}/${path.split('/').map(encodeURIComponent).join('/')}`)), path });
+                        }
+                        catch (e) {
+                            if (e instanceof SovariaError && e.statusCode === 404)
+                                await writeDoc({ id: path.split('/').pop(), path, data: null, exists: false, version: 0 });
+                        }
+                    }
+                }
+            }
+            if (sent) {
+                options.onSynced?.(sent);
+                notifyListeners();
+            }
+            return sent;
+        })().finally(() => { flushing = null; });
+        return flushing;
+    };
+    const timer = setInterval(() => {
+        void store.keys(queuePrefix).then((k) => { if (k.length)
+            void flush(); });
+    }, 30_000);
+    const onOnline = () => void flush();
+    const g = globalThis;
+    g.addEventListener?.('online', onOnline);
+    const request = async (method, path, opts) => {
+        const body = (opts?.body ?? {});
+        const isDocRead = method === 'GET' && path.startsWith(`${BASE}/`) && !path.startsWith(`${BASE}/_`);
+        const isQuery = method === 'POST' && path.startsWith(`${BASE}/_query/`);
+        const isCount = method === 'POST' && path.startsWith(`${BASE}/_count/`);
+        const isCommit = method === 'POST' && path === `${BASE}/_commit`;
+        const isListen = method === 'POST' && path.startsWith(`${BASE}/_listen/`);
+        const isLocalListener = path.startsWith(`${BASE}/_listeners/local-`);
+        if (isLocalListener)
+            return {};
+        if (isCommit) {
+            const writes = body.writes ?? [];
+            if ((body.reads ?? []).length)
+                return inner.request(method, path, opts); // transactions need the server
+            if ((await store.keys(queuePrefix)).length)
+                await flush(); // keep order: older offline writes first
+            if (online || !(await store.keys(queuePrefix)).length) {
+                try {
+                    const out = await inner.request(method, path, opts);
+                    online = true;
+                    const results = out.results ?? [];
+                    const applied = await applyLocally(writes).catch(() => []);
+                    for (let i = 0; i < applied.length; i++)
+                        await writeDoc({ ...applied[i], pending: false, version: Number(results[i]?.version ?? applied[i].version) });
+                    return out;
+                }
+                catch (error) {
+                    if (!isNetwork(error))
+                        throw error;
+                    online = false;
+                }
+            }
+            const applied = await applyLocally(writes);
+            await store.set(`${queuePrefix}${String(++seq).padStart(20, '0')}`, JSON.stringify(writes));
+            notifyListeners();
+            return { results: applied.map((d) => ({ path: d.path, version: d.version, pending: true })), pending: true };
+        }
+        try {
+            const out = await inner.request(method, path, opts);
+            online = true;
+            if (isDocRead)
+                await cacheServerDoc({ ...out, path: decodeURIComponent(path.slice(BASE.length + 1)).split('/').map(decodeURIComponent).join('/') });
+            if (isQuery || isListen)
+                for (const d of out.documents ?? [])
+                    await cacheServerDoc(d);
+            if (online && (await store.keys(queuePrefix)).length)
+                void flush();
+            return out;
+        }
+        catch (error) {
+            if (!isNetwork(error)) {
+                if (isDocRead && error instanceof SovariaError && error.statusCode === 404) {
+                    const p = path.slice(BASE.length + 1).split('/').map(decodeURIComponent).join('/');
+                    const cached = await readDoc(p);
+                    if (!cached?.pending)
+                        await writeDoc({ id: p.split('/').pop(), path: p, data: null, exists: false, version: 0 });
+                }
+                throw error;
+            }
+            online = false;
+            if (isDocRead) {
+                const p = path.slice(BASE.length + 1).split('/').map(decodeURIComponent).join('/');
+                const cached = await readDoc(p);
+                if (!cached)
+                    throw error;
+                if (!cached.exists)
+                    throw new SovariaError(404, { code: 'NOT_FOUND', message: 'Not found (cached)' });
+                return { ...cached, from_cache: true };
+            }
+            if (isQuery || isCount || isListen) {
+                const collection = pathFrom(path, isQuery ? '_query' : isCount ? '_count' : '_listen');
+                const result = evaluateQuery(await collectionDocs(collection), body);
+                if (isCount)
+                    return { count: result.documents.length, from_cache: true };
+                if (isListen) {
+                    const id = `local-${++localListeners}`;
+                    return { id, channel: `local:${id}`, ttl_seconds: 600, documents: result.documents, from_cache: true };
+                }
+                return { documents: result.documents, has_more: result.has_more, from_cache: true };
+            }
+            throw error;
+        }
+    };
+    const transport = {
+        request,
+        openChannel(name, handlers) {
+            const listenerId = name.startsWith('local:') ? name.slice('local:'.length) : '';
+            const key = `${name}#${Math.random()}`;
+            // Local writes and syncs ask every listener to re-read (from the cache while offline).
+            const entry = { listenerId, handlers };
+            let inner_;
+            if (!listenerId) {
+                inner_ = inner.openChannel(name, {
+                    ...handlers,
+                    onMessage: (payload) => {
+                        if (payload && payload.listener_id)
+                            entry.listenerId = String(payload.listener_id);
+                        handlers.onMessage?.(payload);
+                    },
+                });
+            }
+            channels.set(key, entry);
+            return { close: () => { channels.delete(key); inner_?.close(); } };
+        },
+        controller: {
+            get online() { return online; },
+            pendingWrites: async () => {
+                const keys = (await store.keys(queuePrefix)).sort();
+                return Promise.all(keys.map(async (k) => JSON.parse((await store.get(k)) ?? '[]')));
+            },
+            flush,
+            clear: async () => {
+                for (const k of await store.keys(ns))
+                    await store.delete(k);
+            },
+            close: () => {
+                clearInterval(timer);
+                g.removeEventListener?.('online', onOnline);
+            },
+        },
+    };
+    return transport;
+}