dirvi-lib 0.7.0 → 0.8.0

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

@@ -1,117 +1,185 @@
-import { describe, expect, it } from 'vitest';
+import { describe, expect, it, vi } 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);
+import { newBranchesOrNullArb, nodesArrayAndBranchPathArb, nodeAndPathAndExpectedArb, } from './tree-node.arb.js';
+const api = createTreeNodeApi();
+describe('getChildById', () => {
+    it('UT: returns the matching direct child', () => {
+        const child = { id: 'child' };
+        const root = {
+            id: 'root',
+            children: [child],
+        };
+        expect(api.getChildById(root, 'child')).toBe(child);
+    });
+    it('UT: returns undefined for a missing child', () => {
+        const root = {
+            id: 'root',
+            children: [],
+        };
+        expect(api.getChildById(root, 'missing')).toBeUndefined();
+    });
+});
+describe('getAtPath', () => {
+    // Using `selector = vi.fn...` here is too heavy
+    it('applies selector to the node at a valid path', () => {
+        fc.assert(fc.property(nodeAndPathAndExpectedArb, ({ root, path, expected }) => {
+            expect(api.getAtPath(root, path, (node) => node)).toBe(expected);
+            expect(api.getAtPath(root, path, (node) => node.id)).toBe(expected.id);
         }));
     });
-    it('getAtPath applies the selector', () => {
-        const entries = [
-            {
-                id: 'root',
-                children: [{ id: 'child' }],
-            },
-        ];
-        expect(stringNodeApi.getAtPath(entries, ['root', 'child'], (node) => node.id)).toBe('child');
+    it('UT: calls the selector once with the resolved node', () => {
+        const child = { id: 'child' };
+        const root = {
+            id: 'root',
+            children: [child],
+        };
+        const selector = vi.fn((node) => node.id);
+        expect(api.getAtPath(root, ['child'], selector)).toBe('child');
+        expect(selector).toHaveBeenCalledOnce();
+        expect(selector).toHaveBeenCalledWith(child);
     });
-    it('getAtPath returns undefined for an empty path', () => {
-        const entries = [{ id: 'root' }];
-        expect(stringNodeApi.getAtPath(entries, [], (node) => node)).toBeUndefined();
+    it('UT: returns undefined for an invalid root path without calling the selector', () => {
+        const selector = vi.fn((node) => node.id);
+        const result = api.getAtPath([{ id: 'root' }], ['missing'], selector);
+        expect(result).toBeUndefined();
+        expect(selector).not.toHaveBeenCalled();
     });
-    it('getAtPath returns undefined through a closed branch', () => {
-        const entries = [
-            {
-                id: 'root',
-                children: null,
-            },
-        ];
-        expect(stringNodeApi.getAtPath(entries, ['root', 'child'], (node) => node)).toBeUndefined();
+    it('UT: returns undefined when a child is missing from an open branch', () => {
+        const root = {
+            id: 'root',
+            children: [{ id: 'child' }],
+        };
+        const selector = vi.fn((node) => node.id);
+        const result = api.getAtPath(root, ['root', 'missing'], selector);
+        expect(result).toBeUndefined();
+        expect(selector).not.toHaveBeenCalled();
     });
-    it('getAtPath returns undefined when the selector returns undefined', () => {
-        const entries = [{ id: 'root' }];
-        expect(stringNodeApi.getAtPath(entries, ['root'], () => undefined)).toBeUndefined();
+    it('UT: resolves the root for an empty path', () => {
+        const root = { id: 'root' };
+        const selector = vi.fn((node) => node.id);
+        expect(api.getAtPath(root, [], selector)).toBe('root');
+        expect(selector).toHaveBeenCalledOnce();
+        expect(selector).toHaveBeenCalledWith(root);
     });
-    it('getChildById returns the matching child', () => {
-        const child = { id: 'child' };
+    it('UT: returns undefined through a closed branch without calling the selector', () => {
         const root = {
             id: 'root',
-            children: [child],
+            children: null,
         };
-        expect(stringNodeApi.isOpenBranch(root)).toBe(true);
-        if (!stringNodeApi.isOpenBranch(root)) {
-            return;
-        }
-        expect(stringNodeApi.getChildById(root, 'child')).toBe(child);
-        expect(stringNodeApi.getChildById(root, 'missing')).toBeUndefined();
+        const selector = vi.fn((node) => node.id);
+        const result = api.getAtPath(root, ['child'], selector);
+        expect(result).toBeUndefined();
+        expect(selector).not.toHaveBeenCalled();
+    });
+    it('UT: returns undefined when the selector returns undefined', () => {
+        const selector = vi.fn((_node) => undefined);
+        const result = api.getAtPath({ id: 'root' }, [], selector);
+        expect(result).toBeUndefined();
+        expect(selector).toHaveBeenCalledOnce();
+        expect(selector).toHaveBeenCalledWith({ id: 'root' });
     });
-    it('modifyAtPath replaces the generated node', () => {
-        fc.assert(fc.property(forestAndPathAndExpectedArb, ({ entries, path, expected }) => {
+});
+describe('modifyAtPath', () => {
+    it('replaces the generated node', () => {
+        fc.assert(fc.property(nodeAndPathAndExpectedArb, ({ root, path, expected }) => {
             const replacement = {
                 id: expected.id,
             };
-            const updatedForest = stringNodeApi.modifyAtPath(entries, path, () => replacement);
-            expect(updatedForest).not.toBeUndefined();
-            if (updatedForest === undefined) {
+            const updatedRoot = api.modifyAtPath(root, path, () => replacement);
+            expect(updatedRoot).not.toBeUndefined();
+            if (updatedRoot === undefined) {
                 return;
             }
-            expect(stringNodeApi.getAtPath(updatedForest, path, (node) => node)).toBe(replacement);
-            expect(stringNodeApi.getAtPath(entries, path, (node) => node)).toBe(expected);
+            expect(api.getAtPath(updatedRoot, path, (node) => node)).toBe(replacement);
+            expect(api.getAtPath(root, 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) => ({
+    }, 12000);
+    it('replaces children at a branch path', () => {
+        fc.assert(fc.property(nodesArrayAndBranchPathArb, newBranchesOrNullArb, ({ root, path, expected }, newBranches) => {
+            expect(api.isBranch(expected)).toBe(true);
+            const updatedRoot = api.modifyAtPath(root, path, (node) => ({
                 ...node,
                 children: newBranches,
             }));
-            expect(updatedForest).not.toBeUndefined();
-            if (updatedForest === undefined) {
+            expect(updatedRoot).not.toBeUndefined();
+            if (updatedRoot === undefined) {
                 return;
             }
-            const updatedNode = stringNodeApi.getAtPath(updatedForest, path, (node) => node);
+            const updatedNode = api.getAtPath(updatedRoot, path, (node) => node);
             expect(updatedNode).not.toBeUndefined();
             expect(updatedNode).not.toBe(expected);
             if (updatedNode === undefined ||
-                !stringNodeApi.isBranch(updatedNode) ||
-                (!stringNodeApi.isOpenBranch(updatedNode) && newBranches !== null)) {
+                !api.isBranch(updatedNode) ||
+                (!api.isOpenBranch(updatedNode) && newBranches !== null)) {
                 return;
             }
-            if (stringNodeApi.isOpenBranch(updatedNode)) {
-                expect([...stringNodeApi.getChildren(updatedNode)]).toStrictEqual(newBranches);
+            if (api.isOpenBranch(updatedNode)) {
+                expect([...api.getChildren(updatedNode)]).toStrictEqual(newBranches);
             }
-            expect(stringNodeApi.getAtPath(entries, path, (node) => node)).toBe(expected);
+            expect(api.getAtPath(root, 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('UT: calls the modifier once with the resolved node', () => {
+        const child = { id: 'child' };
+        const root = {
+            id: 'root',
+            children: [child],
+        };
+        const replacement = { id: 'replacement' };
+        const modifier = vi.fn(() => replacement);
+        const updatedRoot = api.modifyAtPath(root, ['child'], modifier);
+        expect(updatedRoot).toBeDefined();
+        expect(modifier).toHaveBeenCalledOnce();
+        expect(modifier).toHaveBeenCalledWith(child);
+        expect(api.getAtPath(updatedRoot, ['replacement'], (node) => node)).toBe(replacement);
+        expect(api.getAtPath(updatedRoot, ['child'], (node) => node)).toBeUndefined();
     });
-    it('modifyAtPath returns undefined for an empty path', () => {
-        const entries = [{ id: 'root' }];
-        expect(stringNodeApi.modifyAtPath(entries, [], (node) => node)).toBeUndefined();
+    it('UT: modifies the root for an empty path', () => {
+        const root = { id: 'root' };
+        const replacement = { id: 'replacement' };
+        const modifier = vi.fn(() => replacement);
+        const updatedRoot = api.modifyAtPath(root, [], modifier);
+        expect(updatedRoot).toBe(replacement);
+        expect(modifier).toHaveBeenCalledOnce();
+        expect(modifier).toHaveBeenCalledWith(root);
     });
-    it('modifyAtPath returns undefined for an invalid path', () => {
-        const entries = [
-            {
+    it.each([
+        {
+            name: 'a missing child',
+            root: {
                 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 = [
-            {
+            path: ['missing'],
+        },
+        {
+            name: 'a path through a leaf',
+            root: {
+                id: 'root',
+            },
+            path: ['child'],
+        },
+        {
+            name: 'a path through a closed branch',
+            root: {
                 id: 'root',
                 children: null,
             },
-        ];
-        expect(stringNodeApi.modifyAtPath(entries, ['root', 'child'], (node) => node)).toBeUndefined();
+            path: ['child'],
+        },
+    ])('UT: returns undefined and does not call the modifier', ({ root, path }) => {
+        const modifier = vi.fn((node) => node);
+        const result = api.modifyAtPath(root, path, modifier);
+        expect(result).toBeUndefined();
+        expect(modifier).not.toHaveBeenCalled();
+    });
+    it('UT: returns undefined when the modifier aborts', () => {
+        const root = { id: 'root' };
+        const modifier = vi.fn(() => undefined);
+        const result = api.modifyAtPath(root, [], modifier);
+        expect(result).toBeUndefined();
+        expect(modifier).toHaveBeenCalledOnce();
+        expect(modifier).toHaveBeenCalledWith(root);
     });
 });

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

@@ -1,13 +1,14 @@
 /**
  * A serializable primitive suitable for use as a stable tree ID.
  *
- * The runtime schema guarantees that numeric values are finite. TypeScript
- * cannot represent the exclusion of `NaN` and infinities from `number`, so
- * values from untrusted sources should be validated with
- * `serializableKeySchema` before being used as IDs.
+ * @remarks
+ *
+ * Numeric IDs must be finite. TypeScript cannot represent the exclusion of
+ * `NaN` and infinities from `number`, so values from untrusted sources should
+ * be validated with `serializableKeySchema`.
  *
  * For application-specific IDs, define a narrower branded schema and derive
- * its type with `z.output`.
+ * its type with `z.output`:
  *
  * @example
  *
@@ -27,146 +28,127 @@
  */
 export type SerializableKey = string | number;
 /**
- * A node with no children.
+ * A node in a tree.
+ *
+ * @remarks
+ *
+ * A node's `id` identifies it among its siblings.
+ *
+ * Nodes are discriminated by the shape of their `children` property:
+ *
+ *  - a leaf has no children and does not have a child collection;
+ *  - an open branch has a loaded array of child nodes;
+ *  - a closed branch has children that have not been loaded yet and uses
+ *   `children: null`.
+ *
+ * `Node` is the concrete application-specific node type. It may contain
+ * additional properties, provided that it preserves the leaf-or-branch shape
+ * described by this type.
+ *
+ * The recursive `Node` parameter allows application-specific properties
+ * to be available on every descendant.
+ *
+ * @typeParam Id - The type of node IDs.
+ * @typeParam Node - The application-specific recursive node type.
+ *
+ * @example
+ *
+ * ```ts
+ * type DirectoryEntry = TreeNode<string, DirectoryEntry> & {
+ *   kind: 'file' | 'directory';
+ * };
+ * ```
  */
+export type TreeNode<Id extends SerializableKey, Node extends TreeNode<Id, Node>> = LeafTreeNode<Id> | BranchTreeNode<Id, Node>;
+/** A node with no children. */
 export type LeafTreeNode<Id extends SerializableKey> = {
     id: Id;
     children?: never;
 };
-/**
- * A branch whose children have not been loaded.
- */
-export type ClosedBranchTreeNode<Id extends SerializableKey> = {
+/** A tree node that has children, either loaded or unloaded. */
+export type BranchTreeNode<Id extends SerializableKey, Node extends TreeNode<Id, Node>> = OpenBranchTreeNode<Id, Node> | ClosedBranchTreeNode<Id>;
+/** A branch whose direct children have been loaded. */
+export type OpenBranchTreeNode<Id extends SerializableKey, Node extends TreeNode<Id, Node>> = {
     id: Id;
-    children: null;
+    children: Node[];
 };
-/**
- * A branch whose children have been loaded.
- *
- * TODO Later: Add a dictionary by ID for faster lookup.
- * Then children will just be an array for keeping order.
- */
-export type OpenBranchTreeNode<Id extends SerializableKey, ChildNode extends TreeNode<Id, ChildNode>> = {
+/** A branch whose direct children have not been loaded. */
+export type ClosedBranchTreeNode<Id extends SerializableKey> = {
     id: Id;
-    children: ChildNode[];
+    children: null;
 };
 /**
- * A tree node that has children, either loaded or unloaded.
- */
-export type BranchTreeNode<Id extends SerializableKey, ChildNode extends TreeNode<Id, ChildNode>> = OpenBranchTreeNode<Id, ChildNode> | ClosedBranchTreeNode<Id>;
-/**
- * A node in a tree.
- *
- * `ChildNode` is the concrete application-specific node type. It may contain
- * additional properties, provided that it has the shape of either a leaf or a
- * branch.
- */
-export type TreeNode<Id extends SerializableKey, ChildNode extends TreeNode<Id, ChildNode>> = LeafTreeNode<Id> | BranchTreeNode<Id, ChildNode>;
-/**
- * Selects a value from a node reached by a path.
- *
- * The selector is called only when the complete path exists and identifies
- * a node. Returning `undefined` from the selector is allowed, but is
- * indistinguishable from an unsuccessful lookup in the return value.
- */
-export type TreeNodeSelector<ChildNode, Result> = (node: ChildNode) => Result;
-/**
- * Produces a replacement for a node reached by a path.
+ * Operations for inspecting and immutably updating a tree rooted at a node.
  *
- * Returning `undefined` aborts the modification and causes `modifyAtPath`
- * to return `undefined`.
- */
-export type TreeNodeModifier<ChildNode> = (node: ChildNode) => ChildNode | undefined;
-/**
- * Fundamental operations for inspecting and immutably updating a tree forest.
+ * @remarks
  *
- * A forest is represented by an array of root-level nodes. A path is an array
- * of IDs beginning at a root node and continuing through its descendants.
+ * A path is an array of IDs relative to the supplied root node.
  *
  * For example, given tree with IDs:
  *
  *   root
  *   └── child
  *
- * the path to `child` is `['root', 'child']`.
+ * the path to `root` is `[]`, and the path to `child` is `['child']`.
  *
- * Path traversal and child lookup are performed by this API so that callers
- * do not depend on the internal child-storage representation or need to
- * iterate over children themselves.
+ * Paths cannot pass through leaves or closed branches. A closed branch may be
+ * the final node in a path. An empty path identifies the root node.
  *
- * An empty path does not identify a node and is invalid for both lookup and
- * modification operations.
+ * @typeParam Id - The type of node IDs.
+ * @typeParam Node - The application-specific recursive node type.
  */
-export type TreeNodeApi<Id extends SerializableKey, ChildNode extends TreeNode<Id, ChildNode>> = {
-    isLeaf(node: ChildNode): node is ChildNode & LeafTreeNode<Id>;
-    isBranch(node: ChildNode): node is ChildNode & BranchTreeNode<Id, ChildNode>;
-    isClosedBranch(node: BranchTreeNode<Id, ChildNode>): node is ClosedBranchTreeNode<Id>;
-    isOpenBranch(node: BranchTreeNode<Id, ChildNode>): node is OpenBranchTreeNode<Id, ChildNode>;
+export type TreeNodeApi<Id extends SerializableKey, Node extends TreeNode<Id, Node>> = {
+    isLeaf(node: Node): node is Node & LeafTreeNode<Id>;
+    isBranch(node: Node): node is Node & BranchTreeNode<Id, Node>;
+    isClosedBranch(node: BranchTreeNode<Id, Node>): node is ClosedBranchTreeNode<Id>;
+    isOpenBranch(node: BranchTreeNode<Id, Node>): node is OpenBranchTreeNode<Id, Node>;
     /**
-     * Returns the loaded children of an open branch.
+     * Returns the loaded direct children of an open branch.
      *
-     * The returned iterable preserves the branch's sibling order. The method
-     * can only be called after narrowing the branch with `isOpenBranch`.
+     * The children are returned in sibling order. The returned nodes are the
+     * existing nodes and are not cloned.
      *
-     * The returned children are the existing child nodes; they are not cloned.
+     * @param node - An open branch.
+     * @returns The branch's loaded children.
      */
-    getChildren(node: OpenBranchTreeNode<Id, ChildNode>): Iterable<ChildNode>;
+    getChildren(node: OpenBranchTreeNode<Id, Node>): Iterable<Node>;
     /**
-     * Returns the child with the supplied ID.
+     * Finds a direct child by ID.
      *
-     * Returns `undefined` when the branch has no child with that ID.
-     * The returned child is the existing node; it is not cloned.
+     * @param node - An open branch.
+     * @param id - The ID of the child to find.
+     * @returns The existing child, or `undefined` when no matching child exists.
      */
-    getChildById(node: OpenBranchTreeNode<Id, ChildNode>, id: Id): ChildNode | undefined;
+    getChildById(node: OpenBranchTreeNode<Id, Node>, id: Id): Node | undefined;
     /**
-     * Applies `selector` to the node at `path`.
-     *
-     * The path must:
-     *
-     * - be non-empty;
-     * - begin at one of the supplied forest entries;
-     * - contain only IDs that identify existing entries;
-     * - not traverse through a leaf; and
-     * - not traverse through a closed branch.
-     *
-     * A branch at the end of the path is valid even when it is closed.
+     * Applies a selector to the node at a path relative to `root`.
      *
      * The selector is called only after the complete path has been resolved.
-     * This method does not clone the tree or the selected node.
+     * The selected node is not cloned.
      *
-     * Returns `undefined` when the path cannot be resolved, or when the
-     * selector returns `undefined`.
+     * @param root - The node searching through.
+     * @param path - Path relative to root, with empty selecting the root.
+     * @param selector - The function to apply to the resolved node.
+     * @returns The selector result, or `undefined` when the path cannot be
+     * resolved or the selector returns `undefined`.
      */
-    getAtPath<Result>(entries: ChildNode[], path: Id[], selector: TreeNodeSelector<ChildNode, Result>): Result | undefined;
+    getAtPath<Result>(root: Node, path: readonly Id[], selector: (node: Node) => Result): Result | undefined;
     /**
-     * Immutably modifies the node at `path`.
+     * Immutably replaces the node at a path relative to `root`.
      *
      * The modifier is called only after the complete path has been resolved.
-     * Its return value replaces the target node. Returning `undefined` aborts
-     * the modification.
-     *
-     * The operation creates new arrays and ancestor nodes along the path.
-     * Nodes and arrays unrelated to the path retain their original object
-     * identity. The input forest and its nodes (as objects) are never modified.
-     *
-     * The path must:
-     *
-     * - be non-empty;
-     * - begin at one of the supplied forest entries;
-     * - contain only IDs that identify existing entries;
-     * - not traverse through a leaf; and
-     * - not traverse through a closed branch.
-     *
-     * A leaf or branch, including a closed branch, may be the final target.
+     * Returning `undefined` aborts the modification.
      *
-     * Returns `undefined` when:
+     * New arrays and ancestor nodes are created along the modified path.
+     * Unrelated nodes and arrays retain their original object identity. The
+     * input array is never modified.
      *
-     * - `path` is empty;
-     * - the path does not exist;
-     * - an intermediate node is a leaf;
-     * - an intermediate branch is closed; or
-     * - the modifier returns `undefined`.
+     * @param root - The root node to modify.
+     * @param path - A path relative to root. An empty path selects the root.
+     * @param modifier - Produces the replacement node.
+     * @returns A new root, or `undefined` when the path cannot be resolved or
+     * the modifier returns `undefined`.
      */
-    modifyAtPath(entries: ChildNode[], path: Id[], modifier: TreeNodeModifier<ChildNode>): ChildNode[] | undefined;
+    modifyAtPath(root: Node, path: readonly Id[], modifier: (node: Node) => Node | undefined): Node | undefined;
 };
 //# sourceMappingURL=tree-node.types.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"tree-node.types.d.ts","sourceRoot":"","sources":["../../../src/tree-surfer/tree-node/tree-node.types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"tree-node.types.d.ts","sourceRoot":"","sources":["../../../src/tree-surfer/tree-node/tree-node.types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,MAAM,CAAC;AAE9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,MAAM,QAAQ,CAClB,EAAE,SAAS,eAAe,EAC1B,IAAI,SAAS,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC,IAC7B,YAAY,CAAC,EAAE,CAAC,GAAG,cAAc,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;AAEhD,+BAA+B;AAC/B,MAAM,MAAM,YAAY,CAAC,EAAE,SAAS,eAAe,IAAI;IACrD,EAAE,EAAE,EAAE,CAAC;IACP,QAAQ,CAAC,EAAE,KAAK,CAAC;CAClB,CAAC;AAEF,gEAAgE;AAChE,MAAM,MAAM,cAAc,CACxB,EAAE,SAAS,eAAe,EAC1B,IAAI,SAAS,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC,IAC7B,kBAAkB,CAAC,EAAE,EAAE,IAAI,CAAC,GAAG,oBAAoB,CAAC,EAAE,CAAC,CAAC;AAK5D,uDAAuD;AACvD,MAAM,MAAM,kBAAkB,CAC5B,EAAE,SAAS,eAAe,EAC1B,IAAI,SAAS,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC,IAC7B;IACF,EAAE,EAAE,EAAE,CAAC;IACP,QAAQ,EAAE,IAAI,EAAE,CAAC;CAClB,CAAC;AAEF,2DAA2D;AAC3D,MAAM,MAAM,oBAAoB,CAAC,EAAE,SAAS,eAAe,IAAI;IAC7D,EAAE,EAAE,EAAE,CAAC;IACP,QAAQ,EAAE,IAAI,CAAC;CAChB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,MAAM,WAAW,CACrB,EAAE,SAAS,eAAe,EAC1B,IAAI,SAAS,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC,IAC7B;IACF,MAAM,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,IAAI,IAAI,GAAG,YAAY,CAAC,EAAE,CAAC,CAAC;IACpD,QAAQ,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,IAAI,IAAI,GAAG,cAAc,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;IAC9D,cAAc,CACZ,IAAI,EAAE,cAAc,CAAC,EAAE,EAAE,IAAI,CAAC,GAC7B,IAAI,IAAI,oBAAoB,CAAC,EAAE,CAAC,CAAC;IACpC,YAAY,CACV,IAAI,EAAE,cAAc,CAAC,EAAE,EAAE,IAAI,CAAC,GAC7B,IAAI,IAAI,kBAAkB,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;IAExC;;;;;;;;OAQG;IACH,WAAW,CAAC,IAAI,EAAE,kBAAkB,CAAC,EAAE,EAAE,IAAI,CAAC,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC;IAEhE;;;;;;OAMG;IACH,YAAY,CAAC,IAAI,EAAE,kBAAkB,CAAC,EAAE,EAAE,IAAI,CAAC,EAAE,EAAE,EAAE,EAAE,GAAG,IAAI,GAAG,SAAS,CAAC;IAE3E;;;;;;;;;;;OAWG;IACH,SAAS,CAAC,MAAM,EACd,IAAI,EAAE,IAAI,EACV,IAAI,EAAE,SAAS,EAAE,EAAE,EACnB,QAAQ,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,MAAM,GAC/B,MAAM,GAAG,SAAS,CAAC;IAEtB;;;;;;;;;;;;;;;OAeG;IACH,YAAY,CACV,IAAI,EAAE,IAAI,EACV,IAAI,EAAE,SAAS,EAAE,EAAE,EACnB,QAAQ,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,IAAI,GAAG,SAAS,GACzC,IAAI,GAAG,SAAS,CAAC;CACrB,CAAC"}

package/dist/tree-surfer-ui/application/intent-to-effect.d.ts

@@ -1,6 +1,10 @@
 import { SerializableKey, TreeNode, TreeNodeApi } from '../../tree-surfer/index.js';
 import { Effect, Intent } from '../domain/index.js';
 import { CursorApi, State, StateApi } from '../../tree-surfer/index.js';
-export type IntentToEffect<Id extends SerializableKey, BufferNode extends TreeNode<Id, BufferNode>> = (intent: Intent, state: State<Id, BufferNode>) => Effect<Id, BufferNode> | undefined;
-export declare function createIntentToEffect<Id extends SerializableKey, BufferNode extends TreeNode<Id, BufferNode>>(stateApi: StateApi<Id, BufferNode>, cursorApi: CursorApi<Id>, treeNodeApi: TreeNodeApi<Id, BufferNode>): IntentToEffect<Id, BufferNode>;
+/**
+ * By design "effect = intent + state", so it awaits based on the intent and
+ * the current state whether an effect should be executed.
+ */
+export type IntentToEffect<Id extends SerializableKey, Node extends TreeNode<Id, Node>> = (intent: Intent, state: State<Id, Node>) => Effect<Id, Node> | undefined;
+export declare function createIntentToEffect<Id extends SerializableKey, Node extends TreeNode<Id, Node>>(stateApi: StateApi<Id, Node>, cursorApi: CursorApi<Id>, treeNodeApi: TreeNodeApi<Id, Node>): IntentToEffect<Id, Node>;
 //# sourceMappingURL=intent-to-effect.d.ts.map

package/dist/tree-surfer-ui/application/intent-to-effect.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"intent-to-effect.d.ts","sourceRoot":"","sources":["../../../src/tree-surfer-ui/application/intent-to-effect.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,eAAe,EACf,QAAQ,EACR,WAAW,EACZ,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,MAAM,EAAgB,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAClE,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,4BAA4B,CAAC;AAIxE,MAAM,MAAM,cAAc,CACxB,EAAE,SAAS,eAAe,EAC1B,UAAU,SAAS,QAAQ,CAAC,EAAE,EAAE,UAAU,CAAC,IACzC,CACF,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,KAAK,CAAC,EAAE,EAAE,UAAU,CAAC,KACzB,MAAM,CAAC,EAAE,EAAE,UAAU,CAAC,GAAG,SAAS,CAAC;AAGxC,wBAAgB,oBAAoB,CAClC,EAAE,SAAS,eAAe,EAC1B,UAAU,SAAS,QAAQ,CAAC,EAAE,EAAE,UAAU,CAAC,EAE3C,QAAQ,EAAE,QAAQ,CAAC,EAAE,EAAE,UAAU,CAAC,EAClC,SAAS,EAAE,SAAS,CAAC,EAAE,CAAC,EACxB,WAAW,EAAE,WAAW,CAAC,EAAE,EAAE,UAAU,CAAC,GACvC,cAAc,CAAC,EAAE,EAAE,UAAU,CAAC,CAkEhC"}
+{"version":3,"file":"intent-to-effect.d.ts","sourceRoot":"","sources":["../../../src/tree-surfer-ui/application/intent-to-effect.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,eAAe,EACf,QAAQ,EACR,WAAW,EACZ,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,MAAM,EAAgB,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAClE,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,4BAA4B,CAAC;AAGxE;;;GAGG;AACH,MAAM,MAAM,cAAc,CACxB,EAAE,SAAS,eAAe,EAC1B,IAAI,SAAS,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC,IAC7B,CACF,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,KAAK,CAAC,EAAE,EAAE,IAAI,CAAC,KACnB,MAAM,CAAC,EAAE,EAAE,IAAI,CAAC,GAAG,SAAS,CAAC;AAElC,wBAAgB,oBAAoB,CAClC,EAAE,SAAS,eAAe,EAC1B,IAAI,SAAS,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC,EAE/B,QAAQ,EAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC,EAC5B,SAAS,EAAE,SAAS,CAAC,EAAE,CAAC,EACxB,WAAW,EAAE,WAAW,CAAC,EAAE,EAAE,IAAI,CAAC,GACjC,cAAc,CAAC,EAAE,EAAE,IAAI,CAAC,CAmE1B"}

package/dist/tree-surfer-ui/application/intent-to-effect.js

@@ -1,5 +1,4 @@
 import { parseCommand } from './parse-command.js';
-// Factory method, since Apis are needed to derive intent
 export function createIntentToEffect(stateApi, cursorApi, treeNodeApi) {
     return (intent, state) => {
         switch (intent.intentType) {
@@ -73,10 +72,6 @@ function normalBufferToEffectResult(updatedNormalBuffer) {
                     normalBuffer: updatedNormalBuffer,
                 },
             };
-        case 'za':
-            return dispatchAction({
-                effectActionType: 'toggleFold',
-            });
         case 'zc':
             return dispatchAction({
                 effectActionType: 'fold',
@@ -120,7 +115,7 @@ function normalInteractRightToEffect(state, stateApi, cursorApi, treeNodeApi) {
     return;
 }
 function normalInteractLeftToEffect(state) {
-    if (state.cursor.parentPath.length === 0) {
+    if (state.cursor.length === 0) {
         return undefined;
     }
     return dispatchAction({

package/dist/tree-surfer-ui/application/user-input-to-intent.d.ts

@@ -1,3 +1,11 @@
-import { UserInput, InputState, Intent } from '../domain/index.js';
-export declare function userInputToIntent(userInput: UserInput, inputState: InputState): Intent | undefined;
+import { UserInput, InputModeState, Intent } from '../domain/index.js';
+/**
+ * By design "intent = input + mode + modeState", so it interprets the key
+ * inputs depending on the mode and input so far. No context in terms of UI.
+ *
+ * @param userInput - the key user input.
+ * @param inputModeState - the current mode and the user inputs so far.
+ * @returns The user's intent.
+ */
+export declare function userInputToIntent(userInput: UserInput, inputModeState: InputModeState): Intent | undefined;
 //# sourceMappingURL=user-input-to-intent.d.ts.map

package/dist/tree-surfer-ui/application/user-input-to-intent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"user-input-to-intent.d.ts","sourceRoot":"","sources":["../../../src/tree-surfer-ui/application/user-input-to-intent.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAGnE,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,SAAS,EACpB,UAAU,EAAE,UAAU,GACrB,MAAM,GAAG,SAAS,CAQpB"}
+{"version":3,"file":"user-input-to-intent.d.ts","sourceRoot":"","sources":["../../../src/tree-surfer-ui/application/user-input-to-intent.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAEvE;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,SAAS,EACpB,cAAc,EAAE,cAAc,GAC7B,MAAM,GAAG,SAAS,CAQpB"}

package/dist/tree-surfer-ui/application/user-input-to-intent.js

@@ -1,10 +1,17 @@
-// Derive the intent from the user input and the current input state.
-export function userInputToIntent(userInput, inputState) {
-    switch (inputState.inputMode) {
+/**
+ * By design "intent = input + mode + modeState", so it interprets the key
+ * inputs depending on the mode and input so far. No context in terms of UI.
+ *
+ * @param userInput - the key user input.
+ * @param inputModeState - the current mode and the user inputs so far.
+ * @returns The user's intent.
+ */
+export function userInputToIntent(userInput, inputModeState) {
+    switch (inputModeState.inputMode) {
         case 'normal':
-            return normalUserInputToIntent(userInput, inputState.normalBuffer);
+            return normalUserInputToIntent(userInput, inputModeState.normalBuffer);
         case 'command':
-            return commandUserInputToIntent(userInput, inputState.commandLine);
+            return commandUserInputToIntent(userInput, inputModeState.commandLine);
     }
 }
 function normalUserInputToIntent(userInput, normalBuffer) {