local-lite 0.0.30 โ 0.1.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.
- package/README.md +32 -20
- package/bin/local-lite.mjs +62 -0
- package/dist/adapters/remote/firestore.d.ts +2 -1
- package/dist/adapters/remote/firestore.js +21 -3
- package/dist/adapters/remote/index.d.ts +2 -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 +1 -3
- package/dist/core/client.js +4 -11
- 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 +7 -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/storage/expo.js
CHANGED
|
@@ -31,24 +31,23 @@ function base64ToBytes(base64) {
|
|
|
31
31
|
}
|
|
32
32
|
/**
|
|
33
33
|
* FileDriver implementation for Expo / React Native environments.
|
|
34
|
-
* Uses
|
|
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
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
this.
|
|
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
|
-
|
|
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
|
-
|
|
70
|
-
|
|
71
|
-
|
|
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
|
-
|
|
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
|
|
100
|
-
|
|
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
|
|
118
|
-
* or a string URI path.
|
|
110
|
+
* Resolves a key to a modern Expo `File` instance.
|
|
119
111
|
*/
|
|
120
|
-
async
|
|
121
|
-
|
|
112
|
+
async resolveFile(key) {
|
|
113
|
+
await this.resolveClasses();
|
|
122
114
|
const baseDir = await this.getBaseDirectory();
|
|
123
115
|
const safeKey = key.replace(/\.\./g, '_').replace(/^[/\\?%*:|"<>]+/, '');
|
|
124
|
-
|
|
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
|
-
|
|
132
|
-
|
|
133
|
-
|
|
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
|
-
|
|
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
|
-
:
|
|
153
|
-
|
|
154
|
-
|
|
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
|
|
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
|
|
183
|
-
|
|
184
|
-
|
|
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
|
-
|
|
202
|
-
|
|
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
|
-
|
|
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
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
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
|
|
264
|
-
|
|
265
|
-
|
|
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
|
|
287
|
-
|
|
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
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
|
|
316
|
-
|
|
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
|
|
346
|
-
const
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
|
|
352
|
-
|
|
353
|
-
|
|
354
|
-
|
|
355
|
-
|
|
356
|
-
|
|
357
|
-
|
|
358
|
-
|
|
359
|
-
|
|
360
|
-
|
|
361
|
-
|
|
362
|
-
|
|
363
|
-
|
|
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
|
|
381
|
-
|
|
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
|
-
|
|
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
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
|
package/docs/_sidebar.md
ADDED
|
@@ -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)
|