@interocitor/core 0.0.0-beta.3 → 0.0.0-beta.5

package/dist/core/table.js

@@ -1,23 +1,320 @@
 /**
- * Table<T> — typed handle for a named collection within a SyncEngine.
+ * Table<T> — typed handle for a named collection within a Interocitor.
  *
  * Wraps the engine's raw Row/string API with a type-safe surface.
  * All reads return plain T objects (internal HLC metadata stripped).
  * All writes accept Partial<T> and return T.
  */
+import { createRowId } from "./row-id.js";
+/**
+ * Thenable result of an async query.
+ *
+ * Two layers live here, kept distinct on purpose:
+ *  1. Async query identity: `descriptor` + `cacheKey`. Owned by core. Stable
+ *     across `.sort()` chains. Used by any cache layer (React etc.) to dedupe
+ *     loads, share in-flight promises, and keep stale data across remounts.
+ *  2. Sync derivation: `.sort(compareFn)` runs after the async load. Does not
+ *     change `cacheKey`. Not part of cache identity. Pure post-processing.
+ *
+ * `then(...)` triggers a load through the engine cache. Use `load({ bypassCache })`
+ * to force a fresh fetch.
+ */
+export class QueryResult {
+    constructor(descriptor, _engine, 
+    /** Optional sync transform stack — runs after rows are loaded. */
+    _sortChain = [], 
+    /** Optional pre-resolved promise (used for synthetic / engine-less results). */
+    _explicitPromise = null) {
+        this._engine = _engine;
+        this._sortChain = _sortChain;
+        this._explicitPromise = _explicitPromise;
+        // ─── internals ───────────────────────────────────────────────────
+        /**
+         * Memoization for the typed+sorted projection. Keyed by the raw rows
+         * reference from the engine cache. Same input ref ⇒ same output ref.
+         * Cleared automatically when the engine swaps in a fresh raw rows array
+         * (e.g. after a write invalidation).
+         */
+        this._projectionInputRef = null;
+        this._projectionOutput = null;
+        this.descriptor = descriptor;
+        this.cacheKey = _engine
+            ? _engine.getQueryCacheKey(descriptor)
+            : computeCacheKey(descriptor);
+    }
+    /** Public metadata. Mirrors `QueryMetadata` shape. */
+    get metadata() {
+        return { descriptor: this.descriptor, cacheKey: this.cacheKey };
+    }
+    /**
+     * Async load through engine cache.
+     * Pass `{ bypassCache: true }` to ignore cached snapshot and refetch.
+     */
+    load(options) {
+        return this._loadRaw(options).then(rows => this._applySort(rows));
+    }
+    /**
+     * Read cached rows synchronously, if available. Returns `undefined` only if
+     * the cache has no row snapshot. Does not start a load.
+     *
+     * Stale-while-revalidate contract: pending/error snapshots may still carry
+     * rows from the previous ready load. Expose those rows so consumers can keep
+     * stale data visible while a refresh is in flight.
+     *
+     * Stable reference contract: callers (React, useSyncExternalStore, etc.)
+     * MUST be able to compare the returned array by reference. We memoize the
+     * typed+sorted projection keyed by the raw rows reference from the engine
+     * cache. As long as the engine cache hasn't moved, this returns the exact
+     * same array instance.
+     */
+    peekCache() {
+        if (!this._engine)
+            return undefined;
+        const snap = this._engine.readQueryCache(this.descriptor);
+        if (!snap.rows)
+            return undefined;
+        return this._project(snap.rows);
+    }
+    /**
+     * Sync status read for cache consumers (e.g. React bindings). Mirrors the
+     * cache snapshot status without exposing engine internals.
+     */
+    peekStatus() {
+        if (!this._engine)
+            return { status: 'empty' };
+        const snap = this._engine.readQueryCache(this.descriptor);
+        return { status: snap.status, error: snap.error };
+    }
+    /**
+     * Render-time read. If the engine is ready and a cache snapshot exists,
+     * returns rows synchronously (no flash). Otherwise returns a promise.
+     * If the engine is not ready and `mode === 'cache-first'`, falls back to
+     * sync `undefined`-like behavior by returning a promise — caller decides.
+     */
+    readForRender(policy) {
+        const cached = this.peekCache();
+        if (cached && policy?.mode !== 'bypass-cache')
+            return cached;
+        return this.load({ bypassCache: policy?.mode === 'bypass-cache' });
+    }
+    then(onfulfilled, onrejected) {
+        return this.load().then(onfulfilled, onrejected);
+    }
+    /**
+     * Sort the result. Same signature as `Array.prototype.sort`.
+     * Sync-only. Does NOT change `cacheKey` — this is post-load derivation.
+     */
+    sort(compareFn) {
+        const next = (rows) => [...rows].sort(compareFn);
+        return new QueryResult(this.descriptor, this._engine, [...this._sortChain, next], this._explicitPromise);
+    }
+    /**
+     * Sort by a single field. Default: ascending.
+     *
+     * Deterministic and serializable, so it lives on the descriptor and
+     * participates in `cacheKey`. Two queries with the same shape and the
+     * same `orderBy` share a cache entry; differing only by direction or
+     * field produces a distinct cache entry.
+     *
+     * Re-applying `orderBy` overwrites the previous one (last write wins).
+     * The sync `.sort(compareFn)` chain is preserved on top of orderBy for
+     * post-load derivations.
+     */
+    orderBy(field, dir = 'asc') {
+        const nextDescriptor = {
+            ...this.descriptor,
+            orderBy: { field: field, dir },
+        };
+        return new QueryResult(nextDescriptor, this._engine, this._sortChain, this._explicitPromise);
+    }
+    /**
+     * Subscribe to changes that affect this query's table.
+     * Returns an unsubscribe function. Currently table-wide; finer-grained
+     * invalidation can be added in core later without changing this contract.
+     */
+    subscribe(cb) {
+        if (!this._engine)
+            return () => { };
+        const engine = this._engine;
+        const tableName = this.descriptor.table;
+        return engine.on(event => {
+            if (event.type === 'change' && event.table === tableName) {
+                cb({ type: 'change', rowId: event.rowId, row: rowToTyped(event.row) });
+            }
+            else if (event.type === 'delete' && event.table === tableName) {
+                cb({ type: 'delete', rowId: event.rowId });
+            }
+        });
+    }
+    _project(rawRows) {
+        if (this._projectionInputRef === rawRows && this._projectionOutput !== null) {
+            return this._projectionOutput;
+        }
+        const typed = rawRows.map(r => rowToTyped(r));
+        const sorted = this._applySort(typed);
+        this._projectionInputRef = rawRows;
+        this._projectionOutput = sorted;
+        return sorted;
+    }
+    _applySort(rows) {
+        if (this._sortChain.length === 0)
+            return rows;
+        let out = rows;
+        for (const fn of this._sortChain)
+            out = fn(out);
+        return out;
+    }
+    async _loadRaw(options) {
+        if (this._explicitPromise)
+            return this._explicitPromise;
+        if (!this._engine)
+            return [];
+        const rawRows = await this._engine.loadQueryRows(this.descriptor, options);
+        // Use the same projection cache so post-load + peekCache yield the
+        // same reference for the same raw rows.
+        return this._project(rawRows);
+    }
+}
+/**
+ * Stable, deterministic cache key derived from a query descriptor.
+ *
+ * Only async-affecting fields are included. Sync derivations (custom `sort`)
+ * are intentionally excluded.
+ */
+export function computeCacheKey(descriptor) {
+    const parts = [`t=${descriptor.table}`];
+    if (descriptor.clause) {
+        const c = descriptor.clause;
+        parts.push(`w=${c.field}:${c.op}`);
+        if (c.value !== undefined)
+            parts.push(`v=${serializePrimitive(c.value)}`);
+        if (c.values !== undefined)
+            parts.push(`vs=${c.values.map(serializePrimitive).join(',')}`);
+        if (c.lower !== undefined)
+            parts.push(`l=${serializePrimitive(c.lower)}`);
+        if (c.upper !== undefined)
+            parts.push(`u=${serializePrimitive(c.upper)}`);
+        if (c.lowerOpen)
+            parts.push('lo=1');
+        if (c.upperOpen)
+            parts.push('uo=1');
+    }
+    if (descriptor.orderBy) {
+        parts.push(`o=${descriptor.orderBy.field}:${descriptor.orderBy.dir}`);
+    }
+    return parts.join('|');
+}
+function serializePrimitive(v) {
+    if (v instanceof Date)
+        return `d:${v.getTime()}`;
+    if (typeof v === 'string')
+        return `s:${v}`;
+    if (typeof v === 'number')
+        return `n:${v}`;
+    if (typeof v === 'boolean')
+        return `b:${v ? 1 : 0}`;
+    return `x:${String(v)}`;
+}
+/**
+ * Thenable result of a single-row read.
+ *
+ * Same contract as `QueryResult`, scaled down to one row:
+ *  - identity is `descriptor` + `cacheKey`
+ *  - `then(...)` / `load(...)` go through the engine row cache
+ *  - `peekCache()` / `peekStatus()` are sync probes
+ *  - `subscribe(cb)` fires on table events that touch the same rowId
+ *
+ * Returns `undefined` when the row is absent or deleted.
+ */
+export class RowResult {
+    constructor(descriptor, _engine) {
+        this._engine = _engine;
+        /**
+         * Memoization for the typed projection. Keyed by the raw row reference.
+         * Same input ref ⇒ same output ref — required by useSyncExternalStore
+         * consumers and by selector memoization in the React hooks.
+         */
+        this._projectionInputRef = null;
+        this._projectionOutput = null;
+        this.descriptor = descriptor;
+        this.cacheKey = _engine
+            ? _engine.getRowCacheKey(descriptor)
+            : `r=${descriptor.table}|id=${descriptor.rowId}`;
+    }
+    get metadata() {
+        return { descriptor: this.descriptor, cacheKey: this.cacheKey };
+    }
+    _project(rawRow) {
+        if (!rawRow)
+            return undefined;
+        if (this._projectionInputRef === rawRow && this._projectionOutput !== null) {
+            return this._projectionOutput;
+        }
+        const typed = rowToTyped(rawRow);
+        this._projectionInputRef = rawRow;
+        this._projectionOutput = typed;
+        return typed;
+    }
+    load(options) {
+        if (!this._engine)
+            return Promise.resolve(undefined);
+        return this._engine.loadRow(this.descriptor, options).then(r => this._project(r));
+    }
+    /**
+     * Sync cached row, or `undefined` if the cache has no row. Pending/error
+     * snapshots may still carry the previous row for stale-while-revalidate.
+     */
+    peekCache() {
+        if (!this._engine)
+            return undefined;
+        const snap = this._engine.readRowCache(this.descriptor);
+        return this._project(snap.row);
+    }
+    peekStatus() {
+        if (!this._engine)
+            return { status: 'empty' };
+        const snap = this._engine.readRowCache(this.descriptor);
+        return { status: snap.status, error: snap.error };
+    }
+    readForRender(policy) {
+        const cached = this.peekCache();
+        if (cached !== undefined && policy?.mode !== 'bypass-cache')
+            return cached;
+        return this.load({ bypassCache: policy?.mode === 'bypass-cache' });
+    }
+    then(onfulfilled, onrejected) {
+        return this.load().then(onfulfilled, onrejected);
+    }
+    /**
+     * Subscribe to changes that touch this row's `rowId`.
+     * Returns an unsubscribe function. Filtering done here so callers don't
+     * see unrelated table events.
+     */
+    subscribe(cb) {
+        if (!this._engine)
+            return () => { };
+        const engine = this._engine;
+        const { table, rowId } = this.descriptor;
+        return engine.on(event => {
+            if (event.type === 'change' && event.table === table && event.rowId === rowId) {
+                cb({ type: 'change', rowId: event.rowId, row: rowToTyped(event.row) });
+            }
+            else if (event.type === 'delete' && event.table === table && event.rowId === rowId) {
+                cb({ type: 'delete', rowId: event.rowId });
+            }
+        });
+    }
+}
 function rowToTyped(row) {
+    // Project payload only. _meta is engine-private; user types never see it.
     const result = {};
-    for (const [key, val] of Object.entries(row)) {
-        if (key.startsWith('_'))
-            continue;
-        if (val !== null && val !== undefined && typeof val === 'object' && 'value' in val && 'hlc' in val) {
-            result[key] = val.value;
-        }
+    for (const [key, entry] of Object.entries(row.payload)) {
+        result[key] = entry.value;
     }
     return result;
 }
 /**
- * Typed handle for a named collection within a {@link SyncEngine}.
+ * Typed handle for a named collection within a {@link Interocitor}.
  *
  * All reads return plain objects with CRDT metadata stripped away.
  *
@@ -35,29 +332,88 @@ export class Table {
         this.engine = engine;
         this.name = name;
     }
-    /** Retrieve a single record by ID, or undefined if not found / deleted. */
-    async get(rowId) {
-        const row = await this.engine.get(this.name, rowId);
-        return row ? rowToTyped(row) : undefined;
+    /**
+     * Build a single-row handle. Same descriptor + cacheKey contract as
+     * `query()`, scaled down to one row. Lazy: nothing fetched until
+     * `then()` / `load()` / `readForRender()` is called.
+     *
+     * Use `await table.row(id)` for an async fetch, `table.row(id).peekCache()`
+     * for a sync cache read, or pass the handle directly to `useRow`.
+     */
+    row(rowId) {
+        return new RowResult({ table: this.name, rowId }, this.engine);
     }
     /** Retrieve all live (non-deleted) records in this collection. */
-    async query() {
-        const rows = await this.engine.query(this.name);
-        return rows.map(r => rowToTyped(r));
+    query() {
+        return new QueryResult({ table: this.name }, this.engine);
     }
     /** Build a field-scoped where query (Dexie-style, without string schema syntax). */
     where(field) {
         return new TableWhere(this.engine, this.name, field);
     }
-    /** Insert or update a record. Returns the merged result. */
-    async put(rowId, data, userId) {
+    /**
+     * Patch a record — only the provided fields are updated.
+     * Omitted fields are untouched (CRDT per-field merge).
+     * Returns the full merged row.
+     */
+    async patch(rowId, data, userId) {
         const row = await this.engine.put(this.name, rowId, data, userId);
         return rowToTyped(row);
     }
+    /** Back-compat alias for older code paths. */
+    async put(rowId, data, userId) {
+        return this.patch(rowId, data, userId);
+    }
+    /**
+     * Replace a record — writes ALL fields in `data`, explicitly nulling any
+     * fields present in the existing row but absent from `data`.
+     * Returns the full row.
+     */
+    async replace(rowId, data, userId) {
+        // Iterate ONLY existing payload keys. Meta is in a separate namespace
+        // and must never appear as a "field" to be nulled.
+        const existing = await this.engine.loadRow({ table: this.name, rowId });
+        const existingPayloadKeys = existing ? Object.keys(existing.payload) : [];
+        const nulled = Object.fromEntries(existingPayloadKeys.filter(k => !(k in data)).map(k => [k, null]));
+        const row = await this.engine.put(this.name, rowId, { ...nulled, ...data }, userId);
+        return rowToTyped(row);
+    }
+    /**
+     * Insert a new record with an auto-generated row ID.
+     * Returns the generated ID.
+     *
+     * @example
+     * const id = await table.add({ title: 'Buy milk' });
+     * const id = await table.add({ title: 'Buy milk' }, { prefix: 'task' });
+     */
+    async add(data, opts, userId) {
+        const id = createRowId({ prefix: opts?.prefix });
+        await this.engine.put(this.name, id, data, userId);
+        return id;
+    }
     /** Soft-delete a record. */
     async delete(rowId, userId) {
         return this.engine.delete(this.name, rowId, userId);
     }
+    /**
+     * Subscribe to changes in this table. Fires on every change/delete.
+     * Returns an unsubscribe function.
+     *
+     * @example
+     * const unsub = db.table('tasks').subscribe(event => {
+     *   if (event.type === 'change') console.log(event.row);
+     * });
+     */
+    subscribe(cb) {
+        return this.engine.on(event => {
+            if (event.type === 'change' && event.table === this.name) {
+                cb({ type: 'change', rowId: event.rowId, row: rowToTyped(event.row) });
+            }
+            else if (event.type === 'delete' && event.table === this.name) {
+                cb({ type: 'delete', rowId: event.rowId });
+            }
+        });
+    }
 }
 class TableWhere {
     constructor(engine, table, field) {
@@ -65,12 +421,9 @@ class TableWhere {
         this.table = table;
         this.field = field;
     }
-    async run(clause) {
-        const rows = await this.engine.queryWhere(this.table, {
-            field: this.field,
-            ...clause,
-        });
-        return rows.map(row => rowToTyped(row));
+    run(clause) {
+        const fullClause = { field: this.field, ...clause };
+        return new QueryResult({ table: this.table, clause: fullClause }, this.engine);
     }
     equals(value) {
         return this.run({ op: 'equals', value });
@@ -103,4 +456,3 @@ class TableWhere {
         return this.run({ op: 'anyOf', values });
     }
 }
-//# sourceMappingURL=table.js.map