@vercel/functions 3.0.0 → 3.1.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @vercel/functions
 
+## 3.1.0
+
+### Minor Changes
+
+- Introduces Vercel Purge APIs: invalidateByTag, dangerouslyDeleteByTag ([#13867](https://github.com/vercel/vercel/pull/13867))
+
 ## 3.0.0
 
 ### Major Changes

package/docs/interfaces/index.DangerouslyDeleteOptions.md

@@ -0,0 +1,22 @@
+# Interface: DangerouslyDeleteOptions
+
+[index](../modules/index.md).DangerouslyDeleteOptions
+
+## Table of contents
+
+### Properties
+
+- [revalidationDeadlineSeconds](index.DangerouslyDeleteOptions.md#revalidationdeadlineseconds)
+
+## Properties
+
+### revalidationDeadlineSeconds
+
+• `Optional` **revalidationDeadlineSeconds**: `number`
+
+The time in seconds for how long the stale content can be served while revalidating the new content in the background.
+If none is provided, the default is 0 and the content will be deleted immediately.
+
+#### Defined in
+
+[packages/functions/src/purge/types.ts:6](https://github.com/vercel/vercel/blob/main/packages/functions/src/purge/types.ts#L6)

package/docs/interfaces/index.PurgeApi.md

@@ -0,0 +1,72 @@
+# Interface: PurgeApi
+
+[index](../modules/index.md).PurgeApi
+
+Vercel Cache Purge APIs.
+
+## Table of contents
+
+### Properties
+
+- [dangerouslyDeleteByTag](index.PurgeApi.md#dangerouslydeletebytag)
+- [invalidateByTag](index.PurgeApi.md#invalidatebytag)
+
+## Properties
+
+### dangerouslyDeleteByTag
+
+• **dangerouslyDeleteByTag**: (`tag`: `string` \| `string`[], `options?`: [`DangerouslyDeleteOptions`](index.DangerouslyDeleteOptions.md)) => [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`void`\>
+
+#### Type declaration
+
+▸ (`tag`, `options?`): [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`void`\>
+
+Delete all content associated with a tag or tags after a specified revalidation deadline.
+If accessed prior to the revalidation deadline, the stale content will be served and a background revalidation will be triggered. After the revalidation deadline is reached, the content will be deleted.
+The default revalidation deadline is 0 and the content will be deleted immediately.
+
+##### Parameters
+
+| Name       | Type                                                            | Description                                                        |
+| :--------- | :-------------------------------------------------------------- | :----------------------------------------------------------------- |
+| `tag`      | `string` \| `string`[]                                          | The tag or tags to delete.                                         |
+| `options?` | [`DangerouslyDeleteOptions`](index.DangerouslyDeleteOptions.md) | The options for the delete that specify the revalidation deadline. |
+
+##### Returns
+
+[`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`void`\>
+
+A promise that resolves when the delete is complete.
+
+#### Defined in
+
+[packages/functions/src/purge/types.ts:31](https://github.com/vercel/vercel/blob/main/packages/functions/src/purge/types.ts#L31)
+
+---
+
+### invalidateByTag
+
+• **invalidateByTag**: (`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`\>
+
+Invalidate all content associated with a tag or tags by marking them as stale.
+On the next access to content associated with any of the tags, the stale content will be served and a background revalidation will be triggered.
+
+##### Parameters
+
+| Name  | Type                   | Description                    |
+| :---- | :--------------------- | :----------------------------- |
+| `tag` | `string` \| `string`[] | The tag or tags to invalidate. |
+
+##### Returns
+
+[`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`void`\>
+
+A promise that resolves when the invalidate is complete.
+
+#### Defined in
+
+[packages/functions/src/purge/types.ts:20](https://github.com/vercel/vercel/blob/main/packages/functions/src/purge/types.ts#L20)

package/docs/modules/index.md

@@ -4,17 +4,21 @@
 
 ### Interfaces
 
+- [DangerouslyDeleteOptions](../interfaces/index.DangerouslyDeleteOptions.md)
 - [Geo](../interfaces/index.Geo.md)
+- [PurgeApi](../interfaces/index.PurgeApi.md)
 - [Request](../interfaces/index.Request.md)
 - [RuntimeCache](../interfaces/index.RuntimeCache.md)
 
 ### Functions
 
 - [attachDatabasePool](index.md#attachdatabasepool)
+- [dangerouslyDeleteByTag](index.md#dangerouslydeletebytag)
 - [experimental_attachDatabasePool](index.md#experimental_attachdatabasepool)
 - [geolocation](index.md#geolocation)
 - [getCache](index.md#getcache)
 - [getEnv](index.md#getenv)
+- [invalidateByTag](index.md#invalidatebytag)
 - [ipAddress](index.md#ipaddress)
 - [next](index.md#next)
 - [rewrite](index.md#rewrite)
@@ -56,6 +60,27 @@ attachDatabasePool(pgPool);
 
 ---
 
+### dangerouslyDeleteByTag
+
+▸ **dangerouslyDeleteByTag**(`tag`, `options?`): [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`void`\>
+
+#### Parameters
+
+| Name       | Type                                                                          |
+| :--------- | :---------------------------------------------------------------------------- |
+| `tag`      | `string` \| `string`[]                                                        |
+| `options?` | [`DangerouslyDeleteOptions`](../interfaces/index.DangerouslyDeleteOptions.md) |
+
+#### Returns
+
+[`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`void`\>
+
+#### Defined in
+
+[packages/functions/src/purge/index.ts:13](https://github.com/vercel/vercel/blob/main/packages/functions/src/purge/index.ts#L13)
+
+---
+
 ### experimental_attachDatabasePool
 
 ▸ **experimental_attachDatabasePool**(`dbPool`): `void`
@@ -213,6 +238,26 @@ https://vercel.com/docs/projects/environment-variables/system-environment-variab
 
 ---
 
+### invalidateByTag
+
+▸ **invalidateByTag**(`tag`): [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`void`\>
+
+#### Parameters
+
+| Name  | Type                   |
+| :---- | :--------------------- |
+| `tag` | `string` \| `string`[] |
+
+#### Returns
+
+[`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`void`\>
+
+#### Defined in
+
+[packages/functions/src/purge/index.ts:5](https://github.com/vercel/vercel/blob/main/packages/functions/src/purge/index.ts#L5)
+
+---
+
 ### ipAddress
 
 ▸ **ipAddress**(`input`): `string` \| `undefined`

package/get-context.d.ts

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

package/index.d.ts

@@ -6,3 +6,5 @@ export { rewrite, next } from './middleware';
 export { getCache } from './cache';
 export { attachDatabasePool, experimental_attachDatabasePool, } from './db-connections';
 export type { RuntimeCache } from './cache/types';
+export { invalidateByTag, dangerouslyDeleteByTag } from './purge';
+export type { PurgeApi, DangerouslyDeleteOptions } from './purge/types';

package/index.js

@@ -19,10 +19,12 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var src_exports = {};
 __export(src_exports, {
   attachDatabasePool: () => import_db_connections.attachDatabasePool,
+  dangerouslyDeleteByTag: () => import_purge.dangerouslyDeleteByTag,
   experimental_attachDatabasePool: () => import_db_connections.experimental_attachDatabasePool,
   geolocation: () => import_headers.geolocation,
   getCache: () => import_cache.getCache,
   getEnv: () => import_get_env.getEnv,
+  invalidateByTag: () => import_purge.invalidateByTag,
   ipAddress: () => import_headers.ipAddress,
   next: () => import_middleware.next,
   rewrite: () => import_middleware.rewrite,
@@ -35,13 +37,16 @@ var import_wait_until = require("./wait-until");
 var import_middleware = require("./middleware");
 var import_cache = require("./cache");
 var import_db_connections = require("./db-connections");
+var import_purge = require("./purge");
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   attachDatabasePool,
+  dangerouslyDeleteByTag,
   experimental_attachDatabasePool,
   geolocation,
   getCache,
   getEnv,
+  invalidateByTag,
   ipAddress,
   next,
   rewrite,

package/package.json

@@ -30,7 +30,7 @@
       "require": "./middleware.js"
     }
   },
-  "version": "3.0.0",
+  "version": "3.1.0",
   "repository": {
     "directory": "packages/functions",
     "type": "git",

package/purge/index.d.ts

@@ -0,0 +1,4 @@
+import { DangerouslyDeleteOptions } from './types';
+export * from './types';
+export declare const invalidateByTag: (tag: string | string[]) => Promise<void>;
+export declare const dangerouslyDeleteByTag: (tag: string | string[], options?: DangerouslyDeleteOptions) => Promise<void>;

package/purge/index.js

@@ -0,0 +1,47 @@
+"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 __reExport = (target, mod, secondTarget) => (__copyProps(target, mod, "default"), secondTarget && __copyProps(secondTarget, mod, "default"));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var purge_exports = {};
+__export(purge_exports, {
+  dangerouslyDeleteByTag: () => dangerouslyDeleteByTag,
+  invalidateByTag: () => invalidateByTag
+});
+module.exports = __toCommonJS(purge_exports);
+var import_get_context = require("../get-context");
+__reExport(purge_exports, require("./types"), module.exports);
+const invalidateByTag = (tag) => {
+  const api = (0, import_get_context.getContext)().purge;
+  if (api) {
+    return api.invalidateByTag(tag);
+  }
+  return Promise.resolve();
+};
+const dangerouslyDeleteByTag = (tag, options) => {
+  const api = (0, import_get_context.getContext)().purge;
+  if (api) {
+    return api.dangerouslyDeleteByTag(tag, options);
+  }
+  return Promise.resolve();
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  dangerouslyDeleteByTag,
+  invalidateByTag,
+  ...require("./types")
+});

package/purge/types.d.ts

@@ -0,0 +1,30 @@
+export interface DangerouslyDeleteOptions {
+    /**
+     * The time in seconds for how long the stale content can be served while revalidating the new content in the background.
+     * If none is provided, the default is 0 and the content will be deleted immediately.
+     */
+    revalidationDeadlineSeconds?: number;
+}
+/**
+ * Vercel Cache Purge APIs.
+ */
+export interface PurgeApi {
+    /**
+     * Invalidate all content associated with a tag or tags by marking them as stale.
+     * On the next access to content associated with any of the tags, the stale content will be served and a background revalidation will be triggered.
+     *
+     * @param tag The tag or tags to invalidate.
+     * @returns A promise that resolves when the invalidate is complete.
+     */
+    invalidateByTag: (tag: string | string[]) => Promise<void>;
+    /**
+     * Delete all content associated with a tag or tags after a specified revalidation deadline.
+     * If accessed prior to the revalidation deadline, the stale content will be served and a background revalidation will be triggered. After the revalidation deadline is reached, the content will be deleted.
+     * The default revalidation deadline is 0 and the content will be deleted immediately.
+     *
+     * @param tag The tag or tags to delete.
+     * @param options The options for the delete that specify the revalidation deadline.
+     * @returns A promise that resolves when the delete is complete.
+     */
+    dangerouslyDeleteByTag: (tag: string | string[], options?: DangerouslyDeleteOptions) => Promise<void>;
+}

package/purge/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);