{"id":31802957,"url":"https://github.com/smithg09/zenithdb","last_synced_at":"2025-10-19T10:28:47.065Z","repository":{"id":313620040,"uuid":"1030899886","full_name":"smithg09/zenithdb","owner":"smithg09","description":"A framework-agnostic, local-first state and sync engine. Powerful IndexedDB wrapper provides reactive subscriptions, offline-first syncing, and type-safe queries.","archived":false,"fork":false,"pushed_at":"2025-08-06T16:33:55.000Z","size":365,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-01T06:26:43.032Z","etag":null,"topics":["autosync","indexeddb","reactivity"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/smithg09.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-02T15:14:15.000Z","updated_at":"2025-08-16T17:28:00.000Z","dependencies_parsed_at":"2025-09-07T11:49:27.693Z","dependency_job_id":"189ca5e6-e204-4be9-bf5a-c6a9d18e8b76","html_url":"https://github.com/smithg09/zenithdb","commit_stats":null,"previous_names":["smithg09/zenithdb"],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/smithg09/zenithdb","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smithg09%2Fzenithdb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smithg09%2Fzenithdb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smithg09%2Fzenithdb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smithg09%2Fzenithdb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/smithg09","download_url":"https://codeload.github.com/smithg09/zenithdb/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smithg09%2Fzenithdb/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278909712,"owners_count":26066888,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-08T02:00:06.501Z","response_time":56,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["autosync","indexeddb","reactivity"],"created_at":"2025-10-11T01:00:06.410Z","updated_at":"2025-10-11T01:00:07.675Z","avatar_url":"https://github.com/smithg09.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ZenithDB\n\nA framework-agnostic, local-first state and sync engine that provides a powerful wrapper around IndexedDB with advanced features like reactive subscriptions, offline-first sync, and type-safe queries.\n\n## Key Features\n\n- 🗄️ **Enhanced IndexedDB**: A powerful wrapper around IndexedDB with a clean, intuitive API\n- 🔄 **Offline-First**: Built-in sync engine with conflict resolution and offline queue management\n- ⚡ **Type-Safe**: Full TypeScript support with schema definition and query inference\n- 🔌 **Framework-Agnostic**: Works with React, Vue, Svelte, or vanilla JavaScript\n- 📱 **Reactive**: Observable subscriptions for real-time UI updates\n- 🎯 **Fluent Queries**: Chainable query API with support for complex operations\n- 🚀 **Sync Engine**: Built-in bidirectional synchronization with retry logic and exponential backoff\n- 🔧 **Pluggable**: Adapter-based architecture supporting indexedDB and more in the future (WebSQL/SQLlite)\n- 🛡️ **Validation**: Runtime schema validation with custom error messages\n\n## Packages\n\n- **[@zenithdb/core](./packages/core)** - Core database engine with schema definition and queries\n- **[@zenithdb/storage](./packages/storage)** - Storage adapters (IndexedDB, and future SQL/SQLite)\n- **[@zenithdb/sync](./packages/sync)** - Backend-agnostic sync engine with offline support\n- **[@zenithdb/types](./packages/types)** - TypeScript type definitions\n- **[@zenithdb/utils](./packages/utils)** - Utility functions and helpers\n- **[@zenithdb/kit](./packages/kit)** - Meta-package that installs everything you need\n\n## Documentation\n\n- [Core Package](./packages/core/README.md) - Database engine documentation\n- [Storage Package](./packages/storage/README.md) - Storage adapters documentation\n- [Sync Package](./packages/sync/README.md) - Sync engine documentation\n\n## Installation\n\n### NPM\n\n```bash\n# Complete package (recommended)\nnpm install @zenithdb/kit\n\n# Or install individual packages\nnpm install @zenithdb/core @zenithdb/storage @zenithdb/sync @zenithdb/types\n```\n\n\u003e **Note**: The `@zenithdb/kit` package installs everything you need to get started with Zenith, including core functionality, storage adapters, and sync engine.\n\n## Quick Start\n\n```typescript\nimport { createDatabase, createSchema, fields } from \"@zenithdb/core\";\nimport { IndexedDBAdapter } from \"@zenithdb/storage\";\nimport { ZenithSyncEngine } from \"@zenithdb/sync\";\n\n// Define your schema\nconst schema = createSchema({\n  name: \"MyApp\",\n  version: 1,\n  tables: {\n    users: {\n      primaryKey: \"id\",\n      schema: {\n        id: fields.string({ required: true }),\n        name: fields.string({ required: true }),\n        email: fields.string({ unique: true }),\n        createdAt: fields.timestamp({ defaultValue: () =\u003e Date.now() }),\n      },\n    },\n  },\n  adapter: \"indexeddb\",\n});\n\n// Create database\nconst db = await createDatabase(schema);\n\n// Create a user\nconst user = await db.users.add({\n  id: \"user-1\",\n  name: \"John Doe\",\n  email: \"john@example.com\",\n});\n\n// Query with fluent API\nconst users = await db.users\n  .where(\"name\")\n  .contains(\"John\")\n  .sortBy(\"createdAt\", \"desc\")\n  .limit(10)\n  .toArray();\n\n// Subscribe to changes\ndb.users.subscribe((users) =\u003e {\n  console.log(\"Users updated:\", users);\n});\n\n// Set up sync engine (optional)\nconst syncEngine = new ZenithSyncEngine(transport, adapter, {\n  conflictResolution: \"server-wins\",\n  autoSyncInterval: 30000,\n});\n\nawait syncEngine.start();\n```\n\n## Sync Integration\n\n### Basic Sync Integration\n\n```typescript\nimport { createDatabase, createSchema, fields } from \"@zenithdb/core\";\nimport { createRestTransport } from \"@zenithdb/sync\";\n\nconst transport = createRestTransport({\n  baseUrl: \"https://api.yourapp.com\",\n  endpoints: {\n    push: \"/sync/push\",\n    pull: \"/sync/pull\",\n  },\n  headers: {\n    Authorization: \"Bearer your-token\",\n  },\n});\n\n// Create sync-enabled database schema\nconst schema = createSchema({\n  name: \"SyncIntegrationTest\",\n  version: 1,\n  tables: {\n    users: {\n      primaryKey: \"id\",\n      schema: {\n        id: fields.string({ required: true }),\n        name: fields.string({ required: true }),\n        email: fields.string({ required: true }),\n        createdAt: fields.timestamp({ defaultValue: () =\u003e Date.now() }),\n        updatedAt: fields.timestamp({ defaultValue: () =\u003e Date.now() }),\n      },\n      indexes: [{ name: \"email\", field: \"email\", unique: true }],\n    },\n  },\n  sync: {\n    transport,\n    config: {\n      conflictResolution: \"server-wins\",\n      autoSyncInterval: 5000,\n      batchSize: 10,\n      immediateSync: true,\n      immediateSyncDebounce: 100,\n    },\n    autoStart: false,\n  },\n});\n\n// Create and use sync-enabled database\nconst db = await createDatabase(schema);\n\n// Start sync engine\nawait db.startSync();\n\n// Perform operations that will be automatically synced\nconst user = await db.users.add({\n  id: \"user-1\",\n  name: \"John Doe\",\n  email: \"john@example.com\",\n});\n\n// Update operation\nawait db.users.update(\"user-1\", { name: \"John Smith\" });\n\n// Manual sync trigger\nawait db.syncNow();\n\n// Check sync status\nconst status = db.getSyncStatus();\nconsole.log(\"Sync status:\", status);\n```\n\n### Table-Level Sync Control\n\n```typescript\nimport { createDatabase, createSchema, fields } from \"@zenithdb/core\";\nimport { createGraphQLTransport } from \"@zenithdb/sync\";\n\nconst graphqlTransport = createGraphQLTransport({\n  endpoint: \"https://api.example.com/graphql\",\n  headers: {\n    Authorization: \"Bearer token\",\n  },\n  mutations: {\n    pushData: `\n      mutation SyncPush($operations: [SyncOperationInput!]!) {\n        syncPush(operations: $operations) {\n          success\n          conflicts { id table localValue remoteValue }\n        }\n      }\n    `,\n  },\n  queries: {\n    pullData: `\n      query SyncPull($lastSync: DateTime) {\n        syncPull(since: $lastSync) {\n          operations { id table data timestamp }\n          cursor\n        }\n      }\n    `,\n  },\n});\n\n// Create schema with table-specific sync settings\nconst schema = createSchema({\n  name: \"TableSyncControlTest\",\n  version: 1,\n  tables: {\n    users: {\n      primaryKey: \"id\",\n      schema: {\n        id: fields.string({ required: true }),\n        name: fields.string({ required: true }),\n        email: fields.string({ required: true }),\n        createdAt: fields.timestamp({ defaultValue: () =\u003e Date.now() }),\n      },\n    },\n    posts: {\n      primaryKey: \"id\",\n      schema: {\n        id: fields.string({ required: true }),\n        title: fields.string({ required: true }),\n        content: fields.string({ required: true }),\n        authorId: fields.string({ required: true }),\n        published: fields.boolean({ defaultValue: false }),\n        createdAt: fields.timestamp({ defaultValue: () =\u003e Date.now() }),\n      },\n    },\n  },\n  sync: {\n    transport: graphqlTransport,\n    config: {\n      conflictResolution: \"server-wins\",\n      autoSyncInterval: 5000,\n    },\n    tableSettings: {\n      users: {\n        enabled: true,\n        autoSync: true,\n        syncDirection: \"bidirectional\", // Can sync both ways\n      },\n      posts: {\n        enabled: true,\n        autoSync: true,\n        syncDirection: \"push-only\", // Only push to server\n      },\n    },\n    autoStart: true,\n  },\n});\n\nconst db = await createDatabase(schema);\n\n// Operations on different tables with different sync behaviors\nawait db.users.add({\n  id: \"user-1\",\n  name: \"Bob\",\n  email: \"bob@example.com\",\n});\n\nawait db.posts.add({\n  id: \"post-1\",\n  title: \"Test Post\",\n  content: \"This is a test post\",\n  authorId: \"user-1\",\n});\n\n// Both operations will be synced according to their table settings\n```\n\n## Performance Tips\n\n1. **Use Indexes**: Define indexes on frequently queried fields\n2. **Batch Operations**: Use `bulkAdd()` for multiple records\n3. **Subscribe Wisely**: Unsubscribe from unused subscriptions\n4. **Transaction Scope**: Keep transactions as small as possible\n5. **Query Optimization**: Use specific queries instead of filtering large datasets\n\n## Contributing\n\nWe welcome contributions! Please see our [contributing guidelines](./CONTRIBUTING.md) for details.\n\n### Development Setup\n\n```bash\n# Clone the repository\ngit clone https://github.com/smithg09/zenithdb.git\ncd zenithdb\n\n# Install dependencies\npnpm install\n\n# Instll types\npnpm build --filter=@zenithdb/types\n\n# Build all packages\npnpm build\n\n# Start development mode\npnpm dev\n```\n\n### Monorepo Structure\n\nThis project uses a monorepo structure with multiple packages:\n\n- Each package has its own `package.json` and build configuration\n- Shared TypeScript configuration and build tools\n- Turborepo for efficient task running\n- Changesets for version management and publishing\n\n## License\n\nMIT © [Smith Gajjar](https://www.smithgajjar.dev)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsmithg09%2Fzenithdb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsmithg09%2Fzenithdb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsmithg09%2Fzenithdb/lists"}