@serwist/background-sync 8.4.3 → 9.0.0-preview.0

package/dist/BackgroundSyncPlugin.d.ts

@@ -20,3 +20,4 @@ declare class BackgroundSyncPlugin implements SerwistPlugin {
     fetchDidFail: SerwistPlugin["fetchDidFail"];
 }
 export { BackgroundSyncPlugin };
+//# sourceMappingURL=BackgroundSyncPlugin.d.ts.map

package/dist/BackgroundSyncPlugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BackgroundSyncPlugin.d.ts","sourceRoot":"","sources":["../src/BackgroundSyncPlugin.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAEnD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAG/C;;;GAGG;AACH,cAAM,oBAAqB,YAAW,aAAa;IACjD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAQ;IAE/B;;;;;OAKG;gBACS,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY;IAIhD;;;OAGG;IACH,YAAY,EAAE,aAAa,CAAC,cAAc,CAAC,CAEzC;CACH;AAED,OAAO,EAAE,oBAAoB,EAAE,CAAC"}

package/dist/Queue.d.ts

@@ -114,7 +114,7 @@ declare class Queue {
      *
      * @returns
      */
-    getAll(): Promise<Array<QueueEntry>>;
+    getAll(): Promise<QueueEntry[]>;
     /**
      * Returns the number of entries present in the queue.
      * Note that expired entries (per `maxRetentionTime`) are also included in this count.
@@ -167,3 +167,4 @@ declare class Queue {
     static get _queueNames(): Set<string>;
 }
 export { Queue };
+//# sourceMappingURL=Queue.d.ts.map

package/dist/Queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Queue.d.ts","sourceRoot":"","sources":["../src/Queue.ts"],"names":[],"mappings":"AAgBA,UAAU,qBAAqB;IAC7B,KAAK,EAAE,KAAK,CAAC;CACd;AAED,UAAU,cAAc;IACtB,CAAC,OAAO,EAAE,qBAAqB,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACxD;AAED,MAAM,WAAW,YAAY;IAC3B;;;;;;;OAOG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,cAAc,CAAC;CACzB;AAED,MAAM,WAAW,UAAU;IACzB;;OAEG;IACH,OAAO,EAAE,OAAO,CAAC;IACjB;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AA2BD;;;;GAIG;AACH,cAAM,KAAK;IACT,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAiB;IACzC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAS;IAC3C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAa;IACzC,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAU;IAC7C,OAAO,CAAC,eAAe,CAAS;IAChC,OAAO,CAAC,wBAAwB,CAAS;IAEzC;;;;;;;;OAQG;gBACS,IAAI,EAAE,MAAM,EAAE,EAAE,iBAAiB,EAAE,MAAM,EAAE,gBAAgB,EAAE,GAAE,YAAiB;IAgB5F;;OAEG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;;;;OAKG;IACG,WAAW,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAmBnD;;;;;OAKG;IACG,cAAc,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAmBtD;;;;;;OAMG;IACG,UAAU,IAAI,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC;IAInD;;;;;;OAMG;IACG,YAAY,IAAI,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC;IAIrD;;;;;OAKG;IACG,MAAM,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;IAmBrC;;;;;OAKG;IACG,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC;IAI7B;;;;;;OAMG;IACG,WAAW,CAAC,EAAE,OAAO,EAAE,QAAQ,EAAE,SAAsB,EAAE,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAmC1H;;;;;;;OAOG;IACG,cAAc,CAAC,SAAS,EAAE,KAAK,GAAG,OAAO,GAAG,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC;IA0BjF;;;;OAIG;IACG,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC;IAuBrC;;OAEG;IACG,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;IAenC;;;;;;OAMG;IACH,OAAO,CAAC,gBAAgB;IAmDxB;;;;;;OAMG;IACH,MAAM,KAAK,WAAW,IAAI,GAAG,CAAC,MAAM,CAAC,CAEpC;CACF;AAED,OAAO,EAAE,KAAK,EAAE,CAAC"}

package/dist/QueueDb.d.ts

@@ -87,3 +87,4 @@ export declare class QueueDb {
      */
     private _upgradeDb;
 }
+//# sourceMappingURL=QueueDb.d.ts.map

package/dist/QueueDb.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"QueueDb.d.ts","sourceRoot":"","sources":["../src/QueueDb.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAexD,MAAM,WAAW,2BAA2B;IAC1C,WAAW,EAAE,WAAW,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,MAAM,WAAW,eAAgB,SAAQ,2BAA2B;IAClE,EAAE,EAAE,MAAM,CAAC;CACZ;AAED;;;;;;GAMG;AAEH,qBAAa,OAAO;IAClB,OAAO,CAAC,GAAG,CAA4C;IAEvD;;;;OAIG;IACG,QAAQ,CAAC,KAAK,EAAE,2BAA2B,GAAG,OAAO,CAAC,IAAI,CAAC;IASjE;;;;OAIG;IACG,eAAe,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;IAMpD;;;;;OAKG;IACG,wBAAwB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC;IAM7E;;;;;OAKG;IACG,wBAAwB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAKlE;;;;OAIG;IACG,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAK5C;;;;OAIG;IACG,wBAAwB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,GAAG,SAAS,CAAC;IAIvF;;;;OAIG;IACG,uBAAuB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,GAAG,SAAS,CAAC;IAItF;;;;;;;;OAQG;IACG,oBAAoB,CAAC,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,kBAAkB,GAAG,OAAO,CAAC,eAAe,GAAG,SAAS,CAAC;IAOnH;;;;OAIG;YACW,KAAK;IASnB;;;;;;OAMG;IACH,OAAO,CAAC,UAAU;CAanB"}

package/dist/QueueStore.d.ts

@@ -72,3 +72,4 @@ export declare class QueueStore {
      */
     _removeEntry(entry?: QueueStoreEntry): Promise<QueueStoreEntry | undefined>;
 }
+//# sourceMappingURL=QueueStore.d.ts.map

package/dist/QueueStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"QueueStore.d.ts","sourceRoot":"","sources":["../src/QueueStore.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,eAAe,EAAE,2BAA2B,EAAE,MAAM,cAAc,CAAC;AAGjF;;;;;;GAMG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAU;IAEnC;;;;;OAKG;gBACS,SAAS,EAAE,MAAM;IAK7B;;;;OAIG;IACG,SAAS,CAAC,KAAK,EAAE,2BAA2B,GAAG,OAAO,CAAC,IAAI,CAAC;IAuBlE;;;;OAIG;IACG,YAAY,CAAC,KAAK,EAAE,2BAA2B,GAAG,OAAO,CAAC,IAAI,CAAC;IA8BrE;;;;OAIG;IACG,QAAQ,IAAI,OAAO,CAAC,eAAe,GAAG,SAAS,CAAC;IAItD;;;;OAIG;IACG,UAAU,IAAI,OAAO,CAAC,eAAe,GAAG,SAAS,CAAC;IAIxD;;;;OAIG;IACG,MAAM,IAAI,OAAO,CAAC,eAAe,EAAE,CAAC;IAI1C;;;;OAIG;IACG,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC;IAI7B;;;;;;;;;OASG;IACG,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI5C;;;;;;OAMG;IACG,YAAY,CAAC,KAAK,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,eAAe,GAAG,SAAS,CAAC;CAMlF"}

package/dist/StorableRequest.d.ts

@@ -49,3 +49,4 @@ declare class StorableRequest {
     clone(): StorableRequest;
 }
 export { StorableRequest };
+//# sourceMappingURL=StorableRequest.d.ts.map

package/dist/StorableRequest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"StorableRequest.d.ts","sourceRoot":"","sources":["../src/StorableRequest.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAiBnD,MAAM,WAAW,WAAY,SAAQ,aAAa;IAChD,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,aAAa,CAAC;IACvB,IAAI,CAAC,EAAE,WAAW,CAAC;CACpB;AAED;;;;;;GAMG;AACH,cAAM,eAAe;IACnB,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAc;IAE3C;;;;;;OAMG;WACU,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,eAAe,CAAC;IA6BpE;;;;;;OAMG;gBACS,WAAW,EAAE,WAAW;IAyBpC;;;;OAIG;IACH,QAAQ,IAAI,WAAW;IAUvB;;;;OAIG;IACH,SAAS,IAAI,OAAO;IAIpB;;;;OAIG;IACH,KAAK,IAAI,eAAe;CAGzB;AAED,OAAO,EAAE,eAAe,EAAE,CAAC"}

package/dist/index.d.ts

@@ -21,3 +21,4 @@ declare global {
 }
 export { BackgroundSyncPlugin, Queue, QueueStore, StorableRequest };
 export type { QueueOptions, QueueEntry };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AACjE,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC3D,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAGvD,UAAU,WAAW;IACnB,OAAO,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAC7B,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACtC;AAED,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,yBAAyB;QACjC,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;KAC5B;IAED,UAAU,SAAU,SAAQ,eAAe;QACzC,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;QAC7B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;KACtB;IAED,UAAU,gCAAgC;QACxC,IAAI,EAAE,SAAS,CAAC;KACjB;CACF;AAED,OAAO,EAAE,oBAAoB,EAAE,KAAK,EAAE,UAAU,EAAE,eAAe,EAAE,CAAC;AAEpE,YAAY,EAAE,YAAY,EAAE,UAAU,EAAE,CAAC"}

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@serwist/background-sync",
-  "version": "8.4.3",
+  "version": "9.0.0-preview.0",
   "type": "module",
   "description": "Queues failed requests and uses the Background Sync API to replay them when the network is available",
   "files": [
-    "dist",
-    "!dist/**/dts"
+    "src",
+    "dist"
   ],
   "keywords": [
     "serwist",
@@ -21,30 +21,31 @@
   "repository": "serwist/serwist",
   "bugs": "https://github.com/serwist/serwist/issues",
   "homepage": "https://serwist.pages.dev",
-  "module": "./dist/index.js",
-  "main": "./dist/index.cjs",
+  "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
-      "import": {
-        "types": "./dist/index.d.ts",
-        "default": "./dist/index.js"
-      },
-      "require": {
-        "types": "./dist/index.d.cts",
-        "default": "./dist/index.cjs"
-      }
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
     }
   },
   "dependencies": {
     "idb": "8.0.0",
-    "@serwist/core": "8.4.3"
+    "@serwist/core": "9.0.0-preview.0"
   },
   "devDependencies": {
     "cross-env": "7.0.3",
-    "rollup": "4.9.1",
-    "typescript": "5.4.0-dev.20231226",
-    "@serwist/constants": "8.4.3"
+    "rollup": "4.9.6",
+    "typescript": "5.4.0-dev.20240203",
+    "@serwist/constants": "9.0.0-preview.0"
+  },
+  "peerDependencies": {
+    "typescript": ">=5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "typescript": {
+      "optional": true
+    }
   },
   "scripts": {
     "build": "rimraf dist && cross-env NODE_ENV=production rollup --config rollup.config.js",

package/src/BackgroundSyncPlugin.ts

@@ -0,0 +1,40 @@
+/*
+  Copyright 2018 Google LLC
+
+  Use of this source code is governed by an MIT-style
+  license that can be found in the LICENSE file or at
+  https://opensource.org/licenses/MIT.
+*/
+
+import type { SerwistPlugin } from "@serwist/core";
+
+import type { QueueOptions } from "./Queue.js";
+import { Queue } from "./Queue.js";
+
+/**
+ * A class implementing the `fetchDidFail` lifecycle callback. This makes it
+ * easier to add failed requests to a background sync Queue.
+ */
+class BackgroundSyncPlugin implements SerwistPlugin {
+  private readonly _queue: Queue;
+
+  /**
+   * @param name See the `@serwist/background-sync.Queue`
+   * documentation for parameter details.
+   * @param options See the `@serwist/background-sync.Queue`
+   * documentation for parameter details.
+   */
+  constructor(name: string, options?: QueueOptions) {
+    this._queue = new Queue(name, options);
+  }
+
+  /**
+   * @param options
+   * @private
+   */
+  fetchDidFail: SerwistPlugin["fetchDidFail"] = async ({ request }) => {
+    await this._queue.pushRequest({ request });
+  };
+}
+
+export { BackgroundSyncPlugin };

package/src/Queue.ts

@@ -0,0 +1,444 @@
+/*
+  Copyright 2018 Google LLC
+
+  Use of this source code is governed by an MIT-style
+  license that can be found in the LICENSE file or at
+  https://opensource.org/licenses/MIT.
+*/
+import { assert, SerwistError, getFriendlyURL, logger } from "@serwist/core/internal";
+
+import type { QueueStoreEntry, UnidentifiedQueueStoreEntry } from "./QueueDb.js";
+import { QueueStore } from "./QueueStore.js";
+import { StorableRequest } from "./StorableRequest.js";
+
+// Give TypeScript the correct global.
+declare let self: ServiceWorkerGlobalScope;
+
+interface OnSyncCallbackOptions {
+  queue: Queue;
+}
+
+interface OnSyncCallback {
+  (options: OnSyncCallbackOptions): void | Promise<void>;
+}
+
+export interface QueueOptions {
+  /**
+   * If `true`, instead of attempting to use background sync events, always attempt
+   * to replay queued request at service worker startup. Most folks will not need
+   * this, unless you explicitly target a runtime like Electron that exposes the
+   * interfaces for background sync, but does not have a working implementation.
+   *
+   * @default false
+   */
+  forceSyncFallback?: boolean;
+  /**
+   * The amount of time (in minutes) a request may be retried. After this amount
+   * of time has passed, the request will be deleted from the queue.
+   *
+   * @default 60 * 24 * 7
+   */
+  maxRetentionTime?: number;
+  /**
+   * A function that gets invoked whenever the 'sync' event fires. The function
+   * is invoked with an object containing the `queue` property (referencing this
+   * instance), and you can use the callback to customize the replay behavior of
+   * the queue. When not set the `replayRequests()` method is called. Note: if the
+   * replay fails after a sync event, make sure you throw an error, so the browser
+   * knows to retry the sync event later.
+   */
+  onSync?: OnSyncCallback;
+}
+
+export interface QueueEntry {
+  /**
+   * The request to store in the queue.
+   */
+  request: Request;
+  /**
+   * The timestamp (Epoch time in milliseconds) when the request was first added
+   * to the queue. This is used along with `maxRetentionTime` to remove outdated
+   * requests. In general you don't need to set this value, as it's automatically
+   * set for you (defaulting to `Date.now()`), but you can update it if you don't
+   * want particular requests to expire.
+   */
+  timestamp?: number;
+  /**
+   * Any metadata you want associated with the stored request. When requests are
+   * replayed you'll have access to this metadata object in case you need to modify
+   * the request beforehand.
+   */
+  metadata?: Record<string, unknown>;
+}
+
+const TAG_PREFIX = "serwist-background-sync";
+const MAX_RETENTION_TIME = 60 * 24 * 7; // 7 days in minutes
+
+const queueNames = new Set<string>();
+
+/**
+ * Converts a QueueStore entry into the format exposed by Queue. This entails
+ * converting the request data into a real request and omitting the `id` and
+ * `queueName` properties.
+ *
+ * @param queueStoreEntry
+ * @returns
+ * @private
+ */
+const convertEntry = (queueStoreEntry: UnidentifiedQueueStoreEntry): QueueEntry => {
+  const queueEntry: QueueEntry = {
+    request: new StorableRequest(queueStoreEntry.requestData).toRequest(),
+    timestamp: queueStoreEntry.timestamp,
+  };
+  if (queueStoreEntry.metadata) {
+    queueEntry.metadata = queueStoreEntry.metadata;
+  }
+  return queueEntry;
+};
+
+/**
+ * A class to manage storing failed requests in IndexedDB and retrying them
+ * later. All parts of the storing and replaying process are observable via
+ * callbacks.
+ */
+class Queue {
+  private readonly _name: string;
+  private readonly _onSync: OnSyncCallback;
+  private readonly _maxRetentionTime: number;
+  private readonly _queueStore: QueueStore;
+  private readonly _forceSyncFallback: boolean;
+  private _syncInProgress = false;
+  private _requestsAddedDuringSync = false;
+
+  /**
+   * Creates an instance of Queue with the given options
+   *
+   * @param name The unique name for this queue. This name must be
+   * unique as it's used to register sync events and store requests
+   * in IndexedDB specific to this instance. An error will be thrown if
+   * a duplicate name is detected.
+   * @param options
+   */
+  constructor(name: string, { forceSyncFallback, onSync, maxRetentionTime }: QueueOptions = {}) {
+    // Ensure the store name is not already being used
+    if (queueNames.has(name)) {
+      throw new SerwistError("duplicate-queue-name", { name });
+    }
+    queueNames.add(name);
+
+    this._name = name;
+    this._onSync = onSync || this.replayRequests;
+    this._maxRetentionTime = maxRetentionTime || MAX_RETENTION_TIME;
+    this._forceSyncFallback = Boolean(forceSyncFallback);
+    this._queueStore = new QueueStore(this._name);
+
+    this._addSyncListener();
+  }
+
+  /**
+   * @returns
+   */
+  get name(): string {
+    return this._name;
+  }
+
+  /**
+   * Stores the passed request in IndexedDB (with its timestamp and any
+   * metadata) at the end of the queue.
+   *
+   * @param entry
+   */
+  async pushRequest(entry: QueueEntry): Promise<void> {
+    if (process.env.NODE_ENV !== "production") {
+      assert!.isType(entry, "object", {
+        moduleName: "@serwist/background-sync",
+        className: "Queue",
+        funcName: "pushRequest",
+        paramName: "entry",
+      });
+      assert!.isInstance(entry.request, Request, {
+        moduleName: "@serwist/background-sync",
+        className: "Queue",
+        funcName: "pushRequest",
+        paramName: "entry.request",
+      });
+    }
+
+    await this._addRequest(entry, "push");
+  }
+
+  /**
+   * Stores the passed request in IndexedDB (with its timestamp and any
+   * metadata) at the beginning of the queue.
+   *
+   * @param entry
+   */
+  async unshiftRequest(entry: QueueEntry): Promise<void> {
+    if (process.env.NODE_ENV !== "production") {
+      assert!.isType(entry, "object", {
+        moduleName: "@serwist/background-sync",
+        className: "Queue",
+        funcName: "unshiftRequest",
+        paramName: "entry",
+      });
+      assert!.isInstance(entry.request, Request, {
+        moduleName: "@serwist/background-sync",
+        className: "Queue",
+        funcName: "unshiftRequest",
+        paramName: "entry.request",
+      });
+    }
+
+    await this._addRequest(entry, "unshift");
+  }
+
+  /**
+   * Removes and returns the last request in the queue (along with its
+   * timestamp and any metadata). The returned object takes the form:
+   * `{request, timestamp, metadata}`.
+   *
+   * @returns
+   */
+  async popRequest(): Promise<QueueEntry | undefined> {
+    return this._removeRequest("pop");
+  }
+
+  /**
+   * Removes and returns the first request in the queue (along with its
+   * timestamp and any metadata). The returned object takes the form:
+   * `{request, timestamp, metadata}`.
+   *
+   * @returns
+   */
+  async shiftRequest(): Promise<QueueEntry | undefined> {
+    return this._removeRequest("shift");
+  }
+
+  /**
+   * Returns all the entries that have not expired (per `maxRetentionTime`).
+   * Any expired entries are removed from the queue.
+   *
+   * @returns
+   */
+  async getAll(): Promise<QueueEntry[]> {
+    const allEntries = await this._queueStore.getAll();
+    const now = Date.now();
+
+    const unexpiredEntries = [];
+    for (const entry of allEntries) {
+      // Ignore requests older than maxRetentionTime. Call this function
+      // recursively until an unexpired request is found.
+      const maxRetentionTimeInMs = this._maxRetentionTime * 60 * 1000;
+      if (now - entry.timestamp > maxRetentionTimeInMs) {
+        await this._queueStore.deleteEntry(entry.id);
+      } else {
+        unexpiredEntries.push(convertEntry(entry));
+      }
+    }
+
+    return unexpiredEntries;
+  }
+
+  /**
+   * Returns the number of entries present in the queue.
+   * Note that expired entries (per `maxRetentionTime`) are also included in this count.
+   *
+   * @returns
+   */
+  async size(): Promise<number> {
+    return await this._queueStore.size();
+  }
+
+  /**
+   * Adds the entry to the QueueStore and registers for a sync event.
+   *
+   * @param entry
+   * @param operation
+   * @private
+   */
+  async _addRequest({ request, metadata, timestamp = Date.now() }: QueueEntry, operation: "push" | "unshift"): Promise<void> {
+    const storableRequest = await StorableRequest.fromRequest(request.clone());
+    const entry: UnidentifiedQueueStoreEntry = {
+      requestData: storableRequest.toObject(),
+      timestamp,
+    };
+
+    // Only include metadata if it's present.
+    if (metadata) {
+      entry.metadata = metadata;
+    }
+
+    switch (operation) {
+      case "push":
+        await this._queueStore.pushEntry(entry);
+        break;
+      case "unshift":
+        await this._queueStore.unshiftEntry(entry);
+        break;
+    }
+
+    if (process.env.NODE_ENV !== "production") {
+      logger.log(`Request for '${getFriendlyURL(request.url)}' has ` + `been added to background sync queue '${this._name}'.`);
+    }
+
+    // Don't register for a sync if we're in the middle of a sync. Instead,
+    // we wait until the sync is complete and call register if
+    // `this._requestsAddedDuringSync` is true.
+    if (this._syncInProgress) {
+      this._requestsAddedDuringSync = true;
+    } else {
+      await this.registerSync();
+    }
+  }
+
+  /**
+   * Removes and returns the first or last (depending on `operation`) entry
+   * from the QueueStore that's not older than the `maxRetentionTime`.
+   *
+   * @param operation
+   * @returns
+   * @private
+   */
+  async _removeRequest(operation: "pop" | "shift"): Promise<QueueEntry | undefined> {
+    const now = Date.now();
+    let entry: QueueStoreEntry | undefined;
+    switch (operation) {
+      case "pop":
+        entry = await this._queueStore.popEntry();
+        break;
+      case "shift":
+        entry = await this._queueStore.shiftEntry();
+        break;
+    }
+
+    if (entry) {
+      // Ignore requests older than maxRetentionTime. Call this function
+      // recursively until an unexpired request is found.
+      const maxRetentionTimeInMs = this._maxRetentionTime * 60 * 1000;
+      if (now - entry.timestamp > maxRetentionTimeInMs) {
+        return this._removeRequest(operation);
+      }
+
+      return convertEntry(entry);
+    }
+
+    return undefined;
+  }
+
+  /**
+   * Loops through each request in the queue and attempts to re-fetch it.
+   * If any request fails to re-fetch, it's put back in the same position in
+   * the queue (which registers a retry for the next sync event).
+   */
+  async replayRequests(): Promise<void> {
+    let entry: QueueEntry | undefined = undefined;
+    while ((entry = await this.shiftRequest())) {
+      try {
+        await fetch(entry.request.clone());
+
+        if (process.env.NODE_ENV !== "production") {
+          logger.log(`Request for '${getFriendlyURL(entry.request.url)}' ` + `has been replayed in queue '${this._name}'`);
+        }
+      } catch (error) {
+        await this.unshiftRequest(entry);
+
+        if (process.env.NODE_ENV !== "production") {
+          logger.log(`Request for '${getFriendlyURL(entry.request.url)}' ` + `failed to replay, putting it back in queue '${this._name}'`);
+        }
+        throw new SerwistError("queue-replay-failed", { name: this._name });
+      }
+    }
+    if (process.env.NODE_ENV !== "production") {
+      logger.log(`All requests in queue '${this.name}' have successfully replayed; the queue is now empty!`);
+    }
+  }
+
+  /**
+   * Registers a sync event with a tag unique to this instance.
+   */
+  async registerSync(): Promise<void> {
+    // See https://github.com/GoogleChrome/workbox/issues/2393
+    if ("sync" in self.registration && !this._forceSyncFallback) {
+      try {
+        await self.registration.sync.register(`${TAG_PREFIX}:${this._name}`);
+      } catch (err) {
+        // This means the registration failed for some reason, possibly due to
+        // the user disabling it.
+        if (process.env.NODE_ENV !== "production") {
+          logger.warn(`Unable to register sync event for '${this._name}'.`, err);
+        }
+      }
+    }
+  }
+
+  /**
+   * In sync-supporting browsers, this adds a listener for the sync event.
+   * In non-sync-supporting browsers, or if _forceSyncFallback is true, this
+   * will retry the queue on service worker startup.
+   *
+   * @private
+   */
+  private _addSyncListener() {
+    // See https://github.com/GoogleChrome/workbox/issues/2393
+    if ("sync" in self.registration && !this._forceSyncFallback) {
+      self.addEventListener("sync", (event: SyncEvent) => {
+        if (event.tag === `${TAG_PREFIX}:${this._name}`) {
+          if (process.env.NODE_ENV !== "production") {
+            logger.log(`Background sync for tag '${event.tag}' has been received`);
+          }
+
+          const syncComplete = async () => {
+            this._syncInProgress = true;
+
+            let syncError: Error | undefined = undefined;
+            try {
+              await this._onSync({ queue: this });
+            } catch (error) {
+              if (error instanceof Error) {
+                syncError = error;
+
+                // Rethrow the error. Note: the logic in the finally clause
+                // will run before this gets rethrown.
+                throw syncError;
+              }
+            } finally {
+              // New items may have been added to the queue during the sync,
+              // so we need to register for a new sync if that's happened...
+              // Unless there was an error during the sync, in which
+              // case the browser will automatically retry later, as long
+              // as `event.lastChance` is not true.
+              if (this._requestsAddedDuringSync && !(syncError && !event.lastChance)) {
+                await this.registerSync();
+              }
+
+              this._syncInProgress = false;
+              this._requestsAddedDuringSync = false;
+            }
+          };
+          event.waitUntil(syncComplete());
+        }
+      });
+    } else {
+      if (process.env.NODE_ENV !== "production") {
+        logger.log("Background sync replaying without background sync event");
+      }
+      // If the browser doesn't support background sync, or the developer has
+      // opted-in to not using it, retry every time the service worker starts up
+      // as a fallback.
+      void this._onSync({ queue: this });
+    }
+  }
+
+  /**
+   * Returns the set of queue names. This is primarily used to reset the list
+   * of queue names in tests.
+   *
+   * @returns
+   * @private
+   */
+  static get _queueNames(): Set<string> {
+    return queueNames;
+  }
+}
+
+export { Queue };