dirvi-lib 0.8.0 → 0.8.2

package/dist/trees/tree-node/tree-node.types.d.ts

@@ -0,0 +1,419 @@
+import type { SerializableKey, TreeNodeModel } from './tree-node.model.js';
+/**
+ * A private type-level marker used to make {@link TreeNode} opaque.
+ *
+ * @remarks
+ *
+ * This declaration intentionally has no runtime value: `declare` causes it
+ * to be erased when TypeScript emits JavaScript.
+ *
+ * WARNING: Brand must not be exported.
+ *
+ * The marker gives `TreeNode` a property whose key cannot be named by callers.
+ * Consequently, callers cannot construct a `TreeNode` using an ordinary
+ * object literal. The implementation module is responsible for constructing
+ * valid runtime values and exposing them through the public API.
+ *
+ * This is a compile-time abstraction boundary, not a security boundary.
+ * Consumers can still deliberately bypass it with `as unknown as TreeNode<…>`,
+ * just as they can bypass other TypeScript checks with assertions.
+ */
+declare const treeNodeBrand: unique symbol;
+/**
+ * An immutable tree node with application-defined data.
+ *
+ * @remarks
+ *
+ * `TreeNode` is intentionally opaque. Callers may hold, compare by reference,
+ * pass, store, and return nodes, but should use {@link TreeNodeApi} operations
+ * to create, inspect, and update them.
+ *
+ * In particular, callers do not depend on:
+ *
+ * - the runtime property used to store the node ID;
+ * - the runtime property used to store application data;
+ * - whether a node is represented as a leaf or a branch object;
+ * - how loaded child nodes are stored; or
+ * - how unloaded child state is represented internally.
+ *
+ * This allows the implementation to change its internal representation without
+ * requiring ordinary consumers to change.
+ *
+ * `TreeNode` values are intended to be immutable. Tree update operations
+ * return replacement nodes and do not mutate their inputs. This type does not,
+ * however, recursively freeze `Value`; applications should define their own
+ * value types with `readonly` properties when that is required.
+ *
+ * @typeParam Id - The type used to identify a node among its siblings.
+ * @typeParam Value - Application-owned data stored at each node.
+ *
+ * @example
+ *
+ * ```ts
+ * type MenuItem = Readonly<{
+ *   label: string;
+ *   href?: string;
+ *   requiredRole: 'guest' | 'member' | 'admin';
+ * }>;
+ *
+ * type MenuTree = TreeNode<MenuId, MenuItem>;
+ * ```
+ *
+ * @example
+ *
+ * ```ts
+ * type DirectoryEntry = Readonly<{
+ *   kind: 'file' | 'directory';
+ *   name: string;
+ *   sizeBytes?: number;
+ * }>;
+ *
+ * type DirectoryTree = TreeNode<DirectoryId, DirectoryEntry>;
+ * ```
+ */
+export type TreeNode<Id extends SerializableKey, Value> = {
+    /**
+     * A phantom type-level witness for `Id` and `Value`.
+     *
+     * @remarks
+     *
+     * This property is not part of the intended runtime representation. Its
+     * purpose is to preserve the generic relationship between a tree node, its
+     * ID type, and its application-value type while keeping the node opaque.
+     */
+    readonly [treeNodeBrand]: {
+        readonly id: Id;
+        readonly value: Value;
+    };
+};
+/**
+ * The semantic child kind of tree nodes.
+ *
+ * @remarks
+ *
+ * A node is exactly one of these:
+ *
+ * - `leaf`: The node cannot contain children.
+ * - `unloaded-branch`: The node may contain children, but its child collection
+ *   has not been loaded and is therefore unavailable.
+ * - `loaded-branch`: The node has a loaded child collection. The collection may
+ *   be empty.
+ *
+ * A loaded branch with zero children is distinct from a leaf:
+ *
+ * - a leaf can never contain children;
+ * - an empty loaded branch can contain children, but currently has none;
+ * - an unloaded branch may contain children, but they are not currently loaded.
+ */
+export type TreeNodeKind = 'leaf' | 'unloaded-branch' | 'loaded-branch';
+/**
+ * Case handlers for inspecting an opaque {@link TreeNode}.
+ *
+ * @remarks
+ *
+ * `TreeNodeMatch` provides exhaustive pattern matching over the semantic state
+ * of a node. It is the preferred operation when behavior differs between
+ * leaves, unloaded branches, and loaded branches:
+ *
+ * - `leaf` receives no `children`, because a leaf cannot have children;
+ * - `unloadedBranch` receives no `children`, because its children are not loaded;
+ * - `loadedBranch` receives an iterable of loaded direct child nodes. No
+ *   iteration-order guarantee is made.
+ *
+ * Every handler must return the same `Result` type.
+ *
+ * @typeParam Id - The type used to identify nodes among siblings.
+ * @typeParam Value - The application-specific value stored at each node.
+ * @typeParam Result - The common result type returned by all case handlers.
+ *
+ * @example
+ *
+ * ```ts
+ * const label = api.match(node, {
+ *   leaf: ({ value }) => value.label,
+ *
+ *   unloadedBranch: ({ value }) => `${value.label} (loading…)`,
+ *
+ *   loadedBranch: ({ value, children }) => {
+ *     let childCount = 0;
+ *
+ *     for (const _child of children) {
+ *       childCount += 1;
+ *     }
+ *
+ *     return `${value.label} (${childCount})`;
+ *   },
+ * });
+ * ```
+ */
+export type TreeNodeMatch<Id extends SerializableKey, Value, Result> = Readonly<{
+    leaf: (node: Readonly<{
+        id: Id;
+        value: Value;
+    }>) => Result;
+    unloadedBranch: (node: Readonly<{
+        id: Id;
+        value: Value;
+    }>) => Result;
+    loadedBranch: (node: Readonly<{
+        id: Id;
+        value: Value;
+        children: Iterable<TreeNode<Id, Value>>;
+    }>) => Result;
+}>;
+/**
+ * Operations for constructing, inspecting, and immutably updating tree nodes.
+ *
+ * @remarks
+ *
+ * A `TreeNodeApi` is specialized to one ID type and one application-value
+ * type. It owns the structural tree rules: leaf/branch state, child loading
+ * state, sibling-ID uniqueness, and immutable ancestor reconstruction.
+ *
+ * Child collections are unordered. Although operations expose children as
+ * `Iterable` values, callers must not rely on iteration order being stable,
+ * meaningful, or related to insertion order. The implementation may use an
+ * array, map, set, indexed store, or another representation internally.
+ *
+ * Tree nodes are plain immutable values at runtime. Update operations do not
+ * mutate supplied nodes or their loaded child collections. When an update
+ * succeeds, only nodes and child collections on the updated path need to be
+ * recreated; unrelated parts of the tree may retain their original object
+ * identity.
+ *
+ * A path is an array of IDs relative to a supplied root node. For example,
+ * given this tree:
+ *
+ * ```text
+ * root
+ * └── child
+ * ```
+ *
+ * the root is addressed by `[]`, and `child` is addressed by `['child']`.
+ *
+ * Paths cannot pass through leaves or closed branches. A closed branch may be
+ * selected as the final node in a path, but its unloaded descendants cannot be
+ * addressed.
+ *
+ * @typeParam Id - The type used to identify nodes among siblings.
+ * @typeParam Value - The application-specific value stored at each node.
+ */
+export type TreeNodeApi<Id extends SerializableKey, Value> = Readonly<{
+    /**
+     * Creates a leaf node.
+     *
+     * A leaf cannot contain children. To convert an existing node to a leaf while
+     * retaining its ID and value, use {@link TreeNodeApi.toLeaf}.
+     *
+     * @param id - The ID that identifies this node among its siblings.
+     * @param value - Application-owned data stored on the node.
+     * @returns A new leaf node.
+     */
+    createLeaf(id: Id, value: Value): TreeNode<Id, Value>;
+    /**
+     * Creates a branch whose children are not loaded.
+     *
+     * An unloaded branch may contain children, but its child collection is not
+     * currently available. It is distinct from both a leaf and a loaded branch
+     * with an empty child collection.
+     */
+    createUnloadedBranch(id: Id, value: Value): TreeNode<Id, Value>;
+    /**
+     * Creates a branch with a loaded child collection.
+     *
+     * An empty child collection creates a loaded branch with no current children;
+     * it does not create a leaf.
+     */
+    createLoadedBranch(id: Id, value: Value, children: Iterable<TreeNode<Id, Value>>): TreeNode<Id, Value> | undefined;
+    /**
+     * Returns a node's stable sibling ID.
+     *
+     * @param node - The node to inspect.
+     * @returns The ID identifying `node` among its siblings.
+     */
+    id(node: TreeNode<Id, Value>): Id;
+    /**
+     * Returns application-owned data stored on a node.
+     *
+     * The value is returned by reference and is not cloned. Callers must not
+     * mutate it if the application treats tree nodes as immutable values.
+     *
+     * @param node - The node to inspect.
+     * @returns The value associated with `node`.
+     */
+    value(node: TreeNode<Id, Value>): Value;
+    /**
+     * Returns the semantic kind of a node.
+     *
+     * Prefer {@link TreeNodeApi.match} when behavior differs by node kind and all
+     * three variants must be handled.
+     *
+     * @param node - The node to inspect.
+     * @returns Whether `node` is a leaf, unloaded branch, or loaded branch.
+     */
+    kind(node: TreeNode<Id, Value>): TreeNodeKind;
+    /**
+     * Inspects a node by handling its semantic state exhaustively.
+     *
+     * @param node - The node to inspect.
+     * @param handlers - Case handlers for leaf, closed-branch, and open-branch
+     * states.
+     * @returns The value returned by the selected case handler.
+     */
+    match<Result>(node: TreeNode<Id, Value>, handlers: TreeNodeMatch<Id, Value, Result>): Result;
+    /**
+     * Returns the loaded direct children of a loaded branch.
+     *
+     * The returned child nodes are existing values, not defensive clones. No
+     * iteration-order guarantee is made.
+     *
+     * Returns `undefined` when `node` is a leaf or an unloaded branch. Use
+     * {@link TreeNodeApi.kind} or {@link TreeNodeApi.match} when those cases need
+     * to be distinguished.
+     *
+     * @param node - The node whose direct children to inspect.
+     * @returns An iterable of loaded direct children, or `undefined` when children
+     * are unavailable because `node` is a leaf or closed branch.
+     */
+    getLoadedChildren(node: TreeNode<Id, Value>): Iterable<TreeNode<Id, Value>> | undefined;
+    /**
+     * Finds a loaded direct child by sibling ID.
+     *
+     * The search is performed only among direct children. It does not traverse
+     * descendants.
+     *
+     * @param node - The node whose loaded direct children to search.
+     * @param id - The sibling ID to find.
+     * @returns The existing matching child, or `undefined` when `node` is not an
+     * open branch or does not have a direct child with `id`.
+     */
+    findChildById(node: TreeNode<Id, Value>, id: Id): TreeNode<Id, Value> | undefined;
+    /**
+     * Returns an equivalent node with replacement application data.
+     *
+     * The returned node retains the original node's ID, semantic child state,
+     * and when applicable, existing child-node references. The supplied node is
+     * not mutated.
+     *
+     * @param node - The node to update.
+     * @param value - Replacement application-owned data.
+     * @returns A replacement node with `value`.
+     */
+    withValue(node: TreeNode<Id, Value>, value: Value): TreeNode<Id, Value>;
+    /**
+     * Converts a node to a leaf.
+     *
+     * The returned node retains the source node's ID and application value.
+     * Any existing children, loaded or unloaded, are discarded.
+     *
+     * @param node - The node to convert.
+     * @returns A leaf node with the source node's ID and value.
+     */
+    toLeaf(node: TreeNode<Id, Value>): TreeNode<Id, Value>;
+    /**
+     * Converts a node to a branch with unloaded children.
+     *
+     * The returned node retains the source node's ID and application value.
+     * Any currently loaded child collection is discarded.
+     *
+     * @param node - The node to convert.
+     * @returns A closed branch with the source node's ID and value.
+     */
+    toUnloadedBranch(node: TreeNode<Id, Value>): TreeNode<Id, Value>;
+    /**
+     * Converts a node to an open branch with replacement loaded children.
+     *
+     * The returned node retains the source node's ID and application value.
+     * Any previous child state is replaced.
+     *
+     * Child collections are unordered. Callers must not rely on the iteration order
+     * of the supplied children being retained or exposed by the resulting node.
+     *
+     * Direct siblings must have unique IDs. If two or more supplied children have
+     * the same ID, no replacement node is created and this method returns
+     * `undefined`.
+     *
+     * The supplied node and child collection are not mutated.
+     *
+     * @param node - The node to convert or update.
+     * @param children - Replacement loaded direct children. Their IDs must be
+     * unique among direct siblings.
+     * @returns An open branch with the source node's ID and value, or `undefined`
+     * when `children` contains duplicate sibling IDs.
+     */
+    withLoadedChildren(node: TreeNode<Id, Value>, children: Iterable<TreeNode<Id, Value>>): TreeNode<Id, Value> | undefined;
+    /**
+     * Finds the node addressed by a path relative to `root`.
+     *
+     * An empty path selects `root`. Resolution fails when a path refers to a
+     * missing child or attempts to pass through a leaf or unloaded branch.
+     *
+     * @param root - The root node relative to which `path` is interpreted.
+     * @param path - A sibling-ID path relative to `root`.
+     * @returns The existing node at `path`, or `undefined` when the path cannot
+     * be resolved.
+     */
+    findAtPath(root: TreeNode<Id, Value>, path: readonly Id[]): TreeNode<Id, Value> | undefined;
+    /**
+     * Applies a selector to the node addressed by a path relative to `root`.
+     *
+     * The selector runs only after the complete path has been resolved. The
+     * selected node is supplied as the existing node value and is not cloned.
+     *
+     * An empty path selects `root`. Resolution fails when a path refers to a
+     * missing child or attempts to pass through a leaf or a closed branch.
+     *
+     * @param root - The root node relative to which `path` is interpreted.
+     * @param path - A sibling-ID path relative to `root`.
+     * @param selector - A function applied to the resolved node.
+     * @returns The selector result, or `undefined` when the path cannot be
+     * resolved or when `selector` itself returns `undefined`.
+     */
+    selectAtPath<Result>(root: TreeNode<Id, Value>, path: readonly Id[], selector: (node: TreeNode<Id, Value>) => Result): Result | undefined;
+    /**
+     * Immutably replaces the node addressed by a path relative to `root`.
+     *
+     * The modifier runs only after the complete path has been resolved. Returning
+     * `undefined` aborts the operation and causes this method to return
+     * `undefined`.
+     *
+     * An empty path selects `root`. When a descendant is replaced, replacement
+     * nodes are created only along the path from `root` to that descendant. Nodes
+     * outside that path retain their original object identity.
+     *
+     * The modifier may return a node with a different ID. If it does, the
+     * replacement is subsequently addressed by its new ID rather than the old
+     * path segment.
+     *
+     * The update also fails when the replacement node's ID duplicates the ID of
+     * one of its new siblings. This can occur when `modifier` returns a node with
+     * a different ID.
+     *
+     * @param root - The root node relative to which `path` is interpreted.
+     * @param path - A sibling-ID path relative to `root`.
+     * @param update - Produces a replacement node, or `undefined` to abort.
+     * @returns A replacement root, or `undefined` when the path cannot be
+     *  resolved, `modifier` aborts, or the replacement would create duplicate
+     *  sibling IDs.
+     */
+    updateAtPath(root: TreeNode<Id, Value>, path: readonly Id[], update: (node: TreeNode<Id, Value>) => TreeNode<Id, Value> | undefined): TreeNode<Id, Value> | undefined;
+    /**
+     * Converts an opaque runtime node into a public structural model.
+     *
+     * The returned model is a fresh recursive snapshot. It is suitable for
+     * serialization when `Id` and `Value` are serializable.
+     */
+    toModel(node: TreeNode<Id, Value>): TreeNodeModel<Id, Value>;
+    /**
+     * Constructs an opaque tree from a public structural model.
+     *
+     * Returns `undefined` if any loaded child collection contains duplicate
+     * sibling IDs.
+     *
+     * This function assumes the model has already been validated as data of the
+     * expected shape. Use a schema/decoder at untrusted boundaries.
+     */
+    fromModel(model: TreeNodeModel<Id, Value>): TreeNode<Id, Value> | undefined;
+}>;
+export {};
+//# sourceMappingURL=tree-node.types.d.ts.map

package/dist/trees/tree-node/tree-node.types.d.ts.map

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

package/dist/trees/tree-node/tree-node.types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dirvi-lib",
-  "version": "0.8.0",
+  "version": "0.8.2",
   "description": "Dependency for dirvi apps.",
   "license": "LGPL-3.0-or-later",
   "type": "module",

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

@@ -1 +0,0 @@
-{"version":3,"file":"cursor.d.ts","sourceRoot":"","sources":["../../src/tree-surfer/cursor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,MAAM,MAAM,CAAC,EAAE,IAAI,SAAS,EAAE,EAAE,CAAC;AAEvC;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,SAAS,CAAC,CAAC,UAAU,EAC9D,QAAQ,EAAE,QAAQ,wBAGnB;AAED;;;;GAIG;AACH,MAAM,MAAM,SAAS,CAAC,EAAE,IAAI;IAC1B;;OAEG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,EAAE,CAAC,GAAG,OAAO,CAAC;IAEpD;;;;OAIG;IACH,OAAO,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC;IAElC;;;;;OAKG;IACH,sBAAsB,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC,EAAE,SAAS,EAAE,SAAS,EAAE,EAAE,GAAG,OAAO,CAAC;CAC/E,CAAC;AAEF,wBAAgB,eAAe,CAAC,EAAE,KAAK,SAAS,CAAC,EAAE,CAAC,CAcnD"}

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

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

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

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

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

@@ -1,4 +0,0 @@
-import type { FoldNodeApi, FoldNodeService } from './fold-node.types.js';
-import type { SerializableKey } from '../tree-node/tree-node.types.js';
-export declare function createFoldNodeService<Id extends SerializableKey>(foldNodeApi: FoldNodeApi<Id>): FoldNodeService<Id>;
-//# sourceMappingURL=fold-node.impl.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"fold-node.impl.d.ts","sourceRoot":"","sources":["../../../src/tree-surfer/fold-node/fold-node.impl.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEV,WAAW,EACX,eAAe,EAChB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAgBvE,wBAAgB,qBAAqB,CAAC,EAAE,SAAS,eAAe,EAC9D,WAAW,EAAE,WAAW,CAAC,EAAE,CAAC,GAC3B,eAAe,CAAC,EAAE,CAAC,CAwNrB"}

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

@@ -1,149 +0,0 @@
-function getFoldedChildById(node, id) {
-    return node.foldedChildren.find((child) => child.id === id);
-}
-function hasFoldedChildWithId(node, id) {
-    return getFoldedChildById(node, id) !== undefined;
-}
-export function createFoldNodeService(foldNodeApi) {
-    function createEmptyNode(id) {
-        return {
-            id,
-            children: [],
-            foldedChildren: [],
-        };
-    }
-    return {
-        createEmptyNode,
-        getIfEntryFoldedAtPath(rootNode, path, entryId) {
-            const node = foldNodeApi.getAtPath(rootNode, path, (candidate) => candidate);
-            return node !== undefined && hasFoldedChildWithId(node, entryId);
-        },
-        foldedEntriesAtPath(rootNode, path) {
-            const node = foldNodeApi.getAtPath(rootNode, path, (candidate) => candidate);
-            return node?.foldedChildren.map((child) => child.id);
-        },
-        addFoldedEntryAtPath(rootNode, path, entryId) {
-            const rootWithPath = ensurePath(rootNode, path);
-            if (rootWithPath === undefined) {
-                return undefined;
-            }
-            return foldNodeApi.modifyAtPath(rootWithPath, path, (node) => addFoldedEntry(node, entryId));
-        },
-        removeFoldedEntryAtPath(rootNode, path, entryId) {
-            return foldNodeApi.modifyAtPath(rootNode, path, (node) => removeFoldedEntry(node, entryId));
-        },
-        clearFoldedEntriesAtPath(rootNode, path) {
-            return foldNodeApi.modifyAtPath(rootNode, path, (node) => clearFoldedEntries(node));
-        },
-    };
-    // Node-local operations.
-    //
-    // These functions update only the selected node. Path traversal and immutable
-    // ancestor updates are handled by FoldNodeApi.
-    function addFoldedEntry(node, entryId) {
-        const existingFoldedChild = getFoldedChildById(node, entryId);
-        if (existingFoldedChild !== undefined) {
-            return node;
-        }
-        const childIndex = node.children.findIndex((child) => child.id === entryId);
-        const child = childIndex === -1 ? createEmptyNode(entryId) : node.children[childIndex];
-        const children = childIndex === -1
-            ? node.children
-            : node.children.filter((_, index) => index !== childIndex);
-        return {
-            ...node,
-            children,
-            foldedChildren: [...node.foldedChildren, child],
-        };
-    }
-    function removeFoldedEntry(node, entryId) {
-        const foldedChildIndex = node.foldedChildren.findIndex((child) => child.id === entryId);
-        if (foldedChildIndex === -1) {
-            return node;
-        }
-        const foldedChild = node.foldedChildren[foldedChildIndex];
-        const foldedChildren = node.foldedChildren.filter((_, index) => index !== foldedChildIndex);
-        const hasNestedFoldState = foldedChild.children.length > 0 || foldedChild.foldedChildren.length > 0;
-        return {
-            ...node,
-            children: hasNestedFoldState
-                ? [...node.children, foldedChild]
-                : node.children,
-            foldedChildren,
-        };
-    }
-    function clearFoldedEntries(node) {
-        if (node.foldedChildren.length === 0) {
-            return node;
-        }
-        const children = [...node.children];
-        for (const foldedChild of node.foldedChildren) {
-            const hasNestedFoldState = foldedChild.children.length > 0 ||
-                foldedChild.foldedChildren.length > 0;
-            if (hasNestedFoldState) {
-                children.push(foldedChild);
-            }
-        }
-        return {
-            ...node,
-            children,
-            foldedChildren: [],
-        };
-    }
-    /**
-     * Ensures that the requested path exists in the fold-state tree.
-     *
-     * The path is relative to `rootNode`; an empty path selects the root.
-     * This creates fold nodes only and does not modify the buffer tree.
-     */
-    function ensurePath(rootNode, path) {
-        if (path.length === 0) {
-            return rootNode;
-        }
-        const children = ensureChildPath(rootNode, path, 0);
-        if (children === undefined) {
-            return undefined;
-        }
-        if (children === rootNode.children) {
-            return rootNode;
-        }
-        return {
-            ...rootNode,
-            children,
-        };
-    }
-    function ensureChildPath(parent, path, pathIndex) {
-        const id = path[pathIndex];
-        if (id === undefined) {
-            return parent.children;
-        }
-        if (hasFoldedChildWithId(parent, id)) {
-            return undefined;
-        }
-        const children = parent.children;
-        const childIndex = children.findIndex((child) => child.id === id);
-        const child = childIndex === -1 ? createEmptyNode(id) : children[childIndex];
-        let updatedChild = child;
-        if (pathIndex < path.length - 1) {
-            const updatedChildren = ensureChildPath(child, path, pathIndex + 1);
-            if (updatedChildren === undefined) {
-                return undefined;
-            }
-            if (updatedChildren !== child.children) {
-                updatedChild = {
-                    ...child,
-                    children: updatedChildren,
-                };
-            }
-        }
-        if (childIndex === -1) {
-            return [...children, updatedChild];
-        }
-        if (updatedChild === child) {
-            return children;
-        }
-        const result = [...children];
-        result[childIndex] = updatedChild;
-        return result;
-    }
-}

package/dist/tree-surfer/fold-node/fold-node.schema.d.ts

@@ -1,5 +0,0 @@
-import { z } from 'zod';
-import type { FoldNode } from './fold-node.types.js';
-import { SerializableKey } from '../tree-node/tree-node.types.js';
-export declare function createFoldNodeSchemas<Id extends SerializableKey>(idSchema: z.ZodType<Id>): z.ZodType<FoldNode<Id>>;
-//# sourceMappingURL=fold-node.schema.d.ts.map

package/dist/tree-surfer/fold-node/fold-node.schema.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"fold-node.schema.d.ts","sourceRoot":"","sources":["../../../src/tree-surfer/fold-node/fold-node.schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAElE,wBAAgB,qBAAqB,CAAC,EAAE,SAAS,eAAe,EAC9D,QAAQ,EAAE,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,GACtB,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,CAYzB"}

package/dist/tree-surfer/fold-node/fold-node.schema.js

@@ -1,9 +0,0 @@
-import { z } from 'zod';
-export function createFoldNodeSchemas(idSchema) {
-    const foldNodeSchema = z.lazy(() => z.object({
-        id: idSchema,
-        children: z.array(foldNodeSchema),
-        foldedChildren: z.array(foldNodeSchema),
-    }));
-    return foldNodeSchema;
-}

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

@@ -1 +0,0 @@
-{"version":3,"file":"fold-node.types.d.ts","sourceRoot":"","sources":["../../../src/tree-surfer/fold-node/fold-node.types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,iCAAiC,CAAC;AAE/E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,MAAM,MAAM,QAAQ,CAAC,EAAE,SAAS,eAAe,IAAI;IACjD,EAAE,EAAE,EAAE,CAAC;IACP,QAAQ,EAAE,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAC;IACzB,cAAc,EAAE,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAC;CAChC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,MAAM,WAAW,CAAC,EAAE,SAAS,eAAe,IAAI,WAAW,CAAC,EAAE,EAAE,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC;AAEpF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,MAAM,eAAe,CAAC,EAAE,SAAS,eAAe,IAAI;IACxD;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,EAAE,EAAE,GAAG,QAAQ,CAAC,EAAE,CAAC,CAAC;IAEtC;;;;;;;;;;;;;;OAcG;IACH,sBAAsB,CACpB,QAAQ,EAAE,QAAQ,CAAC,EAAE,CAAC,EACtB,IAAI,EAAE,SAAS,EAAE,EAAE,EACnB,OAAO,EAAE,EAAE,GACV,OAAO,CAAC;IAEX;;;;OAIG;IACH,mBAAmB,CACjB,QAAQ,EAAE,QAAQ,CAAC,EAAE,CAAC,EACtB,IAAI,EAAE,SAAS,EAAE,EAAE,GAClB,EAAE,EAAE,GAAG,SAAS,CAAC;IAEpB;;;;;;;;;;;;;;;;;OAiBG;IACH,oBAAoB,CAClB,QAAQ,EAAE,QAAQ,CAAC,EAAE,CAAC,EACtB,IAAI,EAAE,SAAS,EAAE,EAAE,EACnB,OAAO,EAAE,EAAE,GACV,QAAQ,CAAC,EAAE,CAAC,GAAG,SAAS,CAAC;IAE5B;;;;;;;;;;;;;;;;;OAiBG;IACH,uBAAuB,CACrB,QAAQ,EAAE,QAAQ,CAAC,EAAE,CAAC,EACtB,IAAI,EAAE,SAAS,EAAE,EAAE,EACnB,OAAO,EAAE,EAAE,GACV,QAAQ,CAAC,EAAE,CAAC,GAAG,SAAS,CAAC;IAE5B;;;;;;;;;;;;;;;;;;OAkBG;IACH,wBAAwB,CACtB,QAAQ,EAAE,QAAQ,CAAC,EAAE,CAAC,EACtB,IAAI,EAAE,SAAS,EAAE,EAAE,GAClB,QAAQ,CAAC,EAAE,CAAC,GAAG,SAAS,CAAC;IAC5B,wBAAwB,CACtB,QAAQ,EAAE,QAAQ,CAAC,EAAE,CAAC,EACtB,IAAI,EAAE,SAAS,EAAE,EAAE,GAClB,QAAQ,CAAC,EAAE,CAAC,GAAG,SAAS,CAAC;CAC7B,CAAC"}

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

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