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
@@ -13,6 +13,17 @@ const REACT_NATIVE_PKG = ['react', 'native'].join('-');
13
13
  const PUSH_BATCH_SIZE = 50;
14
14
  /** Maximum incoming delta changes applied in a single database transaction. */
15
15
  const DELTA_CHUNK_SIZE = 250;
16
+ function stableScopeValue(value) {
17
+ if (Array.isArray(value))
18
+ return value.map(stableScopeValue);
19
+ if (value && typeof value === 'object') {
20
+ return Object.fromEntries(Object.keys(value).sort().map((key) => [key, stableScopeValue(value[key])]));
21
+ }
22
+ return value;
23
+ }
24
+ function getScopeCursorKey(scope) {
25
+ return scope === undefined ? 'last_synced_at' : `last_synced_at:scope:${JSON.stringify(stableScopeValue(scope))}`;
26
+ }
16
27
  class SyncWorker {
17
28
  db;
18
29
  remote;
@@ -42,6 +53,8 @@ class SyncWorker {
42
53
  isPulling = false;
43
54
  lastPulledTimestamp = 0;
44
55
  cursorLoaded = false;
56
+ lastSyncedAtKey = 'last_synced_at';
57
+ pullRequested = false;
45
58
  deltaQueue = Promise.resolve();
46
59
  statusRun;
47
60
  statusRerunRequested = false;
@@ -129,7 +142,7 @@ class SyncWorker {
129
142
  this.applyDeltasLocally(deltas, { advanceCursor: false }).catch((err) => {
130
143
  this.logger.error('Error applying live remote deltas:', err);
131
144
  });
132
- });
145
+ }, this.syncScope);
133
146
  if (typeof unsubscribe === 'function')
134
147
  this.remoteUnsubscribe = unsubscribe;
135
148
  // Subscribe to network connectivity changes (only pull on actual offline -> online transition)
@@ -316,6 +329,10 @@ class SyncWorker {
316
329
  */
317
330
  setSyncScope(scope) {
318
331
  this.syncScope = scope;
332
+ this.remote.setSyncScope?.(scope);
333
+ if (this.automaticSync && !this.isPaused) {
334
+ this.pullRemoteChanges().catch((err) => this.logger.error('Error pulling after sync scope change:', err));
335
+ }
319
336
  }
320
337
  async isOnline() {
321
338
  try {
@@ -526,8 +543,12 @@ class SyncWorker {
526
543
  * Pulls delta changes from the remote backend since lastPulledTimestamp.
527
544
  */
528
545
  async pullRemoteChanges() {
529
- if (this.isPulling || this.isPaused)
546
+ if (this.isPaused)
547
+ return;
548
+ if (this.isPulling) {
549
+ this.pullRequested = true;
530
550
  return;
551
+ }
531
552
  this.isPulling = true;
532
553
  this.emitStatus();
533
554
  const startTime = Date.now();
@@ -535,14 +556,13 @@ class SyncWorker {
535
556
  if (!(await this.isOnline()))
536
557
  return;
537
558
  this.totalPullCycles++;
538
- if (!this.cursorLoaded) {
539
- this.lastPulledTimestamp = await meta_store_js_1.MetaStore.getLastSyncedAt(this.db);
540
- this.cursorLoaded = true;
541
- }
542
559
  const scope = typeof this.syncScope === 'function' ? await this.syncScope() : this.syncScope;
560
+ const cursorKey = getScopeCursorKey(scope);
561
+ await this.loadCursor(cursorKey);
562
+ const sinceTimestamp = this.lastPulledTimestamp;
543
563
  const deltas = scope !== undefined
544
- ? await this.remote.fetchChanges(this.lastPulledTimestamp, scope)
545
- : await this.remote.fetchChanges(this.lastPulledTimestamp);
564
+ ? await this.remote.fetchChanges(sinceTimestamp, scope)
565
+ : await this.remote.fetchChanges(sinceTimestamp);
546
566
  const durationMs = Date.now() - startTime;
547
567
  this.lastPullDurationMs = durationMs;
548
568
  this.lastPullTimestamp = Date.now();
@@ -550,10 +570,11 @@ class SyncWorker {
550
570
  const changesCount = deltas?.changes?.length || 0;
551
571
  if (deltas) {
552
572
  this.totalPulledDeltas += changesCount;
553
- await this.applyDeltasLocally(deltas);
554
- if (deltas.timestamp && deltas.timestamp > this.lastPulledTimestamp) {
555
- this.lastPulledTimestamp = deltas.timestamp;
556
- await meta_store_js_1.MetaStore.setLastSyncedAt(this.db, deltas.timestamp);
573
+ await this.applyDeltasLocally(deltas, { cursorKey });
574
+ if (deltas.timestamp && deltas.timestamp > sinceTimestamp) {
575
+ if (cursorKey === this.lastSyncedAtKey)
576
+ this.lastPulledTimestamp = deltas.timestamp;
577
+ await meta_store_js_1.MetaStore.setLastSyncedAt(this.db, deltas.timestamp, cursorKey);
557
578
  }
558
579
  }
559
580
  const pullEvent = {
@@ -584,6 +605,10 @@ class SyncWorker {
584
605
  finally {
585
606
  this.isPulling = false;
586
607
  this.emitStatus();
608
+ if (this.pullRequested && !this.isPaused) {
609
+ this.pullRequested = false;
610
+ void this.pullRemoteChanges();
611
+ }
587
612
  }
588
613
  }
589
614
  /**
@@ -592,18 +617,21 @@ class SyncWorker {
592
617
  */
593
618
  async applyDeltasLocally(deltas, options = {}) {
594
619
  const task = async () => {
595
- await this.getLastPulledTimestamp();
596
- await this.processDeltasLocally(options.advanceCursor === false ? { ...deltas, timestamp: 0 } : deltas);
620
+ const cursorKey = options.cursorKey ?? this.lastSyncedAtKey;
621
+ if (options.advanceCursor !== false)
622
+ await this.loadCursor(cursorKey);
623
+ await this.processDeltasLocally(options.advanceCursor === false ? { ...deltas, timestamp: 0 } : deltas, cursorKey);
597
624
  };
598
625
  const next = this.deltaQueue.then(task, task);
599
626
  this.deltaQueue = next.catch(() => { });
600
627
  return await next;
601
628
  }
602
- async processDeltasLocally(deltas) {
629
+ async processDeltasLocally(deltas, cursorKey = this.lastSyncedAtKey) {
603
630
  if (!deltas.changes || deltas.changes.length === 0) {
604
- if (deltas.timestamp && deltas.timestamp > this.lastPulledTimestamp) {
605
- await meta_store_js_1.MetaStore.setLastSyncedAt(this.db, deltas.timestamp);
606
- this.lastPulledTimestamp = deltas.timestamp;
631
+ if (deltas.timestamp && (cursorKey !== this.lastSyncedAtKey || deltas.timestamp > this.lastPulledTimestamp)) {
632
+ await meta_store_js_1.MetaStore.setLastSyncedAt(this.db, deltas.timestamp, cursorKey);
633
+ if (cursorKey === this.lastSyncedAtKey)
634
+ this.lastPulledTimestamp = deltas.timestamp;
607
635
  }
608
636
  return;
609
637
  }
@@ -670,9 +698,10 @@ class SyncWorker {
670
698
  });
671
699
  }
672
700
  // Advance durable checkpoint only when a valid pull timestamp was provided
673
- if (isLastChunk && deltas.timestamp && deltas.timestamp > this.lastPulledTimestamp) {
674
- await meta_store_js_1.MetaStore.setLastSyncedAt(tx, deltas.timestamp);
675
- this.lastPulledTimestamp = deltas.timestamp;
701
+ if (isLastChunk && deltas.timestamp && (cursorKey !== this.lastSyncedAtKey || deltas.timestamp > this.lastPulledTimestamp)) {
702
+ await meta_store_js_1.MetaStore.setLastSyncedAt(tx, deltas.timestamp, cursorKey);
703
+ if (cursorKey === this.lastSyncedAtKey)
704
+ this.lastPulledTimestamp = deltas.timestamp;
676
705
  }
677
706
  });
678
707
  // Emit events after chunk commit
@@ -684,22 +713,36 @@ class SyncWorker {
684
713
  await new Promise((resolve) => setTimeout(resolve, 0));
685
714
  }
686
715
  }
687
- if (deltas.timestamp) {
716
+ if (deltas.timestamp && cursorKey === this.lastSyncedAtKey) {
688
717
  this.lastPulledTimestamp = Math.max(this.lastPulledTimestamp, deltas.timestamp);
689
718
  }
690
719
  }
691
720
  async getLastPulledTimestamp() {
721
+ const scope = typeof this.syncScope === 'function' ? await this.syncScope() : this.syncScope;
722
+ await this.loadCursor(getScopeCursorKey(scope));
723
+ return this.lastPulledTimestamp;
724
+ }
725
+ async loadCursor(key) {
726
+ if (key !== this.lastSyncedAtKey) {
727
+ this.lastSyncedAtKey = key;
728
+ this.cursorLoaded = false;
729
+ this.lastPulledTimestamp = 0;
730
+ }
692
731
  if (!this.cursorLoaded) {
693
- this.lastPulledTimestamp = await meta_store_js_1.MetaStore.getLastSyncedAt(this.db);
732
+ this.lastPulledTimestamp = await meta_store_js_1.MetaStore.getLastSyncedAt(this.db, key);
694
733
  this.cursorLoaded = true;
695
734
  }
696
- return this.lastPulledTimestamp;
697
735
  }
698
736
  async resetSyncCursor() {
699
- await meta_store_js_1.MetaStore.clearLastSyncedAt(this.db);
737
+ await meta_store_js_1.MetaStore.clearLastSyncedAt(this.db, this.lastSyncedAtKey);
700
738
  this.lastPulledTimestamp = 0;
701
739
  this.cursorLoaded = true;
702
740
  }
741
+ /** Clears a stale push error after an explicit sync stop/reconfiguration. */
742
+ clearPushError() {
743
+ this.lastPushError = null;
744
+ this.emitStatus();
745
+ }
703
746
  /**
704
747
  * Collects real-time engine telemetry snapshot.
705
748
  */
@@ -16,18 +16,7 @@ class SearchStore {
16
16
  // row_id is UNINDEXED in FTS5 so it does not pollute search tokens
17
17
  const columnDefs = ['row_id UNINDEXED', ...cols].join(', ');
18
18
  const sql = `CREATE VIRTUAL TABLE IF NOT EXISTS ${ftsTable} USING fts5(${columnDefs}, tokenize='${tokenize}');`;
19
- try {
20
- await db.execute(sql);
21
- }
22
- catch (err) {
23
- // In case tokenize='unicode61' isn't supported by legacy SQLite build, retry without tokenize option
24
- if (err?.message?.includes('tokenize') || err?.message?.includes('unknown tokenizer')) {
25
- await db.execute(`CREATE VIRTUAL TABLE IF NOT EXISTS ${ftsTable} USING fts5(${columnDefs});`);
26
- }
27
- else {
28
- throw err;
29
- }
30
- }
19
+ await db.execute(sql);
31
20
  }
32
21
  /**
33
22
  * Drops the FTS5 virtual table.
@@ -1,59 +1,7 @@
1
1
  import { FileDriver } from './types.js';
2
- export interface ExpoFileSystemModule {
3
- File?: any;
4
- Directory?: any;
5
- Paths?: any;
6
- documentDirectory?: string | null;
7
- cacheDirectory?: string | null;
8
- EncodingType?: {
9
- UTF8: string;
10
- Base64: string;
11
- };
12
- getInfoAsync?(fileUri: string, options?: {
13
- md5?: boolean;
14
- size?: boolean;
15
- }): Promise<{
16
- exists: boolean;
17
- isDirectory?: boolean;
18
- size?: number;
19
- uri?: string;
20
- }>;
21
- writeAsStringAsync?(fileUri: string, contents: string, options?: {
22
- encoding?: string;
23
- }): Promise<void>;
24
- readAsStringAsync?(fileUri: string, options?: {
25
- encoding?: string;
26
- length?: number;
27
- position?: number;
28
- }): Promise<string>;
29
- makeDirectoryAsync?(fileUri: string, options?: {
30
- intermediates?: boolean;
31
- }): Promise<void>;
32
- deleteAsync?(fileUri: string, options?: {
33
- idempotent?: boolean;
34
- }): Promise<void>;
35
- copyAsync?(options: {
36
- from: string;
37
- to: string;
38
- }): Promise<void>;
39
- moveAsync?(options: {
40
- from: string;
41
- to: string;
42
- }): Promise<void>;
43
- downloadAsync?(url: string, fileUri: string, options?: {
44
- md5?: boolean;
45
- headers?: Record<string, string>;
46
- sessionType?: any;
47
- }): Promise<{
48
- uri: string;
49
- status: number;
50
- headers: Record<string, string>;
51
- md5?: string;
52
- }>;
53
- }
54
2
  export interface ExpoFileDriverOptions {
55
3
  /**
56
- * The modern `File` class from `expo-file-system` (SDK >57/58).
4
+ * The modern `File` class from `expo-file-system` (SDK 57+).
57
5
  * e.g. `import { File } from 'expo-file-system'`
58
6
  */
59
7
  File?: any;
@@ -67,11 +15,6 @@ export interface ExpoFileDriverOptions {
67
15
  * e.g. `import { Paths } from 'expo-file-system'`
68
16
  */
69
17
  Paths?: any;
70
- /**
71
- * The `expo-file-system` module instance.
72
- * e.g. `import * as FileSystem from 'expo-file-system'`
73
- */
74
- fileSystem?: ExpoFileSystemModule | any;
75
18
  /**
76
19
  * Base directory path or `Directory` instance for storing files.
77
20
  * Defaults to: `new Directory(Paths.document, 'local-lite-blobs')`
@@ -91,30 +34,25 @@ export declare function bytesToBase64(bytes: Uint8Array): string;
91
34
  export declare function base64ToBytes(base64: string): Uint8Array;
92
35
  /**
93
36
  * FileDriver implementation for Expo / React Native environments.
94
- * Uses modern Expo (>57/58) `File`, `Directory`, and `Paths` APIs when available,
95
- * with seamless fallback for legacy `expo-file-system` environments.
37
+ * Uses the Expo SDK 58+ `File`, `Directory`, and `Paths` APIs.
96
38
  */
97
39
  export declare class ExpoFileDriver implements FileDriver {
98
40
  private FileClass?;
99
41
  private DirectoryClass?;
100
42
  private PathsObj?;
101
- private legacyFs?;
102
43
  private baseDirOption?;
103
44
  private useCache;
104
45
  private resolvedBaseDir;
105
46
  private resolvedBaseDirPath;
106
- private ensuredDirs;
107
47
  constructor(options?: ExpoFileDriverOptions);
108
48
  private resolveClasses;
109
49
  private getBaseDirectory;
110
50
  /**
111
- * Resolves a key to a modern Expo `File` instance (if File class is available)
112
- * or a string URI path.
51
+ * Resolves a key to a modern Expo `File` instance.
113
52
  */
114
- private resolveFileOrUri;
53
+ private resolveFile;
115
54
  resolveUri(key: string): Promise<string>;
116
55
  getUri(key: string): Promise<string>;
117
- private ensureDirectory;
118
56
  write(key: string, data: Uint8Array): Promise<string>;
119
57
  read(key: string): Promise<Uint8Array | null>;
120
58
  delete(key: string): Promise<void>;