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
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`. The existing
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 may return an unsubscribe function. Legacy adapters
78
- returning void remain supported; stopped workers ignore their later callbacks.
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
- if (typeof this.client.onUpdate !== 'function') {
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
- if (this.unsubscribeLive) {
153
- this.unsubscribeLive();
154
- this.unsubscribeLive = undefined;
155
- }
156
- try {
157
- this.unsubscribeLive = this.client.onUpdate(this.pullQuery, { sinceTimestamp: Date.now() - 2000, tables: this.tables }, (data) => {
158
- if (!data)
159
- return;
160
- if (data.changes && Array.isArray(data.changes)) {
161
- callback({
162
- timestamp: Number(data.timestamp || Date.now()),
163
- changes: data.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
- if (Array.isArray(data) && data.length > 0) {
168
- const changes = data.map((row) => {
169
- const isSoftDeleted = Boolean(row[this.deletedColumn] === true);
170
- const op = isSoftDeleted ? 'DELETE' : 'UPDATE';
171
- const rowTime = getRowTimestamp(row[this.updatedAtColumn], row._creationTime);
172
- const rowId = getRowId(row, this.primaryKey);
173
- const tableName = row.tableName || row._table || (this.tables[0] ?? 'default');
174
- return {
175
- tableName,
176
- operation: op,
177
- rowId,
178
- payload: isSoftDeleted ? null : row,
179
- timestamp: rowTime,
180
- };
181
- });
182
- const maxTime = Math.max(...changes.map((c) => c.timestamp || 0));
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 subscription failed to initialize:', err);
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. Return cleanup when supported. */
7
- subscribeToLiveChanges(callback: (changes: DeltaChanges) => void): void | (() => 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): (() => void) | void;
122
+ subscribeToLiveChanges(callback: (changes: DeltaChanges) => void): () => void;
123
123
  /**
124
124
  * Clean up active realtime channels.
125
125
  */
@@ -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,
@@ -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.
@@ -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.
@@ -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
  }
@@ -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, 'last_synced_at');
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, 'last_synced_at', String(timestamp));
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 = 'last_synced_at'`);
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
  */