@herb-tools/core 0.5.0 → 0.6.1

package/src/node-type-guards.ts

@@ -0,0 +1,878 @@
+// NOTE: This file is generated by the templates/template.rb script and should not
+// be modified manually. See /Users/marcoroth/Development/herb-release-0.6.1/templates/javascript/packages/core/src/node-type-guards.ts.erb
+
+import type { Node, NodeType, ERBNode } from "./nodes.js"
+
+import { Token } from "./token.js"
+import { ParseResult } from "./parse-result.js"
+
+import {
+  DocumentNode,
+  LiteralNode,
+  HTMLOpenTagNode,
+  HTMLCloseTagNode,
+  HTMLElementNode,
+  HTMLAttributeValueNode,
+  HTMLAttributeNameNode,
+  HTMLAttributeNode,
+  HTMLTextNode,
+  HTMLCommentNode,
+  HTMLDoctypeNode,
+  XMLDeclarationNode,
+  CDATANode,
+  WhitespaceNode,
+  ERBContentNode,
+  ERBEndNode,
+  ERBElseNode,
+  ERBIfNode,
+  ERBBlockNode,
+  ERBWhenNode,
+  ERBCaseNode,
+  ERBCaseMatchNode,
+  ERBWhileNode,
+  ERBUntilNode,
+  ERBForNode,
+  ERBRescueNode,
+  ERBEnsureNode,
+  ERBBeginNode,
+  ERBUnlessNode,
+  ERBYieldNode,
+  ERBInNode,
+} from "./nodes.js"
+
+/**
+ * Type guard functions for AST nodes.
+ * These functions provide type checking by combining both instanceof
+ * checks and type string comparisons for maximum reliability across different
+ * runtime scenarios (e.g., serialized/deserialized nodes).
+ */
+
+/**
+ * Checks if a node is a DocumentNode
+ */
+export function isDocumentNode(node: Node): node is DocumentNode {
+  return node instanceof DocumentNode || node.type === "AST_DOCUMENT_NODE" || (node.constructor as any).type === "AST_DOCUMENT_NODE"
+}
+
+/**
+ * Checks if a node is a LiteralNode
+ */
+export function isLiteralNode(node: Node): node is LiteralNode {
+  return node instanceof LiteralNode || node.type === "AST_LITERAL_NODE" || (node.constructor as any).type === "AST_LITERAL_NODE"
+}
+
+/**
+ * Checks if a node is a HTMLOpenTagNode
+ */
+export function isHTMLOpenTagNode(node: Node): node is HTMLOpenTagNode {
+  return node instanceof HTMLOpenTagNode || node.type === "AST_HTML_OPEN_TAG_NODE" || (node.constructor as any).type === "AST_HTML_OPEN_TAG_NODE"
+}
+
+/**
+ * Checks if a node is a HTMLCloseTagNode
+ */
+export function isHTMLCloseTagNode(node: Node): node is HTMLCloseTagNode {
+  return node instanceof HTMLCloseTagNode || node.type === "AST_HTML_CLOSE_TAG_NODE" || (node.constructor as any).type === "AST_HTML_CLOSE_TAG_NODE"
+}
+
+/**
+ * Checks if a node is a HTMLElementNode
+ */
+export function isHTMLElementNode(node: Node): node is HTMLElementNode {
+  return node instanceof HTMLElementNode || node.type === "AST_HTML_ELEMENT_NODE" || (node.constructor as any).type === "AST_HTML_ELEMENT_NODE"
+}
+
+/**
+ * Checks if a node is a HTMLAttributeValueNode
+ */
+export function isHTMLAttributeValueNode(node: Node): node is HTMLAttributeValueNode {
+  return node instanceof HTMLAttributeValueNode || node.type === "AST_HTML_ATTRIBUTE_VALUE_NODE" || (node.constructor as any).type === "AST_HTML_ATTRIBUTE_VALUE_NODE"
+}
+
+/**
+ * Checks if a node is a HTMLAttributeNameNode
+ */
+export function isHTMLAttributeNameNode(node: Node): node is HTMLAttributeNameNode {
+  return node instanceof HTMLAttributeNameNode || node.type === "AST_HTML_ATTRIBUTE_NAME_NODE" || (node.constructor as any).type === "AST_HTML_ATTRIBUTE_NAME_NODE"
+}
+
+/**
+ * Checks if a node is a HTMLAttributeNode
+ */
+export function isHTMLAttributeNode(node: Node): node is HTMLAttributeNode {
+  return node instanceof HTMLAttributeNode || node.type === "AST_HTML_ATTRIBUTE_NODE" || (node.constructor as any).type === "AST_HTML_ATTRIBUTE_NODE"
+}
+
+/**
+ * Checks if a node is a HTMLTextNode
+ */
+export function isHTMLTextNode(node: Node): node is HTMLTextNode {
+  return node instanceof HTMLTextNode || node.type === "AST_HTML_TEXT_NODE" || (node.constructor as any).type === "AST_HTML_TEXT_NODE"
+}
+
+/**
+ * Checks if a node is a HTMLCommentNode
+ */
+export function isHTMLCommentNode(node: Node): node is HTMLCommentNode {
+  return node instanceof HTMLCommentNode || node.type === "AST_HTML_COMMENT_NODE" || (node.constructor as any).type === "AST_HTML_COMMENT_NODE"
+}
+
+/**
+ * Checks if a node is a HTMLDoctypeNode
+ */
+export function isHTMLDoctypeNode(node: Node): node is HTMLDoctypeNode {
+  return node instanceof HTMLDoctypeNode || node.type === "AST_HTML_DOCTYPE_NODE" || (node.constructor as any).type === "AST_HTML_DOCTYPE_NODE"
+}
+
+/**
+ * Checks if a node is a XMLDeclarationNode
+ */
+export function isXMLDeclarationNode(node: Node): node is XMLDeclarationNode {
+  return node instanceof XMLDeclarationNode || node.type === "AST_XML_DECLARATION_NODE" || (node.constructor as any).type === "AST_XML_DECLARATION_NODE"
+}
+
+/**
+ * Checks if a node is a CDATANode
+ */
+export function isCDATANode(node: Node): node is CDATANode {
+  return node instanceof CDATANode || node.type === "AST_CDATA_NODE" || (node.constructor as any).type === "AST_CDATA_NODE"
+}
+
+/**
+ * Checks if a node is a WhitespaceNode
+ */
+export function isWhitespaceNode(node: Node): node is WhitespaceNode {
+  return node instanceof WhitespaceNode || node.type === "AST_WHITESPACE_NODE" || (node.constructor as any).type === "AST_WHITESPACE_NODE"
+}
+
+/**
+ * Checks if a node is a ERBContentNode
+ */
+export function isERBContentNode(node: Node): node is ERBContentNode {
+  return node instanceof ERBContentNode || node.type === "AST_ERB_CONTENT_NODE" || (node.constructor as any).type === "AST_ERB_CONTENT_NODE"
+}
+
+/**
+ * Checks if a node is a ERBEndNode
+ */
+export function isERBEndNode(node: Node): node is ERBEndNode {
+  return node instanceof ERBEndNode || node.type === "AST_ERB_END_NODE" || (node.constructor as any).type === "AST_ERB_END_NODE"
+}
+
+/**
+ * Checks if a node is a ERBElseNode
+ */
+export function isERBElseNode(node: Node): node is ERBElseNode {
+  return node instanceof ERBElseNode || node.type === "AST_ERB_ELSE_NODE" || (node.constructor as any).type === "AST_ERB_ELSE_NODE"
+}
+
+/**
+ * Checks if a node is a ERBIfNode
+ */
+export function isERBIfNode(node: Node): node is ERBIfNode {
+  return node instanceof ERBIfNode || node.type === "AST_ERB_IF_NODE" || (node.constructor as any).type === "AST_ERB_IF_NODE"
+}
+
+/**
+ * Checks if a node is a ERBBlockNode
+ */
+export function isERBBlockNode(node: Node): node is ERBBlockNode {
+  return node instanceof ERBBlockNode || node.type === "AST_ERB_BLOCK_NODE" || (node.constructor as any).type === "AST_ERB_BLOCK_NODE"
+}
+
+/**
+ * Checks if a node is a ERBWhenNode
+ */
+export function isERBWhenNode(node: Node): node is ERBWhenNode {
+  return node instanceof ERBWhenNode || node.type === "AST_ERB_WHEN_NODE" || (node.constructor as any).type === "AST_ERB_WHEN_NODE"
+}
+
+/**
+ * Checks if a node is a ERBCaseNode
+ */
+export function isERBCaseNode(node: Node): node is ERBCaseNode {
+  return node instanceof ERBCaseNode || node.type === "AST_ERB_CASE_NODE" || (node.constructor as any).type === "AST_ERB_CASE_NODE"
+}
+
+/**
+ * Checks if a node is a ERBCaseMatchNode
+ */
+export function isERBCaseMatchNode(node: Node): node is ERBCaseMatchNode {
+  return node instanceof ERBCaseMatchNode || node.type === "AST_ERB_CASE_MATCH_NODE" || (node.constructor as any).type === "AST_ERB_CASE_MATCH_NODE"
+}
+
+/**
+ * Checks if a node is a ERBWhileNode
+ */
+export function isERBWhileNode(node: Node): node is ERBWhileNode {
+  return node instanceof ERBWhileNode || node.type === "AST_ERB_WHILE_NODE" || (node.constructor as any).type === "AST_ERB_WHILE_NODE"
+}
+
+/**
+ * Checks if a node is a ERBUntilNode
+ */
+export function isERBUntilNode(node: Node): node is ERBUntilNode {
+  return node instanceof ERBUntilNode || node.type === "AST_ERB_UNTIL_NODE" || (node.constructor as any).type === "AST_ERB_UNTIL_NODE"
+}
+
+/**
+ * Checks if a node is a ERBForNode
+ */
+export function isERBForNode(node: Node): node is ERBForNode {
+  return node instanceof ERBForNode || node.type === "AST_ERB_FOR_NODE" || (node.constructor as any).type === "AST_ERB_FOR_NODE"
+}
+
+/**
+ * Checks if a node is a ERBRescueNode
+ */
+export function isERBRescueNode(node: Node): node is ERBRescueNode {
+  return node instanceof ERBRescueNode || node.type === "AST_ERB_RESCUE_NODE" || (node.constructor as any).type === "AST_ERB_RESCUE_NODE"
+}
+
+/**
+ * Checks if a node is a ERBEnsureNode
+ */
+export function isERBEnsureNode(node: Node): node is ERBEnsureNode {
+  return node instanceof ERBEnsureNode || node.type === "AST_ERB_ENSURE_NODE" || (node.constructor as any).type === "AST_ERB_ENSURE_NODE"
+}
+
+/**
+ * Checks if a node is a ERBBeginNode
+ */
+export function isERBBeginNode(node: Node): node is ERBBeginNode {
+  return node instanceof ERBBeginNode || node.type === "AST_ERB_BEGIN_NODE" || (node.constructor as any).type === "AST_ERB_BEGIN_NODE"
+}
+
+/**
+ * Checks if a node is a ERBUnlessNode
+ */
+export function isERBUnlessNode(node: Node): node is ERBUnlessNode {
+  return node instanceof ERBUnlessNode || node.type === "AST_ERB_UNLESS_NODE" || (node.constructor as any).type === "AST_ERB_UNLESS_NODE"
+}
+
+/**
+ * Checks if a node is a ERBYieldNode
+ */
+export function isERBYieldNode(node: Node): node is ERBYieldNode {
+  return node instanceof ERBYieldNode || node.type === "AST_ERB_YIELD_NODE" || (node.constructor as any).type === "AST_ERB_YIELD_NODE"
+}
+
+/**
+ * Checks if a node is a ERBInNode
+ */
+export function isERBInNode(node: Node): node is ERBInNode {
+  return node instanceof ERBInNode || node.type === "AST_ERB_IN_NODE" || (node.constructor as any).type === "AST_ERB_IN_NODE"
+}
+
+/**
+ * Convenience type guards for common node categories
+ */
+
+/**
+ * Checks if a node is any HTML node type
+ */
+export function isHTMLNode(node: Node): boolean {
+  return isHTMLOpenTagNode(node) ||
+         isHTMLCloseTagNode(node) ||
+         isHTMLElementNode(node) ||
+         isHTMLAttributeValueNode(node) ||
+         isHTMLAttributeNameNode(node) ||
+         isHTMLAttributeNode(node) ||
+         isHTMLTextNode(node) ||
+         isHTMLCommentNode(node) ||
+         isHTMLDoctypeNode(node)
+}
+
+/**
+ * Checks if a node is any ERB node type
+ */
+export function isERBNode(node: Node): node is ERBNode {
+  return isERBContentNode(node) ||
+         isERBEndNode(node) ||
+         isERBElseNode(node) ||
+         isERBIfNode(node) ||
+         isERBBlockNode(node) ||
+         isERBWhenNode(node) ||
+         isERBCaseNode(node) ||
+         isERBCaseMatchNode(node) ||
+         isERBWhileNode(node) ||
+         isERBUntilNode(node) ||
+         isERBForNode(node) ||
+         isERBRescueNode(node) ||
+         isERBEnsureNode(node) ||
+         isERBBeginNode(node) ||
+         isERBUnlessNode(node) ||
+         isERBYieldNode(node) ||
+         isERBInNode(node)
+}
+
+/**
+ * Map of node classes to their corresponding type guard functions
+ *
+ * @example
+ * const guard = NODE_TYPE_GUARDS[HTMLTextNode]
+ *
+ * if (guard(node)) {
+ *   // node is HTMLTextNode
+ * }
+ */
+export const NODE_TYPE_GUARDS = new Map<new (...args: any[]) => Node, (node: Node) => boolean>([
+  [DocumentNode, isDocumentNode],
+  [LiteralNode, isLiteralNode],
+  [HTMLOpenTagNode, isHTMLOpenTagNode],
+  [HTMLCloseTagNode, isHTMLCloseTagNode],
+  [HTMLElementNode, isHTMLElementNode],
+  [HTMLAttributeValueNode, isHTMLAttributeValueNode],
+  [HTMLAttributeNameNode, isHTMLAttributeNameNode],
+  [HTMLAttributeNode, isHTMLAttributeNode],
+  [HTMLTextNode, isHTMLTextNode],
+  [HTMLCommentNode, isHTMLCommentNode],
+  [HTMLDoctypeNode, isHTMLDoctypeNode],
+  [XMLDeclarationNode, isXMLDeclarationNode],
+  [CDATANode, isCDATANode],
+  [WhitespaceNode, isWhitespaceNode],
+  [ERBContentNode, isERBContentNode],
+  [ERBEndNode, isERBEndNode],
+  [ERBElseNode, isERBElseNode],
+  [ERBIfNode, isERBIfNode],
+  [ERBBlockNode, isERBBlockNode],
+  [ERBWhenNode, isERBWhenNode],
+  [ERBCaseNode, isERBCaseNode],
+  [ERBCaseMatchNode, isERBCaseMatchNode],
+  [ERBWhileNode, isERBWhileNode],
+  [ERBUntilNode, isERBUntilNode],
+  [ERBForNode, isERBForNode],
+  [ERBRescueNode, isERBRescueNode],
+  [ERBEnsureNode, isERBEnsureNode],
+  [ERBBeginNode, isERBBeginNode],
+  [ERBUnlessNode, isERBUnlessNode],
+  [ERBYieldNode, isERBYieldNode],
+  [ERBInNode, isERBInNode],
+])
+
+/**
+ * Map of AST node type strings to their corresponding type guard functions
+ *
+ * @example
+ * const guard = AST_TYPE_GUARDS["AST_HTML_TEXT_NODE"]
+ *
+ * if (guard(node)) {
+ *   // node is HTMLTextNode
+ * }
+ */
+export const AST_TYPE_GUARDS = new Map<NodeType, (node: Node) => boolean>([
+  ["AST_DOCUMENT_NODE", isDocumentNode],
+  ["AST_LITERAL_NODE", isLiteralNode],
+  ["AST_HTML_OPEN_TAG_NODE", isHTMLOpenTagNode],
+  ["AST_HTML_CLOSE_TAG_NODE", isHTMLCloseTagNode],
+  ["AST_HTML_ELEMENT_NODE", isHTMLElementNode],
+  ["AST_HTML_ATTRIBUTE_VALUE_NODE", isHTMLAttributeValueNode],
+  ["AST_HTML_ATTRIBUTE_NAME_NODE", isHTMLAttributeNameNode],
+  ["AST_HTML_ATTRIBUTE_NODE", isHTMLAttributeNode],
+  ["AST_HTML_TEXT_NODE", isHTMLTextNode],
+  ["AST_HTML_COMMENT_NODE", isHTMLCommentNode],
+  ["AST_HTML_DOCTYPE_NODE", isHTMLDoctypeNode],
+  ["AST_XML_DECLARATION_NODE", isXMLDeclarationNode],
+  ["AST_CDATA_NODE", isCDATANode],
+  ["AST_WHITESPACE_NODE", isWhitespaceNode],
+  ["AST_ERB_CONTENT_NODE", isERBContentNode],
+  ["AST_ERB_END_NODE", isERBEndNode],
+  ["AST_ERB_ELSE_NODE", isERBElseNode],
+  ["AST_ERB_IF_NODE", isERBIfNode],
+  ["AST_ERB_BLOCK_NODE", isERBBlockNode],
+  ["AST_ERB_WHEN_NODE", isERBWhenNode],
+  ["AST_ERB_CASE_NODE", isERBCaseNode],
+  ["AST_ERB_CASE_MATCH_NODE", isERBCaseMatchNode],
+  ["AST_ERB_WHILE_NODE", isERBWhileNode],
+  ["AST_ERB_UNTIL_NODE", isERBUntilNode],
+  ["AST_ERB_FOR_NODE", isERBForNode],
+  ["AST_ERB_RESCUE_NODE", isERBRescueNode],
+  ["AST_ERB_ENSURE_NODE", isERBEnsureNode],
+  ["AST_ERB_BEGIN_NODE", isERBBeginNode],
+  ["AST_ERB_UNLESS_NODE", isERBUnlessNode],
+  ["AST_ERB_YIELD_NODE", isERBYieldNode],
+  ["AST_ERB_IN_NODE", isERBInNode],
+])
+
+type NodeTypeToClass = {
+  "AST_DOCUMENT_NODE": DocumentNode;
+  "AST_LITERAL_NODE": LiteralNode;
+  "AST_HTML_OPEN_TAG_NODE": HTMLOpenTagNode;
+  "AST_HTML_CLOSE_TAG_NODE": HTMLCloseTagNode;
+  "AST_HTML_ELEMENT_NODE": HTMLElementNode;
+  "AST_HTML_ATTRIBUTE_VALUE_NODE": HTMLAttributeValueNode;
+  "AST_HTML_ATTRIBUTE_NAME_NODE": HTMLAttributeNameNode;
+  "AST_HTML_ATTRIBUTE_NODE": HTMLAttributeNode;
+  "AST_HTML_TEXT_NODE": HTMLTextNode;
+  "AST_HTML_COMMENT_NODE": HTMLCommentNode;
+  "AST_HTML_DOCTYPE_NODE": HTMLDoctypeNode;
+  "AST_XML_DECLARATION_NODE": XMLDeclarationNode;
+  "AST_CDATA_NODE": CDATANode;
+  "AST_WHITESPACE_NODE": WhitespaceNode;
+  "AST_ERB_CONTENT_NODE": ERBContentNode;
+  "AST_ERB_END_NODE": ERBEndNode;
+  "AST_ERB_ELSE_NODE": ERBElseNode;
+  "AST_ERB_IF_NODE": ERBIfNode;
+  "AST_ERB_BLOCK_NODE": ERBBlockNode;
+  "AST_ERB_WHEN_NODE": ERBWhenNode;
+  "AST_ERB_CASE_NODE": ERBCaseNode;
+  "AST_ERB_CASE_MATCH_NODE": ERBCaseMatchNode;
+  "AST_ERB_WHILE_NODE": ERBWhileNode;
+  "AST_ERB_UNTIL_NODE": ERBUntilNode;
+  "AST_ERB_FOR_NODE": ERBForNode;
+  "AST_ERB_RESCUE_NODE": ERBRescueNode;
+  "AST_ERB_ENSURE_NODE": ERBEnsureNode;
+  "AST_ERB_BEGIN_NODE": ERBBeginNode;
+  "AST_ERB_UNLESS_NODE": ERBUnlessNode;
+  "AST_ERB_YIELD_NODE": ERBYieldNode;
+  "AST_ERB_IN_NODE": ERBInNode;
+}
+
+type ClassToInstance<T> = T extends new (...args: any[]) => infer R ? R : never
+
+/**
+ * Checks if a node matches any of the provided type identifiers with proper type narrowing
+ * Supports AST type strings, node classes, or type guard functions
+ *
+ * @example
+ * if (isAnyOf(node, "AST_HTML_TEXT_NODE", "AST_LITERAL_NODE")) {
+ *   // node is narrowed to HTMLTextNode | LiteralNode
+ * }
+ *
+ * @example
+ * if (isAnyOf(node, HTMLTextNode, LiteralNode)) {
+ *   // node is narrowed to HTMLTextNode | LiteralNode
+ * }
+ */
+
+export function isAnyOf(node: Node, ...types: Array<NodeType | (new (...args: any[]) => Node) | ((node: Node) => boolean)>): boolean {
+  return types.some(type => {
+    if (typeof type === 'string') {
+      return isNode(node, type)
+    } else if (typeof type === 'function' && type.prototype && type.prototype.constructor === type && NODE_TYPE_GUARDS.has(type as new (...args: any[]) => Node)) {
+      return isNode(node, type as new (...args: any[]) => Node)
+    } else if (typeof type === 'function') {
+      return (type as (node: Node) => boolean)(node)
+    } else {
+      return false
+    }
+  })
+}
+
+/**
+ * Checks if a node does NOT match any of the provided type identifiers
+ * Supports AST type strings, node classes, or type guard functions
+ * This is the logical inverse of isAnyOf
+ *
+ * @example
+ * if (isNoneOf(node, "AST_HTML_TEXT_NODE", "AST_LITERAL_NODE")) {
+ *   // node is neither HTMLTextNode nor LiteralNode
+ * }
+ *
+ * @example
+ * if (isNoneOf(node, HTMLTextNode, LiteralNode)) {
+ *   // node is neither HTMLTextNode nor LiteralNode
+ * }
+ *
+ * @example
+ * if (isNoneOf(node, isHTMLTextNode, isLiteralNode)) {
+ *   // node is neither HTMLTextNode nor LiteralNode
+ * }
+ */
+export function isNoneOf(
+  node: Node,
+  ...types: Array<NodeType | (new (...args: any[]) => Node) | ((node: Node) => boolean)>
+): boolean {
+  return !isAnyOf(node, ...types)
+}
+
+/**
+ * Checks if ALL nodes in an array match any of the provided type identifiers
+ * Supports AST type strings, node classes, or type guard functions
+ * Provides type narrowing for the array when true
+ *
+ * @example
+ * if (areAllOfType(nodes, "AST_HTML_TEXT_NODE", "AST_LITERAL_NODE")) {
+ *   // nodes is narrowed to (HTMLTextNode | LiteralNode)[]
+ * }
+ *
+ * @example
+ * if (areAllOfType(nodes, HTMLTextNode, LiteralNode)) {
+ *   // nodes is narrowed to (HTMLTextNode | LiteralNode)[]
+ * }
+ *
+ * @example
+ * if (areAllOfType(nodes, isHTMLTextNode, isLiteralNode)) {
+ *   // all nodes are either HTMLTextNode or LiteralNode
+ * }
+ */
+
+export function areAllOfType<T extends NodeType[]>(
+  nodes: Node[],
+  ...types: T
+): nodes is NodeTypeToClass[T[number]][]
+
+export function areAllOfType<T extends (new (...args: any[]) => Node)[]>(
+  nodes: Node[],
+  ...types: T
+): nodes is ClassToInstance<T[number]>[]
+
+export function areAllOfType(
+  nodes: Node[],
+  ...types: Array<(node: Node) => boolean>
+): boolean
+
+export function areAllOfType(
+  nodes: Node[],
+  ...types: Array<NodeType | (new (...args: any[]) => Node) | ((node: Node) => boolean)>
+): boolean {
+  return nodes.every(node => isAnyOf(node, ...types))
+}
+
+/**
+ * Filters an array of nodes to only include nodes matching any of the provided type identifiers
+ * Supports AST type strings, node classes, or type guard functions
+ * Returns a properly typed array of the filtered nodes
+ *
+ * @example
+ * const filtered = filterNodes(nodes, "AST_HTML_TEXT_NODE", "AST_LITERAL_NODE")
+ * // filtered is typed as (HTMLTextNode | LiteralNode)[]
+ *
+ * @example
+ * const filtered = filterNodes(nodes, HTMLTextNode, LiteralNode)
+ * // filtered is typed as (HTMLTextNode | LiteralNode)[]
+ *
+ * @example
+ * const filtered = filterNodes(nodes, isHTMLTextNode, isLiteralNode)
+ * // filtered contains only HTMLTextNode or LiteralNode instances
+ *
+ * @example
+ * const filtered = filterNodes(nodes, "AST_LITERAL_NODE", HTMLTextNode, isERBContentNode)
+ * // filtered contains only LiteralNode, HTMLTextNode, or ERBContentNode instances
+ */
+
+export function filterNodes<T extends NodeType[]>(
+  nodes: Node[] | undefined | null,
+  ...types: T
+): NodeTypeToClass[T[number]][]
+
+export function filterNodes<T extends (new (...args: any[]) => Node)[]>(
+  nodes: Node[] | undefined | null,
+  ...types: T
+): ClassToInstance<T[number]>[]
+
+export function filterNodes(
+  nodes: Node[] | undefined | null,
+  ...types: Array<(node: Node) => boolean>
+): Node[]
+
+export function filterNodes(
+  nodes: Node[] | undefined | null,
+  ...types: Array<NodeType | (new (...args: any[]) => Node) | ((node: Node) => boolean)>
+): Node[] {
+  if (!nodes) return []
+
+  return nodes.filter(node => isAnyOf(node, ...types))
+}
+
+/**
+ * Checks if a node matches a specific type identifier with proper type narrowing
+ * Supports AST type strings or node classes
+ *
+ * @example
+ * if (isNode(node, "AST_HTML_TEXT_NODE")) {
+ *   // node is narrowed to HTMLTextNode
+ * }
+ *
+ * @example
+ * if (isNode(node, HTMLTextNode)) {
+ *   // node is narrowed to HTMLTextNode
+ * }
+ */
+
+export function isNode<T extends NodeType>(
+  node: Node | null | undefined,
+  type: T
+): node is NodeTypeToClass[T]
+
+export function isNode<T extends new (...args: any[]) => Node>(
+  node: Node | null | undefined,
+  type: T
+): node is ClassToInstance<T>
+
+export function isNode(
+  node: Node | null | undefined,
+  type: NodeType | (new (...args: any[]) => Node)
+): boolean {
+  if (!node) return false
+
+  if (typeof type === 'string') {
+    const guard = AST_TYPE_GUARDS.get(type)
+
+    return guard ? guard(node) : false
+  } else if (typeof type === 'function') {
+    const guard = NODE_TYPE_GUARDS.get(type as new (...args: any[]) => Node)
+
+    return guard ? guard(node) : false
+  } else {
+    return false
+  }
+}
+
+export function isToken(object: any): object is Token {
+  return (object instanceof Token) || (object?.constructor?.name === "Token" && "value" in object) || (object as any).type?.startsWith('TOKEN_')
+}
+
+export function isParseResult(object: any): object is ParseResult {
+  return (object instanceof ParseResult) || (object?.constructor?.name === "ParseResult" && "value" in object)
+}
+
+/**
+ * Checks if a node has children (contains other nodes)
+ */
+export function hasChildren(node: Node): boolean {
+  return isDocumentNode(node) ||
+         isHTMLOpenTagNode(node) ||
+         isHTMLCloseTagNode(node) ||
+         isHTMLElementNode(node) ||
+         isHTMLAttributeValueNode(node) ||
+         isHTMLAttributeNameNode(node) ||
+         isHTMLCommentNode(node) ||
+         isHTMLDoctypeNode(node) ||
+         isERBElseNode(node) ||
+         isERBIfNode(node) ||
+         isERBBlockNode(node) ||
+         isERBWhenNode(node) ||
+         isERBCaseNode(node) ||
+         isERBCaseMatchNode(node) ||
+         isERBWhileNode(node) ||
+         isERBUntilNode(node) ||
+         isERBForNode(node) ||
+         isERBRescueNode(node) ||
+         isERBEnsureNode(node) ||
+         isERBBeginNode(node) ||
+         isERBUnlessNode(node) ||
+         isERBInNode(node)
+}
+
+/**
+ * Filter functions for extracting specific node types from arrays
+ */
+
+/**
+ * Filters an array of nodes to only include DocumentNode nodes
+ */
+export function filterDocumentNodes(nodes: Node[]): DocumentNode[] {
+  return nodes.filter(isDocumentNode) as DocumentNode[]
+}
+
+/**
+ * Filters an array of nodes to only include LiteralNode nodes
+ */
+export function filterLiteralNodes(nodes: Node[]): LiteralNode[] {
+  return nodes.filter(isLiteralNode) as LiteralNode[]
+}
+
+/**
+ * Filters an array of nodes to only include HTMLOpenTagNode nodes
+ */
+export function filterHTMLOpenTagNodes(nodes: Node[]): HTMLOpenTagNode[] {
+  return nodes.filter(isHTMLOpenTagNode) as HTMLOpenTagNode[]
+}
+
+/**
+ * Filters an array of nodes to only include HTMLCloseTagNode nodes
+ */
+export function filterHTMLCloseTagNodes(nodes: Node[]): HTMLCloseTagNode[] {
+  return nodes.filter(isHTMLCloseTagNode) as HTMLCloseTagNode[]
+}
+
+/**
+ * Filters an array of nodes to only include HTMLElementNode nodes
+ */
+export function filterHTMLElementNodes(nodes: Node[]): HTMLElementNode[] {
+  return nodes.filter(isHTMLElementNode) as HTMLElementNode[]
+}
+
+/**
+ * Filters an array of nodes to only include HTMLAttributeValueNode nodes
+ */
+export function filterHTMLAttributeValueNodes(nodes: Node[]): HTMLAttributeValueNode[] {
+  return nodes.filter(isHTMLAttributeValueNode) as HTMLAttributeValueNode[]
+}
+
+/**
+ * Filters an array of nodes to only include HTMLAttributeNameNode nodes
+ */
+export function filterHTMLAttributeNameNodes(nodes: Node[]): HTMLAttributeNameNode[] {
+  return nodes.filter(isHTMLAttributeNameNode) as HTMLAttributeNameNode[]
+}
+
+/**
+ * Filters an array of nodes to only include HTMLAttributeNode nodes
+ */
+export function filterHTMLAttributeNodes(nodes: Node[]): HTMLAttributeNode[] {
+  return nodes.filter(isHTMLAttributeNode) as HTMLAttributeNode[]
+}
+
+/**
+ * Filters an array of nodes to only include HTMLTextNode nodes
+ */
+export function filterHTMLTextNodes(nodes: Node[]): HTMLTextNode[] {
+  return nodes.filter(isHTMLTextNode) as HTMLTextNode[]
+}
+
+/**
+ * Filters an array of nodes to only include HTMLCommentNode nodes
+ */
+export function filterHTMLCommentNodes(nodes: Node[]): HTMLCommentNode[] {
+  return nodes.filter(isHTMLCommentNode) as HTMLCommentNode[]
+}
+
+/**
+ * Filters an array of nodes to only include HTMLDoctypeNode nodes
+ */
+export function filterHTMLDoctypeNodes(nodes: Node[]): HTMLDoctypeNode[] {
+  return nodes.filter(isHTMLDoctypeNode) as HTMLDoctypeNode[]
+}
+
+/**
+ * Filters an array of nodes to only include XMLDeclarationNode nodes
+ */
+export function filterXMLDeclarationNodes(nodes: Node[]): XMLDeclarationNode[] {
+  return nodes.filter(isXMLDeclarationNode) as XMLDeclarationNode[]
+}
+
+/**
+ * Filters an array of nodes to only include CDATANode nodes
+ */
+export function filterCDATANodes(nodes: Node[]): CDATANode[] {
+  return nodes.filter(isCDATANode) as CDATANode[]
+}
+
+/**
+ * Filters an array of nodes to only include WhitespaceNode nodes
+ */
+export function filterWhitespaceNodes(nodes: Node[]): WhitespaceNode[] {
+  return nodes.filter(isWhitespaceNode) as WhitespaceNode[]
+}
+
+/**
+ * Filters an array of nodes to only include ERBContentNode nodes
+ */
+export function filterERBContentNodes(nodes: Node[]): ERBContentNode[] {
+  return nodes.filter(isERBContentNode) as ERBContentNode[]
+}
+
+/**
+ * Filters an array of nodes to only include ERBEndNode nodes
+ */
+export function filterERBEndNodes(nodes: Node[]): ERBEndNode[] {
+  return nodes.filter(isERBEndNode) as ERBEndNode[]
+}
+
+/**
+ * Filters an array of nodes to only include ERBElseNode nodes
+ */
+export function filterERBElseNodes(nodes: Node[]): ERBElseNode[] {
+  return nodes.filter(isERBElseNode) as ERBElseNode[]
+}
+
+/**
+ * Filters an array of nodes to only include ERBIfNode nodes
+ */
+export function filterERBIfNodes(nodes: Node[]): ERBIfNode[] {
+  return nodes.filter(isERBIfNode) as ERBIfNode[]
+}
+
+/**
+ * Filters an array of nodes to only include ERBBlockNode nodes
+ */
+export function filterERBBlockNodes(nodes: Node[]): ERBBlockNode[] {
+  return nodes.filter(isERBBlockNode) as ERBBlockNode[]
+}
+
+/**
+ * Filters an array of nodes to only include ERBWhenNode nodes
+ */
+export function filterERBWhenNodes(nodes: Node[]): ERBWhenNode[] {
+  return nodes.filter(isERBWhenNode) as ERBWhenNode[]
+}
+
+/**
+ * Filters an array of nodes to only include ERBCaseNode nodes
+ */
+export function filterERBCaseNodes(nodes: Node[]): ERBCaseNode[] {
+  return nodes.filter(isERBCaseNode) as ERBCaseNode[]
+}
+
+/**
+ * Filters an array of nodes to only include ERBCaseMatchNode nodes
+ */
+export function filterERBCaseMatchNodes(nodes: Node[]): ERBCaseMatchNode[] {
+  return nodes.filter(isERBCaseMatchNode) as ERBCaseMatchNode[]
+}
+
+/**
+ * Filters an array of nodes to only include ERBWhileNode nodes
+ */
+export function filterERBWhileNodes(nodes: Node[]): ERBWhileNode[] {
+  return nodes.filter(isERBWhileNode) as ERBWhileNode[]
+}
+
+/**
+ * Filters an array of nodes to only include ERBUntilNode nodes
+ */
+export function filterERBUntilNodes(nodes: Node[]): ERBUntilNode[] {
+  return nodes.filter(isERBUntilNode) as ERBUntilNode[]
+}
+
+/**
+ * Filters an array of nodes to only include ERBForNode nodes
+ */
+export function filterERBForNodes(nodes: Node[]): ERBForNode[] {
+  return nodes.filter(isERBForNode) as ERBForNode[]
+}
+
+/**
+ * Filters an array of nodes to only include ERBRescueNode nodes
+ */
+export function filterERBRescueNodes(nodes: Node[]): ERBRescueNode[] {
+  return nodes.filter(isERBRescueNode) as ERBRescueNode[]
+}
+
+/**
+ * Filters an array of nodes to only include ERBEnsureNode nodes
+ */
+export function filterERBEnsureNodes(nodes: Node[]): ERBEnsureNode[] {
+  return nodes.filter(isERBEnsureNode) as ERBEnsureNode[]
+}
+
+/**
+ * Filters an array of nodes to only include ERBBeginNode nodes
+ */
+export function filterERBBeginNodes(nodes: Node[]): ERBBeginNode[] {
+  return nodes.filter(isERBBeginNode) as ERBBeginNode[]
+}
+
+/**
+ * Filters an array of nodes to only include ERBUnlessNode nodes
+ */
+export function filterERBUnlessNodes(nodes: Node[]): ERBUnlessNode[] {
+  return nodes.filter(isERBUnlessNode) as ERBUnlessNode[]
+}
+
+/**
+ * Filters an array of nodes to only include ERBYieldNode nodes
+ */
+export function filterERBYieldNodes(nodes: Node[]): ERBYieldNode[] {
+  return nodes.filter(isERBYieldNode) as ERBYieldNode[]
+}
+
+/**
+ * Filters an array of nodes to only include ERBInNode nodes
+ */
+export function filterERBInNodes(nodes: Node[]): ERBInNode[] {
+  return nodes.filter(isERBInNode) as ERBInNode[]
+}
+