local-lite 0.0.30 → 0.1.0

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 (42) hide show
  1. package/README.md +25 -20
  2. package/dist/adapters/remote/firestore.d.ts +2 -1
  3. package/dist/adapters/remote/firestore.js +21 -3
  4. package/dist/adapters/remote/index.d.ts +2 -2
  5. package/dist/adapters/remote/supabase.d.ts +1 -1
  6. package/dist/config/index.js +3 -1
  7. package/dist/config/types.d.ts +0 -5
  8. package/dist/core/client.d.ts +1 -3
  9. package/dist/core/client.js +4 -11
  10. package/dist/search/store.js +1 -12
  11. package/dist/storage/expo.d.ts +4 -66
  12. package/dist/storage/expo.js +104 -261
  13. package/dist/utils/sql.js +1 -1
  14. package/docs/.nojekyll +1 -0
  15. package/docs/README.md +108 -0
  16. package/docs/_sidebar.md +22 -0
  17. package/docs/actions-email.md +222 -0
  18. package/docs/adapters-local.md +272 -0
  19. package/docs/adapters-remote.md +291 -0
  20. package/docs/api-keys.md +114 -0
  21. package/docs/architecture.md +106 -0
  22. package/docs/auth.md +259 -0
  23. package/docs/backups.md +214 -0
  24. package/docs/breaking-changes.md +147 -0
  25. package/docs/client-api.md +412 -0
  26. package/docs/configuration.md +228 -0
  27. package/docs/conflict-resolution.md +78 -0
  28. package/docs/getting-started.md +190 -0
  29. package/docs/google-auth.md +234 -0
  30. package/docs/index.html +166 -0
  31. package/docs/kv.md +89 -0
  32. package/docs/maintenance-portability.md +133 -0
  33. package/docs/react-hooks.md +457 -0
  34. package/docs/scheduler.md +81 -0
  35. package/docs/search.md +71 -0
  36. package/docs/server.md +101 -0
  37. package/docs/session.md +129 -0
  38. package/docs/storage.md +265 -0
  39. package/package.json +3 -1
  40. package/skills/local-lite-custom-adapter/SKILL.md +59 -0
  41. package/skills/local-lite-setup/SKILL.md +21 -0
  42. package/skills/local-lite-upgrade/SKILL.md +16 -0
package/docs/auth.md ADDED
@@ -0,0 +1,259 @@
1
+ # 🔑 Authentication (Google, Microsoft / OneDrive, GitHub & Apple)
2
+
3
+ `local-lite` provides zero-backend, PKCE-secured authentication clients and React hooks out of the box for the four most popular identity providers:
4
+ * **Google** (`GoogleAuthClient`, `useGoogleAuth`)
5
+ * **Microsoft / OneDrive** (`MicrosoftAuthClient`, `OneDriveAuthClient`, `useMicrosoftAuth`, `useOneDriveAuth`)
6
+ * **GitHub** (`GitHubAuthClient`, `useGitHubAuth`)
7
+ * **Apple** (`AppleAuthClient`, `useAppleAuth`)
8
+
9
+ Built specifically for local-first architectures, these clients allow your Expo, React Native, Web, or Desktop application to authenticate users directly without requiring an intermediate backend auth server.
10
+
11
+ ```typescript
12
+ import {
13
+ GoogleAuthClient,
14
+ MicrosoftAuthClient,
15
+ OneDriveAuthClient,
16
+ GitHubAuthClient,
17
+ AppleAuthClient,
18
+ } from 'local-lite/auth';
19
+
20
+ import {
21
+ useGoogleAuth,
22
+ useMicrosoftAuth,
23
+ useOneDriveAuth,
24
+ useGitHubAuth,
25
+ useAppleAuth,
26
+ } from 'local-lite/react';
27
+ ```
28
+
29
+ ---
30
+
31
+ ## 🌟 Common Architecture & Security
32
+
33
+ * **🛡️ PKCE Security (RFC 7636):** Automatic cryptographically secure 32-byte `code_verifier`, SHA-256 (`S256`) code challenge generation, and CSRF state validation.
34
+ * **👤 Direct Profile Fetching:** Retrieves verified user profile (`id`, `name`, `email`, `picture`) directly from the provider's standard UserInfo / Graph / API endpoints.
35
+ * **🔄 Transparent Token Refreshing:** Inspects token expiration and uses `refresh_token` automatically when within 60 seconds of expiry.
36
+ * **💾 Pluggable Storage:** Use in-memory stores by default or pass any key-value storage adapter (AsyncStorage, SQLite kv-store, SecureStore, etc.) to keep sessions across app restarts.
37
+ * **⚛️ Reactive React Hooks:** Hooks provide reactive user state, sign-in, sign-out, and auto-subscriptions.
38
+
39
+ ---
40
+
41
+ ## 1. Google Authentication
42
+
43
+ ### Setup in Expo / React Native:
44
+ ```typescript
45
+ import * as WebBrowser from 'expo-web-browser';
46
+ import * as Linking from 'expo-linking';
47
+ import { GoogleAuthClient, createGoogleAuthTokenStore } from 'local-lite/auth';
48
+
49
+ export const googleAuth = new GoogleAuthClient({
50
+ clientId: 'YOUR_GOOGLE_CLIENT_ID.apps.googleusercontent.com',
51
+ redirectUri: Linking.createURL('oauth'),
52
+ scopes: ['openid', 'email', 'profile'],
53
+ authorize: async ({ authorizationUrl, redirectUri }) => {
54
+ const result = await WebBrowser.openAuthSessionAsync(authorizationUrl, redirectUri);
55
+ if (result.type !== 'success' || !result.url) return null;
56
+ const url = new URL(result.url);
57
+ return {
58
+ code: url.searchParams.get('code') ?? '',
59
+ state: url.searchParams.get('state') ?? '',
60
+ };
61
+ },
62
+ });
63
+ ```
64
+
65
+ ---
66
+
67
+ ## 2. Microsoft & OneDrive Authentication
68
+
69
+ The Microsoft Identity Platform (v2.0) supports OAuth 2.0 PKCE for public clients without a client secret.
70
+
71
+ ### Setup in Expo / React Native:
72
+ ```typescript
73
+ import * as WebBrowser from 'expo-web-browser';
74
+ import * as Linking from 'expo-linking';
75
+ import { MicrosoftAuthClient, OneDriveAuthClient } from 'local-lite/auth';
76
+
77
+ export const oneDriveAuth = new OneDriveAuthClient({
78
+ clientId: 'YOUR_AZURE_APPLICATION_CLIENT_ID',
79
+ redirectUri: Linking.createURL('oauth'),
80
+ // 'Files.ReadWrite.AppFolder' grants access to dedicated OneDrive app storage
81
+ scopes: ['openid', 'profile', 'email', 'User.Read', 'Files.ReadWrite.AppFolder'],
82
+ authorize: async ({ authorizationUrl, redirectUri }) => {
83
+ const result = await WebBrowser.openAuthSessionAsync(authorizationUrl, redirectUri);
84
+ if (result.type !== 'success' || !result.url) return null;
85
+ const url = new URL(result.url);
86
+ return {
87
+ code: url.searchParams.get('code') ?? '',
88
+ state: url.searchParams.get('state') ?? '',
89
+ };
90
+ },
91
+ });
92
+ ```
93
+
94
+ ### Profile Returned (`MicrosoftUser` / `OneDriveUser`):
95
+ ```typescript
96
+ export interface MicrosoftUser {
97
+ id: string;
98
+ email: string;
99
+ name: string;
100
+ givenName?: string;
101
+ familyName?: string;
102
+ picture?: string;
103
+ userPrincipalName?: string;
104
+ }
105
+ ```
106
+
107
+ ---
108
+
109
+ ## 3. GitHub Authentication
110
+
111
+ Authenticates users via GitHub OAuth and automatically fetches the user's profile and primary verified email address (handling private email profiles seamlessly).
112
+
113
+ ### Setup in Expo / React Native:
114
+ ```typescript
115
+ import * as WebBrowser from 'expo-web-browser';
116
+ import * as Linking from 'expo-linking';
117
+ import { GitHubAuthClient } from 'local-lite/auth';
118
+
119
+ export const gitHubAuth = new GitHubAuthClient({
120
+ clientId: 'YOUR_GITHUB_CLIENT_ID',
121
+ clientSecret: process.env.GITHUB_CLIENT_SECRET, // Optional if using tokenExchangeUrl proxy
122
+ redirectUri: Linking.createURL('oauth'),
123
+ scopes: ['read:user', 'user:email'],
124
+ authorize: async ({ authorizationUrl, redirectUri }) => {
125
+ const result = await WebBrowser.openAuthSessionAsync(authorizationUrl, redirectUri);
126
+ if (result.type !== 'success' || !result.url) return null;
127
+ const url = new URL(result.url);
128
+ return {
129
+ code: url.searchParams.get('code') ?? '',
130
+ state: url.searchParams.get('state') ?? '',
131
+ };
132
+ },
133
+ });
134
+ ```
135
+
136
+ ### Profile Returned (`GitHubUser`):
137
+ ```typescript
138
+ export interface GitHubUser {
139
+ id: string;
140
+ login: string;
141
+ name: string;
142
+ email: string;
143
+ avatarUrl?: string;
144
+ bio?: string;
145
+ company?: string;
146
+ location?: string;
147
+ }
148
+ ```
149
+
150
+ ---
151
+
152
+ ## ⚛️ React Hooks Usage
153
+
154
+ ```tsx
155
+ import React from 'react';
156
+ import { View, Text, Button, Image } from 'react-native';
157
+ import { useGoogleAuth, useMicrosoftAuth, useGitHubAuth } from 'local-lite/react';
158
+ import { googleAuth, oneDriveAuth, gitHubAuth } from './auth';
159
+
160
+ export function LoginButtons() {
161
+ const google = useGoogleAuth(googleAuth);
162
+ const ms = useMicrosoftAuth(oneDriveAuth);
163
+ const github = useGitHubAuth(gitHubAuth);
164
+
165
+ return (
166
+ <View style={{ gap: 10 }}>
167
+ <Button title="Continue with Google" onPress={google.signIn} />
168
+ <Button title="Continue with Microsoft / OneDrive" onPress={ms.signIn} />
169
+ <Button title="Continue with GitHub" onPress={github.signIn} />
170
+ </View>
171
+ );
172
+ }
173
+ ```
174
+
175
+ ---
176
+
177
+ ## 4. Sign in with Apple
178
+
179
+ `AppleAuthClient` supports both native iOS credentials (`expo-apple-authentication` / `ASAuthorizationAppleIDCredential`) and OAuth authorization flows. Because Apple provides full name and email **only on the very first sign-in**, `AppleAuthClient` automatically caches and preserves user details across sessions.
180
+
181
+ ### Setup with `expo-apple-authentication`:
182
+ ```typescript
183
+ import * as AppleAuthentication from 'expo-apple-authentication';
184
+ import { AppleAuthClient } from 'local-lite/auth';
185
+
186
+ export const appleAuth = new AppleAuthClient({
187
+ clientId: 'com.yourcompany.app',
188
+ nativeSignIn: async () => {
189
+ const cred = await AppleAuthentication.signInAsync({
190
+ requestedScopes: [
191
+ AppleAuthentication.AppleAuthenticationScope.FULL_NAME,
192
+ AppleAuthentication.AppleAuthenticationScope.EMAIL,
193
+ ],
194
+ });
195
+ return {
196
+ user: cred.user,
197
+ identityToken: cred.identityToken,
198
+ authorizationCode: cred.authorizationCode,
199
+ email: cred.email,
200
+ fullName: cred.fullName,
201
+ };
202
+ },
203
+ });
204
+ ```
205
+
206
+ ### React Hook Example:
207
+ ```tsx
208
+ import { useAppleAuth } from 'local-lite/react';
209
+ import { appleAuth } from './auth';
210
+
211
+ export function AppleLoginButton() {
212
+ const { user, isSignedIn, signIn, signOut } = useAppleAuth(appleAuth);
213
+
214
+ if (isSignedIn && user) {
215
+ return (
216
+ <View>
217
+ <Text>Welcome {user.name ?? user.email}!</Text>
218
+ <Button title="Sign Out" onPress={signOut} />
219
+ </View>
220
+ );
221
+ }
222
+
223
+ return <Button title="Sign in with Apple" onPress={() => signIn()} />;
224
+ }
225
+ ```
226
+
227
+ ---
228
+
229
+ ## 💾 Session Persistence Adapters
230
+
231
+ All auth clients accept a `storage` option compatible with any key-value store (AsyncStorage, SQLite kv-store, MMKV, or SecureStore):
232
+
233
+ ```typescript
234
+ import AsyncStorage from 'expo-sqlite/kv-store';
235
+ import {
236
+ createGoogleAuthTokenStore,
237
+ createMicrosoftAuthTokenStore,
238
+ createGitHubAuthTokenStore,
239
+ createAppleAuthTokenStore,
240
+ } from 'local-lite/auth';
241
+
242
+ const storage = {
243
+ getItem: async (key: string) => {
244
+ const val = await AsyncStorage.getItem(key);
245
+ return val ? JSON.parse(val) : null;
246
+ },
247
+ setItem: async (key: string, value: unknown) => {
248
+ await AsyncStorage.setItem(key, JSON.stringify(value));
249
+ },
250
+ removeItem: async (key: string) => {
251
+ await AsyncStorage.removeItem(key);
252
+ },
253
+ };
254
+
255
+ const googleTokenStore = createGoogleAuthTokenStore(storage);
256
+ const msTokenStore = createMicrosoftAuthTokenStore(storage);
257
+ const ghTokenStore = createGitHubAuthTokenStore(storage);
258
+ const appleTokenStore = createAppleAuthTokenStore(storage);
259
+ ```
@@ -0,0 +1,214 @@
1
+ # 📦 Cloud Backups & Zero-Knowledge Encryption
2
+
3
+ `local-lite` includes zero-backend cloud backup and client-side zero-knowledge database encryption out of the box.
4
+
5
+ ```typescript
6
+ import {
7
+ GoogleDriveBackupClient,
8
+ OneDriveBackupClient,
9
+ performBackup,
10
+ performRestore,
11
+ createDatabaseBackup,
12
+ restoreDatabaseBackup,
13
+ createEncryptedDatabaseBackup,
14
+ restoreEncryptedDatabaseBackup,
15
+ } from 'local-lite/backups';
16
+
17
+ import {
18
+ useCloudBackup,
19
+ useGoogleDriveBackup,
20
+ useOneDriveBackup,
21
+ } from 'local-lite/react';
22
+ ```
23
+
24
+ ---
25
+
26
+ ## ☁️ 1. Supported Cloud Storage Providers
27
+
28
+ SQLite snapshots are exported directly to user personal cloud storage in secure, application-sandboxed directories without requiring full drive access:
29
+ * **Google Drive** (`GoogleDriveBackupClient`, `GoogleDriveBackupStorage` using the sandboxed `appDataFolder`)
30
+ * **Microsoft OneDrive** (`OneDriveBackupClient`, `OneDriveBackupStorage` using the sandboxed `special/approot` directory)
31
+
32
+ ---
33
+
34
+ ## 🚀 2. Setting Up Backup Clients
35
+
36
+ ### Google Drive Client:
37
+ ```typescript
38
+ import * as WebBrowser from 'expo-web-browser';
39
+ import * as Linking from 'expo-linking';
40
+ import { GoogleDriveBackupClient, createGoogleDriveTokenStore } from 'local-lite/backups';
41
+
42
+ export const googleDriveBackup = new GoogleDriveBackupClient({
43
+ clientId: process.env.EXPO_PUBLIC_GOOGLE_CLIENT_ID!,
44
+ redirectUri: Linking.createURL('oauth'),
45
+ tokenStore: createGoogleDriveTokenStore(secureStorage),
46
+ authorize: async ({ authorizationUrl, redirectUri }) => {
47
+ const res = await WebBrowser.openAuthSessionAsync(authorizationUrl, redirectUri);
48
+ if (res.type !== 'success' || !res.url) return null;
49
+ const url = new URL(res.url);
50
+ return {
51
+ code: url.searchParams.get('code') ?? '',
52
+ state: url.searchParams.get('state') ?? '',
53
+ };
54
+ },
55
+ });
56
+ ```
57
+
58
+ ### OneDrive Client:
59
+ ```typescript
60
+ import * as WebBrowser from 'expo-web-browser';
61
+ import * as Linking from 'expo-linking';
62
+ import { OneDriveBackupClient, createOneDriveTokenStore } from 'local-lite/backups';
63
+
64
+ export const oneDriveBackup = new OneDriveBackupClient({
65
+ clientId: process.env.EXPO_PUBLIC_AZURE_CLIENT_ID!,
66
+ redirectUri: Linking.createURL('oauth'),
67
+ tokenStore: createOneDriveTokenStore(secureStorage),
68
+ authorize: async ({ authorizationUrl, redirectUri }) => {
69
+ const res = await WebBrowser.openAuthSessionAsync(authorizationUrl, redirectUri);
70
+ if (res.type !== 'success' || !res.url) return null;
71
+ const url = new URL(res.url);
72
+ return {
73
+ code: url.searchParams.get('code') ?? '',
74
+ state: url.searchParams.get('state') ?? '',
75
+ };
76
+ },
77
+ });
78
+ ```
79
+
80
+ ---
81
+
82
+ ## 💾 3. Backing Up and Restoring via `client`
83
+
84
+ You can create and restore backups directly through your initialized `LocalFirstClient`:
85
+
86
+ ```typescript
87
+ // Connect user session
88
+ await googleDriveBackup.connect();
89
+
90
+ // 1. Create backup snapshot
91
+ const fileName = await client.backup(googleDriveBackup, {
92
+ fileName: 'my-app-backup.db', // optional
93
+ });
94
+ console.log('Backup created:', fileName);
95
+
96
+ // 2. List backups
97
+ const backups = await googleDriveBackup.list();
98
+
99
+ // 3. Restore snapshot
100
+ await client.restore(googleDriveBackup, backups[0].name);
101
+ ```
102
+
103
+ ---
104
+
105
+ ## 🔐 4. Zero-Knowledge Encryption (AES-256-GCM + PBKDF2)
106
+
107
+ For sensitive applications (medical records, finances, personal notes), data can be encrypted on-device before uploading to the cloud. Neither Google, Microsoft, nor anyone intercepting the file can read the snapshot.
108
+
109
+ ### Security Specifications:
110
+ * **Key Derivation:** PBKDF2 with SHA-256, 50,000 iterations, and a unique 16-byte cryptographic salt per backup.
111
+ * **Authenticated Encryption:** AES-256-GCM with a unique 12-byte initialization vector (IV) and 16-byte authentication tag preventing tampering.
112
+ * **Header Structure:** Self-describing `LLENC1` magic bytes header packing the salt, IV, and iteration count for automatic decryption validation.
113
+
114
+ ### Usage:
115
+ ```typescript
116
+ // Create encrypted backup with passphrase:
117
+ const encryptedFileName = await client.backup(googleDriveBackup, {
118
+ passphrase: 'user-chosen-secret-passphrase',
119
+ fileName: 'medical-snapshot.enc.db',
120
+ });
121
+
122
+ // Restore encrypted backup:
123
+ await client.restore(googleDriveBackup, encryptedFileName, {
124
+ passphrase: 'user-chosen-secret-passphrase',
125
+ });
126
+ ```
127
+
128
+ If the passphrase is incorrect or the file was modified in transit, decryption immediately rejects with:
129
+ `Backup decryption failed: Incorrect passphrase or corrupted database backup.`
130
+
131
+ ---
132
+
133
+ ## ⚛️ 5. React Hooks for Cloud Backups
134
+
135
+ Use `useGoogleDriveBackup` or `useOneDriveBackup` to manage cloud backups reactively in your UI:
136
+
137
+ ```tsx
138
+ import React from 'react';
139
+ import { View, Text, Button, FlatList, ActivityIndicator } from 'react-native';
140
+ import { useGoogleDriveBackup } from 'local-lite/react';
141
+ import { googleDriveBackup } from './backup';
142
+
143
+ export function CloudBackupScreen({ client }) {
144
+ const {
145
+ isConnected,
146
+ isLoading,
147
+ isBackingUp,
148
+ isRestoring,
149
+ backups,
150
+ connect,
151
+ disconnect,
152
+ backup,
153
+ restore,
154
+ deleteBackup,
155
+ } = useGoogleDriveBackup(googleDriveBackup, client, {
156
+ passphrase: 'optional-user-passphrase',
157
+ autoRefresh: true,
158
+ });
159
+
160
+ if (isLoading) return <ActivityIndicator />;
161
+
162
+ if (!isConnected) {
163
+ return (
164
+ <View>
165
+ <Text>Connect your Google Drive to enable cloud backups.</Text>
166
+ <Button title="Connect Google Drive" onPress={() => connect()} />
167
+ </View>
168
+ );
169
+ }
170
+
171
+ return (
172
+ <View style={{ padding: 16 }}>
173
+ <Button
174
+ title={isBackingUp ? 'Creating Backup...' : 'Create New Backup'}
175
+ disabled={isBackingUp}
176
+ onPress={() => backup()}
177
+ />
178
+
179
+ <FlatList
180
+ data={backups}
181
+ keyExtractor={(item) => item.id}
182
+ renderItem={({ item }) => (
183
+ <View style={{ flexDirection: 'row', justifyContent: 'space-between', paddingVertical: 8 }}>
184
+ <View>
185
+ <Text style={{ fontWeight: '600' }}>{item.name}</Text>
186
+ <Text style={{ color: '#666' }}>{new Date(item.createdAt).toLocaleString()}</Text>
187
+ </View>
188
+ <View style={{ flexDirection: 'row', gap: 8 }}>
189
+ <Button title="Restore" onPress={() => restore(item.name)} disabled={isRestoring} />
190
+ <Button title="Delete" color="#ef4444" onPress={() => deleteBackup(item.id)} />
191
+ </View>
192
+ </View>
193
+ )}
194
+ />
195
+
196
+ <Button title="Disconnect" color="#64748b" onPress={() => disconnect()} />
197
+ </View>
198
+ );
199
+ }
200
+ ```
201
+
202
+ ---
203
+
204
+ ## 🗄️ 6. Universal Database Snapshots (`exportDatabase` & `importDatabase`)
205
+
206
+ `LocalFirstClient` includes built-in methods to export and import portable binary snapshots independently of any cloud service (e.g. for local file system saves, air-gapped USB transfers, or diagnostic dumps):
207
+
208
+ ```typescript
209
+ // 1. Export entire SQLite state as Uint8Array bytes
210
+ const snapshotBytes = await client.exportDatabase();
211
+
212
+ // 2. Restore database from snapshot bytes
213
+ await client.importDatabase(snapshotBytes);
214
+ ```
@@ -0,0 +1,147 @@
1
+ # Breaking Changes and AI Code-Review Guide
2
+
3
+ This guide records breaking changes introduced in `local-lite` 0.0.30 and gives
4
+ an actionable checklist for reviewing an application or repository update.
5
+ Use it when upgrading to this version or when asking an AI assistant to check
6
+ whether dependent code needs changes.
7
+
8
+ ## AI review prompt
9
+
10
+ Copy this prompt into your code-review request:
11
+
12
+ > Review this codebase for required updates against
13
+ > [`docs/breaking-changes.md`](./breaking-changes.md). Search application code,
14
+ > configuration, tests, examples, and custom adapters for every affected API.
15
+ > Report each match with file and line, explain whether it needs a change, and
16
+ > suggest a minimal migration. Do not edit files unless asked. Do not treat
17
+ > unrelated uses of the same words as API usage.
18
+
19
+ This guide ships with the package at
20
+ `node_modules/local-lite/docs/breaking-changes.md`. A ready-made skill is at
21
+ `node_modules/local-lite/skills/local-lite-upgrade/SKILL.md` (setup and custom
22
+ adapter skills live beside it); copy the folders
23
+ into `.github/skills/` (Copilot) or `.claude/skills/` (Claude Code).
24
+
25
+ ## Changes in 0.0.30
26
+
27
+ ### 1. Repeat-on-initialize `migrations` option removed
28
+
29
+ The `migrations: string[]` option was removed from `LocalLiteConfig` and
30
+ `LocalFirstClientConfig`. Passing it to `createSyncClient()` or the
31
+ `LocalFirstClient` constructor now throws. Use versioned `schemaMigrations`
32
+ instead.
33
+
34
+ ```typescript
35
+ schemaMigrations: [
36
+ {
37
+ version: 1,
38
+ up: 'CREATE TABLE notes (id TEXT PRIMARY KEY, title TEXT NOT NULL)',
39
+ },
40
+ {
41
+ version: 2,
42
+ up: 'ALTER TABLE notes ADD COLUMN archived INTEGER NOT NULL DEFAULT 0',
43
+ },
44
+ ],
45
+ ```
46
+
47
+ **Review checklist**
48
+
49
+ - Find configuration properties named `migrations` and confirm they are the
50
+ removed local-lite option, not another library's setting or a local variable.
51
+ - Convert SQL into consecutive, one-time `schemaMigrations` entries.
52
+ - Preserve the complete migration history in the application so existing
53
+ installations can upgrade. Do not simply rename the array: old statements
54
+ ran on every initialization, while versioned migrations run once.
55
+ - Update config helpers, test fixtures, and migration-related documentation.
56
+
57
+ ### 2. Expo legacy FileSystem API removed
58
+
59
+ `ExpoFileDriver` now uses Expo SDK 58+ `File`, `Directory`, and `Paths`.
60
+ The `fileSystem` constructor option and legacy `expo-file-system` methods such
61
+ as `writeAsStringAsync`, `getInfoAsync`, `copyAsync`, and `downloadAsync` are no
62
+ longer supported.
63
+
64
+ ```typescript
65
+ import { File, Directory, Paths } from 'expo-file-system';
66
+ import { ExpoFileDriver } from 'local-lite/storage';
67
+
68
+ const driver = new ExpoFileDriver({ File, Directory, Paths });
69
+ ```
70
+
71
+ The `baseDir` and `useCache` options remain available.
72
+
73
+ **Review checklist**
74
+
75
+ - Find `new ExpoFileDriver({ fileSystem: ... })` and replace it with the modern
76
+ named API options.
77
+ - Check Expo dependencies and runtime versions; the modern APIs require Expo
78
+ SDK 58 or newer.
79
+ - Replace direct legacy FileSystem calls in integrations with `File` operations
80
+ or `ExpoFileDriver` methods.
81
+ - Review tests and examples for legacy mocks or imports.
82
+
83
+ ### 3. Custom realtime adapters must return cleanup
84
+
85
+ `RemoteDBAdapter.subscribeToLiveChanges()` now has the required return type
86
+ `() => void`. Every custom adapter implementation must return a function that
87
+ unsubscribes its listener. If no listener is created, return a no-op function.
88
+
89
+ ```typescript
90
+ subscribeToLiveChanges(callback: (changes: DeltaChanges) => void): () => void {
91
+ if (!this.canSubscribe()) return () => {};
92
+
93
+ const subscription = this.startSubscription(callback);
94
+ return () => subscription.unsubscribe();
95
+ }
96
+ ```
97
+
98
+ **Review checklist**
99
+
100
+ - Find classes and object literals implementing `RemoteDBAdapter`.
101
+ - Confirm all code paths, including missing clients, empty table lists, and
102
+ initialization failures, return a cleanup function.
103
+ - Confirm cleanup is safe to call once and prevents callbacks from a stopped or
104
+ replaced subscription.
105
+ - Update mocks and test adapters to match the required signature.
106
+
107
+ ### 4. `_migrations` is no longer an internal table name
108
+
109
+ `isInternalTable('_migrations')` now returns `false`. The name is not treated as
110
+ a local-lite engine table and may consequently appear in APIs that filter
111
+ internal tables, such as `getTables()` and maintenance reports.
112
+
113
+ **Review checklist**
114
+
115
+ - Find uses of `_migrations` as an application table or as a local-lite
116
+ bookkeeping table.
117
+ - If an application uses this name and expects it to be hidden, rename the
118
+ application table or filter it explicitly in the application.
119
+ - Do not rename or delete stored tables as part of an automated upgrade without
120
+ confirming their ownership and contents.
121
+
122
+ ### 5. FTS tokenizer errors now propagate
123
+
124
+ FTS table creation no longer retries without the `tokenize` option after a
125
+ tokenizer error. A configured tokenizer that the SQLite build does not support
126
+ causes search initialization to fail instead of silently creating a table with
127
+ different tokenization behavior.
128
+
129
+ **Review checklist**
130
+
131
+ - Find `client.search` configurations that set a custom tokenizer.
132
+ - Verify the target SQLite build supports the configured tokenizer and FTS5.
133
+ - Test search initialization and representative queries on every supported
134
+ platform/build.
135
+ - Resolve an unsupported tokenizer by selecting one supported by the target
136
+ runtime or correcting the SQLite build; do not rely on an implicit tokenizer
137
+ fallback.
138
+
139
+ ## Suggested review output
140
+
141
+ For each potential issue, report:
142
+
143
+ 1. File and line.
144
+ 2. Which change above applies.
145
+ 3. Whether a code update is required or the match is unrelated.
146
+ 4. The smallest safe migration.
147
+ 5. Any behavior or stored-data risk that needs application-owner confirmation.