@amazon/vinyl-cache-manager 1.0.0

package/dist/types/ts3.7/cacheManager/CacheManager.d.ts

@@ -0,0 +1,119 @@
+import { CacheControl } from './CacheControl';
+export declare const DEFAULT_CACHE_NAME = "offlineCache";
+export declare const DEFAULT_PURGE_AFTER_STALE: number;
+/**
+ * If the cache control options set the onlyIfCached directive and the request is not cached, an error will be thrown.
+ */
+export declare const NOT_CACHED_ERROR = "Not cached";
+export type CacheManagerOptions = {
+    /**
+     * The name of the cache key.
+     */
+    readonly name?: string;
+    /**
+     * The Fetch from network method. Defaults to window.fetch.
+     */
+    readonly requestFromNetwork?: Fetch;
+};
+type Fetch = (request: RequestInfo) => Promise<Response>;
+export type CacheEntryOptions = {
+    /**
+     * If set, the response will be cached under this identifier, not based on the request.
+     * This is required for caching POST requests.
+     */
+    readonly cacheKey?: string | null | undefined;
+    /**
+     * Cache control directive defaults.
+     * These will be used unless overridden by the response headers or the cache control overrides.
+     *
+     * CacheControl directives will be overwritten in the order:
+     * - cacheControlDefaults
+     * - response headers
+     * - cacheControlOverrides
+     */
+    readonly cacheControlDefaults?: CacheControl;
+    /**
+     * Allows the client to set cache control overrides. This object is merged with the actual cache control header.
+     *
+     * For example, to allow cached items to be used 1 day after they are stale while asynchronously revalidating
+     * the cache, set `{ staleWhileRevalidate: 24 * 60 * 60 }`
+     *
+     * These overrides do not change the header cached, only how the cached header is read.
+     * If noStore is true, the entry will not be cached.
+     */
+    readonly cacheControlOverrides?: CacheControl;
+    /**
+     * If set, checks the response if it should be used. This affects whether to cache and whether to use the
+     * cached fallback.
+     */
+    readonly responseIsValid?: (response: Response) => Promise<boolean>;
+};
+export type CacheCleanOptions = {
+    /**
+     * The number of seconds after an entry becomes stale before it should be removed from the cache.
+     * Default: 7 * 24 * 60 * 60 (7 days).
+     * If the cached entry has a stale-while-revalidate cache control directive, this will be ignored.
+     */
+    readonly purgeAfterStale?: number;
+};
+export interface CacheManagerDeps {
+    /**
+     * The cache storages api.
+     * Default: window.caches
+     */
+    readonly caches?: CacheStorage;
+    /**
+     * Creates a Headers object
+     */
+    readonly headersFactory?: (headersInit?: HeadersInit) => Headers;
+    /**
+     * Creates a Response object
+     */
+    readonly responseFactory?: (body?: BodyInit | null, init?: ResponseInit) => Response;
+}
+export declare class CacheManager {
+    readonly name: string;
+    private readonly caches;
+    private cache;
+    private readonly fetch;
+    /**
+     * If set, when asynchronous caching has failed, this callback will be invoked.
+     * This is not invoked when a promise rejects during an operation.
+     */
+    onError?: (error: Error) => void;
+    constructor(options?: CacheManagerOptions, deps?: CacheManagerDeps);
+    private readonly errorHandler;
+    /**
+     * Caches a response with added expiry headers.
+     */
+    put(cacheId: RequestInfo, response: Response): Promise<Response>;
+    /**
+     * Deletes the request from this cache.
+     *
+     * @param cacheId The request or cache id used as the cache key.
+     */
+    delete(cacheId: RequestInfo): Promise<boolean>;
+    /**
+     * Resolves to true if the request is cached.
+     *
+     * @param cacheId
+     */
+    has(cacheId: RequestInfo): Promise<boolean>;
+    get(request: RequestInfo, options?: CacheEntryOptions): Promise<Response>;
+    /**
+     * Returns a Response if it exists in cache.
+     *
+     * @param request
+     */
+    private getCached;
+    /**
+     * @returns a promise that resolves to true if the Cache object is found and deleted, and false otherwise.
+     */
+    clear(): Promise<boolean>;
+    /**
+     * Cleans stale items from the cache.
+     */
+    clean(options?: CacheCleanOptions): Promise<void>;
+}
+export {};
+//# sourceMappingURL=CacheManager.d.ts.map

package/dist/types/ts3.7/index.d.ts

@@ -0,0 +1,4 @@
+/** Auto-generated from build scripts */
+export * from './cacheManager/CacheManager';
+export * from './cacheManager/CacheControl';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/ts4.1/cacheManager/CacheControl.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Represents all known Cache-Control directives.
+ *
+ * https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control
+ */
+export type CacheControl = {
+    /**
+     * The maximum amount of time (in seconds) a resource is considered fresh.
+     * Example: `max-age=3600` (1 hour)
+     */
+    readonly maxAge?: number;
+    /**
+     * Requires the resource to be revalidated with the origin server before serving it from the cache.
+     * Example: `no-cache`
+     */
+    readonly noCache?: boolean;
+    /**
+     * Prevents the resource from being cached by any mechanism.
+     * Example: `no-store`
+     */
+    readonly noStore?: boolean;
+    /**
+     * Ensures that stale responses cannot be used without successful revalidation with the origin server.
+     * Example: `must-revalidate`
+     */
+    readonly mustRevalidate?: boolean;
+    /**
+     * Indicates the resource is cacheable by both shared and private caches.
+     * Example: `public`
+     */
+    readonly public?: boolean;
+    /**
+     * Indicates the resource is cacheable only by the user's browser or private caches, not shared caches.
+     * Example: `private`
+     */
+    readonly private?: boolean;
+    /**
+     * Indicates that the resource will not change, so it does not need to be revalidated.
+     * Example: `immutable`
+     */
+    readonly immutable?: boolean;
+    /**
+     * Allows serving stale responses for the specified duration (in seconds) while asynchronously revalidating the
+     * cache.
+     * Example: `stale-while-revalidate=60`
+     */
+    readonly staleWhileRevalidate?: number;
+    /**
+     * Allows serving stale responses (in seconds) if the origin server is unavailable or returns an error.
+     * Example: `stale-if-error=86400` (1 day)
+     */
+    readonly staleIfError?: number;
+    /**
+     * Indicates the client only wants a response from the cache and will not make a network request.
+     * Example: `only-if-cached`
+     */
+    readonly onlyIfCached?: boolean;
+};
+/**
+ * Parses a Cache-Control header string into a structured object.
+ * Handles known directives with optional numeric values.
+ *
+ * @param str - The Cache-Control header string to parse.
+ * @returns A CacheControl object representing the parsed directives.
+ */
+export declare function parseCacheControl(str: string | null | undefined): CacheControl;
+//# sourceMappingURL=CacheControl.d.ts.map

package/dist/types/ts4.1/cacheManager/CacheManager.d.ts

@@ -0,0 +1,119 @@
+import type { CacheControl } from './CacheControl';
+export declare const DEFAULT_CACHE_NAME = "offlineCache";
+export declare const DEFAULT_PURGE_AFTER_STALE: number;
+/**
+ * If the cache control options set the onlyIfCached directive and the request is not cached, an error will be thrown.
+ */
+export declare const NOT_CACHED_ERROR = "Not cached";
+export type CacheManagerOptions = {
+    /**
+     * The name of the cache key.
+     */
+    readonly name?: string;
+    /**
+     * The Fetch from network method. Defaults to window.fetch.
+     */
+    readonly requestFromNetwork?: Fetch;
+};
+type Fetch = (request: RequestInfo) => Promise<Response>;
+export type CacheEntryOptions = {
+    /**
+     * If set, the response will be cached under this identifier, not based on the request.
+     * This is required for caching POST requests.
+     */
+    readonly cacheKey?: string | null | undefined;
+    /**
+     * Cache control directive defaults.
+     * These will be used unless overridden by the response headers or the cache control overrides.
+     *
+     * CacheControl directives will be overwritten in the order:
+     * - cacheControlDefaults
+     * - response headers
+     * - cacheControlOverrides
+     */
+    readonly cacheControlDefaults?: CacheControl;
+    /**
+     * Allows the client to set cache control overrides. This object is merged with the actual cache control header.
+     *
+     * For example, to allow cached items to be used 1 day after they are stale while asynchronously revalidating
+     * the cache, set `{ staleWhileRevalidate: 24 * 60 * 60 }`
+     *
+     * These overrides do not change the header cached, only how the cached header is read.
+     * If noStore is true, the entry will not be cached.
+     */
+    readonly cacheControlOverrides?: CacheControl;
+    /**
+     * If set, checks the response if it should be used. This affects whether to cache and whether to use the
+     * cached fallback.
+     */
+    readonly responseIsValid?: (response: Response) => Promise<boolean>;
+};
+export type CacheCleanOptions = {
+    /**
+     * The number of seconds after an entry becomes stale before it should be removed from the cache.
+     * Default: 7 * 24 * 60 * 60 (7 days).
+     * If the cached entry has a stale-while-revalidate cache control directive, this will be ignored.
+     */
+    readonly purgeAfterStale?: number;
+};
+export interface CacheManagerDeps {
+    /**
+     * The cache storages api.
+     * Default: window.caches
+     */
+    readonly caches?: CacheStorage;
+    /**
+     * Creates a Headers object
+     */
+    readonly headersFactory?: (headersInit?: HeadersInit) => Headers;
+    /**
+     * Creates a Response object
+     */
+    readonly responseFactory?: (body?: BodyInit | null, init?: ResponseInit) => Response;
+}
+export declare class CacheManager {
+    readonly name: string;
+    private readonly caches;
+    private cache;
+    private readonly fetch;
+    /**
+     * If set, when asynchronous caching has failed, this callback will be invoked.
+     * This is not invoked when a promise rejects during an operation.
+     */
+    onError?: (error: Error) => void;
+    constructor(options?: CacheManagerOptions, deps?: CacheManagerDeps);
+    private readonly errorHandler;
+    /**
+     * Caches a response with added expiry headers.
+     */
+    put(cacheId: RequestInfo, response: Response): Promise<Response>;
+    /**
+     * Deletes the request from this cache.
+     *
+     * @param cacheId The request or cache id used as the cache key.
+     */
+    delete(cacheId: RequestInfo): Promise<boolean>;
+    /**
+     * Resolves to true if the request is cached.
+     *
+     * @param cacheId
+     */
+    has(cacheId: RequestInfo): Promise<boolean>;
+    get(request: RequestInfo, options?: CacheEntryOptions): Promise<Response>;
+    /**
+     * Returns a Response if it exists in cache.
+     *
+     * @param request
+     */
+    private getCached;
+    /**
+     * @returns a promise that resolves to true if the Cache object is found and deleted, and false otherwise.
+     */
+    clear(): Promise<boolean>;
+    /**
+     * Cleans stale items from the cache.
+     */
+    clean(options?: CacheCleanOptions): Promise<void>;
+}
+export {};
+//# sourceMappingURL=CacheManager.d.ts.map

package/dist/types/ts4.1/index.d.ts

@@ -0,0 +1,4 @@
+/** Auto-generated from build scripts */
+export * from './cacheManager/CacheManager';
+export * from './cacheManager/CacheControl';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/ts4.7/cacheManager/CacheControl.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Represents all known Cache-Control directives.
+ *
+ * https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control
+ */
+export type CacheControl = {
+    /**
+     * The maximum amount of time (in seconds) a resource is considered fresh.
+     * Example: `max-age=3600` (1 hour)
+     */
+    readonly maxAge?: number;
+    /**
+     * Requires the resource to be revalidated with the origin server before serving it from the cache.
+     * Example: `no-cache`
+     */
+    readonly noCache?: boolean;
+    /**
+     * Prevents the resource from being cached by any mechanism.
+     * Example: `no-store`
+     */
+    readonly noStore?: boolean;
+    /**
+     * Ensures that stale responses cannot be used without successful revalidation with the origin server.
+     * Example: `must-revalidate`
+     */
+    readonly mustRevalidate?: boolean;
+    /**
+     * Indicates the resource is cacheable by both shared and private caches.
+     * Example: `public`
+     */
+    readonly public?: boolean;
+    /**
+     * Indicates the resource is cacheable only by the user's browser or private caches, not shared caches.
+     * Example: `private`
+     */
+    readonly private?: boolean;
+    /**
+     * Indicates that the resource will not change, so it does not need to be revalidated.
+     * Example: `immutable`
+     */
+    readonly immutable?: boolean;
+    /**
+     * Allows serving stale responses for the specified duration (in seconds) while asynchronously revalidating the
+     * cache.
+     * Example: `stale-while-revalidate=60`
+     */
+    readonly staleWhileRevalidate?: number;
+    /**
+     * Allows serving stale responses (in seconds) if the origin server is unavailable or returns an error.
+     * Example: `stale-if-error=86400` (1 day)
+     */
+    readonly staleIfError?: number;
+    /**
+     * Indicates the client only wants a response from the cache and will not make a network request.
+     * Example: `only-if-cached`
+     */
+    readonly onlyIfCached?: boolean;
+};
+/**
+ * Parses a Cache-Control header string into a structured object.
+ * Handles known directives with optional numeric values.
+ *
+ * @param str - The Cache-Control header string to parse.
+ * @returns A CacheControl object representing the parsed directives.
+ */
+export declare function parseCacheControl(str: string | null | undefined): CacheControl;
+//# sourceMappingURL=CacheControl.d.ts.map

package/dist/types/ts4.7/cacheManager/CacheManager.d.ts

@@ -0,0 +1,119 @@
+import { type CacheControl } from './CacheControl';
+export declare const DEFAULT_CACHE_NAME = "offlineCache";
+export declare const DEFAULT_PURGE_AFTER_STALE: number;
+/**
+ * If the cache control options set the onlyIfCached directive and the request is not cached, an error will be thrown.
+ */
+export declare const NOT_CACHED_ERROR = "Not cached";
+export type CacheManagerOptions = {
+    /**
+     * The name of the cache key.
+     */
+    readonly name?: string;
+    /**
+     * The Fetch from network method. Defaults to window.fetch.
+     */
+    readonly requestFromNetwork?: Fetch;
+};
+type Fetch = (request: RequestInfo) => Promise<Response>;
+export type CacheEntryOptions = {
+    /**
+     * If set, the response will be cached under this identifier, not based on the request.
+     * This is required for caching POST requests.
+     */
+    readonly cacheKey?: string | null | undefined;
+    /**
+     * Cache control directive defaults.
+     * These will be used unless overridden by the response headers or the cache control overrides.
+     *
+     * CacheControl directives will be overwritten in the order:
+     * - cacheControlDefaults
+     * - response headers
+     * - cacheControlOverrides
+     */
+    readonly cacheControlDefaults?: CacheControl;
+    /**
+     * Allows the client to set cache control overrides. This object is merged with the actual cache control header.
+     *
+     * For example, to allow cached items to be used 1 day after they are stale while asynchronously revalidating
+     * the cache, set `{ staleWhileRevalidate: 24 * 60 * 60 }`
+     *
+     * These overrides do not change the header cached, only how the cached header is read.
+     * If noStore is true, the entry will not be cached.
+     */
+    readonly cacheControlOverrides?: CacheControl;
+    /**
+     * If set, checks the response if it should be used. This affects whether to cache and whether to use the
+     * cached fallback.
+     */
+    readonly responseIsValid?: (response: Response) => Promise<boolean>;
+};
+export type CacheCleanOptions = {
+    /**
+     * The number of seconds after an entry becomes stale before it should be removed from the cache.
+     * Default: 7 * 24 * 60 * 60 (7 days).
+     * If the cached entry has a stale-while-revalidate cache control directive, this will be ignored.
+     */
+    readonly purgeAfterStale?: number;
+};
+export interface CacheManagerDeps {
+    /**
+     * The cache storages api.
+     * Default: window.caches
+     */
+    readonly caches?: CacheStorage;
+    /**
+     * Creates a Headers object
+     */
+    readonly headersFactory?: (headersInit?: HeadersInit) => Headers;
+    /**
+     * Creates a Response object
+     */
+    readonly responseFactory?: (body?: BodyInit | null, init?: ResponseInit) => Response;
+}
+export declare class CacheManager {
+    readonly name: string;
+    private readonly caches;
+    private cache;
+    private readonly fetch;
+    /**
+     * If set, when asynchronous caching has failed, this callback will be invoked.
+     * This is not invoked when a promise rejects during an operation.
+     */
+    onError?: (error: Error) => void;
+    constructor(options?: CacheManagerOptions, deps?: CacheManagerDeps);
+    private readonly errorHandler;
+    /**
+     * Caches a response with added expiry headers.
+     */
+    put(cacheId: RequestInfo, response: Response): Promise<Response>;
+    /**
+     * Deletes the request from this cache.
+     *
+     * @param cacheId The request or cache id used as the cache key.
+     */
+    delete(cacheId: RequestInfo): Promise<boolean>;
+    /**
+     * Resolves to true if the request is cached.
+     *
+     * @param cacheId
+     */
+    has(cacheId: RequestInfo): Promise<boolean>;
+    get(request: RequestInfo, options?: CacheEntryOptions): Promise<Response>;
+    /**
+     * Returns a Response if it exists in cache.
+     *
+     * @param request
+     */
+    private getCached;
+    /**
+     * @returns a promise that resolves to true if the Cache object is found and deleted, and false otherwise.
+     */
+    clear(): Promise<boolean>;
+    /**
+     * Cleans stale items from the cache.
+     */
+    clean(options?: CacheCleanOptions): Promise<void>;
+}
+export {};
+//# sourceMappingURL=CacheManager.d.ts.map

package/dist/types/ts4.7/index.d.ts

@@ -0,0 +1,4 @@
+/** Auto-generated from build scripts */
+export * from './cacheManager/CacheManager';
+export * from './cacheManager/CacheControl';
+//# sourceMappingURL=index.d.ts.map

package/package.json

@@ -0,0 +1,81 @@
+{
+    "name": "@amazon/vinyl-cache-manager",
+    "version": "1.0.0",
+    "description": "A mediator for the Cache API",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/amazonmusic/vinyl.git"
+    },
+    "license": "UNLICENSED",
+    "module": "./dist/index.js",
+    "main": "./dist/index.cjs",
+    "types": "./dist/types/ts3.7/index.d.ts",
+    "type": "module",
+    "sideEffects": [
+        "test/**/*"
+    ],
+    "files": [
+        "dist/*",
+        "docs/*"
+    ],
+    "typesVersions": {
+        ">=5.4": {
+            "*": [
+                "./dist/types/current/index.d.ts"
+            ]
+        },
+        ">=4.7": {
+            "*": [
+                "./dist/types/ts4.7/index.d.ts"
+            ]
+        },
+        ">=4.1": {
+            "*": [
+                "./dist/types/ts4.1/index.d.ts"
+            ]
+        },
+        ">=3.7": {
+            "*": [
+                "./dist/types/ts3.7/index.d.ts"
+            ]
+        }
+    },
+    "exports": {
+        ".": {
+            "types@>=5.4": "./dist/types/current/index.d.ts",
+            "types@>=4.7": "./dist/types/ts4.7/index.d.ts",
+            "require": "./dist/index.cjs",
+            "import": "./dist/index.js"
+        }
+    },
+    "scripts": {
+        "analyzeExports": "tsx buildSrc/analyzeExports.ts",
+        "analyzeExports:write": "tsx buildSrc/analyzeExports.ts --write",
+        "clean": "rimraf --glob dist .eslintcache \"**/*.tsbuildinfo\"",
+        "indexFiles:check": "tsx buildSrc/writeIndexFiles.ts --check",
+        "indexFiles:write": "tsx buildSrc/writeIndexFiles.ts",
+        "build": "tsx buildSrc/build.ts",
+        "build:release": "tsx buildSrc/build.ts --release",
+        "prettier:check": "prettier . --ignore-path ../../.prettierignore --cache --check",
+        "prettier:write": "prettier . --ignore-path ../../.prettierignore --cache --write",
+        "eslint:check": "eslint . --cache --max-warnings=0",
+        "eslint:write": "eslint . --cache --fix",
+        "lint": "npm run indexFiles:check && npm run eslint:check && npm run prettier:check",
+        "lint:write": "npm run indexFiles:write && npm run eslint:write && npm run prettier:write",
+        "validate": "tsc --project test/unit && npm run lint && npm run test",
+        "test": "tsx --tsconfig ../../tsconfig.flat.json ../../node_modules/jasmine/bin/jasmine --config=test/unit/jasmine.config.json",
+        "test:coverage": "c8 npm run test",
+        "watch": "tsx buildSrc/build.ts --watch",
+        "watch:release": "tsx buildSrc/build.ts --watch --release"
+    },
+    "devDependencies": {
+        "@amazon/vinyl-build-utils": "^1.0.0",
+        "@amazon/vinyl-jasmine-wrapper": "^1.0.0"
+    },
+    "dependencies": {
+        "@amazon/vinyl-util": "^1.0.0"
+    },
+    "browserslist": [
+        "defaults, chrome 52, firefox 54, edge 15, safari 8"
+    ]
+}