dirvi-lib 0.8.1 → 0.8.2

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

@@ -0,0 +1,451 @@
+function toData(folds) {
+    return folds;
+}
+function fromData(data) {
+    return data;
+}
+function isValidFoldIndex(index) {
+    return Number.isSafeInteger(index) && index >= 0;
+}
+function hasUniqueValues(values) {
+    return new Set(values).size === values.length;
+}
+/**
+ * Creates operations for an immutable collection of independently active fold
+ * trees.
+ *
+ * Each fold tree preserves its own hidden-entry definition. An entry is hidden
+ * by the aggregate when at least one active fold tree hides it.
+ */
+export function createFoldsApi(foldTreeApi) {
+    function createEmptyFoldTree(rootId) {
+        const tree = foldTreeApi.createLoadedBranch(rootId, [], []);
+        /*
+         * An empty child collection cannot contain duplicate IDs. Failure would
+         * therefore indicate a broken TreeNodeApi implementation or contract.
+         */
+        if (tree === undefined) {
+            throw new Error('Could not create an empty fold tree');
+        }
+        return tree;
+    }
+    function getSlotAtIndex(folds, index) {
+        if (!isValidFoldIndex(index)) {
+            return undefined;
+        }
+        return toData(folds).slots[index];
+    }
+    function withSlotAtIndex(folds, index, foldData) {
+        if (!isValidFoldIndex(index)) {
+            throw new RangeError('Fold index must be a non-negative safe integer');
+        }
+        const data = toData(folds);
+        const slots = [...data.slots];
+        while (slots.length <= index) {
+            slots.push(undefined);
+        }
+        slots[index] = foldData;
+        /*
+         * `setAtIndex` permits replacing the primary slot. Other public operations
+         * preserve the invariant that slot zero is always occupied.
+         */
+        return fromData({
+            slots: slots,
+        });
+    }
+    function updateSlotAtIndex(folds, index, update) {
+        const foldData = getSlotAtIndex(folds, index);
+        if (foldData === undefined) {
+            return undefined;
+        }
+        const updatedFoldData = update(foldData);
+        if (updatedFoldData === foldData) {
+            return folds;
+        }
+        return withSlotAtIndex(folds, index, updatedFoldData);
+    }
+    function removeSlotAtIndex(folds, index) {
+        const data = toData(folds);
+        const slots = [...data.slots];
+        slots[index] = undefined;
+        /*
+         * Trailing unoccupied slots carry no information, so omit them from the
+         * immutable runtime representation.
+         */
+        while (slots.length > 1 && slots[slots.length - 1] === undefined) {
+            slots.pop();
+        }
+        return fromData({
+            slots: slots,
+        });
+    }
+    function getLoadedChildren(tree) {
+        const children = foldTreeApi.getLoadedChildren(tree);
+        return children === undefined ? undefined : [...children];
+    }
+    function createEmptyFoldNode(id) {
+        const tree = foldTreeApi.createLoadedBranch(id, [], []);
+        if (tree === undefined) {
+            throw new Error('Could not create an empty fold node');
+        }
+        return tree;
+    }
+    /**
+     * Creates structural fold-tree nodes for `path` where they do not already
+     * exist. A fold tree structurally retains descendants even when an entry is
+     * hidden at its parent, so paths may pass through hidden entry IDs.
+     */
+    function ensurePath(tree, path) {
+        if (path.length === 0) {
+            return tree;
+        }
+        const children = getLoadedChildren(tree);
+        if (children === undefined) {
+            return undefined;
+        }
+        const childId = path[0];
+        if (childId === undefined) {
+            return undefined;
+        }
+        const childIndex = children.findIndex((child) => foldTreeApi.id(child) === childId);
+        const child = childIndex === -1 ? createEmptyFoldNode(childId) : children[childIndex];
+        if (child === undefined) {
+            return undefined;
+        }
+        const updatedChild = ensurePath(child, path.slice(1));
+        if (updatedChild === undefined) {
+            return undefined;
+        }
+        if (childIndex === -1) {
+            return foldTreeApi.withLoadedChildren(tree, [...children, updatedChild]);
+        }
+        if (updatedChild === child) {
+            return tree;
+        }
+        const updatedChildren = [...children];
+        updatedChildren[childIndex] = updatedChild;
+        return foldTreeApi.withLoadedChildren(tree, updatedChildren);
+    }
+    function isEmptyFoldNode(tree) {
+        const children = getLoadedChildren(tree);
+        if (children === undefined) {
+            return undefined;
+        }
+        return foldTreeApi.value(tree).length === 0 && children.length === 0;
+    }
+    /**
+     * Updates one existing fold-tree node and prunes empty sparse descendants on
+     * the path back to the root.
+     *
+     * The root is always retained, even if it becomes empty.
+     */
+    function updateAtPathAndPrune(tree, path, update) {
+        if (path.length === 0) {
+            return update(tree);
+        }
+        const children = getLoadedChildren(tree);
+        if (children === undefined) {
+            return undefined;
+        }
+        const childId = path[0];
+        if (childId === undefined) {
+            return undefined;
+        }
+        const childIndex = children.findIndex((child) => foldTreeApi.id(child) === childId);
+        if (childIndex === -1) {
+            return undefined;
+        }
+        const child = children[childIndex];
+        if (child === undefined) {
+            return undefined;
+        }
+        const updatedChild = updateAtPathAndPrune(child, path.slice(1), update);
+        if (updatedChild === undefined) {
+            return undefined;
+        }
+        if (updatedChild === child) {
+            return tree;
+        }
+        const childIsEmpty = isEmptyFoldNode(updatedChild);
+        if (childIsEmpty === undefined) {
+            return undefined;
+        }
+        const updatedChildren = [...children];
+        if (childIsEmpty) {
+            updatedChildren.splice(childIndex, 1);
+        }
+        else {
+            updatedChildren[childIndex] = updatedChild;
+        }
+        return foldTreeApi.withLoadedChildren(tree, updatedChildren);
+    }
+    function foldTreeToModel(tree) {
+        return foldTreeApi.match(tree, {
+            leaf: () => {
+                throw new Error('Fold trees must contain loaded branch nodes');
+            },
+            unloadedBranch: () => {
+                throw new Error('Fold trees must contain loaded branch nodes');
+            },
+            loadedBranch: ({ id, value, children }) => ({
+                id,
+                hiddenEntryIds: [...value],
+                children: [...children].map(foldTreeToModel),
+            }),
+        });
+    }
+    function foldSlotToModel(foldData) {
+        return {
+            name: foldData.name,
+            description: foldData.description,
+            active: foldData.active,
+            tree: foldTreeToModel(foldData.tree),
+        };
+    }
+    function foldTreeFromModel(model) {
+        if (!hasUniqueValues(model.hiddenEntryIds)) {
+            return undefined;
+        }
+        const children = [];
+        for (const childModel of model.children) {
+            const child = foldTreeFromModel(childModel);
+            if (child === undefined) {
+                return undefined;
+            }
+            children.push(child);
+        }
+        return foldTreeApi.createLoadedBranch(model.id, [...model.hiddenEntryIds], children);
+    }
+    const api = {
+        create(rootId, initialPrimaryInfo) {
+            return fromData({
+                slots: [
+                    {
+                        name: initialPrimaryInfo.name,
+                        description: initialPrimaryInfo.description,
+                        active: true,
+                        tree: createEmptyFoldTree(rootId),
+                    },
+                ],
+            });
+        },
+        getInfoAtIndex(folds, index) {
+            const foldData = getSlotAtIndex(folds, index);
+            if (foldData === undefined) {
+                return undefined;
+            }
+            return {
+                name: foldData.name,
+                description: foldData.description,
+            };
+        },
+        isActiveAtIndex(folds, index) {
+            return getSlotAtIndex(folds, index)?.active;
+        },
+        hasAtIndex(folds, index) {
+            return getSlotAtIndex(folds, index) !== undefined;
+        },
+        *indexes(folds) {
+            const { slots } = toData(folds);
+            for (let index = 0; index < slots.length; index += 1) {
+                if (slots[index] !== undefined) {
+                    yield index;
+                }
+            }
+        },
+        setAtIndex(folds, index, foldData) {
+            if (!isValidFoldIndex(index)) {
+                return undefined;
+            }
+            const tree = foldTreeFromModel(foldData.tree);
+            if (tree === undefined) {
+                return undefined;
+            }
+            return withSlotAtIndex(folds, index, {
+                name: foldData.name,
+                description: foldData.description,
+                active: foldData.active,
+                tree,
+            });
+        },
+        setAdditionalFoldAtIndex(folds, index, rootId, info) {
+            if (!isValidFoldIndex(index) || index === 0) {
+                return undefined;
+            }
+            return withSlotAtIndex(folds, index, {
+                name: info.name,
+                description: info.description,
+                active: true,
+                tree: createEmptyFoldTree(rootId),
+            });
+        },
+        removeAdditionalFoldAtIndex(folds, index) {
+            if (!isValidFoldIndex(index) || index === 0) {
+                return undefined;
+            }
+            if (getSlotAtIndex(folds, index) === undefined) {
+                return folds;
+            }
+            return removeSlotAtIndex(folds, index);
+        },
+        updateInfoAtIndex(folds, index, update) {
+            return updateSlotAtIndex(folds, index, (foldData) => {
+                const name = update.name ?? foldData.name;
+                const description = update.description === undefined
+                    ? foldData.description
+                    : update.description;
+                if (name === foldData.name && description === foldData.description) {
+                    return foldData;
+                }
+                return {
+                    ...foldData,
+                    name,
+                    description,
+                };
+            });
+        },
+        activateAtIndex(folds, index) {
+            return updateSlotAtIndex(folds, index, (foldData) => foldData.active ? foldData : { ...foldData, active: true });
+        },
+        deactivateAtIndex(folds, index) {
+            return updateSlotAtIndex(folds, index, (foldData) => !foldData.active ? foldData : { ...foldData, active: false });
+        },
+        toggleActiveAtIndex(folds, index) {
+            return updateSlotAtIndex(folds, index, (foldData) => ({
+                ...foldData,
+                active: !foldData.active,
+            }));
+        },
+        isEntryHiddenInFoldAtPath(folds, index, path, entryId) {
+            const foldData = getSlotAtIndex(folds, index);
+            if (foldData === undefined) {
+                return false;
+            }
+            return (foldTreeApi.selectAtPath(foldData.tree, path, (node) => foldTreeApi.value(node).includes(entryId)) ?? false);
+        },
+        isEntryHiddenAtPath(folds, path, entryId) {
+            for (const index of api.indexes(folds)) {
+                if (api.isActiveAtIndex(folds, index) === true &&
+                    api.isEntryHiddenInFoldAtPath(folds, index, path, entryId)) {
+                    return true;
+                }
+            }
+            return false;
+        },
+        hiddenEntryIdsAtPath(folds, index, path) {
+            const foldData = getSlotAtIndex(folds, index);
+            if (foldData === undefined) {
+                return undefined;
+            }
+            return foldTreeApi.selectAtPath(foldData.tree, path, (node) => [
+                ...foldTreeApi.value(node),
+            ]);
+        },
+        hideEntryAtPath(folds, index, path, entryId) {
+            const foldData = getSlotAtIndex(folds, index);
+            if (foldData === undefined) {
+                return undefined;
+            }
+            if (api.isEntryHiddenInFoldAtPath(folds, index, path, entryId)) {
+                return folds;
+            }
+            const treeWithPath = ensurePath(foldData.tree, path);
+            if (treeWithPath === undefined) {
+                return undefined;
+            }
+            const updatedTree = updateAtPathAndPrune(treeWithPath, path, (node) => foldTreeApi.withValue(node, [...foldTreeApi.value(node), entryId]));
+            if (updatedTree === undefined) {
+                return undefined;
+            }
+            return withSlotAtIndex(folds, index, {
+                ...foldData,
+                tree: updatedTree,
+            });
+        },
+        showEntryAtPath(folds, index, path, entryId) {
+            const foldData = getSlotAtIndex(folds, index);
+            if (foldData === undefined) {
+                return undefined;
+            }
+            const updatedTree = updateAtPathAndPrune(foldData.tree, path, (node) => {
+                const hiddenEntryIds = foldTreeApi.value(node);
+                if (!hiddenEntryIds.includes(entryId)) {
+                    return node;
+                }
+                return foldTreeApi.withValue(node, hiddenEntryIds.filter((id) => id !== entryId));
+            });
+            if (updatedTree === undefined) {
+                return undefined;
+            }
+            if (updatedTree === foldData.tree) {
+                return folds;
+            }
+            return withSlotAtIndex(folds, index, {
+                ...foldData,
+                tree: updatedTree,
+            });
+        },
+        showAllHiddenEntriesAtPath(folds, index, path) {
+            const foldData = getSlotAtIndex(folds, index);
+            if (foldData === undefined) {
+                return undefined;
+            }
+            const updatedTree = updateAtPathAndPrune(foldData.tree, path, (node) => {
+                if (foldTreeApi.value(node).length === 0) {
+                    return node;
+                }
+                return foldTreeApi.withValue(node, []);
+            });
+            if (updatedTree === undefined) {
+                return undefined;
+            }
+            if (updatedTree === foldData.tree) {
+                return folds;
+            }
+            return withSlotAtIndex(folds, index, {
+                ...foldData,
+                tree: updatedTree,
+            });
+        },
+        toModel(folds) {
+            const { slots } = toData(folds);
+            const modelSlots = [
+                foldSlotToModel(slots[0]),
+                ...slots
+                    .slice(1)
+                    .map((foldData) => foldData === undefined ? null : foldSlotToModel(foldData)),
+            ];
+            return {
+                slots: modelSlots,
+            };
+        },
+        fromModel(model) {
+            const slots = [];
+            for (const foldSlotModel of model.slots) {
+                if (foldSlotModel === null) {
+                    slots.push(undefined);
+                    continue;
+                }
+                const tree = foldTreeFromModel(foldSlotModel.tree);
+                if (tree === undefined) {
+                    return undefined;
+                }
+                slots.push({
+                    name: foldSlotModel.name,
+                    description: foldSlotModel.description,
+                    active: foldSlotModel.active,
+                    tree,
+                });
+            }
+            const primarySlot = slots[0];
+            if (primarySlot === undefined) {
+                return undefined;
+            }
+            const foldSlots = [primarySlot, ...slots.slice(1)];
+            return fromData({
+                slots: foldSlots,
+            });
+        },
+    };
+    return api;
+}

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

@@ -0,0 +1,120 @@
+import { z } from 'zod';
+import type { SerializableKey } from '../tree-node/index.js';
+/**
+ * Serializable semantic representation of one fold-state tree node.
+ *
+ * This is a persistence/interchange model. It is not the runtime
+ * representation of the fold tree.
+ *
+ * A fold node represents one source-tree node. Its `hiddenEntryIds` are IDs of
+ * direct source-tree entries hidden at that node. Its `children` are sparse
+ * fold-state descendants.
+ *
+ * `children` does not contain every source-tree child. It contains only
+ * children which have fold state at or below them.
+ *
+ * A child fold-node ID is allowed to also appear in `hiddenEntryIds`. For
+ * example:
+ *
+ * ```text
+ * root
+ *   hiddenEntryIds: ["src"]
+ *   children:
+ *     - id: "src"
+ *       hiddenEntryIds: ["lib"]
+ * ```
+ *
+ * This means `src` is hidden directly under `root`, while fold state below
+ * `src` is retained for when it is shown again.
+ */
+export type FoldNodeModel<Id extends SerializableKey> = Readonly<{
+    /**
+     * The source-tree node ID represented by this fold-state node.
+     */
+    id: Id;
+    /**
+     * IDs of direct source-tree entries hidden at this node.
+     *
+     * These IDs are semantically a set: duplicates are invalid and iteration
+     * order has no meaning.
+     */
+    hiddenEntryIds: readonly Id[];
+    /**
+     * Sparse child fold-state nodes.
+     *
+     * This is semantically keyed by child ID. Array order has no meaning.
+     */
+    children: readonly FoldNodeModel<Id>[];
+}>;
+/**
+ * Creates a schema for one serialized fold-state tree.
+ *
+ * The schema validates fold-tree-local invariants only:
+ *
+ * - every hidden entry ID is unique within its fold node;
+ * - every child fold-node ID is unique within its parent.
+ *
+ * It intentionally does not validate:
+ *
+ * - that an ID exists in a particular source tree;
+ * - that a child fold node corresponds to a direct source-tree child;
+ * - whether the represented source-tree node is a branch;
+ * - whether an entry is currently loaded in the source tree.
+ *
+ * Those rules require access to the source tree and belong in a fold service,
+ * not in this serialization schema.
+ */
+export declare function createFoldNodeModelSchema<Id extends SerializableKey>(idSchema: z.ZodType<Id>): z.ZodType<FoldNodeModel<Id>>;
+/**
+ * Serializable metadata and fold-state tree for one occupied fold slot.
+ *
+ * `description: null` means that this fold tree has no description.
+ * An empty string is a supplied description with no text.
+ */
+export type FoldSlotModel<Id extends SerializableKey> = Readonly<{
+    /**
+     * User-facing name of this fold tree.
+     */
+    name: string;
+    /**
+     * User-facing description of this fold tree, or `null` when it has none.
+     */
+    description: string | null;
+    /**
+     * Whether this fold tree currently contributes to hiding entries.
+     *
+     * An inactive fold tree retains its fold definition but does not affect the
+     * visible navigation projection.
+     */
+    active: boolean;
+    /**
+     * The fold-state tree stored in this slot.
+     */
+    tree: FoldNodeModel<Id>;
+}>;
+/**
+ * Serializable representation of Folds.
+ *
+ * `null` represents an unoccupied non-primary slot. Do not use `undefined`:
+ * JSON serialization converts undefined array entries to null anyway.
+ */
+export type FoldsModel<Id extends SerializableKey> = Readonly<{
+    slots: readonly [FoldSlotModel<Id>, ...(FoldSlotModel<Id> | null)[]];
+}>;
+/**
+ * Creates a schema for the serializable fold collection.
+ *
+ * This validates:
+ *
+ * - there is always a primary slot at index zero;
+ * - every occupied slot has a name, a description or `null`, active state,
+ *   and a valid fold tree;
+ * - every non-primary slot is either an occupied fold slot or `null`.
+ *
+ * A slot's `description: null` means that its fold tree has no description.
+ *
+ * It does not validate fold-tree names for uniqueness. That is a domain rule
+ * only if the fold service decides names must be unique.
+ */
+export declare function createFoldsModelSchema<Id extends SerializableKey>(idSchema: z.ZodType<Id>): z.ZodType<FoldsModel<Id>>;
+//# sourceMappingURL=fold-node.model.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"fold-node.model.d.ts","sourceRoot":"","sources":["../../../src/trees/fold-node/fold-node.model.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAY7D;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,MAAM,aAAa,CAAC,EAAE,SAAS,eAAe,IAAI,QAAQ,CAAC;IAC/D;;OAEG;IACH,EAAE,EAAE,EAAE,CAAC;IAEP;;;;;OAKG;IACH,cAAc,EAAE,SAAS,EAAE,EAAE,CAAC;IAE9B;;;;OAIG;IACH,QAAQ,EAAE,SAAS,aAAa,CAAC,EAAE,CAAC,EAAE,CAAC;CACxC,CAAC,CAAC;AAEH;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,yBAAyB,CAAC,EAAE,SAAS,eAAe,EAClE,QAAQ,EAAE,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,GACtB,CAAC,CAAC,OAAO,CAAC,aAAa,CAAC,EAAE,CAAC,CAAC,CA0B9B;AAED;;;;;GAKG;AACH,MAAM,MAAM,aAAa,CAAC,EAAE,SAAS,eAAe,IAAI,QAAQ,CAAC;IAC/D;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAE3B;;;;;OAKG;IACH,MAAM,EAAE,OAAO,CAAC;IAEhB;;OAEG;IACH,IAAI,EAAE,aAAa,CAAC,EAAE,CAAC,CAAC;CACzB,CAAC,CAAC;AAEH;;;;;GAKG;AACH,MAAM,MAAM,UAAU,CAAC,EAAE,SAAS,eAAe,IAAI,QAAQ,CAAC;IAC5D,KAAK,EAAE,SAAS,CAAC,aAAa,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,aAAa,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,EAAE,CAAC,CAAC;CACtE,CAAC,CAAC;AAEH;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,sBAAsB,CAAC,EAAE,SAAS,eAAe,EAC/D,QAAQ,EAAE,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,GACtB,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC,CAmB3B"}

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

@@ -0,0 +1,80 @@
+import { z } from 'zod';
+/**
+ * Returns whether every value appears at most once.
+ *
+ * `SerializableKey` values are strings or numbers, so `Set` equality is the
+ * appropriate equality relation for fold-node IDs.
+ */
+function hasUniqueValues(values) {
+    return new Set(values).size === values.length;
+}
+/**
+ * Creates a schema for one serialized fold-state tree.
+ *
+ * The schema validates fold-tree-local invariants only:
+ *
+ * - every hidden entry ID is unique within its fold node;
+ * - every child fold-node ID is unique within its parent.
+ *
+ * It intentionally does not validate:
+ *
+ * - that an ID exists in a particular source tree;
+ * - that a child fold node corresponds to a direct source-tree child;
+ * - whether the represented source-tree node is a branch;
+ * - whether an entry is currently loaded in the source tree.
+ *
+ * Those rules require access to the source tree and belong in a fold service,
+ * not in this serialization schema.
+ */
+export function createFoldNodeModelSchema(idSchema) {
+    let nodeSchema;
+    const hiddenEntryIdsSchema = z.array(idSchema).refine(hasUniqueValues, {
+        message: 'Hidden entry IDs must be unique within a fold node',
+        path: ['hiddenEntryIds'],
+    });
+    nodeSchema = z.lazy(() => z
+        .object({
+        id: idSchema,
+        hiddenEntryIds: hiddenEntryIdsSchema,
+        children: z.array(nodeSchema),
+    })
+        .strict()
+        .refine((node) => hasUniqueValues(node.children.map((child) => child.id)), {
+        message: 'Child fold-node IDs must be unique within a fold node',
+        path: ['children'],
+    }));
+    return nodeSchema;
+}
+/**
+ * Creates a schema for the serializable fold collection.
+ *
+ * This validates:
+ *
+ * - there is always a primary slot at index zero;
+ * - every occupied slot has a name, a description or `null`, active state,
+ *   and a valid fold tree;
+ * - every non-primary slot is either an occupied fold slot or `null`.
+ *
+ * A slot's `description: null` means that its fold tree has no description.
+ *
+ * It does not validate fold-tree names for uniqueness. That is a domain rule
+ * only if the fold service decides names must be unique.
+ */
+export function createFoldsModelSchema(idSchema) {
+    const foldNodeSchema = createFoldNodeModelSchema(idSchema);
+    const foldSlotSchema = z
+        .object({
+        name: z.string(),
+        description: z.string().nullable(),
+        active: z.boolean(),
+        tree: foldNodeSchema,
+    })
+        .strict();
+    return z
+        .object({
+        slots: z
+            .tuple([foldSlotSchema])
+            .rest(z.union([foldSlotSchema, z.null()])),
+    })
+        .strict();
+}