local-lite 0.1.3 → 0.2.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.
@@ -1,16 +1,45 @@
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.
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, migrating from legacy options, fixing bundler errors in Metro/Web, or updating authentication and adapters.
4
+ ---
5
+
6
+ # local-lite upgrade review
7
+
8
+ Checklist and automated review instructions for upgrading apps to the latest version of `local-lite`.
9
+
10
+ ## 1. Upgrade Checklist
11
+
12
+ Search the codebase for each affected pattern and apply the migration:
13
+
14
+ ### Schema Migrations (`schemaMigrations` vs `migrations`)
15
+ * **Old**: `createSyncClient({ migrations: [ ... ] })`
16
+ * **New**: `createSyncClient({ schemaMigrations: [ { version: 1, up: [ ... ] } ] })`
17
+ * **Action**: `schemaMigrations` is strictly required. Each item requires `{ version: number, up: string[] }`.
18
+
19
+ ### Custom Remote Adapters (`subscribeToLiveChanges`)
20
+ * **Contract**: `subscribeToLiveChanges(callback)` must return an unsubscribe cleanup function `() => void`. Returning `void` causes memory leaks and breaks lifecycle tearing.
21
+
22
+ ### Expo Web & Metro Bundler Configuration
23
+ * **Symptom**: `Unable to resolve module ./wa-sqlite/wa-sqlite.wasm` or `Importing react-native internals is not supported on web`.
24
+ * **Fix**: In `metro.config.js`:
25
+ 1. Add `.wasm` to `config.resolver.assetExts.push('wasm')`.
26
+ 2. In `resolveRequest`, map `react-native` to `react-native-web` when `platform === 'web'`.
27
+ 3. Set `"output": "single"` in `app.json` under `expo.web`.
28
+
29
+ ### UUID Generation
30
+ * **Old**: `import { v4 } from 'uuid';`
31
+ * **New**: `import { generateUUID } from 'local-lite';`
32
+ * **Action**: External `uuid` (v10+) references bare `crypto.randomUUID` which throws `Property 'crypto' doesn't exist` on Hermes. Use `generateUUID()` directly from `local-lite`.
33
+
34
+ ### File Storage Driver (`ExpoFileDriver`)
35
+ * **Old**: Injecting `fileSystem` via legacy `expo-file-system`.
36
+ * **New**: Uses standard Expo SDK 58+ `File`, `Directory`, and `Paths` APIs. Remove legacy `fileSystem` option.
37
+
38
+ ---
39
+
40
+ ## 2. Review Workflow
41
+
42
+ 1. Scan `sync.config.ts` (or client creation files) for deprecated options (`migrations`, legacy adapters).
43
+ 2. Verify all synced tables contain `id TEXT PRIMARY KEY` and `updated_at INTEGER NOT NULL`.
44
+ 3. Verify `schemaMigrations` versions are strictly sequential integers starting from 1.
45
+ 4. Report each match with file path and line number alongside minimal migration code.