@pixagram/lacerta-db 0.0.3 → 0.2.0

package/readme.md

@@ -1,998 +1,207 @@
-# LacertaDB Technical Documentation
-*Version 1.0.0 - Architecturally Refined Implementation*
-
-## Table of Contents
-1. [Installation & Prerequisites](#installation--prerequisites)
-2. [Architecture Overview](#architecture-overview)
-3. [API Reference](#api-reference)
-4. [Data Schemas](#data-schemas)
-5. [Error Handling](#error-handling)
-6. [Edge Cases & Behaviors](#edge-cases--behaviors)
-7. [Performance Optimization](#performance-optimization)
-8. [Security Model](#security-model)
-9. [Code Examples](#code-examples)
-
----
-
-## Installation & Prerequisites
-
-### Critical Dependencies
-```javascript
-// REQUIRED: JOYSON library for binary serialization
-npm install joyson
-// OR include via CDN
-<script src="https://cdn.jsdelivr.net/npm/joyson/dist/joyson.min.js"></script>
-```
-
-### Browser Requirements
-| API | Minimum Version | Required |
-|-----|-----------------|----------|
-| IndexedDB | Chrome 24+ | ✅ |
-| localStorage | All modern | ✅ |
-| Web Crypto API | Chrome 37+ | ✅ |
-| CompressionStream | Chrome 86+ | ✅ |
-| Origin Private File System | Chrome 86+ | ✅ |
-
-### Module Import
-```javascript
-import { Database, Document, Collection } from './lacertadb.js';
-```
-
----
-
-## Architecture Overview
-
-### Storage Hierarchy
-```
-┌─────────────────────────────────────────┐
-│         Application Layer               │
-└─────────────┬───────────────────────────┘
-              │
-┌─────────────▼───────────────────────────┐
-│         Database Instance               │
-│  • Collections Management               │
-│  • Global Settings                      │
-│  • Metadata Coordination                │
-└─────────────┬───────────────────────────┘
-              │
-┌─────────────▼───────────────────────────┐
-│         Storage Layers                  │
-├─────────────────────────────────────────┤
-│ IndexedDB    │ Primary document storage │
-│ localStorage │ Metadata & settings      │
-│ OPFS         │ Binary attachments       │
-│ QuickStore   │ Sync localStorage cache  │
-└─────────────────────────────────────────┘
-```
-
-### Transaction Flow
-```
-User Request → TransactionManager → Queue → IndexedDB
-                                      ↓
-                              Metadata Update
-                                      ↓
-                              Observer Events
-```
-
----
-
-## API Reference
-
-### Database Class
-
-#### Constructor
-```javascript
-new Database(dbName: string, settings?: DatabaseSettings)
-```
-
-**Parameters:**
-- `dbName` (string): Unique database identifier
-- `settings` (object, optional): Configuration object
-
-**Settings Schema:**
-```typescript
-interface DatabaseSettings {
-  sizeLimitKB?: number;      // Max size before cleanup (default: Infinity)
-  bufferLimitKB?: number;     // Buffer before trigger (default: -20% of sizeLimitKB)
-  freeSpaceEvery?: number;    // Ms between cleanups (default: 10000, min: 1000)
-}
-```
+LacertaDB (@pixagram/lacerta-db)
+LacertaDB is a Javascript IndexedDB Database for Web Browsers. Simple, Fast, Secure.
 
-#### Methods
+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.
 
-##### `async init(): Promise<void>`
-Initializes database connection and loads collections.
+✨ Key Features
+Simple API: An intuitive and modern API that makes database operations straightforward.
 
-**Throws:** `LacertaDBError` if database cannot be opened
+Strong Encryption: Built-in AES-GCM encryption to secure sensitive documents with a password.
 
-**Example:**
-```javascript
-const db = new Database('myapp');
-await db.init();
-```
+Efficient Compression: Automatic data compression using the Compression Streams API to save storage space.
 
----
+OPFS Attachments: Store large files like images or videos efficiently using the Origin Private File System (OPFS), linking them directly to your documents.
 
-##### `async createCollection(collectionName: string): Promise<LacertaDBResult>`
-Creates a new collection or returns existing one.
+Advanced Queries: A powerful MongoDB-like query engine with support for complex operators ($gt, $in, $regex, etc.) and logical combinations ($and, $or).
 
-**Returns:** `LacertaDBResult` object
-```typescript
-{
-  success: boolean,
-  data: Collection | null,
-  error: LacertaDBError | null
-}
-```
-
-**Behavior Matrix:**
-| Scenario | `success` | `data` | `error` |
-|----------|-----------|---------|----------|
-| New collection created | `true` | Collection instance | `null` |
-| Collection already exists | `false` | Existing Collection | `COLLECTION_EXISTS` error |
-
-**Example:**
-```javascript
-const result = await db.createCollection('users');
-if (result.success) {
-  const collection = result.data;
-} else {
-  console.log('Collection exists:', result.data);
-}
-```
+Aggregation Pipeline: Perform complex data analysis and transformations directly in the database with a multi-stage aggregation pipeline ($match, $group, $sort, etc.).
 
----
+High-Performance Serialization: Uses turboserial and turbobase64 instead of JSON for faster serialization and deserialization of data.
 
-##### `async getCollection(collectionName: string): Promise<LacertaDBResult>`
-Retrieves a collection by name.
+Automatic Cleanup: Set storage limits and let the database automatically manage space by removing the oldest, non-permanent documents.
 
-**Returns:** `LacertaDBResult` object
+Full-Featured: Includes batch operations, query caching, metadata management, and a migration system to handle schema changes over time.
 
-**Behavior Matrix:**
-| Scenario | `success` | `data` | `error` |
-|----------|-----------|---------|----------|
-| Collection exists in memory | `true` | Collection instance | `null` |
-| Collection exists in DB only | `true` | New Collection instance | `null` |
-| Collection doesn't exist | `false` | `null` | `COLLECTION_NOT_FOUND` error |
+🚀 Installation
+Install the package using your favorite package manager.
 
-**Example:**
-```javascript
-const result = await db.getCollection('users');
-if (result.success) {
-  const collection = result.data;
-} else {
-  console.error('Collection not found:', result.error.message);
-}
-```
+npm install @pixagram/lacerta-db
 
----
+⚡ Quick Start
+Here's how to get up and running with LacertaDB in just a few lines of code.
 
-##### `async deleteCollection(collectionName: string): Promise<LacertaDBResult>`
-Deletes a collection and all its documents.
+// Import the default instance
+import LacertaDB from '@pixagram/lacerta-db';
 
-**Returns:** `LacertaDBResult` object
+async function main() {
+  try {
+    // 1. Get a database instance
+    const db = await LacertaDB.getDatabase('my-app-db');
 
-**Behavior Matrix:**
-| Scenario | `success` | `data` | `error` |
-|----------|-----------|---------|----------|
-| Collection deleted | `true` | `null` | `null` |
-| Collection doesn't exist | `false` | `null` | `COLLECTION_NOT_FOUND` error |
+    // 2. Get or create a collection
+    // Collections are created automatically on first access
+    const users = await db.getCollection('users');
 
-**Side Effects:**
-- Clears all documents from IndexedDB
-- Removes collection metadata
-- Cleans up event observers
-- Stops free space timers
+    // 3. Add a new document
+    const newUserId = await users.add({
+      name: 'Alex',
+      level: 10,
+      joined: new Date()
+    });
+    console.log(`User created with ID: ${newUserId}`);
 
----
+    // 4. Get a document by its ID
+    const user = await users.get(newUserId);
+    console.log('Retrieved user:', user);
 
-##### `async close(): Promise<void>`
-Closes all database connections.
+    // 5. Query for documents
+    const highLevelUsers = await users.query({ level: { '$gt': 5 } });
+    console.log('High-level users:', highLevelUsers);
 
-**Important:** Always call before application termination.
+  } catch (error) {
+    console.error('Database operation failed:', error);
+  }
+}
 
----
+main();
 
-##### `async deleteDatabase(): Promise<void>`
-Permanently deletes entire database.
+📖 API Reference
+Database
+The Database object is your main entry point for managing collections.
 
-**Warning:** This operation is irreversible!
+getDatabase(name)
+Retrieves a database instance. If it doesn't exist, it's created.
 
-**Side Effects:**
-- Deletes IndexedDB database
-- Removes all localStorage metadata
-- Clears all settings
-- Invalidates all collection references
+const db = await LacertaDB.getDatabase('my-app-db');
 
----
+getCollection(name)
+Retrieves a collection from the database. If it doesn't exist, it's created.
 
-### Collection Class
+const usersCollection = await db.getCollection('users');
 
-#### Properties
+dropCollection(name)
+Deletes a collection and all of its documents and attachments.
 
-| Property | Type | Description |
-|----------|------|-------------|
-| `name` | string | Collection identifier |
-| `sizeKB` | number | Total size in kilobytes |
-| `length` | number | Document count |
-| `keys` | string[] | All document IDs |
-| `observer` | Observer | Event emitter instance |
-| `documentsMetadata` | Array | Document metadata array |
+await db.dropCollection('users');
 
-#### Methods
+Collection
+The Collection object provides methods to interact with documents.
 
-##### `async addDocument(documentData: DocumentInput, encryptionKey?: string): Promise<boolean>`
+add(data, [options])
+Adds a new document to the collection.
 
-**Parameters:**
-```typescript
-interface DocumentInput {
-  _id?: string;           // Auto-generated if omitted
-  _permanent?: boolean;   // Prevents auto-deletion (default: false)
-  _compressed?: boolean;  // Enable compression (default: false)
-  data: object;          // Document content
-  attachments?: Array<{data: Blob}>; // File attachments
-}
-```
-
-**Returns:** `boolean` - `true` if new document, `false` if updated
-
-**Behavior:**
-- Auto-generates ID if not provided
-- Updates existing document if ID exists
-- Saves attachments to OPFS
-- Triggers space management
-- Emits `beforeAdd` and `afterAdd` events
-
-**Example:**
-```javascript
-const isNew = await collection.addDocument({
-  data: { name: 'Alice', age: 30 },
-  _permanent: true,
-  attachments: [{ data: imageBlob }]
-}, 'encryption-password');
-```
-
----
-
-##### `async getDocument(docId: string, encryptionKey?: string, includeAttachments?: boolean): Promise<Document | false>`
-
-**Returns:** Document object or `false`
-
-**Behavior Matrix:**
-| Scenario | Return Value |
-|----------|--------------|
-| Document exists, no encryption | Document object |
-| Document exists, correct key | Document object |
-| Document exists, wrong/missing key | `false` |
-| Document doesn't exist | `false` |
-
----
-
-##### `async deleteDocument(docId: string, force?: boolean): Promise<boolean>`
-
-**Parameters:**
-- `docId`: Document identifier
-- `force`: Override permanent flag (default: false)
-
-**Returns:** `boolean` - Success status
-
-**Behavior Matrix:**
-| Scenario | `force` | Result |
-|----------|---------|---------|
-| Non-permanent document | any | Deleted |
-| Permanent document | `false` | Not deleted |
-| Permanent document | `true` | Deleted |
-| Document doesn't exist | any | Returns `false` |
-
----
-
-##### `async query(filter?: object, options?: QueryOptions): Promise<Document[]>`
-
-**Parameters:**
-```typescript
-interface QueryOptions {
-  encryptionKey?: string;
-  limit?: number;         // Max results (default: Infinity)
-  offset?: number;        // Skip documents (default: 0)
-  orderBy?: 'asc' | 'desc';
-  index?: string;         // Index name for optimization
-}
-```
+data (Object): The document data.
 
-**Filter Examples:**
-```javascript
-// Simple equality
-{ status: 'active' }
+options (Object, optional):
 
-// Nested property
-{ 'address.city': 'New York' }
-```
+encrypted (boolean): Set to true to encrypt the document.
 
----
+password (string): Required if encrypted is true.
 
-##### `async createIndex(fieldPath: string, options?: IndexOptions): Promise<void>`
+permanent (boolean): If true, the document won't be deleted by the auto-cleanup process.
 
-**Parameters:**
-```typescript
-interface IndexOptions {
-  name?: string;      // Custom index name
-  unique?: boolean;   // Enforce uniqueness
-  multiEntry?: boolean; // Index array values
-}
-```
+attachments (Array): An array of file attachments.
 
-**Example:**
-```javascript
-await collection.createIndex('data.email', {
-  name: 'email_idx',
-  unique: true
-});
-```
+const userId = await users.add({ name: 'Zoe' }, { permanent: true });
 
----
+get(id, [options])
+Retrieves a single document by its _id.
 
-##### `async freeSpace(size: number): Promise<number>`
+id (string): The document ID.
 
-**Parameters:**
-- `size`: Target size in KB (positive) or amount to free (negative)
+options (Object, optional):
 
-**Returns:** Amount freed in KB
+password (string): Required to decrypt an encrypted document.
 
-**Algorithm:**
-1. Sorts non-permanent documents by modification time
-2. Deletes oldest first
-3. Stops when target reached
+includeAttachments (boolean): If true, retrieves file data from OPFS.
 
----
+const user = await users.get(userId);
 
-### Document Class
+query(filter, [options])
+Finds documents matching the filter object.
 
-#### Constructor
-```javascript
-new Document(data: DocumentData, encryptionKey?: string)
-```
+filter (Object): A MongoDB-style query object.
 
-#### Schema
-```typescript
-interface DocumentData {
-  _id?: string;
-  _created?: number;
-  _modified?: number;
-  _permanent?: boolean;
-  _encrypted?: boolean;
-  _compressed?: boolean;
-  data?: object;
-  packedData?: Uint8Array;
-  attachments?: Array;
-}
-```
-
-#### Methods
-
-##### `async pack(): Promise<Uint8Array>`
-Serializes, compresses, and encrypts document data.
-
-##### `async unpack(): Promise<object>`
-Deserializes, decompresses, and decrypts document data.
-
-##### `packSync(): Uint8Array`
-Synchronous packing (no encryption/compression).
+options (Object, optional):
 
-**Throws:** Error if document has encryption or compression enabled
+sort (Object): Sort order (e.g., { level: -1 }).
 
-##### `unpackSync(): object`
-Synchronous unpacking (no encryption/compression).
+limit (number): Max number of documents to return.
 
----
+skip (number): Number of documents to skip.
 
-### QuickStore Class
+const results = await users.query({ name: 'Alex' });
 
-Provides synchronous localStorage-based storage.
+update(id, updates)
+Updates the data of a specific document.
 
-#### Methods
+await users.update(userId, { level: 11 });
 
-##### `setDocumentSync(documentData: object, encryptionKey?: string): boolean`
-**Note:** Cannot use encryption or compression (throws error).
+delete(id)
+Removes a document from the collection.
 
-##### `getDocumentSync(docId: string, encryptionKey?: string): object | null`
+await users.delete(userId);
 
-##### `deleteDocumentSync(docId: string, force?: boolean): boolean`
+aggregate(pipeline)
+Processes documents through an aggregation pipeline.
 
-##### `getAllKeys(): string[]`
+const results = await users.aggregate([
+  { '$match': { level: { '$gt': 5 } } },
+  { '$group': { _id: null, averageLevel: { '$avg': '$level' } } }
+]);
 
----
+🛠️ Advanced Usage
+Encryption 🔒
+To store sensitive data, simply set the encrypted flag and provide a password. LacertaDB handles the rest.
 
-## Data Schemas
+const secretData = { account: '123-456', secret: 'my-secret-key' };
 
-### Document Schema (Stored)
-```javascript
-{
-  "_id": "xxxx-xxxx-xxxx",
-  "_created": 1234567890,
-  "_modified": 1234567890,
-  "_permanent": false,
-  "_encrypted": false,
-  "_compressed": false,
-  "packedData": Uint8Array,
-  "attachments": ["db/collection/doc/0", "db/collection/doc/1"]
-}
-```
-
-### Document Schema (Retrieved)
-```javascript
-{
-  "_id": "xxxx-xxxx-xxxx",
-  "_created": 1234567890,
-  "_modified": 1234567890,
-  "_permanent": false,
-  "_encrypted": false,
-  "_compressed": false,
-  "data": { /* user data */ },
-  "attachments": [
-    { "path": "db/collection/doc/0", "data": File },
-    { "path": "db/collection/doc/1", "data": File }
-  ]
-}
-```
-
-### Metadata Schema
-```javascript
-{
-  "name": "database_name",
-  "collections": {
-    "collection_name": {
-      "name": "collection_name",
-      "sizeKB": 1024.5,
-      "length": 100,
-      "createdAt": 1234567890,
-      "modifiedAt": 1234567890,
-      "documentSizes": { "docId": 10.5 },
-      "documentModifiedAt": { "docId": 1234567890 },
-      "documentPermanent": { "docId": 1 },
-      "documentAttachments": { "docId": 2 }
-    }
-  },
-  "totalSizeKB": 2048.5,
-  "totalLength": 200,
-  "modifiedAt": 1234567890
-}
-```
-
----
-
-## Error Handling
-
-### Error Codes
-| Code | Description | Recovery Strategy |
-|------|-------------|-------------------|
-| `COLLECTION_EXISTS` | Collection already exists | Use existing collection |
-| `COLLECTION_NOT_FOUND` | Collection doesn't exist | Create collection first |
-| `DOCUMENT_NOT_FOUND` | Document doesn't exist | Check document ID |
-| `ENCRYPTION_FAILED` | Encryption/decryption failed | Verify encryption key |
-| `TRANSACTION_FAILED` | Database transaction failed | Retry operation |
-| `QUOTA_EXCEEDED` | Storage quota exceeded | Free space or increase quota |
-| `ATTACHMENT_DELETE_FAILED` | Attachment cleanup failed | Manual OPFS cleanup |
-| `METADATA_SYNC_FAILED` | Metadata save failed | Check localStorage quota |
-
-### Error Handling Pattern
-```javascript
-try {
-  const result = await db.createCollection('users');
-  if (result.success) {
-    // Handle success
-  } else {
-    switch (result.error.code) {
-      case ErrorCodes.COLLECTION_EXISTS:
-        // Use existing collection
-        break;
-      default:
-        throw result.error;
-    }
-  }
-} catch (error) {
-  if (error instanceof LacertaDBError) {
-    console.error(`Database error ${error.code}: ${error.message}`);
-  }
-}
-```
-
----
-
-## Edge Cases & Behaviors
-
-### Collection Operations
-
-#### Creating Existing Collection
-```javascript
-const result1 = await db.createCollection('users');
-// result1.success = true, result1.data = Collection
-
-const result2 = await db.createCollection('users');
-// result2.success = false
-// result2.data = existing Collection instance
-// result2.error.code = 'COLLECTION_EXISTS'
-```
-
-#### Getting Non-Existent Collection
-```javascript
-const result = await db.getCollection('nonexistent');
-// result.success = false
-// result.data = null
-// result.error.code = 'COLLECTION_NOT_FOUND'
-```
-
-#### Deleting Non-Existent Collection
-```javascript
-const result = await db.deleteCollection('nonexistent');
-// result.success = false
-// result.data = null
-// result.error.code = 'COLLECTION_NOT_FOUND'
-```
-
-### Document Operations
-
-#### Adding Document with Existing ID
-```javascript
-// First add
-await collection.addDocument({ _id: 'doc1', data: { v: 1 } });
-// Returns: true (new document)
-
-// Second add with same ID
-await collection.addDocument({ _id: 'doc1', data: { v: 2 } });
-// Returns: false (updated existing)
-// Document is updated, not duplicated
-```
-
-#### Getting Encrypted Document Without Key
-```javascript
-// Add encrypted document
-await collection.addDocument(
-  { data: { secret: 'data' } },
-  'encryption-key'
-);
-
-// Try to get without key
-const doc = await collection.getDocument(docId);
-// Returns: false (cannot decrypt)
-
-// Try with wrong key
-const doc2 = await collection.getDocument(docId, 'wrong-key');
-// Returns: false (decryption fails)
-```
-
-#### Deleting Permanent Document
-```javascript
-// Add permanent document
-await collection.addDocument({
-  _permanent: true,
-  data: { important: 'data' }
+const docId = await db.collection('secrets').add(secretData, {
+  encrypted: true,
+  password: 'a-very-strong-password'
 });
 
-// Try normal delete
-const deleted = await collection.deleteDocument(docId);
-// Returns: false (protected)
-
-// Force delete
-const forceDeleted = await collection.deleteDocument(docId, true);
-// Returns: true (deleted)
-```
-
-### Space Management Behaviors
-
-#### Automatic Cleanup Trigger
-```javascript
-const db = new Database('myapp', {
-  sizeLimitKB: 1000,     // 1MB limit
-  bufferLimitKB: -200,   // Start at 800KB
-  freeSpaceEvery: 5000   // Check every 5 seconds
+// You MUST provide the same password to retrieve it
+const retrieved = await db.collection('secrets').get(docId, {
+  password: 'a-very-strong-password'
 });
 
-// When collection.sizeKB > 800KB:
-// - Automatic cleanup triggers
-// - Deletes oldest non-permanent documents
-// - Stops at 1000KB or when all deletable removed
-```
-
-#### Manual Space Freeing
-```javascript
-// Keep only 500KB
-const freed = await collection.freeSpace(500);
-
-// Free 200KB
-const freed = await collection.freeSpace(-200);
-```
-
-### Transaction Behaviors
-
-#### Retry Logic
-- Transactions retry up to 3 times on failure
-- Exponential backoff: 100ms, 200ms, 400ms
-- Includes idempotency tracking to prevent duplicates
-
-#### Concurrent Operations
-```javascript
-// Operations are queued and executed serially
-const promises = [
-  collection.addDocument({ data: { id: 1 } }),
-  collection.addDocument({ data: { id: 2 } }),
-  collection.addDocument({ data: { id: 3 } })
-];
-await Promise.all(promises);
-// Executed in order, prevents race conditions
-```
-
----
-
-## Performance Optimization
-
-### Indexing Strategy
-```javascript
-// Create indexes for frequently queried fields
-await collection.createIndex('data.status');
-await collection.createIndex('data.userId');
-
-// Use indexes in queries
-const results = await collection.query(
-  { status: 'active' },
-  { index: 'data_status' }  // Index name is fieldPath with dots replaced
-);
-```
-
-### Batch Operations Pattern
-```javascript
-// Efficient batch insert
-const documents = generateDocuments(1000);
-const promises = documents.map(doc => 
-  collection.addDocument(doc)
-);
-await Promise.all(promises);
-```
-
-### Memory Management
-```javascript
-// Process large datasets in chunks
-async function* queryInChunks(collection, filter, chunkSize = 100) {
-  let offset = 0;
-  while (true) {
-    const chunk = await collection.query(filter, {
-      limit: chunkSize,
-      offset: offset
-    });
-    if (chunk.length === 0) break;
-    yield chunk;
-    offset += chunkSize;
-  }
-}
-
-// Usage
-for await (const chunk of queryInChunks(collection, {})) {
-  processChunk(chunk);
-}
-```
-
----
-
-## Security Model
+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.
 
-### Encryption Specifications
-- **Algorithm**: AES-GCM 256-bit
-- **Key Derivation**: PBKDF2-SHA-512, 600,000 iterations
-- **Salt**: 16 bytes random
-- **IV**: 12 bytes random
-- **Checksum**: SHA-256 for integrity
-
-### Security Best Practices
-```javascript
-// Use strong passwords
-const strongKey = crypto.randomUUID() + crypto.randomUUID();
-
-// Encrypt sensitive collections
-class SecureCollection {
-  constructor(collection, masterKey) {
-    this.collection = collection;
-    this.masterKey = masterKey;
-  }
-  
-  async add(data) {
-    return this.collection.addDocument(data, this.masterKey);
-  }
-  
-  async get(id) {
-    return this.collection.getDocument(id, this.masterKey);
-  }
-}
-
-// Field-level encryption pattern
-function encryptField(field, key) {
-  // Implement field-specific encryption
-  return encryptedValue;
-}
-
-const doc = {
-  data: {
-    public: 'visible',
-    ssn: encryptField('123-45-6789', fieldKey)
-  }
+// 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
 };
-```
-
----
-
-## Code Examples
-
-### Complete Application Example
-```javascript
-import { Database } from './lacertadb.js';
-
-class TodoApp {
-  async init() {
-    // Initialize database
-    this.db = new Database('todos', {
-      sizeLimitKB: 5000,
-      bufferLimitKB: -1000,
-      freeSpaceEvery: 60000
-    });
-    await this.db.init();
-    
-    // Get or create collection
-    const result = await this.db.getCollection('tasks');
-    if (!result.success) {
-      const createResult = await this.db.createCollection('tasks');
-      this.tasks = createResult.data;
-    } else {
-      this.tasks = result.data;
-    }
-    
-    // Create indexes
-    await this.tasks.createIndex('data.priority');
-    await this.tasks.createIndex('data.dueDate');
-    
-    // Setup observers
-    this.tasks.observer.on('afterAdd', (doc) => {
-      this.updateUI('added', doc);
-    });
-    
-    this.tasks.observer.on('afterDelete', (id) => {
-      this.updateUI('deleted', id);
-    });
-  }
-  
-  async addTask(title, priority, dueDate) {
-    return await this.tasks.addDocument({
-      data: {
-        title,
-        priority,
-        dueDate,
-        completed: false,
-        createdAt: Date.now()
-      }
-    });
-  }
-  
-  async getHighPriorityTasks() {
-    return await this.tasks.query(
-      { priority: 'high' },
-      { 
-        index: 'data_priority',
-        orderBy: 'asc'
-      }
-    );
-  }
-  
-  async getOverdueTasks() {
-    const now = Date.now();
-    const allTasks = await this.tasks.query({}, {
-      index: 'data_dueDate',
-      orderBy: 'asc'
-    });
-    
-    return allTasks.filter(task => 
-      task.data.dueDate < now && !task.data.completed
-    );
-  }
-  
-  async completeTask(taskId) {
-    const task = await this.tasks.getDocument(taskId);
-    if (task) {
-      task.data.completed = true;
-      task.data.completedAt = Date.now();
-      await this.tasks.addDocument(task);
-    }
-  }
-  
-  async cleanup() {
-    await this.db.close();
-  }
-  
-  updateUI(action, data) {
-    console.log(`UI Update: ${action}`, data);
-  }
-}
-
-// Usage
-const app = new TodoApp();
-await app.init();
-await app.addTask('Review PRs', 'high', Date.now() + 86400000);
-const urgent = await app.getHighPriorityTasks();
-```
-
-### Encrypted Notes Application
-```javascript
-class SecureNotes {
-  constructor(password) {
-    this.password = password;
-  }
-  
-  async init() {
-    this.db = new Database('secure_notes');
-    await this.db.init();
-    
-    const result = await this.db.createCollection('notes');
-    this.notes = result.success ? result.data : result.data;
-  }
-  
-  async addNote(title, content, attachments = []) {
-    return await this.notes.addDocument({
-      data: {
-        title,
-        content,
-        tags: [],
-        createdAt: Date.now()
-      },
-      attachments,
-      _permanent: true,
-      _encrypted: true
-    }, this.password);
-  }
-  
-  async getNote(id) {
-    return await this.notes.getDocument(
-      id, 
-      this.password, 
-      true // Include attachments
-    );
-  }
-  
-  async searchNotes(searchTerm) {
-    // Get all notes (encrypted)
-    const allNotes = await this.notes.query(
-      {}, 
-      { encryptionKey: this.password }
-    );
-    
-    // Search in decrypted content
-    return allNotes.filter(note => 
-      note.data.title.includes(searchTerm) ||
-      note.data.content.includes(searchTerm)
-    );
-  }
-}
-```
-
-### Data Migration Pattern
-```javascript
-class DatabaseMigration {
-  static async migrate(fromDb, toDb) {
-    const sourceDb = new Database(fromDb);
-    const targetDb = new Database(toDb);
-    
-    await sourceDb.init();
-    await targetDb.init();
-    
-    // Get all collections
-    for (const collectionName of sourceDb.metadata.getCollectionNames()) {
-      const sourceResult = await sourceDb.getCollection(collectionName);
-      if (!sourceResult.success) continue;
-      
-      const source = sourceResult.data;
-      const targetResult = await targetDb.createCollection(collectionName);
-      const target = targetResult.success ? 
-        targetResult.data : targetResult.data;
-      
-      // Copy all documents
-      const docs = await source.query({});
-      for (const doc of docs) {
-        await target.addDocument(doc);
-      }
-    }
-    
-    await sourceDb.close();
-    await targetDb.close();
-  }
-}
-```
-
----
-
-## Troubleshooting
 
-### Common Issues
+// Add a document with the attachment
+const reportId = await db.collection('reports').add(
+  { title: 'Q3 Report' },
+  { attachments: [attachment] }
+);
 
-#### QuotaExceededError
-```javascript
-// Solution 1: Enable auto-cleanup
-const db = new Database('app', {
-  sizeLimitKB: 5000,
-  freeSpaceEvery: 30000
+// Retrieve the document and its attachments
+const report = await db.collection('reports').get(reportId, {
+  includeAttachments: true
 });
 
-// Solution 2: Manual cleanup
-await collection.freeSpace(1000);
+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."
 
-// Solution 3: Request more quota
-if (navigator.storage?.persist) {
-  await navigator.storage.persist();
-}
-```
-
-#### Encryption Key Lost
-```javascript
-// Implement key recovery
-class KeyManager {
-  static async deriveFromPassword(password, salt) {
-    const encoder = new TextEncoder();
-    const keyMaterial = await crypto.subtle.importKey(
-      'raw',
-      encoder.encode(password),
-      'PBKDF2',
-      false,
-      ['deriveBits']
-    );
-    
-    const keyBits = await crypto.subtle.deriveBits(
-      {
-        name: 'PBKDF2',
-        salt: encoder.encode(salt),
-        iterations: 100000,
-        hash: 'SHA-256'
-      },
-      keyMaterial,
-      256
-    );
-    
-    return btoa(String.fromCharCode(...new Uint8Array(keyBits)));
-  }
-}
-```
-
-#### Performance Degradation
-```javascript
-// Monitor and optimize
-class PerformanceMonitor {
-  static async analyzeCollection(collection) {
-    return {
-      size: collection.sizeKB,
-      documents: collection.length,
-      avgDocSize: collection.sizeKB / collection.length,
-      metadata: collection.documentsMetadata,
-      recommendation: this.getRecommendation(collection)
-    };
-  }
-  
-  static getRecommendation(collection) {
-    if (collection.length > 10000) {
-      return 'Consider sharding';
-    }
-    if (collection.sizeKB / collection.length > 100) {
-      return 'Consider compression';
-    }
-    return 'Optimal';
-  }
-}
-```
+⚙️ Serialization: TurboSerial
+A key performance feature of LacertaDB is its use of turboserial instead of JSON. This provides several advantages:
 
----
+⚡ Speed: turboserial is significantly faster at serializing and deserializing complex JavaScript objects.
 
-## Version History
+📦 Efficiency: It produces a more compact binary output, especially when compression is enabled, saving storage space.
 
-### v1.0.0 - Architecturally Refined
-- Fixed metadata synchronization issues
-- Improved transaction retry logic with idempotency
-- Added observer cleanup to prevent memory leaks
-- Enhanced error handling with LacertaDBResult
-- Added comprehensive edge case handling
+🔬 Type Support: It correctly handles more data types than JSON, including Date, Map, Set, BigInt, and typed arrays.
 
----
+All data stored in localStorage (like metadata) or passed to IndexedDB is processed through turboserial and turbobase64, ensuring top-tier performance.
 
-## License
-MIT License - Copyright (c) 2024 Matias Affolter
+📜 License
+LacertaDB is licensed under the MIT License.