\n\n\n\n```\n\n## How It Works\n\n### Client Side\n- Uses IndexedDB for local storage\n- Queues changes while offline\n- Auto-syncs when connection restores\n- Real-time updates via WebSocket\n- Sync status indicators and event handling\n\n### Server Side\n- PostgreSQL database for persistent storage\n- WebSocket server for real-time communication\n- Handles concurrent updates\n- Broadcasts changes to all connected clients\n\n## Configuration\n\n### Server Config\n```typescript\ninterface ServerConfig {\n port: number;\n pg: {\n connectionString: string; // PostgreSQL connection string\n table: string; // Table name for your data\n };\n softDelete?: {\n enabled: boolean; // Enable soft delete functionality\n fieldName?: string; // Field to store deletion timestamp (default: 'deletedAt')\n permanentDeleteAfter?: number; // Days to keep soft-deleted items\n };\n}\n```\n\n### Client Config\n```typescript\ninterface ClientConfig {\n storage: {\n type: 'indexeddb';\n name: string; // IndexedDB database name\n };\n sync: {\n type: 'websocket';\n url: string; // WebSocket server URL\n };\n clientId: string; // Unique client identifier\n softDelete?: {\n enabled: boolean; // Enable soft delete functionality\n fieldName?: string; // Field to store deletion timestamp (default: 'deletedAt')\n permanentDeleteAfter?: number; // Days to keep soft-deleted items\n };\n}\n```\n\n### Usage Example with Soft Delete\n\n```javascript\n// Initialize with soft delete enabled\nconst db = new ZenoDB({\n storage: {\n type: 'indexeddb',\n name: 'my-app-db'\n },\n sync: {\n type: 'websocket',\n url: 'ws://localhost:3000'\n },\n clientId: 'client-1',\n softDelete: {\n enabled: true,\n fieldName: 'deletedAt',\n permanentDeleteAfter: 30 // Delete after 30 days\n }\n});\n\n// Soft delete an item\nawait db.delete('note-1');\n\n// Restore a soft-deleted item\nawait db.restore('note-1');\n\n// Get all items including soft-deleted ones\nconst allItems = await db.getAll(true);\n\n// Permanently delete an item\nawait db.delete('note-1', true);\n\n// Purge old soft-deleted items\nawait db.purgeDeleted();\n```\n\n## Sync Status & Events\n\nZenoDB provides real-time sync status updates and event handling to help you build responsive UIs that reflect the current sync state of your application.\n\n```typescript\nimport { ZenoDB, SyncEvent, SyncStatus } from 'zeno-db';\n\n// Initialize your database\nconst db = new ZenoDB({\n storage: {\n type: 'indexeddb',\n name: 'my-app-db'\n },\n sync: {\n type: 'websocket',\n url: 'ws://localhost:3000'\n },\n softDelete: {\n enabled: true,\n fieldName: 'deletedAt',\n permanentDeleteAfter: 30 // Delete after 30 days\n }\n});\n\n// Subscribe to sync events\ndb.subscribe((event: SyncEvent) => {\n const { type, status } = event;\n \n // status contains:\n // - isOnline: boolean (connection status)\n // - isSyncing: boolean (whether sync is in progress)\n // - syncProgress: number (0-100 percentage)\n // - pendingChangesCount: number (changes waiting to sync)\n \n switch(type) {\n case 'connection_change':\n updateConnectionUI(status.isOnline);\n break;\n case 'sync_started':\n showSyncStarted();\n break;\n case 'sync_progress':\n updateProgressBar(status.syncProgress);\n break;\n case 'sync_completed':\n showSyncComplete();\n break;\n }\n});\n\n// Get current status at any time\nconst currentStatus: SyncStatus = db.getSyncStatus();\n```\n\n#### Sync Event Types\n- `connection_change`: Fired when connection status changes (online/offline)\n- `sync_started`: Fired when sync operation begins\n- `sync_progress`: Fired during sync with progress updates\n- `sync_completed`: Fired when sync operation completes\n\n#### Sync Status Properties\n- `isOnline`: Current connection status\n- `isSyncing`: Whether a sync operation is in progress\n- `syncProgress`: Progress percentage (0-100)\n- `pendingChangesCount`: Number of changes waiting to sync\n\n## Best Practices\n\n1. Always initialize before use:\n```javascript\nawait db.init();\n```\n\n2. Handle offline/online transitions gracefully:\n```javascript\nwindow.addEventListener('online', () => {\n console.log('Back online, syncing...');\n});\n```\n\n3. Use try-catch for error handling:\n```javascript\ntry {\n await db.set('key', value);\n} catch (error) {\n console.error('Error saving data:', error);\n}\n```\n\n4. Monitor sync status:\n```javascript\ndb.subscribe((event) => {\n const { type, status } = event;\n // Update UI based on sync status.\n});\n```\n\n5. Use soft delete for important data:\n```javascript\n// Instead of permanent deletion\nawait db.delete('important-data');\n\n// Later, if needed\nawait db.restore('important-data');\n\n// Clean up old deleted items periodically\nawait db.purgeDeleted();\n```\n\n## Schema Migrations & Conflict Resolution\n\n### Client-side Migration Example\n\nWhen evolving your data schema, you may need to migrate existing records. For example, if you add a new field to your notes, you can write a migration function that updates all records after initializing the database:\n\n```js\n// Example: Migrating notes to add a \"tags\" field if missing\nasync function migrateNotes(db) {\n const allNotes = await db.getAll();\n for (const note of allNotes) {\n if (!note.tags) {\n note.tags = [];\n await db.set(note.id, note); // Save migrated note\n }\n }\n}\n\n// Run migration after db.init()\nawait db.init();\nawait migrateNotes(db);\n```\n*Tip: Store a schema version in each record or in IndexedDB metadata, and only run migrations when needed.*\n\n### Application-level Merging Example\n\nFor collaborative or complex data structures, you may need to merge changes from multiple sources. Here is a simple example for merging two versions of a collaborative list:\n\n```js\n// Example: Merging two versions of a collaborative list\nfunction mergeLists(localList, remoteList) {\n const merged = [...localList];\n for (const item of remoteList) {\n if (!merged.find(i => i.id === item.id)) {\n merged.push(item); // Add new items from remote\n }\n // Optionally, resolve conflicts for items with the same id\n }\n return merged;\n}\n\n// Usage in sync event handler\n// (Assuming your sync system emits a 'sync_conflict' event)\ndb.subscribe((event) => {\n if (event.type === 'sync_conflict') {\n const merged = mergeLists(event.local, event.remote);\n db.set(event.key, merged);\n }\n});\n```\n*Tip: For more complex data, consider using libraries like Automerge or Yjs for CRDT-based merging.*\n\n## PostgreSQL Table Structure\n\nYour PostgreSQL table should have this structure:\n```sql\nCREATE TABLE notes (\n id TEXT PRIMARY KEY,\n data JSONB NOT NULL,\n deleted_at TIMESTAMP WITH TIME ZONE,\n created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,\n updated_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP\n);\n\n-- Index for soft delete queries\nCREATE INDEX idx_notes_deleted_at ON notes(deleted_at);\n```\n\n## License\n\nMIT License - see LICENSE file for details.\n\n## TODO List & Roadmap\n\n### Authentication & Security 🔐\n- [ ] User authentication system integration\n- [ ] JWT-based authentication\n- [ ] Role-based access control (RBAC)\n- [ ] API rate limiting\n- [ ] Data encryption at rest\n- [ ] Session management\n- [ ] OAuth2 provider integration (Google, GitHub)\n\n### Data Management 📊\n- [ ] Data versioning\n- [ ] Soft delete functionality\n- [ ] Data validation middleware\n- [ ] Advanced conflict resolution strategies\n- [ ] Bulk import/export functionality\n\n### Performance Optimizations ⚡\n- [ ] Data compression\n- [ ] Caching layer\n- [ ] Request batching\n- [ ] Lazy loading support\n- [ ] Connection pooling\n- [ ] Query optimization\n\n### Developer Experience 🛠️\n- [ ] CLI tool for database management\n- [ ] Better error handling and logging\n- [ ] Development environment tooling\n- [ ] TypeScript type definitions\n- [ ] API documentation with Swagger/OpenAPI\n- [ ] Integration tests\n- [ ] E2E testing suite\n\n### Monitoring & Debugging 📈\n- [ ] Telemetry integration\n- [ ] Performance metrics dashboard\n- [ ] Debug logging\n- [ ] Error tracking integration\n- [ ] Health check endpoints\n- [ ] Audit logging\n\n### Infrastructure 🏗️\n- [ ] Docker containerization\n- [ ] CI/CD pipeline setup\n- [ ] Automated deployment scripts\n- [ ] Database migration tools\n- [ ] Backup and restore functionality\n- [ ] High availability setup\n\n## Troubleshooting\n\n### Common Issues\n\n1. **Connection Issues**\n ```javascript\n // Check if WebSocket server is running\n const ws = new WebSocket('ws://localhost:3000');\n ws.onerror = (error) => {\n console.error('WebSocket connection error:', error);\n };\n ```\n\n2. **Database Initialization Failures**\n ```javascript\n try {\n await db.init();\n } catch (error) {\n console.error('Database initialization failed:', error);\n // Check if IndexedDB is supported\n if (!window.indexedDB) {\n console.error('IndexedDB is not supported in this browser');\n }\n }\n ```\n\n3. **Sync Status Not Updating**\n - Ensure you're properly subscribing to sync events\n - Check network connectivity\n - Verify WebSocket connection is active\n\n### Debugging Tips\n\n1. Enable verbose logging:\n ```javascript\n const db = new ZenoDB({\n // ... config\n debug: true\n });\n ```\n\n2. Monitor sync events:\n ```javascript\n db.subscribe((event) => {\n console.log('Sync event:', event);\n });\n ```\n","readmeFilename":"README.md"}
![\"ZenoDB](\"https://i.ibb.co/67ktWMm0/zenodb.png\")
\n\n