@pixagram/lacerta-db 0.7.2 → 0.8.0

package/index.js

@@ -1,36 +1,105 @@
 /**
- * LacertaDB V0.7.0 - Production Library with QuickStore
- * Added: QuickStore feature, private property/method conventions
- * @version 0.7.0
+ * 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';
 
-// Dependencies - for browser environments using a bundler (e.g., Webpack, Vite)
+// ========================
+// 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);
+    };
+    window.cancelIdleCallback = clearTimeout;
+}
+
+// ========================
+// 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,
-    shareArrayBuffers: 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 [];
@@ -42,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 {
@@ -69,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);
@@ -83,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);
@@ -99,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 => {
@@ -107,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;
@@ -115,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) {
@@ -123,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;
     }
@@ -132,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}`;
 
@@ -164,22 +299,34 @@ 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;
 
-        if (refCount > 1) {
-            this._refCounts.set(key, refCount - 1);
-        } else {
+        // Force close if refCount is 1 or less
+        if (refCount <= 1) {
             const db = this._connections.get(key);
             if (db) {
                 db.close();
                 this._connections.delete(key);
                 this._refCounts.delete(key);
             }
+        } else {
+            this._refCounts.set(key, refCount - 1);
         }
     }
 
+    /**
+     * Closes all connections in the pool.
+     * Should be called during application cleanup.
+     */
     closeAll() {
         for (const db of this._connections.values()) {
             db.close();
@@ -189,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);
@@ -208,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 {
@@ -222,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;
@@ -236,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();
     }
 }
@@ -250,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;
@@ -281,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);
@@ -300,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) {
@@ -309,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);
@@ -326,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;
@@ -341,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;
@@ -358,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);
@@ -383,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));
@@ -429,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));
@@ -437,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);
@@ -445,20 +748,48 @@ 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;
     }
+
+    /** Destroys the cache, clearing all timers and data. */
+    destroy() {
+        for (const timer of this._timers.values()) {
+            clearTimeout(timer);
+        }
+        this._timers.clear();
+        this._cache.clear();
+    }
 }
 
 // ========================
 // 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;
@@ -467,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();
@@ -475,6 +806,7 @@ class CacheStrategy {
         return this._cache;
     }
 
+    /** @private Creates the appropriate cache instance based on config type. */
     _createCache() {
         switch (this._type) {
             case 'lru':
@@ -490,37 +822,77 @@ 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();
+        } else if (this._cache && this._cache.clear) {
+            this._cache.clear();
+        }
+        this._cache = null;
+    }
 }
 
 // ========================
-// 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');
@@ -536,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');
@@ -551,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');
@@ -558,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');
@@ -570,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));
@@ -612,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);
@@ -654,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;
@@ -667,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');
@@ -726,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');
@@ -768,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');
@@ -805,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');
@@ -848,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');
@@ -882,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);
@@ -890,6 +1344,7 @@ class SecureDatabaseEncryption {
             .join('');
     }
 
+    /** Destroys the encryption instance and clears all keys from memory. */
     destroy() {
         this._masterKey = null;
         this._encKey = null;
@@ -898,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++) {
@@ -906,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');
@@ -930,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');
@@ -946,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');
@@ -965,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);
@@ -975,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]) {
@@ -992,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;
 
@@ -1014,6 +1497,7 @@ class BTreeNode {
         }
     }
 
+    /** Inserts a key-value pair into a non-full node. */
     insertNonFull(key, value) {
         let i = this.n - 1;
 
@@ -1060,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;
@@ -1093,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]) {
@@ -1115,6 +1601,7 @@ class BTreeNode {
         }
     }
 
+    /** Verifies and repairs the node structure (self-healing). */
     verify() {
         const issues = [];
 
@@ -1144,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;
@@ -1153,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();
@@ -1181,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 = [];
@@ -1199,6 +1716,7 @@ class BTreeIndex {
         return results;
     }
 
+    /** Finds all document IDs with keys >= min. */
     rangeFrom(min) {
         if (!this._root) return [];
         const results = [];
@@ -1206,6 +1724,7 @@ class BTreeIndex {
         return results;
     }
 
+    /** Finds all document IDs with keys <= max. */
     rangeTo(max) {
         if (!this._root) return [];
         const results = [];
@@ -1213,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);
@@ -1224,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: [] };
@@ -1241,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;
 
@@ -1267,6 +1804,7 @@ class TextIndex {
         }
     }
 
+    /** Removes a document from the text index. */
     removeDocument(docId) {
         const text = this._documentTexts.get(docId);
         if (!text) return;
@@ -1285,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 [];
@@ -1311,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, ' ')
@@ -1318,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;
@@ -1336,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 = [];
 
@@ -1358,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 = [];
 
@@ -1370,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);
 
@@ -1383,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;
@@ -1658,18 +2233,22 @@ class IndexManager {
         return value;
     }
 
-    _saveIndexMetadata() {
-        const metadata = {
-            indexes: Array.from(this._indexes.entries()).map(([name, index]) => ({
-                name,
-                ...index
-            }))
-        };
-
+    async _saveIndexMetadata() {
         const key = `lacertadb_${this._collection.database.name}_${this._collection.name}_indexes`;
-        const serialized = serializer.serialize(metadata);
-        const encoded = base64.encode(serialized);
-        localStorage.setItem(key, encoded);
+        return new Promise((resolve) => {
+            requestIdleCallback(() => {
+                const metadata = {
+                    indexes: Array.from(this._indexes.entries()).map(([name, index]) => ({
+                        name,
+                        ...index
+                    }))
+                };
+                const serialized = serializer.serialize(metadata);
+                const encoded = base64.encode(serialized);
+                localStorage.setItem(key, encoded);
+                resolve();
+            });
+        });
     }
 
     async loadIndexMetadata() {
@@ -1739,11 +2318,20 @@ class IndexManager {
 
         return report;
     }
+    destroy() {
+        // Clear all index data
+        for (const [name, indexData] of this._indexData) {
+            if (indexData && indexData.clear) {
+                indexData.clear();
+            }
+        }
+        this._indexData.clear();
+        this._indexes.clear();
+        this._indexQueue = [];
+        this._processing = false;
+    }
 }
 
-// ========================
-// OPFS (Origin Private File System) Utility
-// ========================
 
 class OPFSUtility {
     async saveAttachments(dbName, collectionName, documentId, attachments) {
@@ -2043,10 +2631,25 @@ class Document {
             if (this._compressed) {
                 unpacked = await this._compression.decompress(unpacked);
             }
+
+            // Validate unpacked data
+            if (!unpacked || unpacked.length === 0) {
+                throw new Error('Empty unpacked data');
+            }
+
             this.data = serializer.deserialize(unpacked);
+
+            // Validate deserialized data
+            if (typeof this.data !== 'object' || this.data === null) {
+                throw new Error('Invalid deserialized data');
+            }
+
             return this.data;
         } catch (error) {
-            throw new LacertaDBError('Failed to unpack document', 'UNPACK_FAILED', error);
+            console.error('Document unpack failed:', error);
+            // Return empty object instead of throwing
+            this.data = {};
+            return this.data;
         }
     }
 
@@ -3085,25 +3688,6 @@ class Collection {
         ));
     }
 
-    async clear(options = {}) {
-        if (!this._initialized) await this.init();
-
-        if (options.force) {
-            await this._indexedDB.clear(this._db, 'documents');
-            this._metadata = new CollectionMetadata(this.name);
-            this.database.metadata.setCollection(this._metadata);
-            this._cacheStrategy.clear();
-
-            for (const indexName of this._indexManager.indexes.keys()) {
-                await this._indexManager.rebuildIndex(indexName);
-            }
-        } else {
-            const allDocs = await this.getAll();
-            const nonPermanentDocs = allDocs.filter(doc => !doc._permanent);
-            await this.batchDelete(nonPermanentDocs.map(doc => doc._id));
-        }
-    }
-
     async _checkSpaceLimit() {
         if (this._settings.sizeLimitKB !== Infinity && this._metadata.sizeKB > this._settings.bufferLimitKB) {
             await this._freeSpace();
@@ -3141,12 +3725,62 @@ class Collection {
         this._cacheStrategy.clear();
     }
 
+    async clear(options = {}) {
+        if (!this._initialized) await this.init();
+
+        if (options.force) {
+            // Clear documents first
+            await this._indexedDB.clear(this._db, 'documents');
+
+            // Reset metadata
+            this._metadata = new CollectionMetadata(this.name);
+            this.database.metadata.setCollection(this._metadata);
+
+            // Clear cache
+            this._cacheStrategy.clear();
+
+            // Rebuild indexes after clearing
+            for (const indexName of this._indexManager.indexes.keys()) {
+                await this._indexManager.rebuildIndex(indexName);
+            }
+        } else {
+            const allDocs = await this.getAll();
+            const nonPermanentDocs = allDocs.filter(doc => !doc._permanent);
+            await this.batchDelete(nonPermanentDocs.map(doc => doc._id));
+        }
+
+        // Reset cleanup interval if needed
+        if (this._cleanupInterval) {
+            clearInterval(this._cleanupInterval);
+            this._cleanupInterval = null;
+
+            if (this._settings.freeSpaceEvery > 0 && this._settings.sizeLimitKB !== Infinity) {
+                this._cleanupInterval = setInterval(() => this._freeSpace(), this._settings.freeSpaceEvery);
+            }
+        }
+    }
+
     destroy() {
-        clearInterval(this._cleanupInterval);
+        // Clear the cleanup interval
+        if (this._cleanupInterval) {
+            clearInterval(this._cleanupInterval);
+            this._cleanupInterval = null;
+        }
+
+        // Destroy cache strategy
+        if (this._cacheStrategy) {
+            this._cacheStrategy.destroy();
+        }
+
+        // Release the connection
         if (this._db) {
             const dbName = `${this.database.name}_${this.name}`;
             connectionPool.releaseConnection(dbName);
+            this._db = null;
         }
+
+        // Clear event listeners
+        this._events.clear();
     }
 }
 // ========================
@@ -3161,7 +3795,7 @@ class Database {
         this._settings = null;
         this._quickStore = null;
         this._performanceMonitor = performanceMonitor;
-        
+
         // Database-level encryption
         this._encryption = null;
         this._isEncrypted = false;
@@ -3199,20 +3833,20 @@ class Database {
         this._metadata = DatabaseMetadata.load(this.name);
         this._settings = Settings.load(this.name);
         this._quickStore = new QuickStore(this.name);
-        
+
         if (options.pin) {
             await this._initializeEncryption(options.pin, options.salt, options.encryptionConfig);
         }
-        
+
         return this;
     }
 
     async _initializeEncryption(pin, salt = null, config = {}) {
         this._encryption = new SecureDatabaseEncryption(config);
-        
+
         const encMetaKey = `lacertadb_${this.name}_encryption`;
         let existingMetadata = null;
-        
+
         if (!salt) {
             const stored = localStorage.getItem(encMetaKey);
             if (stored) {
@@ -3224,16 +3858,16 @@ class Database {
                 }
             }
         }
-        
+
         const saltBase64 = await this._encryption.initialize(pin, salt);
-        
+
         if (!existingMetadata) {
             const metadata = this._encryption.exportMetadata();
             const serialized = serializer.serialize(metadata);
             const encoded = base64.encode(serialized);
             localStorage.setItem(encMetaKey, encoded);
         }
-        
+
         this._isEncrypted = true;
         return saltBase64;
     }
@@ -3242,15 +3876,15 @@ class Database {
         if (!this._isEncrypted) {
             throw new Error('Database is not encrypted');
         }
-        
+
         const newSalt = await this._encryption.changePin(oldPin, newPin);
-        
+
         const encMetaKey = `lacertadb_${this.name}_encryption`;
         const metadata = this._encryption.exportMetadata();
         const serialized = serializer.serialize(metadata);
         const encoded = base64.encode(serialized);
         localStorage.setItem(encMetaKey, encoded);
-        
+
         return newSalt;
     }
 
@@ -3258,17 +3892,17 @@ class Database {
         if (!this._isEncrypted) {
             throw new Error('Database must be encrypted to store private keys');
         }
-        
+
         const encryptedKey = await this._encryption.encryptPrivateKey(
-            privateKey, 
+            privateKey,
             additionalAuth
         );
-        
+
         let keyStore = await this.getCollection('__private_keys__').catch(() => null);
         if (!keyStore) {
             keyStore = await this.createCollection('__private_keys__');
         }
-        
+
         await keyStore.add({
             name: keyName,
             key: encryptedKey,
@@ -3277,7 +3911,7 @@ class Database {
             id: keyName,
             permanent: true
         });
-        
+
         return true;
     }
 
@@ -3285,14 +3919,14 @@ class Database {
         if (!this._isEncrypted) {
             throw new Error('Database must be encrypted to retrieve private keys');
         }
-        
+
         const keyStore = await this.getCollection('__private_keys__');
         const doc = await keyStore.get(keyName);
-        
+
         if (!doc) {
             throw new Error(`Private key '${keyName}' not found`);
         }
-        
+
         return await this._encryption.decryptPrivateKey(doc.key, additionalAuth);
     }
 
@@ -3374,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: {}
@@ -3443,16 +4077,31 @@ class Database {
         this._quickStore.clear();
     }
 
-    destroy() {
-        this._collections.forEach(collection => {
+    async destroy() {
+        // Destroy all collections first
+        for (const collection of this._collections.values()) {
             if (collection.initialized) {
+                await collection.clear({ force: true });
                 collection.destroy();
             }
-        });
+        }
         this._collections.clear();
+
+        // Clear quickstore
+        if (this._quickStore) {
+            this._quickStore.clear();
+        }
+
+        // Destroy encryption
         if (this._encryption) {
             this._encryption.destroy();
         }
+
+        // Clear references
+        this._metadata = null;
+        this._settings = null;
+        this._quickStore = null;
+        this._performanceMonitor = null;
     }
 }
 
@@ -3526,7 +4175,7 @@ class LacertaDB {
 
     async createBackup(password = null) {
         const backup = {
-            version: '0.7.0',
+            version: '0.8.0',
             timestamp: Date.now(),
             databases: {}
         };
@@ -3575,6 +4224,12 @@ class LacertaDB {
         return results;
     }
 
+    // Add this method to LacertaDB class:
+    close() {
+        connectionPool.closeAll();
+    }
+
+    // Then fix destroy to not call close twice:
     destroy() {
         for (const db of this._databases.values()) {
             db.destroy();