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

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

@@ -0,0 +1,340 @@
+/**
+ * @fileoverview Find operation implementation for JoystickDB with MongoDB-like query capabilities.
+ * Supports complex filtering, projection, sorting, pagination, and automatic index optimization.
+ * Includes comprehensive query operators, field path resolution, and performance monitoring.
+ */
+
+import { get_database, build_collection_key } from '../query_engine.js';
+import { can_use_index, find_documents_by_index } from '../index_manager.js';
+import { record_query, record_index_usage } from '../auto_index_manager.js';
+import create_logger from '../logger.js';
+
+const { create_context_logger } = create_logger('find');
+
+/**
+ * Extracts field value from document using dot notation path.
+ * @param {Object} document - Document to extract value from
+ * @param {string} field_path - Dot-separated field path (e.g., 'user.profile.name')
+ * @returns {*} Field value or undefined if path doesn't exist
+ */
+const get_field_value = (document, field_path) => {
+  const parts = field_path.split('.');
+  let value = document;
+  
+  for (const part of parts) {
+    if (value === null || value === undefined) {
+      return undefined;
+    }
+    value = value[part];
+  }
+  
+  return value;
+};
+
+/**
+ * Checks if a field exists in a document using dot notation path.
+ * @param {Object} document - Document to check
+ * @param {string} field_path - Dot-separated field path
+ * @returns {boolean} True if field exists, false otherwise
+ */
+const field_exists = (document, field_path) => {
+  const parts = field_path.split('.');
+  let current = document;
+  
+  for (let i = 0; i < parts.length; i++) {
+    if (current === null || current === undefined || typeof current !== 'object') {
+      return false;
+    }
+    
+    if (i === parts.length - 1) {
+      return current.hasOwnProperty(parts[i]);
+    }
+    
+    current = current[parts[i]];
+  }
+  
+  return false;
+};
+
+/**
+ * Checks if a document matches the provided filter criteria.
+ * Supports MongoDB-like query operators including $eq, $ne, $gt, $gte, $lt, $lte, $in, $nin, $exists, $regex.
+ * @param {Object} document - Document to test against filter
+ * @param {Object} filter - Filter criteria with field names and values/operators
+ * @returns {boolean} True if document matches filter, false otherwise
+ * @throws {Error} When unsupported query operator is used
+ */
+const matches_filter = (document, filter) => {
+  if (!filter || Object.keys(filter).length === 0) {
+    return true;
+  }
+  
+  for (const [field, value] of Object.entries(filter)) {
+    const field_value = get_field_value(document, field);
+    
+    if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+      for (const [operator, operand] of Object.entries(value)) {
+        switch (operator) {
+          case '$eq':
+            if (field_value !== operand) return false;
+            break;
+          case '$ne':
+            if (field_value === operand) return false;
+            break;
+          case '$gt':
+            if (field_value <= operand) return false;
+            break;
+          case '$gte':
+            if (field_value < operand) return false;
+            break;
+          case '$lt':
+            if (field_value >= operand) return false;
+            break;
+          case '$lte':
+            if (field_value > operand) return false;
+            break;
+          case '$in':
+            if (!Array.isArray(operand) || !operand.includes(field_value)) return false;
+            break;
+          case '$nin':
+            if (!Array.isArray(operand) || operand.includes(field_value)) return false;
+            break;
+          case '$exists':
+            const exists = field_exists(document, field);
+            if (operand && !exists) return false;
+            if (!operand && exists) return false;
+            break;
+          case '$regex':
+            const regex = new RegExp(operand);
+            if (!regex.test(field_value)) return false;
+            break;
+          default:
+            throw new Error(`Unsupported query operator: ${operator}`);
+        }
+      }
+    } else {
+      if (field_value !== value) return false;
+    }
+  }
+  
+  return true;
+};
+
+/**
+ * Applies projection to a document, including or excluding specified fields.
+ * Supports both inclusion and exclusion projections with MongoDB-like syntax.
+ * @param {Object} document - Document to project
+ * @param {Object} projection - Projection specification with field names and 1/0 or true/false values
+ * @returns {Object} Projected document with only specified fields
+ */
+const apply_projection = (document, projection) => {
+  if (!projection || Object.keys(projection).length === 0) {
+    return document;
+  }
+  
+  const is_inclusion = Object.values(projection).some(value => value === 1 || value === true);
+  const projected_document = {};
+  
+  if (is_inclusion) {
+    projected_document._id = document._id;
+    
+    for (const [field, include] of Object.entries(projection)) {
+      if (field === '_id' && (include === 0 || include === false)) {
+        delete projected_document._id;
+      } else if (include === 1 || include === true) {
+        projected_document[field] = document[field];
+      }
+    }
+  } else {
+    Object.assign(projected_document, document);
+    
+    for (const [field, exclude] of Object.entries(projection)) {
+      if (exclude === 0 || exclude === false) {
+        delete projected_document[field];
+      }
+    }
+  }
+  
+  return projected_document;
+};
+
+/**
+ * Sorts an array of documents based on sort specification.
+ * Supports multi-field sorting with ascending (1) and descending (-1) directions.
+ * @param {Array<Object>} documents - Array of documents to sort
+ * @param {Object} sort - Sort specification with field names and 1/-1 direction values
+ * @returns {Array<Object>} Sorted array of documents
+ */
+const apply_sort = (documents, sort) => {
+  if (!sort || Object.keys(sort).length === 0) {
+    return documents;
+  }
+  
+  return documents.sort((a, b) => {
+    for (const [field, direction] of Object.entries(sort)) {
+      const a_value = a[field];
+      const b_value = b[field];
+      
+      if (a_value === b_value) continue;
+      
+      if (a_value === undefined) return 1;
+      if (b_value === undefined) return -1;
+      
+      const comparison = a_value < b_value ? -1 : a_value > b_value ? 1 : 0;
+      
+      if (direction === -1) {
+        return -comparison;
+      }
+      
+      return comparison;
+    }
+    
+    return 0;
+  });
+};
+
+/**
+ * Finds documents in a collection matching the specified filter criteria.
+ * Supports MongoDB-like querying with automatic index optimization, projection, sorting, and pagination.
+ * @param {string} database_name - Name of the database
+ * @param {string} collection_name - Name of the collection to search
+ * @param {Object} [filter={}] - Filter criteria for matching documents
+ * @param {Object} [options={}] - Query options
+ * @param {Object} [options.projection] - Fields to include/exclude in results
+ * @param {Object} [options.sort] - Sort specification for ordering results
+ * @param {number} [options.limit] - Maximum number of documents to return
+ * @param {number} [options.skip=0] - Number of documents to skip
+ * @returns {Promise<Array<Object>>} Promise resolving to array of matching documents
+ * @throws {Error} When database or collection name is missing or query execution fails
+ */
+const find = async (database_name, collection_name, filter = {}, 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');
+  }
+  
+  const db = get_database();
+  const { projection, sort, limit, skip = 0 } = options;
+  const start_time = Date.now();
+  
+  try {
+    let matching_documents = [];
+    let used_index = false;
+    let indexed_field = null;
+    
+    const index_info = can_use_index(database_name, collection_name, filter);
+    
+    if (index_info) {
+      const { field, operators } = index_info;
+      const field_filter = filter[field];
+      indexed_field = field;
+      
+      if (typeof field_filter === 'object' && field_filter !== null && !Array.isArray(field_filter)) {
+        for (const operator of operators) {
+          if (field_filter[operator] !== undefined) {
+            const document_ids = find_documents_by_index(database_name, collection_name, field, operator, field_filter[operator]);
+            
+            if (document_ids) {
+              used_index = true;
+              record_index_usage(database_name, collection_name, field);
+              
+              for (const document_id of document_ids) {
+                const collection_key = build_collection_key(database_name, collection_name, document_id);
+                const document_data = db.get(collection_key);
+                
+                if (document_data) {
+                  const document = JSON.parse(document_data);
+                  if (matches_filter(document, filter)) {
+                    matching_documents.push(document);
+                  }
+                }
+              }
+              break;
+            }
+          }
+        }
+      } else if (operators.includes('eq')) {
+        const document_ids = find_documents_by_index(database_name, collection_name, field, 'eq', field_filter);
+        
+        if (document_ids) {
+          used_index = true;
+          record_index_usage(database_name, collection_name, field);
+          
+          for (const document_id of document_ids) {
+            const collection_key = build_collection_key(database_name, collection_name, document_id);
+            const document_data = db.get(collection_key);
+            
+            if (document_data) {
+              const document = JSON.parse(document_data);
+              if (matches_filter(document, filter)) {
+                matching_documents.push(document);
+              }
+            }
+          }
+        }
+      }
+    }
+    
+    if (!used_index) {
+      const collection_prefix = `${database_name}:${collection_name}:`;
+      const range = db.getRange({ start: collection_prefix, end: collection_prefix + '\xFF' });
+      
+      for (const { key, value: document_data } of range) {
+        const document = JSON.parse(document_data);
+        if (matches_filter(document, filter)) {
+          matching_documents.push(document);
+        }
+      }
+    }
+    
+    let sorted_documents = apply_sort(matching_documents, sort);
+    
+    if (skip > 0) {
+      sorted_documents = sorted_documents.slice(skip);
+    }
+    
+    if (limit && limit > 0) {
+      sorted_documents = sorted_documents.slice(0, limit);
+    }
+    
+    const projected_documents = sorted_documents.map(document => 
+      apply_projection(document, projection)
+    );
+    
+    const execution_time = Date.now() - start_time;
+    
+    try {
+      record_query(collection_name, filter, execution_time, used_index, indexed_field);
+    } catch (auto_index_error) {
+      log.warn('Failed to record query for auto-indexing', {
+        error: auto_index_error.message
+      });
+    }
+    
+    log.info('Find operation completed', {
+      database: database_name,
+      collection: collection_name,
+      documents_found: projected_documents.length,
+      total_matching: matching_documents.length,
+      used_index,
+      indexed_field,
+      execution_time_ms: execution_time
+    });
+    
+    return projected_documents;
+  } catch (error) {
+    log.error('Failed to find documents', {
+      database: database_name,
+      collection: collection_name,
+      error: error.message
+    });
+    throw error;
+  }
+};
+
+export default find;

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

@@ -0,0 +1,319 @@
+/**
+ * @fileoverview Find one document operation with indexing, filtering, and projection support.
+ * 
+ * Provides document retrieval with MongoDB-style query operators, index optimization,
+ * field projection, nested field access, and comprehensive query performance tracking.
+ * Supports both indexed and full collection scans with automatic query recording.
+ */
+
+import { get_database, build_collection_key } from '../query_engine.js';
+import { can_use_index, find_documents_by_index } from '../index_manager.js';
+import { record_query, record_index_usage } from '../auto_index_manager.js';
+import create_logger from '../logger.js';
+
+const { create_context_logger } = create_logger('find_one');
+
+/**
+ * Gets the value of a nested field from a document using dot notation.
+ * @param {Object} document - Document to extract field value from
+ * @param {string} field_path - Dot-separated field path (e.g., 'user.name')
+ * @returns {any} Field value or undefined if not found
+ */
+const get_field_value = (document, field_path) => {
+  const parts = field_path.split('.');
+  let value = document;
+  
+  for (const part of parts) {
+    if (value === null || value === undefined) {
+      return undefined;
+    }
+    value = value[part];
+  }
+  
+  return value;
+};
+
+/**
+ * Checks if a nested field exists in a document using dot notation.
+ * @param {Object} document - Document to check
+ * @param {string} field_path - Dot-separated field path (e.g., 'user.name')
+ * @returns {boolean} True if field exists
+ */
+const field_exists = (document, field_path) => {
+  const parts = field_path.split('.');
+  let current = document;
+  
+  for (let i = 0; i < parts.length; i++) {
+    if (current === null || current === undefined || typeof current !== 'object') {
+      return false;
+    }
+    
+    if (i === parts.length - 1) {
+      return current.hasOwnProperty(parts[i]);
+    }
+    
+    current = current[parts[i]];
+  }
+  
+  return false;
+};
+
+/**
+ * Checks if a document matches the given filter criteria.
+ * @param {Object} document - Document to test
+ * @param {Object} filter - Filter criteria with MongoDB-style operators
+ * @returns {boolean} True if document matches filter
+ * @throws {Error} When unsupported query operator is used
+ */
+const matches_filter = (document, filter) => {
+  if (!filter || Object.keys(filter).length === 0) {
+    return true;
+  }
+  
+  for (const [field, value] of Object.entries(filter)) {
+    const field_value = get_field_value(document, field);
+    
+    if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+      for (const [operator, operand] of Object.entries(value)) {
+        switch (operator) {
+          case '$eq':
+            if (field_value !== operand) return false;
+            break;
+          case '$ne':
+            if (field_value === operand) return false;
+            break;
+          case '$gt':
+            if (field_value <= operand) return false;
+            break;
+          case '$gte':
+            if (field_value < operand) return false;
+            break;
+          case '$lt':
+            if (field_value >= operand) return false;
+            break;
+          case '$lte':
+            if (field_value > operand) return false;
+            break;
+          case '$in':
+            if (!Array.isArray(operand) || !operand.includes(field_value)) return false;
+            break;
+          case '$nin':
+            if (!Array.isArray(operand) || operand.includes(field_value)) return false;
+            break;
+          case '$exists':
+            const exists = field_exists(document, field);
+            if (operand && !exists) return false;
+            if (!operand && exists) return false;
+            break;
+          case '$regex':
+            const regex = new RegExp(operand);
+            if (!regex.test(field_value)) return false;
+            break;
+          default:
+            throw new Error(`Unsupported query operator: ${operator}`);
+        }
+      }
+    } else {
+      if (field_value !== value) return false;
+    }
+  }
+  
+  return true;
+};
+
+/**
+ * Applies projection to a document, including or excluding specified fields.
+ * @param {Object} document - Document to project
+ * @param {Object} projection - Projection specification (1/true for inclusion, 0/false for exclusion)
+ * @returns {Object} Projected document
+ */
+const apply_projection = (document, projection) => {
+  if (!projection || Object.keys(projection).length === 0) {
+    return document;
+  }
+  
+  const is_inclusion = Object.values(projection).some(value => value === 1 || value === true);
+  const projected_document = {};
+  
+  if (is_inclusion) {
+    projected_document._id = document._id;
+    
+    for (const [field, include] of Object.entries(projection)) {
+      if (field === '_id' && (include === 0 || include === false)) {
+        delete projected_document._id;
+      } else if (include === 1 || include === true) {
+        projected_document[field] = document[field];
+      }
+    }
+  } else {
+    Object.assign(projected_document, document);
+    
+    for (const [field, exclude] of Object.entries(projection)) {
+      if (exclude === 0 || exclude === false) {
+        delete projected_document[field];
+      }
+    }
+  }
+  
+  return projected_document;
+};
+
+/**
+ * Finds a single document in a collection matching the filter criteria.
+ * @param {string} database_name - Name of the database
+ * @param {string} collection_name - Name of the collection
+ * @param {Object} [filter={}] - Filter criteria
+ * @param {Object} [options={}] - Query options
+ * @param {Object} [options.projection] - Field projection specification
+ * @param {Object} [options.sort] - Sort specification (currently unused)
+ * @returns {Promise<Object|null>} Found document or null if not found
+ * @throws {Error} When database or collection name is missing or query fails
+ */
+const find_one = async (database_name, collection_name, filter = {}, 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');
+  }
+  
+  const db = get_database();
+  const { projection, sort } = options;
+  const start_time = Date.now();
+  
+  try {
+    let found_document = null;
+    let used_index = false;
+    let indexed_field = null;
+    
+    const index_info = can_use_index(database_name, collection_name, filter);
+    
+    if (index_info) {
+      const { field, operators } = index_info;
+      const field_filter = filter[field];
+      indexed_field = field;
+      
+      if (typeof field_filter === 'object' && field_filter !== null && !Array.isArray(field_filter)) {
+        for (const operator of operators) {
+          if (field_filter[operator] !== undefined) {
+            const document_ids = find_documents_by_index(database_name, collection_name, field, operator, field_filter[operator]);
+            
+            if (document_ids && document_ids.length > 0) {
+              used_index = true;
+              record_index_usage(database_name, collection_name, field);
+              
+              for (const document_id of document_ids) {
+                const collection_key = build_collection_key(database_name, collection_name, document_id);
+                const value = db.get(collection_key);
+                
+                if (value) {
+                  try {
+                    const document = JSON.parse(value);
+                    if (matches_filter(document, filter)) {
+                      found_document = document;
+                      break;
+                    }
+                  } catch (parse_error) {
+                    // Skip documents that can't be parsed
+                    continue;
+                  }
+                }
+              }
+              break;
+            }
+          }
+        }
+      } else if (operators.includes('eq')) {
+        const document_ids = find_documents_by_index(database_name, collection_name, field, 'eq', field_filter);
+        
+        if (document_ids && document_ids.length > 0) {
+          used_index = true;
+          record_index_usage(database_name, collection_name, field);
+          
+          for (const document_id of document_ids) {
+            const collection_key = build_collection_key(database_name, collection_name, document_id);
+            const value = db.get(collection_key);
+            
+            if (value) {
+              try {
+                const document = JSON.parse(value);
+                if (matches_filter(document, filter)) {
+                  found_document = document;
+                  break;
+                }
+              } catch (parse_error) {
+                // Skip documents that can't be parsed
+                continue;
+              }
+            }
+          }
+        }
+      }
+    }
+    
+    if (!used_index) {
+      const collection_prefix = `${database_name}:${collection_name}:`;
+      const range = db.getRange({ start: collection_prefix, end: collection_prefix + '\xFF' });
+      
+      for (const { key, value } of range) {
+        try {
+          const document = JSON.parse(value);
+          if (matches_filter(document, filter)) {
+            found_document = document;
+            break;
+          }
+        } catch (parse_error) {
+          // Skip documents that can't be parsed
+          continue;
+        }
+      }
+    }
+    
+    const execution_time = Date.now() - start_time;
+    
+    try {
+      record_query(collection_name, filter, execution_time, used_index, indexed_field);
+    } catch (auto_index_error) {
+      log.warn('Failed to record query for auto-indexing', {
+        error: auto_index_error.message
+      });
+    }
+    
+    if (found_document) {
+      const projected_document = apply_projection(found_document, projection);
+      
+      log.info('Document found', {
+        database: database_name,
+        collection: collection_name,
+        document_id: found_document._id,
+        used_index,
+        indexed_field,
+        execution_time_ms: execution_time
+      });
+      
+      return projected_document;
+    }
+    
+    log.info('No document found', {
+      database: database_name,
+      collection: collection_name,
+      used_index,
+      indexed_field,
+      execution_time_ms: execution_time
+    });
+    
+    return null;
+  } catch (error) {
+    log.error('Failed to find document', {
+      database: database_name,
+      collection: collection_name,
+      error: error.message
+    });
+    throw error;
+  }
+};
+
+export default find_one;

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

@@ -0,0 +1,52 @@
+/**
+ * @fileoverview Get indexes operation for JoystickDB collections.
+ * Provides functionality to retrieve all indexes for a specified collection.
+ */
+
+import { get_indexes } from '../index_manager.js';
+import create_logger from '../logger.js';
+
+const { create_context_logger } = create_logger('get_indexes');
+
+/**
+ * Retrieves all indexes for a specified collection.
+ * @param {string} database_name - Name of the database
+ * @param {string} collection_name - Name of the collection to get indexes for
+ * @returns {Promise<Object>} Result containing acknowledged status and array of indexes
+ * @throws {Error} When database or collection name is missing or index retrieval fails
+ */
+const get_indexes_operation = async (database_name, collection_name) => {
+  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');
+  }
+  
+  try {
+    const indexes = get_indexes(database_name, collection_name);
+    
+    log.info('Retrieved indexes successfully', {
+      database: database_name,
+      collection: collection_name,
+      count: indexes.length
+    });
+    
+    return {
+      acknowledged: true,
+      indexes
+    };
+  } catch (error) {
+    log.error('Failed to get indexes', {
+      database: database_name,
+      collection: collection_name,
+      error: error.message
+    });
+    throw error;
+  }
+};
+
+export default get_indexes_operation;