@pixagram/lacerta-db 0.1.0 → 0.3.0

package/index.js

@@ -1,2091 +1,1853 @@
-/*
-The MIT License (MIT)
-Copyright (c) 2024 Matias Affolter
-*/
-"use strict";
+/**
+ * LacertaDB V4 - Complete Core Library (Repaired and Enhanced)
+ * A powerful browser-based document database with encryption, compression, and OPFS support
+ * @version 4.0.3 (Max Compatibility)
+ * @license MIT
+ */
+
+'use strict';
+// Note: These imports are for browser environments using a bundler (e.g., Webpack, Vite).
+// For direct browser usage, you would use an ES module import from a URL or local path.
 import TurboSerial from "@pixagram/turboserial";
-const TURBO = new TurboSerial({
-                compression: false,           // Enable compression
-                deduplication: true,          // Enable reference deduplication
-                shareArrayBuffers: true,      // Share ArrayBuffer references
-                simdOptimization: true,       // Enable SIMD optimizations
-                detectCircular: true,         // Detect circular references
-                memoryPoolSize: 65536        // Initial memory pool size
-            });
-            
-// Utility function for nested object access
-function getNestedValue(obj, path) {
-    return path.split('.').reduce((curr, prop) => (curr || {})[prop], obj);
-}
-
-class OPFSUtility {
-    static async saveAttachments(dbName, collectionName, documentId, attachments) {
-        const attachmentPaths = [];
-        const rootHandle = await navigator.storage.getDirectory();
-        const pathParts = [dbName, collectionName, documentId];
+import TurboBase64 from "@pixagram/turbobase64";
+
+const serializer = new TurboSerial({
+    compression: true,
+    deduplication: true,
+    shareArrayBuffers: true,
+    simdOptimization: true,
+    detectCircular: true
+});
+const base64 = new TurboBase64();
+
+/**
+ * Async Mutex for managing concurrent operations
+ */
+class AsyncMutex {
+    constructor() {
+        this._queue = [];
+        this._locked = false;
+    }
 
-        let dirHandle = rootHandle;
-        for (const part of pathParts) {
-            dirHandle = await dirHandle.getDirectoryHandle(part, { create: true });
-        }
+    acquire() {
+        return new Promise(resolve => {
+            this._queue.push(resolve);
+            this._dispatch();
+        });
+    }
 
-        for (let i = 0; i < attachments.length; i++) {
-            const fileId = i.toString();
-            const fileHandle = await dirHandle.getFileHandle(fileId, { create: true });
-            const writable = await fileHandle.createWritable();
-            await writable.write(attachments[i].data);
-            await writable.close();
+    release() {
+        this._locked = false;
+        this._dispatch();
+    }
 
-            const filePath = `${dbName}/${collectionName}/${documentId}/${fileId}`;
-            attachmentPaths.push(filePath);
+    async runExclusive(callback) {
+        const release = await this.acquire();
+        try {
+            return await callback();
+        } finally {
+            release();
         }
-
-        return attachmentPaths;
     }
 
-    static async getAttachments(attachmentPaths) {
-        const attachments = [];
-        const rootHandle = await navigator.storage.getDirectory();
-
-        for (const path of attachmentPaths) {
-            try {
-                const pathParts = path.split('/');
-                let dirHandle = rootHandle;
-                for (let i = 0; i < pathParts.length - 1; i++) {
-                    dirHandle = await dirHandle.getDirectoryHandle(pathParts[i]);
-                }
-                const fileHandle = await dirHandle.getFileHandle(pathParts[pathParts.length - 1]);
-                const file = await fileHandle.getFile();
-
-                attachments.push({
-                    path: path,
-                    data: file,
-                });
-            } catch (error) {
-                console.error(`Error retrieving attachment at "${path}": ${error.message}`);
-            }
+    _dispatch() {
+        if (this._locked || this._queue.length === 0) {
+            return;
         }
+        this._locked = true;
+        const resolve = this._queue.shift();
+        resolve(() => this.release());
+    }
+}
 
-        return attachments;
+/**
+ * Custom error class for LacertaDB
+ */
+class LacertaDBError extends Error {
+    constructor(message, code, originalError) {
+        super(message);
+        this.name = 'LacertaDBError';
+        this.code = code;
+        this.originalError = originalError || null;
+        this.timestamp = new Date().toISOString();
     }
+}
 
-    static async deleteAttachments(dbName, collectionName, documentId) {
-        const rootHandle = await navigator.storage.getDirectory();
-        const pathParts = [dbName, collectionName, documentId];
+// ========================
+// Compression Utility
+// ========================
 
-        let dirHandle = rootHandle;
-        for (let i = 0; i < pathParts.length - 1; i++) {
-            dirHandle = await dirHandle.getDirectoryHandle(pathParts[i]);
+class BrowserCompressionUtility {
+    async compress(input) {
+        if (!(input instanceof Uint8Array)) {
+            throw new TypeError('Input must be Uint8Array');
+        }
+        try {
+            const stream = new Response(input).body
+                .pipeThrough(new CompressionStream('deflate'));
+            const compressed = await new Response(stream).arrayBuffer();
+            return new Uint8Array(compressed);
+        } catch (error) {
+            throw new LacertaDBError('Compression failed', 'COMPRESSION_FAILED', error);
         }
+    }
 
+    async decompress(compressedData) {
+        if (!(compressedData instanceof Uint8Array)) {
+            throw new TypeError('Input must be Uint8Array');
+        }
         try {
-            await dirHandle.removeEntry(pathParts[pathParts.length - 1], { recursive: true });
+            const stream = new Response(compressedData).body
+                .pipeThrough(new DecompressionStream('deflate'));
+            const decompressed = await new Response(stream).arrayBuffer();
+            return new Uint8Array(decompressed);
         } catch (error) {
-            console.error(`Error deleting attachments for document "${documentId}": ${error.message}`);
+            throw new LacertaDBError('Decompression failed', 'DECOMPRESSION_FAILED', error);
         }
     }
 
-    toString() {
-        return '[OPFSUtility]';
+    // Fallback sync methods are simple pass-throughs
+    compressSync(input) {
+        if (!(input instanceof Uint8Array)) {
+            throw new TypeError('Input must be Uint8Array');
+        }
+        return input;
     }
-}
 
-class BrowserCompressionUtility {
-    static async compress(input) {
-        const data = typeof input === "string" ? new TextEncoder().encode(input) : input;
-        const stream = new CompressionStream('deflate');
-        const writer = stream.writable.getWriter();
+    decompressSync(compressedData) {
+        if (!(compressedData instanceof Uint8Array)) {
+            throw new TypeError('Input must be Uint8Array');
+        }
+        return compressedData;
+    }
+}
 
-        writer.write(data);
-        writer.close();
+// ========================
+// Encryption Utility (FIXED & IMPROVED)
+// ========================
 
-        return await this._streamToUint8Array(stream.readable);
-    }
+class BrowserEncryptionUtility {
+    async encrypt(data, password) {
+        if (!(data instanceof Uint8Array)) {
+            throw new TypeError('Data must be Uint8Array');
+        }
+        try {
+            const salt = crypto.getRandomValues(new Uint8Array(16));
+            const iv = crypto.getRandomValues(new Uint8Array(12));
 
-    static async decompress(compressedData) {
-        const stream = new DecompressionStream('deflate');
-        const writer = stream.writable.getWriter();
+            const keyMaterial = await crypto.subtle.importKey(
+                'raw',
+                new TextEncoder().encode(password),
+                'PBKDF2',
+                false,
+                ['deriveKey']
+            );
 
-        writer.write(compressedData);
-        writer.close();
+            const key = await crypto.subtle.deriveKey({
+                    name: 'PBKDF2',
+                    salt,
+                    iterations: 600000,
+                    hash: 'SHA-512'
+                },
+                keyMaterial, {
+                    name: 'AES-GCM',
+                    length: 256
+                },
+                false,
+                ['encrypt']
+            );
 
-        return await this._streamToUint8Array(stream.readable);
-    }
+            const encrypted = await crypto.subtle.encrypt({
+                    name: 'AES-GCM',
+                    iv
+                },
+                key,
+                data
+            );
 
-    static async _streamToUint8Array(readableStream) {
-        const reader = readableStream.getReader();
-        const chunks = [];
-        let totalLength = 0;
+            // The checksum was removed as AES-GCM provides this via an authentication tag.
+            const result = new Uint8Array(salt.length + iv.length + encrypted.byteLength);
+            result.set(salt, 0);
+            result.set(iv, salt.length);
+            result.set(new Uint8Array(encrypted), salt.length + iv.length);
 
-        while (true) {
-            const { value, done } = await reader.read();
-            if (done) break;
-            chunks.push(value);
-            totalLength += value.length;
+            return result;
+        } catch (error) {
+            throw new LacertaDBError('Encryption failed', 'ENCRYPTION_FAILED', error);
         }
+    }
 
-        const result = new Uint8Array(totalLength);
-        let offset = 0;
-        for (const chunk of chunks) {
-            result.set(chunk, offset);
-            offset += chunk.length;
+    async decrypt(wrappedData, password) {
+        if (!(wrappedData instanceof Uint8Array)) {
+            throw new TypeError('Data must be Uint8Array');
         }
+        try {
+            const salt = wrappedData.slice(0, 16);
+            const iv = wrappedData.slice(16, 28);
+            const encryptedData = wrappedData.slice(28);
+
+            const keyMaterial = await crypto.subtle.importKey(
+                'raw',
+                new TextEncoder().encode(password),
+                'PBKDF2',
+                false,
+                ['deriveKey']
+            );
 
-        return result;
-    }
+            const key = await crypto.subtle.deriveKey({
+                    name: 'PBKDF2',
+                    salt,
+                    iterations: 600000,
+                    hash: 'SHA-512'
+                },
+                keyMaterial, {
+                    name: 'AES-GCM',
+                    length: 256
+                },
+                false,
+                ['decrypt']
+            );
 
-    toString() {
-        return '[BrowserCompressionUtility]';
+            const decrypted = await crypto.subtle.decrypt({
+                    name: 'AES-GCM',
+                    iv
+                },
+                key,
+                encryptedData
+            );
+
+            // Checksum verification removed. crypto.subtle.decrypt will throw on failure.
+            return new Uint8Array(decrypted);
+        } catch (error) {
+            // Provide a more specific error for failed decryption, which often indicates a wrong password.
+            throw new LacertaDBError('Decryption failed. This may be due to an incorrect password or corrupted data.', 'DECRYPTION_FAILED', error);
+        }
     }
 }
 
-class BrowserEncryptionUtility {
-    static async encrypt(data, password) {
-        const salt = crypto.getRandomValues(new Uint8Array(16));
-        const key = await this._deriveKey(password, salt);
-        const iv = crypto.getRandomValues(new Uint8Array(12));
-        const checksum = await this._generateChecksum(data);
-        const combinedData = this._combineDataAndChecksum(data, checksum);
-
-        const encryptedData = await crypto.subtle.encrypt(
-            { name: "AES-GCM", iv: iv },
-            key,
-            combinedData
-        );
-
-        return this._wrapIntoUint8Array(salt, iv, new Uint8Array(encryptedData));
-    }
-
-    static async decrypt(wrappedData, password) {
-        const { salt, iv, encryptedData } = this._unwrapUint8Array(wrappedData);
-        const key = await this._deriveKey(password, salt);
-
-        const decryptedData = await crypto.subtle.decrypt(
-            { name: "AES-GCM", iv: iv },
-            key,
-            encryptedData
-        );
-
-        const decryptedUint8Array = new Uint8Array(decryptedData);
-        const { data, checksum } = this._separateDataAndChecksum(decryptedUint8Array);
-
-        const validChecksum = await this._generateChecksum(data);
-        if (!this._verifyChecksum(validChecksum, checksum)) {
-            throw new Error("Data integrity check failed. The data has been tampered with.");
-        }
-
-        return data;
-    }
-
-    static async _deriveKey(password, salt) {
-        const encoder = new TextEncoder();
-        const keyMaterial = await crypto.subtle.importKey(
-            "raw",
-            encoder.encode(password),
-            { name: "PBKDF2" },
-            false,
-            ["deriveKey"]
-        );
-
-        return await crypto.subtle.deriveKey(
-            {
-                name: "PBKDF2",
-                salt: salt,
-                iterations: 600000,
-                hash: "SHA-512"
-            },
-            keyMaterial,
-            {
-                name: "AES-GCM",
-                length: 256
-            },
-            false,
-            ["encrypt", "decrypt"]
-        );
-    }
+// ========================
+// OPFS (Origin Private File System) Utility
+// ========================
 
-    static async _generateChecksum(data) {
-        return new Uint8Array(
-            await crypto.subtle.digest("SHA-256", data)
-        );
-    }
+class OPFSUtility {
+    async saveAttachments(dbName, collectionName, documentId, attachments) {
+        try {
+            const attachmentPaths = [];
+            const root = await navigator.storage.getDirectory();
+            const dbDir = await root.getDirectoryHandle(dbName, { create: true });
+            const collDir = await dbDir.getDirectoryHandle(collectionName, { create: true });
+            const docDir = await collDir.getDirectoryHandle(documentId, { create: true });
+
+            for (const [index, attachment] of attachments.entries()) {
+                const filename = `${index}_${attachment.name || 'file'}`;
+                const fileHandle = await docDir.getFileHandle(filename, { create: true });
+                const writable = await fileHandle.createWritable();
+
+                let dataToWrite;
+                if (attachment.data instanceof Uint8Array) {
+                    dataToWrite = attachment.data;
+                } else if (attachment.data instanceof ArrayBuffer) {
+                    dataToWrite = new Uint8Array(attachment.data);
+                } else if (attachment.data instanceof Blob) {
+                    dataToWrite = new Uint8Array(await attachment.data.arrayBuffer());
+                } else {
+                    throw new TypeError('Unsupported attachment data type');
+                }
 
-    static _verifyChecksum(generatedChecksum, originalChecksum) {
-        if (generatedChecksum.length !== originalChecksum.length) return false;
-        for (let i = 0; i < generatedChecksum.length; i++) {
-            if (generatedChecksum[i] !== originalChecksum[i]) {
-                return false;
+                const blob = new Blob([dataToWrite], { type: attachment.type || 'application/octet-stream' });
+                await writable.write(blob);
+                await writable.close();
+
+                const path = `/${dbName}/${collectionName}/${documentId}/${filename}`;
+                attachmentPaths.push({
+                    path,
+                    name: attachment.name,
+                    type: attachment.type,
+                    size: dataToWrite.byteLength,
+                    originalName: attachment.originalName || attachment.name
+                });
             }
+            return attachmentPaths;
+        } catch (error) {
+            throw new LacertaDBError('Failed to save attachments', 'ATTACHMENT_SAVE_FAILED', error);
         }
-        return true;
     }
 
-    static _combineDataAndChecksum(data, checksum) {
-        const combined = new Uint8Array(data.length + checksum.length);
-        combined.set(data);
-        combined.set(checksum, data.length);
-        return combined;
-    }
+    async getAttachments(attachmentPaths) {
+        const attachments = [];
+        const root = await navigator.storage.getDirectory();
 
-    static _separateDataAndChecksum(combinedData) {
-        const dataLength = combinedData.length - 32;
-        const data = combinedData.slice(0, dataLength);
-        const checksum = combinedData.slice(dataLength);
-        return { data, checksum };
-    }
+        for (const attachmentInfo of attachmentPaths) {
+            try {
+                const pathParts = attachmentInfo.path.split('/').filter(p => p);
+                let currentDir = root;
 
-    static _wrapIntoUint8Array(salt, iv, encryptedData) {
-        const result = new Uint8Array(salt.length + iv.length + encryptedData.length);
-        result.set(salt, 0);
-        result.set(iv, salt.length);
-        result.set(encryptedData, salt.length + iv.length);
-        return result;
+                for (let i = 0; i < pathParts.length - 1; i++) {
+                    currentDir = await currentDir.getDirectoryHandle(pathParts[i]);
+                }
+
+                const fileHandle = await currentDir.getFileHandle(pathParts[pathParts.length - 1]);
+                const file = await fileHandle.getFile();
+                const data = await file.arrayBuffer();
+
+                attachments.push({
+                    name: attachmentInfo.originalName || attachmentInfo.name,
+                    type: attachmentInfo.type,
+                    data: new Uint8Array(data),
+                    size: attachmentInfo.size
+                });
+            } catch (error) {
+                console.error(`Failed to get attachment: ${attachmentInfo.path}`, error);
+                // Optionally, collect errors and return them
+            }
+        }
+        return attachments;
     }
 
-    static _unwrapUint8Array(wrappedData) {
-        const salt = wrappedData.slice(0, 16);
-        const iv = wrappedData.slice(16, 28);
-        const encryptedData = wrappedData.slice(28);
-        return { salt, iv, encryptedData };
+    async deleteAttachments(dbName, collectionName, documentId) {
+        try {
+            const root = await navigator.storage.getDirectory();
+            const dbDir = await root.getDirectoryHandle(dbName);
+            const collDir = await dbDir.getDirectoryHandle(collectionName);
+            await collDir.removeEntry(documentId, { recursive: true });
+        } catch (error) {
+            // Ignore "NotFoundError" as the directory might already be gone
+            if (error.name !== 'NotFoundError') {
+                console.error(`Failed to delete attachments for ${documentId}:`, error);
+            }
+        }
     }
 
-    toString() {
-        return '[BrowserEncryptionUtility]';
+    static async prepareAttachment(file, name) {
+        let data;
+        if (file instanceof File || file instanceof Blob) {
+            const buffer = await file.arrayBuffer();
+            data = new Uint8Array(buffer);
+        } else if (file instanceof ArrayBuffer) {
+            data = new Uint8Array(file);
+        } else if (file instanceof Uint8Array) {
+            data = file;
+        } else {
+            throw new TypeError('Unsupported file type for attachment');
+        }
+
+        return {
+            name: name || file.name || 'unnamed',
+            type: file.type || 'application/octet-stream',
+            data,
+            originalName: file.name || name
+        };
     }
 }
 
-class IndexedDBUtility {
-    static openDatabase(dbName, version = null, upgradeCallback = null) {
-        return new Promise((resolve, reject) => {
-            let request;
+// ========================
+// IndexedDB Utility
+// ========================
 
-            if (version) {
-                request = indexedDB.open(dbName, version);
-            } else {
-                request = indexedDB.open(dbName);
-            }
+class IndexedDBUtility {
+    constructor() {
+        this.mutex = new AsyncMutex();
+    }
 
-            request.onupgradeneeded = (event) => {
-                const db = event.target.result;
-                const oldVersion = event.oldVersion;
-                const newVersion = event.newVersion;
-                console.log(`Upgrading database "${dbName}" from version ${oldVersion} to ${newVersion}`);
+    openDatabase(dbName, version = 1, upgradeCallback) {
+        return new Promise((resolve, reject) => {
+            const request = indexedDB.open(dbName, version);
 
+            request.onerror = () => reject(new LacertaDBError(
+                'Failed to open database', 'DATABASE_OPEN_FAILED', request.error
+            ));
+            request.onsuccess = () => resolve(request.result);
+            request.onupgradeneeded = event => {
                 if (upgradeCallback) {
-                    upgradeCallback(db, oldVersion, newVersion);
+                    upgradeCallback(event.target.result, event.oldVersion, event.newVersion);
                 }
             };
-
-            request.onsuccess = (event) => {
-                const db = event.target.result;
-
-                db.onclose = () => {
-                    console.log(`Database "${dbName}" connection is closing.`);
-                };
-
-                resolve(db);
-            };
-
-            request.onerror = (event) => {
-                reject(new Error(`Failed to open database "${dbName}": ${event.target.error.message}`));
-            };
         });
     }
 
-    // Improved transaction handling with better retry logic
-    static async performTransaction(db, storeNames, mode, callback, retries = 3, operationId = null) {
-        let lastError = null;
-
-        for (let attempt = 0; attempt <= retries; attempt++) {
-            try {
-                if (!db || db.readyState !== 'done') {
-                    throw new Error('Database connection is not available or ready.');
-                }
-
-                const tx = db.transaction(Array.isArray(storeNames) ? storeNames : [storeNames], mode);
-                const stores = Array.isArray(storeNames)
-                    ? storeNames.map(name => tx.objectStore(name))
-                    : [tx.objectStore(storeNames)];
+    async performTransaction(db, storeNames, mode, callback, retries = 3) {
+        return this.mutex.runExclusive(async () => {
+            let lastError;
+            for (let i = 0; i < retries; i++) {
+                try {
+                    return await new Promise((resolve, reject) => {
+                        const transaction = db.transaction(storeNames, mode);
+                        let result;
 
-                // Add transaction timeout
-                const timeoutId = setTimeout(() => {
-                    tx.abort();
-                }, 30000); // 30 second timeout
+                        transaction.oncomplete = () => resolve(result);
+                        transaction.onerror = () => reject(transaction.error);
+                        transaction.onabort = () => reject(new Error('Transaction aborted'));
 
-                const result = await callback(...stores, operationId);
-
-                return new Promise((resolve, reject) => {
-                    tx.oncomplete = () => {
-                        clearTimeout(timeoutId);
-                        resolve(result);
-                    };
-                    tx.onerror = () => {
-                        clearTimeout(timeoutId);
-                        lastError = new Error(`Transaction failed: ${tx.error ? tx.error.message : 'unknown error'}`);
-                        reject(lastError);
-                    };
-                    tx.onabort = () => {
-                        clearTimeout(timeoutId);
-                        lastError = new Error(`Transaction aborted: ${tx.error ? tx.error.message : 'timeout or abort'}`);
-                        reject(lastError);
-                    };
-                });
-            } catch (error) {
-                lastError = error;
-                if (attempt < retries) {
-                    console.warn(`Transaction failed, retrying... (${retries - attempt} attempts left): ${error.message}`);
-                    // Exponential backoff with jitter
-                    const delay = Math.pow(2, attempt) * 100 + Math.random() * 100;
-                    await new Promise(resolve => setTimeout(resolve, delay));
+                        try {
+                            const cbResult = callback(transaction);
+                            if (cbResult instanceof Promise) {
+                                cbResult.then(res => { result = res; }).catch(reject);
+                            } else {
+                                result = cbResult;
+                            }
+                        } catch (error) {
+                            reject(error);
+                        }
+                    });
+                } catch (error) {
+                    lastError = error;
+                    if (i < retries - 1) {
+                        await new Promise(resolve => setTimeout(resolve, (2 ** i) * 100));
+                    }
                 }
             }
-        }
-
-        throw new Error(`Transaction ultimately failed after ${retries + 1} attempts: ${lastError.message}`);
-    }
-
-    static add(store, record) {
-        return new Promise((resolve, reject) => {
-            const request = store.add(record);
-            request.onsuccess = () => resolve();
-            request.onerror = event => reject(`Failed to insert record: ${event.target.error.message}`);
+            throw new LacertaDBError('Transaction failed after retries', 'TRANSACTION_FAILED', lastError);
         });
     }
 
-    static put(store, record) {
+    _promisifyRequest(requestFactory) {
         return new Promise((resolve, reject) => {
-            const request = store.put(record);
-            request.onsuccess = () => resolve();
-            request.onerror = event => reject(`Failed to put record: ${event.target.error.message}`);
+            const request = requestFactory();
+            request.onsuccess = () => resolve(request.result);
+            request.onerror = () => reject(request.error);
         });
     }
 
-    static delete(store, key) {
-        return new Promise((resolve, reject) => {
-            const request = store.delete(key);
-            request.onsuccess = () => resolve();
-            request.onerror = event => reject(`Failed to delete record: ${event.target.error.message}`);
+    add(db, storeName, value, key) {
+        return this.performTransaction(db, [storeName], 'readwrite', tx => {
+            const store = tx.objectStore(storeName);
+            return this._promisifyRequest(() => key !== undefined ? store.add(value, key) : store.add(value));
         });
     }
 
-    static get(store, key) {
-        return new Promise((resolve, reject) => {
-            const request = store.get(key);
-            request.onsuccess = event => resolve(event.target.result);
-            request.onerror = event => reject(`Failed to retrieve record with key ${key}: ${event.target.error.message}`);
+    put(db, storeName, value, key) {
+        return this.performTransaction(db, [storeName], 'readwrite', tx => {
+            const store = tx.objectStore(storeName);
+            return this._promisifyRequest(() => key !== undefined ? store.put(value, key) : store.put(value));
         });
     }
 
-    static getAll(store) {
-        return new Promise((resolve, reject) => {
-            const request = store.getAll();
-            request.onsuccess = event => resolve(event.target.result);
-            request.onerror = event => reject(`Failed to retrieve records: ${event.target.error.message}`);
+    get(db, storeName, key) {
+        return this.performTransaction(db, [storeName], 'readonly', tx => {
+            return this._promisifyRequest(() => tx.objectStore(storeName).get(key));
         });
     }
 
-    static count(store) {
-        return new Promise((resolve, reject) => {
-            const request = store.count();
-            request.onsuccess = event => resolve(event.target.result);
-            request.onerror = event => reject(`Failed to count records: ${event.target.error.message}`);
+    getAll(db, storeName, query, count) {
+        return this.performTransaction(db, [storeName], 'readonly', tx => {
+            return this._promisifyRequest(() => tx.objectStore(storeName).getAll(query, count));
         });
     }
 
-    static clear(store) {
-        return new Promise((resolve, reject) => {
-            const request = store.clear();
-            request.onsuccess = () => resolve();
-            request.onerror = event => reject(`Failed to clear store: ${event.target.error.message}`);
+    delete(db, storeName, key) {
+        return this.performTransaction(db, [storeName], 'readwrite', tx => {
+            return this._promisifyRequest(() => tx.objectStore(storeName).delete(key));
         });
     }
 
-    static deleteDatabase(dbName) {
-        return new Promise((resolve, reject) => {
-            const request = indexedDB.deleteDatabase(dbName);
-            request.onsuccess = () => resolve();
-            request.onerror = event => reject(`Failed to delete database: ${event.target.error.message}`);
+    clear(db, storeName) {
+        return this.performTransaction(db, [storeName], 'readwrite', tx => {
+            return this._promisifyRequest(() => tx.objectStore(storeName).clear());
         });
     }
 
-    static iterateCursor(store, processCallback) {
-        return new Promise((resolve, reject) => {
-            const request = store.openCursor();
-            request.onsuccess = event => {
-                const cursor = event.target.result;
-                if (cursor) {
-                    processCallback(cursor.value, cursor.key);
-                    cursor.continue();
-                } else {
-                    resolve();
-                }
-            };
-            request.onerror = event => reject(`Cursor iteration failed: ${event.target.error.message}`);
+    count(db, storeName, query) {
+        return this.performTransaction(db, [storeName], 'readonly', tx => {
+            return this._promisifyRequest(() => tx.objectStore(storeName).count(query));
         });
     }
-    
-    static iterateCursorSafe(store, processCallback, options = {}) {
-        return new Promise((resolve, reject) => {
-            const {
-                index = null,
-                direction = 'next',
-                range = null
-            } = options;
-
-            let source = store;
-            if (index && store.indexNames.contains(index)) {
-                source = store.index(index);
-            }
 
-            const request = source.openCursor(range, direction);
-            const results = [];
-            
-            request.onsuccess = (event) => {
-                const cursor = event.target.result;
-                
-                if (cursor) {
-                    // FIXED: No async operations in cursor callback
-                    const shouldContinue = processCallback(cursor.value, cursor.key, results);
-                    
-                    if (shouldContinue !== false) {
-                        cursor.continue();
+    iterateCursorSafe(db, storeName, callback, direction = 'next', query) {
+        return this.performTransaction(db, [storeName], 'readonly', tx => {
+            return new Promise((resolve, reject) => {
+                const results = [];
+                const request = tx.objectStore(storeName).openCursor(query, direction);
+
+                request.onsuccess = event => {
+                    const cursor = event.target.result;
+                    if (cursor) {
+                        try {
+                            const result = callback(cursor.value, cursor.key);
+                            if (result !== false) {
+                                results.push(result);
+                                cursor.continue();
+                            } else {
+                                resolve(results);
+                            }
+                        } catch (error) {
+                            reject(error);
+                        }
                     } else {
                         resolve(results);
                     }
-                } else {
-                    resolve(results);
-                }
-            };
-            
-            request.onerror = () => reject(request.error);
+                };
+                request.onerror = () => reject(request.error);
+            });
         });
     }
-
-    toString() {
-        return '[IndexedDBUtility]';
-    }
 }
 
-class LocalStorageUtility {
-    static getItem(key) {
-        const value = localStorage.getItem(key);
-        return value ? TURBO.serialize(value) : null;
-    }
-
-    static setItem(key, value) {
-        localStorage.setItem(key, TURBO.serialize(value));
-    }
-
-    static removeItem(key) {
-        localStorage.removeItem(key);
-    }
+// ========================
+// Document Class
+// ========================
 
-    static clear() {
-        localStorage.clear();
-    }
+class Document {
+    constructor(data = {}, options = {}) {
+        this._id = data._id || this.generateId();
+        this._created = data._created || Date.now();
+        this._modified = data._modified || Date.now();
+        this._permanent = data._permanent || options.permanent || false;
+        this._encrypted = data._encrypted || options.encrypted || false;
+        this._compressed = data._compressed || options.compressed || false;
+        this._attachments = data._attachments || [];
+        this.data = data.data || {};
+        this.packedData = data.packedData || null;
 
-    toString() {
-        return '[LocalStorageUtility]';
+        // Utilities can be passed in or instantiated. For simplicity, we keep instantiation here.
+        this.compression = new BrowserCompressionUtility();
+        this.encryption = new BrowserEncryptionUtility();
+        this.password = options.password || null;
     }
-}
 
-class AsyncMutex {
-    constructor() {
-        this.queue = [];
-        this.locked = false;
+    generateId() {
+        return `doc_${Date.now()}_${Math.random().toString(36).substring(2, 11)}`;
     }
 
-    async acquire() {
-        return new Promise((resolve) => {
-            if (!this.locked) {
-                this.locked = true;
-                resolve();
-            } else {
-                this.queue.push(resolve);
+    async pack() {
+        try {
+            let packed = serializer.serialize(this.data);
+            if (this._compressed) {
+                packed = await this.compression.compress(packed);
             }
-        });
-    }
-
-    release() {
-        if (this.queue.length > 0) {
-            const next = this.queue.shift();
-            next();
-        } else {
-            this.locked = false;
+            if (this._encrypted && this.password) {
+                packed = await this.encryption.encrypt(packed, this.password);
+            }
+            this.packedData = packed;
+            return packed;
+        } catch (error) {
+            throw new LacertaDBError('Failed to pack document', 'PACK_FAILED', error);
         }
     }
 
-    async runExclusive(callback) {
-        await this.acquire();
+    async unpack() {
         try {
-            return await callback();
-        } finally {
-            this.release();
-        }
-    }
-
-    toString() {
-        return `[AsyncMutex locked:${this.locked} queue:${this.queue.length}]`;
-    }
-}
-
-class DatabaseMetadata {
-    constructor(dbName) {
-        this._dbName = dbName;
-        this._metadataKey = `lacertadb_${this._dbName}_metadata`;
-        this._collections = new Map();
-        this._metadata = this._loadMetadata();
-        this._mutex = new AsyncMutex();
-    }
-
-    async saveMetadata() {
-        return await this._mutex.runExclusive(() => {
-            LocalStorageUtility.setItem(this.metadataKey, this.getRawMetadata());
-        });
-    }
-
-    async adjustTotals(sizeKBChange, lengthChange) {
-        return await this._mutex.runExclusive(() => {
-            this.data.totalSizeKB += sizeKBChange;
-            this.data.totalLength += lengthChange;
-            this.data.modifiedAt = Date.now();
-        });
-    }
-
-    _loadMetadata() {
-        const metadata = LocalStorageUtility.getItem(this.metadataKey);
-        if (metadata) {
-            for (const collectionName in metadata.collections) {
-                const collectionData = metadata.collections[collectionName];
-                const collectionMetadata = new CollectionMetadata(collectionName, this, collectionData);
-                this.collections.set(collectionName, collectionMetadata);
+            let unpacked = this.packedData;
+            if (this._encrypted && this.password) {
+                unpacked = await this.encryption.decrypt(unpacked, this.password);
             }
-            return metadata;
-        } else {
-            return {
-                name: this._dbName,
-                collections: {},
-                totalSizeKB: 0,
-                totalLength: 0,
-                modifiedAt: Date.now(),
-            };
+            if (this._compressed) {
+                unpacked = await this.compression.decompress(unpacked);
+            }
+            this.data = serializer.deserialize(unpacked);
+            return this.data;
+        } catch (error) {
+            throw new LacertaDBError('Failed to unpack document', 'UNPACK_FAILED', error);
         }
     }
 
-    get data() {
-        return this._metadata;
-    }
-
-    set data(d) {
-        this._metadata = d;
-    }
-
-    get name() {
-        return this.data.name;
-    }
-
-    get metadataKey() {
-        return this._metadataKey;
-    }
-
-    get collections() {
-        return this._collections;
-    }
-
-    set collections(c) {
-        this._collections = c;
-    }
-
-    get totalSizeKB() {
-        return this.data.totalSizeKB;
-    }
-
-    get totalLength() {
-        return this.data.totalLength;
-    }
-
-    get modifiedAt() {
-        return this.data.modifiedAt;
-    }
-
-    getCollectionMetadata(collectionName) {
-        if (!this.collections.has(collectionName)) {
-            const collectionMetadata = new CollectionMetadata(collectionName, this);
-            this.collections.set(collectionName, collectionMetadata);
-            this.data.collections[collectionName] = collectionMetadata.getRawMetadata();
-            this.data.modifiedAt = Date.now();
+    packSync() {
+        let packed = serializer.serialize(this.data);
+        if (this._compressed) {
+            packed = this.compression.compressSync(packed);
         }
-        return this.collections.get(collectionName);
-    }
-
-    getCollectionMetadataData(collectionName) {
-        const metadata = this.getCollectionMetadata(collectionName);
-        return metadata ? metadata.getRawMetadata(): {}
-    }
-
-    removeCollectionMetadata(collectionName) {
-        const collectionMetadata = this.collections.get(collectionName);
-        if (collectionMetadata) {
-            this.data.totalSizeKB -= collectionMetadata.sizeKB;
-            this.data.totalLength -= collectionMetadata.length;
-            this.collections.delete(collectionName);
-            delete this.data.collections[collectionName];
-            this.data.modifiedAt = Date.now();
+        if (this._encrypted) {
+            throw new LacertaDBError('Synchronous encryption not supported', 'SYNC_ENCRYPT_NOT_SUPPORTED');
         }
+        this.packedData = packed;
+        return packed;
     }
 
-    getCollectionNames() {
-        return Array.from(this.collections.keys());
-    }
-
-    getRawMetadata() {
-        for (const [collectionName, collectionMetadata] of this._collections.entries()) {
-            this.data.collections[collectionName] = collectionMetadata.getRawMetadata();
+    unpackSync() {
+        let unpacked = this.packedData;
+        if (this._encrypted) {
+            throw new LacertaDBError('Synchronous decryption not supported', 'SYNC_DECRYPT_NOT_SUPPORTED');
+        }
+        if (this._compressed) {
+            unpacked = this.compression.decompressSync(unpacked);
         }
+        this.data = serializer.deserialize(unpacked);
         return this.data;
     }
 
-    setRawMetadata(metadata) {
-        this._metadata = metadata;
-        this._collections.clear();
-        for (const collectionName in metadata.collections) {
-            const collectionData = metadata.collections[collectionName];
-            const collectionMetadata = new CollectionMetadata(collectionName, this, collectionData);
-            this._collections.set(collectionName, collectionMetadata);
+    objectOutput(includeAttachments = false) {
+        const output = {
+            _id: this._id,
+            _created: this._created,
+            _modified: this._modified,
+            _permanent: this._permanent,
+            ...this.data
+        };
+        if (includeAttachments && this._attachments.length > 0) {
+            output._attachments = this._attachments;
         }
+        return output;
     }
 
-    get dbName() {
-        return this._dbName;
-    }
-
-    get key() {
-        return this._metadataKey;
-    }
-
-    toString() {
-        return `[DatabaseMetadata: ${this.name} | Collections: ${this.collections.size} | Size: ${this.totalSizeKB.toFixed(2)}KB | Documents: ${this.totalLength}]`;
-    }
-}
-
-class LacertaDBError extends Error {
-    constructor(message, code, originalError = null) {
-        super(message);
-        this.name = 'LacertaDBError';
-        this.code = code;
-        this.originalError = originalError;
-        this.timestamp = Date.now();
-    }
-
-    toString() {
-        return `[LacertaDBError ${this.code}: ${this.message} at ${new Date(this.timestamp).toISOString()}]`;
+    databaseOutput() {
+        return {
+            _id: this._id,
+            _created: this._created,
+            _modified: this._modified,
+            _permanent: this._permanent,
+            _encrypted: this._encrypted,
+            _compressed: this._compressed,
+            _attachments: this._attachments,
+            packedData: this.packedData
+        };
     }
 }
 
-const ErrorCodes = {
-    ATTACHMENT_DELETE_FAILED: 'ATTACHMENT_DELETE_FAILED',
-    METADATA_SYNC_FAILED: 'METADATA_SYNC_FAILED',
-    TRANSACTION_FAILED: 'TRANSACTION_FAILED',
-    ENCRYPTION_FAILED: 'ENCRYPTION_FAILED',
-    QUOTA_EXCEEDED: 'QUOTA_EXCEEDED',
-    INVALID_OPERATION: 'INVALID_OPERATION',
-    DOCUMENT_NOT_FOUND: 'DOCUMENT_NOT_FOUND',
-    COLLECTION_NOT_FOUND: 'COLLECTION_NOT_FOUND',
-    COLLECTION_EXISTS: 'COLLECTION_EXISTS'
-};
+// ========================
+// Metadata Classes
+// ========================
 
 class CollectionMetadata {
-    constructor(collectionName, databaseMetadata, existingMetadata = null) {
-        this._collectionName = collectionName;
-        this._databaseMetadata = databaseMetadata;
-
-        if (existingMetadata) {
-            this._metadata = existingMetadata;
-        } else {
-            this._metadata = {
-                name: collectionName,
-                sizeKB: 0,
-                length: 0,
-                createdAt: Date.now(),
-                modifiedAt: Date.now(),
-                documentSizes: {},
-                documentModifiedAt: {},
-                documentPermanent: {},
-                documentAttachments: {},
-            };
-            this._databaseMetadata.data.collections[collectionName] = this._metadata;
-            this._databaseMetadata.data.modifiedAt = Date.now();
-        }
-    }
-
-    get name() {
-        return this._collectionName;
-    }
-
-    get keys() {
-        return Object.keys(this.documentSizes);
-    }
-
-    get collectionName() {
-        return this.name;
-    }
-
-    get sizeKB() {
-        return this._metadata.sizeKB;
-    }
-
-    get length() {
-        return this._metadata.length;
-    }
-
-    get modifiedAt() {
-        return this._metadata.modifiedAt;
-    }
-
-    get metadata() {
-        return this._metadata;
-    }
-
-    set metadata(m) {
-        return this._metadata = m;
-    }
-
-    get data() {
-        return this.metadata;
-    }
-
-    set data(m) {
-        this.metadata = m;
-    }
-
-    get databaseMetadata() {
-        return this._databaseMetadata;
-    }
+    constructor(name, data = {}) {
+        this.name = name;
+        this.sizeKB = data.sizeKB || 0;
+        this.length = data.length || 0;
+        this.createdAt = data.createdAt || Date.now();
+        this.modifiedAt = data.modifiedAt || Date.now();
+        this.documentSizes = data.documentSizes || {};
+        this.documentModifiedAt = data.documentModifiedAt || {};
+        this.documentPermanent = data.documentPermanent || {};
+        this.documentAttachments = data.documentAttachments || {};
+    }
+
+    addDocument(docId, sizeKB, isPermanent, attachmentCount) {
+        this.documentSizes[docId] = sizeKB;
+        this.documentModifiedAt[docId] = Date.now();
+        if (isPermanent) this.documentPermanent[docId] = true;
+        if (attachmentCount > 0) this.documentAttachments[docId] = attachmentCount;
 
-    set databaseMetadata(m) {
-        this._databaseMetadata = m;
+        this.sizeKB += sizeKB;
+        this.length++;
+        this.modifiedAt = Date.now();
     }
 
-    get documentSizes(){return this.metadata.documentSizes;}
-    get documentModifiedAt(){return this.metadata.documentModifiedAt;}
-    get documentPermanent(){return this.metadata.documentPermanent;}
-    get documentAttachments(){return this.metadata.documentAttachments;}
-
-    set documentSizes(v){ this.metadata.documentSizes = v;}
-    set documentModifiedAt(v){ this.metadata.documentModifiedAt = v;}
-    set documentPermanent(v){ this.metadata.documentPermanent = v;}
-    set documentAttachments(v){ this.metadata.documentAttachments = v;}
-
-    updateDocument(docId, docSizeKB, isPermanent = false, attachmentCount = 0) {
-        const isNewDocument = !this.keys.includes(docId);
-        const previousDocSizeKB = this.documentSizes[docId] || 0;
-        const sizeKBChange = docSizeKB - previousDocSizeKB;
-        const lengthChange = isNewDocument ? 1 : 0;
-
-        this.documentSizes[docId] = docSizeKB;
+    updateDocument(docId, newSizeKB, isPermanent, attachmentCount) {
+        const oldSize = this.documentSizes[docId] || 0;
+        this.sizeKB = this.sizeKB - oldSize + newSizeKB;
+        this.documentSizes[docId] = newSizeKB;
         this.documentModifiedAt[docId] = Date.now();
-        this.documentPermanent[docId] = isPermanent ? 1 : 0;
-        this.documentAttachments[docId] = attachmentCount;
 
-        this.metadata.sizeKB += sizeKBChange;
-        this.metadata.length += lengthChange;
-        this.metadata.modifiedAt = Date.now();
-
-        this.databaseMetadata.adjustTotals(sizeKBChange, lengthChange);
-    }
+        if (isPermanent) {
+            this.documentPermanent[docId] = true;
+        } else {
+            delete this.documentPermanent[docId];
+        }
 
-    deleteDocument(docId) {
-        const docExists = docId in this.documentSizes;
-        if (!docExists) {
-            return false;
+        if (attachmentCount > 0) {
+            this.documentAttachments[docId] = attachmentCount;
+        } else {
+            delete this.documentAttachments[docId];
         }
 
-        const docSizeKB = this.documentSizes[docId];
+        this.modifiedAt = Date.now();
+    }
 
+    removeDocument(docId) {
+        const sizeKB = this.documentSizes[docId] || 0;
+        if (this.documentSizes[docId]) {
+            this.sizeKB -= sizeKB;
+            this.length--;
+        }
         delete this.documentSizes[docId];
         delete this.documentModifiedAt[docId];
         delete this.documentPermanent[docId];
         delete this.documentAttachments[docId];
-
-        this.metadata.sizeKB -= docSizeKB;
-        this.metadata.length -= 1;
-        this.metadata.modifiedAt = Date.now();
-
-        this.databaseMetadata.adjustTotals(-docSizeKB, -1);
-
-        return true;
-    }
-
-    updateDocuments(updates) {
-        for (const { docId, docSizeKB, isPermanent, attachmentCount } of updates) {
-            this.updateDocument(docId, docSizeKB, isPermanent, attachmentCount || 0);
-        }
-    }
-
-    getRawMetadata() {
-        return this.metadata;
-    }
-
-    setRawMetadata(metadata) {
-        this.metadata = metadata;
-    }
-
-    toString() {
-        return `[CollectionMetadata: ${this.name} | Size: ${this.sizeKB.toFixed(2)}KB | Documents: ${this.length}]`;
-    }
-}
-
-class LacertaDBResult {
-    constructor(success, data = null, error = null) {
-        this.success = success;
-        this.data = data;
-        this.error = error;
+        this.modifiedAt = Date.now();
     }
 
-    toString() {
-        return `[LacertaDBResult success:${this.success} ${this.error ? 'error:' + this.error : ''}]`;
+    getOldestNonPermanentDocuments(count) {
+        return Object.entries(this.documentModifiedAt)
+            .filter(([docId]) => !this.documentPermanent[docId])
+            .sort(([, timeA], [, timeB]) => timeA - timeB)
+            .slice(0, count)
+            .map(([docId]) => docId);
     }
 }
 
-class QuickStore {
-    constructor(dbName) {
-        this._dbName = dbName;
-        this._metadataKey = `lacertadb_${this._dbName}_quickstore_metadata`;
-        this._documentKeyPrefix = `lacertadb_${this._dbName}_quickstore_data_`;
-        this._metadata = this._loadMetadata();
-    }
-
-    _loadMetadata() {
-        const metadata = LocalStorageUtility.getItem(this._metadataKey);
-        if (metadata) {
-            return metadata;
-        } else {
-            return {
-                totalSizeKB: 0,
-                totalLength: 0,
-                documentSizesKB: {},
-                documentModificationTime: {},
-                documentPermanent: {},
-            };
+class DatabaseMetadata {
+    constructor(name, data = {}) {
+        this.name = name;
+        this.collections = data.collections || {};
+        this.totalSizeKB = data.totalSizeKB || 0;
+        this.totalLength = data.totalLength || 0;
+        this.modifiedAt = data.modifiedAt || Date.now();
+    }
+
+    static load(dbName) {
+        const key = `lacertadb_${dbName}_metadata`;
+        const stored = localStorage.getItem(key);
+        if (stored) {
+            try {
+                const decoded = base64.decode(stored);
+                const data = serializer.deserialize(decoded);
+                return new DatabaseMetadata(dbName, data);
+            } catch (e) {
+                console.error('Failed to load metadata:', e);
+            }
         }
+        return new DatabaseMetadata(dbName);
     }
 
-    _saveMetadata() {
-        LocalStorageUtility.setItem(this._metadataKey, this._metadata);
-    }
-
-    setDocumentSync(documentData, encryptionKey = null) {
-        const document = new Document(documentData, encryptionKey);
-        const packedData = document.packSync();
-        const docId = document._id;
-        const isPermanent = document._permanent || false;
-
-        const dataToStore = TURBO.serialize({
-            _id: document._id,
-            _created: document._created,
-            _modified: document._modified,
-            _permanent: isPermanent,
-            _encrypted: document._encrypted,
-            _compressed: document._compressed,
-            packedData: packedData,
-        });
-
-        const key = this._documentKeyPrefix + docId;
-        localStorage.setItem(key, dataToStore);
-
-        const dataSizeKB = dataToStore.length / 1024;
-
-        const isNewDocument = !(docId in this._metadata.documentSizesKB);
-
-        if (isNewDocument) {
-            this._metadata.totalLength += 1;
-        } else {
-            this._metadata.totalSizeKB -= this._metadata.documentSizesKB[docId];
+    save() {
+        const key = `lacertadb_${this.name}_metadata`;
+        try {
+            const dataToStore = {
+                collections: this.collections,
+                totalSizeKB: this.totalSizeKB,
+                totalLength: this.totalLength,
+                modifiedAt: this.modifiedAt
+            };
+            const serializedData = serializer.serialize(dataToStore);
+            const encodedData = base64.encode(serializedData);
+            localStorage.setItem(key, encodedData);
+        } catch (e) {
+            if (e.name === 'QuotaExceededError') {
+                throw new LacertaDBError('Storage quota exceeded for metadata', 'QUOTA_EXCEEDED', e);
+            }
+            throw new LacertaDBError('Failed to save metadata', 'METADATA_SAVE_FAILED', e);
         }
-
-        this._metadata.documentSizesKB[docId] = dataSizeKB;
-        this._metadata.documentModificationTime[docId] = document._modified;
-        this._metadata.documentPermanent[docId] = isPermanent;
-
-        this._metadata.totalSizeKB += dataSizeKB;
-
-        this._saveMetadata();
-
-        return isNewDocument;
     }
 
-    deleteDocumentSync(docId, force = false) {
-        const isPermanent = this._metadata.documentPermanent[docId] || false;
-        if (isPermanent && !force) {
-            return false;
-        }
-
-        const key = this._documentKeyPrefix + docId;
-        const docSizeKB = this._metadata.documentSizesKB[docId] || 0;
-
-        if (localStorage.getItem(key)) {
-            localStorage.removeItem(key);
-
-            delete this._metadata.documentSizesKB[docId];
-            delete this._metadata.documentModificationTime[docId];
-            delete this._metadata.documentPermanent[docId];
-
-            this._metadata.totalSizeKB -= docSizeKB;
-            this._metadata.totalLength -= 1;
-
-            this._saveMetadata();
-
-            return true;
-        } else {
-            return false;
-        }
+    setCollection(collectionMetadata) {
+        this.collections[collectionMetadata.name] = {
+            sizeKB: collectionMetadata.sizeKB,
+            length: collectionMetadata.length,
+            createdAt: collectionMetadata.createdAt,
+            modifiedAt: collectionMetadata.modifiedAt,
+            documentSizes: collectionMetadata.documentSizes,
+            documentModifiedAt: collectionMetadata.documentModifiedAt,
+            documentPermanent: collectionMetadata.documentPermanent,
+            documentAttachments: collectionMetadata.documentAttachments
+        };
+        this.recalculate();
+        this.save();
     }
 
-    getAllKeys() {
-        return Object.keys(this._metadata.documentSizesKB);
+    removeCollection(collectionName) {
+        delete this.collections[collectionName];
+        this.recalculate();
+        this.save();
     }
 
-    getDocumentSync(docId, encryptionKey = null) {
-        const key = this._documentKeyPrefix + docId;
-        const dataString = localStorage.getItem(key);
-
-        if (dataString) {
-            const docData = TURBO.serialize(dataString);
-            const document = new Document(docData, encryptionKey);
-            return document.unpackSync();
-        } else {
-            return null;
+    recalculate() {
+        this.totalSizeKB = 0;
+        this.totalLength = 0;
+        for (const collName in this.collections) {
+            const coll = this.collections[collName];
+            this.totalSizeKB += coll.sizeKB;
+            this.totalLength += coll.length;
         }
-    }
-
-    toString() {
-        return `[QuickStore: ${this._dbName} | Size: ${this._metadata.totalSizeKB.toFixed(2)}KB | Documents: ${this._metadata.totalLength}]`;
+        this.modifiedAt = Date.now();
     }
 }
 
-class TransactionManager {
-    constructor() {
-        this.queue = [];
-        this.processing = false;
-    }
-
-    async execute(operation) {
-        return new Promise((resolve, reject) => {
-            this.queue.push({ operation, resolve, reject });
-            this.process();
-        });
-    }
-
-    async process() {
-        if (this.processing || this.queue.length === 0) return;
-
-        this.processing = true;
-
-        while (this.queue.length > 0) {
-            const { operation, resolve, reject } = this.queue.shift();
-
+class Settings {
+    constructor(dbName, data = {}) {
+        this.dbName = dbName;
+        // Replaced `??` with ternary operator for compatibility
+        this.sizeLimitKB = data.sizeLimitKB != null ? data.sizeLimitKB : Infinity;
+        const defaultBuffer = this.sizeLimitKB === Infinity ? 0 : this.sizeLimitKB * 0.8;
+        this.bufferLimitKB = data.bufferLimitKB != null ? data.bufferLimitKB : defaultBuffer;
+        this.freeSpaceEvery = data.freeSpaceEvery || 10000;
+    }
+
+    static load(dbName) {
+        const key = `lacertadb_${dbName}_settings`;
+        const stored = localStorage.getItem(key);
+        if (stored) {
             try {
-                const result = await operation();
-                resolve(result);
-            } catch (error) {
-                reject(error);
+                const decoded = base64.decode(stored);
+                const data = serializer.deserialize(decoded);
+                return new Settings(dbName, data);
+            } catch (e) {
+                console.error('Failed to load settings:', e);
             }
         }
+        return new Settings(dbName);
+    }
 
-        this.processing = false;
+    save() {
+        const key = `lacertadb_${this.dbName}_settings`;
+        const dataToStore = {
+            sizeLimitKB: this.sizeLimitKB,
+            bufferLimitKB: this.bufferLimitKB,
+            freeSpaceEvery: this.freeSpaceEvery
+        };
+        const serializedData = serializer.serialize(dataToStore);
+        const encodedData = base64.encode(serializedData);
+        localStorage.setItem(key, encodedData);
     }
 
-    toString() {
-        return `[TransactionManager processing:${this.processing} queue:${this.queue.length}]`;
+    updateSettings(newSettings) {
+        Object.assign(this, newSettings);
+        this.save();
     }
 }
 
-class Observer {
-    constructor() {
-        this._listeners = {
-            'beforeAdd': [],
-            'afterAdd': [],
-            'beforeDelete': [],
-            'afterDelete': [],
-            'beforeGet': [],
-            'afterGet': [],
-        };
+// ========================
+// Quick Store (localStorage based)
+// ========================
+
+class QuickStore {
+    constructor(dbName) {
+        this.dbName = dbName;
+        this.keyPrefix = `lacertadb_${dbName}_quickstore_`;
+        this.indexKey = `${this.keyPrefix}index`;
     }
 
-    on(event, callback) {
-        if (this._listeners[event]) {
-            this._listeners[event].push(callback);
-        } else {
-            throw new Error(`Event "${event}" is not supported.`);
+    _readIndex() {
+        const indexStr = localStorage.getItem(this.indexKey);
+        if (!indexStr) return [];
+        try {
+            const decoded = base64.decode(indexStr);
+            return serializer.deserialize(decoded);
+        } catch {
+            return [];
         }
     }
 
-    off(event, callback) {
-        if (this._listeners[event]) {
-            const index = this._listeners[event].indexOf(callback);
-            if (index > -1) {
-                this._listeners[event].splice(index, 1);
-            }
-        }
+    _writeIndex(index) {
+        const serializedIndex = serializer.serialize(index);
+        const encodedIndex = base64.encode(serializedIndex);
+        localStorage.setItem(this.indexKey, encodedIndex);
     }
 
-    _emit(event, ...args) {
-        if (this._listeners[event]) {
-            for (const callback of this._listeners[event]) {
-                callback(...args);
+    add(docId, data) {
+        const key = `${this.keyPrefix}data_${docId}`;
+        try {
+            const serializedData = serializer.serialize(data);
+            const encodedData = base64.encode(serializedData);
+            localStorage.setItem(key, encodedData);
+
+            const index = this._readIndex();
+            if (!index.includes(docId)) {
+                index.push(docId);
+                this._writeIndex(index);
             }
+            return true;
+        } catch (e) {
+            if (e.name === 'QuotaExceededError') {
+                throw new LacertaDBError('QuickStore quota exceeded', 'QUOTA_EXCEEDED', e);
+            }
+            return false;
         }
     }
 
-    // FIXED: Add cleanup method
-    _cleanup() {
-        for (const event in this._listeners) {
-            this._listeners[event] = [];
+    get(docId) {
+        const key = `${this.keyPrefix}data_${docId}`;
+        const stored = localStorage.getItem(key);
+        if (stored) {
+            try {
+                const decoded = base64.decode(stored);
+                return serializer.deserialize(decoded);
+            } catch (e) {
+                console.error('Failed to parse QuickStore data:', e);
+            }
         }
+        return null;
     }
 
-    toString() {
-        const counts = Object.entries(this._listeners)
-            .map(([event, listeners]) => `${event}:${listeners.length}`)
-            .join(' ');
-        return `[Observer listeners:{${counts}}]`;
-    }
-}
-
-export class Database {
-    constructor(dbName, settings = {}) {
-        this._dbName = dbName;
-        this._db = null;
-        this._collections = new Map();
-        this._metadata = new DatabaseMetadata(dbName);
-        this._settings = new Settings(dbName, settings);
-        this._quickStore = new QuickStore(this._dbName);
-        this._settings.init();
-    }
-
-    get quickStore() {
-        return this._quickStore;
+    update(docId, data) {
+        return this.add(docId, data);
     }
 
-    async init() {
-        this.db = await IndexedDBUtility.openDatabase(this.name, undefined, (db, oldVersion, newVersion) => {
-            this._upgradeDatabase(db, oldVersion, newVersion);
-        });
-
-        const collectionNames = this.data.getCollectionNames();
-        for (const collectionName of collectionNames) {
-            const collection = new Collection(this, collectionName, this.settings);
-            await collection.init();
-            this.collections.set(collectionName, collection);
-        }
-    }
+    delete(docId) {
+        const key = `${this.keyPrefix}data_${docId}`;
+        localStorage.removeItem(key);
 
-    _createDataStores(db) {
-        for (const collectionName of this.collections.keys()) {
-            this._createDataStore(db, collectionName);
+        let index = this._readIndex();
+        const initialLength = index.length;
+        index = index.filter(id => id !== docId);
+        if (index.length < initialLength) {
+            this._writeIndex(index);
         }
     }
 
-    _createDataStore(db, collectionName) {
-        if (!db.objectStoreNames.contains(collectionName)) {
-            db.createObjectStore(collectionName, { keyPath: '_id' });
-        }
+    getAll() {
+        const index = this._readIndex();
+        return index.map(docId => {
+            const doc = this.get(docId);
+            return doc ? { _id: docId, ...doc } : null;
+        }).filter(Boolean);
     }
 
-    _upgradeDatabase(db, oldVersion, newVersion) {
-        console.log(`Upgrading database "${this.name}" from version ${oldVersion} to ${newVersion}`);
-        if (!db.objectStoreNames.contains('_metadata')) {
-            db.createObjectStore('_metadata', { keyPath: '_id' });
+    clear() {
+        const index = this._readIndex();
+        for (const docId of index) {
+            localStorage.removeItem(`${this.keyPrefix}data_${docId}`);
         }
+        localStorage.removeItem(this.indexKey);
     }
+}
 
-    async createCollection(collectionName) {
-        if (this.collections.has(collectionName)) {
-            console.log(`Collection "${collectionName}" already exists.`);
-            return new LacertaDBResult(
-                false, 
-                this.collections.get(collectionName), 
-                new LacertaDBError(
-                    `Collection "${collectionName}" already exists`,
-                    ErrorCodes.COLLECTION_EXISTS
-                )
-            );
-        }
-
-        if (!this.db.objectStoreNames.contains(collectionName)) {
-            const newVersion = this.db.version + 1;
-            this.db.close();
-            this.db = await IndexedDBUtility.openDatabase(this.name, newVersion, (db, oldVersion, newVersion) => {
-                this._createDataStore(db, collectionName);
-            });
-        }
-
-        const collection = new Collection(this, collectionName, this.settings);
-        await collection.init();
-        this.collections.set(collectionName, collection);
-
-        this.data.getCollectionMetadata(collectionName);
-        await this.data.saveMetadata();
-
-        return new LacertaDBResult(true, collection);
-    }
-
-    // FIXED: Add proper cleanup for observers
-    async deleteCollection(collectionName) {
-        if (!this.collections.has(collectionName)) {
-            return new LacertaDBResult(
-                false,
-                null,
-                new LacertaDBError(
-                    `Collection "${collectionName}" does not exist`,
-                    ErrorCodes.COLLECTION_NOT_FOUND
-                )
-            );
-        }
-
-        const collection = this.collections.get(collectionName);
-        
-        // Clean up collection resources
-        await collection.close();
-        collection.observer._cleanup();
-
-        await IndexedDBUtility.performTransaction(this.db, collectionName, 'readwrite', (store) => {
-            return IndexedDBUtility.clear(store);
-        });
-
-        this.collections.delete(collectionName);
-        this.data.removeCollectionMetadata(collectionName);
-        await this.data.saveMetadata();
+// ========================
+// Query Engine
+// ========================
 
-        return new LacertaDBResult(true, null);
+class QueryEngine {
+    constructor() {
+        this.operators = {
+            // Comparison
+            '$eq': (a, b) => a === b,
+            '$ne': (a, b) => a !== b,
+            '$gt': (a, b) => a > b,
+            '$gte': (a, b) => a >= b,
+            '$lt': (a, b) => a < b,
+            '$lte': (a, b) => a <= b,
+            '$in': (a, b) => Array.isArray(b) && b.includes(a),
+            '$nin': (a, b) => Array.isArray(b) && !b.includes(a),
+
+            // Logical
+            '$and': (doc, conditions) => conditions.every(cond => this.evaluate(doc, cond)),
+            '$or': (doc, conditions) => conditions.some(cond => this.evaluate(doc, cond)),
+            '$not': (doc, condition) => !this.evaluate(doc, condition),
+            '$nor': (doc, conditions) => !conditions.some(cond => this.evaluate(doc, cond)),
+
+            // Element
+            '$exists': (value, exists) => (value !== undefined) === exists,
+            '$type': (value, type) => typeof value === type,
+
+            // Array
+            '$all': (arr, values) => Array.isArray(arr) && values.every(v => arr.includes(v)),
+            '$elemMatch': (arr, condition) => Array.isArray(arr) && arr.some(elem => this.evaluate({ value: elem }, { value: condition })),
+            '$size': (arr, size) => Array.isArray(arr) && arr.length === size,
+
+            // String
+            '$regex': (str, pattern) => {
+                if (typeof str !== 'string') return false;
+                try {
+                    const regex = new RegExp(pattern);
+                    return regex.test(str);
+                } catch {
+                    return false;
+                }
+            },
+            '$text': (str, search) => typeof str === 'string' && str.toLowerCase().includes(search.toLowerCase())
+        };
     }
 
-    async getCollection(collectionName) {
-        if (this.collections.has(collectionName)) {
-            return new LacertaDBResult(true, this.collections.get(collectionName));
-        } else {
-            if (this.db.objectStoreNames.contains(collectionName)) {
-                const collection = new Collection(this, collectionName, this.settings);
-                await collection.init();
-                this.collections.set(collectionName, collection);
-                return new LacertaDBResult(true, collection);
+    evaluate(doc, query) {
+        for (const key in query) {
+            const value = query[key];
+            if (key.startsWith('$')) {
+                // Logical operator at root level
+                const operator = this.operators[key];
+                if (!operator || !operator(doc, value)) return false;
             } else {
-                return new LacertaDBResult(
-                    false,
-                    null,
-                    new LacertaDBError(
-                        `Collection "${collectionName}" does not exist`,
-                        ErrorCodes.COLLECTION_NOT_FOUND
-                    )
-                );
+                // Field-level query
+                const fieldValue = this.getFieldValue(doc, key);
+                if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+                    // Operator-based comparison
+                    for (const op in value) {
+                        if (op.startsWith('$')) {
+                            const operatorFn = this.operators[op];
+                            if (!operatorFn || !operatorFn(fieldValue, value[op])) {
+                                return false;
+                            }
+                        }
+                    }
+                } else {
+                    // Direct equality comparison
+                    if (fieldValue !== value) return false;
+                }
             }
         }
+        return true;
     }
 
-    async close() {
-        const collections = this.collectionsArray;
-
-        for (const collection of collections) {
-            await collection.close();
-        }
-
-        if (this.db) {
-            this.db.close();
-            this.db = null;
+    getFieldValue(doc, path) {
+        // Replaced optional chaining with a loop for compatibility
+        let current = doc;
+        for (const part of path.split('.')) {
+            if (current === null || current === undefined) {
+                return undefined;
+            }
+            current = current[part];
         }
+        return current;
     }
+}
+const queryEngine = new QueryEngine();
 
-    async deleteDatabase() {
-        await this.close();
-        await IndexedDBUtility.deleteDatabase(this.name);
-        LocalStorageUtility.removeItem(this.data.metadataKey);
-        this.settings.clear();
-        this.data = null;
-    }
-
-    get name() {
-        return this._dbName;
-    }
-
-    get db() {
-        return this._db;
-    }
-
-    set db(db) {
-        this._db = db;
-    }
-
-    get data() {
-        return this.metadata;
-    }
-
-    set data(d) {
-        this.metadata = d;
-    }
-
-    get collectionsArray() {
-        return Array.from(this.collections.values());
-    }
-
-    get collections() {
-        return this._collections;
-    }
-
-    get metadata() {
-        return this._metadata;
-    }
-
-    set metadata(d) {
-        this._metadata = d;
-    }
-
-    get totalSizeKB() {
-        return this.data.totalSizeKB;
-    }
-
-    get totalLength() {
-        return this.data.totalLength;
-    }
-
-    get modifiedAt() {
-        return this.data.modifiedAt;
-    }
-
-    get settings() {
-        return this._settings;
-    }
 
-    get settingsData() {
-        return this.settings.data;
-    }
+// ========================
+// Aggregation Pipeline
+// ========================
 
-    toString() {
-        return `[Database: ${this.name} | Collections: ${this.collections.size} | Size: ${this.totalSizeKB.toFixed(2)}KB | Documents: ${this.totalLength}]`;
-    }
-}
+class AggregationPipeline {
+    constructor() {
+        this.stages = {
+            '$match': (docs, condition) => docs.filter(doc => queryEngine.evaluate(doc, condition)),
+
+            '$project': (docs, projection) => docs.map(doc => {
+                const projected = {};
+                for (const key in projection) {
+                    const value = projection[key];
+                    if (value === 1 || value === true) {
+                        projected[key] = queryEngine.getFieldValue(doc, key);
+                    } else if (typeof value === 'object') {
+                        // Handle computed fields if necessary
+                    } else if (typeof value === 'string' && value.startsWith('$')) {
+                        projected[key] = queryEngine.getFieldValue(doc, value.substring(1));
+                    }
+                }
+                // Handle exclusion projection
+                if (Object.values(projection).some(v => v === 0 || v === false)) {
+                    const exclusions = Object.keys(projection).filter(k => projection[k] === 0 || projection[k] === false);
+                    const included = { ...doc };
+                    exclusions.forEach(key => delete included[key]);
+                    return included;
+                }
+                return projected;
+            }),
+
+            '$sort': (docs, sortSpec) => [...docs].sort((a, b) => {
+                for (const key in sortSpec) {
+                    const order = sortSpec[key]; // 1 for asc, -1 for desc
+                    const aVal = queryEngine.getFieldValue(a, key);
+                    const bVal = queryEngine.getFieldValue(b, key);
+                    if (aVal < bVal) return -order;
+                    if (aVal > bVal) return order;
+                }
+                return 0;
+            }),
 
-export class Document {
-    constructor(data, encryptionKey = null) {
-        this._id = data._id || this._generateId();
-        this._created = data._created || Date.now();
-        this._permanent = data._permanent ? true : false;
-        this._encrypted = data._encrypted || (encryptionKey ? true : false);
-        this._compressed = data._compressed || false;
+            '$limit': (docs, limit) => docs.slice(0, limit),
 
-        this._attachments = data._attachments || data.attachments || [];
+            '$skip': (docs, skip) => docs.slice(skip),
 
-        if (data.packedData) {
-            this._packedData = data.packedData;
-            this._modified = data._modified || Date.now();
-            this._data = null;
-        } else {
-            this._data = data.data || {};
-            this._modified = Date.now();
-            this._packedData = new Uint8Array(0);
-        }
+            '$group': (docs, groupSpec) => {
+                const groups = new Map();
+                const idField = groupSpec._id;
 
-        this._encryptionKey = encryptionKey || "";
-    }
+                for (const doc of docs) {
+                    const groupKey = typeof idField === 'string' ?
+                        queryEngine.getFieldValue(doc, idField.replace('$', '')) :
+                        JSON.stringify(idField); // Fallback for complex IDs
 
-    get attachments() {
-        return this._attachments;
-    }
+                    if (!groups.has(groupKey)) {
+                        groups.set(groupKey, { _id: groupKey, docs: [] });
+                    }
+                    groups.get(groupKey).docs.push(doc);
+                }
 
-    set attachments(value) {
-        this._attachments = value;
-    }
+                const results = [];
+                for (const group of groups.values()) {
+                    const result = { _id: group._id };
+                    for (const fieldKey in groupSpec) {
+                        if (fieldKey === '_id') continue;
+                        const accumulator = groupSpec[fieldKey];
+                        const op = Object.keys(accumulator)[0];
+                        const field = accumulator[op].toString().replace('$', '');
+
+                        switch(op) {
+                            case '$sum':
+                                result[fieldKey] = group.docs.reduce((sum, d) => sum + (queryEngine.getFieldValue(d, field) || 0), 0);
+                                break;
+                            case '$avg':
+                                const sum = group.docs.reduce((s, d) => s + (queryEngine.getFieldValue(d, field) || 0), 0);
+                                result[fieldKey] = sum / group.docs.length;
+                                break;
+                            case '$count':
+                                result[fieldKey] = group.docs.length;
+                                break;
+                            case '$max':
+                                result[fieldKey] = Math.max(...group.docs.map(d => queryEngine.getFieldValue(d, field)));
+                                break;
+                            case '$min':
+                                result[fieldKey] = Math.min(...group.docs.map(d => queryEngine.getFieldValue(d, field)));
+                                break;
+                        }
+                    }
+                    results.push(result);
+                }
+                return results;
+            },
 
-    get data() {
-        return this._data;
-    }
+            '$lookup': async (docs, lookupSpec, db) => {
+                const foreignCollection = await db.getCollection(lookupSpec.from);
+                const foreignDocs = await foreignCollection.getAll();
+                const foreignMap = new Map();
+                foreignDocs.forEach(doc => {
+                    const key = queryEngine.getFieldValue(doc, lookupSpec.foreignField);
+                    if (!foreignMap.has(key)) foreignMap.set(key, []);
+                    foreignMap.get(key).push(doc);
+                });
 
-    get packedData() {
-        return this._packedData;
+                return docs.map(doc => {
+                    const localValue = queryEngine.getFieldValue(doc, lookupSpec.localField);
+                    return {
+                        ...doc,
+                        [lookupSpec.as]: foreignMap.get(localValue) || []
+                    };
+                });
+            }
+        };
     }
 
-    get encryptionKey() {
-        return this._encryptionKey;
-    }
+    async execute(docs, pipeline, db) {
+        let result = docs;
+        for (const stage of pipeline) {
+            const stageName = Object.keys(stage)[0];
+            const stageSpec = stage[stageName];
+            const stageFunction = this.stages[stageName];
 
-    set data(d) {
-        this._data = d;
-    }
+            if (!stageFunction) {
+                throw new Error(`Unknown aggregation stage: ${stageName}`);
+            }
 
-    set packedData(d) {
-        this._packedData = d;
+            if (stageName === '$lookup') {
+                result = await stageFunction(result, stageSpec, db);
+            } else {
+                result = stageFunction(result, stageSpec);
+            }
+        }
+        return result;
     }
+}
+const aggregationPipeline = new AggregationPipeline();
 
-    set encryptionKey(d) {
-        this._encryptionKey = d;
-    }
+// ========================
+// Migration Manager
+// ========================
 
-    static hasAttachments(documentData) {
-        return (documentData._attachments && documentData._attachments.length > 0) ||
-            (documentData.attachments && documentData.attachments.length > 0);
+class MigrationManager {
+    constructor(database) {
+        this.database = database;
+        this.migrations = [];
+        this.currentVersion = this.loadVersion();
     }
 
-    static async getAttachments(documentData, dbName, collectionName) {
-        if (!Document.hasAttachments(documentData)) {
-            return [];
-        }
-
-        const attachmentPaths = documentData._attachments || documentData.attachments;
-        documentData.attachments = await OPFSUtility.getAttachments(attachmentPaths);
-        return Promise.resolve(documentData);
+    loadVersion() {
+        return localStorage.getItem(`lacertadb_${this.database.name}_version`) || '1.0.0';
     }
 
-    static isEncrypted(documentData) {
-        return documentData._encrypted && documentData.packedData;
+    saveVersion(version) {
+        localStorage.setItem(`lacertadb_${this.database.name}_version`, version);
+        this.currentVersion = version;
     }
 
-    static async decryptDocument(documentData, encryptionKey) {
-        if (!Document.isEncrypted(documentData)) {
-            throw new Error('Document is not encrypted.');
-        }
-        const decryptedData = await BrowserEncryptionUtility.decrypt(documentData.packedData, encryptionKey);
-        const unpackedData = TURBO.deserialize(decryptedData);
-
-        return {
-            _id: documentData._id,
-            _created: documentData._created,
-            _modified: documentData._modified,
-            _encrypted: true,
-            _compressed: documentData._compressed,
-            _permanent: documentData._permanent ? true: false,
-            attachments: documentData.attachments,
-            data: unpackedData
-        };
+    addMigration(migration) {
+        this.migrations.push(migration);
     }
 
-    async pack() {
-        if (!this.data) {
-            throw new Error('No data to pack');
-        }
+    compareVersions(a, b) {
+        const partsA = a.split('.').map(Number);
+        const partsB = b.split('.').map(Number);
+        const len = Math.max(partsA.length, partsB.length);
 
-        let packedData = TURBO.serialize(this.data);
-        if (this._compressed) {
-            packedData = await this._compressData(packedData);
-        }
-        if (this._encrypted) {
-            packedData = await this._encryptData(packedData);
+        for (let i = 0; i < len; i++) {
+            const partA = partsA[i] || 0;
+            const partB = partsB[i] || 0;
+            if (partA > partB) return 1;
+            if (partA < partB) return -1;
         }
-        this.packedData = packedData;
-        return packedData;
+        return 0;
     }
 
-    packSync() {
-        if (!this.data) {
-            throw new Error('No data to pack');
-        }
+    async runMigrations(targetVersion) {
+        const applicableMigrations = this.migrations
+            .filter(m => this.compareVersions(m.version, this.currentVersion) > 0 &&
+                this.compareVersions(m.version, targetVersion) <= 0)
+            .sort((a, b) => this.compareVersions(a.version, b.version));
 
-        if (this._encrypted) {
-            throw new Error("Packing synchronously a document being encrypted is impossible.")
-        }
-        if (this._compressed) {
-            throw new Error("Packing synchronously a document being compressed is impossible.")
+        for (const migration of applicableMigrations) {
+            await this._applyMigration(migration, 'up');
+            this.saveVersion(migration.version);
         }
-
-        let packedData = TURBO.serialize(this.data);
-        this.packedData = packedData;
-        return packedData;
     }
 
-    async unpack() {
-        if (!this.data && this.packedData.length > 0) {
-            let unpackedData = this.packedData;
-            if (this._encrypted) {
-                unpackedData = await this._decryptData(unpackedData);
-            }
-            if (this._compressed) {
-                unpackedData = await this._decompressData(unpackedData);
-            }
-            this.data = TURBO.deserialize(unpackedData);
+    async rollback(targetVersion) {
+        const applicableMigrations = this.migrations
+            .filter(m => m.down &&
+                this.compareVersions(m.version, targetVersion) > 0 &&
+                this.compareVersions(m.version, this.currentVersion) <= 0)
+            .sort((a, b) => this.compareVersions(b.version, a.version));
+
+        for (const migration of applicableMigrations) {
+            await this._applyMigration(migration, 'down');
         }
-        return this.data;
+        this.saveVersion(targetVersion);
     }
 
-    unpackSync() {
-        if (!this.data && this.packedData.length > 0) {
-            if (this._encrypted) {
-                throw new Error("Unpacking synchronously a document being encrypted is impossible.")
-            }
-            if (this._compressed) {
-                throw new Error("Unpacking synchronously a document being compressed is impossible.")
+    async _applyMigration(migration, direction) {
+        console.log(`${direction === 'up' ? 'Running' : 'Rolling back'} migration: ${migration.name} (v${migration.version})`);
+        const collections = await this.database.listCollections();
+        for (const collectionName of collections) {
+            const coll = await this.database.getCollection(collectionName);
+            const docs = await coll.getAll();
+            for (const doc of docs) {
+                const updated = await migration[direction](doc);
+                if (updated) {
+                    await coll.update(doc._id, updated);
+                }
             }
-            this.data = TURBO.deserialize(this.packedData);
         }
-        return this.data;
     }
+}
 
-    async _encryptData(data) {
-        const encryptionKey = this.encryptionKey;
-        return await BrowserEncryptionUtility.encrypt(data, encryptionKey);
-    }
+// ========================
+// Performance Monitor
+// ========================
 
-    async _decryptData(data) {
-        const encryptionKey = this.encryptionKey;
-        return await BrowserEncryptionUtility.decrypt(data, encryptionKey);
+class PerformanceMonitor {
+    constructor() {
+        this.metrics = {
+            operations: [],
+            latencies: [],
+            cacheHits: 0,
+            cacheMisses: 0,
+            memoryUsage: []
+        };
+        this.monitoring = false;
+        this.monitoringInterval = null;
     }
 
-    async _compressData(data) {
-        return await BrowserCompressionUtility.compress(data);
+    startMonitoring() {
+        if (this.monitoring) return;
+        this.monitoring = true;
+        this.monitoringInterval = setInterval(() => this.collectMetrics(), 1000);
     }
 
-    async _decompressData(data) {
-        return await BrowserCompressionUtility.decompress(data);
+    stopMonitoring() {
+        if (!this.monitoring) return;
+        this.monitoring = false;
+        clearInterval(this.monitoringInterval);
+        this.monitoringInterval = null;
     }
 
-    _generateId() {
-        return 'xxxx-xxxx-xxxx'.replace(/[x]/g, () => (Math.random() * 16 | 0).toString(16));
+    recordOperation(type, duration) {
+        if (!this.monitoring) return;
+        this.metrics.operations.push({ type, duration, timestamp: Date.now() });
+        this.metrics.latencies.push(duration);
+        if (this.metrics.operations.length > 100) this.metrics.operations.shift();
+        if (this.metrics.latencies.length > 100) this.metrics.latencies.shift();
     }
 
-    async objectOutput(includeAttachments = false) {
-        if (!this.data) {
-            await this.unpack();
-        }
-
-        const output = {
-            _id: this._id,
-            _created: this._created,
-            _modified: this._modified,
-            _permanent: this._permanent,
-            _encrypted: this._encrypted,
-            _compressed: this._compressed,
-            attachments: this.attachments,
-            data: this.data,
-        };
+    recordCacheHit() { this.metrics.cacheHits++; }
+    recordCacheMiss() { this.metrics.cacheMisses++; }
 
-        if (includeAttachments && this.attachments.length > 0) {
-            const attachments = await OPFSUtility.getAttachments(this.attachments);
-            output.attachments = attachments;
+    collectMetrics() {
+        // Replaced optional chaining with `&&` for compatibility
+        if (performance && performance.memory) {
+            this.metrics.memoryUsage.push({
+                used: performance.memory.usedJSHeapSize,
+                total: performance.memory.totalJSHeapSize,
+                limit: performance.memory.jsHeapSizeLimit,
+                timestamp: Date.now()
+            });
+            if (this.metrics.memoryUsage.length > 60) this.metrics.memoryUsage.shift();
         }
-
-        return output;
     }
 
-    async databaseOutput() {
-        if (!this.packedData || this.packedData.length === 0) {
-            await this.pack();
-        }
+    getStats() {
+        const opsPerSec = this.metrics.operations.filter(op => Date.now() - op.timestamp < 1000).length;
+        const totalLatency = this.metrics.latencies.reduce((a, b) => a + b, 0);
+        const avgLatency = this.metrics.latencies.length > 0 ? totalLatency / this.metrics.latencies.length : 0;
+        const totalCacheOps = this.metrics.cacheHits + this.metrics.cacheMisses;
+        const cacheHitRate = totalCacheOps > 0 ? (this.metrics.cacheHits / totalCacheOps) * 100 : 0;
+
+        // Replaced `.at(-1)` with classic index access for compatibility
+        const latestMemory = this.metrics.memoryUsage.length > 0 ? this.metrics.memoryUsage[this.metrics.memoryUsage.length - 1] : null;
+        const memoryUsageMB = latestMemory ? latestMemory.used / (1024 * 1024) : 0;
 
         return {
-            _id: this._id,
-            _created: this._created,
-            _modified: this._modified,
-            _permanent: this._permanent ? true : false,
-            _compressed: this._compressed,
-            _encrypted: this._encrypted,
-            attachments: this.attachments,
-            packedData: this.packedData,
+            opsPerSec,
+            avgLatency: avgLatency.toFixed(2),
+            cacheHitRate: cacheHitRate.toFixed(1),
+            memoryUsageMB: memoryUsageMB.toFixed(2)
         };
     }
 
-    toString() {
-        return `[Document: ${this._id} | Created: ${new Date(this._created).toISOString()} | Encrypted: ${this._encrypted} | Compressed: ${this._compressed} | Permanent: ${this._permanent}]`;
+    getOptimizationTips() {
+        const tips = [];
+        const stats = this.getStats();
+
+        if (stats.avgLatency > 100) {
+            tips.push('High average latency detected. Consider enabling compression and indexing frequently queried fields.');
+        }
+        if (stats.cacheHitRate < 50 && (this.metrics.cacheHits + this.metrics.cacheMisses) > 20) {
+            tips.push('Low cache hit rate. Consider increasing cache size or optimizing query patterns.');
+        }
+        if (this.metrics.memoryUsage.length > 10) {
+            const recent = this.metrics.memoryUsage.slice(-10);
+            const trend = recent[recent.length - 1].used - recent[0].used;
+            if (trend > 10 * 1024 * 1024) { // > 10MB increase
+                tips.push('Memory usage is increasing rapidly. Check for memory leaks or consider batch processing.');
+            }
+        }
+        return tips.length > 0 ? tips : ['Performance is optimal. No issues detected.'];
     }
 }
 
-class Settings {
-    constructor(dbName, newSettings = {}) {
-        this._dbName = dbName;
-        this._settingsKey = `lacertadb_${this._dbName}_settings`;
-        this._data = this._loadSettings();
-        this._mergeSettings(newSettings);
+// ========================
+// Collection Class
+// ========================
+
+class Collection {
+    constructor(name, database) {
+        this.name = name;
+        this.database = database;
+        this.db = null;
+        this.metadata = null;
+        this.settings = database.settings;
+        this.indexedDB = new IndexedDBUtility();
+        this.opfs = new OPFSUtility();
+        this.cleanupInterval = null;
+        this.events = new Map();
+        this.queryCache = new Map();
+        this.cacheTimeout = 60000;
+        this.performanceMonitor = database.performanceMonitor;
     }
 
-    init() {
-        this.set('sizeLimitKB', this.get('sizeLimitKB') || Infinity);
-        this.set('bufferLimitKB', this.get('bufferLimitKB') || -(this.get('sizeLimitKB') * 0.2));
-
-        if (this.get('bufferLimitKB') < -0.8 * this.get('sizeLimitKB')) {
-            throw new Error("Buffer limit cannot be below -80% of the size limit.");
-        }
+    async init() {
+        const dbName = `${this.database.name}_${this.name}`;
+        this.db = await this.indexedDB.openDatabase(dbName, 1, (db, oldVersion) => {
+            if (oldVersion < 1 && !db.objectStoreNames.contains('documents')) {
+                const store = db.createObjectStore('documents', { keyPath: '_id' });
+                store.createIndex('modified', '_modified', { unique: false });
+            }
+            // Future index creation logic would go here during version bumps
+        });
 
-        this.set('freeSpaceEvery', this._validateFreeSpaceSetting(this.get('freeSpaceEvery')));
-    }
+        const metadataData = this.database.metadata.collections[this.name];
+        this.metadata = new CollectionMetadata(this.name, metadataData);
 
-    _validateFreeSpaceSetting(value = 10000) {
-        if (value === undefined || value === false || value === 0) {
-            return Infinity;
+        if (this.settings.freeSpaceEvery > 0) {
+            this.cleanupInterval = setInterval(() => this.freeSpace(), this.settings.freeSpaceEvery);
         }
-        if (value < 1000 && value !== 0) {
-            throw new Error("Invalid freeSpaceEvery value. It must be 0, Infinity, or above 1000.");
-        }
-        if (value >= 1000 && value < 10000) {
-            console.warn("Warning: freeSpaceEvery value is between 1000 and 10000, which may lead to frequent freeing.");
-        }
-        return value;
+        return this;
     }
 
-    _loadSettings() {
-        const settings = LocalStorageUtility.getItem(this.settingsKey);
-        return settings ? settings : {};
-    }
+    async add(documentData, options = {}) {
+        await this.trigger('beforeAdd', documentData);
 
-    _saveSettings() {
-        LocalStorageUtility.setItem(this.settingsKey, this.data);
-    }
+        const doc = new Document({ data: documentData, _id: options.id }, {
+            encrypted: options.encrypted || false,
+            compressed: options.compressed !== false,
+            permanent: options.permanent || false,
+            password: options.password
+        });
 
-    _mergeSettings(newSettings) {
-        this.data = Object.assign(this.data, newSettings);
-        this._saveSettings();
-    }
+        const attachments = options.attachments;
+        if (attachments && attachments.length > 0) {
+            const preparedAttachments = await Promise.all(
+                attachments.map(att => (att instanceof File || att instanceof Blob) ?
+                    OPFSUtility.prepareAttachment(att, att.name) :
+                    Promise.resolve(att))
+            );
+            doc._attachments = await this.opfs.saveAttachments(this.database.name, this.name, doc._id, preparedAttachments);
+        }
 
-    get(key) {
-        return this.data[key];
-    }
+        await doc.pack();
+        const dbOutput = doc.databaseOutput();
+        await this.indexedDB.add(this.db, 'documents', dbOutput);
 
-    set(key, value) {
-        this.data[key] = value;
-        this._saveSettings();
-    }
+        const sizeKB = dbOutput.packedData.byteLength / 1024;
+        this.metadata.addDocument(doc._id, sizeKB, doc._permanent, doc._attachments.length);
+        this.database.metadata.setCollection(this.metadata);
 
-    remove(key) {
-        delete this.data[key];
-        this._saveSettings();
+        await this.checkSpaceLimit();
+        await this.trigger('afterAdd', doc);
+        this.queryCache.clear();
+        return doc._id;
     }
 
-    clear() {
-        this.data = {};
-        this._saveSettings();
-    }
+    async get(docId, options = {}) {
+        await this.trigger('beforeGet', docId);
 
-    get dbName() {
-        return this._dbName;
-    }
+        const stored = await this.indexedDB.get(this.db, 'documents', docId);
+        if (!stored) {
+            throw new LacertaDBError(`Document with id '${docId}' not found.`, 'DOCUMENT_NOT_FOUND');
+        }
 
-    get data() {
-        return this._data;
-    }
+        const doc = new Document(stored, {
+            password: options.password,
+            encrypted: stored._encrypted,
+            compressed: stored._compressed
+        });
 
-    set data(s) {
-        this._data = s;
-    }
+        if (stored.packedData) {
+            await doc.unpack();
+        }
 
-    get settingsKey() {
-        return this._settingsKey;
-    }
+        if (options.includeAttachments && doc._attachments.length > 0) {
+            doc.data._attachments = await this.opfs.getAttachments(doc._attachments);
+        }
 
-    toString() {
-        return `[Settings: ${this.dbName} | SizeLimit: ${this.get('sizeLimitKB')}KB | BufferLimit: ${this.get('bufferLimitKB')}KB]`;
+        await this.trigger('afterGet', doc);
+        return doc.objectOutput(options.includeAttachments);
     }
-}
 
-export class Collection {
-    constructor(database, collectionName, settings) {
-        this._database = database;
-        this._collectionName = collectionName;
-        this._settings = settings;
-        this._metadata = null;
-        this._lastFreeSpaceTime = 0;
-        this._observer = new Observer();
-        this._transactionManager = new TransactionManager();
-        this._freeSpaceInterval = null;
-        this._freeSpaceHandler = null;
-    }
-
-    get observer() {
-        return this._observer;
-    }
-
-    async createIndex(fieldPath, options = {}) {
-        const indexName = options.name || fieldPath.replace(/\./g, '_');
-        const newVersion = this.database.db.version + 1;
-        this.database.db.close();
-
-        this.database.db = await IndexedDBUtility.openDatabase(
-            this.database.name,
-            newVersion,
-            (db) => {
-                if (db.objectStoreNames.contains(this.name)) {
-                    const tx = db.transaction([this.name]);
-                    const store = tx.objectStore(this.name);
-                    if (!store.indexNames.contains(indexName)) {
-                        store.createIndex(indexName, fieldPath, {
-                            unique: options.unique || false,
-                            multiEntry: options.multiEntry || false
-                        });
-                    }
+    async getAll(options = {}) {
+        const stored = await this.indexedDB.getAll(this.db, 'documents', undefined, options.limit);
+        return Promise.all(stored.map(async docData => {
+            try {
+                const doc = new Document(docData, {
+                    password: options.password,
+                    encrypted: docData._encrypted,
+                    compressed: docData._compressed
+                });
+                if (docData.packedData) {
+                    await doc.unpack();
                 }
+                return doc.objectOutput();
+            } catch (error) {
+                console.error(`Failed to unpack document ${docData._id}:`, error);
+                return null;
             }
-        );
+        })).then(docs => docs.filter(Boolean));
     }
 
-    async init() {
-        // FIXED: Ensure metadata is always accessed through database metadata
-        this.metadata = this.database.metadata.getCollectionMetadata(this.name);
-
-        if (this.settingsData.freeSpaceEvery !== Infinity) {
-            this._freeSpaceHandler = () => this._maybeFreeSpace();
-            this._freeSpaceInterval = setInterval(
-                this._freeSpaceHandler,
-                this.settingsData.freeSpaceEvery
-            );
+    async update(docId, updates, options = {}) {
+        await this.trigger('beforeUpdate', { docId, updates });
+
+        const stored = await this.indexedDB.get(this.db, 'documents', docId);
+        if (!stored) {
+            throw new LacertaDBError(`Document with id '${docId}' not found for update.`, 'DOCUMENT_NOT_FOUND');
         }
-    }
 
-    get name() {
-        return this._collectionName;
-    }
+        const existingDoc = new Document(stored, { password: options.password });
+        if (stored.packedData) await existingDoc.unpack();
 
-    get sizes() {
-        return this.metadataData.documentSizes || {};
-    }
+        const updatedData = { ...existingDoc.data, ...updates };
 
-    get modifications() {
-        return this.metadataData.documentModifiedAt || {};
-    }
+        // Replaced `??` with ternary operator for compatibility
+        const doc = new Document({
+            _id: docId,
+            _created: stored._created,
+            data: updatedData
+        }, {
+            encrypted: options.encrypted !== undefined ? options.encrypted : stored._encrypted,
+            compressed: options.compressed !== undefined ? options.compressed : stored._compressed,
+            permanent: options.permanent !== undefined ? options.permanent : stored._permanent,
+            password: options.password
+        });
+        doc._modified = Date.now();
+
+        const attachments = options.attachments;
+        if (attachments && attachments.length > 0) {
+            await this.opfs.deleteAttachments(this.database.name, this.name, docId);
+            const preparedAttachments = await Promise.all(
+                attachments.map(att => (att instanceof File || att instanceof Blob) ?
+                    OPFSUtility.prepareAttachment(att, att.name) :
+                    Promise.resolve(att))
+            );
+            doc._attachments = await this.opfs.saveAttachments(this.database.name, this.name, doc._id, preparedAttachments);
+        } else {
+            doc._attachments = stored._attachments;
+        }
 
-    get attachments() {
-        return this.metadataData.documentAttachments || {};
-    }
+        await doc.pack();
+        const dbOutput = doc.databaseOutput();
+        await this.indexedDB.put(this.db, 'documents', dbOutput);
 
-    get permanents() {
-        return this.metadataData.documentPermanent || {};
-    }
+        const sizeKB = dbOutput.packedData.byteLength / 1024;
+        this.metadata.updateDocument(doc._id, sizeKB, doc._permanent, doc._attachments.length);
+        this.database.metadata.setCollection(this.metadata);
 
-    get keys() {
-        return Object.keys(this.sizes);
+        await this.trigger('afterUpdate', doc);
+        this.queryCache.clear();
+        return doc._id;
     }
 
-    get documentsMetadata() {
-        var keys = this.keys;
-        var sizes = this.sizes;
-        var modifications = this.modifications;
-        var permanents = this.permanents;
-        var attachments = this.attachments;
-        var metadata = new Array(keys.length);
-        var i = 0;
-        for(const key of keys){
-            metadata[i++] = {
-                id: key,
-                size: sizes[key],
-                modified: modifications[key],
-                permanent: permanents[key],
-                attachment: attachments[key]
-            };
-        }
+    async delete(docId) {
+        await this.trigger('beforeDelete', docId);
 
-        return metadata;
-    }
+        const doc = await this.indexedDB.get(this.db, 'documents', docId);
+        if (!doc) throw new LacertaDBError('Document not found for deletion', 'DOCUMENT_NOT_FOUND');
+        if (doc._permanent) throw new LacertaDBError('Cannot delete a permanent document', 'INVALID_OPERATION');
 
-    get settings() {
-        return this._settings;
-    }
+        await this.indexedDB.delete(this.db, 'documents', docId);
+        const attachments = doc._attachments;
+        if (attachments && attachments.length > 0) {
+            await this.opfs.deleteAttachments(this.database.name, this.name, docId);
+        }
 
-    get settingsData() {
-        return this.settings.data;
-    }
+        this.metadata.removeDocument(docId);
+        this.database.metadata.setCollection(this.metadata);
 
-    set settings(d) {
-        this._settings = d;
+        await this.trigger('afterDelete', docId);
+        this.queryCache.clear();
     }
 
-    get lastFreeSpaceTime() {
-        return this._lastFreeSpaceTime;
-    }
+    async query(filter = {}, options = {}) {
+        const startTime = performance.now();
+        const cacheKey = base64.encode(serializer.serialize({ filter, options }));
+        const cached = this.queryCache.get(cacheKey);
 
-    set lastFreeSpaceTime(t) {
-        this._lastFreeSpaceTime = t;
-    }
+        if (cached && Date.now() - cached.timestamp < this.cacheTimeout) {
+            if (this.performanceMonitor) this.performanceMonitor.recordCacheHit();
+            return cached.data;
+        }
+        if (this.performanceMonitor) this.performanceMonitor.recordCacheMiss();
 
-    get database() {
-        return this._database;
-    }
+        let results = await this.getAll(options);
+        if (Object.keys(filter).length > 0) {
+            results = results.filter(doc => queryEngine.evaluate(doc, filter));
+        }
 
-    get metadata() {
-        // FIXED: Always access through database metadata for consistency
-        return this.database.metadata.getCollectionMetadata(this.name);
-    }
+        if (options.sort) results = aggregationPipeline.stages.$sort(results, options.sort);
+        if (options.skip) results = aggregationPipeline.stages.$skip(results, options.skip);
+        if (options.limit) results = aggregationPipeline.stages.$limit(results, options.limit);
+        if (options.projection) results = aggregationPipeline.stages.$project(results, options.projection);
+
+        if (this.performanceMonitor) this.performanceMonitor.recordOperation('query', performance.now() - startTime);
 
-    get metadataData() {
-        return this.metadata.getRawMetadata();
+        this.queryCache.set(cacheKey, { data: results, timestamp: Date.now() });
+        if (this.queryCache.size > 100) {
+            this.queryCache.delete(this.queryCache.keys().next().value);
+        }
+        return results;
     }
 
-    set metadata(m) {
-        this._metadata = m;
+    async aggregate(pipeline) {
+        const startTime = performance.now();
+        const docs = await this.getAll();
+        const result = await aggregationPipeline.execute(docs, pipeline, this.database);
+        if (this.performanceMonitor) this.performanceMonitor.recordOperation('aggregate', performance.now() - startTime);
+        return result;
     }
 
-    get sizeKB() {
-        return this.metadataData.sizeKB;
+    async batchAdd(documents, options) {
+        const startTime = performance.now();
+        const results = await Promise.all(documents.map(doc =>
+            this.add(doc, options)
+                .then(id => ({ success: true, id }))
+                .catch(error => ({ success: false, error: error.message }))
+        ));
+        if (this.performanceMonitor) this.performanceMonitor.recordOperation('batchAdd', performance.now() - startTime);
+        return results;
     }
 
-    get length() {
-        return this.metadataData.length;
+    batchUpdate(updates, options) {
+        return Promise.all(updates.map(update =>
+            this.update(update.id, update.data, options)
+                .then(id => ({ success: true, id }))
+                .catch(error => ({ success: false, id: update.id, error: error.message }))
+        ));
     }
 
-    get totalSizeKB() {
-        return this.sizeKB;
+    batchDelete(ids) {
+        return Promise.all(ids.map(id =>
+            this.delete(id)
+                .then(() => ({ success: true, id }))
+                .catch(error => ({ success: false, id, error: error.message }))
+        ));
     }
 
-    get totalLength() {
-        return this.length;
+    async clear() {
+        await this.indexedDB.clear(this.db, 'documents');
+        this.metadata = new CollectionMetadata(this.name);
+        this.database.metadata.setCollection(this.metadata);
+        this.queryCache.clear();
     }
 
-    get modifiedAt() {
-        return this.metadataData.modifiedAt;
+    async checkSpaceLimit() {
+        if (this.settings.sizeLimitKB !== Infinity && this.metadata.sizeKB > this.settings.bufferLimitKB) {
+            await this.freeSpace();
+        }
     }
 
-    get isFreeSpaceEnabled() {
-        return this.settingsData.freeSpaceEvery !== Infinity;
+    async freeSpace() {
+        const targetSize = this.settings.bufferLimitKB * 0.8;
+        while (this.metadata.sizeKB > targetSize) {
+            const oldestDocs = this.metadata.getOldestNonPermanentDocuments(10);
+            if (oldestDocs.length === 0) break;
+            await this.batchDelete(oldestDocs);
+        }
     }
 
-    get shouldRunFreeSpaceSize() {
-        return (this.totalSizeKB > this.settingsData.sizeLimitKB + this.settingsData.bufferLimitKB);
+    on(event, callback) {
+        if (!this.events.has(event)) this.events.set(event, []);
+        this.events.get(event).push(callback);
     }
 
-    get shouldRunFreeSpaceTime() {
-        return (this.isFreeSpaceEnabled && (Date.now() - this.lastFreeSpaceTime >= this.settingsData.freeSpaceEvery));
+    off(event, callback) {
+        if (!this.events.has(event)) return;
+        const listeners = this.events.get(event).filter(cb => cb !== callback);
+        this.events.set(event, listeners);
     }
 
-    async _maybeFreeSpace() {
-        if(this.shouldRunFreeSpaceSize || this.shouldRunFreeSpaceTime){
-            return this.freeSpace(this.settingsData.sizeLimitKB);
+    async trigger(event, data) {
+        if (!this.events.has(event)) return;
+        for (const callback of this.events.get(event)) {
+            await callback(data);
         }
     }
 
-    async addDocument(documentData, encryptionKey = null) {
-        return await this._transactionManager.execute(async () => {
-            this.observer._emit('beforeAdd', documentData);
-
-            const document = new Document(documentData, encryptionKey);
-
-            const attachmentPaths = [];
-            if (Document.hasAttachments(documentData)) {
-                const attachments = documentData._attachments || documentData.attachments;
-                for (let i = 0; i < attachments.length; i++) {
-                    attachmentPaths.push(
-                        `${this.database.name}/${this.name}/${document._id}/${i}`
-                    );
-                }
-                document._attachments = attachmentPaths;
-            }
-
-            const docData = await document.databaseOutput();
-            const docId = docData._id;
-            const isPermanent = docData._permanent || false;
-            const docSizeKB = docData.packedData.byteLength / 1024;
-            let isNewDocument = !(docId in this.metadataData.documentSizes);
-
-            try {
-                await IndexedDBUtility.performTransaction(
-                    this.database.db,
-                    this.name,
-                    'readwrite',
-                    (store) => {
-                        if (isNewDocument) {
-                            return IndexedDBUtility.add(store, docData);
-                        } else {
-                            return IndexedDBUtility.put(store, docData);
-                        }
-                    }
-                );
-
-                if (attachmentPaths.length > 0) {
-                    const attachments = documentData._attachments || documentData.attachments;
-                    await OPFSUtility.saveAttachments(
-                        this.database.name,
-                        this.name,
-                        document._id,
-                        attachments
-                    );
-                }
-
-                this.metadata.updateDocument(
-                    docId,
-                    docSizeKB,
-                    isPermanent,
-                    attachmentPaths.length
-                );
+    clearCache() { this.queryCache.clear(); }
 
-                await this.database.metadata.saveMetadata();
-
-            } catch (error) {
-                if (attachmentPaths.length > 0) {
-                    try {
-                        await OPFSUtility.deleteAttachments(
-                            this.database.name,
-                            this.name,
-                            document._id
-                        );
-                    } catch (e) {
-                        // Ignore cleanup errors
-                    }
-                }
-                throw error;
-            }
-
-            await this._maybeFreeSpace();
+    destroy() {
+        clearInterval(this.cleanupInterval);
+        if (this.db) {
+            this.db.close();
+        }
+    }
+}
 
-            this.observer._emit('afterAdd', documentData);
+// ========================
+// Database Class
+// ========================
 
-            return isNewDocument;
-        });
+class Database {
+    constructor(name, performanceMonitor) {
+        this.name = name;
+        this.collections = new Map();
+        this.metadata = null;
+        this.settings = null;
+        this.quickStore = null;
+        this.performanceMonitor = performanceMonitor;
     }
 
-    async getDocument(docId, encryptionKey = null, includeAttachments = false) {
-        this.observer._emit('beforeGet', docId);
+    async init() {
+        this.metadata = DatabaseMetadata.load(this.name);
+        this.settings = Settings.load(this.name);
+        this.quickStore = new QuickStore(this.name);
+        return this;
+    }
 
-        if (!(docId in this.metadataData.documentSizes)) {
-            return false;
+    async createCollection(name, options) {
+        if (this.collections.has(name)) {
+            throw new LacertaDBError(`Collection '${name}' already exists.`, 'COLLECTION_EXISTS');
         }
 
-        const docData = await IndexedDBUtility.performTransaction(
-            this.database.db,
-            this.name,
-            'readonly',
-            (store) => {
-                return IndexedDBUtility.get(store, docId);
-            }
-        );
-
-        if (docData) {
-            let document;
-            if (Document.isEncrypted(docData)) {
-                if (encryptionKey) {
-                    document = new Document(docData, encryptionKey);
-                } else {
-                    return false;
-                }
-            } else {
-                document = new Document(docData);
-            }
-
-            const output = await document.objectOutput(includeAttachments);
-
-            this.observer._emit('afterGet', output);
+        const collection = new Collection(name, this);
+        await collection.init();
+        this.collections.set(name, collection);
 
-            return output;
-        } else {
-            return false;
+        if (!this.metadata.collections[name]) {
+            this.metadata.setCollection(new CollectionMetadata(name));
         }
+        return collection;
     }
 
-    async getDocuments(ids, encryptionKey = null, withAttachments = false) {
-        const results = [];
-        const existingIds = ids.filter(id => id in this.metadataData.documentSizes);
-
-        if (existingIds.length === 0) {
-            return results;
+    async getCollection(name) {
+        if (this.collections.has(name)) {
+            return this.collections.get(name);
         }
+        if (this.metadata.collections[name]) {
+            const collection = new Collection(name, this);
+            await collection.init();
+            this.collections.set(name, collection);
+            return collection;
+        }
+        throw new LacertaDBError(`Collection '${name}' not found.`, 'COLLECTION_NOT_FOUND');
+    }
 
-        await IndexedDBUtility.performTransaction(
-            this.database.db,
-            this.name,
-            'readonly',
-            async (store) => {
-                const getPromises = existingIds.map(id => IndexedDBUtility.get(store, id));
-                const docsData = await Promise.all(getPromises);
+    async dropCollection(name) {
+        if (this.collections.has(name)) {
+            const collection = this.collections.get(name);
+            await collection.clear();
+            collection.destroy();
+            this.collections.delete(name);
+        }
 
-                for (const docData of docsData) {
-                    if (docData) {
-                        let document;
-                        if (Document.isEncrypted(docData)) {
-                            if (encryptionKey) {
-                                document = new Document(docData, encryptionKey);
-                            } else {
-                                continue;
-                            }
-                        } else {
-                            document = new Document(docData);
-                        }
+        this.metadata.removeCollection(name);
 
-                        const output = await document.objectOutput(withAttachments);
-                        results.push(output);
-                    }
-                }
-            }
-        );
+        const dbName = `${this.name}_${name}`;
+        await new Promise((resolve, reject) => {
+            const deleteReq = indexedDB.deleteDatabase(dbName);
+            deleteReq.onsuccess = resolve;
+            deleteReq.onerror = reject;
+            deleteReq.onblocked = () => console.warn(`Deletion of '${dbName}' is blocked.`);
+        });
+    }
 
-        return results;
+    listCollections() {
+        return Object.keys(this.metadata.collections);
     }
 
-    async deleteDocument(docId, force = false) {
-        this.observer._emit('beforeDelete', docId);
+    getStats() {
+        return {
+            name: this.name,
+            totalSizeKB: this.metadata.totalSizeKB,
+            totalDocuments: this.metadata.totalLength,
+            collections: Object.entries(this.metadata.collections).map(([name, data]) => ({
+                name,
+                sizeKB: data.sizeKB,
+                documents: data.length,
+                createdAt: new Date(data.createdAt).toISOString(),
+                modifiedAt: new Date(data.modifiedAt).toISOString()
+            }))
+        };
+    }
 
-        const isPermanent = this.permanents[docId] || false;
-        if (isPermanent && !force) {
-            return false;
-        }
+    updateSettings(newSettings) { this.settings.updateSettings(newSettings); }
 
-        const docExists = docId in this.sizes;
+    async export(format = 'json', password = null) {
+        const data = {
+            version: '4.0.3',
+            database: this.name,
+            timestamp: Date.now(),
+            collections: {}
+        };
 
-        if (!docExists) {
-            return false;
+        for (const collName of this.listCollections()) {
+            const collection = await this.getCollection(collName);
+            data.collections[collName] = await collection.getAll({ password });
         }
 
-        const attachmentCount = this.metadata.documentAttachments[docId] || 0;
-        if (attachmentCount > 0) {
-            await OPFSUtility.deleteAttachments(
-                this.database.name,
-                this.name,
-                docId
-            );
+        if (format === 'json') {
+            const serialized = serializer.serialize(data);
+            return base64.encode(serialized);
         }
-
-        await IndexedDBUtility.performTransaction(
-            this.database.db,
-            this.name,
-            'readwrite',
-            (store) => {
-                return IndexedDBUtility.delete(store, docId);
-            }
-        );
-
-        this.metadata.deleteDocument(docId);
-
-        await this.database.metadata.saveMetadata();
-
-        this.observer._emit('afterDelete', docId);
-
-        return true;
+        if (format === 'encrypted' && password) {
+            const encryption = new BrowserEncryptionUtility();
+            const serializedData = serializer.serialize(data);
+            const encrypted = await encryption.encrypt(serializedData, password);
+            return base64.encode(encrypted);
+        }
+        throw new LacertaDBError(`Unsupported export format: ${format}`, 'INVALID_FORMAT');
     }
 
-    async freeSpace(size) {
-        let spaceToFree;
-        this.lastFreeSpaceTime = Date.now();
-        const currentSize = this.sizeKB;
-
-        if (size >= 0) {
-            if (currentSize <= size) {
-                return 0;
+    async import(data, format = 'json', password = null) {
+        let parsed;
+        try {
+            const decoded = base64.decode(data);
+            if (format === 'encrypted' && password) {
+                const encryption = new BrowserEncryptionUtility();
+                const decrypted = await encryption.decrypt(decoded, password);
+                parsed = serializer.deserialize(decrypted);
             } else {
-                spaceToFree = currentSize - size;
+                parsed = serializer.deserialize(decoded);
             }
-        } else {
-            spaceToFree = -size;
-            size = currentSize - spaceToFree;
+        } catch (e) {
+            throw new LacertaDBError('Failed to parse import data', 'IMPORT_PARSE_FAILED', e);
         }
 
-        const docEntries = Object.entries(this.metadataData.documentModifiedAt)
-            .filter(([docId]) => !this.metadataData.documentPermanent[docId])
-            .sort((a, b) => a[1] - b[1]);
-
-        let totalFreed = 0;
-
-        for (const [docId] of docEntries) {
-            if(this.sizeKB > size){
-                const docSize = this.metadataData.documentSizes[docId];
-                totalFreed += docSize;
-                await this.deleteDocument(docId, true);
-                if (totalFreed >= spaceToFree) {
-                    break;
-                }
-            }
+        for (const collName in parsed.collections) {
+            const docs = parsed.collections[collName];
+            const collection = await this.createCollection(collName).catch(() => this.getCollection(collName));
+            await collection.batchAdd(docs);
         }
 
-        return totalFreed;
+        const docCount = Object.values(parsed.collections).reduce((sum, docs) => sum + docs.length, 0);
+        return {
+            collections: Object.keys(parsed.collections).length,
+            documents: docCount
+        };
     }
 
-    async query(filter = {}, options = {}) {
-        const {
-            encryptionKey = null,
-            limit = Infinity,
-            offset = 0,
-            orderBy = null,
-            index = null
-        } = options;
-
-        // FIXED: Collect raw document data first, then process async operations after transaction
-        const rawDocuments = [];
-        
-        await IndexedDBUtility.performTransaction(
-            this.database.db,
-            this.name,
-            'readonly',
-            async (store) => {
-                let source = store;
-
-                if (index && store.indexNames.contains(index)) {
-                    source = store.index(index);
-                }
-
-                const request = orderBy
-                    ? source.openCursor(null, orderBy === 'asc' ? 'next' : 'prev')
-                    : source.openCursor();
+    async clearAll() {
+        await Promise.all([...this.collections.keys()].map(name => this.dropCollection(name)));
+        this.collections.clear();
+        this.metadata = new DatabaseMetadata(this.name);
+        this.metadata.save();
+        this.quickStore.clear();
+    }
 
-                return new Promise((resolve, reject) => {
-                    let count = 0;
-                    let skipped = 0;
+    destroy() {
+        this.collections.forEach(collection => collection.destroy());
+        this.collections.clear();
+    }
+}
 
-                    request.onsuccess = (event) => {
-                        const cursor = event.target.result;
+// ========================
+// Main LacertaDB Class
+// ========================
 
-                        if (!cursor || count >= limit) {
-                            resolve();
-                            return;
-                        }
+export class LacertaDB {
+    constructor() {
+        this.databases = new Map();
+        this.performanceMonitor = new PerformanceMonitor();
+    }
 
-                        if (skipped < offset) {
-                            skipped++;
-                            cursor.continue();
-                            return;
-                        }
+    async getDatabase(name) {
+        if (!this.databases.has(name)) {
+            const db = new Database(name, this.performanceMonitor);
+            await db.init();
+            this.databases.set(name, db);
+        }
+        return this.databases.get(name);
+    }
 
-                        // FIXED: Just collect raw data, no async operations here
-                        const docData = cursor.value;
-                        rawDocuments.push(docData);
-                        count++;
-                        
-                        cursor.continue();
-                    };
+    async dropDatabase(name) {
+        if (this.databases.has(name)) {
+            const db = this.databases.get(name);
+            await db.clearAll();
+            db.destroy();
+            this.databases.delete(name);
+        }
 
-                    request.onerror = () => reject(request.error);
-                });
-            }
-        );
-
-        // FIXED: Process documents after transaction is complete
-        const results = [];
-        
-        for (const docData of rawDocuments) {
-            let document;
-            if (Document.isEncrypted(docData)) {
-                if (!encryptionKey) {
-                    continue; // Skip encrypted documents without key
-                }
-                document = new Document(docData, encryptionKey);
-            } else {
-                document = new Document(docData);
+        ['metadata', 'settings', 'version'].forEach(suffix => {
+            localStorage.removeItem(`lacertadb_${name}_${suffix}`);
+        });
+        const quickStore = new QuickStore(name);
+        quickStore.clear();
+    }
+
+    listDatabases() {
+        const dbNames = new Set();
+        for (let i = 0; i < localStorage.length; i++) {
+            const key = localStorage.key(i);
+            // Replaced optional chaining with `&&` for compatibility
+            if (key && key.startsWith('lacertadb_')) {
+                const dbName = key.split('_')[1];
+                dbNames.add(dbName);
             }
+        }
+        return [...dbNames];
+    }
 
-            // Apply filters if any
-            if (Object.keys(filter).length > 0) {
-                const object = await document.objectOutput();
-                let match = true;
+    async createBackup(password = null) {
+        const backup = {
+            version: '4.0.3',
+            timestamp: Date.now(),
+            databases: {}
+        };
 
-                for (const key in filter) {
-                    const value = key.includes('.')
-                        ? getNestedValue(object.data, key)
-                        : object.data[key];
+        for (const dbName of this.listDatabases()) {
+            const db = await this.getDatabase(dbName);
+            const exported = await db.export('json');
+            const decoded = base64.decode(exported);
+            backup.databases[dbName] = serializer.deserialize(decoded);
+        }
 
-                    if (value !== filter[key]) {
-                        match = false;
-                        break;
-                    }
-                }
+        const serializedBackup = serializer.serialize(backup);
+        if (password) {
+            const encryption = new BrowserEncryptionUtility();
+            const encrypted = await encryption.encrypt(serializedBackup, password);
+            return base64.encode(encrypted);
+        }
+        return base64.encode(serializedBackup);
+    }
 
-                if (!match) {
-                    continue;
-                }
+    async restoreBackup(backupData, password = null) {
+        let backup;
+        try {
+            let decodedData = base64.decode(backupData);
+            if (password) {
+                const encryption = new BrowserEncryptionUtility();
+                const decrypted = await encryption.decrypt(decodedData, password);
+                backup = serializer.deserialize(decrypted);
+            } else {
+                backup = serializer.deserialize(decodedData);
             }
-
-            results.push(await document.objectOutput());
+        } catch (e) {
+            throw new LacertaDBError('Failed to parse backup data', 'BACKUP_PARSE_FAILED', e);
         }
 
-        return results;
-    }
+        const results = { databases: 0, collections: 0, documents: 0 };
+        for (const [dbName, dbData] of Object.entries(backup.databases)) {
+            const db = await this.getDatabase(dbName);
+            const encodedDbData = base64.encode(serializer.serialize(dbData));
+            const importResult = await db.import(encodedDbData);
 
-    async close() {
-        if (this._freeSpaceInterval) {
-            clearInterval(this._freeSpaceInterval);
-            this._freeSpaceInterval = null;
-            this._freeSpaceHandler = null;
+            results.databases++;
+            results.collections += importResult.collections;
+            results.documents += importResult.documents;
         }
-    }
-
-    toString() {
-        return `[Collection: ${this.name} | Database: ${this.database.name} | Size: ${this.sizeKB.toFixed(2)}KB | Documents: ${this.length}]`;
+        return results;
     }
 }
 
+// Export all major components for advanced usage
+export {
+    Database,
+    Collection,
+    Document,
+    MigrationManager,
+    PerformanceMonitor,
+    LacertaDBError,
+    OPFSUtility
+};