@pixagram/lacerta-db 0.7.3 → 0.8.0

package/index.js

@@ -1,13 +1,32 @@
 /**
- * LacertaDB V0.7.3 - Production Library with QuickStore
- * Added: QuickStore feature, private property/method conventions
- * @version 0.7.3
+ * LacertaDB V0.8.0 - Production Library with QuickStore
+ * 
+ * A high-performance, browser-based document database with support for:
+ * - IndexedDB storage with connection pooling
+ * - Multiple caching strategies (LRU, LFU, TTL)
+ * - Full-text search and geospatial indexing
+ * - Document encryption and compression
+ * - Binary attachments via OPFS (Origin Private File System)
+ * - MongoDB-like query syntax and aggregation pipeline
+ * - Schema migrations and versioning
+ * - QuickStore for fast localStorage-based operations
+ * 
+ * @module LacertaDB
+ * @version 0.8.0
  * @license MIT
+ * @author Pixagram SA
  */
 
 'use strict';
 
-// Add polyfill at the top of the file:
+// ========================
+// Polyfills
+// ========================
+
+/**
+ * Polyfill for requestIdleCallback if not available in the browser.
+ * Falls back to setTimeout with 0ms delay for environments that don't support it.
+ */
 if (!window.requestIdleCallback) {
     window.requestIdleCallback = function(callback) {
         return setTimeout(callback, 0);
@@ -15,29 +34,72 @@ if (!window.requestIdleCallback) {
     window.cancelIdleCallback = clearTimeout;
 }
 
-// Dependencies - for browser environments using a bundler (e.g., Webpack, Vite)
+// ========================
+// Dependencies
+// ========================
+
+/**
+ * Import external serialization and encoding utilities.
+ * TurboSerial provides efficient binary serialization with compression and deduplication.
+ * TurboBase64 provides fast base64 encoding/decoding.
+ */
 import TurboSerial from "@pixagram/turboserial";
 import TurboBase64 from "@pixagram/turbobase64";
 
+/**
+ * Global serializer instance configured for optimal performance.
+ * @type {TurboSerial}
+ */
 const serializer = new TurboSerial({
-    compression: true,
-    deduplication: true,
-    simdOptimization: true,
-    detectCircular: true
+    compression: true,        // Enable built-in compression
+    deduplication: true,      // Deduplicate repeated values
+    simdOptimization: true,   // Use SIMD instructions when available
+    detectCircular: true      // Handle circular references
 });
+
+/**
+ * Global Base64 encoder/decoder instance.
+ * @type {TurboBase64}
+ */
 const base64 = new TurboBase64();
 
 // ========================
 // Quick Store (localStorage based)
 // ========================
 
+/**
+ * QuickStore provides fast, synchronous access to small amounts of data using localStorage.
+ * Ideal for frequently accessed metadata, user preferences, or small documents
+ * where the overhead of IndexedDB is not justified.
+ * 
+ * Data is serialized using TurboSerial and encoded as Base64 for localStorage storage.
+ * 
+ * @class QuickStore
+ * @example
+ * const store = new QuickStore('myDatabase');
+ * store.add('user1', { name: 'John', age: 30 });
+ * const user = store.get('user1');
+ * console.log(user.name); // 'John'
+ */
 class QuickStore {
+    /**
+     * Creates a new QuickStore instance.
+     * @param {string} dbName - The database name used to namespace localStorage keys
+     */
     constructor(dbName) {
+        /** @private @type {string} Database name */
         this._dbName = dbName;
+        /** @private @type {string} Prefix for all localStorage keys */
         this._keyPrefix = `lacertadb_${dbName}_quickstore_`;
+        /** @private @type {string} Key for storing the document index */
         this._indexKey = `${this._keyPrefix}index`;
     }
 
+    /**
+     * Reads the index of all stored document IDs from localStorage.
+     * @private
+     * @returns {Array<string>} Array of document IDs
+     */
     _readIndex() {
         const indexStr = localStorage.getItem(this._indexKey);
         if (!indexStr) return [];
@@ -49,12 +111,24 @@ class QuickStore {
         }
     }
 
+    /**
+     * Writes the document ID index to localStorage.
+     * @private
+     * @param {Array<string>} index - Array of document IDs to store
+     */
     _writeIndex(index) {
         const serializedIndex = serializer.serialize(index);
         const encodedIndex = base64.encode(serializedIndex);
         localStorage.setItem(this._indexKey, encodedIndex);
     }
 
+    /**
+     * Adds or replaces a document in the QuickStore.
+     * @param {string} docId - Unique identifier for the document
+     * @param {Object} data - Document data to store
+     * @returns {boolean} True if successful, false otherwise
+     * @throws {LacertaDBError} If localStorage quota is exceeded
+     */
     add(docId, data) {
         const key = `${this._keyPrefix}data_${docId}`;
         try {
@@ -76,6 +150,11 @@ class QuickStore {
         }
     }
 
+    /**
+     * Retrieves a document from the QuickStore.
+     * @param {string} docId - Document ID to retrieve
+     * @returns {Object|null} The document data, or null if not found
+     */
     get(docId) {
         const key = `${this._keyPrefix}data_${docId}`;
         const stored = localStorage.getItem(key);
@@ -90,10 +169,20 @@ class QuickStore {
         return null;
     }
 
+    /**
+     * Updates an existing document (alias for add).
+     * @param {string} docId - Document ID to update
+     * @param {Object} data - New document data
+     * @returns {boolean} True if successful
+     */
     update(docId, data) {
         return this.add(docId, data);
     }
 
+    /**
+     * Deletes a document from the QuickStore.
+     * @param {string} docId - Document ID to delete
+     */
     delete(docId) {
         const key = `${this._keyPrefix}data_${docId}`;
         localStorage.removeItem(key);
@@ -106,6 +195,10 @@ class QuickStore {
         }
     }
 
+    /**
+     * Retrieves all documents from the QuickStore.
+     * @returns {Array<Object>} Array of all documents with their _id fields
+     */
     getAll() {
         const index = this._readIndex();
         return index.map(docId => {
@@ -114,6 +207,12 @@ class QuickStore {
         }).filter(Boolean);
     }
 
+    /**
+     * Queries documents using MongoDB-like filter syntax.
+     * Uses the global queryEngine for evaluation.
+     * @param {Object} [filter={}] - Query filter object
+     * @returns {Array<Object>} Array of matching documents
+     */
     query(filter = {}) {
         const allDocs = this.getAll();
         if (Object.keys(filter).length === 0) return allDocs;
@@ -122,6 +221,9 @@ class QuickStore {
         return allDocs.filter(doc => queryEngine.evaluate(doc, filter));
     }
 
+    /**
+     * Clears all documents from the QuickStore.
+     */
     clear() {
         const index = this._readIndex();
         for (const docId of index) {
@@ -130,6 +232,10 @@ class QuickStore {
         localStorage.removeItem(this._indexKey);
     }
 
+    /**
+     * Gets the number of documents in the QuickStore.
+     * @type {number}
+     */
     get size() {
         return this._readIndex().length;
     }
@@ -139,12 +245,34 @@ class QuickStore {
 // Global IndexedDB Connection Pool
 // ========================
 
+/**
+ * Manages a pool of IndexedDB connections to optimize database access.
+ * Connections are reused across multiple operations and reference-counted
+ * to ensure proper cleanup.
+ * 
+ * @class IndexedDBConnectionPool
+ */
 class IndexedDBConnectionPool {
+    /**
+     * Creates a new connection pool instance.
+     */
     constructor() {
+        /** @private @type {Map<string, IDBDatabase>} Active database connections */
         this._connections = new Map();
+        /** @private @type {Map<string, number>} Reference counts for each connection */
         this._refCounts = new Map();
     }
 
+    /**
+     * Gets or creates a connection to an IndexedDB database.
+     * If a connection already exists, increments its reference count.
+     * 
+     * @param {string} dbName - Database name
+     * @param {number} [version=1] - Database version
+     * @param {Function} [upgradeCallback] - Callback for onupgradeneeded event
+     * @returns {Promise<IDBDatabase>} The database connection
+     * @throws {LacertaDBError} If database cannot be opened
+     */
     async getConnection(dbName, version = 1, upgradeCallback) {
         const key = `${dbName}_v${version}`;
 
@@ -171,6 +299,13 @@ class IndexedDBConnectionPool {
         return db;
     }
 
+    /**
+     * Releases a database connection. If reference count reaches zero,
+     * the connection is closed.
+     * 
+     * @param {string} dbName - Database name
+     * @param {number} [version=1] - Database version
+     */
     releaseConnection(dbName, version = 1) {
         const key = `${dbName}_v${version}`;
         const refCount = this._refCounts.get(key) || 0;
@@ -188,6 +323,10 @@ class IndexedDBConnectionPool {
         }
     }
 
+    /**
+     * Closes all connections in the pool.
+     * Should be called during application cleanup.
+     */
     closeAll() {
         for (const db of this._connections.values()) {
             db.close();
@@ -197,18 +336,34 @@ class IndexedDBConnectionPool {
     }
 }
 
+/** @type {IndexedDBConnectionPool} Global connection pool instance */
 const connectionPool = new IndexedDBConnectionPool();
 
 // ========================
 // Async Mutex for managing concurrent operations
 // ========================
 
+/**
+ * Provides mutual exclusion for asynchronous operations.
+ * Ensures that only one async operation can access a critical section at a time.
+ * 
+ * @class AsyncMutex
+ */
 class AsyncMutex {
+    /**
+     * Creates a new mutex instance.
+     */
     constructor() {
+        /** @private @type {Array<Function>} Queue of waiting operations */
         this._queue = [];
+        /** @private @type {boolean} Whether the mutex is currently locked */
         this._locked = false;
     }
 
+    /**
+     * Acquires the mutex lock. Returns a release function when the lock is acquired.
+     * @returns {Promise<Function>} A function to release the lock
+     */
     acquire() {
         return new Promise(resolve => {
             this._queue.push(resolve);
@@ -216,11 +371,21 @@ class AsyncMutex {
         });
     }
 
+    /**
+     * Releases the mutex lock.
+     */
     release() {
         this._locked = false;
         this._dispatch();
     }
 
+    /**
+     * Runs a callback with exclusive access to the mutex.
+     * Automatically acquires and releases the lock.
+     * 
+     * @param {Function} callback - Async function to run exclusively
+     * @returns {Promise<*>} Result of the callback
+     */
     async runExclusive(callback) {
         const release = await this.acquire();
         try {
@@ -230,6 +395,10 @@ class AsyncMutex {
         }
     }
 
+    /**
+     * Dispatches the next waiting operation if the mutex is unlocked.
+     * @private
+     */
     _dispatch() {
         if (this._locked || this._queue.length === 0) {
             return;
@@ -244,12 +413,29 @@ class AsyncMutex {
 // Custom error class for LacertaDB
 // ========================
 
+/**
+ * Custom error class for LacertaDB operations.
+ * Includes error codes for programmatic error handling.
+ * 
+ * @class LacertaDBError
+ * @extends Error
+ */
 class LacertaDBError extends Error {
+    /**
+     * Creates a new LacertaDBError.
+     * @param {string} message - Human-readable error message
+     * @param {string} code - Machine-readable error code
+     * @param {Error} [originalError] - Original error that caused this error
+     */
     constructor(message, code, originalError) {
         super(message);
+        /** @type {string} Error name identifier */
         this.name = 'LacertaDBError';
+        /** @type {string} Machine-readable error code */
         this.code = code;
+        /** @type {Error|null} Original error if this is a wrapped error */
         this.originalError = originalError || null;
+        /** @type {string} ISO timestamp when the error occurred */
         this.timestamp = new Date().toISOString();
     }
 }
@@ -258,15 +444,38 @@ class LacertaDBError extends Error {
 // LRU Cache Implementation
 // ========================
 
+/**
+ * Least Recently Used (LRU) cache implementation.
+ * Evicts the least recently accessed items when the cache reaches its maximum size.
+ * Optionally supports TTL (time-to-live) for cache entries.
+ * 
+ * @class LRUCache
+ */
 class LRUCache {
+    /**
+     * Creates a new LRU cache.
+     * @param {number} [maxSize=100] - Maximum number of items to store
+     * @param {number|null} [ttl=null] - Time-to-live in milliseconds (null for no expiration)
+     */
     constructor(maxSize = 100, ttl = null) {
+        /** @private @type {number} Maximum cache size */
         this._maxSize = maxSize;
+        /** @private @type {number|null} TTL in milliseconds */
         this._ttl = ttl;
+        /** @private @type {Map<string, *>} Cache storage */
         this._cache = new Map();
+        /** @private @type {Array<string>} Access order tracking (most recent at end) */
         this._accessOrder = [];
+        /** @private @type {Map<string, number>} Timestamps for TTL */
         this._timestamps = new Map();
     }
 
+    /**
+     * Retrieves a value from the cache.
+     * Updates the access order and checks TTL expiration.
+     * @param {string} key - Cache key
+     * @returns {*|null} Cached value or null if not found/expired
+     */
     get(key) {
         if (!this._cache.has(key)) {
             return null;
@@ -289,6 +498,12 @@ class LRUCache {
         return this._cache.get(key);
     }
 
+    /**
+     * Stores a value in the cache.
+     * Evicts the oldest items if the cache exceeds maxSize.
+     * @param {string} key - Cache key
+     * @param {*} value - Value to store
+     */
     set(key, value) {
         if (this._cache.has(key)) {
             const index = this._accessOrder.indexOf(key);
@@ -308,6 +523,11 @@ class LRUCache {
         }
     }
 
+    /**
+     * Deletes an item from the cache.
+     * @param {string} key - Cache key to delete
+     * @returns {boolean} True if item was deleted
+     */
     delete(key) {
         const index = this._accessOrder.indexOf(key);
         if (index > -1) {
@@ -317,12 +537,20 @@ class LRUCache {
         return this._cache.delete(key);
     }
 
+    /**
+     * Clears all items from the cache.
+     */
     clear() {
         this._cache.clear();
         this._accessOrder = [];
         this._timestamps.clear();
     }
 
+    /**
+     * Checks if a key exists in the cache (respects TTL).
+     * @param {string} key - Cache key
+     * @returns {boolean} True if key exists and is not expired
+     */
     has(key) {
         if (this._ttl && this._cache.has(key)) {
             const timestamp = this._timestamps.get(key);
@@ -334,13 +562,30 @@ class LRUCache {
         return this._cache.has(key);
     }
 
+    /**
+     * Gets the current number of items in the cache.
+     * @type {number}
+     */
     get size() {
         return this._cache.size;
     }
 }
 
-// LFU (Least Frequently Used) Cache
+// ========================
+// LFU Cache Implementation
+// ========================
+
+/**
+ * Least Frequently Used (LFU) cache implementation.
+ * Evicts the least frequently accessed items when the cache reaches its maximum size.
+ * @class LFUCache
+ */
 class LFUCache {
+    /**
+     * Creates a new LFU cache.
+     * @param {number} [maxSize=100] - Maximum number of items to store
+     * @param {number|null} [ttl=null] - Time-to-live in milliseconds
+     */
     constructor(maxSize = 100, ttl = null) {
         this._maxSize = maxSize;
         this._ttl = ttl;
@@ -349,6 +594,11 @@ class LFUCache {
         this._timestamps = new Map();
     }
 
+    /**
+     * Retrieves a value from the cache and increments its frequency.
+     * @param {string} key - Cache key
+     * @returns {*|null} Cached value or null if not found/expired
+     */
     get(key) {
         if (!this._cache.has(key)) {
             return null;
@@ -366,6 +616,11 @@ class LFUCache {
         return this._cache.get(key);
     }
 
+    /**
+     * Stores a value in the cache.
+     * @param {string} key - Cache key
+     * @param {*} value - Value to store
+     */
     set(key, value) {
         if (this._cache.has(key)) {
             this._cache.set(key, value);
@@ -391,39 +646,73 @@ class LFUCache {
         }
     }
 
+    /**
+     * Deletes an item from the cache.
+     * @param {string} key - Cache key to delete
+     * @returns {boolean} True if item was deleted
+     */
     delete(key) {
         this._frequencies.delete(key);
         this._timestamps.delete(key);
         return this._cache.delete(key);
     }
 
+    /** Clears all items from the cache. */
     clear() {
         this._cache.clear();
         this._frequencies.clear();
         this._timestamps.clear();
     }
 
+    /**
+     * Checks if a key exists in the cache.
+     * @param {string} key - Cache key
+     * @returns {boolean} True if key exists
+     */
     has(key) {
         return this._cache.has(key);
     }
 
+    /** @type {number} Current number of items in the cache */
     get size() {
         return this._cache.size;
     }
 }
 
-// TTL (Time To Live) Only Cache
+// ========================
+// TTL Cache Implementation
+// ========================
+
+/**
+ * Time-To-Live (TTL) only cache implementation.
+ * Items automatically expire after a specified duration.
+ * @class TTLCache
+ */
 class TTLCache {
+    /**
+     * Creates a new TTL cache.
+     * @param {number} [ttl=60000] - Time-to-live in milliseconds (default 1 minute)
+     */
     constructor(ttl = 60000) {
         this._ttl = ttl;
         this._cache = new Map();
         this._timers = new Map();
     }
 
+    /**
+     * Retrieves a value from the cache.
+     * @param {string} key - Cache key
+     * @returns {*|null} Cached value or null if not found
+     */
     get(key) {
         return this._cache.get(key) || null;
     }
 
+    /**
+     * Stores a value in the cache with automatic expiration.
+     * @param {string} key - Cache key
+     * @param {*} value - Value to store
+     */
     set(key, value) {
         if (this._timers.has(key)) {
             clearTimeout(this._timers.get(key));
@@ -437,6 +726,11 @@ class TTLCache {
         this._timers.set(key, timer);
     }
 
+    /**
+     * Deletes an item from the cache.
+     * @param {string} key - Cache key to delete
+     * @returns {boolean} True if item was deleted
+     */
     delete(key) {
         if (this._timers.has(key)) {
             clearTimeout(this._timers.get(key));
@@ -445,6 +739,7 @@ class TTLCache {
         return this._cache.delete(key);
     }
 
+    /** Clears all items and timers from the cache. */
     clear() {
         for (const timer of this._timers.values()) {
             clearTimeout(timer);
@@ -453,15 +748,21 @@ class TTLCache {
         this._cache.clear();
     }
 
+    /**
+     * Checks if a key exists in the cache.
+     * @param {string} key - Cache key
+     * @returns {boolean} True if key exists
+     */
     has(key) {
         return this._cache.has(key);
     }
 
+    /** @type {number} Current number of items in the cache */
     get size() {
         return this._cache.size;
     }
 
-    // Add a destroy method:
+    /** Destroys the cache, clearing all timers and data. */
     destroy() {
         for (const timer of this._timers.values()) {
             clearTimeout(timer);
@@ -475,7 +776,20 @@ class TTLCache {
 // Cache Strategy System
 // ========================
 
+/**
+ * Unified cache strategy manager that supports multiple caching algorithms.
+ * Provides a consistent interface regardless of the underlying strategy.
+ * @class CacheStrategy
+ */
 class CacheStrategy {
+    /**
+     * Creates a new cache strategy.
+     * @param {Object} [config={}] - Configuration options
+     * @param {string} [config.type='lru'] - Cache type: 'lru', 'lfu', 'ttl', or 'none'
+     * @param {number} [config.maxSize=100] - Maximum cache size
+     * @param {number|null} [config.ttl=null] - Time-to-live in milliseconds
+     * @param {boolean} [config.enabled=true] - Whether caching is enabled
+     */
     constructor(config = {}) {
         this._type = config.type || 'lru';
         this._maxSize = config.maxSize || 100;
@@ -484,7 +798,7 @@ class CacheStrategy {
         this._cache = null;
     }
 
-    // Lazy initialization with getter
+    /** Gets the cache instance, creating it lazily if needed. */
     get cache() {
         if (!this._cache) {
             this._cache = this._createCache();
@@ -492,6 +806,7 @@ class CacheStrategy {
         return this._cache;
     }
 
+    /** @private Creates the appropriate cache instance based on config type. */
     _createCache() {
         switch (this._type) {
             case 'lru':
@@ -507,31 +822,51 @@ class CacheStrategy {
         }
     }
 
+    /**
+     * Retrieves a value from the cache.
+     * @param {string} key - Cache key
+     * @returns {*|null} Cached value or null
+     */
     get(key) {
         if (!this._enabled || !this.cache) return null;
         return this.cache.get(key);
     }
 
+    /**
+     * Stores a value in the cache.
+     * @param {string} key - Cache key
+     * @param {*} value - Value to store
+     */
     set(key, value) {
         if (!this._enabled || !this.cache) return;
         this.cache.set(key, value);
     }
 
+    /**
+     * Deletes an item from the cache.
+     * @param {string} key - Cache key to delete
+     */
     delete(key) {
         if (!this._enabled || !this.cache) return;
         this.cache.delete(key);
     }
 
+    /** Clears all items from the cache. */
     clear() {
         if (!this._enabled || !this.cache) return;
         this.cache.clear();
     }
 
+    /**
+     * Updates the cache strategy configuration.
+     * @param {Object} newConfig - New configuration options
+     */
     updateStrategy(newConfig) {
         Object.assign(this, newConfig);
         this._cache = null; // Reset cache for lazy reinitialization
     }
 
+    /** Destroys the cache and releases resources. */
     destroy() {
         if (this._cache && this._cache.destroy) {
             this._cache.destroy();
@@ -543,10 +878,21 @@ class CacheStrategy {
 }
 
 // ========================
-// Compression Utility (Fixed)
+// Compression Utility
 // ========================
 
+/**
+ * Browser-based compression utility using the Compression Streams API.
+ * Provides deflate compression and decompression for data storage optimization.
+ * @class BrowserCompressionUtility
+ */
 class BrowserCompressionUtility {
+    /**
+     * Compresses data using the deflate algorithm.
+     * @param {Uint8Array} input - Data to compress
+     * @returns {Promise<Uint8Array>} Compressed data
+     * @throws {TypeError} If input is not a Uint8Array
+     */
     async compress(input) {
         if (!(input instanceof Uint8Array)) {
             throw new TypeError('Input must be Uint8Array');
@@ -562,6 +908,11 @@ class BrowserCompressionUtility {
         }
     }
 
+    /**
+     * Decompresses deflate-compressed data.
+     * @param {Uint8Array} compressedData - Compressed data to decompress
+     * @returns {Promise<Uint8Array>} Decompressed data
+     */
     async decompress(compressedData) {
         if (!(compressedData instanceof Uint8Array)) {
             throw new TypeError('Input must be Uint8Array');
@@ -577,6 +928,11 @@ class BrowserCompressionUtility {
         }
     }
 
+    /**
+     * Synchronous compression (pass-through, no actual compression).
+     * @param {Uint8Array} input - Data to compress
+     * @returns {Uint8Array} Original data (uncompressed)
+     */
     compressSync(input) {
         if (!(input instanceof Uint8Array)) {
             throw new TypeError('Input must be Uint8Array');
@@ -584,6 +940,11 @@ class BrowserCompressionUtility {
         return input;
     }
 
+    /**
+     * Synchronous decompression (pass-through).
+     * @param {Uint8Array} compressedData - Data to decompress
+     * @returns {Uint8Array} Original data
+     */
     decompressSync(compressedData) {
         if (!(compressedData instanceof Uint8Array)) {
             throw new TypeError('Input must be Uint8Array');
@@ -596,7 +957,18 @@ class BrowserCompressionUtility {
 // Browser Encryption Utility
 // ========================
 
+/**
+ * Utility for encrypting and decrypting data using Web Crypto API.
+ * Uses AES-GCM for authenticated encryption with PBKDF2 for key derivation.
+ * @class BrowserEncryptionUtility
+ */
 class BrowserEncryptionUtility {
+    /**
+     * Encrypts data using AES-256-GCM with PBKDF2 key derivation.
+     * @param {Uint8Array} data - Data to encrypt
+     * @param {string} password - Password for encryption
+     * @returns {Promise<Uint8Array>} Encrypted data (salt + IV + ciphertext)
+     */
     async encrypt(data, password) {
         const encoder = new TextEncoder();
         const salt = crypto.getRandomValues(new Uint8Array(16));
@@ -638,6 +1010,12 @@ class BrowserEncryptionUtility {
         return result;
     }
 
+    /**
+     * Decrypts AES-256-GCM encrypted data.
+     * @param {Uint8Array} encryptedData - Encrypted data (salt + IV + ciphertext)
+     * @param {string} password - Password for decryption
+     * @returns {Promise<Uint8Array>} Decrypted data
+     */
     async decrypt(encryptedData, password) {
         const encoder = new TextEncoder();
         const salt = encryptedData.slice(0, 16);
@@ -680,7 +1058,21 @@ class BrowserEncryptionUtility {
 // Database-Level Encryption
 // ========================
 
+/**
+ * Advanced encryption system for database-level security.
+ * Provides PIN-based encryption with HMAC verification for data integrity.
+ * Suitable for securing entire databases or sensitive documents like private keys.
+ * @class SecureDatabaseEncryption
+ */
 class SecureDatabaseEncryption {
+    /**
+     * Creates a new secure encryption instance.
+     * @param {Object} [config={}] - Encryption configuration
+     * @param {number} [config.iterations=100000] - PBKDF2 iteration count
+     * @param {string} [config.hashAlgorithm='SHA-256'] - Hash algorithm for key derivation
+     * @param {number} [config.keyLength=256] - AES key length in bits
+     * @param {number} [config.saltLength=32] - Salt length in bytes
+     */
     constructor(config = {}) {
         this._masterKey = null;
         this._salt = null;
@@ -693,10 +1085,17 @@ class SecureDatabaseEncryption {
         this._hmacKey = null;
     }
 
+    /** @type {boolean} Whether encryption has been initialized */
     get initialized() {
         return this._initialized;
     }
 
+    /**
+     * Initializes encryption with a PIN code.
+     * @param {string} pin - PIN code (typically 4-8 digits)
+     * @param {Uint8Array|null} [salt=null] - Salt for key derivation (generated if null)
+     * @returns {Promise<string>} Base64-encoded salt
+     */
     async initialize(pin, salt = null) {
         if (this._initialized) {
             throw new Error('Database encryption already initialized');
@@ -752,6 +1151,11 @@ class SecureDatabaseEncryption {
         return base64.encode(this._salt);
     }
 
+    /**
+     * Encrypts data with AES-GCM and adds HMAC for integrity.
+     * @param {string|Object|Uint8Array} data - Data to encrypt
+     * @returns {Promise<Uint8Array>} Encrypted data with IV and HMAC
+     */
     async encrypt(data) {
         if (!this._initialized) {
             throw new Error('Database encryption not initialized');
@@ -794,6 +1198,12 @@ class SecureDatabaseEncryption {
         return result;
     }
 
+    /**
+     * Decrypts data and verifies HMAC integrity.
+     * @param {Uint8Array} encryptedPackage - Encrypted data (IV + ciphertext + HMAC)
+     * @returns {Promise<Uint8Array>} Decrypted data
+     * @throws {Error} If HMAC verification fails
+     */
     async decrypt(encryptedPackage) {
         if (!this._initialized) {
             throw new Error('Database encryption not initialized');
@@ -831,6 +1241,12 @@ class SecureDatabaseEncryption {
         return new Uint8Array(decryptedData);
     }
 
+    /**
+     * Encrypts a private key with additional authentication data.
+     * @param {string|Uint8Array|Object} privateKey - Key to encrypt
+     * @param {string} [additionalAuth=''] - Additional authentication data
+     * @returns {Promise<string>} Base64-encoded encrypted key
+     */
     async encryptPrivateKey(privateKey, additionalAuth = '') {
         if (!this._initialized) {
             throw new Error('Database encryption not initialized');
@@ -874,6 +1290,12 @@ class SecureDatabaseEncryption {
         return base64.encode(result);
     }
 
+    /**
+     * Decrypts a private key, verifying additional authentication data.
+     * @param {string} encryptedKeyString - Base64-encoded encrypted key
+     * @param {string} [additionalAuth=''] - Additional authentication data to verify
+     * @returns {Promise<string>} Decrypted private key
+     */
     async decryptPrivateKey(encryptedKeyString, additionalAuth = '') {
         if (!this._initialized) {
             throw new Error('Database encryption not initialized');
@@ -908,6 +1330,12 @@ class SecureDatabaseEncryption {
         return new TextDecoder().decode(decryptedKey);
     }
 
+    /**
+     * Generates a cryptographically secure random PIN.
+     * @static
+     * @param {number} [length=6] - PIN length (number of digits)
+     * @returns {string} Random PIN
+     */
     static generateSecurePIN(length = 6) {
         const digits = new Uint8Array(length);
         crypto.getRandomValues(digits);
@@ -916,6 +1344,7 @@ class SecureDatabaseEncryption {
             .join('');
     }
 
+    /** Destroys the encryption instance and clears all keys from memory. */
     destroy() {
         this._masterKey = null;
         this._encKey = null;
@@ -924,6 +1353,7 @@ class SecureDatabaseEncryption {
         this._initialized = false;
     }
 
+    /** @private Compares two Uint8Arrays for equality. */
     _arrayEquals(a, b) {
         if (a.length !== b.length) return false;
         for (let i = 0; i < a.length; i++) {
@@ -932,6 +1362,12 @@ class SecureDatabaseEncryption {
         return true;
     }
 
+    /**
+     * Changes the encryption PIN.
+     * @param {string} oldPin - Current PIN
+     * @param {string} newPin - New PIN to set
+     * @returns {Promise<string>} Base64-encoded new salt
+     */
     async changePin(oldPin, newPin) {
         if (!this._initialized) {
             throw new Error('Database encryption not initialized');
@@ -956,6 +1392,10 @@ class SecureDatabaseEncryption {
         return newSalt;
     }
 
+    /**
+     * Exports encryption metadata for persistence (does NOT include keys).
+     * @returns {Object} Encryption metadata
+     */
     exportMetadata() {
         if (!this._salt) {
             throw new Error('No encryption metadata to export');
@@ -972,6 +1412,11 @@ class SecureDatabaseEncryption {
         };
     }
 
+    /**
+     * Imports encryption metadata from persistence.
+     * @param {Object} metadata - Encryption metadata
+     * @returns {boolean} True if successful
+     */
     importMetadata(metadata) {
         if (!metadata.salt) {
             throw new Error('Invalid encryption metadata');
@@ -991,7 +1436,17 @@ class SecureDatabaseEncryption {
 // B-Tree Index Implementation with Self-Healing
 // ========================
 
+/**
+ * Node in a B-Tree index structure.
+ * @class BTreeNode
+ * @private
+ */
 class BTreeNode {
+    /**
+     * Creates a new B-Tree node.
+     * @param {number} order - B-Tree order (determines branching factor)
+     * @param {boolean} leaf - Whether this is a leaf node
+     */
     constructor(order, leaf) {
         this.keys = new Array(2 * order - 1);
         this.values = new Array(2 * order - 1);
@@ -1001,6 +1456,7 @@ class BTreeNode {
         this.order = order;
     }
 
+    /** Searches for a key in this node and its subtree. */
     search(key) {
         let i = 0;
         while (i < this.n && key > this.keys[i]) {
@@ -1018,6 +1474,7 @@ class BTreeNode {
         return this.children[i] ? this.children[i].search(key) : null;
     }
 
+    /** Performs a range search within this node and its subtree. */
     rangeSearch(min, max, results) {
         let i = 0;
 
@@ -1040,6 +1497,7 @@ class BTreeNode {
         }
     }
 
+    /** Inserts a key-value pair into a non-full node. */
     insertNonFull(key, value) {
         let i = this.n - 1;
 
@@ -1086,6 +1544,7 @@ class BTreeNode {
         }
     }
 
+    /** Splits a full child node. */
     splitChild(i, y) {
         const z = new BTreeNode(this.order, y.leaf);
         z.n = this.order - 1;
@@ -1119,6 +1578,7 @@ class BTreeNode {
         this.n++;
     }
 
+    /** Removes a value from the key's value set. */
     remove(key, value) {
         let i = 0;
         while (i < this.n && key > this.keys[i]) {
@@ -1141,6 +1601,7 @@ class BTreeNode {
         }
     }
 
+    /** Verifies and repairs the node structure (self-healing). */
     verify() {
         const issues = [];
 
@@ -1170,7 +1631,16 @@ class BTreeNode {
     }
 }
 
+/**
+ * B-Tree index for efficient ordered data access and range queries.
+ * Supports multiple document IDs per key and includes self-healing capabilities.
+ * @class BTreeIndex
+ */
 class BTreeIndex {
+    /**
+     * Creates a new B-Tree index.
+     * @param {number} [order=4] - B-Tree order (minimum degree)
+     */
     constructor(order = 4) {
         this._root = null;
         this._order = order;
@@ -1179,6 +1649,11 @@ class BTreeIndex {
         this._verificationInterval = 60000;
     }
 
+    /**
+     * Inserts a key-value pair into the index.
+     * @param {*} key - Index key
+     * @param {string} value - Document ID
+     */
     insert(key, value) {
         if (Date.now() - this._lastVerification > this._verificationInterval) {
             this.verify();
@@ -1207,17 +1682,33 @@ class BTreeIndex {
         this._size++;
     }
 
+    /**
+     * Finds all document IDs associated with a key.
+     * @param {*} key - Key to search for
+     * @returns {Array<string>} Array of document IDs
+     */
     find(key) {
         if (!this._root) return [];
         const values = this._root.search(key);
         return values ? Array.from(values) : [];
     }
 
+    /**
+     * Checks if a key exists in the index.
+     * @param {*} key - Key to check
+     * @returns {boolean} True if key exists
+     */
     contains(key) {
         if (!this._root) return false;
         return this._root.search(key) !== null;
     }
 
+    /**
+     * Finds all document IDs within a key range.
+     * @param {*} min - Minimum key (inclusive)
+     * @param {*} max - Maximum key (inclusive)
+     * @returns {Array<string>} Array of document IDs
+     */
     range(min, max) {
         if (!this._root) return [];
         const results = [];
@@ -1225,6 +1716,7 @@ class BTreeIndex {
         return results;
     }
 
+    /** Finds all document IDs with keys >= min. */
     rangeFrom(min) {
         if (!this._root) return [];
         const results = [];
@@ -1232,6 +1724,7 @@ class BTreeIndex {
         return results;
     }
 
+    /** Finds all document IDs with keys <= max. */
     rangeTo(max) {
         if (!this._root) return [];
         const results = [];
@@ -1239,6 +1732,7 @@ class BTreeIndex {
         return results;
     }
 
+    /** Removes a document ID from a key's value set. */
     remove(key, value) {
         if (!this._root) return;
         this._root.remove(key, value);
@@ -1250,6 +1744,7 @@ class BTreeIndex {
         this._size--;
     }
 
+    /** Verifies index integrity and performs self-healing repairs. */
     verify() {
         this._lastVerification = Date.now();
         if (!this._root) return { healthy: true, issues: [] };
@@ -1267,18 +1762,34 @@ class BTreeIndex {
         };
     }
 
+    /** @type {number} Total number of entries in the index */
     get size() {
         return this._size;
     }
 }
 
-// Text Index for full-text search
+// ========================
+// Text Index for Full-Text Search
+// ========================
+
+/**
+ * Inverted index for full-text search capabilities.
+ * Tokenizes text and builds an index for fast keyword lookups.
+ * @class TextIndex
+ */
 class TextIndex {
     constructor() {
+        /** @private Token to document IDs mapping */
         this._invertedIndex = new Map();
+        /** @private Document ID to text mapping */
         this._documentTexts = new Map();
     }
 
+    /**
+     * Adds a document to the text index.
+     * @param {string} text - Document text content
+     * @param {string} docId - Document ID
+     */
     addDocument(text, docId) {
         if (typeof text !== 'string') return;
 
@@ -1293,6 +1804,7 @@ class TextIndex {
         }
     }
 
+    /** Removes a document from the text index. */
     removeDocument(docId) {
         const text = this._documentTexts.get(docId);
         if (!text) return;
@@ -1311,11 +1823,17 @@ class TextIndex {
         this._documentTexts.delete(docId);
     }
 
+    /** Updates a document's text in the index. */
     updateDocument(docId, newText) {
         this.removeDocument(docId);
         this.addDocument(newText, docId);
     }
 
+    /**
+     * Searches for documents containing all query terms.
+     * @param {string} query - Search query
+     * @returns {Array<string>} Array of matching document IDs
+     */
     search(query) {
         const tokens = this._tokenize(query);
         if (tokens.length === 0) return [];
@@ -1337,6 +1855,7 @@ class TextIndex {
         return results ? Array.from(results) : [];
     }
 
+    /** @private Tokenizes text into searchable terms. */
     _tokenize(text) {
         return text.toLowerCase()
             .replace(/[^\w\s]/g, ' ')
@@ -1344,17 +1863,32 @@ class TextIndex {
             .filter(token => token.length > 2);
     }
 
+    /** @type {number} Number of indexed documents */
     get size() {
         return this._documentTexts.size;
     }
 }
 
-// Geo Index for spatial queries
+// ========================
+// Geo Index for Spatial Queries
+// ========================
+
+/**
+ * Geospatial index for location-based queries.
+ * Supports proximity searches and bounding box queries.
+ * @class GeoIndex
+ */
 class GeoIndex {
     constructor() {
+        /** @private Document ID to coordinates mapping */
         this._points = new Map();
     }
 
+    /**
+     * Adds a geographic point to the index.
+     * @param {Object} coords - Coordinates object with lat/lng properties
+     * @param {string} docId - Document ID
+     */
     addPoint(coords, docId) {
         if (!coords || typeof coords.lat !== 'number' || typeof coords.lng !== 'number') {
             return;
@@ -1362,14 +1896,22 @@ class GeoIndex {
         this._points.set(docId, coords);
     }
 
+    /** Removes a point from the index. */
     removePoint(docId) {
         this._points.delete(docId);
     }
 
+    /** Updates a point's coordinates. */
     updatePoint(docId, newCoords) {
         this._points.set(docId, newCoords);
     }
 
+    /**
+     * Finds all points within a distance from a center point.
+     * @param {Object} center - Center coordinates
+     * @param {number} maxDistance - Maximum distance in kilometers
+     * @returns {Array<string>} Document IDs sorted by distance
+     */
     findNear(center, maxDistance) {
         const results = [];
 
@@ -1384,6 +1926,11 @@ class GeoIndex {
             .map(r => r.docId);
     }
 
+    /**
+     * Finds all points within a bounding box.
+     * @param {Object} bounds - Bounding box with minLat, maxLat, minLng, maxLng
+     * @returns {Array<string>} Document IDs within bounds
+     */
     findWithin(bounds) {
         const results = [];
 
@@ -1396,8 +1943,9 @@ class GeoIndex {
         return results;
     }
 
+    /** @private Calculates distance using the Haversine formula. */
     _haversine(coord1, coord2) {
-        const R = 6371;
+        const R = 6371; // Earth's radius in km
         const dLat = this._toRad(coord2.lat - coord1.lat);
         const dLng = this._toRad(coord2.lng - coord1.lng);
 
@@ -1409,24 +1957,25 @@ class GeoIndex {
         return R * c;
     }
 
+    /** @private Converts degrees to radians. */
     _toRad(deg) {
         return deg * (Math.PI / 180);
     }
 
+    /** @private Checks if coordinates are within bounds. */
     _isWithinBounds(coords, bounds) {
         return coords.lat >= bounds.minLat && coords.lat <= bounds.maxLat &&
             coords.lng >= bounds.minLng && coords.lng <= bounds.maxLng;
     }
 
+    /** @type {number} Number of indexed points */
     get size() {
         return this._points.size;
     }
 }
-
 // ========================
-// Index Manager (Optimized)
+// B-Tree Index Implementation with Self-Healing
 // ========================
-
 class IndexManager {
     constructor(collection) {
         this._collection = collection;
@@ -3459,7 +4008,7 @@ class Database {
 
     async export(format = 'json', password = null) {
         const data = {
-            version: '0.7.0',
+            version: '0.8.0',
             database: this.name,
             timestamp: Date.now(),
             collections: {}
@@ -3626,7 +4175,7 @@ class LacertaDB {
 
     async createBackup(password = null) {
         const backup = {
-            version: '0.7.0',
+            version: '0.8.0',
             timestamp: Date.now(),
             databases: {}
         };