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

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

@@ -11,72 +11,105 @@ import create_logger from '../logger.js';
 
 const { create_context_logger } = create_logger('find');
 
+/**
+ * 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;
+};
+
+/**
+ * Collects nested values from array elements.
+ * @param {Array} array_value - Array to process
+ * @param {string} remaining_path - Remaining field path
+ * @returns {Array|undefined} Collected nested values or undefined
+ */
+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;
+};
+
 /**
  * Extracts field value from document using dot notation path.
- * Handles nested array object queries like 'reviews.rating' where reviews is an array of objects.
  * @param {Object} document - Document to extract value from
- * @param {string} field_path - Dot-separated field path (e.g., 'user.profile.name', 'reviews.rating')
- * @returns {*} Field value, array of values for nested array queries, or undefined if path doesn't exist
+ * @param {string} field_path - Dot-separated field path
+ * @returns {any} Field value or undefined if path doesn't exist
  */
 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;
+      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 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
+ * @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]];
@@ -85,32 +118,264 @@ const field_exists = (document, field_path) => {
   return false;
 };
 
+/**
+ * Checks if array contains value.
+ * @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 condition.
+ * @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 provided filter criteria.
- * Supports MongoDB-like query operators with optimized array field matching.
  * @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
+ * @returns {boolean} True if document matches filter
  */
 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) {
@@ -123,143 +388,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;
       }
     }
@@ -269,48 +402,90 @@ const matches_filter = (document, filter) => {
 };
 
 /**
- * Applies projection to a document, including or excluding specified fields.
- * Supports both inclusion and exclusion projections with MongoDB-like syntax.
+ * 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 with field names and 1/0 or true/false values
- * @returns {Object} Projected document with only specified fields
+ * @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.
+ * @param {Object} document - Document to project
+ * @param {Object} projection - Projection specification
+ * @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];
-      }
-    }
+  if (is_inclusion_projection(projection)) {
+    return apply_inclusion_projection(document, projection);
   } else {
-    Object.assign(projected_document, document);
-    
-    for (const [field, exclude] of Object.entries(projection)) {
-      if (exclude === 0 || exclude === false) {
-        delete projected_document[field];
-      }
-    }
+    return apply_exclusion_projection(document, projection);
   }
+};
+
+/**
+ * Compares two values for sorting.
+ * @param {any} a_value - First value
+ * @param {any} b_value - Second value
+ * @param {number} direction - Sort direction (1 or -1)
+ * @returns {number} Comparison result
+ */
+const compare_values_for_sort = (a_value, b_value, direction) => {
+  if (a_value === b_value) return 0;
+  if (a_value === undefined) return 1;
+  if (b_value === undefined) return -1;
   
-  return projected_document;
+  const comparison = a_value < b_value ? -1 : a_value > b_value ? 1 : 0;
+  return direction === -1 ? -comparison : comparison;
 };
 
 /**
  * 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
+ * @param {Object} sort - Sort specification
  * @returns {Array<Object>} Sorted array of documents
  */
 const apply_sort = (documents, sort) => {
@@ -320,44 +495,22 @@ const apply_sort = (documents, sort) => {
   
   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;
+      const comparison = compare_values_for_sort(a[field], b[field], direction);
+      if (comparison !== 0) {
+        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
+ * Validates required parameters.
+ * @param {string} database_name - Database name
+ * @param {string} collection_name - Collection name
+ * @throws {Error} When parameters are missing
  */
-const find = async (database_name, collection_name, filter = {}, options = {}) => {
-  const log = create_context_logger();
-  
+const validate_find_parameters = (database_name, collection_name) => {
   if (!database_name) {
     throw new Error('Database name is required');
   }
@@ -365,6 +518,152 @@ const find = async (database_name, collection_name, filter = {}, options = {}) =
   if (!collection_name) {
     throw new Error('Collection name is required');
   }
+};
+
+/**
+ * Searches for documents 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 {Array<Object>} Found documents
+ */
+const search_using_index = (db, database_name, collection_name, filter, index_info) => {
+  const { field, operators } = index_info;
+  const field_filter = filter[field];
+  const matching_documents = [];
+  
+  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 if (operators.includes('eq')) {
+    document_ids = find_documents_by_index(database_name, collection_name, field, 'eq', field_filter);
+  }
+  
+  if (document_ids) {
+    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);
+        }
+      }
+    }
+  }
+  
+  return matching_documents;
+};
+
+/**
+ * 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 {Array<Object>} Found documents
+ */
+const search_using_full_scan = (db, database_name, collection_name, filter) => {
+  const matching_documents = [];
+  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);
+    }
+  }
+  
+  return matching_documents;
+};
+
+/**
+ * Applies pagination to documents.
+ * @param {Array<Object>} documents - Documents to paginate
+ * @param {number} skip - Number of documents to skip
+ * @param {number} limit - Maximum number of documents to return
+ * @returns {Array<Object>} Paginated documents
+ */
+const apply_pagination = (documents, skip, limit) => {
+  let result = documents;
+  
+  if (skip > 0) {
+    result = result.slice(skip);
+  }
+  
+  if (limit && limit > 0) {
+    result = result.slice(0, limit);
+  }
+  
+  return result;
+};
+
+/**
+ * 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 find operation completion.
+ * @param {Function} log - Logger function
+ * @param {string} database_name - Database name
+ * @param {string} collection_name - Collection name
+ * @param {number} documents_found - Number of documents found
+ * @param {number} total_matching - Total matching documents
+ * @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_find_completion = (log, database_name, collection_name, documents_found, total_matching, used_index, indexed_field, execution_time) => {
+  log.info('Find operation completed', {
+    database: database_name,
+    collection: collection_name,
+    documents_found,
+    total_matching,
+    used_index,
+    indexed_field,
+    execution_time_ms: execution_time
+  });
+};
+
+/**
+ * Finds documents in a collection matching the specified filter criteria.
+ * @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
+ * @returns {Promise<Array<Object>>} Array of matching documents
+ */
+const find = async (database_name, collection_name, filter = {}, options = {}) => {
+  const log = create_context_logger();
+  
+  validate_find_parameters(database_name, collection_name);
   
   const db = get_database();
   const { projection, sort, limit, skip = 0 } = options;
@@ -378,101 +677,35 @@ const find = 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) {
-              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);
-              }
-            }
-          }
-        }
-      }
+      indexed_field = index_info.field;
+      matching_documents = search_using_index(db, database_name, collection_name, filter, index_info);
+      used_index = matching_documents.length > 0;
     }
     
     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);
+      matching_documents = search_using_full_scan(db, database_name, collection_name, filter);
     }
     
-    const projected_documents = sorted_documents.map(document => 
+    const sorted_documents = apply_sort(matching_documents, sort);
+    const paginated_documents = apply_pagination(sorted_documents, skip, limit);
+    const projected_documents = paginated_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
-      });
-    }
+    record_query_for_auto_indexing(log, collection_name, filter, execution_time, used_index, indexed_field);
     
-    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
-    });
+    log_find_completion(
+      log, 
+      database_name, 
+      collection_name, 
+      projected_documents.length, 
+      matching_documents.length, 
+      used_index, 
+      indexed_field, 
+      execution_time
+    );
     
     return projected_documents;
   } catch (error) {