@abloatai/ablo 0.35.0 → 0.37.0

package/dist/core/QueryProcessor.js

@@ -1,255 +0,0 @@
-/**
- * Runs in-memory queries over a set of models — filtering by predicate,
- * sorting, paginating, and caching the results. A caller hands
- * {@link QueryProcessor} the candidate models and the query options, and it
- * returns a {@link QueryResult}. It keeps two caches: a string-keyed cache for
- * plain queries, and a structural-identity cache for predicate queries, whose
- * closures cannot be turned into a stable string key.
- */
-/**
- * The default in-memory cache. It keeps a reverse index from model type to the
- * cache keys for that type, so invalidating one model type costs work
- * proportional to that type's keys rather than a scan of the whole cache. A
- * regex fallback still covers the rare pattern that is not a plain model-type
- * match.
- */
-class BasicQueryCache {
-    cache = new Map();
-    // Reverse index: model type -> set of cache keys for that type
-    modelTypeIndex = new Map();
-    get(key) {
-        return this.cache.get(key);
-    }
-    get size() {
-        return this.cache.size;
-    }
-    set(key, data) {
-        this.cache.set(key, data);
-        // Extract model type from cache key (format: "operation:ModelType:options")
-        const modelType = this.extractModelType(key);
-        if (modelType) {
-            if (!this.modelTypeIndex.has(modelType)) {
-                this.modelTypeIndex.set(modelType, new Set());
-            }
-            this.modelTypeIndex.get(modelType).add(key);
-        }
-    }
-    /**
-     * Optimized invalidation - O(k) where k = keys for model type
-     * Supports both exact model type names and regex patterns (fallback)
-     */
-    invalidate(pattern) {
-        if (!pattern) {
-            this.cache.clear();
-            this.modelTypeIndex.clear();
-            return;
-        }
-        // Fast path: Check if pattern is a simple model type match like ".*ModelType.*"
-        const modelType = /^\.\*(\w+)\.\*$/.exec(pattern)?.[1];
-        if (modelType !== undefined) {
-            const keysToDelete = this.modelTypeIndex.get(modelType);
-            if (keysToDelete) {
-                for (const key of keysToDelete) {
-                    this.cache.delete(key);
-                }
-                this.modelTypeIndex.delete(modelType);
-            }
-            return;
-        }
-        // Slow path fallback: regex matching for complex patterns
-        // This should rarely be needed with proper model type patterns
-        const regex = new RegExp(pattern);
-        const keysToDelete = [];
-        for (const key of this.cache.keys()) {
-            if (regex.test(key)) {
-                keysToDelete.push(key);
-            }
-        }
-        // Batch delete to avoid iterator invalidation
-        for (const key of keysToDelete) {
-            this.cache.delete(key);
-            // Clean up index
-            const modelType = this.extractModelType(key);
-            if (modelType) {
-                this.modelTypeIndex.get(modelType)?.delete(key);
-            }
-        }
-    }
-    clear() {
-        this.cache.clear();
-        this.modelTypeIndex.clear();
-    }
-    /**
-     * Extract model type from cache key
-     * Cache key format: "operation:ModelType:options"
-     */
-    extractModelType(key) {
-        // A missing second segment reads as undefined, so `?? null` yields null.
-        return key.split(':')[1] ?? null;
-    }
-}
-export class QueryProcessor {
-    cache;
-    enableCache;
-    // Stable-reference cache for predicate queries. A string cache key cannot
-    // capture a closure, so predicate queries use a separate identity-based
-    // cache keyed on the deterministic part of the query (model name plus
-    // serializable options). Each entry stores the previous result and a
-    // fingerprint of its model ids; when the ids are unchanged, the processor
-    // returns the previous array reference so observers do not re-render.
-    predicateResultCache = new Map();
-    constructor(config = {}) {
-        this.enableCache = config.enableCache ?? true;
-        this.cache = new BasicQueryCache();
-    }
-    /**
-     * Process query with filtering, sorting, and pagination
-     */
-    processQuery(models, modelName, options = {}) {
-        // Generate cache key
-        const cacheKey = this.generateCacheKey('query', modelName, options);
-        // Check string-based cache (non-predicate queries only)
-        if (!options.predicate && !options.skipCache && this.enableCache) {
-            const cached = this.cache.get(cacheKey);
-            if (cached) {
-                return { ...cached, fromCache: true };
-            }
-        }
-        // Apply predicate filter
-        let filtered = options.predicate ? models.filter(options.predicate) : models;
-        // Sort models
-        if (options.orderBy) {
-            filtered = this.sortModels(filtered, options.orderBy, options.order);
-        }
-        const total = filtered.length;
-        // Apply pagination
-        const offset = options.offset || 0;
-        const limit = options.limit || filtered.length;
-        const data = filtered.slice(offset, offset + limit);
-        const result = {
-            data,
-            total,
-            hasMore: offset + limit < total,
-            fromCache: false,
-        };
-        // For predicate queries: compare by structural identity. Return the
-        // previous array reference when the model ids are unchanged, so observers
-        // don't re-render on a structurally identical result.
-        if (options.predicate && this.enableCache) {
-            const ids = data.map((m) => m.id).join(',');
-            const cached = this.predicateResultCache.get(cacheKey);
-            if (cached && cached.ids === ids) {
-                // Structural match — return previous reference for stability
-                return { ...cached.result, fromCache: true };
-            }
-            // New result — store for future comparison
-            this.predicateResultCache.set(cacheKey, { ids, result });
-        }
-        // For non-predicate queries: use the string-based cache.
-        if (!options.predicate && this.enableCache) {
-            this.cache.set(cacheKey, result);
-        }
-        return result;
-    }
-    /**
-     * Sort models by field
-     */
-    sortModels(models, field, order = 'asc') {
-        return [...models].sort((a, b) => {
-            const aVal = a[field];
-            const bVal = b[field];
-            if (aVal === bVal)
-                return 0;
-            if (aVal === null || aVal === undefined)
-                return 1;
-            if (bVal === null || bVal === undefined)
-                return -1;
-            const comparison = aVal < bVal ? -1 : 1;
-            return order === 'asc' ? comparison : -comparison;
-        });
-    }
-    /**
-     * Find first matching model with predicate
-     */
-    findFirst(models, predicate) {
-        for (const model of models) {
-            if (predicate(model)) {
-                return model;
-            }
-        }
-        return undefined;
-    }
-    /**
-     * Count models with optional predicate
-     */
-    countModels(models, predicate) {
-        let count = 0;
-        for (const model of models) {
-            if (!predicate || predicate(model)) {
-                count++;
-            }
-        }
-        return count;
-    }
-    /**
-     * Generate a deterministic cache key from query parameters.
-     * Functions (predicates) are excluded from the key — predicate queries use
-     * the structural identity cache (predicateResultCache) instead of the
-     * string-based cache.
-     */
-    generateCacheKey(operation, modelName, options) {
-        const serializableOptions = {};
-        let hasPredicate = false;
-        for (const [key, value] of Object.entries(options)) {
-            if (typeof value === 'function') {
-                hasPredicate = true;
-                // Mark that this query has a predicate, but use a stable marker
-                // (not Math.random). The actual caching for predicate queries
-                // is handled by predicateResultCache using ID comparison.
-                serializableOptions[key] = `__predicate__`;
-            }
-            else {
-                serializableOptions[key] = value;
-            }
-        }
-        const sortedOptions = JSON.stringify(serializableOptions, Object.keys(serializableOptions).sort());
-        const key = `${operation}:${modelName}:${sortedOptions}`;
-        return hasPredicate ? `pred:${key}` : key;
-    }
-    /**
-     * Invalidate cache by pattern
-     */
-    invalidateCache(pattern) {
-        this.cache.invalidate(pattern);
-        // Also invalidate predicate result cache for this model type
-        if (pattern) {
-            const modelType = /^\.\*(\w+)\.\*$/.exec(pattern)?.[1];
-            if (modelType !== undefined) {
-                for (const key of this.predicateResultCache.keys()) {
-                    if (key.includes(modelType)) {
-                        this.predicateResultCache.delete(key);
-                    }
-                }
-            }
-        }
-        else {
-            this.predicateResultCache.clear();
-        }
-    }
-    /**
-     * Clear all cache
-     */
-    clearCache() {
-        this.cache.clear();
-        this.predicateResultCache.clear();
-    }
-    /**
-     * Get cache stats for debugging
-     */
-    getCacheStats() {
-        return {
-            size: this.cache.size,
-            enabled: this.enableCache,
-        };
-    }
-}

package/dist/core/QueryView.d.ts

@@ -1,79 +0,0 @@
-/**
- * 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 { type Model } from '../Model.js';
-import { ModelScope } from '../transaction/types/index.js';
-import type { ViewRegistry } from './ViewRegistry.js';
-import type { IncrementalView } from './queryUtils.js';
-/**
- * The slice of the object pool that a {@link QueryView} reads. It is a minimal
- * structural interface rather than the concrete pool class, which lets a query
- * view avoid importing the pool and so breaks what would otherwise be an import
- * cycle — the pool imports {@link QueryView} to construct one. The concrete
- * pool satisfies this interface structurally.
- */
-export interface QueryViewPool {
-    hasForeignKeyIndex(typename: string, fieldName: string): boolean;
-    getByForeignKey(modelName: string, fieldName: string, fieldValue: string): Model[];
-    getByTypeName(modelName: string, scope?: ModelScope): Model[];
-}
-export interface QueryViewOptions<T> {
-    where?: Partial<T>;
-    filter?: (entity: T) => boolean;
-    orderBy?: keyof T & string;
-    order?: 'asc' | 'desc';
-    limit?: number;
-    offset?: number;
-    /** Lifecycle filter — `live` (the default), `archived`, or `all`. It is
-     *  named `state` rather than `scope` so it does not collide with the
-     *  sync-group `scope`. */
-    state?: 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: QueryViewPool, 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

@@ -1,218 +0,0 @@
-/**
- * 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 '../transaction/types/index.js';
-import { compareValues, binaryInsertionIndex, findIndexById, } from './queryUtils.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.state ?? ModelScope.live;
-        // Check for FK-index optimization: single-field where with an indexed FK
-        this.fkField = null;
-        this.fkValue = null;
-        const soleWhereEntry = this.whereEntries && this.whereEntries.length === 1 ? this.whereEntries[0] : undefined;
-        if (soleWhereEntry && typeof soleWhereEntry[1] === 'string') {
-            const [field, value] = soleWhereEntry;
-            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 InstanceCache, 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

@@ -1,112 +0,0 @@
-/**
- * Manages the {@link ObjectStore} instances the sync engine keeps in the
- * browser — one per registered model — alongside the single
- * {@link SyncActionStore} for pending changes. It creates each store from the
- * model's metadata, tracks readiness, and provisions the underlying IndexedDB
- * object stores. A model's load strategy — instant or lazy — decides how and
- * when its data is loaded.
- */
-import { ModelRegistry } from '../ModelRegistry.js';
-import { ObjectStore } from '../stores/ObjectStore.js';
-import { SyncActionStore } from '../stores/SyncActionStore.js';
-import { LoadStrategy } from '../transaction/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;
-    /** Strict-durability wrapper for the client write journal and commit outbox. */
-    private transactionStore;
-    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): 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;
-    }>;
-    /**
-     * Reports whether any data store holds at least one record. This is a
-     * cache-validity check: if the stores are empty, the sync cursor
-     * (`lastSyncId`) is meaningless no matter what the metadata says, because the
-     * cursor and the data must travel together — no data means no cursor, which
-     * forces a full bootstrap. To stay cheap it samples up to three stores rather
-     * than scanning them all, and returns true as soon as one has records.
-     */
-    hasAnyData(): Promise<boolean>;
-    /**
-     * Get stores by load strategy
-     */
-    getStoresByStrategy(strategy: LoadStrategy): ObjectStore[];
-    /**
-     * 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;
-        readiness: {
-            ready: number;
-            notReady: number;
-        };
-        totalRecords: number;
-        storeDetails: {
-            modelName: string;
-            storeName: string;
-            strategy: LoadStrategy;
-            ready: boolean;
-            count: number;
-        }[];
-    }>;
-}