@soulcraft/brainy 3.20.4 → 3.21.0

package/dist/types/progress.types.js

@@ -0,0 +1,221 @@
+/**
+ * Standardized Progress Reporting
+ *
+ * Provides unified progress tracking across all long-running operations
+ * in Brainy (imports, clustering, large searches, etc.)
+ *
+ * PRODUCTION-READY - NO MOCKS, NO STUBS, REAL IMPLEMENTATION
+ */
+/**
+ * Progress tracker with automatic time estimation
+ */
+export class ProgressTracker {
+    constructor(total) {
+        this.status = 'pending';
+        this.processed = 0;
+        this.processingTimes = []; // Track last N processing times for estimation
+        if (total < 0) {
+            throw new Error('Total must be non-negative');
+        }
+        this.total = total;
+    }
+    /**
+     * Factory method for creating progress trackers
+     */
+    static create(total) {
+        return new ProgressTracker(total);
+    }
+    /**
+     * Start tracking progress
+     */
+    start() {
+        this.status = 'running';
+        this.startedAt = Date.now();
+        return this.current();
+    }
+    /**
+     * Update progress
+     */
+    update(processed, currentItem) {
+        if (processed < 0) {
+            throw new Error('Processed count must be non-negative');
+        }
+        if (processed > this.total) {
+            throw new Error(`Processed count (${processed}) exceeds total (${this.total})`);
+        }
+        const previousProcessed = this.processed;
+        this.processed = processed;
+        this.currentItem = currentItem;
+        // Track processing time for estimation
+        if (this.startedAt && previousProcessed < processed) {
+            const itemsProcessed = processed - previousProcessed;
+            const timeTaken = Date.now() - this.startedAt;
+            const avgTimePerItem = timeTaken / processed;
+            this.processingTimes.push(avgTimePerItem);
+            // Keep only last 100 measurements for rolling average
+            if (this.processingTimes.length > 100) {
+                this.processingTimes.shift();
+            }
+        }
+        return this.current();
+    }
+    /**
+     * Increment progress by 1
+     */
+    increment(currentItem) {
+        return this.update(this.processed + 1, currentItem);
+    }
+    /**
+     * Mark as completed
+     */
+    complete(result) {
+        this.status = 'completed';
+        this.completedAt = Date.now();
+        this.processed = this.total;
+        this.result = result;
+        return this.current();
+    }
+    /**
+     * Mark as failed
+     */
+    fail(error) {
+        this.status = 'failed';
+        this.completedAt = Date.now();
+        this.error = error;
+        return this.current();
+    }
+    /**
+     * Mark as cancelled
+     */
+    cancel() {
+        this.status = 'cancelled';
+        this.completedAt = Date.now();
+        return this.current();
+    }
+    /**
+     * Get current progress state
+     */
+    current() {
+        const progress = this.total > 0 ? Math.round((this.processed / this.total) * 100) : 0;
+        // Generate message based on status
+        let message;
+        switch (this.status) {
+            case 'pending':
+                message = `Ready to process ${this.total} items`;
+                break;
+            case 'running':
+                message = this.currentItem
+                    ? `Processing: ${this.currentItem} (${this.processed}/${this.total})`
+                    : `Processing ${this.processed}/${this.total} items`;
+                break;
+            case 'completed':
+                message = `Completed ${this.total} items`;
+                break;
+            case 'failed':
+                message = `Failed after ${this.processed} items: ${this.error?.message || 'Unknown error'}`;
+                break;
+            case 'cancelled':
+                message = `Cancelled after ${this.processed} items`;
+                break;
+        }
+        return {
+            status: this.status,
+            progress,
+            message,
+            metadata: {
+                itemsProcessed: this.processed,
+                itemsTotal: this.total,
+                currentItem: this.currentItem,
+                estimatedTimeRemaining: this.estimateTimeRemaining(),
+                startedAt: this.startedAt || Date.now(),
+                completedAt: this.completedAt,
+                throughput: this.calculateThroughput()
+            },
+            result: this.result,
+            error: this.error
+        };
+    }
+    /**
+     * Estimate time remaining based on processing history
+     */
+    estimateTimeRemaining() {
+        if (this.status !== 'running' || !this.startedAt || this.processed === 0) {
+            return undefined;
+        }
+        const remaining = this.total - this.processed;
+        if (remaining === 0) {
+            return 0;
+        }
+        // Use rolling average if we have enough samples
+        if (this.processingTimes.length > 0) {
+            const avgTimePerItem = this.processingTimes.reduce((a, b) => a + b, 0) / this.processingTimes.length;
+            return Math.round(avgTimePerItem * remaining);
+        }
+        // Fallback to simple calculation
+        const elapsed = Date.now() - this.startedAt;
+        const avgTimePerItem = elapsed / this.processed;
+        return Math.round(avgTimePerItem * remaining);
+    }
+    /**
+     * Calculate current throughput (items/second)
+     */
+    calculateThroughput() {
+        if (!this.startedAt || this.processed === 0) {
+            return undefined;
+        }
+        const elapsed = Date.now() - this.startedAt;
+        const seconds = elapsed / 1000;
+        return seconds > 0 ? Math.round((this.processed / seconds) * 100) / 100 : undefined;
+    }
+    /**
+     * Get progress statistics
+     */
+    getStats() {
+        const elapsed = this.startedAt ? Date.now() - this.startedAt : 0;
+        return {
+            status: this.status,
+            processed: this.processed,
+            total: this.total,
+            remaining: this.total - this.processed,
+            progress: this.total > 0 ? this.processed / this.total : 0,
+            elapsed,
+            estimatedTotal: elapsed > 0 && this.processed > 0
+                ? Math.round((elapsed / this.processed) * this.total)
+                : undefined,
+            throughput: this.calculateThroughput()
+        };
+    }
+}
+/**
+ * Helper to format time duration
+ */
+export function formatDuration(ms) {
+    const seconds = Math.floor(ms / 1000);
+    const minutes = Math.floor(seconds / 60);
+    const hours = Math.floor(minutes / 60);
+    if (hours > 0) {
+        return `${hours}h ${minutes % 60}m`;
+    }
+    else if (minutes > 0) {
+        return `${minutes}m ${seconds % 60}s`;
+    }
+    else {
+        return `${seconds}s`;
+    }
+}
+/**
+ * Helper to format progress percentage
+ */
+export function formatProgress(progress) {
+    const { status, progress: pct, metadata } = progress;
+    const remaining = metadata.estimatedTimeRemaining;
+    let str = `[${status.toUpperCase()}] ${pct}% (${metadata.itemsProcessed}/${metadata.itemsTotal})`;
+    if (metadata.throughput) {
+        str += ` - ${metadata.throughput} items/s`;
+    }
+    if (remaining && remaining > 0) {
+        str += ` - ${formatDuration(remaining)} remaining`;
+    }
+    return str;
+}
+//# sourceMappingURL=progress.types.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soulcraft/brainy",
-  "version": "3.20.4",
+  "version": "3.21.0",
   "description": "Universal Knowledge Protocol™ - World's first Triple Intelligence database unifying vector, graph, and document search in one API. 31 nouns × 40 verbs for infinite expressiveness.",
   "main": "dist/index.js",
   "module": "dist/index.js",
@@ -81,11 +81,15 @@
     "format:check": "prettier --check \"src/**/*.{ts,js}\"",
     "migrate:logger": "tsx scripts/migrate-to-structured-logger.ts",
     "migrate:logger:dry": "tsx scripts/migrate-to-structured-logger.ts --dry-run",
-    "release": "standard-version",
-    "release:patch": "standard-version --release-as patch",
-    "release:minor": "standard-version --release-as minor",
-    "release:major": "standard-version --release-as major",
-    "release:dry": "standard-version --dry-run"
+    "release": "./scripts/release.sh patch",
+    "release:patch": "./scripts/release.sh patch",
+    "release:minor": "./scripts/release.sh minor",
+    "release:major": "./scripts/release.sh major",
+    "release:dry": "./scripts/release.sh patch --dry-run",
+    "release:standard-version": "standard-version",
+    "release:standard-version:patch": "standard-version --release-as patch",
+    "release:standard-version:minor": "standard-version --release-as minor",
+    "release:standard-version:major": "standard-version --release-as major"
   },
   "keywords": [
     "ai-database",