@speclynx/apidom-core 4.0.1 → 4.0.3

package/src/refractor/toolbox.ts

@@ -0,0 +1,88 @@
+import {
+  Namespace,
+  isElement,
+  isStringElement,
+  isNumberElement,
+  isNullElement,
+  isBooleanElement,
+  isArrayElement,
+  isObjectElement,
+  isMemberElement,
+  isPrimitiveElement,
+  isLinkElement,
+  isRefElement,
+  isAnnotationElement,
+  isCommentElement,
+  isParseResultElement,
+  isSourceMapElement,
+  hasElementStyle,
+  hasElementSourceMap,
+  includesSymbols,
+  includesClasses,
+} from '@speclynx/apidom-datamodel';
+
+import defaultNamespace from '../namespace.ts';
+
+/**
+ * @public
+ */
+export interface Predicates {
+  isElement: typeof isElement;
+  isStringElement: typeof isStringElement;
+  isNumberElement: typeof isNumberElement;
+  isNullElement: typeof isNullElement;
+  isBooleanElement: typeof isBooleanElement;
+  isArrayElement: typeof isArrayElement;
+  isObjectElement: typeof isObjectElement;
+  isMemberElement: typeof isMemberElement;
+  isPrimitiveElement: typeof isPrimitiveElement;
+  isLinkElement: typeof isLinkElement;
+  isRefElement: typeof isRefElement;
+  isAnnotationElement: typeof isAnnotationElement;
+  isCommentElement: typeof isCommentElement;
+  isParseResultElement: typeof isParseResultElement;
+  isSourceMapElement: typeof isSourceMapElement;
+  hasElementStyle: typeof hasElementStyle;
+  hasElementSourceMap: typeof hasElementSourceMap;
+  includesSymbols: typeof includesSymbols;
+  includesClasses: typeof includesClasses;
+}
+
+const predicates: Predicates = {
+  isElement,
+  isStringElement,
+  isNumberElement,
+  isNullElement,
+  isBooleanElement,
+  isArrayElement,
+  isObjectElement,
+  isMemberElement,
+  isPrimitiveElement,
+  isLinkElement,
+  isRefElement,
+  isAnnotationElement,
+  isCommentElement,
+  isParseResultElement,
+  isSourceMapElement,
+  hasElementStyle,
+  hasElementSourceMap,
+  includesSymbols,
+  includesClasses,
+};
+
+/**
+ * @public
+ */
+export interface Toolbox {
+  predicates: Predicates;
+  namespace: Namespace;
+}
+
+/**
+ * @public
+ */
+const createToolbox = (): Toolbox => {
+  return { predicates, namespace: defaultNamespace };
+};
+
+export default createToolbox;

package/src/specification.cjs

@@ -0,0 +1,63 @@
+"use strict";
+
+exports.__esModule = true;
+exports.resolveSpecification = void 0;
+var _ramda = require("ramda");
+var _ramdaAdjunct = require("ramda-adjunct");
+/**
+ * Base type for resolved specification objects.
+ * Extend this in namespace packages to add specific type information.
+ * @public
+ */
+
+const specCache = new WeakMap();
+
+/**
+ * Resolves a specification object by:
+ * 1. Dereferencing all $ref pointers
+ * 2. Building elementMap from objects with `element` property
+ * 3. Caching results for efficiency
+ *
+ * @public
+ */
+const resolveSpecification = specification => {
+  if (specCache.has(specification)) {
+    return specCache.get(specification);
+  }
+  const elementMap = {};
+  const traverse = (obj, root, currentPath) => {
+    // Collect element mapping
+    if (typeof obj.element === 'string') {
+      elementMap[obj.element] = obj.$visitor ? [...currentPath, '$visitor'] : currentPath;
+    }
+    return (0, _ramda.mapObjIndexed)((val, key) => {
+      const newPath = [...currentPath, key];
+      if ((0, _ramdaAdjunct.isPlainObject)(val) && (0, _ramda.has)('$ref', val) && (0, _ramda.propSatisfies)(_ramdaAdjunct.isString, '$ref', val)) {
+        const $ref = (0, _ramda.path)(['$ref'], val);
+        const pointer = (0, _ramdaAdjunct.trimCharsStart)('#/', $ref);
+        const resolved = (0, _ramda.path)(pointer.split('/'), root);
+        // merge extra properties (e.g. alias) from the $ref object into the resolved value
+        const {
+          $ref: _,
+          ...rest
+        } = val;
+        if (Object.keys(rest).length > 0 && (0, _ramdaAdjunct.isPlainObject)(resolved)) {
+          return {
+            ...resolved,
+            ...rest
+          };
+        }
+        return resolved;
+      }
+      if ((0, _ramdaAdjunct.isPlainObject)(val)) {
+        return traverse(val, root, newPath);
+      }
+      return val;
+    }, obj);
+  };
+  const resolved = traverse(specification, specification, []);
+  resolved.elementMap = elementMap;
+  specCache.set(specification, resolved);
+  return resolved;
+};
+exports.resolveSpecification = resolveSpecification;

package/src/specification.mjs

@@ -0,0 +1,59 @@
+import { mapObjIndexed, path, has, propSatisfies } from 'ramda';
+import { isPlainObject, trimCharsStart, isString } from 'ramda-adjunct';
+
+/**
+ * Base type for resolved specification objects.
+ * Extend this in namespace packages to add specific type information.
+ * @public
+ */
+
+const specCache = new WeakMap();
+
+/**
+ * Resolves a specification object by:
+ * 1. Dereferencing all $ref pointers
+ * 2. Building elementMap from objects with `element` property
+ * 3. Caching results for efficiency
+ *
+ * @public
+ */
+export const resolveSpecification = specification => {
+  if (specCache.has(specification)) {
+    return specCache.get(specification);
+  }
+  const elementMap = {};
+  const traverse = (obj, root, currentPath) => {
+    // Collect element mapping
+    if (typeof obj.element === 'string') {
+      elementMap[obj.element] = obj.$visitor ? [...currentPath, '$visitor'] : currentPath;
+    }
+    return mapObjIndexed((val, key) => {
+      const newPath = [...currentPath, key];
+      if (isPlainObject(val) && has('$ref', val) && propSatisfies(isString, '$ref', val)) {
+        const $ref = path(['$ref'], val);
+        const pointer = trimCharsStart('#/', $ref);
+        const resolved = path(pointer.split('/'), root);
+        // merge extra properties (e.g. alias) from the $ref object into the resolved value
+        const {
+          $ref: _,
+          ...rest
+        } = val;
+        if (Object.keys(rest).length > 0 && isPlainObject(resolved)) {
+          return {
+            ...resolved,
+            ...rest
+          };
+        }
+        return resolved;
+      }
+      if (isPlainObject(val)) {
+        return traverse(val, root, newPath);
+      }
+      return val;
+    }, obj);
+  };
+  const resolved = traverse(specification, specification, []);
+  resolved.elementMap = elementMap;
+  specCache.set(specification, resolved);
+  return resolved;
+};

package/src/specification.ts

@@ -0,0 +1,68 @@
+import { mapObjIndexed, path, has, propSatisfies } from 'ramda';
+import { isPlainObject, trimCharsStart, isString } from 'ramda-adjunct';
+
+/**
+ * Base type for resolved specification objects.
+ * Extend this in namespace packages to add specific type information.
+ * @public
+ */
+export interface ResolvedSpecification {
+  elementMap: Record<string, string[]>;
+}
+
+const specCache = new WeakMap<object, Record<string, unknown>>();
+
+/**
+ * Resolves a specification object by:
+ * 1. Dereferencing all $ref pointers
+ * 2. Building elementMap from objects with `element` property
+ * 3. Caching results for efficiency
+ *
+ * @public
+ */
+export const resolveSpecification = <T extends ResolvedSpecification = ResolvedSpecification>(
+  specification: Record<string, unknown>,
+): T => {
+  if (specCache.has(specification)) {
+    return specCache.get(specification)! as T;
+  }
+
+  const elementMap: Record<string, string[]> = {};
+
+  const traverse = (
+    obj: Record<string, unknown>,
+    root: Record<string, unknown>,
+    currentPath: string[],
+  ): Record<string, unknown> => {
+    // Collect element mapping
+    if (typeof obj.element === 'string') {
+      elementMap[obj.element] = obj.$visitor ? [...currentPath, '$visitor'] : currentPath;
+    }
+
+    return mapObjIndexed((val, key) => {
+      const newPath = [...currentPath, key as string];
+
+      if (isPlainObject(val) && has('$ref', val) && propSatisfies(isString, '$ref', val)) {
+        const $ref = path(['$ref'], val);
+        const pointer = trimCharsStart('#/', $ref as string);
+        const resolved = path(pointer.split('/'), root);
+        // merge extra properties (e.g. alias) from the $ref object into the resolved value
+        const { $ref: _, ...rest } = val as Record<string, unknown>;
+        if (Object.keys(rest).length > 0 && isPlainObject(resolved)) {
+          return { ...(resolved as Record<string, unknown>), ...rest };
+        }
+        return resolved;
+      }
+      if (isPlainObject(val)) {
+        return traverse(val as Record<string, unknown>, root, newPath);
+      }
+      return val;
+    }, obj);
+  };
+
+  const resolved = traverse(specification, specification, []);
+  resolved.elementMap = elementMap;
+
+  specCache.set(specification, resolved);
+  return resolved as T;
+};

package/src/transcluder/Transcluder.cjs

@@ -0,0 +1,111 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = void 0;
+var _apidomDatamodel = require("@speclynx/apidom-datamodel");
+var _ramdaAdjunct = require("ramda-adjunct");
+const computeEdges = (element, edges = new WeakMap()) => {
+  if ((0, _apidomDatamodel.isMemberElement)(element)) {
+    // @ts-ignore
+    edges.set(element.key, element);
+    // @ts-ignore
+    computeEdges(element.key, edges);
+    // @ts-ignore
+    edges.set(element.value, element);
+    // @ts-ignore
+    computeEdges(element.value, edges);
+  } else {
+    element.children.forEach(childElement => {
+      edges.set(childElement, element);
+      computeEdges(childElement, edges);
+    });
+  }
+  return edges;
+};
+const transcludeChildOfMemberElement = (search, replace, edges) => {
+  const memberElement = edges.get(search);
+  if (!(0, _apidomDatamodel.isMemberElement)(memberElement)) {
+    return;
+  }
+  if (memberElement.key === search) {
+    memberElement.key = replace;
+    edges.delete(search);
+    edges.set(replace, memberElement);
+  }
+  if (memberElement.value === search) {
+    memberElement.value = replace;
+    edges.delete(search);
+    edges.set(replace, memberElement);
+  }
+};
+const transcludeChildOfObjectElement = (search, replace, edges) => {
+  const objectElement = edges.get(search);
+  if (!(0, _apidomDatamodel.isObjectElement)(objectElement)) {
+    return;
+  }
+  objectElement.content = objectElement.map((value, key, member) => {
+    if (member === search) {
+      edges.delete(search);
+      edges.set(replace, objectElement);
+      return replace;
+    }
+    return member;
+  });
+};
+const transcludeChildOfArrayElement = (search, replace, edges) => {
+  const arrayElement = edges.get(search);
+  if (!(0, _apidomDatamodel.isArrayElement)(arrayElement)) {
+    return;
+  }
+  arrayElement.content = arrayElement.map(element => {
+    if (element === search) {
+      edges.delete(search);
+      edges.set(replace, arrayElement);
+      return replace;
+    }
+    return element;
+  });
+};
+
+/**
+ * This is a mutating stamp. If you don't want your Element to be mutated,
+ * clone in before passing it to initializer of this stamp.
+ * @public
+ */
+
+class Transcluder {
+  element;
+  edges;
+  constructor({
+    element
+  }) {
+    this.element = element;
+  }
+  transclude(search, replace) {
+    // shortcut 1. - replacing entire ApiDOM tree
+    if (search === this.element) return replace;
+    // shortcut 2. - replacing nothing
+    if (search === replace) return this.element;
+    this.edges = this.edges ?? computeEdges(this.element);
+    const parent = this.edges.get(search);
+    if ((0, _ramdaAdjunct.isUndefined)(parent)) {
+      return undefined;
+    }
+
+    /**
+     * This predicate must be first because ObjectElement extends ArrayElement.
+     * isArrayElement returns true for ObjectElements.
+     * (classical problems with polymorphism)
+     */
+    if ((0, _apidomDatamodel.isObjectElement)(parent)) {
+      // @ts-ignore
+      transcludeChildOfObjectElement(search, replace, this.edges);
+    } else if ((0, _apidomDatamodel.isArrayElement)(parent)) {
+      transcludeChildOfArrayElement(search, replace, this.edges);
+    } else if ((0, _apidomDatamodel.isMemberElement)(parent)) {
+      transcludeChildOfMemberElement(search, replace, this.edges);
+    }
+    return this.element;
+  }
+}
+var _default = exports.default = Transcluder;

package/src/transcluder/Transcluder.mjs

@@ -0,0 +1,107 @@
+import { isObjectElement, isArrayElement, isMemberElement } from '@speclynx/apidom-datamodel';
+import { isUndefined } from 'ramda-adjunct';
+const computeEdges = (element, edges = new WeakMap()) => {
+  if (isMemberElement(element)) {
+    // @ts-ignore
+    edges.set(element.key, element);
+    // @ts-ignore
+    computeEdges(element.key, edges);
+    // @ts-ignore
+    edges.set(element.value, element);
+    // @ts-ignore
+    computeEdges(element.value, edges);
+  } else {
+    element.children.forEach(childElement => {
+      edges.set(childElement, element);
+      computeEdges(childElement, edges);
+    });
+  }
+  return edges;
+};
+const transcludeChildOfMemberElement = (search, replace, edges) => {
+  const memberElement = edges.get(search);
+  if (!isMemberElement(memberElement)) {
+    return;
+  }
+  if (memberElement.key === search) {
+    memberElement.key = replace;
+    edges.delete(search);
+    edges.set(replace, memberElement);
+  }
+  if (memberElement.value === search) {
+    memberElement.value = replace;
+    edges.delete(search);
+    edges.set(replace, memberElement);
+  }
+};
+const transcludeChildOfObjectElement = (search, replace, edges) => {
+  const objectElement = edges.get(search);
+  if (!isObjectElement(objectElement)) {
+    return;
+  }
+  objectElement.content = objectElement.map((value, key, member) => {
+    if (member === search) {
+      edges.delete(search);
+      edges.set(replace, objectElement);
+      return replace;
+    }
+    return member;
+  });
+};
+const transcludeChildOfArrayElement = (search, replace, edges) => {
+  const arrayElement = edges.get(search);
+  if (!isArrayElement(arrayElement)) {
+    return;
+  }
+  arrayElement.content = arrayElement.map(element => {
+    if (element === search) {
+      edges.delete(search);
+      edges.set(replace, arrayElement);
+      return replace;
+    }
+    return element;
+  });
+};
+
+/**
+ * This is a mutating stamp. If you don't want your Element to be mutated,
+ * clone in before passing it to initializer of this stamp.
+ * @public
+ */
+
+class Transcluder {
+  element;
+  edges;
+  constructor({
+    element
+  }) {
+    this.element = element;
+  }
+  transclude(search, replace) {
+    // shortcut 1. - replacing entire ApiDOM tree
+    if (search === this.element) return replace;
+    // shortcut 2. - replacing nothing
+    if (search === replace) return this.element;
+    this.edges = this.edges ?? computeEdges(this.element);
+    const parent = this.edges.get(search);
+    if (isUndefined(parent)) {
+      return undefined;
+    }
+
+    /**
+     * This predicate must be first because ObjectElement extends ArrayElement.
+     * isArrayElement returns true for ObjectElements.
+     * (classical problems with polymorphism)
+     */
+    if (isObjectElement(parent)) {
+      // @ts-ignore
+      transcludeChildOfObjectElement(search, replace, this.edges);
+    } else if (isArrayElement(parent)) {
+      transcludeChildOfArrayElement(search, replace, this.edges);
+    } else if (isMemberElement(parent)) {
+      transcludeChildOfMemberElement(search, replace, this.edges);
+    }
+    return this.element;
+  }
+}
+export default Transcluder;

package/src/transcluder/Transcluder.ts

@@ -0,0 +1,147 @@
+import {
+  ArrayElement,
+  Element,
+  MemberElement,
+  ObjectElement,
+  isObjectElement,
+  isArrayElement,
+  isMemberElement,
+} from '@speclynx/apidom-datamodel';
+import { isUndefined } from 'ramda-adjunct';
+
+const computeEdges = (element: Element, edges = new WeakMap()): WeakMap<Element, any> => {
+  if (isMemberElement(element)) {
+    // @ts-ignore
+    edges.set(element.key, element);
+    // @ts-ignore
+    computeEdges(element.key, edges);
+    // @ts-ignore
+    edges.set(element.value, element);
+    // @ts-ignore
+    computeEdges(element.value, edges);
+  } else {
+    element.children.forEach((childElement: Element): void => {
+      edges.set(childElement, element);
+      computeEdges(childElement, edges);
+    });
+  }
+
+  return edges;
+};
+
+const transcludeChildOfMemberElement = (
+  search: Element,
+  replace: Element,
+  edges: WeakMap<Element, any>,
+): void => {
+  const memberElement: MemberElement = edges.get(search);
+
+  if (!isMemberElement(memberElement)) {
+    return;
+  }
+
+  if (memberElement.key === search) {
+    memberElement.key = replace;
+    edges.delete(search);
+    edges.set(replace, memberElement);
+  }
+
+  if (memberElement.value === search) {
+    memberElement.value = replace;
+    edges.delete(search);
+    edges.set(replace, memberElement);
+  }
+};
+
+const transcludeChildOfObjectElement = (
+  search: Element,
+  replace: MemberElement,
+  edges: WeakMap<Element, any>,
+): void => {
+  const objectElement: ObjectElement = edges.get(search);
+
+  if (!isObjectElement(objectElement)) {
+    return;
+  }
+
+  objectElement.content = objectElement.map(
+    (value: Element, key: Element, member: MemberElement): MemberElement => {
+      if (member === search) {
+        edges.delete(search);
+        edges.set(replace, objectElement);
+        return replace;
+      }
+      return member;
+    },
+  );
+};
+
+const transcludeChildOfArrayElement = (
+  search: Element,
+  replace: Element,
+  edges: WeakMap<Element, any>,
+): void => {
+  const arrayElement: ArrayElement = edges.get(search);
+
+  if (!isArrayElement(arrayElement)) {
+    return;
+  }
+
+  arrayElement.content = arrayElement.map((element: Element): Element => {
+    if (element === search) {
+      edges.delete(search);
+      edges.set(replace, arrayElement);
+      return replace;
+    }
+    return element;
+  });
+};
+
+/**
+ * This is a mutating stamp. If you don't want your Element to be mutated,
+ * clone in before passing it to initializer of this stamp.
+ * @public
+ */
+
+class Transcluder {
+  protected element: Element;
+
+  protected edges!: WeakMap<Element, Element | undefined>;
+
+  constructor({ element }: { element: Element }) {
+    this.element = element;
+  }
+
+  public transclude(search: Element, replace: Element): Element | undefined {
+    // shortcut 1. - replacing entire ApiDOM tree
+    if (search === this.element) return replace;
+    // shortcut 2. - replacing nothing
+    if (search === replace) return this.element;
+
+    this.edges = this.edges ?? computeEdges(this.element);
+
+    const parent = this.edges.get(search);
+
+    if (isUndefined(parent)) {
+      return undefined;
+    }
+
+    /**
+     * This predicate must be first because ObjectElement extends ArrayElement.
+     * isArrayElement returns true for ObjectElements.
+     * (classical problems with polymorphism)
+     */
+    if (isObjectElement(parent)) {
+      // @ts-ignore
+      transcludeChildOfObjectElement(search, replace, this.edges);
+    } else if (isArrayElement(parent)) {
+      transcludeChildOfArrayElement(search, replace, this.edges);
+    } else if (isMemberElement(parent)) {
+      transcludeChildOfMemberElement(search, replace, this.edges);
+    }
+
+    return this.element;
+  }
+}
+
+export default Transcluder;

package/src/transcluder/index.cjs

@@ -0,0 +1,19 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+exports.__esModule = true;
+exports.transclude = exports.default = void 0;
+var _Transcluder = _interopRequireDefault(require("./Transcluder.cjs"));
+/**
+ * This is a mutating function. If you don't want your Element to be mutated,
+ * clone in before passing it to this function.
+ * @public
+ */
+const transclude = (search, replace, element) => {
+  const transcluder = new _Transcluder.default({
+    element
+  });
+  return transcluder.transclude(search, replace);
+};
+exports.transclude = transclude;
+var _default = exports.default = _Transcluder.default;

package/src/transcluder/index.mjs

@@ -0,0 +1,13 @@
+import Transcluder from "./Transcluder.mjs";
+/**
+ * This is a mutating function. If you don't want your Element to be mutated,
+ * clone in before passing it to this function.
+ * @public
+ */
+export const transclude = (search, replace, element) => {
+  const transcluder = new Transcluder({
+    element
+  });
+  return transcluder.transclude(search, replace);
+};
+export default Transcluder;

package/src/transcluder/index.ts

@@ -0,0 +1,15 @@
+import { Element } from '@speclynx/apidom-datamodel';
+
+import Transcluder from './Transcluder.ts';
+
+/**
+ * This is a mutating function. If you don't want your Element to be mutated,
+ * clone in before passing it to this function.
+ * @public
+ */
+export const transclude = (search: Element, replace: Element, element: Element) => {
+  const transcluder = new Transcluder({ element });
+  return transcluder.transclude(search, replace);
+};
+
+export default Transcluder;