@speclynx/apidom-reference 6.1.2 → 6.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@speclynx/apidom-reference",
-  "version": "6.1.2",
+  "version": "6.2.0",
   "description": "Advanced algorithms for semantic ApiDOM manipulations like dereferencing or resolution.",
   "keywords": [
     "apidom",
@@ -299,35 +299,35 @@
   "author": "Vladimir Gorej",
   "license": "Apache-2.0",
   "dependencies": {
-    "@babel/runtime-corejs3": "^8.0.8",
-    "@speclynx/apidom-core": "6.1.2",
-    "@speclynx/apidom-datamodel": "6.1.2",
-    "@speclynx/apidom-error": "6.1.2",
-    "@speclynx/apidom-json-pointer": "6.1.2",
-    "@speclynx/apidom-ns-arazzo-1": "6.1.2",
-    "@speclynx/apidom-ns-asyncapi-2": "6.1.2",
-    "@speclynx/apidom-ns-json-schema-2020-12": "6.1.2",
-    "@speclynx/apidom-ns-openapi-2": "6.1.2",
-    "@speclynx/apidom-ns-openapi-3-0": "6.1.2",
-    "@speclynx/apidom-ns-openapi-3-1": "6.1.2",
-    "@speclynx/apidom-ns-overlay-1": "6.1.2",
-    "@speclynx/apidom-parser-adapter-arazzo-json-1": "6.1.2",
-    "@speclynx/apidom-parser-adapter-arazzo-yaml-1": "6.1.2",
-    "@speclynx/apidom-parser-adapter-asyncapi-json-2": "6.1.2",
-    "@speclynx/apidom-parser-adapter-asyncapi-yaml-2": "6.1.2",
-    "@speclynx/apidom-parser-adapter-json": "6.1.2",
-    "@speclynx/apidom-parser-adapter-openapi-json-2": "6.1.2",
-    "@speclynx/apidom-parser-adapter-openapi-json-3-0": "6.1.2",
-    "@speclynx/apidom-parser-adapter-openapi-json-3-1": "6.1.2",
-    "@speclynx/apidom-parser-adapter-openapi-yaml-2": "6.1.2",
-    "@speclynx/apidom-parser-adapter-openapi-yaml-3-0": "6.1.2",
-    "@speclynx/apidom-parser-adapter-openapi-yaml-3-1": "6.1.2",
-    "@speclynx/apidom-parser-adapter-overlay-json-1": "6.1.2",
-    "@speclynx/apidom-parser-adapter-overlay-yaml-1": "6.1.2",
-    "@speclynx/apidom-parser-adapter-yaml-1-2": "6.1.2",
-    "@speclynx/apidom-traverse": "6.1.2",
+    "@babel/runtime-corejs3": "^8.1.0",
+    "@speclynx/apidom-core": "6.2.0",
+    "@speclynx/apidom-datamodel": "6.2.0",
+    "@speclynx/apidom-error": "6.2.0",
+    "@speclynx/apidom-json-pointer": "6.2.0",
+    "@speclynx/apidom-ns-arazzo-1": "6.2.0",
+    "@speclynx/apidom-ns-asyncapi-2": "6.2.0",
+    "@speclynx/apidom-ns-json-schema-2020-12": "6.2.0",
+    "@speclynx/apidom-ns-openapi-2": "6.2.0",
+    "@speclynx/apidom-ns-openapi-3-0": "6.2.0",
+    "@speclynx/apidom-ns-openapi-3-1": "6.2.0",
+    "@speclynx/apidom-ns-overlay-1": "6.2.0",
+    "@speclynx/apidom-parser-adapter-arazzo-json-1": "6.2.0",
+    "@speclynx/apidom-parser-adapter-arazzo-yaml-1": "6.2.0",
+    "@speclynx/apidom-parser-adapter-asyncapi-json-2": "6.2.0",
+    "@speclynx/apidom-parser-adapter-asyncapi-yaml-2": "6.2.0",
+    "@speclynx/apidom-parser-adapter-json": "6.2.0",
+    "@speclynx/apidom-parser-adapter-openapi-json-2": "6.2.0",
+    "@speclynx/apidom-parser-adapter-openapi-json-3-0": "6.2.0",
+    "@speclynx/apidom-parser-adapter-openapi-json-3-1": "6.2.0",
+    "@speclynx/apidom-parser-adapter-openapi-yaml-2": "6.2.0",
+    "@speclynx/apidom-parser-adapter-openapi-yaml-3-0": "6.2.0",
+    "@speclynx/apidom-parser-adapter-openapi-yaml-3-1": "6.2.0",
+    "@speclynx/apidom-parser-adapter-overlay-json-1": "6.2.0",
+    "@speclynx/apidom-parser-adapter-overlay-yaml-1": "6.2.0",
+    "@speclynx/apidom-parser-adapter-yaml-1-2": "6.2.0",
+    "@speclynx/apidom-traverse": "6.2.0",
     "@swaggerexpert/arazzo-runtime-expression": "^3.2.0",
-    "axios": "^1.20.0",
+    "axios": "^1.21.0",
     "picomatch": "^4.0.7",
     "ramda": "~0.32.0",
     "ramda-adjunct": "^6.1.0"
@@ -346,5 +346,5 @@
     "README.md",
     "CHANGELOG.md"
   ],
-  "gitHead": "e3ba735e1c56369bb263dd8246c711d405ed9606"
+  "gitHead": "13bd86fba1e6c36dd97423e195c48994901c5422"
 }

package/src/bundle/index.cjs

@@ -22,20 +22,22 @@ const bundle = async (uri, options) => {
   const {
     refSet
   } = options.bundle;
-  const sanitizedURI = url.sanitize(uri);
+  // strategies look up same-document references by a resolved, hence normalized, URI;
+  // the file is parsed as a whole document, so its URI has no fragment
+  const baseURI = url.normalize(url.stripHash(uri));
   const mergedOptions = (0, _util.merge)(options, {
     resolve: {
-      baseURI: sanitizedURI
+      baseURI
     }
   });
   let parseResult;
 
   // if refSet was provided, use it to avoid unnecessary parsing
-  if (refSet !== null && refSet.has(sanitizedURI)) {
+  if (refSet !== null && refSet.has(baseURI)) {
     // @ts-ignore
     ({
       value: parseResult
-    } = refSet.find((0, _ramda.propEq)(sanitizedURI, 'uri')));
+    } = refSet.find((0, _ramda.propEq)(baseURI, 'uri')));
   } else {
     parseResult = await (0, _index.default)(uri, mergedOptions);
   }

package/src/bundle/index.mjs

@@ -14,20 +14,22 @@ const bundle = async (uri, options) => {
   const {
     refSet
   } = options.bundle;
-  const sanitizedURI = url.sanitize(uri);
+  // strategies look up same-document references by a resolved, hence normalized, URI;
+  // the file is parsed as a whole document, so its URI has no fragment
+  const baseURI = url.normalize(url.stripHash(uri));
   const mergedOptions = mergeOptions(options, {
     resolve: {
-      baseURI: sanitizedURI
+      baseURI
     }
   });
   let parseResult;
 
   // if refSet was provided, use it to avoid unnecessary parsing
-  if (refSet !== null && refSet.has(sanitizedURI)) {
+  if (refSet !== null && refSet.has(baseURI)) {
     // @ts-ignore
     ({
       value: parseResult
-    } = refSet.find(propEq(sanitizedURI, 'uri')));
+    } = refSet.find(propEq(baseURI, 'uri')));
   } else {
     parseResult = await parse(uri, mergedOptions);
   }

package/src/dereference/index.cjs

@@ -31,8 +31,10 @@ const dereferenceApiDOM = async (element, options) => {
     parseResult = new _apidomDatamodel.ParseResultElement([elementClone]);
     surrogateWrapping = true;
   }
+
+  // strategies look up same-document references by a resolved, hence normalized, URI
   const file = new _File.default({
-    uri: options.resolve.baseURI,
+    uri: url.normalize(options.resolve.baseURI),
     parseResult,
     mediaType: options.parse.mediaType
   });
@@ -66,21 +68,22 @@ const dereference = async (uri, options) => {
   const {
     refSet
   } = options.dereference;
-  const sanitizedURI = url.sanitize(uri);
+  // the file is parsed as a whole document, so its URI has no fragment
+  const baseURI = url.normalize(url.stripHash(uri));
   let parseResult;
 
   // if refSet was provided, use it to avoid unnecessary parsing
-  if (refSet !== null && refSet.has(sanitizedURI)) {
+  if (refSet !== null && refSet.has(baseURI)) {
     // @ts-ignore
     ({
       value: parseResult
-    } = refSet.find((0, _ramda.propEq)(sanitizedURI, 'uri')));
+    } = refSet.find((0, _ramda.propEq)(baseURI, 'uri')));
   } else {
     parseResult = await (0, _index.default)(uri, options);
   }
   const mergedOptions = (0, _util.merge)(options, {
     resolve: {
-      baseURI: sanitizedURI
+      baseURI
     },
     dereference: {
       // if refSet was not provided, then we can work in mutable mode

package/src/dereference/index.mjs

@@ -23,8 +23,10 @@ export const dereferenceApiDOM = async (element, options) => {
     parseResult = new ParseResultElement([elementClone]);
     surrogateWrapping = true;
   }
+
+  // strategies look up same-document references by a resolved, hence normalized, URI
   const file = new File({
-    uri: options.resolve.baseURI,
+    uri: url.normalize(options.resolve.baseURI),
     parseResult,
     mediaType: options.parse.mediaType
   });
@@ -57,21 +59,22 @@ const dereference = async (uri, options) => {
   const {
     refSet
   } = options.dereference;
-  const sanitizedURI = url.sanitize(uri);
+  // the file is parsed as a whole document, so its URI has no fragment
+  const baseURI = url.normalize(url.stripHash(uri));
   let parseResult;
 
   // if refSet was provided, use it to avoid unnecessary parsing
-  if (refSet !== null && refSet.has(sanitizedURI)) {
+  if (refSet !== null && refSet.has(baseURI)) {
     // @ts-ignore
     ({
       value: parseResult
-    } = refSet.find(propEq(sanitizedURI, 'uri')));
+    } = refSet.find(propEq(baseURI, 'uri')));
   } else {
     parseResult = await parse(uri, options);
   }
   const mergedOptions = mergeOptions(options, {
     resolve: {
-      baseURI: sanitizedURI
+      baseURI
     },
     dereference: {
       // if refSet was not provided, then we can work in mutable mode

package/src/options/index.cjs

@@ -68,6 +68,10 @@ const defaultOptions = {
   resolve: {
     /**
      * baseURI serves as a base for all relative URL found in ApiDOM references.
+     * It must be absolute: a file system path, a file:// URL or an HTTP(S) URL.
+     * Defaults to the current working directory (the page URL in browsers).
+     * A fragment marks where the ApiDOM fragment is located in its document;
+     * leave it out when passing a whole document.
      */
     baseURI: '',
     /**

package/src/options/index.mjs

@@ -63,6 +63,10 @@ const defaultOptions = {
   resolve: {
     /**
      * baseURI serves as a base for all relative URL found in ApiDOM references.
+     * It must be absolute: a file system path, a file:// URL or an HTTP(S) URL.
+     * Defaults to the current working directory (the page URL in browsers).
+     * A fragment marks where the ApiDOM fragment is located in its document;
+     * leave it out when passing a whole document.
      */
     baseURI: '',
     /**

package/src/options/util.cjs

@@ -12,7 +12,13 @@ var _url = require("../util/url.cjs");
  */
 
 const baseURILens = (0, _ramda.lens)((0, _ramda.path)(['resolve', 'baseURI']), (0, _ramda.assocPath)(['resolve', 'baseURI']));
-const baseURIDefault = baseURI => (0, _ramdaAdjunct.isEmptyString)(baseURI) ? (0, _url.cwd)() : baseURI;
+// in Node cwd() is a raw file system path; encode it, so that it reads as a URI
+// (in browsers it is the page URL, which may be an already encoded file:// URL)
+const cwdURI = () => {
+  const dir = (0, _url.cwd)();
+  return (0, _url.isFileSystemPath)(dir) && (0, _url.getProtocol)(dir) !== 'file' ? (0, _url.fromFileSystemPath)(dir) : dir;
+};
+const baseURIDefault = baseURI => (0, _ramdaAdjunct.isEmptyString)(baseURI) ? cwdURI() : baseURI;
 
 /**
  * @public

package/src/options/util.mjs

@@ -1,12 +1,18 @@
 import { mergeDeepRight, lens, path, assocPath, over } from 'ramda';
 import { isEmptyString } from 'ramda-adjunct';
-import { cwd } from "../util/url.mjs";
+import { cwd, getProtocol, isFileSystemPath, fromFileSystemPath } from "../util/url.mjs";
 /**
  * Algorithm for deep merging options.
  */
 
 const baseURILens = lens(path(['resolve', 'baseURI']), assocPath(['resolve', 'baseURI']));
-const baseURIDefault = baseURI => isEmptyString(baseURI) ? cwd() : baseURI;
+// in Node cwd() is a raw file system path; encode it, so that it reads as a URI
+// (in browsers it is the page URL, which may be an already encoded file:// URL)
+const cwdURI = () => {
+  const dir = cwd();
+  return isFileSystemPath(dir) && getProtocol(dir) !== 'file' ? fromFileSystemPath(dir) : dir;
+};
+const baseURIDefault = baseURI => isEmptyString(baseURI) ? cwdURI() : baseURI;
 
 /**
  * @public

package/src/resolve/index.cjs

@@ -29,9 +29,10 @@ const resolveApiDOM = async (element, options) => {
     elementClone.classes.push('result');
     parseResult = new _apidomDatamodel.ParseResultElement([elementClone]);
   }
-  const sanitizedURI = url.sanitize(url.stripHash(options.resolve.baseURI));
+
+  // strategies look up same-document references by a resolved, hence normalized, URI
   const file = new _File.default({
-    uri: sanitizedURI,
+    uri: url.normalize(options.resolve.baseURI),
     parseResult,
     mediaType: options.parse.mediaType
   });
@@ -59,9 +60,11 @@ const resolveApiDOM = async (element, options) => {
 exports.resolveApiDOM = resolveApiDOM;
 const resolve = async (uri, options) => {
   const parseResult = await (0, _index.default)(uri, options);
+  // the file is parsed as a whole document, so its URI has no fragment
+  const baseURI = url.normalize(url.stripHash(uri));
   const mergedOptions = (0, _util.merge)(options, {
     resolve: {
-      baseURI: url.sanitize(uri)
+      baseURI
     }
   });
   return resolveApiDOM(parseResult, mergedOptions);

package/src/resolve/index.mjs

@@ -21,9 +21,10 @@ export const resolveApiDOM = async (element, options) => {
     elementClone.classes.push('result');
     parseResult = new ParseResultElement([elementClone]);
   }
-  const sanitizedURI = url.sanitize(url.stripHash(options.resolve.baseURI));
+
+  // strategies look up same-document references by a resolved, hence normalized, URI
   const file = new File({
-    uri: sanitizedURI,
+    uri: url.normalize(options.resolve.baseURI),
     parseResult,
     mediaType: options.parse.mediaType
   });
@@ -50,9 +51,11 @@ export const resolveApiDOM = async (element, options) => {
  */
 const resolve = async (uri, options) => {
   const parseResult = await parse(uri, options);
+  // the file is parsed as a whole document, so its URI has no fragment
+  const baseURI = url.normalize(url.stripHash(uri));
   const mergedOptions = mergeOptions(options, {
     resolve: {
-      baseURI: url.sanitize(uri)
+      baseURI
     }
   });
   return resolveApiDOM(parseResult, mergedOptions);

package/src/util/url.cjs

@@ -3,7 +3,7 @@
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
-exports.unsanitize = exports.toFileSystemPath = exports.stripHash = exports.sanitize = exports.resolve = exports.relative = exports.isURI = exports.isHttpUrl = exports.isFileSystemPath = exports.hasProtocol = exports.getProtocol = exports.getHash = exports.getExtension = exports.getBasename = exports.fromFileSystemPath = exports.cwd = void 0;
+exports.unsanitize = exports.toFileSystemPath = exports.stripHash = exports.sanitize = exports.resolve = exports.relative = exports.normalize = exports.isURI = exports.isHttpUrl = exports.isFileSystemPath = exports.hasProtocol = exports.getProtocol = exports.getHash = exports.getExtension = exports.getBasename = exports.fromFileSystemPath = exports.cwd = void 0;
 var _ramda = require("ramda");
 var _ramdaAdjunct = require("ramda-adjunct");
 /**
@@ -118,21 +118,23 @@ exports.isURI = isURI;
  */
 const toFileSystemPath = (uri, options) => {
   // RegExp patterns to URL-decode special characters for local filesystem paths
-  const urlDecodePatterns = [/%23/g, '#', /%24/g, '$', /%26/g, '&', /%2C/g, ',', /%40/g, '@'];
+  const urlDecodePatterns = [/%23/g, '#', /%24/g, '$', /%26/g, '&', /%2C/g, ',', /%3F/g, '?', /%40/g, '@'];
   const keepFileProtocol = (0, _ramda.propOr)(false, 'keepFileProtocol', options);
   const isWindowsPredicate = (0, _ramda.propOr)(isWindows, 'isWindows', options);
 
-  // Step 1: `decodeURI` will decode characters such as Cyrillic characters, spaces, etc.
-  let path = decodeURI(uri);
-
-  // Step 2: Manually decode characters that are not decoded by `decodeURI`.
+  // Step 1: Manually decode characters that are not decoded by `decodeURI`.
   // This includes characters such as "#" and "?", which have special meaning in URLs,
-  // but are just normal characters in a filesystem path.
+  // but are just normal characters in a filesystem path. It runs before `decodeURI`,
+  // so that an encoded "%" (e.g. "%253F") isn't decoded twice.
+  let path = uri;
   for (let i = 0; i < urlDecodePatterns.length; i += 2) {
     // @ts-ignore
     path = path.replace(urlDecodePatterns[i], urlDecodePatterns[i + 1]);
   }
 
+  // Step 2: `decodeURI` will decode characters such as Cyrillic characters, spaces, etc.
+  path = decodeURI(path);
+
   // Step 3: If it's a "file://" URL, then format it consistently
   // or convert it to a local filesystem path
   let isFileUrl = path.substring(0, 7).toLowerCase() === 'file://';
@@ -278,6 +280,34 @@ const resolve = (from, to) => {
   return resolvedUrl.toString();
 };
 
+/**
+ * Normalizes a URI the way `resolve` normalizes its result (WHATWG URL normalization):
+ * lowercases the scheme and the host of an absolute URL, drops a default port and
+ * removes dot segments. This is not RFC 3986 syntax-based normalization: existing
+ * percent-encoding is left as is. A file system path is sanitized first, so characters
+ * not allowed in URLs (e.g. spaces, `[`, `?`) are percent-encoded; a `file://` URL has
+ * its path sanitized the same way and stays a URL. The fragment is kept as given.
+ * A URI that can't be normalized is returned unchanged.
+ * @public
+ */
+exports.resolve = resolve;
+const normalize = uri => {
+  // getHash returns the root hash ('#') for a URI without fragment
+  const fragment = uri.includes('#') ? getHash(uri) : '';
+  const documentURI = stripHash(uri);
+  try {
+    let sanitizedURI = sanitize(documentURI);
+    // sanitize turns a file:// URL into a path; keep it a URL, as references
+    // resolved against it are, e.g. file:///C:/x.json rather than file://C:/x.json
+    if (getProtocol(documentURI) === 'file') {
+      sanitizedURI = `file://${sanitizedURI.startsWith('/') ? '' : '/'}${sanitizedURI}`;
+    }
+    return resolve('', sanitizedURI) + fragment;
+  } catch {
+    return uri;
+  }
+};
+
 /**
  * Computes the URI reference that resolves to `to` against `from` — the inverse
  * of `resolve`: `resolve(from, relative(from, to)) === to`. The reference is
@@ -287,7 +317,7 @@ const resolve = (from, to) => {
  * returned unchanged.
  * @public
  */
-exports.resolve = resolve;
+exports.normalize = normalize;
 const relative = (from, to) => {
   const fromURL = new URL(from, 'resolve://');
   const toURL = new URL(to, 'resolve://');

package/src/util/url.mjs

@@ -108,21 +108,23 @@ export const isURI = uri => {
  */
 export const toFileSystemPath = (uri, options) => {
   // RegExp patterns to URL-decode special characters for local filesystem paths
-  const urlDecodePatterns = [/%23/g, '#', /%24/g, '$', /%26/g, '&', /%2C/g, ',', /%40/g, '@'];
+  const urlDecodePatterns = [/%23/g, '#', /%24/g, '$', /%26/g, '&', /%2C/g, ',', /%3F/g, '?', /%40/g, '@'];
   const keepFileProtocol = propOr(false, 'keepFileProtocol', options);
   const isWindowsPredicate = propOr(isWindows, 'isWindows', options);
 
-  // Step 1: `decodeURI` will decode characters such as Cyrillic characters, spaces, etc.
-  let path = decodeURI(uri);
-
-  // Step 2: Manually decode characters that are not decoded by `decodeURI`.
+  // Step 1: Manually decode characters that are not decoded by `decodeURI`.
   // This includes characters such as "#" and "?", which have special meaning in URLs,
-  // but are just normal characters in a filesystem path.
+  // but are just normal characters in a filesystem path. It runs before `decodeURI`,
+  // so that an encoded "%" (e.g. "%253F") isn't decoded twice.
+  let path = uri;
   for (let i = 0; i < urlDecodePatterns.length; i += 2) {
     // @ts-ignore
     path = path.replace(urlDecodePatterns[i], urlDecodePatterns[i + 1]);
   }
 
+  // Step 2: `decodeURI` will decode characters such as Cyrillic characters, spaces, etc.
+  path = decodeURI(path);
+
   // Step 3: If it's a "file://" URL, then format it consistently
   // or convert it to a local filesystem path
   let isFileUrl = path.substring(0, 7).toLowerCase() === 'file://';
@@ -263,6 +265,33 @@ export const resolve = (from, to) => {
   return resolvedUrl.toString();
 };
 
+/**
+ * Normalizes a URI the way `resolve` normalizes its result (WHATWG URL normalization):
+ * lowercases the scheme and the host of an absolute URL, drops a default port and
+ * removes dot segments. This is not RFC 3986 syntax-based normalization: existing
+ * percent-encoding is left as is. A file system path is sanitized first, so characters
+ * not allowed in URLs (e.g. spaces, `[`, `?`) are percent-encoded; a `file://` URL has
+ * its path sanitized the same way and stays a URL. The fragment is kept as given.
+ * A URI that can't be normalized is returned unchanged.
+ * @public
+ */
+export const normalize = uri => {
+  // getHash returns the root hash ('#') for a URI without fragment
+  const fragment = uri.includes('#') ? getHash(uri) : '';
+  const documentURI = stripHash(uri);
+  try {
+    let sanitizedURI = sanitize(documentURI);
+    // sanitize turns a file:// URL into a path; keep it a URL, as references
+    // resolved against it are, e.g. file:///C:/x.json rather than file://C:/x.json
+    if (getProtocol(documentURI) === 'file') {
+      sanitizedURI = `file://${sanitizedURI.startsWith('/') ? '' : '/'}${sanitizedURI}`;
+    }
+    return resolve('', sanitizedURI) + fragment;
+  } catch {
+    return uri;
+  }
+};
+
 /**
  * Computes the URI reference that resolves to `to` against `from` — the inverse
  * of `resolve`: `resolve(from, relative(from, to)) === to`. The reference is

package/types/apidom-reference.d.ts

@@ -359,6 +359,18 @@ export declare class MaximumResolveDepthError extends ResolveError {
  */
 export declare const mergeOptions: (lObj: ApiDOMReferenceOptions, rObj: Record<string, any>) => ApiDOMReferenceOptions;
 
+/**
+ * Normalizes a URI the way `resolve` normalizes its result (WHATWG URL normalization):
+ * lowercases the scheme and the host of an absolute URL, drops a default port and
+ * removes dot segments. This is not RFC 3986 syntax-based normalization: existing
+ * percent-encoding is left as is. A file system path is sanitized first, so characters
+ * not allowed in URLs (e.g. spaces, `[`, `?`) are percent-encoded; a `file://` URL has
+ * its path sanitized the same way and stays a URL. The fragment is kept as given.
+ * A URI that can't be normalized is returned unchanged.
+ * @public
+ */
+declare const normalize: (uri: string) => string;
+
 /**
  * @public
  */
@@ -658,6 +670,7 @@ declare namespace url {
         stripHash,
         cwd,
         resolve_2 as resolve,
+        normalize,
         relative,
         sanitize,
         unsanitize

package/types/util/url.d.ts

@@ -96,6 +96,17 @@ export declare const cwd: () => string;
  * @public
  */
 export declare const resolve: (from: string, to: string) => string;
+/**
+ * Normalizes a URI the way `resolve` normalizes its result (WHATWG URL normalization):
+ * lowercases the scheme and the host of an absolute URL, drops a default port and
+ * removes dot segments. This is not RFC 3986 syntax-based normalization: existing
+ * percent-encoding is left as is. A file system path is sanitized first, so characters
+ * not allowed in URLs (e.g. spaces, `[`, `?`) are percent-encoded; a `file://` URL has
+ * its path sanitized the same way and stays a URL. The fragment is kept as given.
+ * A URI that can't be normalized is returned unchanged.
+ * @public
+ */
+export declare const normalize: (uri: string) => string;
 /**
  * Computes the URI reference that resolves to `to` against `from` — the inverse
  * of `resolve`: `resolve(from, relative(from, to)) === to`. The reference is