{"id":31564255,"url":"https://github.com/anivar/amplify-watermelondb-adapter","last_synced_at":"2026-04-27T16:00:41.453Z","repository":{"id":316643118,"uuid":"1064237845","full_name":"anivar/amplify-watermelondb-adapter","owner":"anivar","description":"WatermelonDB storage adapter for AWS Amplify DataStore — reactive queries, JSI-native performance on React Native, cross-platform (web, Node.js, in-memory fallback)","archived":false,"fork":false,"pushed_at":"2026-04-25T08:24:09.000Z","size":144,"stargazers_count":1,"open_issues_count":3,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-25T10:20:18.139Z","etag":null,"topics":["aws-amplify","datastore","graphql","jsi","offline-first","react-native","reactive-database","sqlite","typescript","watermelondb"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/amplify-watermelondb-adapter","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/anivar.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","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-09-25T18:33:46.000Z","updated_at":"2026-04-25T08:20:57.000Z","dependencies_parsed_at":"2025-09-25T21:26:58.147Z","dependency_job_id":null,"html_url":"https://github.com/anivar/amplify-watermelondb-adapter","commit_stats":null,"previous_names":["anivar/amplify-watermelondb-adapter"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/anivar/amplify-watermelondb-adapter","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anivar%2Famplify-watermelondb-adapter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anivar%2Famplify-watermelondb-adapter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anivar%2Famplify-watermelondb-adapter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anivar%2Famplify-watermelondb-adapter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/anivar","download_url":"https://codeload.github.com/anivar/amplify-watermelondb-adapter/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anivar%2Famplify-watermelondb-adapter/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32343571,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-26T23:26:28.701Z","status":"online","status_checked_at":"2026-04-27T02:00:06.769Z","response_time":128,"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":["aws-amplify","datastore","graphql","jsi","offline-first","react-native","reactive-database","sqlite","typescript","watermelondb"],"created_at":"2025-10-05T05:03:24.122Z","updated_at":"2026-04-27T16:00:41.438Z","avatar_url":"https://github.com/anivar.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🍉⚡ amplify-watermelondb-adapter\n\n[![npm version](https://img.shields.io/npm/v/amplify-watermelondb-adapter.svg)](https://www.npmjs.com/package/amplify-watermelondb-adapter)\n[![npm downloads](https://img.shields.io/npm/dm/amplify-watermelondb-adapter.svg)](https://www.npmjs.com/package/amplify-watermelondb-adapter)\n[![CI](https://github.com/anivar/amplify-watermelondb-adapter/actions/workflows/ci.yml/badge.svg)](https://github.com/anivar/amplify-watermelondb-adapter/actions/workflows/ci.yml)\n[![Provenance](https://img.shields.io/badge/npm-provenance-success?logo=npm)](https://docs.npmjs.com/generating-provenance-statements)\n[![npm bundle size](https://img.shields.io/bundlephobia/minzip/amplify-watermelondb-adapter)](https://bundlephobia.com/package/amplify-watermelondb-adapter)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)\n[![Node.js Version](https://img.shields.io/node/v/amplify-watermelondb-adapter.svg)](https://nodejs.org)\n[![React Native](https://img.shields.io/badge/React%20Native-%3E%3D0.76.0-blue.svg)](https://reactnative.dev/)\n[![Amplify DataStore](https://img.shields.io/badge/Amplify%20DataStore-4.x%20%7C%205.x-orange.svg)](https://docs.amplify.aws/lib/datastore/getting-started/)\n[![WatermelonDB](https://img.shields.io/badge/WatermelonDB-%3E%3D0.27.0-green.svg)](https://github.com/Nozbe/WatermelonDB)\n[![GitHub](https://img.shields.io/github/stars/anivar/amplify-watermelondb-adapter?style=social)](https://github.com/anivar/amplify-watermelondb-adapter)\n\n**A WatermelonDB adapter for AWS Amplify DataStore**\n\n\u003e This adapter integrates WatermelonDB as a storage adapter for AWS Amplify DataStore, providing an alternative to the default SQLite adapter.\n\n## 🎯 Overview\n\n### About AWS Amplify DataStore\n\nAWS Amplify DataStore provides a programming model for leveraging shared and distributed data:\n- 🔄 **Automatic sync** between cloud and local data\n- 🔐 **Built-in auth** and conflict resolution\n- 📊 **GraphQL API** integration\n- 🌐 **Cross-platform** support - Web, React Native, iOS, Android\n\n### About WatermelonDB\n\nWatermelonDB is a reactive database framework built for React and React Native applications:\n- 😎 **Lazy loading** - Records load on demand\n- ⚡ **Native SQLite** performance with JSI on React Native\n- ✨ **Fully reactive** - UI updates automatically when data changes\n- 📈 **Designed for scale** - Handles large datasets efficiently\n\n### Integration\n\nThis adapter allows you to use WatermelonDB as the storage engine for Amplify DataStore:\n\n```typescript\n// Standard DataStore setup\nimport { DataStore } from '@aws-amplify/datastore';\nimport { SQLiteAdapter } from '@aws-amplify/datastore-storage-adapter';\n\nDataStore.configure({\n  storageAdapter: SQLiteAdapter\n});\n\n// With WatermelonDB adapter\nimport { WatermelonDBAdapter } from 'amplify-watermelondb-adapter';\n\nDataStore.configure({\n  storageAdapter: new WatermelonDBAdapter()\n});\n```\n\n## 🚀 Platform Support\n\nThe adapter automatically selects the optimal storage engine for each platform:\n\n| Platform | Storage Engine | Features |\n|----------|----------------|----------|\n| **React Native iOS/Android** | JSI + SQLite | Native performance with JSI bridge |\n| **Web** | LokiJS + IndexedDB | Browser-optimized with IndexedDB persistence |\n| **Node.js** | better-sqlite3 | Server-grade SQLite performance |\n| **Fallback** | In-Memory | Full CRUD with reactive queries, automatic when native adapters unavailable |\n\n## 💡 Use Cases\n\nThis adapter is suitable for applications that:\n- 📱 Use **DataStore** for offline-first functionality\n- 📈 Work with **large datasets** or complex queries\n- ⚡ Need **reactive UI updates** when data changes\n- 🔄 Want **WatermelonDB's performance** benefits\n- 🏗️ Require **cross-platform** compatibility\n\n## 🛠️ Installation\n\n```bash\nnpm install amplify-watermelondb-adapter @nozbe/watermelondb\n# or\nyarn add amplify-watermelondb-adapter @nozbe/watermelondb\n```\n\n## 🎯 Quick Start\n\n### Zero Configuration Setup\n\n```typescript\nimport { configureDataStoreWithWatermelonDB } from 'amplify-watermelondb-adapter';\n\n// That's it! DataStore now uses WatermelonDB\nconfigureDataStoreWithWatermelonDB();\n\n// Use DataStore as normal - but faster!\nconst todos = await DataStore.query(Todo);\n```\n\n### Migration from Existing Apps\n\nAlready using DataStore? Migration takes 2 minutes:\n\n```typescript\nimport { createFallbackConfiguration } from 'amplify-watermelondb-adapter';\nimport { SQLiteAdapter } from '@aws-amplify/datastore-storage-adapter';\n\n// Your existing configuration\nconst config = {\n  authProviders: { /* your auth */ },\n  syncExpressions: [ /* your rules */ ]\n};\n\n// Automatic upgrade with fallback safety net\ncreateFallbackConfiguration(\n  config,\n  SQLiteAdapter, // Falls back if needed\n  { enableDebugLogging: true }\n);\n```\n\n## 🔥 Advanced Features\n\n### 🏢 Multi-Tenant Support\n\nIntegrates subscription variables from [Amplify PR #14564](https://github.com/aws-amplify/amplify-js/pull/14564) for multi-tenant GraphQL filtering.\n\n```typescript\nimport { WatermelonDBAdapter } from 'amplify-watermelondb-adapter';\n\nconst adapter = new WatermelonDBAdapter();\n\n// Configure subscription variables for multi-tenant filtering\nadapter.setSubscriptionVariables({\n  tenantId: 'tenant-456',\n  userId: 'user-789'\n});\n\n// Dynamic schema switching\nadapter.setAlternativeSchema(alternativeSchema, () =\u003e {\n  // Your logic to determine which schema to use\n  return shouldUseAlternative() ? 'alternative' : 'primary';\n});\n```\n\n### 📡 WebSocket Health Monitoring\n\nImplements connection health monitoring from [Amplify PR #14563](https://github.com/aws-amplify/amplify-js/pull/14563) with auto-reconnection capabilities.\n\n```typescript\n// Monitor WebSocket connection health\nadapter.startWebSocketHealthMonitoring({\n  interval: 30000, // 30 seconds\n  onHealthCheck: (isHealthy) =\u003e {\n    console.log(`WebSocket health: ${isHealthy ? '✅' : '❌'}`);\n  },\n  onReconnect: () =\u003e {\n    console.log('Attempting WebSocket reconnection...');\n  }\n});\n\n// Track keep-alive timestamps for debugging\nadapter.trackKeepAlive(); // Stores in AsyncStorage\n```\n\n### 📊 Performance Monitoring\n\n```typescript\nimport { getWatermelonDBMetrics, isWatermelonDBAdapterActive } from 'amplify-watermelondb-adapter';\n\n// Check if adapter is active\nconsole.log(`Active: ${isWatermelonDBAdapterActive()}`); // true\n\n// Monitor your performance gains\nconst metrics = getWatermelonDBMetrics();\nif (metrics) {\n  console.log(`Active: ${metrics.isActive}`);             // true\n  console.log(`Dispatcher: ${metrics.dispatcherType}`);    // \"jsi\" on RN, \"lokijs\" on web\n  console.log(`Schema version: ${metrics.schemaVersion}`); // 1\n}\n```\n\n### 🎛️ Fine-Tuning\n\n```typescript\nnew WatermelonDBAdapter({\n  // Optimize for your use case\n  cacheMaxSize: 500,        // More cache for read-heavy apps\n  cacheTTL: 60 * 60 * 1000, // 1 hour for stable data\n  batchSize: 5000,          // Larger batches for bulk imports\n  conflictStrategy: 'ACCEPT_REMOTE' // Your sync strategy\n});\n```\n\n### 🔍 Enhanced Query Operators\n\nSupports 'in' and 'notIn' operators from [Amplify PR #14544](https://github.com/aws-amplify/amplify-js/pull/14544) for advanced filtering.\n\n```typescript\n// Query with 'in' operator\nconst priorityTasks = await DataStore.query(Todo, todo =\u003e\n  todo.priority.in([1, 2, 3])\n);\n\n// Query with 'notIn' operator\nconst nonUrgentTasks = await DataStore.query(Todo, todo =\u003e\n  todo.status.notIn(['urgent', 'critical'])\n);\n```\n\n### 🔄 Reactive Queries\n\n```typescript\n// WatermelonDB's magic: truly reactive queries\nDataStore.observe(Todo).subscribe(msg =\u003e {\n  // Component auto-updates when ANY todo changes\n  // Even from different screens or background sync!\n});\n```\n\n## ✨ Features\n\n### Core Features\n- **🍉 WatermelonDB Integration** - Seamlessly integrates with WatermelonDB's reactive architecture\n- **🔌 Drop-in replacement** - Minimal configuration changes required\n- **📚 Full TypeScript** - Complete type safety and IntelliSense\n- **🔄 Automatic fallback** - Falls back to in-memory storage if initialization fails\n- **⚙️ Configurable** - Customizable cache, batch size, and conflict resolution\n- **🛠️ Development-friendly** - Comprehensive error handling and debugging support\n- **🍉 JSI Performance** - Leverages WatermelonDB's JSI dispatcher on React Native\n- **🚀 Cross-platform** - Works on iOS, Android, Web, and Node.js\n- **💾 Smart Caching** - Built-in LRU cache with configurable TTL\n\n### 🆕 Latest Features\n- **🏢 Multi-Tenant Support** - Dynamic schema switching for multi-tenant applications\n- **📡 Subscription Variables** - Filter GraphQL subscriptions per tenant/user ([Amplify PR #14564](https://github.com/aws-amplify/amplify-js/pull/14564))\n- **🔌 WebSocket Health Monitoring** - Auto-reconnection with health checks ([Amplify PR #14563](https://github.com/aws-amplify/amplify-js/pull/14563))\n- **📝 Keep-Alive Tracking** - Debug connection issues with AsyncStorage timestamps\n- **🔍 Enhanced Operators** - Full support for 'in' and 'notIn' query operators ([Amplify PR #14544](https://github.com/aws-amplify/amplify-js/pull/14544))\n\n## 🎓 Examples\n\n### 🍉 E-commerce App\n```typescript\n// Query products with WatermelonDB's reactive performance\nconst products = await DataStore.query(Product,\n  p =\u003e p.inStock.eq(true),\n  { limit: 1000 }\n);\n```\n\n### 🍉 Chat Application\n```typescript\n// Real-time messaging with reactive updates\nDataStore.observe(Message, m =\u003e\n  m.conversationId.eq(currentChat)\n).subscribe(update =\u003e {\n  // UI updates automatically when data changes\n});\n```\n\n\n## 📊 Technical Specifications\n\nAdapter performance characteristics from automated tests:\n\n```\n🍉 WatermelonDB Adapter Performance Metrics\n==========================================\n\nOperation                 | Average Time\n--------------------------|-------------\nAdapter Creation          | 0.03ms\nConfig Validation         | 0.05ms\nDispatcher Detection      | 0.01ms\nSchema Version Lookup     | 0.02ms\nMemory (1000 instances)   | 2.65MB\nConcurrent Creation       | 500 adapters in 0.96ms\n```\n\n## 🔗 Compatibility\n\nCompatible with:\n- 🍉 **AWS Amplify DataStore** - v4.x and v5.x\n- 🍉 **GraphQL subscriptions** - Full support\n- 🍉 **Multi-auth rules** - All authentication strategies\n- 🍉 **Conflict resolution** - Version-based and custom strategies\n- 🍉 **Schema migrations** - Automatic schema handling\n- 🍉 **DataStore Selective Sync** - Predicate-based syncing\n\n## 📦 What's Included\n\n- 🍉 **WatermelonDBAdapter** - Core adapter implementation\n- 🔧 **Integration helpers** - Easy setup utilities\n- 📊 **Performance monitoring** - Metrics collection\n- 🔄 **Migration tools** - Upgrade from SQLiteAdapter\n- 📚 **TypeScript definitions** - Full type safety\n- 🎯 **Examples** - Real-world usage patterns\n\n## 🚦 Getting Started\n\n1. **🍉 Install the package**\n   ```bash\n   npm install amplify-watermelondb-adapter @nozbe/watermelondb\n   ```\n\n2. **🍉 Configure DataStore**\n   ```typescript\n   import { configureDataStoreWithWatermelonDB } from 'amplify-watermelondb-adapter';\n   configureDataStoreWithWatermelonDB();\n   ```\n\n3. **🍉 Start using DataStore** - Same API, WatermelonDB performance!\n\n## 📋 API Reference\n\n### New Methods\n\n| Method | Description |\n|--------|-------------|\n| `setSubscriptionVariables(vars)` | Set GraphQL subscription filtering variables for multi-tenant support |\n| `getSubscriptionVariables()` | Get current subscription variables |\n| `setAlternativeSchema(schema, selector)` | Configure alternative schema for runtime switching |\n| `startWebSocketHealthMonitoring(options)` | Start monitoring WebSocket connection health |\n| `stopWebSocketHealthMonitoring()` | Stop WebSocket health monitoring |\n| `trackKeepAlive()` | Store keep-alive timestamp in AsyncStorage |\n\n### Core Methods\n\n| Method | Description |\n|--------|-------------|\n| `setup(schema, ...)` | Initialize adapter with DataStore schema |\n| `query(model, predicate, pagination)` | Query records with optional filtering |\n| `save(model, condition)` | Save or update a model instance |\n| `delete(model, condition)` | Delete model(s) |\n| `observe(model, predicate)` | Subscribe to real-time changes |\n| `batchSave(model, items)` | Efficiently save multiple items |\n\n## 📖 Documentation\n\n- [API Reference](https://github.com/anivar/amplify-watermelondb-adapter/wiki)\n- [Migration Guide](https://github.com/anivar/amplify-watermelondb-adapter/wiki/Migration)\n- [Performance Tuning](https://github.com/anivar/amplify-watermelondb-adapter/wiki/Performance)\n- [Examples](./examples)\n\n## 🤔 FAQ\n\n**Q: Is this production-ready?**\nA: Yes! The adapter has 105 tests covering CRUD, predicates, conflict resolution, observables, and full Amplify DataStore interface compatibility.\n\n**Q: Does it support all DataStore features?**\nA: Yes! The adapter implements the complete DataStore storage interface.\n\n**Q: What if WatermelonDB fails to initialize?**\nA: The adapter automatically falls back to a production-grade in-memory storage with full CRUD, predicate queries, sorting, pagination, and reactive observe support.\n\n**Q: What platforms are supported?**\nA: iOS, Android, Web, and Node.js with automatic platform detection.\n\n## 🛟 Support\n\n- 🐛 [Report Issues](https://github.com/anivar/amplify-watermelondb-adapter/issues)\n- 💬 [Discussions](https://github.com/anivar/amplify-watermelondb-adapter/discussions)\n- 📖 [Stack Overflow](https://stackoverflow.com/questions/tagged/amplify-watermelondb)\n\n## 🙏 Acknowledgments\n\n- 🍉 [AWS Amplify](https://aws.amazon.com/amplify/) - For the DataStore framework\n- 🍉 [WatermelonDB](https://github.com/Nozbe/WatermelonDB) - For the reactive database architecture\n- 🍉 [React Native](https://reactnative.dev/) - For cross-platform mobile development\n\n## 📄 License\n\nMIT License - See [LICENSE](LICENSE) file for details.\n\n---\n\n\u003cp align=\"center\"\u003e\n  🍉 Built with WatermelonDB's reactive performance for Amplify DataStore 🍉\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cb\u003eBringing WatermelonDB's ⚡ performance to AWS Amplify DataStore 🍉\u003c/b\u003e\n\u003c/p\u003e","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fanivar%2Famplify-watermelondb-adapter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fanivar%2Famplify-watermelondb-adapter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fanivar%2Famplify-watermelondb-adapter/lists"}