@pixagram/lacerta-db 0.3.0 → 0.5.0

package/readme.md

@@ -1,207 +1,1245 @@
-LacertaDB (@pixagram/lacerta-db)
-LacertaDB is a Javascript IndexedDB Database for Web Browsers. Simple, Fast, Secure.
+# LacertaDB
+![](https://github.com/pixagram-blockchain/LacertaDB/blob/main/logo.webp?raw=true)
+
+> 🦎 **LacertaDB v4.0.3** - 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)]()
+[![Browser Compatible](https://img.shields.io/badge/browser-compatible-green.svg)]()
+
+## 📚 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
+
+```javascript
+import { LacertaDB } from './lacertadb.js';
+
+// Initialize LacertaDB
+const lacerta = new LacertaDB();
+
+// Get or create a database
+const db = await lacerta.getDatabase('myApp');
+
+// Create a collection
+const users = await db.createCollection('users');
+
+// Add a document
+const userId = await users.add({
+  name: 'Alice Johnson',
+  email: 'alice@example.com',
+  age: 28,
+  tags: ['developer', 'javascript']
+});
+
+// Query documents
+const results = await users.query({
+  age: { $gte: 25 },
+  tags: { $in: ['developer'] }
+});
+
+console.log('Found users:', results);
+```
+
+## 📦 Installation
+
+### NPM/Yarn Installation
+
+```bash
+npm install @pixagram/lacertadb
+# or
+yarn add @pixagram/lacertadb
+```
+
+### Browser Module
+
+```html
+<script type="module">
+  import { LacertaDB } from './lacertadb.js';
+  const lacerta = new LacertaDB();
+</script>
+```
+
+### Dependencies
+
+LacertaDB requires:
+- `@pixagram/turboserial` - High-performance serialization
+- `@pixagram/turbobase64` - Optimized Base64 encoding
+
+## 🎯 Basic Usage
+
+### Creating a Database and Collection
+
+```javascript
+const lacerta = new LacertaDB();
+
+// Create or get a database
+const db = await lacerta.getDatabase('myDatabase');
+
+// Create a collection with options
+const products = await db.createCollection('products', {
+  compressed: true,  // Enable compression by default
+  encrypted: false   // Encryption disabled by default
+});
+```
+
+### Adding Documents
+
+```javascript
+// Simple document
+await products.add({
+  name: 'Laptop',
+  price: 999.99,
+  inStock: true
+});
+
+// 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)
+  }
+);
+```
 
-LacertaDB offers a powerful, modern, and feature-rich interface for working with IndexedDB in the browser. It's designed as a document-oriented database, providing a developer-friendly API similar to MongoDB. It prioritizes security, performance, and advanced data handling capabilities right out of the box.
+### Retrieving Documents
 
-✨ Key Features
-Simple API: An intuitive and modern API that makes database operations straightforward.
+```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();
 
-Strong Encryption: Built-in AES-GCM encryption to secure sensitive documents with a password.
+// Get with attachments
+const withFiles = await products.get('doc-id', {
+  includeAttachments: true
+});
+```
 
-Efficient Compression: Automatic data compression using the Compression Streams API to save storage space.
+## 🔧 Core Concepts
 
-OPFS Attachments: Store large files like images or videos efficiently using the Origin Private File System (OPFS), linking them directly to your documents.
+### Database
 
-Advanced Queries: A powerful MongoDB-like query engine with support for complex operators ($gt, $in, $regex, etc.) and logical combinations ($and, $or).
+The database is the top-level container for your collections.
 
-Aggregation Pipeline: Perform complex data analysis and transformations directly in the database with a multi-stage aggregation pipeline ($match, $group, $sort, etc.).
+```javascript
+// Get existing or create new database
+const db = await lacerta.getDatabase('appDB');
 
-High-Performance Serialization: Uses turboserial and turbobase64 instead of JSON for faster serialization and deserialization of data.
+// List all collections
+const collections = db.listCollections();
 
-Automatic Cleanup: Set storage limits and let the database automatically manage space by removing the oldest, non-permanent documents.
+// Get database statistics
+const stats = db.getStats();
+console.log(`Total size: ${stats.totalSizeKB} KB`);
+console.log(`Total documents: ${stats.totalDocuments}`);
 
-Full-Featured: Includes batch operations, query caching, metadata management, and a migration system to handle schema changes over time.
+// Configure database settings
+db.updateSettings({
+  sizeLimitKB: 50000,      // 50MB limit
+  bufferLimitKB: 40000,    // Start cleanup at 40MB
+  freeSpaceEvery: 60000    // Run cleanup every minute
+});
+```
 
-🚀 Installation
-Install the package using your favorite package manager.
+### Collections
 
-npm install @pixagram/lacerta-db
+Collections are containers for documents of similar type.
 
-⚡ Quick Start
-Here's how to get up and running with LacertaDB in just a few lines of code.
+```javascript
+// Create collection
+const posts = await db.createCollection('posts');
 
-// Import the default instance
-import LacertaDB from '@pixagram/lacerta-db';
+// Get existing collection
+const existingPosts = await db.getCollection('posts');
 
-async function main() {
-  try {
-    // 1. Get a database instance
-    const db = await LacertaDB.getDatabase('my-app-db');
+// Collection operations
+await posts.clear();                    // Remove all documents
+await db.dropCollection('posts');       // Delete collection entirely
 
-    // 2. Get or create a collection
-    // Collections are created automatically on first access
-    const users = await db.getCollection('users');
+// Collection events
+posts.on('afterAdd', (doc) => {
+  console.log('Document added:', doc._id);
+});
+```
+
+### Documents
+
+Documents are JavaScript objects with automatic metadata.
+
+```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
+};
+```
 
-    // 3. Add a new document
-    const newUserId = await users.add({
-      name: 'Alex',
-      level: 10,
-      joined: new Date()
-    });
-    console.log(`User created with ID: ${newUserId}`);
+## 🔍 Querying
 
-    // 4. Get a document by its ID
-    const user = await users.get(newUserId);
-    console.log('Retrieved user:', user);
+### Basic Queries
 
-    // 5. Query for documents
-    const highLevelUsers = await users.query({ level: { '$gt': 5 } });
-    console.log('High-level users:', highLevelUsers);
+```javascript
+// Find all documents matching criteria
+const results = await users.query({
+  age: 30,                           // Exact match
+  'address.city': 'New York'         // Nested field
+});
 
-  } catch (error) {
-    console.error('Database operation failed:', error);
+// With options
+const paginatedResults = await users.query(
+  { status: 'active' },
+  {
+    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
+    }
   }
-}
+);
+```
 
-main();
+### Advanced Queries
 
-📖 API Reference
-Database
-The Database object is your main entry point for managing collections.
+LacertaDB supports MongoDB-style query operators:
 
-getDatabase(name)
-Retrieves a database instance. If it doesn't exist, it's created.
+#### Comparison Operators
 
-const db = await LacertaDB.getDatabase('my-app-db');
+```javascript
+// $eq, $ne, $gt, $gte, $lt, $lte
+await products.query({
+  price: { $gte: 100, $lte: 500 }
+});
 
-getCollection(name)
-Retrieves a collection from the database. If it doesn't exist, it's created.
+// $in, $nin
+await users.query({
+  role: { $in: ['admin', 'moderator'] }
+});
+```
 
-const usersCollection = await db.getCollection('users');
+#### Logical Operators
 
-dropCollection(name)
-Deletes a collection and all of its documents and attachments.
+```javascript
+// $and
+await products.query({
+  $and: [
+    { price: { $lt: 1000 } },
+    { category: 'electronics' }
+  ]
+});
 
-await db.dropCollection('users');
+// $or
+await users.query({
+  $or: [
+    { age: { $gte: 65 } },
+    { status: 'premium' }
+  ]
+});
 
-Collection
-The Collection object provides methods to interact with documents.
+// $not
+await products.query({
+  discontinued: { $not: { $eq: true } }
+});
+```
 
-add(data, [options])
-Adds a new document to the collection.
+#### Array Operators
 
-data (Object): The document data.
+```javascript
+// $all - Array contains all values
+await posts.query({
+  tags: { $all: ['javascript', 'database'] }
+});
 
-options (Object, optional):
+// $elemMatch - Element matching
+await orders.query({
+  items: {
+    $elemMatch: {
+      product: 'laptop',
+      quantity: { $gte: 2 }
+    }
+  }
+});
 
-encrypted (boolean): Set to true to encrypt the document.
+// $size - Array length
+await users.query({
+  hobbies: { $size: 3 }
+});
+```
 
-password (string): Required if encrypted is true.
+#### Text Search
 
-permanent (boolean): If true, the document won't be deleted by the auto-cleanup process.
+```javascript
+// $regex - Regular expression
+await users.query({
+  email: { $regex: '@company\\.com$' }
+});
 
-attachments (Array): An array of file attachments.
+// $text - Case-insensitive text search
+await posts.query({
+  content: { $text: 'javascript' }
+});
+```
+
+### Aggregation Pipeline
+
+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'
+      }
+    }
+  }
+]);
+```
+
+#### Lookup (Join) Operations
+
+```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
+    }
+  }
+]);
+```
+
+## 🔐 Security Features
+
+### Encryption
+
+Documents can be individually encrypted with AES-256-GCM:
+
+```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
+  }
+);
 
-const userId = await users.add({ name: 'Zoe' }, { permanent: true });
+// Retrieve encrypted document
+const userData = await users.get('user-id', {
+  password: 'strong-password-here'  // Required for decryption
+});
 
-get(id, [options])
-Retrieves a single document by its _id.
+// Update encrypted document
+await users.update('user-id', 
+  { salary: 80000 },
+  { 
+    encrypted: true,
+    password: 'strong-password-here' 
+  }
+);
+```
 
-id (string): The document ID.
+### Password Protection
 
-options (Object, optional):
+Secure your exports and backups:
 
-password (string): Required to decrypt an encrypted document.
+```javascript
+// Export with encryption
+const encryptedExport = await db.export('encrypted', 'export-password');
 
-includeAttachments (boolean): If true, retrieves file data from OPFS.
+// Import encrypted data
+await db.import(encryptedExport, 'encrypted', 'export-password');
 
-const user = await users.get(userId);
+// Create encrypted backup
+const backup = await lacerta.createBackup('backup-password');
 
-query(filter, [options])
-Finds documents matching the filter object.
+// Restore from encrypted backup
+await lacerta.restoreBackup(backup, 'backup-password');
+```
 
-filter (Object): A MongoDB-style query object.
+## 📎 Attachments
 
-options (Object, optional):
+Store files using the Origin Private File System:
 
-sort (Object): Sort order (e.g., { level: -1 }).
+```javascript
+// Prepare files
+const file1 = new File(['content'], 'document.pdf', { type: 'application/pdf' });
+const file2 = new Blob(['image data'], { type: 'image/png' });
 
-limit (number): Max number of documents to return.
+// 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')
+      }
+    ]
+  }
+);
 
-skip (number): Number of documents to skip.
+// Retrieve with attachments
+const docWithFiles = await documents.get(docId, {
+  includeAttachments: true
+});
 
-const results = await users.query({ name: 'Alex' });
+// Access attachments
+docWithFiles._attachments.forEach(attachment => {
+  console.log(`File: ${attachment.name} (${attachment.size} bytes)`);
+  // attachment.data is Uint8Array
+});
+```
 
-update(id, updates)
-Updates the data of a specific document.
+## ⚡ Performance
 
-await users.update(userId, { level: 11 });
+### Compression
 
-delete(id)
-Removes a document from the collection.
+Reduce storage size with automatic compression:
 
-await users.delete(userId);
+```javascript
+// Enable compression for all documents in collection
+const compressedColl = await db.createCollection('largeDocs', {
+  compressed: true
+});
 
-aggregate(pipeline)
-Processes documents through an aggregation pipeline.
+// Per-document compression
+await collection.add(largeData, {
+  compressed: true  // Uses DeflateStream compression
+});
+```
 
-const results = await users.aggregate([
-  { '$match': { level: { '$gt': 5 } } },
-  { '$group': { _id: null, averageLevel: { '$avg': '$level' } } }
-]);
+### Performance Monitoring
+
+Track database performance metrics:
+
+```javascript
+// Start monitoring
+lacerta.performanceMonitor.startMonitoring();
+
+// Perform operations...
+
+// 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`);
+
+// Get optimization tips
+const tips = lacerta.performanceMonitor.getOptimizationTips();
+tips.forEach(tip => console.log(`💡 ${tip}`));
+
+// Stop monitoring
+lacerta.performanceMonitor.stopMonitoring();
+```
+
+### Query Caching
+
+Queries are automatically cached for 60 seconds:
 
-🛠️ Advanced Usage
-Encryption 🔒
-To store sensitive data, simply set the encrypted flag and provide a password. LacertaDB handles the rest.
+```javascript
+// First query - hits database
+const results1 = await users.query({ status: 'active' });
 
-const secretData = { account: '123-456', secret: 'my-secret-key' };
+// Second identical query - served from cache
+const results2 = await users.query({ status: 'active' });
 
-const docId = await db.collection('secrets').add(secretData, {
-  encrypted: true,
-  password: 'a-very-strong-password'
+// Clear cache manually if needed
+users.clearCache();
+```
+
+## 🔄 Data Migration
+
+Version your schema changes:
+
+```javascript
+const migrationManager = new MigrationManager(db);
+
+// 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' };
+    }
+    return doc;
+  },
+  down: async (doc) => {
+    if (doc.type === 'user') {
+      const { role, ...rest } = doc;
+      return rest;
+    }
+    return doc;
+  }
+});
+
+// Run migrations
+await migrationManager.runMigrations('2.0.0');
+
+// Rollback if needed
+await migrationManager.rollback('1.0.0');
+```
+
+## 💾 Backup & Restore
+
+### Database Export/Import
+
+```javascript
+// Export single database
+const exportData = await db.export('json');
+// Save exportData to file or send to server
+
+// Import data
+const importResult = await db.import(exportData, 'json');
+console.log(`Imported ${importResult.documents} documents`);
+
+// Export with encryption
+const secureExport = await db.export('encrypted', 'password123');
+```
+
+### Full System Backup
+
+```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}`);
+```
+
+## 🛠️ Advanced Features
+
+### Batch Operations
+
+Efficient bulk operations with transaction support:
+
+```javascript
+// Batch insert
+const documents = [
+  { name: 'Doc 1', value: 100 },
+  { name: 'Doc 2', value: 200 },
+  { name: 'Doc 3', value: 300 }
+];
+
+const results = await collection.batchAdd(documents, {
+  compressed: true,
+  encrypted: false
 });
 
-// You MUST provide the same password to retrieve it
-const retrieved = await db.collection('secrets').get(docId, {
-  password: 'a-very-strong-password'
+// Check results
+results.forEach(result => {
+  if (result.success) {
+    console.log(`✅ Added: ${result.id}`);
+  } else {
+    console.log(`❌ Failed: ${result.error}`);
+  }
 });
 
-File Attachments 📎
-You can attach files (like File objects or Uint8Array data) to a document. They are stored efficiently in the browser's Origin Private File System.
+// Batch update
+const updates = [
+  { id: 'doc1', data: { status: 'active' } },
+  { id: 'doc2', data: { status: 'inactive' } }
+];
+await collection.batchUpdate(updates);
 
-// Create a sample file
-const fileContent = new TextEncoder().encode('This is the content of my file.');
-const attachment = {
-    name: 'readme.txt',
-    type: 'text/plain',
-    data: fileContent
+// Batch delete
+const idsToDelete = ['doc3', 'doc4', 'doc5'];
+await collection.batchDelete(idsToDelete);
+```
+
+### Event System
+
+React to database operations:
+
+```javascript
+// Collection-level events
+collection.on('beforeAdd', async (data) => {
+  console.log('Validating document...');
+  // Perform validation
+});
+
+collection.on('afterAdd', async (doc) => {
+  console.log(`Document ${doc._id} added`);
+  // Send notification, update cache, etc.
+});
+
+collection.on('beforeUpdate', async ({ docId, updates }) => {
+  console.log(`Updating ${docId}`);
+});
+
+collection.on('afterDelete', async (docId) => {
+  console.log(`Document ${docId} deleted`);
+  // Cleanup related data
+});
+
+// Remove event listener
+const handler = (doc) => console.log(doc);
+collection.on('afterAdd', handler);
+collection.off('afterAdd', handler);
+```
+
+### Quick Store
+
+Fast localStorage-based storage for small data:
+
+```javascript
+// Access QuickStore
+const quickStore = db.quickStore;
+
+// Store data
+quickStore.add('user-prefs', {
+  theme: 'dark',
+  language: 'en',
+  notifications: 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
+});
+
+// Manual cleanup
+await collection.freeSpace();
+
+// Mark documents as permanent
+await collection.add(importantData, {
+  permanent: true  // Won't be deleted during cleanup
+});
+
+// Check collection size
+const stats = collection.metadata;
+console.log(`Collection size: ${stats.sizeKB} KB`);
+console.log(`Document count: ${stats.length}`);
+```
+
+### Storage Information
+
+```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);
+```
+
+## 🎨 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
+
+```javascript
+// Initialize
+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'
+}, {
+  sort: { createdAt: -1 }
+});
+
+// Mark as complete
+await todos.update(todoId, {
+  completed: true,
+  completedAt: Date.now()
+});
+
+// Get statistics
+const stats = await todos.aggregate([
+  {
+    $group: {
+      _id: '$priority',
+      count: { $count: {} },
+      completed: { 
+        $sum: { $cond: ['$completed', 1, 0] } 
+      }
+    }
+  }
+]);
+```
+
+### E-Commerce Inventory
+
+```javascript
+// Setup
+const db = await lacerta.getDatabase('shop');
+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 }
+});
+
+// Sales report with joins
+const salesReport = await orders.aggregate([
+  { $match: { status: 'completed' } },
+  {
+    $lookup: {
+      from: 'products',
+      localField: 'productId',
+      foreignField: '_id',
+      as: 'product'
+    }
+  },
+  {
+    $group: {
+      _id: '$product.category',
+      revenue: { $sum: '$total' },
+      orderCount: { $count: {} }
+    }
+  },
+  { $sort: { revenue: -1 } }
+]);
+```
+
+### User Session Management
+
+```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
+  }
+);
+
+// Cleanup expired sessions
+const now = Date.now();
+const expired = await sessions.query({
+  expiresAt: { $lt: now }
+});
+
+await sessions.batchDelete(expired.map(s => s._id));
+```
+
+## 🐛 Error Handling
+
+LacertaDB provides detailed error information:
+
+```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;
+    }
+  }
+}
+```
+
+### Common Error Codes
+
+| 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 |
+
+## 📝 Best Practices
+
+### 1. Index 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
+};
+
+// 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' });
+```
+
+### 2. Cache Optimization
+
+```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 }
 };
+```
+
+### 3. Security Best Practices
 
-// Add a document with the attachment
-const reportId = await db.collection('reports').add(
-  { title: 'Q3 Report' },
-  { attachments: [attachment] }
+```javascript
+// For private keys and sensitive data
+const secureDb = await lacerta.getSecureDatabase(
+  'vault',
+  SecureDatabaseEncryption.generateSecurePIN(12)  // 12-digit secure PIN
 );
 
-// Retrieve the document and its attachments
-const report = await db.collection('reports').get(reportId, {
-  includeAttachments: true
+// 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
+};
+```
+
+### 4. Performance Optimization
+
+```javascript
+// Enable monitoring during development
+lacerta.performanceMonitor.startMonitoring();
+
+// 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);
+};
+
+// Get optimization suggestions
+const tips = lacerta.performanceMonitor.getOptimizationTips();
+```
+
+### 5. Storage Management
+
+```javascript
+// Set appropriate limits
+db.updateSettings({
+  sizeLimitKB: 100000,      // 100MB total
+  bufferLimitKB: 80000,     // Start cleanup at 80MB
+  freeSpaceEvery: 300000    // Check every 5 minutes
 });
 
-console.log(report.data._attachments[0].name); // "readme.txt"
-const content = new TextDecoder().decode(report.data._attachments[0].data);
-console.log(content); // "This is the content of my file."
+// Mark critical documents as permanent
+await collection.add(importantData, { permanent: true });
+
+// Regular maintenance
+const maintenance = async () => {
+  const stats = db.getStats();
+  if (stats.totalSizeKB > 90000) {
+    // Cleanup old non-permanent documents
+    await collection.freeSpace();
+  }
+};
+```
+
+## 🔄 Migration from v4.x
+
+### Breaking Changes
+
+None! LacertaDB v5.0.0 is fully backward compatible. All v4.x code continues to work without modifications.
+
+### New Features to Adopt
+
+```javascript
+// v4.x code (still works)
+const collection = await db.createCollection('data');
+const results = await collection.query({ status: 'active' });
+
+// v5.0.0 optimized code
+const collection = await db.createCollection('data');
+
+// Add index for 50x faster queries
+await collection.createIndex('status', { type: 'hash' });
+
+// Configure smart caching
+await collection.configureCacheStrategy({
+  type: 'lru',
+  maxSize: 500,
+  ttl: 120000
+});
+
+// Now queries are much faster
+const results = await collection.query({ status: 'active' });
+```
+
+### Migration Checklist
+
+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
+
+```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!');
+};
+```
+
+## 🤝 Contributing
+
+We welcome contributions! Here's how you can help:
+
+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
+
+### Development Setup
+
+```bash
+# Clone repository
+git clone https://github.com/pixagram-blockchain/LacertaDB.git
+cd LacertaDB
+
+# Install dependencies
+npm install
+
+# Run tests
+npm test
+
+# Build
+npm run build
+```
+
+### Testing
+
+```javascript
+// Test your changes
+import { LacertaDB } from './lacertadb.js';
+
+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);
+  
+  console.log('Tests passed!');
+};
+```
+
+## 📄 License
+
+MIT License - See [LICENSE](LICENSE) file for details
+
+## 🙏 Acknowledgments
+
+- 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)
 
-⚙️ Serialization: TurboSerial
-A key performance feature of LacertaDB is its use of turboserial instead of JSON. This provides several advantages:
+## 📮 Support
 
-⚡ Speed: turboserial is significantly faster at serializing and deserializing complex JavaScript objects.
+- 📧 Email: support@pixagram.com
+- 💬 Discord: [Join our community](https://discord.gg/pixagram)
+- 📚 Documentation: [docs.lacertadb.com](https://docs.lacertadb.com)
+- 🐛 Issues: [GitHub Issues](https://github.com/pixagram-blockchain/LacertaDB/issues)
 
-📦 Efficiency: It produces a more compact binary output, especially when compression is enabled, saving storage space.
+## 🎉 What's New in v5.0.0
 
-🔬 Type Support: It correctly handles more data types than JSON, including Date, Map, Set, BigInt, and typed arrays.
+- ⚡ **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
 
-All data stored in localStorage (like metadata) or passed to IndexedDB is processed through turboserial and turbobase64, ensuring top-tier performance.
+---
 
-📜 License
-LacertaDB is licensed under the MIT License.
+<div align="center">
+  <strong>🦎 LacertaDB v5.0.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>