@serwist/expiration 8.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2018 Google LLC, 2019 ShadowWalker w@weiw.io https://weiw.io, 2023 Serwist
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1 @@
+This module's documentation can be found at https://developers.google.com/web/tools/workbox/modules/workbox-expiration

package/dist/CacheExpiration.d.ts

@@ -0,0 +1,69 @@
+interface CacheExpirationConfig {
+    /**
+     * The maximum number of entries to cache. Entries used the least will
+     * be removed as the maximum is reached.
+     */
+    maxEntries?: number;
+    /**
+     * The maximum age of an entry before it's treated as stale and removed.
+     */
+    maxAgeSeconds?: number;
+    /**
+     * The [`CacheQueryOptions`](https://developer.mozilla.org/en-US/docs/Web/API/Cache/delete#Parameters)
+     * that will be used when calling `delete()` on the cache.
+     */
+    matchOptions?: CacheQueryOptions;
+}
+/**
+ * The `CacheExpiration` class allows you define an expiration and / or
+ * limit on the number of responses stored in a
+ * [`Cache`](https://developer.mozilla.org/en-US/docs/Web/API/Cache).
+ */
+declare class CacheExpiration {
+    private _isRunning;
+    private _rerunRequested;
+    private readonly _maxEntries?;
+    private readonly _maxAgeSeconds?;
+    private readonly _matchOptions?;
+    private readonly _cacheName;
+    private readonly _timestampModel;
+    /**
+     * To construct a new CacheExpiration instance you must provide at least
+     * one of the `config` properties.
+     *
+     * @param cacheName Name of the cache to apply restrictions to.
+     * @param config
+     */
+    constructor(cacheName: string, config?: CacheExpirationConfig);
+    /**
+     * Expires entries for the given cache and given criteria.
+     */
+    expireEntries(): Promise<void>;
+    /**
+     * Update the timestamp for the given URL. This ensures the when
+     * removing entries based on maximum entries, most recently used
+     * is accurate or when expiring, the timestamp is up-to-date.
+     *
+     * @param url
+     */
+    updateTimestamp(url: string): Promise<void>;
+    /**
+     * Can be used to check if a URL has expired or not before it's used.
+     *
+     * This requires a look up from IndexedDB, so can be slow.
+     *
+     * Note: This method will not remove the cached entry, call
+     * `expireEntries()` to remove indexedDB and Cache entries.
+     *
+     * @param url
+     * @returns
+     */
+    isURLExpired(url: string): Promise<boolean>;
+    /**
+     * Removes the IndexedDB object store used to keep track of cache expiration
+     * metadata.
+     */
+    delete(): Promise<void>;
+}
+export { CacheExpiration };
+//# sourceMappingURL=CacheExpiration.d.ts.map

package/dist/CacheExpiration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CacheExpiration.d.ts","sourceRoot":"","sources":["../src/CacheExpiration.ts"],"names":[],"mappings":"AAYA,UAAU,qBAAqB;IAC7B;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,YAAY,CAAC,EAAE,iBAAiB,CAAC;CAClC;AAED;;;;GAIG;AACH,cAAM,eAAe;IACnB,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,eAAe,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAS;IACzC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAoB;IACnD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAuB;IAEvD;;;;;;OAMG;gBACS,SAAS,EAAE,MAAM,EAAE,MAAM,GAAE,qBAA0B;IA2CjE;;OAEG;IACG,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC;IAwCpC;;;;;;OAMG;IACG,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAajD;;;;;;;;;;OAUG;IACG,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAgBjD;;;OAGG;IACG,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;CAM9B;AAED,OAAO,EAAE,eAAe,EAAE,CAAC"}

package/dist/ExpirationPlugin.d.ts

@@ -0,0 +1,116 @@
+import type { SerwistPlugin } from "@serwist/core";
+export interface ExpirationPluginOptions {
+    /**
+     * The maximum number of entries to cache. Entries used the least will be removed
+     * as the maximum is reached.
+     */
+    maxEntries?: number;
+    /**
+     * The maximum age of an entry before it's treated as stale and removed.
+     */
+    maxAgeSeconds?: number;
+    /**
+     * The [`CacheQueryOptions`](https://developer.mozilla.org/en-US/docs/Web/API/Cache/delete#Parameters)
+     * that will be used when calling `delete()` on the cache.
+     */
+    matchOptions?: CacheQueryOptions;
+    /**
+     * Whether to opt this cache in to automatic deletion if the available storage quota has been exceeded.
+     */
+    purgeOnQuotaError?: boolean;
+}
+/**
+ * This plugin can be used in a `@serwist/strategies` Strategy to regularly enforce a
+ * limit on the age and / or the number of cached requests.
+ *
+ * It can only be used with Strategy instances that have a
+ * [custom `cacheName` property set](/web/tools/workbox/guides/configure-workbox#custom_cache_names_in_strategies).
+ * In other words, it can't be used to expire entries in strategy that uses the
+ * default runtime cache name.
+ *
+ * Whenever a cached response is used or updated, this plugin will look
+ * at the associated cache and remove any old or extra responses.
+ *
+ * When using `maxAgeSeconds`, responses may be used *once* after expiring
+ * because the expiration clean up will not have occurred until *after* the
+ * cached response has been used. If the response has a "Date" header, then
+ * a light weight expiration check is performed and the response will not be
+ * used immediately.
+ *
+ * When using `maxEntries`, the entry least-recently requested will be removed
+ * from the cache first.
+ */
+declare class ExpirationPlugin implements SerwistPlugin {
+    private readonly _config;
+    private readonly _maxAgeSeconds?;
+    private _cacheExpirations;
+    /**
+     * @param config
+     */
+    constructor(config?: ExpirationPluginOptions);
+    /**
+     * A simple helper method to return a CacheExpiration instance for a given
+     * cache name.
+     *
+     * @param cacheName
+     * @returns
+     * @private
+     */
+    private _getCacheExpiration;
+    /**
+     * A "lifecycle" callback that will be triggered automatically by the
+     * `@serwist/strategies` handlers when a `Response` is about to be returned
+     * from a [Cache](https://developer.mozilla.org/en-US/docs/Web/API/Cache) to
+     * the handler. It allows the `Response` to be inspected for freshness and
+     * prevents it from being used if the `Response`'s `Date` header value is
+     * older than the configured `maxAgeSeconds`.
+     *
+     * @param options
+     * @returns Either the `cachedResponse`, if it's fresh, or `null` if the `Response`
+     * is older than `maxAgeSeconds`.
+     * @private
+     */
+    cachedResponseWillBeUsed: SerwistPlugin["cachedResponseWillBeUsed"];
+    /**
+     * @param cachedResponse
+     * @returns
+     * @private
+     */
+    private _isResponseDateFresh;
+    /**
+     * This method will extract the data header and parse it into a useful
+     * value.
+     *
+     * @param cachedResponse
+     * @returns
+     * @private
+     */
+    private _getDateHeaderTimestamp;
+    /**
+     * A "lifecycle" callback that will be triggered automatically by the
+     * `@serwist/strategies` handlers when an entry is added to a cache.
+     *
+     * @param options
+     * @private
+     */
+    cacheDidUpdate: SerwistPlugin["cacheDidUpdate"];
+    /**
+     * This is a helper method that performs two operations:
+     *
+     * - Deletes *all* the underlying Cache instances associated with this plugin
+     * instance, by calling caches.delete() on your behalf.
+     * - Deletes the metadata from IndexedDB used to keep track of expiration
+     * details for each Cache instance.
+     *
+     * When using cache expiration, calling this method is preferable to calling
+     * `caches.delete()` directly, since this will ensure that the IndexedDB
+     * metadata is also cleanly removed and open IndexedDB instances are deleted.
+     *
+     * Note that if you're *not* using cache expiration for a given cache, calling
+     * `caches.delete()` and passing in the cache's name should be sufficient.
+     * There is no Serwist-specific method needed for cleanup in that case.
+     */
+    deleteCacheAndMetadata(): Promise<void>;
+}
+export { ExpirationPlugin };
+//# sourceMappingURL=ExpirationPlugin.d.ts.map

package/dist/ExpirationPlugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ExpirationPlugin.d.ts","sourceRoot":"","sources":["../src/ExpirationPlugin.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAMnD,MAAM,WAAW,uBAAuB;IACtC;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,YAAY,CAAC,EAAE,iBAAiB,CAAC;IACjC;;OAEG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,cAAM,gBAAiB,YAAW,aAAa;IAC7C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA0B;IAClD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAS;IACzC,OAAO,CAAC,iBAAiB,CAA+B;IAExD;;OAEG;gBACS,MAAM,GAAE,uBAA4B;IAsChD;;;;;;;OAOG;IACH,OAAO,CAAC,mBAAmB;IAa3B;;;;;;;;;;;;OAYG;IACH,wBAAwB,EAAE,aAAa,CAAC,0BAA0B,CAAC,CAiCjE;IAEF;;;;OAIG;IACH,OAAO,CAAC,oBAAoB;IAqB5B;;;;;;;OAOG;IACH,OAAO,CAAC,uBAAuB;IAkB/B;;;;;;OAMG;IACH,cAAc,EAAE,aAAa,CAAC,gBAAgB,CAAC,CAmB7C;IAEF;;;;;;;;;;;;;;;OAeG;IACG,sBAAsB,IAAI,OAAO,CAAC,IAAI,CAAC;CAW9C;AAED,OAAO,EAAE,gBAAgB,EAAE,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+import { CacheExpiration } from "./CacheExpiration.js";
+import type { ExpirationPluginOptions } from "./ExpirationPlugin.js";
+import { ExpirationPlugin } from "./ExpirationPlugin.js";
+export { CacheExpiration, ExpirationPlugin };
+export type { ExpirationPluginOptions };
+//# 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":"AAQA,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AACrE,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAEzD,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,CAAC;AAE7C,YAAY,EAAE,uBAAuB,EAAE,CAAC"}