Unverified Commit e6472952 authored by Tim Neutkens's avatar Tim Neutkens Committed by GitHub

Add additional comments for reducer/cachenode (#39065)

- Add additional comments for reducer functions.
- Add comments for CacheNode



## Bug

- [ ] Related issues linked using `fixes #number`
- [ ] Integration tests added
- [ ] Errors have helpful link attached, see `contributing.md`

## Feature

- [ ] Implements an existing feature request or RFC. Make sure the feature request has been accepted for implementation before opening a PR.
- [ ] Related issues linked using `fixes #number`
- [ ] Integration tests added
- [ ] Documentation added
- [ ] Telemetry added. In case of a feature if it's used or not.
- [ ] Errors have helpful link attached, see `contributing.md`

## Documentation / Examples

- [ ] Make sure the linting passes by running `pnpm lint`
- [ ] The examples guidelines are followed from [our contributing doc](https://github.com/vercel/next.js/blob/canary/contributing.md#adding-examples)
parent 8fc8a6c8
...@@ -7,6 +7,9 @@ import type { ...@@ -7,6 +7,9 @@ import type {
import { matchSegment } from './match-segments' import { matchSegment } from './match-segments'
import { fetchServerResponse } from './app-router.client' import { fetchServerResponse } from './app-router.client'
/**
* Fill cache with subTreeData based on flightDataPath
*/
function fillCacheWithNewSubTreeData( function fillCacheWithNewSubTreeData(
newCache: CacheNode, newCache: CacheNode,
existingCache: CacheNode, existingCache: CacheNode,
...@@ -73,6 +76,9 @@ function fillCacheWithNewSubTreeData( ...@@ -73,6 +76,9 @@ function fillCacheWithNewSubTreeData(
) )
} }
/**
* Kick off fetch based on the common layout between two routes. Fill cache with data property holding the in-progress fetch.
*/
function fillCacheWithDataProperty( function fillCacheWithDataProperty(
newCache: CacheNode, newCache: CacheNode,
existingCache: CacheNode, existingCache: CacheNode,
...@@ -148,6 +154,10 @@ function fillCacheWithDataProperty( ...@@ -148,6 +154,10 @@ function fillCacheWithDataProperty(
) )
} }
/**
* Decide if the segments can be optimistically rendered, kicking off the fetch in layout-router.
* - When somewhere in the path to the segment there is a loading.js this becomes true
*/
function canOptimisticallyRender( function canOptimisticallyRender(
segments: string[], segments: string[],
flightRouterState: FlightRouterState flightRouterState: FlightRouterState
...@@ -186,6 +196,10 @@ function canOptimisticallyRender( ...@@ -186,6 +196,10 @@ function canOptimisticallyRender(
) )
} }
/**
* Create optimistic version of router state based on the existing router state and segments.
* This is used to allow rendering layout-routers up till the point where data is missing.
*/
function createOptimisticTree( function createOptimisticTree(
segments: string[], segments: string[],
flightRouterState: FlightRouterState | null, flightRouterState: FlightRouterState | null,
...@@ -246,7 +260,10 @@ function createOptimisticTree( ...@@ -246,7 +260,10 @@ function createOptimisticTree(
return result return result
} }
function walkTreeWithFlightDataPath( /**
* Apply the router state from the Flight response. Creates a new router state tree.
*/
function applyRouterStatePatchToTree(
flightSegmentPath: FlightData[0], flightSegmentPath: FlightData[0],
flightRouterState: FlightRouterState, flightRouterState: FlightRouterState,
treePatch: FlightRouterState treePatch: FlightRouterState
...@@ -279,7 +296,7 @@ function walkTreeWithFlightDataPath( ...@@ -279,7 +296,7 @@ function walkTreeWithFlightDataPath(
...parallelRoutes, ...parallelRoutes,
[parallelRouteKey]: lastSegment [parallelRouteKey]: lastSegment
? treePatch ? treePatch
: walkTreeWithFlightDataPath( : applyRouterStatePatchToTree(
flightSegmentPath.slice(2), flightSegmentPath.slice(2),
parallelRoutes[parallelRouteKey], parallelRoutes[parallelRouteKey],
treePatch treePatch
...@@ -299,17 +316,6 @@ function walkTreeWithFlightDataPath( ...@@ -299,17 +316,6 @@ function walkTreeWithFlightDataPath(
return tree return tree
} }
type PushRef = {
/**
* If the app-router should push a new history entry in app-router's useEffect()
*/
pendingPush: boolean
/**
* Multi-page navigation through location.href.
*/
mpaNavigation: boolean
}
export type FocusAndScrollRef = { export type FocusAndScrollRef = {
/** /**
* If focus and scroll should be set in the layout-router's useEffect() * If focus and scroll should be set in the layout-router's useEffect()
...@@ -317,14 +323,6 @@ export type FocusAndScrollRef = { ...@@ -317,14 +323,6 @@ export type FocusAndScrollRef = {
apply: boolean apply: boolean
} }
type AppRouterState = {
tree: FlightRouterState
cache: CacheNode
pushRef: PushRef
focusAndScrollRef: FocusAndScrollRef
canonicalUrl: string
}
export const ACTION_RELOAD = 'reload' export const ACTION_RELOAD = 'reload'
export const ACTION_NAVIGATE = 'navigate' export const ACTION_NAVIGATE = 'navigate'
export const ACTION_RESTORE = 'restore' export const ACTION_RESTORE = 'restore'
...@@ -407,6 +405,47 @@ interface ServerPatchAction { ...@@ -407,6 +405,47 @@ interface ServerPatchAction {
cache: CacheNode cache: CacheNode
} }
interface PushRef {
/**
* If the app-router should push a new history entry in app-router's useEffect()
*/
pendingPush: boolean
/**
* Multi-page navigation through location.href.
*/
mpaNavigation: boolean
}
/**
* Handles keeping the state of app-router.
*/
type AppRouterState = {
/**
* The router state, this is written into the history state in app-router using replaceState/pushState.
* - Has to be serializable as it is written into the history state.
* - Holds which segments are shown on the screen.
* - Holds where loading states (loading.js) exists.
*/
tree: FlightRouterState
/**
* The cache holds React nodes for every segment that is shown on screen as well as previously shown segments and prefetched segments.
* It also holds in-progress data requests.
*/
cache: CacheNode
/**
* Decides if the update should create a new history entry and if the navigation can't be handled by app-router.
*/
pushRef: PushRef
/**
* Decides if the update should apply scroll and focus management.
*/
focusAndScrollRef: FocusAndScrollRef
/**
* The canonical url that is pushed/replaced
*/
canonicalUrl: string
}
/** /**
* Reducer that handles the app-router state updates. * Reducer that handles the app-router state updates.
*/ */
...@@ -575,7 +614,7 @@ export function reducer( ...@@ -575,7 +614,7 @@ export function reducer(
const flightSegmentPath = flightDataPath.slice(0, -3) const flightSegmentPath = flightDataPath.slice(0, -3)
// Create new tree based on the flightSegmentPath and router state patch // Create new tree based on the flightSegmentPath and router state patch
const newTree = walkTreeWithFlightDataPath( const newTree = applyRouterStatePatchToTree(
// TODO-APP: remove '' // TODO-APP: remove ''
['', ...flightSegmentPath], ['', ...flightSegmentPath],
state.tree, state.tree,
...@@ -641,7 +680,7 @@ export function reducer( ...@@ -641,7 +680,7 @@ export function reducer(
const treePath = flightDataPath.slice(0, -3) const treePath = flightDataPath.slice(0, -3)
const [treePatch] = flightDataPath.slice(-2) const [treePatch] = flightDataPath.slice(-2)
const newTree = walkTreeWithFlightDataPath( const newTree = applyRouterStatePatchToTree(
// TODO-APP: remove '' // TODO-APP: remove ''
['', ...treePath], ['', ...treePath],
state.tree, state.tree,
...@@ -726,7 +765,7 @@ export function reducer( ...@@ -726,7 +765,7 @@ export function reducer(
// Given the path can only have two items the items are only the router state and subTreeData for the root. // Given the path can only have two items the items are only the router state and subTreeData for the root.
const [treePatch, subTreeData] = flightDataPath const [treePatch, subTreeData] = flightDataPath
const newTree = walkTreeWithFlightDataPath( const newTree = applyRouterStatePatchToTree(
// TODO-APP: remove '' // TODO-APP: remove ''
[''], [''],
state.tree, state.tree,
......
...@@ -246,6 +246,9 @@ type DynamicParamTypes = 'catchall' | 'optional-catchall' | 'dynamic' ...@@ -246,6 +246,9 @@ type DynamicParamTypes = 'catchall' | 'optional-catchall' | 'dynamic'
// d = dynamic // d = dynamic
export type DynamicParamTypesShort = 'c' | 'oc' | 'd' export type DynamicParamTypesShort = 'c' | 'oc' | 'd'
/**
* Shorten the dynamic param in order to make it smaller when transmitted to the browser.
*/
function getShortDynamicParamType( function getShortDynamicParamType(
type: DynamicParamTypes type: DynamicParamTypes
): DynamicParamTypesShort { ): DynamicParamTypesShort {
...@@ -261,10 +264,16 @@ function getShortDynamicParamType( ...@@ -261,10 +264,16 @@ function getShortDynamicParamType(
} }
} }
/**
* Segment in the router state.
*/
export type Segment = export type Segment =
| string | string
| [param: string, value: string, type: DynamicParamTypesShort] | [param: string, value: string, type: DynamicParamTypesShort]
/**
* LoaderTree is generated in next-app-loader.
*/
type LoaderTree = [ type LoaderTree = [
segment: string, segment: string,
parallelRoutes: { [parallelRouterKey: string]: LoaderTree }, parallelRoutes: { [parallelRouterKey: string]: LoaderTree },
...@@ -275,6 +284,9 @@ type LoaderTree = [ ...@@ -275,6 +284,9 @@ type LoaderTree = [
} }
] ]
/**
* Router state
*/
export type FlightRouterState = [ export type FlightRouterState = [
segment: Segment, segment: Segment,
parallelRoutes: { [parallelRouterKey: string]: FlightRouterState }, parallelRoutes: { [parallelRouterKey: string]: FlightRouterState },
...@@ -283,7 +295,11 @@ export type FlightRouterState = [ ...@@ -283,7 +295,11 @@ export type FlightRouterState = [
loading?: 'loading' loading?: 'loading'
] ]
/**
* Individual Flight response path
*/
export type FlightSegmentPath = export type FlightSegmentPath =
// Uses `any` as repeating pattern can't be typed.
| any[] | any[]
// Looks somewhat like this // Looks somewhat like this
| [ | [
...@@ -296,21 +312,25 @@ export type FlightSegmentPath = ...@@ -296,21 +312,25 @@ export type FlightSegmentPath =
] ]
export type FlightDataPath = export type FlightDataPath =
// Uses `any` as repeating pattern can't be typed.
| any[] | any[]
// Looks somewhat like this // Looks somewhat like this
| [ | [
segment: Segment, // Holds full path to the segment.
parallelRoute: string, ...FlightSegmentPath,
segment: Segment, /* segment of the rendered slice: */ Segment,
parallelRoute: string, /* treePatch */ FlightRouterState,
segment: Segment, /* subTreeData: */ React.ReactNode
parallelRoute: string,
currentSegment: Segment,
tree: FlightRouterState,
subTreeData: React.ReactNode
] ]
/**
* The Flight response data
*/
export type FlightData = Array<FlightDataPath> | string export type FlightData = Array<FlightDataPath> | string
/**
* Property holding the current subTreeData.
*/
export type ChildProp = { export type ChildProp = {
current: React.ReactNode current: React.ReactNode
segment: Segment segment: Segment
......
...@@ -4,11 +4,23 @@ import type { FlightRouterState, FlightData } from '../../server/app-render' ...@@ -4,11 +4,23 @@ import type { FlightRouterState, FlightData } from '../../server/app-render'
export type ChildSegmentMap = Map<string, CacheNode> export type ChildSegmentMap = Map<string, CacheNode>
/**
* Cache node used in app-router / layout-router.
*/
export type CacheNode = { export type CacheNode = {
/**
* In-flight request for this node.
*/
data: ReturnType< data: ReturnType<
typeof import('../../client/components/app-router.client').fetchServerResponse typeof import('../../client/components/app-router.client').fetchServerResponse
> | null > | null
subTreeData: null | React.ReactNode /**
* React Component for this node.
*/
subTreeData: React.ReactNode | null
/**
* Child parallel routes.
*/
parallelRoutes: Map<string, ChildSegmentMap> parallelRoutes: Map<string, ChildSegmentMap>
} }
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment