@speclynx/apidom-traverse 4.0.2 → 4.0.3

package/src/index.cjs

@@ -0,0 +1,43 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+exports.__esModule = true;
+exports.some = exports.reject = exports.parents = exports.mutateNode = exports.mergeVisitorsAsync = exports.mergeVisitors = exports.isNode = exports.getVisitFn = exports.getNodeType = exports.getNodePrimitiveType = exports.getNodeKeys = exports.forEach = exports.findAtOffset = exports.find = exports.filter = exports.cloneNode = void 0;
+var _Path = require("./Path.cjs");
+exports.Path = _Path.Path;
+var _traversal = require("./traversal.cjs");
+exports.traverse = _traversal.traverse;
+exports.traverseAsync = _traversal.traverseAsync;
+var _visitors = require("./visitors.cjs");
+exports.getNodeType = _visitors.getNodeType;
+exports.getNodePrimitiveType = _visitors.getNodePrimitiveType;
+exports.isNode = _visitors.isNode;
+exports.cloneNode = _visitors.cloneNode;
+exports.mutateNode = _visitors.mutateNode;
+exports.getNodeKeys = _visitors.getNodeKeys;
+exports.getVisitFn = _visitors.getVisitFn;
+exports.mergeVisitors = _visitors.mergeVisitors;
+exports.mergeVisitorsAsync = _visitors.mergeVisitorsAsync;
+var _filter = _interopRequireDefault(require("./operations/filter.cjs"));
+exports.filter = _filter.default;
+var _find = _interopRequireDefault(require("./operations/find.cjs"));
+exports.find = _find.default;
+var _some = _interopRequireDefault(require("./operations/some.cjs"));
+exports.some = _some.default;
+var _reject = _interopRequireDefault(require("./operations/reject.cjs"));
+exports.reject = _reject.default;
+var _forEach = _interopRequireDefault(require("./operations/for-each.cjs"));
+exports.forEach = _forEach.default;
+var _parents = _interopRequireDefault(require("./operations/parents.cjs"));
+exports.parents = _parents.default;
+var _findAtOffset = _interopRequireDefault(require("./operations/find-at-offset.cjs"));
+exports.findAtOffset = _findAtOffset.default;
+// Wire up Path.prototype.traverse methods to avoid circular imports
+_Path.Path.prototype.traverse = function (visitor, options) {
+  return (0, _traversal.traverse)(this.node, visitor, options);
+};
+_Path.Path.prototype.traverseAsync = function (visitor, options) {
+  return (0, _traversal.traverseAsync)(this.node, visitor, options);
+};
+
+// Operations

package/src/index.mjs

@@ -0,0 +1,19 @@
+import { Path } from "./Path.mjs";
+import { traverse, traverseAsync } from "./traversal.mjs"; // Wire up Path.prototype.traverse methods to avoid circular imports
+Path.prototype.traverse = function (visitor, options) {
+  return traverse(this.node, visitor, options);
+};
+Path.prototype.traverseAsync = function (visitor, options) {
+  return traverseAsync(this.node, visitor, options);
+};
+export { Path };
+export { getNodeType, getNodePrimitiveType, isNode, cloneNode, mutateNode, getNodeKeys, getVisitFn, mergeVisitors, mergeVisitorsAsync } from "./visitors.mjs";
+export { traverse, traverseAsync } from "./traversal.mjs";
+// Operations
+export { default as filter } from "./operations/filter.mjs";
+export { default as find } from "./operations/find.mjs";
+export { default as some } from "./operations/some.mjs";
+export { default as reject } from "./operations/reject.mjs";
+export { default as forEach } from "./operations/for-each.mjs";
+export { default as parents } from "./operations/parents.mjs";
+export { default as findAtOffset } from "./operations/find-at-offset.mjs";

package/src/index.ts

@@ -0,0 +1,44 @@
+import { Path } from './Path.ts';
+import { traverse, traverseAsync } from './traversal.ts';
+
+// Wire up Path.prototype.traverse methods to avoid circular imports
+Path.prototype.traverse = function (this: Path<any>, visitor: any, options?: any) {
+  return traverse(this.node, visitor, options);
+};
+
+Path.prototype.traverseAsync = function (this: Path<any>, visitor: any, options?: any) {
+  return traverseAsync(this.node, visitor, options);
+};
+
+export { Path };
+export type { VisitorFn, VisitorResult } from './Path.ts';
+export {
+  getNodeType,
+  getNodePrimitiveType,
+  isNode,
+  cloneNode,
+  mutateNode,
+  getNodeKeys,
+  getVisitFn,
+  mergeVisitors,
+  mergeVisitorsAsync,
+} from './visitors.ts';
+export type {
+  NodeVisitor,
+  MergeVisitorsOptions,
+  MergedVisitor,
+  MergedVisitorAsync,
+} from './visitors.ts';
+export { traverse, traverseAsync } from './traversal.ts';
+export type { TraverseOptions } from './traversal.ts';
+
+// Operations
+export { default as filter } from './operations/filter.ts';
+export { default as find } from './operations/find.ts';
+export { default as some } from './operations/some.ts';
+export { default as reject } from './operations/reject.ts';
+export { default as forEach } from './operations/for-each.ts';
+export type { Callback as ForEachCallback, ForEachOptions } from './operations/for-each.ts';
+export { default as parents } from './operations/parents.ts';
+export { default as findAtOffset } from './operations/find-at-offset.ts';
+export type { FindAtOffsetOptions } from './operations/find-at-offset.ts';

package/src/operations/filter.cjs

@@ -0,0 +1,21 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = void 0;
+var _traversal = require("../traversal.cjs");
+/**
+ * Finds all paths whose elements match the predicate.
+ * @public
+ */
+const filter = (element, predicate) => {
+  const result = [];
+  (0, _traversal.traverse)(element, {
+    enter(path) {
+      if (predicate(path)) {
+        result.push(path);
+      }
+    }
+  });
+  return result;
+};
+var _default = exports.default = filter;

package/src/operations/filter.mjs

@@ -0,0 +1,17 @@
+import { traverse } from "../traversal.mjs";
+/**
+ * Finds all paths whose elements match the predicate.
+ * @public
+ */
+const filter = (element, predicate) => {
+  const result = [];
+  traverse(element, {
+    enter(path) {
+      if (predicate(path)) {
+        result.push(path);
+      }
+    }
+  });
+  return result;
+};
+export default filter;

package/src/operations/filter.ts

@@ -0,0 +1,27 @@
+import { Element } from '@speclynx/apidom-datamodel';
+
+import { traverse } from '../traversal.ts';
+import type { Path } from '../Path.ts';
+
+/**
+ * Finds all paths whose elements match the predicate.
+ * @public
+ */
+const filter = <T extends Element>(
+  element: T,
+  predicate: (path: Path<Element>) => boolean,
+): Path<Element>[] => {
+  const result: Path<Element>[] = [];
+
+  traverse(element, {
+    enter(path: Path<Element>) {
+      if (predicate(path)) {
+        result.push(path);
+      }
+    },
+  });
+
+  return result;
+};
+
+export default filter;

package/src/operations/find-at-offset.cjs

@@ -0,0 +1,45 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = void 0;
+var _apidomDatamodel = require("@speclynx/apidom-datamodel");
+var _traversal = require("../traversal.cjs");
+/**
+ * @public
+ */
+
+/**
+ * Finds the path of the most inner node at the given offset.
+ * If includeRightBound is set, also finds nodes that end at the given offset.
+ * @public
+ */
+const findAtOffset = (element, options) => {
+  let offset;
+  let includeRightBound;
+  if (typeof options === 'number') {
+    offset = options;
+    includeRightBound = false;
+  } else {
+    offset = options.offset ?? 0;
+    includeRightBound = options.includeRightBound ?? false;
+  }
+  const result = [];
+  (0, _traversal.traverse)(element, {
+    enter(path) {
+      const node = path.node;
+      if (!(0, _apidomDatamodel.hasElementSourceMap)(node)) {
+        return; // dive in
+      }
+      const startOffset = node.startOffset;
+      const endOffset = node.endOffset;
+      const isWithinOffsetRange = offset >= startOffset && (offset < endOffset || includeRightBound && offset <= endOffset);
+      if (isWithinOffsetRange) {
+        result.push(path);
+        return; // push to stack and dive in
+      }
+      path.skip(); // skip entire sub-tree
+    }
+  });
+  return result.at(-1);
+};
+var _default = exports.default = findAtOffset;

package/src/operations/find-at-offset.mjs

@@ -0,0 +1,40 @@
+import { hasElementSourceMap } from '@speclynx/apidom-datamodel';
+import { traverse } from "../traversal.mjs";
+/**
+ * @public
+ */
+/**
+ * Finds the path of the most inner node at the given offset.
+ * If includeRightBound is set, also finds nodes that end at the given offset.
+ * @public
+ */
+const findAtOffset = (element, options) => {
+  let offset;
+  let includeRightBound;
+  if (typeof options === 'number') {
+    offset = options;
+    includeRightBound = false;
+  } else {
+    offset = options.offset ?? 0;
+    includeRightBound = options.includeRightBound ?? false;
+  }
+  const result = [];
+  traverse(element, {
+    enter(path) {
+      const node = path.node;
+      if (!hasElementSourceMap(node)) {
+        return; // dive in
+      }
+      const startOffset = node.startOffset;
+      const endOffset = node.endOffset;
+      const isWithinOffsetRange = offset >= startOffset && (offset < endOffset || includeRightBound && offset <= endOffset);
+      if (isWithinOffsetRange) {
+        result.push(path);
+        return; // push to stack and dive in
+      }
+      path.skip(); // skip entire sub-tree
+    }
+  });
+  return result.at(-1);
+};
+export default findAtOffset;

package/src/operations/find-at-offset.ts

@@ -0,0 +1,61 @@
+import { Element, hasElementSourceMap } from '@speclynx/apidom-datamodel';
+
+import { traverse } from '../traversal.ts';
+import type { Path } from '../Path.ts';
+
+/**
+ * @public
+ */
+export interface FindAtOffsetOptions {
+  offset: number;
+  includeRightBound?: boolean;
+}
+
+/**
+ * Finds the path of the most inner node at the given offset.
+ * If includeRightBound is set, also finds nodes that end at the given offset.
+ * @public
+ */
+const findAtOffset = <T extends Element>(
+  element: T,
+  options: number | FindAtOffsetOptions,
+): Path<Element> | undefined => {
+  let offset: number;
+  let includeRightBound: boolean;
+
+  if (typeof options === 'number') {
+    offset = options;
+    includeRightBound = false;
+  } else {
+    offset = options.offset ?? 0;
+    includeRightBound = options.includeRightBound ?? false;
+  }
+
+  const result: Path<Element>[] = [];
+
+  traverse(element, {
+    enter(path: Path<Element>) {
+      const node = path.node;
+
+      if (!hasElementSourceMap(node)) {
+        return; // dive in
+      }
+
+      const startOffset: number = node.startOffset!;
+      const endOffset: number = node.endOffset!;
+      const isWithinOffsetRange =
+        offset >= startOffset && (offset < endOffset || (includeRightBound && offset <= endOffset));
+
+      if (isWithinOffsetRange) {
+        result.push(path);
+        return; // push to stack and dive in
+      }
+
+      path.skip(); // skip entire sub-tree
+    },
+  });
+
+  return result.at(-1);
+};
+
+export default findAtOffset;

package/src/operations/find.cjs

@@ -0,0 +1,22 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = void 0;
+var _traversal = require("../traversal.cjs");
+/**
+ * Finds first path whose element satisfies the provided predicate.
+ * @public
+ */
+const find = (element, predicate) => {
+  let result;
+  (0, _traversal.traverse)(element, {
+    enter(path) {
+      if (predicate(path)) {
+        result = path;
+        path.stop();
+      }
+    }
+  });
+  return result;
+};
+var _default = exports.default = find;

package/src/operations/find.mjs

@@ -0,0 +1,18 @@
+import { traverse } from "../traversal.mjs";
+/**
+ * Finds first path whose element satisfies the provided predicate.
+ * @public
+ */
+const find = (element, predicate) => {
+  let result;
+  traverse(element, {
+    enter(path) {
+      if (predicate(path)) {
+        result = path;
+        path.stop();
+      }
+    }
+  });
+  return result;
+};
+export default find;

package/src/operations/find.ts

@@ -0,0 +1,28 @@
+import { Element } from '@speclynx/apidom-datamodel';
+
+import { traverse } from '../traversal.ts';
+import type { Path } from '../Path.ts';
+
+/**
+ * Finds first path whose element satisfies the provided predicate.
+ * @public
+ */
+const find = <T extends Element>(
+  element: T,
+  predicate: (path: Path<Element>) => boolean,
+): Path<Element> | undefined => {
+  let result: Path<Element> | undefined;
+
+  traverse(element, {
+    enter(path: Path<Element>) {
+      if (predicate(path)) {
+        result = path;
+        path.stop();
+      }
+    },
+  });
+
+  return result;
+};
+
+export default find;

package/src/operations/for-each.cjs

@@ -0,0 +1,36 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = void 0;
+var _traversal = require("../traversal.cjs");
+/**
+ * @public
+ */
+
+/**
+ * @public
+ */
+
+/**
+ * Executes the callback on this element's path and all descendant paths.
+ * @public
+ */
+const forEach = (element, options) => {
+  let callback;
+  let predicate;
+  if (typeof options === 'function') {
+    callback = options;
+    predicate = () => true;
+  } else {
+    callback = options.callback ?? (() => {});
+    predicate = options.predicate ?? (() => true);
+  }
+  (0, _traversal.traverse)(element, {
+    enter(path) {
+      if (predicate(path)) {
+        callback(path);
+      }
+    }
+  });
+};
+var _default = exports.default = forEach;

package/src/operations/for-each.mjs

@@ -0,0 +1,30 @@
+import { traverse } from "../traversal.mjs";
+/**
+ * @public
+ */
+/**
+ * @public
+ */
+/**
+ * Executes the callback on this element's path and all descendant paths.
+ * @public
+ */
+const forEach = (element, options) => {
+  let callback;
+  let predicate;
+  if (typeof options === 'function') {
+    callback = options;
+    predicate = () => true;
+  } else {
+    callback = options.callback ?? (() => {});
+    predicate = options.predicate ?? (() => true);
+  }
+  traverse(element, {
+    enter(path) {
+      if (predicate(path)) {
+        callback(path);
+      }
+    }
+  });
+};
+export default forEach;

package/src/operations/for-each.ts

@@ -0,0 +1,44 @@
+import { Element } from '@speclynx/apidom-datamodel';
+
+import { traverse } from '../traversal.ts';
+import type { Path } from '../Path.ts';
+
+/**
+ * @public
+ */
+export type Callback = (path: Path<Element>) => void;
+
+/**
+ * @public
+ */
+export interface ForEachOptions {
+  callback?: Callback;
+  predicate?: (path: Path<Element>) => boolean;
+}
+
+/**
+ * Executes the callback on this element's path and all descendant paths.
+ * @public
+ */
+const forEach = <T extends Element>(element: T, options: Callback | ForEachOptions): void => {
+  let callback: Callback;
+  let predicate: (path: Path<Element>) => boolean;
+
+  if (typeof options === 'function') {
+    callback = options;
+    predicate = () => true;
+  } else {
+    callback = options.callback ?? (() => {});
+    predicate = options.predicate ?? (() => true);
+  }
+
+  traverse(element, {
+    enter(path: Path<Element>) {
+      if (predicate(path)) {
+        callback(path);
+      }
+    },
+  });
+};
+
+export default forEach;

package/src/operations/parents.cjs

@@ -0,0 +1,21 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = void 0;
+var _traversal = require("../traversal.cjs");
+/**
+ * Computes upwards edges from every child to its parent.
+ * @public
+ */
+const parents = element => {
+  const parentEdges = new WeakMap();
+  (0, _traversal.traverse)(element, {
+    enter(path) {
+      // Use parentPath.node to get the actual Element parent.
+      // path.parent could be an array (ArraySlice) when inside ArrayElement/ObjectElement content.
+      parentEdges.set(path.node, path.parentPath?.node);
+    }
+  });
+  return parentEdges;
+};
+var _default = exports.default = parents;

package/src/operations/parents.mjs

@@ -0,0 +1,17 @@
+import { traverse } from "../traversal.mjs";
+/**
+ * Computes upwards edges from every child to its parent.
+ * @public
+ */
+const parents = element => {
+  const parentEdges = new WeakMap();
+  traverse(element, {
+    enter(path) {
+      // Use parentPath.node to get the actual Element parent.
+      // path.parent could be an array (ArraySlice) when inside ArrayElement/ObjectElement content.
+      parentEdges.set(path.node, path.parentPath?.node);
+    }
+  });
+  return parentEdges;
+};
+export default parents;

package/src/operations/parents.ts

@@ -0,0 +1,24 @@
+import { Element } from '@speclynx/apidom-datamodel';
+
+import { traverse } from '../traversal.ts';
+import type { Path } from '../Path.ts';
+
+/**
+ * Computes upwards edges from every child to its parent.
+ * @public
+ */
+const parents = <T extends Element>(element: T): WeakMap<Element, Element | undefined> => {
+  const parentEdges = new WeakMap<Element, Element | undefined>();
+
+  traverse(element, {
+    enter(path: Path<Element>) {
+      // Use parentPath.node to get the actual Element parent.
+      // path.parent could be an array (ArraySlice) when inside ArrayElement/ObjectElement content.
+      parentEdges.set(path.node, path.parentPath?.node);
+    },
+  });
+
+  return parentEdges;
+};
+
+export default parents;

package/src/operations/reject.cjs

@@ -0,0 +1,14 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+exports.__esModule = true;
+exports.default = void 0;
+var _filter = _interopRequireDefault(require("./filter.cjs"));
+/**
+ * Complement of filter. Finds all paths whose elements do NOT match the predicate.
+ * @public
+ */
+const reject = (element, predicate) => {
+  return (0, _filter.default)(element, path => !predicate(path));
+};
+var _default = exports.default = reject;

package/src/operations/reject.mjs

@@ -0,0 +1,9 @@
+import filter from "./filter.mjs";
+/**
+ * Complement of filter. Finds all paths whose elements do NOT match the predicate.
+ * @public
+ */
+const reject = (element, predicate) => {
+  return filter(element, path => !predicate(path));
+};
+export default reject;

package/src/operations/reject.ts

@@ -0,0 +1,17 @@
+import { Element } from '@speclynx/apidom-datamodel';
+
+import filter from './filter.ts';
+import type { Path } from '../Path.ts';
+
+/**
+ * Complement of filter. Finds all paths whose elements do NOT match the predicate.
+ * @public
+ */
+const reject = <T extends Element>(
+  element: T,
+  predicate: (path: Path<Element>) => boolean,
+): Path<Element>[] => {
+  return filter(element, (path) => !predicate(path));
+};
+
+export default reject;

package/src/operations/some.cjs

@@ -0,0 +1,14 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+exports.__esModule = true;
+exports.default = void 0;
+var _find = _interopRequireDefault(require("./find.cjs"));
+/**
+ * Tests whether at least one path's element passes the predicate.
+ * @public
+ */
+const some = (element, predicate) => {
+  return (0, _find.default)(element, predicate) !== undefined;
+};
+var _default = exports.default = some;

package/src/operations/some.mjs

@@ -0,0 +1,9 @@
+import find from "./find.mjs";
+/**
+ * Tests whether at least one path's element passes the predicate.
+ * @public
+ */
+const some = (element, predicate) => {
+  return find(element, predicate) !== undefined;
+};
+export default some;

package/src/operations/some.ts

@@ -0,0 +1,17 @@
+import { Element } from '@speclynx/apidom-datamodel';
+
+import find from './find.ts';
+import type { Path } from '../Path.ts';
+
+/**
+ * Tests whether at least one path's element passes the predicate.
+ * @public
+ */
+const some = <T extends Element>(
+  element: T,
+  predicate: (path: Path<Element>) => boolean,
+): boolean => {
+  return find(element, predicate) !== undefined;
+};
+
+export default some;