@pixagram/lacerta-db 0.0.1

package/index.js

@@ -0,0 +1,2031 @@
+/*
+The MIT License (MIT)
+Copyright (c) 2024 Matias Affolter
+
+CRITICAL DEPENDENCY: This module requires JOYSON library for serialization.
+Install via: npm install joyson or include via CDN
+*/
+"use strict";
+import JOYSON from "joyson";
+
+// 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];
+
+        let dirHandle = rootHandle;
+        for (const part of pathParts) {
+            dirHandle = await dirHandle.getDirectoryHandle(part, { create: true });
+        }
+
+        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();
+
+            const filePath = `${dbName}/${collectionName}/${documentId}/${fileId}`;
+            attachmentPaths.push(filePath);
+        }
+
+        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}`);
+            }
+        }
+
+        return attachments;
+    }
+
+    static async deleteAttachments(dbName, collectionName, documentId) {
+        const rootHandle = await navigator.storage.getDirectory();
+        const pathParts = [dbName, collectionName, documentId];
+
+        let dirHandle = rootHandle;
+        for (let i = 0; i < pathParts.length - 1; i++) {
+            dirHandle = await dirHandle.getDirectoryHandle(pathParts[i]);
+        }
+
+        try {
+            await dirHandle.removeEntry(pathParts[pathParts.length - 1], { recursive: true });
+        } catch (error) {
+            console.error(`Error deleting attachments for document "${documentId}": ${error.message}`);
+        }
+    }
+
+    toString() {
+        return '[OPFSUtility]';
+    }
+}
+
+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();
+
+        writer.write(data);
+        writer.close();
+
+        return await this._streamToUint8Array(stream.readable);
+    }
+
+    static async decompress(compressedData) {
+        const stream = new DecompressionStream('deflate');
+        const writer = stream.writable.getWriter();
+
+        writer.write(compressedData);
+        writer.close();
+
+        return await this._streamToUint8Array(stream.readable);
+    }
+
+    static async _streamToUint8Array(readableStream) {
+        const reader = readableStream.getReader();
+        const chunks = [];
+        let totalLength = 0;
+
+        while (true) {
+            const { value, done } = await reader.read();
+            if (done) break;
+            chunks.push(value);
+            totalLength += value.length;
+        }
+
+        const result = new Uint8Array(totalLength);
+        let offset = 0;
+        for (const chunk of chunks) {
+            result.set(chunk, offset);
+            offset += chunk.length;
+        }
+
+        return result;
+    }
+
+    toString() {
+        return '[BrowserCompressionUtility]';
+    }
+}
+
+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"]
+        );
+    }
+
+    static async _generateChecksum(data) {
+        return new Uint8Array(
+            await crypto.subtle.digest("SHA-256", data)
+        );
+    }
+
+    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;
+            }
+        }
+        return true;
+    }
+
+    static _combineDataAndChecksum(data, checksum) {
+        const combined = new Uint8Array(data.length + checksum.length);
+        combined.set(data);
+        combined.set(checksum, data.length);
+        return combined;
+    }
+
+    static _separateDataAndChecksum(combinedData) {
+        const dataLength = combinedData.length - 32;
+        const data = combinedData.slice(0, dataLength);
+        const checksum = combinedData.slice(dataLength);
+        return { data, checksum };
+    }
+
+    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;
+    }
+
+    static _unwrapUint8Array(wrappedData) {
+        const salt = wrappedData.slice(0, 16);
+        const iv = wrappedData.slice(16, 28);
+        const encryptedData = wrappedData.slice(28);
+        return { salt, iv, encryptedData };
+    }
+
+    toString() {
+        return '[BrowserEncryptionUtility]';
+    }
+}
+
+class IndexedDBUtility {
+    static openDatabase(dbName, version = null, upgradeCallback = null) {
+        return new Promise((resolve, reject) => {
+            let request;
+
+            if (version) {
+                request = indexedDB.open(dbName, version);
+            } else {
+                request = indexedDB.open(dbName);
+            }
+
+            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}`);
+
+                if (upgradeCallback) {
+                    upgradeCallback(db, oldVersion, 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}`));
+            };
+        });
+    }
+
+    // FIXED: Improved transaction retry logic with idempotency check
+    static async performTransaction(db, storeNames, mode, callback, retries = 3, operationId = null) {
+        let lastError = null;
+        
+        for (let attempt = 0; attempt <= retries; attempt++) {
+            try {
+                if (!db) {
+                    throw new Error('Database connection is not available.');
+                }
+                
+                const tx = db.transaction(Array.isArray(storeNames) ? storeNames : [storeNames], mode);
+                const stores = Array.isArray(storeNames) 
+                    ? storeNames.map(name => tx.objectStore(name)) 
+                    : [tx.objectStore(storeNames)];
+                
+                // Track if operation has been applied
+                const operationKey = operationId || `${Date.now()}_${Math.random()}`;
+                
+                const result = await callback(...stores, operationKey);
+
+                return new Promise((resolve, reject) => {
+                    tx.oncomplete = () => resolve(result);
+                    tx.onerror = () => {
+                        lastError = new Error(`Transaction failed: ${tx.error ? tx.error.message : 'unknown error'}`);
+                        reject(lastError);
+                    };
+                    tx.onabort = () => {
+                        lastError = new Error(`Transaction aborted: ${tx.error ? tx.error.message : 'unknown reason'}`);
+                        reject(lastError);
+                    };
+                });
+            } catch (error) {
+                lastError = error;
+                if (attempt < retries) {
+                    console.warn(`Transaction failed, retrying... (${retries - attempt} attempts left): ${error.message}`);
+                    // Exponential backoff
+                    await new Promise(resolve => setTimeout(resolve, Math.pow(2, attempt) * 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}`);
+        });
+    }
+
+    static put(store, record) {
+        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}`);
+        });
+    }
+
+    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}`);
+        });
+    }
+
+    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}`);
+        });
+    }
+
+    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}`);
+        });
+    }
+
+    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}`);
+        });
+    }
+
+    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}`);
+        });
+    }
+
+    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}`);
+        });
+    }
+
+    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}`);
+        });
+    }
+
+    toString() {
+        return '[IndexedDBUtility]';
+    }
+}
+
+class LocalStorageUtility {
+    static getItem(key) {
+        const value = localStorage.getItem(key);
+        return value ? JOYSON.parse(value) : null;
+    }
+
+    static setItem(key, value) {
+        localStorage.setItem(key, JOYSON.stringify(value));
+    }
+
+    static removeItem(key) {
+        localStorage.removeItem(key);
+    }
+
+    static clear() {
+        localStorage.clear();
+    }
+
+    toString() {
+        return '[LocalStorageUtility]';
+    }
+}
+
+class AsyncMutex {
+    constructor() {
+        this.queue = [];
+        this.locked = false;
+    }
+
+    async acquire() {
+        return new Promise((resolve) => {
+            if (!this.locked) {
+                this.locked = true;
+                resolve();
+            } else {
+                this.queue.push(resolve);
+            }
+        });
+    }
+
+    release() {
+        if (this.queue.length > 0) {
+            const next = this.queue.shift();
+            next();
+        } else {
+            this.locked = false;
+        }
+    }
+
+    async runExclusive(callback) {
+        await this.acquire();
+        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);
+            }
+            return metadata;
+        } else {
+            return {
+                name: this._dbName,
+                collections: {},
+                totalSizeKB: 0,
+                totalLength: 0,
+                modifiedAt: Date.now(),
+            };
+        }
+    }
+
+    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();
+        }
+        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();
+        }
+    }
+
+    getCollectionNames() {
+        return Array.from(this.collections.keys());
+    }
+
+    getRawMetadata() {
+        for (const [collectionName, collectionMetadata] of this._collections.entries()) {
+            this.data.collections[collectionName] = collectionMetadata.getRawMetadata();
+        }
+        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);
+        }
+    }
+
+    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()}]`;
+    }
+}
+
+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'
+};
+
+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;
+    }
+
+    set databaseMetadata(m) {
+        this._databaseMetadata = m;
+    }
+
+    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;
+        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);
+    }
+
+    deleteDocument(docId) {
+        const docExists = docId in this.documentSizes;
+        if (!docExists) {
+            return false;
+        }
+
+        const docSizeKB = this.documentSizes[docId];
+
+        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;
+    }
+
+    toString() {
+        return `[LacertaDBResult success:${this.success} ${this.error ? 'error:' + this.error : ''}]`;
+    }
+}
+
+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: {},
+            };
+        }
+    }
+
+    _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 = JOYSON.stringify({
+            _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];
+        }
+
+        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;
+        }
+    }
+
+    getAllKeys() {
+        return Object.keys(this._metadata.documentSizesKB);
+    }
+
+    getDocumentSync(docId, encryptionKey = null) {
+        const key = this._documentKeyPrefix + docId;
+        const dataString = localStorage.getItem(key);
+
+        if (dataString) {
+            const docData = JOYSON.parse(dataString);
+            const document = new Document(docData, encryptionKey);
+            return document.unpackSync();
+        } else {
+            return null;
+        }
+    }
+
+    toString() {
+        return `[QuickStore: ${this._dbName} | Size: ${this._metadata.totalSizeKB.toFixed(2)}KB | Documents: ${this._metadata.totalLength}]`;
+    }
+}
+
+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();
+
+            try {
+                const result = await operation();
+                resolve(result);
+            } catch (error) {
+                reject(error);
+            }
+        }
+
+        this.processing = false;
+    }
+
+    toString() {
+        return `[TransactionManager processing:${this.processing} queue:${this.queue.length}]`;
+    }
+}
+
+class Observer {
+    constructor() {
+        this._listeners = {
+            'beforeAdd': [],
+            'afterAdd': [],
+            'beforeDelete': [],
+            'afterDelete': [],
+            'beforeGet': [],
+            'afterGet': [],
+        };
+    }
+
+    on(event, callback) {
+        if (this._listeners[event]) {
+            this._listeners[event].push(callback);
+        } else {
+            throw new Error(`Event "${event}" is not supported.`);
+        }
+    }
+
+    off(event, callback) {
+        if (this._listeners[event]) {
+            const index = this._listeners[event].indexOf(callback);
+            if (index > -1) {
+                this._listeners[event].splice(index, 1);
+            }
+        }
+    }
+
+    _emit(event, ...args) {
+        if (this._listeners[event]) {
+            for (const callback of this._listeners[event]) {
+                callback(...args);
+            }
+        }
+    }
+
+    // FIXED: Add cleanup method
+    _cleanup() {
+        for (const event in this._listeners) {
+            this._listeners[event] = [];
+        }
+    }
+
+    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;
+    }
+
+    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);
+        }
+    }
+
+    _createDataStores(db) {
+        for (const collectionName of this.collections.keys()) {
+            this._createDataStore(db, collectionName);
+        }
+    }
+
+    _createDataStore(db, collectionName) {
+        if (!db.objectStoreNames.contains(collectionName)) {
+            db.createObjectStore(collectionName, { keyPath: '_id' });
+        }
+    }
+
+    _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' });
+        }
+    }
+
+    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();
+
+        return new LacertaDBResult(true, null);
+    }
+
+    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);
+            } else {
+                return new LacertaDBResult(
+                    false,
+                    null,
+                    new LacertaDBError(
+                        `Collection "${collectionName}" does not exist`,
+                        ErrorCodes.COLLECTION_NOT_FOUND
+                    )
+                );
+            }
+        }
+    }
+
+    async close() {
+        const collections = this.collectionsArray;
+
+        for (const collection of collections) {
+            await collection.close();
+        }
+
+        if (this.db) {
+            this.db.close();
+            this.db = null;
+        }
+    }
+
+    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;
+    }
+
+    toString() {
+        return `[Database: ${this.name} | Collections: ${this.collections.size} | Size: ${this.totalSizeKB.toFixed(2)}KB | Documents: ${this.totalLength}]`;
+    }
+}
+
+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;
+
+        this._attachments = data._attachments || data.attachments || [];
+
+        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);
+        }
+
+        this._encryptionKey = encryptionKey || "";
+    }
+
+    get attachments() {
+        return this._attachments;
+    }
+
+    set attachments(value) {
+        this._attachments = value;
+    }
+
+    get data() {
+        return this._data;
+    }
+
+    get packedData() {
+        return this._packedData;
+    }
+
+    get encryptionKey() {
+        return this._encryptionKey;
+    }
+
+    set data(d) {
+        this._data = d;
+    }
+
+    set packedData(d) {
+        this._packedData = d;
+    }
+
+    set encryptionKey(d) {
+        this._encryptionKey = d;
+    }
+
+    static hasAttachments(documentData) {
+        return (documentData._attachments && documentData._attachments.length > 0) ||
+            (documentData.attachments && documentData.attachments.length > 0);
+    }
+
+    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);
+    }
+
+    static isEncrypted(documentData) {
+        return documentData._encrypted && documentData.packedData;
+    }
+
+    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 = JOYSON.unpack(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
+        };
+    }
+
+    async pack() {
+        if (!this.data) {
+            throw new Error('No data to pack');
+        }
+
+        let packedData = JOYSON.pack(this.data);
+        if (this._compressed) {
+            packedData = await this._compressData(packedData);
+        }
+        if (this._encrypted) {
+            packedData = await this._encryptData(packedData);
+        }
+        this.packedData = packedData;
+        return packedData;
+    }
+
+    packSync() {
+        if (!this.data) {
+            throw new Error('No data to pack');
+        }
+
+        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.")
+        }
+
+        let packedData = JOYSON.pack(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 = JOYSON.unpack(unpackedData);
+        }
+        return this.data;
+    }
+
+    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.")
+            }
+            this.data = JOYSON.unpack(this.packedData);
+        }
+        return this.data;
+    }
+
+    async _encryptData(data) {
+        const encryptionKey = this.encryptionKey;
+        return await BrowserEncryptionUtility.encrypt(data, encryptionKey);
+    }
+
+    async _decryptData(data) {
+        const encryptionKey = this.encryptionKey;
+        return await BrowserEncryptionUtility.decrypt(data, encryptionKey);
+    }
+
+    async _compressData(data) {
+        return await BrowserCompressionUtility.compress(data);
+    }
+
+    async _decompressData(data) {
+        return await BrowserCompressionUtility.decompress(data);
+    }
+
+    _generateId() {
+        return 'xxxx-xxxx-xxxx'.replace(/[x]/g, () => (Math.random() * 16 | 0).toString(16));
+    }
+
+    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,
+        };
+
+        if (includeAttachments && this.attachments.length > 0) {
+            const attachments = await OPFSUtility.getAttachments(this.attachments);
+            output.attachments = attachments;
+        }
+
+        return output;
+    }
+
+    async databaseOutput() {
+        if (!this.packedData || this.packedData.length === 0) {
+            await this.pack();
+        }
+
+        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,
+        };
+    }
+
+    toString() {
+        return `[Document: ${this._id} | Created: ${new Date(this._created).toISOString()} | Encrypted: ${this._encrypted} | Compressed: ${this._compressed} | Permanent: ${this._permanent}]`;
+    }
+}
+
+class Settings {
+    constructor(dbName, newSettings = {}) {
+        this._dbName = dbName;
+        this._settingsKey = `lacertadb_${this._dbName}_settings`;
+        this._data = this._loadSettings();
+        this._mergeSettings(newSettings);
+    }
+
+    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.");
+        }
+
+        this.set('freeSpaceEvery', this._validateFreeSpaceSetting(this.get('freeSpaceEvery')));
+    }
+
+    _validateFreeSpaceSetting(value = 10000) {
+        if (value === undefined || value === false || value === 0) {
+            return Infinity;
+        }
+        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;
+    }
+
+    _loadSettings() {
+        const settings = LocalStorageUtility.getItem(this.settingsKey);
+        return settings ? settings : {};
+    }
+
+    _saveSettings() {
+        LocalStorageUtility.setItem(this.settingsKey, this.data);
+    }
+
+    _mergeSettings(newSettings) {
+        this.data = Object.assign(this.data, newSettings);
+        this._saveSettings();
+    }
+
+    get(key) {
+        return this.data[key];
+    }
+
+    set(key, value) {
+        this.data[key] = value;
+        this._saveSettings();
+    }
+
+    remove(key) {
+        delete this.data[key];
+        this._saveSettings();
+    }
+
+    clear() {
+        this.data = {};
+        this._saveSettings();
+    }
+
+    get dbName() {
+        return this._dbName;
+    }
+
+    get data() {
+        return this._data;
+    }
+
+    set data(s) {
+        this._data = s;
+    }
+
+    get settingsKey() {
+        return this._settingsKey;
+    }
+
+    toString() {
+        return `[Settings: ${this.dbName} | SizeLimit: ${this.get('sizeLimitKB')}KB | BufferLimit: ${this.get('bufferLimitKB')}KB]`;
+    }
+}
+
+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 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
+            );
+        }
+    }
+
+    get name() {
+        return this._collectionName;
+    }
+
+    get sizes() {
+        return this.metadataData.documentSizes || {};
+    }
+
+    get modifications() {
+        return this.metadataData.documentModifiedAt || {};
+    }
+
+    get attachments() {
+        return this.metadataData.documentAttachments || {};
+    }
+
+    get permanents() {
+        return this.metadataData.documentPermanent || {};
+    }
+
+    get keys() {
+        return Object.keys(this.sizes);
+    }
+
+    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]
+            };
+        }
+
+        return metadata;
+    }
+
+    get settings() {
+        return this._settings;
+    }
+
+    get settingsData() {
+        return this.settings.data;
+    }
+
+    set settings(d) {
+        this._settings = d;
+    }
+
+    get lastFreeSpaceTime() {
+        return this._lastFreeSpaceTime;
+    }
+
+    set lastFreeSpaceTime(t) {
+        this._lastFreeSpaceTime = t;
+    }
+
+    get database() {
+        return this._database;
+    }
+
+    get metadata() {
+        // FIXED: Always access through database metadata for consistency
+        return this.database.metadata.getCollectionMetadata(this.name);
+    }
+
+    get metadataData() {
+        return this.metadata.getRawMetadata();
+    }
+
+    set metadata(m) {
+        this._metadata = m;
+    }
+
+    get sizeKB() {
+        return this.metadataData.sizeKB;
+    }
+
+    get length() {
+        return this.metadataData.length;
+    }
+
+    get totalSizeKB() {
+        return this.sizeKB;
+    }
+
+    get totalLength() {
+        return this.length;
+    }
+
+    get modifiedAt() {
+        return this.metadataData.modifiedAt;
+    }
+
+    get isFreeSpaceEnabled() {
+        return this.settingsData.freeSpaceEvery !== Infinity;
+    }
+
+    get shouldRunFreeSpaceSize() {
+        return (this.totalSizeKB > this.settingsData.sizeLimitKB + this.settingsData.bufferLimitKB);
+    }
+
+    get shouldRunFreeSpaceTime() {
+        return (this.isFreeSpaceEnabled && (Date.now() - this.lastFreeSpaceTime >= this.settingsData.freeSpaceEvery));
+    }
+
+    async _maybeFreeSpace() {
+        if(this.shouldRunFreeSpaceSize || this.shouldRunFreeSpaceTime){
+            return this.freeSpace(this.settingsData.sizeLimitKB);
+        }
+    }
+
+    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
+                );
+
+                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();
+
+            this.observer._emit('afterAdd', documentData);
+
+            return isNewDocument;
+        });
+    }
+
+    async getDocument(docId, encryptionKey = null, includeAttachments = false) {
+        this.observer._emit('beforeGet', docId);
+
+        if (!(docId in this.metadataData.documentSizes)) {
+            return false;
+        }
+
+        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);
+
+            return output;
+        } else {
+            return false;
+        }
+    }
+
+    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;
+        }
+
+        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);
+
+                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);
+                        }
+
+                        const output = await document.objectOutput(withAttachments);
+                        results.push(output);
+                    }
+                }
+            }
+        );
+
+        return results;
+    }
+
+    async deleteDocument(docId, force = false) {
+        this.observer._emit('beforeDelete', docId);
+
+        const isPermanent = this.permanents[docId] || false;
+        if (isPermanent && !force) {
+            return false;
+        }
+
+        const docExists = docId in this.sizes;
+
+        if (!docExists) {
+            return false;
+        }
+
+        const attachmentCount = this.metadata.documentAttachments[docId] || 0;
+        if (attachmentCount > 0) {
+            await OPFSUtility.deleteAttachments(
+                this.database.name,
+                this.name,
+                docId
+            );
+        }
+
+        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;
+    }
+
+    async freeSpace(size) {
+        let spaceToFree;
+        this.lastFreeSpaceTime = Date.now();
+        const currentSize = this.sizeKB;
+
+        if (size >= 0) {
+            if (currentSize <= size) {
+                return 0;
+            } else {
+                spaceToFree = currentSize - size;
+            }
+        } else {
+            spaceToFree = -size;
+            size = currentSize - spaceToFree;
+        }
+
+        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;
+                }
+            }
+        }
+
+        return totalFreed;
+    }
+
+    async query(filter = {}, options = {}) {
+        const {
+            encryptionKey = null,
+            limit = Infinity,
+            offset = 0,
+            orderBy = null,
+            index = null
+        } = options;
+
+        const results = [];
+        let count = 0;
+        let skipped = 0;
+
+        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();
+
+                return new Promise((resolve, reject) => {
+                    request.onsuccess = async (event) => {
+                        const cursor = event.target.result;
+
+                        if (!cursor || count >= limit) {
+                            resolve(results);
+                            return;
+                        }
+
+                        const docData = cursor.value;
+
+                        if (skipped < offset) {
+                            skipped++;
+                            cursor.continue();
+                            return;
+                        }
+
+                        let document;
+                        if (Document.isEncrypted(docData)) {
+                            if (!encryptionKey) {
+                                cursor.continue();
+                                return;
+                            }
+                            document = new Document(docData, encryptionKey);
+                        } else {
+                            document = new Document(docData);
+                        }
+
+                        if (Object.keys(filter).length > 0) {
+                            const object = await document.objectOutput();
+                            let match = true;
+
+                            for (const key in filter) {
+                                const value = key.includes('.')
+                                    ? getNestedValue(object.data, key)
+                                    : object.data[key];
+
+                                if (value !== filter[key]) {
+                                    match = false;
+                                    break;
+                                }
+                            }
+
+                            if (!match) {
+                                cursor.continue();
+                                return;
+                            }
+                        }
+
+                        results.push(await document.objectOutput());
+                        count++;
+                        cursor.continue();
+                    };
+
+                    request.onerror = () => reject(request.error);
+                });
+            }
+        );
+
+        return results;
+    }
+
+    async close() {
+        if (this._freeSpaceInterval) {
+            clearInterval(this._freeSpaceInterval);
+            this._freeSpaceInterval = null;
+            this._freeSpaceHandler = null;
+        }
+    }
+
+    toString() {
+        return `[Collection: ${this.name} | Database: ${this.database.name} | Size: ${this.sizeKB.toFixed(2)}KB | Documents: ${this.length}]`;
+    }
+}