@fedify/vocab-runtime 2.4.0-dev.2122 → 2.4.0-dev.2129

package/dist/tests/jsonld-cache.test.mjs

@@ -1,278 +1,7 @@
-import { a as formatIri, c as haveSameFe34Origin, l as haveSameIriOrigin, m as parseIri } from "./url-DgJM9WJn.mjs";
-import { t as jsonld_default } from "./jsonld-DweIJ07b.mjs";
+import { m as parseIri } from "./url-DgJM9WJn.mjs";
+import { a as normalizeJsonLdIris, c as jsonld_default, i as isTrustedIriOrigin, r as getJsonLdContext, t as compactJsonLdCache } from "./jsonld-cache-DnZS0z1G.mjs";
 import { test } from "node:test";
 import { deepStrictEqual, ok, strictEqual } from "node:assert";
-//#region src/internal/jsonld-cache.ts
-const noJsonLdContext = Symbol("noJsonLdContext");
-/**
-* Checks whether an IRI is trusted relative to another IRI.
-*
-* @internal Technically exported for generated vocabulary classes, but not
-* part of the public API contract.  This is not considered public API for
-* Semantic Versioning decisions.
-*/
-function isTrustedIriOrigin(options, left, right) {
-	return options.crossOrigin === "trust" || left == null || right != null && (haveSameIriOrigin(left, right) || haveSameFe34Origin(left, right));
-}
-/**
-* Normalizes portable IRIs in JSON-LD cache data.
-*
-* @internal Technically exported for generated vocabulary classes, but not
-* part of the public API contract.  This is not considered public API for
-* Semantic Versioning decisions.
-*/
-function normalizeJsonLdIris(value, iriKeys, iriPattern = /^ap(?:\+ef61)?:\/\//i) {
-	return normalize(value, void 0, 0, void 0);
-	function isIriPosition(key, parentKey) {
-		return iriKeys.has(key) || (key === "@value" || key === "@list" || key === "@set") && parentKey != null && iriKeys.has(parentKey);
-	}
-	function arrayItemParentKey(key, parentKey) {
-		return key === "@list" || key === "@set" ? parentKey : key;
-	}
-	function entryParentKey(entryKey, key, parentKey) {
-		if (entryKey === "@list" || entryKey === "@set") return parentKey ?? key;
-		return key === "@list" || key === "@set" ? parentKey : key;
-	}
-	function normalize(value, key, depth = 0, parentKey) {
-		if (depth > 32 || key === "@context") return value;
-		if (typeof value === "string") {
-			if (key != null && isIriPosition(key, parentKey) && iriPattern.test(value)) try {
-				return formatIri(value);
-			} catch {
-				return value;
-			}
-			return value;
-		}
-		if (Array.isArray(value)) {
-			let clone;
-			const itemParentKey = arrayItemParentKey(key, parentKey);
-			for (let i = 0; i < value.length; i++) {
-				const result = normalize(value[i], key, depth + 1, itemParentKey);
-				if (result !== value[i]) {
-					clone ??= value.slice(0, i);
-					clone.push(result);
-				} else if (clone != null) clone.push(value[i]);
-			}
-			return clone ?? value;
-		}
-		if (value == null || typeof value !== "object") return value;
-		const object = value;
-		let clone;
-		for (const entryKey of globalThis.Object.keys(object)) {
-			const result = normalize(object[entryKey], entryKey, depth + 1, entryParentKey(entryKey, key, parentKey));
-			if (result !== object[entryKey]) {
-				clone ??= { ...object };
-				defineJsonLdProperty(clone, entryKey, result);
-			}
-		}
-		return clone ?? object;
-	}
-}
-/**
-* Finds the first JSON-LD context in a value.
-*
-* @internal Technically exported for generated vocabulary classes, but not
-* part of the public API contract.  This is not considered public API for
-* Semantic Versioning decisions.
-*/
-function getJsonLdContext(value, depth = 0) {
-	if (depth > 32) return void 0;
-	if (Array.isArray(value)) {
-		for (const item of value) {
-			const context = getJsonLdContext(item, depth + 1);
-			if (context !== void 0) return context;
-		}
-		return;
-	}
-	if (value == null || typeof value !== "object" || !("@context" in value)) return;
-	return value["@context"];
-}
-function getOwnJsonLdContext(value) {
-	if (value == null || typeof value !== "object" || Array.isArray(value) || !("@context" in value)) return noJsonLdContext;
-	return value["@context"];
-}
-/**
-* Recompacts normalized JSON-LD cache data against the original context.
-*
-* @internal Technically exported for generated vocabulary classes, but not
-* part of the public API contract.  This is not considered public API for
-* Semantic Versioning decisions.
-*/
-async function compactJsonLdCache(normalized, original, documentLoader, depth = 0, inheritedContext) {
-	if (depth > 32) return normalized;
-	if (Array.isArray(original)) {
-		const normalizedArray = Array.isArray(normalized) ? normalized : normalized != null && typeof normalized === "object" && "@graph" in normalized && Array.isArray(normalized["@graph"]) ? normalized["@graph"] : void 0;
-		if (normalizedArray == null) return normalized;
-		let clone;
-		for (let i = 0; i < normalizedArray.length; i++) {
-			const item = await compactJsonLdCache(normalizedArray[i], original[i], documentLoader, depth + 1, inheritedContext);
-			if (item !== normalizedArray[i]) {
-				clone ??= normalizedArray.slice(0, i);
-				clone.push(item);
-			} else if (clone != null) clone.push(normalizedArray[i]);
-		}
-		return clone ?? (Array.isArray(normalized) ? normalized : normalizedArray);
-	}
-	const ownContext = getOwnJsonLdContext(original);
-	const context = ownContext === noJsonLdContext ? inheritedContext : ownContext;
-	if (context == null) return preserveNoContextJsonLdShape(normalized, original, depth);
-	return await preserveJsonLdShape(await mergeUnmappedTerms(await jsonld_default.compact(Array.isArray(normalized) && normalized.length === 1 ? normalized[0] : normalized, context, { documentLoader }), original, context, documentLoader), original, context, documentLoader, depth);
-}
-function preserveNoContextJsonLdShape(normalized, original, depth = 0) {
-	if (depth > 32) return normalized;
-	if (original == null || typeof original !== "object" || Array.isArray(original)) return normalized;
-	const normalizedObject = Array.isArray(normalized) && normalized.length === 1 ? normalized[0] : normalized;
-	if (normalizedObject == null || typeof normalizedObject !== "object" || Array.isArray(normalizedObject)) return normalized;
-	const source = normalizedObject;
-	const originalObject = original;
-	let clone;
-	for (const key of globalThis.Object.keys(originalObject)) {
-		if (!globalThis.Object.prototype.hasOwnProperty.call(source, key)) continue;
-		const value = preserveNoContextValue(source[key], originalObject[key], depth + 1);
-		if (value !== originalObject[key]) {
-			clone ??= { ...originalObject };
-			defineJsonLdProperty(clone, key, value);
-		}
-	}
-	return clone ?? original;
-}
-function preserveNoContextValue(normalized, original, depth) {
-	if (depth > 32) return normalized;
-	if (Array.isArray(original)) {
-		const normalizedArray = Array.isArray(normalized) ? normalized : [normalized];
-		let clone;
-		for (let i = 0; i < original.length; i++) {
-			const value = preserveNoContextValue(normalizedArray[i], original[i], depth + 1);
-			if (value !== original[i]) {
-				clone ??= original.slice(0, i);
-				clone.push(value);
-			} else if (clone != null) clone.push(original[i]);
-		}
-		return clone ?? original;
-	}
-	const normalizedValue = Array.isArray(normalized) ? normalized[0] : normalized;
-	if (normalizedValue == null || typeof normalizedValue !== "object" || Array.isArray(normalizedValue)) return normalizedValue;
-	const normalizedObject = normalizedValue;
-	if (original != null && typeof original === "object" && !Array.isArray(original)) return preserveNoContextJsonLdShape(normalizedObject, original, depth + 1);
-	if (typeof normalizedObject["@id"] === "string") return normalizedObject["@id"];
-	if ("@value" in normalizedObject) return normalizedObject["@value"];
-	return normalizedValue;
-}
-function getTopLevelTerms(value) {
-	const terms = /* @__PURE__ */ new Set();
-	const nodes = Array.isArray(value) ? value : [value];
-	for (const node of nodes) {
-		if (node == null || typeof node !== "object" || Array.isArray(node)) continue;
-		for (const key of globalThis.Object.keys(node)) {
-			if (key.startsWith("@")) continue;
-			terms.add(key);
-		}
-	}
-	return terms;
-}
-async function mergeUnmappedTerms(compacted, original, context, documentLoader) {
-	if (original == null || typeof original !== "object" || Array.isArray(original) || compacted == null || typeof compacted !== "object" || Array.isArray(compacted)) return compacted;
-	const unmappedKeys = globalThis.Object.keys(original).filter((key) => key !== "@context" && !globalThis.Object.prototype.hasOwnProperty.call(compacted, key));
-	if (unmappedKeys.length < 1) return compacted;
-	const result = { ...compacted };
-	const compactedWithContext = compacted != null && typeof compacted === "object" && !Array.isArray(compacted) && !("@context" in compacted) ? {
-		"@context": context,
-		...compacted
-	} : compacted;
-	const compactedTerms = getTopLevelTerms(await jsonld_default.expand(compactedWithContext, { documentLoader }));
-	const dummyPrefix = "urn:fedify:dummy:";
-	const dummy = { "@context": context };
-	for (let i = 0; i < unmappedKeys.length; i++) defineJsonLdProperty(dummy, unmappedKeys[i], `${dummyPrefix}${i}`);
-	const expanded = await jsonld_default.expand(dummy, { documentLoader });
-	const representedKeys = /* @__PURE__ */ new Set();
-	const nodes = Array.isArray(expanded) ? expanded : [expanded];
-	for (const node of nodes) {
-		if (node == null || typeof node !== "object" || Array.isArray(node)) continue;
-		for (const [term, termValue] of globalThis.Object.entries(node)) {
-			if (!compactedTerms.has(term)) continue;
-			for (let i = 0; i < unmappedKeys.length; i++) if (containsValue(termValue, `${dummyPrefix}${i}`)) representedKeys.add(unmappedKeys[i]);
-		}
-	}
-	for (const key of unmappedKeys) if (!representedKeys.has(key)) defineJsonLdProperty(result, key, original[key]);
-	return result;
-}
-function defineJsonLdProperty(object, key, value) {
-	globalThis.Object.defineProperty(object, key, {
-		value,
-		enumerable: true,
-		configurable: true,
-		writable: true
-	});
-}
-function containsValue(value, expected, depth = 0) {
-	if (depth > 32) return false;
-	if (value === expected) return true;
-	if (Array.isArray(value)) return value.some((item) => containsValue(item, expected, depth + 1));
-	if (value == null || typeof value !== "object") return false;
-	return globalThis.Object.entries(value).some(([key, item]) => key !== "@context" && containsValue(item, expected, depth + 1));
-}
-async function preserveJsonLdShape(compacted, original, context, documentLoader, depth = 0) {
-	if (depth > 32) return compacted;
-	if (compacted === original) return compacted;
-	if (original == null || typeof original !== "object" || compacted == null || typeof compacted !== "object") return compacted;
-	if (Array.isArray(original)) {
-		const compactedArray = Array.isArray(compacted) ? compacted : "@graph" in compacted && Array.isArray(compacted["@graph"]) ? compacted["@graph"] : void 0;
-		if (compactedArray == null) return compacted;
-		let clone;
-		for (let i = 0; i < compactedArray.length; i++) {
-			const value = await preserveJsonLdShape(compactedArray[i], original[i], context, documentLoader, depth + 1);
-			const originalContext = original[i] != null && typeof original[i] === "object" && !Array.isArray(original[i]) && "@context" in original[i] ? original[i]["@context"] : void 0;
-			const shaped = originalContext !== void 0 && value != null && typeof value === "object" && !Array.isArray(value) && !("@context" in value) ? {
-				"@context": originalContext,
-				...value
-			} : value;
-			if (shaped !== compactedArray[i]) {
-				clone ??= compactedArray.slice(0, i);
-				clone.push(shaped);
-			} else if (clone != null) clone.push(compactedArray[i]);
-		}
-		return clone ?? (Array.isArray(compacted) ? compacted : compactedArray);
-	}
-	if (Array.isArray(compacted)) return compacted;
-	let clone;
-	const ownContext = getOwnJsonLdContext(original);
-	const objectContext = combineContexts(context, ownContext);
-	const objectCompacted = depth > 0 && ownContext === null ? await compactWithEmptyContext(compacted, context, documentLoader) : compacted;
-	const compactedObject = depth > 0 ? await mergeUnmappedTerms(objectCompacted, original, objectContext, documentLoader) : objectCompacted;
-	const originalObject = original;
-	for (const key of globalThis.Object.keys(compactedObject)) {
-		if (key === "@context") continue;
-		const value = await preserveJsonLdShape(compactedObject[key], originalObject[key], objectContext, documentLoader, depth + 1);
-		const shaped = Array.isArray(originalObject[key]) && !Array.isArray(value) ? [value] : value;
-		if (shaped !== compactedObject[key]) {
-			clone ??= { ...compactedObject };
-			defineJsonLdProperty(clone, key, shaped);
-		}
-	}
-	if (depth > 0) {
-		if ("@context" in originalObject && !("@context" in compactedObject)) {
-			clone ??= { ...compactedObject };
-			clone["@context"] = originalObject["@context"];
-		}
-	}
-	return clone ?? compactedObject;
-}
-async function compactWithEmptyContext(compacted, context, documentLoader) {
-	const compactedWithContext = compacted != null && typeof compacted === "object" && !Array.isArray(compacted) && !("@context" in compacted) ? {
-		"@context": context,
-		...compacted
-	} : compacted;
-	const expanded = await jsonld_default.expand(compactedWithContext, { documentLoader });
-	return await jsonld_default.compact(expanded, {}, { documentLoader });
-}
-function combineContexts(inheritedContext, ownContext) {
-	if (ownContext === noJsonLdContext || ownContext === inheritedContext) return inheritedContext;
-	if (ownContext == null) return ownContext;
-	const inherited = Array.isArray(inheritedContext) ? inheritedContext : [inheritedContext];
-	const own = Array.isArray(ownContext) ? ownContext : [ownContext];
-	return [...inherited, ...own];
-}
-//#endregion
 //#region src/jsonld-cache.test.ts
 test("isTrustedIriOrigin() trusts same portable IRI origins", () => {
 	ok(isTrustedIriOrigin({}, parseIri("ap://did:key:z6Mkabc/actor"), parseIri("ap+ef61://did:key:z6Mkabc/outbox")));

package/dist/tests/{request-BLe2W5ua.cjs → request-BMNsRCJF.cjs}

@@ -3,7 +3,7 @@ let node_process = require("node:process");
 node_process = require_rolldown_runtime.__toESM(node_process, 1);
 //#region deno.json
 var name = "@fedify/vocab-runtime";
-var version = "2.4.0-dev.2122+bdc0ce8d";
+var version = "2.4.0-dev.2129+c0ddb433";
 //#endregion
 //#region src/request.ts
 /**

package/dist/tests/{request-CmMy4YVK.mjs → request-CRVyLEa-.mjs}

@@ -1,7 +1,7 @@
 import process from "node:process";
 //#region deno.json
 var name = "@fedify/vocab-runtime";
-var version = "2.4.0-dev.2122+bdc0ce8d";
+var version = "2.4.0-dev.2129+c0ddb433";
 //#endregion
 //#region src/request.ts
 /**

package/dist/tests/request.test.cjs

@@ -1,5 +1,5 @@
 const require_rolldown_runtime = require("./rolldown-runtime-emK7D4bc.cjs");
-const require_request = require("./request-BLe2W5ua.cjs");
+const require_request = require("./request-BMNsRCJF.cjs");
 let node_test = require("node:test");
 let node_process = require("node:process");
 node_process = require_rolldown_runtime.__toESM(node_process, 1);

package/dist/tests/request.test.mjs

@@ -1,4 +1,4 @@
-import { n as createActivityPubRequest, o as version, r as getUserAgent } from "./request-CmMy4YVK.mjs";
+import { n as createActivityPubRequest, o as version, r as getUserAgent } from "./request-CRVyLEa-.mjs";
 import { test } from "node:test";
 import process from "node:process";
 import { deepStrictEqual } from "node:assert";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fedify/vocab-runtime",
-  "version": "2.4.0-dev.2122+bdc0ce8d",
+  "version": "2.4.0-dev.2129+c0ddb433",
   "homepage": "https://fedify.dev/",
   "repository": {
     "type": "git",

package/src/docloader.test.ts

@@ -1,4 +1,5 @@
 import fetchMock from "fetch-mock";
+import { configure, type LogRecord, reset } from "@logtape/logtape";
 import { deepStrictEqual, ok, rejects } from "node:assert";
 import { test } from "node:test";
 import { createServer } from "node:http";
@@ -9,6 +10,78 @@ import { getDocumentLoader, getRemoteDocument } from "./docloader.ts";
 import { FetchError } from "./request.ts";
 import { UrlError } from "./url.ts";
 
+test("getRemoteDocument() forwards options to alternate documents", async () => {
+  const records: LogRecord[] = [];
+  await reset();
+  await configure({
+    sinks: { capture: (record) => records.push(record) },
+    loggers: [{
+      category: ["fedify"],
+      lowestLevel: "debug",
+      sinks: ["capture"],
+    }],
+  });
+  try {
+    for (const linkHeader of [true, false]) {
+      for (const suppressError of [true, false, undefined]) {
+        records.length = 0;
+        const url = "https://example.com/alternate-source";
+        const alternateUrl = "https://example.com/missing-alternate";
+        const options = {
+          suppressError,
+          signal: new AbortController().signal,
+        };
+        const response = new Response(
+          `<link rel="alternate" type="application/activity+json" href="${alternateUrl}">`,
+          {
+            headers: {
+              "Content-Type": "text/html",
+              ...(linkHeader
+                ? {
+                  Link:
+                    `<${alternateUrl}>; rel="alternate"; type="application/activity+json"`,
+                }
+                : {}),
+            },
+          },
+        );
+        let alternateRequests = 0;
+        await rejects(
+          () =>
+            getRemoteDocument(
+              url,
+              response,
+              async (requestedUrl, forwarded) => {
+                alternateRequests++;
+                deepStrictEqual(requestedUrl, alternateUrl);
+                deepStrictEqual(forwarded, options);
+                return await getRemoteDocument(
+                  requestedUrl,
+                  new Response(null, { status: 404 }),
+                  () => {
+                    throw new Error("Unexpected additional alternate");
+                  },
+                  forwarded,
+                );
+              },
+              options,
+            ),
+          FetchError,
+        );
+        deepStrictEqual(alternateRequests, 1);
+        const failures = records.filter((record) =>
+          record.rawMessage ===
+            "Failed to fetch document: {status} {url} {headers}"
+        );
+        deepStrictEqual(failures.length, 1);
+        deepStrictEqual(failures[0].level, suppressError ? "warning" : "error");
+      }
+    }
+  } finally {
+    await reset();
+  }
+});
+
 test("new FetchError()", () => {
   const e = new FetchError("https://example.com/", "An error message.");
   deepStrictEqual(e.name, "FetchError");

package/src/docloader.ts

@@ -47,6 +47,13 @@ export interface DocumentLoaderOptions {
    * @since 1.8.0
    */
   signal?: AbortSignal;
+
+  /**
+   * Whether to lower error-level logs for recoverable document loading
+   * failures to warning-level logs.  The loader still throws the error.
+   * @default `false`
+   */
+  suppressError?: boolean;
 }
 
 /**
@@ -127,6 +134,7 @@ function createResponseMetadata(response: Response): Response {
  * @param url The URL of the document to load.
  * @param response The response to get the document from.
  * @param fetch The function to fetch the document.
+ * @param options The options for loading the document.
  * @returns The loaded remote document.
  * @throws {FetchError} If the response is not OK.
  * @internal
@@ -138,18 +146,31 @@ export async function getRemoteDocument(
     url: string,
     options?: DocumentLoaderOptions,
   ) => Promise<RemoteDocument>,
+  options?: DocumentLoaderOptions,
 ): Promise<RemoteDocument> {
   const documentUrl = response.url === "" ? url : response.url;
   const docUrl = new URL(documentUrl);
   if (!response.ok) {
-    logger.error(
-      "Failed to fetch document: {status} {url} {headers}",
-      {
-        status: response.status,
-        url: documentUrl,
-        headers: Object.fromEntries(response.headers.entries()),
-      },
-    );
+    if (options?.suppressError) {
+      logger.warn(
+        "Failed to fetch document: {status} {url} {headers}",
+        {
+          status: response.status,
+          url: documentUrl,
+          headers: Object.fromEntries(response.headers.entries()),
+        },
+      );
+    } else {
+      logger.error(
+        "Failed to fetch document: {status} {url} {headers}",
+        {
+          status: response.status,
+          url: documentUrl,
+          headers: Object.fromEntries(response.headers.entries()),
+        },
+      );
+    }
+
     throw new FetchError(
       documentUrl,
       `HTTP ${response.status}: ${documentUrl}`,
@@ -198,7 +219,7 @@ export async function getRemoteDocument(
             "Found alternate document: {alternateUrl} from {url}",
             { alternateUrl: altUri.href, url: documentUrl },
           );
-          return await fetch(altUri.href);
+          return await fetch(altUri.href, options);
         }
       }
     }
@@ -260,7 +281,7 @@ export async function getRemoteDocument(
           "Found alternate document: {alternateUrl} from {url}",
           { alternateUrl: attribs.href, url: documentUrl },
         );
-        return await fetch(new URL(attribs.href, docUrl).href);
+        return await fetch(new URL(attribs.href, docUrl).href, options);
       }
     }
     try {
@@ -350,10 +371,13 @@ export function getDocumentLoader(
         await validatePublicUrl(currentUrl);
       } catch (error) {
         if (error instanceof UrlError) {
-          logger.error("Disallowed private URL: {url}", {
-            url: currentUrl,
-            error,
-          });
+          logger[options?.suppressError ? "warn" : "error"](
+            "Disallowed private URL: {url}",
+            {
+              url: currentUrl,
+              error,
+            },
+          );
         }
         throw error;
       }
@@ -387,7 +411,7 @@ export function getDocumentLoader(
             response.headers.has("Location")
           ) {
             if (redirected >= maximumRedirection) {
-              logger.error(
+              logger[options?.suppressError ? "warn" : "error"](
                 "Too many redirections ({redirections}) while fetching document.",
                 { redirections: redirected + 1, url: currentUrl },
               );
@@ -402,7 +426,7 @@ export function getDocumentLoader(
             ).href;
             span.setAttribute("http.redirect.url", redirectUrl);
             if (visited.has(redirectUrl)) {
-              logger.error(
+              logger[options?.suppressError ? "warn" : "error"](
                 "Detected a redirect loop while fetching document: {url} -> " +
                   "{redirectUrl}",
                 { url: currentUrl, redirectUrl },
@@ -415,7 +439,12 @@ export function getDocumentLoader(
             return await load(redirectUrl, options, redirected + 1, visited);
           }
 
-          const result = await getRemoteDocument(currentUrl, response, load);
+          const result = await getRemoteDocument(
+            currentUrl,
+            response,
+            load,
+            options,
+          );
           span.setAttribute("docloader.document_url", result.documentUrl);
           if (result.contextUrl != null) {
             span.setAttribute("docloader.context_url", result.contextUrl);

package/src/internal/jsonld-cache.ts

@@ -4,6 +4,66 @@ import { formatIri, haveSameFe34Origin, haveSameIriOrigin } from "../url.ts";
 
 const noJsonLdContext = Symbol("noJsonLdContext");
 
+const documentLoaderWrappers = new WeakMap<
+  DocumentLoader,
+  { readonly base: DocumentLoader; released: boolean }
+>();
+
+/**
+ * Registers a loader wrapper with the shared released-wrapper registry.
+ * Both suppression and snapshot wrappers must use this registry so mixed
+ * chains can be unwrapped.  The caller updates the state on release.
+ * @internal Not a public API.
+ */
+export function registerDocumentLoaderWrapper(
+  loader: DocumentLoader,
+  state: { readonly base: DocumentLoader; released: boolean },
+): void {
+  documentLoaderWrappers.set(loader, state);
+}
+
+/**
+ * Removes released loader wrappers, stopping at the first active wrapper.
+ * Active wrappers retain their operation's suppression or snapshot cache.
+ * @internal Not a public API.
+ */
+export function unwrapReleasedDocumentLoader(
+  base: DocumentLoader,
+): DocumentLoader {
+  for (
+    let state = documentLoaderWrappers.get(base);
+    state?.released;
+    state = documentLoaderWrappers.get(base)
+  ) {
+    base = state.base;
+  }
+  return base;
+}
+
+/**
+ * Lowers context loading failure logs for one accessor operation.  Parsed
+ * objects retain the loader, so release it before returning to the caller.
+ * Released wrappers are unwrapped to avoid accumulating loader chains.
+ * @internal Used by generated vocabulary accessors; not a public API.
+ */
+export function createScopedContextLoader(
+  base: DocumentLoader,
+  suppressError?: boolean,
+): { loader: DocumentLoader; release: () => void } {
+  base = unwrapReleasedDocumentLoader(base);
+  if (!suppressError) return { loader: base, release: () => {} };
+  const state = { base, released: false };
+  const loader: DocumentLoader = (url, options) =>
+    base(url, state.released ? options : { ...options, suppressError: true });
+  registerDocumentLoaderWrapper(loader, state);
+  return {
+    loader,
+    release: () => {
+      state.released = true;
+    },
+  };
+}
+
 /**
  * Options for deciding whether two IRIs should be treated as same-origin.
  *