@joystick.js/db-canary 0.0.0-canary.2209

package/src/server/lib/operations/insert_one.js

@@ -0,0 +1,113 @@
+/**
+ * @fileoverview Insert operation for adding single documents to collections with indexing and write queue support.
+ * 
+ * Provides document insertion with automatic ID generation, timestamp management,
+ * duplicate prevention, index updates, and write queue serialization for consistency.
+ * Handles both internal and external insert operations with comprehensive error handling.
+ */
+
+import { get_database, generate_document_id, build_collection_key } from '../query_engine.js';
+import { update_indexes_on_insert } from '../index_manager.js';
+import { get_write_queue } from '../write_queue.js';
+import create_logger from '../logger.js';
+
+const { create_context_logger } = create_logger('insert_one');
+
+/**
+ * Internal implementation of insert_one operation without write queue serialization.
+ * @param {string} database_name - Name of the database
+ * @param {string} collection_name - Name of the collection
+ * @param {Object} document - Document to insert
+ * @param {Object} [options={}] - Insert options
+ * @returns {Promise<Object>} Insert result with acknowledged and inserted_id
+ * @throws {Error} When database/collection name is missing, document is invalid, or document already exists
+ */
+const insert_one_internal = async (database_name, collection_name, document, options = {}) => {
+  const log = create_context_logger();
+  
+  if (!database_name) {
+    throw new Error('Database name is required');
+  }
+  
+  if (!collection_name) {
+    throw new Error('Collection name is required');
+  }
+  
+  if (!document || typeof document !== 'object') {
+    throw new Error('Document must be a valid object');
+  }
+  
+  const db = get_database();
+  const document_id = document._id || generate_document_id();
+  const collection_key = build_collection_key(database_name, collection_name, document_id);
+  
+  const document_to_insert = {
+    ...document,
+    _id: document_id,
+    _created_at: new Date().toISOString(),
+    _updated_at: new Date().toISOString()
+  };
+  
+  let inserted_document = null;
+  
+  await db.transaction(() => {
+    const existing_document = db.get(collection_key);
+    
+    if (existing_document) {
+      throw new Error(`Document with _id ${document_id} already exists`);
+    }
+    
+    db.put(collection_key, JSON.stringify(document_to_insert));
+    inserted_document = document_to_insert;
+  });
+  
+  await update_indexes_on_insert(database_name, collection_name, inserted_document);
+  
+  log.info('Document inserted successfully', {
+    database: database_name,
+    collection: collection_name,
+    document_id: document_id
+  });
+  
+  return {
+    acknowledged: true,
+    inserted_id: document_id
+  };
+};
+
+/**
+ * Inserts a single document into a collection with write queue serialization.
+ * @param {string} database_name - Name of the database
+ * @param {string} collection_name - Name of the collection
+ * @param {Object} document - Document to insert
+ * @param {Object} [options={}] - Insert options
+ * @returns {Promise<Object>} Insert result with acknowledged and inserted_id
+ * @throws {Error} When database/collection name is missing or document is invalid
+ */
+const insert_one = async (database_name, collection_name, document, options = {}) => {
+  if (!database_name) {
+    throw new Error('Database name is required');
+  }
+  
+  if (!collection_name) {
+    throw new Error('Collection name is required');
+  }
+  
+  if (!document || typeof document !== 'object') {
+    throw new Error('Document must be a valid object');
+  }
+  
+  const write_queue = get_write_queue();
+  
+  return await write_queue.enqueue_write_operation(
+    () => insert_one_internal(database_name, collection_name, document, options),
+    {
+      operation: 'insert_one',
+      database: database_name,
+      collection: collection_name,
+      document_id: document._id || 'auto-generated'
+    }
+  );
+};
+
+export default insert_one;

package/src/server/lib/operations/update_one.js

@@ -0,0 +1,225 @@
+import { get_database, build_collection_key, generate_document_id } from '../query_engine.js';
+import { update_indexes_on_update, update_indexes_on_insert } from '../index_manager.js';
+import { get_write_queue } from '../write_queue.js';
+import create_logger from '../logger.js';
+
+const { create_context_logger } = create_logger('update_one');
+
+/**
+ * Applies MongoDB-style update operators to a document.
+ * @param {Object} document - Original document
+ * @param {Object} update_operations - Update operations ($set, $unset, $inc, $push, $pull)
+ * @returns {Object} Updated document
+ * @throws {Error} When unsupported update operator is used
+ */
+const apply_update_operators = (document, update_operations) => {
+  const updated_document = { ...document };
+  
+  for (const [operator, operations] of Object.entries(update_operations)) {
+    switch (operator) {
+      case '$set':
+        Object.assign(updated_document, operations);
+        break;
+        
+      case '$unset':
+        for (const field of Object.keys(operations)) {
+          delete updated_document[field];
+        }
+        break;
+        
+      case '$inc':
+        for (const [field, value] of Object.entries(operations)) {
+          updated_document[field] = (updated_document[field] || 0) + value;
+        }
+        break;
+        
+      case '$push':
+        for (const [field, value] of Object.entries(operations)) {
+          if (!Array.isArray(updated_document[field])) {
+            updated_document[field] = [];
+          }
+          updated_document[field].push(value);
+        }
+        break;
+        
+      case '$pull':
+        for (const [field, value] of Object.entries(operations)) {
+          if (Array.isArray(updated_document[field])) {
+            updated_document[field] = updated_document[field].filter(item => item !== value);
+          }
+        }
+        break;
+        
+      default:
+        throw new Error(`Unsupported update operator: ${operator}`);
+    }
+  }
+  
+  return updated_document;
+};
+
+/**
+ * Checks if a document matches the given filter criteria (simple equality check).
+ * @param {Object} document - Document to test
+ * @param {Object} filter - Filter criteria
+ * @returns {boolean} True if document matches filter
+ */
+const matches_filter = (document, filter) => {
+  if (!filter || Object.keys(filter).length === 0) {
+    return true;
+  }
+  
+  for (const [field, value] of Object.entries(filter)) {
+    if (document[field] !== value) {
+      return false;
+    }
+  }
+  
+  return true;
+};
+
+/**
+ * Internal implementation of update_one operation without write queue serialization.
+ * @param {string} database_name - Name of the database
+ * @param {string} collection_name - Name of the collection
+ * @param {Object} filter - Filter criteria to match document
+ * @param {Object} update - Update operations to apply
+ * @param {Object} [options={}] - Update options
+ * @param {boolean} [options.upsert] - Create document if not found
+ * @returns {Promise<Object>} Update result with acknowledged, matched_count, modified_count, and optional upserted_id
+ * @throws {Error} When database name, collection name, filter, or update is invalid
+ */
+const update_one_internal = async (database_name, collection_name, filter, update, options = {}) => {
+  const log = create_context_logger();
+  
+  if (!database_name) {
+    throw new Error('Database name is required');
+  }
+  
+  if (!collection_name) {
+    throw new Error('Collection name is required');
+  }
+  
+  if (!filter || typeof filter !== 'object') {
+    throw new Error('Filter must be a valid object');
+  }
+  
+  if (!update || typeof update !== 'object') {
+    throw new Error('Update must be a valid object');
+  }
+  
+  const db = get_database();
+  let matched_count = 0;
+  let modified_count = 0;
+  let upserted_id = null;
+  
+  let old_document = null;
+  let new_document = null;
+  let upserted_document = null;
+  
+  await db.transaction(() => {
+    const collection_prefix = `${database_name}:${collection_name}:`;
+    let document_found = false;
+    
+    const range = db.getRange({ start: collection_prefix, end: collection_prefix + '\xFF' });
+    for (const { key, value } of range) {
+      let document;
+      try {
+        document = JSON.parse(value);
+      } catch (parse_error) {
+        // Skip documents that can't be parsed
+        continue;
+      }
+      
+      if (matches_filter(document, filter)) {
+        document_found = true;
+        matched_count = 1;
+        
+        const updated_document = apply_update_operators(document, update);
+        updated_document._updated_at = new Date().toISOString();
+        
+        if (JSON.stringify(document) !== JSON.stringify(updated_document)) {
+          db.put(key, JSON.stringify(updated_document));
+          old_document = document;
+          new_document = updated_document;
+          modified_count = 1;
+        }
+        
+        break;
+      }
+    }
+    
+    if (!document_found && options.upsert) {
+      const document_id = generate_document_id();
+      const collection_key = build_collection_key(database_name, collection_name, document_id);
+      
+      const new_doc = {
+        ...filter,
+        _id: document_id,
+        _created_at: new Date().toISOString(),
+        _updated_at: new Date().toISOString()
+      };
+      
+      upserted_document = apply_update_operators(new_doc, update);
+      db.put(collection_key, JSON.stringify(upserted_document));
+      
+      upserted_id = document_id;
+      matched_count = 0;
+      modified_count = 0;
+    }
+  });
+  
+  if (old_document && new_document) {
+    await update_indexes_on_update(database_name, collection_name, old_document, new_document);
+  }
+  
+  if (upserted_document) {
+    await update_indexes_on_insert(database_name, collection_name, upserted_document);
+  }
+  
+  log.info('Update operation completed', {
+    database: database_name,
+    collection: collection_name,
+    matched_count,
+    modified_count,
+    upserted_id
+  });
+  
+  const result = {
+    acknowledged: true,
+    matched_count,
+    modified_count
+  };
+  
+  if (upserted_id) {
+    result.upserted_id = upserted_id;
+  }
+  
+  return result;
+};
+
+/**
+ * Updates a single document in a collection with write queue serialization.
+ * @param {string} database_name - Name of the database
+ * @param {string} collection_name - Name of the collection
+ * @param {Object} filter - Filter criteria to match document
+ * @param {Object} update - Update operations to apply
+ * @param {Object} [options={}] - Update options
+ * @param {boolean} [options.upsert] - Create document if not found
+ * @returns {Promise<Object>} Update result with acknowledged, matched_count, modified_count, and optional upserted_id
+ */
+const update_one = async (database_name, collection_name, filter, update, options = {}) => {
+  const write_queue = get_write_queue();
+  
+  return await write_queue.enqueue_write_operation(
+    () => update_one_internal(database_name, collection_name, filter, update, options),
+    {
+      operation: 'update_one',
+      database: database_name,
+      collection: collection_name,
+      filter_keys: Object.keys(filter || {})
+    }
+  );
+};
+
+export default update_one;

package/src/server/lib/performance_monitor.js

@@ -0,0 +1,313 @@
+/**
+ * @fileoverview Performance monitoring system for JoystickDB server operations.
+ * Tracks operation metrics, response times, error rates, memory usage, database statistics,
+ * and system performance. Provides comprehensive monitoring and logging capabilities.
+ */
+
+import create_logger from './logger.js';
+import { get_database } from './query_engine.js';
+
+const { create_context_logger } = create_logger('performance_monitor');
+
+/**
+ * Performance monitoring class that tracks server operations and system metrics.
+ * Provides detailed statistics on operations, errors, response times, and resource usage.
+ */
+class PerformanceMonitor {
+  /**
+   * Creates a new PerformanceMonitor instance.
+   * Initializes metrics tracking and logging capabilities.
+   */
+  constructor() {
+    this.log = create_context_logger();
+    
+    /** @type {Object} Performance metrics storage */
+    this.metrics = {
+      operations: new Map(),
+      errors: new Map(),
+      response_times: [],
+      start_time: Date.now(),
+      total_requests: 0,
+      total_errors: 0
+    };
+    
+    /** @type {number} Maximum number of response times to keep in memory */
+    this.max_response_times = 1000;
+  }
+  
+  /**
+   * Tracks a database operation with timing and error information.
+   * @param {string} op_type - Type of operation (e.g., 'find', 'insert', 'update')
+   * @param {number} duration_ms - Operation duration in milliseconds
+   * @param {string} status - Operation status ('success' or 'error')
+   * @param {string|null} [error=null] - Error message if operation failed
+   * @param {Object} [metadata={}] - Additional metadata for logging
+   */
+  track_operation(op_type, duration_ms, status, error = null, metadata = {}) {
+    this.metrics.total_requests++;
+    
+    // Track operation counts
+    if (!this.metrics.operations.has(op_type)) {
+      this.metrics.operations.set(op_type, { count: 0, total_time: 0, errors: 0 });
+    }
+    
+    const op_stats = this.metrics.operations.get(op_type);
+    op_stats.count++;
+    op_stats.total_time += duration_ms;
+    
+    if (status === 'error') {
+      this.metrics.total_errors++;
+      op_stats.errors++;
+      
+      // Track error types
+      const error_key = error || 'unknown_error';
+      if (!this.metrics.errors.has(error_key)) {
+        this.metrics.errors.set(error_key, 0);
+      }
+      this.metrics.errors.set(error_key, this.metrics.errors.get(error_key) + 1);
+    }
+    
+    // Track response times (keep only recent ones)
+    this.metrics.response_times.push({
+      timestamp: Date.now(),
+      duration_ms,
+      op_type,
+      status
+    });
+    
+    if (this.metrics.response_times.length > this.max_response_times) {
+      this.metrics.response_times.shift();
+    }
+    
+    // Log detailed operation info
+    this.log.info('Operation tracked', {
+      op: op_type,
+      duration_ms,
+      status,
+      error: error || undefined,
+      ...metadata
+    });
+  }
+  
+  /**
+   * Gets comprehensive performance statistics including operation metrics and rates.
+   * @returns {Object} Performance statistics object
+   * @returns {number} returns.uptime_ms - Server uptime in milliseconds
+   * @returns {number} returns.uptime_seconds - Server uptime in seconds
+   * @returns {number} returns.total_requests - Total number of requests processed
+   * @returns {number} returns.total_errors - Total number of errors encountered
+   * @returns {number} returns.ops_per_second - Operations per second rate
+   * @returns {number} returns.avg_response_time_ms - Average response time in milliseconds
+   * @returns {number} returns.error_rate_percent - Error rate as percentage
+   * @returns {Object} returns.operations - Per-operation statistics breakdown
+   * @returns {Array} returns.top_errors - Top 10 most frequent errors
+   * @returns {number} returns.recent_response_times - Number of recent response times tracked
+   */
+  get_performance_stats() {
+    const now = Date.now();
+    const uptime_ms = now - this.metrics.start_time;
+    const uptime_seconds = uptime_ms / 1000;
+    
+    // Calculate operations per second
+    const ops_per_second = uptime_seconds > 0 ? Math.round(this.metrics.total_requests / uptime_seconds) : 0;
+    
+    // Calculate average response time
+    const recent_response_times = this.metrics.response_times
+      .filter(rt => now - rt.timestamp < 60000) // Last minute
+      .map(rt => rt.duration_ms);
+    
+    const avg_response_time = recent_response_times.length > 0
+      ? Math.round(recent_response_times.reduce((sum, time) => sum + time, 0) / recent_response_times.length)
+      : 0;
+    
+    // Calculate error rate
+    const error_rate = this.metrics.total_requests > 0
+      ? Math.round((this.metrics.total_errors / this.metrics.total_requests) * 100 * 100) / 100
+      : 0;
+    
+    // Get operation breakdown
+    const operation_stats = {};
+    for (const [op_type, stats] of this.metrics.operations) {
+      operation_stats[op_type] = {
+        count: stats.count,
+        avg_duration_ms: stats.count > 0 ? Math.round(stats.total_time / stats.count) : 0,
+        error_count: stats.errors,
+        error_rate: stats.count > 0 ? Math.round((stats.errors / stats.count) * 100 * 100) / 100 : 0
+      };
+    }
+    
+    // Get top errors
+    const top_errors = Array.from(this.metrics.errors.entries())
+      .sort((a, b) => b[1] - a[1])
+      .slice(0, 10)
+      .map(([error, count]) => ({ error, count }));
+    
+    return {
+      uptime_ms,
+      uptime_seconds: Math.round(uptime_seconds),
+      total_requests: this.metrics.total_requests,
+      total_errors: this.metrics.total_errors,
+      ops_per_second,
+      avg_response_time_ms: avg_response_time,
+      error_rate_percent: error_rate,
+      operations: operation_stats,
+      top_errors,
+      recent_response_times: recent_response_times.length
+    };
+  }
+  
+  /**
+   * Gets current Node.js process memory usage statistics.
+   * @returns {Object} Memory usage statistics
+   * @returns {number} returns.rss_mb - Resident Set Size in MB
+   * @returns {number} returns.heap_total_mb - Total heap size in MB
+   * @returns {number} returns.heap_used_mb - Used heap size in MB
+   * @returns {number} returns.heap_used_percent - Heap usage percentage
+   * @returns {number} returns.external_mb - External memory usage in MB
+   * @returns {number} returns.array_buffers_mb - ArrayBuffer memory usage in MB
+   */
+  get_memory_stats() {
+    const memory_usage = process.memoryUsage();
+    
+    return {
+      rss_mb: Math.round(memory_usage.rss / 1024 / 1024),
+      heap_total_mb: Math.round(memory_usage.heapTotal / 1024 / 1024),
+      heap_used_mb: Math.round(memory_usage.heapUsed / 1024 / 1024),
+      heap_used_percent: Math.round((memory_usage.heapUsed / memory_usage.heapTotal) * 100),
+      external_mb: Math.round(memory_usage.external / 1024 / 1024),
+      array_buffers_mb: Math.round((memory_usage.arrayBuffers || 0) / 1024 / 1024)
+    };
+  }
+  
+  /**
+   * Gets LMDB database statistics including storage usage and structure info.
+   * @returns {Object} Database statistics object
+   * @returns {number} returns.map_size_mb - Total database map size in MB
+   * @returns {number} returns.used_space_mb - Used database space in MB
+   * @returns {number} returns.usage_percent - Database usage percentage
+   * @returns {number} returns.page_size - Database page size in bytes
+   * @returns {number} returns.tree_depth - B-tree depth
+   * @returns {number} returns.entry_count - Total number of entries
+   * @returns {number} returns.branch_pages - Number of branch pages
+   * @returns {number} returns.leaf_pages - Number of leaf pages
+   */
+  get_database_stats() {
+    try {
+      const db = get_database();
+      const raw_stats = db.getStats ? db.getStats() : {};
+      
+      const map_size_mb = Math.round((raw_stats.mapSize || 0) / 1024 / 1024);
+      const used_space_mb = Math.round(((raw_stats.lastPageNumber || 0) * (raw_stats.pageSize || 0)) / 1024 / 1024);
+      const usage_percent = map_size_mb > 0 ? Math.round((used_space_mb / map_size_mb) * 100) : 0;
+      
+      return {
+        map_size_mb,
+        used_space_mb,
+        usage_percent,
+        page_size: raw_stats.pageSize || 0,
+        tree_depth: raw_stats.treeDepth || 0,
+        entry_count: raw_stats.entryCount || 0,
+        branch_pages: raw_stats.treeBranchPages || 0,
+        leaf_pages: raw_stats.treeLeafPages || 0
+      };
+    } catch (error) {
+      this.log.warn('Could not get database stats', { error: error.message });
+      return {
+        error: 'Database stats unavailable',
+        map_size_mb: 0,
+        used_space_mb: 0,
+        usage_percent: 0
+      };
+    }
+  }
+  
+  /**
+   * Gets system and Node.js runtime statistics.
+   * @returns {Object} System statistics object
+   * @returns {string} returns.node_version - Node.js version
+   * @returns {string} returns.platform - Operating system platform
+   * @returns {string} returns.arch - CPU architecture
+   * @returns {number} returns.pid - Process ID
+   * @returns {number} returns.cpu_user_ms - CPU user time in milliseconds
+   * @returns {number} returns.cpu_system_ms - CPU system time in milliseconds
+   */
+  get_system_stats() {
+    const cpu_usage = process.cpuUsage();
+    
+    return {
+      node_version: process.version,
+      platform: process.platform,
+      arch: process.arch,
+      pid: process.pid,
+      cpu_user_ms: Math.round(cpu_usage.user / 1000),
+      cpu_system_ms: Math.round(cpu_usage.system / 1000)
+    };
+  }
+  
+  /**
+   * Logs a structured operation entry with detailed metrics and automatically tracks it.
+   * @param {string} client_id - Client identifier
+   * @param {string} op_type - Operation type
+   * @param {string|null} collection - Collection name (if applicable)
+   * @param {number} duration_ms - Operation duration in milliseconds
+   * @param {string} status - Operation status ('success' or 'error')
+   * @param {string|null} [error=null] - Error message if operation failed
+   * @param {number} [request_size=0] - Request size in bytes
+   * @param {number} [response_size=0] - Response size in bytes
+   */
+  log_structured_operation(client_id, op_type, collection, duration_ms, status, error = null, request_size = 0, response_size = 0) {
+    const log_entry = {
+      ts: new Date().toISOString(),
+      client_id,
+      op: op_type,
+      collection: collection || undefined,
+      duration_ms,
+      status,
+      error: error || undefined,
+      request_size: request_size || undefined,
+      response_size: response_size || undefined
+    };
+    
+    // Remove undefined fields
+    Object.keys(log_entry).forEach(key => {
+      if (log_entry[key] === undefined) {
+        delete log_entry[key];
+      }
+    });
+    
+    this.log.info('Structured operation log', log_entry);
+    
+    // Track in performance metrics
+    this.track_operation(op_type, duration_ms, status, error, {
+      client_id,
+      collection,
+      request_size,
+      response_size
+    });
+  }
+  
+  /**
+   * Resets all performance metrics to initial state.
+   * Preserves the start time as current time for accurate uptime calculation.
+   */
+  reset_metrics() {
+    this.metrics = {
+      operations: new Map(),
+      errors: new Map(),
+      response_times: [],
+      start_time: Date.now(),
+      total_requests: 0,
+      total_errors: 0
+    };
+    
+    this.log.info('Performance metrics reset');
+  }
+}
+
+// Global instance
+const performance_monitor = new PerformanceMonitor();
+
+export {
+  performance_monitor,
+  PerformanceMonitor
+};