@vercel/functions 3.5.0 → 3.5.1

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @vercel/functions
 
+## 3.5.1
+
+### Patch Changes
+
+- ae20217: Upgrade to TypeScript 5.9
+- Updated dependencies [ae20217]
+  - @vercel/oidc@3.4.1
+
 ## 3.5.0
 
 ### Minor Changes

package/docs/README.md

@@ -1,8 +1,10 @@
-# @vercel/functions
+**@vercel/functions**
+
+---
 
-## Table of contents
+# @vercel/functions
 
-### Modules
+## Modules
 
-- [index](modules/index.md)
-- [oidc](modules/oidc.md)
+- [index](index/README.md)
+- [oidc](oidc/README.md)

package/docs/index/README.md

@@ -0,0 +1,37 @@
+[**@vercel/functions**](../README.md)
+
+---
+
+# index
+
+## Interfaces
+
+- [DangerouslyDeleteOptions](interfaces/DangerouslyDeleteOptions.md)
+- [Geo](interfaces/Geo.md)
+- [PurgeApi](interfaces/PurgeApi.md)
+- [Request](interfaces/Request.md)
+- [RuntimeCache](interfaces/RuntimeCache.md)
+
+## Type Aliases
+
+- [AddCacheTagApi](type-aliases/AddCacheTagApi.md)
+
+## Variables
+
+- [~~experimental_attachDatabasePool~~](variables/experimental_attachDatabasePool.md)
+
+## Functions
+
+- [addCacheTag](functions/addCacheTag.md)
+- [attachDatabasePool](functions/attachDatabasePool.md)
+- [dangerouslyDeleteBySrcImage](functions/dangerouslyDeleteBySrcImage.md)
+- [dangerouslyDeleteByTag](functions/dangerouslyDeleteByTag.md)
+- [geolocation](functions/geolocation.md)
+- [getCache](functions/getCache.md)
+- [getEnv](functions/getEnv.md)
+- [invalidateBySrcImage](functions/invalidateBySrcImage.md)
+- [invalidateByTag](functions/invalidateByTag.md)
+- [ipAddress](functions/ipAddress.md)
+- [next](functions/next.md)
+- [rewrite](functions/rewrite.md)
+- [waitUntil](functions/waitUntil.md)

package/docs/index/functions/addCacheTag.md

@@ -0,0 +1,19 @@
+[**@vercel/functions**](../../README.md)
+
+***
+
+# Function: addCacheTag()
+
+> **addCacheTag**(`tag`): [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<`void`\>
+
+Defined in: [packages/functions/src/addcachetag/index.ts:3](https://github.com/vercel/vercel/blob/main/packages/functions/src/addcachetag/index.ts#L3)
+
+## Parameters
+
+### tag
+
+`string` \| `string`[]
+
+## Returns
+
+[`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<`void`\>

package/docs/index/functions/attachDatabasePool.md

@@ -0,0 +1,45 @@
+[**@vercel/functions**](../../README.md)
+
+***
+
+# Function: attachDatabasePool()
+
+> **attachDatabasePool**(`dbPool`): `void`
+
+Defined in: [packages/functions/src/db-connections/index.ts:225](https://github.com/vercel/vercel/blob/main/packages/functions/src/db-connections/index.ts#L225)
+
+**`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);
+```

package/docs/index/functions/dangerouslyDeleteBySrcImage.md

@@ -0,0 +1,23 @@
+[**@vercel/functions**](../../README.md)
+
+***
+
+# Function: dangerouslyDeleteBySrcImage()
+
+> **dangerouslyDeleteBySrcImage**(`src`, `options?`): [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<`void`\>
+
+Defined in: [packages/functions/src/purge/index.ts:28](https://github.com/vercel/vercel/blob/main/packages/functions/src/purge/index.ts#L28)
+
+## Parameters
+
+### src
+
+`string` \| `string`[]
+
+### options?
+
+[`DangerouslyDeleteOptions`](../interfaces/DangerouslyDeleteOptions.md)
+
+## Returns
+
+[`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<`void`\>

package/docs/index/functions/dangerouslyDeleteByTag.md

@@ -0,0 +1,23 @@
+[**@vercel/functions**](../../README.md)
+
+***
+
+# Function: dangerouslyDeleteByTag()
+
+> **dangerouslyDeleteByTag**(`tag`, `options?`): [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<`void`\>
+
+Defined in: [packages/functions/src/purge/index.ts:12](https://github.com/vercel/vercel/blob/main/packages/functions/src/purge/index.ts#L12)
+
+## Parameters
+
+### tag
+
+`string` \| `string`[]
+
+### options?
+
+[`DangerouslyDeleteOptions`](../interfaces/DangerouslyDeleteOptions.md)
+
+## Returns
+
+[`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<`void`\>

package/docs/index/functions/geolocation.md

@@ -0,0 +1,49 @@
+[**@vercel/functions**](../../README.md)
+
+***
+
+# Function: geolocation()
+
+> **geolocation**(`request`): [`Geo`](../interfaces/Geo.md)
+
+Defined in: [packages/functions/src/headers.ts:180](https://github.com/vercel/vercel/blob/main/packages/functions/src/headers.ts#L180)
+
+Returns the location information for the incoming request.
+
+## Parameters
+
+### request
+
+[`Request`](../interfaces/Request.md)
+
+The incoming request object which provides the geolocation data
+
+## Returns
+
+[`Geo`](../interfaces/Geo.md)
+
+The location information of the request, in this way:
+
+```json
+{
+ "city": "New York",
+ "country": "US",
+ "flag": "🇺🇸",
+ "countryRegion": "NY",
+ "region": "iad1",
+ "latitude": "40.7128",
+ "longitude": "-74.0060"
+ "postalCode": "10001"
+}
+```
+
+## Example
+
+```js
+import { geolocation } from '@vercel/functions';
+
+export function GET(request) {
+  const details = geolocation(request);
+  return Response.json(details);
+}
+```

package/docs/index/functions/getCache.md

@@ -0,0 +1,36 @@
+[**@vercel/functions**](../../README.md)
+
+***
+
+# Function: getCache()
+
+> **getCache**(`cacheOptions?`): [`RuntimeCache`](../interfaces/RuntimeCache.md)
+
+Defined in: [packages/functions/src/cache/index.ts:33](https://github.com/vercel/vercel/blob/main/packages/functions/src/cache/index.ts#L33)
+
+Retrieves the Vercel Runtime 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.
+
+## Parameters
+
+### cacheOptions?
+
+`CacheOptions`
+
+Optional configuration for the cache.
+
+## Returns
+
+[`RuntimeCache`](../interfaces/RuntimeCache.md)
+
+An instance of the Vercel Runtime Cache.
+
+## Throws
+
+If no cache is available in the context and `InMemoryCache` cannot be created.

package/docs/index/functions/getEnv.md

@@ -0,0 +1,291 @@
+[**@vercel/functions**](../../README.md)
+
+***
+
+# Function: getEnv()
+
+> **getEnv**(`env?`): `object`
+
+Defined in: [packages/functions/src/get-env.ts:6](https://github.com/vercel/vercel/blob/main/packages/functions/src/get-env.ts#L6)
+
+Get System Environment Variables exposed by Vercel.
+
+## Parameters
+
+### env?
+
+## Returns
+
+### CI
+
+> **CI**: `string` \| `undefined`
+
+An indicator that the code is running in a Continuous Integration environment.
+
+#### Example
+
+```ts
+"1"
+```
+
+### VERCEL
+
+> **VERCEL**: `string` \| `undefined`
+
+An indicator to show that System Environment Variables have been exposed to your project's Deployments.
+
+#### Example
+
+```ts
+"1"
+```
+
+### VERCEL\_AUTOMATION\_BYPASS\_SECRET
+
+> **VERCEL\_AUTOMATION\_BYPASS\_SECRET**: `string` \| `undefined`
+
+The Protection Bypass for Automation value, if the secret has been generated in the project's Deployment Protection settings.
+
+### VERCEL\_BRANCH\_URL
+
+> **VERCEL\_BRANCH\_URL**: `string` \| `undefined`
+
+The domain name of the generated Git branch URL. The value does not include the protocol scheme https://.
+
+#### Example
+
+```ts
+"*-git-*.vercel.app"
+```
+
+### VERCEL\_DEPLOYMENT\_ID
+
+> **VERCEL\_DEPLOYMENT\_ID**: `string` \| `undefined`
+
+The unique identifier for the deployment, which can be used to implement Skew Protection.
+
+#### Example
+
+```ts
+"dpl_7Gw5ZMBpQA8h9GF832KGp7nwbuh3"
+```
+
+### VERCEL\_ENV
+
+> **VERCEL\_ENV**: `string` \| `undefined`
+
+The Environment that the app is deployed and running on.
+
+#### Example
+
+```ts
+"production"
+```
+
+### VERCEL\_GIT\_COMMIT\_AUTHOR\_LOGIN
+
+> **VERCEL\_GIT\_COMMIT\_AUTHOR\_LOGIN**: `string` \| `undefined`
+
+The username attached to the author of the commit that the project was deployed by.
+
+#### Example
+
+```ts
+"johndoe"
+```
+
+### VERCEL\_GIT\_COMMIT\_AUTHOR\_NAME
+
+> **VERCEL\_GIT\_COMMIT\_AUTHOR\_NAME**: `string` \| `undefined`
+
+The name attached to the author of the commit that the project was deployed by.
+
+#### Example
+
+```ts
+"John Doe"
+```
+
+### VERCEL\_GIT\_COMMIT\_MESSAGE
+
+> **VERCEL\_GIT\_COMMIT\_MESSAGE**: `string` \| `undefined`
+
+The message attached to the commit the deployment was triggered by.
+
+#### Example
+
+```ts
+"Update about page"
+```
+
+### VERCEL\_GIT\_COMMIT\_REF
+
+> **VERCEL\_GIT\_COMMIT\_REF**: `string` \| `undefined`
+
+The git branch of the commit the deployment was triggered by.
+
+#### Example
+
+```ts
+"improve-about-page"
+```
+
+### VERCEL\_GIT\_COMMIT\_SHA
+
+> **VERCEL\_GIT\_COMMIT\_SHA**: `string` \| `undefined`
+
+The git SHA of the commit the deployment was triggered by.
+
+#### Example
+
+```ts
+"fa1eade47b73733d6312d5abfad33ce9e4068081"
+```
+
+### VERCEL\_GIT\_PREVIOUS\_SHA
+
+> **VERCEL\_GIT\_PREVIOUS\_SHA**: `string` \| `undefined`
+
+The git SHA of the last successful deployment for the project and branch.
+NOTE: This Variable is only exposed when an Ignored Build Step is provided.
+
+#### Example
+
+```ts
+"fa1eade47b73733d6312d5abfad33ce9e4068080"
+```
+
+### VERCEL\_GIT\_PROVIDER
+
+> **VERCEL\_GIT\_PROVIDER**: `string` \| `undefined`
+
+The Git Provider the deployment is triggered from.
+
+#### Example
+
+```ts
+"github"
+```
+
+### VERCEL\_GIT\_PULL\_REQUEST\_ID
+
+> **VERCEL\_GIT\_PULL\_REQUEST\_ID**: `string` \| `undefined`
+
+The pull request id the deployment was triggered by. If a deployment is created on a branch before a pull request is made, this value will be an empty string.
+
+#### Example
+
+```ts
+"23"
+```
+
+### VERCEL\_GIT\_REPO\_ID
+
+> **VERCEL\_GIT\_REPO\_ID**: `string` \| `undefined`
+
+The ID of the repository the deployment is triggered from.
+
+#### Example
+
+```ts
+"117716146"
+```
+
+### VERCEL\_GIT\_REPO\_OWNER
+
+> **VERCEL\_GIT\_REPO\_OWNER**: `string` \| `undefined`
+
+The account that owns the repository the deployment is triggered from.
+
+#### Example
+
+```ts
+"acme"
+```
+
+### VERCEL\_GIT\_REPO\_SLUG
+
+> **VERCEL\_GIT\_REPO\_SLUG**: `string` \| `undefined`
+
+The origin repository the deployment is triggered from.
+
+#### Example
+
+```ts
+"my-site"
+```
+
+### VERCEL\_PROJECT\_PRODUCTION\_URL
+
+> **VERCEL\_PROJECT\_PRODUCTION\_URL**: `string` \| `undefined`
+
+A production domain name of the project. This is useful to reliably generate links that point to production such as OG-image URLs.
+The value does not include the protocol scheme https://.
+
+#### Example
+
+```ts
+"myproject.vercel.app"
+```
+
+### VERCEL\_REGION
+
+> **VERCEL\_REGION**: `string` \| `undefined`
+
+The ID of the Region where the app is running.
+
+Possible values:
+- arn1 (Stockholm, Sweden)
+- bom1 (Mumbai, India)
+- cdg1 (Paris, France)
+- cle1 (Cleveland, USA)
+- cpt1 (Cape Town, South Africa)
+- dub1 (Dublin, Ireland)
+- fra1 (Frankfurt, Germany)
+- gru1 (São Paulo, Brazil)
+- hkg1 (Hong Kong)
+- hnd1 (Tokyo, Japan)
+- iad1 (Washington, D.C., USA)
+- icn1 (Seoul, South Korea)
+- kix1 (Osaka, Japan)
+- lhr1 (London, United Kingdom)
+- pdx1 (Portland, USA)
+- sfo1 (San Francisco, USA)
+- sin1 (Singapore)
+- syd1 (Sydney, Australia)
+- dev1 (Development Region)
+
+#### Example
+
+```ts
+"iad1"
+```
+
+### VERCEL\_SKEW\_PROTECTION\_ENABLED
+
+> **VERCEL\_SKEW\_PROTECTION\_ENABLED**: `string` \| `undefined`
+
+When Skew Protection is enabled in Project Settings, this value is set to 1.
+
+#### Example
+
+```ts
+"1"
+```
+
+### VERCEL\_URL
+
+> **VERCEL\_URL**: `string` \| `undefined`
+
+The domain name of the generated deployment URL. The value does not include the protocol scheme https://.
+NOTE: This Variable cannot be used in conjunction with Standard Deployment Protection.
+
+#### Example
+
+```ts
+"*.vercel.app"
+```
+
+## See
+
+https://vercel.com/docs/projects/environment-variables/system-environment-variables#system-environment-variables

package/docs/index/functions/invalidateBySrcImage.md

@@ -0,0 +1,19 @@
+[**@vercel/functions**](../../README.md)
+
+***
+
+# Function: invalidateBySrcImage()
+
+> **invalidateBySrcImage**(`src`): [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<`void`\>
+
+Defined in: [packages/functions/src/purge/index.ts:23](https://github.com/vercel/vercel/blob/main/packages/functions/src/purge/index.ts#L23)
+
+## Parameters
+
+### src
+
+`string` \| `string`[]
+
+## Returns
+
+[`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<`void`\>

package/docs/index/functions/invalidateByTag.md

@@ -0,0 +1,19 @@
+[**@vercel/functions**](../../README.md)
+
+***
+
+# Function: invalidateByTag()
+
+> **invalidateByTag**(`tag`): [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<`void`\>
+
+Defined in: [packages/functions/src/purge/index.ts:4](https://github.com/vercel/vercel/blob/main/packages/functions/src/purge/index.ts#L4)
+
+## Parameters
+
+### tag
+
+`string` \| `string`[]
+
+## Returns
+
+[`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<`void`\>

package/docs/index/functions/ipAddress.md

@@ -0,0 +1,36 @@
+[**@vercel/functions**](../../README.md)
+
+***
+
+# Function: ipAddress()
+
+> **ipAddress**(`input`): `string` \| `undefined`
+
+Defined in: [packages/functions/src/headers.ts:131](https://github.com/vercel/vercel/blob/main/packages/functions/src/headers.ts#L131)
+
+Returns the IP address of the request from the headers.
+
+## Parameters
+
+### input
+
+`Headers` \| [`Request`](../interfaces/Request.md)
+
+The incoming request object or headers.
+
+## Returns
+
+`string` \| `undefined`
+
+The IP address of the request.
+
+## Example
+
+```js
+import { ipAddress } from '@vercel/functions';
+
+export function GET(request) {
+  const ip = ipAddress(request);
+  return new Response(`Your IP is ${ip}`);
+}
+```

package/docs/index/functions/next.md

@@ -0,0 +1,47 @@
+[**@vercel/functions**](../../README.md)
+
+***
+
+# Function: next()
+
+> **next**(`init?`): [`Response`](https://developer.mozilla.org/docs/Web/API/Response)
+
+Defined in: [packages/functions/src/middleware.ts:145](https://github.com/vercel/vercel/blob/main/packages/functions/src/middleware.ts#L145)
+
+Returns a Response that instructs the system to continue processing the request.
+
+## Parameters
+
+### init?
+
+`ExtraResponseInit`
+
+Additional options for the response
+
+## Returns
+
+[`Response`](https://developer.mozilla.org/docs/Web/API/Response)
+
+## Examples
+
+<caption>No-op middleware</caption>
+
+```ts
+import { next } from '@vercel/edge';
+
+export default function middleware(_req: Request) {
+  return next();
+}
+```
+
+<caption>Add response headers to all requests</caption>
+
+```ts
+import { next } from '@vercel/edge';
+
+export default function middleware(_req: Request) {
+  return next({
+    headers: { 'x-from-middleware': 'true' },
+  })
+}
+```