@abloatai/humans 0.37.0

package/dist/local/stores/SyncActionStore.js

@@ -0,0 +1,506 @@
+/**
+ * A local, IndexedDB-backed store for the sync actions (change deltas) the
+ * server sends. See {@link SyncActionStore}.
+ */
+// Uses native IndexedDB for maximum performance
+import { globalRuntime } from '../context.js';
+import { syncActionSchema } from './syncAction.js';
+/**
+ * The validation boundary for rows read back from the store. A row may have
+ * been written by an earlier session, so this build cannot assume its shape.
+ * Parsing in strip mode also drops the storage bookkeeping fields
+ * (`storedAt`, `applied`, `appliedAt`) that are not part of a
+ * {@link SyncAction}. A row that fails to parse is dropped and logged rather
+ * than replayed as a malformed delta.
+ */
+/** Parse one stored row into a SyncAction, or `null` (dropped + logged). */
+function toSyncAction(row, runtime) {
+    const parsed = syncActionSchema.safeParse(row);
+    if (!parsed.success) {
+        runtime.logger.debug('[SyncActionStore] Dropping malformed stored sync action', {
+            issues: parsed.error.issues.map((i) => i.path.join('.')).join(', '),
+        });
+        return null;
+    }
+    return parsed.data;
+}
+/**
+ * Stores the sync actions (the change deltas) the server sends, keyed by
+ * their sync id, and tracks which ones have been applied. It keeps a
+ * watermark of the last applied id, holds not-yet-applied actions as
+ * pending, and can rewind a range of actions back to pending so they can be
+ * replayed while resolving a conflict.
+ */
+export class SyncActionStore {
+    runtime;
+    db;
+    storeName = 'sync_action_table';
+    lastAppliedSyncId = 0;
+    pendingActions = new Map();
+    constructor(db, runtime = globalRuntime) {
+        this.runtime = runtime;
+        this.db = db;
+    }
+    /**
+     * Initialize store (create if needed)
+     */
+    async initialize() {
+        // Store is created during database migration
+        // Load last applied sync ID from metadata
+        const metadata = await this.getMetadata();
+        if (metadata) {
+            this.lastAppliedSyncId = metadata.lastSyncId || 0;
+        }
+    }
+    /**
+     * Store a sync action
+     */
+    async storeSyncAction(action) {
+        return new Promise((resolve, reject) => {
+            const tx = this.db.transaction([this.storeName], 'readwrite');
+            const store = tx.objectStore(this.storeName);
+            const request = store.put({
+                ...action,
+                storedAt: Date.now(),
+                applied: false,
+            });
+            tx.oncomplete = () => {
+                // Add to pending if not yet applied
+                if (action.id > this.lastAppliedSyncId) {
+                    this.pendingActions.set(action.id, action);
+                }
+                resolve();
+            };
+            tx.onerror = () => { reject(tx.error); };
+            request.onerror = () => { reject(request.error); };
+        });
+    }
+    /**
+     * Store multiple sync actions
+     */
+    async storeSyncActions(actions) {
+        if (actions.length === 0)
+            return;
+        return new Promise((resolve, reject) => {
+            const tx = this.db.transaction([this.storeName], 'readwrite');
+            const store = tx.objectStore(this.storeName);
+            let completed = 0;
+            const total = actions.length;
+            for (const action of actions) {
+                const request = store.put({
+                    ...action,
+                    storedAt: Date.now(),
+                    applied: false,
+                });
+                request.onsuccess = () => {
+                    completed++;
+                    if (completed === total) {
+                        // Add to pending
+                        for (const action of actions) {
+                            if (action.id > this.lastAppliedSyncId) {
+                                this.pendingActions.set(action.id, action);
+                            }
+                        }
+                    }
+                };
+                request.onerror = () => { reject(request.error); };
+            }
+            tx.oncomplete = () => { resolve(); };
+            tx.onerror = () => { reject(tx.error); };
+        });
+    }
+    /**
+     * Get sync action by ID
+     */
+    async getSyncAction(id) {
+        return new Promise((resolve, reject) => {
+            const tx = this.db.transaction([this.storeName], 'readonly');
+            const store = tx.objectStore(this.storeName);
+            const request = store.get(id);
+            request.onsuccess = () => {
+                const data = request.result;
+                if (!data) {
+                    resolve(undefined);
+                    return;
+                }
+                resolve(toSyncAction(data, this.runtime) ?? undefined);
+            };
+            request.onerror = () => { reject(request.error); };
+        });
+    }
+    /**
+     * Get sync actions in range
+     */
+    async getSyncActionsInRange(startId, endId) {
+        return new Promise((resolve, reject) => {
+            const tx = this.db.transaction([this.storeName], 'readonly');
+            const store = tx.objectStore(this.storeName);
+            const index = store.index('syncId');
+            const range = IDBKeyRange.bound(startId, endId);
+            const request = index.getAll(range);
+            request.onsuccess = () => {
+                const allData = request.result;
+                const actions = allData
+                    .map((row) => toSyncAction(row, this.runtime))
+                    .filter((action) => action !== null);
+                resolve(actions);
+            };
+            request.onerror = () => { reject(request.error); };
+        });
+    }
+    /**
+     * Get pending sync actions (not yet applied)
+     */
+    async getPendingSyncActions() {
+        if (this.pendingActions.size === 0) {
+            return [];
+        }
+        // Return sorted by sync ID
+        const sorted = Array.from(this.pendingActions.values()).sort((a, b) => a.id - b.id);
+        return sorted;
+    }
+    /**
+     * Mark sync action as applied
+     */
+    async markAsApplied(syncId) {
+        // Plain (non-async) executor: a sync throw (e.g. transaction() on a
+        // closing DB) must reject this promise, not vanish into an ignored one.
+        return new Promise((resolve, reject) => {
+            const tx = this.db.transaction([this.storeName], 'readwrite');
+            const store = tx.objectStore(this.storeName);
+            const getRequest = store.get(syncId);
+            getRequest.onsuccess = () => {
+                const existing = getRequest.result;
+                if (existing) {
+                    existing.applied = true;
+                    existing.appliedAt = Date.now();
+                    const putRequest = store.put(existing);
+                    putRequest.onerror = () => { reject(putRequest.error); };
+                }
+            };
+            getRequest.onerror = () => { reject(getRequest.error); };
+            tx.oncomplete = async () => {
+                // Update tracking
+                if (syncId > this.lastAppliedSyncId) {
+                    this.lastAppliedSyncId = syncId;
+                }
+                // Remove from pending
+                this.pendingActions.delete(syncId);
+                // Update metadata
+                try {
+                    await this.updateLastSyncId(syncId);
+                    resolve();
+                }
+                catch (error) {
+                    reject(error);
+                }
+            };
+            tx.onerror = () => { reject(tx.error); };
+        });
+    }
+    /**
+     * Mark multiple actions as applied
+     */
+    async markManyAsApplied(syncIds) {
+        if (syncIds.length === 0)
+            return;
+        return new Promise((resolve, reject) => {
+            const tx = this.db.transaction([this.storeName], 'readwrite');
+            const store = tx.objectStore(this.storeName);
+            let processed = 0;
+            const total = syncIds.length;
+            for (const syncId of syncIds) {
+                const getRequest = store.get(syncId);
+                getRequest.onsuccess = () => {
+                    const existing = getRequest.result;
+                    if (existing) {
+                        existing.applied = true;
+                        existing.appliedAt = Date.now();
+                        const putRequest = store.put(existing);
+                        putRequest.onsuccess = () => {
+                            processed++;
+                            // Remove from pending
+                            this.pendingActions.delete(syncId);
+                            if (processed === total) {
+                                // All processed, update last applied ID
+                                const maxId = Math.max(...syncIds);
+                                if (maxId > this.lastAppliedSyncId) {
+                                    this.lastAppliedSyncId = maxId;
+                                }
+                            }
+                        };
+                        putRequest.onerror = () => { reject(putRequest.error); };
+                    }
+                    else {
+                        processed++;
+                        this.pendingActions.delete(syncId);
+                    }
+                };
+                getRequest.onerror = () => { reject(getRequest.error); };
+            }
+            tx.oncomplete = async () => {
+                // Update metadata with the highest sync ID
+                const maxId = Math.max(...syncIds);
+                if (maxId > this.lastAppliedSyncId) {
+                    try {
+                        await this.updateLastSyncId(maxId);
+                        resolve();
+                    }
+                    catch (error) {
+                        reject(error);
+                    }
+                }
+                else {
+                    resolve();
+                }
+            };
+            tx.onerror = () => { reject(tx.error); };
+        });
+    }
+    /**
+     * Get last applied sync ID
+     */
+    getLastAppliedSyncId() {
+        return this.lastAppliedSyncId;
+    }
+    /**
+     * Check if we have a gap in sync IDs
+     */
+    async hasGap(fromId, toId) {
+        return new Promise((resolve, reject) => {
+            const tx = this.db.transaction([this.storeName], 'readonly');
+            const store = tx.objectStore(this.storeName);
+            const index = store.index('syncId');
+            let currentId = fromId;
+            let hasGap = false;
+            const checkNext = () => {
+                if (currentId > toId) {
+                    resolve(hasGap);
+                    return;
+                }
+                const request = index.get(currentId);
+                request.onsuccess = () => {
+                    if (!request.result) {
+                        hasGap = true;
+                        resolve(true);
+                        return;
+                    }
+                    currentId++;
+                    checkNext();
+                };
+                request.onerror = () => { reject(request.error); };
+            };
+            checkNext();
+        });
+    }
+    /**
+     * Get missing sync IDs in range
+     */
+    async getMissingSyncIds(fromId, toId) {
+        return new Promise((resolve, reject) => {
+            const missing = [];
+            const tx = this.db.transaction([this.storeName], 'readonly');
+            const store = tx.objectStore(this.storeName);
+            const index = store.index('syncId');
+            let currentId = fromId;
+            const checkNext = () => {
+                if (currentId > toId) {
+                    resolve(missing);
+                    return;
+                }
+                const request = index.get(currentId);
+                request.onsuccess = () => {
+                    if (!request.result) {
+                        missing.push(currentId);
+                    }
+                    currentId++;
+                    checkNext();
+                };
+                request.onerror = () => { reject(request.error); };
+            };
+            checkNext();
+        });
+    }
+    /**
+     * Clean up old sync actions
+     */
+    async cleanup(keepDays = 7) {
+        return new Promise((resolve, reject) => {
+            const cutoff = Date.now() - keepDays * 24 * 60 * 60 * 1000;
+            const tx = this.db.transaction([this.storeName], 'readwrite');
+            const store = tx.objectStore(this.storeName);
+            const request = store.openCursor();
+            let cleaned = 0;
+            request.onsuccess = (event) => {
+                const cursor = event.target.result;
+                if (cursor) {
+                    if (cursor.value.applied && cursor.value.appliedAt < cutoff) {
+                        const deleteRequest = cursor.delete();
+                        deleteRequest.onsuccess = () => {
+                            cleaned++;
+                            cursor.continue();
+                        };
+                        deleteRequest.onerror = () => { reject(deleteRequest.error); };
+                    }
+                    else {
+                        cursor.continue();
+                    }
+                }
+                else {
+                    // Cursor finished
+                    resolve(cleaned);
+                }
+            };
+            request.onerror = () => { reject(request.error); };
+        });
+    }
+    /**
+     * Clear all sync actions
+     */
+    async clear() {
+        return new Promise((resolve, reject) => {
+            const tx = this.db.transaction([this.storeName], 'readwrite');
+            const store = tx.objectStore(this.storeName);
+            const request = store.clear();
+            tx.oncomplete = () => {
+                this.pendingActions.clear();
+                this.lastAppliedSyncId = 0;
+                resolve();
+            };
+            tx.onerror = () => { reject(tx.error); };
+            request.onerror = () => { reject(request.error); };
+        });
+    }
+    /**
+     * Get statistics
+     */
+    async getStats() {
+        return new Promise((resolve, reject) => {
+            const tx = this.db.transaction([this.storeName], 'readonly');
+            const store = tx.objectStore(this.storeName);
+            const request = store.getAll();
+            request.onsuccess = () => {
+                const allActions = request.result;
+                const applied = allActions.filter((a) => a.applied).length;
+                const pending = allActions.filter((a) => !a.applied).length;
+                const timestamps = allActions
+                    .map((a) => a.storedAt)
+                    .filter(Boolean)
+                    .sort();
+                resolve({
+                    total: allActions.length,
+                    applied,
+                    pending,
+                    lastAppliedId: this.lastAppliedSyncId,
+                    oldestAction: timestamps.length > 0 ? new Date(timestamps[0]) : null,
+                    newestAction: timestamps.length > 0 ? new Date(timestamps[timestamps.length - 1]) : null,
+                });
+            };
+            request.onerror = () => { reject(request.error); };
+        });
+    }
+    /**
+     * Update last sync ID in metadata
+     */
+    async updateLastSyncId(syncId) {
+        return new Promise((resolve, reject) => {
+            const tx = this.db.transaction(['__meta'], 'readwrite');
+            const store = tx.objectStore('__meta');
+            const getRequest = store.get('metadata');
+            getRequest.onsuccess = () => {
+                const metadata = getRequest.result || {};
+                metadata.lastSyncId = syncId;
+                metadata.updatedAt = new Date();
+                const putRequest = store.put(metadata, 'metadata');
+                putRequest.onerror = () => { reject(putRequest.error); };
+            };
+            getRequest.onerror = () => { reject(getRequest.error); };
+            tx.oncomplete = () => { resolve(); };
+            tx.onerror = () => { reject(tx.error); };
+        });
+    }
+    /**
+     * 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).
+     */
+    async getMetadata() {
+        return new Promise((resolve, reject) => {
+            const tx = this.db.transaction(['__meta'], 'readonly');
+            const store = tx.objectStore('__meta');
+            const request = store.get('metadata');
+            request.onsuccess = () => {
+                const raw = request.result;
+                if (raw && typeof raw === 'object' && 'lastSyncId' in raw) {
+                    resolve(raw);
+                }
+                else {
+                    resolve(undefined);
+                }
+            };
+            request.onerror = () => { reject(request.error); };
+        });
+    }
+    /**
+     * Rewind to a specific sync ID (for conflict resolution)
+     */
+    async rewindTo(syncId) {
+        return new Promise((resolve, reject) => {
+            // Get all actions after this sync ID
+            const tx = this.db.transaction([this.storeName], 'readonly');
+            const store = tx.objectStore(this.storeName);
+            const index = store.index('syncId');
+            const range = IDBKeyRange.lowerBound(syncId, false);
+            const request = index.getAll(range);
+            request.onsuccess = async () => {
+                const actionsToRewind = request.result;
+                // Mark them as not applied
+                const writeTx = this.db.transaction([this.storeName], 'readwrite');
+                const writeStore = writeTx.objectStore(this.storeName);
+                let processed = 0;
+                const total = actionsToRewind.length;
+                if (total === 0) {
+                    this.lastAppliedSyncId = syncId - 1;
+                    try {
+                        await this.updateLastSyncId(this.lastAppliedSyncId);
+                        resolve([]);
+                    }
+                    catch (error) {
+                        reject(error);
+                    }
+                    return;
+                }
+                for (const action of actionsToRewind) {
+                    action.applied = false;
+                    delete action.appliedAt;
+                    const putRequest = writeStore.put(action);
+                    putRequest.onsuccess = () => {
+                        processed++;
+                        // Add back to pending
+                        this.pendingActions.set(action.id, action);
+                        if (processed === total) {
+                            // All processed
+                            this.lastAppliedSyncId = syncId - 1;
+                        }
+                    };
+                    putRequest.onerror = () => { reject(putRequest.error); };
+                }
+                writeTx.oncomplete = async () => {
+                    try {
+                        await this.updateLastSyncId(this.lastAppliedSyncId);
+                        const result = actionsToRewind
+                            .map((row) => toSyncAction(row, this.runtime))
+                            .filter((action) => action !== null);
+                        resolve(result);
+                    }
+                    catch (error) {
+                        reject(error);
+                    }
+                };
+                writeTx.onerror = () => { reject(writeTx.error); };
+            };
+            request.onerror = () => { reject(request.error); };
+        });
+    }
+}

package/dist/local/stores/openIDBWithTimeout.d.ts

@@ -0,0 +1,65 @@
+/**
+ * The error raised when opening an IndexedDB database does not complete in a
+ * bounded time. {@link openIDBWithTimeout} throws it in two situations: another
+ * browser tab is holding an older version of the database open and blocking the
+ * upgrade (`reason: 'blocked'`), or the open request produced no result at all
+ * within the timeout (`reason: 'timeout'`).
+ *
+ * The native open request can otherwise hang indefinitely — when a blocking tab
+ * never closes its connection, neither the success nor the error callback fires,
+ * and any code awaiting the open waits forever. Turning that into a thrown error
+ * lets the surrounding application show a recoverable failure instead of an
+ * unbreakable spinner.
+ */
+export declare class IDBOpenTimeoutError extends Error {
+    readonly dbName: string;
+    readonly reason: 'blocked' | 'timeout';
+    /**
+     * A stable identifier for this failure, independent of the message text. When
+     * this error is wrapped into an {@link AbloError} by `toAbloError`, the string
+     * code is preserved, so error handlers can recognize a wedged-storage failure
+     * and offer a recovery path rather than matching on the message.
+     */
+    readonly code = "storage_open_timeout";
+    constructor(dbName: string, reason: 'blocked' | 'timeout', message: string);
+}
+/**
+ * Returns true when a caught value is the storage-open-timeout failure. It
+ * detects the failure by its stable `code`, so it still matches after the error
+ * has been wrapped into an {@link AbloError} or another error type.
+ */
+export declare function isStorageOpenTimeout(err: unknown): boolean;
+export interface OpenIDBOptions {
+    /** Called inside `onupgradeneeded` — mirrors `IDBOpenDBRequest.onupgradeneeded`. */
+    onUpgrade?: (request: IDBOpenDBRequest, event: IDBVersionChangeEvent) => void;
+    /** Max milliseconds to wait for the open request to resolve. Default 10_000. */
+    timeoutMs?: number;
+    /**
+     * Called when another context — a new tab, a page reload after a deploy, or
+     * this package's own {@link deleteIDBWithTimeout} recovery — needs to upgrade
+     * or delete the database and fires a `versionchange` event on this connection.
+     * The connection is always closed first, which is what lets the other
+     * context's upgrade or delete proceed instead of blocking on this one. Provide
+     * this callback to react after that close, for example to prompt the user to
+     * reload. Any error it throws is ignored.
+     */
+    onVersionChange?: () => void;
+}
+export declare function openIDBWithTimeout(name: string, version: number | undefined, options?: OpenIDBOptions): Promise<IDBDatabase>;
+/**
+ * Deletes an IndexedDB database within a bounded time — the delete counterpart
+ * to {@link openIDBWithTimeout}. It is used to recover from a wedged backing
+ * store: when opening a database times out, the caller can delete it and start
+ * fresh, which is safe for any database whose contents can be rebuilt on the
+ * next load.
+ *
+ * Like an open request, a native delete can hang indefinitely — it fires a
+ * blocked event and waits when another connection still holds the database, and
+ * on a truly stuck store it fires no event at all. Both cases become a bounded,
+ * resolved result here, so the caller never spins.
+ *
+ * Resolves to `true` on a clean delete and `false` when the delete was blocked
+ * or timed out. Either way the caller can decide whether to retry the open; a
+ * delete that did nothing leaves the store no worse off.
+ */
+export declare function deleteIDBWithTimeout(name: string, timeoutMs?: number): Promise<boolean>;