@omnistreamai/data-core
Version:
178 lines (134 loc) • 5.16 kB
Markdown
---
name: initialize-sync-system
description: >
Set up the data-sync system. Use createSyncManager, createStore, initStore in
the correct order. Configure IndexedDBAdapter version for schema changes.
Pass localAdapter and remoteAdapter to SyncManager. Call setService on
WebDAVAdapter before any operations.
type: core
library: '@omnistreamai/data-sync'
library_version: '0.4.1'
sources:
- 'omni-stream-ai/data-sync:packages/core/src/sync-manager.ts'
- 'omni-stream-ai/data-sync:packages/core/src/store.ts'
- 'omni-stream-ai/data-sync:packages/adapter-indexeddb/src/indexeddb-adapter.ts'
---
# Initialize the Data Sync System
Set up SyncManager, create stores with proper configuration, and initialize everything in the correct order.
## Setup
```typescript
import { createSyncManager } from '@omnistreamai/data-core';
import { IndexedDBAdapter } from '@omnistreamai/data-adapter-indexeddb';
import { WebDAVAdapter } from '@omnistreamai/data-adapter-webdav';
// 1. Create SyncManager with adapters
const syncManager = createSyncManager({
localAdapter: new IndexedDBAdapter({ dbName: 'my-app', version: 1 }),
remoteAdapter: new WebDAVAdapter(),
});
// 2. Create all stores BEFORE initStore()
const userStore = syncManager.createStore<User>('users', {
idKey: 'id',
indexes: ['email'],
});
const todoStore = syncManager.createStore<Todo>('todos', {
idKey: 'id',
indexes: ['status'],
maxLocalEntries: 1000,
});
// 3. Configure remote adapter AFTER createStore but BEFORE operations
const webdavAdapter = syncManager.getRemoteAdapter() as WebDAVAdapter;
webdavAdapter.setService({
endpoint: 'https://webdav.example.com/data',
basePath: 'app-data',
authentication: {
authType: 'bearer',
bearer: 'your-token',
},
});
// 4. Initialize all stores at once — AFTER all createStore() calls
await syncManager.initStore();
```
## Core Patterns
### Configure IndexedDB with version for schema changes
```typescript
// Initial setup
const adapter = new IndexedDBAdapter({ dbName: 'my-app', version: 1 });
// Later, when adding a new store 'settings', bump the version
const adapter = new IndexedDBAdapter({ dbName: 'my-app', version: 2 });
syncManager.createStore('settings', { idKey: 'id' });
// Version 2 triggers onupgradeneeded, creating the 'settings' object store
```
### Configure WebDAV adapter with authentication
```typescript
const adapter = new WebDAVAdapter();
adapter.setService({
endpoint: 'https://webdav.example.com/dav',
basePath: 'my-app',
authentication: {
authType: 'bearer', // or 'basic' or 'token'
bearer: 'token-value',
},
});
```
### Set up stores with local-only mode
```typescript
// Local-only: no remote sync
const syncManager = createSyncManager({
localAdapter: new IndexedDBAdapter({ dbName: 'offline-app', version: 1 }),
remoteAdapter: null,
});
const store = syncManager.createStore('cache', { idKey: 'id' });
```
## Common Mistakes
### CRITICAL Call initStore before createStore
Wrong:
```typescript
const syncManager = createSyncManager({ localAdapter, remoteAdapter });
await syncManager.initStore(); // ❌ No stores registered yet
const store = syncManager.createStore('todos', { idKey: 'id' });
// store is NOT initialized
```
Correct:
```typescript
const syncManager = createSyncManager({ localAdapter, remoteAdapter });
const store = syncManager.createStore('todos', { idKey: 'id' });
// ... create all stores ...
await syncManager.initStore(); // ✅ All stores initialized
```
`initStore()` iterates over stores already registered via `createStore()`. Calling it before creates an empty store list.
Source: maintainer interview
---
### CRITICAL Forget to bump IndexedDB version when adding stores
Wrong:
```typescript
// Day 1
const adapter = new IndexedDBAdapter({ dbName: 'my-app', version: 1 });
syncManager.createStore('users', { idKey: 'id' });
// Day 30 — adding a new store
const adapter = new IndexedDBAdapter({ dbName: 'my-app', version: 1 }); // ❌ Same version
syncManager.createStore('settings', { idKey: 'id' }); // 'settings' store never created!
```
Correct:
```typescript
// Day 30 — bump version to trigger IndexedDB upgrade
const adapter = new IndexedDBAdapter({ dbName: 'my-app', version: 2 }); // ✅
syncManager.createStore('settings', { idKey: 'id' });
// Version 2 upgrade runs onupgradeneeded, creating 'settings' object store
```
IndexedDB schema is versioned. New object stores are only created during a version upgrade. The `onupgradeneeded` event only fires when `version` increases.
Source: maintainer interview
---
### HIGH Call WebDAV adapter methods before setService
Wrong:
```typescript
const adapter = new WebDAVAdapter();
await adapter.add('todos', { id: '1', title: 'Test' }); // ❌ Throws: Service not configured
```
Correct:
```typescript
const adapter = new WebDAVAdapter();
adapter.setService({ endpoint: 'https://webdav.example.com/data' });
await adapter.add('todos', { id: '1', title: 'Test' }); // ✅
```
`buildUrl()` requires `service` to be configured. Always call `setService()` before any read/write operation.
Source: packages/adapter-webdav/src/webdav-adapter.ts:68-76