@abloatai/ablo 0.35.0 → 0.37.0

package/dist/sync/OnDemandLoader.js

@@ -1,742 +0,0 @@
-/**
- * Loads model rows on demand — the lazy-load path of the sync engine. When
- * something needs an entity that the initial bootstrap did not fetch,
- * {@link OnDemandLoader.fetch | fetch} finds it and populates the
- * in-memory {@link InstanceCache} so the rest of the engine can read it normally.
- *
- * A fetch resolves against three tiers in order, stopping at the first that can
- * answer:
- *   1. The object pool — if rows already in memory match the query, return them.
- *   2. Local storage — if matching rows exist there, hydrate the pool and return.
- *   3. The network — post the query to `/sync/query`, then hydrate both the pool
- *      and local storage.
- *
- * Concurrent calls with the same query key share one in-flight promise, so a
- * burst of components mounting and asking for the same data on first paint
- * triggers a single fetch rather than one each.
- *
- * The coordinator does not replace the bootstrap (which fully syncs instantly
- * loaded models) or the live delta stream (pushed over the WebSocket). It only
- * fills the gap for lazily loaded models read by id or filter after the engine
- * is ready.
- */
-import { ModelScope } from '../InstanceCache.js';
-import { AbloValidationError } from '../transaction/errors.js';
-import { postQuery } from '../query/client.js';
-function timestampMs(value) {
-    if (value instanceof Date) {
-        const timestamp = value.getTime();
-        return Number.isFinite(timestamp) ? timestamp : undefined;
-    }
-    if (typeof value === 'number' && Number.isFinite(value))
-        return value;
-    if (typeof value !== 'string')
-        return undefined;
-    const parsed = Date.parse(value);
-    return Number.isNaN(parsed) ? undefined : parsed;
-}
-/**
- * A query response is a snapshot, not an ordered delta. It may have started
- * before a local optimistic write and completed after it. Only treat the row
- * as authoritative over an existing model when its server timestamp is newer;
- * missing timestamps retain the legacy merge behavior for custom sources that
- * do not expose `updatedAt`.
- */
-function snapshotDoesNotAdvanceModel(data, model) {
-    const incoming = timestampMs(data.updatedAt);
-    const resident = timestampMs(model.updatedAt);
-    return incoming !== undefined && resident !== undefined && incoming <= resident;
-}
-export class OnDemandLoader {
-    opts;
-    inFlight = new Map();
-    /**
-     * Query keys with a background confirm currently in flight. Distinct from
-     * {@link inFlight} (which dedupes *blocking* callers awaiting the same
-     * fetch): this set dedupes the fire-and-forget network confirm kicked off
-     * after a local-first read returns cached data, so a burst of mounts that
-     * all hit the warm pool/IDB don't each spawn their own redundant fetch.
-     */
-    revalidating = new Set();
-    /**
-     * Query keys that have been satisfied from the server at least once this
-     * session. Once a key is here, repeat reads serve purely from the pool with
-     * no network round-trip: the WebSocket delta stream keeps those pool rows
-     * fresh, so re-running the HTTP query would be redundant polling. This ledger
-     * is what stops an already-open view from re-querying on every navigation.
-     *
-     * Cleared on reconnect (see {@link invalidate}) so that, after a connection
-     * drop where deltas may have been missed, the next read re-confirms once.
-     */
-    hydratedKeys = new Set();
-    authTokenProvider = null;
-    /**
-     * The credential-recovery hook (the store's `recoverFromAuthRejection`),
-     * late-bound like {@link setAuthTokenProvider} because the store does not
-     * exist yet when the coordinator is constructed. Handed to `postQuery` so a
-     * 401 on the lazy lane re-mints through the same single-flight path the
-     * WebSocket probe uses, then replays the query once — instead of silently
-     * returning empty rows against an expired key.
-     */
-    credentialRecovery = null;
-    constructor(opts) {
-        this.opts = opts;
-        // Reading the deprecated `getCapabilityToken` is deliberate: it's the
-        // back-compat shim that keeps older callers who still pass it working
-        // until they migrate to `getAuthToken`.
-        // eslint-disable-next-line @typescript-eslint/no-deprecated
-        this.authTokenProvider = opts.getAuthToken ?? opts.getCapabilityToken ?? null;
-    }
-    /**
-     * Late-bind the auth token getter. Browser cookie consumers can omit this;
-     * bearer consumers need it so lazy HTTP queries use the same credential as
-     * bootstrap and the WebSocket.
-     */
-    setAuthTokenProvider(provider) {
-        this.authTokenProvider = provider;
-    }
-    /** Late-bind the auth-recovery backbone. See {@link credentialRecovery}. */
-    setCredentialRecovery(recover) {
-        this.credentialRecovery = recover;
-    }
-    /** @deprecated Use `setAuthTokenProvider`. */
-    setCapabilityTokenProvider(provider) {
-        this.setAuthTokenProvider(provider);
-    }
-    /**
-     * Fetch matching rows for a model, hydrating the pool from IDB or
-     * network if not already present. Idempotent and single-flight
-     * deduped on the (modelName, where, orderBy, limit) tuple.
-     */
-    async fetch(modelName, options) {
-        const typename = this.resolveTypename(modelName);
-        const ModelClass = this.opts.registry.getModelByName(typename)
-            ?? this.opts.registry.getModelByName(modelName);
-        if (!ModelClass) {
-            throw new AbloValidationError(`OnDemandLoader.fetch: unknown model "${modelName}" — ` +
-                `not registered in the schema.`, { code: 'model_not_registered' });
-        }
-        const clauses = normalizeWhere(options?.where);
-        const queryKey = stableKey(modelName, clauses, options?.orderBy, options?.limit, options?.expand);
-        // Single-flight: an identical hydration is already in flight.
-        const inFlight = this.inFlight.get(queryKey);
-        if (inFlight)
-            return inFlight;
-        const work = this.runFetch(modelName, typename, ModelClass, clauses, options, queryKey);
-        this.inFlight.set(queryKey, work);
-        // The rejection (if any) reaches callers via the returned `work`; this
-        // side-chain only clears the single-flight slot. Without the trailing
-        // catch, `.finally()` mirrors the rejection into a second, unhandled
-        // promise even when every caller handles theirs.
-        void work
-            .finally(() => {
-            this.inFlight.delete(queryKey);
-        })
-            .catch(() => undefined);
-        return work;
-    }
-    async runFetch(modelName, typename, ModelClass, clauses, options, queryKey) {
-        // `{ type: 'complete' }` is the only way to force a server round-trip:
-        // read-after-write certainty. Every other read is local-first.
-        const explicitComplete = options?.type === 'complete';
-        const expand = options?.expand;
-        const hasExpand = !!(expand && expand.length > 0);
-        // Fast path — this exact query was already satisfied from the server this
-        // session. The WebSocket delta stream has kept the pool fresh since, so a
-        // repeat read needs no network: serve straight from local. This is what
-        // stops an already-open view from re-querying on every navigation when no
-        // new deltas have arrived.
-        if (!explicitComplete && this.hydratedKeys.has(queryKey)) {
-            return applyLimit(await this.readLocal(modelName, typename, ModelClass, clauses, hasExpand, expand), options?.limit);
-        }
-        // Not yet hydrated (or an explicit complete read). For a non-complete read
-        // without expand, if there is anything local to show (a warm pool, or local
-        // storage after a reload), hand it back immediately and confirm with the
-        // server once in the background — then mark the key hydrated so subsequent
-        // reads are purely local. First paint never blocks on the network.
-        //
-        // Expand queries are deliberately excluded here: the presence of a primary
-        // row says nothing about whether its relations are loaded. Returning the
-        // parent now would surface it with empty children, letting a readiness flag
-        // flip before the children exist. So an un-hydrated expand query falls
-        // through to the blocking fetch that brings parent and children together;
-        // the second open is served by the fast path.
-        if (!explicitComplete && !hasExpand) {
-            const local = await this.readLocal(modelName, typename, ModelClass, clauses, hasExpand, expand);
-            if (local.length > 0) {
-                this.scheduleHydratingFetch(queryKey, modelName, typename, clauses, options);
-                return applyLimit(local, options?.limit);
-            }
-        }
-        // Cold cache, or caller demanded server-confirmed state: block on the
-        // network, then mark this query hydrated so future reads serve local.
-        const networkModels = await this.fetchFromNetwork(modelName, typename, clauses, options);
-        this.hydratedKeys.add(queryKey);
-        if (networkModels.length > 0)
-            return applyLimit(networkModels, options?.limit);
-        // Network returned nothing — fall back to whatever's local (e.g. a
-        // complete read whose server result was empty but IDB still holds rows).
-        return applyLimit(await this.readLocal(modelName, typename, ModelClass, clauses, hasExpand, expand), options?.limit);
-    }
-    /**
-     * Read a query's rows from local storage only — pool first, then IndexedDB
-     * on a pool miss (cold start after reload, or LRU eviction), hydrating the
-     * pool from IDB as a side effect. Resolves requested `expand` relations from
-     * their own local stores too. Never touches the network.
-     */
-    async readLocal(modelName, typename, ModelClass, clauses, hasExpand, expand) {
-        let local = scanPool(this.opts.objectPool, ModelClass, clauses);
-        if (local.length === 0) {
-            const fromIdb = await scanIdb(this.opts.database, typename, clauses);
-            const idbModels = fromIdb
-                .map((raw) => this.hydrateOne(raw, typename))
-                .filter((m) => m !== null);
-            if (idbModels.length > 0) {
-                this.opts.objectPool.addBatch(idbModels, ModelScope.live);
-                local = idbModels;
-            }
-        }
-        if (hasExpand && expand && local.length > 0) {
-            await this.hydrateExpandedFromLocal(modelName, local.map((m) => m.id), expand);
-        }
-        return local;
-    }
-    /**
-     * Drop the hydration ledger so the next read of each query re-confirms with
-     * the server. Called on reconnect — after a connection drop, deltas may have
-     * been missed, so the "WS keeps the pool fresh" assumption no longer holds
-     * until a fresh fetch (or the engine's delta catch-up) reconciles.
-     */
-    invalidate() {
-        this.hydratedKeys.clear();
-    }
-    /**
-     * Run the network leg of a fetch: query the server, hydrate primary rows
-     * (and any expanded relations) into the pool, and persist them to IDB.
-     * Shared by the blocking path (`runFetch` step 3) and the background
-     * revalidation kicked off after an `'unknown'` local hit.
-     */
-    async fetchFromNetwork(modelName, typename, clauses, options) {
-        const networkRows = await this.queryNetwork(modelName, clauses, options);
-        const networkModels = networkRows
-            // Strict: a row the server returned whose type name this client never
-            // registered is a genuine schema collision (the pushed schema differs
-            // from the local one). Throw here, naming the cause, rather than silently
-            // dropping the row and failing downstream as `entity_not_found`.
-            .map((raw) => this.hydrateOne(raw, typename, { strict: true }))
-            .filter((m) => m !== null);
-        if (networkModels.length > 0) {
-            this.opts.objectPool.addBatch(networkModels, ModelScope.live);
-            // Background IDB write — don't block the caller. Expanded children are
-            // persisted to their own stores inside `queryNetwork`/`hydrateExpanded`.
-            void this.persistToIdb(modelName, networkRows);
-        }
-        return networkModels;
-    }
-    /**
-     * Fires the single background confirm for a query that was just served from
-     * local cache but is not hydrated yet. On success the key is marked hydrated,
-     * so every later read serves purely from local with no network until a
-     * reconnect invalidates the ledger. Deduped per query key so a render burst
-     * does not stampede. Errors are swallowed — the caller already has a usable
-     * local snapshot, and a failed confirm leaves the key un-hydrated so the next
-     * read simply tries again.
-     */
-    scheduleHydratingFetch(queryKey, modelName, typename, clauses, options) {
-        if (this.revalidating.has(queryKey))
-            return;
-        this.revalidating.add(queryKey);
-        void this.fetchFromNetwork(modelName, typename, clauses, options)
-            .then(() => {
-            this.hydratedKeys.add(queryKey);
-        })
-            .catch(() => undefined)
-            .finally(() => {
-            this.revalidating.delete(queryKey);
-        });
-    }
-    /**
-     * Hydrate a parent's `hasMany`/`hasOne` relations from their OWN local
-     * stores (pool first, then IndexedDB by the FK secondary index) into the
-     * pool. The mirror of {@link hydrateExpanded} for the local read path:
-     * `hydrateExpanded` walks server-JOINed nested rows, this walks the child
-     * model's own store keyed by the relation's foreign key.
-     *
-     * Fully schema-driven via the relation's `target` + `foreignKey` — no
-     * per-model special-casing. `belongsTo` relations are skipped: those point
-     * at a single parent (the inverse direction), already covered by the
-     * primary scan when that parent is itself the fetched model.
-     */
-    async hydrateExpandedFromLocal(parentModelName, parentIds, relationNames) {
-        if (parentIds.length === 0)
-            return;
-        const parentDef = this.getModelDef(parentModelName);
-        if (!parentDef?.relations)
-            return;
-        for (const rel of relationNames) {
-            const relDef = parentDef.relations[rel];
-            if (!relDef)
-                continue;
-            if (relDef.type !== 'hasMany' && relDef.type !== 'hasOne')
-                continue;
-            const targetKey = relDef.target;
-            const foreignKey = relDef.foreignKey;
-            if (!targetKey || !foreignKey)
-                continue;
-            const targetTypename = this.resolveTypename(targetKey);
-            // Skip parents whose children are already pool-resident (O(1) when the
-            // FK is indexed). Falls through to a local read for the rest.
-            const missing = parentIds.filter((pid) => this.opts.objectPool.getByForeignKey(targetTypename, foreignKey, pid).length === 0);
-            if (missing.length === 0)
-                continue;
-            const rows = await this.readChildrenLocal(targetTypename, foreignKey, missing);
-            const models = rows
-                .map((raw) => this.hydrateOne(this.stampTypename(raw, targetTypename), targetTypename))
-                .filter((m) => m !== null);
-            if (models.length > 0) {
-                this.opts.objectPool.addBatch(models, ModelScope.live);
-            }
-        }
-    }
-    /**
-     * Read a child model's rows from local storage by foreign key.
-     *
-     * Uses the FK secondary index (O(matches) per parent) only when the schema
-     * declares one — `getAllFromIndex` resolves `[]` for a missing index rather
-     * than throwing, so the decision is made up front from the registry, not by
-     * catching. Unindexed FKs — and in-memory stores, which carry no secondary
-     * indexes at all — fall back to a single full-store scan filtered in JS.
-     */
-    async readChildrenLocal(childTypename, foreignKey, parentIds) {
-        const store = this.opts.database.getStore(childTypename);
-        if (!store)
-            return [];
-        const isIndexed = this.opts.registry.getIndexedProperties(childTypename).includes(foreignKey);
-        if (isIndexed) {
-            const collected = [];
-            for (const pid of parentIds) {
-                const rows = await store.getAllFromIndex(foreignKey, pid);
-                if (Array.isArray(rows))
-                    collected.push(...rows);
-            }
-            // A non-empty result means the index is live (browser IDB). Empty can
-            // mean "no children" OR "no physical index" (in-memory) — fall through
-            // to the scan so the in-memory/SSR path stays correct.
-            if (collected.length > 0)
-                return collected;
-        }
-        try {
-            const all = await store.getAll();
-            if (!Array.isArray(all))
-                return [];
-            const idSet = new Set(parentIds);
-            return all.filter((r) => idSet.has((r)[foreignKey]));
-        }
-        catch {
-            return [];
-        }
-    }
-    /** Typed accessor for a model's schema definition (typename + relations). */
-    getModelDef(modelName) {
-        return this.opts.schema.models?.[modelName];
-    }
-    hydrateOne(raw, typename, opts) {
-        if (!raw || typeof raw !== 'object')
-            return null;
-        const obj = raw;
-        if (typeof obj.id !== 'string')
-            return null;
-        if (this.opts.objectPool.has(obj.id)) {
-            // Keep the existing instance alive when a query refreshes it. A query
-            // can carry fresher server state after a missed delta, but unlike the
-            // ordered delta stream it can also finish late with an older snapshot;
-            // the reconciliation below distinguishes those cases before applying.
-            const existing = this.opts.objectPool.get(obj.id);
-            if (existing) {
-                const stamped = this.stampTypename(obj, typename);
-                // Network queries are unordered snapshots. A request that began before
-                // an optimistic resize can return afterward with the old row; applying
-                // it here would visibly snap the live model back, and the matching
-                // authoritative delta cannot repair it because own echoes are
-                // intentionally suppressed. Keep a newer resident row intact.
-                if (snapshotDoesNotAdvanceModel(stamped, existing))
-                    return existing;
-                // If the source has no comparable timestamp, retain pending local
-                // fields while accepting unrelated server fields. This is the same
-                // local-first merge contract used by SyncClient's delta resolver.
-                const localChanges = existing.getChanges();
-                existing.updateFromData(Object.keys(localChanges).length > 0
-                    ? { ...stamped, ...localChanges, updatedAt: existing.updatedAt }
-                    : stamped);
-                return existing;
-            }
-            return null;
-        }
-        // Stamp the known relation typename onto the row when the source
-        // (IndexedDB rows, sometimes network rows) didn't carry one. Without
-        // this, InstanceCache.createFromData falls through to the 'Unknown'
-        // model-name branch and emits the
-        // "InstanceCache.createFromData: No model identifier found" warning,
-        // failing to hydrate the entity from cache (network path then has to
-        // re-populate it). The typename comes from the schema relation
-        // (`'Block'`, `'Section'`, etc.) so no guessing involved.
-        const stamped = this.stampTypename(obj, typename);
-        return this.opts.objectPool.createFromData(stamped, undefined, opts);
-    }
-    /**
-     * Stamp `__typename` onto a row when it's known (from the schema's
-     * relation target). Strips the mangled `_Typename` key the
-     * `postgres.camel` driver leaves behind when the server's SQL
-     * bakes `__typename` into a JSONB literal — the driver's
-     * snake↔camel transform misreads `__typename` as `_typename` with
-     * a leading underscore and produces `_Typename`. InstanceCache only
-     * recognises `__typename`, so without this step nested rows fall
-     * through to the 'Unknown' branch and never instantiate.
-     */
-    stampTypename(item, typename) {
-        if (!item || typeof item !== 'object' || !typename)
-            return item;
-        const obj = item;
-        if (obj.__typename === typename)
-            return obj;
-        // Drop the driver-mangled `_Typename` AND any row-carried `__typename`
-        // that disagrees with the schema's: these rows were returned FOR this
-        // model's query, so the schema typename is correct by construction — and
-        // without stripping it, the spread would put the row's variant (a server
-        // echoing the schema KEY `tasks` instead of the typename `Task`) back on
-        // top of the stamp, sending hydration to the strict unknown-model error.
-        const { _Typename: _dropMangled, __typename: _dropRowVariant, ...rest } = obj;
-        void _dropMangled;
-        void _dropRowVariant;
-        return { __typename: typename, ...rest };
-    }
-    async queryNetwork(modelName, clauses, options) {
-        const typename = this.resolveTypename(modelName);
-        const orderEntries = options?.orderBy ? Object.entries(options.orderBy) : [];
-        const firstOrder = orderEntries[0];
-        const query = {
-            model: typename,
-            where: clauses.map((c) => this.columnizeClause(modelName, c)),
-            ...(firstOrder
-                ? {
-                    orderBy: this.columnizeField(modelName, firstOrder[0]),
-                    order: firstOrder[1] ?? 'asc',
-                }
-                : {}),
-            ...(options?.limit ? { limit: options.limit } : {}),
-            ...(options?.expand && options.expand.length > 0
-                ? { related: options.expand }
-                : {}),
-        };
-        const result = await postQuery({
-            baseUrl: this.opts.baseUrl,
-            getAuthToken: this.authTokenProvider ?? undefined,
-            recoverCredential: this.credentialRecovery ?? undefined,
-        }, { queries: [query] });
-        const rows = Array.isArray(result.results[0]) ? result.results[0] : [];
-        // Normalize: wire rows lack `__typename` when the server elides it.
-        const normalized = rows.map((row) => {
-            if (row && typeof row === 'object' && !('__typename' in row)) {
-                return { __typename: typename, ...row };
-            }
-            return row;
-        });
-        // Expand: server returns related entities nested under each row
-        // (`row.blocks = [{...}, ...]`). Walk the nested shape, stamp the
-        // typename from the schema's relation metadata (the server bakes
-        // `__typename` into the JSONB but the postgres.camel driver
-        // mangles it to `_Typename` mid-flight, so client-side stamping
-        // is the only reliable path), hydrate each related row into its
-        // own typed pool, then leave the nested arrays in place on the
-        // primary row.
-        if (options?.expand && options.expand.length > 0) {
-            this.hydrateExpanded(modelName, normalized, options.expand);
-        }
-        return normalized;
-    }
-    /**
-     * Hydrate nested expanded rows. Resolves each relation's target
-     * typename via the schema and stamps `__typename` on every nested
-     * row before passing to `hydrateOne` — the server's JSONB
-     * `__typename` field gets mangled by `postgres.camel` (`__typename`
-     * → `_Typename`), so the SDK can't trust whatever string lands.
-     */
-    hydrateExpanded(parentModelName, rows, relationNames) {
-        const parentDef = this.getModelDef(parentModelName);
-        for (const row of rows) {
-            if (!row || typeof row !== 'object')
-                continue;
-            const obj = row;
-            for (const rel of relationNames) {
-                const nested = obj[rel];
-                if (!nested)
-                    continue;
-                // Resolve target typename via parent's relations map.
-                const relDef = parentDef?.relations?.[rel];
-                const targetKey = relDef?.target;
-                const targetTypename = targetKey ? this.resolveTypename(targetKey) : undefined;
-                const items = Array.isArray(nested) ? nested : [nested];
-                const models = [];
-                const stampedItems = [];
-                for (const item of items) {
-                    const stamped = this.stampTypename(item, targetTypename);
-                    stampedItems.push(stamped);
-                    const m = this.hydrateOne(stamped);
-                    if (m)
-                        models.push(m);
-                }
-                if (models.length > 0) {
-                    this.opts.objectPool.addBatch(models, ModelScope.live);
-                }
-                // Persist expanded children to their OWN typed store so they survive
-                // reload and can be re-served by `hydrateExpandedFromLocal` — without
-                // this, expand-fetched relations live only inside the parent's row
-                // and are lost to a lazy child query after a cold start.
-                if (stampedItems.length > 0 && targetKey) {
-                    void this.persistToIdb(targetKey, stampedItems);
-                }
-            }
-        }
-    }
-    async persistToIdb(modelName, rows) {
-        const store = this.opts.database.getStore(this.resolveTypename(modelName));
-        if (!store)
-            return;
-        for (const row of rows) {
-            try {
-                await store.put(row);
-            }
-            catch {
-                // IDB writes are best-effort — a transient quota/transaction
-                // failure shouldn't break the hydration's primary purpose.
-            }
-        }
-    }
-    resolveTypename(modelName) {
-        // Schema is the source of truth for wire typenames. The model proxy
-        // is keyed by camelCase plural (`blocks`) but the wire query +
-        // InstanceCache typeIndex use the typename (`Block`).
-        const def = this.opts.schema
-            .models?.[modelName];
-        return def?.typename ?? modelName;
-    }
-    columnizeField(modelName, field) {
-        const fields = this.opts.schema.models?.[modelName]?.fields;
-        if (fields) {
-            const direct = fields[field]?.column;
-            if (direct)
-                return direct;
-            for (const [fieldName, meta] of Object.entries(fields)) {
-                const conventional = columnize(fieldName);
-                if (field === fieldName || field === conventional || field === meta.column) {
-                    return meta.column ?? conventional;
-                }
-            }
-        }
-        return /[A-Z]/.test(field) ? columnize(field) : field;
-    }
-    columnizeClause(modelName, clause) {
-        const finalCol = this.columnizeField(modelName, clause[0]);
-        if (clause.length === 2)
-            return [finalCol, clause[1]];
-        return [finalCol, clause[1], clause[2]];
-    }
-}
-// ── Helpers ────────────────────────────────────────────────────────────
-function stableKey(modelName, clauses, orderBy, limit, expand) {
-    // Sort clauses by their stringified form so caller order doesn't
-    // produce different dedup keys for semantically identical queries.
-    const sorted = [...clauses].map((c) => [...c]).sort((a, b) => {
-        const ka = JSON.stringify(a);
-        const kb = JSON.stringify(b);
-        return ka < kb ? -1 : ka > kb ? 1 : 0;
-    });
-    // Expand is part of the query identity: `sections where report=r1` and the same
-    // with `expand:['blocks']` hydrate different data, so they must not share a
-    // ledger/dedup key. Sorted so relation order doesn't fork the key.
-    const expandKey = expand && expand.length > 0 ? [...expand].sort() : undefined;
-    return JSON.stringify({ modelName, where: sorted, orderBy, limit, expand: expandKey });
-}
-function applyLimit(arr, limit) {
-    return typeof limit === 'number' ? arr.slice(0, limit) : arr;
-}
-function scanPool(pool, ModelClass, clauses) {
-    const all = pool.getByType(ModelClass);
-    if (clauses.length === 0)
-        return all;
-    return all.filter((entity) => matchesClauses(entity, clauses));
-}
-async function scanIdb(database, modelName, clauses) {
-    const store = database.getStore(modelName);
-    if (!store)
-        return [];
-    // Fast path: a single equality `id` lookup hits the primary key.
-    const eqClauses = extractEqClauses(clauses);
-    if (clauses.length === 1 && eqClauses.id !== undefined && typeof eqClauses.id === 'string') {
-        try {
-            const row = await store.get(eqClauses.id);
-            return row ? [row] : [];
-        }
-        catch {
-            return [];
-        }
-    }
-    // Index-aware path: when every clause is equality and exactly one
-    // non-id string column is constrained, hit that column's index for
-    // an O(matches) read. Anything involving LIKE/ILIKE/ranges falls
-    // through to full-scan + filter.
-    if (clausesAreAllEquality(clauses)) {
-        const indexedKeys = Object.keys(eqClauses).filter((k) => k !== 'id' && typeof eqClauses[k] === 'string');
-        const idxKey = indexedKeys.length === 1 ? indexedKeys[0] : undefined;
-        if (idxKey !== undefined) {
-            try {
-                const rows = await store.getAllFromIndex(idxKey, eqClauses[idxKey]);
-                if (Array.isArray(rows)) {
-                    return rows.filter((r) => matchesClauses(r, clauses));
-                }
-            }
-            catch {
-                // index doesn't exist — fall through to full-scan path.
-            }
-        }
-    }
-    try {
-        const rows = await store.getAll();
-        return Array.isArray(rows)
-            ? rows.filter((r) => matchesClauses(r, clauses))
-            : [];
-    }
-    catch {
-        return [];
-    }
-}
-/**
- * Normalize `LoadWhere<T>` input to the canonical `readonly WhereClause[]`
- * tuple form used throughout `runFetch`. Tuple inputs pass through; object
- * inputs become one `['col', '=', val]` or `['col', 'IN', vals]` per key.
- *
- * Detection: an array whose first element is itself an array is treated
- * as tuple form. Object form is the fallback.
- *
- * Exported so callers can pre-normalize (e.g., for tests, or to inspect
- * the canonical clauses before passing them to `load`/`subscribe`).
- */
-export function normalizeWhere(where) {
-    if (where == null)
-        return [];
-    if (Array.isArray(where)) {
-        // Tuple form — assumed to already use server-side column names.
-        return where;
-    }
-    if (typeof where === 'object') {
-        const obj = where;
-        return Object.entries(obj).map(([key, value]) => {
-            if (Array.isArray(value)) {
-                return [key, 'IN', value];
-            }
-            return [key, value];
-        });
-    }
-    return [];
-}
-/** Equality-only subset of clauses, keyed by column. Used by IDB fast paths. */
-function extractEqClauses(clauses) {
-    const out = {};
-    for (const c of clauses) {
-        if (c.length === 2) {
-            out[c[0]] = c[1];
-        }
-        else if (c[1] === '=') {
-            out[c[0]] = c[2];
-        }
-    }
-    return out;
-}
-function clausesAreAllEquality(clauses) {
-    return clauses.every((c) => c.length === 2 || c[1] === '=');
-}
-/**
- * Operator-aware predicate. Mirrors the server's WhereOp semantics for
- * local matching against pool/IDB rows. LIKE/ILIKE use SQL wildcards
- * (`%` = any chars, `_` = one char) translated to a JS regex.
- *
- * Exported so callers can apply the same predicate to in-memory
- * collections (tests, batch operations) using the canonical clauses.
- */
-export function matchesClauses(entity, clauses) {
-    for (const clause of clauses) {
-        const col = clause[0];
-        const op = clause.length === 2 ? '=' : clause[1];
-        const expected = clause.length === 2 ? clause[1] : clause[2];
-        const v = entity[col];
-        if (!matchOp(v, op, expected))
-            return false;
-    }
-    return true;
-}
-function matchOp(actual, op, expected) {
-    switch (op) {
-        case '=':
-            return actual === expected;
-        case '!=':
-            return actual !== expected;
-        case '<':
-            return compareOrdered(actual, expected, (a, b) => a < b);
-        case '<=':
-            return compareOrdered(actual, expected, (a, b) => a <= b);
-        case '>':
-            return compareOrdered(actual, expected, (a, b) => a > b);
-        case '>=':
-            return compareOrdered(actual, expected, (a, b) => a >= b);
-        case 'IN':
-            return Array.isArray(expected) && expected.some((alt) => alt === actual);
-        case 'NOT IN':
-            return Array.isArray(expected) && !expected.some((alt) => alt === actual);
-        case 'IS':
-            // SQL `IS` is null-equality; the only meaningful right-hand side here is null.
-            return actual === expected;
-        case 'IS NOT':
-            return actual !== expected;
-        case 'LIKE':
-            return typeof actual === 'string' && typeof expected === 'string' && likeRegex(expected, false).test(actual);
-        case 'NOT LIKE':
-            return typeof actual === 'string' && typeof expected === 'string' && !likeRegex(expected, false).test(actual);
-        case 'ILIKE':
-            return typeof actual === 'string' && typeof expected === 'string' && likeRegex(expected, true).test(actual);
-        case 'NOT ILIKE':
-            return typeof actual === 'string' && typeof expected === 'string' && !likeRegex(expected, true).test(actual);
-    }
-}
-/**
- * Ordered comparison helper. Both operands must be non-null and the same
- * comparable primitive (string-vs-string or number-vs-number). Mixed
- * types fall back to JS's loose ordering, which would be confusing — so
- * we reject early to match SQL semantics (a NULL operand yields false).
- */
-function compareOrdered(actual, expected, cmp) {
-    if (actual == null || expected == null)
-        return false;
-    if (typeof actual === 'number' && typeof expected === 'number') {
-        return cmp(actual, expected);
-    }
-    if (typeof actual === 'string' && typeof expected === 'string') {
-        return cmp(actual, expected);
-    }
-    return false;
-}
-/** Translate a SQL LIKE/ILIKE pattern to a JS regex (`%` → `.*`, `_` → `.`). */
-function likeRegex(pattern, insensitive) {
-    // Escape regex specials *except* `%` and `_`, then translate those.
-    const escaped = pattern.replace(/[\\^$.*+?()[\]{}|]/g, '\\$&');
-    const body = escaped.replace(/%/g, '.*').replace(/_/g, '.');
-    return new RegExp(`^${body}$`, insensitive ? 'i' : '');
-}
-/**
- * Schema fields are camelCase (`sectionId`); the wire query expects
- * the server-side column name. The query server's input resolver
- * casing-folds, but we send snake_case to match the convention used
- * by the existing loaders' postQuery calls (`'section_id'` etc.).
- */
-function columnize(field) {
-    return field.replace(/[A-Z]/g, (c) => `_${c.toLowerCase()}`);
-}