@vercel/functions 3.5.0 → 3.5.1

package/docs/index/functions/rewrite.md

@@ -0,0 +1,66 @@
+[**@vercel/functions**](../../README.md)
+
+***
+
+# Function: rewrite()
+
+> **rewrite**(`destination`, `init?`): [`Response`](https://developer.mozilla.org/docs/Web/API/Response)
+
+Defined in: [packages/functions/src/middleware.ts:101](https://github.com/vercel/vercel/blob/main/packages/functions/src/middleware.ts#L101)
+
+Returns a response that rewrites the request to a different URL.
+
+## Parameters
+
+### destination
+
+`string` \| [`URL`](https://developer.mozilla.org/docs/Web/API/URL)
+
+new URL to rewrite the request to
+
+### init?
+
+`ExtraResponseInit`
+
+Additional options for the response
+
+## Returns
+
+[`Response`](https://developer.mozilla.org/docs/Web/API/Response)
+
+## Examples
+
+<caption>Rewrite all feature-flagged requests from `/:path*` to `/experimental/:path*`</caption>
+
+```ts
+import { rewrite, next } from '@vercel/edge';
+
+export default async function middleware(req: Request) {
+  const flagged = await getFlag(req, 'isExperimental');
+  if (flagged) {
+    const url = new URL(req.url);
+    url.pathname = `/experimental{url.pathname}`;
+    return rewrite(url);
+  }
+
+  return next();
+}
+```
+
+<caption>JWT authentication for `/api/:path*` requests</caption>
+
+```ts
+import { rewrite, next } from '@vercel/edge';
+
+export default function middleware(req: Request) {
+  const auth = checkJwt(req.headers.get('Authorization'));
+  if (!checkJwt) {
+    return rewrite(new URL('/api/error-unauthorized', req.url));
+  }
+  const url = new URL(req.url);
+  url.searchParams.set('_userId', auth.userId);
+  return rewrite(url);
+}
+
+export const config = { matcher: '/api/users/:path*' };
+```

package/docs/index/functions/waitUntil.md

@@ -0,0 +1,38 @@
+[**@vercel/functions**](../../README.md)
+
+***
+
+# Function: waitUntil()
+
+> **waitUntil**(`promise`): `void` \| `undefined`
+
+Defined in: [packages/functions/src/wait-until.ts:19](https://github.com/vercel/vercel/blob/main/packages/functions/src/wait-until.ts#L19)
+
+Extends the lifetime of the request handler for the lifetime of the given [Promise](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)
+
+## Parameters
+
+### promise
+
+[`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<`unknown`\>
+
+The promise to wait for.
+
+## Returns
+
+`void` \| `undefined`
+
+## See
+
+https://developer.mozilla.org/en-US/docs/Web/API/ExtendableEvent/waitUntil
+
+## Example
+
+```js
+import { waitUntil } from '@vercel/functions';
+
+export function GET(request) {
+  waitUntil(fetch('https://vercel.com'));
+  return new Response('OK');
+}
+```

package/docs/index/interfaces/DangerouslyDeleteOptions.md

@@ -0,0 +1,18 @@
+[**@vercel/functions**](../../README.md)
+
+***
+
+# Interface: DangerouslyDeleteOptions
+
+Defined in: [packages/functions/src/purge/types.ts:1](https://github.com/vercel/vercel/blob/main/packages/functions/src/purge/types.ts#L1)
+
+## Properties
+
+### revalidationDeadlineSeconds?
+
+> `optional` **revalidationDeadlineSeconds?**: `number`
+
+Defined in: [packages/functions/src/purge/types.ts:6](https://github.com/vercel/vercel/blob/main/packages/functions/src/purge/types.ts#L6)
+
+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.

package/docs/index/interfaces/Geo.md

@@ -0,0 +1,90 @@
+[**@vercel/functions**](../../README.md)
+
+***
+
+# Interface: Geo
+
+Defined in: [packages/functions/src/headers.ts:57](https://github.com/vercel/vercel/blob/main/packages/functions/src/headers.ts#L57)
+
+The location information of a given request.
+
+## Properties
+
+### city?
+
+> `optional` **city?**: `string`
+
+Defined in: [packages/functions/src/headers.ts:59](https://github.com/vercel/vercel/blob/main/packages/functions/src/headers.ts#L59)
+
+The city that the request originated from.
+
+***
+
+### country?
+
+> `optional` **country?**: `string`
+
+Defined in: [packages/functions/src/headers.ts:62](https://github.com/vercel/vercel/blob/main/packages/functions/src/headers.ts#L62)
+
+The country that the request originated from.
+
+***
+
+### countryRegion?
+
+> `optional` **countryRegion?**: `string`
+
+Defined in: [packages/functions/src/headers.ts:73](https://github.com/vercel/vercel/blob/main/packages/functions/src/headers.ts#L73)
+
+The region part of the ISO 3166-2 code of the client IP.
+See [docs](https://vercel.com/docs/concepts/edge-network/headers#x-vercel-ip-country-region).
+
+***
+
+### flag?
+
+> `optional` **flag?**: `string`
+
+Defined in: [packages/functions/src/headers.ts:65](https://github.com/vercel/vercel/blob/main/packages/functions/src/headers.ts#L65)
+
+The flag emoji for the country the request originated from.
+
+***
+
+### latitude?
+
+> `optional` **latitude?**: `string`
+
+Defined in: [packages/functions/src/headers.ts:76](https://github.com/vercel/vercel/blob/main/packages/functions/src/headers.ts#L76)
+
+The latitude of the client.
+
+***
+
+### longitude?
+
+> `optional` **longitude?**: `string`
+
+Defined in: [packages/functions/src/headers.ts:79](https://github.com/vercel/vercel/blob/main/packages/functions/src/headers.ts#L79)
+
+The longitude of the client.
+
+***
+
+### postalCode?
+
+> `optional` **postalCode?**: `string`
+
+Defined in: [packages/functions/src/headers.ts:82](https://github.com/vercel/vercel/blob/main/packages/functions/src/headers.ts#L82)
+
+The postal code of the client
+
+***
+
+### region?
+
+> `optional` **region?**: `string`
+
+Defined in: [packages/functions/src/headers.ts:68](https://github.com/vercel/vercel/blob/main/packages/functions/src/headers.ts#L68)
+
+The [Vercel Edge Network region](https://vercel.com/docs/concepts/edge-network/regions) that received the request.

package/docs/index/interfaces/PurgeApi.md

@@ -0,0 +1,123 @@
+[**@vercel/functions**](../../README.md)
+
+***
+
+# Interface: PurgeApi
+
+Defined in: [packages/functions/src/purge/types.ts:12](https://github.com/vercel/vercel/blob/main/packages/functions/src/purge/types.ts#L12)
+
+Vercel Cache Purge APIs.
+
+## Properties
+
+### dangerouslyDeleteBySrcImage
+
+> **dangerouslyDeleteBySrcImage**: (`src`, `options?`) => [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<`void`\>
+
+Defined in: [packages/functions/src/purge/types.ts:54](https://github.com/vercel/vercel/blob/main/packages/functions/src/purge/types.ts#L54)
+
+Given a source image, delete all of its transformed images after a specified revalidation deadline.
+If accessed prior to the revalidation deadline, the stale transformed image will be served and a background task will be triggered. After the revalidation deadline is reached, the transformed image will be deleted.
+The default revalidation deadline is 0 and the content will be deleted immediately.
+
+#### Parameters
+
+##### src
+
+`string` \| `string`[]
+
+The source image to delete.
+
+##### options?
+
+[`DangerouslyDeleteOptions`](DangerouslyDeleteOptions.md)
+
+The options for the delete that specify the revalidation deadline.
+
+#### Returns
+
+[`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<`void`\>
+
+A promise that resolves when the delete is complete.
+
+***
+
+### dangerouslyDeleteByTag
+
+> **dangerouslyDeleteByTag**: (`tag`, `options?`) => [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<`void`\>
+
+Defined in: [packages/functions/src/purge/types.ts:31](https://github.com/vercel/vercel/blob/main/packages/functions/src/purge/types.ts#L31)
+
+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
+
+##### tag
+
+`string` \| `string`[]
+
+The tag or tags to delete.
+
+##### options?
+
+[`DangerouslyDeleteOptions`](DangerouslyDeleteOptions.md)
+
+The options for the delete that specify the revalidation deadline.
+
+#### Returns
+
+[`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<`void`\>
+
+A promise that resolves when the delete is complete.
+
+***
+
+### invalidateBySrcImage
+
+> **invalidateBySrcImage**: (`src`) => [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<`void`\>
+
+Defined in: [packages/functions/src/purge/types.ts:43](https://github.com/vercel/vercel/blob/main/packages/functions/src/purge/types.ts#L43)
+
+Given a source image, invalidate all of its transformed images by marking them as stale.
+On the next access, the stale transformed image will be served and a background task will transform the source image.
+
+#### Parameters
+
+##### src
+
+`string` \| `string`[]
+
+The source image to invalidate.
+
+#### Returns
+
+[`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<`void`\>
+
+A promise that resolves when the invalidate is complete.
+
+***
+
+### invalidateByTag
+
+> **invalidateByTag**: (`tag`) => [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<`void`\>
+
+Defined in: [packages/functions/src/purge/types.ts:20](https://github.com/vercel/vercel/blob/main/packages/functions/src/purge/types.ts#L20)
+
+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
+
+##### tag
+
+`string` \| `string`[]
+
+The tag or tags to invalidate.
+
+#### Returns
+
+[`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<`void`\>
+
+A promise that resolves when the invalidate is complete.

package/docs/index/interfaces/Request.md

@@ -0,0 +1,19 @@
+[**@vercel/functions**](../../README.md)
+
+***
+
+# Interface: Request
+
+Defined in: [packages/functions/src/headers.ts:48](https://github.com/vercel/vercel/blob/main/packages/functions/src/headers.ts#L48)
+
+We define a new type so this function can be reused with the global `Request`, `node-fetch` and other types.
+
+## Properties
+
+### headers
+
+> **headers**: `Headers`
+
+Defined in: [packages/functions/src/headers.ts:52](https://github.com/vercel/vercel/blob/main/packages/functions/src/headers.ts#L52)
+
+Represents the headers of a request.

package/docs/index/interfaces/RuntimeCache.md

@@ -0,0 +1,133 @@
+[**@vercel/functions**](../../README.md)
+
+***
+
+# Interface: RuntimeCache
+
+Defined in: [packages/functions/src/cache/types.ts:4](https://github.com/vercel/vercel/blob/main/packages/functions/src/cache/types.ts#L4)
+
+Interface representing the runtime cache.
+
+## Properties
+
+### delete
+
+> **delete**: (`key`) => [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<`void`\>
+
+Defined in: [packages/functions/src/cache/types.ts:11](https://github.com/vercel/vercel/blob/main/packages/functions/src/cache/types.ts#L11)
+
+Deletes a value from the cache.
+
+#### Parameters
+
+##### key
+
+`string`
+
+The key of the value to delete.
+
+#### Returns
+
+[`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<`void`\>
+
+A promise that resolves when the value is deleted.
+
+***
+
+### expireTag
+
+> **expireTag**: (`tag`) => [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<`void`\>
+
+Defined in: [packages/functions/src/cache/types.ts:44](https://github.com/vercel/vercel/blob/main/packages/functions/src/cache/types.ts#L44)
+
+Expires cache entries by tag.
+
+#### Parameters
+
+##### tag
+
+`string` \| `string`[]
+
+The tag or tags of the cache entries to expire.
+
+#### Returns
+
+[`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<`void`\>
+
+A promise that resolves when the cache entries expiration request is received.
+
+***
+
+### get
+
+> **get**: (`key`) => [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<`unknown`\>
+
+Defined in: [packages/functions/src/cache/types.ts:19](https://github.com/vercel/vercel/blob/main/packages/functions/src/cache/types.ts#L19)
+
+Retrieves a value from the cache.
+
+#### Parameters
+
+##### key
+
+`string`
+
+The key of the value to retrieve.
+
+#### Returns
+
+[`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<`unknown`\>
+
+A promise that resolves to the value, or null if not found.
+
+***
+
+### set
+
+> **set**: (`key`, `value`, `options?`) => [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<`void`\>
+
+Defined in: [packages/functions/src/cache/types.ts:32](https://github.com/vercel/vercel/blob/main/packages/functions/src/cache/types.ts#L32)
+
+Sets a value in the cache.
+
+#### Parameters
+
+##### key
+
+`string`
+
+The key of the value to set.
+
+##### value
+
+`unknown`
+
+The value to set.
+
+##### options?
+
+Optional settings for the cache entry.
+
+###### name?
+
+`string`
+
+Optional user-friendly name for the cache entry used for o11y.
+
+###### tags?
+
+`string`[]
+
+Optional tags to associate with the cache entry.
+
+###### ttl?
+
+`number`
+
+Optional time-to-live for the cache entry, in seconds.
+
+#### Returns
+
+[`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<`void`\>
+
+A promise that resolves when the value is set.

package/docs/index/type-aliases/AddCacheTagApi.md

@@ -0,0 +1,26 @@
+[**@vercel/functions**](../../README.md)
+
+***
+
+# Type Alias: AddCacheTagApi
+
+> **AddCacheTagApi** = (`tag`) => [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<`void`\>
+
+Defined in: [packages/functions/src/addcachetag/types.ts:8](https://github.com/vercel/vercel/blob/main/packages/functions/src/addcachetag/types.ts#L8)
+
+Vercel AddCacheTag API.
+A function that adds one or more tags to the cache content.
+
+## Parameters
+
+### tag
+
+`string` \| `string`[]
+
+One or more tags to add to the cache content.
+
+## Returns
+
+[`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<`void`\>
+
+A promise that resolves when the tag is added.

package/docs/index/variables/experimental_attachDatabasePool.md

@@ -0,0 +1,49 @@
+[**@vercel/functions**](../../README.md)
+
+***
+
+# ~~Variable: experimental\_attachDatabasePool~~
+
+> `const` **experimental\_attachDatabasePool**: (`dbPool`) => `void` = `attachDatabasePool`
+
+Defined in: [packages/functions/src/db-connections/index.ts:323](https://github.com/vercel/vercel/blob/main/packages/functions/src/db-connections/index.ts#L323)
+
+**`Experimental`**
+
+Call this function right after creating a database pool with the database pool object
+as argument.
+This ensures that the current function instance stays alive long enough for
+idle database connections to be removed from the pool.
+
+## Parameters
+
+### dbPool
+
+`DbPool`
+
+The database pool object. The supported pool types are:
+- PostgreSQL (pg)
+- MySQL2
+- MariaDB
+- MongoDB
+- Redis (ioredis)
+- Cassandra (cassandra-driver)
+- OTHER: This method uses duck-typing to detect the pool type. Respectively you can
+  pass in any object with a compatible interface.
+
+## Returns
+
+`void`
+
+## Example
+
+```ts
+const pgPool = new Pool({
+  connectionString: process.env.DATABASE_URL,
+});
+attachDatabasePool(pgPool);
+```
+
+## Deprecated
+
+Use attachDatabasePool instead.

package/docs/oidc/README.md

@@ -0,0 +1,15 @@
+[**@vercel/functions**](../README.md)
+
+---
+
+# oidc
+
+## Interfaces
+
+- [AwsCredentialsProviderInit](interfaces/AwsCredentialsProviderInit.md)
+
+## Functions
+
+- [~~awsCredentialsProvider~~](functions/awsCredentialsProvider.md)
+- [~~getVercelOidcToken~~](functions/getVercelOidcToken.md)
+- [~~getVercelOidcTokenSync~~](functions/getVercelOidcTokenSync.md)

package/docs/oidc/functions/awsCredentialsProvider.md

@@ -0,0 +1,24 @@
+[**@vercel/functions**](../../README.md)
+
+***
+
+# ~~Function: awsCredentialsProvider()~~
+
+> **awsCredentialsProvider**(`init`): `AwsCredentialIdentityProvider`
+
+Defined in: [packages/functions/src/oidc/aws-credentials-provider.ts:70](https://github.com/vercel/vercel/blob/main/packages/functions/src/oidc/aws-credentials-provider.ts#L70)
+
+## Parameters
+
+### init
+
+[`AwsCredentialsProviderInit`](../interfaces/AwsCredentialsProviderInit.md)
+
+## Returns
+
+`AwsCredentialIdentityProvider`
+
+## Deprecated
+
+Use @vercel/oidc-aws-credentials-provider instead
+AWS authentication for Vercel Functions

package/docs/oidc/functions/getVercelOidcToken.md

@@ -0,0 +1,58 @@
+[**@vercel/functions**](../../README.md)
+
+***
+
+# ~~Function: getVercelOidcToken()~~
+
+> **getVercelOidcToken**(`options?`): [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<`string`\>
+
+Defined in: packages/oidc/dist/get-vercel-oidc-token.d.ts:60
+
+Gets the current OIDC token from the request context or the environment variable.
+
+Do not cache this value, as it is subject to change in production!
+
+This function is used to retrieve the OIDC token from the request context or the environment variable.
+It checks for the `x-vercel-oidc-token` header in the request context and falls back to the `VERCEL_OIDC_TOKEN` environment variable if the header is not present.
+
+Unlike the `getVercelOidcTokenSync` function, this function will refresh the token if it is expired in a development environment.
+
+## Parameters
+
+### options?
+
+`GetVercelOidcTokenOptions`
+
+Optional configuration for token retrieval.
+
+## Returns
+
+[`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<`string`\>
+
+A promise that resolves to the OIDC token.
+
+## Throws
+
+If the `x-vercel-oidc-token` header is missing from the request context and the environment variable `VERCEL_OIDC_TOKEN` is not set. If the token
+is expired in a development environment, will also throw an error if the token cannot be refreshed: no CLI credentials are available, CLI credentials are expired, no project configuration is available
+or the token refresh request fails.
+
+## Examples
+
+```js
+// Using the OIDC token
+getVercelOidcToken().then((token) => {
+  console.log('OIDC Token:', token);
+}).catch((error) => {
+  console.error('Error:', error.message);
+});
+```
+
+```js
+// Using the OIDC token with explicit team and project (supports IDs and slugs)
+getVercelOidcToken({ team: 'my-team', project: 'my-project' }).then((token) => {
+  console.log('OIDC Token:', token);
+}).catch((error) => {
+  console.error('Error:', error.message);
+});
+```