@speclynx/apidom-reference 6.1.2 → 7.0.0

package/types/dereference/strategies/arazzo-1/visitor.d.ts

@@ -1,70 +1,70 @@
 import { Element } from '@speclynx/apidom-datamodel';
 import { type Path } from '@speclynx/apidom-traverse';
 import { type Schema$idIndex } from './selectors/uri.ts';
+import DereferenceVisitor from '../DereferenceVisitor.ts';
 import Reference from '../../../Reference.ts';
-import { AncestorLineage } from '../../util.ts';
 import type { ReferenceOptions } from '../../../options/index.ts';
+/**
+ * Context of a source being dereferenced: the `$id`s of the JSON Schema elements enclosing it.
+ */
+interface Arazzo1DereferenceContext {
+    readonly ancestorSchema$ids: string[];
+}
 /**
  * @public
  */
 export interface Arazzo1DereferenceVisitorOptions {
     readonly reference: Reference;
     readonly options: ReferenceOptions;
-    readonly indirections?: Element[];
     readonly schema$idIndex?: Schema$idIndex;
-    readonly ancestors?: AncestorLineage<Element>;
-    readonly visited?: WeakSet<Element>;
     readonly ancestorSchema$ids?: string[];
 }
 /**
+ * Dereferences an Arazzo document. Reusable Objects expect the type of their
+ * `referenced-element` meta, JSON Schema `$ref`s expect a JSON Schema.
+ *
  * @public
  */
-declare class Arazzo1DereferenceVisitor {
-    protected readonly indirections: Element[];
-    protected readonly reference: Reference;
-    /**
-     * Base URI of the current document for resolving relative references.
-     * Honors the Arazzo `$self` field when present, otherwise falls back
-     * to the retrieval URI (`this.reference.uri`).
-     */
-    protected readonly baseURI: string;
-    protected readonly options: ReferenceOptions;
+declare class Arazzo1DereferenceVisitor extends DereferenceVisitor<Arazzo1DereferenceContext> {
     /**
-     * Index of `$id`-bearing schemas per document, shared across nested visitors
-     * of a single dereference run so it never outlives mutations of the documents.
+     * Index of `$id`-bearing schemas per document, shared across the visitors
+     * of a single dereference run.
      */
     protected readonly schema$idIndex: Schema$idIndex;
-    protected readonly visited: WeakSet<Element>;
     /**
      * `$id`s of the JSON Schema elements enclosing the traversal root within its
      * document (outermost first). Empty when the root is the document itself; a
-     * nested visitor traversing a fragment is seeded with the `$id`s of the
-     * schemas the fragment sits under, so the `$ref`s and `$id`s within resolve
-     * against the same base as they would from the document root.
+     * visitor traversing a fragment is seeded with the `$id`s of the schemas the
+     * fragment sits under, so the `$ref`s and `$id`s within resolve against the
+     * same base as they would from the document root.
      */
     protected readonly ancestorSchema$ids: string[];
+    constructor({ reference, options, schema$idIndex, ancestorSchema$ids, }: Arazzo1DereferenceVisitorOptions);
+    protected get strategyName(): string;
+    protected createVisitor(reference: Reference, { ancestorSchema$ids }: Arazzo1DereferenceContext): Arazzo1DereferenceVisitor;
+    protected refractTo(element: Element, type: string): Element;
+    protected isOfType(element: Element, type: string): boolean;
+    /**
+     * Honors the Arazzo `$self` field when present, otherwise falls back to the retrieval URI.
+     */
+    protected toDocumentBaseURI(reference: Reference): string;
+    /**
+     * Identity-based referencing: URI matches `$self` of an already processed Arazzo document.
+     */
+    protected findReferenceByIdentity(uri: string): Reference | undefined;
     /**
-     * Tracks element ancestors across dive-deep traversal boundaries.
-     * Used for cycle detection: if a referenced element is found in
-     * the ancestor lineage, a circular reference is detected.
+     * A document as JSON Schema for locating schemas within it: a generic document is
+     * refracted to JSON Schema once per dereference run, a semantic one is used as it is.
      */
-    protected readonly ancestors: AncestorLineage<Element>;
-    constructor({ reference, options, indirections, schema$idIndex, ancestors, visited, ancestorSchema$ids, }: Arazzo1DereferenceVisitorOptions);
-    protected toAncestorLineage(path: Path<Element>): [AncestorLineage<Element>, Set<Element>];
-    protected toBaseURI(uri: string): string;
-    protected toReference(uri: string): Promise<Reference>;
+    protected toJSONSchemaDocument(document: Element): Element;
     /**
-     * Handles an error according to the continueOnError option.
-     *
-     * For new errors: wraps in UnresolvableReferenceError with structured context
-     * (type, uri, location, codeFrame, refFieldName, refFieldValue, trace).
-     * For errors already wrapped by a nested visitor: prepends the current hop to the trace.
-     *
-     * Inner/intermediate visitors always throw to let the trace accumulate.
-     * Only the entry document visitor respects continueOnError (callback/swallow/throw).
+     * Indexes the `$id`-bearing schemas of a document for the run. Transcluded elements aren't
+     * indexed: they're copies of structures indexed where they're defined,
+     * and in a document dereferenced in place their shared structure would be walked once per path.
      */
-    protected handleError(message: string, error: Error, referencingElement: Element, refFieldName: string, refFieldValue: string, visitorPath: Path<Element>): void;
-    ReusableElement(path: Path<Element>): void;
+    protected index$ids(element: Element): void;
+    enter(path: Path<Element>): void;
+    ReusableElement(path: Path<Element>): Promise<void>;
     JSONSchemaElement(path: Path<Element>): Promise<void>;
 }
 export default Arazzo1DereferenceVisitor;

package/types/dereference/strategies/asyncapi-2/index.d.ts

@@ -13,7 +13,6 @@ export type { default as Parser, ParserOptions } from '../../../parse/parsers/Pa
 export type { default as Resolver, ResolverOptions } from '../../../resolve/resolvers/Resolver.ts';
 export type { default as ResolveStrategy, ResolveStrategyOptions, } from '../../../resolve/strategies/ResolveStrategy.ts';
 export type { default as BundleStrategy, BundleStrategyOptions, } from '../../../bundle/strategies/BundleStrategy.ts';
-export type { AncestorLineage } from '../../util.ts';
 /**
  * @public
  */

package/types/dereference/strategies/asyncapi-2/visitor.d.ts

@@ -1,6 +1,6 @@
 import { Element } from '@speclynx/apidom-datamodel';
-import { type Path } from '@speclynx/apidom-traverse';
-import { AncestorLineage } from '../../util.ts';
+import type { Path } from '@speclynx/apidom-traverse';
+import DereferenceVisitor from '../DereferenceVisitor.ts';
 import Reference from '../../../Reference.ts';
 import type { ReferenceOptions } from '../../../options/index.ts';
 /**
@@ -9,41 +9,25 @@ import type { ReferenceOptions } from '../../../options/index.ts';
 export interface AsyncAPI2DereferenceVisitorOptions {
     readonly reference: Reference;
     readonly options: ReferenceOptions;
-    readonly indirections?: Element[];
-    readonly refractCache?: WeakMap<Element, Element>;
-    readonly ancestors?: AncestorLineage<Element>;
-    readonly visited?: WeakSet<Element>;
 }
 /**
+ * Dereferences an AsyncAPI 2 document. Reference Objects expect the type of their
+ * `referenced-element` meta, Channel Item `$ref`s a Channel Item Object.
+ *
  * @public
  */
-declare class AsyncAPI2DereferenceVisitor {
-    protected readonly indirections: Element[];
-    protected readonly reference: Reference;
-    protected readonly options: ReferenceOptions;
-    protected readonly refractCache: WeakMap<Element, Element>;
-    protected readonly visited: WeakSet<Element>;
+declare class AsyncAPI2DereferenceVisitor extends DereferenceVisitor<undefined> {
+    protected get strategyName(): string;
+    protected createVisitor(reference: Reference): AsyncAPI2DereferenceVisitor;
     /**
-     * Tracks element ancestors across dive-deep traversal boundaries.
-     * Used for cycle detection: if a referenced element is found in
-     * the ancestor lineage, a circular reference is detected.
+     * A Reference Object stands for the type its reference expects: it's dereferenced as that type.
      */
-    protected readonly ancestors: AncestorLineage<Element>;
-    constructor({ reference, options, indirections, ancestors, refractCache, visited, }: AsyncAPI2DereferenceVisitorOptions);
-    protected toAncestorLineage(path: Path<Element>): [AncestorLineage<Element>, Set<Element>];
-    protected toBaseURI(uri: string): string;
-    protected toReference(uri: string): Promise<Reference>;
+    protected isOfType(element: Element, type: string): boolean;
     /**
-     * Handles an error according to the continueOnError option.
-     *
-     * For new errors: wraps in UnresolvableReferenceError with structured context
-     * (type, uri, location, codeFrame, refFieldName, refFieldValue, trace).
-     * For errors already wrapped by a nested visitor: prepends the current hop to the trace.
-     *
-     * Inner/intermediate visitors always throw to let the trace accumulate.
-     * Only the entry document visitor respects continueOnError (callback/swallow/throw).
+     * A generic structure holding a `$ref` is a Reference Object to the expected type,
+     * unless the type has its own `$ref` field (Channel Item Object).
      */
-    protected handleError(message: string, error: Error, referencingElement: Element, refFieldName: string, refFieldValue: string, visitorPath: Path<Element>): void;
+    protected refractTo(element: Element, type: string): Element;
     ReferenceElement(path: Path<Element>): Promise<void>;
     ChannelItemElement(path: Path<Element>): Promise<void>;
 }

package/types/dereference/strategies/openapi-2/index.d.ts

@@ -13,7 +13,6 @@ export type { default as Parser, ParserOptions } from '../../../parse/parsers/Pa
 export type { default as Resolver, ResolverOptions } from '../../../resolve/resolvers/Resolver.ts';
 export type { default as ResolveStrategy, ResolveStrategyOptions, } from '../../../resolve/strategies/ResolveStrategy.ts';
 export type { default as BundleStrategy, BundleStrategyOptions, } from '../../../bundle/strategies/BundleStrategy.ts';
-export type { AncestorLineage } from '../../util.ts';
 export type { AsyncAPI2DereferenceVisitorOptions } from '../asyncapi-2/visitor.ts';
 /**
  * @public

package/types/dereference/strategies/openapi-2/visitor.d.ts

@@ -1,6 +1,6 @@
 import { Element } from '@speclynx/apidom-datamodel';
-import { type Path } from '@speclynx/apidom-traverse';
-import { AncestorLineage } from '../../util.ts';
+import type { Path } from '@speclynx/apidom-traverse';
+import DereferenceVisitor from '../DereferenceVisitor.ts';
 import Reference from '../../../Reference.ts';
 import type { ReferenceOptions } from '../../../options/index.ts';
 /**
@@ -9,41 +9,26 @@ import type { ReferenceOptions } from '../../../options/index.ts';
 export interface OpenAPI2DereferenceVisitorOptions {
     readonly reference: Reference;
     readonly options: ReferenceOptions;
-    readonly indirections?: Element[];
-    readonly refractCache?: WeakMap<Element, Element>;
-    readonly ancestors?: AncestorLineage<Element>;
-    readonly visited?: WeakSet<Element>;
 }
 /**
+ * Dereferences an OpenAPI 2.0 document. Reference Objects and JSON Reference Objects expect
+ * the type of their `referenced-element` meta, Path Item `$ref`s a Path Item Object.
+ *
  * @public
  */
-declare class OpenAPI2DereferenceVisitor {
-    protected readonly indirections: Element[];
-    protected readonly reference: Reference;
-    protected readonly options: ReferenceOptions;
-    protected readonly refractCache: WeakMap<Element, Element>;
-    protected readonly visited: WeakSet<Element>;
+declare class OpenAPI2DereferenceVisitor extends DereferenceVisitor<undefined> {
+    protected get strategyName(): string;
+    protected createVisitor(reference: Reference): OpenAPI2DereferenceVisitor;
     /**
-     * Tracks element ancestors across dive-deep traversal boundaries.
-     * Used for cycle detection: if a referenced element is found in
-     * the ancestor lineage, a circular reference is detected.
+     * A (JSON) Reference Object stands for the type its reference expects: it's dereferenced as that type.
      */
-    protected readonly ancestors: AncestorLineage<Element>;
-    constructor({ reference, options, indirections, ancestors, refractCache, visited, }: OpenAPI2DereferenceVisitorOptions);
-    protected toAncestorLineage(path: Path<Element>): [AncestorLineage<Element>, Set<Element>];
-    protected toBaseURI(uri: string): string;
-    protected toReference(uri: string): Promise<Reference>;
+    protected isOfType(element: Element, type: string): boolean;
     /**
-     * Handles an error according to the continueOnError option.
-     *
-     * For new errors: wraps in UnresolvableReferenceError with structured context
-     * (type, uri, location, codeFrame, refFieldName, refFieldValue, trace).
-     * For errors already wrapped by a nested visitor: prepends the current hop to the trace.
-     *
-     * Inner/intermediate visitors always throw to let the trace accumulate.
-     * Only the entry document visitor respects continueOnError (callback/swallow/throw).
+     * A generic structure holding a `$ref` is a reference to the expected type: a JSON Reference
+     * Object for a Schema Object, a Reference Object otherwise, unless the type has its own `$ref`
+     * field (Path Item Object).
      */
-    protected handleError(message: string, error: Error, referencingElement: Element, refFieldName: string, refFieldValue: string, visitorPath: Path<Element>): void;
+    protected refractTo(element: Element, type: string): Element;
     ReferenceElement(path: Path<Element>): Promise<void>;
     PathItemElement(path: Path<Element>): Promise<void>;
     JSONReferenceElement(path: Path<Element>): Promise<void>;

package/types/dereference/strategies/openapi-3-0/index.d.ts

@@ -13,7 +13,6 @@ export type { default as Parser, ParserOptions } from '../../../parse/parsers/Pa
 export type { default as Resolver, ResolverOptions } from '../../../resolve/resolvers/Resolver.ts';
 export type { default as ResolveStrategy, ResolveStrategyOptions, } from '../../../resolve/strategies/ResolveStrategy.ts';
 export type { default as BundleStrategy, BundleStrategyOptions, } from '../../../bundle/strategies/BundleStrategy.ts';
-export type { AncestorLineage } from '../../util.ts';
 /**
  * @public
  */

package/types/dereference/strategies/openapi-3-0/visitor.d.ts

@@ -1,7 +1,7 @@
 import { Element } from '@speclynx/apidom-datamodel';
 import { type Path } from '@speclynx/apidom-traverse';
+import DereferenceVisitor from '../DereferenceVisitor.ts';
 import Reference from '../../../Reference.ts';
-import { AncestorLineage } from '../../util.ts';
 import type { ReferenceOptions } from '../../../options/index.ts';
 /**
  * @public
@@ -9,41 +9,26 @@ import type { ReferenceOptions } from '../../../options/index.ts';
 export interface OpenAPI3_0DereferenceVisitorOptions {
     readonly reference: Reference;
     readonly options: ReferenceOptions;
-    readonly indirections?: Element[];
-    readonly refractCache?: WeakMap<Element, Element>;
-    readonly ancestors?: AncestorLineage<Element>;
-    readonly visited?: WeakSet<Element>;
 }
 /**
+ * Dereferences an OpenAPI 3.0 document. Reference Objects expect the type of their
+ * `referenced-element` meta, Path Item `$ref`s a Path Item Object. Link Objects get the
+ * Operation Object they point at attached, Example Objects the external value.
+ *
  * @public
  */
-declare class OpenAPI3_0DereferenceVisitor {
-    protected readonly indirections: Element[];
-    protected readonly reference: Reference;
-    protected readonly options: ReferenceOptions;
-    protected readonly refractCache: WeakMap<Element, Element>;
-    protected readonly visited: WeakSet<Element>;
+declare class OpenAPI3_0DereferenceVisitor extends DereferenceVisitor<undefined> {
+    protected get strategyName(): string;
+    protected createVisitor(reference: Reference): OpenAPI3_0DereferenceVisitor;
     /**
-     * Tracks element ancestors across dive-deep traversal boundaries.
-     * Used for cycle detection: if a referenced element is found in
-     * the ancestor lineage, a circular reference is detected.
+     * A Reference Object stands for the type its reference expects: it's dereferenced as that type.
      */
-    protected readonly ancestors: AncestorLineage<Element>;
-    constructor({ reference, options, indirections, ancestors, refractCache, visited, }: OpenAPI3_0DereferenceVisitorOptions);
-    protected toAncestorLineage(path: Path<Element>): [AncestorLineage<Element>, Set<Element>];
-    protected toBaseURI(uri: string): string;
-    protected toReference(uri: string): Promise<Reference>;
+    protected isOfType(element: Element, type: string): boolean;
     /**
-     * Handles an error according to the continueOnError option.
-     *
-     * For new errors: wraps in UnresolvableReferenceError with structured context
-     * (type, uri, location, codeFrame, refFieldName, refFieldValue, trace).
-     * For errors already wrapped by a nested visitor: prepends the current hop to the trace.
-     *
-     * Inner/intermediate visitors always throw to let the trace accumulate.
-     * Only the entry document visitor respects continueOnError (callback/swallow/throw).
+     * A generic structure holding a `$ref` is a Reference Object to the expected type,
+     * unless the type has its own `$ref` field (Path Item Object).
      */
-    protected handleError(message: string, error: Error, referencingElement: Element, refFieldName: string, refFieldValue: string, visitorPath: Path<Element>): void;
+    protected refractTo(element: Element, type: string): Element;
     ReferenceElement(path: Path<Element>): Promise<void>;
     PathItemElement(path: Path<Element>): Promise<void>;
     LinkElement(path: Path<Element>): Promise<void>;

package/types/dereference/strategies/openapi-3-1/index.d.ts

@@ -13,7 +13,6 @@ export type { default as Parser, ParserOptions } from '../../../parse/parsers/Pa
 export type { default as Resolver, ResolverOptions } from '../../../resolve/resolvers/Resolver.ts';
 export type { default as ResolveStrategy, ResolveStrategyOptions, } from '../../../resolve/strategies/ResolveStrategy.ts';
 export type { default as BundleStrategy, BundleStrategyOptions, } from '../../../bundle/strategies/BundleStrategy.ts';
-export type { AncestorLineage } from '../../util.ts';
 /**
  * @public
  */

package/types/dereference/strategies/openapi-3-1/visitor.d.ts

@@ -1,65 +1,69 @@
 import { Element } from '@speclynx/apidom-datamodel';
 import { type Path } from '@speclynx/apidom-traverse';
 import { type Schema$idIndex } from './selectors/uri.ts';
+import DereferenceVisitor from '../DereferenceVisitor.ts';
 import Reference from '../../../Reference.ts';
-import { AncestorLineage } from '../../util.ts';
 import type { ReferenceOptions } from '../../../options/index.ts';
+/**
+ * Context of a source being dereferenced: the `$id`s of the Schema Objects enclosing it.
+ */
+interface OpenAPI3_1DereferenceContext {
+    readonly ancestorSchema$ids: string[];
+}
 /**
  * @public
  */
 export interface OpenAPI3_1DereferenceVisitorOptions {
     readonly reference: Reference;
     readonly options: ReferenceOptions;
-    readonly indirections?: Element[];
-    readonly refractCache?: WeakMap<Element, Element>;
     readonly schema$idIndex?: Schema$idIndex;
-    readonly ancestors?: AncestorLineage<Element>;
-    readonly visited?: WeakSet<Element>;
     readonly ancestorSchema$ids?: string[];
 }
 /**
+ * Dereferences an OpenAPI 3.1 document. Reference Objects expect the type of their
+ * `referenced-element` meta, Path Item `$ref`s a Path Item, Schema Object `$ref`s a Schema Object.
+ * Link Objects get the Operation Object they point at attached, Example Objects
+ * the external value.
+ *
  * @public
  */
-declare class OpenAPI3_1DereferenceVisitor {
-    protected readonly indirections: Element[];
-    protected readonly reference: Reference;
-    protected readonly options: ReferenceOptions;
-    protected readonly refractCache: WeakMap<Element, Element>;
+declare class OpenAPI3_1DereferenceVisitor extends DereferenceVisitor<OpenAPI3_1DereferenceContext> {
     /**
-     * Index of `$id`-bearing schemas per document, shared across nested visitors
-     * of a single dereference run so it never outlives mutations of the documents.
+     * Index of `$id`-bearing schemas per document, shared across the visitors
+     * of a single dereference run.
      */
     protected readonly schema$idIndex: Schema$idIndex;
-    protected readonly visited: WeakSet<Element>;
     /**
      * `$id`s of the JSON Schema elements enclosing the traversal root within its
      * document (outermost first). Empty when the root is the document itself; a
-     * nested visitor traversing a fragment is seeded with the `$id`s of the
-     * schemas the fragment sits under, so the `$ref`s and `$id`s within resolve
-     * against the same base as they would from the document root.
+     * visitor traversing a fragment is seeded with the `$id`s of the schemas the
+     * fragment sits under, so the `$ref`s and `$id`s within resolve against the
+     * same base as they would from the document root.
      */
     protected readonly ancestorSchema$ids: string[];
+    constructor({ reference, options, schema$idIndex, ancestorSchema$ids, }: OpenAPI3_1DereferenceVisitorOptions);
+    protected get strategyName(): string;
+    protected createVisitor(reference: Reference, { ancestorSchema$ids }: OpenAPI3_1DereferenceContext): OpenAPI3_1DereferenceVisitor;
+    /**
+     * A Reference Object stands for the type its reference expects: it's dereferenced as that type.
+     */
+    protected isOfType(element: Element, type: string): boolean;
+    /**
+     * A generic structure holding a `$ref` is a Reference Object to the expected type,
+     * unless the type has its own `$ref` field (Path Item Object, Schema Object).
+     */
+    protected refractTo(element: Element, type: string): Element;
     /**
-     * Tracks element ancestors across dive-deep traversal boundaries.
-     * Used for cycle detection: if a referenced element is found in
-     * the ancestor lineage, a circular reference is detected.
+     * A document as Schema Object for locating schemas within it: a generic document is
+     * refracted to Schema Object once per dereference run, a semantic one is used as it is.
      */
-    protected readonly ancestors: AncestorLineage<Element>;
-    constructor({ reference, options, indirections, refractCache, schema$idIndex, ancestors, visited, ancestorSchema$ids, }: OpenAPI3_1DereferenceVisitorOptions);
-    protected toAncestorLineage(path: Path<Element>): [AncestorLineage<Element>, Set<Element>];
-    protected toBaseURI(uri: string): string;
-    protected toReference(uri: string): Promise<Reference>;
+    protected toSchemaDocument(document: Element): Element;
     /**
-     * Handles an error according to the continueOnError option.
-     *
-     * For new errors: wraps in UnresolvableReferenceError with structured context
-     * (type, uri, location, codeFrame, refFieldName, refFieldValue, trace).
-     * For errors already wrapped by a nested visitor: prepends the current hop to the trace.
-     *
-     * Inner/intermediate visitors always throw to let the trace accumulate.
-     * Only the entry document visitor respects continueOnError (callback/swallow/throw).
+     * Indexes the `$id`-bearing schemas of an element for the run. Transcluded elements aren't
+     * indexed: they're copies of structures indexed where they're defined,
+     * and in a document dereferenced in place their shared structure would be walked once per path.
      */
-    protected handleError(message: string, error: Error, referencingElement: Element, refFieldName: string, refFieldValue: string, visitorPath: Path<Element>): void;
+    protected index$ids(element: Element): void;
     ReferenceElement(path: Path<Element>): Promise<void>;
     PathItemElement(path: Path<Element>): Promise<void>;
     LinkElement(path: Path<Element>): Promise<void>;

package/types/index.d.ts

@@ -13,7 +13,6 @@ export type { ResolverOptions } from './resolve/resolvers/Resolver.ts';
 export type { ResolveStrategyOptions } from './resolve/strategies/ResolveStrategy.ts';
 export { default as DereferenceStrategy } from './dereference/strategies/DereferenceStrategy.ts';
 export type { DereferenceStrategyOptions } from './dereference/strategies/DereferenceStrategy.ts';
-export { AncestorLineage as DereferenceAncestorLineage } from './dereference/util.ts';
 export { default as BundleStrategy } from './bundle/strategies/BundleStrategy.ts';
 export type { BundleStrategyOptions } from './bundle/strategies/BundleStrategy.ts';
 export type { ComponentNamesStrategy, ComponentNameResolver, ComponentNameResolverArgs, ComponentNameCollisionSeverity, } from './options/index.ts';

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