@serwist/background-sync 8.0.0

package/dist/index.js

@@ -0,0 +1,707 @@
+import { assert, SerwistError, logger, getFriendlyURL } from '@serwist/core/internal';
+import { openDB } from 'idb';
+
+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 {
+    _db = null;
+    /**
+   * Add QueueStoreEntry to underlying db.
+   *
+   * @param entry
+   */ async addEntry(entry) {
+        const db = await this.getDb();
+        const tx = db.transaction(REQUEST_OBJECT_STORE_NAME, "readwrite", {
+            durability: "relaxed"
+        });
+        await tx.store.add(entry);
+        await tx.done;
+    }
+    /**
+   * Returns the first entry id in the ObjectStore.
+   *
+   * @returns
+   */ 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) {
+        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) {
+        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) {
+        const db = await this.getDb();
+        await db.delete(REQUEST_OBJECT_STORE_NAME, id);
+    }
+    /**
+   *
+   * @param queueName
+   * @returns
+   */ async getFirstEntryByQueueName(queueName) {
+        return await this.getEndEntryFromIndex(IDBKeyRange.only(queueName), "next");
+    }
+    /**
+   *
+   * @param queueName
+   * @returns
+   */ 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) {
+        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() {
+        if (!this._db) {
+            this._db = await openDB(DB_NAME, DB_VERSION, {
+                upgrade: this._upgradeDb
+            });
+        }
+        return this._db;
+    }
+    /**
+   * Upgrades QueueDB
+   *
+   * @param db
+   * @param oldVersion
+   * @private
+   */ _upgradeDb(db, oldVersion) {
+        if (oldVersion > 0 && oldVersion < DB_VERSION) {
+            if (db.objectStoreNames.contains(REQUEST_OBJECT_STORE_NAME)) {
+                db.deleteObjectStore(REQUEST_OBJECT_STORE_NAME);
+            }
+        }
+        const objStore = db.createObjectStore(REQUEST_OBJECT_STORE_NAME, {
+            autoIncrement: true,
+            keyPath: "id"
+        });
+        objStore.createIndex(QUEUE_NAME_INDEX, QUEUE_NAME_INDEX, {
+            unique: false
+        });
+    }
+}
+
+/**
+ * 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 {
+    _queueName;
+    _queueDb;
+    /**
+   * Associates this instance with a Queue instance, so entries added can be
+   * identified by their queue name.
+   *
+   * @param queueName
+   */ constructor(queueName){
+        this._queueName = queueName;
+        this._queueDb = new QueueDb();
+    }
+    /**
+   * Append an entry last in the queue.
+   *
+   * @param entry
+   */ async pushEntry(entry) {
+        if (process.env.NODE_ENV !== "production") {
+            assert.isType(entry, "object", {
+                moduleName: "@serwist/background-sync",
+                className: "QueueStore",
+                funcName: "pushEntry",
+                paramName: "entry"
+            });
+            assert.isType(entry.requestData, "object", {
+                moduleName: "@serwist/background-sync",
+                className: "QueueStore",
+                funcName: "pushEntry",
+                paramName: "entry.requestData"
+            });
+        }
+        // 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) {
+        if (process.env.NODE_ENV !== "production") {
+            assert.isType(entry, "object", {
+                moduleName: "@serwist/background-sync",
+                className: "QueueStore",
+                funcName: "unshiftEntry",
+                paramName: "entry"
+            });
+            assert.isType(entry.requestData, "object", {
+                moduleName: "@serwist/background-sync",
+                className: "QueueStore",
+                funcName: "unshiftEntry",
+                paramName: "entry.requestData"
+            });
+        }
+        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 {
+            // Otherwise 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() {
+        return this._removeEntry(await this._queueDb.getLastEntryByQueueName(this._queueName));
+    }
+    /**
+   * Removes and returns the first entry in the queue matching the `queueName`.
+   *
+   * @returns
+   */ async shiftEntry() {
+        return this._removeEntry(await this._queueDb.getFirstEntryByQueueName(this._queueName));
+    }
+    /**
+   * Returns all entries in the store matching the `queueName`.
+   *
+   * @returns
+   */ async getAll() {
+        return await this._queueDb.getAllEntriesByQueueName(this._queueName);
+    }
+    /**
+   * Returns the number of entries in the store matching the `queueName`.
+   *
+   * @returns
+   */ 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) {
+        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) {
+        if (entry) {
+            await this.deleteEntry(entry.id);
+        }
+        return entry;
+    }
+}
+
+const serializableProperties = [
+    "method",
+    "referrer",
+    "referrerPolicy",
+    "mode",
+    "credentials",
+    "cache",
+    "redirect",
+    "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 {
+    _requestData;
+    /**
+   * Converts a Request object to a plain object that can be structured
+   * cloned or JSON-stringified.
+   *
+   * @param request
+   * @returns
+   */ 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];
+            }
+        }
+        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){
+        if (process.env.NODE_ENV !== "production") {
+            assert.isType(requestData, "object", {
+                moduleName: "@serwist/background-sync",
+                className: "StorableRequest",
+                funcName: "constructor",
+                paramName: "requestData"
+            });
+            assert.isType(requestData.url, "string", {
+                moduleName: "@serwist/background-sync",
+                className: "StorableRequest",
+                funcName: "constructor",
+                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() {
+        const requestData = Object.assign({}, this._requestData);
+        requestData.headers = Object.assign({}, this._requestData.headers);
+        if (requestData.body) {
+            requestData.body = requestData.body.slice(0);
+        }
+        return requestData;
+    }
+    /**
+   * Converts this instance to a Request.
+   *
+   * @returns
+   */ toRequest() {
+        return new Request(this._requestData.url, this._requestData);
+    }
+    /**
+   * Creates and returns a deep clone of the instance.
+   *
+   * @returns
+   */ clone() {
+        return new StorableRequest(this.toObject());
+    }
+}
+
+const TAG_PREFIX = "serwist-background-sync";
+const MAX_RETENTION_TIME = 60 * 24 * 7; // 7 days in minutes
+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 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 {
+    _name;
+    _onSync;
+    _maxRetentionTime;
+    _queueStore;
+    _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
+        if (queueNames.has(name)) {
+            throw new SerwistError("duplicate-queue-name", {
+                name
+            });
+        } else {
+            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() {
+        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) {
+        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) {
+        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() {
+        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() {
+        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() {
+        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() {
+        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) {
+        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;
+        }
+        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) {
+        const now = Date.now();
+        let entry;
+        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);
+        } else {
+            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() {
+        let entry;
+        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() {
+        // 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
+   */ _addSyncListener() {
+        // See https://github.com/GoogleChrome/workbox/issues/2393
+        if ("sync" in self.registration && !this._forceSyncFallback) {
+            self.addEventListener("sync", (event)=>{
+                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;
+                        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() {
+        return queueNames;
+    }
+}
+
+/**
+ * A class implementing the `fetchDidFail` lifecycle callback. This makes it
+ * easier to add failed requests to a background sync Queue.
+ */ 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){
+        this._queue = new Queue(name, options);
+    }
+    /**
+   * @param options
+   * @private
+   */ fetchDidFail = async ({ request })=>{
+        await this._queue.pushRequest({
+            request
+        });
+    };
+}
+
+export { BackgroundSyncPlugin, Queue, QueueStore, StorableRequest };