@abloatai/ablo 0.26.0 → 0.27.0

package/dist/testing/fixtures/deltas.js

@@ -1,7 +1,8 @@
 /**
- * Delta factories for sync engine tests.
- *
- * Creates well-formed SyncAction objects matching the server wire format.
+ * Factories that build well-formed delta objects for tests. A delta, a
+ * {@link SyncAction}, is a single change to one model instance in the wire
+ * format the server sends: an insert, update, delete, archive, and so on.
+ * These helpers let tests construct deltas without a live server.
  */
 let deltaCounter = 0;
 /** Reset the delta counter (call in beforeEach for deterministic IDs) */
@@ -9,7 +10,7 @@ export function resetDeltaCounter() {
     deltaCounter = 0;
 }
 /**
- * Create a single SyncAction (delta) matching the server wire format.
+ * Builds a single delta ({@link SyncAction}) in the server's wire format.
  */
 export function createDelta(options) {
     deltaCounter++;
@@ -23,25 +24,25 @@ export function createDelta(options) {
     };
 }
 /**
- * Create an INSERT delta for a new entity.
+ * Builds an insert delta for a new entity.
  */
 export function createInsertDelta(modelName, modelId, data, syncId) {
     return createDelta({ modelName, modelId, action: 'I', data, id: syncId });
 }
 /**
- * Create an UPDATE delta for an existing entity.
+ * Builds an update delta for an existing entity.
  */
 export function createUpdateDelta(modelName, modelId, data, syncId) {
     return createDelta({ modelName, modelId, action: 'U', data, id: syncId });
 }
 /**
- * Create a DELETE delta.
+ * Builds a delete delta.
  */
 export function createDeleteDelta(modelName, modelId, syncId) {
     return createDelta({ modelName, modelId, action: 'D', data: {}, id: syncId });
 }
 /**
- * Create an ARCHIVE delta.
+ * Builds an archive delta, stamping `archivedAt` with the current time.
  */
 export function createArchiveDelta(modelName, modelId, syncId) {
     return createDelta({
@@ -53,7 +54,7 @@ export function createArchiveDelta(modelName, modelId, syncId) {
     });
 }
 /**
- * Create an UNARCHIVE (reVive) delta.
+ * Builds an unarchive delta, clearing `archivedAt`.
  */
 export function createUnarchiveDelta(modelName, modelId, syncId) {
     return createDelta({
@@ -65,22 +66,20 @@ export function createUnarchiveDelta(modelName, modelId, syncId) {
     });
 }
 /**
- * Create a COVERING ('C') delta.
- *
- * Signals that the client has gained permission to see an existing entity.
- * Treated as an insert by the client — the entity is added to the local
- * store as if newly created. Typically follows a GroupAdded delta.
+ * Builds a covering ('C') delta. It signals that the client has gained
+ * permission to see an entity that already exists. The client treats it
+ * like an insert, adding the entity to its local store as if newly created.
+ * A covering delta typically follows a group-added delta.
  */
 export function createCoveringDelta(modelName, modelId, data, syncId) {
     return createDelta({ modelName, modelId, action: 'C', data, id: syncId });
 }
 /**
- * Create a GROUP ADDED ('G') delta using the incremental payload shape.
- *
- * Signals that the recipient was added to a single sync group. The client
- * updates its subscription metadata and waits for Covering deltas to
- * deliver the newly-visible entities. Unlike the legacy 'G' payload
- * (addedGroups/removedGroups), this does not trigger a re-bootstrap.
+ * Builds a group-added ('G') delta in the incremental payload shape. It
+ * signals that the recipient was added to a single sync group. The client
+ * updates its subscription state and waits for covering deltas to deliver
+ * the newly visible entities. Unlike the older payload that carries both
+ * added and removed groups, this shape does not trigger a re-bootstrap.
  */
 export function createGroupAddedDelta(userId, group, syncId) {
     return createDelta({
@@ -92,11 +91,10 @@ export function createGroupAddedDelta(userId, group, syncId) {
     });
 }
 /**
- * Create a legacy GROUP CHANGE ('G') delta with the old payload shape.
- *
- * Carries both added and removed groups in one delta and forces a full
- * re-bootstrap on the client. Use for testing backward compatibility with
- * the deprecated EmitGroupChange path.
+ * Builds a group-change ('G') delta in the older payload shape, which
+ * carries both added and removed groups in one delta and forces a full
+ * re-bootstrap on the client. Useful for testing backward compatibility
+ * with that older shape.
  */
 export function createLegacyGroupChangeDelta(userId, added, removed, syncId) {
     return createDelta({
@@ -108,11 +106,9 @@ export function createLegacyGroupChangeDelta(userId, added, removed, syncId) {
     });
 }
 /**
- * Create a GROUP REMOVED ('S') delta.
- *
- * Signals that the recipient lost access to a sync group. The client
- * purges affected local state and triggers a re-bootstrap with the
- * updated group list.
+ * Builds a group-removed ('S') delta. It signals that the recipient lost
+ * access to a sync group. The client purges the affected local state and
+ * re-bootstraps with the updated group list.
  */
 export function createGroupRemovedDelta(userId, group, syncId) {
     return createDelta({
@@ -124,15 +120,16 @@ export function createGroupRemovedDelta(userId, group, syncId) {
     });
 }
 /**
- * Create a batch of deltas with sequential sync IDs.
+ * Builds a batch of deltas with sequential sync IDs.
  */
 export function createDeltaBatch(deltas, startingSyncId) {
     const start = startingSyncId ?? deltaCounter + 1;
     return deltas.map((d, i) => createDelta({ ...d, id: start + i }));
 }
 /**
- * Create a confirmation delta — used to confirm that a mutation
- * was persisted by the server (TransactionQueue watches for this).
+ * Builds a confirmation delta, which signals that a mutation was persisted
+ * by the server. The client's transaction queue watches for these to
+ * confirm its in-flight writes.
  */
 export function createConfirmationDelta(modelName, modelId, syncId, action = 'U', data = {}) {
     return createDelta({ modelName, modelId, action, data, id: syncId });

package/dist/testing/fixtures/models.d.ts

@@ -1,10 +1,9 @@
 /**
- * Test Model subclasses for @abloatai/ablo tests.
- *
- * Lightweight Model implementations with FK relationships matching
- * the MODEL_CREATE_PRIORITY map in TransactionQueue:
- *   TestProject (10) → TestTask (10, FK→Project) → TestComment (30, FK→Task)
- *   TestSlideDeck (10) → TestSlide (15, FK→SlideDeck) → TestSlideLayer (20, FK→Slide)
+ * A small set of {@link Model} subclasses used across the package's tests.
+ * They form two foreign-key chains and carry the creation priorities the
+ * transaction queue uses to order dependent writes:
+ *   TestProject (10) → TestTask (10, references Project) → TestComment (30, references Task)
+ *   TestSlideDeck (10) → TestSlide (15, references SlideDeck) → TestSlideLayer (20, references Slide)
  */
 import { Model } from '../../Model.js';
 import { ModelRegistry } from '../../ModelRegistry.js';
@@ -54,16 +53,18 @@ export declare class TestSlideLayer extends Model {
     getModelName(): string;
 }
 /**
- * Model → priority mapping matching TransactionQueue's MODEL_CREATE_PRIORITY.
+ * Maps each test model to its creation priority, matching the order the
+ * transaction queue uses when writing dependent models.
  */
 export declare const TEST_MODEL_PRIORITIES: Map<string, number>;
 /**
- * Register all test models with a ModelRegistry instance.
- * Sets up properties, references, and FK relationships.
+ * Registers every test model with a {@link ModelRegistry}, wiring up their
+ * properties, references, and foreign-key relationships.
  */
 export declare function registerTestModels(registry: ModelRegistry): void;
 /**
- * Create a SyncEngineConfig pre-configured with test model priorities.
+ * Builds a sync engine configuration pre-loaded with the test models'
+ * creation priorities and related settings.
  */
 export declare function createTestConfig(): {
     modelCreatePriority: ReadonlyMap<string, number>;

package/dist/testing/fixtures/models.js

@@ -1,10 +1,9 @@
 /**
- * Test Model subclasses for @abloatai/ablo tests.
- *
- * Lightweight Model implementations with FK relationships matching
- * the MODEL_CREATE_PRIORITY map in TransactionQueue:
- *   TestProject (10) → TestTask (10, FK→Project) → TestComment (30, FK→Task)
- *   TestSlideDeck (10) → TestSlide (15, FK→SlideDeck) → TestSlideLayer (20, FK→Slide)
+ * A small set of {@link Model} subclasses used across the package's tests.
+ * They form two foreign-key chains and carry the creation priorities the
+ * transaction queue uses to order dependent writes:
+ *   TestProject (10) → TestTask (10, references Project) → TestComment (30, references Task)
+ *   TestSlideDeck (10) → TestSlide (15, references SlideDeck) → TestSlideLayer (20, references Slide)
  */
 import { Model } from '../../Model.js';
 import { ModelRegistry } from '../../ModelRegistry.js';
@@ -127,7 +126,8 @@ export class TestSlideLayer extends Model {
 // Model Registration Helper
 // ─────────────────────────────────────────────
 /**
- * Model → priority mapping matching TransactionQueue's MODEL_CREATE_PRIORITY.
+ * Maps each test model to its creation priority, matching the order the
+ * transaction queue uses when writing dependent models.
  */
 export const TEST_MODEL_PRIORITIES = new Map([
     ['Project', 10],
@@ -138,8 +138,8 @@ export const TEST_MODEL_PRIORITIES = new Map([
     ['Comment', 30],
 ]);
 /**
- * Register all test models with a ModelRegistry instance.
- * Sets up properties, references, and FK relationships.
+ * Registers every test model with a {@link ModelRegistry}, wiring up their
+ * properties, references, and foreign-key relationships.
  */
 export function registerTestModels(registry) {
     registry.startBatch();
@@ -183,7 +183,8 @@ export function registerTestModels(registry) {
 // Test SyncEngineConfig factory
 // ─────────────────────────────────────────────
 /**
- * Create a SyncEngineConfig pre-configured with test model priorities.
+ * Builds a sync engine configuration pre-loaded with the test models'
+ * creation priorities and related settings.
  */
 export function createTestConfig() {
     return {

package/dist/testing/helpers/{react-wrapper.d.ts → reactWrapper.d.ts}

@@ -1,8 +1,8 @@
 /**
- * React test helpers for the sync engine SDK.
- *
- * These helpers wire the SDK's SyncProvider into @testing-library/react
- * so consumers can test components and hooks that use useModel/useModels/useMutations.
+ * React testing helpers for this package. They wire the package's
+ * `SyncProvider` into `@testing-library/react` so you can test components
+ * and hooks built on `useModel`, `useModels`, and `useMutations` against a
+ * mock store, with no live server.
  */
 import * as React from 'react';
 import { type SyncStoreContract } from '../../react/context.js';
@@ -14,8 +14,10 @@ export interface TestWrapperOptions {
     organizationId?: string;
 }
 /**
- * Create a wrapper component for @testing-library/react's renderHook/render.
- * Wraps children in the SDK's SyncProvider with a mock store.
+ * Builds a wrapper component for `@testing-library/react`'s `renderHook`
+ * and `render`. It wraps the children in the package's `SyncProvider`,
+ * backed by a mock store, so the hooks and components under test can read
+ * from it. Pass your own store to seed specific data, or let one be created.
  *
  * @example
  * import { renderHook } from '@testing-library/react';
@@ -33,11 +35,12 @@ export declare function createReactTestWrapper(options?: TestWrapperOptions): Re
     children: React.ReactNode;
 }>;
 /**
- * Drop-in replacement for @testing-library/react's `renderHook` that
- * automatically provides the SDK's SyncProvider with a mock store.
+ * A drop-in replacement for `@testing-library/react`'s `renderHook` that
+ * wraps the hook in the package's `SyncProvider` and a mock store for you,
+ * so you don't build the wrapper by hand.
  *
- * Note: This helper lazy-loads @testing-library/react to avoid forcing
- * consumers without React tests to install it.
+ * `@testing-library/react` is loaded lazily, so projects that don't use
+ * these helpers never have to install it.
  *
  * @example
  * import { renderSyncHook, createMockSyncStore } from '@abloatai/ablo/testing';

package/dist/testing/helpers/{react-wrapper.js → reactWrapper.js}

@@ -1,15 +1,17 @@
 /**
- * React test helpers for the sync engine SDK.
- *
- * These helpers wire the SDK's SyncProvider into @testing-library/react
- * so consumers can test components and hooks that use useModel/useModels/useMutations.
+ * React testing helpers for this package. They wire the package's
+ * `SyncProvider` into `@testing-library/react` so you can test components
+ * and hooks built on `useModel`, `useModels`, and `useMutations` against a
+ * mock store, with no live server.
  */
 import * as React from 'react';
 import { SyncProvider } from '../../react/context.js';
 import { MockSyncStore, createMockSyncStore } from '../mocks/MockSyncStore.js';
 /**
- * Create a wrapper component for @testing-library/react's renderHook/render.
- * Wraps children in the SDK's SyncProvider with a mock store.
+ * Builds a wrapper component for `@testing-library/react`'s `renderHook`
+ * and `render`. It wraps the children in the package's `SyncProvider`,
+ * backed by a mock store, so the hooks and components under test can read
+ * from it. Pass your own store to seed specific data, or let one be created.
  *
  * @example
  * import { renderHook } from '@testing-library/react';
@@ -30,11 +32,12 @@ export function createReactTestWrapper(options = {}) {
     return Wrapper;
 }
 /**
- * Drop-in replacement for @testing-library/react's `renderHook` that
- * automatically provides the SDK's SyncProvider with a mock store.
+ * A drop-in replacement for `@testing-library/react`'s `renderHook` that
+ * wraps the hook in the package's `SyncProvider` and a mock store for you,
+ * so you don't build the wrapper by hand.
  *
- * Note: This helper lazy-loads @testing-library/react to avoid forcing
- * consumers without React tests to install it.
+ * `@testing-library/react` is loaded lazily, so projects that don't use
+ * these helpers never have to install it.
  *
  * @example
  * import { renderSyncHook, createMockSyncStore } from '@abloatai/ablo/testing';
@@ -49,8 +52,8 @@ export function createReactTestWrapper(options = {}) {
  * expect(result.current?.id).toBe(myTask.id);
  */
 export function renderSyncHook(callback, options = {}) {
-    // Lazy-load @testing-library/react so the SDK doesn't force consumers
-    // to install it unless they actually use these helpers.
+    // Load @testing-library/react lazily so projects that never call these
+    // helpers don't have to install it.
     // eslint-disable-next-line @typescript-eslint/no-require-imports
     const rtl = require('@testing-library/react');
     return rtl.renderHook(callback, {

package/dist/testing/helpers/{sync-engine-harness.d.ts → syncEngineHarness.d.ts}

@@ -1,29 +1,29 @@
 /**
- * Full sync engine test harness.
- *
- * Creates a complete stack (ModelRegistry, ObjectPool, TransactionQueue, etc.)
- * with real implementations backed by mocked I/O for integration tests.
+ * An integration-test harness that assembles a full sync engine stack —
+ * the model registry, object pool, transaction queue, and related parts —
+ * from the real implementations, but with mocked input and output. It lets
+ * tests exercise the engine end to end without a network or a live server.
  */
 import { ModelRegistry } from '../../ModelRegistry.js';
-import { ObjectPool } from '../../ObjectPool.js';
+import { InstanceCache } from '../../InstanceCache.js';
 import { MockMutationExecutor } from '../mocks/MockMutationExecutor.js';
 import { MockNetworkMonitor } from '../mocks/MockNetworkMonitor.js';
 import { MockWebSocket } from '../mocks/MockWebSocket.js';
 import type { TestContextResult } from '../mocks/MockSyncContext.js';
 export interface TestHarness {
-    /** Pre-registered ModelRegistry with test models */
+    /** A model registry pre-loaded with the test models. */
     registry: ModelRegistry;
-    /** Real ObjectPool with FK indexes configured */
-    pool: ObjectPool;
-    /** Mock WebSocket for delta injection */
+    /** A real object pool with the test foreign-key indexes configured. */
+    pool: InstanceCache;
+    /** A mock WebSocket for injecting deltas into the engine. */
     webSocket: MockWebSocket;
-    /** DI context with all mocks */
+    /** The dependency-injection context holding every mock. */
     context: TestContextResult;
-    /** Shorthand: mock mutation executor */
+    /** Shorthand for the mock mutation executor on {@link context}. */
     mutationExecutor: MockMutationExecutor;
-    /** Shorthand: mock network monitor */
+    /** Shorthand for the mock network monitor on {@link context}. */
     networkMonitor: MockNetworkMonitor;
-    /** Cleanup everything */
+    /** Tears down the harness and resets its counters. */
     cleanup: () => void;
 }
 export interface TestHarnessOptions {
@@ -31,7 +31,7 @@ export interface TestHarnessOptions {
     startOffline?: boolean;
     /** Initial sync ID for mutation executor */
     initialSyncId?: number;
-    /** ObjectPool config overrides */
+    /** InstanceCache config overrides */
     poolConfig?: {
         maxSize?: number;
         maxAge?: number;
@@ -40,7 +40,9 @@ export interface TestHarnessOptions {
     };
 }
 /**
- * Create a full test harness with real sync engine components + mocked I/O.
+ * Builds a full test harness: real sync engine components wired to mocked
+ * input and output. Reset the counters and tear everything down through the
+ * returned {@link TestHarness.cleanup}.
  *
  * Usage:
  * ```ts

package/dist/testing/helpers/{sync-engine-harness.js → syncEngineHarness.js}

@@ -1,11 +1,11 @@
 /**
- * Full sync engine test harness.
- *
- * Creates a complete stack (ModelRegistry, ObjectPool, TransactionQueue, etc.)
- * with real implementations backed by mocked I/O for integration tests.
+ * An integration-test harness that assembles a full sync engine stack —
+ * the model registry, object pool, transaction queue, and related parts —
+ * from the real implementations, but with mocked input and output. It lets
+ * tests exercise the engine end to end without a network or a live server.
  */
 import { ModelRegistry, setActiveRegistry } from '../../ModelRegistry.js';
-import { ObjectPool } from '../../ObjectPool.js';
+import { InstanceCache } from '../../InstanceCache.js';
 import { MockMutationExecutor } from '../mocks/MockMutationExecutor.js';
 import { MockNetworkMonitor } from '../mocks/MockNetworkMonitor.js';
 import { MockWebSocket } from '../mocks/MockWebSocket.js';
@@ -13,7 +13,9 @@ import { createTestContext } from '../mocks/MockSyncContext.js';
 import { registerTestModels, createTestConfig, resetFixtureCounter, } from '../fixtures/models.js';
 import { resetDeltaCounter } from '../fixtures/deltas.js';
 /**
- * Create a full test harness with real sync engine components + mocked I/O.
+ * Builds a full test harness: real sync engine components wired to mocked
+ * input and output. Reset the counters and tear everything down through the
+ * returned {@link TestHarness.cleanup}.
  *
  * Usage:
  * ```ts
@@ -30,7 +32,7 @@ export function createTestHarness(options = {}) {
     const registry = new ModelRegistry();
     setActiveRegistry(registry);
     registerTestModels(registry);
-    // Create DI context with test config
+    // Create the dependency-injection context with the test config
     const testConfig = createTestConfig();
     const context = createTestContext({
         config: testConfig,
@@ -39,14 +41,14 @@ export function createTestHarness(options = {}) {
             initialSyncId: options.initialSyncId ?? 1,
         },
     });
-    // Create real ObjectPool with FK indexes
-    const pool = new ObjectPool({
+    // Create the real object pool with foreign-key indexes
+    const pool = new InstanceCache({
         maxSize: options.poolConfig?.maxSize ?? 10000,
         maxAge: options.poolConfig?.maxAge ?? 5 * 60 * 1000,
         gcInterval: options.poolConfig?.gcInterval ?? 0, // Disable auto-GC in tests
         useWeakRefs: options.poolConfig?.useWeakRefs ?? false, // Disable WeakRefs for predictable tests
     }, registry);
-    // Register FK indexes for test models
+    // Register foreign-key indexes for the test models
     pool.registerForeignKey('Task', 'projectId');
     pool.registerForeignKey('Comment', 'taskId');
     pool.registerForeignKey('Slide', 'deckId');

package/dist/testing/helpers/wait.d.ts

@@ -1,25 +1,30 @@
 /**
- * Async test helpers for timing-sensitive sync engine tests.
+ * Asynchronous helpers for tests whose assertions depend on timing — for
+ * flushing pending work, polling for a condition, or waiting a fixed delay.
  */
 /**
- * Flush all pending microtasks (Promise.resolve, queueMicrotask).
- * Critical for testing TransactionQueue's microtask batching.
+ * Flushes all pending microtasks, such as resolved promises and
+ * `queueMicrotask` callbacks. Useful for testing work the transaction queue
+ * batches on the microtask queue.
  */
 export declare function flushMicrotasks(): Promise<void>;
 /**
- * Wait for a condition to become true, polling at intervals.
- * Times out after maxWait ms.
+ * Polls `condition` until it returns true, checking every `interval`
+ * milliseconds. Rejects with an {@link AbloConnectionError} if `maxWait`
+ * milliseconds pass first.
  */
 export declare function waitFor(condition: () => boolean, options?: {
     maxWait?: number;
     interval?: number;
 }): Promise<void>;
 /**
- * Wait for N milliseconds. Use sparingly — prefer flushMicrotasks() or waitFor().
+ * Waits for the given number of milliseconds. Use sparingly; prefer
+ * {@link flushMicrotasks} or {@link waitFor}, which don't tie tests to
+ * wall-clock time.
  */
 export declare function delay(ms: number): Promise<void>;
 /**
- * Run a callback after flushing microtasks.
- * Useful for asserting state after TransactionQueue batch processing.
+ * Flushes pending microtasks, then runs `fn` and returns its result. Handy
+ * for asserting state after the transaction queue processes a batch.
  */
 export declare function afterMicrotasks<T>(fn: () => T): Promise<T>;

package/dist/testing/helpers/wait.js

@@ -1,10 +1,12 @@
 /**
- * Async test helpers for timing-sensitive sync engine tests.
+ * Asynchronous helpers for tests whose assertions depend on timing — for
+ * flushing pending work, polling for a condition, or waiting a fixed delay.
  */
 import { AbloConnectionError } from '../../errors.js';
 /**
- * Flush all pending microtasks (Promise.resolve, queueMicrotask).
- * Critical for testing TransactionQueue's microtask batching.
+ * Flushes all pending microtasks, such as resolved promises and
+ * `queueMicrotask` callbacks. Useful for testing work the transaction queue
+ * batches on the microtask queue.
  */
 export function flushMicrotasks() {
     return new Promise((resolve) => {
@@ -13,8 +15,9 @@ export function flushMicrotasks() {
     });
 }
 /**
- * Wait for a condition to become true, polling at intervals.
- * Times out after maxWait ms.
+ * Polls `condition` until it returns true, checking every `interval`
+ * milliseconds. Rejects with an {@link AbloConnectionError} if `maxWait`
+ * milliseconds pass first.
  */
 export async function waitFor(condition, options = {}) {
     const { maxWait = 5000, interval = 10 } = options;
@@ -29,14 +32,16 @@ export async function waitFor(condition, options = {}) {
     }
 }
 /**
- * Wait for N milliseconds. Use sparingly — prefer flushMicrotasks() or waitFor().
+ * Waits for the given number of milliseconds. Use sparingly; prefer
+ * {@link flushMicrotasks} or {@link waitFor}, which don't tie tests to
+ * wall-clock time.
  */
 export function delay(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
 /**
- * Run a callback after flushing microtasks.
- * Useful for asserting state after TransactionQueue batch processing.
+ * Flushes pending microtasks, then runs `fn` and returns its result. Handy
+ * for asserting state after the transaction queue processes a batch.
  */
 export async function afterMicrotasks(fn) {
     await flushMicrotasks();

package/dist/testing/index.d.ts

@@ -15,7 +15,7 @@ export { TestProject, TestTask, TestComment, TestSlideDeck, TestSlide, TestSlide
 export { createDelta, createInsertDelta, createUpdateDelta, createDeleteDelta, createArchiveDelta, createUnarchiveDelta, createCoveringDelta, createGroupAddedDelta, createLegacyGroupChangeDelta, createGroupRemovedDelta, createDeltaBatch, createConfirmationDelta, resetDeltaCounter, } from './fixtures/deltas.js';
 export { createFullBootstrapResponse, createPartialBootstrapResponse, createTestBootstrapResponse, } from './fixtures/bootstrap.js';
 export type { BootstrapModelData, BootstrapResponse } from './fixtures/bootstrap.js';
-export { createTestHarness, } from './helpers/sync-engine-harness.js';
-export type { TestHarness, TestHarnessOptions } from './helpers/sync-engine-harness.js';
+export { createTestHarness, } from './helpers/syncEngineHarness.js';
+export type { TestHarness, TestHarnessOptions } from './helpers/syncEngineHarness.js';
 export { flushMicrotasks, waitFor, delay, afterMicrotasks, } from './helpers/wait.js';
-export { createReactTestWrapper, renderSyncHook, MockSyncStore, createMockSyncStore, type TestWrapperOptions, } from './helpers/react-wrapper.js';
+export { createReactTestWrapper, renderSyncHook, MockSyncStore, createMockSyncStore, type TestWrapperOptions, } from './helpers/reactWrapper.js';

package/dist/testing/index.js

@@ -26,7 +26,7 @@ export { createFullBootstrapResponse, createPartialBootstrapResponse, createTest
 // ─────────────────────────────────────────────
 // Helpers
 // ─────────────────────────────────────────────
-export { createTestHarness, } from './helpers/sync-engine-harness.js';
+export { createTestHarness, } from './helpers/syncEngineHarness.js';
 export { flushMicrotasks, waitFor, delay, afterMicrotasks, } from './helpers/wait.js';
 // React testing helpers
-export { createReactTestWrapper, renderSyncHook, MockSyncStore, createMockSyncStore, } from './helpers/react-wrapper.js';
+export { createReactTestWrapper, renderSyncHook, MockSyncStore, createMockSyncStore, } from './helpers/reactWrapper.js';

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

@@ -1,8 +1,9 @@
 /**
- * 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 type { MutationExecutor, MutationOperation, MutationOptions, CommitResult } from '../../interfaces/index.js';
 export interface CapturedMutation {
@@ -16,15 +17,15 @@ export interface CapturedMutation {
     timestamp: number;
 }
 export interface MockMutationExecutorOptions {
-    /** Starting lastSyncId — increments by 1 per commit call */
+    /** The first `lastSyncId` to return. It increments by one after each commit. */
     initialSyncId?: number;
-    /** Whether mutations should succeed by default */
+    /** Whether mutations succeed by default. Set this false to make every call reject. */
     shouldSucceed?: boolean;
-    /** Simulated network latency in ms */
+    /** A delay applied before each call resolves, in milliseconds, to simulate a slow network. */
     latencyMs?: number;
 }
 export declare class MockMutationExecutor implements MutationExecutor {
-    /** All captured mutation calls in order */
+    /** Every captured call, in the order it was made. Assertions read from this list. */
     readonly calls: CapturedMutation[];
     /** Current sync ID — incremented on each successful commit */
     private _syncId;
@@ -35,23 +36,23 @@ export declare class MockMutationExecutor implements MutationExecutor {
     /** Per-method response overrides */
     private _responseOverrides;
     constructor(options?: MockMutationExecutorOptions);
-    /** Get current sync ID without incrementing */
+    /** Returns the current sync id without advancing it. */
     get currentSyncId(): number;
-    /** Set the next sync ID to return */
+    /** Sets the next sync id the executor will return. */
     setSyncId(id: number): void;
-    /** Make all mutations fail with given error */
+    /** Makes every mutation reject. Pass an error to control what is thrown. */
     failAll(error?: Error): void;
-    /** Make all mutations succeed again */
+    /** Restores the default where mutations succeed, clearing any failure overrides. */
     succeedAll(): void;
-    /** Make a specific method fail */
+    /** Makes a single named method reject. Pass an error to control what is thrown. */
     failMethod(method: string, error?: Error): void;
-    /** Clear failure override for a method */
+    /** Removes the failure override for one method. */
     clearFailure(method: string): void;
-    /** Get calls filtered by method */
+    /** Returns the captured calls for one method, in order. */
     getCallsByMethod(method: string): CapturedMutation[];
-    /** Get the last call made */
+    /** The most recent captured call, or undefined if none have been made. */
     get lastCall(): CapturedMutation | undefined;
-    /** Reset all state */
+    /** Clears captured calls and restores the initial options. */
     reset(options?: MockMutationExecutorOptions): void;
     commit(operations: MutationOperation[], options?: MutationOptions): Promise<CommitResult>;
     executeCreate(modelName: string, id: string, input: Record<string, unknown>, clientMutationId?: string): Promise<void>;