@syncular/client 0.4.1 → 0.5.0

package/dist/reactive-store.js

@@ -0,0 +1,576 @@
+import { windowBaseKey } from './window.js';
+function errorOf(value) {
+    return value instanceof Error ? value : new Error(String(value));
+}
+function readCollection(value) {
+    return typeof value === 'function' ? value() : value;
+}
+function unsupportedCanonicalValue(value) {
+    const description = Object.prototype.toString.call(value);
+    throw new TypeError(`unsupported reactive cache-key value ${description}; use null, string, finite number, bigint, boolean, bytes, arrays, or plain objects`);
+}
+function encodeCanonical(value, stack) {
+    if (value === null)
+        return 'n';
+    if (typeof value === 'string')
+        return `s${value.length}:${value}`;
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value))
+            return unsupportedCanonicalValue(value);
+        if (Object.is(value, -0))
+            return 'd-0';
+        return `d${value}`;
+    }
+    if (typeof value === 'bigint')
+        return `i${value}`;
+    if (typeof value === 'boolean')
+        return value ? 'b1' : 'b0';
+    if (value instanceof Uint8Array) {
+        let hex = '';
+        for (const byte of value)
+            hex += byte.toString(16).padStart(2, '0');
+        return `x${hex}`;
+    }
+    if (Array.isArray(value)) {
+        if (stack.has(value))
+            return unsupportedCanonicalValue(value);
+        stack.add(value);
+        const encoded = `a${value.length}[${value
+            .map((member) => encodeCanonical(member, stack))
+            .join('')}]`;
+        stack.delete(value);
+        return encoded;
+    }
+    if (typeof value === 'object') {
+        const prototype = Object.getPrototypeOf(value);
+        if (prototype !== Object.prototype && prototype !== null) {
+            return unsupportedCanonicalValue(value);
+        }
+        if (stack.has(value))
+            return unsupportedCanonicalValue(value);
+        stack.add(value);
+        const entries = Object.entries(value).sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0));
+        const encoded = `o${entries.length}{${entries
+            .map(([key, member]) => `${encodeCanonical(key, stack)}${encodeCanonical(member, stack)}`)
+            .join('')}}`;
+        stack.delete(value);
+        return encoded;
+    }
+    return unsupportedCanonicalValue(value);
+}
+/** Lossless deterministic identity for query params, bytes, and row keys. */
+export function canonicalValue(value) {
+    return encodeCanonical(value, new Set());
+}
+function scheduleMicrotask(task) {
+    if (typeof queueMicrotask === 'function')
+        queueMicrotask(task);
+    else
+        void Promise.resolve().then(task);
+}
+function batchMatches(batch, spec) {
+    for (const change of batch.tables) {
+        const dependency = spec.dependencies.find((candidate) => candidate.table === change.table);
+        if (dependency === undefined)
+            continue;
+        if (dependency.scopeKeys === undefined || change.scopeKeys === undefined) {
+            return true;
+        }
+        for (const key of dependency.scopeKeys) {
+            if (change.scopeKeys.has(key))
+                return true;
+        }
+    }
+    for (const change of batch.windows) {
+        for (const coverage of spec.coverage ?? []) {
+            if (windowBaseKey(coverage.base) !== change.baseKey)
+                continue;
+            if (coverage.units.some((unit) => change.units.has(unit)))
+                return true;
+        }
+    }
+    return false;
+}
+function valuesEqual(left, right) {
+    if (Object.is(left, right))
+        return true;
+    if (left instanceof Uint8Array || right instanceof Uint8Array) {
+        if (!(left instanceof Uint8Array) || !(right instanceof Uint8Array)) {
+            return false;
+        }
+        if (left.byteLength !== right.byteLength)
+            return false;
+        for (let index = 0; index < left.byteLength; index += 1) {
+            if (left[index] !== right[index])
+                return false;
+        }
+        return true;
+    }
+    if (Array.isArray(left) || Array.isArray(right)) {
+        if (!Array.isArray(left) || !Array.isArray(right))
+            return false;
+        return (left.length === right.length &&
+            left.every((member, index) => valuesEqual(member, right[index])));
+    }
+    if (left === null ||
+        right === null ||
+        typeof left !== 'object' ||
+        typeof right !== 'object') {
+        return false;
+    }
+    const leftRecord = left;
+    const rightRecord = right;
+    const keys = Object.keys(leftRecord);
+    if (keys.length !== Object.keys(rightRecord).length)
+        return false;
+    return keys.every((key) => Object.hasOwn(rightRecord, key) &&
+        valuesEqual(leftRecord[key], rightRecord[key]));
+}
+function reconcileRows(previous, fresh, rowKey) {
+    if (previous.length === 0)
+        return fresh;
+    if (rowKey === undefined) {
+        let changed = previous.length !== fresh.length;
+        const next = fresh.map((row, index) => {
+            const prior = previous[index];
+            if (prior !== undefined && valuesEqual(prior, row))
+                return prior;
+            changed = true;
+            return row;
+        });
+        return changed ? next : previous;
+    }
+    const priorByKey = new Map();
+    let duplicate = false;
+    for (const row of previous) {
+        const key = canonicalValue(rowKey(row));
+        if (priorByKey.has(key))
+            duplicate = true;
+        priorByKey.set(key, row);
+    }
+    const seen = new Set();
+    const next = fresh.map((row) => {
+        const key = canonicalValue(rowKey(row));
+        if (seen.has(key))
+            duplicate = true;
+        seen.add(key);
+        const prior = priorByKey.get(key);
+        return prior !== undefined && valuesEqual(prior, row) ? prior : row;
+    });
+    if (duplicate)
+        return reconcileRows(previous, fresh, undefined);
+    return next.length === previous.length &&
+        next.every((row, i) => row === previous[i])
+        ? previous
+        : next;
+}
+class QueryEntry {
+    store;
+    spec;
+    #owner = Symbol('query-window-claim');
+    #listeners = new Set();
+    #state = {
+        rows: [],
+        phase: 'loading',
+        revision: undefined,
+        error: undefined,
+        isRefreshing: false,
+    };
+    #subscribers = 0;
+    #scheduled = false;
+    #running = false;
+    #requested = false;
+    #desiredRevision = 0n;
+    #claimReady = Promise.resolve();
+    constructor(store, spec) {
+        this.store = store;
+        this.spec = spec;
+    }
+    getSnapshot = () => this.#state;
+    subscribe = (listener) => {
+        this.#listeners.add(listener);
+        this.#subscribers += 1;
+        if (this.#subscribers === 1) {
+            if (this.spec.claimCoverage !== false) {
+                const claims = [];
+                for (const coverage of this.spec.coverage ?? []) {
+                    claims.push(this.store.setWindowClaim(this.#owner, coverage.base, coverage.units));
+                }
+                this.#claimReady = Promise.all(claims).then(() => undefined);
+            }
+            this.#requestRead();
+        }
+        return () => {
+            if (!this.#listeners.delete(listener))
+                return;
+            this.#subscribers -= 1;
+            if (this.#subscribers === 0)
+                this.store.releaseWindowClaims(this.#owner);
+        };
+    };
+    refresh = () => this.#requestRead(true);
+    onChange(batch) {
+        if (!batchMatches(batch, this.spec))
+            return;
+        if (batch.revision > this.#desiredRevision) {
+            this.#desiredRevision = batch.revision;
+        }
+        if (this.#subscribers > 0)
+            this.#requestRead();
+    }
+    #publish(next) {
+        if (next.rows === this.#state.rows &&
+            next.phase === this.#state.phase &&
+            next.error === this.#state.error &&
+            next.isRefreshing === this.#state.isRefreshing) {
+            return;
+        }
+        this.#state = next;
+        for (const listener of this.#listeners)
+            listener();
+    }
+    #requestRead(refreshing = false) {
+        this.#requested = true;
+        if (refreshing &&
+            this.#state.revision !== undefined &&
+            !this.#state.isRefreshing) {
+            this.#publish({ ...this.#state, isRefreshing: true });
+        }
+        if (this.#scheduled || this.#running)
+            return;
+        this.#scheduled = true;
+        scheduleMicrotask(() => {
+            this.#scheduled = false;
+            void this.#readLoop();
+        });
+    }
+    async #readLoop() {
+        if (this.#running || this.#subscribers === 0)
+            return;
+        this.#running = true;
+        try {
+            do {
+                this.#requested = false;
+                await this.#claimReady;
+                const snapshot = await this.store.client.querySnapshot({
+                    sql: this.spec.sql,
+                    ...(this.spec.params !== undefined
+                        ? { params: this.spec.params }
+                        : {}),
+                    ...(this.spec.coverage !== undefined
+                        ? { coverage: this.spec.coverage }
+                        : {}),
+                });
+                if (snapshot.revision < this.#desiredRevision) {
+                    this.#requested = true;
+                    continue;
+                }
+                const rows = reconcileRows(this.#state.rows, snapshot.rows, this.spec.rowKey);
+                const phase = snapshot.coverage.complete
+                    ? 'ready'
+                    : rows.length > 0
+                        ? 'partial'
+                        : 'loading';
+                this.#publish({
+                    rows,
+                    phase,
+                    revision: snapshot.revision,
+                    error: undefined,
+                    isRefreshing: false,
+                });
+            } while (this.#requested && this.#subscribers > 0);
+        }
+        catch (error) {
+            const wrapped = errorOf(error);
+            this.#publish({
+                ...this.#state,
+                phase: this.#state.revision === undefined ? 'error' : this.#state.phase,
+                error: wrapped,
+                isRefreshing: false,
+            });
+        }
+        finally {
+            this.#running = false;
+            if (this.#requested && this.#subscribers > 0)
+                this.#requestRead();
+        }
+    }
+}
+class ValueEntry {
+    value;
+    read;
+    #listeners = new Set();
+    constructor(value, read) {
+        this.value = value;
+        this.read = read;
+    }
+    getSnapshot = () => this.value;
+    subscribe = (listener) => {
+        this.#listeners.add(listener);
+        return () => this.#listeners.delete(listener);
+    };
+    refresh = () => {
+        void this.read().then((next) => this.set(next));
+    };
+    set(next) {
+        if (next === this.value)
+            return;
+        this.value = next;
+        for (const listener of this.#listeners)
+            listener();
+    }
+}
+class WindowEntry {
+    store;
+    base;
+    baseKey;
+    #listeners = new Set();
+    #state = { units: [], pending: [] };
+    #running = false;
+    #requested = false;
+    constructor(store, base, baseKey) {
+        this.store = store;
+        this.base = base;
+        this.baseKey = baseKey;
+    }
+    getSnapshot = () => this.#state;
+    subscribe = (listener) => {
+        this.#listeners.add(listener);
+        if (this.#listeners.size === 1)
+            this.refresh();
+        return () => this.#listeners.delete(listener);
+    };
+    refresh = () => {
+        this.#requested = true;
+        if (this.#running)
+            return;
+        void this.#readLoop();
+    };
+    onChange(batch) {
+        if (batch.windows.some((change) => change.baseKey === this.baseKey) &&
+            this.#listeners.size > 0) {
+            this.refresh();
+        }
+    }
+    async #readLoop() {
+        this.#running = true;
+        try {
+            do {
+                this.#requested = false;
+                const next = await this.store.client.windowState(this.base);
+                if (canonicalValue(next.units) !== canonicalValue(this.#state.units) ||
+                    canonicalValue(next.pending) !== canonicalValue(this.#state.pending)) {
+                    this.#state = next;
+                    for (const listener of this.#listeners)
+                        listener();
+                }
+            } while (this.#requested);
+        }
+        catch {
+            // WindowState predates the error-bearing query result. Keep the last
+            // coherent snapshot; a later exact window event or refresh retries.
+        }
+        finally {
+            this.#running = false;
+            if (this.#requested)
+                this.refresh();
+        }
+    }
+}
+export class ReactiveClientStore {
+    client;
+    #queries = new Map();
+    #windows = new Map();
+    #windowClaims = new Map();
+    #offChange;
+    status;
+    conflicts;
+    constructor(client) {
+        this.client = client;
+        const status = new ValueEntry({ status: undefined, error: undefined, isLoading: true }, async () => {
+            try {
+                return {
+                    status: await client.statusSnapshot(),
+                    error: undefined,
+                    isLoading: false,
+                };
+            }
+            catch (error) {
+                return { status: undefined, error: errorOf(error), isLoading: false };
+            }
+        });
+        const conflicts = new ValueEntry({ conflicts: [], rejections: [], error: undefined, isLoading: true }, async () => {
+            try {
+                const [found, rejected] = await Promise.all([
+                    readCollection(client.conflicts),
+                    readCollection(client.rejections),
+                ]);
+                return {
+                    conflicts: found,
+                    rejections: rejected,
+                    error: undefined,
+                    isLoading: false,
+                };
+            }
+            catch (error) {
+                return {
+                    conflicts: [],
+                    rejections: [],
+                    error: errorOf(error),
+                    isLoading: false,
+                };
+            }
+        });
+        this.status = status;
+        this.conflicts = conflicts;
+        status.refresh();
+        conflicts.refresh();
+        this.start();
+    }
+    query(spec) {
+        const dependencies = spec.dependencies.map((dependency) => ({
+            table: dependency.table,
+            ...(dependency.scopeKeys === undefined
+                ? {}
+                : { scopeKeys: [...new Set(dependency.scopeKeys)].sort() }),
+        }));
+        const coverage = (spec.coverage ?? []).map((item) => ({
+            baseKey: windowBaseKey(item.base),
+            units: [...new Set(item.units)].sort(),
+        }));
+        const key = canonicalValue({
+            id: spec.id,
+            sql: spec.sql,
+            params: spec.params ?? [],
+            dependencies,
+            coverage,
+            claimCoverage: spec.claimCoverage !== false,
+        });
+        let entry = this.#queries.get(key);
+        if (entry === undefined) {
+            entry = new QueryEntry(this, spec);
+            this.#queries.set(key, entry);
+        }
+        return entry;
+    }
+    /** Retain a composable window working set outside React. The returned
+     * handle exposes registration completion and releases only this owner. */
+    retainWindow(base, units) {
+        const owner = Symbol('retained-window');
+        const ready = this.setWindowClaim(owner, base, units);
+        let active = true;
+        return {
+            ready,
+            release: () => {
+                if (!active)
+                    return;
+                active = false;
+                this.releaseWindowClaims(owner);
+            },
+        };
+    }
+    window(base) {
+        const key = windowBaseKey(base);
+        let entry = this.#windows.get(key);
+        if (entry === undefined) {
+            entry = new WindowEntry(this, base, key);
+            this.#windows.set(key, entry);
+        }
+        return entry;
+    }
+    setWindowClaim(owner, base, units) {
+        const key = windowBaseKey(base);
+        let group = this.#windowClaims.get(key);
+        if (group === undefined) {
+            group = {
+                base,
+                claims: new Map(),
+                appliedKey: '',
+                scheduled: false,
+                running: false,
+                requested: false,
+                waiters: [],
+            };
+            this.#windowClaims.set(key, group);
+        }
+        group.claims.set(owner, new Set(units));
+        const result = new Promise((resolve, reject) => {
+            group?.waiters.push({ resolve, reject });
+        });
+        this.#scheduleWindow(group);
+        return result;
+    }
+    releaseWindowClaims(owner) {
+        for (const group of this.#windowClaims.values()) {
+            if (group.claims.delete(owner))
+                this.#scheduleWindow(group);
+        }
+    }
+    #scheduleWindow(group) {
+        group.requested = true;
+        if (group.scheduled || group.running)
+            return;
+        group.scheduled = true;
+        scheduleMicrotask(() => {
+            group.scheduled = false;
+            void this.#flushWindow(group);
+        });
+    }
+    async #flushWindow(group) {
+        if (group.running)
+            return;
+        group.running = true;
+        try {
+            while (group.requested) {
+                group.requested = false;
+                const units = [
+                    ...new Set([...group.claims.values()].flatMap((set) => [...set])),
+                ].sort();
+                const key = canonicalValue(units);
+                if (key !== group.appliedKey) {
+                    await this.client.setWindow(group.base, units);
+                    group.appliedKey = key;
+                }
+            }
+            for (const waiter of group.waiters.splice(0))
+                waiter.resolve();
+        }
+        catch (error) {
+            for (const waiter of group.waiters.splice(0))
+                waiter.reject(error);
+        }
+        finally {
+            group.running = false;
+            if (group.requested)
+                this.#scheduleWindow(group);
+        }
+    }
+    start() {
+        if (this.#offChange !== undefined)
+            return;
+        this.#offChange = this.client.onChange((batch) => {
+            for (const entry of this.#queries.values())
+                entry.onChange(batch);
+            for (const entry of this.#windows.values())
+                entry.onChange(batch);
+            if (batch.status !== undefined) {
+                this.status.set({
+                    status: batch.status,
+                    error: undefined,
+                    isLoading: false,
+                });
+            }
+            if (batch.conflictsChanged || batch.rejectionsChanged) {
+                this.conflicts.refresh();
+            }
+        });
+    }
+    dispose() {
+        this.#offChange?.();
+        this.#offChange = undefined;
+        for (const group of this.#windowClaims.values()) {
+            void Promise.resolve(this.client.setWindow(group.base, []));
+        }
+        this.#windowClaims.clear();
+    }
+}

package/dist/schema.js

@@ -178,6 +178,7 @@ export function ensureLocalSchema(db, schema) {
         }
         db.exec(`CREATE TABLE IF NOT EXISTS _syncular_meta(
       key TEXT PRIMARY KEY, value TEXT NOT NULL)`);
+        db.exec(`INSERT OR IGNORE INTO _syncular_meta(key, value) VALUES ('localRevision', '0')`);
         db.exec(`CREATE TABLE IF NOT EXISTS _syncular_outbox(
       seq INTEGER PRIMARY KEY AUTOINCREMENT,
       client_commit_id TEXT NOT NULL UNIQUE,

package/dist/state.d.ts

@@ -6,6 +6,8 @@
  */
 import type { ScopeMap } from '@syncular/core';
 import type { ClientDatabase } from './database.js';
+import type { LocalRevision } from './invalidation.js';
+export declare const LOCAL_REVISION_KEY = "localRevision";
 export type SubscriptionStatus = 'active' | 'revoked' | 'failed';
 export interface SubscriptionRecord {
     readonly id: string;
@@ -38,3 +40,10 @@ export declare function deleteSubscription(db: ClientDatabase, id: string): void
 export declare function resetSubscriptionsForBump(db: ClientDatabase): void;
 export declare function getMeta(db: ClientDatabase, key: string): string | undefined;
 export declare function setMeta(db: ClientDatabase, key: string, value: string): void;
+/** Read the durable client-local observer revision (SPEC §7.5). */
+export declare function getLocalRevision(db: ClientDatabase): LocalRevision;
+/**
+ * Increment the durable revision. The caller MUST own the same transaction as
+ * the observer-visible writes represented by the corresponding change batch.
+ */
+export declare function bumpLocalRevision(db: ClientDatabase): LocalRevision;

package/dist/state.js

@@ -1,3 +1,5 @@
+export const LOCAL_REVISION_KEY = 'localRevision';
+const MAX_U64 = 18446744073709551615n;
 function rowToRecord(row) {
     return {
         id: row.id,
@@ -75,3 +77,30 @@ export function setMeta(db, key, value) {
         value,
     ]);
 }
+/** Read the durable client-local observer revision (SPEC §7.5). */
+export function getLocalRevision(db) {
+    const raw = getMeta(db, LOCAL_REVISION_KEY);
+    if (raw === undefined)
+        return 0n;
+    if (!/^(0|[1-9][0-9]*)$/.test(raw)) {
+        throw new Error(`invalid persisted local revision ${JSON.stringify(raw)}`);
+    }
+    const revision = BigInt(raw);
+    if (revision > MAX_U64) {
+        throw new Error(`persisted local revision exceeds u64: ${raw}`);
+    }
+    return revision;
+}
+/**
+ * Increment the durable revision. The caller MUST own the same transaction as
+ * the observer-visible writes represented by the corresponding change batch.
+ */
+export function bumpLocalRevision(db) {
+    const current = getLocalRevision(db);
+    if (current === MAX_U64) {
+        throw new Error('local revision exhausted u64');
+    }
+    const next = current + 1n;
+    setMeta(db, LOCAL_REVISION_KEY, next.toString());
+    return next;
+}

package/dist/window.d.ts

@@ -25,7 +25,7 @@ export interface WindowBase {
     /** The scope variable whose values are the window units. */
     readonly variable: string;
     /** Scopes shared by every unit (other variables), if any. */
-    readonly fixedScopes?: ScopeMap;
+    readonly fixedScopes?: Readonly<Record<string, readonly string[]>>;
     readonly params?: string;
 }
 /** A live unit in the registry: its value and the subscription it drives. */
@@ -33,6 +33,9 @@ export interface WindowUnit {
     readonly unit: string;
     readonly subId: string;
 }
+export interface RegisteredWindowUnit extends WindowUnit {
+    readonly baseKey: string;
+}
 /**
  * A stable, server-opaque key for a window base — table + variable +
  * canonical fixed scopes. Two `setWindow` calls with the same base
@@ -50,6 +53,8 @@ export declare function unitScopes(base: WindowBase, unit: string): ScopeMap;
 export declare function deriveSubId(base: WindowBase, unit: string): Promise<string>;
 /** Live units for a base, ordered by unit value. */
 export declare function loadWindowUnits(db: ClientDatabase, baseKey: string): WindowUnit[];
+/** Registry lookup used to emit exact completion changes for a sub id. */
+export declare function getWindowUnitBySubId(db: ClientDatabase, subId: string): RegisteredWindowUnit | undefined;
 export declare function insertWindowUnit(db: ClientDatabase, baseKey: string, unit: string, subId: string): void;
 export declare function deleteWindowUnit(db: ClientDatabase, baseKey: string, unit: string): void;
 /** Is a single scope value windowed-in for this base? (the oracle, I3) */