@speclynx/apidom-reference 4.0.2 → 4.0.3

package/src/dereference/index.mjs

@@ -0,0 +1,83 @@
+import { isEmpty, propEq } from 'ramda';
+import { isParseResultElement, ParseResultElement, cloneShallow } from '@speclynx/apidom-datamodel';
+import File from "../File.mjs";
+import * as plugins from "../util/plugins.mjs";
+import UnmatchedDereferenceStrategyError from "../errors/UnmatchedDereferenceStrategyError.mjs";
+import DereferenceError from "../errors/DereferenceError.mjs";
+import UnresolvableReferenceError from "../errors/UnresolvableReferenceError.mjs";
+import parse from "../parse/index.mjs";
+import { merge as mergeOptions } from "../options/util.mjs";
+import * as url from "../util/url.mjs";
+/**
+ * Dereferences ApiDOM with all its external references.
+ */
+export const dereferenceApiDOM = async (element, options) => {
+  // @ts-ignore
+  let parseResult = element;
+  let surrogateWrapping = false;
+
+  // wrap element into parse result
+  if (!isParseResultElement(element)) {
+    const elementClone = cloneShallow(element);
+    elementClone.classes.push('result');
+    parseResult = new ParseResultElement([elementClone]);
+    surrogateWrapping = true;
+  }
+  const file = new File({
+    uri: options.resolve.baseURI,
+    parseResult,
+    mediaType: options.parse.mediaType
+  });
+  const dereferenceStrategies = await plugins.filter('canDereference', [file, options], options.dereference.strategies);
+
+  // we couldn't find any dereference strategy for this File
+  if (isEmpty(dereferenceStrategies)) {
+    throw new UnmatchedDereferenceStrategyError(`Could not find a dereference strategy that can dereference the file "${file.uri}"`);
+  }
+  try {
+    const {
+      result
+    } = await plugins.run('dereference', [file, options], dereferenceStrategies);
+    // unwrap the element from ParseResult assuming first element is the actual result
+    return surrogateWrapping ? result.get(0) : result;
+  } catch (error) {
+    if (error instanceof UnresolvableReferenceError) {
+      throw error;
+    }
+    throw new DereferenceError(`Error while dereferencing file "${file.uri}"`, {
+      cause: error
+    });
+  }
+};
+
+/**
+ * Dereferences a file with all its external references.
+ */
+const dereference = async (uri, options) => {
+  const {
+    refSet
+  } = options.dereference;
+  const sanitizedURI = url.sanitize(uri);
+  let parseResult;
+
+  // if refSet was provided, use it to avoid unnecessary parsing
+  if (refSet !== null && refSet.has(sanitizedURI)) {
+    // @ts-ignore
+    ({
+      value: parseResult
+    } = refSet.find(propEq(sanitizedURI, 'uri')));
+  } else {
+    parseResult = await parse(uri, options);
+  }
+  const mergedOptions = mergeOptions(options, {
+    resolve: {
+      baseURI: sanitizedURI
+    },
+    dereference: {
+      // if refSet was not provided, then we can work in mutable mode
+      immutable: options.dereference.immutable && refSet !== null
+    }
+  });
+  return dereferenceApiDOM(parseResult, mergedOptions);
+};
+export default dereference;

package/src/dereference/index.ts

@@ -0,0 +1,96 @@
+import { isEmpty, propEq } from 'ramda';
+import {
+  Element,
+  isParseResultElement,
+  ParseResultElement,
+  cloneShallow,
+} from '@speclynx/apidom-datamodel';
+
+import File from '../File.ts';
+import * as plugins from '../util/plugins.ts';
+import UnmatchedDereferenceStrategyError from '../errors/UnmatchedDereferenceStrategyError.ts';
+import DereferenceError from '../errors/DereferenceError.ts';
+import UnresolvableReferenceError from '../errors/UnresolvableReferenceError.ts';
+import parse from '../parse/index.ts';
+import { merge as mergeOptions } from '../options/util.ts';
+import * as url from '../util/url.ts';
+import type { ReferenceOptions } from '../options/index.ts';
+
+/**
+ * Dereferences ApiDOM with all its external references.
+ */
+export const dereferenceApiDOM = async <T extends Element>(
+  element: T,
+  options: ReferenceOptions,
+): Promise<T> => {
+  // @ts-ignore
+  let parseResult: ParseResultElement = element;
+  let surrogateWrapping = false;
+
+  // wrap element into parse result
+  if (!isParseResultElement(element)) {
+    const elementClone = cloneShallow(element);
+    elementClone.classes.push('result');
+    parseResult = new ParseResultElement([elementClone]);
+    surrogateWrapping = true;
+  }
+
+  const file = new File({
+    uri: options.resolve.baseURI,
+    parseResult,
+    mediaType: options.parse.mediaType,
+  });
+
+  const dereferenceStrategies = await plugins.filter(
+    'canDereference',
+    [file, options],
+    options.dereference.strategies,
+  );
+
+  // we couldn't find any dereference strategy for this File
+  if (isEmpty(dereferenceStrategies)) {
+    throw new UnmatchedDereferenceStrategyError(
+      `Could not find a dereference strategy that can dereference the file "${file.uri}"`,
+    );
+  }
+
+  try {
+    const { result } = await plugins.run('dereference', [file, options], dereferenceStrategies);
+    // unwrap the element from ParseResult assuming first element is the actual result
+    return surrogateWrapping ? result.get(0) : result;
+  } catch (error: any) {
+    if (error instanceof UnresolvableReferenceError) {
+      throw error;
+    }
+    throw new DereferenceError(`Error while dereferencing file "${file.uri}"`, { cause: error });
+  }
+};
+
+/**
+ * Dereferences a file with all its external references.
+ */
+const dereference = async (uri: string, options: ReferenceOptions): Promise<ParseResultElement> => {
+  const { refSet } = options.dereference;
+  const sanitizedURI = url.sanitize(uri);
+  let parseResult;
+
+  // if refSet was provided, use it to avoid unnecessary parsing
+  if (refSet !== null && refSet.has(sanitizedURI)) {
+    // @ts-ignore
+    ({ value: parseResult } = refSet.find(propEq(sanitizedURI, 'uri')));
+  } else {
+    parseResult = await parse(uri, options);
+  }
+
+  const mergedOptions = mergeOptions(options, {
+    resolve: { baseURI: sanitizedURI },
+    dereference: {
+      // if refSet was not provided, then we can work in mutable mode
+      immutable: options.dereference.immutable && refSet !== null,
+    },
+  });
+
+  return dereferenceApiDOM(parseResult, mergedOptions);
+};
+
+export default dereference;

package/src/dereference/strategies/DereferenceStrategy.cjs

@@ -0,0 +1,20 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = void 0;
+/**
+ * @public
+ */
+
+/**
+ * @public
+ */
+class DereferenceStrategy {
+  name;
+  constructor({
+    name
+  }) {
+    this.name = name;
+  }
+}
+var _default = exports.default = DereferenceStrategy;

package/src/dereference/strategies/DereferenceStrategy.mjs

@@ -0,0 +1,16 @@
+/**
+ * @public
+ */
+
+/**
+ * @public
+ */
+class DereferenceStrategy {
+  name;
+  constructor({
+    name
+  }) {
+    this.name = name;
+  }
+}
+export default DereferenceStrategy;

package/src/dereference/strategies/DereferenceStrategy.ts

@@ -0,0 +1,27 @@
+import { Element } from '@speclynx/apidom-datamodel';
+
+import File from '../../File.ts';
+import type { ReferenceOptions } from '../../options/index.ts';
+
+/**
+ * @public
+ */
+export interface DereferenceStrategyOptions {
+  readonly name: string;
+}
+
+/**
+ * @public
+ */
+abstract class DereferenceStrategy {
+  public readonly name: string;
+
+  constructor({ name }: DereferenceStrategyOptions) {
+    this.name = name;
+  }
+
+  abstract canDereference(file: File, options: ReferenceOptions): boolean;
+  abstract dereference(file: File, options: ReferenceOptions): Promise<Element>;
+}
+
+export default DereferenceStrategy;

package/src/dereference/strategies/apidom/index.cjs

@@ -0,0 +1,89 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+exports.__esModule = true;
+exports.default = void 0;
+var _apidomDatamodel = require("@speclynx/apidom-datamodel");
+var _apidomTraverse = require("@speclynx/apidom-traverse");
+var _DereferenceStrategy = _interopRequireDefault(require("../DereferenceStrategy.cjs"));
+var _Reference = _interopRequireDefault(require("../../../Reference.cjs"));
+var _ReferenceSet = _interopRequireDefault(require("../../../ReferenceSet.cjs"));
+var _visitor = _interopRequireDefault(require("./visitor.cjs"));
+exports.ApiDOMDereferenceVisitor = _visitor.default;
+/**
+ * @public
+ */
+
+/**
+ * @public
+ */
+class ApiDOMDereferenceStrategy extends _DereferenceStrategy.default {
+  constructor(options) {
+    super({
+      ...(options ?? {}),
+      name: 'apidom'
+    });
+  }
+  canDereference(file) {
+    return file.mediaType.startsWith('application/vnd.apidom') && (0, _apidomDatamodel.isElement)(file.parseResult?.result);
+  }
+  async dereference(file, options) {
+    const immutableRefSet = options.dereference.refSet ?? new _ReferenceSet.default();
+    const mutableRefSet = new _ReferenceSet.default();
+    let refSet = immutableRefSet;
+    let reference;
+
+    // determine the initial reference
+    if (!immutableRefSet.has(file.uri)) {
+      reference = new _Reference.default({
+        uri: file.uri,
+        value: file.parseResult
+      });
+      immutableRefSet.add(reference);
+    } else {
+      // pre-computed refSet was provided as configuration option
+      reference = immutableRefSet.find(ref => ref.uri === file.uri);
+    }
+
+    /**
+     * Clone refSet due the dereferencing process being mutable.
+     * We don't want to mutate the original refSet and the references.
+     */
+    if (options.dereference.immutable) {
+      immutableRefSet.refs.map(ref => new _Reference.default({
+        ...ref,
+        value: (0, _apidomDatamodel.cloneDeep)(ref.value)
+      })).forEach(ref => mutableRefSet.add(ref));
+      reference = mutableRefSet.find(ref => ref.uri === file.uri);
+      refSet = mutableRefSet;
+    }
+    const visitor = new _visitor.default({
+      reference: reference,
+      options
+    });
+    const dereferencedElement = await (0, _apidomTraverse.traverseAsync)(refSet.rootRef.value, visitor, {
+      mutable: true
+    });
+
+    /**
+     * If immutable option is set, replay refs from the refSet.
+     */
+    if (options.dereference.immutable) {
+      mutableRefSet.refs.filter(ref => ref.uri.startsWith('immutable://')).map(ref => new _Reference.default({
+        ...ref,
+        uri: ref.uri.replace(/^immutable:\/\//, '')
+      })).forEach(ref => immutableRefSet.add(ref));
+    }
+
+    /**
+     * Release all memory if this refSet was not provided as a configuration option.
+     * If provided as configuration option, then provider is responsible for cleanup.
+     */
+    if (options.dereference.refSet === null) {
+      immutableRefSet.clean();
+    }
+    mutableRefSet.clean();
+    return dereferencedElement;
+  }
+}
+var _default = exports.default = ApiDOMDereferenceStrategy;

package/src/dereference/strategies/apidom/index.mjs

@@ -0,0 +1,83 @@
+import { isElement, cloneDeep } from '@speclynx/apidom-datamodel';
+import { traverseAsync } from '@speclynx/apidom-traverse';
+import DereferenceStrategy from "../DereferenceStrategy.mjs";
+import Reference from "../../../Reference.mjs";
+import ReferenceSet from "../../../ReferenceSet.mjs";
+import ApiDOMDereferenceVisitor from "./visitor.mjs";
+/**
+ * @public
+ */
+/**
+ * @public
+ */
+class ApiDOMDereferenceStrategy extends DereferenceStrategy {
+  constructor(options) {
+    super({
+      ...(options ?? {}),
+      name: 'apidom'
+    });
+  }
+  canDereference(file) {
+    return file.mediaType.startsWith('application/vnd.apidom') && isElement(file.parseResult?.result);
+  }
+  async dereference(file, options) {
+    const immutableRefSet = options.dereference.refSet ?? new ReferenceSet();
+    const mutableRefSet = new ReferenceSet();
+    let refSet = immutableRefSet;
+    let reference;
+
+    // determine the initial reference
+    if (!immutableRefSet.has(file.uri)) {
+      reference = new Reference({
+        uri: file.uri,
+        value: file.parseResult
+      });
+      immutableRefSet.add(reference);
+    } else {
+      // pre-computed refSet was provided as configuration option
+      reference = immutableRefSet.find(ref => ref.uri === file.uri);
+    }
+
+    /**
+     * Clone refSet due the dereferencing process being mutable.
+     * We don't want to mutate the original refSet and the references.
+     */
+    if (options.dereference.immutable) {
+      immutableRefSet.refs.map(ref => new Reference({
+        ...ref,
+        value: cloneDeep(ref.value)
+      })).forEach(ref => mutableRefSet.add(ref));
+      reference = mutableRefSet.find(ref => ref.uri === file.uri);
+      refSet = mutableRefSet;
+    }
+    const visitor = new ApiDOMDereferenceVisitor({
+      reference: reference,
+      options
+    });
+    const dereferencedElement = await traverseAsync(refSet.rootRef.value, visitor, {
+      mutable: true
+    });
+
+    /**
+     * If immutable option is set, replay refs from the refSet.
+     */
+    if (options.dereference.immutable) {
+      mutableRefSet.refs.filter(ref => ref.uri.startsWith('immutable://')).map(ref => new Reference({
+        ...ref,
+        uri: ref.uri.replace(/^immutable:\/\//, '')
+      })).forEach(ref => immutableRefSet.add(ref));
+    }
+
+    /**
+     * Release all memory if this refSet was not provided as a configuration option.
+     * If provided as configuration option, then provider is responsible for cleanup.
+     */
+    if (options.dereference.refSet === null) {
+      immutableRefSet.clean();
+    }
+    mutableRefSet.clean();
+    return dereferencedElement;
+  }
+}
+export { ApiDOMDereferenceVisitor };
+export default ApiDOMDereferenceStrategy;

package/src/dereference/strategies/apidom/index.ts

@@ -0,0 +1,128 @@
+import { Element, isElement, cloneDeep } from '@speclynx/apidom-datamodel';
+import { traverseAsync } from '@speclynx/apidom-traverse';
+
+import DereferenceStrategy, { DereferenceStrategyOptions } from '../DereferenceStrategy.ts';
+import File from '../../../File.ts';
+import Reference from '../../../Reference.ts';
+import ReferenceSet from '../../../ReferenceSet.ts';
+import ApiDOMDereferenceVisitor from './visitor.ts';
+import type { ReferenceOptions } from '../../../options/index.ts';
+
+export type {
+  default as DereferenceStrategy,
+  DereferenceStrategyOptions,
+} from '../DereferenceStrategy.ts';
+export type { default as File, FileOptions } from '../../../File.ts';
+export type { default as Reference, ReferenceOptions } from '../../../Reference.ts';
+export type { default as ReferenceSet, ReferenceSetOptions } from '../../../ReferenceSet.ts';
+export type { ApiDOMDereferenceVisitorOptions } from './visitor.ts';
+export type {
+  ReferenceOptions as ApiDOMReferenceOptions,
+  ReferenceBundleOptions as ApiDOMReferenceBundleOptions,
+  ReferenceDereferenceOptions as ApiDOMReferenceDereferenceOptions,
+  ReferenceParseOptions as ApiDOMReferenceParseOptions,
+  ReferenceResolveOptions as ApiDOMReferenceResolveOptions,
+} from '../../../options/index.ts';
+export type { default as Parser, ParserOptions } from '../../../parse/parsers/Parser.ts';
+export type { default as Resolver, ResolverOptions } from '../../../resolve/resolvers/Resolver.ts';
+export type {
+  default as ResolveStrategy,
+  ResolveStrategyOptions,
+} from '../../../resolve/strategies/ResolveStrategy.ts';
+export type {
+  default as BundleStrategy,
+  BundleStrategyOptions,
+} from '../../../bundle/strategies/BundleStrategy.ts';
+
+/**
+ * @public
+ */
+export interface ApiDOMDereferenceStrategyOptions extends Omit<
+  DereferenceStrategyOptions,
+  'name'
+> {}
+
+/**
+ * @public
+ */
+class ApiDOMDereferenceStrategy extends DereferenceStrategy {
+  constructor(options?: ApiDOMDereferenceStrategyOptions) {
+    super({ ...(options ?? {}), name: 'apidom' });
+  }
+
+  canDereference(file: File) {
+    return (
+      file.mediaType.startsWith('application/vnd.apidom') && isElement(file.parseResult?.result)
+    );
+  }
+
+  async dereference(file: File, options: ReferenceOptions): Promise<Element> {
+    const immutableRefSet = options.dereference.refSet ?? new ReferenceSet();
+    const mutableRefSet = new ReferenceSet();
+    let refSet = immutableRefSet;
+    let reference;
+
+    // determine the initial reference
+    if (!immutableRefSet.has(file.uri)) {
+      reference = new Reference({ uri: file.uri, value: file.parseResult! });
+      immutableRefSet.add(reference);
+    } else {
+      // pre-computed refSet was provided as configuration option
+      reference = immutableRefSet.find((ref) => ref.uri === file.uri);
+    }
+
+    /**
+     * Clone refSet due the dereferencing process being mutable.
+     * We don't want to mutate the original refSet and the references.
+     */
+    if (options.dereference.immutable) {
+      immutableRefSet.refs
+        .map(
+          (ref) =>
+            new Reference({
+              ...ref,
+              value: cloneDeep(ref.value),
+            }),
+        )
+        .forEach((ref) => mutableRefSet.add(ref));
+      reference = mutableRefSet.find((ref) => ref.uri === file.uri);
+      refSet = mutableRefSet;
+    }
+
+    const visitor = new ApiDOMDereferenceVisitor({ reference: reference!, options });
+    const dereferencedElement = await traverseAsync(refSet.rootRef!.value, visitor, {
+      mutable: true,
+    });
+
+    /**
+     * If immutable option is set, replay refs from the refSet.
+     */
+    if (options.dereference.immutable) {
+      mutableRefSet.refs
+        .filter((ref) => ref.uri.startsWith('immutable://'))
+        .map(
+          (ref) =>
+            new Reference({
+              ...ref,
+              uri: ref.uri.replace(/^immutable:\/\//, ''),
+            }),
+        )
+        .forEach((ref) => immutableRefSet.add(ref));
+    }
+
+    /**
+     * Release all memory if this refSet was not provided as a configuration option.
+     * If provided as configuration option, then provider is responsible for cleanup.
+     */
+    if (options.dereference.refSet === null) {
+      immutableRefSet.clean();
+    }
+
+    mutableRefSet.clean();
+
+    return dereferencedElement;
+  }
+}
+
+export { ApiDOMDereferenceVisitor };
+export default ApiDOMDereferenceStrategy;

package/src/dereference/strategies/apidom/selectors/element-id.cjs

@@ -0,0 +1,47 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+exports.__esModule = true;
+exports.evaluate = void 0;
+var _ramdaAdjunct = require("ramda-adjunct");
+var _apidomDatamodel = require("@speclynx/apidom-datamodel");
+var _apidomCore = require("@speclynx/apidom-core");
+var _apidomTraverse = require("@speclynx/apidom-traverse");
+var _EvaluationElementIdError = _interopRequireDefault(require("../../../../errors/EvaluationElementIdError.cjs"));
+exports.EvaluationElementIdError = _EvaluationElementIdError.default;
+const getElementID = element => {
+  const id = element.meta.get('id');
+  // handle both raw string (new format) and StringElement (legacy Refract without __meta_raw__)
+  return (0, _apidomDatamodel.isElement)(id) ? (0, _apidomCore.toValue)(id) : id;
+};
+const hasElementID = path => {
+  if (!path.node.hasMetaProperty('id')) return false;
+  const id = getElementID(path.node);
+  return typeof id === 'string' && id !== '';
+};
+
+/**
+ * Evaluates element ID against ApiDOM fragment.
+ * @public
+ */
+const evaluate = (elementID, element) => {
+  const {
+    cache
+  } = evaluate;
+  // warm the cache
+  if (!cache.has(element)) {
+    const pathsWithID = (0, _apidomTraverse.filter)(element, hasElementID);
+    cache.set(element, pathsWithID.map(path => path.node));
+  }
+
+  // search for the matching element
+  const result = cache.get(element).find(e => {
+    return getElementID(e) === elementID;
+  });
+  if ((0, _ramdaAdjunct.isUndefined)(result)) {
+    throw new _EvaluationElementIdError.default(`Evaluation failed on element ID: "${elementID}"`);
+  }
+  return result;
+};
+exports.evaluate = evaluate;
+evaluate.cache = new WeakMap();

package/src/dereference/strategies/apidom/selectors/element-id.mjs

@@ -0,0 +1,41 @@
+import { isUndefined } from 'ramda-adjunct';
+import { isElement } from '@speclynx/apidom-datamodel';
+import { toValue } from '@speclynx/apidom-core';
+import { filter } from '@speclynx/apidom-traverse';
+import EvaluationElementIdError from "../../../../errors/EvaluationElementIdError.mjs";
+const getElementID = element => {
+  const id = element.meta.get('id');
+  // handle both raw string (new format) and StringElement (legacy Refract without __meta_raw__)
+  return isElement(id) ? toValue(id) : id;
+};
+const hasElementID = path => {
+  if (!path.node.hasMetaProperty('id')) return false;
+  const id = getElementID(path.node);
+  return typeof id === 'string' && id !== '';
+};
+
+/**
+ * Evaluates element ID against ApiDOM fragment.
+ * @public
+ */
+export const evaluate = (elementID, element) => {
+  const {
+    cache
+  } = evaluate;
+  // warm the cache
+  if (!cache.has(element)) {
+    const pathsWithID = filter(element, hasElementID);
+    cache.set(element, pathsWithID.map(path => path.node));
+  }
+
+  // search for the matching element
+  const result = cache.get(element).find(e => {
+    return getElementID(e) === elementID;
+  });
+  if (isUndefined(result)) {
+    throw new EvaluationElementIdError(`Evaluation failed on element ID: "${elementID}"`);
+  }
+  return result;
+};
+evaluate.cache = new WeakMap();
+export { EvaluationElementIdError };

package/src/dereference/strategies/apidom/selectors/element-id.ts

@@ -0,0 +1,48 @@
+import { isUndefined } from 'ramda-adjunct';
+import { Element, isElement } from '@speclynx/apidom-datamodel';
+import { toValue } from '@speclynx/apidom-core';
+import { filter, type Path } from '@speclynx/apidom-traverse';
+
+import EvaluationElementIdError from '../../../../errors/EvaluationElementIdError.ts';
+
+const getElementID = (element: Element): string => {
+  const id = element.meta.get('id');
+  // handle both raw string (new format) and StringElement (legacy Refract without __meta_raw__)
+  return isElement(id) ? (toValue(id) as string) : (id as string);
+};
+
+const hasElementID = (path: Path<Element>): boolean => {
+  if (!path.node.hasMetaProperty('id')) return false;
+  const id = getElementID(path.node);
+  return typeof id === 'string' && id !== '';
+};
+
+/**
+ * Evaluates element ID against ApiDOM fragment.
+ * @public
+ */
+export const evaluate = <T extends Element>(elementID: string, element: T): Element | undefined => {
+  const { cache } = evaluate;
+  // warm the cache
+  if (!cache.has(element)) {
+    const pathsWithID = filter(element, hasElementID);
+    cache.set(
+      element,
+      pathsWithID.map((path) => path.node),
+    );
+  }
+
+  // search for the matching element
+  const result = cache.get(element).find((e: Element) => {
+    return getElementID(e) === elementID;
+  });
+
+  if (isUndefined(result)) {
+    throw new EvaluationElementIdError(`Evaluation failed on element ID: "${elementID}"`);
+  }
+
+  return result;
+};
+evaluate.cache = new WeakMap();
+
+export { EvaluationElementIdError };