local-lite 0.0.30 → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (43) hide show
  1. package/README.md +32 -20
  2. package/bin/local-lite.mjs +62 -0
  3. package/dist/adapters/remote/firestore.d.ts +2 -1
  4. package/dist/adapters/remote/firestore.js +21 -3
  5. package/dist/adapters/remote/index.d.ts +2 -2
  6. package/dist/adapters/remote/supabase.d.ts +1 -1
  7. package/dist/config/index.js +3 -1
  8. package/dist/config/types.d.ts +0 -5
  9. package/dist/core/client.d.ts +1 -3
  10. package/dist/core/client.js +4 -11
  11. package/dist/search/store.js +1 -12
  12. package/dist/storage/expo.d.ts +4 -66
  13. package/dist/storage/expo.js +104 -261
  14. package/dist/utils/sql.js +1 -1
  15. package/docs/.nojekyll +1 -0
  16. package/docs/README.md +108 -0
  17. package/docs/_sidebar.md +22 -0
  18. package/docs/actions-email.md +222 -0
  19. package/docs/adapters-local.md +272 -0
  20. package/docs/adapters-remote.md +291 -0
  21. package/docs/api-keys.md +114 -0
  22. package/docs/architecture.md +106 -0
  23. package/docs/auth.md +259 -0
  24. package/docs/backups.md +214 -0
  25. package/docs/breaking-changes.md +147 -0
  26. package/docs/client-api.md +412 -0
  27. package/docs/configuration.md +228 -0
  28. package/docs/conflict-resolution.md +78 -0
  29. package/docs/getting-started.md +190 -0
  30. package/docs/google-auth.md +234 -0
  31. package/docs/index.html +166 -0
  32. package/docs/kv.md +89 -0
  33. package/docs/maintenance-portability.md +133 -0
  34. package/docs/react-hooks.md +457 -0
  35. package/docs/scheduler.md +81 -0
  36. package/docs/search.md +71 -0
  37. package/docs/server.md +101 -0
  38. package/docs/session.md +129 -0
  39. package/docs/storage.md +265 -0
  40. package/package.json +7 -1
  41. package/skills/local-lite-custom-adapter/SKILL.md +59 -0
  42. package/skills/local-lite-setup/SKILL.md +21 -0
  43. package/skills/local-lite-upgrade/SKILL.md +16 -0
@@ -0,0 +1,59 @@
1
+ ---
2
+ name: local-lite-custom-adapter
3
+ description: Write or review a custom local-lite RemoteDBAdapter for a REST, GraphQL or WebSocket backend. Use when implementing pushChanges, fetchChanges, subscribeToLiveChanges or setSyncScope, or debugging sync that duplicates, loses, or never stops receiving changes.
4
+ ---
5
+
6
+ # local-lite custom remote adapter
7
+
8
+ Implement `RemoteDBAdapter` (exported from `local-lite`, with `SyncOperation`, `DeltaChanges`, `PushResult` types). Check `node_modules/local-lite/dist` type definitions and `docs/adapters-remote.md` ("Custom Remote Adapters") for exact shapes.
9
+
10
+ ## Contract
11
+
12
+ - `pushChanges(operations): Promise<boolean | PushResult>`
13
+ - Must be idempotent: the client retries after failures, so applying the same operation twice must be safe.
14
+ - Return `false` (or a failing `PushResult`) or reject on failure so operations stay in the outbox. Never report success for operations that were not stored.
15
+ - `fetchChanges(sinceTimestamp, scope?): Promise<DeltaChanges>`
16
+ - Return a **complete** batch of everything changed after `sinceTimestamp`, through the timestamp you report. Reject on partial failure; never return a truncated page as complete, or the checkpoint will skip data.
17
+ - Apply `scope` filtering server-side when provided.
18
+ - `subscribeToLiveChanges(callback, scope?): () => void`
19
+ - **Must return a cleanup function** (a no-op if no listener was created). Returning `void` is a breaking change since 0.0.30.
20
+ - Live events do not advance the durable pull checkpoint.
21
+ - `scope` may be an object or a (possibly async) function. If setup is async, guard against cleanup running before setup finishes (generation counter or cancelled flag) so listeners do not leak.
22
+ - `setSyncScope?(scope)`: optional; implement it if the backend filters by scope, and re-subscribe live listeners when scope changes.
23
+
24
+ ## Skeleton
25
+
26
+ ```typescript
27
+ import type { RemoteDBAdapter, SyncOperation, DeltaChanges } from 'local-lite';
28
+
29
+ export class MyAdapter implements RemoteDBAdapter {
30
+ async pushChanges(operations: SyncOperation[]): Promise<boolean> {
31
+ const res = await fetch('/sync/push', {
32
+ method: 'POST',
33
+ headers: { 'Content-Type': 'application/json' },
34
+ body: JSON.stringify({ operations }),
35
+ });
36
+ return res.ok;
37
+ }
38
+
39
+ async fetchChanges(since: number, scope?: Record<string, any>): Promise<DeltaChanges> {
40
+ const res = await fetch(`/sync/pull?since=${since}&scope=${encodeURIComponent(JSON.stringify(scope ?? {}))}`);
41
+ if (!res.ok) throw new Error(`Pull failed: ${res.status}`);
42
+ return res.json();
43
+ }
44
+
45
+ subscribeToLiveChanges(callback: (c: DeltaChanges) => void): () => void {
46
+ const ws = new WebSocket('wss://example.com/realtime');
47
+ ws.onmessage = (e) => callback(JSON.parse(e.data));
48
+ return () => ws.close();
49
+ }
50
+ }
51
+ ```
52
+
53
+ ## Review checklist
54
+
55
+ - Non-OK HTTP responses throw or return failure, never silently succeed.
56
+ - Server timestamps are consistent with `sinceTimestamp`.
57
+ - Pushes are idempotent (upsert by `id`).
58
+ - A cleanup function is always returned and actually releases the listener.
59
+ - Tests with a mock server cover push failure, partial pull failure, and cleanup.
@@ -0,0 +1,21 @@
1
+ ---
2
+ name: local-lite-setup
3
+ description: Set up the local-lite local-first SQLite sync engine in a React / React Native / Expo / Node app. Use when adding local-lite, writing a sync config with defineSyncConfig, schemaMigrations, choosing a remote backend (Supabase, Convex, Firestore, demo), or wiring useLiveQuery and useSyncStatus.
4
+ ---
5
+
6
+ # local-lite setup
7
+
8
+ Read `node_modules/local-lite/README.md` and the docs (`docs/getting-started.md`, `docs/configuration.md`, `docs/adapters-remote.md` in the repo) if available. Then:
9
+
10
+ 1. **Install** `local-lite`, a SQLite driver (`expo-sqlite` for Expo/RN, or a Node SQLite driver for Node/Electron), and one backend SDK (`@supabase/supabase-js`, `convex`, or `firebase`). Ask which platform and backend if unclear.
11
+ 2. **Create `sync.config.ts`** using `defineSyncConfig` and `createSyncClient` from `local-lite/config`:
12
+ - `database`: instance or factory, e.g. `() => SQLite.openDatabaseAsync('app.db')`
13
+ - `tables`: array of synced table names
14
+ - `schemaMigrations`: ordered `{ version, up: [sql...] }`. Each synced table needs `id TEXT PRIMARY KEY` and `updated_at INTEGER NOT NULL`. Never edit an applied migration; append a new version.
15
+ - one remote config (`supabase`, `convex`, `firestore`, or demo) with credentials from env vars
16
+ - optional `conflictResolver: 'last-write-wins'`, `pushIntervalMs`, `pullIntervalMs`
17
+ - export a singleton `getSyncClient()` that caches the `createSyncClient(syncConfig)` promise
18
+ 3. **Backend schema**: follow the matching section of `docs/adapters-remote.md` (Postgres SQL, Convex schema and sync functions, or Firestore setup) so server tables match.
19
+ 4. **UI**: use `useLiveQuery` and `useSyncStatus` from `local-lite/react`; generate IDs with `generateUUID` from `local-lite`.
20
+ 5. **Do not** use the removed `migrations` option (use `schemaMigrations`) and do not pass `fileSystem` to `ExpoFileDriver`. See `docs/breaking-changes.md`.
21
+ 6. Verify the app type-checks and completes a first sync against the demo backend before switching to a real one.
@@ -0,0 +1,16 @@
1
+ ---
2
+ name: local-lite-upgrade
3
+ description: Review a codebase that uses the local-lite npm package for code that must change after a local-lite upgrade. Use when upgrading local-lite, fixing errors about the removed `migrations` option, `fileSystem` in ExpoFileDriver, custom RemoteDBAdapter implementations, or `_migrations` table handling.
4
+ ---
5
+
6
+ # local-lite upgrade review
7
+
8
+ 1. Read `node_modules/local-lite/docs/breaking-changes.md` (or `docs/breaking-changes.md` in the local-lite repo). It lists each breaking change with migration code and a review checklist.
9
+ 2. Search the user's code, config, tests and examples for every affected API listed there:
10
+ - `migrations` option passed to `createSyncClient()` / `LocalFirstClient` (use `schemaMigrations`)
11
+ - `ExpoFileDriver` with a `fileSystem` option or legacy `expo-file-system` APIs
12
+ - custom `RemoteDBAdapter` whose `subscribeToLiveChanges` does not return an unsubscribe function
13
+ - reliance on FTS tokenizer fallback
14
+ - code treating `_migrations` as an internal table
15
+ 3. Report each match with file and line, whether it needs a change, and a minimal migration.
16
+ 4. Do not edit files unless the user asks. Ignore unrelated uses of the same words.