dirvi-lib 0.11.0-beta.1 → 0.11.0-beta.13

package/dist/state-and-nav/tree/deprecated/tree-node.schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree-node.schemas.d.ts","sourceRoot":"","sources":["../../../../src/state-and-nav/tree/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/state-and-nav/tree/deprecated/tree-node.test.d.ts.map

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

package/dist/state-and-nav/tree/deprecated/tree-node.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree-node.types.d.ts","sourceRoot":"","sources":["../../../../src/state-and-nav/tree/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/state-and-nav/tree/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * To be used as the dependencies of State and Navigation.
+ */
+export type { SerializableKey } from './tree-node.model.js';
+export type * from './tree.types.js';
+export { createTreeMethods } from './tree.impl.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/state-and-nav/tree/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/state-and-nav/tree/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,YAAY,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAC5D,mBAAmB,iBAAiB,CAAC;AACrC,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/state-and-nav/tree/index.js

@@ -0,0 +1 @@
+export { createTreeMethods } from './tree.impl.js';

package/dist/state-and-nav/tree/tree-node.arb.d.ts

@@ -0,0 +1,94 @@
+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 Id = string;
+type Value = number;
+type ModelAndPath = {
+    model: TreeNodeModel<Id, Value>;
+    path: Id[];
+};
+/**
+ * A model and a pair of a model and its path for every reachable path in the
+ * model
+ *
+ * Includes this model at `[]` and every descendant reachable through loaded
+ * branches. Descendants behind unloaded branches are intentionally absent.
+ */
+type ModelWithReachableModels = {
+    model: TreeNodeModel<Id, Value>;
+    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 idArb: fc.Arbitrary<string>;
+/**
+ * Generates serializable application values for test nodes.
+ */
+export declare const valueArb: fc.Arbitrary<number>;
+/**
+ * Generates a leaf model.
+ */
+export declare const leafModelWRMArb: fc.Arbitrary<ModelWithReachableModels>;
+/**
+ * Generates an unloaded-branch model.
+ */
+export declare const unloadedBranchModelWRMArb: 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 loaded branches a geometric drop off.
+ */
+export declare const modelWithReachableModelsArb: fc.Arbitrary<ModelWithReachableModels>;
+/**
+ * Generates an array of generated models with unique sibling IDs.
+ *
+ * The result is suitable for use as the loaded children of a loaded branch.
+ */
+export declare const siblingModelsWRMArb: fc.Arbitrary<ModelWithReachableModels[]>;
+/**
+ * Generates root-level models and a path to one of their reachable models.
+ *
+ * Every generated path is valid for `getAtPath`; unreachable paths are not
+ * included.
+ */
+export declare const modelAndReachablePathArb: fc.Arbitrary<{
+    root: TreeNodeModel<string, number>;
+    path: string[];
+    expected: TreeNodeModel<string, number>;
+}>;
+/**
+ * Generates a root model and a path to one of its reachable branch models.
+ *
+ * Both loaded and unloaded branches are included.
+ */
+export declare const modelAndBranchPathArb: fc.Arbitrary<{
+    root: TreeNodeModel<string, number>;
+    path: string[];
+    expected: TreeNodeModel<string, number>;
+}>;
+/**
+ * Generates a new array of loaded child models.
+ *
+ * The generated models have unique IDs, making the result suitable for use as
+ * the children of a loaded branch.
+ */
+export declare const childrenModelsArb: fc.Arbitrary<TreeNodeModel<string, number>[]>;
+/**
+ * Generates either a new array of loaded child models or `null`.
+ *
+ * An array represents a loaded branch, including a loaded branch with no
+ * children. `null` represents an unloaded branch.
+ */
+export declare const childrenStateModelArb: fc.Arbitrary<TreeNodeModel<string, number>[] | null>;
+export {};
+//# sourceMappingURL=tree-node.arb.d.ts.map

package/dist/state-and-nav/tree/tree-node.arb.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree-node.arb.d.ts","sourceRoot":"","sources":["../../../src/state-and-nav/tree/tree-node.arb.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,YAAY,CAAC;AAEjC,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAErD;;;;;GAKG;AACH,KAAK,EAAE,GAAG,MAAM,CAAC;AACjB,KAAK,KAAK,GAAG,MAAM,CAAC;AAEpB,KAAK,YAAY,GAAG;IAClB,KAAK,EAAE,aAAa,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC;IAChC,IAAI,EAAE,EAAE,EAAE,CAAC;CACZ,CAAC;AAEF;;;;;;GAMG;AACH,KAAK,wBAAwB,GAAG;IAC9B,KAAK,EAAE,aAAa,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC;IAChC,eAAe,EAAE,YAAY,EAAE,CAAC;CACjC,CAAC;AAWF;;;GAGG;AACH,eAAO,MAAM,KAAK,sBAIhB,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,QAAQ,sBAGnB,CAAC;AAyEH;;GAEG;AACH,eAAO,MAAM,eAAe,EAAE,EAAE,CAAC,SAAS,CAAC,wBAAwB,CAEhB,CAAC;AAEpD;;GAEG;AACH,eAAO,MAAM,yBAAyB,EAAE,EAAE,CAAC,SAAS,CAAC,wBAAwB,CAGd,CAAC;AAUhE;;;;;;;GAOG;AACH,eAAO,MAAM,2BAA2B,EAAE,EAAE,CAAC,SAAS,CAAC,wBAAwB,CAyCtE,CAAC;AASV;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,0CAI9B,CAAC;AAIH;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB;;;;EAOpC,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,qBAAqB;;;;EAc/B,CAAC;AAEJ;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,+CAE7B,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,sDAAiD,CAAC"}

package/dist/state-and-nav/tree/tree-node.arb.debug.test.d.ts

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

package/dist/state-and-nav/tree/tree-node.arb.debug.test.d.ts.map

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

package/dist/state-and-nav/tree/tree-node.arb.debug.test.js

@@ -0,0 +1,54 @@
+import { describe, it } from 'vitest';
+import * as fc from 'fast-check';
+import { modelWithReachableModelsArb, siblingModelsWRMArb } from './tree-node.arb.js';
+/**
+ * Manual inspection of generated models and their reachable paths.
+ *
+ * Remove `.skip` temporarily to run these inspections.
+ * These are debugging aids, not assertions about the arbitraries.
+ */
+describe.skip('inspect tree-node arbitraries', () => {
+    const seed = 12345;
+    it('prints generated models and reachable paths', () => {
+        const samples = fc.sample(modelWithReachableModelsArb, {
+            numRuns: 10,
+            seed,
+        });
+        for (const [index, generated] of samples.entries()) {
+            console.log(`\n--- model ${index + 1} ---`);
+            console.dir(generated.model, {
+                depth: Infinity,
+                colors: false,
+            });
+            console.log(`reachable nodes: ${generated.reachableModels.length}`, `maximum depth: ${Math.max(...generated.reachableModels.map(({ path }) => path.length))}`);
+            console.log('reachable paths:');
+            console.dir(generated.reachableModels.map(({ path, model }) => ({
+                path,
+                id: model.id,
+                kind: !('children' in model)
+                    ? 'leaf'
+                    : model.children === null
+                        ? 'unloaded-branch'
+                        : 'loaded-branch',
+            })), {
+                depth: Infinity,
+                colors: false,
+            });
+        }
+    });
+    it('prints generated sibling collections', () => {
+        const samples = fc.sample(siblingModelsWRMArb, {
+            numRuns: 5,
+            seed,
+        });
+        for (const [index, generatedNodes] of samples.entries()) {
+            console.log(`\n--- sibling collection ${index + 1} ---`);
+            console.dir(generatedNodes.map(({ model }) => model), {
+                depth: Infinity,
+                colors: false,
+            });
+            console.log('sibling IDs:', generatedNodes.map(({ model }) => model.id));
+            console.log('total reachable nodes:', generatedNodes.reduce((count, generated) => count + generated.reachableModels.length, 0));
+        }
+    });
+});

package/dist/state-and-nav/tree/tree-node.arb.js

@@ -0,0 +1,188 @@
+import * as fc from 'fast-check';
+// =============================================================================
+// ID and Value Arbitraries
+// =============================================================================
+/**
+ * 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 idArb = fc.string({
+    unit: fc.constantFrom(...smallLetterCharacters),
+    minLength: 1,
+    maxLength: 8,
+});
+/**
+ * Generates serializable application values for test nodes.
+ */
+export const valueArb = fc.integer({
+    min: -10_000,
+    max: 10_000,
+});
+// =============================================================================
+// Generating Models with Reachable Models
+// =============================================================================
+// Helpers
+const createLeafModel = (id, value) => {
+    const model = {
+        id,
+        value,
+    };
+    return {
+        model,
+        reachableModels: [{ path: [], model }],
+    };
+};
+function createUnloadedBranchModel(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 preserved, both in the model and in the enumeration
+ * of reachable descendants.
+ */
+function createLoadedBranchModel(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],
+    };
+}
+// Arbs
+/**
+ * Generates a leaf model.
+ */
+export const leafModelWRMArb = fc
+    .tuple(idArb, valueArb)
+    .map(([id, value]) => createLeafModel(id, value));
+/**
+ * Generates an unloaded-branch model.
+ */
+export const unloadedBranchModelWRMArb = fc
+    .tuple(idArb, valueArb)
+    .map(([id, value]) => createUnloadedBranchModel(id, value));
+/**
+ * Generates either kind of 'terminal' model.
+ *
+ * Both leaves and unloaded branches terminate path traversal.
+ */
+const terminalModelWRMArb = fc.oneof(leafModelWRMArb, unloadedBranchModelWRMArb);
+/**
+ * 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 loaded branches a geometric drop off.
+ */
+export const modelWithReachableModelsArb = fc.letrec((tie) => {
+    const generatedChildModelArb = tie('node');
+    /**
+     * Generates the loaded children of a loaded branch.
+     *
+     * Sibling IDs must be unique so that child lookup is unambiguous. The
+     * maximum length also limits the branching factor of recursive examples.
+     */
+    const generatedLoadedChildrenArb = fc.uniqueArray(generatedChildModelArb, {
+        minLength: 0,
+        maxLength: 4,
+        size: 'medium',
+        selector: ({ model }) => model.id,
+    });
+    /**
+     * Generates a loaded branch and its reachable descendants.
+     */
+    const generatedLoadedBranchModelArb = fc
+        .tuple(idArb, valueArb, generatedLoadedChildrenArb)
+        .map(([id, value, children]) => createLoadedBranchModel(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
+            : terminalModelWRMArb),
+    };
+}).node;
+// =============================================================================
+// Generating Models
+// =============================================================================
+// Prepares inputs for particular tests.
+// Generating Replacement Child State
+/**
+ * Generates an array of generated models with unique sibling IDs.
+ *
+ * The result is suitable for use as the loaded children of a loaded branch.
+ */
+export const siblingModelsWRMArb = fc.uniqueArray(modelWithReachableModelsArb, {
+    minLength: 0,
+    size: 'small',
+    selector: (generated) => generated.model.id,
+});
+// Generating Models with a Selected Reachable Target
+/**
+ * Generates root-level models and a path to one of their reachable models.
+ *
+ * Every generated path is valid for `getAtPath`; unreachable paths are not
+ * included.
+ */
+export const modelAndReachablePathArb = modelWithReachableModelsArb.chain(({ model: root, reachableModels }) => fc.constantFrom(...reachableModels).map(({ path, model }) => ({
+    root,
+    path,
+    expected: model,
+})));
+/**
+ * Generates a root model and a path to one of its reachable branch models.
+ *
+ * Both loaded and unloaded branches are included.
+ */
+export const modelAndBranchPathArb = modelWithReachableModelsArb
+    .map(({ model: root, reachableModels }) => ({
+    root,
+    branchPathEntries: reachableModels.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 models.
+ *
+ * The generated models have unique IDs, making the result suitable for use as
+ * the children of a loaded branch.
+ */
+export const childrenModelsArb = siblingModelsWRMArb.map((generatedNodes) => generatedNodes.map(({ model }) => model));
+/**
+ * Generates either a new array of loaded child models or `null`.
+ *
+ * An array represents a loaded branch, including a loaded branch with no
+ * children. `null` represents an unloaded branch.
+ */
+export const childrenStateModelArb = fc.oneof(childrenModelsArb, fc.constant(null));

package/dist/state-and-nav/tree/tree-node.model.d.ts

@@ -0,0 +1,194 @@
+import { z } from 'zod';
+import type { SerializableKey } from 'dirvi-apis';
+/**
+ * A serializable primitive suitable for use as a stable tree-node ID.
+ *
+ * @remarks
+ *
+ * A node ID identifies a node among its direct siblings. It is not required
+ * to be globally unique across the whole tree: two nodes in different
+ * branches may have the same ID.
+ *
+ * Numeric IDs must be finite. TypeScript cannot represent the exclusion of
+ * `NaN`, `Infinity`, and `-Infinity` from `number`, so values received from
+ * an untrusted source should be validated at an application boundary, for
+ * example with `serializableKeySchema`.
+ *
+ * Applications should normally define a narrower domain-specific ID type.
+ * Branded ID types prevent IDs from unrelated domains from being mixed
+ * accidentally, even when both use strings at runtime.
+ *
+ * @example
+ *
+ * ```ts
+ * const myIdSchema = z
+ *   .string()
+ *   .min(1)
+ *   .brand<'MyId'>();
+ *
+ * type MyId = z.output<typeof myIdSchema>;
+ *
+ * type MyItem = Readonly<{
+ *   label: string;
+ *   href?: string;
+ * }>;
+ *
+ * type MyTreeModel = TreeNodeModel<MyId, MyItem>;
+ * ```
+ */
+export type { SerializableKey };
+/**
+ * Validates a serializable primitive suitable for use as a tree-node ID.
+ *
+ * Strings are accepted without additional restrictions. Numbers must be
+ * finite: `NaN`, `Infinity`, and `-Infinity` are rejected.
+ *
+ * Applications can derive narrower schemas to impose domain-specific
+ * restrictions or produce branded ID types.
+ *
+ * @remarks
+ *
+ * Requires Zod v4, where `z.number()` rejects non-finite values.
+ */
+export declare const serializableKeySchema: z.ZodType<SerializableKey>;
+/**
+ * A structural model for persisting or exchanging a tree node.
+ *
+ * @remarks
+ *
+ * This model is independent of the opaque runtime tree representation.
+ * It consists of ordinary objects and ordered child arrays.
+ *
+ * The presence and value of `children` distinguish three node states:
+ *
+ * - Absent: a leaf, which cannot contain children.
+ * - `null`: a branch whose children have not been loaded.
+ * - An array: a branch whose children are loaded, possibly with no children.
+ *
+ * Loaded children form an ordered sequence. Their array positions describe
+ * child order, while their IDs identify them independently of those positions.
+ * Direct siblings must have unique IDs.
+ *
+ * The model is suitable for JSON serialization when `Id` and `Value` are
+ * JSON-serializable. The generic `Value` type does not itself guarantee this.
+ *
+ * `Readonly` prevents structural mutation through these types at compile time.
+ * It does not freeze objects at runtime or make application-owned values
+ * deeply immutable.
+ *
+ * Models represent finite trees, not cyclic object graphs.
+ *
+ * @typeParam Id - The type identifying each node among its direct siblings.
+ * @typeParam Value - Application-owned data associated with each node.
+ */
+export type TreeNodeModel<Id extends SerializableKey, Value> = LeafTreeNodeModel<Id, Value> | UnloadedBranchTreeNodeModel<Id, Value> | LoadedBranchTreeNodeModel<Id, Value>;
+/**
+ * A structural model of a leaf node.
+ *
+ * A leaf cannot contain children. This is distinct from a loaded branch
+ * whose child array is currently empty.
+ *
+ * @typeParam Id - The type identifying this node among its direct siblings.
+ * @typeParam Value - Application-owned data associated with this node.
+ */
+export type LeafTreeNodeModel<Id extends SerializableKey, Value> = Readonly<{
+    id: Id;
+    value: Value;
+    children?: never;
+}>;
+/**
+ * A structural model of a branch whose children have not been loaded.
+ *
+ * The branch may contain children, but their identities, order, and values
+ * are unavailable in this model. `null` does not mean the branch is empty.
+ *
+ * @typeParam Id - The type identifying this node among its direct siblings.
+ * @typeParam Value - Application-owned data associated with this node.
+ */
+export type UnloadedBranchTreeNodeModel<Id extends SerializableKey, Value> = Readonly<{
+    id: Id;
+    value: Value;
+    children: null;
+}>;
+/**
+ * A structural model of a branch with loaded children.
+ *
+ * An empty child array represents a loaded branch with no current children,
+ * not a leaf. The branch can still contain children.
+ *
+ * @typeParam Id - The type identifying this node among its direct siblings.
+ * @typeParam Value - Application-owned data associated with this node.
+ */
+export type LoadedBranchTreeNodeModel<Id extends SerializableKey, Value> = Readonly<{
+    id: Id;
+    value: Value;
+    children: readonly TreeNodeModel<Id, Value>[];
+}>;
+/**
+ * Creates a recursive schema for validating structural tree-node models.
+ *
+ * @remarks
+ *
+ * The supplied schemas validate every node's ID and application-owned value.
+ * The returned schema validates the three node shapes recursively:
+ *
+ * - Leaves omit `children`.
+ * - Unloaded branches have `children: null`.
+ * - Loaded branches have an ordered array of valid child models.
+ *
+ * Node objects are strict: properties other than `id`, `value`, and the
+ * appropriate `children` property are rejected. Validation of properties
+ * inside `value` is controlled by `valueSchema`.
+ *
+ * Child arrays are parsed in their existing order; this schema does not sort
+ * or reorder children.
+ *
+ * This schema validates shape and field values, but does not enforce
+ * sibling-ID uniqueness. That invariant must be checked when constructing
+ * runtime tree nodes or by an additional validation step.
+ *
+ * The supplied ID schema is responsible for enforcing the runtime ID
+ * constraints, including finite numeric IDs. The generic constraint alone
+ * cannot enforce those restrictions.
+ *
+ * Inputs must describe finite trees. Cyclic object graphs are not supported.
+ *
+ * @typeParam Id - The validated node-ID type.
+ * @typeParam Value - The validated application-value type.
+ * @param idSchema - Schema used to validate every node's ID.
+ * @param valueSchema - Schema used to validate every node's application data.
+ * @returns A recursive schema for the application's tree-node models.
+ *
+ * @example
+ *
+ * ```ts
+ * const myIdSchema = serializableKeySchema
+ *   .pipe(z.string().min(1))
+ *   .brand<'MyId'>();
+ *
+ * type MyId = z.output<typeof myIdSchema>;
+ *
+ * const modelSchema = createTreeNodeModelSchema(
+ *   myIdSchema,
+ *   z.object({ label: z.string() }).strict(),
+ * );
+ *
+ * const model = modelSchema.parse({
+ *   id: 'root',
+ *   value: { label: 'My' },
+ *   children: [
+ *     {
+ *       id: 'home',
+ *       value: { label: 'Home' },
+ *     },
+ *     {
+ *       id: 'settings',
+ *       value: { label: 'Settings' },
+ *       children: null,
+ *     },
+ *   ],
+ * });
+ * ```
+ */
+export declare function createTreeNodeModelSchema<Id extends SerializableKey, Value>(idSchema: z.ZodType<Id>, valueSchema: z.ZodType<Value>): z.ZodType<TreeNodeModel<Id, Value>>;
+//# sourceMappingURL=tree-node.model.d.ts.map

package/dist/state-and-nav/tree/tree-node.model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree-node.model.d.ts","sourceRoot":"","sources":["../../../src/state-and-nav/tree/tree-node.model.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,YAAY,EAAE,eAAe,EAAE,CAAA;AAE/B;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,qBAAqB,EAAE,CAAC,CAAC,OAAO,CAAC,eAAe,CAG3D,CAAC;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,MAAM,aAAa,CAAC,EAAE,SAAS,eAAe,EAAE,KAAK,IACvD,iBAAiB,CAAC,EAAE,EAAE,KAAK,CAAC,GAC5B,2BAA2B,CAAC,EAAE,EAAE,KAAK,CAAC,GACtC,yBAAyB,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC;AAEzC;;;;;;;;GAQG;AACH,MAAM,MAAM,iBAAiB,CAAC,EAAE,SAAS,eAAe,EAAE,KAAK,IAAI,QAAQ,CAAC;IAC1E,EAAE,EAAE,EAAE,CAAC;IACP,KAAK,EAAE,KAAK,CAAC;IACb,QAAQ,CAAC,EAAE,KAAK,CAAC;CAClB,CAAC,CAAC;AAEH;;;;;;;;GAQG;AACH,MAAM,MAAM,2BAA2B,CACrC,EAAE,SAAS,eAAe,EAC1B,KAAK,IACH,QAAQ,CAAC;IACX,EAAE,EAAE,EAAE,CAAC;IACP,KAAK,EAAE,KAAK,CAAC;IACb,QAAQ,EAAE,IAAI,CAAC;CAChB,CAAC,CAAC;AAEH;;;;;;;;GAQG;AACH,MAAM,MAAM,yBAAyB,CACnC,EAAE,SAAS,eAAe,EAC1B,KAAK,IACH,QAAQ,CAAC;IACX,EAAE,EAAE,EAAE,CAAC;IACP,KAAK,EAAE,KAAK,CAAC;IACb,QAAQ,EAAE,SAAS,aAAa,CAAC,EAAE,EAAE,KAAK,CAAC,EAAE,CAAC;CAC/C,CAAC,CAAC;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiEG;AACH,wBAAgB,yBAAyB,CAAC,EAAE,SAAS,eAAe,EAAE,KAAK,EACzE,QAAQ,EAAE,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,EACvB,WAAW,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,GAC5B,CAAC,CAAC,OAAO,CAAC,aAAa,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC,CA+BrC"}