@speclynx/apidom-reference 2.12.3 → 2.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@speclynx/apidom-reference",
-  "version": "2.12.3",
+  "version": "2.13.0",
   "description": "Advanced algorithms for semantic ApiDOM manipulations like dereferencing or resolution.",
   "publishConfig": {
     "access": "public",
@@ -231,31 +231,31 @@
   "license": "Apache-2.0",
   "dependencies": {
     "@babel/runtime-corejs3": "^7.28.4",
-    "@speclynx/apidom-core": "2.12.3",
-    "@speclynx/apidom-datamodel": "2.12.3",
-    "@speclynx/apidom-error": "2.12.3",
-    "@speclynx/apidom-json-pointer": "2.12.3",
-    "@speclynx/apidom-ns-arazzo-1": "2.12.3",
-    "@speclynx/apidom-ns-asyncapi-2": "2.12.3",
-    "@speclynx/apidom-ns-json-schema-2020-12": "2.12.3",
-    "@speclynx/apidom-ns-openapi-2": "2.12.3",
-    "@speclynx/apidom-ns-openapi-3-0": "2.12.3",
-    "@speclynx/apidom-ns-openapi-3-1": "2.12.3",
-    "@speclynx/apidom-parser-adapter-arazzo-json-1": "2.12.3",
-    "@speclynx/apidom-parser-adapter-arazzo-yaml-1": "2.12.3",
-    "@speclynx/apidom-parser-adapter-asyncapi-json-2": "2.12.3",
-    "@speclynx/apidom-parser-adapter-asyncapi-yaml-2": "2.12.3",
-    "@speclynx/apidom-parser-adapter-json": "2.12.3",
-    "@speclynx/apidom-parser-adapter-openapi-json-2": "2.12.3",
-    "@speclynx/apidom-parser-adapter-openapi-json-3-0": "2.12.3",
-    "@speclynx/apidom-parser-adapter-openapi-json-3-1": "2.12.3",
-    "@speclynx/apidom-parser-adapter-openapi-yaml-2": "2.12.3",
-    "@speclynx/apidom-parser-adapter-openapi-yaml-3-0": "2.12.3",
-    "@speclynx/apidom-parser-adapter-openapi-yaml-3-1": "2.12.3",
-    "@speclynx/apidom-parser-adapter-yaml-1-2": "2.12.3",
-    "@speclynx/apidom-traverse": "2.12.3",
+    "@speclynx/apidom-core": "2.13.0",
+    "@speclynx/apidom-datamodel": "2.13.0",
+    "@speclynx/apidom-error": "2.13.0",
+    "@speclynx/apidom-json-pointer": "2.13.0",
+    "@speclynx/apidom-ns-arazzo-1": "2.13.0",
+    "@speclynx/apidom-ns-asyncapi-2": "2.13.0",
+    "@speclynx/apidom-ns-json-schema-2020-12": "2.13.0",
+    "@speclynx/apidom-ns-openapi-2": "2.13.0",
+    "@speclynx/apidom-ns-openapi-3-0": "2.13.0",
+    "@speclynx/apidom-ns-openapi-3-1": "2.13.0",
+    "@speclynx/apidom-parser-adapter-arazzo-json-1": "2.13.0",
+    "@speclynx/apidom-parser-adapter-arazzo-yaml-1": "2.13.0",
+    "@speclynx/apidom-parser-adapter-asyncapi-json-2": "2.13.0",
+    "@speclynx/apidom-parser-adapter-asyncapi-yaml-2": "2.13.0",
+    "@speclynx/apidom-parser-adapter-json": "2.13.0",
+    "@speclynx/apidom-parser-adapter-openapi-json-2": "2.13.0",
+    "@speclynx/apidom-parser-adapter-openapi-json-3-0": "2.13.0",
+    "@speclynx/apidom-parser-adapter-openapi-json-3-1": "2.13.0",
+    "@speclynx/apidom-parser-adapter-openapi-yaml-2": "2.13.0",
+    "@speclynx/apidom-parser-adapter-openapi-yaml-3-0": "2.13.0",
+    "@speclynx/apidom-parser-adapter-openapi-yaml-3-1": "2.13.0",
+    "@speclynx/apidom-parser-adapter-yaml-1-2": "2.13.0",
+    "@speclynx/apidom-traverse": "2.13.0",
     "@swaggerexpert/arazzo-runtime-expression": "^2.0.3",
-    "axios": "^1.13.0",
+    "axios": "^1.13.5",
     "picomatch": "^4.0.3",
     "process": "^0.11.10",
     "ramda": "~0.32.0",
@@ -275,5 +275,5 @@
     "README.md",
     "CHANGELOG.md"
   ],
-  "gitHead": "d2fa8fd38db1ab53534fef4d812d261cf92945ab"
+  "gitHead": "3c92eda7e227426c3a40c918c418c14dc20fca7e"
 }

package/src/resolve/resolvers/HTTPResolver.cjs

@@ -10,6 +10,10 @@ var url = _interopRequireWildcard(require("../../util/url.cjs"));
  * @public
  */
 
+/**
+ * @public
+ */
+
 /**
  * @public
  */
@@ -17,12 +21,14 @@ class HTTPResolver extends _Resolver.default {
   timeout;
   redirects;
   withCredentials;
+  cache;
   constructor(options) {
     const {
       name = 'http-resolver',
       timeout = 5000,
       redirects = 5,
-      withCredentials = false
+      withCredentials = false,
+      cache = false
     } = options ?? {};
     super({
       name
@@ -30,6 +36,7 @@ class HTTPResolver extends _Resolver.default {
     this.timeout = timeout;
     this.redirects = redirects;
     this.withCredentials = withCredentials;
+    this.cache = cache;
   }
   canRead(file) {
     return url.isHttpUrl(file.uri);

package/src/resolve/resolvers/HTTPResolver.mjs

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

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

@@ -0,0 +1,44 @@
+"use strict";
+
+exports.__esModule = true;
+exports.default = void 0;
+/**
+ * @public
+ */
+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,40 @@
+/**
+ * @public
+ */
+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/index.cjs

@@ -1,5 +1,6 @@
 "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;
@@ -7,7 +8,9 @@ var _ramda = require("ramda");
 var _ramdaAdjunct = require("ramda-adjunct");
 var _axios = _interopRequireDefault(require("axios"));
 var _HTTPResolver = _interopRequireDefault(require("../HTTPResolver.cjs"));
+var _MemoryCache = _interopRequireDefault(require("./cache/MemoryCache.cjs"));
 var _ResolverError = _interopRequireDefault(require("../../../errors/ResolverError.cjs"));
+var url = _interopRequireWildcard(require("../../../util/url.cjs"));
 /**
  * @public
  */
@@ -23,6 +26,8 @@ class HTTPResolverAxios extends _HTTPResolver.default {
   axiosConfig = {};
   axiosInstance;
   previousAxiosConfig;
+  cacheStore;
+  previousCache;
   constructor(options) {
     const {
       axiosConfig = {},
@@ -33,6 +38,7 @@ class HTTPResolverAxios extends _HTTPResolver.default {
       name: 'http-axios'
     });
     this.axiosConfig = axiosConfig;
+    this.cacheStore = new _MemoryCache.default((0, _ramdaAdjunct.isPlainObject)(this.cache) ? this.cache : {});
   }
   getHttpClient() {
     if (this.axiosInstance === undefined || this.previousAxiosConfig !== this.axiosConfig) {
@@ -65,10 +71,37 @@ class HTTPResolverAxios extends _HTTPResolver.default {
     }
     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.
+   */
+  getCacheStore() {
+    if (this.previousCache !== this.cache) {
+      if (!Object.hasOwn(this, 'cacheStore')) {
+        this.cacheStore = Object.create(this.cacheStore);
+      }
+      if ((0, _ramdaAdjunct.isPlainObject)(this.cache)) {
+        Object.assign(this.cacheStore, this.cache);
+      }
+      this.previousCache = this.cache;
+    }
+    return this.cacheStore;
+  }
   async read(file) {
+    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 = this.getHttpClient();
     try {
-      const response = await client.get(file.uri);
+      const response = await client.get(uri);
+      cacheStore?.set(uri, response.data);
       return response.data;
     } catch (error) {
       throw new _ResolverError.default(`Error downloading "${file.uri}"`, {

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

@@ -1,8 +1,10 @@
 import { omit } from 'ramda';
-import { ensureArray } from 'ramda-adjunct';
+import { ensureArray, isPlainObject } from 'ramda-adjunct';
 import axios from 'axios';
 import HTTPResolver from "../HTTPResolver.mjs";
+import MemoryCache from "./cache/MemoryCache.mjs";
 import ResolverError from "../../../errors/ResolverError.mjs";
+import * as url from "../../../util/url.mjs";
 /**
  * @public
  */
@@ -16,6 +18,8 @@ class HTTPResolverAxios extends HTTPResolver {
   axiosConfig = {};
   axiosInstance;
   previousAxiosConfig;
+  cacheStore;
+  previousCache;
   constructor(options) {
     const {
       axiosConfig = {},
@@ -26,6 +30,7 @@ class HTTPResolverAxios extends HTTPResolver {
       name: 'http-axios'
     });
     this.axiosConfig = axiosConfig;
+    this.cacheStore = new MemoryCache(isPlainObject(this.cache) ? this.cache : {});
   }
   getHttpClient() {
     if (this.axiosInstance === undefined || this.previousAxiosConfig !== this.axiosConfig) {
@@ -58,10 +63,37 @@ class HTTPResolverAxios extends HTTPResolver {
     }
     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.
+   */
+  getCacheStore() {
+    if (this.previousCache !== this.cache) {
+      if (!Object.hasOwn(this, 'cacheStore')) {
+        this.cacheStore = Object.create(this.cacheStore);
+      }
+      if (isPlainObject(this.cache)) {
+        Object.assign(this.cacheStore, this.cache);
+      }
+      this.previousCache = this.cache;
+    }
+    return this.cacheStore;
+  }
   async read(file) {
+    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 = this.getHttpClient();
     try {
-      const response = await client.get(file.uri);
+      const response = await client.get(uri);
+      cacheStore?.set(uri, response.data);
       return response.data;
     } catch (error) {
       throw new ResolverError(`Error downloading "${file.uri}"`, {

package/types/apidom-reference.d.ts

@@ -86,6 +86,14 @@ export declare interface BundleStrategyOptions {
     readonly name: string;
 }
 
+/**
+ * @public
+ */
+declare interface CacheOptions {
+    readonly maxEntries?: number | false;
+    readonly maxStaleAge?: number | false;
+}
+
 /**
  * Returns the current working directory (in Node) or the current page URL (in browsers).
  * @public
@@ -227,6 +235,7 @@ export declare 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);
     canRead(file: File_2): boolean;
     abstract getHttpClient(): unknown;
@@ -239,6 +248,7 @@ export declare interface HTTPResolverOptions extends ResolverOptions {
     readonly timeout?: number;
     readonly redirects?: number;
     readonly withCredentials?: boolean;
+    readonly cache?: boolean | CacheOptions;
 }
 
 /**

package/types/resolve/resolvers/HTTPResolver.d.ts

@@ -1,5 +1,12 @@
 import Resolver, { ResolverOptions } from './Resolver.ts';
 import File from '../../File.ts';
+/**
+ * @public
+ */
+export interface CacheOptions {
+    readonly maxEntries?: number | false;
+    readonly maxStaleAge?: number | false;
+}
 /**
  * @public
  */
@@ -7,6 +14,7 @@ export interface HTTPResolverOptions extends ResolverOptions {
     readonly timeout?: number;
     readonly redirects?: number;
     readonly withCredentials?: boolean;
+    readonly cache?: boolean | CacheOptions;
 }
 /**
  * @public
@@ -15,6 +23,7 @@ declare 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);
     canRead(file: File): boolean;
     abstract getHttpClient(): unknown;

package/types/resolve/resolvers/http-axios/cache/MemoryCache.d.ts

@@ -0,0 +1,17 @@
+import type { CacheOptions } from '../../HTTPResolver.ts';
+interface CacheEntry<T> {
+    value: T;
+    createdAt: number;
+}
+/**
+ * @public
+ */
+declare class MemoryCache<T> {
+    protected maxEntries: number | false;
+    protected maxStaleAge: number | false;
+    protected readonly store: Map<string, CacheEntry<T>>;
+    constructor(options?: CacheOptions);
+    get(key: string): T | undefined;
+    set(key: string, value: T): void;
+}
+export default MemoryCache;

package/types/resolve/resolvers/http-axios/index.d.ts

@@ -1,7 +1,8 @@
 import { Axios, AxiosInstance, CreateAxiosDefaults } from 'axios';
 import HTTPResolver, { HTTPResolverOptions } from '../HTTPResolver.ts';
+import MemoryCache from './cache/MemoryCache.ts';
 import File from '../../../File.ts';
-export type { default as HTTPResolver, HTTPResolverOptions } from '../HTTPResolver.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';
 /**
@@ -23,8 +24,18 @@ declare class HTTPResolverAxios extends HTTPResolver {
     axiosConfig: HTTPResolverAxiosConfig;
     protected axiosInstance: AxiosInstance;
     protected previousAxiosConfig: HTTPResolverAxiosConfig;
+    protected cacheStore: MemoryCache<Buffer>;
+    protected previousCache: typeof this.cache;
     constructor(options?: HTTPResolverAxiosOptions);
     getHttpClient(): 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>;
     read(file: File): Promise<Buffer>;
 }
 export default HTTPResolverAxios;