dirvi-lib 0.3.0 → 0.5.0

package/dist/tree-surfer/nav-node/nav-node.types.d.ts

@@ -0,0 +1,42 @@
+import { LeafTreeNode, SerializableKey, TreeNode } from '../tree-node/tree-node.types.js';
+import { FoldNodeRoot } from '../fold-node/fold-node.types.js';
+import { Cursor } from '../cursor.js';
+/**
+ * A navigation entry preserves the original buffer-node properties, but
+ * replaces a branch's buffer children with a NavNode.
+ */
+export type NavEntry<Id extends SerializableKey, BufferNode extends TreeNode<Id, BufferNode>> = NavLeaf<Id, BufferNode> | NavBranch<Id, BufferNode>;
+export type NavLeaf<Id extends SerializableKey, BufferNode extends TreeNode<Id, BufferNode>> = BufferNode & LeafTreeNode<Id>;
+type ReplaceChildren<Node, Children> = Node extends {
+    children: unknown;
+} ? Omit<Node, 'children'> & {
+    children: Children;
+} : never;
+export type NavBranch<Id extends SerializableKey, BufferNode extends TreeNode<Id, BufferNode>> = ReplaceChildren<BufferNode, NavNode<Id, BufferNode> | null>;
+export declare function isNavBranch<Id extends SerializableKey, BufferNode extends TreeNode<Id, BufferNode>>(entry: NavEntry<Id, BufferNode>): entry is NavBranch<Id, BufferNode>;
+/**
+ * The derived tree as navigated: list of visible entries and folded entries.
+ */
+export type NavNode<Id extends SerializableKey, BufferNode extends TreeNode<Id, BufferNode>> = {
+    /**
+     * Currently visible entries.
+     */
+    entries: NavEntry<Id, BufferNode>[];
+    /**
+     * Currently loaded entries hidden by this directory's fold.
+     */
+    foldedEntries: NavEntry<Id, BufferNode>[];
+};
+export type NavNodeApi<Id extends SerializableKey, BufferNode extends TreeNode<Id, BufferNode>> = {
+    from(entries: BufferNode[], foldNode: FoldNodeRoot<Id>): NavNode<Id, BufferNode>;
+    getNodeAtPath(navigation: NavNode<Id, BufferNode>, path: Id[]): NavNode<Id, BufferNode> | undefined;
+    getEntryAtPath(navigation: NavNode<Id, BufferNode>, path: Id[]): NavEntry<Id, BufferNode> | undefined;
+    nextCursor(rootNode: NavNode<Id, BufferNode>, cursor: Cursor<Id>): Cursor<Id> | undefined;
+    previousCursor(rootNode: NavNode<Id, BufferNode>, cursor: Cursor<Id>): Cursor<Id> | undefined;
+    cursorAfterFold(rootNode: NavNode<Id, BufferNode>, cursor: Cursor<Id>): Cursor<Id> | undefined;
+    parentCursor(navigation: NavNode<Id, BufferNode>, cursor: Cursor<Id>): Cursor<Id> | undefined;
+    cursors(navigation: NavNode<Id, BufferNode>, parentPath?: Id[]): Cursor<Id>[];
+    visibleLeavesPaths(navigation: NavNode<Id, BufferNode>, parentPath?: Id[]): Id[][];
+};
+export {};
+//# sourceMappingURL=nav-node.types.d.ts.map

package/dist/tree-surfer/nav-node/nav-node.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nav-node.types.d.ts","sourceRoot":"","sources":["../../../src/tree-surfer/nav-node/nav-node.types.ts"],"names":[],"mappings":"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"}

package/dist/tree-surfer/nav-node/nav-node.types.js

@@ -0,0 +1,3 @@
+export function isNavBranch(entry) {
+    return 'children' in entry;
+}

package/dist/tree-surfer/state.d.ts

@@ -0,0 +1,19 @@
+import { Cursor, CursorApi } from './cursor.js';
+import { SerializableKey, TreeNode, TreeNodeApi } from './tree-node/tree-node.types.js';
+import { FoldNodeApi, FoldNodeRoot } from './fold-node/fold-node.types.js';
+import { NavNodeApi } from './nav-node/nav-node.types.js';
+export type State<Id extends SerializableKey, BufferNode extends TreeNode<Id, BufferNode>> = {
+    buffer: BufferNode[];
+    foldNode: FoldNodeRoot<Id>;
+    cursor: Cursor<Id>;
+};
+export type StateApi<Id extends SerializableKey, BufferNode extends TreeNode<Id, BufferNode>> = {
+    getNodeAtCursor(state: State<Id, BufferNode>): BufferNode | undefined;
+    /**
+     * Reloads the root and all descendant branches that were loaded in the
+     * previous state.
+     */
+    resync(oldState: State<Id, BufferNode>, loadBranches: (path: Id[]) => Promise<BufferNode[]>): Promise<State<Id, BufferNode>>;
+};
+export declare function createStateApi<Id extends SerializableKey, BufferNode extends TreeNode<Id, BufferNode>>(treeNodeApi: TreeNodeApi<Id, BufferNode>, foldNodeApi: FoldNodeApi<Id>, cursorApi: CursorApi<Id>, navNodeApi: NavNodeApi<Id, BufferNode>): StateApi<Id, BufferNode>;
+//# sourceMappingURL=state.d.ts.map

package/dist/tree-surfer/state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../../src/tree-surfer/state.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,SAAS,EAAc,MAAM,aAAa,CAAC;AAC5D,OAAO,EAAE,eAAe,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,gCAAgC,CAAC;AACxF,OAAO,EAAY,WAAW,EAAE,YAAY,EAAE,MAAM,gCAAgC,CAAC;AACrF,OAAO,EAAE,UAAU,EAAE,MAAM,8BAA8B,CAAC;AAE1D,MAAM,MAAM,KAAK,CACf,EAAE,SAAS,eAAe,EAC1B,UAAU,SAAS,QAAQ,CAAC,EAAE,EAAE,UAAU,CAAC,IACzC;IACF,MAAM,EAAE,UAAU,EAAE,CAAC;IACrB,QAAQ,EAAE,YAAY,CAAC,EAAE,CAAC,CAAC;IAC3B,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,QAAQ,CAClB,EAAE,SAAS,eAAe,EAC1B,UAAU,SAAS,QAAQ,CAAC,EAAE,EAAE,UAAU,CAAC,IACzC;IACF,eAAe,CAAC,KAAK,EAAE,KAAK,CAAC,EAAE,EAAE,UAAU,CAAC,GAAG,UAAU,GAAG,SAAS,CAAC;IAEtE;;;OAGG;IACH,MAAM,CACJ,QAAQ,EAAE,KAAK,CAAC,EAAE,EAAE,UAAU,CAAC,EAC/B,YAAY,EAAE,CAAC,IAAI,EAAE,EAAE,EAAE,KAAK,OAAO,CAAC,UAAU,EAAE,CAAC,GAClD,OAAO,CAAC,KAAK,CAAC,EAAE,EAAE,UAAU,CAAC,CAAC,CAAC;CACnC,CAAC;AAEF,wBAAgB,cAAc,CAC5B,EAAE,SAAS,eAAe,EAC1B,UAAU,SAAS,QAAQ,CAAC,EAAE,EAAE,UAAU,CAAC,EAE3C,WAAW,EAAE,WAAW,CAAC,EAAE,EAAE,UAAU,CAAC,EACxC,WAAW,EAAE,WAAW,CAAC,EAAE,CAAC,EAC5B,SAAS,EAAE,SAAS,CAAC,EAAE,CAAC,EACxB,UAAU,EAAE,UAAU,CAAC,EAAE,EAAE,UAAU,CAAC,GACrC,QAAQ,CAAC,EAAE,EAAE,UAAU,CAAC,CAoK1B"}

package/dist/tree-surfer/state.js

@@ -0,0 +1,109 @@
+import { CursorKind } from './cursor.js';
+export function createStateApi(treeNodeApi, foldNodeApi, cursorApi, navNodeApi) {
+    // Helpers
+    /**
+     * Create a new buffer and fold node at this level.
+     *
+     * Works on fold root and child level through the generic.
+     */
+    async function reload(oldBuffer, oldFoldNode, // Can be FoldNode too
+    parentPath, loadBranches) {
+        let newBufferAtRoot = await loadBranches(parentPath);
+        let newFoldNode = oldFoldNode; // Start with assumption of no changes
+        /**
+         * Reload descendants that were already loaded in the old buffer.
+         *
+         * Fold membership is represented by IDs in `folds`, so it remains
+         * valid across a reload without rebuilding an entry array.
+         */
+        for (const oldEntry of oldBuffer) {
+            // If it wasn't an open branch, then there's no need to reload descendants.
+            // Either the new entry is a leaf or an unopen branch.
+            if (!treeNodeApi.isBranch(oldEntry) ||
+                !treeNodeApi.isOpenBranch(oldEntry)) {
+                continue;
+            }
+            // Get the entry being updated, in the new buffer
+            const newEntry = treeNodeApi.getAtPath(newBufferAtRoot, [oldEntry.id], (entry) => entry);
+            // If it doesn't exist (an open branch was deleted) then move on
+            if (newEntry === undefined) {
+                continue;
+            }
+            // The old entry may have changed into a leaf.
+            // A newly loaded branch is normally closed here because loadBranches
+            // returns flat entries, and the descendants are to be attached below.
+            if (!treeNodeApi.isBranch(newEntry)) {
+                continue;
+            }
+            const oldChildFoldNode = oldFoldNode === undefined
+                ? undefined
+                : foldNodeApi.getChildById(oldFoldNode, oldEntry.id);
+            const entryPath = [...parentPath, oldEntry.id];
+            const reloadedChild = await reload([...treeNodeApi.getChildren(oldEntry)], oldChildFoldNode, entryPath, loadBranches);
+            const updatedBuffer = treeNodeApi.modifyAtPath(newBufferAtRoot, [oldEntry.id], (entry) => {
+                // The entry may be closed: loadBranches normally returns branches
+                // with `branches: null`. We are turning it back into an open branch.
+                if (!treeNodeApi.isBranch(entry)) {
+                    return undefined;
+                }
+                return {
+                    ...entry,
+                    branches: reloadedChild.buffer,
+                };
+            });
+            if (updatedBuffer !== undefined) {
+                newBufferAtRoot = updatedBuffer;
+            }
+        }
+        return {
+            buffer: newBufferAtRoot,
+            foldNode: newFoldNode,
+        };
+    }
+    /**
+     * Currently the cursor just goes to the first entry at root if
+     * not all root entries are folded, otherwise the fold.
+     *
+     * TODO: Cursor policy:
+     * 1. Keep the exact cursor if it survives,
+     * 2. Otherwise, choose the deepest surviving ancestor entry,
+     * 3. Otherwise, choose the nearest preceding old cursor that still survives,
+     * 4. Otherwise, choose the first new cursor.
+     * 5. If no cursor exists, use the root fold cursor.
+     */
+    function resyncCursor(oldState, newBuffer, newFoldNode) {
+        const navigation = navNodeApi.from(newBuffer, newFoldNode);
+        return navNodeApi.cursors(navigation)[0];
+    }
+    return {
+        getNodeAtCursor(state) {
+            const path = cursorApi.getPath(state.cursor);
+            if (path === undefined) {
+                // The cursor is positioned on a fold rather than an entry.
+                return undefined;
+            }
+            return treeNodeApi.getAtPath(state.buffer, path, (node) => node);
+        },
+        async resync(oldState, loadBranches) {
+            const reloaded = await reload(oldState.buffer, oldState.foldNode, [], loadBranches);
+            /*
+             * `oldState.foldNode` is always present. At the root reload starts with
+             * that node, so `reloaded.foldNode` should also always be present.
+             *
+             * The fallback expresses the State invariant while satisfying the
+             * optional return type needed by recursive child reloads.
+             */
+            const foldNode = reloaded.foldNode ?? oldState.foldNode;
+            const cursor = resyncCursor(oldState, reloaded.buffer, foldNode) ?? {
+                kind: CursorKind.Fold,
+                parentPath: [],
+            };
+            return {
+                ...oldState,
+                buffer: reloaded.buffer,
+                foldNode,
+                cursor,
+            };
+        },
+    };
+}

package/dist/tree-surfer/tree-node/tree-node.arb.d.ts

@@ -0,0 +1,31 @@
+import * as fc from 'fast-check';
+import type { TreeNode } from './tree-node.types.js';
+export type StringNode = TreeNode<string, StringNode>;
+export type PathEntry = {
+    path: string[];
+    node: StringNode;
+};
+export type GeneratedNode = {
+    node: StringNode;
+    pathEntries: PathEntry[];
+};
+export declare const idArb: fc.Arbitrary<string>;
+export declare const generatedNodeArb: fc.Arbitrary<GeneratedNode>;
+export declare const generatedNodesArrayArb: fc.Arbitrary<GeneratedNode[]>;
+export declare const forestAndPathsArb: fc.Arbitrary<{
+    entries: any[];
+    pathEntries: PathEntry[];
+}>;
+export declare const forestAndPathAndExpectedArb: fc.Arbitrary<{
+    entries: any[];
+    path: string[];
+    expected: any;
+}>;
+export declare const nodesArrayAndBranchPathArb: fc.Arbitrary<{
+    entries: any[];
+    path: string[];
+    expected: any;
+}>;
+export declare const newBranchesArb: fc.Arbitrary<any[]>;
+export declare const newBranchesOrNullArb: fc.Arbitrary<any[] | null>;
+//# sourceMappingURL=tree-node.arb.d.ts.map

package/dist/tree-surfer/tree-node/tree-node.arb.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree-node.arb.d.ts","sourceRoot":"","sources":["../../../src/tree-surfer/tree-node/tree-node.arb.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,YAAY,CAAC;AAEjC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAGrD,MAAM,MAAM,UAAU,GAAG,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;AAEtD,MAAM,MAAM,SAAS,GAAG;IACtB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,IAAI,EAAE,UAAU,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,IAAI,EAAE,UAAU,CAAC;IACjB,WAAW,EAAE,SAAS,EAAE,CAAC;CAC1B,CAAC;AAEF,eAAO,MAAM,KAAK,sBAGhB,CAAC;AAEH,eAAO,MAAM,gBAAgB,EAAE,EAAE,CAAC,SAAS,CAAC,aAAa,CA4DjD,CAAC;AAET,eAAO,MAAM,sBAAsB,+BAIjC,CAAC;AAEH,eAAO,MAAM,iBAAiB;;;EAK7B,CAAC;AAEF,eAAO,MAAM,2BAA2B;;;;EAQrC,CAAC;AAEJ,eAAO,MAAM,0BAA0B;;;;EAYpC,CAAC;AAEJ,eAAO,MAAM,cAAc,qBAE1B,CAAC;AAEF,eAAO,MAAM,oBAAoB,4BAA8C,CAAC"}

package/dist/tree-surfer/tree-node/tree-node.arb.js

@@ -0,0 +1,80 @@
+import * as fc from 'fast-check';
+export const idArb = fc.string({
+    minLength: 1,
+    maxLength: 8,
+});
+export const generatedNodeArb = fc.letrec((tie) => ({
+    node: fc.oneof(idArb.map((id) => {
+        const node = { id: id };
+        return {
+            node,
+            pathEntries: [
+                {
+                    path: [id],
+                    node,
+                },
+            ],
+        };
+    }), fc
+        .tuple(idArb, fc.oneof(fc.constant(null), fc.uniqueArray(tie('node'), {
+        minLength: 0,
+        size: 'medium',
+        // @ts-ignore
+        selector: (generated) => generated.node.id,
+    })))
+        .map(([id, children]) => {
+        const node = {
+            id,
+            children: 
+            // @ts-ignore
+            children === null ? null : children.map((child) => child.node),
+        };
+        const descendantPathEntries = children === null
+            ? []
+            : children.flatMap((child) => 
+            // @ts-ignore
+            child.pathEntries.map(({ path, node }) => ({
+                path: [id, ...path],
+                node,
+            })));
+        return {
+            node,
+            pathEntries: [
+                {
+                    path: [id],
+                    node,
+                },
+                ...descendantPathEntries,
+            ],
+        };
+    })),
+})).node;
+export const generatedNodesArrayArb = fc.uniqueArray(generatedNodeArb, {
+    minLength: 0,
+    size: 'small',
+    selector: (generated) => generated.node.id,
+});
+export const forestAndPathsArb = generatedNodesArrayArb.map((generatedNodes) => ({
+    entries: generatedNodes.map((generated) => generated.node),
+    pathEntries: generatedNodes.flatMap((generated) => generated.pathEntries),
+}));
+export const forestAndPathAndExpectedArb = forestAndPathsArb
+    .filter(({ pathEntries }) => pathEntries.length > 0)
+    .chain(({ entries, pathEntries }) => fc.constantFrom(...pathEntries).map(({ path, node }) => ({
+    entries,
+    path,
+    expected: node,
+})));
+export const nodesArrayAndBranchPathArb = forestAndPathsArb
+    .map(({ entries, pathEntries }) => ({
+    entries,
+    branchPathEntries: pathEntries.filter(({ node }) => 'children' in node),
+}))
+    .filter(({ branchPathEntries }) => branchPathEntries.length > 0)
+    .chain(({ entries, branchPathEntries }) => fc.constantFrom(...branchPathEntries).map(({ path, node }) => ({
+    entries,
+    path,
+    expected: node,
+})));
+export const newBranchesArb = generatedNodesArrayArb.map((generatedNodes) => generatedNodes.map(({ node }) => node));
+export const newBranchesOrNullArb = fc.oneof(newBranchesArb, fc.constant(null));

package/dist/tree-surfer/tree-node/tree-node.impl.d.ts

@@ -0,0 +1,13 @@
+import type { SerializableKey, TreeNode, TreeNodeApi } from './tree-node.types.js';
+/**
+ * Creates an API for inspecting and immutably updating tree nodes.
+ *
+ * Tree updates do not mutate the supplied forest or its nodes. Updated
+ * arrays and ancestor nodes are created as needed, while unrelated nodes
+ * retain their original object identity.
+ *
+ * Node IDs are compared using JavaScript value equality. Sibling IDs
+ * should be unique.
+ */
+export declare function createTreeNodeApi<Id extends SerializableKey, ChildNode extends TreeNode<Id, ChildNode>>(): TreeNodeApi<Id, ChildNode>;
+//# sourceMappingURL=tree-node.impl.d.ts.map

package/dist/tree-surfer/tree-node/tree-node.impl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree-node.impl.d.ts","sourceRoot":"","sources":["../../../src/tree-surfer/tree-node/tree-node.impl.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAIU,eAAe,EACnC,QAAQ,EACR,WAAW,EACZ,MAAM,sBAAsB,CAAC;AAE9B;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAC/B,EAAE,SAAS,eAAe,EAC1B,SAAS,SAAS,QAAQ,CAAC,EAAE,EAAE,SAAS,CAAC,KACtC,WAAW,CAAC,EAAE,EAAE,SAAS,CAAC,CAwG9B"}

package/dist/tree-surfer/tree-node/tree-node.impl.js

@@ -0,0 +1,87 @@
+/**
+ * Creates an API for inspecting and immutably updating tree nodes.
+ *
+ * Tree updates do not mutate the supplied forest or its nodes. Updated
+ * arrays and ancestor nodes are created as needed, while unrelated nodes
+ * retain their original object identity.
+ *
+ * Node IDs are compared using JavaScript value equality. Sibling IDs
+ * should be unique.
+ */
+export function createTreeNodeApi() {
+    const treeNodeApi = {
+        isLeaf(node) {
+            return !('children' in node);
+        },
+        isBranch(node) {
+            return 'children' in node;
+        },
+        isClosedBranch(node) {
+            return node.children === null;
+        },
+        isOpenBranch(node) {
+            return node.children !== null;
+        },
+        getChildren(node) {
+            return node.children;
+        },
+        getChildById(node, id) {
+            return node.children.find((child) => child.id === id);
+        },
+        getAtPath(entries, path, selector) {
+            if (path.length === 0) {
+                return undefined;
+            }
+            // Accumulator
+            let node = entries.find((candidate) => candidate.id === path[0]);
+            for (let index = 1; node !== undefined && index < path.length; index += 1) {
+                if (treeNodeApi.isOpenBranch(node)) {
+                    node = treeNodeApi.getChildById(node, path[index]);
+                }
+                else {
+                    node = undefined;
+                }
+            }
+            return node === undefined ? undefined : selector(node);
+        },
+        modifyAtPath(entries, path, modifier) {
+            if (path.length === 0) {
+                return undefined;
+            }
+            // Only cloned arrays/nodes are modified below.
+            const updatedEntries = [...entries];
+            let currentEntries = updatedEntries;
+            for (let index = 0; index < path.length; index += 1) {
+                const id = path[index];
+                const childIndex = currentEntries.findIndex((candidate) => candidate.id === id);
+                if (childIndex === -1) {
+                    return undefined;
+                }
+                const child = currentEntries[childIndex];
+                if (index === path.length - 1) {
+                    const replacement = modifier(child);
+                    if (replacement === undefined) {
+                        return undefined;
+                    }
+                    currentEntries[childIndex] = replacement;
+                    return updatedEntries;
+                }
+                if (!treeNodeApi.isBranch(child) || !treeNodeApi.isOpenBranch(child)) {
+                    // The path cannot continue through a leaf or closed branch.
+                    return undefined;
+                }
+                // Clone the child array before modifying it.
+                const updatedChildren = [...treeNodeApi.getChildren(child)];
+                // Clone the ancestor node and attach the cloned child array.
+                currentEntries[childIndex] = {
+                    ...child,
+                    children: updatedChildren,
+                };
+                // Continue traversal through the cloned children.
+                currentEntries = updatedChildren;
+            }
+            return undefined;
+        },
+    };
+    return treeNodeApi;
+}

package/dist/tree-surfer/tree-node/tree-node.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=tree-node.test.d.ts.map

package/dist/tree-surfer/tree-node/tree-node.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree-node.test.d.ts","sourceRoot":"","sources":["../../../src/tree-surfer/tree-node/tree-node.test.ts"],"names":[],"mappings":""}

package/dist/tree-surfer/tree-node/tree-node.test.js

@@ -0,0 +1,117 @@
+import { describe, expect, it } from 'vitest';
+import * as fc from 'fast-check';
+import { createTreeNodeApi } from './tree-node.impl.js';
+import { forestAndPathAndExpectedArb, newBranchesOrNullArb, nodesArrayAndBranchPathArb, } from './tree-node.arb.js';
+const stringNodeApi = createTreeNodeApi();
+describe('tree node API', () => {
+    it('getAtPath returns the node at the generated path', () => {
+        fc.assert(fc.property(forestAndPathAndExpectedArb, ({ entries, path, expected }) => {
+            expect(stringNodeApi.getAtPath(entries, path, (node) => node)).toBe(expected);
+        }));
+    });
+    it('getAtPath applies the selector', () => {
+        const entries = [
+            {
+                id: 'root',
+                children: [{ id: 'child' }],
+            },
+        ];
+        expect(stringNodeApi.getAtPath(entries, ['root', 'child'], (node) => node.id)).toBe('child');
+    });
+    it('getAtPath returns undefined for an empty path', () => {
+        const entries = [{ id: 'root' }];
+        expect(stringNodeApi.getAtPath(entries, [], (node) => node)).toBeUndefined();
+    });
+    it('getAtPath returns undefined through a closed branch', () => {
+        const entries = [
+            {
+                id: 'root',
+                children: null,
+            },
+        ];
+        expect(stringNodeApi.getAtPath(entries, ['root', 'child'], (node) => node)).toBeUndefined();
+    });
+    it('getAtPath returns undefined when the selector returns undefined', () => {
+        const entries = [{ id: 'root' }];
+        expect(stringNodeApi.getAtPath(entries, ['root'], () => undefined)).toBeUndefined();
+    });
+    it('getChildById returns the matching child', () => {
+        const child = { id: 'child' };
+        const root = {
+            id: 'root',
+            children: [child],
+        };
+        expect(stringNodeApi.isOpenBranch(root)).toBe(true);
+        if (!stringNodeApi.isOpenBranch(root)) {
+            return;
+        }
+        expect(stringNodeApi.getChildById(root, 'child')).toBe(child);
+        expect(stringNodeApi.getChildById(root, 'missing')).toBeUndefined();
+    });
+    it('modifyAtPath replaces the generated node', () => {
+        fc.assert(fc.property(forestAndPathAndExpectedArb, ({ entries, path, expected }) => {
+            const replacement = {
+                id: expected.id,
+            };
+            const updatedForest = stringNodeApi.modifyAtPath(entries, path, () => replacement);
+            expect(updatedForest).not.toBeUndefined();
+            if (updatedForest === undefined) {
+                return;
+            }
+            expect(stringNodeApi.getAtPath(updatedForest, path, (node) => node)).toBe(replacement);
+            expect(stringNodeApi.getAtPath(entries, path, (node) => node)).toBe(expected);
+        }));
+    });
+    it('modifyAtPath replaces children at a branch path', () => {
+        fc.assert(fc.property(nodesArrayAndBranchPathArb, newBranchesOrNullArb, ({ entries, path, expected }, newBranches) => {
+            expect(stringNodeApi.isBranch(expected)).toBe(true);
+            const updatedForest = stringNodeApi.modifyAtPath(entries, path, (node) => ({
+                ...node,
+                children: newBranches,
+            }));
+            expect(updatedForest).not.toBeUndefined();
+            if (updatedForest === undefined) {
+                return;
+            }
+            const updatedNode = stringNodeApi.getAtPath(updatedForest, path, (node) => node);
+            expect(updatedNode).not.toBeUndefined();
+            expect(updatedNode).not.toBe(expected);
+            if (updatedNode === undefined ||
+                !stringNodeApi.isBranch(updatedNode) ||
+                (!stringNodeApi.isOpenBranch(updatedNode) && newBranches !== null)) {
+                return;
+            }
+            if (stringNodeApi.isOpenBranch(updatedNode)) {
+                expect([...stringNodeApi.getChildren(updatedNode)]).toStrictEqual(newBranches);
+            }
+            expect(stringNodeApi.getAtPath(entries, path, (node) => node)).toBe(expected);
+        }));
+    });
+    it('modifyAtPath returns undefined when the modifier aborts', () => {
+        const entries = [{ id: 'root' }];
+        expect(stringNodeApi.modifyAtPath(entries, ['root'], () => undefined)).toBeUndefined();
+    });
+    it('modifyAtPath returns undefined for an empty path', () => {
+        const entries = [{ id: 'root' }];
+        expect(stringNodeApi.modifyAtPath(entries, [], (node) => node)).toBeUndefined();
+    });
+    it('modifyAtPath returns undefined for an invalid path', () => {
+        const entries = [
+            {
+                id: 'root',
+                children: [],
+            },
+        ];
+        expect(stringNodeApi.modifyAtPath(entries, ['missing'], (node) => node)).toBeUndefined();
+        expect(stringNodeApi.modifyAtPath(entries, ['root', 'missing'], (node) => node)).toBeUndefined();
+    });
+    it('modifyAtPath cannot traverse a closed branch', () => {
+        const entries = [
+            {
+                id: 'root',
+                children: null,
+            },
+        ];
+        expect(stringNodeApi.modifyAtPath(entries, ['root', 'child'], (node) => node)).toBeUndefined();
+    });
+});