local-lite 0.0.29 โ†’ 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 (50) hide show
  1. package/README.md +25 -20
  2. package/dist/adapters/remote/convex.d.ts +7 -2
  3. package/dist/adapters/remote/convex.js +73 -40
  4. package/dist/adapters/remote/firestore.d.ts +2 -1
  5. package/dist/adapters/remote/firestore.js +21 -3
  6. package/dist/adapters/remote/index.d.ts +3 -2
  7. package/dist/adapters/remote/supabase.d.ts +1 -1
  8. package/dist/config/index.js +3 -1
  9. package/dist/config/types.d.ts +0 -5
  10. package/dist/core/client.d.ts +7 -3
  11. package/dist/core/client.js +14 -11
  12. package/dist/core/meta-store.d.ts +3 -3
  13. package/dist/core/meta-store.js +6 -6
  14. package/dist/core/outbox-store.d.ts +9 -0
  15. package/dist/core/outbox-store.js +31 -0
  16. package/dist/core/sync-worker.d.ts +6 -0
  17. package/dist/core/sync-worker.js +68 -25
  18. package/dist/search/store.js +1 -12
  19. package/dist/storage/expo.d.ts +4 -66
  20. package/dist/storage/expo.js +104 -261
  21. package/dist/utils/sql.js +1 -1
  22. package/docs/.nojekyll +1 -0
  23. package/docs/README.md +108 -0
  24. package/docs/_sidebar.md +22 -0
  25. package/docs/actions-email.md +222 -0
  26. package/docs/adapters-local.md +272 -0
  27. package/docs/adapters-remote.md +291 -0
  28. package/docs/api-keys.md +114 -0
  29. package/docs/architecture.md +106 -0
  30. package/docs/auth.md +259 -0
  31. package/docs/backups.md +214 -0
  32. package/docs/breaking-changes.md +147 -0
  33. package/docs/client-api.md +412 -0
  34. package/docs/configuration.md +228 -0
  35. package/docs/conflict-resolution.md +78 -0
  36. package/docs/getting-started.md +190 -0
  37. package/docs/google-auth.md +234 -0
  38. package/docs/index.html +166 -0
  39. package/docs/kv.md +89 -0
  40. package/docs/maintenance-portability.md +133 -0
  41. package/docs/react-hooks.md +457 -0
  42. package/docs/scheduler.md +81 -0
  43. package/docs/search.md +71 -0
  44. package/docs/server.md +101 -0
  45. package/docs/session.md +129 -0
  46. package/docs/storage.md +265 -0
  47. package/package.json +3 -1
  48. package/skills/local-lite-custom-adapter/SKILL.md +59 -0
  49. package/skills/local-lite-setup/SKILL.md +21 -0
  50. package/skills/local-lite-upgrade/SKILL.md +16 -0
@@ -31,24 +31,23 @@ function base64ToBytes(base64) {
31
31
  }
32
32
  /**
33
33
  * FileDriver implementation for Expo / React Native environments.
34
- * Uses modern Expo (>57/58) `File`, `Directory`, and `Paths` APIs when available,
35
- * with seamless fallback for legacy `expo-file-system` environments.
34
+ * Uses the Expo SDK 58+ `File`, `Directory`, and `Paths` APIs.
36
35
  */
37
36
  class ExpoFileDriver {
38
37
  FileClass;
39
38
  DirectoryClass;
40
39
  PathsObj;
41
- legacyFs;
42
40
  baseDirOption;
43
41
  useCache;
44
42
  resolvedBaseDir = null;
45
43
  resolvedBaseDirPath = null;
46
- ensuredDirs = new Set();
47
44
  constructor(options = {}) {
48
- this.FileClass = options.File ?? options.fileSystem?.File;
49
- this.DirectoryClass = options.Directory ?? options.fileSystem?.Directory;
50
- this.PathsObj = options.Paths ?? options.fileSystem?.Paths;
51
- this.legacyFs = options.fileSystem;
45
+ if ('fileSystem' in options) {
46
+ throw new TypeError('ExpoFileDriver no longer accepts fileSystem. Pass File, Directory, and Paths instead.');
47
+ }
48
+ this.FileClass = options.File;
49
+ this.DirectoryClass = options.Directory;
50
+ this.PathsObj = options.Paths;
52
51
  this.baseDirOption = options.baseDir;
53
52
  this.useCache = Boolean(options.useCache);
54
53
  }
@@ -60,27 +59,25 @@ class ExpoFileDriver {
60
59
  this.FileClass = this.FileClass ?? mod.File;
61
60
  this.DirectoryClass = this.DirectoryClass ?? mod.Directory;
62
61
  this.PathsObj = this.PathsObj ?? mod.Paths;
63
- this.legacyFs = this.legacyFs ?? mod;
64
62
  }
65
- catch {
66
- // Dynamic import may fail if not installed or bundler forbids
63
+ catch (error) {
64
+ if (!this.FileClass) {
65
+ throw new Error('ExpoFileDriver requires expo-file-system SDK 58 or newer.', { cause: error });
66
+ }
67
67
  }
68
68
  }
69
- return {
70
- FileClass: this.FileClass,
71
- DirectoryClass: this.DirectoryClass,
72
- PathsObj: this.PathsObj,
73
- legacyFs: this.legacyFs,
74
- };
69
+ if (!this.FileClass) {
70
+ throw new Error('ExpoFileDriver requires the modern File API from expo-file-system SDK 58 or newer.');
71
+ }
75
72
  }
76
73
  async getBaseDirectory() {
77
74
  if (this.resolvedBaseDir)
78
75
  return this.resolvedBaseDir;
79
- const { DirectoryClass, PathsObj, legacyFs } = await this.resolveClasses();
76
+ await this.resolveClasses();
80
77
  if (this.baseDirOption) {
81
78
  if (typeof this.baseDirOption === 'string') {
82
- if (DirectoryClass) {
83
- this.resolvedBaseDir = new DirectoryClass(this.baseDirOption);
79
+ if (this.DirectoryClass) {
80
+ this.resolvedBaseDir = new this.DirectoryClass(this.baseDirOption);
84
81
  }
85
82
  else {
86
83
  this.resolvedBaseDirPath = this.baseDirOption.endsWith('/')
@@ -92,16 +89,12 @@ class ExpoFileDriver {
92
89
  this.resolvedBaseDir = this.baseDirOption;
93
90
  }
94
91
  }
95
- else if (DirectoryClass && PathsObj) {
96
- const root = this.useCache ? PathsObj.cache : PathsObj.document;
97
- this.resolvedBaseDir = new DirectoryClass(root, 'local-lite-blobs');
92
+ else if (this.DirectoryClass && this.PathsObj) {
93
+ const root = this.useCache ? this.PathsObj.cache : this.PathsObj.document;
94
+ this.resolvedBaseDir = new this.DirectoryClass(root, 'local-lite-blobs');
98
95
  }
99
- else if (legacyFs) {
100
- const root = this.useCache ? legacyFs.cacheDirectory : legacyFs.documentDirectory;
101
- if (!root) {
102
- throw new Error('ExpoFileDriver: FileSystem documentDirectory is null or unavailable.');
103
- }
104
- this.resolvedBaseDirPath = root.endsWith('/') ? `${root}local-lite-blobs/` : `${root}/local-lite-blobs/`;
96
+ else {
97
+ throw new Error('ExpoFileDriver requires the modern Directory and Paths APIs from expo-file-system.');
105
98
  }
106
99
  if (this.resolvedBaseDir) {
107
100
  try {
@@ -114,227 +107,100 @@ class ExpoFileDriver {
114
107
  return this.resolvedBaseDir;
115
108
  }
116
109
  /**
117
- * Resolves a key to a modern Expo `File` instance (if File class is available)
118
- * or a string URI path.
110
+ * Resolves a key to a modern Expo `File` instance.
119
111
  */
120
- async resolveFileOrUri(key) {
121
- const { FileClass, DirectoryClass } = await this.resolveClasses();
112
+ async resolveFile(key) {
113
+ await this.resolveClasses();
122
114
  const baseDir = await this.getBaseDirectory();
123
115
  const safeKey = key.replace(/\.\./g, '_').replace(/^[/\\?%*:|"<>]+/, '');
124
- // Modern Expo File & Directory path
125
- if (FileClass && baseDir) {
116
+ if (baseDir && this.DirectoryClass) {
126
117
  const segments = safeKey.split('/').filter(Boolean);
127
118
  const fileName = segments.pop() || 'blob';
128
119
  let currentDir = baseDir;
129
120
  for (const seg of segments) {
130
121
  const safeSeg = seg.replace(/[/\\?%*:|"<>]/g, '_');
131
- if (DirectoryClass) {
132
- const subDir = new DirectoryClass(currentDir, safeSeg);
133
- try {
134
- if (!subDir.exists && typeof subDir.create === 'function') {
135
- subDir.create({ idempotent: true });
136
- }
137
- }
138
- catch { }
139
- currentDir = subDir;
122
+ const subDir = new this.DirectoryClass(currentDir, safeSeg);
123
+ if (!subDir.exists) {
124
+ subDir.create({ idempotent: true, intermediates: true });
140
125
  }
126
+ currentDir = subDir;
141
127
  }
142
128
  const safeFileName = fileName.replace(/[/\\?%*:|"<>]/g, '_');
143
- const file = new FileClass(currentDir, safeFileName);
144
- return { file, uri: file.uri };
129
+ const file = new this.FileClass(currentDir, safeFileName);
130
+ if (file.parentDirectory && !file.parentDirectory.exists) {
131
+ file.parentDirectory.create({ idempotent: true, intermediates: true });
132
+ }
133
+ return file;
145
134
  }
146
- // Legacy URI resolution
147
135
  const basePath = this.resolvedBaseDirPath ||
148
136
  (this.resolvedBaseDir?.uri
149
137
  ? this.resolvedBaseDir.uri.endsWith('/')
150
138
  ? this.resolvedBaseDir.uri
151
139
  : `${this.resolvedBaseDir.uri}/`
152
- : 'file:///local-lite-blobs/');
153
- const uri = `${basePath}${safeKey}`;
154
- return { file: null, uri };
140
+ : undefined);
141
+ if (!basePath) {
142
+ throw new Error('ExpoFileDriver could not resolve a base directory for the requested file.');
143
+ }
144
+ const safePath = safeKey
145
+ .split('/')
146
+ .filter(Boolean)
147
+ .map((segment) => segment.replace(/[/\\?%*:|"<>]/g, '_'))
148
+ .join('/');
149
+ return new this.FileClass(`${basePath}${safePath}`);
155
150
  }
156
151
  async resolveUri(key) {
157
- const { uri } = await this.resolveFileOrUri(key);
158
- return uri;
152
+ const file = await this.resolveFile(key);
153
+ return file.uri;
159
154
  }
160
155
  async getUri(key) {
161
156
  return this.resolveUri(key);
162
157
  }
163
- async ensureDirectory(fileUri) {
164
- const { legacyFs } = await this.resolveClasses();
165
- if (!legacyFs || typeof legacyFs.makeDirectoryAsync !== 'function')
166
- return;
167
- const lastSlash = fileUri.lastIndexOf('/');
168
- if (lastSlash === -1)
169
- return;
170
- const dir = fileUri.substring(0, lastSlash);
171
- if (this.ensuredDirs.has(dir))
172
- return;
173
- try {
174
- await legacyFs.makeDirectoryAsync(dir, { intermediates: true });
175
- this.ensuredDirs.add(dir);
176
- }
177
- catch {
178
- this.ensuredDirs.add(dir);
179
- }
180
- }
181
158
  async write(key, data) {
182
- const { file, uri } = await this.resolveFileOrUri(key);
183
- // Modern Expo File (>57/58)
184
- if (file) {
185
- // Ensure parent directory exists before writing
186
- try {
187
- if (file.parentDirectory && !file.parentDirectory.exists) {
188
- file.parentDirectory.create({ idempotent: true });
189
- }
190
- }
191
- catch { }
192
- if (typeof file.write === 'function') {
193
- await file.write(data);
194
- return file.uri;
195
- }
196
- if (typeof file.writeSync === 'function') {
197
- file.writeSync(data);
198
- return file.uri;
199
- }
159
+ const file = await this.resolveFile(key);
160
+ if (typeof file.write === 'function') {
161
+ await file.write(data);
200
162
  }
201
- // Legacy FileSystem API
202
- const { legacyFs } = await this.resolveClasses();
203
- if (legacyFs && typeof legacyFs.writeAsStringAsync === 'function') {
204
- await this.ensureDirectory(uri);
205
- const base64 = bytesToBase64(data);
206
- const encoding = legacyFs.EncodingType?.Base64 ?? 'base64';
207
- await legacyFs.writeAsStringAsync(uri, base64, { encoding });
208
- return uri;
163
+ else if (typeof file.writeSync === 'function') {
164
+ file.writeSync(data);
209
165
  }
210
- throw new Error('ExpoFileDriver: No supported File or write method found on expo-file-system.');
166
+ else {
167
+ throw new Error('ExpoFileDriver: The Expo File instance does not support writing.');
168
+ }
169
+ return file.uri;
211
170
  }
212
171
  async read(key) {
213
- const { file, uri } = await this.resolveFileOrUri(key);
214
- // Modern Expo File (>57/58)
215
- if (file) {
216
- try {
217
- if (!file.exists) {
218
- return null;
219
- }
220
- if (typeof file.bytes === 'function') {
221
- const res = await file.bytes();
222
- return new Uint8Array(res);
223
- }
224
- if (typeof file.bytesSync === 'function') {
225
- return new Uint8Array(file.bytesSync());
226
- }
227
- if (typeof file.arrayBuffer === 'function') {
228
- const ab = await file.arrayBuffer();
229
- return new Uint8Array(ab);
230
- }
231
- if (typeof file.base64 === 'function') {
232
- const b64 = await file.base64();
233
- return base64ToBytes(b64);
234
- }
235
- if (typeof file.base64Sync === 'function') {
236
- return base64ToBytes(file.base64Sync());
237
- }
238
- }
239
- catch {
240
- return null;
241
- }
242
- }
243
- // Legacy FileSystem API
244
- const { legacyFs } = await this.resolveClasses();
245
- if (legacyFs && typeof legacyFs.readAsStringAsync === 'function') {
246
- try {
247
- if (typeof legacyFs.getInfoAsync === 'function') {
248
- const info = await legacyFs.getInfoAsync(uri);
249
- if (!info.exists)
250
- return null;
251
- }
252
- const encoding = legacyFs.EncodingType?.Base64 ?? 'base64';
253
- const base64 = await legacyFs.readAsStringAsync(uri, { encoding });
254
- return base64ToBytes(base64);
255
- }
256
- catch {
257
- return null;
258
- }
259
- }
260
- return null;
172
+ const file = await this.resolveFile(key);
173
+ if (!file.exists)
174
+ return null;
175
+ if (typeof file.bytes === 'function')
176
+ return new Uint8Array(await file.bytes());
177
+ if (typeof file.bytesSync === 'function')
178
+ return new Uint8Array(file.bytesSync());
179
+ if (typeof file.arrayBuffer === 'function')
180
+ return new Uint8Array(await file.arrayBuffer());
181
+ if (typeof file.base64 === 'function')
182
+ return base64ToBytes(await file.base64());
183
+ if (typeof file.base64Sync === 'function')
184
+ return base64ToBytes(file.base64Sync());
185
+ throw new Error('ExpoFileDriver: The Expo File instance does not support reading.');
261
186
  }
262
187
  async delete(key) {
263
- const { file, uri } = await this.resolveFileOrUri(key);
264
- // Modern Expo File (>57/58)
265
- if (file) {
266
- try {
267
- if (file.exists && typeof file.delete === 'function') {
268
- file.delete();
269
- }
270
- return;
271
- }
272
- catch {
273
- return;
274
- }
275
- }
276
- // Legacy FileSystem API
277
- const { legacyFs } = await this.resolveClasses();
278
- if (legacyFs && typeof legacyFs.deleteAsync === 'function') {
279
- try {
280
- await legacyFs.deleteAsync(uri, { idempotent: true });
281
- }
282
- catch { }
283
- }
188
+ const file = await this.resolveFile(key);
189
+ if (file.exists && typeof file.delete === 'function')
190
+ await file.delete();
284
191
  }
285
192
  async exists(key) {
286
- const { file, uri } = await this.resolveFileOrUri(key);
287
- // Modern Expo File (>57/58)
288
- if (file) {
289
- try {
290
- return Boolean(file.exists);
291
- }
292
- catch {
293
- return false;
294
- }
295
- }
296
- // Legacy FileSystem API
297
- const { legacyFs } = await this.resolveClasses();
298
- if (legacyFs && typeof legacyFs.getInfoAsync === 'function') {
299
- try {
300
- const info = await legacyFs.getInfoAsync(uri);
301
- return Boolean(info.exists);
302
- }
303
- catch {
304
- return false;
305
- }
306
- }
307
- return false;
193
+ const file = await this.resolveFile(key);
194
+ return Boolean(file.exists);
308
195
  }
309
196
  async getSize(key) {
310
- const { file, uri } = await this.resolveFileOrUri(key);
311
- // Modern Expo File (>57/58)
312
- if (file) {
313
- try {
314
- if (!file.exists)
315
- return 0;
316
- if (typeof file.size === 'number')
317
- return file.size;
318
- if (typeof file.info === 'function') {
319
- const info = file.info();
320
- return info?.size ?? 0;
321
- }
322
- }
323
- catch {
324
- return 0;
325
- }
326
- }
327
- // Legacy FileSystem API
328
- const { legacyFs } = await this.resolveClasses();
329
- if (legacyFs && typeof legacyFs.getInfoAsync === 'function') {
330
- try {
331
- const info = await legacyFs.getInfoAsync(uri, { size: true });
332
- return info.size ?? 0;
333
- }
334
- catch {
335
- return 0;
336
- }
337
- }
197
+ const file = await this.resolveFile(key);
198
+ if (!file.exists)
199
+ return 0;
200
+ if (typeof file.size === 'number')
201
+ return file.size;
202
+ if (typeof file.info === 'function')
203
+ return (await file.info())?.size ?? 0;
338
204
  return 0;
339
205
  }
340
206
  /**
@@ -342,61 +208,38 @@ class ExpoFileDriver {
342
208
  * into local-lite managed storage without reading entire file contents into memory.
343
209
  */
344
210
  async copyFrom(sourceUri, key) {
345
- const { file, uri } = await this.resolveFileOrUri(key);
346
- const { FileClass, legacyFs } = await this.resolveClasses();
347
- // Modern Expo File (>57/58)
348
- if (file && FileClass) {
349
- try {
350
- const srcFile = new FileClass(sourceUri);
351
- if (srcFile.exists && typeof srcFile.copy === 'function') {
352
- if (file.parentDirectory && !file.parentDirectory.exists) {
353
- file.parentDirectory.create({ idempotent: true });
354
- }
355
- await srcFile.copy(file);
356
- return file.uri;
357
- }
358
- }
359
- catch { }
360
- }
361
- // Legacy FileSystem API
362
- if (legacyFs && typeof legacyFs.copyAsync === 'function') {
363
- await this.ensureDirectory(uri);
364
- await legacyFs.copyAsync({ from: sourceUri, to: uri });
365
- return uri;
366
- }
367
- // Fallback: read bytes and write
368
- if (legacyFs && typeof legacyFs.readAsStringAsync === 'function') {
369
- const encoding = legacyFs.EncodingType?.Base64 ?? 'base64';
370
- const content = await legacyFs.readAsStringAsync(sourceUri, { encoding });
371
- await this.write(key, base64ToBytes(content));
372
- return uri;
373
- }
374
- return uri;
211
+ const file = await this.resolveFile(key);
212
+ const sourceFile = new this.FileClass(sourceUri);
213
+ if (!sourceFile.exists)
214
+ throw new Error(`ExpoFileDriver: Source file "${sourceUri}" does not exist.`);
215
+ if (typeof sourceFile.copy === 'function') {
216
+ await sourceFile.copy(file);
217
+ }
218
+ else {
219
+ const contents = typeof sourceFile.bytes === 'function'
220
+ ? await sourceFile.bytes()
221
+ : typeof sourceFile.bytesSync === 'function'
222
+ ? sourceFile.bytesSync()
223
+ : null;
224
+ if (!contents) {
225
+ throw new Error('ExpoFileDriver: The source File instance does not support copying or reading.');
226
+ }
227
+ await this.write(key, new Uint8Array(contents));
228
+ }
229
+ return file.uri;
375
230
  }
376
231
  /**
377
232
  * Downloads a remote URL directly to the destination key on disk.
378
233
  */
379
234
  async downloadFrom(remoteUrl, key) {
380
- const { file, uri } = await this.resolveFileOrUri(key);
381
- const { FileClass, legacyFs } = await this.resolveClasses();
382
- // Modern Expo File (>57/58)
383
- if (file && FileClass && typeof FileClass.downloadFileAsync === 'function') {
235
+ const file = await this.resolveFile(key);
236
+ if (typeof this.FileClass.downloadFileAsync === 'function') {
384
237
  try {
385
- if (file.parentDirectory && !file.parentDirectory.exists) {
386
- file.parentDirectory.create({ idempotent: true });
387
- }
388
- await FileClass.downloadFileAsync(remoteUrl, file, { idempotent: true });
238
+ await this.FileClass.downloadFileAsync(remoteUrl, file, { idempotent: true });
389
239
  return file.uri;
390
240
  }
391
241
  catch { }
392
242
  }
393
- // Legacy FileSystem API
394
- if (legacyFs && typeof legacyFs.downloadAsync === 'function') {
395
- await this.ensureDirectory(uri);
396
- const res = await legacyFs.downloadAsync(remoteUrl, uri);
397
- return res.uri;
398
- }
399
- // Universal fetch fallback
400
243
  const response = await fetch(remoteUrl);
401
244
  if (!response.ok) {
402
245
  throw new Error(`Failed to download file from "${remoteUrl}": ${response.statusText}`);
package/dist/utils/sql.js CHANGED
@@ -24,7 +24,7 @@ function isInternalTable(tableName) {
24
24
  return true;
25
25
  if (lower.startsWith('sync_'))
26
26
  return true;
27
- if (lower === 'schema_migrations' || lower === '_migrations')
27
+ if (lower === 'schema_migrations')
28
28
  return true;
29
29
  return false;
30
30
  }
package/docs/.nojekyll ADDED
@@ -0,0 +1 @@
1
+ # Disable Jekyll processing on GitHub Pages
package/docs/README.md ADDED
@@ -0,0 +1,108 @@
1
+ # โšก local-lite Documentation
2
+
3
+ Welcome to the official documentation for **`local-lite`**, a lightweight, vendor-agnostic **local-first synchronization engine** for React Native, Expo, Web, and Node.js applications.
4
+
5
+ ---
6
+
7
+ ## ๐Ÿ“š Documentation Index
8
+
9
+ 1. **[Getting Started](./getting-started.md)**
10
+ - Installation & peer dependencies
11
+ - 5-minute Quickstart with SQLite & Cloud
12
+ 2. **[Architecture & Concepts](./architecture.md)**
13
+ - The Transactional Outbox Pattern
14
+ - 0ms local reads & writes
15
+ - SyncWorker pipeline & infinite loop safety
16
+ 3. **[Configuration Reference](./configuration.md)**
17
+ - `defineSyncConfig()` and `LocalLiteConfig` options
18
+ - User data isolation (`syncScope`), outbox coalescing, JSON auto-hydration, and advanced retry policies
19
+ 4. **[Client API & Query Builder](./client-api.md)**
20
+ - Atomic dual-write CRUD (`insert`, `update`, `delete`, `mutate`, `trackMutation`)
21
+ - Batches (`batch`) and custom transactions (`transaction`)
22
+ - Fluent `QueryBuilder` (`from`, `select`, `join`, `where`, `groupBy`, `orderBy`)
23
+ - Native SQL aggregations (`count`, `sum`, `avg`, `aggregate`)
24
+ - Telemetry & outbox management (`getMetrics`, `retryFailedMutations`, `clearFailedMutations`)
25
+ 5. **[Fast Key-Value & Encrypted Preferences](./kv.md)**
26
+ - Typed storage for strings, numbers, booleans, and JSON objects (`client.kv`)
27
+ - TTL expiration with lazy cleanup and batch pruning
28
+ - Zero-Knowledge client-side encrypted secrets (AES-256-GCM + PBKDF2)
29
+ - Reactive `useKV()` React hook
30
+ 6. **[Instant Full-Text Search](./search.md)**
31
+ - Native SQLite FTS5 engine integration (`client.search`)
32
+ - Prefix matching, BM25 ranking, and highlighted `<mark>` snippets
33
+ - Reactive `useSearch()` React hook with automatic debouncing
34
+ 7. **[Offline Media & Blob Storage](./storage.md)**
35
+ - Decoupled binary storage from SQLite table queries (`client.storage`)
36
+ - Local filesystem and in-memory file drivers with SHA-256 integrity verification
37
+ - Background cloud sync queue for S3, Supabase, Cloudinary, and Firebase Storage
38
+ 8. **[Offline Job Scheduler & Background Cron](./scheduler.md)**
39
+ - Persistent offline job scheduling surviving app restarts (`client.scheduler`)
40
+ - Human expressions (`'daily'`, `'hourly'`, `'every 15 minutes'`) and 5-part cron
41
+ - Run history tracking, duration telemetry, and automatic error logging
42
+ 9. **[Local SQLite Adapters](./adapters-local.md)**
43
+ - Expo SQLite (`expo-sqlite`)
44
+ - Bare React Native (`@op-engineering/op-sqlite`)
45
+ - Node.js / Electron (`better-sqlite3`)
46
+ - Built-in Node 22+ (`node:sqlite`)
47
+ - Edge / Turso (`@libsql/client`)
48
+ - Web / Browser (`sql.js`)
49
+ 10. **[Remote Backend Adapters](./adapters-remote.md)**
50
+ - Supabase (Postgres + Realtime)
51
+ - Convex (Reactive documents + RPCs)
52
+ - Firebase / Firestore
53
+ - Memory Demo (Mock testing without cloud)
54
+ - Building custom backend adapters
55
+ 11. **[React & Expo Hooks](./react-hooks.md)**
56
+ - `useLiveQuery()`: Zero-SQL single table reactive query
57
+ - `useLiveQueries()`: Parallel multi-table queries with single atomic commit
58
+ - `useLiveRow()`: Targeted single-record live query with row-level invalidation
59
+ - `useLiveInfiniteQuery()`: Paginated infinite scrolling live query
60
+ - `useKV()`: Reactive state binding for key-value preferences
61
+ - `useSearch()`: Debounced instant full-text search hook
62
+ - `useMutations()`: Null-safe memoized mutation helper methods
63
+ - `useSyncStatus()`: Real-time sync engine & outbox queue inspector
64
+ - `useDatabaseMaintenance()`: Reactive storage stats, outbox pruning, VACUUM, and WAL checkpoints
65
+ - `<SyncInspector />` and `<BenchmarkModal />` (from `local-lite/devtools`): Developer UI debugging tools
66
+ 12. **[Authentication (Google, Microsoft, GitHub, Apple)](./auth.md)**
67
+ - Zero-backend OAuth 2.0 PKCE authentication
68
+ - Automatic token refreshing & user profile fetching
69
+ - Microsoft Graph & OneDrive integration
70
+ - GitHub OAuth with verified email resolution
71
+ - Sign in with Apple (Native iOS & OAuth)
72
+ - Pluggable storage adapters (AsyncStorage, SecureStore, MMKV)
73
+ 13. **[Google Sign-In & Drive Guide](./google-auth.md)**
74
+ - Dedicated guide for zero-backend Google authentication
75
+ - Unified Google Drive cloud backup synergy
76
+ 14. **[Conflict Resolution & Field Merge](./conflict-resolution.md)**
77
+ - Smart 3-Way field-level merge (`createFieldMergeResolver`)
78
+ - Last-Write-Wins (LWW)
79
+ - Client-Wins & Server-Wins
80
+ - Custom conflict resolvers
81
+ 15. **[Database Backups & Zero-Knowledge Encryption](./backups.md)**
82
+ - Google Drive and Microsoft OneDrive sandboxed backups
83
+ - Zero-Knowledge client-side encryption (AES-256-GCM + PBKDF2)
84
+ - React backup hooks (`useGoogleDriveBackup`, `useOneDriveBackup`)
85
+ - Universal binary database snapshots (`exportDatabase`, `importDatabase`)
86
+ 16. **[Maintenance & Data Portability](./maintenance-portability.md)**
87
+ - Storage breakdown, outbox pruning, VACUUM, and WAL checkpoints
88
+ - PRAGMA analyze and structural integrity checks
89
+ - Universal JSON & RFC-4180 CSV export and import
90
+ 17. **[Action Outbox & Email Queue](./actions-email.md)**
91
+ - 0ms offline transactional email enqueuing
92
+ - Generic action dispatchers (push notifications, webhooks, analytics)
93
+ - Idempotency deduplication, TTL expiration, and crash recovery
94
+ 18. **[API Keys & Signed Tokens](./api-keys.md)**
95
+ - Checksummed API key generation & verification (Stripe/GitHub pattern)
96
+ - HMAC-SHA256 signed tokens with expiration and renewal
97
+ - Local SQLite API key manager (`client.keys`)
98
+
99
+ ---
100
+
101
+ ## ๐Ÿ’ก Core Philosophy
102
+
103
+ * **Local-First By Default:** The app writes to and reads from local SQLite first. Operations never stall on slow cell connections or outages.
104
+ * **Guaranteed Durability:** Every mutate operation executes in an atomic transaction that updates the user table and inserts a mutation into `sync_outbox` simultaneously. If the device restarts or loses power, pending changes are never lost.
105
+ * **Zero Lock-In:** Switch seamlessly between Supabase, Convex, Firestore, or your own REST/GraphQL server without rewriting your UI layer.
106
+ 5. **[Server API Routing](./server.md)**
107
+ - Create server route handlers from one typed config
108
+ - Add middleware and use provider-specific server services
@@ -0,0 +1,22 @@
1
+ * [๐Ÿ  Home](README.md)
2
+ * [๐Ÿš€ Getting Started](getting-started.md)
3
+ * [๐Ÿ›๏ธ Architecture & Concepts](architecture.md)
4
+ * [โš™๏ธ Configuration](configuration.md)
5
+ * [โš ๏ธ Breaking Changes](breaking-changes.md)
6
+ * [๐Ÿ’ป Client API & Query Builder](client-api.md)
7
+ * [โšก Fast Key-Value & Preferences](kv.md)
8
+ * [๐Ÿ” Full-Text Search (FTS5)](search.md)
9
+ * [๐Ÿ“ Offline Media & Blob Storage](storage.md)
10
+ * [โฐ Offline Job Scheduler & Cron](scheduler.md)
11
+ * [๐Ÿ“จ Action Outbox & Email Queue](actions-email.md)
12
+ * [๐Ÿ’พ Local SQLite Adapters](adapters-local.md)
13
+ * [โ˜๏ธ Remote Cloud Adapters](adapters-remote.md)
14
+ * [โš›๏ธ React & Expo Hooks](react-hooks.md)
15
+ * [๐Ÿ”‘ Authentication (Google, Microsoft, GitHub, Apple)](auth.md)
16
+ * [๐Ÿ›ก๏ธ Offline Session Management](session.md)
17
+ * [๐Ÿ” API Keys & Signed Tokens](api-keys.md)
18
+ * [๐ŸŒ Google Sign-In & Drive Guide](google-auth.md)
19
+ * [๐Ÿ”€ Conflict Resolution & Field Merge](conflict-resolution.md)
20
+ * [๐Ÿ“ฆ Cloud Backups & Zero-Knowledge Encryption](backups.md)
21
+ * [๐Ÿงน Maintenance & Universal Data Portability](maintenance-portability.md)
22
+ * [Server API Routing](server.md)