local-lite 1.0.4 → 2.0.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.
Files changed (39) hide show
  1. package/dist/adapters/local/better-sqlite3.js +10 -3
  2. package/dist/adapters/local/expo-sqlite.js +3 -3
  3. package/dist/adapters/local/node-sqlite.js +10 -3
  4. package/dist/adapters/remote/index.d.ts +5 -2
  5. package/dist/adapters/remote/self-hosted.d.ts +3 -3
  6. package/dist/adapters/remote/self-hosted.js +17 -4
  7. package/dist/adapters/remote/supabase.d.ts +1 -2
  8. package/dist/config/index.d.ts +0 -1
  9. package/dist/config/index.js +3 -10
  10. package/dist/config/types.d.ts +5 -10
  11. package/dist/core/client.d.ts +3 -12
  12. package/dist/core/client.js +166 -59
  13. package/dist/core/outbox-store.d.ts +1 -1
  14. package/dist/core/outbox-store.js +58 -21
  15. package/dist/core/query-builder.js +36 -45
  16. package/dist/core/sync-worker.d.ts +12 -2
  17. package/dist/core/sync-worker.js +84 -21
  18. package/dist/core/table-manager.js +19 -8
  19. package/dist/core/types.d.ts +1 -0
  20. package/dist/index.d.ts +1 -0
  21. package/dist/index.js +1 -0
  22. package/dist/payments/adapters.d.ts +49 -0
  23. package/dist/payments/adapters.js +459 -0
  24. package/dist/payments/index.d.ts +3 -0
  25. package/dist/payments/index.js +19 -0
  26. package/dist/payments/registry.d.ts +18 -0
  27. package/dist/payments/registry.js +114 -0
  28. package/dist/payments/server.d.ts +19 -0
  29. package/dist/payments/server.js +235 -0
  30. package/dist/payments/types.d.ts +106 -0
  31. package/dist/payments/types.js +2 -0
  32. package/dist/react/index.js +54 -2
  33. package/dist/server/sync.d.ts +38 -0
  34. package/dist/server/sync.js +214 -2
  35. package/dist/storage/supabase.d.ts +7 -2
  36. package/package.json +14 -5
  37. package/skills/local-lite-auth/SKILL.md +1 -1
  38. package/skills/local-lite-setup/SKILL.md +1 -1
  39. package/skills/local-lite-upgrade/SKILL.md +32 -9
@@ -87,12 +87,20 @@ async function executeFindByIds(db, tableName, ids, primaryKey, hydrateRow, incl
87
87
  return [];
88
88
  const safeTable = (0, sql_js_1.escapeIdentifier)(tableName);
89
89
  const safePk = (0, sql_js_1.escapeIdentifier)(primaryKey);
90
- const placeholders = ids.map(() => '?').join(', ');
90
+ const CHUNK_SIZE = 500;
91
91
  try {
92
- const rows = await db.execute(`SELECT * FROM ${safeTable} WHERE ${safePk} IN (${placeholders})`, ids);
93
- if (!rows || rows.length === 0)
92
+ const allRows = [];
93
+ for (let i = 0; i < ids.length; i += CHUNK_SIZE) {
94
+ const chunk = ids.slice(i, i + CHUNK_SIZE);
95
+ const placeholders = chunk.map(() => '?').join(', ');
96
+ const rows = await db.execute(`SELECT * FROM ${safeTable} WHERE ${safePk} IN (${placeholders})`, chunk);
97
+ if (rows && rows.length > 0) {
98
+ allRows.push(...rows);
99
+ }
100
+ }
101
+ if (allRows.length === 0)
94
102
  return [];
95
- const hydrated = rows.map((r) => hydrateRow(tableName, r));
103
+ const hydrated = allRows.map((r) => hydrateRow(tableName, r));
96
104
  return !includeDeleted
97
105
  ? hydrated.filter((r) => !(0, query_js_1.isDeletedRecord)(r))
98
106
  : hydrated;
@@ -128,6 +136,9 @@ class TransactionalClient {
128
136
  return;
129
137
  visited.add(key);
130
138
  const relationships = this.parent.relationships.filter((relationship) => relationship.references === tableName);
139
+ // Check restrict/noAction relationships first to fail fast before mutating any child rows.
140
+ const resolvedChildren = [];
141
+ const pk = this.parent.getPrimaryKey();
131
142
  for (const relationship of relationships) {
132
143
  const relatedRows = await this.findMany(relationship.table, {
133
144
  where: { [relationship.foreignKey]: rowId },
@@ -138,24 +149,144 @@ class TransactionalClient {
138
149
  if (action === 'restrict' || action === 'noAction') {
139
150
  throw new Error(`Cannot delete ${tableName} record while ${relationship.table} records still reference it.`);
140
151
  }
152
+ const childIds = relatedRows
153
+ .map((r) => r[pk])
154
+ .filter((id) => id !== undefined && id !== null)
155
+ .map((id) => String(id));
156
+ if (childIds.length > 0) {
157
+ resolvedChildren.push({ relationship, childIds });
158
+ }
159
+ }
160
+ for (const { relationship, childIds } of resolvedChildren) {
161
+ const action = relationship.onDelete ?? 'noAction';
141
162
  if (action === 'setNull') {
142
- for (const row of relatedRows) {
143
- const childId = row[this.parent.getPrimaryKey()];
144
- if (childId !== undefined && childId !== null) {
145
- await this.update(relationship.table, String(childId), { [relationship.foreignKey]: null }, options);
146
- }
147
- }
163
+ await this.batchSetNull(relationship.table, relationship.foreignKey, childIds, options);
148
164
  continue;
149
165
  }
150
- for (const row of relatedRows) {
151
- const childId = row[this.parent.getPrimaryKey()];
152
- if (childId !== undefined && childId !== null) {
153
- await this.deleteRelated(relationship.table, String(childId), visited, options);
166
+ const hasDownstream = this.parent.relationships.some((rel) => rel.references === relationship.table);
167
+ if (!hasDownstream) {
168
+ await this.batchDeleteRows(relationship.table, childIds, visited, options);
169
+ }
170
+ else {
171
+ for (const childId of childIds) {
172
+ await this.deleteRelated(relationship.table, childId, visited, options);
154
173
  }
155
174
  }
156
175
  }
157
176
  await this.applyMutation(tableName, rowId, 'DELETE', null, options);
158
177
  }
178
+ async batchSetNull(tableName, foreignKey, rowIds, options = {}) {
179
+ if (rowIds.length === 0)
180
+ return;
181
+ const pk = options.primaryKey ?? this.parent.getPrimaryKey();
182
+ const timestamp = options.customTimestamp ?? Date.now();
183
+ const mutOpts = this.parent.localMutationOptions(timestamp);
184
+ const safeTable = (0, sql_js_1.escapeIdentifier)(tableName);
185
+ const safePk = (0, sql_js_1.escapeIdentifier)(pk);
186
+ const safeFk = (0, sql_js_1.escapeIdentifier)(foreignKey);
187
+ let setClause = `${safeFk} = NULL`;
188
+ const setParams = [];
189
+ if (mutOpts.touchColumn &&
190
+ (mutOpts.autoSchema ||
191
+ (await this.parent.schemaManager.tableHasColumn(this.tx, tableName, mutOpts.touchColumn)))) {
192
+ setClause += `, ${(0, sql_js_1.escapeIdentifier)(mutOpts.touchColumn)} = ?`;
193
+ setParams.push(mutOpts.touchValue);
194
+ }
195
+ for (let i = 0; i < rowIds.length; i += 500) {
196
+ const chunk = rowIds.slice(i, i + 500);
197
+ if (chunk.length === 1) {
198
+ await this.tx.execute(`UPDATE ${safeTable} SET ${setClause} WHERE ${safePk} = ?`, [...setParams, chunk[0]]);
199
+ }
200
+ else {
201
+ const placeholders = chunk.map(() => '?').join(', ');
202
+ await this.tx.execute(`UPDATE ${safeTable} SET ${setClause} WHERE ${safePk} IN (${placeholders})`, [...setParams, ...chunk]);
203
+ }
204
+ }
205
+ const payload = { [foreignKey]: null };
206
+ if (!options.skipOutbox) {
207
+ if (!this.parent.coalesceOutbox) {
208
+ const ops = rowIds.map((id) => ({
209
+ id: (0, uuid_js_1.generateUUID)(),
210
+ tableName,
211
+ rowId: id,
212
+ operation: 'UPDATE',
213
+ payload,
214
+ timestamp,
215
+ }));
216
+ await outbox_store_js_1.OutboxStore.insertRecords(this.tx, ops);
217
+ for (const op of ops)
218
+ this.queuedOutboxIds.push(op.id);
219
+ }
220
+ else {
221
+ const pendingMap = await outbox_store_js_1.OutboxStore.getActivePendingMap(this.tx, rowIds);
222
+ for (const id of rowIds) {
223
+ const outboxId = await this.parent.recordOutboxMutation(this.tx, tableName, id, 'UPDATE', payload, timestamp, pendingMap);
224
+ if (outboxId)
225
+ this.queuedOutboxIds.push(outboxId);
226
+ }
227
+ }
228
+ }
229
+ for (const id of rowIds) {
230
+ this.queuedTableEvents.push({
231
+ tableName,
232
+ event: { operation: 'UPDATE', rowId: id, payload, source: 'local' },
233
+ });
234
+ }
235
+ }
236
+ async batchDeleteRows(tableName, rowIds, visited, options = {}) {
237
+ const unvisitedIds = rowIds.filter((id) => {
238
+ const key = `${tableName}:${id}`;
239
+ if (visited.has(key))
240
+ return false;
241
+ visited.add(key);
242
+ return true;
243
+ });
244
+ if (unvisitedIds.length === 0)
245
+ return;
246
+ const pk = options.primaryKey ?? this.parent.getPrimaryKey();
247
+ const timestamp = options.customTimestamp ?? Date.now();
248
+ const safeTable = (0, sql_js_1.escapeIdentifier)(tableName);
249
+ const safePk = (0, sql_js_1.escapeIdentifier)(pk);
250
+ for (let i = 0; i < unvisitedIds.length; i += 500) {
251
+ const chunk = unvisitedIds.slice(i, i + 500);
252
+ if (chunk.length === 1) {
253
+ await this.tx.execute(`DELETE FROM ${safeTable} WHERE ${safePk} = ?`, [chunk[0]]);
254
+ }
255
+ else {
256
+ const placeholders = chunk.map(() => '?').join(', ');
257
+ await this.tx.execute(`DELETE FROM ${safeTable} WHERE ${safePk} IN (${placeholders})`, chunk);
258
+ }
259
+ }
260
+ if (!options.skipOutbox) {
261
+ if (!this.parent.coalesceOutbox) {
262
+ const ops = unvisitedIds.map((id) => ({
263
+ id: (0, uuid_js_1.generateUUID)(),
264
+ tableName,
265
+ rowId: id,
266
+ operation: 'DELETE',
267
+ payload: null,
268
+ timestamp,
269
+ }));
270
+ await outbox_store_js_1.OutboxStore.insertRecords(this.tx, ops);
271
+ for (const op of ops)
272
+ this.queuedOutboxIds.push(op.id);
273
+ }
274
+ else {
275
+ const pendingMap = await outbox_store_js_1.OutboxStore.getActivePendingMap(this.tx, unvisitedIds);
276
+ for (const id of unvisitedIds) {
277
+ const outboxId = await this.parent.recordOutboxMutation(this.tx, tableName, id, 'DELETE', null, timestamp, pendingMap);
278
+ if (outboxId)
279
+ this.queuedOutboxIds.push(outboxId);
280
+ }
281
+ }
282
+ }
283
+ for (const id of unvisitedIds) {
284
+ this.queuedTableEvents.push({
285
+ tableName,
286
+ event: { operation: 'DELETE', rowId: id, payload: null, source: 'local' },
287
+ });
288
+ }
289
+ }
159
290
  async applyMutation(tableName, rowId, operation, payload, options = {}) {
160
291
  const pk = options.primaryKey ?? this.parent.getPrimaryKey();
161
292
  const timestamp = options.customTimestamp ?? Date.now();
@@ -211,19 +342,16 @@ class TransactionalClient {
211
342
  return executeFindByIds(this.tx, tableName, ids, this.parent.getPrimaryKey(), (t, r) => this.parent.hydrateRow(t, r), options?.includeDeleted);
212
343
  }
213
344
  async findMany(tableName, options) {
214
- if (!this.parent.db.supportsSqlPushdown ||
215
- shouldUseClientSideQuery(options)) {
345
+ const fnFallback = shouldUseClientSideQuery(options);
346
+ if (!this.parent.db.supportsSqlPushdown || fnFallback) {
347
+ if (fnFallback) {
348
+ this.parent.syncWorker.logger.warn(`findMany('${tableName}') uses a function predicate; falling back to full-table load in JS memory.`);
349
+ }
216
350
  const rows = await this.from(tableName).execute();
217
351
  return (0, query_js_1.applyQueryOptions)(rows, options);
218
352
  }
219
353
  return this.from(tableName).applyOptions(options).execute();
220
354
  }
221
- /**
222
- * Alias for findMany().
223
- */
224
- async find(tableName, options) {
225
- return this.findMany(tableName, options);
226
- }
227
355
  async query(sql, params = []) {
228
356
  return (await this.tx.execute(sql, params));
229
357
  }
@@ -246,7 +374,6 @@ class LocalFirstClient {
246
374
  tables;
247
375
  relationships;
248
376
  jsonColumns;
249
- autoHydrateJSON;
250
377
  /** Local column stamped on INSERT/UPDATE writes, or null when disabled. */
251
378
  touchColumn;
252
379
  maintenance;
@@ -263,9 +390,6 @@ class LocalFirstClient {
263
390
  autoStart;
264
391
  initialization;
265
392
  constructor(config) {
266
- if ('migrations' in config) {
267
- throw new TypeError('The migrations option has been removed. Use schemaMigrations instead.');
268
- }
269
393
  this.db = config.local;
270
394
  this.remote = config.remote;
271
395
  this.events = new event_emitter_js_1.EventEmitter();
@@ -303,7 +427,6 @@ class LocalFirstClient {
303
427
  this.schemaMigrations = normalizeSchemaMigrations(config.schemaMigrations ?? []);
304
428
  this.autoStart = config.autoStart ?? true;
305
429
  this.jsonColumns = config.jsonColumns ?? {};
306
- this.autoHydrateJSON = config.autoHydrateJSON ?? false;
307
430
  const touch = config.touchUpdatedAt ?? true;
308
431
  this.touchColumn =
309
432
  touch === false
@@ -352,7 +475,7 @@ class LocalFirstClient {
352
475
  network: config.network,
353
476
  ...config.session,
354
477
  });
355
- this.auth = new local_js_1.LocalAuthEngine(this.db, this.session, this.events, config.auth || config.localAuth);
478
+ this.auth = new local_js_1.LocalAuthEngine(this.db, this.session, this.events, config.auth);
356
479
  this.actions = new index_js_2.ActionManager(this.db, this.events, () => Promise.resolve(actionNetwork ? actionNetwork.isOnline() : true), {
357
480
  network: actionNetwork,
358
481
  ...config.actions,
@@ -363,7 +486,7 @@ class LocalFirstClient {
363
486
  primaryKey: this.primaryKey,
364
487
  pushIntervalMs: config.pushIntervalMs,
365
488
  pullIntervalMs: config.pullIntervalMs,
366
- maxRetries: config.maxRetries,
489
+ requestTimeoutMs: config.requestTimeoutMs,
367
490
  retry: config.retry,
368
491
  logger: config.logger,
369
492
  logLevel: config.logLevel,
@@ -456,14 +579,17 @@ class LocalFirstClient {
456
579
  return row;
457
580
  const cols = this.jsonColumns[tableName];
458
581
  if (cols && cols.length > 0) {
459
- const copy = { ...row };
582
+ let copy = null;
460
583
  for (const col of cols) {
461
- if (typeof copy[col] === 'string') {
462
- const val = copy[col].trim();
584
+ const raw = row[col];
585
+ if (typeof raw === 'string') {
586
+ const val = raw.trim();
463
587
  if ((val.startsWith('{') && val.endsWith('}')) ||
464
588
  (val.startsWith('[') && val.endsWith(']'))) {
465
589
  try {
466
- copy[col] = JSON.parse(val);
590
+ const parsed = JSON.parse(val);
591
+ const target = (copy ??= { ...row });
592
+ target[col] = parsed;
467
593
  }
468
594
  catch {
469
595
  // keep string if not valid JSON
@@ -471,25 +597,7 @@ class LocalFirstClient {
471
597
  }
472
598
  }
473
599
  }
474
- return copy;
475
- }
476
- if (this.autoHydrateJSON) {
477
- const copy = { ...row };
478
- for (const [key, val] of Object.entries(copy)) {
479
- if (typeof val === 'string') {
480
- const trimmed = val.trim();
481
- if ((trimmed.startsWith('{') && trimmed.endsWith('}')) ||
482
- (trimmed.startsWith('[') && trimmed.endsWith(']'))) {
483
- try {
484
- copy[key] = JSON.parse(trimmed);
485
- }
486
- catch {
487
- // keep string
488
- }
489
- }
490
- }
491
- }
492
- return copy;
600
+ return (copy ?? row);
493
601
  }
494
602
  return row;
495
603
  }
@@ -1018,18 +1126,16 @@ class LocalFirstClient {
1018
1126
  return result;
1019
1127
  }
1020
1128
  async findMany(tableName, options) {
1021
- if (!this.db.supportsSqlPushdown || shouldUseClientSideQuery(options)) {
1129
+ const fnFallback = shouldUseClientSideQuery(options);
1130
+ if (!this.db.supportsSqlPushdown || fnFallback) {
1131
+ if (fnFallback) {
1132
+ this.syncWorker.logger.warn(`findMany('${tableName}') uses a function predicate; falling back to full-table load in JS memory.`);
1133
+ }
1022
1134
  const rows = await this.from(tableName).execute();
1023
1135
  return (0, query_js_1.applyQueryOptions)(rows, options);
1024
1136
  }
1025
1137
  return this.from(tableName).applyOptions(options).execute();
1026
1138
  }
1027
- /**
1028
- * Alias for findMany().
1029
- */
1030
- async find(tableName, options) {
1031
- return this.findMany(tableName, options);
1032
- }
1033
1139
  /**
1034
1140
  * Returns true if client storage has successfully initialized.
1035
1141
  */
@@ -1182,6 +1288,7 @@ class LocalFirstClient {
1182
1288
  */
1183
1289
  async close() {
1184
1290
  this.stop();
1291
+ await this.syncWorker.flush().catch(() => { });
1185
1292
  if (typeof this.remote.destroy === 'function') {
1186
1293
  this.remote.destroy();
1187
1294
  }
@@ -32,7 +32,7 @@ export declare class OutboxStore {
32
32
  * Retrieves active (non-FAILED) pending outbox records indexed by `${table_name}:${row_id}`.
33
33
  * Enables O(1) in-memory conflict lookup during delta ingestion, eliminating N+1 queries.
34
34
  */
35
- static getActivePendingMap(tx: LocalTransaction): Promise<Map<string, OutboxRecord>>;
35
+ static getActivePendingMap(tx: LocalTransaction, rowIds?: string[]): Promise<Map<string, OutboxRecord>>;
36
36
  /**
37
37
  * Marks a batch of outbox IDs as 'PROCESSING'.
38
38
  */
@@ -1,6 +1,16 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
3
  exports.OutboxStore = void 0;
4
+ const SQLITE_IN_CHUNK_SIZE = 500;
5
+ function chunkArray(items, size = SQLITE_IN_CHUNK_SIZE) {
6
+ if (items.length <= size)
7
+ return [items];
8
+ const chunks = [];
9
+ for (let i = 0; i < items.length; i += size) {
10
+ chunks.push(items.slice(i, i + size));
11
+ }
12
+ return chunks;
13
+ }
4
14
  /**
5
15
  * Maps a raw sync_outbox row into an OutboxRecord.
6
16
  */
@@ -91,10 +101,10 @@ class OutboxStore {
91
101
  const query = isInfinite
92
102
  ? `SELECT * FROM sync_outbox
93
103
  WHERE status = 'PENDING' OR status = 'FAILED'
94
- ORDER BY timestamp ASC LIMIT ?`
104
+ ORDER BY timestamp ASC, rowid ASC LIMIT ?`
95
105
  : `SELECT * FROM sync_outbox
96
106
  WHERE status = 'PENDING' OR (status = 'FAILED' AND retry_count < ?)
97
- ORDER BY timestamp ASC LIMIT ?`;
107
+ ORDER BY timestamp ASC, rowid ASC LIMIT ?`;
98
108
  const params = isInfinite ? [limit] : [maxRetries, limit];
99
109
  const rows = await db.execute(query, params);
100
110
  if (!rows || rows.length === 0)
@@ -116,11 +126,28 @@ class OutboxStore {
116
126
  * Retrieves active (non-FAILED) pending outbox records indexed by `${table_name}:${row_id}`.
117
127
  * Enables O(1) in-memory conflict lookup during delta ingestion, eliminating N+1 queries.
118
128
  */
119
- static async getActivePendingMap(tx) {
129
+ static async getActivePendingMap(tx, rowIds) {
120
130
  const map = new Map();
131
+ if (rowIds && rowIds.length === 0)
132
+ return map;
121
133
  try {
122
- const rows = await tx.execute(`SELECT * FROM sync_outbox WHERE status != 'FAILED' ORDER BY timestamp DESC`);
123
- if (!rows || rows.length === 0)
134
+ const rows = [];
135
+ if (rowIds && rowIds.length > 0) {
136
+ const uniqueRowIds = Array.from(new Set(rowIds));
137
+ for (const chunk of chunkArray(uniqueRowIds)) {
138
+ const placeholders = chunk.map(() => '?').join(',');
139
+ const chunkRows = await tx.execute(`SELECT * FROM sync_outbox WHERE status != 'FAILED' AND row_id IN (${placeholders}) ORDER BY timestamp DESC`, chunk);
140
+ if (chunkRows?.length)
141
+ rows.push(...chunkRows);
142
+ }
143
+ rows.sort((a, b) => Number(b.timestamp) - Number(a.timestamp));
144
+ }
145
+ else {
146
+ const allRows = await tx.execute(`SELECT * FROM sync_outbox WHERE status != 'FAILED' ORDER BY timestamp DESC`);
147
+ if (allRows?.length)
148
+ rows.push(...allRows);
149
+ }
150
+ if (rows.length === 0)
124
151
  return map;
125
152
  for (const r of rows) {
126
153
  const record = mapOutboxRow(r);
@@ -142,8 +169,10 @@ class OutboxStore {
142
169
  static async markProcessing(db, ids) {
143
170
  if (ids.length === 0)
144
171
  return;
145
- const placeholders = ids.map(() => '?').join(',');
146
- await db.execute(`UPDATE sync_outbox SET status = 'PROCESSING' WHERE id IN (${placeholders})`, ids);
172
+ for (const chunk of chunkArray(ids)) {
173
+ const placeholders = chunk.map(() => '?').join(',');
174
+ await db.execute(`UPDATE sync_outbox SET status = 'PROCESSING' WHERE id IN (${placeholders})`, chunk);
175
+ }
147
176
  }
148
177
  /**
149
178
  * Resets any orphaned 'PROCESSING' records back to 'PENDING' on startup.
@@ -163,8 +192,10 @@ class OutboxStore {
163
192
  static async deleteCompleted(db, ids) {
164
193
  if (ids.length === 0)
165
194
  return;
166
- const placeholders = ids.map(() => '?').join(',');
167
- await db.execute(`DELETE FROM sync_outbox WHERE id IN (${placeholders})`, ids);
195
+ for (const chunk of chunkArray(ids)) {
196
+ const placeholders = chunk.map(() => '?').join(',');
197
+ await db.execute(`DELETE FROM sync_outbox WHERE id IN (${placeholders})`, chunk);
198
+ }
168
199
  }
169
200
  /** Deletes outbox records matching one or more safe, parameterized clauses. */
170
201
  static async deleteMatching(db, clauses) {
@@ -230,12 +261,14 @@ class OutboxStore {
230
261
  static async markFailed(db, ids, errorMessage) {
231
262
  if (ids.length === 0)
232
263
  return;
233
- const placeholders = ids.map(() => '?').join(',');
234
- await db.execute(`UPDATE sync_outbox
235
- SET status = 'FAILED',
236
- retry_count = retry_count + 1,
237
- last_error = ?
238
- WHERE id IN (${placeholders})`, [errorMessage, ...ids]);
264
+ for (const chunk of chunkArray(ids)) {
265
+ const placeholders = chunk.map(() => '?').join(',');
266
+ await db.execute(`UPDATE sync_outbox
267
+ SET status = 'FAILED',
268
+ retry_count = retry_count + 1,
269
+ last_error = ?
270
+ WHERE id IN (${placeholders})`, [errorMessage, ...chunk]);
271
+ }
239
272
  }
240
273
  /**
241
274
  * Retrieves accurate counts of outbox records categorized by status.
@@ -272,10 +305,12 @@ class OutboxStore {
272
305
  static async retryFailed(db, ids) {
273
306
  try {
274
307
  if (ids && ids.length > 0) {
275
- const placeholders = ids.map(() => '?').join(',');
276
- await db.execute(`UPDATE sync_outbox
277
- SET status = 'PENDING', retry_count = 0, last_error = NULL
278
- WHERE status = 'FAILED' AND id IN (${placeholders})`, ids);
308
+ for (const chunk of chunkArray(ids)) {
309
+ const placeholders = chunk.map(() => '?').join(',');
310
+ await db.execute(`UPDATE sync_outbox
311
+ SET status = 'PENDING', retry_count = 0, last_error = NULL
312
+ WHERE status = 'FAILED' AND id IN (${placeholders})`, chunk);
313
+ }
279
314
  return ids.length;
280
315
  }
281
316
  else {
@@ -297,8 +332,10 @@ class OutboxStore {
297
332
  static async clearFailed(db, ids) {
298
333
  try {
299
334
  if (ids && ids.length > 0) {
300
- const placeholders = ids.map(() => '?').join(',');
301
- await db.execute(`DELETE FROM sync_outbox WHERE status = 'FAILED' AND id IN (${placeholders})`, ids);
335
+ for (const chunk of chunkArray(ids)) {
336
+ const placeholders = chunk.map(() => '?').join(',');
337
+ await db.execute(`DELETE FROM sync_outbox WHERE status = 'FAILED' AND id IN (${placeholders})`, chunk);
338
+ }
302
339
  return ids.length;
303
340
  }
304
341
  else {
@@ -38,6 +38,9 @@ function formatColumnIdentifier(col) {
38
38
  // ---------------------------------------------------------------------------
39
39
  // Module-scoped SQL compilation helpers (defined once, reused on every query)
40
40
  // ---------------------------------------------------------------------------
41
+ function escapeLikePattern(value) {
42
+ return String(value).replace(/[\\%_]/g, '\\$&');
43
+ }
41
44
  /**
42
45
  * Compiles a single column comparison value into one or more SQL fragments.
43
46
  * Supports null, boolean, scalar, and operator-object forms ($eq, $gt, $in, …).
@@ -57,66 +60,54 @@ function compileComparison(safeCol, val, params) {
57
60
  if (typeof val === 'object' && !Array.isArray(val)) {
58
61
  const ops = val;
59
62
  const subClauses = [];
60
- const eqVal = ops.$eq !== undefined ? ops.$eq : ops.eq;
61
- if (eqVal !== undefined) {
63
+ if (ops.$eq !== undefined) {
62
64
  subClauses.push(`${safeCol} = ?`);
63
- params.push(typeof eqVal === 'boolean' ? (eqVal ? 1 : 0) : eqVal);
65
+ params.push(typeof ops.$eq === 'boolean' ? (ops.$eq ? 1 : 0) : ops.$eq);
64
66
  }
65
- const neVal = ops.$ne !== undefined ? ops.$ne : ops.ne;
66
- if (neVal !== undefined) {
67
+ if (ops.$ne !== undefined) {
67
68
  subClauses.push(`${safeCol} != ?`);
68
- params.push(typeof neVal === 'boolean' ? (neVal ? 1 : 0) : neVal);
69
+ params.push(typeof ops.$ne === 'boolean' ? (ops.$ne ? 1 : 0) : ops.$ne);
69
70
  }
70
- const gtVal = ops.$gt !== undefined ? ops.$gt : ops.gt;
71
- if (gtVal !== undefined) {
71
+ if (ops.$gt !== undefined) {
72
72
  subClauses.push(`${safeCol} > ?`);
73
- params.push(gtVal);
73
+ params.push(ops.$gt);
74
74
  }
75
- const gteVal = ops.$gte !== undefined ? ops.$gte : ops.gte;
76
- if (gteVal !== undefined) {
75
+ if (ops.$gte !== undefined) {
77
76
  subClauses.push(`${safeCol} >= ?`);
78
- params.push(gteVal);
77
+ params.push(ops.$gte);
79
78
  }
80
- const ltVal = ops.$lt !== undefined ? ops.$lt : ops.lt;
81
- if (ltVal !== undefined) {
79
+ if (ops.$lt !== undefined) {
82
80
  subClauses.push(`${safeCol} < ?`);
83
- params.push(ltVal);
81
+ params.push(ops.$lt);
84
82
  }
85
- const lteVal = ops.$lte !== undefined ? ops.$lte : ops.lte;
86
- if (lteVal !== undefined) {
83
+ if (ops.$lte !== undefined) {
87
84
  subClauses.push(`${safeCol} <= ?`);
88
- params.push(lteVal);
85
+ params.push(ops.$lte);
89
86
  }
90
- const inVal = ops.$in !== undefined ? ops.$in : ops.in;
91
- if (Array.isArray(inVal) && inVal.length > 0) {
92
- const placeholders = inVal.map(() => '?').join(', ');
87
+ if (Array.isArray(ops.$in) && ops.$in.length > 0) {
88
+ const placeholders = ops.$in.map(() => '?').join(', ');
93
89
  subClauses.push(`${safeCol} IN (${placeholders})`);
94
- params.push(...inVal);
90
+ params.push(...ops.$in);
95
91
  }
96
- const ninVal = ops.$nin !== undefined ? ops.$nin : ops.nin;
97
- if (Array.isArray(ninVal) && ninVal.length > 0) {
98
- const placeholders = ninVal.map(() => '?').join(', ');
92
+ if (Array.isArray(ops.$nin) && ops.$nin.length > 0) {
93
+ const placeholders = ops.$nin.map(() => '?').join(', ');
99
94
  subClauses.push(`${safeCol} NOT IN (${placeholders})`);
100
- params.push(...ninVal);
101
- }
102
- const containsVal = ops.$contains !== undefined ? ops.$contains : ops.contains;
103
- if (containsVal !== undefined) {
104
- subClauses.push(`${safeCol} LIKE ?`);
105
- params.push(`%${containsVal}%`);
106
- }
107
- const startsWithVal = ops.$startsWith !== undefined ? ops.$startsWith : ops.startsWith;
108
- if (startsWithVal !== undefined) {
109
- subClauses.push(`${safeCol} LIKE ?`);
110
- params.push(`${startsWithVal}%`);
111
- }
112
- const endsWithVal = ops.$endsWith !== undefined ? ops.$endsWith : ops.endsWith;
113
- if (endsWithVal !== undefined) {
114
- subClauses.push(`${safeCol} LIKE ?`);
115
- params.push(`%${endsWithVal}`);
116
- }
117
- const nullVal = ops.$null !== undefined ? ops.$null : ops.null;
118
- if (nullVal !== undefined) {
119
- subClauses.push(nullVal ? `${safeCol} IS NULL` : `${safeCol} IS NOT NULL`);
95
+ params.push(...ops.$nin);
96
+ }
97
+ if (ops.$contains !== undefined) {
98
+ subClauses.push(`${safeCol} LIKE ? ESCAPE '\\'`);
99
+ params.push(`%${escapeLikePattern(ops.$contains)}%`);
100
+ }
101
+ if (ops.$startsWith !== undefined) {
102
+ subClauses.push(`${safeCol} LIKE ? ESCAPE '\\'`);
103
+ params.push(`${escapeLikePattern(ops.$startsWith)}%`);
104
+ }
105
+ if (ops.$endsWith !== undefined) {
106
+ subClauses.push(`${safeCol} LIKE ? ESCAPE '\\'`);
107
+ params.push(`%${escapeLikePattern(ops.$endsWith)}`);
108
+ }
109
+ if (ops.$null !== undefined) {
110
+ subClauses.push(ops.$null ? `${safeCol} IS NULL` : `${safeCol} IS NOT NULL`);
120
111
  }
121
112
  if (subClauses.length > 0) {
122
113
  return subClauses.join(' AND ');
@@ -7,7 +7,6 @@ import { SyncLogger, CustomLogger, LogLevel } from '../utils/logger.js';
7
7
  export interface SyncWorkerOptions {
8
8
  pushIntervalMs?: number;
9
9
  pullIntervalMs?: number;
10
- maxRetries?: number;
11
10
  retry?: number | RetryConfig;
12
11
  logger?: SyncLogger | CustomLogger | boolean;
13
12
  logLevel?: LogLevel;
@@ -19,6 +18,8 @@ export interface SyncWorkerOptions {
19
18
  autoSync?: boolean;
20
19
  syncScope?: Record<string, any> | (() => Record<string, any> | Promise<Record<string, any>>);
21
20
  autoPauseOnBackground?: boolean;
21
+ /** Timeout in ms for remote push/pull calls (0 to disable). Default: 30000 */
22
+ requestTimeoutMs?: number;
22
23
  }
23
24
  export declare class SyncWorker {
24
25
  private db;
@@ -34,6 +35,7 @@ export declare class SyncWorker {
34
35
  retryConfig: RetryConfig;
35
36
  private pushIntervalMs;
36
37
  private pullIntervalMs;
38
+ private requestTimeoutMs;
37
39
  private maxRetries;
38
40
  private autoPauseOnBackground;
39
41
  private isPaused;
@@ -54,6 +56,7 @@ export declare class SyncWorker {
54
56
  private deltaQueue;
55
57
  private statusRun?;
56
58
  private statusRerunRequested;
59
+ private activeControllers;
57
60
  private totalPushedOperations;
58
61
  private totalPulledDeltas;
59
62
  private totalPushCycles;
@@ -95,6 +98,7 @@ export declare class SyncWorker {
95
98
  * Dynamically sets or updates the active sync scope (e.g. switching active businessId or userId).
96
99
  */
97
100
  setSyncScope(scope?: Record<string, any> | (() => Record<string, any> | Promise<Record<string, any>>)): void;
101
+ private runWithAbortTimeout;
98
102
  private isOnline;
99
103
  /**
100
104
  * Emits a `sync:status` snapshot. Calls are coalesced: while one snapshot is being
@@ -123,7 +127,13 @@ export declare class SyncWorker {
123
127
  getLastPulledTimestamp(): Promise<number>;
124
128
  private loadCursor;
125
129
  resetSyncCursor(): Promise<void>;
126
- /** Clears a stale push error after an explicit sync stop/reconfiguration. */
130
+ /**
131
+ * Waits for any in-flight delta ingestion queue to drain.
132
+ */
133
+ flush(): Promise<void>;
134
+ /**
135
+ * Clears a stale push error after an explicit sync stop/reconfiguration.
136
+ */
127
137
  clearPushError(): void;
128
138
  /**
129
139
  * Collects real-time engine telemetry snapshot.