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.
- package/README.md +25 -20
- package/dist/adapters/remote/convex.d.ts +7 -2
- package/dist/adapters/remote/convex.js +73 -40
- package/dist/adapters/remote/firestore.d.ts +2 -1
- package/dist/adapters/remote/firestore.js +21 -3
- package/dist/adapters/remote/index.d.ts +3 -2
- package/dist/adapters/remote/supabase.d.ts +1 -1
- package/dist/config/index.js +3 -1
- package/dist/config/types.d.ts +0 -5
- package/dist/core/client.d.ts +7 -3
- package/dist/core/client.js +14 -11
- package/dist/core/meta-store.d.ts +3 -3
- package/dist/core/meta-store.js +6 -6
- package/dist/core/outbox-store.d.ts +9 -0
- package/dist/core/outbox-store.js +31 -0
- package/dist/core/sync-worker.d.ts +6 -0
- package/dist/core/sync-worker.js +68 -25
- package/dist/search/store.js +1 -12
- package/dist/storage/expo.d.ts +4 -66
- package/dist/storage/expo.js +104 -261
- package/dist/utils/sql.js +1 -1
- package/docs/.nojekyll +1 -0
- package/docs/README.md +108 -0
- package/docs/_sidebar.md +22 -0
- package/docs/actions-email.md +222 -0
- package/docs/adapters-local.md +272 -0
- package/docs/adapters-remote.md +291 -0
- package/docs/api-keys.md +114 -0
- package/docs/architecture.md +106 -0
- package/docs/auth.md +259 -0
- package/docs/backups.md +214 -0
- package/docs/breaking-changes.md +147 -0
- package/docs/client-api.md +412 -0
- package/docs/configuration.md +228 -0
- package/docs/conflict-resolution.md +78 -0
- package/docs/getting-started.md +190 -0
- package/docs/google-auth.md +234 -0
- package/docs/index.html +166 -0
- package/docs/kv.md +89 -0
- package/docs/maintenance-portability.md +133 -0
- package/docs/react-hooks.md +457 -0
- package/docs/scheduler.md +81 -0
- package/docs/search.md +71 -0
- package/docs/server.md +101 -0
- package/docs/session.md +129 -0
- package/docs/storage.md +265 -0
- package/package.json +3 -1
- package/skills/local-lite-custom-adapter/SKILL.md +59 -0
- package/skills/local-lite-setup/SKILL.md +21 -0
- package/skills/local-lite-upgrade/SKILL.md +16 -0
package/dist/core/sync-worker.js
CHANGED
|
@@ -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.
|
|
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(
|
|
545
|
-
: await this.remote.fetchChanges(
|
|
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 >
|
|
555
|
-
|
|
556
|
-
|
|
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
|
-
|
|
596
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
*/
|
package/dist/search/store.js
CHANGED
|
@@ -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
|
-
|
|
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.
|
package/dist/storage/expo.d.ts
CHANGED
|
@@ -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
|
|
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
|
|
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
|
|
112
|
-
* or a string URI path.
|
|
51
|
+
* Resolves a key to a modern Expo `File` instance.
|
|
113
52
|
*/
|
|
114
|
-
private
|
|
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>;
|