@speclynx/apidom-reference 4.0.3 → 4.0.4

package/src/parse/parsers/yaml-1-2/index.ts

@@ -1,60 +0,0 @@
-import { ParseResultElement } from '@speclynx/apidom-datamodel';
-import {
-  parse,
-  mediaTypes as YAMLMediaTypes,
-  detect,
-} from '@speclynx/apidom-parser-adapter-yaml-1-2';
-
-import ParserError from '../../../errors/ParserError.ts';
-import Parser, { ParserOptions } from '../Parser.ts';
-import File from '../../../File.ts';
-
-export type { default as Parser, ParserOptions } from '../Parser.ts';
-export type { default as File, FileOptions } from '../../../File.ts';
-
-/**
- * @public
- */
-export interface YAMLParserOptions extends Omit<ParserOptions, 'name'> {}
-
-/**
- * @public
- */
-class YAML1Parser extends Parser {
-  public refractorOpts!: object;
-
-  constructor(options?: YAMLParserOptions) {
-    const { fileExtensions = [], mediaTypes = YAMLMediaTypes, ...rest } = options ?? {};
-
-    super({ ...rest, name: 'yaml-1-2', fileExtensions, mediaTypes });
-  }
-
-  async canParse(file: File): Promise<boolean> {
-    const hasSupportedFileExtension =
-      this.fileExtensions.length === 0 ? true : this.fileExtensions.includes(file.extension);
-    const hasSupportedMediaType = this.mediaTypes.includes(file.mediaType);
-
-    if (!hasSupportedFileExtension) return false;
-    if (hasSupportedMediaType) return true;
-    if (!hasSupportedMediaType) {
-      return detect(file.toString());
-    }
-    return false;
-  }
-
-  async parse(file: File): Promise<ParseResultElement> {
-    const source = file.toString();
-
-    try {
-      return await parse(source, {
-        sourceMap: this.sourceMap,
-        style: this.style,
-        strict: this.strict,
-      });
-    } catch (error: unknown) {
-      throw new ParserError(`Error parsing "${file.uri}"`, { cause: error });
-    }
-  }
-}
-
-export default YAML1Parser;

package/src/resolve/index.ts

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

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

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

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

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

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

package/src/resolve/resolvers/http-axios/index.ts

@@ -1,130 +0,0 @@
-import { omit } from 'ramda';
-import { ensureArray, isPlainObject } from 'ramda-adjunct';
-import axios, { Axios, AxiosInstance, CreateAxiosDefaults } from 'axios';
-
-import HTTPResolver, { HTTPResolverOptions } from '../HTTPResolver.ts';
-import MemoryCache from './cache/MemoryCache.ts';
-import File from '../../../File.ts';
-import ResolverError from '../../../errors/ResolverError.ts';
-import * as url from '../../../util/url.ts';
-
-export type {
-  default as HTTPResolver,
-  HTTPResolverOptions,
-  CacheOptions,
-} from '../HTTPResolver.ts';
-export type { default as Resolver, ResolverOptions } from '../Resolver.ts';
-export type { default as File, FileOptions } from '../../../File.ts';
-
-/**
- * @public
- */
-export interface HTTPResolverAxiosConfig extends CreateAxiosDefaults {
-  interceptors?: Axios['interceptors'];
-}
-
-/**
- * @public
- */
-export interface HTTPResolverAxiosOptions extends Omit<HTTPResolverOptions, 'name'> {
-  readonly axiosConfig?: HTTPResolverAxiosConfig;
-}
-
-/**
- * @public
- */
-class HTTPResolverAxios extends HTTPResolver {
-  public axiosConfig: HTTPResolverAxiosConfig = {};
-
-  protected axiosInstance!: AxiosInstance;
-
-  protected previousAxiosConfig!: HTTPResolverAxiosConfig;
-
-  protected cacheStore: MemoryCache<Buffer>;
-
-  protected previousCache!: typeof this.cache;
-
-  constructor(options?: HTTPResolverAxiosOptions) {
-    const { axiosConfig = {}, ...rest } = options ?? {};
-
-    super({ ...rest, name: 'http-axios' });
-    this.axiosConfig = axiosConfig;
-    this.cacheStore = new MemoryCache(isPlainObject(this.cache) ? this.cache : {});
-  }
-
-  getHttpClient(): AxiosInstance {
-    if (this.axiosInstance === undefined || this.previousAxiosConfig !== this.axiosConfig) {
-      const config = omit(['interceptors'], this.axiosConfig);
-      const { interceptors } = this.axiosConfig;
-
-      this.axiosInstance = axios.create({
-        timeout: this.timeout,
-        maxRedirects: this.redirects,
-        withCredentials: this.withCredentials,
-        responseType: 'arraybuffer',
-        ...config,
-      });
-
-      // settings up request interceptors
-      if (Array.isArray(interceptors?.request)) {
-        interceptors.request.forEach((requestInterceptor) => {
-          this.axiosInstance.interceptors.request.use(...ensureArray(requestInterceptor));
-        });
-      }
-
-      // settings up response interceptors
-      if (Array.isArray(interceptors?.response)) {
-        interceptors.response.forEach((responseInterceptor: any) => {
-          this.axiosInstance.interceptors.response.use(...ensureArray(responseInterceptor));
-        });
-      }
-
-      this.previousAxiosConfig = this.axiosConfig;
-    }
-
-    return this.axiosInstance;
-  }
-
-  /**
-   * Ensures cacheStore is config-isolated for cloned resolvers.
-   * When a resolver is cloned via Object.create (in readFile), the clone inherits
-   * cacheStore from the prototype. Object.create(cacheStore) creates a view that
-   * shares the underlying store Map but allows isolated config (maxEntries, maxStaleAge)
-   * via own properties set by Object.assign.
-   */
-  protected getCacheStore(): MemoryCache<Buffer> {
-    if (this.previousCache !== this.cache) {
-      if (!Object.hasOwn(this, 'cacheStore')) {
-        this.cacheStore = Object.create(this.cacheStore) as MemoryCache<Buffer>;
-      }
-      if (isPlainObject(this.cache)) {
-        Object.assign(this.cacheStore, this.cache);
-      }
-
-      this.previousCache = this.cache;
-    }
-
-    return this.cacheStore;
-  }
-
-  async read(file: File): Promise<Buffer> {
-    const uri = url.stripHash(file.uri);
-    const cacheStore = this.cache ? this.getCacheStore() : undefined;
-
-    // return cached content if available
-    const cached = cacheStore?.get(uri);
-    if (cached !== undefined) return cached;
-
-    const client: AxiosInstance = this.getHttpClient();
-
-    try {
-      const response = await client.get<Buffer>(uri);
-      cacheStore?.set(uri, response.data);
-      return response.data;
-    } catch (error: unknown) {
-      throw new ResolverError(`Error downloading "${file.uri}"`, { cause: error });
-    }
-  }
-}
-
-export default HTTPResolverAxios;

package/src/resolve/strategies/ResolveStrategy.ts

@@ -1,26 +0,0 @@
-import File from '../../File.ts';
-import ReferenceSet from '../../ReferenceSet.ts';
-import type { ReferenceOptions } from '../../options/index.ts';
-
-/**
- * @public
- */
-export interface ResolveStrategyOptions {
-  readonly name: string;
-}
-
-/**
- * @public
- */
-abstract class ResolveStrategy {
-  public readonly name: string;
-
-  constructor({ name }: ResolveStrategyOptions) {
-    this.name = name;
-  }
-
-  abstract canResolve(file: File, options: ReferenceOptions): boolean;
-  abstract resolve(file: File, options: ReferenceOptions): Promise<ReferenceSet>;
-}
-
-export default ResolveStrategy;

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

@@ -1,78 +0,0 @@
-import ResolveStrategy, { ResolveStrategyOptions } from '../ResolveStrategy.ts';
-import ReferenceSet from '../../../ReferenceSet.ts';
-import File from '../../../File.ts';
-import { merge as mergeOptions } from '../../../options/util.ts';
-import UnmatchedDereferenceStrategyError from '../../../errors/UnmatchedDereferenceStrategyError.ts';
-import type { ReferenceOptions } from '../../../options/index.ts';
-
-export type { default as ResolveStrategy, ResolveStrategyOptions } from '../ResolveStrategy.ts';
-export type { default as ReferenceSet, ReferenceSetOptions } from '../../../ReferenceSet.ts';
-export type { default as File, FileOptions } from '../../../File.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 '../../resolvers/Resolver.ts';
-export type {
-  default as DereferenceStrategy,
-  DereferenceStrategyOptions,
-} from '../../../dereference/strategies/DereferenceStrategy.ts';
-export type {
-  default as BundleStrategy,
-  BundleStrategyOptions,
-} from '../../../bundle/strategies/BundleStrategy.ts';
-export type { default as Reference, ReferenceOptions } from '../../../Reference.ts';
-
-/**
- * @public
- */
-export interface ApiDOMResolveStrategyOptions extends Omit<ResolveStrategyOptions, 'name'> {}
-
-/**
- * @public
- */
-class ApiDOMResolveStrategy extends ResolveStrategy {
-  constructor(options?: ApiDOMResolveStrategyOptions) {
-    super({ ...(options ?? {}), name: 'apidom' });
-  }
-
-  canResolve(file: File, options: ReferenceOptions): boolean {
-    const dereferenceStrategy = options.dereference.strategies.find(
-      (strategy) => strategy.name === 'apidom',
-    );
-
-    if (dereferenceStrategy === undefined) {
-      return false;
-    }
-
-    return dereferenceStrategy.canDereference(file, options);
-  }
-
-  async resolve(file: File, options: ReferenceOptions) {
-    const dereferenceStrategy = options.dereference.strategies.find(
-      (strategy) => strategy.name === 'apidom',
-    );
-
-    if (dereferenceStrategy === undefined) {
-      throw new UnmatchedDereferenceStrategyError(
-        `"apidom" resolve strategy requires "apidom" dereference strategy to be configured for file "${file.uri}"`,
-      );
-    }
-
-    const refSet = new ReferenceSet();
-    const mergedOptions = mergeOptions(options, {
-      resolve: { internal: false },
-      dereference: { refSet },
-    });
-
-    await dereferenceStrategy.dereference(file, mergedOptions);
-
-    return refSet;
-  }
-}
-
-export default ApiDOMResolveStrategy;

package/src/resolve/strategies/asyncapi-2/index.ts

@@ -1,78 +0,0 @@
-import ResolveStrategy, { ResolveStrategyOptions } from '../ResolveStrategy.ts';
-import ReferenceSet from '../../../ReferenceSet.ts';
-import File from '../../../File.ts';
-import { merge as mergeOptions } from '../../../options/util.ts';
-import UnmatchedDereferenceStrategyError from '../../../errors/UnmatchedDereferenceStrategyError.ts';
-import type { ReferenceOptions } from '../../../options/index.ts';
-
-export type { default as ResolveStrategy, ResolveStrategyOptions } from '../ResolveStrategy.ts';
-export type { default as ReferenceSet, ReferenceSetOptions } from '../../../ReferenceSet.ts';
-export type { default as File, FileOptions } from '../../../File.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 '../../resolvers/Resolver.ts';
-export type {
-  default as DereferenceStrategy,
-  DereferenceStrategyOptions,
-} from '../../../dereference/strategies/DereferenceStrategy.ts';
-export type {
-  default as BundleStrategy,
-  BundleStrategyOptions,
-} from '../../../bundle/strategies/BundleStrategy.ts';
-export type { default as Reference, ReferenceOptions } from '../../../Reference.ts';
-
-/**
- * @public
- */
-export interface AsyncAPI2ResolveStrategyOptions extends Omit<ResolveStrategyOptions, 'name'> {}
-
-/**
- * @public
- */
-class AsyncAPI2ResolveStrategy extends ResolveStrategy {
-  constructor(options?: AsyncAPI2ResolveStrategyOptions) {
-    super({ ...(options ?? {}), name: 'asyncapi-2' });
-  }
-
-  canResolve(file: File, options: ReferenceOptions) {
-    const dereferenceStrategy = options.dereference.strategies.find(
-      (strategy) => strategy.name === 'asyncapi-2',
-    );
-
-    if (dereferenceStrategy === undefined) {
-      return false;
-    }
-
-    return dereferenceStrategy.canDereference(file, options);
-  }
-
-  async resolve(file: File, options: ReferenceOptions) {
-    const dereferenceStrategy = options.dereference.strategies.find(
-      (strategy) => strategy.name === 'asyncapi-2',
-    );
-
-    if (dereferenceStrategy === undefined) {
-      throw new UnmatchedDereferenceStrategyError(
-        `"asyncapi-2" resolve strategy requires "asyncapi-2" dereference strategy to be configured for file "${file.uri}"`,
-      );
-    }
-
-    const refSet = new ReferenceSet();
-    const mergedOptions = mergeOptions(options, {
-      resolve: { internal: false },
-      dereference: { refSet },
-    });
-
-    await dereferenceStrategy.dereference(file, mergedOptions);
-
-    return refSet;
-  }
-}
-
-export default AsyncAPI2ResolveStrategy;