@pixagram/lacerta-db 0.3.1 → 0.5.1

package/index.js

@@ -1,13 +1,14 @@
 /**
- * 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)
+ * LacertaDB V5.0.0 - Complete Production Library
+ * A powerful browser-based document database with encryption, compression, OPFS support,
+ * custom indexes, LRU caching, and database-level security for private keys
+ * @version 5.0.0
  * @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.
+
+// Dependencies - for browser environments using a bundler (e.g., Webpack, Vite)
 import TurboSerial from "@pixagram/turboserial";
 import TurboBase64 from "@pixagram/turbobase64";
 
@@ -20,9 +21,10 @@ const serializer = new TurboSerial({
 });
 const base64 = new TurboBase64();
 
-/**
- * Async Mutex for managing concurrent operations
- */
+// ========================
+// Async Mutex for managing concurrent operations
+// ========================
+
 class AsyncMutex {
     constructor() {
         this._queue = [];
@@ -60,9 +62,10 @@ class AsyncMutex {
     }
 }
 
-/**
- * Custom error class for LacertaDB
- */
+// ========================
+// Custom error class for LacertaDB
+// ========================
+
 class LacertaDBError extends Error {
     constructor(message, code, originalError) {
         super(message);
@@ -73,6 +76,269 @@ class LacertaDBError extends Error {
     }
 }
 
+// ========================
+// LRU Cache Implementation
+// ========================
+
+class LRUCache {
+    constructor(maxSize = 100, ttl = null) {
+        this.maxSize = maxSize;
+        this.ttl = ttl;
+        this.cache = new Map();
+        this.accessOrder = [];
+        this.timestamps = new Map();
+    }
+
+    get(key) {
+        if (!this.cache.has(key)) {
+            return null;
+        }
+
+        if (this.ttl) {
+            const timestamp = this.timestamps.get(key);
+            if (Date.now() - timestamp > this.ttl) {
+                this.delete(key);
+                return null;
+            }
+        }
+
+        const index = this.accessOrder.indexOf(key);
+        if (index > -1) {
+            this.accessOrder.splice(index, 1);
+        }
+        this.accessOrder.push(key);
+
+        return this.cache.get(key);
+    }
+
+    set(key, value) {
+        if (this.cache.has(key)) {
+            const index = this.accessOrder.indexOf(key);
+            if (index > -1) {
+                this.accessOrder.splice(index, 1);
+            }
+        }
+
+        this.cache.set(key, value);
+        this.accessOrder.push(key);
+        this.timestamps.set(key, Date.now());
+
+        while (this.cache.size > this.maxSize) {
+            const oldest = this.accessOrder.shift();
+            this.cache.delete(oldest);
+            this.timestamps.delete(oldest);
+        }
+    }
+
+    delete(key) {
+        const index = this.accessOrder.indexOf(key);
+        if (index > -1) {
+            this.accessOrder.splice(index, 1);
+        }
+        this.timestamps.delete(key);
+        return this.cache.delete(key);
+    }
+
+    clear() {
+        this.cache.clear();
+        this.accessOrder = [];
+        this.timestamps.clear();
+    }
+
+    has(key) {
+        if (this.ttl && this.cache.has(key)) {
+            const timestamp = this.timestamps.get(key);
+            if (Date.now() - timestamp > this.ttl) {
+                this.delete(key);
+                return false;
+            }
+        }
+        return this.cache.has(key);
+    }
+
+    get size() {
+        return this.cache.size;
+    }
+}
+
+// LFU (Least Frequently Used) Cache
+class LFUCache {
+    constructor(maxSize = 100, ttl = null) {
+        this.maxSize = maxSize;
+        this.ttl = ttl;
+        this.cache = new Map();
+        this.frequencies = new Map();
+        this.timestamps = new Map();
+    }
+
+    get(key) {
+        if (!this.cache.has(key)) {
+            return null;
+        }
+
+        if (this.ttl) {
+            const timestamp = this.timestamps.get(key);
+            if (Date.now() - timestamp > this.ttl) {
+                this.delete(key);
+                return null;
+            }
+        }
+
+        this.frequencies.set(key, (this.frequencies.get(key) || 0) + 1);
+        return this.cache.get(key);
+    }
+
+    set(key, value) {
+        if (this.cache.has(key)) {
+            this.cache.set(key, value);
+            this.frequencies.set(key, (this.frequencies.get(key) || 0) + 1);
+        } else {
+            if (this.cache.size >= this.maxSize) {
+                let minFreq = Infinity;
+                let evictKey = null;
+                for (const [k, freq] of this.frequencies) {
+                    if (freq < minFreq) {
+                        minFreq = freq;
+                        evictKey = k;
+                    }
+                }
+                if (evictKey) {
+                    this.delete(evictKey);
+                }
+            }
+            
+            this.cache.set(key, value);
+            this.frequencies.set(key, 1);
+            this.timestamps.set(key, Date.now());
+        }
+    }
+
+    delete(key) {
+        this.frequencies.delete(key);
+        this.timestamps.delete(key);
+        return this.cache.delete(key);
+    }
+
+    clear() {
+        this.cache.clear();
+        this.frequencies.clear();
+        this.timestamps.clear();
+    }
+
+    has(key) {
+        return this.cache.has(key);
+    }
+
+    get size() {
+        return this.cache.size;
+    }
+}
+
+// TTL (Time To Live) Only Cache
+class TTLCache {
+    constructor(ttl = 60000) {
+        this.ttl = ttl;
+        this.cache = new Map();
+        this.timers = new Map();
+    }
+
+    get(key) {
+        return this.cache.get(key) || null;
+    }
+
+    set(key, value) {
+        if (this.timers.has(key)) {
+            clearTimeout(this.timers.get(key));
+        }
+
+        this.cache.set(key, value);
+        
+        const timer = setTimeout(() => {
+            this.delete(key);
+        }, this.ttl);
+        this.timers.set(key, timer);
+    }
+
+    delete(key) {
+        if (this.timers.has(key)) {
+            clearTimeout(this.timers.get(key));
+            this.timers.delete(key);
+        }
+        return this.cache.delete(key);
+    }
+
+    clear() {
+        for (const timer of this.timers.values()) {
+            clearTimeout(timer);
+        }
+        this.timers.clear();
+        this.cache.clear();
+    }
+
+    has(key) {
+        return this.cache.has(key);
+    }
+
+    get size() {
+        return this.cache.size;
+    }
+}
+
+// ========================
+// Cache Strategy System
+// ========================
+
+class CacheStrategy {
+    constructor(config = {}) {
+        this.type = config.type || 'lru';
+        this.maxSize = config.maxSize || 100;
+        this.ttl = config.ttl || null;
+        this.enabled = config.enabled !== false;
+        
+        this.cache = this.createCache();
+    }
+
+    createCache() {
+        switch (this.type) {
+            case 'lru':
+                return new LRUCache(this.maxSize, this.ttl);
+            case 'lfu':
+                return new LFUCache(this.maxSize, this.ttl);
+            case 'ttl':
+                return new TTLCache(this.ttl);
+            case 'none':
+                return null;
+            default:
+                return new LRUCache(this.maxSize, this.ttl);
+        }
+    }
+
+    get(key) {
+        if (!this.enabled || !this.cache) return null;
+        return this.cache.get(key);
+    }
+
+    set(key, value) {
+        if (!this.enabled || !this.cache) return;
+        this.cache.set(key, value);
+    }
+
+    delete(key) {
+        if (!this.enabled || !this.cache) return;
+        this.cache.delete(key);
+    }
+
+    clear() {
+        if (!this.enabled || !this.cache) return;
+        this.cache.clear();
+    }
+
+    updateStrategy(newConfig) {
+        Object.assign(this, newConfig);
+        this.cache = this.createCache();
+    }
+}
+
 // ========================
 // Compression Utility
 // ========================
@@ -106,7 +372,6 @@ class BrowserCompressionUtility {
         }
     }
 
-    // Fallback sync methods are simple pass-throughs
     compressSync(input) {
         if (!(input instanceof Uint8Array)) {
             throw new TypeError('Input must be Uint8Array');
@@ -123,7 +388,7 @@ class BrowserCompressionUtility {
 }
 
 // ========================
-// Encryption Utility (FIXED & IMPROVED)
+// Encryption Utility
 // ========================
 
 class BrowserEncryptionUtility {
@@ -165,7 +430,6 @@ class BrowserEncryptionUtility {
                 data
             );
 
-            // 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);
@@ -216,15 +480,984 @@ class BrowserEncryptionUtility {
                 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);
         }
     }
 }
 
+// ========================
+// Database-Level Encryption
+// ========================
+
+class SecureDatabaseEncryption {
+    constructor() {
+        this.masterKey = null;
+        this.salt = null;
+        this.iterations = 1000000;
+        this.initialized = false;
+    }
+
+    async initialize(pin, salt = null) {
+        if (this.initialized) {
+            throw new Error('Database encryption already initialized');
+        }
+
+        this.salt = salt || crypto.getRandomValues(new Uint8Array(32));
+        
+        const encoder = new TextEncoder();
+        const pinBuffer = encoder.encode(pin);
+        
+        const keyMaterial = await crypto.subtle.importKey(
+            'raw',
+            pinBuffer,
+            'PBKDF2',
+            false,
+            ['deriveBits', 'deriveKey']
+        );
+
+        const derivedBits = await crypto.subtle.deriveBits(
+            {
+                name: 'PBKDF2',
+                salt: this.salt,
+                iterations: this.iterations,
+                hash: 'SHA-512'
+            },
+            keyMaterial,
+            512
+        );
+
+        const derivedArray = new Uint8Array(derivedBits);
+        
+        const encKeyBytes = derivedArray.slice(0, 32);
+        const hmacKeyBytes = derivedArray.slice(32, 64);
+
+        this.encKey = await crypto.subtle.importKey(
+            'raw',
+            encKeyBytes,
+            { name: 'AES-GCM', length: 256 },
+            false,
+            ['encrypt', 'decrypt']
+        );
+
+        this.hmacKey = await crypto.subtle.importKey(
+            'raw',
+            hmacKeyBytes,
+            { name: 'HMAC', hash: 'SHA-256' },
+            false,
+            ['sign', 'verify']
+        );
+
+        this.initialized = true;
+        
+        return base64.encode(this.salt);
+    }
+
+    async encrypt(data) {
+        if (!this.initialized) {
+            throw new Error('Database encryption not initialized');
+        }
+
+        let dataBytes;
+        if (typeof data === 'string') {
+            dataBytes = new TextEncoder().encode(data);
+        } else if (data instanceof Uint8Array) {
+            dataBytes = data;
+        } else {
+            dataBytes = serializer.serialize(data);
+        }
+
+        const iv = crypto.getRandomValues(new Uint8Array(12));
+
+        const encryptedData = await crypto.subtle.encrypt(
+            { name: 'AES-GCM', iv },
+            this.encKey,
+            dataBytes
+        );
+
+        const hmacData = new Uint8Array(iv.length + encryptedData.byteLength);
+        hmacData.set(iv, 0);
+        hmacData.set(new Uint8Array(encryptedData), iv.length);
+        
+        const hmac = await crypto.subtle.sign(
+            'HMAC',
+            this.hmacKey,
+            hmacData
+        );
+
+        const result = new Uint8Array(
+            iv.length + encryptedData.byteLength + 32
+        );
+        result.set(iv, 0);
+        result.set(new Uint8Array(encryptedData), iv.length);
+        result.set(new Uint8Array(hmac), iv.length + encryptedData.byteLength);
+
+        return result;
+    }
+
+    async decrypt(encryptedPackage) {
+        if (!this.initialized) {
+            throw new Error('Database encryption not initialized');
+        }
+
+        if (!(encryptedPackage instanceof Uint8Array)) {
+            throw new TypeError('Encrypted data must be Uint8Array');
+        }
+
+        const iv = encryptedPackage.slice(0, 12);
+        const hmac = encryptedPackage.slice(-32);
+        const encryptedData = encryptedPackage.slice(12, -32);
+
+        const hmacData = new Uint8Array(iv.length + encryptedData.length);
+        hmacData.set(iv, 0);
+        hmacData.set(encryptedData, iv.length);
+        
+        const isValid = await crypto.subtle.verify(
+            'HMAC',
+            this.hmacKey,
+            hmac,
+            hmacData
+        );
+
+        if (!isValid) {
+            throw new Error('HMAC verification failed - data may be tampered');
+        }
+
+        const decryptedData = await crypto.subtle.decrypt(
+            { name: 'AES-GCM', iv },
+            this.encKey,
+            encryptedData
+        );
+
+        return new Uint8Array(decryptedData);
+    }
+
+    async encryptPrivateKey(privateKey, additionalAuth = '') {
+        if (!this.initialized) {
+            throw new Error('Database encryption not initialized');
+        }
+
+        const encoder = new TextEncoder();
+        const authData = encoder.encode(additionalAuth);
+
+        let keyData;
+        if (typeof privateKey === 'string') {
+            keyData = encoder.encode(privateKey);
+        } else if (privateKey instanceof Uint8Array) {
+            keyData = privateKey;
+        } else {
+            keyData = encoder.encode(JSON.stringify(privateKey));
+        }
+
+        const iv = crypto.getRandomValues(new Uint8Array(16));
+
+        const encryptedKey = await crypto.subtle.encrypt(
+            {
+                name: 'AES-GCM',
+                iv,
+                additionalData: authData,
+                tagLength: 128
+            },
+            this.encKey,
+            keyData
+        );
+
+        const authLength = new Uint32Array([authData.length]);
+        const result = new Uint8Array(
+            16 + 4 + authData.length + encryptedKey.byteLength
+        );
+        
+        result.set(iv, 0);
+        result.set(new Uint8Array(authLength.buffer), 16);
+        result.set(authData, 20);
+        result.set(new Uint8Array(encryptedKey), 20 + authData.length);
+
+        return base64.encode(result);
+    }
+
+    async decryptPrivateKey(encryptedKeyString, additionalAuth = '') {
+        if (!this.initialized) {
+            throw new Error('Database encryption not initialized');
+        }
+
+        const encryptedPackage = base64.decode(encryptedKeyString);
+        
+        const iv = encryptedPackage.slice(0, 16);
+        const authLengthBytes = encryptedPackage.slice(16, 20);
+        const authLength = new Uint32Array(authLengthBytes.buffer)[0];
+        const authData = encryptedPackage.slice(20, 20 + authLength);
+        const encryptedKey = encryptedPackage.slice(20 + authLength);
+
+        const encoder = new TextEncoder();
+        const expectedAuth = encoder.encode(additionalAuth);
+        
+        if (!this.arrayEquals(authData, expectedAuth)) {
+            throw new Error('Additional authentication data mismatch');
+        }
+
+        const decryptedKey = await crypto.subtle.decrypt(
+            {
+                name: 'AES-GCM',
+                iv,
+                additionalData: authData,
+                tagLength: 128
+            },
+            this.encKey,
+            encryptedKey
+        );
+
+        return new TextDecoder().decode(decryptedKey);
+    }
+
+    static generateSecurePIN(length = 6) {
+        const digits = new Uint8Array(length);
+        crypto.getRandomValues(digits);
+        return Array.from(digits)
+            .map(b => (b % 10).toString())
+            .join('');
+    }
+
+    destroy() {
+        this.masterKey = null;
+        this.encKey = null;
+        this.hmacKey = null;
+        this.salt = null;
+        this.initialized = false;
+    }
+
+    arrayEquals(a, b) {
+        if (a.length !== b.length) return false;
+        for (let i = 0; i < a.length; i++) {
+            if (a[i] !== b[i]) return false;
+        }
+        return true;
+    }
+
+    async changePin(oldPin, newPin) {
+        if (!this.initialized) {
+            throw new Error('Database encryption not initialized');
+        }
+
+        const currentSalt = this.salt;
+        
+        this.destroy();
+        await this.initialize(oldPin, currentSalt);
+        
+        this.destroy();
+        const newSalt = await this.initialize(newPin);
+        
+        return newSalt;
+    }
+
+    exportMetadata() {
+        if (!this.salt) {
+            throw new Error('No encryption metadata to export');
+        }
+        
+        return {
+            salt: base64.encode(this.salt),
+            iterations: this.iterations,
+            algorithm: 'AES-GCM-256',
+            kdf: 'PBKDF2-SHA-512'
+        };
+    }
+
+    importMetadata(metadata) {
+        if (!metadata.salt) {
+            throw new Error('Invalid encryption metadata');
+        }
+        
+        this.salt = base64.decode(metadata.salt);
+        this.iterations = metadata.iterations || 1000000;
+        
+        return true;
+    }
+}
+
+// ========================
+// B-Tree Index Implementation
+// ========================
+
+class BTreeNode {
+    constructor(order, leaf) {
+        this.keys = new Array(2 * order - 1);
+        this.values = new Array(2 * order - 1);
+        this.children = new Array(2 * order);
+        this.n = 0;
+        this.leaf = leaf;
+        this.order = order;
+    }
+
+    search(key) {
+        let i = 0;
+        while (i < this.n && key > this.keys[i]) {
+            i++;
+        }
+        
+        if (i < this.n && key === this.keys[i]) {
+            return this.values[i];
+        }
+        
+        if (this.leaf) {
+            return null;
+        }
+        
+        return this.children[i].search(key);
+    }
+
+    rangeSearch(min, max, results) {
+        let i = 0;
+        
+        while (i < this.n) {
+            if (!this.leaf && this.children[i]) {
+                this.children[i].rangeSearch(min, max, results);
+            }
+            
+            if (this.keys[i] >= min && this.keys[i] <= max) {
+                this.values[i].forEach(v => results.push(v));
+            }
+            
+            i++;
+        }
+        
+        if (!this.leaf && this.children[i]) {
+            this.children[i].rangeSearch(min, max, results);
+        }
+    }
+
+    insertNonFull(key, value) {
+        let i = this.n - 1;
+        
+        if (this.leaf) {
+            while (i >= 0 && this.keys[i] > key) {
+                this.keys[i + 1] = this.keys[i];
+                this.values[i + 1] = this.values[i];
+                i--;
+            }
+            
+            if (i >= 0 && this.keys[i] === key) {
+                this.values[i].add(value);
+            } else {
+                this.keys[i + 1] = key;
+                this.values[i + 1] = new Set([value]);
+                this.n++;
+            }
+        } else {
+            while (i >= 0 && this.keys[i] > key) {
+                i--;
+            }
+            
+            if (i >= 0 && this.keys[i] === key) {
+                this.values[i].add(value);
+                return;
+            }
+            
+            i++;
+            if (this.children[i].n === 2 * this.order - 1) {
+                this.splitChild(i, this.children[i]);
+                if (this.keys[i] < key) {
+                    i++;
+                }
+            }
+            this.children[i].insertNonFull(key, value);
+        }
+    }
+
+    splitChild(i, y) {
+        const z = new BTreeNode(this.order, y.leaf);
+        z.n = this.order - 1;
+        
+        for (let j = 0; j < this.order - 1; j++) {
+            z.keys[j] = y.keys[j + this.order];
+            z.values[j] = y.values[j + this.order];
+        }
+        
+        if (!y.leaf) {
+            for (let j = 0; j < this.order; j++) {
+                z.children[j] = y.children[j + this.order];
+            }
+        }
+        
+        y.n = this.order - 1;
+        
+        for (let j = this.n; j >= i + 1; j--) {
+            this.children[j + 1] = this.children[j];
+        }
+        
+        this.children[i + 1] = z;
+        
+        for (let j = this.n - 1; j >= i; j--) {
+            this.keys[j + 1] = this.keys[j];
+            this.values[j + 1] = this.values[j];
+        }
+        
+        this.keys[i] = y.keys[this.order - 1];
+        this.values[i] = y.values[this.order - 1];
+        this.n++;
+    }
+
+    remove(key, value) {
+        let i = 0;
+        while (i < this.n && key > this.keys[i]) {
+            i++;
+        }
+        
+        if (i < this.n && key === this.keys[i]) {
+            this.values[i].delete(value);
+            if (this.values[i].size === 0) {
+                for (let j = i; j < this.n - 1; j++) {
+                    this.keys[j] = this.keys[j + 1];
+                    this.values[j] = this.values[j + 1];
+                }
+                this.n--;
+            }
+        } else if (!this.leaf) {
+            this.children[i].remove(key, value);
+        }
+    }
+}
+
+class BTreeIndex {
+    constructor(order = 4) {
+        this.root = null;
+        this.order = order;
+        this.size = 0;
+    }
+
+    insert(key, value) {
+        if (!this.root) {
+            this.root = new BTreeNode(this.order, true);
+            this.root.keys[0] = key;
+            this.root.values[0] = new Set([value]);
+            this.root.n = 1;
+        } else {
+            if (this.root.n === 2 * this.order - 1) {
+                const s = new BTreeNode(this.order, false);
+                s.children[0] = this.root;
+                s.splitChild(0, this.root);
+                
+                let i = 0;
+                if (s.keys[0] < key) i++;
+                s.children[i].insertNonFull(key, value);
+                
+                this.root = s;
+            } else {
+                this.root.insertNonFull(key, value);
+            }
+        }
+        this.size++;
+    }
+
+    find(key) {
+        if (!this.root) return [];
+        const values = this.root.search(key);
+        return values ? Array.from(values) : [];
+    }
+
+    contains(key) {
+        if (!this.root) return false;
+        return this.root.search(key) !== null;
+    }
+
+    range(min, max) {
+        if (!this.root) return [];
+        const results = [];
+        this.root.rangeSearch(min, max, results);
+        return results;
+    }
+
+    rangeFrom(min) {
+        if (!this.root) return [];
+        const results = [];
+        this.root.rangeSearch(min, Infinity, results);
+        return results;
+    }
+
+    rangeTo(max) {
+        if (!this.root) return [];
+        const results = [];
+        this.root.rangeSearch(-Infinity, max, results);
+        return results;
+    }
+
+    remove(key, value) {
+        if (!this.root) return;
+        this.root.remove(key, value);
+        if (this.root.n === 0) {
+            if (!this.root.leaf && this.root.children[0]) {
+                this.root = this.root.children[0];
+            }
+        }
+        this.size--;
+    }
+}
+
+// Text Index for full-text search
+class TextIndex {
+    constructor() {
+        this.invertedIndex = new Map();
+        this.documentTexts = new Map();
+    }
+
+    addDocument(text, docId) {
+        if (typeof text !== 'string') return;
+        
+        this.documentTexts.set(docId, text);
+        const tokens = this.tokenize(text);
+        
+        for (const token of tokens) {
+            if (!this.invertedIndex.has(token)) {
+                this.invertedIndex.set(token, new Set());
+            }
+            this.invertedIndex.get(token).add(docId);
+        }
+    }
+
+    removeDocument(docId) {
+        const text = this.documentTexts.get(docId);
+        if (!text) return;
+        
+        const tokens = this.tokenize(text);
+        for (const token of tokens) {
+            const docs = this.invertedIndex.get(token);
+            if (docs) {
+                docs.delete(docId);
+                if (docs.size === 0) {
+                    this.invertedIndex.delete(token);
+                }
+            }
+        }
+        
+        this.documentTexts.delete(docId);
+    }
+
+    search(query) {
+        const tokens = this.tokenize(query);
+        if (tokens.length === 0) return [];
+        
+        let results = null;
+        for (const token of tokens) {
+            const docs = this.invertedIndex.get(token);
+            if (!docs || docs.size === 0) {
+                return [];
+            }
+            
+            if (results === null) {
+                results = new Set(docs);
+            } else {
+                results = new Set([...results].filter(x => docs.has(x)));
+            }
+        }
+        
+        return results ? Array.from(results) : [];
+    }
+
+    tokenize(text) {
+        return text.toLowerCase()
+            .replace(/[^\w\s]/g, ' ')
+            .split(/\s+/)
+            .filter(token => token.length > 2);
+    }
+
+    get size() {
+        return this.documentTexts.size;
+    }
+}
+
+// Geo Index for spatial queries
+class GeoIndex {
+    constructor() {
+        this.points = new Map();
+    }
+
+    addPoint(coords, docId) {
+        if (!coords || typeof coords.lat !== 'number' || typeof coords.lng !== 'number') {
+            return;
+        }
+        this.points.set(docId, coords);
+    }
+
+    removePoint(docId) {
+        this.points.delete(docId);
+    }
+
+    findNear(center, maxDistance) {
+        const results = [];
+        
+        for (const [docId, coords] of this.points) {
+            const distance = this.haversine(center, coords);
+            if (distance <= maxDistance) {
+                results.push({ docId, distance });
+            }
+        }
+        
+        return results.sort((a, b) => a.distance - b.distance)
+            .map(r => r.docId);
+    }
+
+    findWithin(bounds) {
+        const results = [];
+        
+        for (const [docId, coords] of this.points) {
+            if (this.isWithinBounds(coords, bounds)) {
+                results.push(docId);
+            }
+        }
+        
+        return results;
+    }
+
+    haversine(coord1, coord2) {
+        const R = 6371;
+        const dLat = this.toRad(coord2.lat - coord1.lat);
+        const dLng = this.toRad(coord2.lng - coord1.lng);
+        
+        const a = Math.sin(dLat/2) * Math.sin(dLat/2) +
+            Math.cos(this.toRad(coord1.lat)) * Math.cos(this.toRad(coord2.lat)) *
+            Math.sin(dLng/2) * Math.sin(dLng/2);
+        
+        const c = 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1-a));
+        return R * c;
+    }
+
+    toRad(deg) {
+        return deg * (Math.PI / 180);
+    }
+
+    isWithinBounds(coords, bounds) {
+        return coords.lat >= bounds.minLat && coords.lat <= bounds.maxLat &&
+               coords.lng >= bounds.minLng && coords.lng <= bounds.maxLng;
+    }
+
+    get size() {
+        return this.points.size;
+    }
+}
+
+// ========================
+// Index Manager
+// ========================
+
+class IndexManager {
+    constructor(collection) {
+        this.collection = collection;
+        this.indexes = new Map();
+        this.indexData = new Map();
+    }
+
+    async createIndex(fieldPath, options = {}) {
+        const indexName = options.name || fieldPath;
+        
+        if (this.indexes.has(indexName)) {
+            throw new Error(`Index '${indexName}' already exists`);
+        }
+
+        const index = {
+            fieldPath,
+            unique: options.unique || false,
+            sparse: options.sparse || false,
+            type: options.type || 'btree',
+            collation: options.collation || null,
+            createdAt: Date.now()
+        };
+
+        this.indexes.set(indexName, index);
+        
+        await this.rebuildIndex(indexName);
+        
+        this.saveIndexMetadata();
+        
+        return indexName;
+    }
+
+    async rebuildIndex(indexName) {
+        const index = this.indexes.get(indexName);
+        if (!index) {
+            throw new Error(`Index '${indexName}' not found`);
+        }
+
+        const indexData = this.createIndexStructure(index.type);
+        
+        const allDocs = await this.collection.getAll();
+        
+        for (const doc of allDocs) {
+            const value = this.getFieldValue(doc, index.fieldPath);
+            
+            if (index.sparse && (value === null || value === undefined)) {
+                continue;
+            }
+
+            if (index.unique && indexData.has && indexData.has(value)) {
+                throw new Error(`Unique constraint violation on index '${indexName}'`);
+            }
+
+            this.addToIndex(indexData, value, doc._id, index.type);
+        }
+
+        this.indexData.set(indexName, indexData);
+    }
+
+    createIndexStructure(type) {
+        switch (type) {
+            case 'btree':
+                return new BTreeIndex();
+            case 'hash':
+                return new Map();
+            case 'text':
+                return new TextIndex();
+            case 'geo':
+                return new GeoIndex();
+            default:
+                return new Map();
+        }
+    }
+
+    addToIndex(indexData, value, docId, type) {
+        switch (type) {
+            case 'btree':
+                indexData.insert(value, docId);
+                break;
+            case 'hash':
+                if (!indexData.has(value)) {
+                    indexData.set(value, new Set());
+                }
+                indexData.get(value).add(docId);
+                break;
+            case 'text':
+                indexData.addDocument(value, docId);
+                break;
+            case 'geo':
+                indexData.addPoint(value, docId);
+                break;
+        }
+    }
+
+    async updateIndex(indexName, docId, oldValue, newValue) {
+        const index = this.indexes.get(indexName);
+        const indexData = this.indexData.get(indexName);
+        
+        if (!index || !indexData) return;
+
+        if (oldValue !== undefined && oldValue !== null) {
+            this.removeFromIndex(indexData, oldValue, docId, index.type);
+        }
+
+        if (newValue !== undefined && newValue !== null) {
+            if (index.unique && this.indexContains(indexData, newValue, index.type)) {
+                throw new Error(`Unique constraint violation on index '${indexName}'`);
+            }
+            this.addToIndex(indexData, newValue, docId, index.type);
+        }
+    }
+
+    removeFromIndex(indexData, value, docId, type) {
+        switch (type) {
+            case 'btree':
+                indexData.remove(value, docId);
+                break;
+            case 'hash':
+                const docs = indexData.get(value);
+                if (docs) {
+                    docs.delete(docId);
+                    if (docs.size === 0) {
+                        indexData.delete(value);
+                    }
+                }
+                break;
+            case 'text':
+                indexData.removeDocument(docId);
+                break;
+            case 'geo':
+                indexData.removePoint(docId);
+                break;
+        }
+    }
+
+    indexContains(indexData, value, type) {
+        switch (type) {
+            case 'btree':
+                return indexData.contains(value);
+            case 'hash':
+                return indexData.has(value);
+            case 'text':
+                return false;
+            case 'geo':
+                return false;
+            default:
+                return false;
+        }
+    }
+
+    async query(indexName, queryOptions) {
+        const index = this.indexes.get(indexName);
+        const indexData = this.indexData.get(indexName);
+        
+        if (!index || !indexData) {
+            throw new Error(`Index '${indexName}' not found`);
+        }
+
+        return this.queryIndex(indexData, queryOptions, index.type);
+    }
+
+    queryIndex(indexData, options, type) {
+        switch (type) {
+            case 'btree':
+                return this.queryBTree(indexData, options);
+            case 'hash':
+                return this.queryHash(indexData, options);
+            case 'text':
+                return this.queryText(indexData, options);
+            case 'geo':
+                return this.queryGeo(indexData, options);
+            default:
+                return [];
+        }
+    }
+
+    queryBTree(indexData, options) {
+        const results = new Set();
+        
+        if (options.$eq !== undefined) {
+            const docs = indexData.find(options.$eq);
+            docs.forEach(doc => results.add(doc));
+        }
+        
+        if (options.$gte !== undefined && options.$lte !== undefined) {
+            const docs = indexData.range(options.$gte, options.$lte);
+            docs.forEach(doc => results.add(doc));
+        } else if (options.$gte !== undefined) {
+            const docs = indexData.rangeFrom(options.$gte);
+            docs.forEach(doc => results.add(doc));
+        } else if (options.$lte !== undefined) {
+            const docs = indexData.rangeTo(options.$lte);
+            docs.forEach(doc => results.add(doc));
+        }
+        
+        return Array.from(results);
+    }
+
+    queryHash(indexData, options) {
+        if (options.$eq !== undefined) {
+            const docs = indexData.get(options.$eq);
+            return docs ? Array.from(docs) : [];
+        }
+        
+        if (options.$in !== undefined) {
+            const results = new Set();
+            for (const value of options.$in) {
+                const docs = indexData.get(value);
+                if (docs) {
+                    docs.forEach(doc => results.add(doc));
+                }
+            }
+            return Array.from(results);
+        }
+        
+        return [];
+    }
+
+    queryText(indexData, options) {
+        if (options.$search) {
+            return indexData.search(options.$search);
+        }
+        return [];
+    }
+
+    queryGeo(indexData, options) {
+        if (options.$near) {
+            return indexData.findNear(
+                options.$near.coordinates,
+                options.$near.maxDistance || 1000
+            );
+        }
+        if (options.$within) {
+            return indexData.findWithin(options.$within);
+        }
+        return [];
+    }
+
+    dropIndex(indexName) {
+        this.indexes.delete(indexName);
+        this.indexData.delete(indexName);
+        this.saveIndexMetadata();
+    }
+
+    getFieldValue(doc, path) {
+        const parts = path.split('.');
+        let value = doc;
+        for (const part of parts) {
+            if (value === null || value === undefined) {
+                return undefined;
+            }
+            value = value[part];
+        }
+        return value;
+    }
+
+    saveIndexMetadata() {
+        const metadata = {
+            indexes: Array.from(this.indexes.entries()).map(([name, index]) => ({
+                name,
+                ...index
+            }))
+        };
+        
+        const key = `lacertadb_${this.collection.database.name}_${this.collection.name}_indexes`;
+        const serialized = serializer.serialize(metadata);
+        const encoded = base64.encode(serialized);
+        localStorage.setItem(key, encoded);
+    }
+
+    async loadIndexMetadata() {
+        const key = `lacertadb_${this.collection.database.name}_${this.collection.name}_indexes`;
+        const stored = localStorage.getItem(key);
+        
+        if (!stored) return;
+        
+        try {
+            const decoded = base64.decode(stored);
+            const metadata = serializer.deserialize(decoded);
+            
+            for (const indexDef of metadata.indexes) {
+                const { name, ...index } = indexDef;
+                this.indexes.set(name, index);
+            }
+            
+            for (const indexName of this.indexes.keys()) {
+                await this.rebuildIndex(indexName);
+            }
+        } catch (error) {
+            console.error('Failed to load index metadata:', error);
+        }
+    }
+
+    getIndexStats() {
+        const stats = {};
+        for (const [name, index] of this.indexes) {
+            const indexData = this.indexData.get(name);
+            stats[name] = {
+                ...index,
+                size: indexData ? indexData.size || indexData.length || 0 : 0,
+                memoryUsage: this.estimateMemoryUsage(indexData)
+            };
+        }
+        return stats;
+    }
+
+    estimateMemoryUsage(indexData) {
+        if (!indexData) return 0;
+        
+        if (indexData instanceof Map) {
+            return indexData.size * 100;
+        }
+        if (indexData instanceof BTreeIndex) {
+            return indexData.size * 120;
+        }
+        return 0;
+    }
+}
+
 // ========================
 // OPFS (Origin Private File System) Utility
 // ========================
@@ -298,7 +1531,6 @@ class OPFSUtility {
                 });
             } catch (error) {
                 console.error(`Failed to get attachment: ${attachmentInfo.path}`, error);
-                // Optionally, collect errors and return them
             }
         }
         return attachments;
@@ -311,7 +1543,6 @@ class OPFSUtility {
             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);
             }
@@ -498,7 +1729,6 @@ class Document {
         this.data = data.data || {};
         this.packedData = data.packedData || null;
 
-        // 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;
@@ -743,7 +1973,6 @@ class DatabaseMetadata {
 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;
@@ -886,7 +2115,6 @@ class QuickStore {
 class QueryEngine {
     constructor() {
         this.operators = {
-            // Comparison
             '$eq': (a, b) => a === b,
             '$ne': (a, b) => a !== b,
             '$gt': (a, b) => a > b,
@@ -896,22 +2124,18 @@ class QueryEngine {
             '$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 {
@@ -929,14 +2153,11 @@ class QueryEngine {
         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 {
-                // 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];
@@ -946,7 +2167,6 @@ class QueryEngine {
                         }
                     }
                 } else {
-                    // Direct equality comparison
                     if (fieldValue !== value) return false;
                 }
             }
@@ -955,7 +2175,6 @@ class QueryEngine {
     }
 
     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) {
@@ -968,7 +2187,6 @@ class QueryEngine {
 }
 const queryEngine = new QueryEngine();
 
-
 // ========================
 // Aggregation Pipeline
 // ========================
@@ -984,13 +2202,10 @@ class AggregationPipeline {
                     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 };
@@ -1002,7 +2217,7 @@ class AggregationPipeline {
 
             '$sort': (docs, sortSpec) => [...docs].sort((a, b) => {
                 for (const key in sortSpec) {
-                    const order = sortSpec[key]; // 1 for asc, -1 for desc
+                    const order = sortSpec[key];
                     const aVal = queryEngine.getFieldValue(a, key);
                     const bVal = queryEngine.getFieldValue(b, key);
                     if (aVal < bVal) return -order;
@@ -1022,7 +2237,7 @@ class AggregationPipeline {
                 for (const doc of docs) {
                     const groupKey = typeof idField === 'string' ?
                         queryEngine.getFieldValue(doc, idField.replace('$', '')) :
-                        JSON.stringify(idField); // Fallback for complex IDs
+                        JSON.stringify(idField);
 
                     if (!groups.has(groupKey)) {
                         groups.set(groupKey, { _id: groupKey, docs: [] });
@@ -1227,7 +2442,6 @@ class PerformanceMonitor {
     recordCacheMiss() { this.metrics.cacheMisses++; }
 
     collectMetrics() {
-        // Replaced optional chaining with `&&` for compatibility
         if (performance && performance.memory) {
             this.metrics.memoryUsage.push({
                 used: performance.memory.usedJSHeapSize,
@@ -1246,7 +2460,6 @@ class PerformanceMonitor {
         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;
 
@@ -1271,7 +2484,7 @@ class PerformanceMonitor {
         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
+            if (trend > 10 * 1024 * 1024) {
                 tips.push('Memory usage is increasing rapidly. Check for memory leaks or consider batch processing.');
             }
         }
@@ -1294,8 +2507,16 @@ class Collection {
         this.opfs = new OPFSUtility();
         this.cleanupInterval = null;
         this.events = new Map();
-        this.queryCache = new Map();
-        this.cacheTimeout = 60000;
+        
+        // Enhanced features
+        this.indexManager = new IndexManager(this);
+        this.cacheStrategy = new CacheStrategy({
+            type: 'lru',
+            maxSize: 100,
+            ttl: 60000,
+            enabled: true
+        });
+        
         this.performanceMonitor = database.performanceMonitor;
     }
 
@@ -1306,18 +2527,38 @@ class Collection {
                 const store = db.createObjectStore('documents', { keyPath: '_id' });
                 store.createIndex('modified', '_modified', { unique: false });
             }
-            // Future index creation logic would go here during version bumps
         });
 
         const metadataData = this.database.metadata.collections[this.name];
         this.metadata = new CollectionMetadata(this.name, metadataData);
 
+        // Load indexes
+        await this.indexManager.loadIndexMetadata();
+
         if (this.settings.freeSpaceEvery > 0) {
             this.cleanupInterval = setInterval(() => this.freeSpace(), this.settings.freeSpaceEvery);
         }
         return this;
     }
 
+    // Index methods
+    async createIndex(fieldPath, options = {}) {
+        return await this.indexManager.createIndex(fieldPath, options);
+    }
+
+    async dropIndex(indexName) {
+        return this.indexManager.dropIndex(indexName);
+    }
+
+    async getIndexes() {
+        return this.indexManager.getIndexStats();
+    }
+
+    // Cache configuration
+    configureCacheStrategy(config) {
+        this.cacheStrategy.updateStrategy(config);
+    }
+
     async add(documentData, options = {}) {
         await this.trigger('beforeAdd', documentData);
 
@@ -1342,13 +2583,22 @@ class Collection {
         const dbOutput = doc.databaseOutput();
         await this.indexedDB.add(this.db, 'documents', dbOutput);
 
+        // Update indexes
+        const fullDoc = doc.objectOutput();
+        for (const [indexName, index] of this.indexManager.indexes) {
+            const value = this.indexManager.getFieldValue(fullDoc, index.fieldPath);
+            if (value !== undefined && value !== null) {
+                await this.indexManager.updateIndex(indexName, doc._id, undefined, value);
+            }
+        }
+
         const sizeKB = dbOutput.packedData.byteLength / 1024;
         this.metadata.addDocument(doc._id, sizeKB, doc._permanent, doc._attachments.length);
         this.database.metadata.setCollection(this.metadata);
 
         await this.checkSpaceLimit();
         await this.trigger('afterAdd', doc);
-        this.queryCache.clear();
+        this.cacheStrategy.clear();
         return doc._id;
     }
 
@@ -1409,9 +2659,9 @@ class Collection {
         const existingDoc = new Document(stored, { password: options.password });
         if (stored.packedData) await existingDoc.unpack();
 
+        const oldDocOutput = existingDoc.objectOutput();
         const updatedData = { ...existingDoc.data, ...updates };
 
-        // Replaced `??` with ternary operator for compatibility
         const doc = new Document({
             _id: docId,
             _created: stored._created,
@@ -1441,21 +2691,55 @@ class Collection {
         const dbOutput = doc.databaseOutput();
         await this.indexedDB.put(this.db, 'documents', dbOutput);
 
+        // Update indexes
+        const newDocOutput = doc.objectOutput();
+        for (const [indexName, index] of this.indexManager.indexes) {
+            const oldValue = this.indexManager.getFieldValue(oldDocOutput, index.fieldPath);
+            const newValue = this.indexManager.getFieldValue(newDocOutput, index.fieldPath);
+            
+            if (oldValue !== newValue) {
+                await this.indexManager.updateIndex(indexName, doc._id, oldValue, newValue);
+            }
+        }
+
         const sizeKB = dbOutput.packedData.byteLength / 1024;
         this.metadata.updateDocument(doc._id, sizeKB, doc._permanent, doc._attachments.length);
         this.database.metadata.setCollection(this.metadata);
 
         await this.trigger('afterUpdate', doc);
-        this.queryCache.clear();
+        this.cacheStrategy.clear();
         return doc._id;
     }
 
-    async delete(docId) {
+    async delete(docId, options = {}) {
         await this.trigger('beforeDelete', docId);
 
         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');
+        if (!doc) {
+            throw new LacertaDBError('Document not found for deletion', 'DOCUMENT_NOT_FOUND');
+        }
+        
+        if (doc._permanent && !options.force) {
+            throw new LacertaDBError(
+                'Cannot delete a permanent document. Use options.force = true to force deletion.',
+                'PERMANENT_DOCUMENT_PROTECTION'
+            );
+        }
+
+        if (doc._permanent && options.force) {
+            console.warn(`Force deleting permanent document: ${docId}`);
+        }
+
+        // Get full document for index cleanup
+        const fullDoc = await this.get(docId);
+        
+        // Remove from indexes
+        for (const [indexName, index] of this.indexManager.indexes) {
+            const value = this.indexManager.getFieldValue(fullDoc, index.fieldPath);
+            if (value !== undefined && value !== null) {
+                await this.indexManager.updateIndex(indexName, docId, value, undefined);
+            }
+        }
 
         await this.indexedDB.delete(this.db, 'documents', docId);
         const attachments = doc._attachments;
@@ -1467,36 +2751,63 @@ class Collection {
         this.database.metadata.setCollection(this.metadata);
 
         await this.trigger('afterDelete', docId);
-        this.queryCache.clear();
+        this.cacheStrategy.clear();
     }
 
     async query(filter = {}, options = {}) {
         const startTime = performance.now();
+        
+        // Try cache first
         const cacheKey = base64.encode(serializer.serialize({ filter, options }));
-        const cached = this.queryCache.get(cacheKey);
-
-        if (cached && Date.now() - cached.timestamp < this.cacheTimeout) {
+        const cached = this.cacheStrategy.get(cacheKey);
+        
+        if (cached) {
             if (this.performanceMonitor) this.performanceMonitor.recordCacheHit();
-            return cached.data;
+            return cached;
         }
         if (this.performanceMonitor) this.performanceMonitor.recordCacheMiss();
-
-        let results = await this.getAll(options);
-        if (Object.keys(filter).length > 0) {
-            results = results.filter(doc => queryEngine.evaluate(doc, filter));
+        
+        // Check if we can use an index
+        let results;
+        let usedIndex = false;
+        
+        for (const [indexName, index] of this.indexManager.indexes) {
+            const fieldValue = filter[index.fieldPath];
+            if (fieldValue !== undefined) {
+                const docIds = await this.indexManager.query(indexName, fieldValue);
+                results = await Promise.all(
+                    docIds.map(id => this.get(id).catch(() => null))
+                );
+                results = results.filter(Boolean);
+                usedIndex = true;
+                break;
+            }
         }
-
+        
+        // Fall back to full scan if no index available
+        if (!usedIndex) {
+            results = await this.getAll(options);
+            if (Object.keys(filter).length > 0) {
+                results = results.filter(doc => queryEngine.evaluate(doc, filter));
+            }
+        }
+        
+        // Apply sorting, pagination, projection
         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);
-
-        this.queryCache.set(cacheKey, { data: results, timestamp: Date.now() });
-        if (this.queryCache.size > 100) {
-            this.queryCache.delete(this.queryCache.keys().next().value);
+        
+        if (this.performanceMonitor) {
+            this.performanceMonitor.recordOperation(
+                usedIndex ? 'indexed-query' : 'full-scan-query', 
+                performance.now() - startTime
+            );
         }
+        
+        // Store in cache
+        this.cacheStrategy.set(cacheKey, results);
+        
         return results;
     }
 
@@ -1519,7 +2830,7 @@ class Collection {
         return results;
     }
 
-    batchUpdate(updates, options) {
+    async batchUpdate(updates, options) {
         return Promise.all(updates.map(update =>
             this.update(update.id, update.data, options)
                 .then(id => ({ success: true, id }))
@@ -1527,19 +2838,37 @@ class Collection {
         ));
     }
 
-    batchDelete(ids) {
-        return Promise.all(ids.map(id =>
-            this.delete(id)
+    async batchDelete(items) {
+        const normalizedItems = items.map(item => {
+            if (typeof item === 'string') {
+                return { id: item, options: {} };
+            }
+            return { id: item.id, options: item.options || {} };
+        });
+
+        return Promise.all(normalizedItems.map(({ id, options }) =>
+            this.delete(id, options)
                 .then(() => ({ success: true, id }))
                 .catch(error => ({ success: false, id, error: error.message }))
         ));
     }
 
-    async clear() {
-        await this.indexedDB.clear(this.db, 'documents');
-        this.metadata = new CollectionMetadata(this.name);
-        this.database.metadata.setCollection(this.metadata);
-        this.queryCache.clear();
+    async clear(options = {}) {
+        if (options.force) {
+            await this.indexedDB.clear(this.db, 'documents');
+            this.metadata = new CollectionMetadata(this.name);
+            this.database.metadata.setCollection(this.metadata);
+            this.cacheStrategy.clear();
+            
+            // Clear all indexes
+            for (const indexName of this.indexManager.indexes.keys()) {
+                await this.indexManager.rebuildIndex(indexName);
+            }
+        } else {
+            const allDocs = await this.getAll();
+            const nonPermanentDocs = allDocs.filter(doc => !doc._permanent);
+            await this.batchDelete(nonPermanentDocs.map(doc => doc._id));
+        }
     }
 
     async checkSpaceLimit() {
@@ -1575,7 +2904,9 @@ class Collection {
         }
     }
 
-    clearCache() { this.queryCache.clear(); }
+    clearCache() {
+        this.cacheStrategy.clear();
+    }
 
     destroy() {
         clearInterval(this.cleanupInterval);
@@ -1597,15 +2928,115 @@ class Database {
         this.settings = null;
         this.quickStore = null;
         this.performanceMonitor = performanceMonitor;
+        
+        // Database-level encryption
+        this.encryption = null;
+        this.isEncrypted = false;
     }
 
-    async init() {
+    async init(options = {}) {
         this.metadata = DatabaseMetadata.load(this.name);
         this.settings = Settings.load(this.name);
         this.quickStore = new QuickStore(this.name);
+        
+        // Initialize encryption if PIN provided
+        if (options.pin) {
+            await this.initializeEncryption(options.pin, options.salt);
+        }
+        
         return this;
     }
 
+    async initializeEncryption(pin, salt = null) {
+        this.encryption = new SecureDatabaseEncryption();
+        
+        // Check if we have existing salt in metadata
+        const encMetaKey = `lacertadb_${this.name}_encryption`;
+        let existingSalt = null;
+        
+        if (!salt) {
+            const stored = localStorage.getItem(encMetaKey);
+            if (stored) {
+                const metadata = JSON.parse(stored);
+                existingSalt = metadata.salt;
+            }
+        }
+        
+        const saltBase64 = await this.encryption.initialize(
+            pin, 
+            existingSalt ? base64.decode(existingSalt) : salt
+        );
+        
+        // Store salt for future sessions
+        if (!existingSalt) {
+            const metadata = this.encryption.exportMetadata();
+            localStorage.setItem(encMetaKey, JSON.stringify(metadata));
+        }
+        
+        this.isEncrypted = true;
+        return saltBase64;
+    }
+
+    async changePin(oldPin, newPin) {
+        if (!this.isEncrypted) {
+            throw new Error('Database is not encrypted');
+        }
+        
+        const newSalt = await this.encryption.changePin(oldPin, newPin);
+        
+        // Update stored metadata
+        const encMetaKey = `lacertadb_${this.name}_encryption`;
+        const metadata = this.encryption.exportMetadata();
+        localStorage.setItem(encMetaKey, JSON.stringify(metadata));
+        
+        return newSalt;
+    }
+
+    async storePrivateKey(keyName, privateKey, additionalAuth = '') {
+        if (!this.isEncrypted) {
+            throw new Error('Database must be encrypted to store private keys');
+        }
+        
+        const encryptedKey = await this.encryption.encryptPrivateKey(
+            privateKey, 
+            additionalAuth
+        );
+        
+        // Store in a special collection
+        let keyStore = await this.getCollection('__private_keys__').catch(() => null);
+        if (!keyStore) {
+            keyStore = await this.createCollection('__private_keys__', {
+                encrypted: false // Already encrypted at database level
+            });
+        }
+        
+        await keyStore.add({
+            name: keyName,
+            key: encryptedKey,
+            createdAt: Date.now()
+        }, {
+            id: keyName,
+            permanent: true
+        });
+        
+        return true;
+    }
+
+    async getPrivateKey(keyName, additionalAuth = '') {
+        if (!this.isEncrypted) {
+            throw new Error('Database must be encrypted to retrieve private keys');
+        }
+        
+        const keyStore = await this.getCollection('__private_keys__');
+        const doc = await keyStore.get(keyName);
+        
+        if (!doc) {
+            throw new Error(`Private key '${keyName}' not found`);
+        }
+        
+        return await this.encryption.decryptPrivateKey(doc.key, additionalAuth);
+    }
+
     async createCollection(name, options) {
         if (this.collections.has(name)) {
             throw new LacertaDBError(`Collection '${name}' already exists.`, 'COLLECTION_EXISTS');
@@ -1637,7 +3068,7 @@ class Database {
     async dropCollection(name) {
         if (this.collections.has(name)) {
             const collection = this.collections.get(name);
-            await collection.clear();
+            await collection.clear({ force: true });
             collection.destroy();
             this.collections.delete(name);
         }
@@ -1672,11 +3103,13 @@ class Database {
         };
     }
 
-    updateSettings(newSettings) { this.settings.updateSettings(newSettings); }
+    updateSettings(newSettings) {
+        this.settings.updateSettings(newSettings);
+    }
 
     async export(format = 'json', password = null) {
         const data = {
-            version: '4.0.3',
+            version: '5.0.0',
             database: this.name,
             timestamp: Date.now(),
             collections: {}
@@ -1739,6 +3172,9 @@ class Database {
     destroy() {
         this.collections.forEach(collection => collection.destroy());
         this.collections.clear();
+        if (this.encryption) {
+            this.encryption.destroy();
+        }
     }
 }
 
@@ -1752,15 +3188,19 @@ export class LacertaDB {
         this.performanceMonitor = new PerformanceMonitor();
     }
 
-    async getDatabase(name) {
+    async getDatabase(name, options = {}) {
         if (!this.databases.has(name)) {
             const db = new Database(name, this.performanceMonitor);
-            await db.init();
+            await db.init(options);
             this.databases.set(name, db);
         }
         return this.databases.get(name);
     }
 
+    async getSecureDatabase(name, pin, salt = null) {
+        return this.getDatabase(name, { pin, salt });
+    }
+
     async dropDatabase(name) {
         if (this.databases.has(name)) {
             const db = this.databases.get(name);
@@ -1769,7 +3209,7 @@ export class LacertaDB {
             this.databases.delete(name);
         }
 
-        ['metadata', 'settings', 'version'].forEach(suffix => {
+        ['metadata', 'settings', 'version', 'encryption'].forEach(suffix => {
             localStorage.removeItem(`lacertadb_${name}_${suffix}`);
         });
         const quickStore = new QuickStore(name);
@@ -1780,10 +3220,11 @@ export class LacertaDB {
         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);
+                const parts = key.split('_');
+                if (parts.length >= 2) {
+                    dbNames.add(parts[1]);
+                }
             }
         }
         return [...dbNames];
@@ -1791,7 +3232,7 @@ export class LacertaDB {
 
     async createBackup(password = null) {
         const backup = {
-            version: '4.0.3',
+            version: '5.0.0',
             timestamp: Date.now(),
             databases: {}
         };
@@ -1841,7 +3282,10 @@ export class LacertaDB {
     }
 }
 
-// Export all major components for advanced usage
+// ========================
+// Export all components
+// ========================
+
 export {
     Database,
     Collection,
@@ -1849,5 +3293,17 @@ export {
     MigrationManager,
     PerformanceMonitor,
     LacertaDBError,
-    OPFSUtility
-};
+    OPFSUtility,
+    IndexManager,
+    CacheStrategy,
+    LRUCache,
+    LFUCache,
+    TTLCache,
+    BTreeIndex,
+    TextIndex,
+    GeoIndex,
+    SecureDatabaseEncryption
+};
+
+// Default export
+export default LacertaDB;