@soulcraft/brainy 3.0.0 → 3.1.0

package/dist/utils/structuredLogger.js

@@ -0,0 +1,394 @@
+/**
+ * Enhanced Structured Logging System for Brainy
+ * Provides production-ready logging with structured output, context preservation,
+ * performance tracking, and multiple transport support
+ */
+import { performance } from 'perf_hooks';
+import { hostname } from 'os';
+import { randomUUID } from 'crypto';
+export var LogLevel;
+(function (LogLevel) {
+    LogLevel[LogLevel["SILENT"] = -1] = "SILENT";
+    LogLevel[LogLevel["FATAL"] = 0] = "FATAL";
+    LogLevel[LogLevel["ERROR"] = 1] = "ERROR";
+    LogLevel[LogLevel["WARN"] = 2] = "WARN";
+    LogLevel[LogLevel["INFO"] = 3] = "INFO";
+    LogLevel[LogLevel["DEBUG"] = 4] = "DEBUG";
+    LogLevel[LogLevel["TRACE"] = 5] = "TRACE";
+})(LogLevel || (LogLevel = {}));
+class ConsoleTransport {
+    constructor(format = 'json') {
+        this.name = 'console';
+        this.format = format;
+    }
+    log(entry) {
+        const method = this.getConsoleMethod(entry.levelNumeric);
+        if (this.format === 'json') {
+            method(JSON.stringify(entry));
+        }
+        else if (this.format === 'pretty') {
+            const color = this.getColor(entry.levelNumeric);
+            const prefix = `${entry.timestamp} ${color}[${entry.level}]\\x1b[0m [${entry.module}]`;
+            const message = entry.message;
+            if (entry.error) {
+                method(`${prefix} ${message}`, entry.error);
+            }
+            else if (entry.data) {
+                method(`${prefix} ${message}`, entry.data);
+            }
+            else {
+                method(`${prefix} ${message}`);
+            }
+        }
+        else {
+            // Simple format
+            method(`[${entry.level}] ${entry.message}`);
+        }
+    }
+    getConsoleMethod(level) {
+        switch (level) {
+            case LogLevel.FATAL:
+            case LogLevel.ERROR:
+                return console.error;
+            case LogLevel.WARN:
+                return console.warn;
+            case LogLevel.INFO:
+                return console.info;
+            default:
+                return console.log;
+        }
+    }
+    getColor(level) {
+        switch (level) {
+            case LogLevel.FATAL:
+                return '\\x1b[35m'; // Magenta
+            case LogLevel.ERROR:
+                return '\\x1b[31m'; // Red
+            case LogLevel.WARN:
+                return '\\x1b[33m'; // Yellow
+            case LogLevel.INFO:
+                return '\\x1b[36m'; // Cyan
+            case LogLevel.DEBUG:
+                return '\\x1b[32m'; // Green
+            case LogLevel.TRACE:
+                return '\\x1b[90m'; // Gray
+            default:
+                return '\\x1b[0m'; // Reset
+        }
+    }
+}
+class BufferedTransport {
+    constructor(innerTransport, bufferSize = 100, flushInterval = 5000) {
+        this.name = 'buffered';
+        this.buffer = [];
+        this.innerTransport = innerTransport;
+        this.bufferSize = bufferSize;
+        if (flushInterval > 0) {
+            this.flushTimer = setInterval(() => this.flush(), flushInterval);
+        }
+    }
+    log(entry) {
+        this.buffer.push(entry);
+        if (this.buffer.length >= this.bufferSize) {
+            this.flush();
+        }
+    }
+    async flush() {
+        const entries = this.buffer.splice(0);
+        for (const entry of entries) {
+            await this.innerTransport.log(entry);
+        }
+        if (this.innerTransport.flush) {
+            await this.innerTransport.flush();
+        }
+    }
+    destroy() {
+        if (this.flushTimer) {
+            clearInterval(this.flushTimer);
+        }
+        this.flush();
+    }
+}
+export class StructuredLogger {
+    constructor() {
+        this.defaultContext = {};
+        this.performanceMarks = new Map();
+        const isDevelopment = process.env.NODE_ENV !== 'production';
+        const format = isDevelopment ? 'pretty' : 'json';
+        this.config = {
+            level: isDevelopment ? LogLevel.DEBUG : LogLevel.INFO,
+            format,
+            transports: [new ConsoleTransport(format)],
+            includeHost: !isDevelopment,
+            includeMemory: false,
+            bufferSize: 100,
+            flushInterval: 5000,
+            version: process.env.npm_package_version
+        };
+        // Load from environment
+        this.loadEnvironmentConfig();
+    }
+    loadEnvironmentConfig() {
+        const envLevel = process.env.BRAINY_LOG_LEVEL;
+        if (envLevel) {
+            const level = LogLevel[envLevel.toUpperCase()];
+            if (level !== undefined) {
+                this.config.level = level;
+            }
+        }
+        const envFormat = process.env.BRAINY_LOG_FORMAT;
+        if (envFormat && ['json', 'pretty', 'simple'].includes(envFormat)) {
+            this.config.format = envFormat;
+        }
+        const moduleConfig = process.env.BRAINY_MODULE_LOG_LEVELS;
+        if (moduleConfig) {
+            try {
+                this.config.modules = JSON.parse(moduleConfig);
+            }
+            catch {
+                // Ignore parse errors
+            }
+        }
+    }
+    static getInstance() {
+        if (!StructuredLogger.instance) {
+            StructuredLogger.instance = new StructuredLogger();
+        }
+        return StructuredLogger.instance;
+    }
+    configure(config) {
+        this.config = { ...this.config, ...config };
+    }
+    setContext(context) {
+        this.defaultContext = { ...this.defaultContext, ...context };
+    }
+    clearContext() {
+        this.defaultContext = {};
+    }
+    withContext(context) {
+        const contextualLogger = Object.create(this);
+        contextualLogger.defaultContext = { ...this.defaultContext, ...context };
+        return contextualLogger;
+    }
+    startTimer(label) {
+        this.performanceMarks.set(label, performance.now());
+    }
+    endTimer(label) {
+        const start = this.performanceMarks.get(label);
+        if (start === undefined)
+            return undefined;
+        const duration = performance.now() - start;
+        this.performanceMarks.delete(label);
+        return duration;
+    }
+    shouldLog(level, module) {
+        if (this.config.modules?.[module] !== undefined) {
+            return level <= this.config.modules[module];
+        }
+        return level <= this.config.level;
+    }
+    createLogEntry(level, module, message, context, data, error) {
+        const entry = {
+            timestamp: new Date().toISOString(),
+            level: LogLevel[level],
+            levelNumeric: level,
+            module,
+            message,
+            pid: process.pid,
+            version: this.config.version
+        };
+        // Merge contexts
+        const mergedContext = { ...this.defaultContext, ...context };
+        if (Object.keys(mergedContext).length > 0) {
+            entry.context = mergedContext;
+        }
+        if (data !== undefined) {
+            entry.data = data;
+        }
+        if (error) {
+            entry.error = {
+                name: error.name,
+                message: error.message,
+                stack: error.stack,
+                code: error.code
+            };
+        }
+        if (this.config.includeHost) {
+            entry.host = hostname();
+        }
+        if (this.config.includeMemory) {
+            const mem = process.memoryUsage();
+            entry.performance = {
+                memory: {
+                    used: Math.round(mem.heapUsed / 1024 / 1024),
+                    total: Math.round(mem.heapTotal / 1024 / 1024)
+                }
+            };
+        }
+        return entry;
+    }
+    log(level, module, message, contextOrData, data) {
+        if (!this.shouldLog(level, module)) {
+            return;
+        }
+        // Handle overloaded parameters
+        let context;
+        let logData;
+        if (contextOrData && typeof contextOrData === 'object' && !Array.isArray(contextOrData)) {
+            // Check if it looks like a context object
+            const hasContextKeys = ['requestId', 'userId', 'operation', 'entityId', 'entityType']
+                .some(key => key in contextOrData);
+            if (hasContextKeys) {
+                context = contextOrData;
+                logData = data;
+            }
+            else {
+                logData = contextOrData;
+            }
+        }
+        else {
+            logData = contextOrData;
+        }
+        // Extract error if present
+        let error;
+        if (logData instanceof Error) {
+            error = logData;
+            logData = undefined;
+        }
+        else if (logData?.error instanceof Error) {
+            error = logData.error;
+            delete logData.error;
+        }
+        const entry = this.createLogEntry(level, module, message, context, logData, error);
+        // Send to all transports
+        for (const transport of this.config.transports) {
+            try {
+                transport.log(entry);
+            }
+            catch (err) {
+                // Fallback to console.error if transport fails
+                console.error('Logger transport error:', err);
+            }
+        }
+    }
+    fatal(module, message, contextOrData, data) {
+        this.log(LogLevel.FATAL, module, message, contextOrData, data);
+    }
+    error(module, message, contextOrData, data) {
+        this.log(LogLevel.ERROR, module, message, contextOrData, data);
+    }
+    warn(module, message, contextOrData, data) {
+        this.log(LogLevel.WARN, module, message, contextOrData, data);
+    }
+    info(module, message, contextOrData, data) {
+        this.log(LogLevel.INFO, module, message, contextOrData, data);
+    }
+    debug(module, message, contextOrData, data) {
+        this.log(LogLevel.DEBUG, module, message, contextOrData, data);
+    }
+    trace(module, message, contextOrData, data) {
+        this.log(LogLevel.TRACE, module, message, contextOrData, data);
+    }
+    createModuleLogger(module) {
+        const self = this;
+        return {
+            fatal: (message, contextOrData, data) => self.fatal(module, message, contextOrData, data),
+            error: (message, contextOrData, data) => self.error(module, message, contextOrData, data),
+            warn: (message, contextOrData, data) => self.warn(module, message, contextOrData, data),
+            info: (message, contextOrData, data) => self.info(module, message, contextOrData, data),
+            debug: (message, contextOrData, data) => self.debug(module, message, contextOrData, data),
+            trace: (message, contextOrData, data) => self.trace(module, message, contextOrData, data),
+            withContext: (context) => {
+                const contextual = self.withContext(context);
+                return contextual.createModuleLogger(module);
+            },
+            startTimer: (label) => self.startTimer(`${module}:${label}`),
+            endTimer: (label) => self.endTimer(`${module}:${label}`)
+        };
+    }
+    async flush() {
+        const flushPromises = this.config.transports
+            .filter(t => t.flush)
+            .map(t => t.flush());
+        await Promise.all(flushPromises);
+    }
+    addTransport(transport) {
+        this.config.transports.push(transport);
+    }
+    removeTransport(name) {
+        this.config.transports = this.config.transports.filter(t => t.name !== name);
+    }
+    child(context) {
+        return this.withContext(context);
+    }
+}
+// Singleton instance
+export const structuredLogger = StructuredLogger.getInstance();
+// Convenience functions
+export function createModuleLogger(module) {
+    return structuredLogger.createModuleLogger(module);
+}
+export function setLogContext(context) {
+    structuredLogger.setContext(context);
+}
+export function withLogContext(context) {
+    return structuredLogger.withContext(context);
+}
+// Correlation ID middleware helper
+export function createCorrelationId() {
+    return randomUUID();
+}
+// Performance logging helper
+export function logPerformance(logger, operation, fn) {
+    logger.startTimer(operation);
+    try {
+        const result = fn();
+        if (result && typeof result.then === 'function') {
+            return result.finally(() => {
+                const duration = logger.endTimer(operation);
+                logger.debug(`${operation} completed`, { duration });
+            });
+        }
+        const duration = logger.endTimer(operation);
+        logger.debug(`${operation} completed`, { duration });
+        return result;
+    }
+    catch (error) {
+        const duration = logger.endTimer(operation);
+        logger.error(`${operation} failed`, { duration, error });
+        throw error;
+    }
+}
+// Backward compatibility wrapper for existing logger
+export class LoggerCompatibilityWrapper {
+    constructor(module = 'legacy') {
+        this.moduleLogger = createModuleLogger(module);
+    }
+    error(module, message, ...args) {
+        this.moduleLogger.error(message, { module, data: args });
+    }
+    warn(module, message, ...args) {
+        this.moduleLogger.warn(message, { module, data: args });
+    }
+    info(module, message, ...args) {
+        this.moduleLogger.info(message, { module, data: args });
+    }
+    debug(module, message, ...args) {
+        this.moduleLogger.debug(message, { module, data: args });
+    }
+    trace(module, message, ...args) {
+        this.moduleLogger.trace(message, { module, data: args });
+    }
+    createModuleLogger(module) {
+        const logger = createModuleLogger(module);
+        return {
+            error: (message, ...args) => logger.error(message, { data: args }),
+            warn: (message, ...args) => logger.warn(message, { data: args }),
+            info: (message, ...args) => logger.info(message, { data: args }),
+            debug: (message, ...args) => logger.debug(message, { data: args }),
+            trace: (message, ...args) => logger.trace(message, { data: args })
+        };
+    }
+}
+// Types are already exported above, no need to re-export
+//# sourceMappingURL=structuredLogger.js.map

package/dist/utils/textEncoding.js

@@ -26,7 +26,8 @@ export async function applyTensorFlowPatch() {
                 return globalThis;
             if (typeof global !== 'undefined')
                 return global;
-            return {};
+            throw new Error('Cannot apply TextEncoder/TextDecoder patches: No global object found. ' +
+                'This environment does not have globalThis or global defined.');
         })();
         // Make sure TextEncoder and TextDecoder are available globally
         if (!globalObj.TextEncoder) {

package/dist/utils/typeValidation.d.ts

@@ -0,0 +1,59 @@
+import { NounType, VerbType } from '../types/graphTypes.js';
+export declare function isValidNounType(type: unknown): type is NounType;
+export declare function isValidVerbType(type: unknown): type is VerbType;
+export declare function validateNounType(type: unknown): NounType;
+export declare function validateVerbType(type: unknown): VerbType;
+export interface ValidatedGraphNoun {
+    noun: NounType;
+    [key: string]: any;
+}
+export interface ValidatedGraphVerb {
+    verb: VerbType;
+    [key: string]: any;
+}
+export declare function validateGraphNoun(noun: unknown): ValidatedGraphNoun;
+export declare function validateGraphVerb(verb: unknown): ValidatedGraphVerb;
+export declare function validateNounTypes(types: unknown[]): NounType[];
+export declare function validateVerbTypes(types: unknown[]): VerbType[];
+export interface ValidationStats {
+    validated: number;
+    failed: number;
+    inferred: number;
+    suggestions: number;
+}
+export declare function getValidationStats(): ValidationStats;
+export declare function resetValidationStats(): void;
+export declare class ValidationError extends Error {
+    readonly parameter: string;
+    readonly value: any;
+    readonly constraint: string;
+    constructor(parameter: string, value: any, constraint: string);
+}
+/**
+ * Validate required ID parameter
+ * Standard validation for all ID-based operations
+ */
+export declare function validateId(id: unknown, paramName?: string): string;
+/**
+ * Validate search query input
+ * Handles string queries, vectors, and objects for search operations
+ */
+export declare function validateSearchQuery(query: unknown, paramName?: string): any;
+/**
+ * Validate data input for addNoun/updateNoun operations
+ * Handles vectors, objects, strings, and validates structure
+ */
+export declare function validateDataInput(data: unknown, paramName?: string, allowNull?: boolean): any;
+/**
+ * Validate search options
+ * Comprehensive validation for search API options
+ */
+export declare function validateSearchOptions(options: unknown, paramName?: string): any;
+/**
+ * Validate ID arrays (for bulk operations)
+ */
+export declare function validateIdArray(ids: unknown, paramName?: string): string[];
+/**
+ * Track validation stats for monitoring
+ */
+export declare function recordValidation(success: boolean): void;