@soulcraft/brainy 5.7.13 → 5.9.0

package/dist/transaction/TransactionManager.js

@@ -0,0 +1,145 @@
+/**
+ * Transaction Manager
+ *
+ * Manages transaction execution across the system.
+ * Provides high-level API for executing atomic operations.
+ *
+ * Usage:
+ * ```typescript
+ * const txManager = new TransactionManager()
+ *
+ * const result = await txManager.executeTransaction(async (tx) => {
+ *   tx.addOperation(operation1)
+ *   tx.addOperation(operation2)
+ *   return someValue
+ * })
+ * ```
+ */
+import { Transaction } from './Transaction.js';
+import { TransactionError } from './errors.js';
+import { prodLog } from '../utils/logger.js';
+/**
+ * Transaction Manager
+ */
+export class TransactionManager {
+    constructor() {
+        this.stats = {
+            totalTransactions: 0,
+            successfulTransactions: 0,
+            failedTransactions: 0,
+            rolledBackTransactions: 0,
+            averageExecutionTimeMs: 0,
+            averageOperationsPerTransaction: 0
+        };
+        this.totalExecutionTime = 0;
+        this.totalOperations = 0;
+    }
+    /**
+     * Execute a function within a transaction
+     * All operations succeed atomically or all rollback
+     *
+     * @param fn Function that builds and executes transaction
+     * @param options Transaction execution options
+     * @returns Result from user function
+     * @throws TransactionError if transaction fails
+     */
+    async executeTransaction(fn, options) {
+        const transaction = new Transaction(options);
+        this.stats.totalTransactions++;
+        try {
+            // Execute user function (builds operations list)
+            const result = await fn(transaction);
+            // Execute all operations atomically
+            await transaction.execute();
+            // Update statistics
+            this.stats.successfulTransactions++;
+            this.updateStats(transaction);
+            return result;
+        }
+        catch (error) {
+            // Transaction failed and rolled back
+            this.stats.failedTransactions++;
+            if (transaction.getState() === 'rolled_back') {
+                this.stats.rolledBackTransactions++;
+            }
+            this.updateStats(transaction);
+            // Re-throw with context
+            if (error instanceof TransactionError) {
+                throw error;
+            }
+            else {
+                throw new TransactionError(`Transaction failed: ${error.message}`, { cause: error });
+            }
+        }
+    }
+    /**
+     * Execute a transaction and return detailed result
+     */
+    async executeTransactionWithResult(fn, options) {
+        const startTime = Date.now();
+        const transaction = new Transaction(options);
+        try {
+            const value = await fn(transaction);
+            await transaction.execute();
+            const executionTimeMs = Date.now() - startTime;
+            return {
+                value,
+                operationCount: transaction.getOperationCount(),
+                executionTimeMs
+            };
+        }
+        catch (error) {
+            // Transaction failed
+            throw error;
+        }
+    }
+    /**
+     * Get transaction statistics
+     */
+    getStats() {
+        return { ...this.stats };
+    }
+    /**
+     * Reset transaction statistics
+     */
+    resetStats() {
+        this.stats = {
+            totalTransactions: 0,
+            successfulTransactions: 0,
+            failedTransactions: 0,
+            rolledBackTransactions: 0,
+            averageExecutionTimeMs: 0,
+            averageOperationsPerTransaction: 0
+        };
+        this.totalExecutionTime = 0;
+        this.totalOperations = 0;
+    }
+    /**
+     * Update running statistics
+     */
+    updateStats(transaction) {
+        const executionTime = transaction.getExecutionTimeMs();
+        const operationCount = transaction.getOperationCount();
+        if (executionTime !== undefined) {
+            this.totalExecutionTime += executionTime;
+            this.stats.averageExecutionTimeMs =
+                this.totalExecutionTime / this.stats.totalTransactions;
+        }
+        this.totalOperations += operationCount;
+        this.stats.averageOperationsPerTransaction =
+            this.totalOperations / this.stats.totalTransactions;
+    }
+    /**
+     * Log current statistics
+     */
+    logStats() {
+        prodLog.info('[TransactionManager] Statistics:');
+        prodLog.info(`  Total: ${this.stats.totalTransactions}`);
+        prodLog.info(`  Successful: ${this.stats.successfulTransactions}`);
+        prodLog.info(`  Failed: ${this.stats.failedTransactions}`);
+        prodLog.info(`  Rolled back: ${this.stats.rolledBackTransactions}`);
+        prodLog.info(`  Avg execution time: ${this.stats.averageExecutionTimeMs.toFixed(2)}ms`);
+        prodLog.info(`  Avg operations/tx: ${this.stats.averageOperationsPerTransaction.toFixed(2)}`);
+    }
+}
+//# sourceMappingURL=TransactionManager.js.map

package/dist/transaction/errors.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Transaction System Errors
+ *
+ * Provides detailed error information for transaction failures.
+ */
+/**
+ * Base class for all transaction errors
+ */
+export declare class TransactionError extends Error {
+    readonly context?: Record<string, any>;
+    constructor(message: string, context?: Record<string, any>);
+}
+/**
+ * Error during transaction execution
+ */
+export declare class TransactionExecutionError extends TransactionError {
+    readonly operationIndex: number;
+    readonly operationName: string | undefined;
+    readonly cause: Error;
+    constructor(message: string, operationIndex: number, operationName: string | undefined, cause: Error);
+}
+/**
+ * Error during transaction rollback
+ */
+export declare class TransactionRollbackError extends TransactionError {
+    readonly originalError: Error;
+    readonly rollbackErrors: Error[];
+    constructor(message: string, originalError: Error, rollbackErrors: Error[]);
+}
+/**
+ * Error for invalid transaction state
+ */
+export declare class InvalidTransactionStateError extends TransactionError {
+    constructor(currentState: string, attemptedAction: string);
+}
+/**
+ * Error for transaction timeout
+ */
+export declare class TransactionTimeoutError extends TransactionError {
+    constructor(timeoutMs: number, operationIndex: number);
+}

package/dist/transaction/errors.js

@@ -0,0 +1,66 @@
+/**
+ * Transaction System Errors
+ *
+ * Provides detailed error information for transaction failures.
+ */
+/**
+ * Base class for all transaction errors
+ */
+export class TransactionError extends Error {
+    constructor(message, context) {
+        super(message);
+        this.context = context;
+        this.name = 'TransactionError';
+        Error.captureStackTrace(this, this.constructor);
+    }
+}
+/**
+ * Error during transaction execution
+ */
+export class TransactionExecutionError extends TransactionError {
+    constructor(message, operationIndex, operationName, cause) {
+        super(message, {
+            operationIndex,
+            operationName,
+            cause: cause.message
+        });
+        this.operationIndex = operationIndex;
+        this.operationName = operationName;
+        this.cause = cause;
+        this.name = 'TransactionExecutionError';
+    }
+}
+/**
+ * Error during transaction rollback
+ */
+export class TransactionRollbackError extends TransactionError {
+    constructor(message, originalError, rollbackErrors) {
+        super(message, {
+            originalError: originalError.message,
+            rollbackErrorCount: rollbackErrors.length,
+            rollbackErrors: rollbackErrors.map(e => e.message)
+        });
+        this.originalError = originalError;
+        this.rollbackErrors = rollbackErrors;
+        this.name = 'TransactionRollbackError';
+    }
+}
+/**
+ * Error for invalid transaction state
+ */
+export class InvalidTransactionStateError extends TransactionError {
+    constructor(currentState, attemptedAction) {
+        super(`Cannot ${attemptedAction}: transaction is in state '${currentState}'`, { currentState, attemptedAction });
+        this.name = 'InvalidTransactionStateError';
+    }
+}
+/**
+ * Error for transaction timeout
+ */
+export class TransactionTimeoutError extends TransactionError {
+    constructor(timeoutMs, operationIndex) {
+        super(`Transaction timed out after ${timeoutMs}ms at operation ${operationIndex}`, { timeoutMs, operationIndex });
+        this.name = 'TransactionTimeoutError';
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/transaction/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Transaction System
+ *
+ * Provides atomicity for Brainy operations.
+ * All operations succeed or all rollback - no partial failures.
+ *
+ * @module transaction
+ */
+export * from './types.js';
+export * from './errors.js';
+export { Transaction } from './Transaction.js';
+export { TransactionManager, type TransactionStats } from './TransactionManager.js';
+export type { Operation, RollbackAction, TransactionState, TransactionContext, TransactionFunction, TransactionResult, TransactionOptions } from './types.js';
+export { TransactionError, TransactionExecutionError, TransactionRollbackError, InvalidTransactionStateError, TransactionTimeoutError } from './errors.js';

package/dist/transaction/index.js

@@ -0,0 +1,14 @@
+/**
+ * Transaction System
+ *
+ * Provides atomicity for Brainy operations.
+ * All operations succeed or all rollback - no partial failures.
+ *
+ * @module transaction
+ */
+export * from './types.js';
+export * from './errors.js';
+export { Transaction } from './Transaction.js';
+export { TransactionManager } from './TransactionManager.js';
+export { TransactionError, TransactionExecutionError, TransactionRollbackError, InvalidTransactionStateError, TransactionTimeoutError } from './errors.js';
+//# sourceMappingURL=index.js.map

package/dist/transaction/operations/IndexOperations.d.ts

@@ -0,0 +1,172 @@
+/**
+ * Index Operations with Rollback Support
+ *
+ * Provides transactional operations for all indexes:
+ * - TypeAwareHNSWIndex (per-type vector indexes)
+ * - HNSWIndex (legacy/fallback vector index)
+ * - MetadataIndexManager (roaring bitmap filtering)
+ * - GraphAdjacencyIndex (LSM-tree graph storage)
+ *
+ * Each operation can be executed and rolled back atomically.
+ */
+import type { HNSWIndex } from '../../hnsw/hnswIndex.js';
+import type { TypeAwareHNSWIndex } from '../../hnsw/typeAwareHNSWIndex.js';
+import type { MetadataIndexManager } from '../../utils/metadataIndex.js';
+import type { GraphAdjacencyIndex } from '../../graph/graphAdjacencyIndex.js';
+import type { NounType } from '../../types/graphTypes.js';
+import type { GraphVerb } from '../../coreTypes.js';
+import type { Operation, RollbackAction } from '../types.js';
+/**
+ * Add to HNSW index with rollback support
+ *
+ * Rollback strategy:
+ * - Remove item from index
+ *
+ * Note: Works with both HNSWIndex and TypeAwareHNSWIndex
+ */
+export declare class AddToHNSWOperation implements Operation {
+    private readonly index;
+    private readonly id;
+    private readonly vector;
+    readonly name = "AddToHNSW";
+    constructor(index: HNSWIndex, id: string, vector: number[]);
+    execute(): Promise<RollbackAction>;
+    /**
+     * Check if item exists in index
+     */
+    private itemExists;
+}
+/**
+ * Add to TypeAwareHNSW index with rollback support
+ *
+ * Rollback strategy:
+ * - Remove item from type-specific index
+ */
+export declare class AddToTypeAwareHNSWOperation implements Operation {
+    private readonly index;
+    private readonly id;
+    private readonly vector;
+    private readonly nounType;
+    readonly name = "AddToTypeAwareHNSW";
+    constructor(index: TypeAwareHNSWIndex, id: string, vector: number[], nounType: NounType);
+    execute(): Promise<RollbackAction>;
+    /**
+     * Check if item exists in type-specific index
+     */
+    private itemExists;
+}
+/**
+ * Remove from HNSW index with rollback support
+ *
+ * Rollback strategy:
+ * - Re-add item to index with original vector
+ *
+ * Note: Requires storing the vector for rollback
+ */
+export declare class RemoveFromHNSWOperation implements Operation {
+    private readonly index;
+    private readonly id;
+    private readonly vector;
+    readonly name = "RemoveFromHNSW";
+    constructor(index: HNSWIndex, id: string, vector: number[]);
+    execute(): Promise<RollbackAction>;
+}
+/**
+ * Remove from TypeAwareHNSW index with rollback support
+ *
+ * Rollback strategy:
+ * - Re-add item to type-specific index with original vector
+ */
+export declare class RemoveFromTypeAwareHNSWOperation implements Operation {
+    private readonly index;
+    private readonly id;
+    private readonly vector;
+    private readonly nounType;
+    readonly name = "RemoveFromTypeAwareHNSW";
+    constructor(index: TypeAwareHNSWIndex, id: string, vector: number[], // Required for rollback
+    nounType: NounType);
+    execute(): Promise<RollbackAction>;
+}
+/**
+ * Add to metadata index with rollback support
+ *
+ * Rollback strategy:
+ * - Remove item from index
+ */
+export declare class AddToMetadataIndexOperation implements Operation {
+    private readonly index;
+    private readonly id;
+    private readonly entity;
+    readonly name = "AddToMetadataIndex";
+    constructor(index: MetadataIndexManager, id: string, entity: any);
+    execute(): Promise<RollbackAction>;
+}
+/**
+ * Remove from metadata index with rollback support
+ *
+ * Rollback strategy:
+ * - Re-add item to index with original metadata
+ */
+export declare class RemoveFromMetadataIndexOperation implements Operation {
+    private readonly index;
+    private readonly id;
+    private readonly entity;
+    readonly name = "RemoveFromMetadataIndex";
+    constructor(index: MetadataIndexManager, id: string, entity: any);
+    execute(): Promise<RollbackAction>;
+}
+/**
+ * Add verb to graph index with rollback support
+ *
+ * Rollback strategy:
+ * - Remove verb from graph index
+ */
+export declare class AddToGraphIndexOperation implements Operation {
+    private readonly index;
+    private readonly verb;
+    readonly name = "AddToGraphIndex";
+    constructor(index: GraphAdjacencyIndex, verb: GraphVerb);
+    execute(): Promise<RollbackAction>;
+}
+/**
+ * Remove verb from graph index with rollback support
+ *
+ * Rollback strategy:
+ * - Re-add verb to graph index
+ */
+export declare class RemoveFromGraphIndexOperation implements Operation {
+    private readonly index;
+    private readonly verb;
+    readonly name = "RemoveFromGraphIndex";
+    constructor(index: GraphAdjacencyIndex, verb: GraphVerb);
+    execute(): Promise<RollbackAction>;
+}
+/**
+ * Batch operation: Add multiple items to HNSW index
+ *
+ * Useful for bulk imports with transaction support.
+ * Rolls back all items if any fail.
+ */
+export declare class BatchAddToHNSWOperation implements Operation {
+    readonly name = "BatchAddToHNSW";
+    private operations;
+    constructor(index: HNSWIndex, items: Array<{
+        id: string;
+        vector: number[];
+    }>);
+    execute(): Promise<RollbackAction>;
+}
+/**
+ * Batch operation: Add multiple entities to metadata index
+ *
+ * Useful for bulk imports with transaction support.
+ */
+export declare class BatchAddToMetadataIndexOperation implements Operation {
+    readonly name = "BatchAddToMetadataIndex";
+    private operations;
+    constructor(index: MetadataIndexManager, items: Array<{
+        id: string;
+        entity: any;
+    }>);
+    execute(): Promise<RollbackAction>;
+}