Skip to content
Source
Sign inSign up
TanStack/form
Open History to see the last commit

fieldTraversal.lib.ts

102 lines3.2 KB

1import type { AnyInternalFieldApi } from './FieldApi.lib'
2import type { InternalRootFieldApi } from './RootFieldApi.lib'
3​
4const stop = Symbol('stop field traversal')
5type FieldTraversalStop = typeof stop
6​
7type FieldVisitor = (
8 field: AnyInternalFieldApi,
9 stop: FieldTraversalStop,
10) => void | FieldTraversalStop
11​
12/**
13 * Visits a field node followed by each of its ancestors, stopping before the
14 * synthetic root node. Return the visitor's `stop` argument to stop the
15 * traversal.
16 *
17 * The next parent is captured before the visitor runs, so removing or
18 * reparenting the current node does not change the ancestor chain being walked.
19 */
20export function visitFieldAndAncestors(
21 field: AnyInternalFieldApi,
22 visitor: FieldVisitor,
23): void {
24 let current: AnyInternalFieldApi | InternalRootFieldApi = field
25​
26 while (!current._isRoot) {
27 const parent: AnyInternalFieldApi | InternalRootFieldApi = current._parent
28 if (visitor(current, stop) === stop) return
29 current = parent
30 }
32​
33/**
34 * Shared iterative trie walker for one or more starting field nodes. Starting
35 * nodes and every child collection are visited in insertion order. Children
36 * are pushed in reverse so the stack yields preorder without recursion.
37 */
38function visitFields(
39 fields: ReadonlyArray<AnyInternalFieldApi>,
40 visitor: FieldVisitor,
41): void {
42 const stack: Array<AnyInternalFieldApi> = []
43 for (let index = fields.length - 1; index >= 0; index--) {
44 stack.push(fields[index]!)
45 }
46​
47 while (stack.length > 0) {
48 const field = stack.pop()!
49 if (visitor(field, stop) === stop) return
50​
51 const children = field._children
52 for (let index = children.length - 1; index >= 0; index--) {
53 stack.push(children[index]!)
54 }
55 }
57​
58/**
59 * Visits a field node and its descendants in insertion-order preorder. The
60 * starting field is included. Return the visitor's `stop` argument to stop the
61 * entire traversal, not only the current branch.
62 *
63 * A node's children are read after its visitor runs, so structural mutations
64 * made by the visitor affect which descendants are visited.
65 */
66export function visitFieldSubtree(
67 field: AnyInternalFieldApi,
68 visitor: FieldVisitor,
69): void {
70 visitFields([field], visitor)
72​
73/**
74 * Visits every field in a form trie in insertion-order preorder. The synthetic
75 * root node is excluded; traversal starts at each of its field children. Return
76 * the visitor's `stop` argument to stop the entire traversal.
77 *
78 * A node's children are read after its visitor runs, so structural mutations
79 * made by the visitor affect which descendants are visited.
80 */
81export function visitAllFormFields(
82 root: InternalRootFieldApi,
83 visitor: FieldVisitor,
84): void {
85 visitFields(root._children, visitor)
87​
88/**
89 * Collects a field node and all of its descendants in insertion-order
90 * preorder. Use this when an operation needs a stable array of node references
91 * before it starts mutating the trie; use `visitFieldSubtree` when no snapshot
92 * allocation is required.
93 */
94export function collectFieldSubtree(
95 field: AnyInternalFieldApi,
96): Array<AnyInternalFieldApi> {
97 const fields: Array<AnyInternalFieldApi> = []
98 visitFieldSubtree(field, (current) => {
99 fields.push(current)
100 })
101 return fields