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/README.md
CHANGED
|
@@ -64,9 +64,7 @@ remain configurable; the existing default conflict strategy is last-write-wins.
|
|
|
64
64
|
- `autoSchema` now defaults to `false` in the configuration factory as well as the
|
|
65
65
|
core constructor. Set `autoSchema: true` to retain inferred schema behavior.
|
|
66
66
|
- Versioned `schemaMigrations` run transactionally before sync starts, including
|
|
67
|
-
when initialization is deferred with `autoInitialize: false`.
|
|
68
|
-
`migrations` option remains available for legacy idempotent SQL that runs on
|
|
69
|
-
every initialization.
|
|
67
|
+
when initialization is deferred with `autoInitialize: false`.
|
|
70
68
|
- `initialize()` is safe to call repeatedly or concurrently. After `stop()`, call
|
|
71
69
|
`client.syncWorker.start()` to resume. Mutations after stop remain queued.
|
|
72
70
|
- `autoStart: false` prepares storage without automatic sync. Explicit push/pull
|
|
@@ -74,8 +72,30 @@ remain configurable; the existing default conflict strategy is last-write-wins.
|
|
|
74
72
|
- Realtime changes update local rows without advancing the durable pull cursor.
|
|
75
73
|
Custom pull adapters must return complete batches through their checkpoint and
|
|
76
74
|
reject partial failures. Supabase table failures now reject the pull.
|
|
77
|
-
- Custom realtime adapters
|
|
78
|
-
|
|
75
|
+
- Custom realtime adapters must return an unsubscribe function; stopped workers
|
|
76
|
+
ignore callbacks from a previous subscription.
|
|
77
|
+
|
|
78
|
+
For an application-level upgrade checklist or AI-assisted code review, see the
|
|
79
|
+
[Breaking Changes and AI Code-Review Guide](./docs/breaking-changes.md).
|
|
80
|
+
|
|
81
|
+
### Breaking changes in 0.0.30
|
|
82
|
+
|
|
83
|
+
- The repeat-on-initialize `migrations` option has been removed. Move SQL into
|
|
84
|
+
versioned `schemaMigrations`.
|
|
85
|
+
- `ExpoFileDriver` now requires the Expo SDK 58+ `File`, `Directory`, and `Paths`
|
|
86
|
+
APIs. Replace `fileSystem` injection with those named options.
|
|
87
|
+
- Custom `RemoteDBAdapter.subscribeToLiveChanges()` implementations must return
|
|
88
|
+
a cleanup function, including when no subscription is established.
|
|
89
|
+
- `_migrations` is no longer treated as an internal table name.
|
|
90
|
+
- FTS table creation no longer retries without the configured tokenizer; SQLite
|
|
91
|
+
tokenizer errors now propagate.
|
|
92
|
+
|
|
93
|
+
## AI Skills
|
|
94
|
+
|
|
95
|
+
The package ships [Agent Skills](./skills) that AI coding assistants can load:
|
|
96
|
+
`local-lite-setup`, `local-lite-custom-adapter` and `local-lite-upgrade`. Copy
|
|
97
|
+
the folders from `node_modules/local-lite/skills/` into `.github/skills/`
|
|
98
|
+
(Copilot) or `.claude/skills/` (Claude Code).
|
|
79
99
|
|
|
80
100
|
## Features
|
|
81
101
|
|
|
@@ -522,21 +542,6 @@ SyncWorker
|
|
|
522
542
|
|
|
523
543
|
---
|
|
524
544
|
|
|
525
|
-
## Example App
|
|
526
|
-
|
|
527
|
-
An interactive Expo app is included in the [`example/`](./example) directory demonstrating:
|
|
528
|
-
- Rental property & tenant management application
|
|
529
|
-
- Live SQLite reads and atomic dual-writes
|
|
530
|
-
- Network online/offline toggle simulation
|
|
531
|
-
- Real-time `sync_outbox` inspector
|
|
532
|
-
- Simulated server delta broadcasts
|
|
533
|
-
|
|
534
|
-
To run the example:
|
|
535
|
-
```bash
|
|
536
|
-
cd example
|
|
537
|
-
npm start
|
|
538
|
-
```
|
|
539
|
-
|
|
540
545
|
---
|
|
541
546
|
|
|
542
547
|
## Testing
|
|
@@ -47,6 +47,9 @@ export declare class ConvexRemoteAdapter implements RemoteDBAdapter {
|
|
|
47
47
|
private deletedColumn;
|
|
48
48
|
private updatedAtColumn;
|
|
49
49
|
private unsubscribeLive?;
|
|
50
|
+
private liveCallback?;
|
|
51
|
+
private liveScope?;
|
|
52
|
+
private liveGeneration;
|
|
50
53
|
logger: SyncLogger;
|
|
51
54
|
constructor(client: any, options?: ConvexRemoteAdapterOptions);
|
|
52
55
|
/**
|
|
@@ -60,11 +63,13 @@ export declare class ConvexRemoteAdapter implements RemoteDBAdapter {
|
|
|
60
63
|
/**
|
|
61
64
|
* Fetches delta changes from Convex since a given timestamp.
|
|
62
65
|
*/
|
|
63
|
-
fetchChanges(sinceTimestamp: number): Promise<DeltaChanges>;
|
|
66
|
+
fetchChanges(sinceTimestamp: number, scope?: Record<string, any>): Promise<DeltaChanges>;
|
|
64
67
|
/**
|
|
65
68
|
* Subscribes to live reactive query updates from Convex.
|
|
66
69
|
*/
|
|
67
|
-
subscribeToLiveChanges(callback: (changes: DeltaChanges) => void): void;
|
|
70
|
+
subscribeToLiveChanges(callback: (changes: DeltaChanges) => void, scope?: Record<string, any> | (() => Record<string, any> | Promise<Record<string, any>>)): () => void;
|
|
71
|
+
setSyncScope(scope?: Record<string, any> | (() => Record<string, any> | Promise<Record<string, any>>)): void;
|
|
72
|
+
private refreshLiveSubscription;
|
|
68
73
|
/**
|
|
69
74
|
* Cleans up live subscriptions.
|
|
70
75
|
*/
|
|
@@ -34,6 +34,9 @@ class ConvexRemoteAdapter {
|
|
|
34
34
|
deletedColumn;
|
|
35
35
|
updatedAtColumn;
|
|
36
36
|
unsubscribeLive;
|
|
37
|
+
liveCallback;
|
|
38
|
+
liveScope;
|
|
39
|
+
liveGeneration = 0;
|
|
37
40
|
logger;
|
|
38
41
|
constructor(client, options = {}) {
|
|
39
42
|
if (!client) {
|
|
@@ -90,11 +93,12 @@ class ConvexRemoteAdapter {
|
|
|
90
93
|
/**
|
|
91
94
|
* Fetches delta changes from Convex since a given timestamp.
|
|
92
95
|
*/
|
|
93
|
-
async fetchChanges(sinceTimestamp) {
|
|
96
|
+
async fetchChanges(sinceTimestamp, scope) {
|
|
94
97
|
try {
|
|
95
98
|
const res = await this.client.query(this.pullQuery, {
|
|
96
99
|
sinceTimestamp,
|
|
97
100
|
tables: this.tables,
|
|
101
|
+
...(scope ? { scope } : {}),
|
|
98
102
|
});
|
|
99
103
|
if (!res) {
|
|
100
104
|
return { timestamp: sinceTimestamp, changes: [] };
|
|
@@ -145,56 +149,85 @@ class ConvexRemoteAdapter {
|
|
|
145
149
|
/**
|
|
146
150
|
* Subscribes to live reactive query updates from Convex.
|
|
147
151
|
*/
|
|
148
|
-
subscribeToLiveChanges(callback) {
|
|
149
|
-
|
|
152
|
+
subscribeToLiveChanges(callback, scope) {
|
|
153
|
+
this.liveCallback = callback;
|
|
154
|
+
this.liveScope = scope;
|
|
155
|
+
this.refreshLiveSubscription();
|
|
156
|
+
return () => {
|
|
157
|
+
if (this.liveCallback !== callback)
|
|
158
|
+
return;
|
|
159
|
+
this.liveCallback = undefined;
|
|
160
|
+
this.destroy();
|
|
161
|
+
};
|
|
162
|
+
}
|
|
163
|
+
setSyncScope(scope) {
|
|
164
|
+
this.liveScope = scope;
|
|
165
|
+
if (this.liveCallback)
|
|
166
|
+
this.refreshLiveSubscription();
|
|
167
|
+
}
|
|
168
|
+
refreshLiveSubscription() {
|
|
169
|
+
this.unsubscribeLive?.();
|
|
170
|
+
this.unsubscribeLive = undefined;
|
|
171
|
+
const generation = ++this.liveGeneration;
|
|
172
|
+
const callback = this.liveCallback;
|
|
173
|
+
if (!callback || typeof this.client.onUpdate !== 'function')
|
|
150
174
|
return;
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
changes
|
|
164
|
-
|
|
175
|
+
const subscribe = (scope) => {
|
|
176
|
+
if (generation !== this.liveGeneration || this.liveCallback !== callback)
|
|
177
|
+
return;
|
|
178
|
+
try {
|
|
179
|
+
const unsubscribe = this.client.onUpdate(this.pullQuery, { sinceTimestamp: Date.now() - 2000, tables: this.tables, ...(scope ? { scope } : {}) }, (data) => {
|
|
180
|
+
if (generation !== this.liveGeneration || !data)
|
|
181
|
+
return;
|
|
182
|
+
if (data.changes && Array.isArray(data.changes)) {
|
|
183
|
+
callback({ timestamp: Number(data.timestamp || Date.now()), changes: data.changes });
|
|
184
|
+
return;
|
|
185
|
+
}
|
|
186
|
+
if (Array.isArray(data) && data.length > 0) {
|
|
187
|
+
const changes = data.map((row) => {
|
|
188
|
+
const isSoftDeleted = Boolean(row[this.deletedColumn] === true);
|
|
189
|
+
const op = isSoftDeleted ? 'DELETE' : 'UPDATE';
|
|
190
|
+
const rowTime = getRowTimestamp(row[this.updatedAtColumn], row._creationTime);
|
|
191
|
+
const rowId = getRowId(row, this.primaryKey);
|
|
192
|
+
const tableName = row.tableName || row._table || (this.tables[0] ?? 'default');
|
|
193
|
+
return { tableName, operation: op, rowId, payload: isSoftDeleted ? null : row, timestamp: rowTime };
|
|
194
|
+
});
|
|
195
|
+
const maxTime = Math.max(...changes.map((change) => change.timestamp || 0));
|
|
196
|
+
callback({ timestamp: maxTime > 0 ? maxTime : Date.now(), changes });
|
|
197
|
+
}
|
|
198
|
+
});
|
|
199
|
+
if (generation !== this.liveGeneration) {
|
|
200
|
+
if (typeof unsubscribe === 'function')
|
|
201
|
+
unsubscribe();
|
|
165
202
|
return;
|
|
166
203
|
}
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
callback({
|
|
184
|
-
timestamp: maxTime > 0 ? maxTime : Date.now(),
|
|
185
|
-
changes,
|
|
186
|
-
});
|
|
187
|
-
}
|
|
188
|
-
});
|
|
204
|
+
this.unsubscribeLive = typeof unsubscribe === 'function' ? unsubscribe : undefined;
|
|
205
|
+
}
|
|
206
|
+
catch (err) {
|
|
207
|
+
console.warn('ConvexRemoteAdapter live subscription failed to initialize:', err);
|
|
208
|
+
}
|
|
209
|
+
};
|
|
210
|
+
try {
|
|
211
|
+
const scopeResult = typeof this.liveScope === 'function' ? this.liveScope() : this.liveScope;
|
|
212
|
+
if (scopeResult && typeof scopeResult.then === 'function') {
|
|
213
|
+
void Promise.resolve(scopeResult).then(subscribe).catch((err) => {
|
|
214
|
+
console.warn('ConvexRemoteAdapter live scope failed to resolve:', err);
|
|
215
|
+
});
|
|
216
|
+
}
|
|
217
|
+
else {
|
|
218
|
+
subscribe(scopeResult);
|
|
219
|
+
}
|
|
189
220
|
}
|
|
190
221
|
catch (err) {
|
|
191
|
-
console.warn('ConvexRemoteAdapter live
|
|
222
|
+
console.warn('ConvexRemoteAdapter live scope failed to resolve:', err);
|
|
192
223
|
}
|
|
193
224
|
}
|
|
194
225
|
/**
|
|
195
226
|
* Cleans up live subscriptions.
|
|
196
227
|
*/
|
|
197
228
|
destroy() {
|
|
229
|
+
this.liveGeneration++;
|
|
230
|
+
this.liveCallback = undefined;
|
|
198
231
|
if (this.unsubscribeLive) {
|
|
199
232
|
this.unsubscribeLive();
|
|
200
233
|
this.unsubscribeLive = undefined;
|
|
@@ -41,6 +41,7 @@ export declare class FirestoreRemoteAdapter implements RemoteDBAdapter {
|
|
|
41
41
|
private updatedAtColumn;
|
|
42
42
|
private firestoreModule;
|
|
43
43
|
private unsubscribers;
|
|
44
|
+
private liveGeneration;
|
|
44
45
|
logger: SyncLogger;
|
|
45
46
|
constructor(db: any, options?: FirestoreAdapterOptions);
|
|
46
47
|
setTables(tables: string[]): void;
|
|
@@ -58,7 +59,7 @@ export declare class FirestoreRemoteAdapter implements RemoteDBAdapter {
|
|
|
58
59
|
/**
|
|
59
60
|
* Subscribes to live real-time query updates via onSnapshot.
|
|
60
61
|
*/
|
|
61
|
-
subscribeToLiveChanges(callback: (changes: DeltaChanges) => void): void;
|
|
62
|
+
subscribeToLiveChanges(callback: (changes: DeltaChanges) => void): () => void;
|
|
62
63
|
/**
|
|
63
64
|
* Cleans up all active real-time listeners.
|
|
64
65
|
*/
|
|
@@ -46,6 +46,7 @@ class FirestoreRemoteAdapter {
|
|
|
46
46
|
updatedAtColumn;
|
|
47
47
|
firestoreModule;
|
|
48
48
|
unsubscribers = [];
|
|
49
|
+
liveGeneration = 0;
|
|
49
50
|
logger;
|
|
50
51
|
constructor(db, options = {}) {
|
|
51
52
|
if (!db) {
|
|
@@ -250,17 +251,25 @@ class FirestoreRemoteAdapter {
|
|
|
250
251
|
*/
|
|
251
252
|
subscribeToLiveChanges(callback) {
|
|
252
253
|
this.destroy();
|
|
254
|
+
const generation = this.liveGeneration;
|
|
253
255
|
if (!this.tables || this.tables.length === 0) {
|
|
254
|
-
return
|
|
256
|
+
return () => {
|
|
257
|
+
if (generation === this.liveGeneration)
|
|
258
|
+
this.destroy();
|
|
259
|
+
};
|
|
255
260
|
}
|
|
256
261
|
const setupListeners = async () => {
|
|
257
262
|
const isCompat = typeof this.db.collection === 'function';
|
|
258
263
|
const mod = isCompat ? null : await this.getModule();
|
|
264
|
+
if (generation !== this.liveGeneration)
|
|
265
|
+
return;
|
|
259
266
|
const currentCursor = Date.now() - 2000;
|
|
260
267
|
for (const table of this.tables) {
|
|
268
|
+
if (generation !== this.liveGeneration)
|
|
269
|
+
return;
|
|
261
270
|
try {
|
|
262
271
|
const handleSnapshot = (snapshot) => {
|
|
263
|
-
if (!snapshot)
|
|
272
|
+
if (generation !== this.liveGeneration || !snapshot)
|
|
264
273
|
return;
|
|
265
274
|
let docList = [];
|
|
266
275
|
if (typeof snapshot.docChanges === 'function') {
|
|
@@ -328,12 +337,21 @@ class FirestoreRemoteAdapter {
|
|
|
328
337
|
}
|
|
329
338
|
}
|
|
330
339
|
};
|
|
331
|
-
setupListeners()
|
|
340
|
+
void setupListeners().catch((err) => {
|
|
341
|
+
if (generation === this.liveGeneration) {
|
|
342
|
+
console.warn('Failed to initialize Firestore live listeners:', err);
|
|
343
|
+
}
|
|
344
|
+
});
|
|
345
|
+
return () => {
|
|
346
|
+
if (generation === this.liveGeneration)
|
|
347
|
+
this.destroy();
|
|
348
|
+
};
|
|
332
349
|
}
|
|
333
350
|
/**
|
|
334
351
|
* Cleans up all active real-time listeners.
|
|
335
352
|
*/
|
|
336
353
|
destroy() {
|
|
354
|
+
this.liveGeneration++;
|
|
337
355
|
for (const unsub of this.unsubscribers) {
|
|
338
356
|
try {
|
|
339
357
|
unsub();
|
|
@@ -3,8 +3,9 @@ export interface RemoteDBAdapter {
|
|
|
3
3
|
pushChanges(operations: SyncOperation[]): Promise<boolean | PushResult>;
|
|
4
4
|
/** Return a complete batch through timestamp; reject on partial failure. Supports optional scope for data filtering. */
|
|
5
5
|
fetchChanges(sinceTimestamp: number, scope?: Record<string, any>): Promise<DeltaChanges>;
|
|
6
|
-
/** Live events do not advance the durable pull checkpoint
|
|
7
|
-
subscribeToLiveChanges(callback: (changes: DeltaChanges) => void
|
|
6
|
+
/** Live events do not advance the durable pull checkpoint; return a cleanup function. */
|
|
7
|
+
subscribeToLiveChanges(callback: (changes: DeltaChanges) => void, scope?: Record<string, any> | (() => Record<string, any> | Promise<Record<string, any>>)): () => void;
|
|
8
|
+
setSyncScope?(scope?: Record<string, any> | (() => Record<string, any> | Promise<Record<string, any>>)): void;
|
|
8
9
|
}
|
|
9
10
|
export * from './supabase.js';
|
|
10
11
|
export * from './demo.js';
|
|
@@ -119,7 +119,7 @@ export declare class SupabaseRemoteAdapter implements RemoteDBAdapter {
|
|
|
119
119
|
* Subscribes to live realtime postgres_changes from Supabase.
|
|
120
120
|
* Batches rapid burst events in the same microtask turn into a single SQLite sync transaction.
|
|
121
121
|
*/
|
|
122
|
-
subscribeToLiveChanges(callback: (changes: DeltaChanges) => void): (
|
|
122
|
+
subscribeToLiveChanges(callback: (changes: DeltaChanges) => void): () => void;
|
|
123
123
|
/**
|
|
124
124
|
* Clean up active realtime channels.
|
|
125
125
|
*/
|
package/dist/config/index.js
CHANGED
|
@@ -62,6 +62,9 @@ function defineSyncConfig(config) {
|
|
|
62
62
|
* Factory that instantiates, wires up, and initializes a LocalFirstClient from a LocalLiteConfig.
|
|
63
63
|
*/
|
|
64
64
|
async function createSyncClient(config) {
|
|
65
|
+
if ('migrations' in config) {
|
|
66
|
+
throw new TypeError('The migrations option has been removed. Use schemaMigrations instead.');
|
|
67
|
+
}
|
|
65
68
|
// 1. Resolve Local Database Adapter
|
|
66
69
|
const localAdapter = await (0, resolve_local_js_1.resolveLocalAdapter)(config);
|
|
67
70
|
// 2. Resolve Remote Cloud Adapter
|
|
@@ -85,7 +88,6 @@ async function createSyncClient(config) {
|
|
|
85
88
|
autoSchema,
|
|
86
89
|
tables: config.tables ?? [],
|
|
87
90
|
relationships: config.relationships ?? [],
|
|
88
|
-
migrations: config.migrations,
|
|
89
91
|
schemaMigrations: config.schemaMigrations,
|
|
90
92
|
autoStart: config.autoStart,
|
|
91
93
|
jsonColumns: config.jsonColumns,
|
package/dist/config/types.d.ts
CHANGED
|
@@ -90,11 +90,6 @@ export interface LocalLiteConfig {
|
|
|
90
90
|
* Deletes through client.delete(), client.mutate(..., 'DELETE'), or batch are handled atomically.
|
|
91
91
|
*/
|
|
92
92
|
relationships?: RelationshipDefinition[];
|
|
93
|
-
/**
|
|
94
|
-
* Legacy idempotent SQL statements executed transactionally on every initialization.
|
|
95
|
-
* e.g. ["CREATE TABLE IF NOT EXISTS todos (id TEXT PRIMARY KEY, title TEXT);"]
|
|
96
|
-
*/
|
|
97
|
-
migrations?: string[];
|
|
98
93
|
/**
|
|
99
94
|
* Versioned application schema migrations. Versions must be consecutive integers
|
|
100
95
|
* starting at 1; each migration is applied once and recorded in schema_migrations.
|
package/dist/core/client.d.ts
CHANGED
|
@@ -2,6 +2,7 @@ import { LocalDBAdapter, LocalTransaction } from '../adapters/local/index.js';
|
|
|
2
2
|
import { RemoteDBAdapter } from '../adapters/remote/index.js';
|
|
3
3
|
import { EventEmitter } from '../reactive/event-emitter.js';
|
|
4
4
|
import { SyncWorker } from './sync-worker.js';
|
|
5
|
+
import { type OutboxDeleteClause } from './outbox-store.js';
|
|
5
6
|
import { DatabaseMaintenance } from './maintenance.js';
|
|
6
7
|
import { SchemaManager } from './schema-manager.js';
|
|
7
8
|
import { BatchMutation, ConflictResolver, ConflictStrategy, MutateOptions, NetworkStatusProvider, OutboxRecord, OutboxStatus, QueryOptions, RetryConfig, SchemaMigration, SyncMetrics, SyncOp, TableChangeEvent, WhereFilter } from './types.js';
|
|
@@ -42,7 +43,6 @@ export interface LocalFirstClientConfig {
|
|
|
42
43
|
autoSchema?: boolean;
|
|
43
44
|
tables?: string[];
|
|
44
45
|
relationships?: RelationshipDefinition[];
|
|
45
|
-
migrations?: string[];
|
|
46
46
|
schemaMigrations?: SchemaMigration[];
|
|
47
47
|
autoStart?: boolean;
|
|
48
48
|
coalesceOutbox?: boolean;
|
|
@@ -123,7 +123,6 @@ export declare class LocalFirstClient {
|
|
|
123
123
|
readonly scheduler: JobScheduler;
|
|
124
124
|
readonly session: SessionManager;
|
|
125
125
|
private primaryKey;
|
|
126
|
-
private migrations;
|
|
127
126
|
private schemaMigrations;
|
|
128
127
|
private autoStart;
|
|
129
128
|
private initialization?;
|
|
@@ -151,7 +150,7 @@ export declare class LocalFirstClient {
|
|
|
151
150
|
recordOutboxMutation(tx: LocalTransaction, tableName: string, rowId: string, operation: SyncOp, payload: Record<string, any> | null, timestamp: number, pendingOutboxMap?: Map<string, OutboxRecord>): Promise<string | undefined>;
|
|
152
151
|
/**
|
|
153
152
|
* Initializes the client: creates sync_outbox schema, ensures autoSchema tables if enabled,
|
|
154
|
-
* applies migrations, and optionally starts automatic sync. Concurrent/repeated calls
|
|
153
|
+
* applies schema migrations, and optionally starts automatic sync. Concurrent/repeated calls
|
|
155
154
|
* share initialization; failures can be retried. After stop(), explicitly start the worker.
|
|
156
155
|
*/
|
|
157
156
|
initialize(): Promise<void>;
|
|
@@ -326,6 +325,11 @@ export declare class LocalFirstClient {
|
|
|
326
325
|
limit?: number;
|
|
327
326
|
offset?: number;
|
|
328
327
|
}): Promise<OutboxRecord[]>;
|
|
328
|
+
/**
|
|
329
|
+
* Deletes outbox entries matching one or more filter clauses. Intended for
|
|
330
|
+
* application cleanup of intentionally local-only or obsolete operations.
|
|
331
|
+
*/
|
|
332
|
+
deleteOutboxRecords(clauses: OutboxDeleteClause[]): Promise<void>;
|
|
329
333
|
/**
|
|
330
334
|
* Re-queues failed outbox mutations for retry by resetting their status to PENDING.
|
|
331
335
|
* Triggers an immediate sync push.
|
package/dist/core/client.js
CHANGED
|
@@ -247,11 +247,13 @@ class LocalFirstClient {
|
|
|
247
247
|
scheduler;
|
|
248
248
|
session;
|
|
249
249
|
primaryKey;
|
|
250
|
-
migrations;
|
|
251
250
|
schemaMigrations;
|
|
252
251
|
autoStart;
|
|
253
252
|
initialization;
|
|
254
253
|
constructor(config) {
|
|
254
|
+
if ('migrations' in config) {
|
|
255
|
+
throw new TypeError('The migrations option has been removed. Use schemaMigrations instead.');
|
|
256
|
+
}
|
|
255
257
|
this.db = config.local;
|
|
256
258
|
this.remote = config.remote;
|
|
257
259
|
this.events = new event_emitter_js_1.EventEmitter();
|
|
@@ -284,7 +286,6 @@ class LocalFirstClient {
|
|
|
284
286
|
}
|
|
285
287
|
relationshipKeys.add(key);
|
|
286
288
|
}
|
|
287
|
-
this.migrations = config.migrations ?? [];
|
|
288
289
|
this.schemaMigrations = normalizeSchemaMigrations(config.schemaMigrations ?? []);
|
|
289
290
|
this.autoStart = config.autoStart ?? true;
|
|
290
291
|
this.jsonColumns = config.jsonColumns ?? {};
|
|
@@ -470,7 +471,7 @@ class LocalFirstClient {
|
|
|
470
471
|
}
|
|
471
472
|
/**
|
|
472
473
|
* Initializes the client: creates sync_outbox schema, ensures autoSchema tables if enabled,
|
|
473
|
-
* applies migrations, and optionally starts automatic sync. Concurrent/repeated calls
|
|
474
|
+
* applies schema migrations, and optionally starts automatic sync. Concurrent/repeated calls
|
|
474
475
|
* share initialization; failures can be retried. After stop(), explicitly start the worker.
|
|
475
476
|
*/
|
|
476
477
|
async initialize() {
|
|
@@ -501,14 +502,6 @@ class LocalFirstClient {
|
|
|
501
502
|
await this.storage.initialize();
|
|
502
503
|
await this.scheduler.initialize();
|
|
503
504
|
await this.session.initialize();
|
|
504
|
-
if (this.migrations.length > 0) {
|
|
505
|
-
await this.db.transaction(async (tx) => {
|
|
506
|
-
for (const query of this.migrations) {
|
|
507
|
-
if (query.trim())
|
|
508
|
-
await tx.execute(query);
|
|
509
|
-
}
|
|
510
|
-
});
|
|
511
|
-
}
|
|
512
505
|
await this.applySchemaMigrations();
|
|
513
506
|
if (this.autoSchema && this.tables.length > 0) {
|
|
514
507
|
for (const table of this.tables) {
|
|
@@ -1027,6 +1020,16 @@ class LocalFirstClient {
|
|
|
1027
1020
|
async getOutboxRecords(options) {
|
|
1028
1021
|
return await outbox_store_js_1.OutboxStore.getAllRecords(this.db, options);
|
|
1029
1022
|
}
|
|
1023
|
+
/**
|
|
1024
|
+
* Deletes outbox entries matching one or more filter clauses. Intended for
|
|
1025
|
+
* application cleanup of intentionally local-only or obsolete operations.
|
|
1026
|
+
*/
|
|
1027
|
+
async deleteOutboxRecords(clauses) {
|
|
1028
|
+
if (clauses.length === 0)
|
|
1029
|
+
return;
|
|
1030
|
+
await outbox_store_js_1.OutboxStore.deleteMatching(this.db, clauses);
|
|
1031
|
+
this.events.emit('sync_outbox', { operation: 'DELETE', rowId: 'filtered' });
|
|
1032
|
+
}
|
|
1030
1033
|
/**
|
|
1031
1034
|
* Re-queues failed outbox mutations for retry by resetting their status to PENDING.
|
|
1032
1035
|
* Triggers an immediate sync push.
|
|
@@ -16,13 +16,13 @@ export declare class MetaStore {
|
|
|
16
16
|
/**
|
|
17
17
|
* Retrieves the persisted last_synced_at cursor timestamp (in ms). Returns 0 if never synced.
|
|
18
18
|
*/
|
|
19
|
-
static getLastSyncedAt(db: LocalDBAdapter): Promise<number>;
|
|
19
|
+
static getLastSyncedAt(db: LocalDBAdapter, key?: string): Promise<number>;
|
|
20
20
|
/**
|
|
21
21
|
* Persists the last_synced_at cursor timestamp.
|
|
22
22
|
*/
|
|
23
|
-
static setLastSyncedAt(db: LocalDBAdapter | LocalTransaction, timestamp: number): Promise<void>;
|
|
23
|
+
static setLastSyncedAt(db: LocalDBAdapter | LocalTransaction, timestamp: number, key?: string): Promise<void>;
|
|
24
24
|
/**
|
|
25
25
|
* Clears the persisted cursor (forces next pull to re-query active remote records).
|
|
26
26
|
*/
|
|
27
|
-
static clearLastSyncedAt(db: LocalDBAdapter | LocalTransaction): Promise<void>;
|
|
27
|
+
static clearLastSyncedAt(db: LocalDBAdapter | LocalTransaction, key?: string): Promise<void>;
|
|
28
28
|
}
|
package/dist/core/meta-store.js
CHANGED
|
@@ -36,8 +36,8 @@ class MetaStore {
|
|
|
36
36
|
/**
|
|
37
37
|
* Retrieves the persisted last_synced_at cursor timestamp (in ms). Returns 0 if never synced.
|
|
38
38
|
*/
|
|
39
|
-
static async getLastSyncedAt(db) {
|
|
40
|
-
const val = await this.get(db,
|
|
39
|
+
static async getLastSyncedAt(db, key = 'last_synced_at') {
|
|
40
|
+
const val = await this.get(db, key);
|
|
41
41
|
if (!val)
|
|
42
42
|
return 0;
|
|
43
43
|
const parsed = parseInt(val, 10);
|
|
@@ -46,15 +46,15 @@ class MetaStore {
|
|
|
46
46
|
/**
|
|
47
47
|
* Persists the last_synced_at cursor timestamp.
|
|
48
48
|
*/
|
|
49
|
-
static async setLastSyncedAt(db, timestamp) {
|
|
50
|
-
await this.set(db,
|
|
49
|
+
static async setLastSyncedAt(db, timestamp, key = 'last_synced_at') {
|
|
50
|
+
await this.set(db, key, String(timestamp));
|
|
51
51
|
}
|
|
52
52
|
/**
|
|
53
53
|
* Clears the persisted cursor (forces next pull to re-query active remote records).
|
|
54
54
|
*/
|
|
55
|
-
static async clearLastSyncedAt(db) {
|
|
55
|
+
static async clearLastSyncedAt(db, key = 'last_synced_at') {
|
|
56
56
|
try {
|
|
57
|
-
await db.execute(`DELETE FROM sync_meta WHERE key =
|
|
57
|
+
await db.execute(`DELETE FROM sync_meta WHERE key = ?`, [key]);
|
|
58
58
|
}
|
|
59
59
|
catch {
|
|
60
60
|
// Ignored if table doesn't exist yet
|
|
@@ -1,5 +1,12 @@
|
|
|
1
1
|
import { LocalDBAdapter, LocalTransaction } from '../adapters/local/index.js';
|
|
2
2
|
import { OutboxRecord, OutboxStatus, SyncOp, SyncOperation } from './types.js';
|
|
3
|
+
export type OutboxFilterValue = string | number | boolean | null;
|
|
4
|
+
export interface OutboxDeleteClause {
|
|
5
|
+
tableName?: string;
|
|
6
|
+
operation?: string;
|
|
7
|
+
rowIds?: string[];
|
|
8
|
+
payloadIn?: Record<string, OutboxFilterValue[]>;
|
|
9
|
+
}
|
|
3
10
|
export declare class OutboxStore {
|
|
4
11
|
/**
|
|
5
12
|
* Initializes the sync_outbox schema if it does not already exist.
|
|
@@ -39,6 +46,8 @@ export declare class OutboxStore {
|
|
|
39
46
|
* Deletes a batch of successfully pushed outbox entries.
|
|
40
47
|
*/
|
|
41
48
|
static deleteCompleted(db: LocalDBAdapter, ids: string[]): Promise<void>;
|
|
49
|
+
/** Deletes outbox records matching one or more safe, parameterized clauses. */
|
|
50
|
+
static deleteMatching(db: LocalDBAdapter, clauses: OutboxDeleteClause[]): Promise<void>;
|
|
42
51
|
/**
|
|
43
52
|
* Deletes a single outbox record within an active transaction.
|
|
44
53
|
*/
|
|
@@ -162,6 +162,37 @@ class OutboxStore {
|
|
|
162
162
|
const placeholders = ids.map(() => '?').join(',');
|
|
163
163
|
await db.execute(`DELETE FROM sync_outbox WHERE id IN (${placeholders})`, ids);
|
|
164
164
|
}
|
|
165
|
+
/** Deletes outbox records matching one or more safe, parameterized clauses. */
|
|
166
|
+
static async deleteMatching(db, clauses) {
|
|
167
|
+
const alternatives = [];
|
|
168
|
+
const params = [];
|
|
169
|
+
for (const clause of clauses) {
|
|
170
|
+
const conditions = [];
|
|
171
|
+
if (clause.tableName) {
|
|
172
|
+
conditions.push('table_name = ?');
|
|
173
|
+
params.push(clause.tableName);
|
|
174
|
+
}
|
|
175
|
+
if (clause.operation) {
|
|
176
|
+
conditions.push('operation = ?');
|
|
177
|
+
params.push(clause.operation);
|
|
178
|
+
}
|
|
179
|
+
if (clause.rowIds?.length) {
|
|
180
|
+
conditions.push(`row_id IN (${clause.rowIds.map(() => '?').join(',')})`);
|
|
181
|
+
params.push(...clause.rowIds);
|
|
182
|
+
}
|
|
183
|
+
for (const [field, values] of Object.entries(clause.payloadIn ?? {})) {
|
|
184
|
+
if (!/^[A-Za-z0-9_]+$/.test(field) || values.length === 0)
|
|
185
|
+
continue;
|
|
186
|
+
conditions.push(`json_extract(CASE WHEN json_valid(payload) THEN payload ELSE '{}' END, ?) IN (${values.map(() => '?').join(',')})`);
|
|
187
|
+
params.push(`$.${field}`, ...values);
|
|
188
|
+
}
|
|
189
|
+
if (conditions.length > 0)
|
|
190
|
+
alternatives.push(`(${conditions.join(' AND ')})`);
|
|
191
|
+
}
|
|
192
|
+
if (alternatives.length === 0)
|
|
193
|
+
return;
|
|
194
|
+
await db.execute(`DELETE FROM sync_outbox WHERE ${alternatives.join(' OR ')}`, params);
|
|
195
|
+
}
|
|
165
196
|
/**
|
|
166
197
|
* Deletes a single outbox record within an active transaction.
|
|
167
198
|
*/
|
|
@@ -49,6 +49,8 @@ export declare class SyncWorker {
|
|
|
49
49
|
private isPulling;
|
|
50
50
|
private lastPulledTimestamp;
|
|
51
51
|
private cursorLoaded;
|
|
52
|
+
private lastSyncedAtKey;
|
|
53
|
+
private pullRequested;
|
|
52
54
|
private deltaQueue;
|
|
53
55
|
private statusRun?;
|
|
54
56
|
private statusRerunRequested;
|
|
@@ -115,10 +117,14 @@ export declare class SyncWorker {
|
|
|
115
117
|
*/
|
|
116
118
|
applyDeltasLocally(deltas: DeltaChanges, options?: {
|
|
117
119
|
advanceCursor?: boolean;
|
|
120
|
+
cursorKey?: string;
|
|
118
121
|
}): Promise<void>;
|
|
119
122
|
private processDeltasLocally;
|
|
120
123
|
getLastPulledTimestamp(): Promise<number>;
|
|
124
|
+
private loadCursor;
|
|
121
125
|
resetSyncCursor(): Promise<void>;
|
|
126
|
+
/** Clears a stale push error after an explicit sync stop/reconfiguration. */
|
|
127
|
+
clearPushError(): void;
|
|
122
128
|
/**
|
|
123
129
|
* Collects real-time engine telemetry snapshot.
|
|
124
130
|
*/
|