@netlify/cache 1.1.0 → 1.3.0

package/dist/main.cjs

@@ -3,6 +3,10 @@ var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
 var __copyProps = (to, from, except, desc) => {
   if (from && typeof from === "object" || typeof from === "function") {
     for (let key of __getOwnPropNames(from))
@@ -15,4 +19,280 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 
 // src/main.ts
 var main_exports = {};
+__export(main_exports, {
+  fetchWithCache: () => fetchWithCache,
+  getCacheStatus: () => getCacheStatus,
+  setCacheHeaders: () => setCacheHeaders
+});
 module.exports = __toCommonJS(main_exports);
+
+// src/headers.ts
+var CacheStatus = "cache-status";
+var NetlifyCacheId = "netlify-cache-id";
+var NetlifyCacheTag = "netlify-cache-tag";
+var NetlifyCdnCacheControl = "netlify-cdn-cache-control";
+var NetlifyVary = "netlify-vary";
+
+// src/cache-headers/validation.ts
+var ensureArray = (value) => Array.isArray(value) ? value : [value];
+var requireArrayOfStrings = (name, value) => {
+  if (!Array.isArray(value) || value.some((part) => typeof part !== "string" || part.length === 0)) {
+    throw new TypeError(`'${name}' must be an array of non-empty strings.`);
+  }
+  return value;
+};
+var requireArrayOfStringsWithNesting = (name, value, joiner) => {
+  if (!Array.isArray(value)) {
+    throw new TypeError(`'${name}' must be an array.`);
+  }
+  return value.map((part, index) => {
+    if (typeof part === "string") {
+      return part;
+    }
+    return requireArrayOfStrings(`${name}[${index}]`, part).join(joiner);
+  });
+};
+var requirePositiveInteger = (name, value) => {
+  const number = Number.parseFloat(value);
+  if (Number.isNaN(number) || !Number.isInteger(number) || number < 0 || number === Number.POSITIVE_INFINITY) {
+    throw new TypeError(`'${name}' must be a positive integer number.`);
+  }
+  return number;
+};
+
+// src/cache-headers/cache-headers.ts
+var ONE_YEAR = 60 * 24 * 365;
+var cacheHeaders = (cacheSettings) => {
+  const { durable, overrideDeployRevalidation: id, tags, ttl, swr, vary } = cacheSettings;
+  const headers = {};
+  const cacheControlDirectives = [];
+  if (ttl) {
+    const ttlValue = requirePositiveInteger("ttl", ttl);
+    if (ttlValue > 0) {
+      cacheControlDirectives.push(`s-maxage=${ttlValue}`);
+    }
+  }
+  if (swr) {
+    const swrValue = swr === true ? ONE_YEAR : requirePositiveInteger("swr", swr);
+    if (swrValue > 0) {
+      cacheControlDirectives.push(`stale-while-revalidate=${swrValue}`);
+    }
+  }
+  if (cacheControlDirectives.length > 0) {
+    if (durable) {
+      cacheControlDirectives.push("durable");
+    }
+    headers[NetlifyCdnCacheControl] = cacheControlDirectives.join(",");
+  }
+  if (tags) {
+    headers[NetlifyCacheTag] = requireArrayOfStrings("tags", tags).join(",");
+  }
+  const netlifyVary = getNetlifyVary(vary);
+  if (netlifyVary) {
+    headers[NetlifyVary] = netlifyVary;
+  }
+  if (id) {
+    headers[NetlifyCacheId] = requireArrayOfStrings("id", ensureArray(id)).join(",");
+  }
+  return headers;
+};
+var getNetlifyVary = (varyOptions) => {
+  if (!varyOptions) {
+    return null;
+  }
+  const { cookie, country, header, language, query } = varyOptions;
+  const directives = [];
+  if (cookie) {
+    directives.push(`cookie=${requireArrayOfStrings("cookie", ensureArray(cookie)).join("|")}`);
+  }
+  if (country) {
+    directives.push(`country=${requireArrayOfStringsWithNesting("country", ensureArray(country), "+").join("|")}`);
+  }
+  if (header) {
+    directives.push(`header=${requireArrayOfStrings("header", ensureArray(header)).join("|")}`);
+  }
+  if (language) {
+    directives.push(`language=${requireArrayOfStringsWithNesting("language", ensureArray(language), "+").join("|")}`);
+  }
+  if (query) {
+    if (query === true) {
+      directives.push(`query`);
+    } else {
+      directives.push(`query=${requireArrayOfStrings("query", ensureArray(query)).join("|")}`);
+    }
+  }
+  if (directives.length === 0) {
+    return null;
+  }
+  return directives.join(",");
+};
+var applyHeaders = (subject, headersObject) => {
+  for (const name in headersObject) {
+    if (name === NetlifyCdnCacheControl) {
+      subject.set(name, headersObject[name]);
+    } else {
+      subject.append(name, headersObject[name]);
+    }
+  }
+};
+var setCacheHeaders = (response, cacheSettings) => {
+  if (!(response instanceof Response)) {
+    throw new TypeError("Input must be a Response object.");
+  }
+  const newResponse = new Response(response.body, response);
+  applyHeaders(newResponse.headers, cacheHeaders(cacheSettings));
+  return newResponse;
+};
+
+// src/cache-status/cache-status.ts
+var CACHE_DURABLE = "netlify durable";
+var CACHE_EDGE = "netlify edge";
+var parseCacheStatusValue = (value) => {
+  const parts = value.split(";").map((part) => part.trim());
+  const [namePart, ...attributeParts] = parts;
+  const name = (namePart ?? "").replace(/"/g, "").toLowerCase();
+  const attributes = attributeParts.reduce((acc, part) => {
+    const [key, value2 = ""] = part.split("=");
+    return {
+      ...acc,
+      [key]: value2
+    };
+  }, {});
+  return {
+    attributes,
+    name
+  };
+};
+var parseCacheStatusValues = (cacheStatusValues) => {
+  const cacheStatus = {
+    hit: false,
+    caches: {}
+  };
+  for (const value of cacheStatusValues.split(",")) {
+    const { attributes, name } = parseCacheStatusValue(value);
+    if (name === CACHE_EDGE) {
+      const hit = attributes.hit !== void 0;
+      cacheStatus.caches.edge = {
+        hit,
+        fresh: hit && attributes.fwd !== "stale"
+      };
+      cacheStatus.hit = cacheStatus.hit || hit;
+      continue;
+    }
+    if (name === CACHE_DURABLE) {
+      let ttl = 0;
+      if (attributes.ttl !== void 0) {
+        const parsedTTL = Number.parseInt(attributes.ttl);
+        if (!Number.isNaN(parsedTTL)) {
+          ttl = parsedTTL;
+        }
+      }
+      const hit = attributes.hit !== void 0;
+      cacheStatus.caches.durable = {
+        hit,
+        fresh: hit && attributes.fwd !== "stale",
+        stored: attributes.stored === "true",
+        ttl
+      };
+      cacheStatus.hit = cacheStatus.hit || hit;
+      continue;
+    }
+  }
+  if (Object.keys(cacheStatus.caches).length === 0) {
+    return null;
+  }
+  return cacheStatus;
+};
+var getCacheStatus = (input) => {
+  if (typeof input === "string") {
+    return parseCacheStatusValues(input);
+  }
+  if (input instanceof Headers) {
+    return parseCacheStatusValues(input.get(CacheStatus) ?? "");
+  }
+  if (input instanceof Response) {
+    return parseCacheStatusValues(input.headers.get(CacheStatus) ?? "");
+  }
+  throw new TypeError("`getCacheStatus` expects a string, a `Headers` object or a `Response` object.");
+};
+
+// src/fetchwithcache.ts
+var requestInitOptions = [
+  "method",
+  "keepalive",
+  "headers",
+  "body",
+  "redirect",
+  "integrity",
+  "signal",
+  "credentials",
+  "mode",
+  "referrer",
+  "referrerPolicy",
+  "window",
+  "dispatcher",
+  "duplex"
+];
+var isRequestInit = (input) => {
+  if (typeof input !== "object") {
+    return false;
+  }
+  for (const property of requestInitOptions) {
+    if (property in input) {
+      return true;
+    }
+  }
+  return false;
+};
+var fetchWithCache = async (request, optionsOrCacheSettings, cacheOptionsParam) => {
+  let cacheOptions;
+  let requestInit;
+  if (isRequestInit(optionsOrCacheSettings)) {
+    cacheOptions = cacheOptionsParam || {};
+    requestInit = optionsOrCacheSettings;
+  } else {
+    cacheOptions = optionsOrCacheSettings || {};
+    requestInit = {};
+  }
+  let method;
+  if (request instanceof Request) {
+    method = request.method;
+  } else {
+    method = requestInit?.method;
+  }
+  if (method && method?.toLowerCase() !== "get") {
+    throw new TypeError("`fetchWithCache` only supports GET requests.");
+  }
+  let cache;
+  const { cache: cacheParam, onCachePut, ...cacheSettings } = cacheOptions;
+  if (cacheParam) {
+    if (typeof cacheParam === "string") {
+      cache = await caches.open(cacheParam);
+    } else if (cacheParam instanceof Cache) {
+      cache = cacheParam;
+    } else {
+      throw new TypeError("`cache` must be a string representing the cache name or an instance of `Cache`.");
+    }
+  } else {
+    cache = await caches.open("");
+  }
+  const cached = await cache.match(request);
+  if (cached) {
+    return cached;
+  }
+  const fresh = await fetch(request, requestInit);
+  const responseForCache = setCacheHeaders(fresh.clone(), cacheSettings);
+  const cachePut = cache.put(request, responseForCache);
+  if (onCachePut) {
+    await onCachePut(cachePut);
+  } else {
+    await cachePut;
+  }
+  return fresh;
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  fetchWithCache,
+  getCacheStatus,
+  setCacheHeaders
+});

package/dist/main.d.cts

@@ -1,2 +1,156 @@
+import { N as NetlifyCache } from './cache-854474ad.js';
 
-export { }
+interface CacheSettings {
+    /**
+     * Persist the response in the durable cache, shared across all CDN nodes.
+     *
+     * {@link} https://ntl.fyi/durable
+     */
+    durable?: boolean;
+    /**
+     * Override the default behavior of revalidating cached responses with new
+     * deploys. You must provide one or more values that will be registered as
+     * cache tags for you to purge the responses on-demand.
+     *
+     * {@link} https://ntl.fyi/cache-id
+     */
+    overrideDeployRevalidation?: string | string[];
+    /**
+     * Provide one or more cache tags to associate with the response. You can use
+     * these tags to revalidate responses on-demand, making sure you target the
+     * specific responses you want based on your application logic.
+     *
+     * {@link} https://ntl.fyi/cache-tags
+     */
+    tags?: string[];
+    /**
+     * Define the period of time (in seconds) during which the response can be
+     * considered fresh. After this period, the response will revalidated in
+     * the background if used with the `stale-while-revalidate` directive,
+     * otherwise the response will be discarded.
+     *
+     * {@link} https://ntl.fyi/cache-ttl
+     */
+    ttl?: number;
+    /**
+     * Define the period of time (in seconds) after the response is considered
+     * stale (set by the `ttl` property) and during which it can still
+     * be served, while starting a revalidation in the background.
+     *
+     * {@link} https://ntl.fyi/cache-swr
+     */
+    swr?: boolean | number;
+    /**
+     * Defines how cache key variations are created for the response, giving you
+     * fine-grained control over which parts of a request are taken into
+     * consideration for matching cache objects.
+     *
+     * {@link} https://ntl.fyi/cache-vary
+     */
+    vary?: VaryOptions;
+}
+interface VaryOptions {
+    /**
+     * Define cache key variations based on a subset of cookie keys.
+     */
+    cookie?: string | string[];
+    /**
+     * Define cache key variations based on the geographical origin of the request.
+     */
+    country?: string | (string | string[])[];
+    /**
+     * Define cache key variations based on your custom request headers and most
+     * standard request headers.
+     */
+    header?: string | string[];
+    /**
+     * Define cache key variations for one or more individual languages or custom
+     * language groups.
+     */
+    language?: string | (string | string[])[];
+    /**
+     * Define cache key variations based on a specific subset of query parameters
+     * included with a request or all request query parameters.
+     */
+    query?: boolean | string | string[];
+}
+
+declare const setCacheHeaders: (response: Response, cacheSettings: CacheSettings) => Response;
+
+interface CacheStatus {
+    /**
+     * Whether the response was served from a Netlify cache.
+     */
+    hit: boolean;
+    /**
+     * Granular information about how the different Netlify caches have
+     * contributed to the delivery of the response.
+     */
+    caches: {
+        /**
+         * How the response has interacted with the durable cache.
+         *
+         * {@link} https://ntl.fyi/durable
+         */
+        durable?: {
+            hit: boolean;
+            fresh: boolean;
+            stored?: boolean;
+            ttl: number;
+        };
+        /**
+         * How the response has interacted with the edge cache.
+         *
+         * {@link} https://ntl.fyi/edge-cache
+         */
+        edge?: {
+            hit: boolean;
+            fresh: boolean;
+        };
+    };
+}
+type ParseCacheStatus = {
+    (header: string): CacheStatus | null;
+    (headers: Headers): CacheStatus | null;
+    (response: Response): CacheStatus | null;
+};
+/**
+ * Retrieves information about how a response has interacted with Netlify's
+ * global caching infrastructure, including whether the response has been
+ * served by a cache and whether it's fresh or stale.
+ */
+declare const getCacheStatus: ParseCacheStatus;
+
+type CacheOptions = CacheSettings & {
+    /**
+     * A `Cache` instance or the name of the cache that should be used. If not
+     * set, a cache without a name (i.e. `""`) will be used.
+     */
+    cache?: NetlifyCache | string;
+    /**
+     * When `fetchWithCache` fetches a new response and adds it to the cache, the
+     * `Promise` it returns waits for both the network call to finish and for the
+     * response to be cached. Customize this behavior by setting a `onCachePut`
+     * handler that receives the cache write `Promise`, giving you the option to
+     * handle it as you like. This lets you remove the cache write from the "hot
+     * path" and run it in the background.
+     */
+    onCachePut?: (cachePut: Promise<void>) => void | Promise<void>;
+};
+type FetchWithCache = {
+    (request: string | URL | Request, init?: RequestInit): Promise<Response>;
+    (request: string | URL | Request, cacheSettings?: CacheOptions): Promise<Response>;
+    (request: string | URL | Request, init: RequestInit, cacheSettings?: CacheOptions): Promise<Response>;
+};
+/**
+ * Serves a resource from the Cache API if available, otherwise it's fetched
+ * from the network and added to the cache. It's a drop-in replacement for
+ * `fetch`, supporting the same arguments and return value. A third (optional)
+ * argument makes it possible to set the caching configuration of the response
+ * as it's added to the cache, overridding any cache control settings it sets.
+ * It returns a `Promise` that resolves with the resulting `Response` object,
+ * whether it comes from the cache or from the network.
+ */
+declare const fetchWithCache: FetchWithCache;
+
+export { fetchWithCache, getCacheStatus, setCacheHeaders };

package/dist/main.d.ts

@@ -1,2 +1,156 @@
+import { N as NetlifyCache } from './cache-854474ad.js';
 
-export { }
+interface CacheSettings {
+    /**
+     * Persist the response in the durable cache, shared across all CDN nodes.
+     *
+     * {@link} https://ntl.fyi/durable
+     */
+    durable?: boolean;
+    /**
+     * Override the default behavior of revalidating cached responses with new
+     * deploys. You must provide one or more values that will be registered as
+     * cache tags for you to purge the responses on-demand.
+     *
+     * {@link} https://ntl.fyi/cache-id
+     */
+    overrideDeployRevalidation?: string | string[];
+    /**
+     * Provide one or more cache tags to associate with the response. You can use
+     * these tags to revalidate responses on-demand, making sure you target the
+     * specific responses you want based on your application logic.
+     *
+     * {@link} https://ntl.fyi/cache-tags
+     */
+    tags?: string[];
+    /**
+     * Define the period of time (in seconds) during which the response can be
+     * considered fresh. After this period, the response will revalidated in
+     * the background if used with the `stale-while-revalidate` directive,
+     * otherwise the response will be discarded.
+     *
+     * {@link} https://ntl.fyi/cache-ttl
+     */
+    ttl?: number;
+    /**
+     * Define the period of time (in seconds) after the response is considered
+     * stale (set by the `ttl` property) and during which it can still
+     * be served, while starting a revalidation in the background.
+     *
+     * {@link} https://ntl.fyi/cache-swr
+     */
+    swr?: boolean | number;
+    /**
+     * Defines how cache key variations are created for the response, giving you
+     * fine-grained control over which parts of a request are taken into
+     * consideration for matching cache objects.
+     *
+     * {@link} https://ntl.fyi/cache-vary
+     */
+    vary?: VaryOptions;
+}
+interface VaryOptions {
+    /**
+     * Define cache key variations based on a subset of cookie keys.
+     */
+    cookie?: string | string[];
+    /**
+     * Define cache key variations based on the geographical origin of the request.
+     */
+    country?: string | (string | string[])[];
+    /**
+     * Define cache key variations based on your custom request headers and most
+     * standard request headers.
+     */
+    header?: string | string[];
+    /**
+     * Define cache key variations for one or more individual languages or custom
+     * language groups.
+     */
+    language?: string | (string | string[])[];
+    /**
+     * Define cache key variations based on a specific subset of query parameters
+     * included with a request or all request query parameters.
+     */
+    query?: boolean | string | string[];
+}
+
+declare const setCacheHeaders: (response: Response, cacheSettings: CacheSettings) => Response;
+
+interface CacheStatus {
+    /**
+     * Whether the response was served from a Netlify cache.
+     */
+    hit: boolean;
+    /**
+     * Granular information about how the different Netlify caches have
+     * contributed to the delivery of the response.
+     */
+    caches: {
+        /**
+         * How the response has interacted with the durable cache.
+         *
+         * {@link} https://ntl.fyi/durable
+         */
+        durable?: {
+            hit: boolean;
+            fresh: boolean;
+            stored?: boolean;
+            ttl: number;
+        };
+        /**
+         * How the response has interacted with the edge cache.
+         *
+         * {@link} https://ntl.fyi/edge-cache
+         */
+        edge?: {
+            hit: boolean;
+            fresh: boolean;
+        };
+    };
+}
+type ParseCacheStatus = {
+    (header: string): CacheStatus | null;
+    (headers: Headers): CacheStatus | null;
+    (response: Response): CacheStatus | null;
+};
+/**
+ * Retrieves information about how a response has interacted with Netlify's
+ * global caching infrastructure, including whether the response has been
+ * served by a cache and whether it's fresh or stale.
+ */
+declare const getCacheStatus: ParseCacheStatus;
+
+type CacheOptions = CacheSettings & {
+    /**
+     * A `Cache` instance or the name of the cache that should be used. If not
+     * set, a cache without a name (i.e. `""`) will be used.
+     */
+    cache?: NetlifyCache | string;
+    /**
+     * When `fetchWithCache` fetches a new response and adds it to the cache, the
+     * `Promise` it returns waits for both the network call to finish and for the
+     * response to be cached. Customize this behavior by setting a `onCachePut`
+     * handler that receives the cache write `Promise`, giving you the option to
+     * handle it as you like. This lets you remove the cache write from the "hot
+     * path" and run it in the background.
+     */
+    onCachePut?: (cachePut: Promise<void>) => void | Promise<void>;
+};
+type FetchWithCache = {
+    (request: string | URL | Request, init?: RequestInit): Promise<Response>;
+    (request: string | URL | Request, cacheSettings?: CacheOptions): Promise<Response>;
+    (request: string | URL | Request, init: RequestInit, cacheSettings?: CacheOptions): Promise<Response>;
+};
+/**
+ * Serves a resource from the Cache API if available, otherwise it's fetched
+ * from the network and added to the cache. It's a drop-in replacement for
+ * `fetch`, supporting the same arguments and return value. A third (optional)
+ * argument makes it possible to set the caching configuration of the response
+ * as it's added to the cache, overridding any cache control settings it sets.
+ * It returns a `Promise` that resolves with the resulting `Response` object,
+ * whether it comes from the cache or from the network.
+ */
+declare const fetchWithCache: FetchWithCache;
+
+export { fetchWithCache, getCacheStatus, setCacheHeaders };