diff --git a/packages/edge/docs/README.md b/packages/edge/docs/README.md index c19c62f08..2c3a25edb 100644 --- a/packages/edge/docs/README.md +++ b/packages/edge/docs/README.md @@ -7,6 +7,7 @@ - [ExtraResponseInit](interfaces/ExtraResponseInit.md) - [Geo](interfaces/Geo.md) - [ModifiedRequest](interfaces/ModifiedRequest.md) +- [RequestContext](interfaces/RequestContext.md) ### Variables diff --git a/packages/edge/docs/interfaces/RequestContext.md b/packages/edge/docs/interfaces/RequestContext.md new file mode 100644 index 000000000..7a41c912d --- /dev/null +++ b/packages/edge/docs/interfaces/RequestContext.md @@ -0,0 +1,79 @@ +# Interface: RequestContext + +An extension to the standard `Request` object that is passed to every Edge Function. + +**`Example`** + +```ts +import type { RequestContext } from '@vercel/edge'; + +export default async function handler( + request: Request, + ctx: RequestContext +): Promise { + // ctx is the RequestContext +} +``` + +## Table of contents + +### Methods + +- [waitUntil](RequestContext.md#waituntil) + +## Methods + +### waitUntil + +▸ **waitUntil**(`promise`): `void` + +A method that can be used to keep the function running after a response has been sent. +This is useful when you have an async task that you want to keep running even after the +response has been sent and the request has ended. + +**`Example`** + +Sending an internal error to an error tracking service + +```ts +import type { RequestContext } from '@vercel/edge'; + +export async function handleRequest( + request: Request, + ctx: RequestContext +): Promise { + try { + return await myFunctionThatReturnsResponse(); + } catch (e) { + ctx.waitUntil( + (async () => { + // report this error to your error tracking service + await fetch('https://my-error-tracking-service.com', { + method: 'POST', + body: JSON.stringify({ + stack: e.stack, + message: e.message, + name: e.name, + url: request.url, + }), + }); + })() + ); + return new Response('Internal Server Error', { status: 500 }); + } +} +``` + +#### Parameters + +| Name | Type | Description | +| :-------- | :---------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------- | +| `promise` | [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)<`unknown`\> | A promise that will be kept alive until it resolves or rejects. | + +#### Returns + +`void` + +#### Defined in + +[packages/edge/src/request.ts:47](https://github.com/vercel/vercel/blob/main/packages/edge/src/request.ts#L47) diff --git a/packages/edge/src/index.ts b/packages/edge/src/index.ts index e286ff4d5..8f5e55111 100644 --- a/packages/edge/src/index.ts +++ b/packages/edge/src/index.ts @@ -4,5 +4,6 @@ export * from './middleware-helpers'; export type { Geo } from './edge-headers'; export * from './edge-headers'; export * from './response'; +export type { RequestContext } from './request'; import './published-types.d.ts'; diff --git a/packages/edge/src/request.ts b/packages/edge/src/request.ts new file mode 100644 index 000000000..10b373f71 --- /dev/null +++ b/packages/edge/src/request.ts @@ -0,0 +1,52 @@ +/** + * An extension to the standard `Request` object that is passed to every Edge Function. + * + * @example + * ```ts + * import type { RequestContext } from '@vercel/edge'; + * + * export default async function handler(request: Request, ctx: RequestContext): Promise { + * // ctx is the RequestContext + * } + * ``` + */ +export interface RequestContext { + /** + * A method that can be used to keep the function running after a response has been sent. + * This is useful when you have an async task that you want to keep running even after the + * response has been sent and the request has ended. + * + * @example + * + * Sending an internal error to an error tracking service + * + * ```ts + * import type { RequestContext } from '@vercel/edge'; + * + * export async function handleRequest(request: Request, ctx: RequestContext): Promise { + * try { + * return await myFunctionThatReturnsResponse(); + * } catch (e) { + * ctx.waitUntil((async () => { + * // report this error to your error tracking service + * await fetch('https://my-error-tracking-service.com', { + * method: 'POST', + * body: JSON.stringify({ + * stack: e.stack, + * message: e.message, + * name: e.name, + * url: request.url, + * }), + * }); + * })()); + * return new Response('Internal Server Error', { status: 500 }); + * } + * } + * ``` + */ + waitUntil( + /** + * A promise that will be kept alive until it resolves or rejects. + */ promise: Promise + ): void; +}