simile-search 0.3.2 → 0.4.1

package/dist/updater.js

@@ -0,0 +1,336 @@
+/**
+ * Background Updater - Non-blocking updates with queue-based processing.
+ *
+ * Allows adding items asynchronously without blocking search operations.
+ * Items are batched and processed in the background for efficiency.
+ */
+/**
+ * Background updater for non-blocking item additions.
+ */
+export class BackgroundUpdater {
+    constructor(simile, config = {}) {
+        this._queue = [];
+        this.processing = false;
+        this.timeoutId = null;
+        this.eventHandlers = new Map();
+        // Stats
+        this.totalProcessed = 0;
+        this.batchCount = 0;
+        this.totalBatchItems = 0;
+        this.simile = simile;
+        this.config = {
+            batchDelay: config.batchDelay ?? 100,
+            maxBatchSize: config.maxBatchSize ?? 50,
+            onProgress: config.onProgress,
+            onError: config.onError,
+        };
+    }
+    /**
+     * Queue items for background embedding.
+     * Items are batched and processed after batchDelay ms.
+     */
+    enqueue(items) {
+        this._queue.push(...items);
+        this.scheduleProcessing();
+    }
+    /**
+     * Queue a single item.
+     */
+    enqueueOne(item) {
+        this._queue.push(item);
+        this.scheduleProcessing();
+    }
+    /**
+     * Force immediate processing of queued items.
+     */
+    async flush() {
+        if (this.timeoutId) {
+            clearTimeout(this.timeoutId);
+            this.timeoutId = null;
+        }
+        await this.processQueue();
+    }
+    /**
+     * Wait for all pending items to be processed.
+     */
+    async waitForCompletion() {
+        while (this._queue.length > 0 || this.processing) {
+            await new Promise(resolve => setTimeout(resolve, 50));
+        }
+    }
+    /**
+     * Get the number of items waiting to be processed.
+     */
+    getPendingCount() {
+        return this._queue.length;
+    }
+    /**
+     * Check if currently processing.
+     */
+    isProcessing() {
+        return this.processing;
+    }
+    /**
+     * Clear all pending items without processing.
+     */
+    clear() {
+        if (this.timeoutId) {
+            clearTimeout(this.timeoutId);
+            this.timeoutId = null;
+        }
+        this._queue = [];
+    }
+    /**
+     * Get updater statistics.
+     */
+    getStats() {
+        return {
+            totalProcessed: this.totalProcessed,
+            pendingCount: this._queue.length,
+            isProcessing: this.processing,
+            avgBatchSize: this.batchCount > 0 ? this.totalBatchItems / this.batchCount : 0,
+            batchCount: this.batchCount,
+        };
+    }
+    /**
+     * Reset statistics.
+     */
+    resetStats() {
+        this.totalProcessed = 0;
+        this.batchCount = 0;
+        this.totalBatchItems = 0;
+    }
+    /**
+     * Register an event handler.
+     */
+    on(event, handler) {
+        if (!this.eventHandlers.has(event)) {
+            this.eventHandlers.set(event, new Set());
+        }
+        this.eventHandlers.get(event).add(handler);
+    }
+    /**
+     * Remove an event handler.
+     */
+    off(event, handler) {
+        this.eventHandlers.get(event)?.delete(handler);
+    }
+    /**
+     * Emit an event to all registered handlers.
+     */
+    emit(event, ...args) {
+        const handlers = this.eventHandlers.get(event);
+        if (handlers) {
+            for (const handler of handlers) {
+                try {
+                    handler(...args);
+                }
+                catch (e) {
+                    console.error(`Error in ${event} handler:`, e);
+                }
+            }
+        }
+    }
+    scheduleProcessing() {
+        if (this.timeoutId || this.processing)
+            return;
+        this.timeoutId = setTimeout(() => {
+            this.timeoutId = null;
+            this.processQueue().catch(console.error);
+        }, this.config.batchDelay);
+    }
+    async processQueue() {
+        if (this.processing || this._queue.length === 0)
+            return;
+        this.processing = true;
+        const total = this._queue.length;
+        try {
+            while (this._queue.length > 0) {
+                // Take batch from queue
+                const batch = this._queue.splice(0, this.config.maxBatchSize);
+                const processed = total - this._queue.length;
+                this.emit('batch', batch, processed, total);
+                try {
+                    await this.simile.add(batch);
+                    this.totalProcessed += batch.length;
+                    this.batchCount++;
+                    this.totalBatchItems += batch.length;
+                    if (this.config.onProgress) {
+                        this.config.onProgress(processed, total);
+                    }
+                    this.emit('progress', processed, total);
+                }
+                catch (error) {
+                    // Handle errors per-item if possible
+                    for (const item of batch) {
+                        if (this.config.onError) {
+                            this.config.onError(error, item);
+                        }
+                        this.emit('error', error, item);
+                    }
+                }
+            }
+            this.emit('complete', this.totalProcessed);
+        }
+        finally {
+            this.processing = false;
+        }
+    }
+}
+/**
+ * Debounced updater - coalesces rapid updates.
+ * Useful when items change frequently (e.g., user typing).
+ */
+export class DebouncedUpdater {
+    constructor(simile, debounceMs = 300, config = {}) {
+        this.pending = new Map();
+        this.timeoutId = null;
+        this.updater = new BackgroundUpdater(simile, config);
+        this.debounceMs = debounceMs;
+    }
+    /**
+     * Queue an item for update. If same ID is queued again before flush,
+     * only the latest version is processed.
+     */
+    update(item) {
+        this.pending.set(item.id, item);
+        this.scheduleFlush();
+    }
+    /**
+     * Force immediate flush of pending items.
+     */
+    async flush() {
+        if (this.timeoutId) {
+            clearTimeout(this.timeoutId);
+            this.timeoutId = null;
+        }
+        await this.doFlush();
+    }
+    scheduleFlush() {
+        if (this.timeoutId) {
+            clearTimeout(this.timeoutId);
+        }
+        this.timeoutId = setTimeout(() => {
+            this.timeoutId = null;
+            this.doFlush().catch(console.error);
+        }, this.debounceMs);
+    }
+    async doFlush() {
+        const items = Array.from(this.pending.values());
+        this.pending.clear();
+        if (items.length > 0) {
+            this.updater.enqueue(items);
+            await this.updater.flush();
+        }
+    }
+    /**
+     * Get pending count (not yet flushed + in queue).
+     */
+    getPendingCount() {
+        return this.pending.size + this.updater.getPendingCount();
+    }
+    /**
+     * Clear all pending updates.
+     */
+    clear() {
+        if (this.timeoutId) {
+            clearTimeout(this.timeoutId);
+            this.timeoutId = null;
+        }
+        this.pending.clear();
+        this.updater.clear();
+    }
+    /**
+     * Get the underlying updater for event handling.
+     */
+    getUpdater() {
+        return this.updater;
+    }
+}
+/**
+ * Priority queue for updates - high priority items processed first.
+ */
+export class PriorityUpdater {
+    constructor(simile, config = {}) {
+        this.highPriority = [];
+        this.normalPriority = [];
+        this.processing = false;
+        this.timeoutId = null;
+        this.simile = simile;
+        this.config = {
+            batchDelay: config.batchDelay ?? 50,
+            maxBatchSize: config.maxBatchSize ?? 50,
+            ...config,
+        };
+    }
+    /**
+     * Queue high priority item (processed first).
+     */
+    queueHigh(items) {
+        this.highPriority.push(...items);
+        this.scheduleProcessing();
+    }
+    /**
+     * Queue normal priority item.
+     */
+    enqueue(items) {
+        this.normalPriority.push(...items);
+        this.scheduleProcessing();
+    }
+    scheduleProcessing() {
+        if (this.timeoutId || this.processing)
+            return;
+        this.timeoutId = setTimeout(() => {
+            this.timeoutId = null;
+            this.processQueue().catch(console.error);
+        }, this.config.batchDelay);
+    }
+    async processQueue() {
+        if (this.processing)
+            return;
+        this.processing = true;
+        const maxBatch = this.config.maxBatchSize ?? 50;
+        try {
+            // Process high priority first
+            while (this.highPriority.length > 0) {
+                const batch = this.highPriority.splice(0, maxBatch);
+                await this.simile.add(batch);
+            }
+            // Then normal priority
+            while (this.normalPriority.length > 0) {
+                const batch = this.normalPriority.splice(0, maxBatch);
+                await this.simile.add(batch);
+            }
+        }
+        finally {
+            this.processing = false;
+        }
+    }
+    /**
+     * Force immediate processing.
+     */
+    async flush() {
+        if (this.timeoutId) {
+            clearTimeout(this.timeoutId);
+            this.timeoutId = null;
+        }
+        await this.processQueue();
+    }
+    /**
+     * Get total pending count.
+     */
+    getPendingCount() {
+        return this.highPriority.length + this.normalPriority.length;
+    }
+    /**
+     * Clear all pending items.
+     */
+    clear() {
+        if (this.timeoutId) {
+            clearTimeout(this.timeoutId);
+            this.timeoutId = null;
+        }
+        this.highPriority = [];
+        this.normalPriority = [];
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "simile-search",
-  "version": "0.3.2",
+  "version": "0.4.1",
   "description": "Offline-first semantic + fuzzy search engine for catalogs, names, and products",
   "type": "module",
   "main": "dist/index.js",