@vercel/functions 2.0.0 → 2.0.1

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @vercel/functions
 
+## 2.0.1
+
+### Patch Changes
+
+- Add Vercel Function Cache api ([#13221](https://github.com/vercel/vercel/pull/13221))
+
 ## 2.0.0
 
 ### Major Changes

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

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

package/cache/in-memory-cache.js

@@ -0,0 +1,70 @@
+"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 in_memory_cache_exports = {};
+__export(in_memory_cache_exports, {
+  InMemoryCache: () => InMemoryCache
+});
+module.exports = __toCommonJS(in_memory_cache_exports);
+class InMemoryCache {
+  constructor() {
+    this.cache = {};
+  }
+  async get(key, options) {
+    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;
+  }
+  async set(key, value, options) {
+    this.cache[key] = {
+      value,
+      lastModified: Date.now(),
+      ttl: options?.ttl,
+      tags: new Set(options?.tags || [])
+    };
+  }
+  async delete(key) {
+    delete this.cache[key];
+  }
+  async expireTag(tag) {
+    const tags = Array.isArray(tag) ? tag : [tag];
+    for (const key in this.cache) {
+      if (Object.prototype.hasOwnProperty.call(this.cache, key)) {
+        const entry = this.cache[key];
+        if (tags.some((t) => entry.tags.has(t))) {
+          delete this.cache[key];
+        }
+      }
+    }
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  InMemoryCache
+});

package/cache/index.d.ts

@@ -0,0 +1,16 @@
+import { CacheOptions, FunctionCache } from './types';
+/**
+ * Retrieves the Vercel Function Cache.
+ *
+ * Keys are hashed to ensure they are unique and consistent. The hashing function can be overridden by providing a custom
+ * `keyHashFunction` in the `cacheOptions` parameter.
+ *
+ * To specify a namespace for the cache keys, you can pass a `namespace` option in the `cacheOptions` parameter. If
+ * a namespace is provided, the cache keys will be prefixed with the namespace followed by a separator (default is `$`). The
+ * namespaceSeparator can also be customized using the `namespaceSeparator` option.
+ *
+ * @param cacheOptions - Optional configuration for the cache.
+ * @returns An instance of the Vercel Function Cache.
+ * @throws {Error} If no cache is available in the context and `InMemoryCache` cannot be created.
+ */
+export declare const getFunctionCache: (cacheOptions?: CacheOptions) => FunctionCache;

package/cache/index.js

@@ -0,0 +1,68 @@
+"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 cache_exports = {};
+__export(cache_exports, {
+  getFunctionCache: () => getFunctionCache
+});
+module.exports = __toCommonJS(cache_exports);
+var import_get_context = require("../get-context");
+var import_in_memory_cache = require("./in-memory-cache");
+const defaultKeyHashFunction = (key) => {
+  let hash = 5381;
+  for (let i = 0; i < key.length; i++) {
+    hash = hash * 33 ^ key.charCodeAt(i);
+  }
+  return (hash >>> 0).toString(16);
+};
+const defaultNamespaceSeparator = "$";
+const getFunctionCache = (cacheOptions) => {
+  let cache;
+  if ((0, import_get_context.getContext)().cache) {
+    cache = (0, import_get_context.getContext)().cache;
+  } else {
+    cache = new import_in_memory_cache.InMemoryCache();
+  }
+  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 {
+    get: (key, options) => {
+      return cache.get(makeKey(key), options);
+    },
+    set: (key, value, options) => {
+      return cache.set(makeKey(key), value, options);
+    },
+    delete: (key) => {
+      return cache.delete(makeKey(key));
+    },
+    expireTag: (tag) => {
+      return cache.expireTag(tag);
+    }
+  };
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  getFunctionCache
+});

package/cache/types.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Interface representing the function cache.
+ */
+export interface FunctionCache {
+    /**
+     * Deletes a value from the cache.
+     *
+     * @param {string} key - The key of the value to delete.
+     * @returns {Promise<void>} A promise that resolves when the value is deleted.
+     */
+    delete: (key: string) => Promise<void>;
+    /**
+     * 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>;
+    /**
+     * Sets a value in the cache.
+     *
+     * @param {string} key - The key of the value to set.
+     * @param {unknown} value - The value to set.
+     * @param {Object} [options] - Optional settings for the cache entry.
+     * @param {string} [options.name] - Optional user-friendly name for the cache entry used for o11y.
+     * @param {string[]} [options.tags] - Optional tags to associate with the cache entry.
+     * @param {number} [options.ttl] - Optional time-to-live for the cache entry, in seconds.
+     * @returns {Promise<void>} A promise that resolves when the value is set.
+     */
+    set: (key: string, value: unknown, options?: {
+        name?: string;
+        tags?: string[];
+        ttl?: number;
+    }) => Promise<void>;
+    /**
+     * Expires cache entries by tag.
+     *
+     * @param {string | string[]} tag - The tag or tags of the cache entries to expire.
+     * @returns {Promise<void>} A promise that resolves when the cache entries expiration request is received.
+     */
+    expireTag: (tag: string | string[]) => Promise<void>;
+}
+/**
+ * Interface representing options for configuring the cache.
+ */
+export interface CacheOptions {
+    /**
+     * Optional custom hash function for generating keys.
+     *
+     * @param {string} key - The key to hash.
+     * @returns {string} The hashed key.
+     */
+    keyHashFunction?: (key: string) => string;
+    /**
+     * Optional namespace to prefix cache keys.
+     */
+    namespace?: string;
+    /**
+     * Optional separator string for the namespace.
+     */
+    namespaceSeparator?: string;
+}

package/cache/types.js

@@ -0,0 +1,16 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+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 types_exports = {};
+module.exports = __toCommonJS(types_exports);

package/docs/interfaces/index.FunctionCache.md

@@ -0,0 +1,133 @@
+# Interface: FunctionCache
+
+[index](../modules/index.md).FunctionCache
+
+Interface representing the function cache.
+
+## Table of contents
+
+### Properties
+
+- [delete](index.FunctionCache.md#delete)
+- [expireTag](index.FunctionCache.md#expiretag)
+- [get](index.FunctionCache.md#get)
+- [set](index.FunctionCache.md#set)
+
+## Properties
+
+### delete
+
+• **delete**: (`key`: `string`) => [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`void`\>
+
+#### Type declaration
+
+▸ (`key`): [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`void`\>
+
+Deletes a value from the cache.
+
+##### Parameters
+
+| Name  | Type     | Description                     |
+| :---- | :------- | :------------------------------ |
+| `key` | `string` | The key of the value to delete. |
+
+##### Returns
+
+[`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`void`\>
+
+A promise that resolves when the value is deleted.
+
+#### Defined in
+
+[packages/functions/src/cache/types.ts:11](https://github.com/vercel/vercel/blob/main/packages/functions/src/cache/types.ts#L11)
+
+---
+
+### expireTag
+
+• **expireTag**: (`tag`: `string` \| `string`[]) => [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`void`\>
+
+#### Type declaration
+
+▸ (`tag`): [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`void`\>
+
+Expires cache entries by tag.
+
+##### Parameters
+
+| Name  | Type                   | Description                                     |
+| :---- | :--------------------- | :---------------------------------------------- |
+| `tag` | `string` \| `string`[] | The tag or tags of the cache entries to expire. |
+
+##### Returns
+
+[`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`void`\>
+
+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)
+
+---
+
+### get
+
+• **get**: (`key`: `string`, `options?`: { `tags?`: `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`\>
+
+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. |
+
+##### Returns
+
+[`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`unknown`\>
+
+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)
+
+---
+
+### set
+
+• **set**: (`key`: `string`, `value`: `unknown`, `options?`: { `name?`: `string` ; `tags?`: `string`[] ; `ttl?`: `number` }) => [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`void`\>
+
+#### Type declaration
+
+▸ (`key`, `value`, `options?`): [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`void`\>
+
+Sets a value in the cache.
+
+##### Parameters
+
+| Name            | Type       | Description                                                    |
+| :-------------- | :--------- | :------------------------------------------------------------- |
+| `key`           | `string`   | The key of the value to set.                                   |
+| `value`         | `unknown`  | The value to set.                                              |
+| `options?`      | `Object`   | Optional settings for the cache entry.                         |
+| `options.name?` | `string`   | Optional user-friendly name for the cache entry used for o11y. |
+| `options.tags?` | `string`[] | Optional tags to associate with the cache entry.               |
+| `options.ttl?`  | `number`   | Optional time-to-live for the cache entry, in seconds.         |
+
+##### Returns
+
+[`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`void`\>
+
+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)

package/docs/modules/index.md

@@ -4,6 +4,7 @@
 
 ### Interfaces
 
+- [FunctionCache](../interfaces/index.FunctionCache.md)
 - [Geo](../interfaces/index.Geo.md)
 - [Request](../interfaces/index.Request.md)
 
@@ -11,6 +12,7 @@
 
 - [geolocation](index.md#geolocation)
 - [getEnv](index.md#getenv)
+- [getFunctionCache](index.md#getfunctioncache)
 - [ipAddress](index.md#ipaddress)
 - [next](index.md#next)
 - [rewrite](index.md#rewrite)
@@ -116,6 +118,41 @@ https://vercel.com/docs/projects/environment-variables/system-environment-variab
 
 ---
 
+### getFunctionCache
+
+▸ **getFunctionCache**(`cacheOptions?`): [`FunctionCache`](../interfaces/index.FunctionCache.md)
+
+Retrieves the Vercel Function Cache.
+
+Keys are hashed to ensure they are unique and consistent. The hashing function can be overridden by providing a custom
+`keyHashFunction` in the `cacheOptions` parameter.
+
+To specify a namespace for the cache keys, you can pass a `namespace` option in the `cacheOptions` parameter. If
+a namespace is provided, the cache keys will be prefixed with the namespace followed by a separator (default is `$`). The
+namespaceSeparator can also be customized using the `namespaceSeparator` option.
+
+**`Throws`**
+
+If no cache is available in the context and `InMemoryCache` cannot be created.
+
+#### Parameters
+
+| Name            | Type           | Description                           |
+| :-------------- | :------------- | :------------------------------------ |
+| `cacheOptions?` | `CacheOptions` | Optional configuration for the cache. |
+
+#### Returns
+
+[`FunctionCache`](../interfaces/index.FunctionCache.md)
+
+An instance of the Vercel Function Cache.
+
+#### Defined in
+
+[packages/functions/src/cache/index.ts:29](https://github.com/vercel/vercel/blob/main/packages/functions/src/cache/index.ts#L29)
+
+---
+
 ### ipAddress
 
 ▸ **ipAddress**(`input`): `string` \| `undefined`

package/get-context.d.ts

@@ -1,5 +1,7 @@
+import { FunctionCache } from './cache/types';
 type Context = {
     waitUntil?: (promise: Promise<unknown>) => void;
+    cache?: FunctionCache;
     headers?: Record<string, string>;
 };
 export declare const SYMBOL_FOR_REQ_CONTEXT: unique symbol;

package/index.d.ts

@@ -3,3 +3,5 @@ export { geolocation, ipAddress } from './headers';
 export { getEnv } from './get-env';
 export { waitUntil } from './wait-until';
 export { rewrite, next } from './middleware';
+export { getFunctionCache } from './cache';
+export type { FunctionCache } from './cache/types';

package/index.js

@@ -20,6 +20,7 @@ var src_exports = {};
 __export(src_exports, {
   geolocation: () => import_headers.geolocation,
   getEnv: () => import_get_env.getEnv,
+  getFunctionCache: () => import_cache.getFunctionCache,
   ipAddress: () => import_headers.ipAddress,
   next: () => import_middleware.next,
   rewrite: () => import_middleware.rewrite,
@@ -30,10 +31,12 @@ var import_headers = require("./headers");
 var import_get_env = require("./get-env");
 var import_wait_until = require("./wait-until");
 var import_middleware = require("./middleware");
+var import_cache = require("./cache");
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   geolocation,
   getEnv,
+  getFunctionCache,
   ipAddress,
   next,
   rewrite,

package/package.json

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