jexidb 2.1.9 → 2.2.1

package/dist/Database.cjs

@@ -418,6 +418,10 @@ class IndexManager {
     this.rangeThreshold = 10; // Sensible threshold: 10+ consecutive numbers justify ranges
     this.binarySearchThreshold = 32; // Much higher for better performance
     this.database = database; // Reference to database for term manager access
+    this.indexLoaded = false;
+    this.indexIdleUnloadMs = typeof this.opts.indexIdleUnloadMs === 'number' ? this.opts.indexIdleUnloadMs : 30000;
+    this._idleUnloadTimer = null;
+    this._indexLoadPromise = null;
 
     // CRITICAL: Use database mutex to prevent deadlocks
     // If no database mutex provided, create a local one (for backward compatibility)
@@ -429,9 +433,9 @@ class IndexManager {
     this.totalLines = total;
   }
 
-  /**
-   * Update indexes configuration and ensure internal structures stay in sync
-   * @param {Object|Array<string>} indexes
+  /**
+   * Update indexes configuration and ensure internal structures stay in sync
+   * @param {Object|Array<string>} indexes
    */
   setIndexesConfig(indexes) {
     if (!indexes) {
@@ -463,11 +467,57 @@ class IndexManager {
       }
     }
   }
+  _clearIdleUnloadTimer() {
+    if (this._idleUnloadTimer) {
+      clearTimeout(this._idleUnloadTimer);
+      this._idleUnloadTimer = null;
+    }
+  }
+  cancelIdleUnloadTimer() {
+    this._clearIdleUnloadTimer();
+  }
+  markIndexUsed() {
+    if (!this.indexLoaded) return;
+    this._clearIdleUnloadTimer();
+    if (this.indexIdleUnloadMs > 0) {
+      const timer = setTimeout(() => {
+        try {
+          this.unload();
+        } catch (error) {
+          if (this.opts.debugMode) {
+            console.error('⚠️ IndexManager.markIndexUsed: Failed to unload index', error);
+          }
+        }
+      }, this.indexIdleUnloadMs);
+      if (timer && typeof timer.unref === 'function') {
+        timer.unref();
+      }
+      this._idleUnloadTimer = timer;
+    }
+  }
+  unload() {
+    if (!this.indexLoaded) return;
+    if (this.opts.debugMode) {
+      console.log(`🧹 IndexManager.unload: Unloading index data after ${this.indexIdleUnloadMs}ms idle`);
+    }
 
-  /**
-   * Check if a field is configured as an index
-   * @param {string} field - Field name
-   * @returns {boolean}
+    // Mark rebuild as needed so score() can trigger lazy reload
+    if (this.database) {
+      this.database._indexRebuildNeeded = true;
+    }
+    this._clearIdleUnloadTimer();
+    const newData = {};
+    for (const field of this.indexedFields) {
+      newData[field] = {};
+    }
+    this.index.data = newData;
+    this.indexLoaded = false;
+  }
+
+  /**
+   * Check if a field is configured as an index
+   * @param {string} field - Field name
+   * @returns {boolean}
    */
   isFieldIndexed(field) {
     if (!field) return false;
@@ -477,10 +527,10 @@ class IndexManager {
     return this.indexedFields.includes(field);
   }
 
-  /**
-   * Determine whether the index has usable data for a given field
-   * @param {string} field - Field name
-   * @returns {boolean}
+  /**
+   * Determine whether the index has usable data for a given field
+   * @param {string} field - Field name
+   * @returns {boolean}
    */
   hasUsableIndexData(field) {
     if (!field) return false;
@@ -875,6 +925,7 @@ class IndexManager {
 
   // OPTIMIZATION 6: Ultra-fast add operation with incremental index updates
   async add(row, lineNumber) {
+    this.markIndexUsed();
     if (typeof row !== 'object' || !row) {
       throw new Error('Invalid \'row\' parameter, it must be an object');
     }
@@ -950,12 +1001,13 @@ class IndexManager {
     }
   }
 
-  /**
-   * OPTIMIZATION 6: Add multiple records to the index in batch with optimized operations
-   * @param {Array} records - Records to add
-   * @param {number} startLineNumber - Starting line number
+  /**
+   * OPTIMIZATION 6: Add multiple records to the index in batch with optimized operations
+   * @param {Array} records - Records to add
+   * @param {number} startLineNumber - Starting line number
    */
   async addBatch(records, startLineNumber) {
+    this.markIndexUsed();
     if (!records || !records.length) return;
 
     // OPTIMIZATION 6: Pre-allocate index structures for better performance
@@ -1072,6 +1124,7 @@ class IndexManager {
 
   // Cleanup method to free memory
   cleanup() {
+    this._clearIdleUnloadTimer();
     const data = this.index.data;
     for (const field in data) {
       for (const value in data[field]) {
@@ -1096,12 +1149,14 @@ class IndexManager {
 
   // Clear all indexes
   clear() {
+    this._clearIdleUnloadTimer();
     this.index.data = {};
     this.totalLines = 0;
   }
 
   // Update a record in the index
   async update(oldRecord, newRecord, lineNumber = null) {
+    this.markIndexUsed();
     if (!oldRecord || !newRecord) return;
 
     // Remove old record by ID
@@ -1130,6 +1185,7 @@ class IndexManager {
 
   // Remove a record from the index
   async remove(record) {
+    this.markIndexUsed();
     if (!record) return;
 
     // If record is an array of line numbers, use the original method
@@ -1307,6 +1363,7 @@ class IndexManager {
 
   // Ultra-fast query with early exit and smart processing
   query(criteria, options = {}) {
+    this.markIndexUsed();
     if (typeof options === 'boolean') {
       options = {
         matchAny: options
@@ -1772,36 +1829,37 @@ class IndexManager {
     return matchingLines || new Set();
   }
 
-  /**
-   * Check if any records exist for given field and terms (index-only, ultra-fast)
-   * Stops at first match for maximum performance - no disk I/O required
-   * 
-   * @param {string} fieldName - Indexed field name (e.g., 'nameTerms', 'groupTerms')
-   * @param {string|Array<string>} terms - Single term or array of terms to check
-   * @param {Object} options - Options: { $all: true/false, caseInsensitive: true/false, excludes: Array<string> }
-   * @returns {boolean} - True if at least one match exists
-   * 
-   * @example
-   * // Check if any record has 'channel' in nameTerms
-   * indexManager.exists('nameTerms', 'channel')
-   * 
-   * @example
-   * // Check if any record has ALL terms ['a', 'e'] in nameTerms ($all)
-   * indexManager.exists('nameTerms', ['a', 'e'], { $all: true })
-   * 
-   * @example
-   * // Check if any record has ANY of the terms ['channel', 'tv'] in nameTerms
-   * indexManager.exists('nameTerms', ['channel', 'tv'], { $all: false })
-   * 
-   * @example
-   * // Check if any record has 'tv' but NOT 'globo' in nameTerms
-   * indexManager.exists('nameTerms', 'tv', { excludes: ['globo'] })
-   * 
-   * @example
-   * // Check if any record has ['tv', 'news'] but NOT 'sports' in nameTerms
-   * indexManager.exists('nameTerms', ['tv', 'news'], { $all: true, excludes: ['sports'] })
+  /**
+   * Check if any records exist for given field and terms (index-only, ultra-fast)
+   * Stops at first match for maximum performance - no disk I/O required
+   * 
+   * @param {string} fieldName - Indexed field name (e.g., 'nameTerms', 'groupTerms')
+   * @param {string|Array<string>} terms - Single term or array of terms to check
+   * @param {Object} options - Options: { $all: true/false, caseInsensitive: true/false, excludes: Array<string> }
+   * @returns {boolean} - True if at least one match exists
+   * 
+   * @example
+   * // Check if any record has 'channel' in nameTerms
+   * indexManager.exists('nameTerms', 'channel')
+   * 
+   * @example
+   * // Check if any record has ALL terms ['a', 'e'] in nameTerms ($all)
+   * indexManager.exists('nameTerms', ['a', 'e'], { $all: true })
+   * 
+   * @example
+   * // Check if any record has ANY of the terms ['channel', 'tv'] in nameTerms
+   * indexManager.exists('nameTerms', ['channel', 'tv'], { $all: false })
+   * 
+   * @example
+   * // Check if any record has 'tv' but NOT 'globo' in nameTerms
+   * indexManager.exists('nameTerms', 'tv', { excludes: ['globo'] })
+   * 
+   * @example
+   * // Check if any record has ['tv', 'news'] but NOT 'sports' in nameTerms
+   * indexManager.exists('nameTerms', ['tv', 'news'], { $all: true, excludes: ['sports'] })
    */
   exists(fieldName, terms, options = {}) {
+    this.markIndexUsed();
     // Early exit: validate fieldName
     if (!fieldName || typeof fieldName !== 'string') {
       return false;
@@ -2154,16 +2212,17 @@ class IndexManager {
     return candidateLines.size > 0;
   }
 
-  /**
-   * Evaluate many index-only existence checks while sharing the same field data.
-   * Returns a map keyed by the criteria id so callers can reuse a single scan per field.
-   *
-   * @param {string} fieldName - Indexed field name
-   * @param {Array<Object>} criteriaArray - Array of { id, terms, options }
-   * @param {Object} opts - { limit, allowPartial } (limit only applies when allowPartial is true)
-   * @returns {Object<string, boolean>} - Map of criteria id to boolean existence
+  /**
+   * Evaluate many index-only existence checks while sharing the same field data.
+   * Returns a map keyed by the criteria id so callers can reuse a single scan per field.
+   *
+   * @param {string} fieldName - Indexed field name
+   * @param {Array<Object>} criteriaArray - Array of { id, terms, options }
+   * @param {Object} opts - { limit, allowPartial } (limit only applies when allowPartial is true)
+   * @returns {Object<string, boolean>} - Map of criteria id to boolean existence
    */
   multiExists(fieldName, criteriaArray, opts = {}) {
+    this.markIndexUsed();
     const results = {};
     if (!Array.isArray(criteriaArray) || criteriaArray.length === 0) {
       return results;
@@ -2549,6 +2608,8 @@ class IndexManager {
         console.log(`🔍 IndexManager.load: No data loaded, preserving initialized fields: ${Object.keys(this.index.data).join(', ')}`);
       }
       // Keep the current index with initialized fields
+      this.indexLoaded = true;
+      this.markIndexUsed();
       return;
     }
 
@@ -2560,11 +2621,13 @@ class IndexManager {
       }
     }
     this.index = processedIndex;
+    this.indexLoaded = true;
+    this.markIndexUsed();
   }
 
-  /**
-   * CRITICAL FIX: Initialize default index structure when invalid data is provided
-   * This prevents TypeError when Object.keys() is called on null/undefined
+  /**
+   * CRITICAL FIX: Initialize default index structure when invalid data is provided
+   * This prevents TypeError when Object.keys() is called on null/undefined
    */
   _initializeDefaults() {
     if (this.opts.debugMode) {
@@ -2585,17 +2648,13 @@ class IndexManager {
         }
       }
     }
-    if (this.opts.debugMode) {
-      console.log(`🔍 IndexManager._initializeDefaults: Initialized with fields: ${Object.keys(this.index.data).join(', ')}`);
-    }
-  }
-  readColumnIndex(column) {
-    return new Set(this.index.data && this.index.data[column] ? Object.keys(this.index.data[column]) : []);
+    this.indexLoaded = true;
+    this.markIndexUsed();
   }
 
-  /**
-   * Convert index to JSON-serializable format for debugging and export
-   * This resolves the issue where Sets appear as empty objects in JSON.stringify
+  /**
+   * Convert index to JSON-serializable format for debugging and export
+   * This resolves the issue where Sets appear as empty objects in JSON.stringify
    */
   toJSON() {
     const serializable = {
@@ -2661,9 +2720,9 @@ class IndexManager {
     return serializable;
   }
 
-  /**
-   * Get a JSON string representation of the index
-   * This properly handles Sets unlike the default JSON.stringify
+  /**
+   * Get a JSON string representation of the index
+   * This properly handles Sets unlike the default JSON.stringify
    */
   toString() {
     return JSON.stringify(this.toJSON(), null, 2);
@@ -2671,8 +2730,8 @@ class IndexManager {
 
   // Simplified term mapping methods - just basic functionality
 
-  /**
-   * Rebuild index (stub for compatibility)
+  /**
+   * Rebuild index (stub for compatibility)
    */
   async rebuild() {
     // Stub implementation for compatibility
@@ -2680,9 +2739,9 @@ class IndexManager {
   }
 }
 
-/**
- * SchemaManager - Manages field schemas for optimized array-based serialization
- * This replaces the need for repeating field names in JSON objects
+/**
+ * SchemaManager - Manages field schemas for optimized array-based serialization
+ * This replaces the need for repeating field names in JSON objects
  */
 class SchemaManager {
   constructor(opts = {}) {
@@ -2700,8 +2759,8 @@ class SchemaManager {
     this.isInitialized = false;
   }
 
-  /**
-   * Initialize schema from options or auto-detect from data
+  /**
+   * Initialize schema from options or auto-detect from data
    */
   initializeSchema(schemaOrData, autoDetect = false) {
     if (this.isInitialized && this.opts.strictSchema) {
@@ -2726,8 +2785,8 @@ class SchemaManager {
     }
   }
 
-  /**
-   * Set explicit schema
+  /**
+   * Set explicit schema
    */
   setSchema(fieldNames) {
     this.schema = [...fieldNames]; // Create copy
@@ -2742,8 +2801,8 @@ class SchemaManager {
     }
   }
 
-  /**
-   * Auto-detect schema from sample data
+  /**
+   * Auto-detect schema from sample data
    */
   autoDetectSchema(sampleData) {
     if (Array.isArray(sampleData)) {
@@ -2764,9 +2823,9 @@ class SchemaManager {
     }
   }
 
-  /**
-   * Initialize schema from database options
-   * Note: schema option is no longer supported, use fields instead
+  /**
+   * Initialize schema from database options
+   * Note: schema option is no longer supported, use fields instead
    */
   initializeFromOptions(opts) {
     // Schema option is no longer supported - fields should be used instead
@@ -2774,8 +2833,8 @@ class SchemaManager {
     // Schema initialization is handled by Database.initializeSchema() using fields
   }
 
-  /**
-   * Add new field to schema (for schema evolution)
+  /**
+   * Add new field to schema (for schema evolution)
    */
   addField(fieldName) {
     if (this.fieldToIndex.has(fieldName)) {
@@ -2791,8 +2850,8 @@ class SchemaManager {
     return newIndex;
   }
 
-  /**
-   * Convert object to array using schema with strict field enforcement
+  /**
+   * Convert object to array using schema with strict field enforcement
    */
   objectToArray(obj) {
     if (!this.isInitialized || !this.opts.enableArraySerialization) {
@@ -2818,8 +2877,8 @@ class SchemaManager {
     return result;
   }
 
-  /**
-   * Convert array back to object using schema
+  /**
+   * Convert array back to object using schema
    */
   arrayToObject(arr) {
     if (!this.isInitialized || !this.opts.enableArraySerialization) {
@@ -2867,43 +2926,43 @@ class SchemaManager {
     return obj;
   }
 
-  /**
-   * Get field index by name
+  /**
+   * Get field index by name
    */
   getFieldIndex(fieldName) {
     return this.fieldToIndex.get(fieldName);
   }
 
-  /**
-   * Get field name by index
+  /**
+   * Get field name by index
    */
   getFieldName(index) {
     return this.indexToField.get(index);
   }
 
-  /**
-   * Check if field exists in schema
+  /**
+   * Check if field exists in schema
    */
   hasField(fieldName) {
     return this.fieldToIndex.has(fieldName);
   }
 
-  /**
-   * Get schema as array of field names
+  /**
+   * Get schema as array of field names
    */
   getSchema() {
     return [...this.schema]; // Return copy
   }
 
-  /**
-   * Get schema size
+  /**
+   * Get schema size
    */
   getSchemaSize() {
     return this.schema.length;
   }
 
-  /**
-   * Validate that object conforms to schema
+  /**
+   * Validate that object conforms to schema
    */
   validateObject(obj) {
     if (!this.isInitialized || !this.opts.strictSchema) {
@@ -2925,8 +2984,8 @@ class SchemaManager {
     return true;
   }
 
-  /**
-   * Get schema metadata for serialization
+  /**
+   * Get schema metadata for serialization
    */
   getSchemaMetadata() {
     return {
@@ -2937,8 +2996,8 @@ class SchemaManager {
     };
   }
 
-  /**
-   * Reset schema
+  /**
+   * Reset schema
    */
   reset() {
     this.schema = [];
@@ -2948,8 +3007,8 @@ class SchemaManager {
     this.schemaVersion++;
   }
 
-  /**
-   * Get performance statistics
+  /**
+   * Get performance statistics
    */
   getStats() {
     return {
@@ -2992,22 +3051,22 @@ class Serializer {
     };
   }
 
-  /**
-   * Initialize schema for array-based serialization
+  /**
+   * Initialize schema for array-based serialization
    */
   initializeSchema(schemaOrData, autoDetect = false) {
     this.schemaManager.initializeSchema(schemaOrData, autoDetect);
   }
 
-  /**
-   * Get current schema
+  /**
+   * Get current schema
    */
   getSchema() {
     return this.schemaManager.getSchema();
   }
 
-  /**
-   * Convert object to array format for optimized serialization
+  /**
+   * Convert object to array format for optimized serialization
    */
   convertToArrayFormat(obj) {
     if (!this.opts.enableArraySerialization) {
@@ -3016,8 +3075,8 @@ class Serializer {
     return this.schemaManager.objectToArray(obj);
   }
 
-  /**
-   * Convert array format back to object
+  /**
+   * Convert array format back to object
    */
   convertFromArrayFormat(arr) {
     if (!this.opts.enableArraySerialization) {
@@ -3044,8 +3103,8 @@ class Serializer {
     return obj;
   }
 
-  /**
-   * Advanced serialization with optimized JSON and buffer pooling
+  /**
+   * Advanced serialization with optimized JSON and buffer pooling
    */
   serialize(data, opts = {}) {
     this.serializationStats.totalSerializations++;
@@ -3072,8 +3131,8 @@ class Serializer {
     return this.serializeStandard(serializationData, addLinebreak);
   }
 
-  /**
-   * Advanced serialization with optimized JSON.stringify and buffer pooling
+  /**
+   * Advanced serialization with optimized JSON.stringify and buffer pooling
    */
   serializeAdvanced(data, addLinebreak) {
     // CRITICAL FIX: Sanitize data to remove problematic characters before serialization
@@ -3098,9 +3157,9 @@ class Serializer {
     return result;
   }
 
-  /**
-   * Proper encoding normalization with UTF-8 validation
-   * Fixed to prevent double-encoding and data corruption
+  /**
+   * Proper encoding normalization with UTF-8 validation
+   * Fixed to prevent double-encoding and data corruption
    */
   normalizeEncoding(str) {
     if (typeof str !== 'string') return str;
@@ -3112,8 +3171,8 @@ class Serializer {
     return this.safeConvertToUTF8(str);
   }
 
-  /**
-   * Check if string is valid UTF-8
+  /**
+   * Check if string is valid UTF-8
    */
   isValidUTF8(str) {
     try {
@@ -3126,8 +3185,8 @@ class Serializer {
     }
   }
 
-  /**
-   * Safe conversion to UTF-8 with proper encoding detection
+  /**
+   * Safe conversion to UTF-8 with proper encoding detection
    */
   safeConvertToUTF8(str) {
     // Try common encodings in order of likelihood
@@ -3151,9 +3210,9 @@ class Serializer {
     return str;
   }
 
-  /**
-   * Enhanced deep encoding normalization with UTF-8 validation
-   * Fixed to prevent double-encoding and data corruption
+  /**
+   * Enhanced deep encoding normalization with UTF-8 validation
+   * Fixed to prevent double-encoding and data corruption
    */
   deepNormalizeEncoding(obj) {
     if (obj === null || obj === undefined) return obj;
@@ -3179,13 +3238,13 @@ class Serializer {
     return obj;
   }
 
-  /**
-   * Validate encoding before serialization
+  /**
+   * Validate encoding before serialization
    */
-  /**
-   * Sanitize data to remove problematic characters that break JSON parsing
-   * CRITICAL FIX: Prevents "Expected ',' or ']'" and "Unterminated string" errors
-   * by removing control characters that cannot be safely represented in JSON
+  /**
+   * Sanitize data to remove problematic characters that break JSON parsing
+   * CRITICAL FIX: Prevents "Expected ',' or ']'" and "Unterminated string" errors
+   * by removing control characters that cannot be safely represented in JSON
    */
   sanitizeDataForJSON(data) {
     const sanitizeString = str => {
@@ -3247,9 +3306,9 @@ class Serializer {
     return issues.length === 0;
   }
 
-  /**
-   * Optimized JSON.stringify with fast paths for common data structures
-   * Now includes deep encoding normalization for all string fields
+  /**
+   * Optimized JSON.stringify with fast paths for common data structures
+   * Now includes deep encoding normalization for all string fields
    */
   optimizedStringify(obj) {
     // CRITICAL: Normalize encoding for all string fields before stringify
@@ -3310,8 +3369,8 @@ class Serializer {
     return result;
   }
 
-  /**
-   * Standard serialization (fallback)
+  /**
+   * Standard serialization (fallback)
    */
   serializeStandard(data, addLinebreak) {
     // CRITICAL FIX: Sanitize data to remove problematic characters before serialization
@@ -3337,8 +3396,8 @@ class Serializer {
     return result;
   }
 
-  /**
-   * Advanced deserialization with fast paths
+  /**
+   * Advanced deserialization with fast paths
    */
   deserialize(data) {
     this.serializationStats.totalDeserializations++;
@@ -3522,8 +3581,8 @@ class Serializer {
     }
   }
 
-  /**
-   * Batch serialization for multiple records
+  /**
+   * Batch serialization for multiple records
    */
   serializeBatch(dataArray, opts = {}) {
     // CRITICAL FIX: Sanitize data to remove problematic characters before serialization
@@ -3574,8 +3633,8 @@ class Serializer {
     }
   }
 
-  /**
-   * Batch deserialization for multiple records
+  /**
+   * Batch deserialization for multiple records
    */
   deserializeBatch(dataArray) {
     // Optimization: try to parse all entries as a single JSON array first
@@ -3617,16 +3676,16 @@ class Serializer {
     }
   }
 
-  /**
-   * Check if data appears to be binary (always false since we only use JSON now)
+  /**
+   * Check if data appears to be binary (always false since we only use JSON now)
    */
   isBinaryData(data) {
     // All data is now JSON format
     return false;
   }
 
-  /**
-   * Get comprehensive performance statistics
+  /**
+   * Get comprehensive performance statistics
    */
   getStats() {
     // NOTE: Buffer pool stats removed - buffer pool was causing more problems than benefits
@@ -3645,8 +3704,8 @@ class Serializer {
     };
   }
 
-  /**
-   * Cleanup resources
+  /**
+   * Cleanup resources
    */
   cleanup() {
     // NOTE: Buffer pool cleanup removed - buffer pool was causing more problems than benefits
@@ -4626,12 +4685,12 @@ class FileHandler {
     return groupedRanges;
   }
 
-  /**
-   * Ensure a line is complete by reading until newline if JSON appears truncated
-   * @param {string} line - The potentially incomplete line
-   * @param {number} fd - File descriptor
-   * @param {number} currentOffset - Current read offset
-   * @returns {string} Complete line
+  /**
+   * Ensure a line is complete by reading until newline if JSON appears truncated
+   * @param {string} line - The potentially incomplete line
+   * @param {number} fd - File descriptor
+   * @param {number} currentOffset - Current read offset
+   * @returns {string} Complete line
    */
   async ensureCompleteLine(line, fd, currentOffset) {
     // Fast check: if line already ends with newline, it's likely complete
@@ -4707,12 +4766,12 @@ class FileHandler {
     }
   }
 
-  /**
-   * Split content into complete JSON lines, handling special characters and escaped quotes
-   * CRITICAL FIX: Prevents "Expected ',' or ']'" and "Unterminated string" errors by ensuring
-   * each line is a complete, valid JSON object/array, even when containing special characters
-   * @param {string} content - Raw content containing multiple JSON lines
-   * @returns {string[]} Array of complete JSON lines
+  /**
+   * Split content into complete JSON lines, handling special characters and escaped quotes
+   * CRITICAL FIX: Prevents "Expected ',' or ']'" and "Unterminated string" errors by ensuring
+   * each line is a complete, valid JSON object/array, even when containing special characters
+   * @param {string} content - Raw content containing multiple JSON lines
+   * @returns {string[]} Array of complete JSON lines
    */
   splitJsonLines(content) {
     const lines = [];
@@ -5149,16 +5208,16 @@ class FileHandler {
     await fs.promises.appendFile(this.file, data);
   }
 
-  /**
-   * Check if data appears to be binary (always false since we only use JSON now)
+  /**
+   * Check if data appears to be binary (always false since we only use JSON now)
    */
   isBinaryData(data) {
     // All data is now JSON format
     return false;
   }
 
-  /**
-   * Check if file is binary (always false since we only use JSON now)
+  /**
+   * Check if file is binary (always false since we only use JSON now)
    */
   async isBinaryFile() {
     // All files are now JSON format
@@ -5215,12 +5274,12 @@ class FileHandler {
     });
   }
 
-  /**
-   * Read records with streaming using readline
-   * @param {Object} criteria - Filter criteria
-   * @param {Object} options - Options (limit, skip)
-   * @param {Function} matchesCriteria - Function to check if record matches criteria
-   * @returns {Promise<Array>} - Array of records
+  /**
+   * Read records with streaming using readline
+   * @param {Object} criteria - Filter criteria
+   * @param {Object} options - Options (limit, skip)
+   * @param {Function} matchesCriteria - Function to check if record matches criteria
+   * @returns {Promise<Array>} - Array of records
    */
   async readWithStreaming(criteria, options = {}, matchesCriteria, serializer = null) {
     // CRITICAL: Always use file mutex to prevent concurrent file operations
@@ -5389,12 +5448,12 @@ class FileHandler {
     }
   }
 
-  /**
-   * Count records with streaming
-   * @param {Object} criteria - Filter criteria
-   * @param {Object} options - Options (limit)
-   * @param {Function} matchesCriteria - Function to check if record matches criteria
-   * @returns {Promise<number>} - Number of records
+  /**
+   * Count records with streaming
+   * @param {Object} criteria - Filter criteria
+   * @param {Object} options - Options (limit)
+   * @param {Function} matchesCriteria - Function to check if record matches criteria
+   * @returns {Promise<number>} - Number of records
    */
   async countWithStreaming(criteria, options = {}, matchesCriteria, serializer = null) {
     const {
@@ -5459,9 +5518,9 @@ class FileHandler {
     }
   }
 
-  /**
-   * Get file statistics
-   * @returns {Promise<Object>} - File statistics
+  /**
+   * Get file statistics
+   * @returns {Promise<Object>} - File statistics
    */
   async getFileStats() {
     try {
@@ -5478,9 +5537,9 @@ class FileHandler {
     }
   }
 
-  /**
-   * Count lines in file
-   * @returns {Promise<number>} - Number of lines
+  /**
+   * Count lines in file
+   * @returns {Promise<number>} - Number of lines
    */
   async countLines() {
     let lineCount = 0;
@@ -5568,10 +5627,10 @@ class FileHandler {
     }
   }
 
-  /**
-   * Optimized batch write operation (OPTIMIZATION)
-   * @param {Array} dataChunks - Array of data chunks to write
-   * @param {boolean} append - Whether to append or overwrite
+  /**
+   * Optimized batch write operation (OPTIMIZATION)
+   * @param {Array} dataChunks - Array of data chunks to write
+   * @param {boolean} append - Whether to append or overwrite
    */
   async writeBatch(dataChunks, append = false) {
     if (!dataChunks || !dataChunks.length) return;
@@ -5594,10 +5653,10 @@ class FileHandler {
     }
   }
 
-  /**
-   * OPTIMIZATION: Streaming write for multiple chunks
-   * @param {Array} dataChunks - Array of data chunks to write
-   * @param {boolean} append - Whether to append or overwrite
+  /**
+   * OPTIMIZATION: Streaming write for multiple chunks
+   * @param {Array} dataChunks - Array of data chunks to write
+   * @param {boolean} append - Whether to append or overwrite
    */
   async _writeBatchStreaming(dataChunks, append = false) {
     // OPTIMIZATION: Use createWriteStream for better performance
@@ -5628,9 +5687,9 @@ class FileHandler {
     });
   }
 
-  /**
-   * Optimized append operation for single data chunk (OPTIMIZATION)
-   * @param {string|Buffer} data - Data to append
+  /**
+   * Optimized append operation for single data chunk (OPTIMIZATION)
+   * @param {string|Buffer} data - Data to append
    */
   async appendOptimized(data) {
     const release = this.fileMutex ? await this.fileMutex.acquire() : () => {};
@@ -5642,9 +5701,9 @@ class FileHandler {
     }
   }
 
-  /**
-   * Windows-specific retry logic for fs.promises.writeFile operations
-   * Based on node-graceful-fs workarounds for EPERM issues
+  /**
+   * Windows-specific retry logic for fs.promises.writeFile operations
+   * Based on node-graceful-fs workarounds for EPERM issues
    */
   async _writeFileWithRetry(filePath, data, maxRetries = 3) {
     const isWindows = process.platform === 'win32';
@@ -5680,9 +5739,9 @@ class FileHandler {
     }
   }
 
-  /**
-   * Windows-specific retry logic for file operations
-   * Based on node-graceful-fs workarounds for EPERM issues
+  /**
+   * Windows-specific retry logic for file operations
+   * Based on node-graceful-fs workarounds for EPERM issues
    */
   async _writeWithRetry(data, maxRetries = 3) {
     const isWindows = process.platform === 'win32';
@@ -5748,11 +5807,11 @@ class FileHandler {
     }
   }
 
-  /**
-   * Read specific lines from the file using line numbers
-   * This is optimized for partial reads when using indexed queries
-   * @param {number[]} lineNumbers - Array of line numbers to read (1-based)
-   * @returns {Promise<string>} - Content of the specified lines
+  /**
+   * Read specific lines from the file using line numbers
+   * This is optimized for partial reads when using indexed queries
+   * @param {number[]} lineNumbers - Array of line numbers to read (1-based)
+   * @returns {Promise<string>} - Content of the specified lines
    */
   async readSpecificLines(lineNumbers) {
     if (!lineNumbers || lineNumbers.length === 0) {
@@ -5822,15 +5881,15 @@ class FileHandler {
   }
 }
 
-/**
- * QueryManager - Handles all query operations and strategies
- * 
- * Responsibilities:
- * - find(), findOne(), count(), query()
- * - findWithStreaming(), findWithIndexed()
- * - matchesCriteria(), extractQueryFields()
- * - Query strategies (INDEXED vs STREAMING)
- * - Result estimation
+/**
+ * QueryManager - Handles all query operations and strategies
+ * 
+ * Responsibilities:
+ * - find(), findOne(), count(), query()
+ * - findWithStreaming(), findWithIndexed()
+ * - matchesCriteria(), extractQueryFields()
+ * - Query strategies (INDEXED vs STREAMING)
+ * - Result estimation
  */
 
 class QueryManager {
@@ -5849,11 +5908,11 @@ class QueryManager {
     };
   }
 
-  /**
-   * Main find method with strategy selection
-   * @param {Object} criteria - Query criteria
-   * @param {Object} options - Query options
-   * @returns {Promise<Array>} - Query results
+  /**
+   * Main find method with strategy selection
+   * @param {Object} criteria - Query criteria
+   * @param {Object} options - Query options
+   * @returns {Promise<Array>} - Query results
    */
   async find(criteria, options = {}) {
     if (this.database.destroyed) throw new Error('Database is destroyed');
@@ -5902,11 +5961,11 @@ class QueryManager {
     }
   }
 
-  /**
-   * Find one record
-   * @param {Object} criteria - Query criteria
-   * @param {Object} options - Query options
-   * @returns {Promise<Object|null>} - First matching record or null
+  /**
+   * Find one record
+   * @param {Object} criteria - Query criteria
+   * @param {Object} options - Query options
+   * @returns {Promise<Object|null>} - First matching record or null
    */
   async findOne(criteria, options = {}) {
     if (this.database.destroyed) throw new Error('Database is destroyed');
@@ -5957,11 +6016,11 @@ class QueryManager {
     }
   }
 
-  /**
-   * Count records matching criteria
-   * @param {Object} criteria - Query criteria
-   * @param {Object} options - Query options
-   * @returns {Promise<number>} - Count of matching records
+  /**
+   * Count records matching criteria
+   * @param {Object} criteria - Query criteria
+   * @param {Object} options - Query options
+   * @returns {Promise<number>} - Count of matching records
    */
   async count(criteria, options = {}) {
     if (this.database.destroyed) throw new Error('Database is destroyed');
@@ -5985,7 +6044,18 @@ class QueryManager {
       const results = await this.findWithStreaming(criteria, options);
       count = results.length;
     } else {
-      // OPTIMIZATION: For indexed strategy, use indexManager.query().size directly
+      try {
+        await this.database._ensureLazyIndexLoaded();
+      } catch (error) {
+        if (this.opts.debugMode) {
+          console.log('⚠️ _ensureLazyIndexLoaded failed in count, falling back to streaming', error.message || error);
+        }
+        const streamingResults = await this.findWithStreaming(criteria, {
+          ...options,
+          forceFullScan: true
+        });
+        return streamingResults.length;
+      }
       // This avoids reading actual records from the file - much faster!
       const lineNumbers = this.indexManager.query(criteria, options);
       if (lineNumbers.size === 0) {
@@ -6038,21 +6108,21 @@ class QueryManager {
     return count;
   }
 
-  /**
-   * Compatibility method that redirects to find
-   * @param {Object} criteria - Query criteria
-   * @param {Object} options - Query options
-   * @returns {Promise<Array>} - Query results
+  /**
+   * Compatibility method that redirects to find
+   * @param {Object} criteria - Query criteria
+   * @param {Object} options - Query options
+   * @returns {Promise<Array>} - Query results
    */
   async query(criteria, options = {}) {
     return this.find(criteria, options);
   }
 
-  /**
-   * Find using streaming strategy with pre-filtering optimization
-   * @param {Object} criteria - Query criteria
-   * @param {Object} options - Query options
-   * @returns {Promise<Array>} - Query results
+  /**
+   * Find using streaming strategy with pre-filtering optimization
+   * @param {Object} criteria - Query criteria
+   * @param {Object} options - Query options
+   * @returns {Promise<Array>} - Query results
    */
   async findWithStreaming(criteria, options = {}) {
     const streamingOptions = {
@@ -6071,6 +6141,21 @@ class QueryManager {
       // OPTIMIZATION: Try to use indices for pre-filtering when possible
       const indexableFields = this._getIndexableFields(criteria);
       if (indexableFields.length > 0) {
+        try {
+          await this.database._ensureLazyIndexLoaded();
+        } catch (error) {
+          if (this.opts.debugMode) {
+            console.log('⚠️ _ensureLazyIndexLoaded failed, falling back to full streaming', error.message || error);
+          }
+          return this._streamAllRecords(criteria, streamingOptions);
+        }
+        const usableIndexableFields = indexableFields.filter(field => this.indexManager.hasUsableIndexData(field));
+        if (usableIndexableFields.length !== indexableFields.length) {
+          if (this.opts.debugMode) {
+            console.log('🌊 Falling back to full streaming because some indexed fields lack usable index data');
+          }
+          return this._streamAllRecords(criteria, streamingOptions);
+        }
         if (this.opts.debugMode) {
           console.log(`🌊 Using pre-filtered streaming with ${indexableFields.length} indexable fields`);
         }
@@ -6090,10 +6175,10 @@ class QueryManager {
     return this._streamAllRecords(criteria, streamingOptions);
   }
 
-  /**
-   * Get indexable fields from criteria
-   * @param {Object} criteria - Query criteria
-   * @returns {Array} - Array of indexable field names
+  /**
+   * Get indexable fields from criteria
+   * @param {Object} criteria - Query criteria
+   * @returns {Array} - Array of indexable field names
    */
   _getIndexableFields(criteria) {
     const indexableFields = [];
@@ -6123,10 +6208,10 @@ class QueryManager {
     return [...new Set(indexableFields)]; // Remove duplicates
   }
 
-  /**
-   * Extract indexable criteria for pre-filtering
-   * @param {Object} criteria - Full query criteria
-   * @returns {Object} - Criteria with only indexable fields
+  /**
+   * Extract indexable criteria for pre-filtering
+   * @param {Object} criteria - Full query criteria
+   * @returns {Object} - Criteria with only indexable fields
    */
   _extractIndexableCriteria(criteria) {
     if (!criteria || typeof criteria !== 'object') {
@@ -6171,9 +6256,9 @@ class QueryManager {
     return indexableCriteria;
   }
 
-  /**
-   * Determine whether the database currently has any records (persisted or pending)
-   * @returns {boolean}
+  /**
+   * Determine whether the database currently has any records (persisted or pending)
+   * @returns {boolean}
    */
   _hasAnyRecords() {
     if (!this.database) {
@@ -6191,11 +6276,11 @@ class QueryManager {
     return false;
   }
 
-  /**
-   * Extract all indexed fields referenced in the criteria
-   * @param {Object} criteria
-   * @param {Set<string>} accumulator
-   * @returns {Array<string>}
+  /**
+   * Extract all indexed fields referenced in the criteria
+   * @param {Object} criteria
+   * @param {Set<string>} accumulator
+   * @returns {Array<string>}
    */
   _extractIndexedFields(criteria, accumulator = new Set()) {
     if (!criteria) {
@@ -6225,10 +6310,10 @@ class QueryManager {
     return Array.from(accumulator);
   }
 
-  /**
-   * Identify indexed fields present in criteria whose index data is missing
-   * @param {Object} criteria
-   * @returns {Array<string>}
+  /**
+   * Identify indexed fields present in criteria whose index data is missing
+   * @param {Object} criteria
+   * @returns {Array<string>}
    */
   _getIndexedFieldsWithMissingData(criteria) {
     if (!this.indexManager || !criteria) {
@@ -6247,12 +6332,12 @@ class QueryManager {
     return missing;
   }
 
-  /**
-   * OPTIMIZATION 4: Stream pre-filtered records using line numbers from indices with partial index optimization
-   * @param {Set} preFilteredLines - Line numbers from index query
-   * @param {Object} criteria - Full query criteria
-   * @param {Object} options - Query options
-   * @returns {Promise<Array>} - Query results
+  /**
+   * OPTIMIZATION 4: Stream pre-filtered records using line numbers from indices with partial index optimization
+   * @param {Set} preFilteredLines - Line numbers from index query
+   * @param {Object} criteria - Full query criteria
+   * @param {Object} options - Query options
+   * @returns {Promise<Array>} - Query results
    */
   async _streamPreFilteredRecords(preFilteredLines, criteria, options = {}) {
     if (preFilteredLines.size === 0) {
@@ -6270,71 +6355,95 @@ class QueryManager {
     for (let i = 0; i < lineNumbers.length; i += batchSize) {
       batches.push(lineNumbers.slice(i, i + batchSize));
     }
-    for (const batch of batches) {
-      // OPTIMIZATION: Use ranges instead of reading entire file
-      const ranges = this.database.getRanges(batch);
-      const groupedRanges = await this.fileHandler.groupedRanges(ranges);
-      const fd = await fs.promises.open(this.fileHandler.file, 'r');
-      try {
-        for (const groupedRange of groupedRanges) {
-          var _iteratorAbruptCompletion = false;
-          var _didIteratorError = false;
-          var _iteratorError;
-          try {
-            for (var _iterator = _asyncIterator(this.fileHandler.readGroupedRange(groupedRange, fd)), _step; _iteratorAbruptCompletion = !(_step = await _iterator.next()).done; _iteratorAbruptCompletion = false) {
-              const row = _step.value;
-              {
-                if (row.line && row.line.trim()) {
-                  try {
-                    // CRITICAL FIX: Use serializer.deserialize instead of JSON.parse to handle array format
-                    const record = this.database.serializer.deserialize(row.line);
-
-                    // OPTIMIZATION 4: Use optimized criteria matching for pre-filtered records
-                    if (this._matchesCriteriaOptimized(record, criteria, options)) {
-                      // SPACE OPTIMIZATION: Restore term IDs to terms for user (unless disabled)
-                      const recordWithTerms = options.restoreTerms !== false ? this.database.restoreTermIdsAfterDeserialization(record) : record;
-                      results.push(recordWithTerms);
-
-                      // Check limit
-                      if (options.limit && results.length >= options.limit) {
-                        return this._applyOrdering(results, options);
+    const persistedCount = Array.isArray(this.database.offsets) ? this.database.offsets.length : 0;
+    const fileLineNumbers = [];
+    const writeBufferLineNumbers = [];
+    for (const lineNumber of lineNumbers) {
+      if (lineNumber >= persistedCount) {
+        writeBufferLineNumbers.push(lineNumber);
+      } else {
+        fileLineNumbers.push(lineNumber);
+      }
+    }
+    if (fileLineNumbers.length > 0) {
+      const fileBatches = [];
+      for (let i = 0; i < fileLineNumbers.length; i += batchSize) {
+        fileBatches.push(fileLineNumbers.slice(i, i + batchSize));
+      }
+      for (const batch of fileBatches) {
+        // OPTIMIZATION: Use ranges instead of reading entire file
+        const ranges = this.database.getRanges(batch);
+        const groupedRanges = await this.fileHandler.groupedRanges(ranges);
+        const fd = await fs.promises.open(this.fileHandler.file, 'r');
+        try {
+          for (const groupedRange of groupedRanges) {
+            var _iteratorAbruptCompletion = false;
+            var _didIteratorError = false;
+            var _iteratorError;
+            try {
+              for (var _iterator = _asyncIterator(this.fileHandler.readGroupedRange(groupedRange, fd)), _step; _iteratorAbruptCompletion = !(_step = await _iterator.next()).done; _iteratorAbruptCompletion = false) {
+                const row = _step.value;
+                {
+                  if (row.line && row.line.trim()) {
+                    try {
+                      const record = this.database.serializer.deserialize(row.line);
+                      if (this._matchesCriteriaOptimized(record, criteria, options)) {
+                        const recordWithTerms = options.restoreTerms !== false ? this.database.restoreTermIdsAfterDeserialization(record) : record;
+                        results.push(recordWithTerms);
+                        if (options.limit && results.length >= options.limit) {
+                          return this._applyOrdering(results, options);
+                        }
                       }
+                    } catch (error) {
+                      continue;
                     }
-                  } catch (error) {
-                    // Skip invalid lines
-                    continue;
                   }
                 }
               }
-            }
-          } catch (err) {
-            _didIteratorError = true;
-            _iteratorError = err;
-          } finally {
-            try {
-              if (_iteratorAbruptCompletion && _iterator.return != null) {
-                await _iterator.return();
-              }
+            } catch (err) {
+              _didIteratorError = true;
+              _iteratorError = err;
             } finally {
-              if (_didIteratorError) {
-                throw _iteratorError;
+              try {
+                if (_iteratorAbruptCompletion && _iterator.return != null) {
+                  await _iterator.return();
+                }
+              } finally {
+                if (_didIteratorError) {
+                  throw _iteratorError;
+                }
               }
             }
           }
+        } finally {
+          await fd.close();
+        }
+      }
+    }
+    if (writeBufferLineNumbers.length > 0) {
+      writeBufferLineNumbers.sort((a, b) => a - b);
+      for (const lineNumber of writeBufferLineNumbers) {
+        const writeBufferIndex = lineNumber - persistedCount;
+        const record = this.database.writeBuffer[writeBufferIndex];
+        if (!record) continue;
+        if (this._matchesCriteriaOptimized(record, criteria, options)) {
+          const recordWithTerms = options.restoreTerms !== false ? this.database.restoreTermIdsAfterDeserialization(record) : record;
+          results.push(recordWithTerms);
+          if (options.limit && results.length >= options.limit) {
+            return this._applyOrdering(results, options);
+          }
         }
-      } finally {
-        await fd.close();
       }
     }
     return this._applyOrdering(results, options);
   }
 
-  /**
-   * OPTIMIZATION 4: Optimized criteria matching for pre-filtered records
-   * @param {Object} record - Record to check
-   * @param {Object} criteria - Filter criteria
-   * @param {Object} options - Query options
-   * @returns {boolean} - True if matches
+  /**
+   * OPTIMIZATION 4: Optimized criteria matching for pre-filtered records
+   * @param {Object} record - Record to check
+   * @param {Object} criteria - Filter criteria
+   * @param {Object} options - Query options
+   * @returns {boolean} - True if matches
    */
   _matchesCriteriaOptimized(record, criteria, options = {}) {
     if (!criteria || Object.keys(criteria).length === 0) {
@@ -6393,11 +6502,11 @@ class QueryManager {
     return true;
   }
 
-  /**
-   * OPTIMIZATION 4: Apply ordering to results
-   * @param {Array} results - Results to order
-   * @param {Object} options - Query options
-   * @returns {Array} - Ordered results
+  /**
+   * OPTIMIZATION 4: Apply ordering to results
+   * @param {Array} results - Results to order
+   * @param {Object} options - Query options
+   * @returns {Array} - Ordered results
    */
   _applyOrdering(results, options) {
     if (options.orderBy) {
@@ -6411,11 +6520,11 @@ class QueryManager {
     return results;
   }
 
-  /**
-   * Stream all records (fallback method)
-   * @param {Object} criteria - Query criteria
-   * @param {Object} options - Query options
-   * @returns {Promise<Array>} - Query results
+  /**
+   * Stream all records (fallback method)
+   * @param {Object} criteria - Query criteria
+   * @param {Object} options - Query options
+   * @returns {Promise<Array>} - Query results
    */
   async _streamAllRecords(criteria, options = {}) {
     const memoryLimit = options.limit || undefined;
@@ -6442,16 +6551,27 @@ class QueryManager {
     return resultsWithTerms;
   }
 
-  /**
-   * Find using indexed search strategy with real streaming
-   * @param {Object} criteria - Query criteria
-   * @param {Object} options - Query options
-   * @returns {Promise<Array>} - Query results
+  /**
+   * Find using indexed search strategy with real streaming
+   * @param {Object} criteria - Query criteria
+   * @param {Object} options - Query options
+   * @returns {Promise<Array>} - Query results
    */
   async findWithIndexed(criteria, options = {}) {
     if (this.opts.debugMode) {
       console.log('📊 Using indexed strategy with real streaming');
     }
+    try {
+      await this.database._ensureLazyIndexLoaded();
+    } catch (error) {
+      if (this.opts.debugMode) {
+        console.log('⚠️ _ensureLazyIndexLoaded failed, falling back to full streaming', error.message || error);
+      }
+      return this.findWithStreaming(criteria, {
+        ...options,
+        forceFullScan: true
+      });
+    }
     let results = [];
     const limit = options.limit; // No default limit - return all results unless explicitly limited
 
@@ -6598,12 +6718,12 @@ class QueryManager {
     return results;
   }
 
-  /**
-   * Check if a record matches criteria
-   * @param {Object} record - Record to check
-   * @param {Object} criteria - Filter criteria
-   * @param {Object} options - Query options (for caseInsensitive, etc.)
-   * @returns {boolean} - True if matches
+  /**
+   * Check if a record matches criteria
+   * @param {Object} record - Record to check
+   * @param {Object} criteria - Filter criteria
+   * @param {Object} options - Query options (for caseInsensitive, etc.)
+   * @returns {boolean} - True if matches
    */
   matchesCriteria(record, criteria, options = {}) {
     if (!criteria || Object.keys(criteria).length === 0) {
@@ -6672,13 +6792,13 @@ class QueryManager {
     return true;
   }
 
-  /**
-   * Check if a field matches a condition
-   * @param {Object} record - Record to check
-   * @param {string} field - Field name
-   * @param {*} condition - Condition to match
-   * @param {Object} options - Query options
-   * @returns {boolean} - True if matches
+  /**
+   * Check if a field matches a condition
+   * @param {Object} record - Record to check
+   * @param {string} field - Field name
+   * @param {*} condition - Condition to match
+   * @param {Object} options - Query options
+   * @returns {boolean} - True if matches
    */
   matchesFieldCondition(record, field, condition, options = {}) {
     const value = record[field];
@@ -6753,13 +6873,13 @@ class QueryManager {
     return value === condition;
   }
 
-  /**
-   * Check if a value matches an operator condition
-   * @param {*} value - Value to check
-   * @param {string} operator - Operator
-   * @param {*} operatorValue - Operator value
-   * @param {Object} options - Query options
-   * @returns {boolean} - True if matches
+  /**
+   * Check if a value matches an operator condition
+   * @param {*} value - Value to check
+   * @param {string} operator - Operator
+   * @param {*} operatorValue - Operator value
+   * @param {Object} options - Query options
+   * @returns {boolean} - True if matches
    */
   matchesOperator(value, operator, operatorValue, options = {}) {
     switch (operator) {
@@ -6825,10 +6945,10 @@ class QueryManager {
     }
   }
 
-  /**
-   * Preprocess query to handle array field syntax automatically
-   * @param {Object} criteria - Query criteria
-   * @returns {Object} - Processed criteria
+  /**
+   * Preprocess query to handle array field syntax automatically
+   * @param {Object} criteria - Query criteria
+   * @returns {Object} - Processed criteria
    */
   preprocessQuery(criteria) {
     if (!criteria || typeof criteria !== 'object') {
@@ -6903,11 +7023,11 @@ class QueryManager {
     return processed;
   }
 
-  /**
-   * Determine which query strategy to use
-   * @param {Object} criteria - Query criteria
-   * @param {Object} options - Query options
-   * @returns {string} - 'streaming' or 'indexed'
+  /**
+   * Determine which query strategy to use
+   * @param {Object} criteria - Query criteria
+   * @param {Object} options - Query options
+   * @returns {string} - 'streaming' or 'indexed'
    */
   shouldUseStreaming(criteria, options = {}) {
     const {
@@ -7062,7 +7182,7 @@ class QueryManager {
 
     // OPTIMIZATION 2: Hybrid strategy - use pre-filtered streaming when index is empty
     const indexData = this.indexManager.index.data || {};
-    const hasIndexData = Object.keys(indexData).length > 0;
+    const hasIndexData = Object.keys(indexData).some(field => this.indexManager.hasUsableIndexData(field));
     if (!hasIndexData) {
       // Check if we can use pre-filtered streaming with term mapping
       if (this.opts.termMapping && this._canUsePreFilteredStreaming(criteria)) {
@@ -7092,11 +7212,11 @@ class QueryManager {
     return 'indexed';
   }
 
-  /**
-   * Estimate number of results for a query
-   * @param {Object} criteria - Query criteria
-   * @param {number} totalRecords - Total records in database
-   * @returns {number} - Estimated results
+  /**
+   * Estimate number of results for a query
+   * @param {Object} criteria - Query criteria
+   * @param {number} totalRecords - Total records in database
+   * @returns {number} - Estimated results
    */
   estimateQueryResults(criteria, totalRecords) {
     // If database is empty, return 0
@@ -7152,11 +7272,11 @@ class QueryManager {
     return minResults === Infinity ? 0 : minResults;
   }
 
-  /**
-   * Estimate results for $all operator
-   * @param {Object} fieldIndex - Field index
-   * @param {Array} values - Values to match
-   * @returns {number} - Estimated results
+  /**
+   * Estimate results for $all operator
+   * @param {Object} fieldIndex - Field index
+   * @param {Array} values - Values to match
+   * @returns {number} - Estimated results
    */
   estimateAllOperator(fieldIndex, values) {
     if (!Array.isArray(values) || values.length === 0) {
@@ -7171,13 +7291,13 @@ class QueryManager {
     return minCount === Infinity ? 0 : minCount;
   }
 
-  /**
-   * Estimate results for operators
-   * @param {Object} fieldIndex - Field index
-   * @param {string} operator - Operator
-   * @param {*} value - Value
-   * @param {number} totalRecords - Total records
-   * @returns {number} - Estimated results
+  /**
+   * Estimate results for operators
+   * @param {Object} fieldIndex - Field index
+   * @param {string} operator - Operator
+   * @param {*} value - Value
+   * @param {number} totalRecords - Total records
+   * @returns {number} - Estimated results
    */
   estimateOperatorResults(fieldIndex, operator, value, totalRecords) {
     // This is a simplified estimation - in practice, you might want more sophisticated logic
@@ -7208,10 +7328,10 @@ class QueryManager {
     return 0;
   }
 
-  /**
-   * Validate strict query mode
-   * @param {Object} criteria - Query criteria
-   * @param {Object} options - Query options
+  /**
+   * Validate strict query mode
+   * @param {Object} criteria - Query criteria
+   * @param {Object} options - Query options
    */
   validateStrictQuery(criteria, options = {}) {
     // Allow bypassing strict mode validation with allowNonIndexed option
@@ -7278,10 +7398,10 @@ class QueryManager {
     }
   }
 
-  /**
-   * Update average time for performance tracking
-   * @param {string} type - Type of operation ('streaming' or 'indexed')
-   * @param {number} time - Time taken
+  /**
+   * Update average time for performance tracking
+   * @param {string} type - Type of operation ('streaming' or 'indexed')
+   * @param {number} time - Time taken
    */
   updateAverageTime(type, time) {
     if (!this.usageStats[`${type}AverageTime`]) {
@@ -7294,10 +7414,10 @@ class QueryManager {
     this.usageStats[`${type}AverageTime`] = (currentAverage * (count - 1) + time) / count;
   }
 
-  /**
-   * OPTIMIZATION 2: Check if we can use pre-filtered streaming with term mapping
-   * @param {Object} criteria - Query criteria
-   * @returns {boolean} - True if pre-filtered streaming can be used
+  /**
+   * OPTIMIZATION 2: Check if we can use pre-filtered streaming with term mapping
+   * @param {Object} criteria - Query criteria
+   * @returns {boolean} - True if pre-filtered streaming can be used
    */
   _canUsePreFilteredStreaming(criteria) {
     if (!criteria || typeof criteria !== 'object') {
@@ -8213,14 +8333,14 @@ class StreamingProcessor extends events.EventEmitter {
   }
 }
 
-/**
- * TermManager - Manages term-to-ID mapping for efficient storage
- * 
- * Responsibilities:
- * - Map terms to numeric IDs for space efficiency
- * - Track term usage counts for cleanup
- * - Load/save terms from/to index file
- * - Clean up orphaned terms
+/**
+ * TermManager - Manages term-to-ID mapping for efficient storage
+ * 
+ * Responsibilities:
+ * - Map terms to numeric IDs for space efficiency
+ * - Track term usage counts for cleanup
+ * - Load/save terms from/to index file
+ * - Clean up orphaned terms
  */
 class TermManager {
   constructor() {
@@ -8230,10 +8350,10 @@ class TermManager {
     this.nextId = 1;
   }
 
-  /**
-   * Get ID for a term (create if doesn't exist)
-   * @param {string} term - Term to get ID for
-   * @returns {number} - Numeric ID for the term
+  /**
+   * Get ID for a term (create if doesn't exist)
+   * @param {string} term - Term to get ID for
+   * @returns {number} - Numeric ID for the term
    */
   getTermId(term) {
     if (this.termToId.has(term)) {
@@ -8248,12 +8368,12 @@ class TermManager {
     return id;
   }
 
-  /**
-   * Get term ID without incrementing count (for IndexManager use)
-   * @param {string} term - Term to get ID for
-   * @returns {number|undefined} - Numeric ID for the term, or undefined if not found
-   * CRITICAL: Does NOT create new IDs - only returns existing ones
-   * This prevents creating invalid term IDs during queries when terms haven't been loaded yet
+  /**
+   * Get term ID without incrementing count (for IndexManager use)
+   * @param {string} term - Term to get ID for
+   * @returns {number|undefined} - Numeric ID for the term, or undefined if not found
+   * CRITICAL: Does NOT create new IDs - only returns existing ones
+   * This prevents creating invalid term IDs during queries when terms haven't been loaded yet
    */
   getTermIdWithoutIncrement(term) {
     if (this.termToId.has(term)) {
@@ -8266,19 +8386,19 @@ class TermManager {
     return undefined;
   }
 
-  /**
-   * Get term by ID
-   * @param {number} id - Numeric ID
-   * @returns {string|null} - Term or null if not found
+  /**
+   * Get term by ID
+   * @param {number} id - Numeric ID
+   * @returns {string|null} - Term or null if not found
    */
   getTerm(id) {
     return this.idToTerm.get(id) || null;
   }
 
-  /**
-   * Bulk get term IDs for multiple terms (optimized for performance)
-   * @param {string[]} terms - Array of terms to get IDs for
-   * @returns {number[]} - Array of term IDs in the same order
+  /**
+   * Bulk get term IDs for multiple terms (optimized for performance)
+   * @param {string[]} terms - Array of terms to get IDs for
+   * @returns {number[]} - Array of term IDs in the same order
    */
   bulkGetTermIds(terms) {
     if (!Array.isArray(terms) || terms.length === 0) {
@@ -8304,9 +8424,9 @@ class TermManager {
     return termIds;
   }
 
-  /**
-   * Load terms from file data
-   * @param {Object} termsData - Terms data from file
+  /**
+   * Load terms from file data
+   * @param {Object} termsData - Terms data from file
    */
   loadTerms(termsData) {
     if (!termsData || typeof termsData !== 'object') {
@@ -8324,9 +8444,9 @@ class TermManager {
     }
   }
 
-  /**
-   * Save terms to file format
-   * @returns {Object} - Terms data for file
+  /**
+   * Save terms to file format
+   * @returns {Object} - Terms data for file
    */
   saveTerms() {
     const termsData = {};
@@ -8336,11 +8456,11 @@ class TermManager {
     return termsData;
   }
 
-  /**
-   * Clean up orphaned terms (terms with count 0)
-   * @param {boolean} forceCleanup - Force cleanup even if conditions not met
-   * @param {Object} options - Cleanup options
-   * @returns {number} - Number of orphaned terms removed
+  /**
+   * Clean up orphaned terms (terms with count 0)
+   * @param {boolean} forceCleanup - Force cleanup even if conditions not met
+   * @param {Object} options - Cleanup options
+   * @returns {number} - Number of orphaned terms removed
    */
   cleanupOrphanedTerms(forceCleanup = false, options = {}) {
     const {
@@ -8398,9 +8518,9 @@ class TermManager {
     return orphanedIds.length;
   }
 
-  /**
-   * Check if system is safe for cleanup operations
-   * @returns {boolean} - True if system is safe for cleanup
+  /**
+   * Check if system is safe for cleanup operations
+   * @returns {boolean} - True if system is safe for cleanup
    */
   isSystemSafe() {
     // This method should be overridden by the database instance
@@ -8408,10 +8528,10 @@ class TermManager {
     return true; // Default to safe for backward compatibility
   }
 
-  /**
-   * Perform intelligent automatic cleanup
-   * @param {Object} options - Cleanup options
-   * @returns {number} - Number of orphaned terms removed
+  /**
+   * Perform intelligent automatic cleanup
+   * @param {Object} options - Cleanup options
+   * @returns {number} - Number of orphaned terms removed
    */
   performIntelligentCleanup(options = {}) {
     return this.cleanupOrphanedTerms(false, {
@@ -8425,27 +8545,27 @@ class TermManager {
     });
   }
 
-  /**
-   * Decrement term count (when term is removed from index)
-   * @param {number} termId - Term ID to decrement
+  /**
+   * Decrement term count (when term is removed from index)
+   * @param {number} termId - Term ID to decrement
    */
   decrementTermCount(termId) {
     const count = this.termCounts.get(termId) || 0;
     this.termCounts.set(termId, Math.max(0, count - 1));
   }
 
-  /**
-   * Increment term count (when term is added to index)
-   * @param {number} termId - Term ID to increment
+  /**
+   * Increment term count (when term is added to index)
+   * @param {number} termId - Term ID to increment
    */
   incrementTermCount(termId) {
     const count = this.termCounts.get(termId) || 0;
     this.termCounts.set(termId, count + 1);
   }
 
-  /**
-   * Get statistics about terms
-   * @returns {Object} - Term statistics
+  /**
+   * Get statistics about terms
+   * @returns {Object} - Term statistics
    */
   getStats() {
     return {
@@ -8455,34 +8575,34 @@ class TermManager {
     };
   }
 
-  /**
-   * Check if a term exists
-   * @param {string} term - Term to check
-   * @returns {boolean} - True if term exists
+  /**
+   * Check if a term exists
+   * @param {string} term - Term to check
+   * @returns {boolean} - True if term exists
    */
   hasTerm(term) {
     return this.termToId.has(term);
   }
 
-  /**
-   * Get all terms
-   * @returns {Array} - Array of all terms
+  /**
+   * Get all terms
+   * @returns {Array} - Array of all terms
    */
   getAllTerms() {
     return Array.from(this.termToId.keys());
   }
 
-  /**
-   * Get all term IDs
-   * @returns {Array} - Array of all term IDs
+  /**
+   * Get all term IDs
+   * @returns {Array} - Array of all term IDs
    */
   getAllTermIds() {
     return Array.from(this.idToTerm.keys());
   }
 
-  /**
-   * Get statistics about term mapping
-   * @returns {Object} - Statistics object
+  /**
+   * Get statistics about term mapping
+   * @returns {Object} - Statistics object
    */
   getStatistics() {
     return {
@@ -8494,9 +8614,9 @@ class TermManager {
   }
 }
 
-/**
- * IterateEntry class for intuitive API with automatic change detection
- * Uses native JavaScript setters for maximum performance
+/**
+ * IterateEntry class for intuitive API with automatic change detection
+ * Uses native JavaScript setters for maximum performance
  */
 class IterateEntry {
   constructor(entry, originalRecord) {
@@ -8549,8 +8669,8 @@ class IterateEntry {
   }
 }
 
-/**
- * InsertSession - Simple batch insertion without memory duplication
+/**
+ * InsertSession - Simple batch insertion without memory duplication
  */
 class InsertSession {
   constructor(database, sessionOptions = {}) {
@@ -8731,8 +8851,8 @@ class InsertSession {
     return insertedCount;
   }
 
-  /**
-   * Wait for this session's operations to complete
+  /**
+   * Wait for this session's operations to complete
    */
   async waitForOperations(maxWaitTime = null) {
     const startTime = Date.now();
@@ -8750,15 +8870,15 @@ class InsertSession {
     return true;
   }
 
-  /**
-   * Check if this session has pending operations
+  /**
+   * Check if this session has pending operations
    */
   hasPendingOperations() {
     return this.pendingAutoFlushes.size > 0 || this.flushing || this.batches.length > 0 || this.currentBatch.length > 0;
   }
 
-  /**
-   * Destroy this session and unregister it
+  /**
+   * Destroy this session and unregister it
    */
   destroy() {
     // Unregister from database
@@ -8773,16 +8893,16 @@ class InsertSession {
   }
 }
 
-/**
- * JexiDB - A high-performance, in-memory database with persistence
- * 
- * Features:
- * - In-memory storage with optional persistence
- * - Advanced indexing and querying
- * - Transaction support
- * - Manual save functionality
- * - Recovery mechanisms
- * - Performance optimizations
+/**
+ * JexiDB - A high-performance, in-memory database with persistence
+ * 
+ * Features:
+ * - In-memory storage with optional persistence
+ * - Advanced indexing and querying
+ * - Transaction support
+ * - Manual save functionality
+ * - Recovery mechanisms
+ * - Performance optimizations
  */
 class Database extends events.EventEmitter {
   constructor(file, opts = {}) {
@@ -8906,8 +9026,8 @@ class Database extends events.EventEmitter {
     // Note: Validation will be done after configuration conversion in initializeManagers()
   }
 
-  /**
-   * Validate field and index configuration
+  /**
+   * Validate field and index configuration
    */
   validateIndexConfiguration() {
     // Validate fields configuration
@@ -8937,8 +9057,8 @@ class Database extends events.EventEmitter {
     }
   }
 
-  /**
-   * Validate field types
+  /**
+   * Validate field types
    */
   validateFieldTypes(fields, configType) {
     const supportedTypes = ['string', 'number', 'boolean', 'array:string', 'array:number', 'array:boolean', 'array', 'object', 'auto'];
@@ -8970,8 +9090,8 @@ class Database extends events.EventEmitter {
     }
   }
 
-  /**
-   * Validate index fields array
+  /**
+   * Validate index fields array
    */
   validateIndexFields(indexFields) {
     if (!this.opts.fields) {
@@ -8989,8 +9109,8 @@ class Database extends events.EventEmitter {
     }
   }
 
-  /**
-   * Prepare index configuration for IndexManager
+  /**
+   * Prepare index configuration for IndexManager
    */
   prepareIndexConfiguration() {
     if (Array.isArray(this.opts.indexes)) {
@@ -9013,8 +9133,8 @@ class Database extends events.EventEmitter {
     // Legacy format (indexes as object) is already compatible
   }
 
-  /**
-   * Initialize all managers
+  /**
+   * Initialize all managers
    */
   initializeManagers() {
     // CRITICAL FIX: Prevent double initialization which corrupts term mappings
@@ -9120,9 +9240,9 @@ class Database extends events.EventEmitter {
     this.streamingProcessor = new StreamingProcessor(this.opts);
   }
 
-  /**
-   * Get term mapping fields from configuration or indexes (auto-detected)
-   * @returns {string[]} Array of field names that use term mapping
+  /**
+   * Get term mapping fields from configuration or indexes (auto-detected)
+   * @returns {string[]} Array of field names that use term mapping
    */
   getTermMappingFields() {
     // If termMappingFields is explicitly configured, use it
@@ -9142,9 +9262,9 @@ class Database extends events.EventEmitter {
     return termMappingFields;
   }
 
-  /**
-   * CRITICAL FIX: Validate database state before critical operations
-   * Prevents crashes from undefined methods and invalid states
+  /**
+   * CRITICAL FIX: Validate database state before critical operations
+   * Prevents crashes from undefined methods and invalid states
    */
   validateState() {
     if (this.destroyed) {
@@ -9171,9 +9291,9 @@ class Database extends events.EventEmitter {
     return true;
   }
 
-  /**
-   * CRITICAL FIX: Ensure file path is valid and accessible
-   * Prevents file path loss issues mentioned in crash report
+  /**
+   * CRITICAL FIX: Ensure file path is valid and accessible
+   * Prevents file path loss issues mentioned in crash report
    */
   ensureFilePath() {
     if (!this.normalizedFile) {
@@ -9182,16 +9302,16 @@ class Database extends events.EventEmitter {
     return this.normalizedFile;
   }
 
-  /**
-   * Normalize file path to ensure it ends with .jdb
+  /**
+   * Normalize file path to ensure it ends with .jdb
    */
   normalizeFilePath(file) {
     if (!file) return null;
     return file.endsWith('.jdb') ? file : `${file}.jdb`;
   }
 
-  /**
-   * Initialize the database
+  /**
+   * Initialize the database
    */
   async initialize() {
     // Check if database is destroyed first (before checking initialized)
@@ -9281,10 +9401,10 @@ class Database extends events.EventEmitter {
     }
   }
 
-  /**
-   * Validate that the database is initialized before performing operations
-   * @param {string} operation - The operation being attempted
-   * @throws {Error} If database is not initialized
+  /**
+   * Validate that the database is initialized before performing operations
+   * @param {string} operation - The operation being attempted
+   * @throws {Error} If database is not initialized
    */
   _validateInitialization(operation) {
     if (this.destroyed) {
@@ -9299,8 +9419,8 @@ class Database extends events.EventEmitter {
     }
   }
 
-  /**
-   * Clear existing database files (.jdb and .idx.jdb)
+  /**
+   * Clear existing database files (.jdb and .idx.jdb)
    */
   async clearExistingFiles() {
     if (!this.normalizedFile) return;
@@ -9341,8 +9461,8 @@ class Database extends events.EventEmitter {
     }
   }
 
-  /**
-   * Load data from file
+  /**
+   * Load data from file
    */
   async load() {
     if (!this.normalizedFile) return;
@@ -9627,9 +9747,9 @@ class Database extends events.EventEmitter {
     }
   }
 
-  /**
-   * Save data to file
-   * @param {boolean} inQueue - Whether to execute within the operation queue (default: false)
+  /**
+   * Save data to file
+   * @param {boolean} inQueue - Whether to execute within the operation queue (default: false)
    */
   async save(inQueue = false) {
     this._validateInitialization('save');
@@ -9706,8 +9826,8 @@ class Database extends events.EventEmitter {
     }
   }
 
-  /**
-   * Internal save implementation (without queue)
+  /**
+   * Internal save implementation (without queue)
    */
   async _doSave() {
     // CRITICAL FIX: Check if database is destroyed
@@ -9758,6 +9878,7 @@ class Database extends events.EventEmitter {
         const startLineNumber = this.pendingIndexUpdates[0].lineNumber;
 
         // Process index updates in batch
+        await this._ensureLazyIndexLoaded();
         await this.indexManager.addBatch(records, startLineNumber);
 
         // Clear pending updates
@@ -10282,11 +10403,11 @@ class Database extends events.EventEmitter {
     }
   }
 
-  /**
-   * Process term mapping for a record
-   * @param {Object} record - Record to process
-   * @param {boolean} isUpdate - Whether this is an update operation
-   * @param {Object} oldRecord - Original record (for updates)
+  /**
+   * Process term mapping for a record
+   * @param {Object} record - Record to process
+   * @param {boolean} isUpdate - Whether this is an update operation
+   * @param {Object} oldRecord - Original record (for updates)
    */
   processTermMapping(record, isUpdate = false, oldRecord = null) {
     const termMappingFields = this.getTermMappingFields();
@@ -10347,10 +10468,10 @@ class Database extends events.EventEmitter {
     }
   }
 
-  /**
-   * Convert terms to term IDs for serialization (SPACE OPTIMIZATION)
-   * @param {Object} record - Record to process
-   * @returns {Object} - Record with terms converted to term IDs
+  /**
+   * Convert terms to term IDs for serialization (SPACE OPTIMIZATION)
+   * @param {Object} record - Record to process
+   * @returns {Object} - Record with terms converted to term IDs
    */
   removeTermIdsForSerialization(record) {
     const termMappingFields = this.getTermMappingFields();
@@ -10376,10 +10497,10 @@ class Database extends events.EventEmitter {
     return optimizedRecord;
   }
 
-  /**
-   * Convert term IDs back to terms after deserialization (SPACE OPTIMIZATION)
-   * @param {Object} record - Record with term IDs
-   * @returns {Object} - Record with terms restored
+  /**
+   * Convert term IDs back to terms after deserialization (SPACE OPTIMIZATION)
+   * @param {Object} record - Record with term IDs
+   * @returns {Object} - Record with terms restored
    */
   restoreTermIdsAfterDeserialization(record) {
     const termMappingFields = this.getTermMappingFields();
@@ -10409,9 +10530,9 @@ class Database extends events.EventEmitter {
     return restoredRecord;
   }
 
-  /**
-   * Remove term mapping for a record
-   * @param {Object} record - Record to process
+  /**
+   * Remove term mapping for a record
+   * @param {Object} record - Record to process
    */
   removeTermMapping(record) {
     const termMappingFields = this.getTermMappingFields();
@@ -10433,10 +10554,10 @@ class Database extends events.EventEmitter {
     }
   }
 
-  /**
-   * Process term mapping for multiple records in batch (OPTIMIZATION)
-   * @param {Array} records - Records to process
-   * @returns {Array} - Processed records with term mappings
+  /**
+   * Process term mapping for multiple records in batch (OPTIMIZATION)
+   * @param {Array} records - Records to process
+   * @returns {Array} - Processed records with term mappings
    */
   processTermMappingBatch(records) {
     const termMappingFields = this.getTermMappingFields();
@@ -10488,10 +10609,10 @@ class Database extends events.EventEmitter {
     return records;
   }
 
-  /**
-   * Calculate total size of serialized records (OPTIMIZATION)
-   * @param {Array} records - Records to calculate size for
-   * @returns {number} - Total size in bytes
+  /**
+   * Calculate total size of serialized records (OPTIMIZATION)
+   * @param {Array} records - Records to calculate size for
+   * @returns {number} - Total size in bytes
    */
   calculateBatchSize(records) {
     if (!records || !records.length) return 0;
@@ -10506,10 +10627,10 @@ class Database extends events.EventEmitter {
     return totalSize;
   }
 
-  /**
-   * Begin an insert session for batch operations
-   * @param {Object} sessionOptions - Options for the insert session
-   * @returns {InsertSession} - The insert session instance
+  /**
+   * Begin an insert session for batch operations
+   * @param {Object} sessionOptions - Options for the insert session
+   * @returns {InsertSession} - The insert session instance
    */
   beginInsertSession(sessionOptions = {}) {
     if (this.destroyed) {
@@ -10521,8 +10642,8 @@ class Database extends events.EventEmitter {
     return new InsertSession(this, sessionOptions);
   }
 
-  /**
-   * Insert a new record
+  /**
+   * Insert a new record
    */
   async insert(data) {
     this._validateInitialization('insert');
@@ -10615,8 +10736,8 @@ class Database extends events.EventEmitter {
     });
   }
 
-  /**
-   * Insert multiple records in batch (OPTIMIZATION)
+  /**
+   * Insert multiple records in batch (OPTIMIZATION)
    */
   async insertBatch(dataArray) {
     this._validateInitialization('insertBatch');
@@ -10641,8 +10762,8 @@ class Database extends events.EventEmitter {
     });
   }
 
-  /**
-   * Internal implementation for insertBatch to allow inline execution when already inside the queue
+  /**
+   * Internal implementation for insertBatch to allow inline execution when already inside the queue
    */
   async _insertBatchInternal(dataArray) {
     // CRITICAL FIX: Validate state before insert operation
@@ -10733,8 +10854,8 @@ class Database extends events.EventEmitter {
     return processedRecords;
   }
 
-  /**
-   * Find records matching criteria
+  /**
+   * Find records matching criteria
    */
   async find(criteria = {}, options = {}) {
     this._validateInitialization('find');
@@ -10842,11 +10963,11 @@ class Database extends events.EventEmitter {
     }
   }
 
-  /**
-   * Validate indexed query mode for strict mode
-   * @private
-   * @param {Object} criteria - Query criteria
-   * @param {Object} options - Query options
+  /**
+   * Validate indexed query mode for strict mode
+   * @private
+   * @param {Object} criteria - Query criteria
+   * @param {Object} options - Query options
    */
   _validateIndexedQuery(criteria, options = {}) {
     // Allow bypassing strict mode validation with allowNonIndexed option
@@ -10872,10 +10993,10 @@ class Database extends events.EventEmitter {
     }
   }
 
-  /**
-   * Create a shallow copy of a record for change detection
-   * Optimized for known field types: number, string, null, or single-level arrays
-   * @private
+  /**
+   * Create a shallow copy of a record for change detection
+   * Optimized for known field types: number, string, null, or single-level arrays
+   * @private
    */
   _createShallowCopy(record) {
     const copy = {};
@@ -10900,10 +11021,10 @@ class Database extends events.EventEmitter {
     return copy;
   }
 
-  /**
-   * Create an intuitive API wrapper using a class with Proxy
-   * Combines the benefits of classes with the flexibility of Proxy
-   * @private
+  /**
+   * Create an intuitive API wrapper using a class with Proxy
+   * Combines the benefits of classes with the flexibility of Proxy
+   * @private
    */
   _createEntryProxy(entry, originalRecord) {
     // Create a class instance that wraps the entry
@@ -10938,9 +11059,9 @@ class Database extends events.EventEmitter {
     });
   }
 
-  /**
-   * Create a high-performance wrapper for maximum speed
-   * @private
+  /**
+   * Create a high-performance wrapper for maximum speed
+   * @private
    */
   _createHighPerformanceWrapper(entry, originalRecord) {
     // Create a simple wrapper object for high performance
@@ -10958,10 +11079,10 @@ class Database extends events.EventEmitter {
     return wrapper;
   }
 
-  /**
-   * Check if a record has changed using optimized comparison
-   * Optimized for known field types: number, string, null, or single-level arrays
-   * @private
+  /**
+   * Check if a record has changed using optimized comparison
+   * Optimized for known field types: number, string, null, or single-level arrays
+   * @private
    */
   _hasRecordChanged(current, original) {
     // Quick reference check first
@@ -11025,9 +11146,9 @@ class Database extends events.EventEmitter {
     return false;
   }
 
-  /**
-   * Extract field names from query criteria
-   * @private
+  /**
+   * Extract field names from query criteria
+   * @private
    */
   _extractQueryFields(criteria) {
     const fields = new Set();
@@ -11054,8 +11175,8 @@ class Database extends events.EventEmitter {
     return Array.from(fields);
   }
 
-  /**
-   * Update records matching criteria
+  /**
+   * Update records matching criteria
    */
   async update(criteria, updateData) {
     this._validateInitialization('update');
@@ -11116,6 +11237,7 @@ class Database extends events.EventEmitter {
 
           // CRITICAL FIX: Remove old terms from index before adding new ones
           if (this.indexManager) {
+            await this._ensureLazyIndexLoaded();
             await this.indexManager.remove(record);
             if (this.opts.debugMode) {
               console.log(`🔄 UPDATE: Removed old terms from index for record ${record.id}`);
@@ -11151,6 +11273,7 @@ class Database extends events.EventEmitter {
             }
           }
           const indexUpdateStart = Date.now();
+          await this._ensureLazyIndexLoaded();
           await this.indexManager.update(record, updated, lineNumber);
           if (this.opts.debugMode) {
             console.log(`🔄 UPDATE: Index update completed in ${Date.now() - indexUpdateStart}ms`);
@@ -11173,8 +11296,8 @@ class Database extends events.EventEmitter {
     });
   }
 
-  /**
-   * Delete records matching criteria
+  /**
+   * Delete records matching criteria
    */
   async delete(criteria) {
     this._validateInitialization('delete');
@@ -11217,6 +11340,7 @@ class Database extends events.EventEmitter {
         for (const record of records) {
           // Remove term mapping
           this.removeTermMapping(record);
+          await this._ensureLazyIndexLoaded();
           await this.indexManager.remove(record);
 
           // Remove record from writeBuffer or mark as deleted
@@ -11248,16 +11372,16 @@ class Database extends events.EventEmitter {
     });
   }
 
-  /**
-   * Generate a unique ID
+  /**
+   * Generate a unique ID
    */
   generateId() {
     return Date.now().toString(36) + Math.random().toString(36).substr(2);
   }
 
-  /**
-   * Apply schema enforcement to a record
-   * Converts object to array and back to enforce schema (remove extra fields, add undefined for missing fields)
+  /**
+   * Apply schema enforcement to a record
+   * Converts object to array and back to enforce schema (remove extra fields, add undefined for missing fields)
    */
   applySchemaEnforcement(record) {
     // Only apply schema enforcement if fields configuration is explicitly provided
@@ -11281,8 +11405,8 @@ class Database extends events.EventEmitter {
     return enforcedRecord;
   }
 
-  /**
-   * Initialize schema for array-based serialization
+  /**
+   * Initialize schema for array-based serialization
    */
   initializeSchema() {
     if (!this.serializer || !this.serializer.schemaManager) {
@@ -11314,8 +11438,8 @@ class Database extends events.EventEmitter {
     }
   }
 
-  /**
-   * Get database length (number of records)
+  /**
+   * Get database length (number of records)
    */
   get length() {
     // Return total records: writeBuffer + saved records
@@ -11378,15 +11502,15 @@ class Database extends events.EventEmitter {
     return writeBufferRecords + savedRecords;
   }
 
-  /**
-   * Calculate current writeBuffer size in bytes (similar to published v1.1.0)
+  /**
+   * Calculate current writeBuffer size in bytes (similar to published v1.1.0)
    */
   currentWriteBufferSize() {
     return this.writeBufferTotalSize || 0;
   }
 
-  /**
-   * Get database statistics
+  /**
+   * Get database statistics
    */
   getStats() {
     const stats = {
@@ -11406,16 +11530,16 @@ class Database extends events.EventEmitter {
     return stats;
   }
 
-  /**
-   * Initialize database (alias for initialize for backward compatibility)
+  /**
+   * Initialize database (alias for initialize for backward compatibility)
    */
   async init() {
     return this.initialize();
   }
 
-  /**
-   * Schedule index rebuild when index data is missing or corrupted
-   * @private
+  /**
+   * Schedule index rebuild when index data is missing or corrupted
+   * @private
    */
   _scheduleIndexRebuild() {
     // Mark that rebuild is needed
@@ -11425,9 +11549,9 @@ class Database extends events.EventEmitter {
     // This avoids blocking init() but ensures index is available when needed
   }
 
-  /**
-   * Rebuild indexes from data file if needed
-   * @private
+  /**
+   * Rebuild indexes from data file if needed
+   * @private
    */
   async _rebuildIndexesIfNeeded() {
     if (this.opts.debugMode) {
@@ -11489,9 +11613,9 @@ class Database extends events.EventEmitter {
     }
   }
 
-  /**
-   * Rebuild indexes with retry logic to handle I/O hangs
-   * @private
+  /**
+   * Rebuild indexes with retry logic to handle I/O hangs
+   * @private
    */
   async _rebuildIndexesWithRetry() {
     // If no timeout configured, use original implementation without retry
@@ -11671,10 +11795,10 @@ class Database extends events.EventEmitter {
     return count;
   }
 
-  /**
-   * Destroy database - DESTRUCTIVE MODE
-   * Assumes save() has already been called by user
-   * If anything is still active, it indicates a bug - log error and force cleanup
+  /**
+   * Destroy database - DESTRUCTIVE MODE
+   * Assumes save() has already been called by user
+   * If anything is still active, it indicates a bug - log error and force cleanup
    */
   async destroy() {
     if (this.destroyed) return;
@@ -11732,8 +11856,8 @@ class Database extends events.EventEmitter {
     }
   }
 
-  /**
-   * Internal destroy implementation
+  /**
+   * Internal destroy implementation
    */
   async _performDestroy() {
     try {
@@ -11833,8 +11957,8 @@ class Database extends events.EventEmitter {
     }
   }
 
-  /**
-   * Find one record
+  /**
+   * Find one record
    */
   async findOne(criteria, options = {}) {
     this._validateInitialization('findOne');
@@ -11845,8 +11969,8 @@ class Database extends events.EventEmitter {
     return results.length > 0 ? results[0] : null;
   }
 
-  /**
-   * Count records
+  /**
+   * Count records
    */
   async count(criteria = {}, options = {}) {
     this._validateInitialization('count');
@@ -11860,23 +11984,23 @@ class Database extends events.EventEmitter {
     return fileCount + writeBufferCount;
   }
 
-  /**
-   * Check if any records exist matching the given criteria (ultra-fast when using indexed fields)
-   *
-   * @param {string|object} fieldName - Indexed field name (legacy) OR query criteria object (new)
-   * @param {string|Array<string>} terms - Single term or array of terms (when using legacy syntax)
-   * @param {Object} options - Options: { $all: true/false, caseInsensitive: true/false, excludes: Array<string> }
-   * @returns {Promise<boolean>} - True if at least one match exists
-   *
-   * @example
-   * // Legacy syntax - ultra-fast index-only check
-   * const exists = await db.exists('nameTerms', 'tv');
-   * const existsAll = await db.exists('nameTerms', ['tv', 'globo'], { $all: true });
-   *
-   * @example
-   * // New syntax - full query criteria support
-   * const exists = await db.exists({ mediaType: 'live', status: 'active' });
-   * const existsOr = await db.exists({ mediaType: ['live', 'vod'] });
+  /**
+   * Check if any records exist matching the given criteria (ultra-fast when using indexed fields)
+   *
+   * @param {string|object} fieldName - Indexed field name (legacy) OR query criteria object (new)
+   * @param {string|Array<string>} terms - Single term or array of terms (when using legacy syntax)
+   * @param {Object} options - Options: { $all: true/false, caseInsensitive: true/false, excludes: Array<string> }
+   * @returns {Promise<boolean>} - True if at least one match exists
+   *
+   * @example
+   * // Legacy syntax - ultra-fast index-only check
+   * const exists = await db.exists('nameTerms', 'tv');
+   * const existsAll = await db.exists('nameTerms', ['tv', 'globo'], { $all: true });
+   *
+   * @example
+   * // New syntax - full query criteria support
+   * const exists = await db.exists({ mediaType: 'live', status: 'active' });
+   * const existsOr = await db.exists({ mediaType: ['live', 'vod'] });
    */
   async exists(fieldNameOrCriteria, terms, options = {}) {
     this._validateInitialization('exists');
@@ -11890,6 +12014,7 @@ class Database extends events.EventEmitter {
       // Legacy syntax: exists(fieldName, terms, options)
       // Also handle invalid inputs (null, array) for backward compatibility
       const fieldName = fieldNameOrCriteria;
+      await this._ensureLazyIndexLoaded();
       return this.indexManager.exists(fieldName, terms, options);
     } else {
       // Invalid input type
@@ -11897,13 +12022,13 @@ class Database extends events.EventEmitter {
     }
   }
 
-  /**
-   * Run batched index-only existence checks using a single connection per field.
-   * Each entry must specify { field, terms, options?, id? } so the result map stays stable.
-   *
-   * @param {Array<Object>} criteriaArray
-   * @param {Object} opts
-   * @returns {Promise<Object<string, boolean>>}
+  /**
+   * Run batched index-only existence checks using a single connection per field.
+   * Each entry must specify { field, terms, options?, id? } so the result map stays stable.
+   *
+   * @param {Array<Object>} criteriaArray
+   * @param {Object} opts
+   * @returns {Promise<Object<string, boolean>>}
    */
   async multiExists(criteriaArray, opts = {}) {
     this._validateInitialization('multiExists');
@@ -11913,6 +12038,7 @@ class Database extends events.EventEmitter {
     if (!this.indexManager) {
       return {};
     }
+    await this._ensureLazyIndexLoaded();
     const results = {};
     const perField = new Map();
     for (let i = 0; i < criteriaArray.length; i++) {
@@ -11942,12 +12068,12 @@ class Database extends events.EventEmitter {
     return results;
   }
 
-  /**
-   * Check if any records exist using full query criteria
-   * Uses index intersection when possible for maximum performance
-   * @private
-   * @param {object} criteria - Query criteria object
-   * @returns {Promise<boolean>} - True if at least one match exists
+  /**
+   * Check if any records exist using full query criteria
+   * Uses index intersection when possible for maximum performance
+   * @private
+   * @param {object} criteria - Query criteria object
+   * @returns {Promise<boolean>} - True if at least one match exists
    */
 
   async _existsWithCriteria(criteria) {
@@ -11974,7 +12100,7 @@ class Database extends events.EventEmitter {
       if (this.opts.debugMode) {
         console.log(`⚡ exists() using INDEX-ONLY optimization for: ${JSON.stringify(criteria)}`);
       }
-      return this._existsIndexOnly(criteria);
+      return await this._existsIndexOnly(criteria);
     }
 
     // 🎯 FALLBACK: Use the same find() logic for complex criteria or non-indexed fields
@@ -11990,11 +12116,11 @@ class Database extends events.EventEmitter {
     }
   }
 
-  /**
-   * Check if criteria can use index-only existence check
-   * @private
-   * @param {object} criteria - Query criteria
-   * @returns {boolean} - True if can use index-only
+  /**
+   * Check if criteria can use index-only existence check
+   * @private
+   * @param {object} criteria - Query criteria
+   * @returns {boolean} - True if can use index-only
    */
   _canUseIndexOnlyForExists(criteria) {
     // Must have indexes configured
@@ -12025,13 +12151,14 @@ class Database extends events.EventEmitter {
     return true;
   }
 
-  /**
-   * Perform index-only existence check (ultra-fast, no disk I/O)
-   * @private
-   * @param {object} criteria - Simple criteria with only indexed fields
-   * @returns {boolean} - True if any records match the criteria
+  /**
+   * Perform index-only existence check (ultra-fast, no disk I/O)
+   * @private
+   * @param {object} criteria - Simple criteria with only indexed fields
+   * @returns {boolean} - True if any records match the criteria
    */
-  _existsIndexOnly(criteria) {
+  async _existsIndexOnly(criteria) {
+    await this._ensureLazyIndexLoaded();
     const criteriaEntries = Object.entries(criteria);
 
     // For single field criteria, use direct indexManager.exists()
@@ -12066,12 +12193,12 @@ class Database extends events.EventEmitter {
     return intersection.size > 0;
   }
 
-  /**
-   * Get line numbers for a field/value combination using index-only lookup
-   * @private
-   * @param {string} field - Field name
-   * @param {*} value - Field value (string, number, or array)
-   * @returns {Array<number>} Array of line numbers
+  /**
+   * Get line numbers for a field/value combination using index-only lookup
+   * @private
+   * @param {string} field - Field name
+   * @param {*} value - Field value (string, number, or array)
+   * @returns {Array<number>} Array of line numbers
    */
   _getIndexLinesForFieldValue(field, value) {
     // For arrays (OR logic), check each value
@@ -12088,12 +12215,12 @@ class Database extends events.EventEmitter {
     return this._getSingleFieldLines(field, value);
   }
 
-  /**
-   * Get line numbers for a single field/value using index lookup
-   * @private
-   * @param {string} field - Field name
-   * @param {*} value - Single field value
-   * @returns {Array<number>} Array of line numbers
+  /**
+   * Get line numbers for a single field/value using index lookup
+   * @private
+   * @param {string} field - Field name
+   * @param {*} value - Single field value
+   * @returns {Array<number>} Array of line numbers
    */
   _getSingleFieldLines(field, value) {
     // Use indexManager.exists() logic but return line numbers instead of boolean
@@ -12136,13 +12263,13 @@ class Database extends events.EventEmitter {
     return Array.from(lines);
   }
 
-  /**
-   * Calculate coverage for grouped include/exclude term sets
-   * @param {string} fieldName - Name of the indexed field
-   * @param {Array<object>} groups - Array of { terms, excludes } objects
-   * @param {object} filterCriteria - Optional filter criteria
-   * @param {object} options - Optional settings
-   * @returns {Promise<number>} Coverage percentage between 0 and 100
+  /**
+   * Calculate coverage for grouped include/exclude term sets
+   * @param {string} fieldName - Name of the indexed field
+   * @param {Array<object>} groups - Array of { terms, excludes } objects
+   * @param {object} filterCriteria - Optional filter criteria
+   * @param {object} options - Optional settings
+   * @returns {Promise<number>} Coverage percentage between 0 and 100
    */
   async coverage(fieldName, groups, filterCriteria = null, options = {}) {
     this._validateInitialization('coverage');
@@ -12308,12 +12435,12 @@ class Database extends events.EventEmitter {
     return Number(coverageValue.toFixed(precision));
   }
 
-  /**
-   * Score records based on weighted terms in an indexed array:string field
-   * @param {string} fieldName - Name of indexed array:string field
-   * @param {object} scores - Map of terms to numeric weights
-   * @param {object} options - Query options
-   * @returns {Promise<Array>} Records with scores, sorted by score
+  /**
+   * Score records based on weighted terms in an indexed array:string field
+   * @param {string} fieldName - Name of indexed array:string field
+   * @param {object} scores - Map of terms to numeric weights
+   * @param {object} options - Query options
+   * @returns {Promise<Array>} Records with scores, sorted by score
    */
   async score(fieldName, scores, options = {}) {
     // Validate initialization
@@ -12367,12 +12494,23 @@ class Database extends events.EventEmitter {
     // Check if this is a term-mapped field
     const isTermMapped = this.termManager && this.termManager.termMappingFields && this.termManager.termMappingFields.includes(fieldName);
 
+    // CRITICAL FIX: Ensure index is loaded before accessing data
+    // After idle unload, index.data[fieldName] becomes {} (truthy but empty)
+    // Use _ensureLazyIndexLoaded() to reload from disk instead of _rebuildIndexesIfNeeded()
+    // which requires allowIndexRebuild=true and rebuilds from scratch
+    if (!this.indexManager.indexLoaded) {
+      await this._ensureLazyIndexLoaded();
+    }
+
     // Access the index for this field
     const fieldIndex = this.indexManager.index.data[fieldName];
-    if (!fieldIndex) {
+    if (!fieldIndex || Object.keys(fieldIndex).length === 0) {
       return [];
     }
 
+    // Reset idle unload timer since we're using the index
+    this.indexManager.markIndexUsed();
+
     // Accumulate scores for each line number
     const scoreMap = new Map();
     const countMap = opts.mode === 'avg' ? new Map() : null;
@@ -12538,9 +12676,9 @@ class Database extends events.EventEmitter {
     return results;
   }
 
-  /**
-   * Read a grouped range with retry logic to handle I/O hangs
-   * @private
+  /**
+   * Read a grouped range with retry logic to handle I/O hangs
+   * @private
    */
   async _readGroupedRangeWithRetry(groupedRange, fd, startToLineNumber, scoresByLineNumber, opts) {
     // If no timeout configured, use original implementation without retry
@@ -12635,9 +12773,9 @@ class Database extends events.EventEmitter {
     return results;
   }
 
-  /**
-   * Original read grouped range logic without retry (for backward compatibility)
-   * @private
+  /**
+   * Original read grouped range logic without retry (for backward compatibility)
+   * @private
    */
   async _readGroupedRangeOriginal(groupedRange, fd, startToLineNumber, scoresByLineNumber, opts) {
     const results = [];
@@ -12695,9 +12833,9 @@ class Database extends events.EventEmitter {
     return results;
   }
 
-  /**
-   * Original rebuild indexes logic without retry (for backward compatibility)
-   * @private
+  /**
+   * Original rebuild indexes logic without retry (for backward compatibility)
+   * @private
    */
   async _rebuildIndexesOriginal() {
     let count = 0;
@@ -12832,8 +12970,8 @@ class Database extends events.EventEmitter {
     return count;
   }
 
-  /**
-   * Wait for all pending operations to complete
+  /**
+   * Wait for all pending operations to complete
    */
   async _waitForPendingOperations() {
     if (this.operationQueue && this.operationQueue.getQueueLength() > 0) {
@@ -12851,8 +12989,8 @@ class Database extends events.EventEmitter {
     }
   }
 
-  /**
-   * Flush write buffer completely with smart detection of ongoing insertions
+  /**
+   * Flush write buffer completely with smart detection of ongoing insertions
    */
   async _flushWriteBufferCompletely() {
     // Force complete flush of write buffer with intelligent detection
@@ -12912,9 +13050,9 @@ class Database extends events.EventEmitter {
     }
   }
 
-  /**
-   * Get a lightweight sample of the write buffer for comparison
-   * @returns {Object} - Sample data for comparison
+  /**
+   * Get a lightweight sample of the write buffer for comparison
+   * @returns {Object} - Sample data for comparison
    */
   _getBufferSample() {
     if (!this.writeBuffer || this.writeBuffer.length === 0) {
@@ -12953,11 +13091,11 @@ class Database extends events.EventEmitter {
     return sample;
   }
 
-  /**
-   * Check if two buffer samples are identical (indicating stuck flush)
-   * @param {Object} sample1 - First sample
-   * @param {Object} sample2 - Second sample
-   * @returns {boolean} - True if samples are identical
+  /**
+   * Check if two buffer samples are identical (indicating stuck flush)
+   * @param {Object} sample1 - First sample
+   * @param {Object} sample2 - Second sample
+   * @returns {boolean} - True if samples are identical
    */
   _isBufferSampleIdentical(sample1, sample2) {
     if (!sample1 || !sample2) {
@@ -12991,8 +13129,8 @@ class Database extends events.EventEmitter {
     return true;
   }
 
-  /**
-   * Process write buffer items
+  /**
+   * Process write buffer items
    */
   async _processWriteBuffer() {
     // Process write buffer items without loading entire file
@@ -13070,8 +13208,8 @@ class Database extends events.EventEmitter {
     }
   }
 
-  /**
-   * Process individual buffer item
+  /**
+   * Process individual buffer item
    */
   async _processBufferItem(buffer) {
     // Process buffer item without loading entire file
@@ -13082,8 +13220,8 @@ class Database extends events.EventEmitter {
     }
   }
 
-  /**
-   * Process individual object item
+  /**
+   * Process individual object item
    */
   async _processObjectItem(obj) {
     // Process object item without loading entire file
@@ -13096,8 +13234,8 @@ class Database extends events.EventEmitter {
     }
   }
 
-  /**
-   * Process multiple object items in a single batch write operation
+  /**
+   * Process multiple object items in a single batch write operation
    */
   async _processObjectItemsBatch(objects) {
     if (!this.fileHandler || objects.length === 0) return;
@@ -13115,8 +13253,8 @@ class Database extends events.EventEmitter {
     await this.fileHandler.writeDataAsync(buffer);
   }
 
-  /**
-   * Wait for all I/O operations to complete
+  /**
+   * Wait for all I/O operations to complete
    */
   async _waitForIOCompletion() {
     // Wait for all file operations to complete
@@ -13128,9 +13266,9 @@ class Database extends events.EventEmitter {
     }
   }
 
-  /**
-   * CRITICAL FIX: Safe fallback method to load existing records when _streamExistingRecords fails
-   * This prevents data loss by attempting alternative methods to preserve existing data
+  /**
+   * CRITICAL FIX: Safe fallback method to load existing records when _streamExistingRecords fails
+   * This prevents data loss by attempting alternative methods to preserve existing data
    */
   async _loadExistingRecordsFallback(deletedIdsSnapshot, writeBufferSnapshot) {
     const existingRecords = [];
@@ -13176,9 +13314,9 @@ class Database extends events.EventEmitter {
     }
   }
 
-  /**
-   * Stream existing records without loading entire file into memory
-   * Optimized with group ranging and reduced JSON parsing
+  /**
+   * Stream existing records without loading entire file into memory
+   * Optimized with group ranging and reduced JSON parsing
    */
   async _streamExistingRecords(deletedIdsSnapshot, writeBufferSnapshot) {
     const existingRecords = [];
@@ -13650,8 +13788,8 @@ class Database extends events.EventEmitter {
     return existingRecords;
   }
 
-  /**
-   * Flush write buffer
+  /**
+   * Flush write buffer
    */
   async flush() {
     return this.operationQueue.enqueue(async () => {
@@ -13668,8 +13806,8 @@ class Database extends events.EventEmitter {
     });
   }
 
-  /**
-   * Flush insertion buffer (backward compatibility)
+  /**
+   * Flush insertion buffer (backward compatibility)
    */
   async flushInsertionBuffer() {
     // Flush insertion buffer implementation - save any pending data
@@ -13677,8 +13815,8 @@ class Database extends events.EventEmitter {
     return this.flush();
   }
 
-  /**
-   * Get memory usage
+  /**
+   * Get memory usage
    */
   getMemoryUsage() {
     return {
@@ -13690,7 +13828,7 @@ class Database extends events.EventEmitter {
     };
   }
   _hasActualIndexData() {
-    if (!this.indexManager) return false;
+    if (!this.indexManager || this.indexManager.indexLoaded === false) return false;
     const data = this.indexManager.index.data;
     for (const field in data) {
       const fieldData = data[field];
@@ -13703,11 +13841,53 @@ class Database extends events.EventEmitter {
     }
     return false;
   }
+  async _loadIndexDataFromFile() {
+    const idxPath = this.normalizedFile.replace('.jdb', '.idx.jdb');
+    try {
+      await fs.promises.access(idxPath);
+    } catch (error) {
+      return null;
+    }
+    try {
+      const raw = await fs.promises.readFile(idxPath, 'utf8');
+      const parsed = JSON.parse(raw);
+      return parsed?.index ?? null;
+    } catch (error) {
+      if (this.opts.debugMode) {
+        console.error(`⚠️ _loadIndexDataFromFile: Failed to read or parse ${idxPath}`, error);
+      }
+      return null;
+    }
+  }
+  async _ensureLazyIndexLoaded() {
+    if (!this.indexManager || this.indexManager.indexLoaded) return;
+    if (!this.indexManager.indexedFields || this.indexManager.indexedFields.length === 0) {
+      this.indexManager.indexLoaded = true;
+      return;
+    }
+    if (this._lazyIndexLoadPromise) {
+      return this._lazyIndexLoadPromise;
+    }
+    this._lazyIndexLoadPromise = (async () => {
+      const indexData = await this._loadIndexDataFromFile();
+      if (indexData) {
+        this.indexManager.load(indexData);
+      } else {
+        if (this.opts.debugMode) {
+          console.log('🔍 _ensureLazyIndexLoaded: No index file found or invalid index data, continuing with empty index');
+        }
+        this.indexManager.indexLoaded = true;
+        this.indexManager.markIndexUsed();
+      }
+      this._lazyIndexLoadPromise = null;
+    })();
+    return this._lazyIndexLoadPromise;
+  }
 
-  /**
-   * Locate a record by line number and return its byte range
-   * @param {number} n - Line number
-   * @returns {Array} - [start, end] byte range or undefined
+  /**
+   * Locate a record by line number and return its byte range
+   * @param {number} n - Line number
+   * @returns {Array} - [start, end] byte range or undefined
    */
   locate(n) {
     if (this.offsets[n] === undefined) {
@@ -13726,10 +13906,10 @@ class Database extends events.EventEmitter {
     return [this.offsets[n], end];
   }
 
-  /**
-   * Get ranges for streaming based on line numbers
-   * @param {Array|Set} map - Line numbers to get ranges for
-   * @returns {Array} - Array of range objects {start, end, index}
+  /**
+   * Get ranges for streaming based on line numbers
+   * @param {Array|Set} map - Line numbers to get ranges for
+   * @returns {Array} - Array of range objects {start, end, index}
    */
   getRanges(map) {
     return (map || Array.from(this.offsets.keys())).map(n => {
@@ -13742,19 +13922,19 @@ class Database extends events.EventEmitter {
     }).filter(n => n !== undefined);
   }
 
-  /**
-   * Get the base line number for writeBuffer entries (number of persisted records)
-   * @private
+  /**
+   * Get the base line number for writeBuffer entries (number of persisted records)
+   * @private
    */
   _getWriteBufferBaseLineNumber() {
     return Array.isArray(this.offsets) ? this.offsets.length : 0;
   }
 
-  /**
-   * Convert a writeBuffer index into an absolute line number
-   * @param {number} writeBufferIndex - Index inside writeBuffer (0-based)
-   * @returns {number} Absolute line number (0-based)
-   * @private
+  /**
+   * Convert a writeBuffer index into an absolute line number
+   * @param {number} writeBufferIndex - Index inside writeBuffer (0-based)
+   * @returns {number} Absolute line number (0-based)
+   * @private
    */
   _getAbsoluteLineNumber(writeBufferIndex) {
     if (typeof writeBufferIndex !== 'number' || writeBufferIndex < 0) {
@@ -13763,10 +13943,10 @@ class Database extends events.EventEmitter {
     return this._getWriteBufferBaseLineNumber() + writeBufferIndex;
   }
 
-  /**
-   * Attempts to recover a corrupted line by cleaning invalid characters and fixing common JSON issues
-   * @param {string} line - The corrupted line to recover
-   * @returns {string|null} - The recovered line or null if recovery is not possible
+  /**
+   * Attempts to recover a corrupted line by cleaning invalid characters and fixing common JSON issues
+   * @param {string} line - The corrupted line to recover
+   * @returns {string|null} - The recovered line or null if recovery is not possible
    */
   _tryRecoverLine(line) {
     if (!line || typeof line !== 'string') {
@@ -14016,8 +14196,8 @@ class Database extends events.EventEmitter {
     }).apply(this, arguments);
   }
 
-  /**
-   * Walk through records using streaming (real implementation)
+  /**
+   * Walk through records using streaming (real implementation)
    */
   walk(_x3) {
     var _this2 = this;
@@ -14474,18 +14654,18 @@ class Database extends events.EventEmitter {
     }).apply(this, arguments);
   }
 
-  /**
-   * Iterate through records with bulk update capabilities
-   * Allows in-place modifications and deletions with optimized performance
-   * 
-   * @param {Object} criteria - Query criteria
-   * @param {Object} options - Iteration options
-   * @param {number} options.chunkSize - Batch size for processing (default: 1000)
-   * @param {string} options.strategy - Processing strategy: 'streaming' (always uses walk() method)
-   * @param {boolean} options.autoSave - Auto-save after each chunk (default: false)
-   * @param {Function} options.progressCallback - Progress callback function
-   * @param {boolean} options.detectChanges - Auto-detect changes (default: true)
-   * @returns {AsyncGenerator} Generator yielding records for modification
+  /**
+   * Iterate through records with bulk update capabilities
+   * Allows in-place modifications and deletions with optimized performance
+   * 
+   * @param {Object} criteria - Query criteria
+   * @param {Object} options - Iteration options
+   * @param {number} options.chunkSize - Batch size for processing (default: 1000)
+   * @param {string} options.strategy - Processing strategy: 'streaming' (always uses walk() method)
+   * @param {boolean} options.autoSave - Auto-save after each chunk (default: false)
+   * @param {Function} options.progressCallback - Progress callback function
+   * @param {boolean} options.detectChanges - Auto-detect changes (default: true)
+   * @returns {AsyncGenerator} Generator yielding records for modification
    */
   iterate(_x4) {
     var _this3 = this;
@@ -14620,9 +14800,9 @@ class Database extends events.EventEmitter {
     }).apply(this, arguments);
   }
 
-  /**
-   * Process a batch of updates and deletes from iterate operation
-   * @private
+  /**
+   * Process a batch of updates and deletes from iterate operation
+   * @private
    */
   async _processIterateBatch(updateBuffer, deleteBuffer, options) {
     if (updateBuffer.length === 0 && deleteBuffer.size === 0) return;
@@ -14649,6 +14829,7 @@ class Database extends events.EventEmitter {
 
           // Update index
           const absoluteLineNumber = this._getAbsoluteLineNumber(targetIndex);
+          await this._ensureLazyIndexLoaded();
           await this.indexManager.update(record, record, absoluteLineNumber);
         }
         if (this.opts.debugMode) {
@@ -14668,6 +14849,7 @@ class Database extends events.EventEmitter {
             this.removeTermMapping(record);
 
             // Remove from index
+            await this._ensureLazyIndexLoaded();
             await this.indexManager.remove(record);
 
             // Remove from writeBuffer or mark as deleted
@@ -14697,8 +14879,8 @@ class Database extends events.EventEmitter {
     }
   }
 
-  /**
-   * Close the database
+  /**
+   * Close the database
    */
   async close() {
     if (this.destroyed || this.closed) return;
@@ -14742,11 +14924,14 @@ class Database extends events.EventEmitter {
         }
       }
 
-      // 2. Mark as closed (but not destroyed) to allow reopening
+      // 2. Cancel any pending idle unload timers before shutdown
+      this.indexManager?.cancelIdleUnloadTimer?.();
+
+      // 3. Mark as closed (but not destroyed) to allow reopening
       this.closed = true;
       this.initialized = false;
 
-      // 3. Clear any remaining state for clean reopening
+      // 4. Clear any remaining state for clean reopening
       this.writeBuffer = [];
       this.writeBufferOffsets = [];
       this.writeBufferSizes = [];
@@ -14765,14 +14950,20 @@ class Database extends events.EventEmitter {
     }
   }
 
-  /**
-   * Save index data to .idx.jdb file
-   * @private
+  /**
+   * Save index data to .idx.jdb file
+   * @private
    */
   async _saveIndexDataToFile() {
     if (this.indexManager) {
       try {
         const idxPath = this.normalizedFile.replace('.jdb', '.idx.jdb');
+        if (this.indexManager.indexLoaded === false && fs.existsSync(idxPath)) {
+          if (this.opts.debugMode) {
+            console.log(`⚠️ _saveIndexDataToFile: Index unloaded in memory, preserving existing index file ${idxPath}`);
+          }
+          return;
+        }
         const indexJSON = this.indexManager.indexedFields && this.indexManager.indexedFields.length > 0 ? this.indexManager.toJSON() : {};
 
         // Check if index is empty
@@ -14843,8 +15034,8 @@ class Database extends events.EventEmitter {
     }
   }
 
-  /**
-   * Get operation queue statistics
+  /**
+   * Get operation queue statistics
    */
   getQueueStats() {
     if (!this.operationQueue) {
@@ -14862,11 +15053,11 @@ class Database extends events.EventEmitter {
     return this.operationQueue.getStats();
   }
 
-  /**
-   * Wait for all pending operations to complete
-   * This includes operation queue AND active insert sessions
-   * If called with no arguments, interpret as waitForOperations(null).
-   * If argument provided (maxWaitTime), pass that on.
+  /**
+   * Wait for all pending operations to complete
+   * This includes operation queue AND active insert sessions
+   * If called with no arguments, interpret as waitForOperations(null).
+   * If argument provided (maxWaitTime), pass that on.
    */
   async waitForOperations(maxWaitTime = null) {
     // Accept any falsy/undefined/empty call as "wait for all"