@abloatai/ablo 0.3.0

package/dist/stores/ObjectStore.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Linear Sync Engine - Object Store Base Class
+ *
+ * Abstract base class for all store implementations.
+ * Provides the interface for storing and retrieving models from IndexedDB.
+ * Uses native IndexedDB for maximum performance (no wrapper overhead).
+ */
+import { ModelMetadata } from '../types/index.js';
+import type { ObjectStoreContract } from './ObjectStoreContract.js';
+/**
+ * ObjectStore - IDB-backed model storage.
+ *
+ * Implements {@link ObjectStoreContract}, the shared surface that
+ * `InMemoryObjectStore` also satisfies. Centralizing the contract
+ * means callers can hold either implementation behind one type and
+ * a future drift between the two trips a typecheck error here.
+ *
+ * Uses native IndexedDB API for Linear-level performance.
+ */
+export declare class ObjectStore implements ObjectStoreContract {
+    protected db: IDBDatabase;
+    protected modelName: string;
+    protected storeName: string;
+    protected metadata: ModelMetadata;
+    private isClosing;
+    constructor(db: IDBDatabase, modelName: string, storeName: string, metadata: ModelMetadata);
+    /**
+     * Mark this store as closing to prevent new operations
+     */
+    markAsClosing(): void;
+    /**
+     * Check if database is available for operations
+     */
+    private checkDatabaseAvailable;
+    /**
+     * Store a model in IndexedDB.
+     * Matches the {@link InMemoryObjectStore.put} signature so both
+     * stores satisfy the same caller-visible contract.
+     */
+    put(data: Record<string, unknown>): Promise<void>;
+    /**
+     * Get a model by ID
+     */
+    get(id: string): Promise<Record<string, unknown> | undefined>;
+    /**
+     * Batch get multiple models by IDs in a single IDB transaction.
+     * Much faster than N sequential get() calls (1 transaction vs N).
+     */
+    getMany(ids: string[]): Promise<Map<string, Record<string, unknown>>>;
+    /**
+     * Get all models
+     */
+    getAll(): Promise<Record<string, unknown>[]>;
+    /**
+     * Delete a model by ID
+     */
+    delete(id: string): Promise<void>;
+    /**
+     * Check if store is ready (has data)
+     */
+    checkIsReady(): Promise<boolean>;
+    /**
+     * Clear all data in store
+     */
+    clear(): Promise<void>;
+    /**
+     * Get count of models in store
+     */
+    count(): Promise<number>;
+    /**
+     * Get models by indexed property
+     */
+    getAllFromIndex(indexName: string, value: IDBValidKey): Promise<Record<string, unknown>[]>;
+    /**
+     * Get models by indexed key (supports compound keys)
+     */
+    getAllForIndexedKey(indexedKey: string, keyValue: IDBValidKey): Promise<Record<string, unknown>[]>;
+    /**
+     * Get first model matching index
+     */
+    getFromIndex(indexName: string, value: IDBValidKey): Promise<Record<string, unknown> | undefined>;
+    /**
+     * Get count from index
+     */
+    countFromIndex(indexName: string, value: IDBValidKey): Promise<number>;
+    /**
+     * Check if any models exist for index value
+     */
+    hasModelsForIndex(indexName: string, value: IDBValidKey): Promise<boolean>;
+    /**
+     * Get store statistics
+     */
+    getStats(): Promise<{
+        count: number;
+        ready: boolean;
+        loadStrategy: string;
+        indexes: string[];
+    }>;
+    /**
+     * Perform maintenance (override in subclasses for specific needs)
+     */
+    performMaintenance(): Promise<void>;
+}

package/dist/stores/ObjectStore.js

@@ -0,0 +1,371 @@
+/**
+ * Linear Sync Engine - Object Store Base Class
+ *
+ * Abstract base class for all store implementations.
+ * Provides the interface for storing and retrieving models from IndexedDB.
+ * Uses native IndexedDB for maximum performance (no wrapper overhead).
+ */
+/**
+ * ObjectStore - IDB-backed model storage.
+ *
+ * Implements {@link ObjectStoreContract}, the shared surface that
+ * `InMemoryObjectStore` also satisfies. Centralizing the contract
+ * means callers can hold either implementation behind one type and
+ * a future drift between the two trips a typecheck error here.
+ *
+ * Uses native IndexedDB API for Linear-level performance.
+ */
+export class ObjectStore {
+    db;
+    modelName;
+    storeName;
+    metadata;
+    isClosing = false;
+    constructor(db, modelName, storeName, metadata) {
+        this.db = db;
+        this.modelName = modelName;
+        this.storeName = storeName;
+        this.metadata = metadata;
+    }
+    /**
+     * Mark this store as closing to prevent new operations
+     */
+    markAsClosing() {
+        this.isClosing = true;
+    }
+    /**
+     * Check if database is available for operations
+     */
+    checkDatabaseAvailable() {
+        if (this.isClosing) {
+            return false;
+        }
+        // Check if the database connection is still open
+        // In IndexedDB, there's no direct way to check if a connection is open,
+        // but we can check if the database object is still valid
+        try {
+            // Accessing objectStoreNames will throw if the database is closed
+            const _ = this.db.objectStoreNames;
+            return true;
+        }
+        catch (error) {
+            return false;
+        }
+    }
+    /**
+     * Store a model in IndexedDB.
+     * Matches the {@link InMemoryObjectStore.put} signature so both
+     * stores satisfy the same caller-visible contract.
+     */
+    async put(data) {
+        if (!this.checkDatabaseAvailable()) {
+            // Surface an explicit error so upstream does not assume success
+            return Promise.reject(new Error('IndexedDB not available (closing or invalid)'));
+        }
+        return new Promise((resolve, reject) => {
+            try {
+                // Use relaxed durability for ~16x write performance (safe with optimistic sync)
+                const tx = this.db.transaction([this.storeName], 'readwrite', {
+                    durability: 'relaxed',
+                });
+                const store = tx.objectStore(this.storeName);
+                const request = store.put(data);
+                tx.oncomplete = () => resolve();
+                tx.onerror = () => reject(tx.error || new Error('IndexedDB transaction error'));
+                request.onerror = () => reject(request.error || new Error('IndexedDB request error'));
+            }
+            catch (error) {
+                // Propagate failure so callers do not continue with inconsistent state
+                reject(error instanceof Error ? error : new Error(String(error)));
+            }
+        });
+    }
+    /**
+     * Get a model by ID
+     */
+    async get(id) {
+        if (!this.checkDatabaseAvailable()) {
+            return Promise.resolve(undefined);
+        }
+        return new Promise((resolve, reject) => {
+            try {
+                const tx = this.db.transaction([this.storeName], 'readonly');
+                const store = tx.objectStore(this.storeName);
+                const request = store.get(id);
+                request.onsuccess = () => resolve(request.result);
+                request.onerror = () => reject(request.error);
+            }
+            catch (error) {
+                resolve(undefined);
+            }
+        });
+    }
+    /**
+     * Batch get multiple models by IDs in a single IDB transaction.
+     * Much faster than N sequential get() calls (1 transaction vs N).
+     */
+    async getMany(ids) {
+        const results = new Map();
+        if (ids.length === 0 || !this.checkDatabaseAvailable()) {
+            return results;
+        }
+        return new Promise((resolve, reject) => {
+            try {
+                const tx = this.db.transaction([this.storeName], 'readonly');
+                const store = tx.objectStore(this.storeName);
+                let completed = 0;
+                for (const id of ids) {
+                    const request = store.get(id);
+                    request.onsuccess = () => {
+                        if (request.result) {
+                            results.set(id, request.result);
+                        }
+                        completed++;
+                        if (completed === ids.length) {
+                            resolve(results);
+                        }
+                    };
+                    request.onerror = () => {
+                        completed++;
+                        if (completed === ids.length) {
+                            resolve(results);
+                        }
+                    };
+                }
+                tx.onerror = () => reject(tx.error);
+            }
+            catch (error) {
+                resolve(results);
+            }
+        });
+    }
+    /**
+     * Get all models
+     */
+    async getAll() {
+        if (!this.checkDatabaseAvailable()) {
+            return Promise.resolve([]);
+        }
+        return new Promise((resolve, reject) => {
+            try {
+                const tx = this.db.transaction([this.storeName], 'readonly');
+                const store = tx.objectStore(this.storeName);
+                const request = store.getAll();
+                request.onsuccess = () => resolve(request.result || []);
+                request.onerror = () => reject(request.error);
+            }
+            catch (error) {
+                resolve([]);
+            }
+        });
+    }
+    /**
+     * Delete a model by ID
+     */
+    async delete(id) {
+        if (!this.checkDatabaseAvailable()) {
+            return Promise.reject(new Error('IndexedDB not available (closing or invalid)'));
+        }
+        return new Promise((resolve, reject) => {
+            try {
+                // Use relaxed durability for ~16x write performance (safe with optimistic sync)
+                const tx = this.db.transaction([this.storeName], 'readwrite', {
+                    durability: 'relaxed',
+                });
+                const store = tx.objectStore(this.storeName);
+                const request = store.delete(id);
+                tx.oncomplete = () => resolve();
+                tx.onerror = () => reject(tx.error || new Error('IndexedDB transaction error'));
+                request.onerror = () => reject(request.error || new Error('IndexedDB request error'));
+            }
+            catch (error) {
+                reject(error instanceof Error ? error : new Error(String(error)));
+            }
+        });
+    }
+    /**
+     * Check if store is ready (has data)
+     */
+    async checkIsReady() {
+        try {
+            await this.count();
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Clear all data in store
+     */
+    async clear() {
+        if (!this.checkDatabaseAvailable()) {
+            return Promise.reject(new Error('IndexedDB not available (closing or invalid)'));
+        }
+        return new Promise((resolve, reject) => {
+            try {
+                // Use relaxed durability for ~16x write performance (safe with optimistic sync)
+                const tx = this.db.transaction([this.storeName], 'readwrite', {
+                    durability: 'relaxed',
+                });
+                const store = tx.objectStore(this.storeName);
+                const request = store.clear();
+                tx.oncomplete = () => resolve();
+                tx.onerror = () => reject(tx.error || new Error('IndexedDB transaction error'));
+                request.onerror = () => reject(request.error || new Error('IndexedDB request error'));
+            }
+            catch (error) {
+                reject(error instanceof Error ? error : new Error(String(error)));
+            }
+        });
+    }
+    /**
+     * Get count of models in store
+     */
+    async count() {
+        if (!this.checkDatabaseAvailable()) {
+            return Promise.resolve(0);
+        }
+        return new Promise((resolve, reject) => {
+            try {
+                const tx = this.db.transaction([this.storeName], 'readonly');
+                const store = tx.objectStore(this.storeName);
+                const request = store.count();
+                request.onsuccess = () => resolve(request.result);
+                request.onerror = () => reject(request.error);
+            }
+            catch (error) {
+                resolve(0);
+            }
+        });
+    }
+    /**
+     * Get models by indexed property
+     */
+    async getAllFromIndex(indexName, value) {
+        if (!this.checkDatabaseAvailable()) {
+            return Promise.resolve([]);
+        }
+        return new Promise((resolve, reject) => {
+            try {
+                const tx = this.db.transaction([this.storeName], 'readonly');
+                const store = tx.objectStore(this.storeName);
+                const index = store.index(indexName);
+                const request = index.getAll(value);
+                request.onsuccess = () => resolve(request.result);
+                request.onerror = () => reject(request.error);
+            }
+            catch (error) {
+                resolve([]);
+            }
+        });
+    }
+    /**
+     * Get models by indexed key (supports compound keys)
+     */
+    async getAllForIndexedKey(indexedKey, keyValue) {
+        if (!this.checkDatabaseAvailable()) {
+            return Promise.resolve([]);
+        }
+        // For simple index
+        if (!indexedKey.includes('.')) {
+            return this.getAllFromIndex(indexedKey, keyValue);
+        }
+        // For compound index (e.g., "teamId.status")
+        return new Promise((resolve, reject) => {
+            try {
+                const tx = this.db.transaction([this.storeName], 'readonly');
+                const store = tx.objectStore(this.storeName);
+                const request = store.getAll();
+                request.onsuccess = () => {
+                    const allRecords = request.result;
+                    // Filter in memory for compound keys
+                    const keyParts = indexedKey.split('.');
+                    const filtered = allRecords.filter((record) => {
+                        let value = record;
+                        for (const part of keyParts) {
+                            value = value?.[part];
+                            if (value === undefined)
+                                return false;
+                        }
+                        return value === keyValue;
+                    });
+                    resolve(filtered);
+                };
+                request.onerror = () => reject(request.error);
+            }
+            catch (error) {
+                resolve([]);
+            }
+        });
+    }
+    /**
+     * Get first model matching index
+     */
+    async getFromIndex(indexName, value) {
+        if (!this.checkDatabaseAvailable()) {
+            return Promise.resolve(undefined);
+        }
+        return new Promise((resolve, reject) => {
+            try {
+                const tx = this.db.transaction([this.storeName], 'readonly');
+                const store = tx.objectStore(this.storeName);
+                const index = store.index(indexName);
+                const request = index.get(value);
+                request.onsuccess = () => resolve(request.result);
+                request.onerror = () => reject(request.error);
+            }
+            catch (error) {
+                resolve(undefined);
+            }
+        });
+    }
+    /**
+     * Get count from index
+     */
+    async countFromIndex(indexName, value) {
+        if (!this.checkDatabaseAvailable()) {
+            return Promise.resolve(0);
+        }
+        return new Promise((resolve, reject) => {
+            try {
+                const tx = this.db.transaction([this.storeName], 'readonly');
+                const store = tx.objectStore(this.storeName);
+                const index = store.index(indexName);
+                const request = index.count(value);
+                request.onsuccess = () => resolve(request.result);
+                request.onerror = () => reject(request.error);
+            }
+            catch (error) {
+                resolve(0);
+            }
+        });
+    }
+    /**
+     * Check if any models exist for index value
+     */
+    async hasModelsForIndex(indexName, value) {
+        const count = await this.countFromIndex(indexName, value);
+        return count > 0;
+    }
+    /**
+     * Get store statistics
+     */
+    async getStats() {
+        const tx = this.db.transaction([this.storeName], 'readonly');
+        const store = tx.objectStore(this.storeName);
+        return {
+            count: await this.count(),
+            ready: await this.checkIsReady(),
+            loadStrategy: this.metadata.loadStrategy,
+            indexes: store.indexNames ? Array.from(store.indexNames) : [],
+        };
+    }
+    /**
+     * Perform maintenance (override in subclasses for specific needs)
+     */
+    async performMaintenance() {
+        // Default: no maintenance needed
+        // Subclasses can override for compaction, cleanup, etc.
+    }
+}

package/dist/stores/ObjectStoreContract.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Shared contract for record-shaped object stores.
+ *
+ * The SDK has two implementations:
+ *   - {@link ObjectStore} — IndexedDB-backed (browser persistence)
+ *   - {@link InMemoryObjectStore} — Map-backed (tests, SSR fallback)
+ *
+ * Both expose the same async surface: `put` / `get` / `getAll` /
+ * `delete` / `getAllFromIndex` / `clear` / `markAsClosing`.
+ * Callers depend on this interface so they don't have to
+ * branch on which concrete class they got from `Database.getStore` —
+ * the bootstrap, hydration, transaction-persistence, and reconciler
+ * paths all consume the contract.
+ *
+ * Centralizing the types here means a future drift between the two
+ * stores trips a typecheck error at the implementor, not silently in
+ * a caller. This replaced ad-hoc `as unknown as ReturnType<...>`
+ * casts in `Database.ts` that bridged the two classes.
+ */
+export interface ObjectStoreContract {
+    /** Insert or update a record. The record must carry an `id` field. */
+    put(data: Record<string, unknown>): Promise<void>;
+    /** Look up a record by id. */
+    get(id: string): Promise<Record<string, unknown> | undefined>;
+    /** Read every record currently in the store. */
+    getAll(): Promise<Record<string, unknown>[]>;
+    /** Delete a record by id. No-op if absent. */
+    delete(id: string): Promise<void>;
+    /** Read every record matching an indexed value. */
+    getAllFromIndex(indexName: string, value: IDBValidKey): Promise<Record<string, unknown>[]>;
+    /** Remove every record. */
+    clear(): Promise<void>;
+    /**
+     * Mark the store as closing so subsequent `put`/`get` calls
+     * short-circuit to a rejection rather than racing the underlying
+     * IDB connection close. No-op for in-memory stores.
+     */
+    markAsClosing(): void;
+}

package/dist/stores/ObjectStoreContract.js

@@ -0,0 +1 @@
+export {};

package/dist/stores/SyncActionStore.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Linear Sync Engine - Sync Action Store
+ *
+ * Stores and manages sync actions received from the server.
+ * Critical for delta sync and maintaining sync state consistency.
+ */
+import { SyncAction } from '../types/index.js';
+/**
+ * SyncActionStore - Manages sync actions (deltas)
+ *
+ * Features:
+ * - Stores sync actions by ID for replay
+ * - Tracks applied vs pending actions
+ * - Enables rewind/replay for conflict resolution
+ * - Maintains sync watermark
+ */
+export declare class SyncActionStore {
+    private db;
+    private storeName;
+    private lastAppliedSyncId;
+    private pendingActions;
+    constructor(db: IDBDatabase);
+    /**
+     * Initialize store (create if needed)
+     */
+    initialize(): Promise<void>;
+    /**
+     * Store a sync action
+     */
+    storeSyncAction(action: SyncAction): Promise<void>;
+    /**
+     * Store multiple sync actions
+     */
+    storeSyncActions(actions: SyncAction[]): Promise<void>;
+    /**
+     * Get sync action by ID
+     */
+    getSyncAction(id: number): Promise<SyncAction | undefined>;
+    /**
+     * Get sync actions in range
+     */
+    getSyncActionsInRange(startId: number, endId: number): Promise<SyncAction[]>;
+    /**
+     * Get pending sync actions (not yet applied)
+     */
+    getPendingSyncActions(): Promise<SyncAction[]>;
+    /**
+     * Mark sync action as applied
+     */
+    markAsApplied(syncId: number): Promise<void>;
+    /**
+     * Mark multiple actions as applied
+     */
+    markManyAsApplied(syncIds: number[]): Promise<void>;
+    /**
+     * Get last applied sync ID
+     */
+    getLastAppliedSyncId(): number;
+    /**
+     * Check if we have a gap in sync IDs
+     */
+    hasGap(fromId: number, toId: number): Promise<boolean>;
+    /**
+     * Get missing sync IDs in range
+     */
+    getMissingSyncIds(fromId: number, toId: number): Promise<number[]>;
+    /**
+     * Clean up old sync actions
+     */
+    cleanup(keepDays?: number): Promise<number>;
+    /**
+     * Clear all sync actions
+     */
+    clear(): Promise<void>;
+    /**
+     * Get statistics
+     */
+    getStats(): Promise<{
+        total: number;
+        applied: number;
+        pending: number;
+        lastAppliedId: number;
+        oldestAction: Date | null;
+        newestAction: Date | null;
+    }>;
+    /**
+     * Update last sync ID in metadata
+     */
+    private updateLastSyncId;
+    /**
+     * Get metadata. Shape mirrors what's written by the database manager
+     * — currently only `lastSyncId` is consumed here (in `initialize`),
+     * so the return type is narrowed to that read surface. Returns
+     * `undefined` when the row hasn't been written yet (fresh DB).
+     */
+    private getMetadata;
+    /**
+     * Rewind to a specific sync ID (for conflict resolution)
+     */
+    rewindTo(syncId: number): Promise<SyncAction[]>;
+}