dirvi-lib 0.8.1 → 0.9.0

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

@@ -0,0 +1,286 @@
+/**
+ * Crosses from the opaque public type into the private representation.
+ *
+ * This cast is intentionally centralized here. Public callers should never
+ * need to know that tree nodes currently use `{ id, value, children }`.
+ */
+function toData(node) {
+    return node;
+}
+/**
+ * Crosses from the private representation into the opaque public type.
+ */
+function fromData(data) {
+    return data;
+}
+function isLeafData(node) {
+    return !('children' in node);
+}
+function isUnloadedBranchData(node) {
+    return 'children' in node && node.children === null;
+}
+function isLoadedBranchData(node) {
+    return 'children' in node && node.children !== null;
+}
+/**
+ * Returns a reusable iterable over child nodes without exposing the internal
+ * child-array representation.
+ *
+ * The implementation currently stores children in an array, but callers only
+ * receive an `Iterable` and must not rely on iteration order.
+ */
+function asChildrenIterable(children) {
+    return Object.freeze({
+        *[Symbol.iterator]() {
+            yield* children;
+        },
+    });
+}
+/**
+ * Copies an arbitrary child iterable into the current private representation
+ * and verifies sibling-ID uniqueness.
+ *
+ * Returning `undefined` represents an invalid child collection rather than an
+ * exceptional implementation failure. This matches the public API contract
+ * for `createLoadedBranch` and `withLoadedChildren`.
+ */
+function copyUniqueChildren(children, getId) {
+    const copiedChildren = [...children];
+    const seenIds = new Set();
+    for (const child of copiedChildren) {
+        const id = getId(child);
+        if (seenIds.has(id)) {
+            return undefined;
+        }
+        seenIds.add(id);
+    }
+    return Object.freeze(copiedChildren);
+}
+function createLeafData(id, value) {
+    return Object.freeze({
+        id,
+        value,
+    });
+}
+function createUnloadedBranchData(id, value) {
+    return Object.freeze({
+        id,
+        value,
+        children: null,
+    });
+}
+function createLoadedBranchData(id, value, children) {
+    return Object.freeze({
+        id,
+        value,
+        children,
+    });
+}
+/**
+ * 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 function createTreeNodeApi() {
+    function getOpenChildren(node) {
+        const data = toData(node);
+        return isLoadedBranchData(data) ? data.children : undefined;
+    }
+    const api = {
+        createLeaf(id, value) {
+            return fromData(createLeafData(id, value));
+        },
+        createUnloadedBranch(id, value) {
+            return fromData(createUnloadedBranchData(id, value));
+        },
+        createLoadedBranch(id, value, children) {
+            const copiedChildren = copyUniqueChildren(children, api.id);
+            if (copiedChildren === undefined) {
+                return undefined;
+            }
+            return fromData(createLoadedBranchData(id, value, copiedChildren));
+        },
+        id(node) {
+            return toData(node).id;
+        },
+        value(node) {
+            return toData(node).value;
+        },
+        kind(node) {
+            const data = toData(node);
+            if (isLeafData(data)) {
+                return 'leaf';
+            }
+            if (isUnloadedBranchData(data)) {
+                return 'unloaded-branch';
+            }
+            return 'loaded-branch';
+        },
+        match(node, handlers) {
+            const data = toData(node);
+            if (isLeafData(data)) {
+                return handlers.leaf({
+                    id: data.id,
+                    value: data.value,
+                });
+            }
+            if (isUnloadedBranchData(data)) {
+                return handlers.unloadedBranch({
+                    id: data.id,
+                    value: data.value,
+                });
+            }
+            return handlers.loadedBranch({
+                id: data.id,
+                value: data.value,
+                children: asChildrenIterable(data.children),
+            });
+        },
+        getLoadedChildren(node) {
+            const children = getOpenChildren(node);
+            return children === undefined ? undefined : asChildrenIterable(children);
+        },
+        findChildById(node, id) {
+            const children = getOpenChildren(node);
+            if (children === undefined) {
+                return undefined;
+            }
+            for (const child of children) {
+                if (api.id(child) === id) {
+                    return child;
+                }
+            }
+            return undefined;
+        },
+        withValue(node, value) {
+            const data = toData(node);
+            if (isLeafData(data)) {
+                return fromData(createLeafData(data.id, value));
+            }
+            if (isUnloadedBranchData(data)) {
+                return fromData(createUnloadedBranchData(data.id, value));
+            }
+            return fromData(createLoadedBranchData(data.id, value, data.children));
+        },
+        toLeaf(node) {
+            const data = toData(node);
+            return fromData(createLeafData(data.id, data.value));
+        },
+        toUnloadedBranch(node) {
+            const data = toData(node);
+            return fromData(createUnloadedBranchData(data.id, data.value));
+        },
+        withLoadedChildren(node, children) {
+            const copiedChildren = copyUniqueChildren(children, api.id);
+            if (copiedChildren === undefined) {
+                return undefined;
+            }
+            const data = toData(node);
+            return fromData(createLoadedBranchData(data.id, data.value, copiedChildren));
+        },
+        findAtPath(root, path) {
+            return api.selectAtPath(root, path, (node) => node);
+        },
+        selectAtPath(root, path, selector) {
+            let node = root;
+            for (const id of path) {
+                const child = api.findChildById(node, id);
+                if (child === undefined) {
+                    return undefined;
+                }
+                node = child;
+            }
+            return selector(node);
+        },
+        updateAtPath(root, path, update) {
+            if (path.length === 0) {
+                return update(root);
+            }
+            return modifyChildAtPath(root, path, update);
+        },
+        toModel(node) {
+            const data = toData(node);
+            if (isLeafData(data)) {
+                return {
+                    id: data.id,
+                    value: data.value,
+                };
+            }
+            if (isUnloadedBranchData(data)) {
+                return {
+                    id: data.id,
+                    value: data.value,
+                    children: null,
+                };
+            }
+            return {
+                id: data.id,
+                value: data.value,
+                children: data.children.map(api.toModel),
+            };
+        },
+        fromModel(model) {
+            if (!('children' in model)) {
+                return api.createLeaf(model.id, model.value);
+            }
+            if (model.children === null) {
+                return api.createUnloadedBranch(model.id, model.value);
+            }
+            const children = [];
+            for (const childModel of model.children) {
+                const child = api.fromModel(childModel);
+                if (child === undefined) {
+                    return undefined;
+                }
+                children.push(child);
+            }
+            return api.createLoadedBranch(model.id, model.value, children);
+        }
+    };
+    function modifyChildAtPath(node, path, modifier) {
+        const childId = path[0];
+        const children = getOpenChildren(node);
+        if (childId === undefined || children === undefined) {
+            return undefined;
+        }
+        let childIndex = -1;
+        for (const [index, child] of children.entries()) {
+            if (api.id(child) === childId) {
+                childIndex = index;
+                break;
+            }
+        }
+        if (childIndex === -1) {
+            return undefined;
+        }
+        const child = children[childIndex];
+        if (child === undefined) {
+            return undefined;
+        }
+        const updatedChild = path.length === 1
+            ? modifier(child)
+            : modifyChildAtPath(child, path.slice(1), modifier);
+        if (updatedChild === undefined) {
+            return undefined;
+        }
+        /*
+         * The current representation happens to use an array, so replacing one
+         * child is efficient internally. The public API makes no ordering promise:
+         * this is solely an implementation detail.
+         */
+        const updatedChildren = [...children];
+        updatedChildren[childIndex] = updatedChild;
+        /*
+         * `withChildren` revalidates sibling-ID uniqueness. This matters when
+         * `modifier` replaces a node with another node having a different ID.
+         */
+        return api.withLoadedChildren(node, updatedChildren);
+    }
+    return api;
+}

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

@@ -0,0 +1,78 @@
+import { z } from 'zod';
+/**
+ * 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 menuIdSchema = z
+ *   .string()
+ *   .min(1)
+ *   .brand<'MenuId'>();
+ *
+ * type MenuId = z.output<typeof menuIdSchema>;
+ *
+ * type MenuItem = Readonly<{
+ *   label: string;
+ *   href?: string;
+ * }>;
+ *
+ * type MenuTree = TreeNode<MenuId, MenuItem>;
+ * ```
+ */
+export type SerializableKey = string | number;
+/**
+ * Validates a serializable primitive suitable for use as a stable tree-node ID.
+ *
+ * Strings are always accepted. Numbers must be finite: `NaN`, `Infinity`, and
+ * `-Infinity` are rejected.
+ */
+export declare const serializableKeySchema: z.ZodType<SerializableKey>;
+/**
+ * A structural, serializable snapshot of a tree node.
+ *
+ * This is a public persistence and interchange model for `TreeNode`; it is
+ * not the runtime representation of an opaque `TreeNode` value.
+ *
+ * Loaded children are represented by an array because JSON has no native
+ * unordered collection type. The array encodes an unordered collection of
+ * sibling-unique nodes: its iteration order has no semantic meaning and is
+ * not guaranteed to be preserved by `TreeNodeApi.fromModel`,
+ * `TreeNodeApi.toModel`, or other tree operations.
+ *
+ * Applications that need visual or navigation order should derive ordered UI
+ * rows from the tree using an explicit ordering policy.
+ */
+export type TreeNodeModel<Id extends SerializableKey, Value> = LeafTreeNodeModel<Id, Value> | UnloadedBranchTreeNodeModel<Id, Value> | LoadedBranchTreeNodeModel<Id, Value>;
+export type LeafTreeNodeModel<Id extends SerializableKey, Value> = Readonly<{
+    id: Id;
+    value: Value;
+    children?: never;
+}>;
+export type UnloadedBranchTreeNodeModel<Id extends SerializableKey, Value> = Readonly<{
+    id: Id;
+    value: Value;
+    children: null;
+}>;
+export type LoadedBranchTreeNodeModel<Id extends SerializableKey, Value> = Readonly<{
+    id: Id;
+    value: Value;
+    children: readonly TreeNodeModel<Id, Value>[];
+}>;
+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/trees/tree-node/tree-node.model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree-node.model.d.ts","sourceRoot":"","sources":["../../../src/trees/tree-node/tree-node.model.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,MAAM,CAAC;AAE9C;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,EAAE,CAAC,CAAC,OAAO,CAAC,eAAe,CAG3D,CAAC;AAEH;;;;;;;;;;;;;;GAcG;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,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,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,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,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"}

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

@@ -0,0 +1,37 @@
+import { z } from 'zod';
+/**
+ * Validates a serializable primitive suitable for use as a stable tree-node ID.
+ *
+ * Strings are always accepted. Numbers must be finite: `NaN`, `Infinity`, and
+ * `-Infinity` are rejected.
+ */
+export const serializableKeySchema = z.union([
+    z.string(),
+    z.number(),
+]);
+export function createTreeNodeModelSchema(idSchema, valueSchema) {
+    let nodeSchema;
+    nodeSchema = z.lazy(() => z.union([
+        z
+            .object({
+            id: idSchema,
+            value: valueSchema,
+        })
+            .strict(),
+        z
+            .object({
+            id: idSchema,
+            value: valueSchema,
+            children: z.null(),
+        })
+            .strict(),
+        z
+            .object({
+            id: idSchema,
+            value: valueSchema,
+            children: z.array(nodeSchema),
+        })
+            .strict(),
+    ]));
+    return nodeSchema;
+}