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

package/dist/index.js

@@ -5,19 +5,9 @@ const DB_VERSION = 3;
 const DB_NAME = "serwist-background-sync";
 const REQUEST_OBJECT_STORE_NAME = "requests";
 const QUEUE_NAME_INDEX = "queueName";
-/**
- * A class to interact directly an IndexedDB created specifically to save and
- * retrieve QueueStoreEntries. This class encapsulates all the schema details
- * to store the representation of a Queue.
- *
- * @private
- */ class QueueDb {
+class QueueDb {
     _db = null;
-    /**
-   * Add QueueStoreEntry to underlying db.
-   *
-   * @param entry
-   */ async addEntry(entry) {
+    async addEntry(entry) {
         const db = await this.getDb();
         const tx = db.transaction(REQUEST_OBJECT_STORE_NAME, "readwrite", {
             durability: "relaxed"
@@ -25,74 +15,36 @@ const QUEUE_NAME_INDEX = "queueName";
         await tx.store.add(entry);
         await tx.done;
     }
-    /**
-   * Returns the first entry id in the ObjectStore.
-   *
-   * @returns
-   */ async getFirstEntryId() {
+    async getFirstEntryId() {
         const db = await this.getDb();
         const cursor = await db.transaction(REQUEST_OBJECT_STORE_NAME).store.openCursor();
         return cursor?.value.id;
     }
-    /**
-   * Get all the entries filtered by index
-   *
-   * @param queueName
-   * @returns
-   */ async getAllEntriesByQueueName(queueName) {
+    async getAllEntriesByQueueName(queueName) {
         const db = await this.getDb();
         const results = await db.getAllFromIndex(REQUEST_OBJECT_STORE_NAME, QUEUE_NAME_INDEX, IDBKeyRange.only(queueName));
         return results ? results : new Array();
     }
-    /**
-   * Returns the number of entries filtered by index
-   *
-   * @param queueName
-   * @returns
-   */ async getEntryCountByQueueName(queueName) {
+    async getEntryCountByQueueName(queueName) {
         const db = await this.getDb();
         return db.countFromIndex(REQUEST_OBJECT_STORE_NAME, QUEUE_NAME_INDEX, IDBKeyRange.only(queueName));
     }
-    /**
-   * Deletes a single entry by id.
-   *
-   * @param id the id of the entry to be deleted
-   */ async deleteEntry(id) {
+    async deleteEntry(id) {
         const db = await this.getDb();
         await db.delete(REQUEST_OBJECT_STORE_NAME, id);
     }
-    /**
-   *
-   * @param queueName
-   * @returns
-   */ async getFirstEntryByQueueName(queueName) {
+    async getFirstEntryByQueueName(queueName) {
         return await this.getEndEntryFromIndex(IDBKeyRange.only(queueName), "next");
     }
-    /**
-   *
-   * @param queueName
-   * @returns
-   */ async getLastEntryByQueueName(queueName) {
+    async getLastEntryByQueueName(queueName) {
         return await this.getEndEntryFromIndex(IDBKeyRange.only(queueName), "prev");
     }
-    /**
-   * Returns either the first or the last entries, depending on direction.
-   * Filtered by index.
-   *
-   * @param direction
-   * @param query
-   * @returns
-   * @private
-   */ async getEndEntryFromIndex(query, direction) {
+    async getEndEntryFromIndex(query, direction) {
         const db = await this.getDb();
         const cursor = await db.transaction(REQUEST_OBJECT_STORE_NAME).store.index(QUEUE_NAME_INDEX).openCursor(query, direction);
         return cursor?.value;
     }
-    /**
-   * Returns an open connection to the database.
-   *
-   * @private
-   */ async getDb() {
+    async getDb() {
         if (!this._db) {
             this._db = await openDB(DB_NAME, DB_VERSION, {
                 upgrade: this._upgradeDb
@@ -100,13 +52,7 @@ const QUEUE_NAME_INDEX = "queueName";
         }
         return this._db;
     }
-    /**
-   * Upgrades QueueDB
-   *
-   * @param db
-   * @param oldVersion
-   * @private
-   */ _upgradeDb(db, oldVersion) {
+    _upgradeDb(db, oldVersion) {
         if (oldVersion > 0 && oldVersion < DB_VERSION) {
             if (db.objectStoreNames.contains(REQUEST_OBJECT_STORE_NAME)) {
                 db.deleteObjectStore(REQUEST_OBJECT_STORE_NAME);
@@ -122,29 +68,14 @@ const QUEUE_NAME_INDEX = "queueName";
     }
 }
 
-/**
- * A class to manage storing requests from a Queue in IndexedDB,
- * indexed by their queue name for easier access.
- *
- * Most developers will not need to access this class directly;
- * it is exposed for advanced use cases.
- */ class QueueStore {
+class QueueStore {
     _queueName;
     _queueDb;
-    /**
-   * Associates this instance with a Queue instance, so entries added can be
-   * identified by their queue name.
-   *
-   * @param queueName
-   */ constructor(queueName){
+    constructor(queueName){
         this._queueName = queueName;
         this._queueDb = new QueueDb();
     }
-    /**
-   * Append an entry last in the queue.
-   *
-   * @param entry
-   */ async pushEntry(entry) {
+    async pushEntry(entry) {
         if (process.env.NODE_ENV !== "production") {
             assert.isType(entry, "object", {
                 moduleName: "@serwist/background-sync",
@@ -159,16 +90,11 @@ const QUEUE_NAME_INDEX = "queueName";
                 paramName: "entry.requestData"
             });
         }
-        // biome-ignore lint/performance/noDelete: Don't specify an ID since one is automatically generated.
         delete entry.id;
         entry.queueName = this._queueName;
         await this._queueDb.addEntry(entry);
     }
-    /**
-   * Prepend an entry first in the queue.
-   *
-   * @param entry
-   */ async unshiftEntry(entry) {
+    async unshiftEntry(entry) {
         if (process.env.NODE_ENV !== "production") {
             assert.isType(entry, "object", {
                 moduleName: "@serwist/background-sync",
@@ -185,62 +111,29 @@ const QUEUE_NAME_INDEX = "queueName";
         }
         const firstId = await this._queueDb.getFirstEntryId();
         if (firstId) {
-            // Pick an ID one less than the lowest ID in the object store.
             entry.id = firstId - 1;
         } else {
-            // biome-ignore lint/performance/noDelete: Let the auto-incrementor assign the ID.
             delete entry.id;
         }
         entry.queueName = this._queueName;
         await this._queueDb.addEntry(entry);
     }
-    /**
-   * Removes and returns the last entry in the queue matching the `queueName`.
-   *
-   * @returns
-   */ async popEntry() {
+    async popEntry() {
         return this._removeEntry(await this._queueDb.getLastEntryByQueueName(this._queueName));
     }
-    /**
-   * Removes and returns the first entry in the queue matching the `queueName`.
-   *
-   * @returns
-   */ async shiftEntry() {
+    async shiftEntry() {
         return this._removeEntry(await this._queueDb.getFirstEntryByQueueName(this._queueName));
     }
-    /**
-   * Returns all entries in the store matching the `queueName`.
-   *
-   * @returns
-   */ async getAll() {
+    async getAll() {
         return await this._queueDb.getAllEntriesByQueueName(this._queueName);
     }
-    /**
-   * Returns the number of entries in the store matching the `queueName`.
-   *
-   * @returns
-   */ async size() {
+    async size() {
         return await this._queueDb.getEntryCountByQueueName(this._queueName);
     }
-    /**
-   * Deletes the entry for the given ID.
-   *
-   * WARNING: this method does not ensure the deleted entry belongs to this
-   * queue (i.e. matches the `queueName`). But this limitation is acceptable
-   * as this class is not publicly exposed. An additional check would make
-   * this method slower than it needs to be.
-   *
-   * @param id
-   */ async deleteEntry(id) {
+    async deleteEntry(id) {
         await this._queueDb.deleteEntry(id);
     }
-    /**
-   * Removes and returns the first or last entry in the queue (based on the
-   * `direction` argument) matching the `queueName`.
-   *
-   * @returns
-   * @private
-   */ async _removeEntry(entry) {
+    async _removeEntry(entry) {
         if (entry) {
             await this.deleteEntry(entry.id);
         }
@@ -259,37 +152,19 @@ const serializableProperties = [
     "integrity",
     "keepalive"
 ];
-/**
- * A class to make it easier to serialize and de-serialize requests so they
- * can be stored in IndexedDB.
- *
- * Most developers will not need to access this class directly;
- * it is exposed for advanced use cases.
- */ class StorableRequest {
+class StorableRequest {
     _requestData;
-    /**
-   * Converts a Request object to a plain object that can be structured
-   * cloned or JSON-stringified.
-   *
-   * @param request
-   * @returns
-   */ static async fromRequest(request) {
+    static async fromRequest(request) {
         const requestData = {
             url: request.url,
             headers: {}
         };
-        // Set the body if present.
         if (request.method !== "GET") {
-            // Use ArrayBuffer to support non-text request bodies.
-            // NOTE: we can't use Blobs becuse Safari doesn't support storing
-            // Blobs in IndexedDB in some cases:
-            // https://github.com/dfahlander/Dexie.js/issues/618#issuecomment-398348457
             requestData.body = await request.clone().arrayBuffer();
         }
         request.headers.forEach((value, key)=>{
             requestData.headers[key] = value;
         });
-        // Add all other serializable request properties
         for (const prop of serializableProperties){
             if (request[prop] !== undefined) {
                 requestData[prop] = request[prop];
@@ -297,13 +172,7 @@ const serializableProperties = [
         }
         return new StorableRequest(requestData);
     }
-    /**
-   * Accepts an object of request data that can be used to construct a
-   * `Request` but can also be stored in IndexedDB.
-   *
-   * @param requestData An object of request data that includes the `url` plus any relevant properties of
-   * [requestInit](https://fetch.spec.whatwg.org/#requestinit).
-   */ constructor(requestData){
+    constructor(requestData){
         if (process.env.NODE_ENV !== "production") {
             assert.isType(requestData, "object", {
                 moduleName: "@serwist/background-sync",
@@ -318,18 +187,12 @@ const serializableProperties = [
                 paramName: "requestData.url"
             });
         }
-        // If the request's mode is `navigate`, convert it to `same-origin` since
-        // navigation requests can't be constructed via script.
         if (requestData.mode === "navigate") {
             requestData.mode = "same-origin";
         }
         this._requestData = requestData;
     }
-    /**
-   * Returns a deep clone of the instances `_requestData` object.
-   *
-   * @returns
-   */ toObject() {
+    toObject() {
         const requestData = Object.assign({}, this._requestData);
         requestData.headers = Object.assign({}, this._requestData.headers);
         if (requestData.body) {
@@ -337,34 +200,18 @@ const serializableProperties = [
         }
         return requestData;
     }
-    /**
-   * Converts this instance to a Request.
-   *
-   * @returns
-   */ toRequest() {
+    toRequest() {
         return new Request(this._requestData.url, this._requestData);
     }
-    /**
-   * Creates and returns a deep clone of the instance.
-   *
-   * @returns
-   */ clone() {
+    clone() {
         return new StorableRequest(this.toObject());
     }
 }
 
 const TAG_PREFIX = "serwist-background-sync";
-const MAX_RETENTION_TIME = 60 * 24 * 7; // 7 days in minutes
+const MAX_RETENTION_TIME = 60 * 24 * 7;
 const queueNames = new Set();
-/**
- * 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)=>{
+const convertEntry = (queueStoreEntry)=>{
     const queueEntry = {
         request: new StorableRequest(queueStoreEntry.requestData).toRequest(),
         timestamp: queueStoreEntry.timestamp
@@ -374,11 +221,7 @@ const queueNames = new Set();
     }
     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 {
+class Queue {
     _name;
     _onSync;
     _maxRetentionTime;
@@ -386,16 +229,7 @@ const queueNames = new Set();
     _forceSyncFallback;
     _syncInProgress = false;
     _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, { forceSyncFallback, onSync, maxRetentionTime } = {}){
-        // Ensure the store name is not already being used
+    constructor(name, { forceSyncFallback, onSync, maxRetentionTime } = {}){
         if (queueNames.has(name)) {
             throw new SerwistError("duplicate-queue-name", {
                 name
@@ -409,17 +243,10 @@ const queueNames = new Set();
         this._queueStore = new QueueStore(this._name);
         this._addSyncListener();
     }
-    /**
-   * @returns
-   */ get name() {
+    get name() {
         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) {
+    async pushRequest(entry) {
         if (process.env.NODE_ENV !== "production") {
             assert.isType(entry, "object", {
                 moduleName: "@serwist/background-sync",
@@ -436,12 +263,7 @@ const queueNames = new Set();
         }
         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) {
+    async unshiftRequest(entry) {
         if (process.env.NODE_ENV !== "production") {
             assert.isType(entry, "object", {
                 moduleName: "@serwist/background-sync",
@@ -458,36 +280,17 @@ const queueNames = new Set();
         }
         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() {
+    async popRequest() {
         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() {
+    async shiftRequest() {
         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() {
+    async getAll() {
         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);
@@ -497,27 +300,15 @@ const queueNames = new Set();
         }
         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() {
+    async size() {
         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() }, operation) {
+    async _addRequest({ request, metadata, timestamp = Date.now() }, operation) {
         const storableRequest = await StorableRequest.fromRequest(request.clone());
         const entry = {
             requestData: storableRequest.toObject(),
             timestamp
         };
-        // Only include metadata if it's present.
         if (metadata) {
             entry.metadata = metadata;
         }
@@ -532,23 +323,13 @@ const queueNames = new Set();
         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) {
+    async _removeRequest(operation) {
         const now = Date.now();
         let entry;
         switch(operation){
@@ -560,8 +341,6 @@ const queueNames = new Set();
                 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);
@@ -570,11 +349,7 @@ const queueNames = new Set();
         }
         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() {
+    async replayRequests() {
         let entry = undefined;
         while(entry = await this.shiftRequest()){
             try {
@@ -596,30 +371,18 @@ const queueNames = new Set();
             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() {
-        // See https://github.com/GoogleChrome/workbox/issues/2393
+    async registerSync() {
         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
-   */ _addSyncListener() {
-        // See https://github.com/GoogleChrome/workbox/issues/2393
+    _addSyncListener() {
         if ("sync" in self.registration && !this._forceSyncFallback) {
             self.addEventListener("sync", (event)=>{
                 if (event.tag === `${TAG_PREFIX}:${this._name}`) {
@@ -636,16 +399,9 @@ const queueNames = new Set();
                         } 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();
                             }
@@ -660,42 +416,22 @@ const queueNames = new Set();
             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() {
+    static get _queueNames() {
         return queueNames;
     }
 }
 
-/**
- * A class implementing the `fetchDidFail` lifecycle callback. This makes it
- * easier to add failed requests to a background sync Queue.
- */ class BackgroundSyncPlugin {
+class BackgroundSyncPlugin {
     _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, options){
+    constructor(name, options){
         this._queue = new Queue(name, options);
     }
-    /**
-   * @param options
-   * @private
-   */ fetchDidFail = async ({ request })=>{
+    fetchDidFail = async ({ request })=>{
         await this._queue.pushRequest({
             request
         });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serwist/background-sync",
-  "version": "9.0.0-preview.0",
+  "version": "9.0.0-preview.2",
   "type": "module",
   "description": "Queues failed requests and uses the Background Sync API to replay them when the network is available",
   "files": [
@@ -31,13 +31,13 @@
   },
   "dependencies": {
     "idb": "8.0.0",
-    "@serwist/core": "9.0.0-preview.0"
+    "@serwist/core": "9.0.0-preview.2"
   },
   "devDependencies": {
     "cross-env": "7.0.3",
     "rollup": "4.9.6",
-    "typescript": "5.4.0-dev.20240203",
-    "@serwist/constants": "9.0.0-preview.0"
+    "typescript": "5.4.0-dev.20240206",
+    "@serwist/constants": "9.0.0-preview.2"
   },
   "peerDependencies": {
     "typescript": ">=5.0.0"