@speclynx/apidom-core 4.0.3 → 4.0.4

package/src/refractor/plugins/dispatcher/index.ts

@@ -1,102 +0,0 @@
-import { Element } from '@speclynx/apidom-datamodel';
-import {
-  traverse,
-  traverseAsync,
-  mergeVisitors,
-  mergeVisitorsAsync,
-} from '@speclynx/apidom-traverse';
-import { mergeDeepRight, propOr } from 'ramda';
-import { invokeArgs } from 'ramda-adjunct';
-
-import createToolbox from '../../toolbox.ts';
-
-/**
- * @public
- */
-export interface DispatchPluginsOptions {
-  toolboxCreator: typeof createToolbox;
-  visitorOptions: {
-    exposeEdits: boolean;
-  };
-}
-
-/**
- * @public
- */
-export interface DispatchPluginsSync {
-  <T extends Element, U extends Element = Element>(
-    element: T,
-    plugins: ((toolbox: any) => object)[],
-    options?: Record<string, unknown>,
-  ): U;
-  [key: symbol]: DispatchPluginsAsync;
-}
-
-/**
- * @public
- */
-export interface DispatchPluginsAsync {
-  <T extends Element, U extends Element = Element>(
-    element: T,
-    plugins: ((toolbox: any) => object)[],
-    options?: Record<string, unknown>,
-  ): Promise<U>;
-}
-
-const defaultDispatchPluginsOptions: DispatchPluginsOptions = {
-  toolboxCreator: createToolbox,
-  visitorOptions: {
-    exposeEdits: true,
-  },
-};
-
-/**
- * @public
- */
-export const dispatchPluginsSync: DispatchPluginsSync = ((element, plugins, options = {}) => {
-  if (plugins.length === 0) return element;
-
-  const mergedOptions = mergeDeepRight(
-    defaultDispatchPluginsOptions,
-    options,
-  ) as DispatchPluginsOptions;
-  const { toolboxCreator, visitorOptions } = mergedOptions;
-  const toolbox = toolboxCreator();
-  const pluginsSpecs = plugins.map((plugin) => plugin(toolbox));
-  const mergedPluginsVisitor = mergeVisitors(
-    pluginsSpecs.map(propOr({}, 'visitor')) as object[],
-    visitorOptions,
-  );
-
-  pluginsSpecs.forEach(invokeArgs(['pre'], []));
-  const newElement = traverse(element, mergedPluginsVisitor);
-  pluginsSpecs.forEach(invokeArgs(['post'], []));
-  return newElement;
-}) as DispatchPluginsSync;
-
-export const dispatchPluginsAsync: DispatchPluginsAsync = (async (
-  element,
-  plugins,
-  options = {},
-) => {
-  if (plugins.length === 0) return element;
-
-  const mergedOptions = mergeDeepRight(
-    defaultDispatchPluginsOptions,
-    options,
-  ) as DispatchPluginsOptions;
-  const { toolboxCreator, visitorOptions } = mergedOptions;
-  const toolbox = toolboxCreator();
-  const pluginsSpecs = plugins.map((plugin) => plugin(toolbox));
-  const mergedPluginsVisitor = mergeVisitorsAsync(
-    pluginsSpecs.map(propOr({}, 'visitor')) as object[],
-    visitorOptions,
-  );
-
-  await Promise.allSettled(pluginsSpecs.map(invokeArgs(['pre'], [])));
-  const newElement = await traverseAsync(element, mergedPluginsVisitor);
-  await Promise.allSettled(pluginsSpecs.map(invokeArgs(['post'], [])));
-  return newElement;
-}) as DispatchPluginsAsync;
-
-dispatchPluginsSync[Symbol.for('nodejs.util.promisify.custom')] = dispatchPluginsAsync;

package/src/refractor/plugins/element-identity.ts

@@ -1,31 +0,0 @@
-import { Element } from '@speclynx/apidom-datamodel';
-import { Path } from '@speclynx/apidom-traverse';
-
-import { IdentityManager } from '../../identity/index.ts';
-
-/**
- * Plugin for decorating every element in ApiDOM tree with UUID.
- * @public
- */
-
-const plugin =
-  ({ length = 6 } = {}) =>
-  () => {
-    let identityManager: IdentityManager | null;
-
-    return {
-      pre() {
-        identityManager = new IdentityManager({ length });
-      },
-      visitor: {
-        enter(path: Path<Element>) {
-          path.node.id = identityManager!.identify(path.node);
-        },
-      },
-      post() {
-        identityManager = null;
-      },
-    };
-  };
-
-export default plugin;

package/src/refractor/plugins/semantic-element-identity.ts

@@ -1,32 +0,0 @@
-import { Element, isPrimitiveElement } from '@speclynx/apidom-datamodel';
-import { Path } from '@speclynx/apidom-traverse';
-
-import { IdentityManager } from '../../identity/index.ts';
-
-/**
- * Plugin for decorating every semantic element in ApiDOM tree with UUID.
- * @public
- */
-const plugin =
-  ({ length = 6 } = {}) =>
-  () => {
-    let identityManager: IdentityManager | null;
-
-    return {
-      pre() {
-        identityManager = new IdentityManager({ length });
-      },
-      visitor: {
-        enter(path: Path<Element>) {
-          if (!isPrimitiveElement(path.node)) {
-            path.node.id = identityManager!.identify(path.node);
-          }
-        },
-      },
-      post() {
-        identityManager = null;
-      },
-    };
-  };
-
-export default plugin;

package/src/refractor/toolbox.ts

@@ -1,88 +0,0 @@
-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.ts

@@ -1,68 +0,0 @@
-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.ts

@@ -1,147 +0,0 @@
-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.ts

@@ -1,15 +0,0 @@
-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;

package/src/transformers/dehydrate.ts

@@ -1,14 +0,0 @@
-import { Element, Namespace } from '@speclynx/apidom-datamodel';
-
-import defaultNamespaceInstance from '../namespace.ts';
-
-/**
- * Creates a refract representation of an Element.
- * https://github.com/refractproject/refract-spec
- * @public
- */
-const dehydrate = (element: Element, namespace: Namespace = defaultNamespaceInstance): unknown => {
-  return namespace.toRefract(element);
-};
-
-export default dehydrate;

package/src/transformers/from.ts

@@ -1,34 +0,0 @@
-import { has } from 'ramda';
-import { isPlainObject, isString } from 'ramda-adjunct';
-import { Element, Namespace } from '@speclynx/apidom-datamodel';
-
-import defaultNamespace from '../namespace.ts';
-
-/**
- * Transforms data to an Element from a particular namespace.
- *
- * The name of the function was originally `from`,
- * but it was renamed to `fromFn` to avoid issues with Parcel.js:
- *
- * - https://github.com/parcel-bundler/parcel/issues/9473
- * - https://github.com/swagger-api/swagger-ui/issues/9466#issuecomment-1881053410
- * @public
- */
-const fromFn = (data: unknown, namespace: Namespace = defaultNamespace): Element | undefined => {
-  if (isString(data)) {
-    // JSON serialized refract
-    try {
-      return namespace.fromRefract(JSON.parse(data));
-    } catch {
-      // noop
-    }
-  }
-  if (isPlainObject(data) && has('element', data)) {
-    // refract javascript structure
-    return namespace.fromRefract(data);
-  }
-
-  return namespace.toElement(data);
-};
-
-export default fromFn;

package/src/transformers/serializers/json.ts

@@ -1,107 +0,0 @@
-import {
-  Element,
-  isElement,
-  isObjectElement,
-  isArrayElement,
-  isRefElement,
-  isLinkElement,
-  isStringElement,
-  isNumberElement,
-} from '@speclynx/apidom-datamodel';
-
-import toValue from './value.ts';
-
-interface JSONElementStyle {
-  indent?: number;
-  rawContent?: string;
-}
-
-const getStyle = (element: Element): JSONElementStyle => {
-  return (element.style?.json ?? {}) as JSONElementStyle;
-};
-
-/**
- * @public
- */
-export interface JSONSerializerOptions {
-  /** Preserve original formatting styles from `element.style.json` */
-  preserveStyle?: boolean;
-}
-
-/**
- * Builds a POJO from an ApiDOM element tree. Numbers with rawContent
- * are replaced with sentinel strings; all other values go through toValue().
- */
-const toPojo = (element: Element, sentinels: Map<string, string>): unknown => {
-  const visited = new WeakSet<object>();
-
-  const convert = (node: unknown): unknown => {
-    if (!isElement(node)) return node;
-
-    if (visited.has(node as object)) return null;
-    visited.add(node as object);
-
-    if (isObjectElement(node)) {
-      const obj: Record<string, unknown> = {};
-      node.forEach((value, key) => {
-        const k = isElement(key) ? toValue(key) : key;
-        if (typeof k === 'string') obj[k] = convert(value);
-      });
-      return obj;
-    }
-
-    if (isArrayElement(node)) {
-      const arr: unknown[] = [];
-      node.forEach((item) => arr.push(convert(item)));
-      return arr;
-    }
-
-    if (isRefElement(node)) return String(toValue(node));
-    if (isLinkElement(node)) return isStringElement(node.href) ? toValue(node.href) : '';
-
-    // number with rawContent — substitute with sentinel
-    if (isNumberElement(node)) {
-      const style = getStyle(node);
-      if (typeof style.rawContent === 'string') {
-        const sentinel = `\0RAW${sentinels.size}\0`;
-        sentinels.set(sentinel, style.rawContent);
-        return sentinel;
-      }
-    }
-
-    return toValue(node);
-  };
-
-  return convert(element);
-};
-
-/**
- * @public
- */
-const serializer = (
-  element: Element,
-  replacer?: (this: unknown, key: string, value: unknown) => unknown,
-  space?: string | number,
-  options?: JSONSerializerOptions,
-): string => {
-  if (options?.preserveStyle) {
-    const style = getStyle(element);
-    const indent =
-      typeof space === 'number' ? space : typeof style.indent === 'number' ? style.indent : 0;
-
-    const sentinels = new Map<string, string>();
-    const pojo = toPojo(element, sentinels);
-    let serialized = JSON.stringify(pojo, null, indent);
-
-    // replace quoted sentinels with raw number representations
-    for (const [sentinel, raw] of sentinels) {
-      serialized = serialized.replace(JSON.stringify(sentinel), raw);
-    }
-
-    return serialized;
-  }
-
-  return JSON.stringify(toValue(element), replacer, space);
-};
-
-export default serializer;