dirvi-lib 0.6.1 → 0.7.1

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

@@ -1,71 +1,172 @@
 import * as fc from 'fast-check';
-export const idArb = fc.string({
+/**
+ * Characters used by readable generated node IDs.
+ */
+const smallLetterCharacters = Array.from('abcdefghijklmnopqrstuvwxyz');
+/**
+ * Generates valid string IDs for test nodes. Note that the API just does
+ * comparisons on the IDs so we can safely restrict to any subset.
+ */
+export const testIdArb = fc.string({
+    unit: fc.constantFrom(...smallLetterCharacters),
     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'), {
+/**
+ * Generates the metadata for a leaf node.
+ *
+ * @param id - The ID assigned to the leaf.
+ * @returns The leaf and the path that resolves to it.
+ */
+const generatedLeafNodeWithReachableNodes = (id) => {
+    const node = { id };
+    return {
+        node,
+        reachableNodes: [{ path: [id], node }],
+    };
+};
+/**
+ * Generates the metadata for a closed branch.
+ *
+ * A closed branch contributes no descendant paths because its children are not
+ * loaded.
+ *
+ * @param id - The ID assigned to the branch.
+ * @returns The closed branch and the path that resolves to it.
+ */
+const generatedClosedBranchWithReachableNodes = (id) => {
+    const node = {
+        id,
+        children: null,
+    };
+    return {
+        node,
+        reachableNodes: [{ path: [id], node }],
+    };
+};
+/**
+ * Generates the metadata for an open branch and its descendants.
+ *
+ * @param id - The ID assigned to the branch.
+ * @param children - The generated children of the branch.
+ * @returns The open branch and paths to the branch and all its descendants.
+ */
+const generatedOpenBranchWithReachableNodes = (id, children) => {
+    const node = {
+        id,
+        children: children.map(({ node }) => node),
+    };
+    const descendantNodes = children.flatMap(({ reachableNodes }) => reachableNodes.map(({ path, node }) => ({
+        path: [id, ...path],
+        node,
+    })));
+    return {
+        node,
+        reachableNodes: [
+            { path: [id], node },
+            ...descendantNodes,
+        ],
+    };
+};
+/**
+ * Generates a leaf node.
+ */
+export const generatedLeafNodeArb = testIdArb.map(generatedLeafNodeWithReachableNodes);
+/**
+ * Generates a closed branch.
+ */
+export const generatedClosedBranchNodeArb = testIdArb.map(generatedClosedBranchWithReachableNodes);
+/**
+ * Generates a leaf or a closed branch.
+ *
+ * These node types terminate a generated path because they have no reachable
+ * descendants.
+ */
+const generatedTerminalNodeArb = fc.oneof(generatedLeafNodeArb, generatedClosedBranchNodeArb);
+/**
+ * Generates a leaf, an open branch, or a closed branch.
+ *
+ * Open branches have unique child IDs. Root IDs are made unique separately
+ * when generating a forest.
+ *
+ * The weighted choice gives recursive open branches a geometric dropoff.
+ */
+export const generatedNodeArb = fc.letrec((tie) => {
+    const generatedChildNodeArb = tie('node');
+    /**
+     * Generates the loaded children of an open branch.
+     *
+     * Sibling IDs must be unique so that child lookup is unambiguous. The
+     * maximum length also limits the branching factor of recursive examples.
+     */
+    const generatedOpenChildrenArb = fc.uniqueArray(generatedChildNodeArb, {
         minLength: 0,
+        maxLength: 4,
         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;
+        selector: ({ node }) => node.id,
+    });
+    /**
+     * Generates an open branch and its reachable descendants.
+     */
+    const generatedOpenBranchNodeArb = fc
+        .tuple(testIdArb, generatedOpenChildrenArb)
+        .map(([id, children]) => generatedOpenBranchWithReachableNodes(id, children));
+    return {
+        node: fc
+            .integer({
+            min: 0,
+            max: 9999,
+        })
+            .chain((choice) => 
+        // 5046 works for getAtPath tests, but too heavy for modifyAtPath tests
+        choice >= 5050
+            ? generatedOpenBranchNodeArb
+            : generatedTerminalNodeArb),
+    };
+}).node;
+/**
+ * Generates an array of generated nodes with unique IDs suitable for use as
+ * the root of a forest.
+ *
+ * Root IDs must be unique because paths begin by looking up an ID in this
+ * array.
+ */
 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),
+/**
+ * An array of root-level nodes and all paths that can be resolved through
+ * those nodes.
+ *
+ * Paths through closed branches stop at the closed branch because its
+ * descendants are not loaded.
+ */
+export const nodesArrayAndPathsArb = generatedNodesArrayArb.map((generatedNodes) => ({
+    entries: generatedNodes.map(({ node }) => node),
+    pathEntries: generatedNodes.flatMap(({ reachableNodes }) => reachableNodes),
 }));
-export const forestAndPathAndExpectedArb = forestAndPathsArb
+/**
+ * Generates root-level nodes and a path to one of their reachable nodes.
+ *
+ * Every generated path is valid for `getAtPath`; unreachable paths are not
+ * included.
+ */
+export const nodesArrayAndPathAndExpectedArb = nodesArrayAndPathsArb
     .filter(({ pathEntries }) => pathEntries.length > 0)
     .chain(({ entries, pathEntries }) => fc.constantFrom(...pathEntries).map(({ path, node }) => ({
     entries,
     path,
     expected: node,
 })));
-export const nodesArrayAndBranchPathArb = forestAndPathsArb
+/**
+ * Generates root-level nodes and a path to one of their branch nodes.
+ *
+ * Both open and closed branches are included. A path to a closed branch is
+ * valid, but a path through a closed branch cannot reach any descendants.
+ */
+export const nodesArrayAndBranchPathArb = nodesArrayAndPathsArb
     .map(({ entries, pathEntries }) => ({
     entries,
     branchPathEntries: pathEntries.filter(({ node }) => 'children' in node),
@@ -76,5 +177,17 @@ export const nodesArrayAndBranchPathArb = forestAndPathsArb
     path,
     expected: node,
 })));
+/**
+ * Generates a new array of loaded child nodes.
+ *
+ * The generated nodes have unique IDs, making the result suitable for use as
+ * the children of an open branch.
+ */
 export const newBranchesArb = generatedNodesArrayArb.map((generatedNodes) => generatedNodes.map(({ node }) => node));
+/**
+ * Generates either a new array of loaded child nodes or `null`.
+ *
+ * An array represents an open branch, including an open branch with no
+ * children. `null` represents a closed branch.
+ */
 export const newBranchesOrNullArb = fc.oneof(newBranchesArb, fc.constant(null));

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

@@ -0,0 +1,32 @@
+import { z } from 'zod';
+import { SerializableKey, TreeNode } from './tree-node.types.js';
+/**
+ * Runtime schema for IDs that can be safely represented as serializable
+ * primitive values.
+ *
+ * Strings are accepted as-is. Numbers must be finite, so `NaN`, `Infinity`,
+ * and `-Infinity` are rejected.
+ *
+ * Applications should derive a more specific schema when those constraints
+ * are needed.
+ */
+export declare const serializableKeySchema: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+/**
+ * Helper for creating the schemas for the structural variants of a tree node.
+ *
+ * The concrete application can extend these schemas with additional fields.
+ */
+export declare function createTreeNodeSchemas<Id extends SerializableKey, ChildNode extends TreeNode<Id, ChildNode>>(idSchema: z.ZodType<Id>, childSchema: z.ZodType<ChildNode>): {
+    leafSchema: z.ZodObject<{
+        id: z.ZodType<Id, unknown, z.core.$ZodTypeInternals<Id, unknown>>;
+    }, z.core.$strip>;
+    closedBranchSchema: z.ZodObject<{
+        id: z.ZodType<Id, unknown, z.core.$ZodTypeInternals<Id, unknown>>;
+        children: z.ZodNull;
+    }, z.core.$strip>;
+    openBranchSchema: z.ZodObject<{
+        id: z.ZodType<Id, unknown, z.core.$ZodTypeInternals<Id, unknown>>;
+        children: z.ZodArray<z.ZodType<ChildNode, unknown, z.core.$ZodTypeInternals<ChildNode, unknown>>>;
+    }, z.core.$strip>;
+};
+//# sourceMappingURL=tree-node.schemas.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tree-node.schemas.d.ts","sourceRoot":"","sources":["../../../src/tree-surfer/tree-node/tree-node.schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAEjE;;;;;;;;;GASG;AACH,eAAO,MAAM,qBAAqB,iDAA6C,CAAC;AAEhF;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,EAAE,SAAS,eAAe,EAC1B,SAAS,SAAS,QAAQ,CAAC,EAAE,EAAE,SAAS,CAAC,EACzC,QAAQ,EAAE,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,EAAE,WAAW,EAAE,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC;;;;;;;;;;;;EAoB3D"}

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

@@ -0,0 +1,35 @@
+import { z } from 'zod';
+/**
+ * Runtime schema for IDs that can be safely represented as serializable
+ * primitive values.
+ *
+ * Strings are accepted as-is. Numbers must be finite, so `NaN`, `Infinity`,
+ * and `-Infinity` are rejected.
+ *
+ * Applications should derive a more specific schema when those constraints
+ * are needed.
+ */
+export const serializableKeySchema = z.union([z.string(), z.number().finite()]);
+/**
+ * Helper for creating the schemas for the structural variants of a tree node.
+ *
+ * The concrete application can extend these schemas with additional fields.
+ */
+export function createTreeNodeSchemas(idSchema, childSchema) {
+    const leafSchema = z.object({
+        id: idSchema,
+    });
+    const closedBranchSchema = z.object({
+        id: idSchema,
+        children: z.null(),
+    });
+    const openBranchSchema = z.object({
+        id: idSchema,
+        children: z.array(childSchema),
+    });
+    return {
+        leafSchema,
+        closedBranchSchema,
+        openBranchSchema,
+    };
+}

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

@@ -1,71 +1,109 @@
-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, nodesArrayAndPathAndExpectedArb, } 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(nodesArrayAndPathAndExpectedArb, ({ entries, path, expected }) => {
+            expect(api.getAtPath(entries, path, (node) => node)).toBe(expected);
+            expect(api.getAtPath(entries, path, (node) => node.id)).toBe(expected.id);
         }));
     });
-    it('getAtPath applies the selector', () => {
+    it('UT: calls the selector once with the resolved node', () => {
+        const expected = { id: 'child' };
+        const entries = [
+            {
+                id: 'root',
+                children: [expected],
+            },
+        ];
+        const selector = vi.fn((node) => node.id);
+        expect(api.getAtPath(entries, ['root', 'child'], selector)).toBe('child');
+        expect(selector).toHaveBeenCalledOnce();
+        expect(selector).toHaveBeenCalledWith(expected);
+    });
+    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('UT: returns undefined when a child is missing from an open branch', () => {
         const entries = [
             {
                 id: 'root',
                 children: [{ id: 'child' }],
             },
         ];
-        expect(stringNodeApi.getAtPath(entries, ['root', 'child'], (node) => node.id)).toBe('child');
+        const selector = vi.fn((node) => node.id);
+        const result = api.getAtPath(entries, ['root', 'missing'], selector);
+        expect(result).toBeUndefined();
+        expect(selector).not.toHaveBeenCalled();
     });
-    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 empty path without calling the selector', () => {
+        const selector = vi.fn((node) => node.id);
+        const result = api.getAtPath([{ id: 'root' }], [], selector);
+        expect(result).toBeUndefined();
+        expect(selector).not.toHaveBeenCalled();
     });
-    it('getAtPath returns undefined through a closed branch', () => {
+    it('UT: returns undefined through a closed branch without calling the selector', () => {
         const entries = [
             {
                 id: 'root',
                 children: null,
             },
         ];
-        expect(stringNodeApi.getAtPath(entries, ['root', 'child'], (node) => node)).toBeUndefined();
+        const selector = vi.fn((node) => node.id);
+        const result = api.getAtPath(entries, ['root', 'child'], 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: returns undefined when the selector returns undefined', () => {
+        const selector = vi.fn((_node) => undefined);
+        const result = api.getAtPath([{ id: 'root' }], ['root'], selector);
+        expect(result).toBeUndefined();
+        expect(selector).toHaveBeenCalledOnce();
+        expect(selector).toHaveBeenCalledWith({ id: 'root' });
     });
-    it('getChildById returns the matching child', () => {
-        const child = { id: 'child' };
-        const root = {
-            id: 'root',
-            children: [child],
-        };
-        expect(stringNodeApi.isOpenBranch(root)).toBe(true);
-        if (!stringNodeApi.isOpenBranch(root)) {
-            return;
-        }
-        expect(stringNodeApi.getChildById(root, 'child')).toBe(child);
-        expect(stringNodeApi.getChildById(root, 'missing')).toBeUndefined();
-    });
-    it('modifyAtPath replaces the generated node', () => {
-        fc.assert(fc.property(forestAndPathAndExpectedArb, ({ entries, path, expected }) => {
+});
+describe('modifyAtPath', () => {
+    it('replaces the generated node', () => {
+        fc.assert(fc.property(nodesArrayAndPathAndExpectedArb, ({ entries, path, expected }) => {
             const replacement = {
                 id: expected.id,
             };
-            const updatedForest = stringNodeApi.modifyAtPath(entries, path, () => replacement);
+            const updatedForest = api.modifyAtPath(entries, path, () => replacement);
             expect(updatedForest).not.toBeUndefined();
             if (updatedForest === undefined) {
                 return;
             }
-            expect(stringNodeApi.getAtPath(updatedForest, path, (node) => node)).toBe(replacement);
-            expect(stringNodeApi.getAtPath(entries, path, (node) => node)).toBe(expected);
+            expect(api.getAtPath(updatedForest, path, (node) => node)).toBe(replacement);
+            expect(api.getAtPath(entries, path, (node) => node)).toBe(expected);
         }));
-    });
-    it('modifyAtPath replaces children at a branch path', () => {
+    }, 10000);
+    it('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) => ({
+            expect(api.isBranch(expected)).toBe(true);
+            const updatedForest = api.modifyAtPath(entries, path, (node) => ({
                 ...node,
                 children: newBranches,
             }));
@@ -73,45 +111,80 @@ describe('tree node API', () => {
             if (updatedForest === undefined) {
                 return;
             }
-            const updatedNode = stringNodeApi.getAtPath(updatedForest, path, (node) => node);
+            const updatedNode = api.getAtPath(updatedForest, path, (node) => node);
             expect(updatedNode).not.toBeUndefined();
             expect(updatedNode).not.toBe(expected);
             if (updatedNode === undefined ||
-                !stringNodeApi.isBranch(updatedNode) ||
-                (!stringNodeApi.isOpenBranch(updatedNode) && newBranches !== null)) {
+                !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(entries, path, (node) => node)).toBe(expected);
         }));
     });
-    it('modifyAtPath returns undefined when the modifier aborts', () => {
-        const entries = [{ id: 'root' }];
-        expect(stringNodeApi.modifyAtPath(entries, ['root'], () => undefined)).toBeUndefined();
-    });
-    it('modifyAtPath returns undefined for an empty path', () => {
-        const entries = [{ id: 'root' }];
-        expect(stringNodeApi.modifyAtPath(entries, [], (node) => node)).toBeUndefined();
-    });
-    it('modifyAtPath returns undefined for an invalid path', () => {
+    it('UT: calls the modifier once with the resolved node', () => {
+        const child = { id: 'child' };
         const entries = [
             {
                 id: 'root',
-                children: [],
+                children: [child],
             },
         ];
-        expect(stringNodeApi.modifyAtPath(entries, ['missing'], (node) => node)).toBeUndefined();
-        expect(stringNodeApi.modifyAtPath(entries, ['root', 'missing'], (node) => node)).toBeUndefined();
+        const replacement = { id: 'replacement' };
+        const modifier = vi.fn(() => replacement);
+        const updatedEntries = api.modifyAtPath(entries, ['root', 'child'], modifier);
+        expect(updatedEntries).toBeDefined();
+        expect(modifier).toHaveBeenCalledOnce();
+        expect(modifier).toHaveBeenCalledWith(child);
+        expect(api.getAtPath(updatedEntries, ['root', 'replacement'], (node) => node)).toBe(replacement);
+        expect(api.getAtPath(updatedEntries, ['root', 'child'], (node) => node)).toBeUndefined();
     });
-    it('modifyAtPath cannot traverse a closed branch', () => {
-        const entries = [
-            {
-                id: 'root',
-                children: null,
-            },
-        ];
-        expect(stringNodeApi.modifyAtPath(entries, ['root', 'child'], (node) => node)).toBeUndefined();
+    it.each([
+        {
+            name: 'an empty path',
+            entries: [{ id: 'root' }],
+            path: [],
+        },
+        {
+            name: 'a missing root',
+            entries: [{ id: 'root' }],
+            path: ['missing'],
+        },
+        {
+            name: 'a missing child',
+            entries: [
+                {
+                    id: 'root',
+                    children: [{ id: 'child' }],
+                },
+            ],
+            path: ['root', 'missing'],
+        },
+        {
+            name: 'a path through a leaf',
+            entries: [{ id: 'root' }],
+            path: ['root', 'child'],
+        },
+        {
+            name: 'a path through a closed branch',
+            entries: [{ id: 'root', children: null }],
+            path: ['root', 'child'],
+        },
+    ])('UT: returns undefined and does not call the modifier', ({ entries, path }) => {
+        const modifier = vi.fn((node) => node);
+        const result = api.modifyAtPath(entries, 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, ['root'], modifier);
+        expect(result).toBeUndefined();
+        expect(modifier).toHaveBeenCalledOnce();
+        expect(modifier).toHaveBeenCalledWith(root[0]);
     });
 });