@pixagram/lacerta-db 0.10.2 → 0.11.0

package/index.js

@@ -1,7 +1,7 @@
 /**
- * LacertaDB V0.10.2 - Production Library
+ * LacertaDB V0.11.0 - Production Library
  * @module LacertaDB
- * @version 0.9.2
+ * @version 0.11.0
  * @license MIT
  * @author Pixagram SA
  */
@@ -26,19 +26,18 @@ if (typeof window !== 'undefined' && !window.requestIdleCallback) {
 import TurboSerial from "@pixagram/turboserial";
 import TurboBase64 from "@pixagram/turbobase64";
 
-const serializer = new TurboSerial({
-    compression: true,        // Enable built-in compression
-    preservePropertyDescriptors: true, // Preserve property descriptors
-    deduplication: true,      // Deduplicate repeated values
-    simdOptimization: true,   // Use SIMD instructions when available
-    detectCircular: true,      // Handle circular references
-    shareArrayBuffers: true,      // Share ArrayBuffer references
-    allowFunction: false,         // Allow function storage/retrieval (security gate)
-    serializeFunctions: false,    // Capture and reconstruct function source
-    memoryPoolSize: 65536*16         // Initial memory pool size (1MB)
-});
-
-const base64 = new TurboBase64();
+// Default TurboSerial configuration (overridable via LacertaDB constructor)
+const TURBO_SERIAL_DEFAULTS = {
+    compression: false,
+    preservePropertyDescriptors: true,
+    deduplication: false,
+    simdOptimization: true,
+    detectCircular: true,
+    shareArrayBuffers: true,
+    allowFunction: false,
+    serializeFunctions: false,
+    memoryPoolSize: 65536 * 16
+};
 
 // ========================
 // Quick Store (Optimized)
@@ -49,8 +48,10 @@ const base64 = new TurboBase64();
  * Keeps index in memory to avoid blocking main thread with JSON parsing.
  */
 class QuickStore {
-    constructor(dbName) {
+    constructor(dbName, serializer, base64) {
         this._dbName = dbName;
+        this._serializer = serializer;
+        this._base64 = base64;
         this._keyPrefix = `lacertadb_${dbName}_quickstore_`;
         this._indexKey = `${this._keyPrefix}index`;
         
@@ -91,8 +92,8 @@ class QuickStore {
         const indexStr = localStorage.getItem(this._indexKey);
         if (indexStr) {
             try {
-                const decoded = base64.decode(indexStr);
-                const list = serializer.deserialize(decoded);
+                const decoded = this._base64.decode(indexStr);
+                const list = this._serializer.deserialize(decoded);
                 this._indexCache = new Set(list);
             } catch (e) {
                 console.warn('QuickStore index corrupted, resetting.', e);
@@ -110,8 +111,8 @@ class QuickStore {
             if (!this._dirty) return;
             try {
                 const list = Array.from(this._indexCache);
-                const serializedIndex = serializer.serialize(list);
-                const encodedIndex = base64.encode(serializedIndex);
+                const serializedIndex = this._serializer.serialize(list);
+                const encodedIndex = this._base64.encode(serializedIndex);
                 localStorage.setItem(this._indexKey, encodedIndex);
                 this._dirty = false;
             } catch (e) {
@@ -128,7 +129,7 @@ class QuickStore {
         };
 
         // Debounce with idle callback to prevent UI freezing
-        if (window.requestIdleCallback) {
+        if (typeof window !== 'undefined' && window.requestIdleCallback) {
             this._saveIndexTimer = window.requestIdleCallback(save);
         } else {
             this._saveIndexTimer = setTimeout(save, 200);
@@ -139,8 +140,8 @@ class QuickStore {
         if (!this._dirty) return;
         try {
             const list = Array.from(this._indexCache);
-            const serializedIndex = serializer.serialize(list);
-            const encodedIndex = base64.encode(serializedIndex);
+            const serializedIndex = this._serializer.serialize(list);
+            const encodedIndex = this._base64.encode(serializedIndex);
             localStorage.setItem(this._indexKey, encodedIndex);
             this._dirty = false;
         } catch (e) {
@@ -159,8 +160,8 @@ class QuickStore {
         this._ensureIndexLoaded();
         const key = `${this._keyPrefix}data_${docId}`;
         try {
-            const serializedData = serializer.serialize(data);
-            const encodedData = base64.encode(serializedData);
+            const serializedData = this._serializer.serialize(data);
+            const encodedData = this._base64.encode(serializedData);
             localStorage.setItem(key, encodedData);
 
             if (!this._indexCache.has(docId)) {
@@ -182,8 +183,8 @@ class QuickStore {
         const stored = localStorage.getItem(key);
         if (stored) {
             try {
-                const decoded = base64.decode(stored);
-                return serializer.deserialize(decoded);
+                const decoded = this._base64.decode(stored);
+                return this._serializer.deserialize(decoded);
             } catch (e) {
                 console.error('Failed to parse QuickStore data:', e);
             }
@@ -768,12 +769,14 @@ class BrowserEncryptionUtility {
 // ========================
 
 class SecureDatabaseEncryption {
-    constructor(config = {}) {
+    constructor(config = {}, serializer, base64) {
         this._iterations = config.iterations || 600000; // Increased to OWASP recommendation
         this._hashAlgorithm = config.hashAlgorithm || 'SHA-256';
         this._keyLength = config.keyLength || 256;
         this._saltLength = config.saltLength || 32;
         this._initialized = false;
+        this._serializer = serializer;
+        this._base64 = base64;
         
         this._masterKey = null; // The actual key used for data encryption
         this._hmacKey = null;   // Key for HMAC operations
@@ -793,11 +796,11 @@ class SecureDatabaseEncryption {
 
         if (existingMetadata) {
             // Load existing
-            this._salt = base64.decode(existingMetadata.salt);
+            this._salt = this._base64.decode(existingMetadata.salt);
             const kek = await this._deriveKEK(pinBytes, this._salt);
             
             // Unwrap Master Key
-            const wrappedBytes = base64.decode(existingMetadata.wrappedKey);
+            const wrappedBytes = this._base64.decode(existingMetadata.wrappedKey);
             const iv = wrappedBytes.slice(0, 12);
             const encryptedMK = wrappedBytes.slice(12);
 
@@ -828,7 +831,7 @@ class SecureDatabaseEncryption {
             wrappedKey.set(iv, 0);
             wrappedKey.set(new Uint8Array(encryptedMK), 12);
             
-            this._wrappedKeyBlob = base64.encode(wrappedKey);
+            this._wrappedKeyBlob = this._base64.encode(wrappedKey);
         }
 
         this._initialized = true;
@@ -882,7 +885,7 @@ class SecureDatabaseEncryption {
 
         // Verify old PIN by attempting to unwrap current master key
         const oldKek = await this._deriveKEK(new TextEncoder().encode(oldPin), this._salt);
-        const currentWrappedBytes = base64.decode(this._wrappedKeyBlob);
+        const currentWrappedBytes = this._base64.decode(this._wrappedKeyBlob);
         const currentIv = currentWrappedBytes.slice(0, 12);
         const currentEncMK = currentWrappedBytes.slice(12);
         try {
@@ -910,7 +913,7 @@ class SecureDatabaseEncryption {
 
         // Update State
         this._salt = newSalt;
-        this._wrappedKeyBlob = base64.encode(wrappedKey);
+        this._wrappedKeyBlob = this._base64.encode(wrappedKey);
         
         return this.exportMetadata();
     }
@@ -926,7 +929,7 @@ class SecureDatabaseEncryption {
         } else if (data instanceof Uint8Array) {
             dataBytes = data;
         } else {
-            dataBytes = serializer.serialize(data);
+            dataBytes = this._serializer.serialize(data);
         }
 
         const iv = crypto.getRandomValues(new Uint8Array(12));
@@ -1007,7 +1010,7 @@ class SecureDatabaseEncryption {
         } else if (privateKey instanceof Uint8Array) {
             keyData = privateKey;
         } else {
-            keyData = serializer.serialize(privateKey);
+            keyData = this._serializer.serialize(privateKey);
         }
 
         const iv = crypto.getRandomValues(new Uint8Array(12));
@@ -1033,7 +1036,7 @@ class SecureDatabaseEncryption {
         result.set(authData, 16);
         result.set(new Uint8Array(encryptedKey), 16 + authData.length);
 
-        return base64.encode(result);
+        return this._base64.encode(result);
     }
 
     async decryptPrivateKey(encryptedKeyString, additionalAuth = '') {
@@ -1041,7 +1044,7 @@ class SecureDatabaseEncryption {
             throw new Error('Database encryption not initialized');
         }
 
-        const encryptedPackage = base64.decode(encryptedKeyString);
+        const encryptedPackage = this._base64.decode(encryptedKeyString);
 
         const iv = encryptedPackage.slice(0, 12);
         const authLengthBytes = encryptedPackage.slice(12, 16);
@@ -1101,7 +1104,7 @@ class SecureDatabaseEncryption {
 
     exportMetadata() {
         return {
-            salt: base64.encode(this._salt),
+            salt: this._base64.encode(this._salt),
             wrappedKey: this._wrappedKeyBlob,
             iterations: this._iterations,
             algorithm: 'AES-GCM-256',
@@ -1220,26 +1223,53 @@ class BTreeNode {
         return this.children[i] ? this.children[i].search(key) : null;
     }
 
-    rangeSearch(min, max, results) {
+    // Optimized range search with subtree pruning (O(log n + k) instead of O(n))
+    // excludeMin/excludeMax: when true, boundary values are excluded from results
+    rangeSearch(min, max, results, excludeMin = false, excludeMax = false) {
+        // Skip keys strictly below the min bound
         let i = 0;
-        while (i < this.n) {
+        if (min !== null) {
+            while (i < this.n && this.keys[i] < min) {
+                i++;
+            }
+            // If min is exclusive, also skip keys equal to min
+            if (excludeMin) {
+                // But first descend into the child at boundary — it may have keys > min
+                // that are relevant. We handle this below in the loop.
+            }
+        }
+
+        // Process keys from i onward
+        for (; i < this.n; i++) {
+            // Early exit: if current key exceeds max (or equals max when exclusive),
+            // descend into left child then stop — no further keys can match
+            if (max !== null) {
+                const pastMax = excludeMax ? this.keys[i] >= max : this.keys[i] > max;
+                if (pastMax) {
+                    if (!this.leaf && this.children[i]) {
+                        this.children[i].rangeSearch(min, max, results, excludeMin, excludeMax);
+                    }
+                    return;
+                }
+            }
+
+            // Descend into left child of current key
             if (!this.leaf && this.children[i]) {
-                this.children[i].rangeSearch(min, max, results);
+                this.children[i].rangeSearch(min, max, results, excludeMin, excludeMax);
             }
 
-            // Treat null as unbounded (wildcard) to avoid broken string vs Infinity comparisons
-            const meetsMin = min === null || this.keys[i] >= min;
-            const meetsMax = max === null || this.keys[i] <= max;
+            // Check current key against bounds
+            const meetsMin = min === null || (excludeMin ? this.keys[i] > min : this.keys[i] >= min);
+            const meetsMax = max === null || (excludeMax ? this.keys[i] < max : this.keys[i] <= max);
 
-            if (meetsMin && meetsMax) {
-                if (this.values[i]) {
-                    this.values[i].forEach(v => results.push(v));
-                }
+            if (meetsMin && meetsMax && this.values[i]) {
+                this.values[i].forEach(v => results.push(v));
             }
-            i++;
         }
+
+        // Descend into rightmost child
         if (!this.leaf && this.children[i]) {
-            this.children[i].rangeSearch(min, max, results);
+            this.children[i].rangeSearch(min, max, results, excludeMin, excludeMax);
         }
     }
 
@@ -1279,6 +1309,18 @@ class BTreeNode {
             i++;
             if (this.children[i] && this.children[i].n === 2 * this.order - 1) {
                 this.splitChild(i, this.children[i]);
+
+                // FIX: After split, the promoted median may equal key.
+                // If so, add value to it directly instead of descending
+                // (which would create a duplicate entry in the child).
+                if (this.keys[i] === key) {
+                    if (!this.values[i]) {
+                        this.values[i] = new Set();
+                    }
+                    this.values[i].add(value);
+                    return;
+                }
+
                 if (this.keys[i] < key) {
                     i++;
                 }
@@ -1306,6 +1348,17 @@ class BTreeNode {
 
         y.n = this.order - 1;
 
+        // Clean stale slots in y after split
+        for (let j = this.order - 1; j < 2 * this.order - 1; j++) {
+            y.keys[j] = undefined;
+            y.values[j] = undefined;
+        }
+        if (!y.leaf) {
+            for (let j = this.order; j < 2 * this.order; j++) {
+                y.children[j] = undefined;
+            }
+        }
+
         for (let j = this.n; j >= i + 1; j--) {
             this.children[j + 1] = this.children[j];
         }
@@ -1319,31 +1372,267 @@ class BTreeNode {
 
         this.keys[i] = y.keys[this.order - 1];
         this.values[i] = y.values[this.order - 1];
+        // Clear the promoted median from y (it's now in the parent)
+        y.keys[this.order - 1] = undefined;
+        y.values[this.order - 1] = undefined;
         this.n++;
     }
 
-    remove(key, value) {
+    // ---- Deletion helpers (proper B-tree delete with rebalancing) ----
+
+    // Get the predecessor: rightmost key in the left subtree of keys[idx]
+    _getPredecessor(idx) {
+        let node = this.children[idx];
+        while (!node.leaf) {
+            node = node.children[node.n];
+        }
+        return { key: node.keys[node.n - 1], value: node.values[node.n - 1] };
+    }
+
+    // Get the successor: leftmost key in the right subtree of keys[idx]
+    _getSuccessor(idx) {
+        let node = this.children[idx + 1];
+        while (!node.leaf) {
+            node = node.children[0];
+        }
+        return { key: node.keys[0], value: node.values[0] };
+    }
+
+    // Merge children[idx+1] into children[idx], pulling keys[idx] down as separator
+    _merge(idx) {
+        const child = this.children[idx];
+        const sibling = this.children[idx + 1];
+        const t = this.order;
+
+        // Pull separator key down into child
+        child.keys[t - 1] = this.keys[idx];
+        child.values[t - 1] = this.values[idx];
+
+        // Copy keys/values from sibling into child
+        for (let j = 0; j < sibling.n; j++) {
+            child.keys[t + j] = sibling.keys[j];
+            child.values[t + j] = sibling.values[j];
+        }
+
+        // Copy children from sibling
+        if (!child.leaf) {
+            for (let j = 0; j <= sibling.n; j++) {
+                child.children[t + j] = sibling.children[j];
+            }
+        }
+
+        child.n += sibling.n + 1;
+
+        // Shift keys/values left in this node to fill the gap
+        for (let j = idx; j < this.n - 1; j++) {
+            this.keys[j] = this.keys[j + 1];
+            this.values[j] = this.values[j + 1];
+        }
+
+        // Shift children left in this node
+        for (let j = idx + 1; j < this.n; j++) {
+            this.children[j] = this.children[j + 1];
+        }
+
+        // Clean stale trailing slots
+        this.keys[this.n - 1] = undefined;
+        this.values[this.n - 1] = undefined;
+        this.children[this.n] = undefined;
+
+        this.n--;
+    }
+
+    // Borrow the last key from children[idx-1] through the parent
+    _borrowFromPrev(idx) {
+        const child = this.children[idx];
+        const sibling = this.children[idx - 1];
+
+        // Shift everything in child right by 1
+        for (let j = child.n - 1; j >= 0; j--) {
+            child.keys[j + 1] = child.keys[j];
+            child.values[j + 1] = child.values[j];
+        }
+        if (!child.leaf) {
+            for (let j = child.n; j >= 0; j--) {
+                child.children[j + 1] = child.children[j];
+            }
+        }
+
+        // Move separator from parent down to child[0]
+        child.keys[0] = this.keys[idx - 1];
+        child.values[0] = this.values[idx - 1];
+
+        // Move last child of sibling to child
+        if (!child.leaf) {
+            child.children[0] = sibling.children[sibling.n];
+            sibling.children[sibling.n] = undefined;
+        }
+
+        // Move last key of sibling up to parent
+        this.keys[idx - 1] = sibling.keys[sibling.n - 1];
+        this.values[idx - 1] = sibling.values[sibling.n - 1];
+
+        // Clean stale slots in sibling
+        sibling.keys[sibling.n - 1] = undefined;
+        sibling.values[sibling.n - 1] = undefined;
+
+        child.n++;
+        sibling.n--;
+    }
+
+    // Borrow the first key from children[idx+1] through the parent
+    _borrowFromNext(idx) {
+        const child = this.children[idx];
+        const sibling = this.children[idx + 1];
+
+        // Move separator from parent down to end of child
+        child.keys[child.n] = this.keys[idx];
+        child.values[child.n] = this.values[idx];
+
+        // Move first child of sibling to child
+        if (!child.leaf) {
+            child.children[child.n + 1] = sibling.children[0];
+        }
+
+        // Move first key of sibling up to parent
+        this.keys[idx] = sibling.keys[0];
+        this.values[idx] = sibling.values[0];
+
+        // Shift sibling's keys/values left
+        for (let j = 0; j < sibling.n - 1; j++) {
+            sibling.keys[j] = sibling.keys[j + 1];
+            sibling.values[j] = sibling.values[j + 1];
+        }
+        if (!sibling.leaf) {
+            for (let j = 0; j < sibling.n; j++) {
+                sibling.children[j] = sibling.children[j + 1];
+            }
+            sibling.children[sibling.n] = undefined;
+        }
+
+        // Clean stale trailing slots in sibling
+        sibling.keys[sibling.n - 1] = undefined;
+        sibling.values[sibling.n - 1] = undefined;
+
+        child.n++;
+        sibling.n--;
+    }
+
+    // Ensure children[idx] has at least `order` keys (minimum degree)
+    // so we can safely descend into it during deletion
+    _fill(idx) {
+        const t = this.order;
+        if (idx > 0 && this.children[idx - 1] && this.children[idx - 1].n >= t) {
+            this._borrowFromPrev(idx);
+        } else if (idx < this.n && this.children[idx + 1] && this.children[idx + 1].n >= t) {
+            this._borrowFromNext(idx);
+        } else {
+            // Merge with a sibling
+            if (idx < this.n) {
+                this._merge(idx);
+            } else {
+                this._merge(idx - 1);
+            }
+        }
+    }
+
+    // Remove a leaf-level key entry (shift keys, values left)
+    _removeFromLeaf(idx) {
+        for (let j = idx; j < this.n - 1; j++) {
+            this.keys[j] = this.keys[j + 1];
+            this.values[j] = this.values[j + 1];
+        }
+        this.keys[this.n - 1] = undefined;
+        this.values[this.n - 1] = undefined;
+        this.n--;
+    }
+
+    // Remove an internal key entry using predecessor/successor replacement
+    _removeFromInternal(idx) {
+        const t = this.order;
+        const key = this.keys[idx];
+
+        if (this.children[idx] && this.children[idx].n >= t) {
+            // Left child has enough keys: replace with predecessor
+            const pred = this._getPredecessor(idx);
+            this.keys[idx] = pred.key;
+            this.values[idx] = pred.value;
+            this.children[idx]._remove(pred.key, null, true);
+        } else if (this.children[idx + 1] && this.children[idx + 1].n >= t) {
+            // Right child has enough keys: replace with successor
+            const succ = this._getSuccessor(idx);
+            this.keys[idx] = succ.key;
+            this.values[idx] = succ.value;
+            this.children[idx + 1]._remove(succ.key, null, true);
+        } else {
+            // Both children at minimum: merge them, then delete from merged child
+            this._merge(idx);
+            this.children[idx]._remove(key, null, true);
+        }
+    }
+
+    // Core removal engine.
+    // removeEntire=false: remove one value from the Set; delete key entry if Set empties
+    // removeEntire=true:  delete the entire key entry regardless of Set contents
+    // Returns true if a key entry was fully removed, false otherwise
+    _remove(key, value, removeEntire) {
         let i = 0;
         while (i < this.n && key > this.keys[i]) {
             i++;
         }
 
         if (i < this.n && key === this.keys[i]) {
-            if (this.values[i]) {
+            // Key found at this node
+            let shouldRemoveEntry = removeEntire;
+
+            if (!shouldRemoveEntry && this.values[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--;
+                shouldRemoveEntry = this.values[i].size === 0;
+            }
+
+            if (shouldRemoveEntry) {
+                if (this.leaf) {
+                    this._removeFromLeaf(i);
+                } else {
+                    this._removeFromInternal(i);
                 }
+                return true;
+            }
+            return false;
+        } else {
+            // Key not found at this level — descend
+            if (this.leaf) return false;
+
+            const isLastChild = (i === this.n);
+
+            // Ensure the child we descend into has enough keys for safe deletion
+            if (this.children[i] && this.children[i].n < this.order) {
+                this._fill(i);
+            }
+
+            // After _fill, if the last child was merged, idx shifted
+            if (isLastChild && i > this.n) {
+                return this.children[i - 1]
+                    ? this.children[i - 1]._remove(key, value, removeEntire)
+                    : false;
+            } else {
+                return this.children[i]
+                    ? this.children[i]._remove(key, value, removeEntire)
+                    : false;
             }
-        } else if (!this.leaf && this.children[i]) {
-            this.children[i].remove(key, value);
         }
     }
 
+    // Public remove: remove a single (key, value) pair
+    remove(key, value) {
+        return this._remove(key, value, false);
+    }
+
+    // Public removeKey: remove an entire key entry (used internally for predecessor/successor cleanup)
+    removeKey(key) {
+        return this._remove(key, null, true);
+    }
+
     verify() {
         const issues = [];
         for (let i = 1; i < this.n; i++) {
@@ -1377,6 +1666,14 @@ class BTreeIndex {
             this.verify();
         }
 
+        // Check for exact duplicate (key, value) to keep _size accurate
+        if (this._root) {
+            const existing = this._root.search(key);
+            if (existing && existing.has(value)) {
+                return; // Already present, no-op
+            }
+        }
+
         if (!this._root) {
             this._root = new BTreeNode(this._order, true);
             this._root.keys[0] = key;
@@ -1388,9 +1685,15 @@ class BTreeIndex {
                 s.children[0] = this._root;
                 s.splitChild(0, this._root);
 
+                // FIX: Check if promoted median equals key
                 let i = 0;
-                if (s.keys[0] < key) i++;
-                s.children[i].insertNonFull(key, value);
+                if (s.keys[0] === key) {
+                    if (!s.values[0]) s.values[0] = new Set();
+                    s.values[0].add(value);
+                } else {
+                    if (s.keys[0] < key) i++;
+                    s.children[i].insertNonFull(key, value);
+                }
 
                 this._root = s;
             } else {
@@ -1411,24 +1714,24 @@ class BTreeIndex {
         return this._root.search(key) !== null;
     }
 
-    range(min, max) {
+    range(min, max, excludeMin = false, excludeMax = false) {
         if (!this._root) return [];
         const results = [];
-        this._root.rangeSearch(min, max, results);
+        this._root.rangeSearch(min, max, results, excludeMin, excludeMax);
         return results;
     }
 
-    rangeFrom(min) {
+    rangeFrom(min, excludeMin = false) {
         if (!this._root) return [];
         const results = [];
-        this._root.rangeSearch(min, null, results);
+        this._root.rangeSearch(min, null, results, excludeMin, false);
         return results;
     }
 
-    rangeTo(max) {
+    rangeTo(max, excludeMax = false) {
         if (!this._root) return [];
         const results = [];
-        this._root.rangeSearch(null, max, results);
+        this._root.rangeSearch(null, max, results, false, excludeMax);
         return results;
     }
 
@@ -1437,6 +1740,7 @@ class BTreeIndex {
         const existing = this._root.search(key);
         if (existing && existing.has(value)) {
             this._root.remove(key, value);
+            // Shrink root if it became empty (all keys merged down)
             if (this._root.n === 0 && !this._root.leaf && this._root.children[0]) {
                 this._root = this._root.children[0];
             }
@@ -1449,15 +1753,22 @@ class BTreeIndex {
         if (!this._root) return { healthy: true, issues: [] };
         const issues = this._root.verify();
         if (issues.length > 0) {
-            console.warn('BTree index issues detected and fixed:', issues);
+            // NOTE: verify detects structural violations but cannot auto-repair.
+            // A full rebuild is required to fix a corrupted index.
+            console.warn('BTree index issues detected (rebuild required):', issues);
         }
         return {
             healthy: issues.length === 0,
             issues,
-            repaired: issues.length
+            requiresRebuild: issues.length > 0
         };
     }
 
+    clear() {
+        this._root = null;
+        this._size = 0;
+    }
+
     get size() {
         return this._size;
     }
@@ -1641,6 +1952,8 @@ class GeoIndex {
 class IndexManager {
     constructor(collection) {
         this._collection = collection;
+        this._serializer = collection.database._serializer;
+        this._base64 = collection.database._base64;
         this._indexes = new Map();
         this._indexData = new Map();
         this._indexQueue = [];
@@ -1711,7 +2024,7 @@ class IndexManager {
                     const d = new Document(docData, {
                         compressed: docData._compressed, 
                         encrypted: docData._encrypted
-                    });
+                    }, this._serializer);
                     // This await is what killed the transaction before
                     await d.unpack(this._collection.database.encryption); 
                     doc = d.objectOutput();
@@ -1778,7 +2091,7 @@ class IndexManager {
     async _hashVal(val) {
         const msg = new TextEncoder().encode(String(val));
         const hash = await crypto.subtle.digest('SHA-256', msg);
-        return base64.encode(new Uint8Array(hash));
+        return this._base64.encode(new Uint8Array(hash));
     }
 
     async updateIndexForDocument(docId, oldDoc, newDoc) {
@@ -1870,25 +2183,20 @@ class IndexManager {
             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.$gt !== undefined) {
-            const docs = indexData.rangeFrom(options.$gt);
-            docs.forEach(doc => {
-                if (doc !== options.$gt) results.add(doc);
-            });
-        } else if (options.$lte !== undefined) {
-            const docs = indexData.rangeTo(options.$lte);
+        // Combined range queries: pick the tightest bounds and correct exclusivity
+        const hasGte = options.$gte !== undefined;
+        const hasGt  = options.$gt  !== undefined;
+        const hasLte = options.$lte !== undefined;
+        const hasLt  = options.$lt  !== undefined;
+
+        if (hasGte || hasGt || hasLte || hasLt) {
+            const min        = hasGte ? options.$gte : (hasGt ? options.$gt : null);
+            const max        = hasLte ? options.$lte : (hasLt ? options.$lt : null);
+            const excludeMin = !hasGte && hasGt;
+            const excludeMax = !hasLte && hasLt;
+
+            const docs = indexData.range(min, max, excludeMin, excludeMax);
             docs.forEach(doc => results.add(doc));
-        } else if (options.$lt !== undefined) {
-            const docs = indexData.rangeTo(options.$lt);
-            docs.forEach(doc => {
-                if (doc !== options.$lt) results.add(doc);
-            });
         }
 
         return Array.from(results);
@@ -1962,8 +2270,8 @@ class IndexManager {
                         ...index
                     }))
                 };
-                const serialized = serializer.serialize(metadata);
-                const encoded = base64.encode(serialized);
+                const serialized = this._serializer.serialize(metadata);
+                const encoded = this._base64.encode(serialized);
                 localStorage.setItem(key, encoded);
                 resolve();
             };
@@ -1982,8 +2290,8 @@ class IndexManager {
         if (!stored) return;
 
         try {
-            const decoded = base64.decode(stored);
-            const metadata = serializer.deserialize(decoded);
+            const decoded = this._base64.decode(stored);
+            const metadata = this._serializer.deserialize(decoded);
 
             for (const indexDef of metadata.indexes) {
                 const { name, ...index } = indexDef;
@@ -2026,7 +2334,13 @@ class IndexManager {
                 report[name] = { status: 'missing', rebuilt: true };
                 await this.rebuildIndex(name);
             } else if (indexData.verify) {
-                report[name] = indexData.verify();
+                const result = indexData.verify();
+                if (result.requiresRebuild) {
+                    // BTree detected structural issues — rebuild the index from source data
+                    await this.rebuildIndex(name);
+                    result.rebuilt = true;
+                }
+                report[name] = result;
             } else {
                 report[name] = { status: 'ok' };
             }
@@ -2310,7 +2624,7 @@ class IndexedDBUtility {
 // ========================
 
 class Document {
-    constructor(data = {}, options = {}) {
+    constructor(data = {}, options = {}, serializer) {
         this._id = data._id || this._generateId();
         this._created = data._created || Date.now();
         this._modified = data._modified || Date.now();
@@ -2321,6 +2635,7 @@ class Document {
         this._data = null;
         this._packedData = data.packedData || null;
         this._compression = new BrowserCompressionUtility();
+        this._serializer = serializer;
 
         if (data.data) {
             this.data = data.data;
@@ -2341,7 +2656,7 @@ class Document {
 
     async pack(encryptionUtil = null) {
         try {
-            let packed = serializer.serialize(this.data);
+            let packed = this._serializer.serialize(this.data);
             if (this._compressed) {
                 packed = await this._compression.compress(packed);
             }
@@ -2370,7 +2685,7 @@ class Document {
                 throw new Error('Empty unpacked data');
             }
 
-            this.data = serializer.deserialize(unpacked);
+            this.data = this._serializer.deserialize(unpacked);
 
             if (typeof this.data !== 'object' || this.data === null) {
                 throw new Error('Invalid deserialized data');
@@ -2385,7 +2700,7 @@ class Document {
     }
 
     packSync() {
-        let packed = serializer.serialize(this.data);
+        let packed = this._serializer.serialize(this.data);
         if (this._compressed) {
             packed = this._compression.compressSync(packed);
         }
@@ -2401,7 +2716,7 @@ class Document {
         if (this._compressed) {
             unpacked = this._compression.decompressSync(unpacked);
         }
-        this.data = serializer.deserialize(unpacked);
+        this.data = this._serializer.deserialize(unpacked);
         return this.data;
     }
 
@@ -2481,27 +2796,29 @@ class CollectionMetadata {
 }
 
 class DatabaseMetadata {
-    constructor(name, data = {}) {
+    constructor(name, data = {}, serializer, base64) {
         this.name = name;
+        this._serializer = serializer;
+        this._base64 = base64;
         this.collections = data.collections || {};
         this.totalSizeKB = data.totalSizeKB || 0;
         this.totalLength = data.totalLength || 0;
         this.modifiedAt = data.modifiedAt || Date.now();
     }
 
-    static load(dbName) {
+    static load(dbName, serializer, base64) {
         const key = `lacertadb_${dbName}_metadata`;
         const stored = localStorage.getItem(key);
         if (stored) {
             try {
                 const decoded = base64.decode(stored);
                 const data = serializer.deserialize(decoded);
-                return new DatabaseMetadata(dbName, data);
+                return new DatabaseMetadata(dbName, data, serializer, base64);
             } catch (e) {
                 console.error('Failed to load metadata:', e);
             }
         }
-        return new DatabaseMetadata(dbName);
+        return new DatabaseMetadata(dbName, {}, serializer, base64);
     }
 
     save() {
@@ -2513,8 +2830,8 @@ class DatabaseMetadata {
                 totalLength: this.totalLength,
                 modifiedAt: this.modifiedAt
             };
-            const serializedData = serializer.serialize(dataToStore);
-            const encodedData = base64.encode(serializedData);
+            const serializedData = this._serializer.serialize(dataToStore);
+            const encodedData = this._base64.encode(serializedData);
             localStorage.setItem(key, encodedData);
         } catch (e) {
             if (e.name === 'QuotaExceededError') {
@@ -2558,27 +2875,29 @@ class DatabaseMetadata {
 }
 
 class Settings {
-    constructor(dbName, data = {}) {
+    constructor(dbName, data = {}, serializer, base64) {
         this.dbName = dbName;
+        this._serializer = serializer;
+        this._base64 = base64;
         this.sizeLimitKB = data.sizeLimitKB != null ? data.sizeLimitKB : Infinity;
         const defaultBuffer = this.sizeLimitKB === Infinity ? Infinity : this.sizeLimitKB * 0.8;
         this.bufferLimitKB = data.bufferLimitKB != null ? data.bufferLimitKB : defaultBuffer;
         this.freeSpaceEvery = this.sizeLimitKB === Infinity ? 0 : (data.freeSpaceEvery || 10000);
     }
 
-    static load(dbName) {
+    static load(dbName, serializer, base64) {
         const key = `lacertadb_${dbName}_settings`;
         const stored = localStorage.getItem(key);
         if (stored) {
             try {
                 const decoded = base64.decode(stored);
                 const data = serializer.deserialize(decoded);
-                return new Settings(dbName, data);
+                return new Settings(dbName, data, serializer, base64);
             } catch (e) {
                 console.error('Failed to load settings:', e);
             }
         }
-        return new Settings(dbName);
+        return new Settings(dbName, {}, serializer, base64);
     }
 
     save() {
@@ -2589,8 +2908,8 @@ class Settings {
                 bufferLimitKB: this.bufferLimitKB,
                 freeSpaceEvery: this.freeSpaceEvery
             };
-            const serializedData = serializer.serialize(dataToStore);
-            const encodedData = base64.encode(serializedData);
+            const serializedData = this._serializer.serialize(dataToStore);
+            const encodedData = this._base64.encode(serializedData);
             localStorage.setItem(key, encodedData);
         } catch (e) {
             if (e.name === 'QuotaExceededError') {
@@ -3039,6 +3358,8 @@ class Collection {
     constructor(name, database) {
         this.name = name;
         this.database = database;
+        this._serializer = database._serializer;
+        this._base64 = database._base64;
         this._db = null;
         this._metadata = null;
         this._settings = database.settings;
@@ -3131,7 +3452,7 @@ class Collection {
         const doc = new Document({data: documentData, _id: options.id}, {
             compressed: options.compressed !== false,
             permanent: options.permanent || false
-        });
+        }, this._serializer);
 
         const attachments = options.attachments;
         if (attachments && attachments.length > 0) {
@@ -3173,7 +3494,7 @@ class Collection {
         const doc = new Document(stored, {
             encrypted: stored._encrypted,
             compressed: stored._compressed
-        });
+        }, this._serializer);
 
         if (stored.packedData) {
             await doc.unpack(this.database.encryption);
@@ -3196,7 +3517,7 @@ class Collection {
                 const doc = new Document(docData, {
                     encrypted: docData._encrypted,
                     compressed: docData._compressed
-                });
+                }, this._serializer);
                 if (docData.packedData) {
                     await doc.unpack(this.database.encryption);
                 }
@@ -3218,7 +3539,7 @@ class Collection {
             throw new LacertaDBError(`Document with id '${docId}' not found for update.`, 'DOCUMENT_NOT_FOUND');
         }
 
-        const existingDoc = new Document(stored);
+        const existingDoc = new Document(stored, {}, this._serializer);
         if (stored.packedData) await existingDoc.unpack(this.database.encryption);
 
         const oldDocOutput = existingDoc.objectOutput();
@@ -3231,7 +3552,7 @@ class Collection {
         }, {
             compressed: options.compressed !== undefined ? options.compressed : stored._compressed,
             permanent: options.permanent !== undefined ? options.permanent : stored._permanent
-        });
+        }, this._serializer);
         doc._modified = Date.now();
 
         const attachments = options.attachments;
@@ -3306,7 +3627,7 @@ class Collection {
 
         const startTime = performance.now();
 
-        const cacheKey = base64.encode(serializer.serialize({filter, options}));
+        const cacheKey = this._base64.encode(this._serializer.serialize({filter, options}));
         const cached = this._cacheStrategy.get(cacheKey);
 
         if (cached) {
@@ -3376,7 +3697,7 @@ class Collection {
             const doc = new Document({data: documentData}, {
                 compressed: options.compressed !== false,
                 permanent: options.permanent || false
-            });
+            }, this._serializer);
 
             await doc.pack(this.database.encryption);
             operations.push({
@@ -3427,7 +3748,7 @@ class Collection {
                 continue;
             }
 
-            const existingDoc = new Document(stored);
+            const existingDoc = new Document(stored, {}, this._serializer);
             if (stored.packedData) await existingDoc.unpack(this.database.encryption);
 
             oldDocs.push(existingDoc.objectOutput());
@@ -3440,7 +3761,7 @@ class Collection {
             }, {
                 compressed: options.compressed !== undefined ? options.compressed : stored._compressed,
                 permanent: options.permanent !== undefined ? options.permanent : stored._permanent
-            });
+            }, this._serializer);
             doc._modified = Date.now();
             doc._attachments = stored._attachments;
 
@@ -3652,13 +3973,15 @@ class Collection {
 // ========================
 
 class Database {
-    constructor(name, performanceMonitor) {
+    constructor(name, performanceMonitor, serializer, base64) {
         this.name = name;
         this._collections = new Map();
         this._metadata = null;
         this._settings = null;
         this._quickStore = null;
         this._performanceMonitor = performanceMonitor;
+        this._serializer = serializer;
+        this._base64 = base64;
 
         // Database-level encryption
         this._encryption = null;
@@ -3693,9 +4016,9 @@ class Database {
     }
 
     async init(options = {}) {
-        this._metadata = DatabaseMetadata.load(this.name);
-        this._settings = Settings.load(this.name);
-        this._quickStore = new QuickStore(this.name);
+        this._metadata = DatabaseMetadata.load(this.name, this._serializer, this._base64);
+        this._settings = Settings.load(this.name, this._serializer, this._base64);
+        this._quickStore = new QuickStore(this.name, this._serializer, this._base64);
 
         if (options.pin) {
             await this._initializeEncryption(options.pin, options.salt, options.encryptionConfig);
@@ -3710,16 +4033,16 @@ class Database {
         const stored = localStorage.getItem(encMetaKey);
         
         if (stored) {
-            const decoded = base64.decode(stored);
-            existingMetadata = serializer.deserialize(decoded);
+            const decoded = this._base64.decode(stored);
+            existingMetadata = this._serializer.deserialize(decoded);
         }
 
-        this._encryption = new SecureDatabaseEncryption(config);
+        this._encryption = new SecureDatabaseEncryption(config, this._serializer, this._base64);
         const newMeta = await this._encryption.initialize(pin, existingMetadata);
 
         if (!existingMetadata) {
-            const serialized = serializer.serialize(newMeta);
-            const encoded = base64.encode(serialized);
+            const serialized = this._serializer.serialize(newMeta);
+            const encoded = this._base64.encode(serialized);
             localStorage.setItem(encMetaKey, encoded);
         }
     }
@@ -3732,8 +4055,8 @@ class Database {
         const newMeta = await this._encryption.changePin(oldPin, newPin);
 
         const encMetaKey = `lacertadb_${this.name}_encryption`;
-        const serialized = serializer.serialize(newMeta);
-        const encoded = base64.encode(serialized);
+        const serialized = this._serializer.serialize(newMeta);
+        const encoded = this._base64.encode(serialized);
         localStorage.setItem(encMetaKey, encoded);
 
         return true;
@@ -3859,7 +4182,7 @@ class Database {
 
     async export(format = 'json', password = null) {
         const data = {
-            version: '0.9.2',
+            version: '0.10.2',
             database: this.name,
             timestamp: Date.now(),
             collections: {}
@@ -3871,14 +4194,14 @@ class Database {
         }
 
         if (format === 'json') {
-            const serialized = serializer.serialize(data);
-            return base64.encode(serialized);
+            const serialized = this._serializer.serialize(data);
+            return this._base64.encode(serialized);
         }
         if (format === 'encrypted' && password) {
             const encryption = new BrowserEncryptionUtility();
-            const serializedData = serializer.serialize(data);
+            const serializedData = this._serializer.serialize(data);
             const encrypted = await encryption.encrypt(serializedData, password);
-            return base64.encode(encrypted);
+            return this._base64.encode(encrypted);
         }
         throw new LacertaDBError(`Unsupported export format: ${format}`, 'INVALID_FORMAT');
     }
@@ -3886,13 +4209,13 @@ class Database {
     async import(data, format = 'json', password = null) {
         let parsed;
         try {
-            const decoded = base64.decode(data);
+            const decoded = this._base64.decode(data);
             if (format === 'encrypted' && password) {
                 const encryption = new BrowserEncryptionUtility();
                 const decrypted = await encryption.decrypt(decoded, password);
-                parsed = serializer.deserialize(decrypted);
+                parsed = this._serializer.deserialize(decrypted);
             } else {
-                parsed = serializer.deserialize(decoded);
+                parsed = this._serializer.deserialize(decoded);
             }
         } catch (e) {
             throw new LacertaDBError('Failed to parse import data', 'IMPORT_PARSE_FAILED', e);
@@ -3923,7 +4246,7 @@ class Database {
     async clearAll() {
         await Promise.all([...this._collections.keys()].map(name => this.dropCollection(name)));
         this._collections.clear();
-        this._metadata = new DatabaseMetadata(this.name);
+        this._metadata = new DatabaseMetadata(this.name, {}, this._serializer, this._base64);
         this._metadata.save();
         this._quickStore.clear();
     }
@@ -3961,18 +4284,31 @@ class Database {
 // ========================
 
 class LacertaDB {
-    constructor() {
+    constructor(config = {}) {
         this._databases = new Map();
         this._performanceMonitor = new PerformanceMonitor();
+
+        // Instantiate serializer with user-overridable config merged over defaults
+        const serialConfig = { ...TURBO_SERIAL_DEFAULTS, ...(config.turboSerial || {}) };
+        this._serializer = new TurboSerial(serialConfig);
+        this._base64 = new TurboBase64();
     }
 
     get performanceMonitor() {
         return this._performanceMonitor;
     }
 
+    get serializer() {
+        return this._serializer;
+    }
+
+    get base64() {
+        return this._base64;
+    }
+
     async getDatabase(name, options = {}) {
         if (!this._databases.has(name)) {
-            const db = new Database(name, this._performanceMonitor);
+            const db = new Database(name, this._performanceMonitor, this._serializer, this._base64);
             await db.init(options);
             this._databases.set(name, db);
         }
@@ -3996,7 +4332,7 @@ class LacertaDB {
         });
 
         // Clean up quickstore
-        const quickStore = new QuickStore(name);
+        const quickStore = new QuickStore(name, this._serializer, this._base64);
         quickStore.clear();
 
         // Clean up all collections and indexes
@@ -4026,7 +4362,7 @@ class LacertaDB {
 
     async createBackup(password = null) {
         const backup = {
-            version: '0.9.2',
+            version: '0.10.2',
             timestamp: Date.now(),
             databases: {}
         };
@@ -4034,29 +4370,29 @@ class LacertaDB {
         for (const dbName of this.listDatabases()) {
             const db = await this.getDatabase(dbName);
             const exported = await db.export('json');
-            const decoded = base64.decode(exported);
-            backup.databases[dbName] = serializer.deserialize(decoded);
+            const decoded = this._base64.decode(exported);
+            backup.databases[dbName] = this._serializer.deserialize(decoded);
         }
 
-        const serializedBackup = serializer.serialize(backup);
+        const serializedBackup = this._serializer.serialize(backup);
         if (password) {
             const encryption = new BrowserEncryptionUtility();
             const encrypted = await encryption.encrypt(serializedBackup, password);
-            return base64.encode(encrypted);
+            return this._base64.encode(encrypted);
         }
-        return base64.encode(serializedBackup);
+        return this._base64.encode(serializedBackup);
     }
 
     async restoreBackup(backupData, password = null) {
         let backup;
         try {
-            let decodedData = base64.decode(backupData);
+            let decodedData = this._base64.decode(backupData);
             if (password) {
                 const encryption = new BrowserEncryptionUtility();
                 const decrypted = await encryption.decrypt(decodedData, password);
-                backup = serializer.deserialize(decrypted);
+                backup = this._serializer.deserialize(decrypted);
             } else {
-                backup = serializer.deserialize(decodedData);
+                backup = this._serializer.deserialize(decodedData);
             }
         } catch (e) {
             throw new LacertaDBError('Failed to parse backup data', 'BACKUP_PARSE_FAILED', e);
@@ -4065,7 +4401,7 @@ class LacertaDB {
         const results = { databases: 0, collections: 0, documents: 0 };
         for (const [dbName, dbData] of Object.entries(backup.databases)) {
             const db = await this.getDatabase(dbName);
-            const encodedDbData = base64.encode(serializer.serialize(dbData));
+            const encodedDbData = this._base64.encode(this._serializer.serialize(dbData));
             const importResult = await db.import(encodedDbData);
 
             results.databases++;