@vercel/functions 2.2.2 → 2.2.3

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @vercel/functions
 
+## 2.2.3
+
+### Patch Changes
+
+- Update runtime cache api to support usage during builds ([#13426](https://github.com/vercel/vercel/pull/13426))
+
 ## 2.2.2
 
 ### Patch Changes

package/cache/build-client.d.ts

@@ -0,0 +1,18 @@
+export declare class BuildCache {
+    private readonly endpoint;
+    private readonly headers;
+    private readonly onError?;
+    constructor({ endpoint, headers, onError, }: {
+        endpoint: string;
+        headers: Record<string, string>;
+        onError?: (error: Error) => void;
+    });
+    get: (key: string) => Promise<unknown>;
+    set: (key: string, value: unknown, options?: {
+        name?: string;
+        ttl?: number;
+        tags?: string[];
+    }) => Promise<void>;
+    delete: (key: string) => Promise<void>;
+    expireTag: (tag: string | string[]) => Promise<void>;
+}

package/cache/build-client.js

@@ -0,0 +1,121 @@
+"use strict";
+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))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var build_client_exports = {};
+__export(build_client_exports, {
+  BuildCache: () => BuildCache
+});
+module.exports = __toCommonJS(build_client_exports);
+var import_index = require("./index");
+class BuildCache {
+  constructor({
+    endpoint,
+    headers,
+    onError
+  }) {
+    this.get = async (key) => {
+      try {
+        const res = await fetch(`${this.endpoint}${key}`, {
+          headers: this.headers,
+          method: "GET"
+        });
+        if (res.status === 404) {
+          return null;
+        }
+        if (res.status === 200) {
+          const cacheState = res.headers.get(
+            import_index.HEADERS_VERCEL_CACHE_STATE
+          );
+          if (cacheState !== import_index.PkgCacheState.Fresh) {
+            res.body?.cancel?.();
+            return null;
+          }
+          return await res.json();
+        } else {
+          throw new Error(`Failed to get cache: ${res.statusText}`);
+        }
+      } catch (error) {
+        this.onError?.(error);
+        return null;
+      }
+    };
+    this.set = async (key, value, options) => {
+      try {
+        const optionalHeaders = {};
+        if (options?.ttl) {
+          optionalHeaders[import_index.HEADERS_VERCEL_REVALIDATE] = options.ttl.toString();
+        }
+        if (options?.tags && options.tags.length > 0) {
+          optionalHeaders[import_index.HEADERS_VERCEL_CACHE_TAGS] = options.tags.join(",");
+        }
+        if (options?.name) {
+          optionalHeaders[import_index.HEADERS_VERCEL_CACHE_ITEM_NAME] = options.name;
+        }
+        const res = await fetch(`${this.endpoint}${key}`, {
+          method: "POST",
+          headers: {
+            ...this.headers,
+            ...optionalHeaders
+          },
+          body: JSON.stringify(value)
+        });
+        if (res.status !== 200) {
+          throw new Error(`Failed to set cache: ${res.status} ${res.statusText}`);
+        }
+      } catch (error) {
+        this.onError?.(error);
+      }
+    };
+    this.delete = async (key) => {
+      try {
+        const res = await fetch(`${this.endpoint}${key}`, {
+          method: "DELETE",
+          headers: this.headers
+        });
+        if (res.status !== 200) {
+          throw new Error(`Failed to delete cache: ${res.statusText}`);
+        }
+      } catch (error) {
+        this.onError?.(error);
+      }
+    };
+    this.expireTag = async (tag) => {
+      try {
+        if (Array.isArray(tag)) {
+          tag = tag.join(",");
+        }
+        const res = await fetch(`${this.endpoint}revalidate?tags=${tag}`, {
+          method: "POST",
+          headers: this.headers
+        });
+        if (res.status !== 200) {
+          throw new Error(`Failed to revalidate tag: ${res.statusText}`);
+        }
+      } catch (error) {
+        this.onError?.(error);
+      }
+    };
+    this.endpoint = endpoint;
+    this.headers = headers;
+    this.onError = onError;
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  BuildCache
+});

package/cache/in-memory-cache.d.ts

@@ -1,9 +1,7 @@
 import { RuntimeCache } from './types';
 export declare class InMemoryCache implements RuntimeCache {
     private cache;
-    get(key: string, options?: {
-        tags?: string[];
-    }): Promise<unknown | null>;
+    get(key: string): Promise<unknown | null>;
     set(key: string, value: unknown, options?: {
         ttl?: number;
         tags?: string[];

package/cache/in-memory-cache.js

@@ -25,18 +25,13 @@ class InMemoryCache {
   constructor() {
     this.cache = {};
   }
-  async get(key, options) {
+  async get(key) {
     const entry = this.cache[key];
     if (entry) {
       if (entry.ttl && entry.lastModified + entry.ttl * 1e3 < Date.now()) {
         await this.delete(key);
         return null;
       }
-      if (options?.tags) {
-        for (const tag of options.tags) {
-          entry.tags.add(tag);
-        }
-      }
       return entry.value;
     }
     return null;

package/cache/index.d.ts

@@ -14,3 +14,14 @@ import { CacheOptions, RuntimeCache } from './types';
  * @throws {Error} If no cache is available in the context and `InMemoryCache` cannot be created.
  */
 export declare const getCache: (cacheOptions?: CacheOptions) => RuntimeCache;
+export declare enum PkgCacheState {
+    Fresh = "fresh",
+    Stale = "stale",
+    Expired = "expired",
+    NotFound = "notFound",
+    Error = "error"
+}
+export declare const HEADERS_VERCEL_CACHE_STATE = "x-vercel-cache-state";
+export declare const HEADERS_VERCEL_REVALIDATE = "x-vercel-revalidate";
+export declare const HEADERS_VERCEL_CACHE_TAGS = "x-vercel-cache-tags";
+export declare const HEADERS_VERCEL_CACHE_ITEM_NAME = "x-vercel-cache-item-name";

package/cache/index.js

@@ -18,11 +18,17 @@ var __copyProps = (to, from, except, desc) => {
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var cache_exports = {};
 __export(cache_exports, {
+  HEADERS_VERCEL_CACHE_ITEM_NAME: () => HEADERS_VERCEL_CACHE_ITEM_NAME,
+  HEADERS_VERCEL_CACHE_STATE: () => HEADERS_VERCEL_CACHE_STATE,
+  HEADERS_VERCEL_CACHE_TAGS: () => HEADERS_VERCEL_CACHE_TAGS,
+  HEADERS_VERCEL_REVALIDATE: () => HEADERS_VERCEL_REVALIDATE,
+  PkgCacheState: () => PkgCacheState,
   getCache: () => getCache
 });
 module.exports = __toCommonJS(cache_exports);
 var import_get_context = require("../get-context");
 var import_in_memory_cache = require("./in-memory-cache");
+var import_build_client = require("./build-client");
 const defaultKeyHashFunction = (key) => {
   let hash = 5381;
   for (let i = 0; i < key.length; i++) {
@@ -32,31 +38,37 @@ const defaultKeyHashFunction = (key) => {
 };
 const defaultNamespaceSeparator = "$";
 let inMemoryCacheInstance = null;
+let buildCacheInstance = null;
 const getCache = (cacheOptions) => {
   const resolveCache = () => {
-    const ctxCache = (0, import_get_context.getContext)().cache;
-    if (ctxCache)
-      return ctxCache;
-    if (!inMemoryCacheInstance) {
-      inMemoryCacheInstance = new import_in_memory_cache.InMemoryCache();
-      console.warn(
-        "Runtime Cache unavailable in this environment. Falling back to in-memory cache."
+    let cache;
+    if ((0, import_get_context.getContext)().cache) {
+      cache = (0, import_get_context.getContext)().cache;
+    } else {
+      cache = getCacheImplementation(
+        process.env.SUSPENSE_CACHE_DEBUG === "true"
       );
     }
-    return inMemoryCacheInstance;
+    return cache;
   };
+  return wrapWithKeyTransformation(
+    resolveCache,
+    createKeyTransformer(cacheOptions)
+  );
+};
+function createKeyTransformer(cacheOptions) {
   const hashFunction = cacheOptions?.keyHashFunction || defaultKeyHashFunction;
-  const makeKey = (key) => {
-    let prefix = "";
-    if (cacheOptions?.namespace) {
-      const namespaceSeparator = cacheOptions.namespaceSeparator || defaultNamespaceSeparator;
-      prefix = `${cacheOptions.namespace}${namespaceSeparator}`;
-    }
-    return `${prefix}${hashFunction(key)}`;
+  return (key) => {
+    if (!cacheOptions?.namespace)
+      return hashFunction(key);
+    const separator = cacheOptions.namespaceSeparator || defaultNamespaceSeparator;
+    return `${cacheOptions.namespace}${separator}${hashFunction(key)}`;
   };
+}
+function wrapWithKeyTransformation(resolveCache, makeKey) {
   return {
-    get: (key, options) => {
-      return resolveCache().get(makeKey(key), options);
+    get: (key) => {
+      return resolveCache().get(makeKey(key));
     },
     set: (key, value, options) => {
       return resolveCache().set(makeKey(key), value, options);
@@ -68,8 +80,62 @@ const getCache = (cacheOptions) => {
       return resolveCache().expireTag(tag);
     }
   };
-};
+}
+function getCacheImplementation(debug) {
+  if (!inMemoryCacheInstance) {
+    inMemoryCacheInstance = new import_in_memory_cache.InMemoryCache();
+  }
+  if (process.env.RUNTIME_CACHE_DISABLE_BUILD_CACHE === "true") {
+    debug && console.log("Using InMemoryCache as build cache is disabled");
+    return inMemoryCacheInstance;
+  }
+  const { RUNTIME_CACHE_ENDPOINT, RUNTIME_CACHE_HEADERS } = process.env;
+  if (debug) {
+    console.log("Runtime cache environment variables:", {
+      RUNTIME_CACHE_ENDPOINT,
+      RUNTIME_CACHE_HEADERS
+    });
+  }
+  if (!RUNTIME_CACHE_ENDPOINT || !RUNTIME_CACHE_HEADERS) {
+    console.warn(
+      "Runtime Cache unavailable in this environment. Falling back to in-memory cache."
+    );
+    return inMemoryCacheInstance;
+  }
+  if (!buildCacheInstance) {
+    let parsedHeaders = {};
+    try {
+      parsedHeaders = JSON.parse(RUNTIME_CACHE_HEADERS);
+    } catch (e) {
+      console.error("Failed to parse RUNTIME_CACHE_HEADERS:", e);
+      return inMemoryCacheInstance;
+    }
+    buildCacheInstance = new import_build_client.BuildCache({
+      endpoint: RUNTIME_CACHE_ENDPOINT,
+      headers: parsedHeaders,
+      onError: (error) => console.error(error)
+    });
+  }
+  return buildCacheInstance;
+}
+var PkgCacheState = /* @__PURE__ */ ((PkgCacheState2) => {
+  PkgCacheState2["Fresh"] = "fresh";
+  PkgCacheState2["Stale"] = "stale";
+  PkgCacheState2["Expired"] = "expired";
+  PkgCacheState2["NotFound"] = "notFound";
+  PkgCacheState2["Error"] = "error";
+  return PkgCacheState2;
+})(PkgCacheState || {});
+const HEADERS_VERCEL_CACHE_STATE = "x-vercel-cache-state";
+const HEADERS_VERCEL_REVALIDATE = "x-vercel-revalidate";
+const HEADERS_VERCEL_CACHE_TAGS = "x-vercel-cache-tags";
+const HEADERS_VERCEL_CACHE_ITEM_NAME = "x-vercel-cache-item-name";
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  HEADERS_VERCEL_CACHE_ITEM_NAME,
+  HEADERS_VERCEL_CACHE_STATE,
+  HEADERS_VERCEL_CACHE_TAGS,
+  HEADERS_VERCEL_REVALIDATE,
+  PkgCacheState,
   getCache
 });

package/cache/types.d.ts

@@ -13,13 +13,9 @@ export interface RuntimeCache {
      * Retrieves a value from the cache.
      *
      * @param {string} key - The key of the value to retrieve.
-     * @param {Object} [options] - Optional settings for the cache entry.
-     * @param {string[]} [options.tags] - Optional tags to associate wit the cache entry.
      * @returns {Promise<unknown | null>} A promise that resolves to the value, or null if not found.
      */
-    get: (key: string, options?: {
-        tags?: string[];
-    }) => Promise<unknown | null>;
+    get: (key: string) => Promise<unknown | null>;
     /**
      * Sets a value in the cache.
      *

package/docs/interfaces/index.RuntimeCache.md

@@ -67,27 +67,25 @@ A promise that resolves when the cache entries expiration request is received.
 
 #### Defined in
 
-[packages/functions/src/cache/types.ts:46](https://github.com/vercel/vercel/blob/main/packages/functions/src/cache/types.ts#L46)
+[packages/functions/src/cache/types.ts:44](https://github.com/vercel/vercel/blob/main/packages/functions/src/cache/types.ts#L44)
 
 ---
 
 ### get
 
-• **get**: (`key`: `string`, `options?`: { `tags?`: `string`[] }) => [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`unknown`\>
+• **get**: (`key`: `string`) => [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`unknown`\>
 
 #### Type declaration
 
-▸ (`key`, `options?`): [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`unknown`\>
+▸ (`key`): [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`unknown`\>
 
 Retrieves a value from the cache.
 
 ##### Parameters
 
-| Name            | Type       | Description                                     |
-| :-------------- | :--------- | :---------------------------------------------- |
-| `key`           | `string`   | The key of the value to retrieve.               |
-| `options?`      | `Object`   | Optional settings for the cache entry.          |
-| `options.tags?` | `string`[] | Optional tags to associate wit the cache entry. |
+| Name  | Type     | Description                       |
+| :---- | :------- | :-------------------------------- |
+| `key` | `string` | The key of the value to retrieve. |
 
 ##### Returns
 
@@ -97,7 +95,7 @@ A promise that resolves to the value, or null if not found.
 
 #### Defined in
 
-[packages/functions/src/cache/types.ts:21](https://github.com/vercel/vercel/blob/main/packages/functions/src/cache/types.ts#L21)
+[packages/functions/src/cache/types.ts:19](https://github.com/vercel/vercel/blob/main/packages/functions/src/cache/types.ts#L19)
 
 ---
 
@@ -130,4 +128,4 @@ A promise that resolves when the value is set.
 
 #### Defined in
 
-[packages/functions/src/cache/types.ts:34](https://github.com/vercel/vercel/blob/main/packages/functions/src/cache/types.ts#L34)
+[packages/functions/src/cache/types.ts:32](https://github.com/vercel/vercel/blob/main/packages/functions/src/cache/types.ts#L32)

package/docs/modules/index.md

@@ -99,7 +99,7 @@ An instance of the Vercel Runtime Cache.
 
 #### Defined in
 
-[packages/functions/src/cache/index.ts:32](https://github.com/vercel/vercel/blob/main/packages/functions/src/cache/index.ts#L32)
+[packages/functions/src/cache/index.ts:33](https://github.com/vercel/vercel/blob/main/packages/functions/src/cache/index.ts#L33)
 
 ---
 

package/package.json

@@ -26,7 +26,7 @@
       "require": "./middleware.js"
     }
   },
-  "version": "2.2.2",
+  "version": "2.2.3",
   "repository": {
     "directory": "packages/functions",
     "type": "git",