@abloatai/ablo 0.3.0

package/dist/core/DatabaseManager.js

@@ -0,0 +1,361 @@
+/**
+ * Ablo Sync Engine - Database Manager
+ *
+ * Manages the two-tier database architecture:
+ * 1. ablo_databases - Metadata about workspace databases
+ * 2. ablo_(hash) - Workspace-specific data storage
+ *
+ * Follows Ablo's architecture for database management.
+ */
+import { getContext } from '../context.js';
+import { openIDBWithTimeout } from './openIDBWithTimeout.js';
+import { AbloConnectionError } from '../errors.js';
+import { getActiveRegistry, hasActiveRegistry } from '../ModelRegistry.js';
+/**
+ * DatabaseManager - Manages Ablo's two-tier database architecture
+ *
+ * Key responsibilities:
+ * - Manages ablo_databases (database registry)
+ * - Creates workspace-specific databases (ablo_hash)
+ * - Handles database migration and versioning
+ * - Provides database info and metadata management
+ */
+export class DatabaseManager {
+    metaDb = null;
+    metaDbName = 'ablo_databases';
+    constructor() {
+        // Singleton-like behavior
+    }
+    /**
+     * Initialize the meta database (ablo_databases)
+     */
+    async initializeMetaDatabase() {
+        this.metaDb = await openIDBWithTimeout(this.metaDbName, 1, {
+            onUpgrade: (request) => {
+                const db = request.result;
+                if (!db.objectStoreNames.contains('databases')) {
+                    const store = db.createObjectStore('databases', { keyPath: 'name' });
+                    store.createIndex('userId', 'userId');
+                    store.createIndex('workspaceId', 'workspaceId');
+                    store.createIndex('schemaHash', 'schemaHash');
+                    store.createIndex('updatedAt', 'updatedAt');
+                }
+            },
+        });
+    }
+    /**
+     * Calculate database info for a user/workspace combination
+     */
+    async calculateDatabaseInfo(userId, workspaceId, userVersion = 1) {
+        // Get schema hash from the active ModelRegistry
+        const schemaHash = hasActiveRegistry()
+            ? getActiveRegistry().getSchemaHash()
+            : 'no-registry-hash';
+        // Generate database name from userId, workspaceId, and versions
+        const dbName = this.generateDatabaseName(userId, workspaceId, userVersion);
+        // Check if we need to increment schema version
+        const existingInfo = await this.getDatabaseInfo(dbName);
+        let schemaVersion = 1;
+        if (existingInfo && existingInfo.schemaHash !== schemaHash) {
+            schemaVersion = (existingInfo.schemaVersion || 1) + 1;
+        }
+        else if (existingInfo) {
+            schemaVersion = existingInfo.schemaVersion || 1;
+        }
+        // DEBUG: Log all existing databases for this user to detect duplicates
+        const allUserDatabases = await this.getDatabasesForUser(userId);
+        const allIndexedDBs = (await indexedDB.databases?.()) || [];
+        const abloDatabases = allIndexedDBs.filter((db) => db.name?.startsWith('ablo_'));
+        getContext().observability.breadcrumb('Database info calculated', 'sync.database', 'info', {
+            dbName,
+            schemaVersion,
+            existingDbCount: allUserDatabases.length,
+            abloDbCount: abloDatabases.length,
+        });
+        return {
+            name: dbName,
+            userId,
+            workspaceId,
+            schemaHash,
+            schemaVersion,
+            userVersion,
+            createdAt: existingInfo?.createdAt || new Date(),
+            updatedAt: new Date(),
+        };
+    }
+    /**
+     * Generate deterministic database name
+     */
+    generateDatabaseName(userId, workspaceId, userVersion = 1) {
+        // Combine userId, workspaceId, and userVersion for unique database
+        const combined = `${userId}:${workspaceId}:${userVersion}`;
+        // Generate hash similar to Linear's approach
+        let hash = 0;
+        for (let i = 0; i < combined.length; i++) {
+            hash = (hash << 5) - hash + combined.charCodeAt(i);
+            hash = hash & hash; // Convert to 32bit integer
+        }
+        // Convert to hex and create Ablo-style name
+        const hexHash = Math.abs(hash).toString(16).padStart(8, '0');
+        return `ablo_${hexHash}`;
+    }
+    /**
+     * Register database info in ablo_databases
+     */
+    async registerDatabase(info) {
+        if (!this.metaDb) {
+            throw new AbloConnectionError('Meta database not initialized', {
+                code: 'meta_db_not_initialized',
+            });
+        }
+        return new Promise((resolve, reject) => {
+            const tx = this.metaDb.transaction(['databases'], 'readwrite');
+            const store = tx.objectStore('databases');
+            const request = store.put(info);
+            tx.oncomplete = () => {
+                resolve();
+            };
+            tx.onerror = () => reject(tx.error);
+            request.onerror = () => reject(request.error);
+        });
+    }
+    /**
+     * Get database info by name
+     */
+    async getDatabaseInfo(name) {
+        if (!this.metaDb)
+            return null;
+        return new Promise((resolve, reject) => {
+            const tx = this.metaDb.transaction(['databases'], 'readonly');
+            const store = tx.objectStore('databases');
+            const request = store.get(name);
+            request.onsuccess = () => resolve(request.result || null);
+            request.onerror = () => reject(request.error);
+        });
+    }
+    /**
+     * Get all databases for a user
+     */
+    async getDatabasesForUser(userId) {
+        if (!this.metaDb)
+            return [];
+        return new Promise((resolve, reject) => {
+            const tx = this.metaDb.transaction(['databases'], 'readonly');
+            const store = tx.objectStore('databases');
+            const index = store.index('userId');
+            const request = index.getAll(userId);
+            request.onsuccess = () => resolve(request.result || []);
+            request.onerror = () => reject(request.error);
+        });
+    }
+    /**
+     * Open workspace-specific database
+     */
+    async openWorkspaceDatabase(dbInfo, createStoresFn) {
+        try {
+            return await openIDBWithTimeout(dbInfo.name, dbInfo.schemaVersion, {
+                onUpgrade: (request, event) => {
+                    const db = request.result;
+                    const tx = event.target.transaction;
+                    // Per jakearchibald/idb's "Transaction Lifetime Management":
+                    // only IDB-request awaits keep an upgrade transaction alive; any
+                    // non-IDB await (fetch, timer, etc.) commits it prematurely and
+                    // later ops throw `TransactionInactiveError`. StoreManager.createStores
+                    // (src/core/StoreManager.ts:93) is only synchronous createObjectStore
+                    // / createIndex calls wrapped in an `async` keyword, so firing it
+                    // without awaiting is safe and matches the VCS-slot semantics.
+                    if (createStoresFn && tx) {
+                        try {
+                            void createStoresFn(db, tx).catch((err) => {
+                                getContext().observability.captureBootstrapFailure(err, {
+                                    type: 'store-creation',
+                                });
+                            });
+                        }
+                        catch (err) {
+                            getContext().observability.captureBootstrapFailure(err, {
+                                type: 'store-creation',
+                            });
+                        }
+                    }
+                },
+            });
+        }
+        catch (error) {
+            getContext().observability.captureBootstrapFailure(error, {
+                type: 'database-open',
+            });
+            throw error;
+        }
+    }
+    /**
+     * Read workspace metadata from __meta table
+     */
+    async getWorkspaceMetadata(db) {
+        return new Promise((resolve, reject) => {
+            const tx = db.transaction(['__meta'], 'readonly');
+            const store = tx.objectStore('__meta');
+            const request = store.get('metadata');
+            request.onsuccess = () => {
+                const data = request.result;
+                if (!data) {
+                    resolve(null);
+                    return;
+                }
+                const meta = {
+                    lastSyncId: data.lastSyncId || 0,
+                    firstSyncId: data.firstSyncId || 0,
+                    backendDatabaseVersion: data.backendDatabaseVersion || 1,
+                    subscribedSyncGroups: data.subscribedSyncGroups || [],
+                    updatedAt: data.updatedAt ? new Date(data.updatedAt) : new Date(),
+                    schemaHash: data.schemaHash,
+                    syncGroups: data.syncGroups,
+                    versions: data.versions || undefined,
+                };
+                resolve(meta);
+            };
+            request.onerror = () => reject(request.error);
+        });
+    }
+    /**
+     * Write workspace metadata to __meta table
+     */
+    async setWorkspaceMetadata(db, metadata) {
+        return new Promise((resolve, reject) => {
+            const tx = db.transaction(['__meta'], 'readwrite');
+            const store = tx.objectStore('__meta');
+            const request = store.put(metadata, 'metadata');
+            tx.oncomplete = () => resolve();
+            tx.onerror = () => reject(tx.error);
+            request.onerror = () => reject(request.error);
+        });
+    }
+    /**
+     * Check if a model is persisted (all instances loaded)
+     */
+    async isModelPersisted(db, modelName) {
+        return new Promise((resolve, reject) => {
+            const tx = db.transaction(['__meta'], 'readonly');
+            const store = tx.objectStore('__meta');
+            const request = store.get(modelName);
+            request.onsuccess = () => {
+                const data = request.result;
+                resolve(data?.persisted === true);
+            };
+            request.onerror = () => reject(request.error);
+        });
+    }
+    /**
+     * Mark a model as persisted
+     */
+    async setModelPersisted(db, modelName, persisted) {
+        return new Promise((resolve, reject) => {
+            const tx = db.transaction(['__meta'], 'readwrite');
+            const store = tx.objectStore('__meta');
+            const persistenceData = {
+                persisted,
+                modelName,
+                timestamp: Date.now(),
+                updatedAt: new Date().toISOString(),
+            };
+            const request = store.put(persistenceData, modelName);
+            tx.oncomplete = () => resolve();
+            tx.onerror = () => reject(tx.error);
+            request.onerror = () => reject(request.error);
+        });
+    }
+    /**
+     * Get all model persistence states
+     */
+    async getAllModelPersistenceStates(db) {
+        return new Promise((resolve, reject) => {
+            const tx = db.transaction(['__meta'], 'readonly');
+            const store = tx.objectStore('__meta');
+            const request = store.getAll();
+            request.onsuccess = () => {
+                const states = {};
+                for (const item of request.result) {
+                    // Skip metadata entry
+                    if (item.key === 'metadata')
+                        continue;
+                    if (item.modelName) {
+                        states[item.modelName] = item.persisted === true;
+                    }
+                }
+                resolve(states);
+            };
+            request.onerror = () => reject(request.error);
+        });
+    }
+    /**
+     * Delete a workspace database
+     */
+    async deleteWorkspaceDatabase(dbInfo) {
+        return new Promise((resolve, reject) => {
+            const deleteRequest = indexedDB.deleteDatabase(dbInfo.name);
+            deleteRequest.onsuccess = async () => {
+                // Remove from registry
+                if (this.metaDb) {
+                    const tx = this.metaDb.transaction(['databases'], 'readwrite');
+                    const store = tx.objectStore('databases');
+                    store.delete(dbInfo.name);
+                }
+                resolve();
+            };
+            deleteRequest.onerror = () => {
+                getContext().observability.breadcrumb(`Failed to delete workspace database: ${dbInfo.name}`, 'sync.database', 'error');
+                reject(deleteRequest.error);
+            };
+            deleteRequest.onblocked = () => {
+                getContext().observability.breadcrumb(`Database deletion blocked: ${dbInfo.name}`, 'sync.database', 'warning');
+                // Could implement retry logic or user notification
+            };
+        });
+    }
+    /**
+     * Get comprehensive database statistics
+     */
+    async getDatabaseStatistics() {
+        if (!this.metaDb) {
+            return {
+                metaDatabaseSize: 0,
+                totalWorkspaceDatabases: 0,
+                databasesByUser: {},
+                schemaVersions: {},
+            };
+        }
+        return new Promise((resolve, reject) => {
+            const tx = this.metaDb.transaction(['databases'], 'readonly');
+            const store = tx.objectStore('databases');
+            const request = store.getAll();
+            request.onsuccess = () => {
+                const databases = request.result;
+                const databasesByUser = {};
+                const schemaVersions = {};
+                for (const db of databases) {
+                    // Count by user
+                    databasesByUser[db.userId] = (databasesByUser[db.userId] || 0) + 1;
+                    // Count schema versions
+                    const versionKey = `v${db.schemaVersion}`;
+                    schemaVersions[versionKey] = (schemaVersions[versionKey] || 0) + 1;
+                }
+                resolve({
+                    metaDatabaseSize: databases.length,
+                    totalWorkspaceDatabases: databases.length,
+                    databasesByUser,
+                    schemaVersions,
+                });
+            };
+            request.onerror = () => reject(request.error);
+        });
+    }
+    /**
+     * Close all database connections
+     */
+    async close() {
+        if (this.metaDb) {
+            this.metaDb.close();
+            this.metaDb = null;
+        }
+    }
+}

package/dist/core/QueryProcessor.d.ts

@@ -0,0 +1,77 @@
+/**
+ * QueryProcessor - Centralized query processing for the sync engine
+ *
+ * Responsibilities:
+ * - Complex filtering, sorting, and pagination logic
+ * - Query optimization and caching strategies
+ * - Predicate evaluation and result processing
+ *
+ * This extracts query processing logic from SyncedStore for proper separation of concerns
+ */
+import type { Model } from '../Model.js';
+import type { ModelScope } from '../ObjectPool.js';
+export interface QueryOptions<T extends Model> {
+    predicate?: (model: T) => boolean;
+    /** Stable key to distinguish different predicates for the same model type.
+     *  Required when multiple predicate queries exist for the same model — without this,
+     *  they share a cache key and thrash each other's cached result every render. */
+    predicateKey?: string;
+    scope?: ModelScope;
+    orderBy?: keyof T;
+    order?: 'asc' | 'desc';
+    limit?: number;
+    offset?: number;
+    skipCache?: boolean;
+}
+export interface QueryResult<T extends Model> {
+    data: T[];
+    total: number;
+    hasMore: boolean;
+    fromCache?: boolean;
+}
+export declare class QueryProcessor {
+    private cache;
+    private enableCache;
+    private predicateResultCache;
+    constructor(config?: {
+        enableCache?: boolean;
+    });
+    /**
+     * Process query with filtering, sorting, and pagination
+     */
+    processQuery<T extends Model>(models: T[], modelName: string, options?: QueryOptions<T>): QueryResult<T>;
+    /**
+     * Sort models by field
+     */
+    private sortModels;
+    /**
+     * Find first matching model with predicate
+     */
+    findFirst<T extends Model>(models: Generator<T, void, unknown>, predicate: (model: T) => boolean): T | undefined;
+    /**
+     * Count models with optional predicate
+     */
+    countModels<T extends Model>(models: Generator<T, void, unknown>, predicate?: (model: T) => boolean): number;
+    /**
+     * 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.
+     */
+    private generateCacheKey;
+    /**
+     * Invalidate cache by pattern
+     */
+    invalidateCache(pattern?: string): void;
+    /**
+     * Clear all cache
+     */
+    clearCache(): void;
+    /**
+     * Get cache stats for debugging
+     */
+    getCacheStats(): {
+        size: number;
+        enabled: boolean;
+    };
+}

package/dist/core/QueryProcessor.js

@@ -0,0 +1,262 @@
+/**
+ * QueryProcessor - Centralized query processing for the sync engine
+ *
+ * Responsibilities:
+ * - Complex filtering, sorting, and pagination logic
+ * - Query optimization and caching strategies
+ * - Predicate evaluation and result processing
+ *
+ * This extracts query processing logic from SyncedStore for proper separation of concerns
+ */
+/**
+ * Optimized in-memory cache implementation
+ *
+ * 2025 Best Practice: O(1) invalidation by model type instead of O(n) regex matching
+ * - Maintains a reverse index from model type to cache keys
+ * - Invalidation by model type is O(k) where k = keys for that model type
+ * - No regex compilation or full cache iteration needed
+ */
+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 simpleMatch = pattern.match(/^\.\*(\w+)\.\*$/);
+        if (simpleMatch) {
+            const modelType = simpleMatch[1];
+            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) {
+        const parts = key.split(':');
+        return parts.length >= 2 ? parts[1] : null;
+    }
+}
+export class QueryProcessor {
+    cache;
+    enableCache;
+    // Stable-reference cache for predicate queries.
+    // String-based cache keys can't represent closures, so we use a separate
+    // identity-based cache that compares result model IDs. This follows the same
+    // principle as MobX's comparer.structural — return the previous reference
+    // when the structural content hasn't changed.
+    // Key: deterministic portion of query (modelName + serializable options)
+    // Value: previous result + its ID fingerprint
+    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: use structural identity comparison
+        // Return the previous array reference if model IDs haven't changed.
+        // This is the query-layer equivalent of MobX's comparer.structural —
+        // observers won't re-render when the result is structurally identical.
+        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 string-based cache as before
+        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 simpleMatch = pattern.match(/^\.\*(\w+)\.\*$/);
+            if (simpleMatch) {
+                const modelType = simpleMatch[1];
+                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,
+        };
+    }
+}