@abloatai/ablo 0.3.0

package/dist/core/QueryView.d.ts

@@ -0,0 +1,64 @@
+/**
+ * QueryView<T> — Incrementally maintained materialized view for a single query.
+ *
+ * Instead of scanning the full collection on every render, a QueryView
+ * builds the result set once, then maintains it via handleAdded /
+ * handleUpdated / handleRemoved calls from the ViewRegistry.
+ *
+ * `results` is a stable MobX observable array — components observe it
+ * directly and receive granular updates (splice/push, never replacement).
+ */
+import { type IObservableArray } from 'mobx';
+import { ModelScope } from '../types/index.js';
+import type { ObjectPool } from '../ObjectPool.js';
+import type { ViewRegistry } from './ViewRegistry.js';
+import type { IncrementalView } from './query-utils.js';
+export interface QueryViewOptions<T> {
+    where?: Partial<T>;
+    filter?: (entity: T) => boolean;
+    orderBy?: keyof T & string;
+    order?: 'asc' | 'desc';
+    limit?: number;
+    offset?: number;
+    scope?: ModelScope;
+}
+export declare class QueryView<T extends Record<string, unknown>> implements IncrementalView {
+    /** The full (unlimited) internal result set, kept sorted. */
+    private _internal;
+    /**
+     * Public observable result set — windowed by offset/limit.
+     * Components observe this directly.
+     */
+    readonly results: IObservableArray<T>;
+    private readonly typename;
+    private readonly pool;
+    private readonly registry;
+    private readonly whereEntries;
+    private readonly filterFn;
+    private readonly sortKey;
+    private readonly sortDir;
+    private readonly limitN;
+    private readonly offsetN;
+    private readonly scope;
+    /** FK-index optimization: if the where clause targets a single FK-indexed field. */
+    private readonly fkField;
+    private readonly fkValue;
+    private disposed;
+    constructor(typename: string, pool: ObjectPool, registry: ViewRegistry, options?: QueryViewOptions<T>);
+    private initialScan;
+    handleAdded(model: Record<string, unknown>): void;
+    handleUpdated(model: Record<string, unknown>): void;
+    handleRemoved(modelId: string): void;
+    dispose(): void;
+    /** Check whether an entity passes both `where` and `filter`. */
+    private matchesFilter;
+    /** Insert entity into _internal at the correct sorted position. */
+    private insertSorted;
+    /** Find index of entity by id in _internal. */
+    private findIndexById;
+    /**
+     * Synchronize the public `results` array with the windowed slice of
+     * `_internal`. Mutates in place to keep the reference stable.
+     */
+    private syncWindow;
+}

package/dist/core/QueryView.js

@@ -0,0 +1,219 @@
+/**
+ * QueryView<T> — Incrementally maintained materialized view for a single query.
+ *
+ * Instead of scanning the full collection on every render, a QueryView
+ * builds the result set once, then maintains it via handleAdded /
+ * handleUpdated / handleRemoved calls from the ViewRegistry.
+ *
+ * `results` is a stable MobX observable array — components observe it
+ * directly and receive granular updates (splice/push, never replacement).
+ */
+import { observable, runInAction } from 'mobx';
+import { modelAsRow } from '../Model.js';
+import { ModelScope } from '../types/index.js';
+import { compareValues, binaryInsertionIndex, findIndexById, } from './query-utils.js';
+// ---------------------------------------------------------------------------
+// QueryView
+// ---------------------------------------------------------------------------
+export class QueryView {
+    /** The full (unlimited) internal result set, kept sorted. */
+    _internal;
+    /**
+     * Public observable result set — windowed by offset/limit.
+     * Components observe this directly.
+     */
+    results;
+    typename;
+    pool;
+    registry;
+    whereEntries;
+    filterFn;
+    sortKey;
+    sortDir;
+    limitN;
+    offsetN;
+    scope;
+    /** FK-index optimization: if the where clause targets a single FK-indexed field. */
+    fkField;
+    fkValue;
+    disposed = false;
+    constructor(typename, pool, registry, options = {}) {
+        this.typename = typename;
+        this.pool = pool;
+        this.registry = registry;
+        // Parse options
+        this.whereEntries = options.where
+            ? Object.entries(options.where).filter(([, v]) => v !== undefined)
+            : null;
+        this.filterFn = options.filter ?? null;
+        this.sortKey = options.orderBy ?? null;
+        this.sortDir = options.order === 'desc' ? -1 : 1;
+        this.limitN = options.limit;
+        this.offsetN = options.offset ?? 0;
+        this.scope = options.scope ?? ModelScope.live;
+        // Check for FK-index optimization: single-field where with an indexed FK
+        this.fkField = null;
+        this.fkValue = null;
+        if (this.whereEntries &&
+            this.whereEntries.length === 1 &&
+            typeof this.whereEntries[0][1] === 'string') {
+            const [field, value] = this.whereEntries[0];
+            if (pool.hasForeignKeyIndex(typename, field)) {
+                this.fkField = field;
+                this.fkValue = value;
+            }
+        }
+        // Create observable arrays (shallow — models are already observable)
+        this._internal = observable.array([], { deep: false });
+        this.results = observable.array([], { deep: false });
+        // Perform initial scan
+        this.initialScan();
+        // Register for incremental updates
+        this.registry.register(typename, this);
+    }
+    // -----------------------------------------------------------------------
+    // Initial scan
+    // -----------------------------------------------------------------------
+    initialScan() {
+        let candidates;
+        if (this.fkField && this.fkValue) {
+            // O(1) FK-index lookup
+            candidates = this.pool.getByForeignKey(this.typename, this.fkField, this.fkValue);
+        }
+        else {
+            candidates = this.pool.getByTypeName(this.typename, this.scope);
+        }
+        const matching = [];
+        for (const model of candidates) {
+            const entity = modelAsRow(model);
+            if (this.matchesFilter(entity)) {
+                matching.push(entity);
+            }
+        }
+        // Sort
+        if (this.sortKey) {
+            const key = this.sortKey;
+            const dir = this.sortDir;
+            matching.sort((a, b) => compareValues(a[key], b[key], dir));
+        }
+        runInAction(() => {
+            this._internal.replace(matching);
+            this.syncWindow();
+        });
+    }
+    // -----------------------------------------------------------------------
+    // Incremental update handlers (called by ViewRegistry)
+    // -----------------------------------------------------------------------
+    handleAdded(model) {
+        if (this.disposed)
+            return;
+        const entity = model;
+        const passesFilter = this.matchesFilter(entity);
+        if (!passesFilter)
+            return;
+        runInAction(() => {
+            this.insertSorted(entity);
+            this.syncWindow();
+        });
+    }
+    handleUpdated(model) {
+        if (this.disposed)
+            return;
+        const entity = model;
+        const id = entity['id'];
+        const idx = id !== undefined ? this.findIndexById(id) : -1;
+        const matchesNow = this.matchesFilter(entity);
+        runInAction(() => {
+            if (idx >= 0 && matchesNow) {
+                // Was in view and still matches.
+                // Models are plain objects (not MobX-observable), so we must notify
+                // observers that the data changed. Splice-in-place triggers the
+                // observable array to fire, which causes useQuery consumers to
+                // re-render with fresh property values.
+                this._internal.splice(idx, 1);
+                this.insertSorted(entity);
+            }
+            else if (idx >= 0 && !matchesNow) {
+                // Was in view but no longer matches — remove
+                this._internal.splice(idx, 1);
+            }
+            else if (idx < 0 && matchesNow) {
+                // Wasn't in view but now matches — add
+                this.insertSorted(entity);
+            }
+            this.syncWindow();
+        });
+    }
+    handleRemoved(modelId) {
+        if (this.disposed)
+            return;
+        const idx = this.findIndexById(modelId);
+        if (idx < 0)
+            return;
+        runInAction(() => {
+            this._internal.splice(idx, 1);
+            this.syncWindow();
+        });
+    }
+    // -----------------------------------------------------------------------
+    // Dispose
+    // -----------------------------------------------------------------------
+    dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        this.registry.unregister(this.typename, this);
+    }
+    // -----------------------------------------------------------------------
+    // Private helpers
+    // -----------------------------------------------------------------------
+    /** Check whether an entity passes both `where` and `filter`. */
+    matchesFilter(entity) {
+        // Note: scope is tracked per-entry in the ObjectPool, not on the model.
+        // The initial scan handles scope via getByTypeName(typename, scope).
+        // Incremental notifications from the pool are scope-appropriate since
+        // add/upsert/remove reflect the pool's authoritative scope tracking.
+        // Where clause: declarative field matching
+        if (this.whereEntries) {
+            for (const [key, value] of this.whereEntries) {
+                if (entity[key] !== value)
+                    return false;
+            }
+        }
+        // Arbitrary predicate
+        if (this.filterFn) {
+            if (!this.filterFn(entity))
+                return false;
+        }
+        return true;
+    }
+    /** Insert entity into _internal at the correct sorted position. */
+    insertSorted(entity) {
+        if (this.sortKey) {
+            const idx = binaryInsertionIndex(this._internal, entity, this.sortKey, this.sortDir);
+            this._internal.splice(idx, 0, entity);
+        }
+        else {
+            this._internal.push(entity);
+        }
+    }
+    /** Find index of entity by id in _internal. */
+    findIndexById(id) {
+        return findIndexById(this._internal, id);
+    }
+    /**
+     * Synchronize the public `results` array with the windowed slice of
+     * `_internal`. Mutates in place to keep the reference stable.
+     */
+    syncWindow() {
+        const start = this.offsetN;
+        const end = this.limitN !== undefined ? start + this.limitN : this._internal.length;
+        const windowed = this._internal.slice(start, end);
+        // Minimal diff: only splice if contents differ
+        if (windowed.length === this.results.length &&
+            windowed.every((item, i) => this.results[i] === item)) {
+            return; // no change
+        }
+        this.results.replace(windowed);
+    }
+}

package/dist/core/StoreManager.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Linear Sync Engine - Store Manager
+ *
+ * Manages all ObjectStore instances for registered models.
+ * Creates appropriate store types based on model load strategies.
+ * Follows Linear's architecture with 80+ ObjectStore instances.
+ */
+import { ModelRegistry } from '../ModelRegistry.js';
+import { ObjectStore } from '../stores/ObjectStore.js';
+import { SyncActionStore } from '../stores/SyncActionStore.js';
+import { LoadStrategy } from '../types/index.js';
+/**
+ * StoreManager - Central manager for all ObjectStore instances
+ *
+ * Key responsibilities:
+ * - Creates ObjectStore instances for each registered model
+ * - Manages store lifecycle and readiness
+ * - Provides unified interface for database operations
+ * - Handles store-specific optimizations based on load strategies
+ */
+export declare class StoreManager {
+    private stores;
+    private syncactionStore;
+    private db;
+    private isInitialized;
+    private modelRegistry;
+    constructor(modelRegistry: ModelRegistry);
+    /**
+     * Initialize all stores for registered models
+     */
+    initializeStores(db: IDBDatabase): Promise<void>;
+    /**
+     * Create ObjectStore for a specific model
+     */
+    private createStoreForModel;
+    /**
+     * Create stores (tables) in IndexedDB
+     */
+    createStores(db: IDBDatabase, transaction: IDBTransaction): Promise<void>;
+    /**
+     * Create special tables (sync_action_table, model_table, model_table_partial, __meta, __transactions)
+     */
+    private createSpecialTables;
+    /**
+     * Get ObjectStore for a model
+     */
+    getStore(modelName: string): ObjectStore | undefined;
+    /**
+     * Get SyncactionStore instance
+     */
+    getSyncactionStore(): SyncActionStore | null;
+    /**
+     * Get all stores
+     */
+    getAllStores(): Map<string, ObjectStore>;
+    /**
+     * Check readiness of all stores
+     */
+    checkReadinessOfStores(): Promise<{
+        ready: boolean;
+        readyStores: string[];
+        notReadyStores: string[];
+        totalStores: number;
+    }>;
+    /**
+     * Check if ANY data store has at least one record.
+     *
+     * This is the Zero-style cache-validity check: if the stores are empty,
+     * the sync cursor (lastSyncId) is invalid regardless of what the metadata
+     * says. The cursor and the data must be co-located — no data means no
+     * cursor, which means full bootstrap.
+     *
+     * Samples up to 3 stores to avoid a full scan. If any store has records,
+     * returns true (we have cached data worth preserving).
+     */
+    hasAnyData(): Promise<boolean>;
+    /**
+     * Get store type distribution for debugging
+     */
+    getStoreTypeDistribution(): {
+        full: number;
+        partial: number;
+    };
+    /**
+     * Get stores by load strategy
+     */
+    getStoresByStrategy(strategy: LoadStrategy): ObjectStore[];
+    /**
+     * Get models to load for bootstrapping
+     */
+    getModelsToLoad(): {
+        instant: string[];
+        lazy: string[];
+        partial: string[];
+    };
+    /**
+     * Perform maintenance on all stores
+     */
+    performMaintenance(): Promise<void>;
+    /**
+     * Clear all stores
+     */
+    clearAllStores(): Promise<void>;
+    /**
+     * Mark all stores as closing to prevent new operations
+     * Called before database connection is closed
+     */
+    markAllStoresAsClosing(): void;
+    /**
+     * Get comprehensive statistics
+     */
+    getComprehensiveStats(): Promise<{
+        totalStores: number;
+        storeTypes: {
+            full: number;
+            partial: number;
+        };
+        readiness: {
+            ready: number;
+            notReady: number;
+        };
+        totalRecords: number;
+        storeDetails: Array<{
+            modelName: string;
+            storeName: string;
+            strategy: LoadStrategy;
+            ready: boolean;
+            count: number;
+        }>;
+    }>;
+}