@eksml/xml 0.1.0

package/src/utilities/escapeRegExp.ts

@@ -0,0 +1,19 @@
+// RegExp.escape is not yet in the ES2023 lib typings
+declare global {
+  interface RegExpConstructor {
+    escape?: (s: string) => string;
+  }
+}
+
+/**
+ * Escapes special regex characters in a string so it can be safely
+ * interpolated into a `new RegExp(...)` pattern.
+ *
+ * Uses the native `RegExp.escape` when available (Node ≥ 24, Chrome ≥ 136,
+ * Firefox ≥ 134, Safari ≥ 18.2), otherwise falls back to a manual replacement.
+ * @internal
+ */
+export const escapeRegExp: (s: string) => string =
+  typeof RegExp.escape === 'function'
+    ? RegExp.escape
+    : (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');

package/src/utilities/filter.ts

@@ -0,0 +1,63 @@
+import type { TNode } from '#src/parser.ts';
+import { parse } from '#src/parser.ts';
+
+/**
+ * Filter nodes like Array.filter - returns nodes where the filter function returns true
+ * @param input - XML string or array of nodes to filter
+ * @param predicate - Filter function
+ * @param depth - Current depth in the tree (internal use)
+ * @param path - Current path in the tree (internal use)
+ * @returns Filtered array of nodes
+ */
+export function filter(
+  input: string | (TNode | string)[],
+  predicate: (
+    node: TNode,
+    index: number,
+    depth: number,
+    path: string,
+  ) => boolean,
+  depth: number = 0,
+  path: string = '',
+): TNode[] {
+  const out: TNode[] = [];
+  filterInto(
+    out,
+    typeof input === 'string' ? parse(input) : input,
+    predicate,
+    depth,
+    path,
+  );
+  return out;
+}
+
+function filterInto(
+  out: TNode[],
+  children: (TNode | string)[],
+  predicate: (
+    node: TNode,
+    index: number,
+    depth: number,
+    path: string,
+  ) => boolean,
+  depth: number,
+  path: string,
+): void {
+  for (let i = 0; i < children.length; i++) {
+    const child = children[i]!;
+    if (typeof child === 'object') {
+      if (predicate(child, i, depth, path)) {
+        out.push(child);
+      }
+      if (child.children) {
+        filterInto(
+          out,
+          child.children,
+          predicate,
+          depth + 1,
+          (path ? path + '.' : '') + i + '.' + child.tagName,
+        );
+      }
+    }
+  }
+}

package/src/utilities/getElementById.ts

@@ -0,0 +1,21 @@
+import type { TNode } from '#src/parser.ts';
+import { parse } from '#src/parser.ts';
+import { filter } from '#src/utilities/filter.ts';
+
+/**
+ * Find an element by ID attribute
+ * @param input - XML string or parsed DOM to search
+ * @param id - ID value to find
+ * @returns Found node, or undefined if not found
+ */
+export function getElementById(
+  input: string | (TNode | string)[],
+  id: string,
+): TNode | undefined {
+  if (typeof input === 'string') {
+    const out = parse(input, { attrValue: id });
+    return out[0] as TNode | undefined;
+  }
+  const matches = filter(input, (node) => node.attributes?.id === id);
+  return matches[0];
+}

package/src/utilities/getElementsByClassName.ts

@@ -0,0 +1,22 @@
+import type { TNode } from '#src/parser.ts';
+import { parse } from '#src/parser.ts';
+import { escapeRegExp } from '#src/utilities/escapeRegExp.ts';
+import { filter } from '#src/utilities/filter.ts';
+
+/**
+ * Find elements by class name
+ * @param input - XML string or parsed DOM to search
+ * @param className - Class name to find
+ * @returns Found nodes
+ */
+export function getElementsByClassName(
+  input: string | (TNode | string)[],
+  className: string,
+): TNode[] {
+  const dom = typeof input === 'string' ? parse(input) : input;
+  const re = new RegExp('(?:^|\\s)' + escapeRegExp(className) + '(?:\\s|$)');
+  return filter(dom, (node) => {
+    const cls = node.attributes?.class;
+    return cls != null && re.test(cls);
+  });
+}

package/src/utilities/htmlConstants.ts

@@ -0,0 +1,26 @@
+/**
+ * Standard HTML void elements that are self-closing and never have children.
+ * Used as the default for `selfClosingTags` when `html: true`.
+ */
+export const HTML_VOID_ELEMENTS = [
+  'area',
+  'base',
+  'br',
+  'col',
+  'embed',
+  'hr',
+  'img',
+  'input',
+  'link',
+  'meta',
+  'param',
+  'source',
+  'track',
+  'wbr',
+];
+
+/**
+ * HTML elements whose content is raw text (not parsed as markup).
+ * Used as the default for `rawContentTags` when `html: true`.
+ */
+export const HTML_RAW_CONTENT_TAGS = ['script', 'style'];

package/src/utilities/index.ts

@@ -0,0 +1,7 @@
+export * from '#src/utilities/htmlConstants.ts';
+export * from '#src/utilities/filter.ts';
+export * from '#src/utilities/toContentString.ts';
+export * from '#src/utilities/getElementById.ts';
+export * from '#src/utilities/getElementsByClassName.ts';
+export * from '#src/utilities/isTextNode.ts';
+export * from '#src/utilities/isElementNode.ts';

package/src/utilities/isElementNode.ts

@@ -0,0 +1,19 @@
+import type { TNode } from '#src/parser.ts';
+
+/**
+ * Type guard to check if a node is an element node (TNode object).
+ * Useful for filtering and type narrowing when working with mixed node arrays.
+ *
+ * @param node - The node to check
+ * @returns True if the node is a TNode (element node)
+ * @example
+ * const parsed = parse('<div>Hello <span>World</span></div>');
+ * parsed[0].children.forEach(child => {
+ *   if (isElementNode(child)) {
+ *     console.log('Element:', child.tagName);
+ *   }
+ * });
+ */
+export function isElementNode(node: TNode | string): node is TNode {
+  return typeof node === 'object' && node !== null && 'tagName' in node;
+}

package/src/utilities/isTextNode.ts

@@ -0,0 +1,19 @@
+import type { TNode } from '#src/parser.ts';
+
+/**
+ * Type guard to check if a node is a text node (string).
+ * Useful for filtering and type narrowing when working with mixed node arrays.
+ *
+ * @param node - The node to check
+ * @returns True if the node is a string (text node)
+ * @example
+ * const parsed = parse('<div>Hello <span>World</span></div>');
+ * parsed[0].children.forEach(child => {
+ *   if (isTextNode(child)) {
+ *     console.log('Text:', child);
+ *   }
+ * });
+ */
+export function isTextNode(node: TNode | string): node is string {
+  return typeof node === 'string';
+}

package/src/utilities/toContentString.ts

@@ -0,0 +1,23 @@
+import type { TNode } from '#src/parser.ts';
+
+/**
+ * Read the text content of a node, useful for mixed content.
+ * Example: "this text has some <b>big</b> text and a <a href=''>link</a>"
+ * @param domContent - The node(s) to extract text from
+ * @returns Concatenated text content
+ */
+export function toContentString(
+  domContent: TNode | (TNode | string)[] | string,
+): string {
+  if (Array.isArray(domContent)) {
+    let out = '';
+    for (let i = 0; i < domContent.length; i++) {
+      out += ' ' + toContentString(domContent[i]!);
+    }
+    return out.trim();
+  } else if (typeof domContent === 'object' && domContent !== null) {
+    return toContentString(domContent.children);
+  } else {
+    return ' ' + domContent;
+  }
+}