wip

Author: Guy Bedford

types/cache-override.d.ts

@@ -1,4 +1,51 @@
 declare module 'fastly:cache-override' {
+  interface ICacheOverride {
+    /**
+     * The cache key for this cache entry
+     */
+    cacheKey?: string | undefined;
+    /**
+     * Override the caching behavior of this request/response to use the given Time to Live (TTL), in seconds.
+     */
+    ttl?: number | undefined;
+    /**
+     * Override the caching behavior of this request/response to use the given `stale-while-revalidate` time,
+     * in seconds
+     */
+    swr?: number | undefined;
+    /**
+     * Override the caching behavior of this request/response to include the given surrogate key, provided as
+     * a header value.
+     *
+     * See the [Fastly surrogate keys guide](https://docs.fastly.com/en/guides/purging-api-cache-with-surrogate-keys)
+     * for details.
+     */
+    surrogateKeys?: Set<string>;
+    /**
+     * Override the caching behavior of this request/response to include the given surrogate keys, provided as
+     * a header value.
+     *
+     * See the [Fastly surrogate keys guide](https://docs.fastly.com/en/guides/purging-api-cache-with-surrogate-keys)
+     * for details.
+     */
+    surrogateKey?: string | undefined;
+    /**
+     * Override the caching behavior of this request/response to enable or disable PCI/HIPAA-compliant
+     * non-volatile caching.
+     *
+     * By default, this is false, which means the request may not be PCI/HIPAA-compliant. Set it to
+     * true to enable compliant caching.
+     *
+     * See the [Fastly PCI-Compliant Caching and Delivery documentation](https://docs.fastly.com/products/pci-compliant-caching-and-delivery)
+     * for details.
+     */
+    pci?: boolean;
+    /**
+     * Get or set the set of request headers for which the response may vary.
+     */
+    vary?: Set<string>;
+  }
+
   /**
    * Configures the caching behavior of a {@linkcode "globals".Response}.
    *
@@ -17,8 +64,6 @@ declare module 'fastly:cache-override' {
    *   "origins": [
    *     "https://http-me.glitch.me"
    *   ],
-   *   "src": {
-   *     "deps": "{\n  \"@fastly/js-compute\": \"^0.7.0\"\n}",
    *     "main": "/// <reference types=\"@fastly/js-compute\" />\nimport { CacheOverride } from \"fastly:cache-override\";\n\n// In this example we override the cache for all the requests prefixed /static/ \n// to have a long TTL (Time To Live), and the home page to have a short TTL and \n// a long SWR (Stale While Revalidate).\nasync function app (event) {\n  const path = (new URL(event.request.url)).pathname;\n  let cacheOverride;\n  if (path == '/') {\n    cacheOverride = new CacheOverride('override', {ttl: 10, swr: 86_400});\n  } else if (path.startsWith('/static/')) {\n    cacheOverride = new CacheOverride('override', {ttl: 86_400});\n  } else {\n    cacheOverride = new CacheOverride('none')\n  }\n  return fetch(event.request.url, {\n    cacheOverride,\n    backend: 'origin_0'\n  });\n}\naddEventListener(\"fetch\", event => event.respondWith(app(event)));\n"
    *   },
    *   "requests": [
@@ -64,6 +109,7 @@ declare module 'fastly:cache-override' {
    * ```
    * </noscript>
    */
+
   class CacheOverride {
     /**
      * @param mode Sets the cache override mode for a request
@@ -73,41 +119,12 @@ declare module 'fastly:cache-override' {
      * - "pass": Do not cache the response to this request, regardless of the origin response’s headers.
      * - "override": Override particular cache control settings using a {@linkcode CacheOverride} object.
      *
-     * @param [init]
-     *
-     * @param {number} [init.ttl]
-     * Override the caching behavior of this request to use the given Time to Live (TTL), in seconds.
-     *
-     * @param {number} [init.swr]
-     * Override the caching behavior of this request to use the given `stale-while-revalidate` time,
-     * in seconds
-     *
-     * @param {string} [init.surrogateKey]
-     * Override the caching behavior of this request to include the given surrogate key, provided as
-     * a header value.
-     *
-     * See the [Fastly surrogate keys guide](https://docs.fastly.com/en/guides/purging-api-cache-with-surrogate-keys)
-     * for details.
-     *
-     * @param {boolean} [init.pci]
-     * Override the caching behavior of this request to enable or disable PCI/HIPAA-compliant
-     * non-volatile caching.
+     * @param [init] Init options for the cache override
      *
-     * By default, this is false, which means the request may not be PCI/HIPAA-compliant. Set it to
-     * true to enable compliant caching.
-     *
-     * See the [Fastly PCI-Compliant Caching and Delivery documentation](https://docs.fastly.com/products/pci-compliant-caching-and-delivery)
-     * for details.
      */
-    constructor(
-      mode: 'none' | 'pass' | 'override',
-      init?: {
-        ttl?: number;
-        swr?: number;
-        surrogateKey?: string;
-        pci?: boolean;
-      },
-    );
+    constructor(mode: 'none' | 'pass' | 'override', init?: ICacheOverride);
+
+    cacheKey?: string;
 
     /**
      * Sets the cache override mode for a request
@@ -121,20 +138,28 @@ declare module 'fastly:cache-override' {
     /**
      * Override the caching behavior of this request to use the given Time to Live (TTL), in seconds.
      */
-    public ttl?: number;
+    public ttl: number | undefined;
     /**
      * Override the caching behavior of this request to use the given `stale-while-revalidate` time,
      * in seconds
      */
-    public swr?: number;
+    public swr: number | undefined;
     /**
      * Override the caching behavior of this request to include the given surrogate key, provided as
      * a header value.
      *
      * See the [Fastly surrogate keys guide](https://docs.fastly.com/en/guides/purging-api-cache-with-surrogate-keys)
      * for details.
      */
-    public surrogateKey?: string;
+    public surrogateKey: string | undefined;
+    /**
+     * Override the caching behavior of this request to include the given surrogate key, provided as
+     * a header value.
+     *
+     * See the [Fastly surrogate keys guide](https://docs.fastly.com/en/guides/purging-api-cache-with-surrogate-keys)
+     * for details.
+     */
+    public surrogateKeys: Set<string> | undefined;
     /**
      * Override the caching behavior of this request to enable or disable PCI/HIPAA-compliant
      * non-volatile caching.
@@ -145,6 +170,10 @@ declare module 'fastly:cache-override' {
      * See the [Fastly PCI-Compliant Caching and Delivery documentation](https://docs.fastly.com/products/pci-compliant-caching-and-delivery)
      * for details.
      */
-    public pci?: boolean;
+    public pci: boolean | undefined;
+    /**
+     * Get or set the set of request headers for which the response may vary.
+     */
+    public vary: Set<string> | undefined;
   }
 }

types/globals.d.ts

@@ -1225,6 +1225,25 @@ declare interface RequestInit {
   /** The Fastly configured backend name or instance the request should be sent to. */
   backend?: string | import('fastly:backend').Backend;
   cacheOverride?: import('fastly:cache-override').CacheOverride;
+  /**
+   * Provide a callback to modify the request before sending to the backend.
+   */
+  beforeSend?: (req: Request) => Promise<void>;
+  /**
+   * Provide a callback to modify the response before storing in the cache.
+   *
+   * May return another response entirely.
+   *
+   * Alternatively a void return indicates that the request will not be cached.
+   */
+  beforeCache?: (res: Response) => Promise<Response | undefined>;
+  /**
+   * Boolean indicating if the request is cacheable under standard cache rules.
+   */
+  isCacheable: boolean;
+  /**
+   * @deprecated use cacheOverride.cacheKey instead
+   */
   cacheKey?: string;
   fastly?: {
     decompressGzip?: boolean;
@@ -1272,12 +1291,24 @@ interface Request extends Body {
   clone(): Request;
 
   /**
-   * The request backend, null for the downstream request itself
+   * The request backend, undefined for the downstream request itself
+   */
+  readonly backend: import('fastly:backend').Backend | undefined;
+
+  /**
+   * The cache override options for this request. May be modified up until the point that
+   * the request is stored in the cache.
+   */
+  readonly cacheOverride: import('fastly:cache-override').CacheOverride;
+  /**
+   * @deprecated use {@link cacheOverride} directly.
    */
-  backend: import('fastly:backend').Backend | undefined;
   setCacheOverride(
     override: import('fastly:cache-override').CacheOverride,
   ): void;
+  /**
+   * @deprecated set {@link cacheOverride.cacheKey} instead.
+   */
   setCacheKey(key: string): void;
   setManualFramingHeaders(manual: boolean): void;
 }
@@ -1311,10 +1342,18 @@ declare interface ResponseInit {
  * @group Fetch API
  */
 interface Response extends Body {
+  /**
+   * The response headers.
+   *
+   * May be modified even for upstream responses prior to storage in the cache.
+   */
   readonly headers: Headers;
   readonly ok: boolean;
   // readonly redirected: boolean;
-  readonly status: number;
+  /**
+   * The response status. May be modified prior to storage in the cache.
+   */
+  status: number;
   readonly statusText: string;
   // readonly type: ResponseType;
   readonly url: string;
@@ -1334,10 +1373,24 @@ interface Response extends Body {
   readonly port: number | undefined;
   // clone(): Response;
   setManualFramingHeaders(manual: boolean): void;
+  /**
+   * The cache override options for this response.
+   *
+   * May be modified prior to storage in the cache.
+   */
+  readonly cacheOverride: import('fastly:cache-override').CacheOverride;
+  /**
+   * Set a custom transform stream for the origin on cache miss.
+   * Can only be called when the onAfterSend hook is triggered, and before the promise has resolved.
+   *
+   * @param transformStream A transform stream to transform the backend response before storing
+   *        in the cache and returning the response to the client.
+   */
+  setCacheTransform(transformStream: TransformStream): void;
   /**
    * The response backend, if an upstream response
    */
-  backend: import('fastly:backend').Backend | undefined;
+  readonly backend: import('fastly:backend').Backend | undefined;
 }
 
 /**