@abloatai/ablo 0.25.0 → 0.27.0

package/dist/core/index.d.ts

@@ -1,28 +1,33 @@
 /**
- * @abloatai/ablo/core — Framework extension
+ * The framework-extension entry point of this package. Import from here only
+ * when you are building on top of the sync engine — wiring your own store and
+ * provider stack, writing a sync adapter, or driving a test harness. Everyday
+ * application code should use the `Ablo({ schema })` client from the package
+ * root instead; the primitives exported here are lower-level building blocks.
  *
- * Only imported by the handful of files that extend or orchestrate the
- * sync engine (the app-shell store/provider stack, sync adapters, demo
- * harnesses). Regular model files and components should NOT import from
- * here — the consumer surface is `Ablo({ schema })` on the root.
- *
- * TRIMMED to what framework-level consumers actually import (verified by
- * a monorepo-wide import scan). Everything else the engine defines stays
- * module-private: if a new framework concern genuinely needs another
- * primitive, add the export deliberately — don't re-widen the barrel.
+ * The surface is deliberately narrow: it exposes only the types and classes an
+ * extension actually needs. Anything the engine does not export here is
+ * internal and may change.
  */
 export { BaseSyncedStore, type ModelConstructor, type ConcreteModelConstructor, } from '../BaseSyncedStore.js';
 export { SyncClient } from '../SyncClient.js';
 export { Database } from '../Database.js';
-export { ObjectPool, ModelScope } from '../ObjectPool.js';
+export { InstanceCache, ModelScope } from '../InstanceCache.js';
+/** @deprecated `ObjectPool` was renamed to {@link InstanceCache} — the class is an
+ *  identity-map cache of live model instances, not a reuse pool. This alias keeps existing
+ *  imports working and will be removed in a future major version. */
+export { InstanceCache as ObjectPool } from '../InstanceCache.js';
 export { Model } from '../Model.js';
 export { LazyReferenceCollection, type LazyCollectionOptions, } from '../LazyReferenceCollection.js';
 export { ModelRegistry, getActiveRegistry, } from '../ModelRegistry.js';
 export { postQuery, type PostQueryOptions } from '../query/client.js';
 export { computeFKDepthPriority, type InternalAbloOptions } from '../client/Ablo.js';
-export type { SyncLogger, SyncObservabilityProvider, MutationExecutor, MutationDispatcher, SessionErrorDetector, OnlineStatusProvider, CommitResult, MutationOperation, } from '../interfaces/index.js';
+export type { SyncLogger, SyncObservabilityProvider, MutationExecutor, SessionErrorDetector, OnlineStatusProvider, CommitResult, MutationOperation, } from '../interfaces/index.js';
 export { SyncWebSocket, type SyncDelta, type SyncWebSocketOptions, } from '../sync/SyncWebSocket.js';
-export { BootstrapHelper } from '../sync/BootstrapHelper.js';
+export { BootstrapFetcher } from '../sync/BootstrapFetcher.js';
+/** @deprecated `BootstrapHelper` was renamed to {@link BootstrapFetcher}. This alias keeps
+ *  existing imports working and will be removed in a future major version. */
+export { BootstrapFetcher as BootstrapHelper } from '../sync/BootstrapFetcher.js';
 export { createClaimStream, type AttachableClaimStream, type ClaimStreamConfig, } from '../sync/createClaimStream.js';
 export { awaitClaimGrant, type GrantTransport, } from '../sync/awaitClaimGrant.js';
 export { LoadStrategy } from '../types/index.js';

package/dist/core/index.js

@@ -1,42 +1,48 @@
 /**
- * @abloatai/ablo/core — Framework extension
+ * The framework-extension entry point of this package. Import from here only
+ * when you are building on top of the sync engine — wiring your own store and
+ * provider stack, writing a sync adapter, or driving a test harness. Everyday
+ * application code should use the `Ablo({ schema })` client from the package
+ * root instead; the primitives exported here are lower-level building blocks.
  *
- * Only imported by the handful of files that extend or orchestrate the
- * sync engine (the app-shell store/provider stack, sync adapters, demo
- * harnesses). Regular model files and components should NOT import from
- * here — the consumer surface is `Ablo({ schema })` on the root.
- *
- * TRIMMED to what framework-level consumers actually import (verified by
- * a monorepo-wide import scan). Everything else the engine defines stays
- * module-private: if a new framework concern genuinely needs another
- * primitive, add the export deliberately — don't re-widen the barrel.
+ * The surface is deliberately narrow: it exposes only the types and classes an
+ * extension actually needs. Anything the engine does not export here is
+ * internal and may change.
  */
-// Base store class + the constructor shapes subclasses reference
+// The base store class, plus the constructor shapes that subclasses reference.
 export { BaseSyncedStore, } from '../BaseSyncedStore.js';
 // Core infrastructure classes
 export { SyncClient } from '../SyncClient.js';
 export { Database } from '../Database.js';
-export { ObjectPool, ModelScope } from '../ObjectPool.js';
+export { InstanceCache, ModelScope } from '../InstanceCache.js';
+/** @deprecated `ObjectPool` was renamed to {@link InstanceCache} — the class is an
+ *  identity-map cache of live model instances, not a reuse pool. This alias keeps existing
+ *  imports working and will be removed in a future major version. */
+export { InstanceCache as ObjectPool } from '../InstanceCache.js';
 export { Model } from '../Model.js';
 export { LazyReferenceCollection, } from '../LazyReferenceCollection.js';
 export { ModelRegistry, getActiveRegistry, } from '../ModelRegistry.js';
-// Lower-level network read — for per-app demand loaders that haven't
-// migrated to `ablo.<model>.list(...)` yet.
+// A lower-level network read primitive. Prefer `ablo.<model>.list(...)` for
+// ordinary reads; reach for this only when writing a custom on-demand loader.
 export { postQuery } from '../query/client.js';
-// FK-cycle / dependency-order helper — used by schema-aware test
-// fixtures and scaffolding tools to compute commit ordering.
+// Computes a dependency-safe ordering for a set of models by walking their
+// foreign-key relationships, so writes commit parents before children. Used by
+// schema-aware test fixtures and scaffolding tools.
 export { computeFKDepthPriority } from '../client/Ablo.js';
-// Sync layer — the wire socket + delta shape, for sync adapters and the
-// multi-agent demo harnesses.
+// The sync layer: the WebSocket wrapper and the delta shape it carries. Needed
+// when writing a sync adapter or a multi-participant test harness.
 export { SyncWebSocket, } from '../sync/SyncWebSocket.js';
-export { BootstrapHelper } from '../sync/BootstrapHelper.js';
-// Claim coordination primitives (the lower-level pieces behind the
-// consumer-facing `ablo.<model>.claim`). The stream factory builds the
-// announce/await machinery on a SyncWebSocket; `awaitClaimGrant` is the
-// fair-queue grant coordinator. Exposed on /core for framework-level
-// orchestration and e2e harnesses — NOT on the consumer `.` root.
+export { BootstrapFetcher } from '../sync/BootstrapFetcher.js';
+/** @deprecated `BootstrapHelper` was renamed to {@link BootstrapFetcher}. This alias keeps
+ *  existing imports working and will be removed in a future major version. */
+export { BootstrapFetcher as BootstrapHelper } from '../sync/BootstrapFetcher.js';
+// The lower-level claim-coordination primitives behind the `ablo.<model>.claim`
+// API. `createClaimStream` builds the announce-and-await machinery on top of a
+// `SyncWebSocket`; `awaitClaimGrant` coordinates fair, first-in-first-out
+// grants. These are for extension code and test harnesses; ordinary
+// application code should use `ablo.<model>.claim`.
 export { createClaimStream, } from '../sync/createClaimStream.js';
 export { awaitClaimGrant, } from '../sync/awaitClaimGrant.js';
-// Schema/model load strategy enum — referenced by model registration in
-// framework code.
+// An enum naming the strategies for loading a model's data. Referenced when
+// registering models in extension code.
 export { LoadStrategy } from '../types/index.js';

package/dist/core/openIDBWithTimeout.d.ts

@@ -1,32 +1,33 @@
 /**
- * Wrap `indexedDB.open()` with a timeout + loud `onblocked` surfacing so the
- * request can never silently hang the app.
+ * The error raised when opening an IndexedDB database does not complete in a
+ * bounded time. {@link openIDBWithTimeout} throws it in two situations: another
+ * browser tab is holding an older version of the database open and blocking the
+ * upgrade (`reason: 'blocked'`), or the open request produced no result at all
+ * within the timeout (`reason: 'timeout'`).
  *
- * The native `IDBOpenDBRequest` has a nasty failure mode: if another tab is
- * holding an older schema version, the request fires `onblocked` and then
- * waits forever for that tab to close the DB. Neither `onsuccess` nor
- * `onerror` fires — the promise wrapping it never settles and every caller
- * above sits indefinitely.
- *
- * This helper converts that into a real error after a bounded wait, which
- * flows up through `engine.ready()` → `SyncEngineProvider.handleError()` →
- * the error skeleton with a retry button. A visible error is strictly better
- * than a forever-spinner the user can only escape by closing the tab.
+ * The native open request can otherwise hang indefinitely — when a blocking tab
+ * never closes its connection, neither the success nor the error callback fires,
+ * and any code awaiting the open waits forever. Turning that into a thrown error
+ * lets the surrounding application show a recoverable failure instead of an
+ * unbreakable spinner.
  */
 export declare class IDBOpenTimeoutError extends Error {
     readonly dbName: string;
     readonly reason: 'blocked' | 'timeout';
     /**
-     * Stable, transport-independent code. `toAbloError` preserves a string
-     * `.code`, so this survives the wrap into `AbloError` and reaches the
-     * provider's `onError` intact — letting the app distinguish a wedged-storage
-     * failure (show a recovery screen) from any other bootstrap error without a
-     * brittle message match.
+     * A stable identifier for this failure, independent of the message text. When
+     * this error is wrapped into an {@link AbloError} by `toAbloError`, the string
+     * code is preserved, so error handlers can recognize a wedged-storage failure
+     * and offer a recovery path rather than matching on the message.
      */
     readonly code = "storage_open_timeout";
     constructor(dbName: string, reason: 'blocked' | 'timeout', message: string);
 }
-/** True for the wedged-IndexedDB failure, after it has been wrapped anywhere. */
+/**
+ * Returns true when a caught value is the storage-open-timeout failure. It
+ * detects the failure by its stable `code`, so it still matches after the error
+ * has been wrapped into an {@link AbloError} or another error type.
+ */
 export declare function isStorageOpenTimeout(err: unknown): boolean;
 export interface OpenIDBOptions {
     /** Called inside `onupgradeneeded` — mirrors `IDBOpenDBRequest.onupgradeneeded`. */
@@ -34,30 +35,31 @@ export interface OpenIDBOptions {
     /** Max milliseconds to wait for the open request to resolve. Default 10_000. */
     timeoutMs?: number;
     /**
-     * Called when another context (a new tab, a fresh deploy, or our own
-     * `deleteIDBWithTimeout` self-heal) fires `versionchange` on this connection.
-     * By default the connection is `close()`d immediately — the W3C/MDN-mandated
-     * behavior that lets the other context's upgrade/delete proceed instead of
-     * blocking forever. Provide this to ALSO react (e.g. prompt a reload) AFTER
-     * the close. Throwing here is swallowed.
+     * Called when another context — a new tab, a page reload after a deploy, or
+     * this package's own {@link deleteIDBWithTimeout} recovery — needs to upgrade
+     * or delete the database and fires a `versionchange` event on this connection.
+     * The connection is always closed first, which is what lets the other
+     * context's upgrade or delete proceed instead of blocking on this one. Provide
+     * this callback to react after that close, for example to prompt the user to
+     * reload. Any error it throws is ignored.
      */
     onVersionChange?: () => void;
 }
 export declare function openIDBWithTimeout(name: string, version: number | undefined, options?: OpenIDBOptions): Promise<IDBDatabase>;
 /**
- * Bounded `indexedDB.deleteDatabase()` — the delete counterpart of
- * `openIDBWithTimeout`. Used by the meta-DB self-heal: when opening
- * `ablo_databases` times out (a wedged backing store), we attempt to delete it
- * and re-create from scratch. The registry it holds is rebuildable from the
- * server on the next bootstrap, so dropping it is safe.
+ * Deletes an IndexedDB database within a bounded time — the delete counterpart
+ * to {@link openIDBWithTimeout}. It is used to recover from a wedged backing
+ * store: when opening a database times out, the caller can delete it and start
+ * fresh, which is safe for any database whose contents can be rebuilt on the
+ * next load.
  *
- * Like `open`, `deleteDatabase` can hang indefinitely: if another live
- * connection holds the DB it fires `onblocked` and waits, and on a truly stuck
- * store it fires *no* event at all. Both become a bounded rejection here so the
- * caller can fall through to surfacing a real error instead of spinning.
+ * Like an open request, a native delete can hang indefinitely — it fires a
+ * blocked event and waits when another connection still holds the database, and
+ * on a truly stuck store it fires no event at all. Both cases become a bounded,
+ * resolved result here, so the caller never spins.
  *
- * Resolves `true` on a clean delete, `false` if it was blocked or timed out
- * (caller decides whether to retry the open regardless — a no-op delete still
- * leaves us no worse off).
+ * Resolves to `true` on a clean delete and `false` when the delete was blocked
+ * or timed out. Either way the caller can decide whether to retry the open; a
+ * delete that did nothing leaves the store no worse off.
  */
 export declare function deleteIDBWithTimeout(name: string, timeoutMs?: number): Promise<boolean>;

package/dist/core/openIDBWithTimeout.js

@@ -1,27 +1,24 @@
 /**
- * Wrap `indexedDB.open()` with a timeout + loud `onblocked` surfacing so the
- * request can never silently hang the app.
+ * The error raised when opening an IndexedDB database does not complete in a
+ * bounded time. {@link openIDBWithTimeout} throws it in two situations: another
+ * browser tab is holding an older version of the database open and blocking the
+ * upgrade (`reason: 'blocked'`), or the open request produced no result at all
+ * within the timeout (`reason: 'timeout'`).
  *
- * The native `IDBOpenDBRequest` has a nasty failure mode: if another tab is
- * holding an older schema version, the request fires `onblocked` and then
- * waits forever for that tab to close the DB. Neither `onsuccess` nor
- * `onerror` fires — the promise wrapping it never settles and every caller
- * above sits indefinitely.
- *
- * This helper converts that into a real error after a bounded wait, which
- * flows up through `engine.ready()` → `SyncEngineProvider.handleError()` →
- * the error skeleton with a retry button. A visible error is strictly better
- * than a forever-spinner the user can only escape by closing the tab.
+ * The native open request can otherwise hang indefinitely — when a blocking tab
+ * never closes its connection, neither the success nor the error callback fires,
+ * and any code awaiting the open waits forever. Turning that into a thrown error
+ * lets the surrounding application show a recoverable failure instead of an
+ * unbreakable spinner.
  */
 export class IDBOpenTimeoutError extends Error {
     dbName;
     reason;
     /**
-     * Stable, transport-independent code. `toAbloError` preserves a string
-     * `.code`, so this survives the wrap into `AbloError` and reaches the
-     * provider's `onError` intact — letting the app distinguish a wedged-storage
-     * failure (show a recovery screen) from any other bootstrap error without a
-     * brittle message match.
+     * A stable identifier for this failure, independent of the message text. When
+     * this error is wrapped into an {@link AbloError} by `toAbloError`, the string
+     * code is preserved, so error handlers can recognize a wedged-storage failure
+     * and offer a recovery path rather than matching on the message.
      */
     code = 'storage_open_timeout';
     constructor(dbName, reason, message) {
@@ -31,7 +28,11 @@ export class IDBOpenTimeoutError extends Error {
         this.name = 'IDBOpenTimeoutError';
     }
 }
-/** True for the wedged-IndexedDB failure, after it has been wrapped anywhere. */
+/**
+ * Returns true when a caught value is the storage-open-timeout failure. It
+ * detects the failure by its stable `code`, so it still matches after the error
+ * has been wrapped into an {@link AbloError} or another error type.
+ */
 export function isStorageOpenTimeout(err) {
     return (typeof err === 'object' &&
         err !== null &&
@@ -57,13 +58,12 @@ export function openIDBWithTimeout(name, version, options = {}) {
             };
         }
         request.onsuccess = () => {
-            // If we ALREADY timed out (or blocked) and rejected, this is a late
+            // If we already timed out or were blocked and rejected, this is a late
             // success: the native open eventually completed after we gave up. The
-            // resulting connection is orphaned — nobody up the stack holds it, so
-            // nobody will `.close()` it. A leaked open connection holds an IndexedDB
-            // lock that wedges every subsequent open/delete of this DB name (the
-            // exact "ablo_databases open/delete hangs forever with no event" failure
-            // mode). Close it here so a timed-out attempt can't poison the store.
+            // resulting connection is orphaned — nothing up the stack holds it, so
+            // nothing will close it. A leaked open connection holds an IndexedDB lock
+            // that wedges every later open or delete of this database name, so close
+            // it here to keep a timed-out attempt from poisoning the store.
             if (settled) {
                 try {
                     request.result.close();
@@ -74,13 +74,12 @@ export function openIDBWithTimeout(name, version, options = {}) {
                 return;
             }
             const db = request.result;
-            // MANDATORY resilience handler (W3C IndexedDB / MDN): close this
-            // connection the instant any other context wants to upgrade or delete the
-            // DB. Without it, an open connection that ignores `versionchange` blocks
-            // the other context's request indefinitely — the root cause of a wedged
-            // `ablo_databases` that survives reloads (an interrupted transaction's
-            // connection never closes, so every later open/delete hangs with no
-            // event). Auto-closing here makes the store self-releasing.
+            // Required resilience handler per the IndexedDB specification: close this
+            // connection as soon as any other context wants to upgrade or delete the
+            // database. Without it, a connection that ignores `versionchange` blocks
+            // the other context's request indefinitely — a common cause of a database
+            // that stays wedged across reloads. Closing here makes the store release
+            // itself.
             db.onversionchange = () => {
                 try {
                     db.close();
@@ -95,41 +94,45 @@ export function openIDBWithTimeout(name, version, options = {}) {
                     // A consumer reaction must never break the close.
                 }
             };
-            settle(() => resolve(db));
+            settle(() => { resolve(db); });
         };
-        request.onerror = () => settle(() => reject(request.error));
+        request.onerror = () => { settle(() => { reject(request.error); }); };
         // The critical handler: another tab is blocking us. Native API leaves
         // the request pending indefinitely; we fail fast with a clear error so
         // the UI can tell the user to close other tabs.
         request.onblocked = () => {
-            settle(() => reject(new IDBOpenTimeoutError(name, 'blocked', `IndexedDB \"${name}\" open blocked — another tab is holding an ` +
-                `older version. Close other Ablo tabs and reload.`)));
+            settle(() => {
+                reject(new IDBOpenTimeoutError(name, 'blocked', `IndexedDB \"${name}\" open blocked — another tab is holding an ` +
+                    `older version. Close other Ablo tabs and reload.`));
+            });
         };
         // Catch-all timeout: even without `onblocked`, some browsers in some
         // storage states hang without firing any event. Bounded wait →
         // deterministic error.
         const timer = setTimeout(() => {
-            settle(() => reject(new IDBOpenTimeoutError(name, 'timeout', `IndexedDB \"${name}\" open did not resolve within ${timeoutMs}ms. ` +
-                `Storage may be in a bad state — clearing site data and reloading ` +
-                `usually fixes this.`)));
+            settle(() => {
+                reject(new IDBOpenTimeoutError(name, 'timeout', `IndexedDB \"${name}\" open did not resolve within ${timeoutMs}ms. ` +
+                    `Storage may be in a bad state — clearing site data and reloading ` +
+                    `usually fixes this.`));
+            });
         }, timeoutMs);
     });
 }
 /**
- * Bounded `indexedDB.deleteDatabase()` — the delete counterpart of
- * `openIDBWithTimeout`. Used by the meta-DB self-heal: when opening
- * `ablo_databases` times out (a wedged backing store), we attempt to delete it
- * and re-create from scratch. The registry it holds is rebuildable from the
- * server on the next bootstrap, so dropping it is safe.
+ * Deletes an IndexedDB database within a bounded time — the delete counterpart
+ * to {@link openIDBWithTimeout}. It is used to recover from a wedged backing
+ * store: when opening a database times out, the caller can delete it and start
+ * fresh, which is safe for any database whose contents can be rebuilt on the
+ * next load.
  *
- * Like `open`, `deleteDatabase` can hang indefinitely: if another live
- * connection holds the DB it fires `onblocked` and waits, and on a truly stuck
- * store it fires *no* event at all. Both become a bounded rejection here so the
- * caller can fall through to surfacing a real error instead of spinning.
+ * Like an open request, a native delete can hang indefinitely — it fires a
+ * blocked event and waits when another connection still holds the database, and
+ * on a truly stuck store it fires no event at all. Both cases become a bounded,
+ * resolved result here, so the caller never spins.
  *
- * Resolves `true` on a clean delete, `false` if it was blocked or timed out
- * (caller decides whether to retry the open regardless — a no-op delete still
- * leaves us no worse off).
+ * Resolves to `true` on a clean delete and `false` when the delete was blocked
+ * or timed out. Either way the caller can decide whether to retry the open; a
+ * delete that did nothing leaves the store no worse off.
  */
 export function deleteIDBWithTimeout(name, timeoutMs = 5_000) {
     return new Promise((resolve) => {
@@ -142,9 +145,9 @@ export function deleteIDBWithTimeout(name, timeoutMs = 5_000) {
             resolve(value);
         };
         const request = indexedDB.deleteDatabase(name);
-        request.onsuccess = () => settle(true);
-        request.onerror = () => settle(false);
-        request.onblocked = () => settle(false);
-        const timer = setTimeout(() => settle(false), timeoutMs);
+        request.onsuccess = () => { settle(true); };
+        request.onerror = () => { settle(false); };
+        request.onblocked = () => { settle(false); };
+        const timer = setTimeout(() => { settle(false); }, timeoutMs);
     });
 }

package/dist/core/queryUtils.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Small, self-contained helpers for sorting, filtering, and binary insertion.
+ * The incrementally-updated views that implement {@link IncrementalView} rely on
+ * these for their ordering and matching, so keeping the rules in one place
+ * ensures every view sorts and filters identically. The functions here work on
+ * plain arrays and values — they hold no reference to models, pools, or the
+ * reactivity system.
+ */
+/**
+ * The interface a live view implements to receive incremental updates: one call
+ * when an entity is added, one when it changes, and one when it is removed. A
+ * view registry holds its views under this non-generic base type so it can keep
+ * views over different entity shapes in a single collection and notify them
+ * uniformly. Because a generic `View<T>` is invariant in `T`, this shared base
+ * is what lets the registry store and dispatch to them without unsafe casts.
+ */
+export interface IncrementalView {
+    handleAdded(entity: Record<string, unknown>): void;
+    handleUpdated(entity: Record<string, unknown>): void;
+    handleRemoved(id: string): void;
+}
+/**
+ * Compares two values for sorting, tolerating `null` and `undefined`, which
+ * always sort last regardless of direction. `dir` is 1 for ascending or -1 for
+ * descending. Returns -1, 0, or 1.
+ */
+export declare function compareValues(a: unknown, b: unknown, dir: 1 | -1): number;
+/**
+ * Finds, by binary search, the index at which `item` should be inserted to keep
+ * an array ordered. The array must already be sorted by `sortKey` in direction
+ * `dir`, using the same rule as {@link compareValues}. Returns that insertion
+ * index.
+ */
+export declare function binaryInsertionIndex<T>(arr: ArrayLike<T>, item: T, sortKey: string, dir: 1 | -1): number;
+/**
+ * Returns true when an entity satisfies a declarative `where` filter: every key
+ * present in `where` must equal the entity's value for that key. A key whose
+ * filter value is `undefined` is skipped, so a partially-filled filter matches
+ * on only its defined keys.
+ */
+export declare function matchesWhere<T extends Record<string, unknown>>(entity: T, where: Partial<T>): boolean;
+/**
+ * Find the index of an entity by id in an array. Returns -1 if not found.
+ */
+export declare function findIndexById<T extends Record<string, unknown>>(arr: ArrayLike<T>, id: string): number;

package/dist/core/queryUtils.js

@@ -0,0 +1,69 @@
+/**
+ * Small, self-contained helpers for sorting, filtering, and binary insertion.
+ * The incrementally-updated views that implement {@link IncrementalView} rely on
+ * these for their ordering and matching, so keeping the rules in one place
+ * ensures every view sorts and filters identically. The functions here work on
+ * plain arrays and values — they hold no reference to models, pools, or the
+ * reactivity system.
+ */
+/**
+ * Compares two values for sorting, tolerating `null` and `undefined`, which
+ * always sort last regardless of direction. `dir` is 1 for ascending or -1 for
+ * descending. Returns -1, 0, or 1.
+ */
+export function compareValues(a, b, dir) {
+    if (a === b)
+        return 0;
+    if (a == null)
+        return 1;
+    if (b == null)
+        return -1;
+    return (a < b ? -1 : 1) * dir;
+}
+/**
+ * Finds, by binary search, the index at which `item` should be inserted to keep
+ * an array ordered. The array must already be sorted by `sortKey` in direction
+ * `dir`, using the same rule as {@link compareValues}. Returns that insertion
+ * index.
+ */
+export function binaryInsertionIndex(arr, item, sortKey, dir) {
+    let lo = 0;
+    let hi = arr.length;
+    const itemVal = item[sortKey];
+    while (lo < hi) {
+        const mid = (lo + hi) >>> 1;
+        const midVal = arr[mid][sortKey];
+        if (compareValues(midVal, itemVal, dir) <= 0) {
+            lo = mid + 1;
+        }
+        else {
+            hi = mid;
+        }
+    }
+    return lo;
+}
+/**
+ * Returns true when an entity satisfies a declarative `where` filter: every key
+ * present in `where` must equal the entity's value for that key. A key whose
+ * filter value is `undefined` is skipped, so a partially-filled filter matches
+ * on only its defined keys.
+ */
+export function matchesWhere(entity, where) {
+    for (const [key, value] of Object.entries(where)) {
+        if (value === undefined)
+            continue;
+        if (entity[key] !== value)
+            return false;
+    }
+    return true;
+}
+/**
+ * Find the index of an entity by id in an array. Returns -1 if not found.
+ */
+export function findIndexById(arr, id) {
+    for (let i = 0; i < arr.length; i++) {
+        if (arr[i]?.id === id)
+            return i;
+    }
+    return -1;
+}