Instant Validation | blade47/next.js Wiki | doc0

Public

Instant Validation | blade47/next.js Wiki | doc0

Configuration / Constant	Type	Meaning / Purpose
`VALIDATION_LEVEL.WARNING`	Enum (`0`)	Dev-time validation threshold used in `anySegmentNeedsInstantValidationInDev`.
`VALIDATION_LEVEL.ERROR`	Enum (`1`)	Build-time validation threshold used in `anySegmentNeedsInstantValidationInBuild`.
`unstable_disableValidation`	Boolean	Disables validation globally for the entire loader tree when encountered on any segment config.
`unstable_disableDevValidation`	Boolean	Disables validation specifically during development runs when `level === VALIDATION_LEVEL.WARNING`.
`unstable_disableBuildValidation`	Boolean	Disables validation specifically during build runs when `level === VALIDATION_LEVEL.ERROR`.
`prefetch: 'allow-runtime'`	String	Indicates runtime prefetch configuration checked by `anySegmentHasRuntimePrefetchEnabled`.

Design Choice	Benefit	Cost
Segment override without merging	Predictable, isolated sample definitions per page or layout without deep object merging overhead.	Outer layout samples cannot be augmented by child pages; child definitions completely replace parent ones.
Cache scoped to WorkStore	Avoids redundant loader tree walks during a single request or render context.	Cache lifetime is strictly bound to the duration of the active `WorkStore`.
Explicit framework error exclusion	Prevents unintended validation failures on framework-managed error UI without user configuration.	Framework error routes require explicit user opt-in via `instant` configs if validation is desired.

export function createCookiesFromSample(
  sampleCookies: InstantSample['cookies'],
  route: string
): ReadonlyRequestCookies {
  const declaredNames = new Set<string>()
 
  const cookies = new RequestCookies(new Headers())
  if (sampleCookies) {
    for (const cookie of sampleCookies) {
      declaredNames.add(cookie.name)
      if (cookie.value !== null) {
        cookies.set(cookie.name, cookie.value)
      }
    }
  }
 
  const sealed = RequestCookiesAdapter.seal(cookies)
 
  return new Proxy(sealed, {
    get(target, prop, receiver) {
      if (prop === 'has') {
        const originalMethod = Reflect.get(target, prop, receiver)
        const wrappedMethod: typeof originalMethod = function (name) {
          if (!declaredNames.has(name)) {
            trackMissingSampleErrorAndThrow(
              createMissingCookieSampleError(route, name)
            )
          }
          return originalMethod.call(target, name)
        }
        return wrappedMethod
      }
      if (prop === 'get') {
        // ...
      }
    }
  })
}

Segment Param Type	Handling Behavior	Error or Fallback
`catchall` / `optional-catchall`	Looks up `params[param.paramName]`, encodes array values.	Uses `[rawSegment]` as placeholder if undefined; throws `InstantValidationError` if value is not an array.
`dynamic`	Looks up `params[param.paramName]`, encodes string value.	Uses `rawSegment` as placeholder if undefined; throws `InstantValidationError` if value is not a string.
Intercepting route variants (`catchall-intercepted-`, `dynamic-intercepted-`)	Unsupported interception route validation.	Throws `InvariantError` with message `'Not implemented: Validation of interception routes'`.
Static segments	Appends raw segment directly to interpolated segments.	None.

Validation Function	Target Store Type	Action on Missing Declarations
`expectCompleteParamsInClientValidation`	`validation-client`	Calls `trackMissingSampleErrorAndThrow` with an `InstantValidationError` detailing missing fallback parameters.
`instrumentSearchParamsForClientValidation`	`validation-client`	Wraps `ReadonlyURLSearchParams` in an exhaustive search parameters proxy using declared sample keys.
`createServerParamsProxyForInstantValidation`	`request` / `validation`	Intercepts server-side `params` access using `createExhaustiveParamsProxy`.

Constant Name	Value	Purpose
`INSTANT_VALIDATION_BOUNDARY_NAME`	`__next_instant_validation_boundary__`	Component name identifier for instant validation boundaries in React stacks.
`INSTANT_SLOT_MARKER_PREFIX`	`__next_instant_slot_`	Prefix string for parallel layout slot marker components.
`INSTANT_SLOT_MARKER_SUFFIX`	`__`	Suffix string closing parallel layout slot marker components.

Design Choice	Benefit	Cost
Namespace object for boundary name	Retains exact function name at runtime despite production minification	Requires string slice trick (`.slice(0)`) to prevent bundler inlining
Context-based placement (`PlaceValidationBoundaryBelowThisLevel`)	Automatically propagates boundary placement down layout trees without manual wrapping	Relies on router cooperation (`OuterLayoutRouter`) to render validation boundaries
Cached slot marker generator (`slotMarkerCache`)	Avoids dynamic component creation overhead across re-renders	Retains references to generated marker components in memory for the process lifetime

function traverseRootSeedDataSegments(
  initialRSCPayload: InitialRSCPayload,
  processSegment: (
    segmentPath: SegmentPath,
    seedData: CacheNodeSeedData
  ) => void
) {
  const { flightRouterState, seedData } =
    getRootDataFromPayload(initialRSCPayload)
 
  const [rootSegment] = flightRouterState
  const rootPath = stringifySegment(rootSegment)
  return traverseCacheNodeSegments(
    rootPath,
    flightRouterState,
    seedData,
    processSegment
  )
}

function createChildSegmentPath(
  parentPath: SegmentPath,
  parallelRouteKey: string,
  segment: Segment
): SegmentPath {
  const parallelRoutePrefix =
    parallelRouteKey === 'children'
      ? ''
      : `@${encodeURIComponent(parallelRouteKey)}/`
  return `${parentPath}/${parallelRoutePrefix}${stringifySegment(segment)}` as SegmentPath
}

function stringifySegment(segment: Segment): SegmentPath {
  return (
    typeof segment === 'string'
      ? encodeURIComponent(segment)
      : encodeURIComponent(segment[0]) + '|' + segment[1] + '|' + segment[2]
  ) as SegmentPath
}

Export Name	Type / Values	Purpose
`SegmentPath`	`string & { _tag: 'SegmentPath' }`	Branded string type identifying a unique route segment path.
`RouteTree`	Object (`path`, `segment`, `module`, `slots`)	Isomorphic structure to `FlightRouterState` augmented with instant configuration metadata.
`SegmentStage`	`RenderStage.Static`, `RenderStage.Runtime`, `RenderStage.Dynamic`	Enumerated stages that route segments can traverse during rendering.
`StageChunks`	`Record<SegmentStage, Uint8Array[]>`	Mapping of render stages to accumulated binary chunk arrays.
`StageEndTimes`	`RecordrefetchedSegmentStage, number>`	Timing records tracking when prefetched segment stages complete.

Design Choice	Benefit	Cost
Stringified segment paths (`stringifySegment`)	Provides unique, cache-friendly string keys for tree lookups	Requires URI encoding and delimiter joining overhead per segment node
Global manifests singleton (`globalThis`)	Allows module-level server action and reference resolution without React context	Relies on global state mutation and explicit initialization order
Parallel route slot prefixing (`@slot/`)	Distinguishes parallel route branches cleanly within unified path strings	Lengthens path strings and requires special parsing rules for child segments

Export Name	Type / Value	Purpose
`INSTANT_VALIDATION_ERROR_DIGEST`	`'INSTANT_VALIDATION_ERROR'`	Constant string assigned to error digests for identification.
`isInstantValidationError`	`(err: unknown) => err is InstantValidationError`	Type guard verifying object type, `Error` instance, and matching digest.
`InstantValidationError`	Class extending `Error`	Custom error subclass carrying the validation error digest.