@abloatai/humans 0.37.0

package/src/local/stores/ObjectStore.ts

@@ -0,0 +1,449 @@
+/**
+ * The IndexedDB-backed object store: durable, per-model record storage for
+ * the browser. See {@link ObjectStore}.
+ */
+
+import type { ModelMetadata } from '@abloatai/transaction/types';
+import type { ObjectStoreContract } from './ObjectStoreContract.js';
+
+/**
+ * IDB transaction options type (TypeScript's lib.dom.d.ts may be outdated)
+ * durability: 'relaxed' provides ~16x write performance improvement
+ * by not requiring fsync on each transaction commit.
+ * Safe for optimistic sync engines that can recover from server state.
+ */
+interface IDBTransactionOptionsWithDurability {
+  durability?: 'default' | 'relaxed' | 'strict';
+}
+
+/**
+ * An IndexedDB-backed store holding the records of a single model.
+ *
+ * It implements {@link ObjectStoreContract}, the shared surface that
+ * {@link InMemoryObjectStore} also satisfies, so callers can hold either
+ * implementation behind one type. Because both are checked against the same
+ * interface, any drift between them surfaces as a typecheck error rather
+ * than a runtime surprise.
+ *
+ * The store talks to the native IndexedDB API directly and uses relaxed
+ * transaction durability on writes.
+ */
+export class ObjectStore implements ObjectStoreContract {
+  private isClosing = false;
+
+  constructor(
+    protected db: IDBDatabase,
+    protected modelName: string,
+    protected storeName: string,
+    protected metadata: ModelMetadata,
+    private readonly writeDurability: NonNullable<IDBTransactionOptionsWithDurability['durability']> = 'relaxed',
+  ) {}
+
+  /** Insert without replacing an existing key (used by the commit outbox). */
+  async add(data: Record<string, unknown>): Promise<void> {
+    if (!this.checkDatabaseAvailable()) {
+      return Promise.reject(new Error('IndexedDB not available (closing or invalid)'));
+    }
+
+    return new Promise((resolve, reject) => {
+      try {
+        const tx = this.db.transaction([this.storeName], 'readwrite', {
+          durability: this.writeDurability,
+        });
+        const store = tx.objectStore(this.storeName);
+        const request = store.add(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) {
+        reject(error instanceof Error ? error : new Error(String(error)));
+      }
+    });
+  }
+
+  /**
+   * Mark this store as closing to prevent new operations
+   */
+  markAsClosing(): void {
+    this.isClosing = true;
+  }
+
+  /**
+   * Check if database is available for operations
+   */
+  private checkDatabaseAvailable(): boolean {
+    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
+      void 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: Record<string, unknown>): Promise<void> {
+    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: this.writeDurability,
+        });
+        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: string): Promise<Record<string, unknown> | undefined> {
+    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: string[]): Promise<Map<string, Record<string, unknown>>> {
+    const results = new Map<string, Record<string, unknown>>();
+    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(): Promise<Record<string, unknown>[]> {
+    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: string): Promise<void> {
+    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: this.writeDurability,
+        });
+        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(): Promise<boolean> {
+    try {
+      await this.count();
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Clear all data in store
+   */
+  async clear(): Promise<void> {
+    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: this.writeDurability,
+        });
+        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(): Promise<number> {
+    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: string,
+    value: IDBValidKey,
+  ): Promise<Record<string, unknown>[]> {
+    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: string,
+    keyValue: IDBValidKey,
+  ): Promise<Record<string, unknown>[]> {
+    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: string,
+    value: IDBValidKey,
+  ): Promise<Record<string, unknown> | undefined> {
+    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: string, value: IDBValidKey): Promise<number> {
+    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: string, value: IDBValidKey): Promise<boolean> {
+    const count = await this.countFromIndex(indexName, value);
+    return count > 0;
+  }
+
+  /**
+   * Get store statistics
+   */
+  async getStats(): Promise<{
+    count: number;
+    ready: boolean;
+    loadStrategy: string;
+    indexes: string[];
+  }> {
+    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(): Promise<void> {
+    // Default: no maintenance needed
+    // Subclasses can override for compaction, cleanup, etc.
+  }
+}

package/src/local/stores/ObjectStoreContract.ts

@@ -0,0 +1,48 @@
+/**
+ * The shared interface for record-shaped object stores. Two implementations
+ * satisfy it:
+ *
+ *   - {@link ObjectStore} — backed by IndexedDB, for durable persistence in
+ *     the browser.
+ *   - {@link InMemoryObjectStore} — backed by a Map, for tests and
+ *     environments without IndexedDB.
+ *
+ * Both expose the same asynchronous surface — `put`, `get`, `getAll`,
+ * `delete`, `getAllFromIndex`, `clear`, and `markAsClosing` — so callers
+ * work against this interface and never branch on which concrete store they
+ * hold. Because both implementations are checked against one interface, any
+ * drift between them surfaces as a typecheck error at the store rather than
+ * a silent failure in a caller.
+ */
+export interface ObjectStoreContract {
+  /** Insert a record only when its key is absent. */
+  add(data: Record<string, unknown>): Promise<void>;
+
+  /** 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;
+}