dirvi-lib 0.4.0 → 0.5.0

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

@@ -0,0 +1,191 @@
+import { CursorKind } from '../cursor.js';
+import { isNavBranch } from './nav-node.types.js';
+export function createNavNodeApi(treeNodeApi, foldNodeApi, cursorApi) {
+    const navNodeApi = {
+        // Return a nav node from the BufferNode tree and FoldNode tree.
+        from(entries, foldNode) {
+            const visibleEntriesSoFar = [];
+            const foldedEntriesSoFar = [];
+            for (const entry of entries) {
+                // Find the node
+                let navigationEntry;
+                if (treeNodeApi.isBranch(entry)) {
+                    // If fold node does not have children (recursively no folds),
+                    // then just use empty.
+                    const childFoldNode = foldNodeApi.getChildById(foldNode, entry.id) ??
+                        createEmptyFoldNode();
+                    navigationEntry = {
+                        ...entry,
+                        children: entry.children === null
+                            ? null
+                            : navNodeApi.from(entry.children, childFoldNode),
+                    };
+                }
+                else if (treeNodeApi.isLeaf(entry)) {
+                    navigationEntry = entry;
+                }
+                else {
+                    // This should be unreachable if BufferNode correctly extends TreeNode.
+                    throw new Error('Unsupported tree node');
+                }
+                if (foldNode.folds.has(entry.id)) {
+                    foldedEntriesSoFar.push(navigationEntry);
+                }
+                else {
+                    visibleEntriesSoFar.push(navigationEntry);
+                }
+            }
+            return {
+                entries: visibleEntriesSoFar,
+                foldedEntries: foldedEntriesSoFar,
+            };
+        },
+        getNodeAtPath(navigation, path) {
+            const [currentId, ...remainingPath] = path;
+            // An empty path identifies the current node.
+            if (currentId === undefined) {
+                return navigation;
+            }
+            const entry = [...navigation.entries, ...navigation.foldedEntries].find((candidate) => candidate.id === currentId);
+            if (entry === undefined) {
+                return undefined;
+            }
+            if (!isNavBranch(entry)) {
+                return undefined;
+            }
+            // The directory has not been loaded/opened.
+            if (entry.children === null) {
+                return undefined;
+            }
+            return navNodeApi.getNodeAtPath(entry.children, remainingPath);
+        },
+        getEntryAtPath(navigation, path) {
+            const [currentId, ...remainingPath] = path;
+            if (currentId === undefined) {
+                return undefined;
+            }
+            const entry = [...navigation.entries, ...navigation.foldedEntries].find((candidate) => candidate.id === currentId);
+            if (entry === undefined) {
+                return undefined;
+            }
+            if (remainingPath.length === 0) {
+                return entry;
+            }
+            if (!isNavBranch(entry) || entry.children === null) {
+                return undefined;
+            }
+            return navNodeApi.getEntryAtPath(entry.children, remainingPath);
+        },
+        nextCursor(rootNode, cursor) {
+            const cursors = cursorsInNode(rootNode, []);
+            const currentIndex = cursors.findIndex((candidate) => cursorApi.equal(candidate, cursor));
+            if (currentIndex === -1 || currentIndex === cursors.length - 1) {
+                return undefined;
+            }
+            return cursors[currentIndex + 1];
+        },
+        previousCursor(rootNode, cursor) {
+            const cursors = cursorsInNode(rootNode, []);
+            const currentIndex = cursors.findIndex((candidate) => cursorApi.equal(candidate, cursor));
+            if (currentIndex <= 0) {
+                return undefined;
+            }
+            return cursors[currentIndex - 1];
+        },
+        cursorAfterFold(rootNode, cursor) {
+            if (cursorApi.isFold(cursor)) {
+                return undefined;
+            }
+            const cursors = cursorsInNode(rootNode, []);
+            const currentIndex = cursors.findIndex((candidate) => cursorApi.equal(candidate, cursor));
+            if (currentIndex === -1) {
+                return undefined;
+            }
+            const foldedPath = [...cursor.parentPath, cursor.entryId];
+            for (let index = currentIndex + 1; index < cursors.length; index += 1) {
+                const candidate = cursors[index];
+                if (candidate === undefined) {
+                    continue;
+                }
+                if (cursorApi.cursorBelongsToSubtree(candidate, foldedPath)) {
+                    continue;
+                }
+                return candidate;
+            }
+            // The fold row will be created at the end of this directory.
+            return {
+                kind: CursorKind.Fold,
+                parentPath: cursor.parentPath,
+            };
+        },
+        parentCursor(navigation, cursor) {
+            const parentPath = cursor.parentPath;
+            // The cursor is already in the root directory.
+            if (parentPath.length === 0) {
+                return undefined;
+            }
+            const entryId = parentPath.at(-1);
+            if (entryId === undefined) {
+                return undefined;
+            }
+            const containingPath = parentPath.slice(0, -1);
+            const entry = navNodeApi.getEntryAtPath(navigation, [...parentPath]);
+            // The parent path must identify a navigable branch.
+            if (entry === undefined || !isNavBranch(entry)) {
+                return undefined;
+            }
+            return {
+                kind: CursorKind.Entry,
+                parentPath: containingPath,
+                entryId: entryId,
+            };
+        },
+        cursors(navigation, parentPath = []) {
+            return cursorsInNode(navigation, parentPath);
+        },
+        visibleLeavesPaths(navigation, parentPath = []) {
+            const paths = [];
+            for (const entry of navigation.entries) {
+                const entryPath = [...parentPath, entry.id];
+                if (isNavBranch(entry)) {
+                    // A null children value means that the directory has not been
+                    // loaded/opened, so there are no visible descendant files.
+                    if (entry.children !== null) {
+                        paths.push(...navNodeApi.visibleLeavesPaths(entry.children, entryPath));
+                    }
+                    continue;
+                }
+                paths.push(entryPath);
+            }
+            return paths;
+        },
+    };
+    return navNodeApi;
+}
+function createEmptyFoldNode() {
+    return {
+        children: [],
+        folds: new Set(),
+    };
+}
+function cursorsInNode(node, parentPath) {
+    const cursors = [];
+    for (const entry of node.entries) {
+        cursors.push({
+            kind: CursorKind.Entry,
+            parentPath,
+            entryId: entry.id,
+        });
+        if (!isNavBranch(entry) || entry.children === null) {
+            continue;
+        }
+        cursors.push(...cursorsInNode(entry.children, [...parentPath, entry.id]));
+    }
+    if (node.foldedEntries.length > 0) {
+        cursors.push({
+            kind: CursorKind.Fold,
+            parentPath,
+        });
+    }
+    return cursors;
+}

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":""}