@abloatai/ablo 0.26.0 → 0.27.0

package/dist/testing/mocks/MockMutationExecutor.js

@@ -1,12 +1,13 @@
 /**
- * MockMutationExecutor — Test double for the MutationExecutor interface.
- *
- * Captures all mutation calls, allows controlled responses (success/failure/latency),
- * and returns configurable lastSyncId for delta confirmation testing.
+ * A test double for {@link MutationExecutor} that records every call instead
+ * of writing to a database. Use it to assert what a component tried to commit
+ * and to script the response — success, failure, or added latency — without a
+ * live backend. Each successful commit hands back an incrementing `lastSyncId`,
+ * so tests can drive the delta-confirmation flow that depends on those ids.
  */
 import { AbloError } from '../../errors.js';
 export class MockMutationExecutor {
-    /** All captured mutation calls in order */
+    /** Every captured call, in the order it was made. Assertions read from this list. */
     calls = [];
     /** Current sync ID — incremented on each successful commit */
     _syncId;
@@ -24,43 +25,43 @@ export class MockMutationExecutor {
     // ─────────────────────────────────────────────
     // Test control API
     // ─────────────────────────────────────────────
-    /** Get current sync ID without incrementing */
+    /** Returns the current sync id without advancing it. */
     get currentSyncId() {
         return this._syncId;
     }
-    /** Set the next sync ID to return */
+    /** Sets the next sync id the executor will return. */
     setSyncId(id) {
         this._syncId = id;
     }
-    /** Make all mutations fail with given error */
+    /** Makes every mutation reject. Pass an error to control what is thrown. */
     failAll(error) {
         this._shouldSucceed = false;
         if (error) {
             this._failureOverrides.set('*', error);
         }
     }
-    /** Make all mutations succeed again */
+    /** Restores the default where mutations succeed, clearing any failure overrides. */
     succeedAll() {
         this._shouldSucceed = true;
         this._failureOverrides.clear();
     }
-    /** Make a specific method fail */
+    /** Makes a single named method reject. Pass an error to control what is thrown. */
     failMethod(method, error) {
         this._failureOverrides.set(method, error ?? new Error(`Mock ${method} failed`));
     }
-    /** Clear failure override for a method */
+    /** Removes the failure override for one method. */
     clearFailure(method) {
         this._failureOverrides.delete(method);
     }
-    /** Get calls filtered by method */
+    /** Returns the captured calls for one method, in order. */
     getCallsByMethod(method) {
         return this.calls.filter((c) => c.method === method);
     }
-    /** Get the last call made */
+    /** The most recent captured call, or undefined if none have been made. */
     get lastCall() {
         return this.calls[this.calls.length - 1];
     }
-    /** Reset all state */
+    /** Clears captured calls and restores the initial options. */
     reset(options) {
         this.calls.length = 0;
         this._syncId = options?.initialSyncId ?? 1;

package/dist/testing/mocks/MockNetworkMonitor.d.ts

@@ -1,20 +1,20 @@
 /**
- * MockNetworkMonitor — Test double for OnlineStatusProvider.
- *
- * Allows tests to programmatically toggle online/offline state
- * and trigger visibility change events.
+ * A test double for {@link OnlineStatusProvider} that lets tests flip the
+ * connection between online and offline on demand. Alongside its own state, it
+ * updates the global `navigator.onLine` flag so code that reads the browser
+ * value directly sees the same status.
  */
 import type { OnlineStatusProvider } from '../../interfaces/index.js';
 export declare class MockNetworkMonitor implements OnlineStatusProvider {
     private _online;
     constructor(initialOnline?: boolean);
     isOnline(): boolean;
-    /** Simulate going online */
+    /** Marks the connection online and sets `navigator.onLine` to true. */
     goOnline(): void;
-    /** Simulate going offline */
+    /** Marks the connection offline and sets `navigator.onLine` to false. */
     goOffline(): void;
-    /** Toggle online state and return new value */
+    /** Flips between online and offline, returning the new online state. */
     toggle(): boolean;
-    /** Reset to initial state (online) */
+    /** Returns the monitor to its online starting state. */
     reset(): void;
 }

package/dist/testing/mocks/MockNetworkMonitor.js

@@ -1,8 +1,8 @@
 /**
- * MockNetworkMonitor — Test double for OnlineStatusProvider.
- *
- * Allows tests to programmatically toggle online/offline state
- * and trigger visibility change events.
+ * A test double for {@link OnlineStatusProvider} that lets tests flip the
+ * connection between online and offline on demand. Alongside its own state, it
+ * updates the global `navigator.onLine` flag so code that reads the browser
+ * value directly sees the same status.
  */
 export class MockNetworkMonitor {
     _online;
@@ -12,7 +12,7 @@ export class MockNetworkMonitor {
     isOnline() {
         return this._online;
     }
-    /** Simulate going online */
+    /** Marks the connection online and sets `navigator.onLine` to true. */
     goOnline() {
         this._online = true;
         // Also update navigator.onLine for code that reads it directly
@@ -21,7 +21,7 @@ export class MockNetworkMonitor {
             value: true,
         });
     }
-    /** Simulate going offline */
+    /** Marks the connection offline and sets `navigator.onLine` to false. */
     goOffline() {
         this._online = false;
         Object.defineProperty(navigator, 'onLine', {
@@ -29,7 +29,7 @@ export class MockNetworkMonitor {
             value: false,
         });
     }
-    /** Toggle online state and return new value */
+    /** Flips between online and offline, returning the new online state. */
     toggle() {
         if (this._online) {
             this.goOffline();
@@ -39,7 +39,7 @@ export class MockNetworkMonitor {
         }
         return this._online;
     }
-    /** Reset to initial state (online) */
+    /** Returns the monitor to its online starting state. */
     reset() {
         this.goOnline();
     }

package/dist/testing/mocks/MockSyncContext.d.ts

@@ -1,44 +1,47 @@
 /**
- * MockSyncContext — Creates a fully-wired SyncEngineContext for tests.
- *
- * `createTestContext()` is the primary test utility: it builds a complete
- * DI container with mock implementations, calls initSyncEngine(), and
- * returns handles to all mocks for test assertions.
+ * Assembles a ready-to-use {@link SyncEngineContext} for tests. The context
+ * bundles every dependency the engine needs — logger, network monitor,
+ * mutation executor, and configuration — so a test can start the engine
+ * without a real backend. {@link createTestContext} is the entry point: it
+ * wires the mocks, installs the context globally through {@link initSyncEngine},
+ * and returns handles to each mock for assertions.
  */
 import type { SyncEngineContext } from '../../SyncEngineContext.js';
 import type { SyncLogger, SyncObservabilityProvider, SessionErrorDetector, SyncEngineConfig } from '../../interfaces/index.js';
 import { MockMutationExecutor } from './MockMutationExecutor.js';
 import { MockNetworkMonitor } from './MockNetworkMonitor.js';
 export interface TestContextOptions {
-    /** Override the logger (default: noopLogger) */
+    /** Replaces the default no-op logger. */
     logger?: SyncLogger;
-    /** Override observability (default: noopObservability) */
+    /** Replaces the default no-op observability provider. */
     observability?: SyncObservabilityProvider;
-    /** Override session error detector */
+    /** Replaces the detector that decides whether an error means the session has expired. */
     sessionErrorDetector?: SessionErrorDetector;
-    /** Override mutation executor options */
+    /** Options forwarded to the {@link MockMutationExecutor} that the context creates. */
     mutationExecutorOptions?: ConstructorParameters<typeof MockMutationExecutor>[0];
-    /** Override the sync engine config */
+    /** A partial {@link SyncEngineConfig} merged over the defaults. */
     config?: Partial<SyncEngineConfig>;
-    /** Start offline (default: false) */
+    /** Starts the network monitor offline. Defaults to online. */
     startOffline?: boolean;
 }
 export interface TestContextResult {
-    /** The full SyncEngineContext passed to initSyncEngine */
+    /** The assembled context that {@link createTestContext} installed globally. */
     context: SyncEngineContext;
-    /** Mock handles for test assertions */
+    /** Handles to the underlying mocks, so tests can drive them and assert on them. */
     mocks: {
         mutationExecutor: MockMutationExecutor;
         networkMonitor: MockNetworkMonitor;
     };
-    /** Cleanup: calls resetSyncEngine() */
+    /** Tears the test down by resetting the engine and the mocks. Call it when the test finishes. */
     cleanup: () => void;
 }
 /**
- * Create a test SyncEngineContext with all mocks pre-wired.
- * Calls initSyncEngine() so the global context is set.
+ * Builds a {@link SyncEngineContext} with every mock pre-wired and installs it
+ * globally through {@link initSyncEngine}, so code under test reaches the engine
+ * the same way it would in production. Returns the context, the mock handles,
+ * and a cleanup function to call when the test finishes.
  *
- * Usage:
+ * @example
  * ```ts
  * const { context, mocks, cleanup } = createTestContext();
  * // ... run tests using mocks.mutationExecutor, mocks.networkMonitor

package/dist/testing/mocks/MockSyncContext.js

@@ -1,9 +1,10 @@
 /**
- * MockSyncContext — Creates a fully-wired SyncEngineContext for tests.
- *
- * `createTestContext()` is the primary test utility: it builds a complete
- * DI container with mock implementations, calls initSyncEngine(), and
- * returns handles to all mocks for test assertions.
+ * Assembles a ready-to-use {@link SyncEngineContext} for tests. The context
+ * bundles every dependency the engine needs — logger, network monitor,
+ * mutation executor, and configuration — so a test can start the engine
+ * without a real backend. {@link createTestContext} is the entry point: it
+ * wires the mocks, installs the context globally through {@link initSyncEngine},
+ * and returns handles to each mock for assertions.
  */
 import { noopLogger, noopObservability, noopAnalytics, defaultSessionErrorDetector, emptyConfig, } from '../../SyncEngineContext.js';
 import { initSyncEngine, resetSyncEngine } from '../../context.js';
@@ -12,10 +13,12 @@ import { registerTestModels } from '../fixtures/models.js';
 import { MockMutationExecutor } from './MockMutationExecutor.js';
 import { MockNetworkMonitor } from './MockNetworkMonitor.js';
 /**
- * Create a test SyncEngineContext with all mocks pre-wired.
- * Calls initSyncEngine() so the global context is set.
+ * Builds a {@link SyncEngineContext} with every mock pre-wired and installs it
+ * globally through {@link initSyncEngine}, so code under test reaches the engine
+ * the same way it would in production. Returns the context, the mock handles,
+ * and a cleanup function to call when the test finishes.
  *
- * Usage:
+ * @example
  * ```ts
  * const { context, mocks, cleanup } = createTestContext();
  * // ... run tests using mocks.mutationExecutor, mocks.networkMonitor
@@ -57,11 +60,10 @@ export function createTestContext(options = {}) {
         },
         cleanup: () => {
             resetSyncEngine();
-            // Intentionally do NOT clear the active ModelRegistry — async callbacks
-            // from in-flight transactions (e.g. fc.asyncProperty iterations) may
-            // call Model.toJSON() after afterEach runs. Leaving the default
-            // registry in place keeps those calls valid; the next createTestContext
-            // with hasActiveRegistry()===true simply reuses it.
+            // Leave the active ModelRegistry in place on purpose. Async callbacks
+            // from in-flight transactions can call Model.toJSON() after a test's
+            // teardown has run; keeping the default registry available keeps those
+            // late calls valid, and the next createTestContext simply reuses it.
             mutationExecutor.reset();
             networkMonitor.reset();
         },

package/dist/testing/mocks/MockSyncStore.d.ts

@@ -1,11 +1,10 @@
 /**
- * MockSyncStore — a SyncStoreContract implementation for testing.
- *
- * Provides an in-memory store that tests can configure, inspect, and mutate.
- * All reactive operations are synchronous and observable via Jest spies.
+ * An in-memory {@link SyncStoreContract} for tests. It lets you seed rows,
+ * read and write them synchronously, and inspect every call the code under
+ * test made — all without a real sync backend.
  */
 import type { Model } from '../../Model.js';
-import type { ModelScope } from '../../ObjectPool.js';
+import type { ModelScope } from '../../InstanceCache.js';
 import type { SyncStoreContract } from '../../react/context.js';
 interface QueryOptions<T extends Model> {
     predicate?: (model: T) => boolean;
@@ -20,9 +19,10 @@ interface QueryResult<T extends Model> {
 }
 type ModelCtor<T extends Model> = abstract new (...args: never[]) => T;
 /**
- * MockSyncStore is an in-memory implementation of SyncStoreContract.
- * Tests can seed data with `setModels()`, inspect calls via `calls`,
- * and assert behavior without needing a real sync backend.
+ * An in-memory implementation of {@link SyncStoreContract}. Seed rows with
+ * {@link MockSyncStore.setModels}, then read and write through the contract
+ * methods; every call is recorded on {@link MockSyncStore.calls} so tests can
+ * assert on what happened.
  */
 export declare class MockSyncStore implements SyncStoreContract {
     private byClass;
@@ -48,7 +48,7 @@ export declare class MockSyncStore implements SyncStoreContract {
      */
     setModels<T extends Model>(modelClass: ModelCtor<T>, models: T[]): void;
     /**
-     * Add a single model (upsert).
+     * Adds or replaces a single model, keyed by its id.
      */
     addModel<T extends Model>(modelClass: ModelCtor<T>, model: T): void;
     /**
@@ -77,7 +77,7 @@ export declare class MockSyncStore implements SyncStoreContract {
         pendingChanges: number;
         isSessionError: boolean;
     };
-    /** Mock pool for useEntity/useEntities hooks. */
+    /** A minimal object pool backing the useEntity and useEntities hooks in tests. */
     pool: SyncStoreContract['pool'];
 }
 /**

package/dist/testing/mocks/MockSyncStore.js

@@ -1,15 +1,15 @@
 /**
- * MockSyncStore — a SyncStoreContract implementation for testing.
- *
- * Provides an in-memory store that tests can configure, inspect, and mutate.
- * All reactive operations are synchronous and observable via Jest spies.
+ * An in-memory {@link SyncStoreContract} for tests. It lets you seed rows,
+ * read and write them synchronously, and inspect every call the code under
+ * test made — all without a real sync backend.
  */
 import { ViewRegistry } from '../../core/ViewRegistry.js';
 import { AbloValidationError } from '../../errors.js';
 /**
- * MockSyncStore is an in-memory implementation of SyncStoreContract.
- * Tests can seed data with `setModels()`, inspect calls via `calls`,
- * and assert behavior without needing a real sync backend.
+ * An in-memory implementation of {@link SyncStoreContract}. Seed rows with
+ * {@link MockSyncStore.setModels}, then read and write through the contract
+ * methods; every call is recorded on {@link MockSyncStore.calls} so tests can
+ * assert on what happened.
  */
 export class MockSyncStore {
     // Seeded data, keyed by model class
@@ -37,7 +37,7 @@ export class MockSyncStore {
         this.byClass.set(modelClass, map);
     }
     /**
-     * Add a single model (upsert).
+     * Adds or replaces a single model, keyed by its id.
      */
     addModel(modelClass, model) {
         let map = this.byClass.get(modelClass);
@@ -110,8 +110,8 @@ export class MockSyncStore {
     }
     async save(model) {
         this.calls.save.push(model);
-        // Auto-seed on save so findById returns it afterwards
-        // Consumer passes a concrete class-less object; we store by constructor
+        // Store the model under its constructor so a later retrieve or query
+        // returns it.
         const ctor = model.constructor;
         this.addModel(ctor, model);
     }
@@ -140,7 +140,7 @@ export class MockSyncStore {
         pendingChanges: 0,
         isSessionError: false,
     };
-    /** Mock pool for useEntity/useEntities hooks. */
+    /** A minimal object pool backing the useEntity and useEntities hooks in tests. */
     pool = {
         get: (id) => {
             for (const models of this.byClass.values()) {

package/dist/testing/mocks/MockWebSocket.d.ts

@@ -1,12 +1,10 @@
 /**
- * MockWebSocket — Controllable WebSocket for sync engine tests.
- *
- * Simulates the SyncWebSocket event interface without a real connection.
- * Provides methods to inject deltas, simulate disconnection/reconnection,
- * and trigger bootstrap hints.
+ * A controllable WebSocket stand-in for sync engine tests. It reproduces the
+ * event interface of the real connection without opening a socket, so tests
+ * can drive connection changes, deltas, and bootstrap hints by hand.
  */
 import type { SyncActionType } from '../../types/index.js';
-/** Delta shape matching the SyncAction interface */
+/** The shape of a single delta — one change the server pushes to the client. */
 export interface MockDelta {
     id: number;
     modelName: string;
@@ -14,7 +12,10 @@ export interface MockDelta {
     action: SyncActionType;
     data: Record<string, unknown>;
 }
-/** Bootstrap hint from server */
+/**
+ * A hint from the server that the client has fallen too far behind and should
+ * rebuild its data from scratch rather than catch up one delta at a time.
+ */
 export interface MockBootstrapHint {
     reason: 'too_far_behind' | 'too_many_deltas' | 'missing_entities';
     tables?: string[];
@@ -22,14 +23,17 @@ export interface MockBootstrapHint {
 }
 type EventHandler = (...args: unknown[]) => void;
 /**
- * MockWebSocket provides a controllable event-based interface
- * for testing sync engine components that consume WebSocket events.
+ * A controllable, event-based stand-in for the sync engine's WebSocket
+ * connection. Subscribe with {@link MockWebSocket.on} exactly as production
+ * code does, then use the `simulate*` and `receive*` methods to push
+ * connection changes, deltas, and bootstrap hints. Every event the mock emits
+ * is recorded on {@link MockWebSocket.emittedEvents} for assertions.
  */
 export declare class MockWebSocket {
     private _connected;
     private _sessionError;
     private _listeners;
-    /** Track all emitted events for assertions */
+    /** Every event the mock has emitted, in order, for assertions. */
     readonly emittedEvents: {
         type: string;
         data: unknown;
@@ -38,29 +42,29 @@ export declare class MockWebSocket {
     get sessionError(): boolean;
     on(event: string, handler: EventHandler): () => void;
     private emit;
-    /** Simulate successful connection */
+    /** Fires a successful connection, emitting the `connected` event. */
     simulateConnect(): void;
-    /** Simulate disconnection */
+    /** Drops the connection, emitting the `disconnected` event. */
     simulateDisconnect(): void;
-    /** Simulate reconnection attempt */
+    /** Emits a `reconnecting` event carrying the attempt number and retry delay. */
     simulateReconnecting(attempt: number, delay: number): void;
-    /** Simulate session error (401/403) */
+    /** Emits a `session_error` event, as when the server rejects the session as unauthorized. The code defaults to 401. */
     simulateSessionError(code?: number): void;
-    /** Simulate reconnection failure (max attempts reached) */
+    /** Emits a `reconnect_failed` event, signaling the client gave up after exhausting its retries. */
     simulateReconnectFailed(): void;
-    /** Inject a single delta (as if received from server) */
+    /** Delivers a single delta, emitting a `delta` event as if the server had sent it. */
     receiveDelta(delta: MockDelta): void;
-    /** Inject a batch of deltas */
+    /** Delivers a batch of deltas, emitting a `delta_batch` event. */
     receiveDeltas(deltas: MockDelta[]): void;
-    /** Inject a bootstrap_required hint from server */
+    /** Emits a `bootstrap_required` hint, telling the client to rebuild its data instead of catching up. */
     simulateBootstrapHint(hint: MockBootstrapHint): void;
-    /** Inject a presence update */
+    /** Emits a `presence_update` event carrying the given payload. */
     simulatePresenceUpdate(data: Record<string, unknown>): void;
-    /** Get all events of a specific type */
+    /** Returns the payloads of every emitted event of the given type, in order. */
     getEvents(type: string): unknown[];
-    /** Check if a specific event was emitted */
+    /** Reports whether an event of the given type has been emitted. */
     hasEmitted(type: string): boolean;
-    /** Reset all state */
+    /** Clears connection state, listeners, and the record of emitted events. */
     reset(): void;
 }
 export {};

package/dist/testing/mocks/MockWebSocket.js

@@ -1,19 +1,20 @@
 /**
- * MockWebSocket — Controllable WebSocket for sync engine tests.
- *
- * Simulates the SyncWebSocket event interface without a real connection.
- * Provides methods to inject deltas, simulate disconnection/reconnection,
- * and trigger bootstrap hints.
+ * A controllable WebSocket stand-in for sync engine tests. It reproduces the
+ * event interface of the real connection without opening a socket, so tests
+ * can drive connection changes, deltas, and bootstrap hints by hand.
  */
 /**
- * MockWebSocket provides a controllable event-based interface
- * for testing sync engine components that consume WebSocket events.
+ * A controllable, event-based stand-in for the sync engine's WebSocket
+ * connection. Subscribe with {@link MockWebSocket.on} exactly as production
+ * code does, then use the `simulate*` and `receive*` methods to push
+ * connection changes, deltas, and bootstrap hints. Every event the mock emits
+ * is recorded on {@link MockWebSocket.emittedEvents} for assertions.
  */
 export class MockWebSocket {
     _connected = false;
     _sessionError = false;
     _listeners = new Map();
-    /** Track all emitted events for assertions */
+    /** Every event the mock has emitted, in order, for assertions. */
     emittedEvents = [];
     get connected() {
         return this._connected;
@@ -22,7 +23,7 @@ export class MockWebSocket {
         return this._sessionError;
     }
     // ─────────────────────────────────────────────
-    // Event subscription (matches SyncWebSocket API)
+    // Event subscription (matches the real connection's API)
     // ─────────────────────────────────────────────
     on(event, handler) {
         if (!this._listeners.has(event)) {
@@ -45,28 +46,28 @@ export class MockWebSocket {
     // ─────────────────────────────────────────────
     // Test control: connection lifecycle
     // ─────────────────────────────────────────────
-    /** Simulate successful connection */
+    /** Fires a successful connection, emitting the `connected` event. */
     simulateConnect() {
         this._connected = true;
         this._sessionError = false;
         this.emit('connected');
     }
-    /** Simulate disconnection */
+    /** Drops the connection, emitting the `disconnected` event. */
     simulateDisconnect() {
         this._connected = false;
         this.emit('disconnected');
     }
-    /** Simulate reconnection attempt */
+    /** Emits a `reconnecting` event carrying the attempt number and retry delay. */
     simulateReconnecting(attempt, delay) {
         this.emit('reconnecting', { attempt, delay });
     }
-    /** Simulate session error (401/403) */
+    /** Emits a `session_error` event, as when the server rejects the session as unauthorized. The code defaults to 401. */
     simulateSessionError(code = 401) {
         this._sessionError = true;
         this._connected = false;
         this.emit('session_error', { code });
     }
-    /** Simulate reconnection failure (max attempts reached) */
+    /** Emits a `reconnect_failed` event, signaling the client gave up after exhausting its retries. */
     simulateReconnectFailed() {
         this._connected = false;
         this.emit('reconnect_failed');
@@ -74,40 +75,40 @@ export class MockWebSocket {
     // ─────────────────────────────────────────────
     // Test control: delta injection
     // ─────────────────────────────────────────────
-    /** Inject a single delta (as if received from server) */
+    /** Delivers a single delta, emitting a `delta` event as if the server had sent it. */
     receiveDelta(delta) {
         this.emit('delta', delta);
     }
-    /** Inject a batch of deltas */
+    /** Delivers a batch of deltas, emitting a `delta_batch` event. */
     receiveDeltas(deltas) {
         this.emit('delta_batch', deltas);
     }
     // ─────────────────────────────────────────────
     // Test control: bootstrap hints
     // ─────────────────────────────────────────────
-    /** Inject a bootstrap_required hint from server */
+    /** Emits a `bootstrap_required` hint, telling the client to rebuild its data instead of catching up. */
     simulateBootstrapHint(hint) {
         this.emit('bootstrap_required', hint);
     }
     // ─────────────────────────────────────────────
     // Test control: presence
     // ─────────────────────────────────────────────
-    /** Inject a presence update */
+    /** Emits a `presence_update` event carrying the given payload. */
     simulatePresenceUpdate(data) {
         this.emit('presence_update', data);
     }
     // ─────────────────────────────────────────────
     // Assertions
     // ─────────────────────────────────────────────
-    /** Get all events of a specific type */
+    /** Returns the payloads of every emitted event of the given type, in order. */
     getEvents(type) {
         return this.emittedEvents.filter((e) => e.type === type).map((e) => e.data);
     }
-    /** Check if a specific event was emitted */
+    /** Reports whether an event of the given type has been emitted. */
     hasEmitted(type) {
         return this.emittedEvents.some((e) => e.type === type);
     }
-    /** Reset all state */
+    /** Clears connection state, listeners, and the record of emitted events. */
     reset() {
         this._connected = false;
         this._sessionError = false;