@abloatai/ablo 0.34.1 → 0.36.0

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

@@ -1,18 +0,0 @@
-import type { Database } from '../../Database.js';
-/**
- * Overrides for {@link fakeDatabase}. Everything is typechecked against
- * Database's public surface except `getPersistedTransactions`, which widens to
- * `unknown[]`: persisted rows are untrusted input (the DurableWriteStore port
- * documents this), and restore-path tests feed deliberately corrupt rows.
- */
-export type FakeDatabaseOverrides = Omit<Partial<Database>, 'getPersistedTransactions'> & {
-    getPersistedTransactions?: () => Promise<unknown[]>;
-};
-/**
- * A Database double that implements ONLY the given members — no real
- * prototype behind it, so a code path reaching for anything else fails
- * loudly instead of silently running real IndexedDB logic. The bare `as`
- * is a single narrowing assert (Database is assignable to the overrides
- * type), so every override stays typechecked against the real surface.
- */
-export declare function fakeDatabase(overrides: FakeDatabaseOverrides): Database;

package/dist/testing/mocks/FakeDatabase.js

@@ -1,10 +0,0 @@
-/**
- * A Database double that implements ONLY the given members — no real
- * prototype behind it, so a code path reaching for anything else fails
- * loudly instead of silently running real IndexedDB logic. The bare `as`
- * is a single narrowing assert (Database is assignable to the overrides
- * type), so every override stays typechecked against the real surface.
- */
-export function fakeDatabase(overrides) {
-    return overrides;
-}

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

@@ -1,87 +0,0 @@
-/**
- * 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';
-import type { StaleNotification } from '../../coordination/schema.js';
-export interface CapturedMutation {
-    method: string;
-    modelName?: string;
-    modelId?: string;
-    input?: Record<string, unknown>;
-    operations?: MutationOperation[];
-    options?: MutationOptions;
-    clientMutationId?: string;
-    timestamp: number;
-}
-export interface MockMutationExecutorOptions {
-    /** The first `lastSyncId` to return. It increments by one after each commit. */
-    initialSyncId?: number;
-    /** Whether mutations succeed by default. Set this false to make every call reject. */
-    shouldSucceed?: boolean;
-    /** A delay applied before each call resolves, in milliseconds, to simulate a slow network. */
-    latencyMs?: number;
-    /** Optional explicit receipt status. Omission preserves legacy confirmed semantics. */
-    status?: CommitResult['status'];
-    /** Optional server-issued source/WAL correlation returned with queued receipts. */
-    correlationId?: string;
-    /** Optional stale-context notifications returned with each commit. */
-    notifications?: StaleNotification[];
-    /** Optional zero-row target ids returned with each commit. */
-    missingIds?: string[];
-}
-export declare class MockMutationExecutor implements MutationExecutor {
-    /** 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;
-    private _shouldSucceed;
-    private _latencyMs;
-    private _status;
-    private _correlationId;
-    private _notifications;
-    private _missingIds;
-    /** Per-method failure overrides: method name → error */
-    private _failureOverrides;
-    /** Per-method response overrides */
-    private _responseOverrides;
-    constructor(options?: MockMutationExecutorOptions);
-    /** Returns the current sync id without advancing it. */
-    get currentSyncId(): number;
-    /** Sets the next sync id the executor will return. */
-    setSyncId(id: number): void;
-    /** Sets the settlement status returned by subsequent commit calls. */
-    setStatus(status: CommitResult['status']): void;
-    /** Sets the opaque source/WAL correlation returned by subsequent commits. */
-    setCorrelationId(correlationId: string | undefined): void;
-    /** Sets stale-context notifications returned by subsequent commit calls. */
-    setNotifications(notifications: StaleNotification[] | undefined): void;
-    /** Sets zero-row target ids returned by subsequent commit calls. */
-    setMissingIds(missingIds: string[] | undefined): void;
-    /** Makes every mutation reject. Pass an error to control what is thrown. */
-    failAll(error?: Error): void;
-    /** Restores the default where mutations succeed, clearing any failure overrides. */
-    succeedAll(): void;
-    /** Makes a single named method reject. Pass an error to control what is thrown. */
-    failMethod(method: string, error?: Error): void;
-    /** Removes the failure override for one method. */
-    clearFailure(method: string): void;
-    /** Returns the captured calls for one method, in order. */
-    getCallsByMethod(method: string): CapturedMutation[];
-    /** The most recent captured call, or undefined if none have been made. */
-    get lastCall(): CapturedMutation | undefined;
-    /** 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>;
-    executeUpdate(modelName: string, modelId: string, data: Record<string, unknown>, clientMutationId?: string): Promise<CommitResult | null>;
-    executeDelete(modelName: string, modelId: string, clientMutationId?: string): Promise<void>;
-    executeArchive(modelName: string, modelId: string, clientMutationId?: string): Promise<void>;
-    executeUnarchive(modelName: string, modelId: string, clientMutationId?: string): Promise<void>;
-    private _capture;
-    private _maybeDelay;
-    private _maybeThrow;
-}

package/dist/testing/mocks/MockMutationExecutor.js

@@ -1,192 +0,0 @@
-/**
- * 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 {
-    /** Every captured call, in the order it was made. Assertions read from this list. */
-    calls = [];
-    /** Current sync ID — incremented on each successful commit */
-    _syncId;
-    _shouldSucceed;
-    _latencyMs;
-    _status;
-    _correlationId;
-    _notifications;
-    _missingIds;
-    /** Per-method failure overrides: method name → error */
-    _failureOverrides = new Map();
-    /** Per-method response overrides */
-    _responseOverrides = new Map();
-    constructor(options = {}) {
-        this._syncId = options.initialSyncId ?? 1;
-        this._shouldSucceed = options.shouldSucceed ?? true;
-        this._latencyMs = options.latencyMs ?? 0;
-        this._status = options.status;
-        this._correlationId = options.correlationId;
-        this._notifications = options.notifications;
-        this._missingIds = options.missingIds;
-    }
-    // ─────────────────────────────────────────────
-    // Test control API
-    // ─────────────────────────────────────────────
-    /** Returns the current sync id without advancing it. */
-    get currentSyncId() {
-        return this._syncId;
-    }
-    /** Sets the next sync id the executor will return. */
-    setSyncId(id) {
-        this._syncId = id;
-    }
-    /** Sets the settlement status returned by subsequent commit calls. */
-    setStatus(status) {
-        this._status = status;
-    }
-    /** Sets the opaque source/WAL correlation returned by subsequent commits. */
-    setCorrelationId(correlationId) {
-        this._correlationId = correlationId;
-    }
-    /** Sets stale-context notifications returned by subsequent commit calls. */
-    setNotifications(notifications) {
-        this._notifications = notifications;
-    }
-    /** Sets zero-row target ids returned by subsequent commit calls. */
-    setMissingIds(missingIds) {
-        this._missingIds = missingIds;
-    }
-    /** Makes every mutation reject. Pass an error to control what is thrown. */
-    failAll(error) {
-        this._shouldSucceed = false;
-        if (error) {
-            this._failureOverrides.set('*', error);
-        }
-    }
-    /** Restores the default where mutations succeed, clearing any failure overrides. */
-    succeedAll() {
-        this._shouldSucceed = true;
-        this._failureOverrides.clear();
-    }
-    /** 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`));
-    }
-    /** Removes the failure override for one method. */
-    clearFailure(method) {
-        this._failureOverrides.delete(method);
-    }
-    /** Returns the captured calls for one method, in order. */
-    getCallsByMethod(method) {
-        return this.calls.filter((c) => c.method === method);
-    }
-    /** The most recent captured call, or undefined if none have been made. */
-    get lastCall() {
-        return this.calls[this.calls.length - 1];
-    }
-    /** Clears captured calls and restores the initial options. */
-    reset(options) {
-        this.calls.length = 0;
-        this._syncId = options?.initialSyncId ?? 1;
-        this._shouldSucceed = options?.shouldSucceed ?? true;
-        this._latencyMs = options?.latencyMs ?? 0;
-        this._status = options?.status;
-        this._correlationId = options?.correlationId;
-        this._notifications = options?.notifications;
-        this._missingIds = options?.missingIds;
-        this._failureOverrides.clear();
-        this._responseOverrides.clear();
-    }
-    // ─────────────────────────────────────────────
-    // MutationExecutor interface implementation
-    // ─────────────────────────────────────────────
-    async commit(operations, options) {
-        this._capture('commit', { operations, options });
-        await this._maybeDelay();
-        this._maybeThrow('commit');
-        const syncId = this._syncId++;
-        if (this._status === 'queued') {
-            if (!this._correlationId) {
-                throw new Error('Mock queued commits require a correlationId');
-            }
-            return {
-                lastSyncId: 0,
-                status: 'queued',
-                correlationId: this._correlationId,
-                ...(this._notifications ? { notifications: this._notifications } : {}),
-                ...(this._missingIds ? { missingIds: this._missingIds } : {}),
-            };
-        }
-        const evidence = {
-            ...(this._notifications ? { notifications: this._notifications } : {}),
-            ...(this._missingIds ? { missingIds: this._missingIds } : {}),
-        };
-        if (this._status === 'confirmed') {
-            return {
-                lastSyncId: syncId,
-                status: 'confirmed',
-                ...(this._correlationId ? { correlationId: this._correlationId } : {}),
-                ...evidence,
-            };
-        }
-        return { lastSyncId: syncId, ...evidence };
-    }
-    async executeCreate(modelName, id, input, clientMutationId) {
-        this._capture('executeCreate', { modelName, modelId: id, input, clientMutationId });
-        await this._maybeDelay();
-        this._maybeThrow('executeCreate');
-    }
-    async executeUpdate(modelName, modelId, data, clientMutationId) {
-        this._capture('executeUpdate', { modelName, modelId, input: data, clientMutationId });
-        await this._maybeDelay();
-        this._maybeThrow('executeUpdate');
-        return { lastSyncId: this._syncId++ };
-    }
-    async executeDelete(modelName, modelId, clientMutationId) {
-        this._capture('executeDelete', { modelName, modelId, clientMutationId });
-        await this._maybeDelay();
-        this._maybeThrow('executeDelete');
-    }
-    async executeArchive(modelName, modelId, clientMutationId) {
-        this._capture('executeArchive', { modelName, modelId, clientMutationId });
-        await this._maybeDelay();
-        this._maybeThrow('executeArchive');
-    }
-    async executeUnarchive(modelName, modelId, clientMutationId) {
-        this._capture('executeUnarchive', { modelName, modelId, clientMutationId });
-        await this._maybeDelay();
-        this._maybeThrow('executeUnarchive');
-    }
-    // ─────────────────────────────────────────────
-    // Internal helpers
-    // ─────────────────────────────────────────────
-    _capture(method, data) {
-        this.calls.push({
-            method,
-            timestamp: Date.now(),
-            ...data,
-        });
-    }
-    async _maybeDelay() {
-        if (this._latencyMs > 0) {
-            await new Promise((r) => setTimeout(r, this._latencyMs));
-        }
-    }
-    _maybeThrow(method) {
-        // Check specific method override first
-        const methodError = this._failureOverrides.get(method);
-        if (methodError)
-            throw methodError;
-        // Check global override
-        const globalError = this._failureOverrides.get('*');
-        if (globalError)
-            throw globalError;
-        // Check global flag
-        if (!this._shouldSucceed) {
-            throw new AbloError(`Mock mutation failed: ${method}`, {
-                code: 'mock_mutation_failed',
-            });
-        }
-    }
-}

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

@@ -1,20 +0,0 @@
-/**
- * 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;
-    /** Marks the connection online and sets `navigator.onLine` to true. */
-    goOnline(): void;
-    /** Marks the connection offline and sets `navigator.onLine` to false. */
-    goOffline(): void;
-    /** Flips between online and offline, returning the new online state. */
-    toggle(): boolean;
-    /** Returns the monitor to its online starting state. */
-    reset(): void;
-}

package/dist/testing/mocks/MockNetworkMonitor.js

@@ -1,46 +0,0 @@
-/**
- * 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;
-    constructor(initialOnline = true) {
-        this._online = initialOnline;
-    }
-    isOnline() {
-        return this._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
-        Object.defineProperty(navigator, 'onLine', {
-            writable: true,
-            value: true,
-        });
-    }
-    /** Marks the connection offline and sets `navigator.onLine` to false. */
-    goOffline() {
-        this._online = false;
-        Object.defineProperty(navigator, 'onLine', {
-            writable: true,
-            value: false,
-        });
-    }
-    /** Flips between online and offline, returning the new online state. */
-    toggle() {
-        if (this._online) {
-            this.goOffline();
-        }
-        else {
-            this.goOnline();
-        }
-        return this._online;
-    }
-    /** Returns the monitor to its online starting state. */
-    reset() {
-        this.goOnline();
-    }
-}

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

@@ -1,51 +0,0 @@
-/**
- * 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 {
-    /** Replaces the default no-op logger. */
-    logger?: SyncLogger;
-    /** Replaces the default no-op observability provider. */
-    observability?: SyncObservabilityProvider;
-    /** Replaces the detector that decides whether an error means the session has expired. */
-    sessionErrorDetector?: SessionErrorDetector;
-    /** Options forwarded to the {@link MockMutationExecutor} that the context creates. */
-    mutationExecutorOptions?: ConstructorParameters<typeof MockMutationExecutor>[0];
-    /** A partial {@link SyncEngineConfig} merged over the defaults. */
-    config?: Partial<SyncEngineConfig>;
-    /** Starts the network monitor offline. Defaults to online. */
-    startOffline?: boolean;
-}
-export interface TestContextResult {
-    /** The assembled context that {@link createTestContext} installed globally. */
-    context: SyncEngineContext;
-    /** Handles to the underlying mocks, so tests can drive them and assert on them. */
-    mocks: {
-        mutationExecutor: MockMutationExecutor;
-        networkMonitor: MockNetworkMonitor;
-    };
-    /** Tears the test down by resetting the engine and the mocks. Call it when the test finishes. */
-    cleanup: () => void;
-}
-/**
- * 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.
- *
- * @example
- * ```ts
- * const { context, mocks, cleanup } = createTestContext();
- * // ... run tests using mocks.mutationExecutor, mocks.networkMonitor
- * cleanup();
- * ```
- */
-export declare function createTestContext(options?: TestContextOptions): TestContextResult;

package/dist/testing/mocks/MockSyncContext.js

@@ -1,71 +0,0 @@
-/**
- * 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';
-import { ModelRegistry, setActiveRegistry, hasActiveRegistry, clearActiveRegistry, } from '../../ModelRegistry.js';
-import { registerTestModels } from '../fixtures/models.js';
-import { MockMutationExecutor } from './MockMutationExecutor.js';
-import { MockNetworkMonitor } from './MockNetworkMonitor.js';
-/**
- * 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.
- *
- * @example
- * ```ts
- * const { context, mocks, cleanup } = createTestContext();
- * // ... run tests using mocks.mutationExecutor, mocks.networkMonitor
- * cleanup();
- * ```
- */
-export function createTestContext(options = {}) {
-    const mutationExecutor = new MockMutationExecutor(options.mutationExecutorOptions);
-    const networkMonitor = new MockNetworkMonitor(!options.startOffline);
-    const config = {
-        ...emptyConfig,
-        ...options.config,
-        // Merge maps/sets properly if overrides provided
-        modelCreatePriority: options.config?.modelCreatePriority ?? emptyConfig.modelCreatePriority,
-    };
-    const context = {
-        logger: options.logger ?? noopLogger,
-        observability: options.observability ?? noopObservability,
-        analytics: noopAnalytics,
-        sessionErrorDetector: options.sessionErrorDetector ?? defaultSessionErrorDetector,
-        onlineStatus: networkMonitor,
-        mutationExecutor,
-        config,
-    };
-    initSyncEngine(context);
-    // Bootstrap a default ModelRegistry with test models if none is active.
-    // Tests that manage their own registry call setActiveRegistry before this.
-    const bootstrappedRegistry = !hasActiveRegistry();
-    if (bootstrappedRegistry) {
-        const defaultRegistry = new ModelRegistry();
-        setActiveRegistry(defaultRegistry);
-        registerTestModels(defaultRegistry);
-    }
-    return {
-        context,
-        mocks: {
-            mutationExecutor,
-            networkMonitor,
-        },
-        cleanup: () => {
-            resetSyncEngine();
-            // 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,88 +0,0 @@
-/**
- * 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 '../../InstanceCache.js';
-import type { SyncStoreContract } from '../../react/context.js';
-interface QueryOptions<T extends Model> {
-    predicate?: (model: T) => boolean;
-    scope?: ModelScope;
-    orderBy?: keyof T;
-    order?: 'asc' | 'desc';
-    limit?: number;
-    offset?: number;
-}
-interface QueryResult<T extends Model> {
-    data: T[];
-}
-type ModelCtor<T extends Model> = abstract new (...args: never[]) => T;
-/**
- * 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;
-    calls: {
-        retrieve: {
-            modelClass: ModelCtor<Model>;
-            id: string;
-        }[];
-        query: {
-            modelClass: ModelCtor<Model>;
-            options?: QueryOptions<Model>;
-        }[];
-        save: Model[];
-        delete: Model[];
-        archive: Model[];
-        unarchive: Model[];
-    };
-    /**
-     * Seed the store with models of a specific class.
-     *
-     * @example
-     * mockStore.setModels(Task, [task1, task2]);
-     */
-    setModels<T extends Model>(modelClass: ModelCtor<T>, models: T[]): void;
-    /**
-     * Adds or replaces a single model, keyed by its id.
-     */
-    addModel<T extends Model>(modelClass: ModelCtor<T>, model: T): void;
-    /**
-     * Remove a model by ID.
-     */
-    removeModel<T extends Model>(modelClass: ModelCtor<T>, id: string): void;
-    /**
-     * Clear all seeded data and call history.
-     */
-    reset(): void;
-    retrieve<T extends Model>(modelClass: ModelCtor<T>, id: string): T | undefined;
-    queryByClass<T extends Model>(modelClass: ModelCtor<T>, options?: QueryOptions<T>): QueryResult<T>;
-    save(model: Model): Promise<void>;
-    delete(model: Model): Promise<void>;
-    archive(model: Model): Promise<void>;
-    unarchive(model: Model): Promise<void>;
-    isReady: boolean;
-    isSyncing: boolean;
-    isOffline: boolean;
-    isReconnecting: boolean;
-    isError: boolean;
-    hasUnsyncedChanges: boolean;
-    syncStatus: {
-        state: "idle";
-        progress: number;
-        pendingChanges: number;
-        isSessionError: boolean;
-    };
-    /** A minimal object pool backing the useEntity and useEntities hooks in tests. */
-    pool: SyncStoreContract['pool'];
-}
-/**
- * Create a new MockSyncStore.
- * Shorthand for `new MockSyncStore()`.
- */
-export declare function createMockSyncStore(): MockSyncStore;
-export {};