velocious 1.0.715 → 1.0.716

package/build/background-jobs/sync-replay-job.js

@@ -0,0 +1,79 @@
+// @ts-check
+
+import Logger from "../logger.js"
+import VelociousJob from "./platform-job.js"
+import {currentSyncClientOrNull} from "../sync/sync-client-registry.js"
+
+const logger = new Logger("SyncReplayJob")
+
+/**
+ * Durable, deduplicated replay of the device's pending sync queue.
+ *
+ * Offline-capable apps write local mutations with `syncClient.queue()`, which
+ * schedules an in-process replay attempt. That attempt lives only as long as the
+ * JavaScript runtime, so a scan (or any other mutation) that happens while the app
+ * is closing, backgrounding, or briefly online can leave rows pending. Enqueueing
+ * this job after such a mutation makes the replay durable: the local background-jobs
+ * adapter stores the trigger in SQLite, runs it in process as soon as the app is
+ * active, and collapses overlapping triggers onto one queued job.
+ *
+ * `perform()` is deliberately best-effort. Pending rows are only deleted after the
+ * backend acknowledges them, so a failed or offline replay leaves the queue intact
+ * for the next enqueue (next mutation, focus, or foreground trigger) instead of
+ * consuming the job's retries on a device that may stay offline for hours.
+ *
+ * Apps register it next to their other jobs and enqueue it after local mutations:
+ *
+ * ```js
+ * backgroundJobs: {mode: "background", jobClasses: [SyncReplayJob]}
+ *
+ * await SyncReplayJob.enqueue()
+ * ```
+ * @augments {VelociousJob}
+ */
+export default class SyncReplayJob extends VelociousJob {
+  /**
+   * Returns the stable job name used by the persisted queue.
+   * @returns {string} - Job name.
+   */
+  static jobName() { return "syncReplay" }
+
+  /**
+   * Enqueues one deduplicated replay. Resolves after the durable enqueue, not after
+   * the replay finishes, so callers can stay on the synchronous local path.
+   * @returns {Promise<string>} - Queued job id.
+   */
+  static async enqueue() {
+    return await this.performLaterWithOptions({
+      args: [],
+      options: {
+        concurrencyKey: "sync-replay",
+        deduplicateWhileQueued: true,
+        maxConcurrency: 1
+      }
+    })
+  }
+
+  /**
+   * Drains the pending sync queue through the app's current sync client.
+   * @returns {Promise<void>}
+   */
+  async perform() {
+    const syncClient = currentSyncClientOrNull()
+
+    if (!syncClient) {
+      void logger.debug("sync replay skipped because no sync client is registered")
+
+      return
+    }
+
+    try {
+      await syncClient.replayPending()
+    } catch (error) {
+      // Pending rows survive a failed or offline replay, so the next enqueue retries
+      // them. Re-throwing would make the adapter retry a device that may be offline
+      // for hours and mark healthy offline periods as job failures.
+      void logger.error(() => ["sync replay failed (pending rows stay queued)", error])
+    }
+  }
+}

package/build/src/background-jobs/sync-replay-job.d.ts

@@ -0,0 +1,45 @@
+import VelociousJob from "./platform-job.js";
+/**
+ * Durable, deduplicated replay of the device's pending sync queue.
+ *
+ * Offline-capable apps write local mutations with `syncClient.queue()`, which
+ * schedules an in-process replay attempt. That attempt lives only as long as the
+ * JavaScript runtime, so a scan (or any other mutation) that happens while the app
+ * is closing, backgrounding, or briefly online can leave rows pending. Enqueueing
+ * this job after such a mutation makes the replay durable: the local background-jobs
+ * adapter stores the trigger in SQLite, runs it in process as soon as the app is
+ * active, and collapses overlapping triggers onto one queued job.
+ *
+ * `perform()` is deliberately best-effort. Pending rows are only deleted after the
+ * backend acknowledges them, so a failed or offline replay leaves the queue intact
+ * for the next enqueue (next mutation, focus, or foreground trigger) instead of
+ * consuming the job's retries on a device that may stay offline for hours.
+ *
+ * Apps register it next to their other jobs and enqueue it after local mutations:
+ *
+ * ```js
+ * backgroundJobs: {mode: "background", jobClasses: [SyncReplayJob]}
+ *
+ * await SyncReplayJob.enqueue()
+ * ```
+ * @augments {VelociousJob}
+ */
+export default class SyncReplayJob extends VelociousJob {
+    /**
+     * Returns the stable job name used by the persisted queue.
+     * @returns {string} - Job name.
+     */
+    static jobName(): string;
+    /**
+     * Enqueues one deduplicated replay. Resolves after the durable enqueue, not after
+     * the replay finishes, so callers can stay on the synchronous local path.
+     * @returns {Promise<string>} - Queued job id.
+     */
+    static enqueue(): Promise<string>;
+    /**
+     * Drains the pending sync queue through the app's current sync client.
+     * @returns {Promise<void>}
+     */
+    perform(): Promise<void>;
+}
+//# sourceMappingURL=sync-replay-job.d.ts.map

package/build/src/background-jobs/sync-replay-job.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync-replay-job.d.ts","sourceRoot":"","sources":["../../../src/background-jobs/sync-replay-job.js"],"names":[],"mappings":"AAGA,OAAO,YAAY,MAAM,mBAAmB,CAAA;AAK5C;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,CAAC,OAAO,OAAO,aAAc,SAAQ,YAAY;IACrD;;;OAGG;IACH,MAAM,CAAC,OAAO,IAFD,MAAM,CAEqB;IAExC;;;;OAIG;IACH,OAAa,OAAO,IAFP,OAAO,CAAC,MAAM,CAAC,CAW3B;IAED;;;OAGG;IACG,OAAO,IAFA,OAAO,CAAC,IAAI,CAAC,CAmBzB;CACF"}

package/build/src/background-jobs/sync-replay-job.js

@@ -0,0 +1,73 @@
+// @ts-check
+import Logger from "../logger.js";
+import VelociousJob from "./platform-job.js";
+import { currentSyncClientOrNull } from "../sync/sync-client-registry.js";
+const logger = new Logger("SyncReplayJob");
+/**
+ * Durable, deduplicated replay of the device's pending sync queue.
+ *
+ * Offline-capable apps write local mutations with `syncClient.queue()`, which
+ * schedules an in-process replay attempt. That attempt lives only as long as the
+ * JavaScript runtime, so a scan (or any other mutation) that happens while the app
+ * is closing, backgrounding, or briefly online can leave rows pending. Enqueueing
+ * this job after such a mutation makes the replay durable: the local background-jobs
+ * adapter stores the trigger in SQLite, runs it in process as soon as the app is
+ * active, and collapses overlapping triggers onto one queued job.
+ *
+ * `perform()` is deliberately best-effort. Pending rows are only deleted after the
+ * backend acknowledges them, so a failed or offline replay leaves the queue intact
+ * for the next enqueue (next mutation, focus, or foreground trigger) instead of
+ * consuming the job's retries on a device that may stay offline for hours.
+ *
+ * Apps register it next to their other jobs and enqueue it after local mutations:
+ *
+ * ```js
+ * backgroundJobs: {mode: "background", jobClasses: [SyncReplayJob]}
+ *
+ * await SyncReplayJob.enqueue()
+ * ```
+ * @augments {VelociousJob}
+ */
+export default class SyncReplayJob extends VelociousJob {
+    /**
+     * Returns the stable job name used by the persisted queue.
+     * @returns {string} - Job name.
+     */
+    static jobName() { return "syncReplay"; }
+    /**
+     * Enqueues one deduplicated replay. Resolves after the durable enqueue, not after
+     * the replay finishes, so callers can stay on the synchronous local path.
+     * @returns {Promise<string>} - Queued job id.
+     */
+    static async enqueue() {
+        return await this.performLaterWithOptions({
+            args: [],
+            options: {
+                concurrencyKey: "sync-replay",
+                deduplicateWhileQueued: true,
+                maxConcurrency: 1
+            }
+        });
+    }
+    /**
+     * Drains the pending sync queue through the app's current sync client.
+     * @returns {Promise<void>}
+     */
+    async perform() {
+        const syncClient = currentSyncClientOrNull();
+        if (!syncClient) {
+            void logger.debug("sync replay skipped because no sync client is registered");
+            return;
+        }
+        try {
+            await syncClient.replayPending();
+        }
+        catch (error) {
+            // Pending rows survive a failed or offline replay, so the next enqueue retries
+            // them. Re-throwing would make the adapter retry a device that may be offline
+            // for hours and mark healthy offline periods as job failures.
+            void logger.error(() => ["sync replay failed (pending rows stay queued)", error]);
+        }
+    }
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic3luYy1yZXBsYXktam9iLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vLi4vc3JjL2JhY2tncm91bmQtam9icy9zeW5jLXJlcGxheS1qb2IuanMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsWUFBWTtBQUVaLE9BQU8sTUFBTSxNQUFNLGNBQWMsQ0FBQTtBQUNqQyxPQUFPLFlBQVksTUFBTSxtQkFBbUIsQ0FBQTtBQUM1QyxPQUFPLEVBQUMsdUJBQXVCLEVBQUMsTUFBTSxpQ0FBaUMsQ0FBQTtBQUV2RSxNQUFNLE1BQU0sR0FBRyxJQUFJLE1BQU0sQ0FBQyxlQUFlLENBQUMsQ0FBQTtBQUUxQzs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7O0dBd0JHO0FBQ0gsTUFBTSxDQUFDLE9BQU8sT0FBTyxhQUFjLFNBQVEsWUFBWTtJQUNyRDs7O09BR0c7SUFDSCxNQUFNLENBQUMsT0FBTyxLQUFLLE9BQU8sWUFBWSxDQUFBLENBQUMsQ0FBQztJQUV4Qzs7OztPQUlHO0lBQ0gsTUFBTSxDQUFDLEtBQUssQ0FBQyxPQUFPO1FBQ2xCLE9BQU8sTUFBTSxJQUFJLENBQUMsdUJBQXVCLENBQUM7WUFDeEMsSUFBSSxFQUFFLEVBQUU7WUFDUixPQUFPLEVBQUU7Z0JBQ1AsY0FBYyxFQUFFLGFBQWE7Z0JBQzdCLHNCQUFzQixFQUFFLElBQUk7Z0JBQzVCLGNBQWMsRUFBRSxDQUFDO2FBQ2xCO1NBQ0YsQ0FBQyxDQUFBO0lBQ0osQ0FBQztJQUVEOzs7T0FHRztJQUNILEtBQUssQ0FBQyxPQUFPO1FBQ1gsTUFBTSxVQUFVLEdBQUcsdUJBQXVCLEVBQUUsQ0FBQTtRQUU1QyxJQUFJLENBQUMsVUFBVSxFQUFFLENBQUM7WUFDaEIsS0FBSyxNQUFNLENBQUMsS0FBSyxDQUFDLDBEQUEwRCxDQUFDLENBQUE7WUFFN0UsT0FBTTtRQUNSLENBQUM7UUFFRCxJQUFJLENBQUM7WUFDSCxNQUFNLFVBQVUsQ0FBQyxhQUFhLEVBQUUsQ0FBQTtRQUNsQyxDQUFDO1FBQUMsT0FBTyxLQUFLLEVBQUUsQ0FBQztZQUNmLCtFQUErRTtZQUMvRSw4RUFBOEU7WUFDOUUsOERBQThEO1lBQzlELEtBQUssTUFBTSxDQUFDLEtBQUssQ0FBQyxHQUFHLEVBQUUsQ0FBQyxDQUFDLCtDQUErQyxFQUFFLEtBQUssQ0FBQyxDQUFDLENBQUE7UUFDbkYsQ0FBQztJQUNILENBQUM7Q0FDRiIsInNvdXJjZXNDb250ZW50IjpbIi8vIEB0cy1jaGVja1xuXG5pbXBvcnQgTG9nZ2VyIGZyb20gXCIuLi9sb2dnZXIuanNcIlxuaW1wb3J0IFZlbG9jaW91c0pvYiBmcm9tIFwiLi9wbGF0Zm9ybS1qb2IuanNcIlxuaW1wb3J0IHtjdXJyZW50U3luY0NsaWVudE9yTnVsbH0gZnJvbSBcIi4uL3N5bmMvc3luYy1jbGllbnQtcmVnaXN0cnkuanNcIlxuXG5jb25zdCBsb2dnZXIgPSBuZXcgTG9nZ2VyKFwiU3luY1JlcGxheUpvYlwiKVxuXG4vKipcbiAqIER1cmFibGUsIGRlZHVwbGljYXRlZCByZXBsYXkgb2YgdGhlIGRldmljZSdzIHBlbmRpbmcgc3luYyBxdWV1ZS5cbiAqXG4gKiBPZmZsaW5lLWNhcGFibGUgYXBwcyB3cml0ZSBsb2NhbCBtdXRhdGlvbnMgd2l0aCBgc3luY0NsaWVudC5xdWV1ZSgpYCwgd2hpY2hcbiAqIHNjaGVkdWxlcyBhbiBpbi1wcm9jZXNzIHJlcGxheSBhdHRlbXB0LiBUaGF0IGF0dGVtcHQgbGl2ZXMgb25seSBhcyBsb25nIGFzIHRoZVxuICogSmF2YVNjcmlwdCBydW50aW1lLCBzbyBhIHNjYW4gKG9yIGFueSBvdGhlciBtdXRhdGlvbikgdGhhdCBoYXBwZW5zIHdoaWxlIHRoZSBhcHBcbiAqIGlzIGNsb3NpbmcsIGJhY2tncm91bmRpbmcsIG9yIGJyaWVmbHkgb25saW5lIGNhbiBsZWF2ZSByb3dzIHBlbmRpbmcuIEVucXVldWVpbmdcbiAqIHRoaXMgam9iIGFmdGVyIHN1Y2ggYSBtdXRhdGlvbiBtYWtlcyB0aGUgcmVwbGF5IGR1cmFibGU6IHRoZSBsb2NhbCBiYWNrZ3JvdW5kLWpvYnNcbiAqIGFkYXB0ZXIgc3RvcmVzIHRoZSB0cmlnZ2VyIGluIFNRTGl0ZSwgcnVucyBpdCBpbiBwcm9jZXNzIGFzIHNvb24gYXMgdGhlIGFwcCBpc1xuICogYWN0aXZlLCBhbmQgY29sbGFwc2VzIG92ZXJsYXBwaW5nIHRyaWdnZXJzIG9udG8gb25lIHF1ZXVlZCBqb2IuXG4gKlxuICogYHBlcmZvcm0oKWAgaXMgZGVsaWJlcmF0ZWx5IGJlc3QtZWZmb3J0LiBQZW5kaW5nIHJvd3MgYXJlIG9ubHkgZGVsZXRlZCBhZnRlciB0aGVcbiAqIGJhY2tlbmQgYWNrbm93bGVkZ2VzIHRoZW0sIHNvIGEgZmFpbGVkIG9yIG9mZmxpbmUgcmVwbGF5IGxlYXZlcyB0aGUgcXVldWUgaW50YWN0XG4gKiBmb3IgdGhlIG5leHQgZW5xdWV1ZSAobmV4dCBtdXRhdGlvbiwgZm9jdXMsIG9yIGZvcmVncm91bmQgdHJpZ2dlcikgaW5zdGVhZCBvZlxuICogY29uc3VtaW5nIHRoZSBqb2IncyByZXRyaWVzIG9uIGEgZGV2aWNlIHRoYXQgbWF5IHN0YXkgb2ZmbGluZSBmb3IgaG91cnMuXG4gKlxuICogQXBwcyByZWdpc3RlciBpdCBuZXh0IHRvIHRoZWlyIG90aGVyIGpvYnMgYW5kIGVucXVldWUgaXQgYWZ0ZXIgbG9jYWwgbXV0YXRpb25zOlxuICpcbiAqIGBgYGpzXG4gKiBiYWNrZ3JvdW5kSm9iczoge21vZGU6IFwiYmFja2dyb3VuZFwiLCBqb2JDbGFzc2VzOiBbU3luY1JlcGxheUpvYl19XG4gKlxuICogYXdhaXQgU3luY1JlcGxheUpvYi5lbnF1ZXVlKClcbiAqIGBgYFxuICogQGF1Z21lbnRzIHtWZWxvY2lvdXNKb2J9XG4gKi9cbmV4cG9ydCBkZWZhdWx0IGNsYXNzIFN5bmNSZXBsYXlKb2IgZXh0ZW5kcyBWZWxvY2lvdXNKb2Ige1xuICAvKipcbiAgICogUmV0dXJucyB0aGUgc3RhYmxlIGpvYiBuYW1lIHVzZWQgYnkgdGhlIHBlcnNpc3RlZCBxdWV1ZS5cbiAgICogQHJldHVybnMge3N0cmluZ30gLSBKb2IgbmFtZS5cbiAgICovXG4gIHN0YXRpYyBqb2JOYW1lKCkgeyByZXR1cm4gXCJzeW5jUmVwbGF5XCIgfVxuXG4gIC8qKlxuICAgKiBFbnF1ZXVlcyBvbmUgZGVkdXBsaWNhdGVkIHJlcGxheS4gUmVzb2x2ZXMgYWZ0ZXIgdGhlIGR1cmFibGUgZW5xdWV1ZSwgbm90IGFmdGVyXG4gICAqIHRoZSByZXBsYXkgZmluaXNoZXMsIHNvIGNhbGxlcnMgY2FuIHN0YXkgb24gdGhlIHN5bmNocm9ub3VzIGxvY2FsIHBhdGguXG4gICAqIEByZXR1cm5zIHtQcm9taXNlPHN0cmluZz59IC0gUXVldWVkIGpvYiBpZC5cbiAgICovXG4gIHN0YXRpYyBhc3luYyBlbnF1ZXVlKCkge1xuICAgIHJldHVybiBhd2FpdCB0aGlzLnBlcmZvcm1MYXRlcldpdGhPcHRpb25zKHtcbiAgICAgIGFyZ3M6IFtdLFxuICAgICAgb3B0aW9uczoge1xuICAgICAgICBjb25jdXJyZW5jeUtleTogXCJzeW5jLXJlcGxheVwiLFxuICAgICAgICBkZWR1cGxpY2F0ZVdoaWxlUXVldWVkOiB0cnVlLFxuICAgICAgICBtYXhDb25jdXJyZW5jeTogMVxuICAgICAgfVxuICAgIH0pXG4gIH1cblxuICAvKipcbiAgICogRHJhaW5zIHRoZSBwZW5kaW5nIHN5bmMgcXVldWUgdGhyb3VnaCB0aGUgYXBwJ3MgY3VycmVudCBzeW5jIGNsaWVudC5cbiAgICogQHJldHVybnMge1Byb21pc2U8dm9pZD59XG4gICAqL1xuICBhc3luYyBwZXJmb3JtKCkge1xuICAgIGNvbnN0IHN5bmNDbGllbnQgPSBjdXJyZW50U3luY0NsaWVudE9yTnVsbCgpXG5cbiAgICBpZiAoIXN5bmNDbGllbnQpIHtcbiAgICAgIHZvaWQgbG9nZ2VyLmRlYnVnKFwic3luYyByZXBsYXkgc2tpcHBlZCBiZWNhdXNlIG5vIHN5bmMgY2xpZW50IGlzIHJlZ2lzdGVyZWRcIilcblxuICAgICAgcmV0dXJuXG4gICAgfVxuXG4gICAgdHJ5IHtcbiAgICAgIGF3YWl0IHN5bmNDbGllbnQucmVwbGF5UGVuZGluZygpXG4gICAgfSBjYXRjaCAoZXJyb3IpIHtcbiAgICAgIC8vIFBlbmRpbmcgcm93cyBzdXJ2aXZlIGEgZmFpbGVkIG9yIG9mZmxpbmUgcmVwbGF5LCBzbyB0aGUgbmV4dCBlbnF1ZXVlIHJldHJpZXNcbiAgICAgIC8vIHRoZW0uIFJlLXRocm93aW5nIHdvdWxkIG1ha2UgdGhlIGFkYXB0ZXIgcmV0cnkgYSBkZXZpY2UgdGhhdCBtYXkgYmUgb2ZmbGluZVxuICAgICAgLy8gZm9yIGhvdXJzIGFuZCBtYXJrIGhlYWx0aHkgb2ZmbGluZSBwZXJpb2RzIGFzIGpvYiBmYWlsdXJlcy5cbiAgICAgIHZvaWQgbG9nZ2VyLmVycm9yKCgpID0+IFtcInN5bmMgcmVwbGF5IGZhaWxlZCAocGVuZGluZyByb3dzIHN0YXkgcXVldWVkKVwiLCBlcnJvcl0pXG4gICAgfVxuICB9XG59XG4iXX0=

package/build/src/sync/sync-client-registry.d.ts

@@ -9,4 +9,13 @@ export declare function setCurrentSyncClient(client: ReturnType<typeof JSON.pars
  * @returns {ReturnType<typeof JSON.parse>} Current sync client.
  */
 export declare function currentSyncClient(): ReturnType<typeof JSON.parse>;
+/**
+ * Returns the current sync client when one is registered.
+ *
+ * Background jobs that replay the sync queue can legitimately run before an app has
+ * registered its client, or after it cleared it on sign-out. They need a non-throwing
+ * lookup so that state is a no-op instead of a failed job.
+ * @returns {ReturnType<typeof JSON.parse> | null} Current sync client, or null.
+ */
+export declare function currentSyncClientOrNull(): ReturnType<typeof JSON.parse> | null;
 //# sourceMappingURL=sync-client-registry.d.ts.map

package/build/src/sync/sync-client-registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sync-client-registry.d.ts","sourceRoot":"","sources":["../../../src/sync/sync-client-registry.js"],"names":[],"mappings":"AAYA;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAHhC,UAAU,CAAC,OAAO,IAAI,CAAC,KAAK,CAGI,GAF9B,IAAI,CAIhB;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,IAFpB,UAAU,CAAC,OAAO,IAAI,CAAC,KAAK,CAAC,CAMzC"}
+{"version":3,"file":"sync-client-registry.d.ts","sourceRoot":"","sources":["../../../src/sync/sync-client-registry.js"],"names":[],"mappings":"AAYA;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAHhC,UAAU,CAAC,OAAO,IAAI,CAAC,KAAK,CAGI,GAF9B,IAAI,CAIhB;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,IAFpB,UAAU,CAAC,OAAO,IAAI,CAAC,KAAK,CAAC,CAMzC;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,IAF1B,UAAU,CAAC,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,IAAI,CAIhD"}

package/build/src/sync/sync-client-registry.js

@@ -24,4 +24,15 @@ export function currentSyncClient() {
         throw new Error("No sync client configured - create a SyncClient and call setCurrent() on it first");
     return currentClient;
 }
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic3luYy1jbGllbnQtcmVnaXN0cnkuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi8uLi9zcmMvc3luYy9zeW5jLWNsaWVudC1yZWdpc3RyeS5qcyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxZQUFZO0FBRVo7Ozs7O0dBS0c7QUFFSCw0Q0FBNEM7QUFDNUMsSUFBSSxhQUFhLEdBQUcsSUFBSSxDQUFBO0FBRXhCOzs7O0dBSUc7QUFDSCxNQUFNLFVBQVUsb0JBQW9CLENBQUMsTUFBTTtJQUN6QyxhQUFhLEdBQUcsTUFBTSxDQUFBO0FBQ3hCLENBQUM7QUFFRDs7O0dBR0c7QUFDSCxNQUFNLFVBQVUsaUJBQWlCO0lBQy9CLElBQUksQ0FBQyxhQUFhO1FBQUUsTUFBTSxJQUFJLEtBQUssQ0FBQyxtRkFBbUYsQ0FBQyxDQUFBO0lBRXhILE9BQU8sYUFBYSxDQUFBO0FBQ3RCLENBQUMiLCJzb3VyY2VzQ29udGVudCI6WyIvLyBAdHMtY2hlY2tcblxuLyoqXG4gKiBSZWdpc3RyeSBmb3IgdGhlIGFwcCdzIGN1cnJlbnQgc3luYyBjbGllbnQuXG4gKlxuICogS2VwdCBkZXBlbmRlbmN5LWZyZWUgc28gY2xpZW50LWJ1bmRsZWQgbW9kdWxlcyAobGlrZSB0aGUgcXVlcnkgbGF5ZXIpIGNhblxuICogZGVsZWdhdGUgdG8gYSBjb25maWd1cmVkIHN5bmMgY2xpZW50IHdpdGhvdXQgaW1wb3J0aW5nIHRoZSBzeW5jIHN0YWNrLlxuICovXG5cbi8qKiBAdHlwZSB7UmV0dXJuVHlwZTx0eXBlb2YgSlNPTi5wYXJzZT59ICovXG5sZXQgY3VycmVudENsaWVudCA9IG51bGxcblxuLyoqXG4gKiBSZWdpc3RlcnMgdGhlIGN1cnJlbnQgc3luYyBjbGllbnQuXG4gKiBAcGFyYW0ge1JldHVyblR5cGU8dHlwZW9mIEpTT04ucGFyc2U+fSBjbGllbnQgLSBDb25maWd1cmVkIHN5bmMgY2xpZW50IChvciBudWxsIHRvIGNsZWFyKS5cbiAqIEByZXR1cm5zIHt2b2lkfVxuICovXG5leHBvcnQgZnVuY3Rpb24gc2V0Q3VycmVudFN5bmNDbGllbnQoY2xpZW50KSB7XG4gIGN1cnJlbnRDbGllbnQgPSBjbGllbnRcbn1cblxuLyoqXG4gKiBSZXR1cm5zIHRoZSBjdXJyZW50IHN5bmMgY2xpZW50LlxuICogQHJldHVybnMge1JldHVyblR5cGU8dHlwZW9mIEpTT04ucGFyc2U+fSBDdXJyZW50IHN5bmMgY2xpZW50LlxuICovXG5leHBvcnQgZnVuY3Rpb24gY3VycmVudFN5bmNDbGllbnQoKSB7XG4gIGlmICghY3VycmVudENsaWVudCkgdGhyb3cgbmV3IEVycm9yKFwiTm8gc3luYyBjbGllbnQgY29uZmlndXJlZCAtIGNyZWF0ZSBhIFN5bmNDbGllbnQgYW5kIGNhbGwgc2V0Q3VycmVudCgpIG9uIGl0IGZpcnN0XCIpXG5cbiAgcmV0dXJuIGN1cnJlbnRDbGllbnRcbn1cbiJdfQ==
+/**
+ * Returns the current sync client when one is registered.
+ *
+ * Background jobs that replay the sync queue can legitimately run before an app has
+ * registered its client, or after it cleared it on sign-out. They need a non-throwing
+ * lookup so that state is a no-op instead of a failed job.
+ * @returns {ReturnType<typeof JSON.parse> | null} Current sync client, or null.
+ */
+export function currentSyncClientOrNull() {
+    return currentClient;
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic3luYy1jbGllbnQtcmVnaXN0cnkuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi8uLi9zcmMvc3luYy9zeW5jLWNsaWVudC1yZWdpc3RyeS5qcyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxZQUFZO0FBRVo7Ozs7O0dBS0c7QUFFSCw0Q0FBNEM7QUFDNUMsSUFBSSxhQUFhLEdBQUcsSUFBSSxDQUFBO0FBRXhCOzs7O0dBSUc7QUFDSCxNQUFNLFVBQVUsb0JBQW9CLENBQUMsTUFBTTtJQUN6QyxhQUFhLEdBQUcsTUFBTSxDQUFBO0FBQ3hCLENBQUM7QUFFRDs7O0dBR0c7QUFDSCxNQUFNLFVBQVUsaUJBQWlCO0lBQy9CLElBQUksQ0FBQyxhQUFhO1FBQUUsTUFBTSxJQUFJLEtBQUssQ0FBQyxtRkFBbUYsQ0FBQyxDQUFBO0lBRXhILE9BQU8sYUFBYSxDQUFBO0FBQ3RCLENBQUM7QUFFRDs7Ozs7OztHQU9HO0FBQ0gsTUFBTSxVQUFVLHVCQUF1QjtJQUNyQyxPQUFPLGFBQWEsQ0FBQTtBQUN0QixDQUFDIiwic291cmNlc0NvbnRlbnQiOlsiLy8gQHRzLWNoZWNrXG5cbi8qKlxuICogUmVnaXN0cnkgZm9yIHRoZSBhcHAncyBjdXJyZW50IHN5bmMgY2xpZW50LlxuICpcbiAqIEtlcHQgZGVwZW5kZW5jeS1mcmVlIHNvIGNsaWVudC1idW5kbGVkIG1vZHVsZXMgKGxpa2UgdGhlIHF1ZXJ5IGxheWVyKSBjYW5cbiAqIGRlbGVnYXRlIHRvIGEgY29uZmlndXJlZCBzeW5jIGNsaWVudCB3aXRob3V0IGltcG9ydGluZyB0aGUgc3luYyBzdGFjay5cbiAqL1xuXG4vKiogQHR5cGUge1JldHVyblR5cGU8dHlwZW9mIEpTT04ucGFyc2U+fSAqL1xubGV0IGN1cnJlbnRDbGllbnQgPSBudWxsXG5cbi8qKlxuICogUmVnaXN0ZXJzIHRoZSBjdXJyZW50IHN5bmMgY2xpZW50LlxuICogQHBhcmFtIHtSZXR1cm5UeXBlPHR5cGVvZiBKU09OLnBhcnNlPn0gY2xpZW50IC0gQ29uZmlndXJlZCBzeW5jIGNsaWVudCAob3IgbnVsbCB0byBjbGVhcikuXG4gKiBAcmV0dXJucyB7dm9pZH1cbiAqL1xuZXhwb3J0IGZ1bmN0aW9uIHNldEN1cnJlbnRTeW5jQ2xpZW50KGNsaWVudCkge1xuICBjdXJyZW50Q2xpZW50ID0gY2xpZW50XG59XG5cbi8qKlxuICogUmV0dXJucyB0aGUgY3VycmVudCBzeW5jIGNsaWVudC5cbiAqIEByZXR1cm5zIHtSZXR1cm5UeXBlPHR5cGVvZiBKU09OLnBhcnNlPn0gQ3VycmVudCBzeW5jIGNsaWVudC5cbiAqL1xuZXhwb3J0IGZ1bmN0aW9uIGN1cnJlbnRTeW5jQ2xpZW50KCkge1xuICBpZiAoIWN1cnJlbnRDbGllbnQpIHRocm93IG5ldyBFcnJvcihcIk5vIHN5bmMgY2xpZW50IGNvbmZpZ3VyZWQgLSBjcmVhdGUgYSBTeW5jQ2xpZW50IGFuZCBjYWxsIHNldEN1cnJlbnQoKSBvbiBpdCBmaXJzdFwiKVxuXG4gIHJldHVybiBjdXJyZW50Q2xpZW50XG59XG5cbi8qKlxuICogUmV0dXJucyB0aGUgY3VycmVudCBzeW5jIGNsaWVudCB3aGVuIG9uZSBpcyByZWdpc3RlcmVkLlxuICpcbiAqIEJhY2tncm91bmQgam9icyB0aGF0IHJlcGxheSB0aGUgc3luYyBxdWV1ZSBjYW4gbGVnaXRpbWF0ZWx5IHJ1biBiZWZvcmUgYW4gYXBwIGhhc1xuICogcmVnaXN0ZXJlZCBpdHMgY2xpZW50LCBvciBhZnRlciBpdCBjbGVhcmVkIGl0IG9uIHNpZ24tb3V0LiBUaGV5IG5lZWQgYSBub24tdGhyb3dpbmdcbiAqIGxvb2t1cCBzbyB0aGF0IHN0YXRlIGlzIGEgbm8tb3AgaW5zdGVhZCBvZiBhIGZhaWxlZCBqb2IuXG4gKiBAcmV0dXJucyB7UmV0dXJuVHlwZTx0eXBlb2YgSlNPTi5wYXJzZT4gfCBudWxsfSBDdXJyZW50IHN5bmMgY2xpZW50LCBvciBudWxsLlxuICovXG5leHBvcnQgZnVuY3Rpb24gY3VycmVudFN5bmNDbGllbnRPck51bGwoKSB7XG4gIHJldHVybiBjdXJyZW50Q2xpZW50XG59XG4iXX0=

package/build/sync/sync-client-registry.js

@@ -28,3 +28,15 @@ export function currentSyncClient() {
 
   return currentClient
 }
+
+/**
+ * Returns the current sync client when one is registered.
+ *
+ * Background jobs that replay the sync queue can legitimately run before an app has
+ * registered its client, or after it cleared it on sign-out. They need a non-throwing
+ * lookup so that state is a no-op instead of a failed job.
+ * @returns {ReturnType<typeof JSON.parse> | null} Current sync client, or null.
+ */
+export function currentSyncClientOrNull() {
+  return currentClient
+}

package/package.json

@@ -3,7 +3,7 @@
     "velocious": "build/bin/velocious.js"
   },
   "name": "velocious",
-  "version": "1.0.715",
+  "version": "1.0.716",
   "main": "build/index.js",
   "types": "build/index.d.ts",
   "files": [

package/src/background-jobs/sync-replay-job.js

@@ -0,0 +1,79 @@
+// @ts-check
+
+import Logger from "../logger.js"
+import VelociousJob from "./platform-job.js"
+import {currentSyncClientOrNull} from "../sync/sync-client-registry.js"
+
+const logger = new Logger("SyncReplayJob")
+
+/**
+ * Durable, deduplicated replay of the device's pending sync queue.
+ *
+ * Offline-capable apps write local mutations with `syncClient.queue()`, which
+ * schedules an in-process replay attempt. That attempt lives only as long as the
+ * JavaScript runtime, so a scan (or any other mutation) that happens while the app
+ * is closing, backgrounding, or briefly online can leave rows pending. Enqueueing
+ * this job after such a mutation makes the replay durable: the local background-jobs
+ * adapter stores the trigger in SQLite, runs it in process as soon as the app is
+ * active, and collapses overlapping triggers onto one queued job.
+ *
+ * `perform()` is deliberately best-effort. Pending rows are only deleted after the
+ * backend acknowledges them, so a failed or offline replay leaves the queue intact
+ * for the next enqueue (next mutation, focus, or foreground trigger) instead of
+ * consuming the job's retries on a device that may stay offline for hours.
+ *
+ * Apps register it next to their other jobs and enqueue it after local mutations:
+ *
+ * ```js
+ * backgroundJobs: {mode: "background", jobClasses: [SyncReplayJob]}
+ *
+ * await SyncReplayJob.enqueue()
+ * ```
+ * @augments {VelociousJob}
+ */
+export default class SyncReplayJob extends VelociousJob {
+  /**
+   * Returns the stable job name used by the persisted queue.
+   * @returns {string} - Job name.
+   */
+  static jobName() { return "syncReplay" }
+
+  /**
+   * Enqueues one deduplicated replay. Resolves after the durable enqueue, not after
+   * the replay finishes, so callers can stay on the synchronous local path.
+   * @returns {Promise<string>} - Queued job id.
+   */
+  static async enqueue() {
+    return await this.performLaterWithOptions({
+      args: [],
+      options: {
+        concurrencyKey: "sync-replay",
+        deduplicateWhileQueued: true,
+        maxConcurrency: 1
+      }
+    })
+  }
+
+  /**
+   * Drains the pending sync queue through the app's current sync client.
+   * @returns {Promise<void>}
+   */
+  async perform() {
+    const syncClient = currentSyncClientOrNull()
+
+    if (!syncClient) {
+      void logger.debug("sync replay skipped because no sync client is registered")
+
+      return
+    }
+
+    try {
+      await syncClient.replayPending()
+    } catch (error) {
+      // Pending rows survive a failed or offline replay, so the next enqueue retries
+      // them. Re-throwing would make the adapter retry a device that may be offline
+      // for hours and mark healthy offline periods as job failures.
+      void logger.error(() => ["sync replay failed (pending rows stay queued)", error])
+    }
+  }
+}

package/src/sync/sync-client-registry.js

@@ -28,3 +28,15 @@ export function currentSyncClient() {
 
   return currentClient
 }
+
+/**
+ * Returns the current sync client when one is registered.
+ *
+ * Background jobs that replay the sync queue can legitimately run before an app has
+ * registered its client, or after it cleared it on sign-out. They need a non-throwing
+ * lookup so that state is a no-op instead of a failed job.
+ * @returns {ReturnType<typeof JSON.parse> | null} Current sync client, or null.
+ */
+export function currentSyncClientOrNull() {
+  return currentClient
+}