Async Request Context | blade47/next.js Wiki | doc0

Public

Async Request Context | blade47/next.js Wiki | doc0

const maybeGlobalAsyncLocalStorage =
  typeof globalThis !== 'undefined' && (globalThis as any).AsyncLocalStorage
 
export function createAsyncLocalStorage<
  Store extends {},
>(): AsyncLocalStorage<Store> {
  if (maybeGlobalAsyncLocalStorage) {
    return new maybeGlobalAsyncLocalStorage()
  }
  return new FakeAsyncLocalStorage()
}

Store Instance Module	Interface Type	Store Properties / Shape
`action-async-storage-instance.ts`	`ActionAsyncStorage`	`readonly isAction?: boolean`, `readonly isAppRoute?: boolean`
`console-async-storage-instance.ts`	`ConsoleAsyncStorage`	`readonly dim: boolean`
`dynamic-access-async-storage-instance.ts`	`DynamicAccessStorage`	`readonly abortController: AbortController`
`work-async-storage-instance.ts`	`WorkAsyncStorage`	Defined via external storage module
`work-unit-async-storage-instance.ts`	`WorkUnitAsyncStorage`	Defined via external storage module
`after-task-async-storage-instance.ts`	`AfterTaskAsyncStorage`	Defined via external storage module

export function bindSnapshot<T>(
  fn: T
): T {
  if (maybeGlobalAsyncLocalStorage) {
    return maybeGlobalAsyncLocalStorage.bind(fn)
  }
  return FakeAsyncLocalStorage.bind(fn)
}
 
export function createSnapshot(): <R, TArgs extends any[]>(
  fn: (...args: TArgs) => R,
  ...args: TArgs
) => R {
  if (maybeGlobalAsyncLocalStorage) {
    return maybeGlobalAsyncLocalStorage.snapshot()
  }
  return function (fn: any, ...args: any[]) {
    return fn(...args)
  }
}

function getHeaders(headers: Headers | IncomingHttpHeaders): ReadonlyHeaders {
  const cleaned = HeadersAdapter.from(headers)
  for (const header of FLIGHT_HEADERS) {
    cleaned.delete(header)
  }
 
  cleaned.delete(NEXT_REQUEST_ID_HEADER)
  cleaned.delete(NEXT_HTML_REQUEST_ID_HEADER)
 
  return HeadersAdapter.seal(cleaned)
}

function mergeMiddlewareCookies(
  headers: Headers | IncomingHttpHeaders,
  existingCookies: RequestCookies | ResponseCookies
) {
  if (
    'x-middleware-set-cookie' in headers &&
    typeof headers['x-middleware-set-cookie'] === 'string'
  ) {
    const setCookieValue = headers['x-middleware-set-cookie']
    const responseHeaders = new Headers()
 
    for (const cookie of splitCookiesString(setCookieValue)) {
      responseHeaders.append('set-cookie', cookie)
    }
 
    const responseCookies = new ResponseCookies(responseHeaders)
 
    for (const cookie of responseCookies.getAll()) {
      existingCookies.set(cookie)
    }
  }
}

const requestStore = createRequestStoreForAPI(
  request,
  request.nextUrl,
  implicitTags,
  onUpdateCookies,
  previewProps
)
 
return await workAsyncStorage.run(workStore, () =>
  workUnitAsyncStorage.run(
    requestStore,
    params.handler,
    request,
    event
  )
)

const workUnitStore = createRequestStore({
  phase: 'render',
  headers: new Headers(msg.request.headers),
  onUpdateCookies: undefined,
  url: { pathname: msg.request.urlPathname, search: msg.request.urlSearch },
  rootParams: msg.request.rootParams,
  implicitTags: { tags: [], expirationsByCacheKind: new Map() },
  resumeDataCache: null,
  previewProps: undefined,
  isHmrRefresh: msg.request.isHmrRefresh,
  serverComponentsHmrCache: undefined,
  fallbackParams: null,
})

Request Store Input Property	Expected Type / Shape	Purpose in Request Lifecycle
`phase`	`RequestStore['phase']`	Defines the current execution phase (e.g., `'render'`)
`headers`	`Headers \| IncomingHttpHeaders`	Raw request headers before adapter sanitization
`onUpdateCookies`	`((cookies: string[]) => void) \| undefined`	Callback invoked when userspace mutates cookies
`url`	`{ pathname: string; search?: string }`	Identifies the pathname and search components of the request URL
`rootParams`	`Params`	Root route parameters for the active render
`implicitTags`	`ImplicitTags`	Cache tags implicitly associated with the request route
`resumeDataCache`	`ResumeDataCache \| null`	Cache used for streaming resume data during rendering
`previewProps`	`__ApiPreviewProps \| undefined`	Configuration properties for draft and preview modes
`isHmrRefresh`	`boolean \| undefined`	Flag indicating whether the request stems from a Hot Module Replacement refresh
`serverComponentsHmrCache`	`ServerComponentsHmrCache \| undefined`	Cache storage for Server Components during development HMR
`fallbackParams`	`OpaqueFallbackRouteParams \| null \| undefined`	Opaque fallback parameters for static paths

WorkStore Property	Type	Purpose / Description
`isStaticGeneration`	`boolean`	Determines if the current pass is a static prerender.
`page`	`string`	File path relative to the page being rendered.
`route`	`string`	Normalized route path without trailing `/page` or `/route`.
`incrementalCache`	`IncrementalCache \| undefined`	Global or local incremental cache instance.
`useCacheTimeout`	`number`	Timeout limit in milliseconds for `"use cache"` executions.
`staticPageGenerationTimeout`	`number`	Timeout limit for static page generation.
`pendingCacheInvocations`	`Map<string, Promise<SharedCacheResult>>`	Intra-request deduplication map keyed by coarse cache key.
`runInCleanSnapshot`	`(<R, TArgs extends any[]>(fn: (...args: TArgs) => R, ...args: TArgs) => R)`	Executes functions inside a clean `AsyncLocalStorage` snapshot.

WorkUnitStore Type	Identifier String	Scope & Behavior
`RequestStore`	`'request'`	Represents an active HTTP request with cookies, headers, and resume cache.
`PublicUseCacheStore`	`'cache'`	Public `"use cache"` boundary isolating requests from cached output.
`PrivateUseCacheStore`	`'private-cache'`	Private cache boundary retaining scoped headers, cookies, and root parameters.
`UnstableCacheStore`	`'unstable-cache'`	Legacy `unstable_cache` scope where root parameters are `undefined`.
`PrerenderStore`	`'prerender'`, `'prerender-ppr'`, etc.	Manages static prerendering, streaming, and staged rendering controllers.
`GenerateStaticParamsStore`	`'generate-static-params'`	Tracks generation parameters (`rootParams`) during static path generation.

function generateCacheEntry(
  workStore: WorkStore,
  cacheContext: CacheContext,
  clientReferenceManifest: DeepReadonly<ClientReferenceManifest>,
  encodedArguments: FormData | string,
  fn: (...args: unknown[]) => Promise<unknown>,
  timeoutError: UseCacheTimeoutError,
  deadlockError: UseCacheDeadlockError | undefined
) {
  return workStore.runInCleanSnapshot(
    generateCacheEntryWithRestoredWorkStore,
    workStore,
    cacheContext,
    clientReferenceManifest,
    encodedArguments,
    fn,
    timeoutError,
    deadlockError
  )
}

Instrumenting Function	Target Promise Type	Properties / Symbols Intercepted
`instrumentHeadersPromiseWithDevWarnings`	`Promise<ReadonlyHeaders>`	`Symbol.iterator`, `append`, `delete`, `get`, `has`, `set`, `getSetCookie`, `forEach`, `keys`, `values`, `entries`
`instrumentCookiesPromiseWithDevWarnings`	`Promise<ReadonlyRequestCookies>`	`Symbol.iterator`, `size`, `get`, `getAll`, `has`, `set`, `delete`, `clear`, `toString`

Option / Property	Type	Description
`waitUntil`	`RequestLifecycleOpts['waitUntil'] \| undefined`	Platform function to extend the lifetime of the request worker for promises and callback execution.
`onClose`	`RequestLifecycleOpts['onClose']`	Handler triggered when the request connection closes, initiating callback execution.
`onTaskError`	`RequestLifecycleOpts['onAfterTaskError'] \| undefined`	Custom error handler invoked if a background task or promise rejects.
`callbackQueue`	`PromiseQueue`	Internal queue managing callback execution order and concurrency.
`workUnitStores`	`Set<WorkUnitStore>`	Set tracking associated work unit stores whose phases transition to `'after'` during execution.

export class AfterRunner {
  private awaiter = new AwaiterOnce()
  private closeController = new CloseController()
  private finishedWithoutErrors = new DetachedPromise<void>()
 
  readonly context: Ctx = {
    waitUntil: this.awaiter.waitUntil.bind(this.awaiter),
    onClose: this.closeController.onClose.bind(this.closeController),
    onTaskError: (error) => this.finishedWithoutErrors.reject(error),
  }
 
  public async executeAfter() {
    this.closeController.dispatchClose()
    await this.awaiter.awaiting()
 
    this.finishedWithoutErrors.resolve()
 
    return this.finishedWithoutErrors.promise
  }
}