@speclynx/apidom-reference 4.0.1 → 4.0.3

package/src/resolve/index.ts

@@ -0,0 +1,75 @@
+import { isEmpty } from 'ramda';
+import {
+  Element,
+  isParseResultElement,
+  ParseResultElement,
+  cloneShallow,
+} from '@speclynx/apidom-datamodel';
+
+import { merge as mergeOptions } from '../options/util.ts';
+import parse from '../parse/index.ts';
+import * as plugins from '../util/plugins.ts';
+import File from '../File.ts';
+import ReferenceSet from '../ReferenceSet.ts';
+import ResolveError from '../errors/ResolverError.ts';
+import UnmatchedResolveStrategyError from '../errors/UnmatchedResolveStrategyError.ts';
+import * as url from '../util/url.ts';
+import type { ReferenceOptions } from '../options/index.ts';
+
+/**
+ * Resolves ApiDOM with all its external references.
+ */
+export const resolveApiDOM = async <T extends Element>(
+  element: T,
+  options: ReferenceOptions,
+): Promise<ReferenceSet> => {
+  // @ts-ignore
+  let parseResult: ParseResultElement = element;
+
+  // wrap element into parse result
+  if (!isParseResultElement(element)) {
+    // shallow clone of the element
+    const elementClone = cloneShallow(element);
+    elementClone.classes.push('result');
+    parseResult = new ParseResultElement([elementClone]);
+  }
+
+  const sanitizedURI = url.sanitize(url.stripHash(options.resolve.baseURI));
+  const file = new File({
+    uri: sanitizedURI,
+    parseResult,
+    mediaType: options.parse.mediaType,
+  });
+
+  const resolveStrategies = await plugins.filter(
+    'canResolve',
+    [file, options],
+    options.resolve.strategies,
+  );
+
+  // we couldn't find any resolve strategy for this File
+  if (isEmpty(resolveStrategies)) {
+    throw new UnmatchedResolveStrategyError(
+      `Could not find a resolve strategy that can resolve the file "${file.uri}"`,
+    );
+  }
+
+  try {
+    const { result } = await plugins.run('resolve', [file, options], resolveStrategies);
+    return result;
+  } catch (error: any) {
+    throw new ResolveError(`Error while resolving file "${file.uri}"`, { cause: error });
+  }
+};
+
+/**
+ * Resolves a file with all its external references.
+ */
+const resolve = async (uri: string, options: ReferenceOptions): Promise<ReferenceSet> => {
+  const parseResult = await parse(uri, options);
+  const mergedOptions = mergeOptions(options, { resolve: { baseURI: url.sanitize(uri) } });
+
+  return resolveApiDOM(parseResult, mergedOptions);
+};
+
+export default resolve;

package/src/resolve/resolvers/HTTPResolver.cjs

@@ -0,0 +1,45 @@
+"use strict";
+
+var _interopRequireWildcard = require("@babel/runtime-corejs3/helpers/interopRequireWildcard").default;
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+exports.__esModule = true;
+exports.default = void 0;
+var _Resolver = _interopRequireDefault(require("./Resolver.cjs"));
+var url = _interopRequireWildcard(require("../../util/url.cjs"));
+/**
+ * @public
+ */
+
+/**
+ * @public
+ */
+
+/**
+ * @public
+ */
+class HTTPResolver extends _Resolver.default {
+  timeout;
+  redirects;
+  withCredentials;
+  cache;
+  constructor(options) {
+    const {
+      name = 'http-resolver',
+      timeout = 5000,
+      redirects = 5,
+      withCredentials = false,
+      cache = false
+    } = options ?? {};
+    super({
+      name
+    });
+    this.timeout = timeout;
+    this.redirects = redirects;
+    this.withCredentials = withCredentials;
+    this.cache = cache;
+  }
+  canRead(file) {
+    return url.isHttpUrl(file.uri);
+  }
+}
+var _default = exports.default = HTTPResolver;

package/src/resolve/resolvers/HTTPResolver.mjs

@@ -0,0 +1,37 @@
+import Resolver from "./Resolver.mjs";
+import * as url from "../../util/url.mjs";
+/**
+ * @public
+ */
+/**
+ * @public
+ */
+/**
+ * @public
+ */
+class HTTPResolver extends Resolver {
+  timeout;
+  redirects;
+  withCredentials;
+  cache;
+  constructor(options) {
+    const {
+      name = 'http-resolver',
+      timeout = 5000,
+      redirects = 5,
+      withCredentials = false,
+      cache = false
+    } = options ?? {};
+    super({
+      name
+    });
+    this.timeout = timeout;
+    this.redirects = redirects;
+    this.withCredentials = withCredentials;
+    this.cache = cache;
+  }
+  canRead(file) {
+    return url.isHttpUrl(file.uri);
+  }
+}
+export default HTTPResolver;

package/src/resolve/resolvers/HTTPResolver.ts

@@ -0,0 +1,58 @@
+import Resolver, { ResolverOptions } from './Resolver.ts';
+import * as url from '../../util/url.ts';
+import File from '../../File.ts';
+
+/**
+ * @public
+ */
+export interface CacheOptions {
+  readonly maxEntries?: number | false;
+  readonly maxStaleAge?: number | false;
+}
+
+/**
+ * @public
+ */
+export interface HTTPResolverOptions extends ResolverOptions {
+  readonly timeout?: number;
+  readonly redirects?: number;
+  readonly withCredentials?: boolean;
+  readonly cache?: boolean | CacheOptions;
+}
+
+/**
+ * @public
+ */
+abstract class HTTPResolver extends Resolver {
+  protected readonly timeout: number;
+
+  protected readonly redirects: number;
+
+  protected readonly withCredentials: boolean;
+
+  protected readonly cache: boolean | CacheOptions;
+
+  constructor(options?: HTTPResolverOptions) {
+    const {
+      name = 'http-resolver',
+      timeout = 5000,
+      redirects = 5,
+      withCredentials = false,
+      cache = false,
+    } = options ?? {};
+
+    super({ name });
+    this.timeout = timeout;
+    this.redirects = redirects;
+    this.withCredentials = withCredentials;
+    this.cache = cache;
+  }
+
+  canRead(file: File): boolean {
+    return url.isHttpUrl(file.uri);
+  }
+
+  abstract getHttpClient(): unknown;
+}
+
+export default HTTPResolver;

package/src/resolve/resolvers/Resolver.cjs

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

package/src/resolve/resolvers/Resolver.mjs

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

package/src/resolve/resolvers/Resolver.ts

@@ -0,0 +1,25 @@
+import File from '../../File.ts';
+import type { ReferenceOptions } from '../../options/index.ts';
+
+/**
+ * @public
+ */
+export interface ResolverOptions {
+  readonly name: string;
+}
+
+/**
+ * @public
+ */
+abstract class Resolver {
+  public readonly name: string;
+
+  constructor({ name }: ResolverOptions) {
+    this.name = name;
+  }
+
+  public abstract canRead(file: File, options?: ReferenceOptions): boolean;
+  public abstract read(file: File, options?: ReferenceOptions): Promise<Buffer>;
+}
+
+export default Resolver;

package/src/resolve/resolvers/file/index-browser.cjs

@@ -0,0 +1,24 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+exports.__esModule = true;
+exports.default = void 0;
+var _Resolver = _interopRequireDefault(require("../Resolver.cjs"));
+var _ResolverError = _interopRequireDefault(require("../../../errors/ResolverError.cjs"));
+/**
+ * @public
+ */
+class FileResolver extends _Resolver.default {
+  constructor() {
+    super({
+      name: 'file'
+    });
+  }
+  canRead() {
+    return false;
+  }
+  read() {
+    throw new _ResolverError.default('FileResolver is not intended to be used in browser context');
+  }
+}
+var _default = exports.default = FileResolver;

package/src/resolve/resolvers/file/index-browser.mjs

@@ -0,0 +1,19 @@
+import Resolver from "../Resolver.mjs";
+import ResolverError from "../../../errors/ResolverError.mjs";
+/**
+ * @public
+ */
+class FileResolver extends Resolver {
+  constructor() {
+    super({
+      name: 'file'
+    });
+  }
+  canRead() {
+    return false;
+  }
+  read() {
+    throw new ResolverError('FileResolver is not intended to be used in browser context');
+  }
+}
+export default FileResolver;

package/src/resolve/resolvers/file/index-browser.ts

@@ -0,0 +1,24 @@
+import Resolver from '../Resolver.ts';
+import ResolverError from '../../../errors/ResolverError.ts';
+
+export type { default as Resolver, ResolverOptions } from '../Resolver.ts';
+export type { default as File, FileOptions } from '../../../File.ts';
+
+/**
+ * @public
+ */
+class FileResolver extends Resolver {
+  constructor() {
+    super({ name: 'file' });
+  }
+
+  canRead(): boolean {
+    return false;
+  }
+
+  read(): Promise<Buffer> {
+    throw new ResolverError('FileResolver is not intended to be used in browser context');
+  }
+}
+
+export default FileResolver;

package/src/resolve/resolvers/file/index-node.cjs

@@ -0,0 +1,49 @@
+"use strict";
+
+var _interopRequireWildcard = require("@babel/runtime-corejs3/helpers/interopRequireWildcard").default;
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+exports.__esModule = true;
+exports.default = void 0;
+var _nodeFs = require("node:fs");
+var _nodeUtil = require("node:util");
+var _picomatch = _interopRequireDefault(require("picomatch"));
+var _Resolver = _interopRequireDefault(require("../Resolver.cjs"));
+var url = _interopRequireWildcard(require("../../../util/url.cjs"));
+var _ResolverError = _interopRequireDefault(require("../../../errors/ResolverError.cjs"));
+/**
+ * @public
+ */
+
+/**
+ * @public
+ */
+class FileResolver extends _Resolver.default {
+  fileAllowList;
+  constructor(options) {
+    const {
+      fileAllowList = []
+    } = options ?? {};
+    super({
+      name: 'file'
+    });
+    this.fileAllowList = fileAllowList;
+  }
+  canRead(file) {
+    return url.isFileSystemPath(file.uri) && this.fileAllowList.some(pattern => {
+      return typeof pattern === 'string' ? _picomatch.default.isMatch(file.uri, pattern, {
+        matchBase: true
+      }) : pattern.test(file.uri);
+    });
+  }
+  async read(file) {
+    const fileSystemPath = url.toFileSystemPath(file.uri);
+    try {
+      return await (0, _nodeUtil.promisify)(_nodeFs.readFile)(fileSystemPath);
+    } catch (error) {
+      throw new _ResolverError.default(`Error opening file "${file.uri}"`, {
+        cause: error
+      });
+    }
+  }
+}
+var _default = exports.default = FileResolver;

package/src/resolve/resolvers/file/index-node.mjs

@@ -0,0 +1,42 @@
+import { readFile } from 'node:fs';
+import { promisify } from 'node:util';
+import picomatch from 'picomatch';
+import Resolver from "../Resolver.mjs";
+import * as url from "../../../util/url.mjs";
+import ResolverError from "../../../errors/ResolverError.mjs";
+/**
+ * @public
+ */
+/**
+ * @public
+ */
+class FileResolver extends Resolver {
+  fileAllowList;
+  constructor(options) {
+    const {
+      fileAllowList = []
+    } = options ?? {};
+    super({
+      name: 'file'
+    });
+    this.fileAllowList = fileAllowList;
+  }
+  canRead(file) {
+    return url.isFileSystemPath(file.uri) && this.fileAllowList.some(pattern => {
+      return typeof pattern === 'string' ? picomatch.isMatch(file.uri, pattern, {
+        matchBase: true
+      }) : pattern.test(file.uri);
+    });
+  }
+  async read(file) {
+    const fileSystemPath = url.toFileSystemPath(file.uri);
+    try {
+      return await promisify(readFile)(fileSystemPath);
+    } catch (error) {
+      throw new ResolverError(`Error opening file "${file.uri}"`, {
+        cause: error
+      });
+    }
+  }
+}
+export default FileResolver;

package/src/resolve/resolvers/file/index-node.ts

@@ -0,0 +1,55 @@
+import { readFile } from 'node:fs';
+import { promisify } from 'node:util';
+import picomatch from 'picomatch';
+
+import File from '../../../File.ts';
+import Resolver, { ResolverOptions } from '../Resolver.ts';
+import * as url from '../../../util/url.ts';
+import ResolverError from '../../../errors/ResolverError.ts';
+
+export type { default as Resolver, ResolverOptions } from '../Resolver.ts';
+export type { default as File, FileOptions } from '../../../File.ts';
+
+/**
+ * @public
+ */
+export interface FileResolverOptions extends Omit<ResolverOptions, 'name'> {
+  readonly fileAllowList?: string[] | RegExp[];
+}
+
+/**
+ * @public
+ */
+class FileResolver extends Resolver {
+  public fileAllowList: string[] | RegExp[];
+
+  constructor(options?: FileResolverOptions) {
+    const { fileAllowList = [] } = options ?? {};
+
+    super({ name: 'file' });
+    this.fileAllowList = fileAllowList;
+  }
+
+  canRead(file: File): boolean {
+    return (
+      url.isFileSystemPath(file.uri) &&
+      this.fileAllowList.some((pattern) => {
+        return typeof pattern === 'string'
+          ? picomatch.isMatch(file.uri, pattern, { matchBase: true })
+          : pattern.test(file.uri);
+      })
+    );
+  }
+
+  async read(file: File): Promise<Buffer> {
+    const fileSystemPath = url.toFileSystemPath(file.uri);
+
+    try {
+      return await promisify(readFile)(fileSystemPath);
+    } catch (error: unknown) {
+      throw new ResolverError(`Error opening file "${file.uri}"`, { cause: error });
+    }
+  }
+}
+
+export default FileResolver;

package/src/resolve/resolvers/http-axios/cache/MemoryCache.cjs

@@ -0,0 +1,41 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = void 0;
+class MemoryCache {
+  maxEntries;
+  maxStaleAge;
+  store = new Map();
+  constructor(options = {}) {
+    const {
+      maxEntries = 1024,
+      maxStaleAge = 3_600_000
+    } = options;
+    this.maxEntries = maxEntries;
+    this.maxStaleAge = maxStaleAge;
+  }
+  get(key) {
+    const entry = this.store.get(key);
+    if (entry === undefined) return undefined;
+
+    // evict if entry has exceeded maxStaleAge
+    if (this.maxStaleAge !== false && Date.now() - entry.createdAt > this.maxStaleAge) {
+      this.store.delete(key);
+      return undefined;
+    }
+    return entry.value;
+  }
+  set(key, value) {
+    this.store.set(key, {
+      value,
+      createdAt: Date.now()
+    });
+
+    // evict oldest entries if maxEntries exceeded
+    if (this.maxEntries !== false && this.store.size > this.maxEntries) {
+      const firstKey = this.store.keys().next().value;
+      this.store.delete(firstKey);
+    }
+  }
+}
+var _default = exports.default = MemoryCache;

package/src/resolve/resolvers/http-axios/cache/MemoryCache.mjs

@@ -0,0 +1,37 @@
+class MemoryCache {
+  maxEntries;
+  maxStaleAge;
+  store = new Map();
+  constructor(options = {}) {
+    const {
+      maxEntries = 1024,
+      maxStaleAge = 3_600_000
+    } = options;
+    this.maxEntries = maxEntries;
+    this.maxStaleAge = maxStaleAge;
+  }
+  get(key) {
+    const entry = this.store.get(key);
+    if (entry === undefined) return undefined;
+
+    // evict if entry has exceeded maxStaleAge
+    if (this.maxStaleAge !== false && Date.now() - entry.createdAt > this.maxStaleAge) {
+      this.store.delete(key);
+      return undefined;
+    }
+    return entry.value;
+  }
+  set(key, value) {
+    this.store.set(key, {
+      value,
+      createdAt: Date.now()
+    });
+
+    // evict oldest entries if maxEntries exceeded
+    if (this.maxEntries !== false && this.store.size > this.maxEntries) {
+      const firstKey = this.store.keys().next().value;
+      this.store.delete(firstKey);
+    }
+  }
+}
+export default MemoryCache;

package/src/resolve/resolvers/http-axios/cache/MemoryCache.ts

@@ -0,0 +1,46 @@
+import type { CacheOptions } from '../../HTTPResolver.ts';
+
+interface CacheEntry<T> {
+  value: T;
+  createdAt: number;
+}
+
+class MemoryCache<T> {
+  protected maxEntries: number | false;
+
+  protected maxStaleAge: number | false;
+
+  protected readonly store: Map<string, CacheEntry<T>> = new Map();
+
+  constructor(options: CacheOptions = {}) {
+    const { maxEntries = 1024, maxStaleAge = 3_600_000 } = options;
+
+    this.maxEntries = maxEntries;
+    this.maxStaleAge = maxStaleAge;
+  }
+
+  get(key: string): T | undefined {
+    const entry = this.store.get(key);
+    if (entry === undefined) return undefined;
+
+    // evict if entry has exceeded maxStaleAge
+    if (this.maxStaleAge !== false && Date.now() - entry.createdAt > this.maxStaleAge) {
+      this.store.delete(key);
+      return undefined;
+    }
+
+    return entry.value;
+  }
+
+  set(key: string, value: T): void {
+    this.store.set(key, { value, createdAt: Date.now() });
+
+    // evict oldest entries if maxEntries exceeded
+    if (this.maxEntries !== false && this.store.size > this.maxEntries) {
+      const firstKey = this.store.keys().next().value as string;
+      this.store.delete(firstKey);
+    }
+  }
+}
+
+export default MemoryCache;