dirvi-lib 0.8.0 → 0.8.2

package/dist/trees/fold-node/deprecated/fold-node.impl.js

@@ -0,0 +1,248 @@
+/**
+ * Creates semantic operations for a fold-state tree.
+ *
+ * Structural children are owned by `FoldNodeApi`; folded children are
+ * application-owned FoldNode values stored in `FoldNodeValue`.
+ */
+export function createFoldNodeService(foldNodeApi) {
+    function createEmptyNode(id) {
+        const node = foldNodeApi.createLoadedBranch(id, { foldedChildren: [] }, []);
+        /*
+         * An empty child collection cannot contain duplicate sibling IDs, so this
+         * would indicate a broken TreeNodeApi implementation or changed contract.
+         */
+        if (node === undefined) {
+            throw new Error('Could not create an empty fold node');
+        }
+        return node;
+    }
+    /**
+     * Returns an array snapshot of loaded structural children.
+     *
+     * Fold nodes are intended always to be open branches. `undefined` therefore
+     * signals an invalid FoldNode supplied to this service, for example one made
+     * with `asLeaf` or `asClosedBranch` through the lower-level tree API.
+     */
+    function getStructuralChildren(node) {
+        const children = foldNodeApi.getLoadedChildren(node);
+        return children === undefined ? undefined : [...children];
+    }
+    function getFoldedChildren(node) {
+        return foldNodeApi.value(node).foldedChildren;
+    }
+    function getFoldedChildById(node, id) {
+        return getFoldedChildren(node).find((child) => foldNodeApi.id(child) === id);
+    }
+    function hasFoldedChildWithId(node, id) {
+        return getFoldedChildById(node, id) !== undefined;
+    }
+    /**
+     * Replaces only fold-domain data, retaining the node's ID and structural
+     * child state.
+     */
+    function withFoldedChildren(node, foldedChildren) {
+        return foldNodeApi.withValue(node, {
+            ...foldNodeApi.value(node),
+            foldedChildren,
+        });
+    }
+    /**
+     * Replaces structural children while requiring that the source node is
+     * already an open branch.
+     *
+     * `withChildren` could convert any tree node into an open branch. That is
+     * useful in the generic API, but FoldNodeService wants to preserve its
+     * invariant that every FoldNode is already an open branch.
+     */
+    function withStructuralChildren(node, children) {
+        if (foldNodeApi.getLoadedChildren(node) === undefined) {
+            return undefined;
+        }
+        return foldNodeApi.withLoadedChildren(node, children);
+    }
+    /**
+     * Returns whether a fold-state node carries state below itself.
+     *
+     * A folded node has nested state when it has either:
+     *
+     * - structural child fold nodes; or
+     * - folded direct children.
+     */
+    function hasNestedFoldState(node) {
+        const structuralChildren = getStructuralChildren(node);
+        if (structuralChildren === undefined) {
+            return undefined;
+        }
+        return structuralChildren.length > 0 || getFoldedChildren(node).length > 0;
+    }
+    return {
+        createEmptyNode,
+        getIfEntryFoldedAtPath(rootNode, path, entryId) {
+            return (foldNodeApi.selectAtPath(rootNode, path, (node) => hasFoldedChildWithId(node, entryId)) ?? false);
+        },
+        foldedEntriesAtPath(rootNode, path) {
+            return foldNodeApi.selectAtPath(rootNode, path, (node) => getFoldedChildren(node).map(foldNodeApi.id));
+        },
+        addFoldedEntryAtPath(rootNode, path, entryId) {
+            const rootWithPath = ensurePath(rootNode, path);
+            if (rootWithPath === undefined) {
+                return undefined;
+            }
+            return foldNodeApi.updateAtPath(rootWithPath, path, (node) => addFoldedEntry(node, entryId));
+        },
+        removeFoldedEntryAtPath(rootNode, path, entryId) {
+            return foldNodeApi.updateAtPath(rootNode, path, (node) => removeFoldedEntry(node, entryId));
+        },
+        clearFoldedEntriesAtPath(rootNode, path) {
+            return foldNodeApi.updateAtPath(rootNode, path, clearFoldedEntries);
+        },
+    };
+    /**
+     * Folds a direct child at one node.
+     *
+     * If the child already exists as a structural child, it moves to
+     * `foldedChildren`, preserving any fold state beneath it. If it does not
+     * exist in either collection, a new empty fold node is created.
+     */
+    function addFoldedEntry(node, entryId) {
+        if (hasFoldedChildWithId(node, entryId)) {
+            return node;
+        }
+        const children = getStructuralChildren(node);
+        if (children === undefined) {
+            return undefined;
+        }
+        const childIndex = children.findIndex((child) => foldNodeApi.id(child) === entryId);
+        const foldedChild = childIndex === -1 ? createEmptyNode(entryId) : children[childIndex];
+        if (foldedChild === undefined) {
+            return undefined;
+        }
+        const remainingChildren = childIndex === -1
+            ? children
+            : [...children.slice(0, childIndex), ...children.slice(childIndex + 1)];
+        const nodeWithoutStructuralChild = withStructuralChildren(node, remainingChildren);
+        if (nodeWithoutStructuralChild === undefined) {
+            return undefined;
+        }
+        return withFoldedChildren(nodeWithoutStructuralChild, [
+            ...getFoldedChildren(nodeWithoutStructuralChild),
+            foldedChild,
+        ]);
+    }
+    /**
+     * Unfolds a direct child at one node.
+     *
+     * A folded child that has nested fold state is moved into structural
+     * children. A folded child without nested state is omitted entirely.
+     */
+    function removeFoldedEntry(node, entryId) {
+        const foldedChildren = getFoldedChildren(node);
+        const foldedChildIndex = foldedChildren.findIndex((child) => foldNodeApi.id(child) === entryId);
+        if (foldedChildIndex === -1) {
+            return node;
+        }
+        const foldedChild = foldedChildren[foldedChildIndex];
+        if (foldedChild === undefined) {
+            return undefined;
+        }
+        const hasNestedState = hasNestedFoldState(foldedChild);
+        if (hasNestedState === undefined) {
+            return undefined;
+        }
+        const remainingFoldedChildren = [
+            ...foldedChildren.slice(0, foldedChildIndex),
+            ...foldedChildren.slice(foldedChildIndex + 1),
+        ];
+        const nodeWithoutFoldedChild = withFoldedChildren(node, remainingFoldedChildren);
+        if (!hasNestedState) {
+            return nodeWithoutFoldedChild;
+        }
+        const children = getStructuralChildren(nodeWithoutFoldedChild);
+        if (children === undefined) {
+            return undefined;
+        }
+        return withStructuralChildren(nodeWithoutFoldedChild, [
+            ...children,
+            foldedChild,
+        ]);
+    }
+    /**
+     * Unfolds all directly folded children at one node.
+     *
+     * Folded children that contain nested state become structural children;
+     * empty folded children are omitted.
+     */
+    function clearFoldedEntries(node) {
+        const foldedChildren = getFoldedChildren(node);
+        if (foldedChildren.length === 0) {
+            return node;
+        }
+        const children = getStructuralChildren(node);
+        if (children === undefined) {
+            return undefined;
+        }
+        const retainedFoldedChildren = [];
+        for (const foldedChild of foldedChildren) {
+            const nestedState = hasNestedFoldState(foldedChild);
+            if (nestedState === undefined) {
+                return undefined;
+            }
+            if (nestedState) {
+                retainedFoldedChildren.push(foldedChild);
+            }
+        }
+        const nodeWithoutFoldedChildren = withFoldedChildren(node, []);
+        return withStructuralChildren(nodeWithoutFoldedChildren, [
+            ...children,
+            ...retainedFoldedChildren,
+        ]);
+    }
+    /**
+     * Ensures the path exists as structural fold nodes.
+     *
+     * A path may not pass through a folded child: folded children represent
+     * entries whose contents are collapsed, so they cannot simultaneously be
+     * part of the visible structural fold-state path.
+     */
+    function ensurePath(rootNode, path) {
+        return ensurePathAtIndex(rootNode, path, 0);
+    }
+    function ensurePathAtIndex(node, path, pathIndex) {
+        if (pathIndex === path.length) {
+            return node;
+        }
+        const childId = path[pathIndex];
+        if (childId === undefined) {
+            return undefined;
+        }
+        /*
+         * A folded child is intentionally absent from the structural child tree.
+         * Do not create a duplicate FoldNode with the same ID in `children`.
+         */
+        if (hasFoldedChildWithId(node, childId)) {
+            return undefined;
+        }
+        const children = getStructuralChildren(node);
+        if (children === undefined) {
+            return undefined;
+        }
+        const childIndex = children.findIndex((child) => foldNodeApi.id(child) === childId);
+        const child = childIndex === -1 ? createEmptyNode(childId) : children[childIndex];
+        if (child === undefined) {
+            return undefined;
+        }
+        const updatedChild = ensurePathAtIndex(child, path, pathIndex + 1);
+        if (updatedChild === undefined) {
+            return undefined;
+        }
+        if (childIndex === -1) {
+            return withStructuralChildren(node, [...children, updatedChild]);
+        }
+        if (updatedChild === child) {
+            return node;
+        }
+        const updatedChildren = [...children];
+        updatedChildren[childIndex] = updatedChild;
+        return withStructuralChildren(node, updatedChildren);
+    }
+}

package/dist/trees/fold-node/deprecated/fold-node.test.d.ts

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

package/dist/trees/fold-node/deprecated/fold-node.test.d.ts.map

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

package/dist/trees/fold-node/deprecated/fold-node.test.js

@@ -0,0 +1,130 @@
+import { describe, expect, it } from 'vitest';
+import { createTreeNodeApi } from '../../tree-node/tree-node.impl.js';
+import { createFoldNodeService } from './fold-node.impl.js';
+const foldNodeApi = createTreeNodeApi();
+const service = createFoldNodeService(foldNodeApi);
+function createFoldNode(id, options = {}) {
+    const node = foldNodeApi.createLoadedBranch(id, {
+        foldedChildren: options.foldedChildren ?? [],
+    }, options.children ?? []);
+    if (node === undefined) {
+        throw new Error('Test fixture has duplicate structural child IDs');
+    }
+    return node;
+}
+function getStructuralChildren(node) {
+    const children = foldNodeApi.getLoadedChildren(node);
+    if (children === undefined) {
+        throw new Error('Expected test FoldNode to be an open branch');
+    }
+    return [...children];
+}
+function getFoldedChildren(node) {
+    return foldNodeApi.value(node).foldedChildren;
+}
+function expectFoldNode(node, expected) {
+    expect(foldNodeApi.id(node)).toBe(expected.id);
+    expect(getStructuralChildren(node).map(foldNodeApi.id)).toStrictEqual(expected.childIds);
+    expect(getFoldedChildren(node).map(foldNodeApi.id)).toStrictEqual(expected.foldedChildIds);
+}
+describe('createFoldNodeService', () => {
+    it('UT: adds a new entry to folded children', () => {
+        const root = service.createEmptyNode(0);
+        const updated = service.addFoldedEntryAtPath(root, [], 0);
+        expect(updated).toBeDefined();
+        if (updated === undefined) {
+            return;
+        }
+        expectFoldNode(updated, {
+            id: 0,
+            childIds: [],
+            foldedChildIds: [0],
+        });
+        const foldedChild = getFoldedChildren(updated)[0];
+        expect(foldedChild).toBeDefined();
+        if (foldedChild === undefined) {
+            return;
+        }
+        expectFoldNode(foldedChild, {
+            id: 0,
+            childIds: [],
+            foldedChildIds: [],
+        });
+    });
+    it('UT: moves an existing structural entry to folded children', () => {
+        const child = createFoldNode(1);
+        const root = createFoldNode(0, {
+            children: [child],
+        });
+        const updated = service.addFoldedEntryAtPath(root, [], 1);
+        expect(updated).toBeDefined();
+        if (updated === undefined) {
+            return;
+        }
+        expectFoldNode(updated, {
+            id: 0,
+            childIds: [],
+            foldedChildIds: [1],
+        });
+        /*
+         * Moving an existing child preserves the exact node value, including any
+         * fold state nested below it.
+         */
+        expect(getFoldedChildren(updated)[0]).toBe(child);
+        /*
+         * The original immutable tree remains unchanged.
+         */
+        expectFoldNode(root, {
+            id: 0,
+            childIds: [1],
+            foldedChildIds: [],
+        });
+    });
+    it('UT: preserves nested fold state when moving an entry', () => {
+        const nestedChild = createFoldNode(2);
+        const child = createFoldNode(1, {
+            foldedChildren: [nestedChild],
+        });
+        const root = createFoldNode(0, {
+            children: [child],
+        });
+        const updated = service.addFoldedEntryAtPath(root, [], 1);
+        expect(updated).toBeDefined();
+        if (updated === undefined) {
+            return;
+        }
+        expectFoldNode(updated, {
+            id: 0,
+            childIds: [],
+            foldedChildIds: [1],
+        });
+        const movedChild = getFoldedChildren(updated)[0];
+        expect(movedChild).toBe(child);
+        if (movedChild === undefined) {
+            return;
+        }
+        expectFoldNode(movedChild, {
+            id: 1,
+            childIds: [],
+            foldedChildIds: [2],
+        });
+        expect(getFoldedChildren(movedChild)[0]).toBe(nestedChild);
+    });
+    it('UT: rejects a path through a folded entry', () => {
+        const foldedChild = createFoldNode(1);
+        const root = createFoldNode(0, {
+            foldedChildren: [foldedChild],
+        });
+        const updated = service.addFoldedEntryAtPath(root, [1], 2);
+        expect(updated).toBeUndefined();
+        /*
+         * The failed immutable operation leaves the original root untouched.
+         */
+        expectFoldNode(root, {
+            id: 0,
+            childIds: [],
+            foldedChildIds: [1],
+        });
+        expect(getFoldedChildren(root)[0]).toBe(foldedChild);
+    });
+});

package/dist/{tree-surfer/fold-node → trees/fold-node/deprecated}/fold-node.types.d.ts

@@ -1,84 +1,24 @@
-import { SerializableKey, TreeNodeApi } from '../tree-node/tree-node.types.js';
+import type { TreeNode, TreeNodeApi, SerializableKey } from '../../tree-node/index.js';
 /**
- * A node in the fold-state tree.
+ * Application-specific state stored in each fold-tree node.
  *
- * @remarks
- *
- * A fold-state tree is a sparse projection of a buffer tree. Apart from its
- * root, it stores only nodes that are folded or that have fold information
- * somewhere below them. It does not contain buffer entries or buffer-specific
- * properties.
- *
- * The `id` identifies the corresponding buffer entry among its siblings.
- *
- * `children` contains fold-state nodes for direct buffer entries that are not
- * folded at this node but have fold information below them.
- *
- * `foldedChildren` contains fold-state nodes for direct buffer entries whose contents
- * are folded at this node. Each folded entry is represented by a complete
- * `FoldNode`, allowing fold state within a folded entry to be preserved
- * recursively.
- *
- * A direct buffer entry with no fold state at or below it is omitted from both
- * collections. Consequently, the union of `children` and `foldedChildren` does not
- * need to contain every direct buffer child.
- *
- * The following invariant holds for every fold-state node:
- *
- *  - no ID occurs more than once in `children`;
- *  - no ID occurs more than once in `foldedChildren`;
- *  - no ID occurs in both collections;
- *  - every ID in either collection identifies a direct child in the
- *    corresponding buffer-tree node.
- *
- * Every fold node is an open branch from the perspective of `TreeNodeApi`.
- * Missing paths may nevertheless be created lazily by `FoldNodeService`.
- *
- * @typeParam Id - The type of IDs in the actual tree nodes.
- *
- * @example
- *
- * ```ts
- * type FileId = string;
- * type FileFoldNode = FoldNode<FileId>;
- *
- * const root: FileFoldNode = {
- *   id: '/',
- *   children: [],
- *   foldedChildren: [],
- * };
- * ```
+ * Structural children are owned by TreeNode. `foldedChildren` are semantic
+ * fold-state children: direct buffer entries whose contents are folded.
  */
-export type FoldNode<Id extends SerializableKey> = {
-    id: Id;
-    children: FoldNode<Id>[];
-    foldedChildren: FoldNode<Id>[];
-};
+export type FoldNodeValue<Id extends SerializableKey> = Readonly<{
+    foldedChildren: readonly FoldNode<Id>[];
+}>;
 /**
- * Operations for inspecting and immutably updating a fold-state tree.
- *
- * @remarks
- *
- * This API is `TreeNodeApi` specialized for `FoldNode`. It provides structural
- * tree operations such as node lookup and immutable path updates.
- *
- * Paths are relative to the supplied root node:
- *
- *  - `[]` identifies the root;
- *  - `['child']` identifies a direct child of the root;
- *  - `['child', 'grandchild']` identifies a descendant.
+ * A fold-state node.
  *
- * Path operations are strict. They operate only on nodes that already exist
- * in the fold-state tree. Use `FoldNodeService` when missing fold-state nodes
- * should be automatically created.
- *
- * The API does not interpret the `foldedChildren` collection. It only navigates and
- * updates the structural `children` tree. The semantic operations for adding
- * and removing foldedChildren belong to `FoldNodeService`.
- *
- * @typeParam Id - The type of IDs in the actual tree nodes.
+ * The structural child tree is represented by the opaque TreeNode. The value
+ * holds only fold-specific state.
  */
-export type FoldNodeApi<Id extends SerializableKey> = TreeNodeApi<Id, FoldNode<Id>>;
+export type FoldNode<Id extends SerializableKey> = TreeNode<Id, FoldNodeValue<Id>>;
+/**
+ * Generic structural operations specialized to a fold-state tree.
+ */
+export type FoldNodeApi<Id extends SerializableKey> = TreeNodeApi<Id, FoldNodeValue<Id>>;
 /**
  * Semantic operations for managing fold state.
  *
@@ -188,6 +128,5 @@ export type FoldNodeService<Id extends SerializableKey> = {
      * `undefined` when the path does not exist.
      */
     clearFoldedEntriesAtPath(rootNode: FoldNode<Id>, path: readonly Id[]): FoldNode<Id> | undefined;
-    clearFoldedEntriesAtPath(rootNode: FoldNode<Id>, path: readonly Id[]): FoldNode<Id> | undefined;
 };
 //# sourceMappingURL=fold-node.types.d.ts.map

package/dist/trees/fold-node/deprecated/fold-node.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fold-node.types.d.ts","sourceRoot":"","sources":["../../../../src/trees/fold-node/deprecated/fold-node.types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAEvF;;;;;GAKG;AACH,MAAM,MAAM,aAAa,CAAC,EAAE,SAAS,eAAe,IAAI,QAAQ,CAAC;IAC/D,cAAc,EAAE,SAAS,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAC;CACzC,CAAC,CAAC;AAEH;;;;;GAKG;AACH,MAAM,MAAM,QAAQ,CAAC,EAAE,SAAS,eAAe,IAAI,QAAQ,CACzD,EAAE,EACF,aAAa,CAAC,EAAE,CAAC,CAClB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,WAAW,CAAC,EAAE,SAAS,eAAe,IAAI,WAAW,CAC/D,EAAE,EACF,aAAa,CAAC,EAAE,CAAC,CAClB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;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;CAC7B,CAAC"}

package/dist/trees/fold-node/fold-node.impl.d.ts

@@ -0,0 +1,16 @@
+import type { SerializableKey, TreeNodeApi } from '../tree-node/index.js';
+import type { FoldsApi } from './fold-node.types.js';
+/**
+ * IDs of direct source-tree entries hidden at one source-tree branch.
+ */
+type HiddenEntryIds<Id extends SerializableKey> = readonly Id[];
+/**
+ * Creates operations for an immutable collection of independently active fold
+ * trees.
+ *
+ * Each fold tree preserves its own hidden-entry definition. An entry is hidden
+ * by the aggregate when at least one active fold tree hides it.
+ */
+export declare function createFoldsApi<Id extends SerializableKey>(foldTreeApi: TreeNodeApi<Id, HiddenEntryIds<Id>>): FoldsApi<Id>;
+export {};
+//# sourceMappingURL=fold-node.impl.d.ts.map

package/dist/trees/fold-node/fold-node.impl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fold-node.impl.d.ts","sourceRoot":"","sources":["../../../src/trees/fold-node/fold-node.impl.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,eAAe,EAEf,WAAW,EACZ,MAAM,uBAAuB,CAAC;AAM/B,OAAO,KAAK,EAIV,QAAQ,EACT,MAAM,sBAAsB,CAAC;AAE9B;;GAEG;AACH,KAAK,cAAc,CAAC,EAAE,SAAS,eAAe,IAAI,SAAS,EAAE,EAAE,CAAC;AA0ChE;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,EAAE,SAAS,eAAe,EACvD,WAAW,EAAE,WAAW,CAAC,EAAE,EAAE,cAAc,CAAC,EAAE,CAAC,CAAC,GAC/C,QAAQ,CAAC,EAAE,CAAC,CAmmBd"}