@voidhash/mimic 0.0.1 → 0.0.3

package/dist/utils/tree-helpers.d.cts

@@ -0,0 +1,280 @@
+import { AnyTreeNodePrimitive } from "../primitives/TreeNode.cjs";
+import { TreeNodeSnapshot, TreePrimitive } from "../primitives/Tree.cjs";
+
+//#region src/utils/tree-helpers.d.ts
+declare namespace tree_helpers_d_exports {
+  export { FlattenedNode, NodeSearchResult, ParentSearchResult, TraverseOptions, buildNodeTypeMap, canAddChildType, findNode, findNodeById, findNodeWithPath, findNodes, flattenTree, getAllNodeTypes, getAllowedChildTypes, getAllowedChildTypesForNode, getAncestors, getDescendants, getNodeDepth, getNodePrimitive, getNodeTypeByName, getParent, getSiblings, getSubtree, isAncestorOf, isChildTypeAllowed, mapTree, traverse };
+}
+/**
+ * Result of finding a node with path information.
+ */
+interface NodeSearchResult<TNode extends AnyTreeNodePrimitive> {
+  readonly node: TreeNodeSnapshot<TNode>;
+  readonly path: readonly string[];
+  readonly depth: number;
+}
+/**
+ * Result of finding a parent node.
+ */
+interface ParentSearchResult<TNode extends AnyTreeNodePrimitive> {
+  readonly parent: TreeNodeSnapshot<TNode>;
+  readonly childIndex: number;
+}
+/**
+ * Flattened node with parent information.
+ */
+interface FlattenedNode<TNode extends AnyTreeNodePrimitive> {
+  readonly node: TreeNodeSnapshot<TNode>;
+  readonly parentId: string | null;
+  readonly depth: number;
+}
+/**
+ * Options for tree traversal.
+ */
+interface TraverseOptions {
+  readonly order?: "pre" | "post";
+}
+/**
+ * Find a node by ID in a tree snapshot.
+ *
+ * @param snapshot - The root tree snapshot
+ * @param id - The node ID to find
+ * @returns The node snapshot if found, undefined otherwise
+ */
+declare function findNodeById<TNode extends AnyTreeNodePrimitive>(snapshot: TreeNodeSnapshot<TNode> | undefined, id: string): TreeNodeSnapshot<TNode> | undefined;
+/**
+ * Find a node by ID with full path information.
+ *
+ * @param snapshot - The root tree snapshot
+ * @param id - The node ID to find
+ * @returns NodeSearchResult with node, path, and depth, or undefined if not found
+ */
+declare function findNodeWithPath<TNode extends AnyTreeNodePrimitive>(snapshot: TreeNodeSnapshot<TNode> | undefined, id: string): NodeSearchResult<TNode> | undefined;
+/**
+ * Get the parent node of a given node ID.
+ *
+ * @param snapshot - The root tree snapshot
+ * @param nodeId - The ID of the node whose parent we want
+ * @returns ParentSearchResult with parent node and child index, or undefined
+ */
+declare function getParent<TNode extends AnyTreeNodePrimitive>(snapshot: TreeNodeSnapshot<TNode> | undefined, nodeId: string): ParentSearchResult<TNode> | undefined;
+/**
+ * Get a subtree rooted at a specific node ID.
+ *
+ * @param snapshot - The root tree snapshot
+ * @param nodeId - The ID of the node to use as new root
+ * @returns The subtree snapshot, or undefined if node not found
+ */
+declare function getSubtree<TNode extends AnyTreeNodePrimitive>(snapshot: TreeNodeSnapshot<TNode> | undefined, nodeId: string): TreeNodeSnapshot<TNode> | undefined;
+/**
+ * Get all ancestor nodes from a node up to the root.
+ *
+ * @param snapshot - The root tree snapshot
+ * @param nodeId - The ID of the node
+ * @returns Array of ancestor snapshots from immediate parent to root, or empty array
+ */
+declare function getAncestors<TNode extends AnyTreeNodePrimitive>(snapshot: TreeNodeSnapshot<TNode> | undefined, nodeId: string): readonly TreeNodeSnapshot<TNode>[];
+/**
+ * Get all descendant nodes of a given node (flat array).
+ *
+ * @param snapshot - The root tree snapshot
+ * @param nodeId - The ID of the node (if undefined, returns all descendants of root)
+ * @returns Flat array of all descendant node snapshots
+ */
+declare function getDescendants<TNode extends AnyTreeNodePrimitive>(snapshot: TreeNodeSnapshot<TNode> | undefined, nodeId?: string): readonly TreeNodeSnapshot<TNode>[];
+/**
+ * Get siblings of a node (nodes with the same parent).
+ *
+ * @param snapshot - The root tree snapshot
+ * @param nodeId - The ID of the node
+ * @param includeSelf - Whether to include the node itself (default: false)
+ * @returns Array of sibling snapshots
+ */
+declare function getSiblings<TNode extends AnyTreeNodePrimitive>(snapshot: TreeNodeSnapshot<TNode> | undefined, nodeId: string, includeSelf?: boolean): readonly TreeNodeSnapshot<TNode>[];
+/**
+ * Find the first node matching a predicate.
+ *
+ * @param snapshot - The root tree snapshot
+ * @param predicate - Function to test each node
+ * @returns First matching node snapshot, or undefined
+ */
+declare function findNode<TNode extends AnyTreeNodePrimitive>(snapshot: TreeNodeSnapshot<TNode> | undefined, predicate: (node: TreeNodeSnapshot<TNode>) => boolean): TreeNodeSnapshot<TNode> | undefined;
+/**
+ * Find all nodes matching a predicate.
+ *
+ * @param snapshot - The root tree snapshot
+ * @param predicate - Function to test each node
+ * @returns Array of matching node snapshots
+ */
+declare function findNodes<TNode extends AnyTreeNodePrimitive>(snapshot: TreeNodeSnapshot<TNode> | undefined, predicate: (node: TreeNodeSnapshot<TNode>) => boolean): readonly TreeNodeSnapshot<TNode>[];
+/**
+ * Get the depth of a specific node (0 = root).
+ *
+ * @param snapshot - The root tree snapshot
+ * @param nodeId - The ID of the node
+ * @returns The depth, or -1 if not found
+ */
+declare function getNodeDepth<TNode extends AnyTreeNodePrimitive>(snapshot: TreeNodeSnapshot<TNode> | undefined, nodeId: string): number;
+/**
+ * Check if one node is an ancestor of another.
+ *
+ * @param snapshot - The root tree snapshot
+ * @param ancestorId - Potential ancestor node ID
+ * @param descendantId - Potential descendant node ID
+ * @returns true if ancestorId is an ancestor of descendantId
+ */
+declare function isAncestorOf<TNode extends AnyTreeNodePrimitive>(snapshot: TreeNodeSnapshot<TNode> | undefined, ancestorId: string, descendantId: string): boolean;
+/**
+ * Traverse the tree and call a visitor function for each node.
+ * Return false from visitor to stop traversal.
+ *
+ * @param snapshot - The root tree snapshot
+ * @param visitor - Function called for each node (return false to stop)
+ * @param options - Traversal options (order: 'pre' | 'post')
+ */
+declare function traverse<TNode extends AnyTreeNodePrimitive>(snapshot: TreeNodeSnapshot<TNode> | undefined, visitor: (node: TreeNodeSnapshot<TNode>, depth: number) => void | false, options?: TraverseOptions): void;
+/**
+ * Flatten the tree into an array with parent information.
+ *
+ * @param snapshot - The root tree snapshot
+ * @returns Array of { node, parentId, depth } objects
+ */
+declare function flattenTree<TNode extends AnyTreeNodePrimitive>(snapshot: TreeNodeSnapshot<TNode> | undefined): readonly FlattenedNode<TNode>[];
+/**
+ * Map over all nodes in the tree, transforming each node's data.
+ * Preserves tree structure while transforming node content.
+ *
+ * @param snapshot - The root tree snapshot
+ * @param mapper - Function to transform each node
+ * @returns New tree structure with transformed nodes, or undefined
+ */
+declare function mapTree<TNode extends AnyTreeNodePrimitive, R>(snapshot: TreeNodeSnapshot<TNode> | undefined, mapper: (node: TreeNodeSnapshot<TNode>, depth: number) => R): {
+  value: R;
+  children: ReturnType<typeof mapTree<TNode, R>>[];
+} | undefined;
+/**
+ * Build a lookup map from node type strings to their TreeNodePrimitive definitions.
+ * Useful for resolving snapshot node types back to their schema definitions.
+ *
+ * @param tree - The TreePrimitive to analyze
+ * @returns Map from type string to TreeNodePrimitive
+ *
+ * @example
+ * ```ts
+ * const typeMap = buildNodeTypeMap(fileTree);
+ * const folderPrimitive = typeMap.get("folder"); // FolderNode
+ * ```
+ */
+declare function buildNodeTypeMap<TRoot extends AnyTreeNodePrimitive>(tree: TreePrimitive<TRoot>): Map<string, AnyTreeNodePrimitive>;
+/**
+ * Get the TreeNodePrimitive definition for a snapshot node.
+ * Requires the tree schema to resolve the type string to its primitive.
+ *
+ * @param tree - The TreePrimitive schema
+ * @param snapshot - The node snapshot to get the primitive for
+ * @returns The TreeNodePrimitive, or undefined if not found
+ *
+ * @example
+ * ```ts
+ * const node = findNodeById(treeSnapshot, "some-id");
+ * const primitive = getNodePrimitive(fileTree, node);
+ * // primitive is FolderNode or FileNode depending on node.type
+ * ```
+ */
+declare function getNodePrimitive<TRoot extends AnyTreeNodePrimitive>(tree: TreePrimitive<TRoot>, snapshot: TreeNodeSnapshot<AnyTreeNodePrimitive>): AnyTreeNodePrimitive | undefined;
+/**
+ * Get the allowed child types for a snapshot node.
+ * Combines schema lookup with the node's allowed children.
+ *
+ * @param tree - The TreePrimitive schema
+ * @param snapshot - The node snapshot to get allowed children for
+ * @returns Array of allowed child TreeNodePrimitives, or empty array if not found
+ *
+ * @example
+ * ```ts
+ * const node = findNodeById(treeSnapshot, "folder-id");
+ * const allowedChildren = getAllowedChildTypesForNode(fileTree, node);
+ * // Returns [FolderNode, FileNode] if the folder can contain both
+ * ```
+ */
+declare function getAllowedChildTypesForNode<TRoot extends AnyTreeNodePrimitive>(tree: TreePrimitive<TRoot>, snapshot: TreeNodeSnapshot<AnyTreeNodePrimitive>): readonly AnyTreeNodePrimitive[];
+/**
+ * Check if a child type is allowed for a specific snapshot node.
+ *
+ * @param tree - The TreePrimitive schema
+ * @param parentSnapshot - The parent node snapshot
+ * @param childTypeName - The type string of the potential child
+ * @returns true if the child type is allowed
+ *
+ * @example
+ * ```ts
+ * const folder = findNodeById(treeSnapshot, "folder-id");
+ * canAddChildType(fileTree, folder, "file"); // true
+ * canAddChildType(fileTree, folder, "unknown"); // false
+ * ```
+ */
+declare function canAddChildType<TRoot extends AnyTreeNodePrimitive>(tree: TreePrimitive<TRoot>, parentSnapshot: TreeNodeSnapshot<AnyTreeNodePrimitive>, childTypeName: string): boolean;
+/**
+ * Get all allowed child node types for a specific node type.
+ *
+ * @param nodeType - The TreeNodePrimitive to get children for
+ * @returns Array of allowed child TreeNodePrimitives
+ *
+ * @example
+ * ```ts
+ * const FolderNode = TreeNode("folder", { ... });
+ * const FileNode = TreeNode("file", { ... });
+ *
+ * // Get allowed children for FolderNode
+ * const allowedChildren = getAllowedChildTypes(FolderNode);
+ * // Returns [FolderNode, FileNode] if folder can contain both
+ * ```
+ */
+declare function getAllowedChildTypes<TNode extends AnyTreeNodePrimitive>(nodeType: TNode): readonly AnyTreeNodePrimitive[];
+/**
+ * Get all unique node types reachable in a tree schema.
+ * Recursively traverses the tree structure starting from the root.
+ *
+ * @param tree - The TreePrimitive to analyze
+ * @returns Array of all unique TreeNodePrimitives in the tree schema
+ *
+ * @example
+ * ```ts
+ * const fileTree = Tree({ root: FolderNode });
+ * const allNodeTypes = getAllNodeTypes(fileTree);
+ * // Returns [FolderNode, FileNode] - all possible node types
+ * ```
+ */
+declare function getAllNodeTypes<TRoot extends AnyTreeNodePrimitive>(tree: TreePrimitive<TRoot>): readonly AnyTreeNodePrimitive[];
+/**
+ * Get the node type primitive by its type string from a tree schema.
+ *
+ * @param tree - The TreePrimitive to search
+ * @param typeName - The type string to find (e.g., "folder", "file")
+ * @returns The matching TreeNodePrimitive, or undefined if not found
+ *
+ * @example
+ * ```ts
+ * const fileTree = Tree({ root: FolderNode });
+ * const folderType = getNodeTypeByName(fileTree, "folder");
+ * // Returns FolderNode
+ * ```
+ */
+declare function getNodeTypeByName<TRoot extends AnyTreeNodePrimitive>(tree: TreePrimitive<TRoot>, typeName: string): AnyTreeNodePrimitive | undefined;
+/**
+ * Check if a child type is allowed under a parent type.
+ *
+ * @param parentType - The parent TreeNodePrimitive
+ * @param childTypeName - The type string of the potential child
+ * @returns true if the child type is allowed
+ *
+ * @example
+ * ```ts
+ * isChildTypeAllowed(FolderNode, "file"); // true if folder can contain files
+ * isChildTypeAllowed(FileNode, "folder"); // false - files can't have children
+ * ```
+ */
+declare function isChildTypeAllowed(parentType: AnyTreeNodePrimitive, childTypeName: string): boolean;
+//#endregion
+export { tree_helpers_d_exports };
+//# sourceMappingURL=tree-helpers.d.cts.map

package/dist/utils/tree-helpers.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree-helpers.d.cts","names":[],"sources":["../../src/utils/tree-helpers.ts"],"sourcesContent":[],"mappings":"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"}

package/dist/utils/tree-helpers.d.mts

@@ -0,0 +1,280 @@
+import { AnyTreeNodePrimitive } from "../primitives/TreeNode.mjs";
+import { TreeNodeSnapshot, TreePrimitive } from "../primitives/Tree.mjs";
+
+//#region src/utils/tree-helpers.d.ts
+declare namespace tree_helpers_d_exports {
+  export { FlattenedNode, NodeSearchResult, ParentSearchResult, TraverseOptions, buildNodeTypeMap, canAddChildType, findNode, findNodeById, findNodeWithPath, findNodes, flattenTree, getAllNodeTypes, getAllowedChildTypes, getAllowedChildTypesForNode, getAncestors, getDescendants, getNodeDepth, getNodePrimitive, getNodeTypeByName, getParent, getSiblings, getSubtree, isAncestorOf, isChildTypeAllowed, mapTree, traverse };
+}
+/**
+ * Result of finding a node with path information.
+ */
+interface NodeSearchResult<TNode extends AnyTreeNodePrimitive> {
+  readonly node: TreeNodeSnapshot<TNode>;
+  readonly path: readonly string[];
+  readonly depth: number;
+}
+/**
+ * Result of finding a parent node.
+ */
+interface ParentSearchResult<TNode extends AnyTreeNodePrimitive> {
+  readonly parent: TreeNodeSnapshot<TNode>;
+  readonly childIndex: number;
+}
+/**
+ * Flattened node with parent information.
+ */
+interface FlattenedNode<TNode extends AnyTreeNodePrimitive> {
+  readonly node: TreeNodeSnapshot<TNode>;
+  readonly parentId: string | null;
+  readonly depth: number;
+}
+/**
+ * Options for tree traversal.
+ */
+interface TraverseOptions {
+  readonly order?: "pre" | "post";
+}
+/**
+ * Find a node by ID in a tree snapshot.
+ *
+ * @param snapshot - The root tree snapshot
+ * @param id - The node ID to find
+ * @returns The node snapshot if found, undefined otherwise
+ */
+declare function findNodeById<TNode extends AnyTreeNodePrimitive>(snapshot: TreeNodeSnapshot<TNode> | undefined, id: string): TreeNodeSnapshot<TNode> | undefined;
+/**
+ * Find a node by ID with full path information.
+ *
+ * @param snapshot - The root tree snapshot
+ * @param id - The node ID to find
+ * @returns NodeSearchResult with node, path, and depth, or undefined if not found
+ */
+declare function findNodeWithPath<TNode extends AnyTreeNodePrimitive>(snapshot: TreeNodeSnapshot<TNode> | undefined, id: string): NodeSearchResult<TNode> | undefined;
+/**
+ * Get the parent node of a given node ID.
+ *
+ * @param snapshot - The root tree snapshot
+ * @param nodeId - The ID of the node whose parent we want
+ * @returns ParentSearchResult with parent node and child index, or undefined
+ */
+declare function getParent<TNode extends AnyTreeNodePrimitive>(snapshot: TreeNodeSnapshot<TNode> | undefined, nodeId: string): ParentSearchResult<TNode> | undefined;
+/**
+ * Get a subtree rooted at a specific node ID.
+ *
+ * @param snapshot - The root tree snapshot
+ * @param nodeId - The ID of the node to use as new root
+ * @returns The subtree snapshot, or undefined if node not found
+ */
+declare function getSubtree<TNode extends AnyTreeNodePrimitive>(snapshot: TreeNodeSnapshot<TNode> | undefined, nodeId: string): TreeNodeSnapshot<TNode> | undefined;
+/**
+ * Get all ancestor nodes from a node up to the root.
+ *
+ * @param snapshot - The root tree snapshot
+ * @param nodeId - The ID of the node
+ * @returns Array of ancestor snapshots from immediate parent to root, or empty array
+ */
+declare function getAncestors<TNode extends AnyTreeNodePrimitive>(snapshot: TreeNodeSnapshot<TNode> | undefined, nodeId: string): readonly TreeNodeSnapshot<TNode>[];
+/**
+ * Get all descendant nodes of a given node (flat array).
+ *
+ * @param snapshot - The root tree snapshot
+ * @param nodeId - The ID of the node (if undefined, returns all descendants of root)
+ * @returns Flat array of all descendant node snapshots
+ */
+declare function getDescendants<TNode extends AnyTreeNodePrimitive>(snapshot: TreeNodeSnapshot<TNode> | undefined, nodeId?: string): readonly TreeNodeSnapshot<TNode>[];
+/**
+ * Get siblings of a node (nodes with the same parent).
+ *
+ * @param snapshot - The root tree snapshot
+ * @param nodeId - The ID of the node
+ * @param includeSelf - Whether to include the node itself (default: false)
+ * @returns Array of sibling snapshots
+ */
+declare function getSiblings<TNode extends AnyTreeNodePrimitive>(snapshot: TreeNodeSnapshot<TNode> | undefined, nodeId: string, includeSelf?: boolean): readonly TreeNodeSnapshot<TNode>[];
+/**
+ * Find the first node matching a predicate.
+ *
+ * @param snapshot - The root tree snapshot
+ * @param predicate - Function to test each node
+ * @returns First matching node snapshot, or undefined
+ */
+declare function findNode<TNode extends AnyTreeNodePrimitive>(snapshot: TreeNodeSnapshot<TNode> | undefined, predicate: (node: TreeNodeSnapshot<TNode>) => boolean): TreeNodeSnapshot<TNode> | undefined;
+/**
+ * Find all nodes matching a predicate.
+ *
+ * @param snapshot - The root tree snapshot
+ * @param predicate - Function to test each node
+ * @returns Array of matching node snapshots
+ */
+declare function findNodes<TNode extends AnyTreeNodePrimitive>(snapshot: TreeNodeSnapshot<TNode> | undefined, predicate: (node: TreeNodeSnapshot<TNode>) => boolean): readonly TreeNodeSnapshot<TNode>[];
+/**
+ * Get the depth of a specific node (0 = root).
+ *
+ * @param snapshot - The root tree snapshot
+ * @param nodeId - The ID of the node
+ * @returns The depth, or -1 if not found
+ */
+declare function getNodeDepth<TNode extends AnyTreeNodePrimitive>(snapshot: TreeNodeSnapshot<TNode> | undefined, nodeId: string): number;
+/**
+ * Check if one node is an ancestor of another.
+ *
+ * @param snapshot - The root tree snapshot
+ * @param ancestorId - Potential ancestor node ID
+ * @param descendantId - Potential descendant node ID
+ * @returns true if ancestorId is an ancestor of descendantId
+ */
+declare function isAncestorOf<TNode extends AnyTreeNodePrimitive>(snapshot: TreeNodeSnapshot<TNode> | undefined, ancestorId: string, descendantId: string): boolean;
+/**
+ * Traverse the tree and call a visitor function for each node.
+ * Return false from visitor to stop traversal.
+ *
+ * @param snapshot - The root tree snapshot
+ * @param visitor - Function called for each node (return false to stop)
+ * @param options - Traversal options (order: 'pre' | 'post')
+ */
+declare function traverse<TNode extends AnyTreeNodePrimitive>(snapshot: TreeNodeSnapshot<TNode> | undefined, visitor: (node: TreeNodeSnapshot<TNode>, depth: number) => void | false, options?: TraverseOptions): void;
+/**
+ * Flatten the tree into an array with parent information.
+ *
+ * @param snapshot - The root tree snapshot
+ * @returns Array of { node, parentId, depth } objects
+ */
+declare function flattenTree<TNode extends AnyTreeNodePrimitive>(snapshot: TreeNodeSnapshot<TNode> | undefined): readonly FlattenedNode<TNode>[];
+/**
+ * Map over all nodes in the tree, transforming each node's data.
+ * Preserves tree structure while transforming node content.
+ *
+ * @param snapshot - The root tree snapshot
+ * @param mapper - Function to transform each node
+ * @returns New tree structure with transformed nodes, or undefined
+ */
+declare function mapTree<TNode extends AnyTreeNodePrimitive, R>(snapshot: TreeNodeSnapshot<TNode> | undefined, mapper: (node: TreeNodeSnapshot<TNode>, depth: number) => R): {
+  value: R;
+  children: ReturnType<typeof mapTree<TNode, R>>[];
+} | undefined;
+/**
+ * Build a lookup map from node type strings to their TreeNodePrimitive definitions.
+ * Useful for resolving snapshot node types back to their schema definitions.
+ *
+ * @param tree - The TreePrimitive to analyze
+ * @returns Map from type string to TreeNodePrimitive
+ *
+ * @example
+ * ```ts
+ * const typeMap = buildNodeTypeMap(fileTree);
+ * const folderPrimitive = typeMap.get("folder"); // FolderNode
+ * ```
+ */
+declare function buildNodeTypeMap<TRoot extends AnyTreeNodePrimitive>(tree: TreePrimitive<TRoot>): Map<string, AnyTreeNodePrimitive>;
+/**
+ * Get the TreeNodePrimitive definition for a snapshot node.
+ * Requires the tree schema to resolve the type string to its primitive.
+ *
+ * @param tree - The TreePrimitive schema
+ * @param snapshot - The node snapshot to get the primitive for
+ * @returns The TreeNodePrimitive, or undefined if not found
+ *
+ * @example
+ * ```ts
+ * const node = findNodeById(treeSnapshot, "some-id");
+ * const primitive = getNodePrimitive(fileTree, node);
+ * // primitive is FolderNode or FileNode depending on node.type
+ * ```
+ */
+declare function getNodePrimitive<TRoot extends AnyTreeNodePrimitive>(tree: TreePrimitive<TRoot>, snapshot: TreeNodeSnapshot<AnyTreeNodePrimitive>): AnyTreeNodePrimitive | undefined;
+/**
+ * Get the allowed child types for a snapshot node.
+ * Combines schema lookup with the node's allowed children.
+ *
+ * @param tree - The TreePrimitive schema
+ * @param snapshot - The node snapshot to get allowed children for
+ * @returns Array of allowed child TreeNodePrimitives, or empty array if not found
+ *
+ * @example
+ * ```ts
+ * const node = findNodeById(treeSnapshot, "folder-id");
+ * const allowedChildren = getAllowedChildTypesForNode(fileTree, node);
+ * // Returns [FolderNode, FileNode] if the folder can contain both
+ * ```
+ */
+declare function getAllowedChildTypesForNode<TRoot extends AnyTreeNodePrimitive>(tree: TreePrimitive<TRoot>, snapshot: TreeNodeSnapshot<AnyTreeNodePrimitive>): readonly AnyTreeNodePrimitive[];
+/**
+ * Check if a child type is allowed for a specific snapshot node.
+ *
+ * @param tree - The TreePrimitive schema
+ * @param parentSnapshot - The parent node snapshot
+ * @param childTypeName - The type string of the potential child
+ * @returns true if the child type is allowed
+ *
+ * @example
+ * ```ts
+ * const folder = findNodeById(treeSnapshot, "folder-id");
+ * canAddChildType(fileTree, folder, "file"); // true
+ * canAddChildType(fileTree, folder, "unknown"); // false
+ * ```
+ */
+declare function canAddChildType<TRoot extends AnyTreeNodePrimitive>(tree: TreePrimitive<TRoot>, parentSnapshot: TreeNodeSnapshot<AnyTreeNodePrimitive>, childTypeName: string): boolean;
+/**
+ * Get all allowed child node types for a specific node type.
+ *
+ * @param nodeType - The TreeNodePrimitive to get children for
+ * @returns Array of allowed child TreeNodePrimitives
+ *
+ * @example
+ * ```ts
+ * const FolderNode = TreeNode("folder", { ... });
+ * const FileNode = TreeNode("file", { ... });
+ *
+ * // Get allowed children for FolderNode
+ * const allowedChildren = getAllowedChildTypes(FolderNode);
+ * // Returns [FolderNode, FileNode] if folder can contain both
+ * ```
+ */
+declare function getAllowedChildTypes<TNode extends AnyTreeNodePrimitive>(nodeType: TNode): readonly AnyTreeNodePrimitive[];
+/**
+ * Get all unique node types reachable in a tree schema.
+ * Recursively traverses the tree structure starting from the root.
+ *
+ * @param tree - The TreePrimitive to analyze
+ * @returns Array of all unique TreeNodePrimitives in the tree schema
+ *
+ * @example
+ * ```ts
+ * const fileTree = Tree({ root: FolderNode });
+ * const allNodeTypes = getAllNodeTypes(fileTree);
+ * // Returns [FolderNode, FileNode] - all possible node types
+ * ```
+ */
+declare function getAllNodeTypes<TRoot extends AnyTreeNodePrimitive>(tree: TreePrimitive<TRoot>): readonly AnyTreeNodePrimitive[];
+/**
+ * Get the node type primitive by its type string from a tree schema.
+ *
+ * @param tree - The TreePrimitive to search
+ * @param typeName - The type string to find (e.g., "folder", "file")
+ * @returns The matching TreeNodePrimitive, or undefined if not found
+ *
+ * @example
+ * ```ts
+ * const fileTree = Tree({ root: FolderNode });
+ * const folderType = getNodeTypeByName(fileTree, "folder");
+ * // Returns FolderNode
+ * ```
+ */
+declare function getNodeTypeByName<TRoot extends AnyTreeNodePrimitive>(tree: TreePrimitive<TRoot>, typeName: string): AnyTreeNodePrimitive | undefined;
+/**
+ * Check if a child type is allowed under a parent type.
+ *
+ * @param parentType - The parent TreeNodePrimitive
+ * @param childTypeName - The type string of the potential child
+ * @returns true if the child type is allowed
+ *
+ * @example
+ * ```ts
+ * isChildTypeAllowed(FolderNode, "file"); // true if folder can contain files
+ * isChildTypeAllowed(FileNode, "folder"); // false - files can't have children
+ * ```
+ */
+declare function isChildTypeAllowed(parentType: AnyTreeNodePrimitive, childTypeName: string): boolean;
+//#endregion
+export { tree_helpers_d_exports };
+//# sourceMappingURL=tree-helpers.d.mts.map

package/dist/utils/tree-helpers.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree-helpers.d.mts","names":[],"sources":["../../src/utils/tree-helpers.ts"],"sourcesContent":[],"mappings":"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"}