@joystick.js/db-canary 0.0.0-canary.2251 → 0.0.0-canary.2252

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

@@ -13,6 +13,60 @@ import create_logger from '../logger.js';
 
 const { create_context_logger } = create_logger('find_one');
 
+/**
+ * Splits field path into parts.
+ * @param {string} field_path - Dot-separated field path
+ * @returns {Array<string>} Array of field parts
+ */
+const split_field_path = (field_path) => {
+  return field_path.split('.');
+};
+
+/**
+ * Checks if value is null or undefined.
+ * @param {any} value - Value to check
+ * @returns {boolean} True if null or undefined
+ */
+const is_null_or_undefined = (value) => {
+  return value === null || value === undefined;
+};
+
+/**
+ * Extracts remaining path from field parts.
+ * @param {Array<string>} parts - Field path parts
+ * @param {number} current_index - Current index in parts
+ * @returns {string} Remaining path
+ */
+const get_remaining_path = (parts, current_index) => {
+  return parts.slice(current_index + 1).join('.');
+};
+
+/**
+ * Collects nested values from array elements.
+ * @param {Array} array_value - Array to process
+ * @param {string} remaining_path - Remaining field path
+ * @returns {Array} Collected nested values
+ */
+const collect_nested_values_from_array = (array_value, remaining_path) => {
+  const nested_values = [];
+  
+  for (let j = 0; j < array_value.length; j++) {
+    const item = array_value[j];
+    if (typeof item === 'object' && item !== null) {
+      const nested_value = get_field_value(item, remaining_path);
+      if (nested_value !== undefined) {
+        if (Array.isArray(nested_value)) {
+          nested_values.push(...nested_value);
+        } else {
+          nested_values.push(nested_value);
+        }
+      }
+    }
+  }
+  
+  return nested_values.length > 0 ? nested_values : undefined;
+};
+
 /**
  * Gets the value of a nested field from a document using dot notation.
  * Handles nested array object queries like 'reviews.rating' where reviews is an array of objects.
@@ -21,47 +75,37 @@ const { create_context_logger } = create_logger('find_one');
  * @returns {any} Field value, array of values for nested array queries, or undefined if not found
  */
 const get_field_value = (document, field_path) => {
-  const parts = field_path.split('.');
+  const parts = split_field_path(field_path);
   let value = document;
   
   for (let i = 0; i < parts.length; i++) {
     const part = parts[i];
     
-    if (value === null || value === undefined) {
+    if (is_null_or_undefined(value)) {
       return undefined;
     }
     
     value = value[part];
     
-    // If we got an array and there are more parts to traverse
     if (Array.isArray(value) && i < parts.length - 1) {
-      // Extract the remaining path
-      const remaining_path = parts.slice(i + 1).join('.');
-      
-      // Collect all matching values from array elements
-      const nested_values = [];
-      for (let j = 0; j < value.length; j++) {
-        const item = value[j];
-        if (typeof item === 'object' && item !== null) {
-          const nested_value = get_field_value(item, remaining_path);
-          if (nested_value !== undefined) {
-            if (Array.isArray(nested_value)) {
-              nested_values.push(...nested_value);
-            } else {
-              nested_values.push(nested_value);
-            }
-          }
-        }
-      }
-      
-      // Return array of values for nested array queries
-      return nested_values.length > 0 ? nested_values : undefined;
+      const remaining_path = get_remaining_path(parts, i);
+      return collect_nested_values_from_array(value, remaining_path);
     }
   }
   
   return value;
 };
 
+/**
+ * Checks if current object has the specified property.
+ * @param {Object} current - Current object
+ * @param {string} property - Property name
+ * @returns {boolean} True if property exists
+ */
+const has_property = (current, property) => {
+  return current.hasOwnProperty(property);
+};
+
 /**
  * Checks if a nested field exists in a document using dot notation.
  * @param {Object} document - Document to check
@@ -69,16 +113,16 @@ const get_field_value = (document, field_path) => {
  * @returns {boolean} True if field exists
  */
 const field_exists = (document, field_path) => {
-  const parts = field_path.split('.');
+  const parts = split_field_path(field_path);
   let current = document;
   
   for (let i = 0; i < parts.length; i++) {
-    if (current === null || current === undefined || typeof current !== 'object') {
+    if (is_null_or_undefined(current) || typeof current !== 'object') {
       return false;
     }
     
     if (i === parts.length - 1) {
-      return current.hasOwnProperty(parts[i]);
+      return has_property(current, parts[i]);
     }
     
     current = current[parts[i]];
@@ -87,32 +131,265 @@ const field_exists = (document, field_path) => {
   return false;
 };
 
+/**
+ * Checks if array contains value for equality operator.
+ * @param {Array} field_value - Array field value
+ * @param {any} operand - Value to check
+ * @returns {boolean} True if array contains value
+ */
+const array_contains_value = (field_value, operand) => {
+  return field_value.includes(operand);
+};
+
+/**
+ * Checks if any array element satisfies comparison operator.
+ * @param {Array} field_value - Array field value
+ * @param {any} operand - Value to compare
+ * @param {Function} comparator - Comparison function
+ * @returns {boolean} True if any element satisfies condition
+ */
+const any_array_element_satisfies = (field_value, operand, comparator) => {
+  for (let i = 0; i < field_value.length; i++) {
+    if (comparator(field_value[i], operand)) {
+      return true;
+    }
+  }
+  return false;
+};
+
+/**
+ * Handles equality operator matching.
+ * @param {any} field_value - Field value to test
+ * @param {any} operand - Value to match
+ * @returns {boolean} True if matches
+ */
+const handle_equality_operator = (field_value, operand) => {
+  if (Array.isArray(field_value)) {
+    return array_contains_value(field_value, operand);
+  }
+  return field_value === operand;
+};
+
+/**
+ * Handles not equal operator matching.
+ * @param {any} field_value - Field value to test
+ * @param {any} operand - Value to match
+ * @returns {boolean} True if does not match
+ */
+const handle_not_equal_operator = (field_value, operand) => {
+  if (Array.isArray(field_value)) {
+    return !array_contains_value(field_value, operand);
+  }
+  return field_value !== operand;
+};
+
+/**
+ * Handles greater than operator matching.
+ * @param {any} field_value - Field value to test
+ * @param {any} operand - Value to compare
+ * @returns {boolean} True if greater than
+ */
+const handle_greater_than_operator = (field_value, operand) => {
+  if (Array.isArray(field_value)) {
+    return any_array_element_satisfies(field_value, operand, (val, op) => val > op);
+  }
+  return field_value > operand;
+};
+
+/**
+ * Handles greater than or equal operator matching.
+ * @param {any} field_value - Field value to test
+ * @param {any} operand - Value to compare
+ * @returns {boolean} True if greater than or equal
+ */
+const handle_greater_than_equal_operator = (field_value, operand) => {
+  if (Array.isArray(field_value)) {
+    return any_array_element_satisfies(field_value, operand, (val, op) => val >= op);
+  }
+  return field_value >= operand;
+};
+
+/**
+ * Handles less than operator matching.
+ * @param {any} field_value - Field value to test
+ * @param {any} operand - Value to compare
+ * @returns {boolean} True if less than
+ */
+const handle_less_than_operator = (field_value, operand) => {
+  if (Array.isArray(field_value)) {
+    return any_array_element_satisfies(field_value, operand, (val, op) => val < op);
+  }
+  return field_value < operand;
+};
+
+/**
+ * Handles less than or equal operator matching.
+ * @param {any} field_value - Field value to test
+ * @param {any} operand - Value to compare
+ * @returns {boolean} True if less than or equal
+ */
+const handle_less_than_equal_operator = (field_value, operand) => {
+  if (Array.isArray(field_value)) {
+    return any_array_element_satisfies(field_value, operand, (val, op) => val <= op);
+  }
+  return field_value <= operand;
+};
+
+/**
+ * Handles in operator matching.
+ * @param {any} field_value - Field value to test
+ * @param {Array} operand - Array of values to match
+ * @returns {boolean} True if value is in array
+ */
+const handle_in_operator = (field_value, operand) => {
+  if (!Array.isArray(operand)) {
+    return false;
+  }
+  
+  if (Array.isArray(field_value)) {
+    return any_array_element_satisfies(field_value, operand, (val, op) => op.includes(val));
+  }
+  
+  return operand.includes(field_value);
+};
+
+/**
+ * Handles not in operator matching.
+ * @param {any} field_value - Field value to test
+ * @param {Array} operand - Array of values to exclude
+ * @returns {boolean} True if value is not in array
+ */
+const handle_not_in_operator = (field_value, operand) => {
+  if (!Array.isArray(operand)) {
+    return false;
+  }
+  
+  if (Array.isArray(field_value)) {
+    for (let i = 0; i < field_value.length; i++) {
+      if (operand.includes(field_value[i])) {
+        return false;
+      }
+    }
+    return true;
+  }
+  
+  return !operand.includes(field_value);
+};
+
+/**
+ * Handles exists operator matching.
+ * @param {Object} document - Document to check
+ * @param {string} field - Field name
+ * @param {boolean} operand - Whether field should exist
+ * @returns {boolean} True if existence matches expectation
+ */
+const handle_exists_operator = (document, field, operand) => {
+  const exists = field_exists(document, field);
+  return operand ? exists : !exists;
+};
+
+/**
+ * Handles regex operator matching.
+ * @param {any} field_value - Field value to test
+ * @param {string} pattern - Regex pattern
+ * @param {string} options - Regex options
+ * @returns {boolean} True if matches regex
+ */
+const handle_regex_operator = (field_value, pattern, options = '') => {
+  const regex = new RegExp(pattern, options);
+  
+  if (Array.isArray(field_value)) {
+    return any_array_element_satisfies(field_value, regex, (val, reg) => {
+      return typeof val === 'string' && reg.test(val);
+    });
+  }
+  
+  return regex.test(field_value);
+};
+
+/**
+ * Processes query operators for a field.
+ * @param {Object} document - Document to test
+ * @param {string} field - Field name
+ * @param {any} field_value - Field value
+ * @param {Object} value - Query value with operators
+ * @returns {boolean} True if all operators match
+ */
+const process_query_operators = (document, field, field_value, value) => {
+  for (const [operator, operand] of Object.entries(value)) {
+    switch (operator) {
+      case '$eq':
+        if (!handle_equality_operator(field_value, operand)) return false;
+        break;
+      case '$ne':
+        if (!handle_not_equal_operator(field_value, operand)) return false;
+        break;
+      case '$gt':
+        if (!handle_greater_than_operator(field_value, operand)) return false;
+        break;
+      case '$gte':
+        if (!handle_greater_than_equal_operator(field_value, operand)) return false;
+        break;
+      case '$lt':
+        if (!handle_less_than_operator(field_value, operand)) return false;
+        break;
+      case '$lte':
+        if (!handle_less_than_equal_operator(field_value, operand)) return false;
+        break;
+      case '$in':
+        if (!handle_in_operator(field_value, operand)) return false;
+        break;
+      case '$nin':
+        if (!handle_not_in_operator(field_value, operand)) return false;
+        break;
+      case '$exists':
+        if (!handle_exists_operator(document, field, operand)) return false;
+        break;
+      case '$regex':
+        const regex_options = value.$options || '';
+        if (!handle_regex_operator(field_value, operand, regex_options)) return false;
+        break;
+      case '$options':
+        break;
+      default:
+        throw new Error(`Unsupported query operator: ${operator}`);
+    }
+  }
+  return true;
+};
+
+/**
+ * Handles OR operator matching.
+ * @param {Object} document - Document to test
+ * @param {Array} or_conditions - Array of OR conditions
+ * @returns {boolean} True if any condition matches
+ */
+const handle_or_operator = (document, or_conditions) => {
+  for (let i = 0; i < or_conditions.length; i++) {
+    if (matches_filter(document, or_conditions[i])) {
+      return true;
+    }
+  }
+  return false;
+};
+
 /**
  * Checks if a document matches the given filter criteria.
  * Supports MongoDB-like query operators with optimized array field matching.
  * @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;
   }
   
-  // Handle $or operator at the top level
   if (filter.$or && Array.isArray(filter.$or)) {
-    const or_conditions = filter.$or;
-    let or_match = false;
-    for (let i = 0; i < or_conditions.length; i++) {
-      if (matches_filter(document, or_conditions[i])) {
-        or_match = true;
-        break;
-      }
+    if (!handle_or_operator(document, filter.$or)) {
+      return false;
     }
-    if (!or_match) return false;
     
-    // Continue checking other conditions (if any) outside of $or
     const remaining_filter = { ...filter };
     delete remaining_filter.$or;
     if (Object.keys(remaining_filter).length > 0) {
@@ -125,143 +402,11 @@ const matches_filter = (document, 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':
-            // Handle array field matching for $eq
-            if (Array.isArray(field_value)) {
-              if (!field_value.includes(operand)) return false;
-            } else if (field_value !== operand) {
-              return false;
-            }
-            break;
-          case '$ne':
-            // Handle array field matching for $ne
-            if (Array.isArray(field_value)) {
-              if (field_value.includes(operand)) return false;
-            } else if (field_value === operand) {
-              return false;
-            }
-            break;
-          case '$gt':
-            if (Array.isArray(field_value)) {
-              let found = false;
-              for (let i = 0; i < field_value.length; i++) {
-                if (field_value[i] > operand) {
-                  found = true;
-                  break;
-                }
-              }
-              if (!found) return false;
-            } else if (field_value <= operand) {
-              return false;
-            }
-            break;
-          case '$gte':
-            if (Array.isArray(field_value)) {
-              let found = false;
-              for (let i = 0; i < field_value.length; i++) {
-                if (field_value[i] >= operand) {
-                  found = true;
-                  break;
-                }
-              }
-              if (!found) return false;
-            } else if (field_value < operand) {
-              return false;
-            }
-            break;
-          case '$lt':
-            if (Array.isArray(field_value)) {
-              let found = false;
-              for (let i = 0; i < field_value.length; i++) {
-                if (field_value[i] < operand) {
-                  found = true;
-                  break;
-                }
-              }
-              if (!found) return false;
-            } else if (field_value >= operand) {
-              return false;
-            }
-            break;
-          case '$lte':
-            if (Array.isArray(field_value)) {
-              let found = false;
-              for (let i = 0; i < field_value.length; i++) {
-                if (field_value[i] <= operand) {
-                  found = true;
-                  break;
-                }
-              }
-              if (!found) return false;
-            } else if (field_value > operand) {
-              return false;
-            }
-            break;
-          case '$in':
-            if (!Array.isArray(operand)) return false;
-            if (Array.isArray(field_value)) {
-              // Check if any array element is in the operand array
-              let found = false;
-              for (let i = 0; i < field_value.length; i++) {
-                if (operand.includes(field_value[i])) {
-                  found = true;
-                  break;
-                }
-              }
-              if (!found) return false;
-            } else if (!operand.includes(field_value)) {
-              return false;
-            }
-            break;
-          case '$nin':
-            if (!Array.isArray(operand)) return false;
-            if (Array.isArray(field_value)) {
-              // Check if any array element is in the operand array
-              for (let i = 0; i < field_value.length; i++) {
-                if (operand.includes(field_value[i])) {
-                  return false;
-                }
-              }
-            } else if (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':
-            // Handle $options parameter for regex flags
-            const regex_options = value.$options || '';
-            const regex = new RegExp(operand, regex_options);
-            if (Array.isArray(field_value)) {
-              let found = false;
-              for (let i = 0; i < field_value.length; i++) {
-                if (typeof field_value[i] === 'string' && regex.test(field_value[i])) {
-                  found = true;
-                  break;
-                }
-              }
-              if (!found) return false;
-            } else if (!regex.test(field_value)) {
-              return false;
-            }
-            break;
-          case '$options':
-            // $options is handled as part of $regex, skip it here
-            break;
-          default:
-            throw new Error(`Unsupported query operator: ${operator}`);
-        }
+      if (!process_query_operators(document, field, field_value, value)) {
+        return false;
       }
     } else {
-      // Direct field matching with array support
-      if (Array.isArray(field_value)) {
-        if (!field_value.includes(value)) return false;
-      } else if (field_value !== value) {
+      if (!handle_equality_operator(field_value, value)) {
         return false;
       }
     }
@@ -270,10 +415,57 @@ const matches_filter = (document, filter) => {
   return true;
 };
 
+/**
+ * Determines if projection is inclusion-based.
+ * @param {Object} projection - Projection specification
+ * @returns {boolean} True if inclusion-based
+ */
+const is_inclusion_projection = (projection) => {
+  return Object.values(projection).some(value => value === 1 || value === true);
+};
+
+/**
+ * Applies inclusion projection to document.
+ * @param {Object} document - Document to project
+ * @param {Object} projection - Projection specification
+ * @returns {Object} Projected document
+ */
+const apply_inclusion_projection = (document, projection) => {
+  const 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];
+    }
+  }
+  
+  return projected_document;
+};
+
+/**
+ * Applies exclusion projection to document.
+ * @param {Object} document - Document to project
+ * @param {Object} projection - Projection specification
+ * @returns {Object} Projected document
+ */
+const apply_exclusion_projection = (document, projection) => {
+  const projected_document = { ...document };
+  
+  for (const [field, exclude] of Object.entries(projection)) {
+    if (exclude === 0 || exclude === false) {
+      delete projected_document[field];
+    }
+  }
+  
+  return projected_document;
+};
+
 /**
  * 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)
+ * @param {Object} projection - Projection specification
  * @returns {Object} Projected document
  */
 const apply_projection = (document, projection) => {
@@ -281,56 +473,183 @@ const apply_projection = (document, projection) => {
     return document;
   }
   
-  const is_inclusion = Object.values(projection).some(value => value === 1 || value === true);
-  const projected_document = {};
+  if (is_inclusion_projection(projection)) {
+    return apply_inclusion_projection(document, projection);
+  } else {
+    return apply_exclusion_projection(document, projection);
+  }
+};
+
+/**
+ * Validates required parameters.
+ * @param {string} database_name - Database name
+ * @param {string} collection_name - Collection name
+ * @throws {Error} When parameters are missing
+ */
+const validate_find_parameters = (database_name, collection_name) => {
+  if (!database_name) {
+    throw new Error('Database name is required');
+  }
   
-  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];
+  if (!collection_name) {
+    throw new Error('Collection name is required');
+  }
+};
+
+/**
+ * Attempts to parse document from JSON string.
+ * @param {string} value - JSON string
+ * @returns {Object|null} Parsed document or null
+ */
+const parse_document_safely = (value) => {
+  try {
+    return JSON.parse(value);
+  } catch (parse_error) {
+    return null;
+  }
+};
+
+/**
+ * Searches for document using index.
+ * @param {Object} db - Database instance
+ * @param {string} database_name - Database name
+ * @param {string} collection_name - Collection name
+ * @param {Object} filter - Query filter
+ * @param {Object} index_info - Index information
+ * @returns {Object|null} Found document or null
+ */
+const search_using_index = (db, database_name, collection_name, filter, index_info) => {
+  const { field, operators } = index_info;
+  const field_filter = filter[field];
+  
+  record_index_usage(database_name, collection_name, field);
+  
+  let document_ids = null;
+  
+  if (typeof field_filter === 'object' && field_filter !== null && !Array.isArray(field_filter)) {
+    for (const operator of operators) {
+      if (field_filter[operator] !== undefined) {
+        document_ids = find_documents_by_index(database_name, collection_name, field, operator, field_filter[operator]);
+        break;
       }
     }
-  } else {
-    Object.assign(projected_document, document);
-    
-    for (const [field, exclude] of Object.entries(projection)) {
-      if (exclude === 0 || exclude === false) {
-        delete projected_document[field];
+  } else if (operators.includes('eq')) {
+    document_ids = find_documents_by_index(database_name, collection_name, field, 'eq', field_filter);
+  }
+  
+  if (document_ids && document_ids.length > 0) {
+    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) {
+        const document = parse_document_safely(value);
+        if (document && matches_filter(document, filter)) {
+          return document;
+        }
       }
     }
   }
   
-  return projected_document;
+  return null;
+};
+
+/**
+ * Searches collection using full scan.
+ * @param {Object} db - Database instance
+ * @param {string} database_name - Database name
+ * @param {string} collection_name - Collection name
+ * @param {Object} filter - Query filter
+ * @returns {Object|null} Found document or null
+ */
+const search_using_full_scan = (db, database_name, collection_name, filter) => {
+  const collection_prefix = `${database_name}:${collection_name}:`;
+  const range = db.getRange({ start: collection_prefix, end: collection_prefix + '\xFF' });
+  
+  for (const { key, value } of range) {
+    const document = parse_document_safely(value);
+    if (document && matches_filter(document, filter)) {
+      return document;
+    }
+  }
+  
+  return null;
+};
+
+/**
+ * Records query for auto-indexing analysis.
+ * @param {Function} log - Logger function
+ * @param {string} collection_name - Collection name
+ * @param {Object} filter - Query filter
+ * @param {number} execution_time - Execution time in milliseconds
+ * @param {boolean} used_index - Whether index was used
+ * @param {string} indexed_field - Field that was indexed
+ */
+const record_query_for_auto_indexing = (log, collection_name, filter, execution_time, used_index, indexed_field) => {
+  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
+    });
+  }
+};
+
+/**
+ * Logs successful document find.
+ * @param {Function} log - Logger function
+ * @param {string} database_name - Database name
+ * @param {string} collection_name - Collection name
+ * @param {string} document_id - Document ID
+ * @param {boolean} used_index - Whether index was used
+ * @param {string} indexed_field - Field that was indexed
+ * @param {number} execution_time - Execution time in milliseconds
+ */
+const log_document_found = (log, database_name, collection_name, document_id, used_index, indexed_field, execution_time) => {
+  log.info('Document found', {
+    database: database_name,
+    collection: collection_name,
+    document_id,
+    used_index,
+    indexed_field,
+    execution_time_ms: execution_time
+  });
+};
+
+/**
+ * Logs when no document is found.
+ * @param {Function} log - Logger function
+ * @param {string} database_name - Database name
+ * @param {string} collection_name - Collection name
+ * @param {boolean} used_index - Whether index was used
+ * @param {string} indexed_field - Field that was indexed
+ * @param {number} execution_time - Execution time in milliseconds
+ */
+const log_no_document_found = (log, database_name, collection_name, used_index, indexed_field, execution_time) => {
+  log.info('No document found', {
+    database: database_name,
+    collection: collection_name,
+    used_index,
+    indexed_field,
+    execution_time_ms: execution_time
+  });
 };
 
 /**
  * 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)
+ * @param {Object} filter - Filter criteria
+ * @param {Object} options - Query options
  * @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');
-  }
+  validate_find_parameters(database_name, collection_name);
   
   const db = get_database();
-  const { projection, sort } = options;
+  const { projection } = options;
   const start_time = Date.now();
   
   try {
@@ -341,119 +660,26 @@ const find_one = async (database_name, collection_name, filter = {}, options = {
     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;
-              }
-            }
-          }
-        }
-      }
+      indexed_field = index_info.field;
+      found_document = search_using_index(db, database_name, collection_name, filter, index_info);
+      used_index = found_document !== null;
     }
     
     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;
-        }
-      }
+      found_document = search_using_full_scan(db, database_name, collection_name, filter);
     }
     
     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
-      });
-    }
+    record_query_for_auto_indexing(log, collection_name, filter, execution_time, used_index, indexed_field);
     
     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
-      });
-      
+      log_document_found(log, database_name, collection_name, found_document._id, used_index, indexed_field, 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
-    });
-    
+    log_no_document_found(log, database_name, collection_name, used_index, indexed_field, execution_time);
     return null;
   } catch (error) {
     log.error('Failed to find document', {