@pixagram/lacerta-db 0.6.0 → 0.6.2

package/readme.md

@@ -1,1238 +1,1364 @@
-# LacertaDB 0.6.0
+# LacertaDB 0.6.2
 ![](https://github.com/pixagram-blockchain/LacertaDB/blob/main/logo.webp?raw=true)
 
 > 🦎 **LacertaDB** - A powerful, feature-rich browser-based document database with encryption, compression, and advanced querying capabilities.
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Version](https://img.shields.io/badge/version-4.0.3-blue.svg)]()
+[![Version](https://img.shields.io/badge/version-0.6.2-blue.svg)]()
 [![Browser Compatible](https://img.shields.io/badge/browser-compatible-green.svg)]()
+[![npm downloads](https://img.shields.io/npm/dm/lacertadb.svg)](https://www.npmjs.com/package/lacertadb)
+[![Bundle Size](https://img.shields.io/bundlephobia/minzip/lacertadb)](https://bundlephobia.com/package/lacertadb)
 
-## 📚 Table of Contents
-
-- [✨ Features](#-features)
-- [🚀 Quick Start](#-quick-start)
-- [📦 Installation](#-installation)
-- [🎯 Basic Usage](#-basic-usage)
-- [🔧 Core Concepts](#-core-concepts)
-  - [Database](#database)
-  - [Collections](#collections)
-  - [Documents](#documents)
-- [🔍 Querying](#-querying)
-  - [Basic Queries](#basic-queries)
-  - [Advanced Queries](#advanced-queries)
-  - [Aggregation Pipeline](#aggregation-pipeline)
-- [🔐 Security Features](#-security-features)
-  - [Encryption](#encryption)
-  - [Password Protection](#password-protection)
-- [📎 Attachments](#-attachments)
-- [⚡ Performance](#-performance)
-  - [Compression](#compression)
-  - [Performance Monitoring](#performance-monitoring)
-  - [Query Caching](#query-caching)
-- [🔄 Data Migration](#-data-migration)
-- [💾 Backup & Restore](#-backup--restore)
-- [🛠️ Advanced Features](#️-advanced-features)
-  - [Batch Operations](#batch-operations)
-  - [Event System](#event-system)
-  - [Quick Store](#quick-store)
-- [📊 Storage Management](#-storage-management)
-- [🎨 API Reference](#-api-reference)
-- [💡 Examples](#-examples)
-- [🐛 Error Handling](#-error-handling)
-- [📝 Best Practices](#-best-practices)
-- [🤝 Contributing](#-contributing)
-
-## ✨ Features
-
-🎯 **Core Features**
-- 📁 **Document-based storage** using IndexedDB
-- 🔍 **MongoDB-like query syntax** for familiar operations
-- 🔐 **AES-256-GCM encryption** with PBKDF2 key derivation
-- 🗜️ **Built-in compression** using CompressionStream API
-- 📎 **File attachments** via Origin Private File System (OPFS)
-- ⚡ **High performance** with async operations and caching
-
-🚀 **Advanced Capabilities**
-- 📊 **Aggregation pipeline** for complex data processing
-- 🔄 **Schema migration system** for version management
-- 📈 **Performance monitoring** with real-time metrics
-- 🎭 **Event-driven architecture** with hooks
-- 💾 **Import/Export functionality** with encryption support
-- 🔧 **Batch operations** for efficient bulk processing
-
-## 🚀 Quick Start
+[**🎮 PLAYGROUND**](https://codepen.io/Matias-Affolter/pen/ogjrQdB) 
 
-```javascript
-import * AS LACERTA from './lacertadb.js';
+---
 
-// Initialize LacertaDB
-const lacerta = new LACERTA.LacertaDB();
+## 📖 Table of Contents
+
+1. [Introduction](#introduction)
+2. [Browser Compatibility](#browser-compatibility)
+3. [Quick Start](#quick-start)
+4. [Installation](#installation)
+5. [Core Concepts](#core-concepts)
+6. [API Reference](#api-reference)
+   - [LacertaDB Class](#lacertadb-class)
+   - [Database Class](#database-class)
+   - [Collection Class](#collection-class)
+   - [Document Class](#document-class)
+   - [Index Management](#index-management)
+   - [Encryption](#encryption)
+7. [Advanced Features](#advanced-features)
+8. [Real-World Examples](#real-world-examples)
+9. [Performance Optimization](#performance-optimization)
+10. [Migration Guide](#migration-guide)
+11. [Troubleshooting](#troubleshooting)
+12. [Error Handling](#error-handling)
+13. [Comparison](#comparison)
+14. [Contributing](#contributing)
+15. [Changelog](#changelog)
 
-// Get or create a database
-const db = await lacerta.getDatabase('myApp');
+---
 
-// Create a collection
-const users = await db.createCollection('users');
+## Introduction
 
-// Add a document
-const userId = await users.add({
-  name: 'Alice Johnson',
-  email: 'alice@example.com',
-  age: 28,
-  tags: ['developer', 'javascript']
-});
+LacertaDB is a high-performance, browser-based NoSQL database built on IndexedDB. It provides MongoDB-like query capabilities, automatic compression, encryption support, and advanced indexing strategies - all running entirely in the browser with zero backend dependencies.
 
-// Query documents
-const results = await users.query({
-  age: { $gte: 25 },
-  tags: { $in: ['developer'] }
-});
+### ✨ Key Features
 
-console.log('Found users:', results);
-```
+- 🔐 **Database-level encryption** with AES-GCM-256
+- 🗜️ **Automatic compression** using native browser APIs (60-80% size reduction)
+- 🔍 **Multiple index types** (B-Tree, Hash, Text, Geo)
+- ⚡ **Smart caching strategies** (LRU, LFU, TTL)
+- 📊 **Aggregation pipeline** for complex queries
+- 🔄 **Atomic batch operations**
+- 📈 **Built-in performance monitoring**
+- 💾 **OPFS support** for attachments
+- 🌐 **Works offline** - no server required
+- 📦 **Small bundle size** (~45KB gzipped)
 
-## 📦 Installation
+### 🎯 Use Cases
 
-### NPM/Yarn Installation
+- **PWAs & Offline-First Apps** - Full database functionality without connectivity
+- **Client-Side Encryption** - Secure sensitive data before any network transmission
+- **Local Data Processing** - Complex queries and aggregations without server round-trips
+- **Browser Extensions** - Persistent storage with advanced querying
+- **Prototyping** - Rapid development without backend setup
 
-```bash
-npm install @pixagram/lacertadb
-# or
-yarn add @pixagram/lacertadb
-```
+---
 
-### Browser Module
+## Browser Compatibility
 
-```html
-<script type="module">
-  import { LacertaDB } from './lacertadb.js';
-  const lacerta = new LacertaDB();
-</script>
-```
+| Browser | Minimum Version | Notes |
+|---------|----------------|--------|
+| Chrome | 88+ | Full support including compression |
+| Firefox | 90+ | Full support |
+| Safari | 15.4+ | Full support |
+| Edge | 88+ | Full support |
+| Opera | 74+ | Full support |
+| Chrome Mobile | 88+ | Full support |
+| Safari iOS | 15.4+ | Storage limits may apply |
 
-### Dependencies
+### Required Browser APIs
+- IndexedDB API
+- Web Crypto API
+- CompressionStream API (optional, falls back gracefully)
+- Origin Private File System (optional, for attachments)
 
-LacertaDB requires:
-- `@pixagram/turboserial` - High-performance serialization
-- `@pixagram/turbobase64` - Optimized Base64 encoding
+---
 
-## 🎯 Basic Usage
+## Quick Start
 
-### Creating a Database and Collection
+### 🚀 5-Minute Setup
 
 ```javascript
+import { LacertaDB } from 'lacertadb';
+
+// 1. Initialize LacertaDB
 const lacerta = new LacertaDB();
 
-// Create or get a database
-const db = await lacerta.getDatabase('myDatabase');
+// 2. Get a database
+const db = await lacerta.getDatabase('my-app');
 
-// Create a collection with options
-const products = await db.createCollection('products', {
-  compressed: true,  // Enable compression by default
-  encrypted: false   // Encryption disabled by default
-});
-```
+// 3. Create a collection
+const users = await db.createCollection('users');
 
-### Adding Documents
+// 4. Add documents
+await users.add({
+  name: 'John Doe',
+  email: 'john@example.com',
+  age: 30,
+  tags: ['developer', 'javascript']
+});
 
-```javascript
-// Simple document
-await products.add({
-  name: 'Laptop',
-  price: 999.99,
-  inStock: true
+// 5. Query documents
+const developers = await users.query({
+  tags: { $in: ['developer'] },
+  age: { $gte: 25 }
 });
 
-// Document with options
-await products.add(
-  {
-    name: 'Secure Document',
-    data: 'sensitive information'
-  },
-  {
-    id: 'custom-id-123',        // Custom ID
-    encrypted: true,             // Encrypt this document
-    password: 'secretPassword',  // Encryption password
-    compressed: true,            // Compress the document
-    permanent: true              // Mark as permanent (won't be auto-deleted)
-  }
-);
+// 6. Use aggregation
+const stats = await users.aggregate([
+  { $match: { age: { $gte: 18 } } },
+  { $group: {
+    _id: null,
+    avgAge: { $avg: '$age' },
+    total: { $count: {} }
+  }}
+]);
 ```
 
-### Retrieving Documents
+### 🔐 Encrypted Database Setup
 
 ```javascript
-// Get by ID
-const product = await products.get('custom-id-123', {
-  password: 'secretPassword'  // Required for encrypted documents
-});
-
-// Get all documents
-const allProducts = await products.getAll();
+// Create an encrypted database
+const secureDb = await lacerta.getSecureDatabase(
+  'secure-app',
+  'user-pin-123456'  // User's PIN
+);
 
-// Get with attachments
-const withFiles = await products.get('doc-id', {
-  includeAttachments: true
-});
+// All operations are automatically encrypted
+const secrets = await secureDb.createCollection('secrets');
+await secrets.add({ apiKey: 'sk_live_...' });
 ```
 
-## 🔧 Core Concepts
-
-### Database
-
-The database is the top-level container for your collections.
-
-```javascript
-// Get existing or create new database
-const db = await lacerta.getDatabase('appDB');
+---
 
-// List all collections
-const collections = db.listCollections();
+## Installation
 
-// Get database statistics
-const stats = db.getStats();
-console.log(`Total size: ${stats.totalSizeKB} KB`);
-console.log(`Total documents: ${stats.totalDocuments}`);
+### NPM
+```bash
+npm install lacertadb
+```
 
-// Configure database settings
-db.updateSettings({
-  sizeLimitKB: 50000,      // 50MB limit
-  bufferLimitKB: 40000,    // Start cleanup at 40MB
-  freeSpaceEvery: 60000    // Run cleanup every minute
-});
+### Yarn
+```bash
+yarn add lacertadb
 ```
 
-### Collections
+### CDN
+```html
+<script type="module">
+  import { LacertaDB } from 'https://cdn.jsdelivr.net/npm/lacertadb@latest/dist/index.min.js';
+</script>
+```
 
-Collections are containers for documents of similar type.
+### Import Options
 
 ```javascript
-// Create collection
-const posts = await db.createCollection('posts');
+// ES6 Modules
+import { LacertaDB } from 'lacertadb';
+
+// Import specific components
+import { 
+  LacertaDB, 
+  SecureDatabaseEncryption,
+  PerformanceMonitor,
+  MigrationManager 
+} from 'lacertadb';
+
+// CommonJS (Node.js)
+const { LacertaDB } = require('lacertadb');
+```
 
-// Get existing collection
-const existingPosts = await db.getCollection('posts');
+---
 
-// Collection operations
-await posts.clear();                    // Remove all documents
-await db.dropCollection('posts');       // Delete collection entirely
+## Core Concepts
+
+### Database Structure
 
-// Collection events
-posts.on('afterAdd', (doc) => {
-  console.log('Document added:', doc._id);
-});
+```
+LacertaDB Instance
+├── Database 1
+│   ├── Collection A
+│   │   ├── Document 1
+│   │   ├── Document 2
+│   │   └── Indexes
+│   └── Collection B
+└── Database 2
+    └── __private_keys__ (special collection for encrypted keys)
 ```
 
-### Documents
+### Document Structure
 
-Documents are JavaScript objects with automatic metadata.
+Every document automatically includes:
 
 ```javascript
-// Document structure
-const doc = {
-  // User data
-  title: 'My Post',
-  content: 'Lorem ipsum...',
-  
-  // Automatic metadata (added by LacertaDB)
-  _id: 'doc_1234567890_abc',  // Auto-generated unique ID
-  _created: 1704067200000,     // Creation timestamp
-  _modified: 1704067200000,    // Last modification timestamp
-  _permanent: false,            // Deletion protection flag
-};
+{
+  _id: "doc_1234567890_abc",        // Auto-generated unique ID
+  _created: 1234567890,              // Creation timestamp
+  _modified: 1234567890,             // Last modified timestamp
+  _permanent: false,                 // Protection from auto-cleanup
+  ...yourData                       // Your document fields
+}
 ```
 
-## 🔍 Querying
+---
+
+## API Reference
+
+### 📦 LacertaDB Class
+
+The main entry point for database operations.
 
-### Basic Queries
+| Method | Parameters | Returns | Description |
+|--------|------------|---------|-------------|
+| `getDatabase()` | `name: string`<br/>`options?: object` | `Promise<Database>` | Get or create a database |
+| `getSecureDatabase()` | `name: string`<br/>`pin: string`<br/>`salt?: string`<br/>`config?: object` | `Promise<Database>` | Get encrypted database |
+| `dropDatabase()` | `name: string` | `Promise<void>` | Delete a database |
+| `listDatabases()` | - | `string[]` | List all databases |
+| `createBackup()` | `password?: string` | `Promise<string>` | Create full backup |
+| `restoreBackup()` | `data: string`<br/>`password?: string` | `Promise<object>` | Restore from backup |
+| `destroy()` | - | `void` | Clean up all connections |
+
+<details>
+<summary><strong>Examples</strong></summary>
 
 ```javascript
-// Find all documents matching criteria
-const results = await users.query({
-  age: 30,                           // Exact match
-  'address.city': 'New York'         // Nested field
-});
+// Initialize LacertaDB
+const lacerta = new LacertaDB();
+
+// Get a standard database
+const db = await lacerta.getDatabase('myapp');
 
-// With options
-const paginatedResults = await users.query(
-  { status: 'active' },
+// Get an encrypted database with custom security
+const secureDb = await lacerta.getSecureDatabase(
+  'sensitive-data',
+  'my-secure-pin-123456',
+  null,  // Auto-generate salt
   {
-    sort: { createdAt: -1 },         // Sort descending
-    skip: 10,                         // Skip first 10
-    limit: 20,                        // Limit to 20 results
-    projection: {                    // Select fields
-      name: 1,
-      email: 1,
-      _id: 0
-    }
+    iterations: 200000,    // Higher = more secure but slower
+    keyLength: 256
   }
 );
-```
-
-### Advanced Queries
 
-LacertaDB supports MongoDB-style query operators:
+// Create a full backup
+const backup = await lacerta.createBackup('backup-password');
+// Save to file or cloud
+await saveToCloud(backup);
 
-#### Comparison Operators
+// Restore from backup
+const backupData = await loadFromCloud();
+const result = await lacerta.restoreBackup(backupData, 'backup-password');
+console.log(`Restored: ${result.databases} databases, ${result.documents} documents`);
 
-```javascript
-// $eq, $ne, $gt, $gte, $lt, $lte
-await products.query({
-  price: { $gte: 100, $lte: 500 }
-});
+// List all databases
+const databases = lacerta.listDatabases();
+console.log('Available databases:', databases);
 
-// $in, $nin
-await users.query({
-  role: { $in: ['admin', 'moderator'] }
+// Clean up when done (important for SPAs)
+window.addEventListener('beforeunload', () => {
+  lacerta.destroy();
 });
 ```
 
-#### Logical Operators
+</details>
 
-```javascript
-// $and
-await products.query({
-  $and: [
-    { price: { $lt: 1000 } },
-    { category: 'electronics' }
-  ]
-});
+---
 
-// $or
-await users.query({
-  $or: [
-    { age: { $gte: 65 } },
-    { status: 'premium' }
-  ]
-});
+### 🗄️ Database Class
 
-// $not
-await products.query({
-  discontinued: { $not: { $eq: true } }
-});
-```
+Manages collections and database-level operations.
 
-#### Array Operators
+| Method | Parameters | Returns | Description |
+|--------|------------|---------|-------------|
+| `createCollection()` | `name: string`<br/>`options?: object` | `Promise<Collection>` | Create a new collection |
+| `getCollection()` | `name: string` | `Promise<Collection>` | Get existing collection |
+| `dropCollection()` | `name: string` | `Promise<void>` | Delete a collection |
+| `listCollections()` | - | `string[]` | List all collections |
+| `getStats()` | - | `object` | Get database statistics |
+| `updateSettings()` | `settings: object` | `void` | Update database settings |
+| `export()` | `format: 'json'│'encrypted'`<br/>`password?: string` | `Promise<string>` | Export database |
+| `import()` | `data: string`<br/>`format: string`<br/>`password?: string` | `Promise<object>` | Import data |
+| `storePrivateKey()` | `name: string`<br/>`key: string`<br/>`auth?: string` | `Promise<boolean>` | Store encrypted key |
+| `getPrivateKey()` | `name: string`<br/>`auth?: string` | `Promise<string>` | Retrieve encrypted key |
+| `clearAll()` | - | `Promise<void>` | Clear all collections |
+
+#### Database Settings
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `sizeLimitKB` | `number` | `Infinity` | Maximum database size |
+| `bufferLimitKB` | `number` | `80% of limit` | Start cleanup threshold |
+| `freeSpaceEvery` | `number` | `10000` | Cleanup interval (ms) |
+
+<details>
+<summary><strong>Examples</strong></summary>
 
 ```javascript
-// $all - Array contains all values
-await posts.query({
-  tags: { $all: ['javascript', 'database'] }
+// Create collections
+const users = await db.createCollection('users');
+const posts = await db.createCollection('posts', {
+  compressed: true
 });
 
-// $elemMatch - Element matching
-await orders.query({
-  items: {
-    $elemMatch: {
-      product: 'laptop',
-      quantity: { $gte: 2 }
-    }
-  }
+// Configure database limits
+db.updateSettings({
+  sizeLimitKB: 100000,     // 100MB limit
+  bufferLimitKB: 80000,    // Start cleanup at 80MB
+  freeSpaceEvery: 30000    // Check every 30 seconds
 });
 
-// $size - Array length
-await users.query({
-  hobbies: { $size: 3 }
+// Get database statistics
+const stats = db.getStats();
+console.log(`Database: ${stats.name}`);
+console.log(`Size: ${(stats.totalSizeKB / 1024).toFixed(2)}MB`);
+console.log(`Documents: ${stats.totalDocuments}`);
+stats.collections.forEach(coll => {
+  console.log(`  ${coll.name}: ${coll.documents} docs, ${coll.sizeKB}KB`);
 });
-```
 
-#### Text Search
+// Export/Import database
+const exportData = await db.export('encrypted', 'export-password');
+await saveToFile(exportData, 'backup.lacerta');
 
-```javascript
-// $regex - Regular expression
-await users.query({
-  email: { $regex: '@company\\.com$' }
-});
+// Later...
+const importData = await loadFromFile('backup.lacerta');
+const result = await db.import(importData, 'encrypted', 'export-password');
 
-// $text - Case-insensitive text search
-await posts.query({
-  content: { $text: 'javascript' }
-});
+// Store private keys (requires encrypted database)
+await secureDb.storePrivateKey(
+  'stripe-api',
+  'sk_live_abcd1234',
+  'myapp.com'  // Additional authentication
+);
+
+// Retrieve private key
+const apiKey = await secureDb.getPrivateKey(
+  'stripe-api',
+  'myapp.com'
+);
 ```
 
-### Aggregation Pipeline
+</details>
 
-Powerful data processing with aggregation stages:
+---
 
-```javascript
-// Sales analysis pipeline
-const salesReport = await orders.aggregate([
-  // Stage 1: Filter orders
-  { $match: { status: 'completed' } },
-  
-  // Stage 2: Group by customer
-  {
-    $group: {
-      _id: '$customerId',
-      totalSpent: { $sum: '$amount' },
-      orderCount: { $count: {} },
-      avgOrderValue: { $avg: '$amount' }
-    }
-  },
-  
-  // Stage 3: Sort by total spent
-  { $sort: { totalSpent: -1 } },
-  
-  // Stage 4: Limit to top 10
-  { $limit: 10 },
-  
-  // Stage 5: Project final shape
-  {
-    $project: {
-      customer: '$_id',
-      metrics: {
-        total: '$totalSpent',
-        orders: '$orderCount',
-        average: '$avgOrderValue'
-      }
-    }
-  }
-]);
-```
+### 📁 Collection Class
 
-#### Lookup (Join) Operations
+Manages documents within a collection.
 
-```javascript
-// Join with another collection
-const ordersWithProducts = await orders.aggregate([
-  {
-    $lookup: {
-      from: 'products',           // Foreign collection
-      localField: 'productId',    // Field in orders
-      foreignField: '_id',         // Field in products
-      as: 'productDetails'         // Output array field
-    }
-  }
-]);
-```
+#### Core Methods
 
-## 🔐 Security Features
+| Method | Parameters | Returns | Description |
+|--------|------------|---------|-------------|
+| `add()` | `data: object`<br/>`options?: object` | `Promise<string>` | Add a document |
+| `get()` | `id: string`<br/>`options?: object` | `Promise<object>` | Get a document |
+| `update()` | `id: string`<br/>`updates: object`<br/>`options?: object` | `Promise<string>` | Update a document |
+| `delete()` | `id: string`<br/>`options?: object` | `Promise<void>` | Delete a document |
+| `getAll()` | `options?: object` | `Promise<object[]>` | Get all documents |
+| `clear()` | `options?: object` | `Promise<void>` | Clear collection |
+| `count()` | `filter?: object` | `Promise<number>` | Count documents |
 
-### Encryption
+#### Query Methods
 
-Documents can be individually encrypted with AES-256-GCM:
+| Method | Parameters | Returns | Description |
+|--------|------------|---------|-------------|
+| `query()` | `filter: object`<br/>`options?: object` | `Promise<object[]>` | Query documents |
+| `aggregate()` | `pipeline: object[]` | `Promise<object[]>` | Run aggregation pipeline |
+| `findOne()` | `filter: object` | `Promise<object│null>` | Find first matching document |
 
-```javascript
-// Add encrypted document
-await users.add(
-  {
-    ssn: '123-45-6789',
-    bankAccount: 'SECRET123',
-    salary: 75000
-  },
-  {
-    encrypted: true,
-    password: 'strong-password-here',
-    permanent: true  // Protect from auto-deletion
-  }
-);
+#### Batch Operations
 
-// Retrieve encrypted document
-const userData = await users.get('user-id', {
-  password: 'strong-password-here'  // Required for decryption
-});
+| Method | Parameters | Returns | Description |
+|--------|------------|---------|-------------|
+| `batchAdd()` | `documents: object[]`<br/>`options?: object` | `Promise<object[]>` | Add multiple documents |
+| `batchUpdate()` | `updates: object[]`<br/>`options?: object` | `Promise<object[]>` | Update multiple documents |
+| `batchDelete()` | `items: string[]│object[]` | `Promise<object[]>` | Delete multiple documents |
 
-// Update encrypted document
-await users.update('user-id', 
-  { salary: 80000 },
-  { 
-    encrypted: true,
-    password: 'strong-password-here' 
-  }
-);
-```
+#### Event Methods
 
-### Password Protection
+| Method | Parameters | Returns | Description |
+|--------|------------|---------|-------------|
+| `on()` | `event: string`<br/>`callback: function` | `void` | Add event listener |
+| `off()` | `event: string`<br/>`callback: function` | `void` | Remove event listener |
 
-Secure your exports and backups:
+#### Cache Methods
 
-```javascript
-// Export with encryption
-const encryptedExport = await db.export('encrypted', 'export-password');
+| Method | Parameters | Returns | Description |
+|--------|------------|---------|-------------|
+| `configureCacheStrategy()` | `config: object` | `void` | Configure caching |
+| `clearCache()` | - | `void` | Clear query cache |
 
-// Import encrypted data
-await db.import(encryptedExport, 'encrypted', 'export-password');
+#### Options Parameters
 
-// Create encrypted backup
-const backup = await lacerta.createBackup('backup-password');
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `id` | `string` | auto-generated | Custom document ID |
+| `compressed` | `boolean` | `true` | Enable compression |
+| `permanent` | `boolean` | `false` | Prevent auto-deletion |
+| `includeAttachments` | `boolean` | `false` | Include file attachments |
+| `attachments` | `Array` | `[]` | File attachments to store |
+| `force` | `boolean` | `false` | Force delete permanent docs |
+| `limit` | `number` | - | Limit results |
+| `skip` | `number` | - | Skip results |
+| `sort` | `object` | - | Sort criteria |
+| `projection` | `object` | - | Field projection |
 
-// Restore from encrypted backup
-await lacerta.restoreBackup(backup, 'backup-password');
-```
+<details>
+<summary><strong>Examples</strong></summary>
 
-## 📎 Attachments
+```javascript
+const users = await db.getCollection('users');
 
-Store files using the Origin Private File System:
+// Add document with custom ID
+const userId = await users.add({
+  name: 'John Doe',
+  email: 'john@example.com',
+  age: 30,
+  skills: ['JavaScript', 'TypeScript', 'React']
+}, {
+  id: 'user_john_doe',
+  permanent: true  // Protect from auto-cleanup
+});
 
-```javascript
-// Prepare files
-const file1 = new File(['content'], 'document.pdf', { type: 'application/pdf' });
-const file2 = new Blob(['image data'], { type: 'image/png' });
+// Find one document
+const john = await users.findOne({ email: 'john@example.com' });
 
-// Add document with attachments
-const docId = await documents.add(
-  { title: 'Report with Files' },
-  {
-    attachments: [
-      file1,
-      file2,
-      {
-        name: 'custom.txt',
-        type: 'text/plain',
-        data: new TextEncoder().encode('Custom file content')
-      }
-    ]
+// Query with multiple conditions
+const seniorDevs = await users.query(
+  { 
+    age: { $gte: 25, $lte: 45 },
+    skills: { $all: ['JavaScript', 'React'] }
+  },
+  { 
+    sort: { age: -1 },
+    limit: 10,
+    projection: { name: 1, email: 1, skills: 1 }
   }
 );
 
-// Retrieve with attachments
-const docWithFiles = await documents.get(docId, {
-  includeAttachments: true
-});
+// Complex aggregation pipeline
+const skillStats = await users.aggregate([
+  { $match: { age: { $gte: 18 } } },
+  { $project: { skills: 1 } },
+  { $unwind: '$skills' },
+  { $group: {
+      _id: '$skills',
+      count: { $count: {} },
+      users: { $push: '$_id' }
+    }
+  },
+  { $sort: { count: -1 } },
+  { $limit: 5 }
+]);
 
-// Access attachments
-docWithFiles._attachments.forEach(attachment => {
-  console.log(`File: ${attachment.name} (${attachment.size} bytes)`);
-  // attachment.data is Uint8Array
+// Batch operations with error handling
+const newUsers = [
+  { name: 'Alice', email: 'alice@example.com' },
+  { name: 'Bob', email: 'bob@example.com' }
+];
+
+const results = await users.batchAdd(newUsers, {
+  compressed: true,
+  permanent: false
 });
-```
 
-## ⚡ Performance
+results.forEach(result => {
+  if (result.success) {
+    console.log(`Added user: ${result.id}`);
+  } else {
+    console.error(`Failed to add user: ${result.error}`);
+  }
+});
 
-### Compression
+// Event listeners
+users.on('beforeAdd', (data) => {
+  console.log('Adding document:', data);
+});
 
-Reduce storage size with automatic compression:
+users.on('afterDelete', (id) => {
+  console.log('Deleted document:', id);
+});
 
-```javascript
-// Enable compression for all documents in collection
-const compressedColl = await db.createCollection('largeDocs', {
-  compressed: true
+// Add with file attachments
+const profile = await users.add({
+  name: 'User with Avatar'
+}, {
+  attachments: [
+    await OPFSUtility.prepareAttachment(avatarFile, 'avatar.jpg'),
+    await OPFSUtility.prepareAttachment(resumeFile, 'resume.pdf')
+  ]
 });
 
-// Per-document compression
-await collection.add(largeData, {
-  compressed: true  // Uses DeflateStream compression
+// Retrieve with attachments
+const userWithFiles = await users.get(profile, {
+  includeAttachments: true
 });
+// userWithFiles._attachments will contain the file data
 ```
 
-### Performance Monitoring
+</details>
 
-Track database performance metrics:
+---
 
-```javascript
-// Start monitoring
-lacerta.performanceMonitor.startMonitoring();
+### 🔍 Index Management
 
-// Perform operations...
+Create indexes for optimized queries.
 
-// Get performance stats
-const stats = lacerta.performanceMonitor.getStats();
-console.log(`Operations/sec: ${stats.opsPerSec}`);
-console.log(`Avg latency: ${stats.avgLatency}ms`);
-console.log(`Cache hit rate: ${stats.cacheHitRate}%`);
-console.log(`Memory usage: ${stats.memoryUsageMB}MB`);
+| Method | Parameters | Returns | Description |
+|--------|------------|---------|-------------|
+| `createIndex()` | `field: string`<br/>`options: object` | `Promise<string>` | Create an index |
+| `dropIndex()` | `name: string` | `Promise<void>` | Remove an index |
+| `getIndexes()` | - | `Promise<object>` | Get index statistics |
+| `verifyIndexes()` | - | `Promise<object>` | Verify and repair indexes |
+| `reindexCollection()` | - | `Promise<void>` | Rebuild all indexes |
 
-// Get optimization tips
-const tips = lacerta.performanceMonitor.getOptimizationTips();
-tips.forEach(tip => console.log(`💡 ${tip}`));
+#### Index Types and Use Cases
 
-// Stop monitoring
-lacerta.performanceMonitor.stopMonitoring();
-```
+| Type | Use Case | Query Performance | Space Overhead |
+|------|----------|-------------------|----------------|
+| `btree` | Range queries, sorting | O(log n) | Medium |
+| `hash` | Exact match queries | O(1) | Low |
+| `text` | Full-text search | O(n) for terms | High |
+| `geo` | Spatial queries | O(n log n) | Medium |
+
+#### Index Options
 
-### Query Caching
+| Option | Type | Default | Values | Description |
+|--------|------|---------|--------|-------------|
+| `type` | `string` | `'btree'` | `'btree'`, `'hash'`, `'text'`, `'geo'` | Index type |
+| `unique` | `boolean` | `false` | - | Enforce uniqueness |
+| `sparse` | `boolean` | `false` | - | Skip null values |
+| `name` | `string` | field name | - | Custom index name |
+| `collation` | `object` | null | - | Collation rules |
 
-Queries are automatically cached for 60 seconds:
+<details>
+<summary><strong>Examples</strong></summary>
 
 ```javascript
-// First query - hits database
-const results1 = await users.query({ status: 'active' });
+// Create B-Tree index for range queries
+await users.createIndex('age', { 
+  type: 'btree',
+  name: 'age_index'
+});
 
-// Second identical query - served from cache
-const results2 = await users.query({ status: 'active' });
+// Create compound index (nested fields)
+await users.createIndex('address.city', { 
+  type: 'hash',
+  name: 'city_index'
+});
 
-// Clear cache manually if needed
-users.clearCache();
-```
+// Create unique index on email
+await users.createIndex('email', { 
+  unique: true,
+  sparse: true  // Allow multiple nulls
+});
 
-## 🔄 Data Migration
+// Create text index for full-text search
+await posts.createIndex('content', { 
+  type: 'text',
+  name: 'content_search'
+});
 
-Version your schema changes:
+// Use text index
+const searchResults = await posts.query({
+  content: { $text: 'javascript tutorial' }
+});
 
-```javascript
-const migrationManager = new MigrationManager(db);
+// Create geo index for location queries
+await stores.createIndex('location', { 
+  type: 'geo'
+});
 
-// Define migrations
-migrationManager.addMigration({
-  version: '2.0.0',
-  name: 'Add user roles',
-  up: async (doc) => {
-    if (doc.type === 'user' && !doc.role) {
-      return { ...doc, role: 'standard' };
+// Query using geo index - find nearby
+const nearbyStores = await stores.query({
+  location: {
+    $near: {
+      coordinates: { lat: 40.7128, lng: -74.0060 },
+      maxDistance: 5000  // 5km in meters
     }
-    return doc;
-  },
-  down: async (doc) => {
-    if (doc.type === 'user') {
-      const { role, ...rest } = doc;
-      return rest;
+  }
+});
+
+// Query using geo index - find within bounds
+const storesInArea = await stores.query({
+  location: {
+    $within: {
+      minLat: 40.7,
+      maxLat: 40.8,
+      minLng: -74.1,
+      maxLng: -74.0
     }
-    return doc;
   }
 });
 
-// Run migrations
-await migrationManager.runMigrations('2.0.0');
+// Get index statistics
+const indexes = await users.getIndexes();
+Object.entries(indexes).forEach(([name, info]) => {
+  console.log(`Index: ${name}`);
+  console.log(`  Type: ${info.type}`);
+  console.log(`  Size: ${info.size} entries`);
+  console.log(`  Memory: ~${info.memoryUsage} bytes`);
+});
 
-// Rollback if needed
-await migrationManager.rollback('1.0.0');
+// Verify and auto-repair indexes
+const report = await users.verifyIndexes();
+if (!report.healthy) {
+  console.log('Indexes repaired:', report.repaired);
+}
 ```
 
-## 💾 Backup & Restore
+</details>
 
-### Database Export/Import
+---
 
-```javascript
-// Export single database
-const exportData = await db.export('json');
-// Save exportData to file or send to server
+### 🔐 Encryption
 
-// Import data
-const importResult = await db.import(exportData, 'json');
-console.log(`Imported ${importResult.documents} documents`);
+Database-level encryption configuration.
 
-// Export with encryption
-const secureExport = await db.export('encrypted', 'password123');
-```
+| Method | Parameters | Returns | Description |
+|--------|------------|---------|-------------|
+| `initialize()` | `pin: string`<br/>`salt?: Uint8Array` | `Promise<string>` | Initialize encryption |
+| `changePin()` | `oldPin: string`<br/>`newPin: string` | `Promise<string>` | Change encryption PIN |
+| `destroy()` | - | `void` | Clear encryption keys |
+| `exportMetadata()` | - | `object` | Export encryption config |
+| `importMetadata()` | `metadata: object` | `boolean` | Import encryption config |
 
-### Full System Backup
+#### Encryption Configuration
 
-```javascript
-// Backup all databases
-const systemBackup = await lacerta.createBackup();
-// Optional: encrypt the backup
-const encryptedBackup = await lacerta.createBackup('backup-password');
-
-// Restore from backup
-const restoreResult = await lacerta.restoreBackup(systemBackup);
-console.log(`Restored: ${restoreResult.databases} databases`);
-console.log(`Total documents: ${restoreResult.documents}`);
-```
+| Option | Type | Default | Range | Description |
+|--------|------|---------|-------|-------------|
+| `iterations` | `number` | `100000` | 10000-1000000 | PBKDF2 iterations |
+| `hashAlgorithm` | `string` | `'SHA-256'` | SHA-256/SHA-512 | Hash algorithm |
+| `keyLength` | `number` | `256` | 128/192/256 | Key length in bits |
+| `saltLength` | `number` | `32` | 16-64 | Salt length in bytes |
 
-## 🛠️ Advanced Features
+#### Static Methods
 
-### Batch Operations
+| Method | Parameters | Returns | Description |
+|--------|------------|---------|-------------|
+| `generateSecurePIN()` | `length: number` | `string` | Generate random PIN |
 
-Efficient bulk operations with transaction support:
+<details>
+<summary><strong>Examples</strong></summary>
 
 ```javascript
-// Batch insert
-const documents = [
-  { name: 'Doc 1', value: 100 },
-  { name: 'Doc 2', value: 200 },
-  { name: 'Doc 3', value: 300 }
-];
+// Initialize encrypted database with custom config
+const secureDb = await lacerta.getSecureDatabase(
+  'secure-app',
+  'user-pin-123456',
+  null,  // Auto-generate salt
+  {
+    iterations: 200000,     // Higher = more secure but slower
+    keyLength: 256,
+    hashAlgorithm: 'SHA-512'
+  }
+);
 
-const results = await collection.batchAdd(documents, {
-  compressed: true,
-  encrypted: false
-});
+// Change PIN
+const newSalt = await secureDb.changePin(
+  'old-pin-123456',
+  'new-pin-789012'
+);
+console.log('New salt (store securely):', newSalt);
 
-// Check results
-results.forEach(result => {
-  if (result.success) {
-    console.log(`✅ Added: ${result.id}`);
-  } else {
-    console.log(`❌ Failed: ${result.error}`);
-  }
-});
+// Generate secure PIN
+const securePin = SecureDatabaseEncryption.generateSecurePIN(8);
+console.log('Generated PIN:', securePin);
 
-// Batch update
-const updates = [
-  { id: 'doc1', data: { status: 'active' } },
-  { id: 'doc2', data: { status: 'inactive' } }
-];
-await collection.batchUpdate(updates);
+// Export encryption metadata (for backup)
+const encryptionMeta = secureDb.encryption.exportMetadata();
+// Store this securely with your backups
 
-// Batch delete
-const idsToDelete = ['doc3', 'doc4', 'doc5'];
-await collection.batchDelete(idsToDelete);
+// Restore encryption with same config
+const restoredDb = await lacerta.getSecureDatabase(
+  'secure-app',
+  userPin,
+  encryptionMeta.salt  // Use stored salt
+);
 ```
 
-### Event System
+</details>
 
-React to database operations:
+---
 
-```javascript
-// Collection-level events
-collection.on('beforeAdd', async (data) => {
-  console.log('Validating document...');
-  // Perform validation
-});
+## Advanced Features
 
-collection.on('afterAdd', async (doc) => {
-  console.log(`Document ${doc._id} added`);
-  // Send notification, update cache, etc.
-});
+### 🎯 Query Operators
 
-collection.on('beforeUpdate', async ({ docId, updates }) => {
-  console.log(`Updating ${docId}`);
-});
+#### Comparison Operators
 
-collection.on('afterDelete', async (docId) => {
-  console.log(`Document ${docId} deleted`);
-  // Cleanup related data
-});
+| Operator | Description | Example |
+|----------|-------------|---------|
+| `$eq` | Equals | `{ age: { $eq: 25 } }` |
+| `$ne` | Not equals | `{ status: { $ne: 'deleted' } }` |
+| `$gt` | Greater than | `{ price: { $gt: 100 } }` |
+| `$gte` | Greater than or equal | `{ age: { $gte: 18 } }` |
+| `$lt` | Less than | `{ score: { $lt: 50 } }` |
+| `$lte` | Less than or equal | `{ age: { $lte: 65 } }` |
 
-// Remove event listener
-const handler = (doc) => console.log(doc);
-collection.on('afterAdd', handler);
-collection.off('afterAdd', handler);
-```
+#### Array Operators
 
-### Quick Store
+| Operator | Description | Example |
+|----------|-------------|---------|
+| `$in` | Value in array | `{ category: { $in: ['A', 'B'] } }` |
+| `$nin` | Value not in array | `{ status: { $nin: ['banned'] } }` |
+| `$all` | Array contains all | `{ tags: { $all: ['js', 'node'] } }` |
+| `$elemMatch` | Array element match | `{ scores: { $elemMatch: { $gt: 80 } } }` |
+| `$size` | Array size | `{ items: { $size: 3 } }` |
+
+#### Logical Operators
 
-Fast localStorage-based storage for small data:
+| Operator | Description | Example |
+|----------|-------------|---------|
+| `$and` | Logical AND | `{ $and: [{ age: { $gte: 18 } }, { active: true }] }` |
+| `$or` | Logical OR | `{ $or: [{ role: 'admin' }, { role: 'moderator' }] }` |
+| `$not` | Logical NOT | `{ age: { $not: { $lt: 18 } } }` |
+| `$nor` | Logical NOR | `{ $nor: [{ expired: true }, { deleted: true }] }` |
+
+#### Element Operators
+
+| Operator | Description | Example |
+|----------|-------------|---------|
+| `$exists` | Field exists | `{ email: { $exists: true } }` |
+| `$type` | Field type | `{ age: { $type: 'number' } }` |
+
+#### String Operators
+
+| Operator | Description | Example |
+|----------|-------------|---------|
+| `$regex` | Regular expression | `{ name: { $regex: '^John' } }` |
+| `$text` | Text search | `{ bio: { $text: 'developer' } }` |
+
+### 📊 Aggregation Pipeline Stages
+
+| Stage | Description | Example |
+|-------|-------------|---------|
+| `$match` | Filter documents | `{ $match: { age: { $gte: 18 } } }` |
+| `$group` | Group by field | `{ $group: { _id: '$category', count: { $count: {} } } }` |
+| `$sort` | Sort results | `{ $sort: { createdAt: -1 } }` |
+| `$limit` | Limit results | `{ $limit: 10 }` |
+| `$skip` | Skip results | `{ $skip: 20 }` |
+| `$project` | Project fields | `{ $project: { name: 1, email: 1 } }` |
+| `$lookup` | Join collections | `{ $lookup: { from: 'posts', localField: '_id', foreignField: 'userId', as: 'userPosts' } }` |
+
+#### Aggregation Accumulator Operators
+
+| Operator | Description | Example |
+|----------|-------------|---------|
+| `$sum` | Sum values | `{ total: { $sum: '$amount' } }` |
+| `$avg` | Average values | `{ avgAge: { $avg: '$age' } }` |
+| `$min` | Minimum value | `{ minPrice: { $min: '$price' } }` |
+| `$max` | Maximum value | `{ maxScore: { $max: '$score' } }` |
+| `$count` | Count documents | `{ total: { $count: {} } }` |
+
+### 💾 Cache Strategies
+
+| Strategy | Description | Best For | Configuration |
+|----------|-------------|----------|---------------|
+| `lru` | Least Recently Used | General purpose | `maxSize`, `ttl` |
+| `lfu` | Least Frequently Used | Repeated queries | `maxSize`, `ttl` |
+| `ttl` | Time To Live | Time-sensitive data | `ttl` |
+| `none` | No caching | Real-time data | - |
+
+<details>
+<summary><strong>Examples</strong></summary>
 
 ```javascript
-// Access QuickStore
-const quickStore = db.quickStore;
-
-// Store data
-quickStore.add('user-prefs', {
-  theme: 'dark',
-  language: 'en',
-  notifications: true
+// Configure LRU cache with TTL
+users.configureCacheStrategy({
+  type: 'lru',
+  maxSize: 200,        // Max 200 cached queries
+  ttl: 60000,         // Expire after 1 minute
+  enabled: true
 });
 
-// Retrieve data
-const prefs = quickStore.get('user-prefs');
-
-// Update
-quickStore.update('user-prefs', { theme: 'light' });
-
-// Get all stored items
-const allItems = quickStore.getAll();
-
-// Clear QuickStore
-quickStore.clear();
-```
-
-## 📊 Storage Management
-
-### Size Limits and Auto-Cleanup
-
-```javascript
-// Configure storage limits
-db.updateSettings({
-  sizeLimitKB: 100000,      // 100MB total limit
-  bufferLimitKB: 80000,     // Start cleanup at 80MB
-  freeSpaceEvery: 30000     // Check every 30 seconds
+// Configure LFU for frequently accessed data
+products.configureCacheStrategy({
+  type: 'lfu',
+  maxSize: 500,
+  ttl: 300000        // 5 minutes
 });
 
-// Manual cleanup
-await collection.freeSpace();
+// TTL-only for session data
+sessions.configureCacheStrategy({
+  type: 'ttl',
+  ttl: 900000        // 15 minutes
+});
 
-// Mark documents as permanent
-await collection.add(importantData, {
-  permanent: true  // Won't be deleted during cleanup
+// Disable caching for real-time data
+liveData.configureCacheStrategy({
+  type: 'none'
 });
 
-// Check collection size
-const stats = collection.metadata;
-console.log(`Collection size: ${stats.sizeKB} KB`);
-console.log(`Document count: ${stats.length}`);
+// Manual cache control
+users.clearCache();  // Clear all cached queries
 ```
 
-### Storage Information
+</details>
 
-```javascript
-// Database statistics
-const dbStats = db.getStats();
-console.log(dbStats);
-/* Output:
-{
-  name: 'myDatabase',
-  totalSizeKB: 2457.3,
-  totalDocuments: 1250,
-  collections: [
-    {
-      name: 'users',
-      sizeKB: 1024.5,
-      documents: 500,
-      createdAt: '2024-01-01T00:00:00.000Z',
-      modifiedAt: '2024-01-15T10:30:00.000Z'
-    }
-  ]
-}
-*/
+---
 
-// List all databases
-const allDatabases = lacerta.listDatabases();
-console.log('Available databases:', allDatabases);
-```
+## Real-World Examples
 
-## 🎨 API Reference
-
-### LacertaDB Class
-
-| Method | Description | Returns |
-|--------|-------------|---------|
-| `getDatabase(name)` | Get or create a database | `Promise<Database>` |
-| `dropDatabase(name)` | Delete a database | `Promise<void>` |
-| `listDatabases()` | List all database names | `Array<string>` |
-| `createBackup(password?)` | Create full system backup | `Promise<string>` |
-| `restoreBackup(data, password?)` | Restore from backup | `Promise<Object>` |
-
-### Database Class
-
-| Method | Description | Returns |
-|--------|-------------|---------|
-| `createCollection(name, options?)` | Create new collection | `Promise<Collection>` |
-| `getCollection(name)` | Get existing collection | `Promise<Collection>` |
-| `dropCollection(name)` | Delete collection | `Promise<void>` |
-| `listCollections()` | Get collection names | `Array<string>` |
-| `getStats()` | Get database statistics | `Object` |
-| `updateSettings(settings)` | Update configuration | `void` |
-| `export(format, password?)` | Export database | `Promise<string>` |
-| `import(data, format, password?)` | Import data | `Promise<Object>` |
-| `clearAll()` | Delete all collections | `Promise<void>` |
-
-### Collection Class
-
-| Method | Description | Returns |
-|--------|-------------|---------|
-| `add(data, options?)` | Add document | `Promise<string>` |
-| `get(id, options?)` | Get document by ID | `Promise<Object>` |
-| `getAll(options?)` | Get all documents | `Promise<Array>` |
-| `update(id, updates, options?)` | Update document | `Promise<string>` |
-| `delete(id)` | Delete document | `Promise<void>` |
-| `query(filter, options?)` | Query documents | `Promise<Array>` |
-| `aggregate(pipeline)` | Run aggregation | `Promise<Array>` |
-| `batchAdd(documents, options?)` | Add multiple documents | `Promise<Array>` |
-| `batchUpdate(updates, options?)` | Update multiple documents | `Promise<Array>` |
-| `batchDelete(ids)` | Delete multiple documents | `Promise<Array>` |
-| `clear()` | Remove all documents | `Promise<void>` |
-| `on(event, callback)` | Add event listener | `void` |
-| `off(event, callback)` | Remove event listener | `void` |
-| `clearCache()` | Clear query cache | `void` |
-
-## 💡 Examples
-
-### Todo Application
+### 💬 Chat Application
 
 ```javascript
-// Initialize
+// Initialize encrypted database for chat
 const lacerta = new LacertaDB();
-const db = await lacerta.getDatabase('todoApp');
-const todos = await db.createCollection('todos');
-
-// Add todos
-await todos.add({
-  title: 'Learn LacertaDB',
-  completed: false,
-  priority: 'high',
-  tags: ['learning', 'database'],
-  createdAt: Date.now()
-});
-
-// Query incomplete high-priority todos
-const urgentTodos = await todos.query({
-  completed: false,
-  priority: 'high'
+const db = await lacerta.getSecureDatabase('chat-app', userPin);
+
+// Create collections
+const messages = await db.createCollection('messages');
+const conversations = await db.createCollection('conversations');
+
+// Create indexes for performance
+await messages.createIndex('conversationId', { type: 'hash' });
+await messages.createIndex('timestamp', { type: 'btree' });
+await messages.createIndex('content', { type: 'text' });
+
+// Store message with attachment
+const messageId = await messages.add({
+  conversationId: 'conv_123',
+  userId: 'user_456',
+  content: 'Check out this photo!',
+  timestamp: Date.now(),
+  read: false
 }, {
-  sort: { createdAt: -1 }
+  attachments: [imageFile],
+  permanent: false
 });
 
-// Mark as complete
-await todos.update(todoId, {
-  completed: true,
-  completedAt: Date.now()
+// Get recent messages with pagination
+const recentMessages = await messages.query(
+  { conversationId: 'conv_123' },
+  { 
+    sort: { timestamp: -1 },
+    limit: 20,
+    skip: 0
+  }
+);
+
+// Search messages
+const searchResults = await messages.query({
+  content: { $text: 'photo' }
 });
 
-// Get statistics
-const stats = await todos.aggregate([
-  {
-    $group: {
-      _id: '$priority',
-      count: { $count: {} },
-      completed: { 
-        $sum: { $cond: ['$completed', 1, 0] } 
-      }
-    }
-  }
-]);
+// Mark messages as read
+await messages.batchUpdate(
+  unreadMessages.map(msg => ({
+    id: msg._id,
+    data: { read: true }
+  }))
+);
 ```
 
-### E-Commerce Inventory
+### 🛒 E-Commerce Cart
 
 ```javascript
-// Setup
+// Shopping cart with product management
 const db = await lacerta.getDatabase('shop');
+const cart = await db.createCollection('cart');
 const products = await db.createCollection('products');
-const orders = await db.createCollection('orders');
-
-// Product with images
-const productId = await products.add(
-  {
-    name: 'Wireless Mouse',
-    price: 29.99,
-    stock: 150,
-    category: 'electronics'
-  },
-  {
-    attachments: [productImage1, productImage2]
-  }
-);
 
-// Complex inventory query
-const lowStock = await products.query({
-  $and: [
-    { stock: { $lt: 20 } },
-    { category: { $in: ['electronics', 'accessories'] } }
-  ]
-}, {
-  projection: { name: 1, stock: 1, price: 1 }
+// Add product to cart
+await cart.add({
+  productId: 'prod_123',
+  quantity: 2,
+  price: 29.99,
+  addedAt: Date.now()
 });
 
-// Sales report with joins
-const salesReport = await orders.aggregate([
-  { $match: { status: 'completed' } },
-  {
-    $lookup: {
+// Calculate cart total with aggregation
+const cartTotal = await cart.aggregate([
+  { $lookup: {
       from: 'products',
       localField: 'productId',
       foreignField: '_id',
       as: 'product'
     }
   },
-  {
-    $group: {
-      _id: '$product.category',
-      revenue: { $sum: '$total' },
-      orderCount: { $count: {} }
+  { $project: {
+      quantity: 1,
+      price: 1,
+      total: { $multiply: ['$quantity', '$price'] }
     }
   },
-  { $sort: { revenue: -1 } }
+  { $group: {
+      _id: null,
+      subtotal: { $sum: '$total' },
+      items: { $sum: '$quantity' }
+    }
+  }
 ]);
+
+// Clear old cart items
+const oneWeekAgo = Date.now() - (7 * 24 * 60 * 60 * 1000);
+await cart.query(
+  { addedAt: { $lt: oneWeekAgo } }
+).then(oldItems => 
+  cart.batchDelete(oldItems.map(item => item._id))
+);
 ```
 
-### User Session Management
+### 📝 Note-Taking App
 
 ```javascript
-// Encrypted session storage
-const sessions = await db.createCollection('sessions');
-
-// Store session with encryption
-await sessions.add(
-  {
-    userId: 'user123',
-    token: 'secret-session-token',
-    ipAddress: '192.168.1.1',
-    userAgent: navigator.userAgent,
-    expiresAt: Date.now() + (24 * 60 * 60 * 1000)
-  },
-  {
-    encrypted: true,
-    password: process.env.SESSION_KEY,
-    permanent: false
+// Note app with full-text search
+const db = await lacerta.getDatabase('notes');
+const notes = await db.createCollection('notes');
+
+// Create search index
+await notes.createIndex('content', { type: 'text' });
+await notes.createIndex('tags', { type: 'hash' });
+
+// Save note with auto-save
+let noteId;
+const autoSave = async (content) => {
+  if (noteId) {
+    await notes.update(noteId, { 
+      content,
+      lastModified: Date.now()
+    });
+  } else {
+    noteId = await notes.add({
+      title: 'New Note',
+      content,
+      tags: [],
+      createdAt: Date.now()
+    }, { permanent: true });
   }
-);
-
-// Cleanup expired sessions
-const now = Date.now();
-const expired = await sessions.query({
-  expiresAt: { $lt: now }
-});
+};
 
-await sessions.batchDelete(expired.map(s => s._id));
+// Search notes
+const searchNotes = async (query) => {
+  return await notes.query({
+    $or: [
+      { content: { $text: query } },
+      { title: { $regex: query } },
+      { tags: { $in: [query] } }
+    ]
+  });
+};
 ```
 
-## 🐛 Error Handling
+---
+
+## Performance Optimization
 
-LacertaDB provides detailed error information:
+### 📈 Performance Monitoring
 
 ```javascript
-try {
-  await collection.get('non-existent-id');
-} catch (error) {
-  if (error instanceof LacertaDBError) {
-    console.error('Error:', error.message);
-    console.error('Code:', error.code);
-    console.error('Timestamp:', error.timestamp);
-    
-    // Handle specific error codes
-    switch(error.code) {
-      case 'DOCUMENT_NOT_FOUND':
-        // Handle missing document
-        break;
-      case 'ENCRYPTION_FAILED':
-        // Handle encryption error
-        break;
-      case 'QUOTA_EXCEEDED':
-        // Handle storage limit
-        break;
-    }
-  }
-}
-```
+// Enable performance monitoring
+lacerta.performanceMonitor.startMonitoring();
+
+// Get real-time statistics
+const stats = lacerta.performanceMonitor.getStats();
+console.log(`Operations/sec: ${stats.opsPerSec}`);
+console.log(`Avg latency: ${stats.avgLatency}ms`);
+console.log(`Cache hit rate: ${stats.cacheHitRate}%`);
+console.log(`Memory usage: ${stats.memoryUsageMB}MB`);
 
-### Common Error Codes
+// Get optimization recommendations
+const tips = lacerta.performanceMonitor.getOptimizationTips();
+tips.forEach(tip => console.log('💡', tip));
 
-| Code | Description | Solution |
-|------|-------------|----------|
-| `DOCUMENT_NOT_FOUND` | Document ID doesn't exist | Check ID or use query |
-| `COLLECTION_NOT_FOUND` | Collection doesn't exist | Create collection first |
-| `ENCRYPTION_FAILED` | Encryption/decryption error | Check password |
-| `COMPRESSION_FAILED` | Compression error | Check data format |
-| `QUOTA_EXCEEDED` | Storage limit reached | Increase limit or cleanup |
-| `INVALID_OPERATION` | Operation not allowed | Check document flags |
-| `TRANSACTION_FAILED` | Database transaction error | Retry operation |
+// Monitor specific operations
+const startTime = performance.now();
+await users.query({ age: { $gte: 18 } });
+console.log(`Query took: ${performance.now() - startTime}ms`);
 
-## 📝 Best Practices
+// Stop monitoring
+lacerta.performanceMonitor.stopMonitoring();
+```
 
-### 1. Index Strategy
+### ⚡ Best Practices
 
+#### 1. **Indexing Strategy**
 ```javascript
-// Analyze query patterns first
-const queryPatterns = {
-  byEmail: { email: 'user@example.com' },           // Hash index
-  byAgeRange: { age: { $gte: 25, $lte: 35 } },     // B-Tree index
-  byDescription: { $text: 'search terms' },         // Text index
-  byLocation: { $near: { lat: 0, lng: 0 } }        // Geo index
-};
+// Index frequently queried fields
+await users.createIndex('email', { unique: true });
+await users.createIndex('createdAt', { type: 'btree' });
 
-// Create appropriate indexes
-await users.createIndex('email', { type: 'hash', unique: true });
-await users.createIndex('age', { type: 'btree' });
-await users.createIndex('bio', { type: 'text' });
-await users.createIndex('location', { type: 'geo' });
+// Use compound indexes for complex queries
+await orders.createIndex('userId', { type: 'hash' });
+await orders.createIndex('status', { type: 'hash' });
 ```
 
-### 2. Cache Optimization
+#### 2. **Compression Settings**
+```javascript
+// Enable compression for large documents
+await logs.add(largeLogData, { compressed: true });
+
+// Disable for frequently accessed small docs
+await config.add(settings, { compressed: false });
+```
 
+#### 3. **Batch Operations**
 ```javascript
-// Match cache strategy to access patterns
-const cacheStrategies = {
-  // Frequently changing data - LRU with short TTL
-  activeSessions: { type: 'lru', maxSize: 1000, ttl: 60000 },
-  
-  // Hot data - LFU for keeping popular items
-  trendingProducts: { type: 'lfu', maxSize: 500 },
-  
-  // Time-sensitive - TTL only
-  tempTokens: { type: 'ttl', ttl: 300000 },
-  
-  // Sensitive data - No cache
-  privateKeys: { type: 'none', enabled: false }
-};
+// Good: Single batch operation
+await users.batchAdd(thousandUsers);
+
+// Bad: Individual adds in loop
+for (const user of thousandUsers) {
+  await users.add(user);  // Slow!
+}
 ```
 
-### 3. Security Best Practices
+#### 4. **Memory Management**
+```javascript
+// Configure size limits
+db.updateSettings({
+  sizeLimitKB: 50000,      // 50MB limit
+  bufferLimitKB: 40000,    // Start cleanup at 40MB
+  freeSpaceEvery: 10000    // Check every 10 seconds
+});
+
+// Mark important docs as permanent
+await users.add(adminUser, { permanent: true });
+```
 
+#### 5. **Query Optimization**
 ```javascript
-// For private keys and sensitive data
-const secureDb = await lacerta.getSecureDatabase(
-  'vault',
-  SecureDatabaseEncryption.generateSecurePIN(12)  // 12-digit secure PIN
+// Use projection to reduce data transfer
+const names = await users.query(
+  { active: true },
+  { projection: { name: 1, email: 1 } }
 );
 
-// Always use additional authentication
-await secureDb.storePrivateKey('key-name', privateKey, userEmail);
-
-// Regular PIN rotation
-const rotatePin = async () => {
-  const newPin = SecureDatabaseEncryption.generateSecurePIN(12);
-  await secureDb.changePin(currentPin, newPin);
-  // Securely store newPin
-};
+// Use indexes for sorting
+await messages.createIndex('timestamp', { type: 'btree' });
+const recent = await messages.query({}, { sort: { timestamp: -1 } });
 ```
 
-### 4. Performance Optimization
+---
 
-```javascript
-// Enable monitoring during development
-lacerta.performanceMonitor.startMonitoring();
+## Migration Guide
 
-// Test different strategies
-const testPerformance = async () => {
-  // Test without index
-  const start1 = Date.now();
-  await collection.query({ field: 'value' });
-  console.log('Without index:', Date.now() - start1);
-  
-  // Create index
-  await collection.createIndex('field', { type: 'hash' });
-  
-  // Test with index
-  const start2 = Date.now();
-  await collection.query({ field: 'value' });
-  console.log('With index:', Date.now() - start2);
-};
+### Schema Migrations
 
-// Get optimization suggestions
-const tips = lacerta.performanceMonitor.getOptimizationTips();
-```
+```javascript
+const migrationManager = new MigrationManager(db);
 
-### 5. Storage Management
+// Add a migration
+migrationManager.addMigration({
+  version: '2.0.0',
+  name: 'Add user roles',
+  up: async (doc) => {
+    if (doc.type === 'user' && !doc.role) {
+      return { ...doc, role: 'member' };
+    }
+    return null;
+  },
+  down: async (doc) => {
+    if (doc.type === 'user') {
+      const { role, ...rest } = doc;
+      return rest;
+    }
+    return null;
+  }
+});
 
-```javascript
-// Set appropriate limits
-db.updateSettings({
-  sizeLimitKB: 100000,      // 100MB total
-  bufferLimitKB: 80000,     // Start cleanup at 80MB
-  freeSpaceEvery: 300000    // Check every 5 minutes
+// Add another migration
+migrationManager.addMigration({
+  version: '2.1.0',
+  name: 'Add timestamps',
+  up: async (doc) => {
+    if (!doc.updatedAt) {
+      return { ...doc, updatedAt: doc._modified };
+    }
+    return null;
+  }
 });
 
-// Mark critical documents as permanent
-await collection.add(importantData, { permanent: true });
+// Run all migrations up to version
+await migrationManager.runMigrations('2.1.0');
 
-// Regular maintenance
-const maintenance = async () => {
-  const stats = db.getStats();
-  if (stats.totalSizeKB > 90000) {
-    // Cleanup old non-permanent documents
-    await collection.freeSpace();
-  }
-};
+// Rollback if needed
+await migrationManager.rollback('1.0.0');
 ```
 
-## 🔄 Migration from v4.x
+### Upgrading from v0.5.x to v0.6.x
+
+```javascript
+// Export data from old version
+const oldDb = await getOldDatabase();
+const backup = await oldDb.export('json');
+
+// Import to new version
+const newLacerta = new LacertaDB();
+const newDb = await newLacerta.getDatabase('upgraded-db');
+await newDb.import(backup, 'json');
+
+// Update indexes for better performance
+const collections = newDb.listCollections();
+for (const collName of collections) {
+  const coll = await newDb.getCollection(collName);
+  await coll.verifyIndexes();
+}
+```
 
-### Breaking Changes
+---
 
-None! LacertaDB v5.0.0 is fully backward compatible. All v4.x code continues to work without modifications.
+## Troubleshooting
 
-### New Features to Adopt
+### Common Issues and Solutions
 
-```javascript
-// v4.x code (still works)
-const collection = await db.createCollection('data');
-const results = await collection.query({ status: 'active' });
+#### 🔴 **QuotaExceededError**
 
-// v5.0.0 optimized code
-const collection = await db.createCollection('data');
+**Problem:** Browser storage limit reached
 
-// Add index for 50x faster queries
-await collection.createIndex('status', { type: 'hash' });
+**Solutions:**
+```javascript
+// 1. Check current usage
+const stats = db.getStats();
+console.log(`Using ${stats.totalSizeKB}KB`);
 
-// Configure smart caching
-await collection.configureCacheStrategy({
-  type: 'lru',
-  maxSize: 500,
-  ttl: 120000
+// 2. Clear old data
+await logs.clear();
+
+// 3. Enable automatic cleanup
+db.updateSettings({
+  sizeLimitKB: 45000,
+  bufferLimitKB: 40000
 });
 
-// Now queries are much faster
-const results = await collection.query({ status: 'active' });
+// 4. Use compression
+await collection.add(data, { compressed: true });
 ```
 
-### Migration Checklist
+#### 🔴 **Slow Query Performance**
 
-1. **Add Indexes** to frequently queried fields
-2. **Configure Cache Strategies** based on access patterns
-3. **Enable PIN encryption** for databases with sensitive data
-4. **Update force delete** calls for permanent document management
-5. **Monitor performance** to identify optimization opportunities
+**Problem:** Queries taking too long
 
+**Solutions:**
 ```javascript
-// Complete migration example
-const migrate = async () => {
-  // 1. Get existing database
-  const db = await lacerta.getDatabase('myApp');
-  
-  // 2. Add indexes to collections
-  const users = await db.getCollection('users');
-  await users.createIndex('email', { type: 'hash', unique: true });
-  await users.createIndex('createdAt', { type: 'btree' });
-  
-  // 3. Configure caching
-  await users.configureCacheStrategy({
-    type: 'lru',
-    maxSize: 1000,
-    ttl: 300000
-  });
-  
-  // 4. For sensitive data, create new secure database
-  const secureDb = await lacerta.getSecureDatabase('secure', pin);
-  // Migrate sensitive data to secure database
-  
-  console.log('Migration complete!');
-};
+// 1. Add appropriate indexes
+await collection.createIndex('fieldName', { type: 'btree' });
+
+// 2. Use query projection
+const results = await collection.query(
+  filter,
+  { projection: { needed: 1, fields: 1 } }
+);
+
+// 3. Enable caching
+collection.configureCacheStrategy({
+  type: 'lru',
+  maxSize: 100
+});
+
+// 4. Check index health
+const report = await collection.verifyIndexes();
 ```
 
-## 🤝 Contributing
+#### 🔴 **Memory Leaks in SPAs**
 
-We welcome contributions! Here's how you can help:
+**Problem:** Memory usage growing over time
 
-1. **Report Bugs**: Open an issue with reproduction steps
-2. **Suggest Features**: Share your ideas in discussions
-3. **Improve Docs**: Fix typos or add examples
-4. **Submit PRs**: Fork, code, test, and submit
+**Solutions:**
+```javascript
+// 1. Clean up on component unmount
+componentWillUnmount() {
+  this.collection.off('update', this.handleUpdate);
+  this.db.destroy();
+}
 
-### Development Setup
+// 2. Use destroy method
+window.addEventListener('beforeunload', () => {
+  lacerta.destroy();
+});
 
-```bash
-# Clone repository
-git clone https://github.com/pixagram-blockchain/LacertaDB.git
-cd LacertaDB
+// 3. Clear caches periodically
+setInterval(() => {
+  collection.clearCache();
+}, 300000);  // Every 5 minutes
+```
+
+#### 🔴 **Encryption Issues**
+
+**Problem:** Cannot access encrypted database
 
-# Install dependencies
-npm install
+**Solutions:**
+```javascript
+// 1. Verify PIN is correct
+try {
+  const db = await lacerta.getSecureDatabase('app', pin);
+} catch (error) {
+  if (error.code === 'ENCRYPTION_FAILED') {
+    console.error('Invalid PIN');
+  }
+}
 
-# Run tests
-npm test
+// 2. Check if salt is preserved
+const metadata = db.encryption.exportMetadata();
+localStorage.setItem('app-salt', metadata.salt);
 
-# Build
-npm run build
+// 3. Use same encryption config
+const db = await lacerta.getSecureDatabase('app', pin, salt, {
+  iterations: 100000,  // Must match original
+  keyLength: 256
+});
 ```
 
-### Testing
+### Debug Mode
 
 ```javascript
-// Test your changes
-import { LacertaDB } from './lacertadb.js';
+// Enable debug logging
+window.LACERTA_DEBUG = true;
+
+// Log all operations
+const originalAdd = collection.add;
+collection.add = async function(...args) {
+  console.log('Adding document:', args);
+  const result = await originalAdd.apply(this, args);
+  console.log('Document added:', result);
+  return result;
+};
+```
 
-const runTests = async () => {
-  const lacerta = new LacertaDB();
-  const db = await lacerta.getDatabase('test');
-  
-  // Test new features
-  const collection = await db.createCollection('test');
-  await collection.createIndex('field', { type: 'hash' });
-  
-  // Verify functionality
-  console.assert(collection.indexManager.indexes.size === 1);
+---
+
+## Error Handling
+
+### Error Types
+
+| Error Code | Description | Resolution |
+|------------|-------------|------------|
+| `DATABASE_OPEN_FAILED` | Cannot open database | Check browser support, clear browser data |
+| `DOCUMENT_NOT_FOUND` | Document doesn't exist | Verify document ID exists |
+| `COLLECTION_NOT_FOUND` | Collection doesn't exist | Create collection first |
+| `COLLECTION_EXISTS` | Collection already exists | Use getCollection instead |
+| `UNIQUE_CONSTRAINT` | Unique index violation | Use different value or update existing |
+| `QUOTA_EXCEEDED` | Storage limit reached | Clear old data or increase limit |
+| `ENCRYPTION_NOT_INITIALIZED` | Encryption required | Use getSecureDatabase |
+| `ENCRYPTION_FAILED` | Decryption failed | Check PIN and salt |
+| `PERMANENT_DOCUMENT_PROTECTION` | Cannot delete permanent | Use force: true option |
+| `TRANSACTION_FAILED` | Transaction aborted | Retry operation |
+| `INVALID_FORMAT` | Invalid data format | Check data structure |
+
+<details>
+<summary><strong>Example Error Handling</strong></summary>
+
+```javascript
+// Comprehensive error handling
+class DatabaseService {
+  async safeOperation(operation) {
+    try {
+      return await operation();
+    } catch (error) {
+      switch (error.code) {
+        case 'UNIQUE_CONSTRAINT':
+          console.error('Duplicate entry:', error.message);
+          // Handle duplicate
+          break;
+          
+        case 'QUOTA_EXCEEDED':
+          console.warn('Storage full, cleaning up...');
+          await this.cleanup();
+          // Retry operation
+          return await operation();
+          
+        case 'DOCUMENT_NOT_FOUND':
+          console.error('Document not found');
+          return null;
+          
+        case 'ENCRYPTION_FAILED':
+          console.error('Invalid credentials');
+          throw new Error('Authentication failed');
+          
+        default:
+          console.error('Database error:', error);
+          throw error;
+      }
+    }
+  }
   
-  console.log('Tests passed!');
-};
+  async cleanup() {
+    const logs = await db.getCollection('logs');
+    const oldLogs = await logs.query({
+      timestamp: { $lt: Date.now() - 86400000 }
+    });
+    await logs.batchDelete(oldLogs.map(log => log._id));
+  }
+}
+
+// Usage
+const service = new DatabaseService();
+const result = await service.safeOperation(async () => {
+  return await users.add({ email: 'test@example.com' });
+});
 ```
 
-## 📄 License
+</details>
 
-MIT License - See [LICENSE](LICENSE) file for details
+---
 
-## 🙏 Acknowledgments
+## Comparison
+
+### LacertaDB vs Alternatives
+
+| Feature | LacertaDB | LocalStorage | IndexedDB (Raw) | PouchDB | Dexie.js |
+|---------|-----------|--------------|-----------------|---------|----------|
+| **Size Limit** | ~2GB* | 5-10MB | ~2GB* | ~2GB* | ~2GB* |
+| **Encryption** | ✅ Built-in | ❌ | ❌ | ⚠️ Plugin | ❌ |
+| **Compression** | ✅ Automatic | ❌ | ❌ | ❌ | ❌ |
+| **Query Language** | ✅ MongoDB-like | ❌ | ❌ | ✅ Map/Reduce | ⚠️ Limited |
+| **Indexes** | ✅ Multiple types | ❌ | ⚠️ Basic | ✅ | ✅ |
+| **Aggregation** | ✅ Full pipeline | ❌ | ❌ | ⚠️ Views | ❌ |
+| **File Attachments** | ✅ OPFS | ❌ | ❌ | ✅ | ❌ |
+| **Performance Monitor** | ✅ Built-in | ❌ | ❌ | ❌ | ❌ |
+| **Bundle Size** | ~45KB | 0KB | 0KB | ~140KB | ~90KB |
+| **TypeScript** | ✅ | ✅ | ✅ | ✅ | ✅ |
+| **Learning Curve** | Medium | Low | High | Medium | Low |
+
+*Actual limit varies by browser and available disk space
+
+### When to Use LacertaDB
+
+✅ **Use LacertaDB when you need:**
+- Client-side encryption for sensitive data
+- Complex queries and aggregations
+- Automatic compression to save space
+- MongoDB-like query syntax
+- Built-in performance monitoring
+- File attachment support
+
+❌ **Consider alternatives when:**
+- You need < 1MB storage (use localStorage)
+- You need server synchronization (use PouchDB)
+- You need minimal bundle size (use raw IndexedDB)
+- You only need key-value storage (use localStorage)
+
+---
+
+## 📝 License
 
-- Built with ❤️ by the Pixagram team
-- Uses TurboSerial and TurboBase64 for high performance
-- Inspired by MongoDB's query language
-- Powered by modern browser APIs (IndexedDB, OPFS, Web Crypto)
+MIT © 2024 LacertaDB Contributors
 
-## 🎉 What's New in v5.0.0
+---
 
-- ⚡ **Custom Indexing**: B-Tree, Hash, Text, and Geo indexes for 50x faster queries
-- 🧠 **Smart Caching**: LRU, LFU, and TTL strategies with per-collection configuration
-- 🔐 **Database Encryption**: PIN-based security with 1M PBKDF2 iterations for private keys
-- 💪 **Force Delete**: Administrative control over permanent documents
-- 📊 **Enhanced Monitoring**: Detailed performance metrics and optimization tips
+## 🙏 Acknowledgments
 
+Special thanks to all contributors and the open-source community.
+
+Built with ❤️ using:
+- [TurboSerial](https://github.com/pixagram/turboserial) for serialization
+- [TurboBase64](https://github.com/pixagram/turbobase64) for encoding
+
+---
 ---
 
-<div align="center">
-  <strong>🦎 LacertaDB v0.6.0 - Fast, Secure, Browser-Native Database</strong>
-  <br>
-  <i>50x faster queries • Military-grade encryption • Smart caching</i>
-  <br><br>
-  Made with ❤️ by Pixagram Blockchain
-</div>
+<p align="center">
+  <strong>Star ⭐ this repository if you find it helpful!</strong>
+</p>