dirvi-lib 0.8.1 → 0.9.0

package/dist/trees/state/state.impl.js

@@ -0,0 +1,128 @@
+/**
+ * Creates operations for navigating and resynchronizing tree-surfer state.
+ */
+export function createStateApi(treeNodeApi, cursorApi) {
+    /**
+     * Reloads one node's direct children and recursively reloads descendant
+     * branches that were open in the old state.
+     *
+     * The node itself retains its existing application value. The supplied
+     * loader refreshes only its direct child collection.
+     *
+     * A branch that was previously closed remains closed: its children were not
+     * loaded in the old state, so there is no descendant loading state to
+     * preserve or refresh.
+     */
+    async function reload(oldRoot, parentPath, loadBranches) {
+        const oldChildren = treeNodeApi.getLoadedChildren(oldRoot);
+        /*
+         * The old node was either a leaf or a closed branch. In either case, it
+         * had no loaded child collection to resynchronize.
+         */
+        if (oldChildren === undefined) {
+            return { root: oldRoot };
+        }
+        const loadedChildren = await loadBranches(parentPath);
+        /*
+         * `withChildren` retains oldRoot's ID and application value, replacing
+         * only its structural child collection.
+         *
+         * Failure means the loader supplied duplicate sibling IDs, violating the
+         * TreeNodeApi contract. This is a loader/data-integrity error rather than
+         * an ordinary missing-path condition.
+         */
+        let newRoot = treeNodeApi.withLoadedChildren(oldRoot, loadedChildren);
+        if (newRoot === undefined) {
+            throw new Error('Cannot resync tree: loaded branch contains duplicate sibling IDs');
+        }
+        /*
+         * Recurse only into entries that were open in the old state and which
+         * still exist in the freshly loaded child collection.
+         *
+         * This preserves fresh values from loaded children while restoring their
+         * previously loaded descendant collections.
+         */
+        for (const oldEntry of oldChildren) {
+            const oldEntryChildren = treeNodeApi.getLoadedChildren(oldEntry);
+            /*
+             * A leaf or closed branch did not have loaded descendants in old state.
+             */
+            if (oldEntryChildren === undefined) {
+                continue;
+            }
+            const oldEntryId = treeNodeApi.id(oldEntry);
+            const currentChildren = treeNodeApi.getLoadedChildren(newRoot);
+            if (currentChildren === undefined) {
+                throw new Error('Cannot resync tree: replacement root unexpectedly has no children');
+            }
+            const currentChildrenArray = [...currentChildren];
+            const currentChildIndex = currentChildrenArray.findIndex((child) => treeNodeApi.id(child) === oldEntryId);
+            if (currentChildIndex === -1) {
+                continue;
+            }
+            const currentChild = currentChildrenArray[currentChildIndex];
+            if (currentChild === undefined) {
+                continue;
+            }
+            if (treeNodeApi.kind(currentChild) === 'leaf') {
+                continue;
+            }
+            const reloadedChild = await reload(oldEntry, [...parentPath, oldEntryId], loadBranches);
+            const reloadedGrandchildren = treeNodeApi.getLoadedChildren(reloadedChild.root);
+            if (reloadedGrandchildren === undefined) {
+                throw new Error('Cannot resync tree: reloaded open branch has no children');
+            }
+            const updatedCurrentChild = treeNodeApi.withLoadedChildren(currentChild, reloadedGrandchildren);
+            if (updatedCurrentChild === undefined) {
+                throw new Error('Cannot resync tree: reloaded descendants contain duplicate sibling IDs');
+            }
+            const updatedChildren = [...currentChildrenArray];
+            updatedChildren[currentChildIndex] = updatedCurrentChild;
+            const updatedRoot = treeNodeApi.withLoadedChildren(newRoot, updatedChildren);
+            if (updatedRoot === undefined) {
+                throw new Error('Cannot resync tree: updated branch contains duplicate sibling IDs');
+            }
+            newRoot = updatedRoot;
+        }
+        return {
+            root: newRoot,
+        };
+    }
+    /**
+     * Determines the cursor after resynchronization.
+     *
+     * Current policy: return the root cursor.
+     *
+     * Future policy:
+     *
+     * 1. Keep the exact cursor if it survives.
+     * 2. Otherwise choose the deepest surviving ancestor.
+     * 3. Otherwise choose the nearest preceding surviving cursor.
+     * 4. Otherwise choose the first valid cursor.
+     * 5. If no entry cursor exists, use the root cursor.
+     */
+    function resyncCursor(_oldState, _newRoot, _newFolds) {
+        return [];
+    }
+    return {
+        getNodeAtCursor(state) {
+            const path = cursorApi.getPath(state.cursor);
+            return treeNodeApi.selectAtPath(state.root, path, (node) => node);
+        },
+        async resync(oldState, loadBranches) {
+            const reloaded = await reload(oldState.root, [], loadBranches);
+            /*
+             * Fold-state resynchronization is not implemented yet. Keep the existing
+             * fold definitions while the source tree is reloaded.
+             */
+            const folds = oldState.folds;
+            const root = reloaded.root;
+            return {
+                ...oldState,
+                root,
+                folds,
+                cursor: resyncCursor(oldState, root, folds),
+            };
+        },
+    };
+}

package/dist/trees/state/state.schemas.d.ts

@@ -0,0 +1,25 @@
+import { z } from 'zod';
+import type { Cursor } from '../cursor.js';
+import type { FoldsModel } from '../fold-node/index.js';
+import type { SerializableKey, TreeNodeModel } from '../tree-node/index.js';
+/**
+ * Serializable persistence/interchange model for tree-surfer state.
+ *
+ * This is intentionally distinct from runtime `State`: its root and folds use
+ * public structural models, while runtime state holds opaque TreeNode and
+ * Folds values.
+ */
+export type StateModel<Id extends SerializableKey, Value> = Readonly<{
+    root: TreeNodeModel<Id, Value>;
+    folds: FoldsModel<Id>;
+    cursor: Cursor<Id>;
+}>;
+/**
+ * Creates a schema for the serializable StateModel DTO.
+ *
+ * This validates only the persistence representation. Applications must decode
+ * the validated root and folds models through their specialized TreeNodeApi and
+ * FoldsApi before constructing opaque runtime State.
+ */
+export declare function createStateModelSchema<Id extends SerializableKey, Value>(rootSchema: z.ZodType<TreeNodeModel<Id, Value>>, foldsSchema: z.ZodType<FoldsModel<Id>>, cursorSchema: z.ZodType<Cursor<Id>>): z.ZodType<StateModel<Id, Value>>;
+//# sourceMappingURL=state.schemas.d.ts.map

package/dist/trees/state/state.schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.schemas.d.ts","sourceRoot":"","sources":["../../../src/trees/state/state.schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAE5E;;;;;;GAMG;AACH,MAAM,MAAM,UAAU,CACpB,EAAE,SAAS,eAAe,EAC1B,KAAK,IACH,QAAQ,CAAC;IACX,IAAI,EAAE,aAAa,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC;IAC/B,KAAK,EAAE,UAAU,CAAC,EAAE,CAAC,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC;CACpB,CAAC,CAAC;AAEH;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,EAAE,SAAS,eAAe,EAC1B,KAAK,EAEL,UAAU,EAAE,CAAC,CAAC,OAAO,CAAC,aAAa,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC,EAC/C,WAAW,EAAE,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC,EACtC,YAAY,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,GAClC,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC,CAQlC"}

package/dist/trees/state/state.schemas.js

@@ -0,0 +1,17 @@
+import { z } from 'zod';
+/**
+ * Creates a schema for the serializable StateModel DTO.
+ *
+ * This validates only the persistence representation. Applications must decode
+ * the validated root and folds models through their specialized TreeNodeApi and
+ * FoldsApi before constructing opaque runtime State.
+ */
+export function createStateModelSchema(rootSchema, foldsSchema, cursorSchema) {
+    return z
+        .object({
+        root: rootSchema,
+        folds: foldsSchema,
+        cursor: cursorSchema,
+    })
+        .strict();
+}

package/dist/trees/state/state.types.d.ts

@@ -0,0 +1,36 @@
+import type { Cursor } from '../cursor.js';
+import type { Folds } from '../fold-node/index.js';
+import type { SerializableKey, TreeNode } from '../tree-node/index.js';
+/**
+ * State for navigating a tree and its associated fold-state tree.
+ *
+ * Invariant: `root` is an open branch.
+ *
+ * Note: This cannot be represented through a structural intersection because
+ * TreeNode is opaque; enforce it when constructing State, using
+ * TreeNodeApi.state or TreeNodeApi.getChildren.
+ *
+ * @typeParam Id - Tree-node sibling ID type.
+ * @typeParam Value - Application-owned value stored in every tree node.
+ */
+export type State<Id extends SerializableKey, Value> = Readonly<{
+    root: TreeNode<Id, Value>;
+    folds: Folds<Id>;
+    cursor: Cursor<Id>;
+}>;
+export type StateApi<Id extends SerializableKey, Value> = Readonly<{
+    getNodeAtCursor(state: State<Id, Value>): TreeNode<Id, Value> | undefined;
+    /**
+     * Reloads the root's children and all descendant branches that were loaded
+     * in the previous state.
+     *
+     * `loadBranches([])` loads the root's direct children.
+     * `loadBranches(['src'])` loads the children of `src`, where `src` is the
+     * ID of a root child.
+     *
+     * Returned nodes must be valid TreeNode values created or decoded through
+     * the specialized TreeNodeApi for `Id` and `Value`.
+     */
+    resync(oldState: State<Id, Value>, loadBranches: (path: readonly Id[]) => Promise<readonly TreeNode<Id, Value>[]>): Promise<State<Id, Value>>;
+}>;
+//# sourceMappingURL=state.types.d.ts.map

package/dist/trees/state/state.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.types.d.ts","sourceRoot":"","sources":["../../../src/trees/state/state.types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,uBAAuB,CAAC;AACnD,OAAO,KAAK,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAEvE;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,KAAK,CAAC,EAAE,SAAS,eAAe,EAAE,KAAK,IAAI,QAAQ,CAAC;IAC9D,IAAI,EAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC;IAC1B,KAAK,EAAE,KAAK,CAAC,EAAE,CAAC,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC;CACpB,CAAC,CAAC;AAEH,MAAM,MAAM,QAAQ,CAAC,EAAE,SAAS,eAAe,EAAE,KAAK,IAAI,QAAQ,CAAC;IACjE,eAAe,CAAC,KAAK,EAAE,KAAK,CAAC,EAAE,EAAE,KAAK,CAAC,GAAG,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC,GAAG,SAAS,CAAC;IAE1E;;;;;;;;;;OAUG;IACH,MAAM,CACJ,QAAQ,EAAE,KAAK,CAAC,EAAE,EAAE,KAAK,CAAC,EAC1B,YAAY,EAAE,CACZ,IAAI,EAAE,SAAS,EAAE,EAAE,KAChB,OAAO,CAAC,SAAS,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC,EAAE,CAAC,GAC3C,OAAO,CAAC,KAAK,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC,CAAC;CAC9B,CAAC,CAAC"}

package/dist/trees/state/state.types.js

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

package/dist/trees/tree-node/deprecated/tree-node.arb.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree-node.arb.d.ts","sourceRoot":"","sources":["../../../../src/trees/tree-node/deprecated/tree-node.arb.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,YAAY,CAAC;AAEjC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAErD;;;;GAIG;AACH,KAAK,UAAU,GAAG,MAAM,CAAC;AAOzB;;;GAGG;AACH,eAAO,MAAM,SAAS,sBAIpB,CAAC;AAEH;;GAEG;AAEH,MAAM,MAAM,UAAU,GAAG,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC,CAAC;AAC1D,KAAK,IAAI,GAAG,UAAU,EAAE,CAAC;AAEzB,KAAK,UAAU,GAAG;IAChB,IAAI,EAAE,IAAI,CAAC;IACX,IAAI,EAAE,UAAU,CAAC;CAClB,CAAC;AAEF,KAAK,sBAAsB,GAAG;IAC5B,IAAI,EAAE,UAAU,CAAC;IACjB,cAAc,EAAE,UAAU,EAAE,CAAC;CAC9B,CAAC;AAuEF;;GAEG;AACH,eAAO,MAAM,oBAAoB,sCAEhC,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,4BAA4B,sCAExC,CAAC;AAaF;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB,EAAE,EAAE,CAAC,SAAS,CAAC,sBAAsB,CA0C5D,CAAC;AAEP;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,wCAIjC,CAAC;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,eAAe;;;EAK3B,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB;;;;EAQnC,CAAC;AAEJ;;;;;GAKG;AACH,eAAO,MAAM,0BAA0B;;;;EAYpC,CAAC;AAEJ;;;;;GAKG;AACH,eAAO,MAAM,cAAc,qBAE1B,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,4BAA8C,CAAC"}

package/dist/trees/tree-node/deprecated/tree-node.arb.debug.test.d.ts.map

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

package/dist/{tree-surfer/tree-node → trees/tree-node/deprecated}/tree-node.arb.debug.test.js

@@ -1,6 +1,6 @@
 import { describe, it } from 'vitest';
 import * as fc from 'fast-check';
-import { generatedNodeArb, generatedNodesArrayArb, } from './tree-node.arb.js';
+import { generatedNodeArb, generatedNodesArrayArb } from './tree-node.arb.js';
 /**
  * Used for looking at the tree distributions generated by the arbs.
  */

package/dist/trees/tree-node/deprecated/tree-node.impl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree-node.impl.d.ts","sourceRoot":"","sources":["../../../../src/trees/tree-node/deprecated/tree-node.impl.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAKV,eAAe,EACf,QAAQ,EACR,WAAW,EACZ,MAAM,sBAAsB,CAAC;AAE9B;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAC/B,EAAE,SAAS,eAAe,EAC1B,IAAI,SAAS,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC,KAC5B,WAAW,CAAC,EAAE,EAAE,IAAI,CAAC,CAqGzB"}

package/dist/trees/tree-node/deprecated/tree-node.schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree-node.schemas.d.ts","sourceRoot":"","sources":["../../../../src/trees/tree-node/deprecated/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,IAAI,SAAS,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC,EAC/B,QAAQ,EAAE,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,EAAE,UAAU,EAAE,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC;;;;;;;;;;;;EAoBrD"}

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"tree-node.types.d.ts","sourceRoot":"","sources":["../../../../src/trees/tree-node/deprecated/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;AAE5D,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/trees/tree-node/deprecated/tree-node.types.js

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

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

@@ -0,0 +1,5 @@
+export type * from './tree-node.model.js';
+export { serializableKeySchema, createTreeNodeModelSchema } from './tree-node.model.js';
+export type * from './tree-node.types.js';
+export { createTreeNodeApi } from './tree-node.impl.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/trees/tree-node/index.ts"],"names":[],"mappings":"AAAA,mBAAmB,sBAAsB,CAAC;AAC1C,OAAO,EAAE,qBAAqB,EAAE,yBAAyB,EAAE,MAAM,sBAAsB,CAAC;AACxF,mBAAmB,sBAAsB,CAAC;AAC1C,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC"}

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

@@ -0,0 +1,2 @@
+export { serializableKeySchema, createTreeNodeModelSchema } from './tree-node.model.js';
+export { createTreeNodeApi } from './tree-node.impl.js';

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

@@ -0,0 +1,104 @@
+import * as fc from 'fast-check';
+import { TreeNodeModel } from './tree-node.model.js';
+/**
+ * The ID and Values types used for the generated test trees.
+ *
+ * Short strings keep generated counterexamples readable. Values just have to
+ * be something easily checked for equality.
+ */
+type TestNodeId = string;
+type TestValue = number;
+type TestNodeModel = TreeNodeModel<TestNodeId, TestValue>;
+type ModelAndPath = {
+    path: TestNodeId[];
+    model: TestNodeModel;
+};
+type ModelWithReachableModels = {
+    model: TestNodeModel;
+    /**
+     * Includes this model at `[]` and every descendant reachable through loaded
+     * branches. Descendants behind unloaded branches are intentionally absent.
+     */
+    reachableModels: ModelAndPath[];
+};
+/**
+ * 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 declare const testIdArb: fc.Arbitrary<string>;
+/**
+ * Generates serializable application values for test nodes.
+ */
+export declare const testValueArb: fc.Arbitrary<number>;
+/**
+ * Generates a leaf model.
+ */
+export declare const generatedLeafModelArb: fc.Arbitrary<ModelWithReachableModels>;
+/**
+ * Generates an unloaded-branch model.
+ */
+export declare const generatedUnloadedBranchModelArb: fc.Arbitrary<ModelWithReachableModels>;
+/**
+ * Generates a leaf, an unloaded branch, or a loaded branch.
+ *
+ * Loaded 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 declare const generatedNodeArb: fc.Arbitrary<ModelWithReachableModels>;
+/**
+ * Generates an array of generated nodes with unique sibling IDs.
+ *
+ * The result is suitable for use as the loaded children of an open branch.
+ */
+export declare const generatedNodesArrayArb: fc.Arbitrary<ModelWithReachableModels[]>;
+/**
+ * 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 declare const nodeAndPathsArb: fc.Arbitrary<{
+    root: TestNodeModel;
+    pathEntries: ModelAndPath[];
+}>;
+/**
+ * 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 declare const nodeAndPathAndExpectedArb: fc.Arbitrary<{
+    root: TestNodeModel;
+    path: string[];
+    expected: TestNodeModel;
+}>;
+/**
+ * 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 declare const nodesArrayAndBranchPathArb: fc.Arbitrary<{
+    root: TestNodeModel;
+    path: string[];
+    expected: TestNodeModel;
+}>;
+/**
+ * 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 declare const newBranchesArb: fc.Arbitrary<TestNodeModel[]>;
+/**
+ * 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 declare const newBranchesOrNullArb: fc.Arbitrary<TestNodeModel[] | null>;
+export {};
+//# sourceMappingURL=tree-node.arb.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tree-node.arb.d.ts","sourceRoot":"","sources":["../../../src/trees/tree-node/tree-node.arb.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,YAAY,CAAC;AAGjC,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAErD;;;;;GAKG;AACH,KAAK,UAAU,GAAG,MAAM,CAAC;AACzB,KAAK,SAAS,GAAG,MAAM,CAAC;AAGxB,KAAK,aAAa,GAAG,aAAa,CAAC,UAAU,EAAE,SAAS,CAAC,CAAC;AAE1D,KAAK,YAAY,GAAG;IAClB,IAAI,EAAE,UAAU,EAAE,CAAC;IACnB,KAAK,EAAE,aAAa,CAAC;CACtB,CAAC;AAEF,KAAK,wBAAwB,GAAG;IAC9B,KAAK,EAAE,aAAa,CAAC;IACrB;;;OAGG;IACH,eAAe,EAAE,YAAY,EAAE,CAAC;CACjC,CAAC;AAOF;;;GAGG;AACH,eAAO,MAAM,SAAS,sBAIpB,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,YAAY,sBAGvB,CAAC;AAoEH;;GAEG;AACH,eAAO,MAAM,qBAAqB,EAAE,EAAE,CAAC,SAAS,CAAC,wBAAwB,CAGjB,CAAC;AAEzD;;GAEG;AACH,eAAO,MAAM,+BAA+B,EAAE,EAAE,CAAC,SAAS,CAAC,wBAAwB,CAGjB,CAAC;AAanE;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB,EAAE,EAAE,CAAC,SAAS,CAAC,wBAAwB,CAwC9D,CAAC;AAEP;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,0CAIjC,CAAC;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,eAAe;;;EAK3B,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB;;;;EAQnC,CAAC;AAEJ;;;;;GAKG;AACH,eAAO,MAAM,0BAA0B;;;;EAYpC,CAAC;AAEJ;;;;;GAKG;AACH,eAAO,MAAM,cAAc,+BAE1B,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,sCAA8C,CAAC"}

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

@@ -0,0 +1,191 @@
+import * as fc from 'fast-check';
+/**
+ * Characters used for 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,
+});
+/**
+ * Generates serializable application values for test nodes.
+ */
+export const testValueArb = fc.integer({
+    min: -10_000,
+    max: 10_000,
+});
+const generatedLeafModel = (id, value) => {
+    const model = {
+        id,
+        value,
+    };
+    return {
+        model,
+        reachableModels: [{ path: [], model }],
+    };
+};
+function generatedUnloadedBranchModel(id, value) {
+    const model = {
+        id,
+        value,
+        children: null,
+    };
+    return {
+        model,
+        reachableModels: [{ path: [], model }],
+    };
+}
+/**
+ * Creates the metadata for a loaded branch and all descendants reachable
+ * through its loaded child collection.
+ *
+ * Child-array order is not semantically meaningful to the tree API. The
+ * generator happens to use an array because `TreeNodeModel` is serializable.
+ */
+function generatedLoadedBranchModel(id, value, children) {
+    const model = {
+        id,
+        value,
+        children: children.map(({ model: child }) => child),
+    };
+    const reachableDescendants = children.flatMap(({ model: childModel, reachableModels }) => reachableModels.map(({ path, model: reachableModel }) => ({
+        path: [childModel.id, ...path],
+        model: reachableModel,
+    })));
+    return {
+        model,
+        reachableModels: [
+            { path: [], model },
+            ...reachableDescendants,
+        ],
+    };
+}
+/**
+ * Generates a leaf model.
+ */
+export const generatedLeafModelArb = fc
+    .tuple(testIdArb, testValueArb)
+    .map(([id, value]) => generatedLeafModel(id, value));
+/**
+ * Generates an unloaded-branch model.
+ */
+export const generatedUnloadedBranchModelArb = fc
+    .tuple(testIdArb, testValueArb)
+    .map(([id, value]) => generatedUnloadedBranchModel(id, value));
+/**
+ * Generates either kind of terminal model.
+ *
+ * Both leaves and unloaded branches terminate path traversal.
+ */
+const generatedTerminalModelArb = fc.oneof(generatedLeafModelArb, generatedUnloadedBranchModelArb);
+/**
+ * Generates a leaf, an unloaded branch, or a loaded branch.
+ *
+ * Loaded 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 generatedChildModelArb = 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(generatedChildModelArb, {
+        minLength: 0,
+        maxLength: 4,
+        size: 'medium',
+        selector: ({ model }) => model.id,
+    });
+    /**
+     * Generates an open branch and its reachable descendants.
+     */
+    const generatedLoadedBranchModelArb = fc
+        .tuple(testIdArb, testValueArb, generatedOpenChildrenArb)
+        .map(([id, value, children]) => generatedLoadedBranchModel(id, value, children));
+    return {
+        node: fc
+            .integer({
+            min: 0,
+            max: 9999,
+        })
+            .chain((choice) => 
+        // 5046 works for getAtPath tests, but too heavy for modifyAtPath tests
+        choice >= 5050
+            ? generatedLoadedBranchModelArb
+            : generatedTerminalModelArb),
+    };
+}).node;
+/**
+ * Generates an array of generated nodes with unique sibling IDs.
+ *
+ * The result is suitable for use as the loaded children of an open branch.
+ */
+export const generatedNodesArrayArb = fc.uniqueArray(generatedNodeArb, {
+    minLength: 0,
+    size: 'small',
+    selector: (generated) => generated.model.id,
+});
+/**
+ * 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 nodeAndPathsArb = generatedNodeArb.map(({ model: root, reachableModels }) => ({
+    root,
+    pathEntries: reachableModels,
+}));
+/**
+ * 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 nodeAndPathAndExpectedArb = nodeAndPathsArb
+    .filter(({ pathEntries }) => pathEntries.length > 0)
+    .chain(({ root, pathEntries }) => fc.constantFrom(...pathEntries).map(({ path, model }) => ({
+    root,
+    path,
+    expected: model,
+})));
+/**
+ * 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 = nodeAndPathsArb
+    .map(({ root, pathEntries }) => ({
+    root,
+    branchPathEntries: pathEntries.filter(({ model }) => 'children' in model),
+}))
+    .filter(({ branchPathEntries }) => branchPathEntries.length > 0)
+    .chain(({ root, branchPathEntries }) => fc.constantFrom(...branchPathEntries).map(({ path, model }) => ({
+    root,
+    path,
+    expected: model,
+})));
+/**
+ * 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(({ model }) => model));
+/**
+ * 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/trees/tree-node/tree-node.impl.d.ts

@@ -0,0 +1,15 @@
+import type { TreeNodeApi } from './tree-node.types.js';
+import type { SerializableKey } from './tree-node.model.js';
+/**
+ * Creates an API for constructing, inspecting, and immutably updating opaque
+ * tree nodes.
+ *
+ * The returned nodes are ordinary JavaScript objects at runtime. Their
+ * structural representation is private to this module; consumers interact
+ * with them only through the returned API.
+ *
+ * Tree updates preserve object identity for unrelated nodes. New ancestor
+ * nodes and child collections are created only along an updated path.
+ */
+export declare function createTreeNodeApi<Id extends SerializableKey, Value>(): TreeNodeApi<Id, Value>;
+//# sourceMappingURL=tree-node.impl.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tree-node.impl.d.ts","sourceRoot":"","sources":["../../../src/trees/tree-node/tree-node.impl.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEV,WAAW,EAGZ,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,eAAe,EAAiB,MAAM,sBAAsB,CAAC;AAqJ3E;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAC/B,EAAE,SAAS,eAAe,EAC1B,KAAK,KACF,WAAW,CAAC,EAAE,EAAE,KAAK,CAAC,CAiR1B"}