import type * as pkgTypes from '@flex-development/pkg-types';
import type { ImportsSubpath, PackageJson, Exports, ExportsObject, Imports } from '@flex-development/pkg-types';

/**
 * @file Interfaces - Aliases
 * @module mlly/interfaces/Aliases
 */
/**
 * Record, where each key is a path alias or pattern and each value
 * is a path mapping configuration.
 *
 * This interface can be augmented to register custom aliases.
 *
 * @example
 *  declare module '@flex-development/mlly' {
 *    interface Aliases {
 *      custom?: string[] | string | null
 *    }
 *  }
 */
interface Aliases {
    [alias: string]: (string | null | undefined)[] | string | null | undefined;
}

/**
 * @file Interfaces - BufferEncodingMap
 * @module mlly/interfaces/BufferEncodingMap
 */
/**
 * Registry of character encodings that can be used when working
 * with {@linkcode Buffer} objects.
 *
 * This interface can be augmented to register custom encodings.
 *
 * @example
 *  declare module '@flex-development/mlly' {
 *    interface BufferEncodingMap {
 *      custom: 'custom'
 *    }
 *  }
 */
interface BufferEncodingMap {
    ascii: 'ascii';
    base64: 'base64';
    base64url: 'base64url';
    binary: 'binary';
    hex: 'hex';
    latin1: 'latin1';
    ucs2: 'ucs2' | 'ucs-2';
    utf16le: 'utf16le' | 'utf-16le';
    utf8: 'utf8' | 'utf-8';
}

/**
 * @file Interfaces - ConditionMap
 * @module mlly/interfaces/ConditionMap
 */

/**
 * Registry of export/import conditions.
 *
 * This interface can be augmented to register custom conditions.
 *
 * @see {@linkcode pkgTypes.ConditionMap}
 *
 * @example
 *  declare module '@flex-development/mlly' {
 *    interface ConditionMap {
 *      custom: 'custom'
 *    }
 *  }
 *
 * @extends {pkgTypes.ConditionMap}
 */
interface ConditionMap extends pkgTypes.ConditionMap {
}

/**
 * @file Interfaces - FileSystem
 * @module mlly/interfaces/FileSystem
 */

/**
 * The file system API.
 */
interface FileSystem {
    /**
     * Read the entire contents of a file.
     *
     * @see {@linkcode ReadFile}
     */
    readFile: ReadFile;
    /**
     * Compute a canonical pathname by resolving `.`, `..`, and symbolic links.
     *
     * @see {@linkcode Realpath}
     */
    realpath: Realpath;
    /**
     * Get information about a directory or file.
     *
     * @see {@linkcode Stat}
     */
    stat: Stat;
}

/**
 * @file Interfaces - GetSourceContext
 * @module mlly/interfaces/GetSourceContext
 */

/**
 * Source code retrieval context.
 *
 * @see {@linkcode GetSourceOptions}
 *
 * @extends {GetSourceOptions}
 */
interface GetSourceContext extends GetSourceOptions {
    /**
     * The file system API.
     *
     * @see {@linkcode FileSystem}
     *
     * @override
     */
    fs: FileSystem;
    /**
     * Record, where each key is a URL protocol
     * and each value is a source code handler.
     *
     * @see {@linkcode GetSourceHandlers}
     *
     * @override
     */
    handlers: GetSourceHandlers;
    /**
     * Request options for network based modules.
     *
     * @override
     */
    req: RequestInit;
    /**
     * The list of supported URL schemes.
     *
     * @override
     */
    schemes: Set<string>;
}

/**
 * @file Interfaces - GetSourceOptions
 * @module mlly/interfaces/GetSourceOptions
 */

/**
 * Options for retrieving source code.
 */
interface GetSourceOptions {
    /**
     * The encoding of the result.
     *
     * > 👉 **Note**: Used when the `file:` handler is called.
     *
     * @see {@linkcode BufferEncoding}
     */
    encoding?: BufferEncoding | null | undefined;
    /**
     * The module format hint.
     *
     * @see {@linkcode ModuleFormat}
     */
    format?: ModuleFormat | null | undefined;
    /**
     * The file system API.
     *
     * @see {@linkcode FileSystem}
     */
    fs?: FileSystem | null | undefined;
    /**
     * Record, where each key is a URL protocol
     * and each value is a source code handler.
     *
     * @see {@linkcode GetSourceHandlers}
     */
    handlers?: GetSourceHandlers | null | undefined;
    /**
     * Whether to ignore [`ERR_UNSUPPORTED_ESM_URL_SCHEME`][err] if thrown.
     *
     * [err]: https://nodejs.org/api/errors.html#err_unsupported_esm_url_scheme
     */
    ignoreErrors?: boolean | null | undefined;
    /**
     * Request options for network based modules.
     */
    req?: RequestInit | null | undefined;
    /**
     * The list of supported URL schemes.
     *
     * @see {@linkcode List}
     *
     * @default ['data','file','http','https','node']
     */
    schemes?: List<string> | null | undefined;
}

/**
 * @file Interfaces - IsDirectory
 * @module mlly/interfaces/IsDirectory
 */
/**
 * Check if a stats object describes a directory.
 */
interface IsDirectory {
    /**
     * @this {unknown}
     *
     * @return {boolean}
     *  `true` if stats describes directory, `false` otherwise
     */
    (): boolean;
}

/**
 * @file Interfaces - IsFile
 * @module mlly/interfaces/IsFile
 */
/**
 * Check if a stats object describes a file.
 */
interface IsFile {
    /**
     * @this {void}
     *
     * @return {boolean}
     *  `true` if stats object describes regular file, `false` otherwise
     */
    (): boolean;
}

/**
 * @file Interfaces - MainFieldMap
 * @module mlly/interfaces/MainFieldMap
 */
/**
 * Registry of main fields.
 *
 * This interface can be augmented to register custom main fields.
 *
 * @example
 *  declare module '@flex-development/mlly' {
 *    interface MainFieldMap {
 *      unpkg: 'unpkg'
 *    }
 *  }
 */
interface MainFieldMap {
    main: 'main';
    module: 'module';
    types: 'types';
}

/**
 * @file Interfaces - ModuleFormatMap
 * @module mlly/interfaces/ModuleFormatMap
 */
/**
 * Registry of module formats.
 *
 * This interface can be augmented to register custom module formats.
 *
 * @example
 *  declare module '@flex-development/mlly' {
 *    interface ModuleFormatMap {
 *      custom: 'custom'
 *    }
 *  }
 */
interface ModuleFormatMap {
    builtin: 'builtin';
    commonjs: 'commonjs';
    cts: 'commonjs-typescript';
    json: 'json';
    module: 'module';
    mts: 'module-typescript';
    wasm: 'wasm';
}

/**
 * @file Interfaces - PatternKeyComparisonMap
 * @module mlly/interfaces/PatternKeyComparisonMap
 */
/**
 * Registry of `PATTERN_KEY_COMPARE` algorithm results.
 *
 * This interface can be augmented to register custom results.
 *
 * @example
 *  declare module '@flex-development/mlly' {
 *    interface PatternKeyComparisonMap {
 *      afterThree: 3
 *    }
 *  }
 */
interface PatternKeyComparisonMap {
    /**
     * `a` should come after `b`.
     */
    after: 1;
    /**
     * `a` should come before `b`.
     */
    before: -1;
    /**
     * `a` and `b` are equal.
     */
    equal: 0;
}

/**
 * @file Interfaces - ProtocolMap
 * @module mlly/interfaces/ProtocolMap
 */
/**
 * Registry of URL protocols.
 *
 * This interface can be augmented to register custom protocols.
 *
 * @see https://nodejs.org/api/url.html#urlprotocol
 * @see https://iana.org/assignments/uri-schemes/uri-schemes.xhtml
 * @see https://url.spec.whatwg.org/#special-scheme
 *
 * @example
 *  declare module '@flex-development/mlly' {
 *    interface ProtocolMap {
 *      custom: 'custom:'
 *    }
 *  }
 */
interface ProtocolMap {
    blob: 'blob:';
    content: 'content:';
    cvs: 'cvs:';
    data: 'data:';
    dns: 'dns:';
    file: 'file:';
    fish: 'fish:';
    ftp: 'ftp:';
    git: 'git:';
    http: 'http:';
    https: 'https:';
    mvn: 'mvn:';
    node: 'node:';
    redis: 'redis:';
    sftp: 'sftp:';
    ssh: 'ssh:';
    svn: 'svn:';
    urn: 'urn:';
    viewSource: 'view-source:';
    ws: 'ws:';
    wss: 'wss:';
}

/**
 * @file Interfaces - ReadFile
 * @module mlly/interfaces/ReadFile
 */

/**
 * Read the entire contents of a file.
 */
interface ReadFile {
    /**
     * @see {@linkcode ModuleId}
     *
     * @this {unknown}
     *
     * @param {ModuleId} id
     *  The module id
     * @param {BufferEncoding} encoding
     *  The encoding of the file contents
     * @return {Awaitable<string>}
     *  The file contents
     */
    (id: ModuleId, encoding: BufferEncoding): Awaitable<string>;
    /**
     * @see {@linkcode Awaitable}
     * @see {@linkcode FileContent}
     * @see {@linkcode ModuleId}
     *
     * @template {Awaitable<FileContent | null | undefined>} T
     *  The file contents
     *
     * @this {unknown}
     *
     * @param {ModuleId} id
     *  The module id
     * @param {BufferEncoding | null | undefined} [encoding]
     *  The encoding of the file contents
     * @return {T}
     *  The file contents
     */
    <T extends Awaitable<FileContent | null | undefined>>(id: ModuleId, encoding?: BufferEncoding | null | undefined): T;
}

/**
 * @file Interfaces - Realpath
 * @module mlly/interfaces/Realpath
 */

/**
 * Compute a canonical pathname by resolving `.`, `..`, and symbolic links.
 *
 * > 👉 **Note**: A canonical pathname is not necessarily unique.
 * > Hard links and bind mounts can expose an entity through many pathnames.
 */
interface Realpath {
    /**
     * @see {@linkcode Awaitable}
     * @see {@linkcode ModuleId}
     *
     * @template {Awaitable<string>} T
     *  The canonical pathname
     *
     * @this {unknown}
     *
     * @param {ModuleId} id
     *  The module id
     * @return {T}
     *  The canonical pathname
     */
    <T extends Awaitable<string>>(id: ModuleId): T;
}

/**
 * @file Interfaces - ResolveAliasOptions
 * @module mlly/interfaces/ResolveAliasOptions
 */

/**
 * Options for path alias resolution.
 */
interface ResolveAliasOptions {
    /**
     * Whether the resolved specifier should be absolute.
     *
     * If `true`, the resolved specifier will be a [`file:` URL][file-url].
     *
     * [file-url]: https://nodejs.org/api/esm.html#file-urls
     *
     * @see https://nodejs.org/api/esm.html#terminology
     */
    absolute?: boolean | null | undefined;
    /**
     * The path mappings dictionary.
     *
     * > 👉 **Note**: Paths should be relative to {@linkcode cwd}.
     *
     * @see {@linkcode Aliases}
     */
    aliases?: Aliases | null | undefined;
    /**
     * The URL of the directory to resolve non-absolute modules from.
     *
     * @see {@linkcode ModuleId}
     *
     * @default cwd()
     */
    cwd?: ModuleId | null | undefined;
    /**
     * The URL of the parent module.
     *
     * @see {@linkcode ModuleId}
     */
    parent?: ModuleId | null | undefined;
}

/**
 * @file Interfaces - ResolveModuleOptions
 * @module mlly/interfaces/ResolveModuleOptions
 */

/**
 * Options for module resolution.
 */
interface ResolveModuleOptions {
    /**
     * The path mappings dictionary.
     *
     * > 👉 **Note**: Paths should be relative to {@linkcode cwd}.
     *
     * @see {@linkcode Aliases}
     */
    aliases?: Aliases | null | undefined;
    /**
     * The list of export/import conditions.
     *
     * > 👉 **Note**: Should be sorted by priority.
     *
     * @see {@linkcode Condition}
     * @see {@linkcode List}
     * @see https://nodejs.org/api/packages.html#conditional-exports
     *
     * @default defaultConditions
     */
    conditions?: List<Condition> | null | undefined;
    /**
     * The URL of the directory to resolve path {@linkcode aliases} from.
     *
     * @see {@linkcode ModuleId}
     *
     * @default cwd()
     */
    cwd?: ModuleId | null | undefined;
    /**
     * A replacement file extension, a record of replacement file extensions,
     * or a function that returns a replacement file extension.
     *
     * > 👉 **Note**: Replacement file extensions are normalized and do not
     * > need to begin with a dot character (`'.'`); an empty string (`''`),
     * > `false`, or `null` will remove an extension.
     *
     * @see {@linkcode ExtensionRewrites}
     * @see {@linkcode GetNewExtension}
     */
    ext?: ExtensionRewrites | GetNewExtension | string | false | null | undefined;
    /**
     * The module extensions to probe for.
     *
     * > 👉 **Note**: Should be sorted by priority.
     *
     * @see {@linkcode List}
     *
     * @default defaultExtensions
     */
    extensions?: List<string> | null | undefined;
    /**
     * The file system API.
     *
     * @see {@linkcode FileSystem}
     */
    fs?: FileSystem | null | undefined;
    /**
     * The list of legacy `main` fields.
     *
     * > 👉 **Note**: Should be sorted by priority.
     *
     * @see {@linkcode List}
     * @see {@linkcode MainField}
     *
     * @default defaultMainFields
     */
    mainFields?: List<MainField> | null | undefined;
    /**
     * Whether to keep symlinks instead of resolving them.
     */
    preserveSymlinks?: boolean | null | undefined;
}

/**
 * @file Interfaces - Stat
 * @module mlly/interfaces/Stat
 */

/**
 * Get information about a directory or file.
 */
interface Stat {
    /**
     * @see {@linkcode Awaitable}
     * @see {@linkcode ModuleId}
     * @see {@linkcode Stats}
     *
     * @template {Awaitable<Stats>} T
     *  The info
     *
     * @this {unknown}
     *
     * @param {ModuleId} id
     *  The module id
     * @return {T}
     *  The info
     */
    <T extends Awaitable<Stats>>(id: ModuleId): T;
}

/**
 * @file Interfaces - Stats
 * @module mlly/interfaces/Stats
 */

/**
 * An object describing a directory or file.
 */
interface Stats {
    /**
     * Check if the stats object describes a directory.
     *
     * @see {@linkcode IsDirectory}
     */
    isDirectory: IsDirectory;
    /**
     * Check if the stats object describes a file.
     *
     * @see {@linkcode IsFile}
     */
    isFile: IsFile;
}

/**
 * @file canParseUrl
 * @module mlly/lib/canParseUrl
 */
/**
 * Check if `input` can be parsed to a {@linkcode URL}.
 *
 * > 👉 **Note**: If `input` is relative, `base` is required.
 * > If `input` is absolute, `base` is ignored.
 *
 * @see {@linkcode ModuleId}
 *
 * @this {void}
 *
 * @param {unknown} input
 *  The input URL
 * @param {unknown} [base]
 *  The base URL to resolve against if `input` is not absolute
 * @return {boolean}
 *  `true` if `input` can be parsed to a `URL`, `false` otherwise
 */
declare function canParseUrl(this: void, input: unknown, base?: unknown): boolean;

/**
 * @file cwd
 * @module mlly/lib/cwd
 */
/**
 * Get the URL of the current working directory.
 *
 * @this {void}
 *
 * @return {URL}
 *  The current working directory URL
 */
declare function cwd(this: void): URL;

/**
 * @file defaultConditions
 * @module mlly/lib/defaultConditions
 */

/**
 * The default list of conditions.
 *
 * @see {@linkcode Condition}
 * @see https://nodejs.org/api/packages.html#conditional-exports
 *
 * @const {Set<Condition>} defaultConditions
 */
declare const defaultConditions: Set<Condition>;

/**
 * @file defaultExtensions
 * @module mlly/lib/defaultExtensions
 */

/**
 * The default list of resolvable file extensions.
 *
 * @see {@linkcode Ext}
 *
 * @const {Set<Ext>} defaultExtensions
 */
declare const defaultExtensions: Set<Ext>;

/**
 * @file defaultMainFields
 * @module mlly/lib/defaultMainFields
 */

/**
 * The default list of main fields.
 *
 * @see {@linkcode MainField}
 *
 * @const {Set<MainField>} defaultMainFields
 */
declare const defaultMainFields: Set<MainField>;

/**
 * @file extensionFormatMap
 * @module mlly/lib/extensionFormatMap
 */

/**
 * Map, where each key is a file extension
 * and each value is a default module format.
 *
 * @see {@linkcode Ext}
 * @see {@linkcode ModuleFormat}
 *
 * @const {Map<Ext, ModuleFormat>} extensionFormatMap
 */
declare const extensionFormatMap: Map<Ext, ModuleFormat>;

/**
 * @file formats
 * @module mlly/lib/formats
 */
/**
 * Default module formats.
 *
 * @see {@linkcode ModuleFormat}
 *
 * @enum {ModuleFormat}
 */
declare const enum formats {
    builtin = "builtin",
    commonjs = "commonjs",
    cts = "commonjs-typescript",
    json = "json",
    module = "module",
    mts = "module-typescript",
    wasm = "wasm"
}

/**
 * @file getSource
 * @module mlly/lib/getSource
 */

/**
 * Get the source code for a module.
 *
 * @see {@linkcode EmptyString}
 * @see {@linkcode GetSourceOptions}
 *
 * @this {void}
 *
 * @param {EmptyString | null | undefined} id
 *  The module id
 * @param {GetSourceOptions | null | undefined} [options]
 *  Source code retrieval options
 * @return {null}
 *  The module source code
 */
declare function getSource(this: void, id: EmptyString | null | undefined, options?: GetSourceOptions | null | undefined): null;
/**
 * Get the source code for a module.
 *
 * > 👉 **Note**: Returns a promise if the handler for `id` is async.
 *
 * @see {@linkcode Awaitable}
 * @see {@linkcode ErrUnsupportedEsmUrlScheme}
 * @see {@linkcode GetSourceOptions}
 * @see {@linkcode ModuleId}
 *
 * @template {Awaitable<FileContent | null | undefined>} T
 *  The module source code
 *
 * @this {void}
 *
 * @param {ModuleId | null | undefined} id
 *  The module id
 * @param {GetSourceOptions | null | undefined} [options]
 *  Source code retrieval options
 * @return {T}
 *  The module source code
 * @throws {ErrUnsupportedEsmUrlScheme}
 */
declare function getSource<T extends Awaitable<FileContent | null | undefined>>(this: void, id: ModuleId | null | undefined, options?: GetSourceOptions | null | undefined): T;

/**
 * @file isAbsoluteSpecifier
 * @module mlly/lib/isAbsoluteSpecifier
 */
/**
 * Check if `value` is an *absolute specifier*.
 *
 * ::: warning
 * Only checks specifier syntax.
 * Does **not** guarantee the specifier references an existing module.
 * :::
 *
 * @see https://nodejs.org/api/esm.html#terminology
 *
 * @this {void}
 *
 * @param {unknown} value
 *  The value to check
 * @return {boolean}
 *  `true` if `value` is absolute specifier, `false` otherwise
 */
declare function isAbsoluteSpecifier(this: void, value: unknown): boolean;

/**
 * @file isArrayIndex
 * @module mlly/lib/isArrayIndex
 */

/**
 * Check if `value` is a valid array index.
 *
 * @see {@linkcode Numeric}
 *
 * @this {void}
 *
 * @param {unknown} value
 *  The value to check
 * @return {value is Numeric}
 *  `true` if `value` is valid array index, `false` otherwise
 */
declare function isArrayIndex(this: void, value: unknown): value is Numeric;

/**
 * @file isBareSpecifier
 * @module mlly/lib/isBareSpecifier
 */
/**
 * Check if `value` is a *bare specifier*.
 *
 * ::: warning
 * Only checks specifier syntax.
 * Does **not** guarantee the specifier references an existing module.
 * :::
 *
 * @see https://nodejs.org/api/esm.html#terminology
 *
 * @this {void}
 *
 * @param {unknown} value
 *  The value to check
 * @return {boolean}
 *  `true` if `value` is bare specifier, `false` otherwise
 */
declare function isBareSpecifier(this: void, value: unknown): boolean;

/**
 * @file isDirectory
 * @module mlly/lib/isDirectory
 */

/**
 * Check if a directory exists.
 *
 * > 👉 **Note**: Returns a promise if `fs.stat` is async.
 *
 * @see {@linkcode Awaitable}
 * @see {@linkcode FileSystem}
 *
 * @template {Awaitable<boolean>} T
 *  The result of the check
 *
 * @this {void}
 *
 * @param {unknown} id
 *  The module id to check
 * @param {FileSystem | null | undefined} fs
 *  The file system API
 * @return {T}
 *  `true` if directory exists at `id`, `false` otherwise
 */
declare function isDirectory<T extends Awaitable<boolean>>(this: void, id: unknown, fs?: FileSystem | null | undefined): T;

/**
 * @file isFile
 * @module mlly/lib/isFile
 */

/**
 * Check if a file exists.
 *
 * > 👉 **Note**: Returns a promise if `fs.stat` is async.
 *
 * @see {@linkcode Awaitable}
 * @see {@linkcode FileSystem}
 *
 * @template {Awaitable<boolean>} T
 *  The result of the check
 *
 * @this {void}
 *
 * @param {unknown} id
 *  The module id to check
 * @param {FileSystem | null | undefined} fs
 *  The file system API
 * @return {T}
 *  `true` if file exists at `id`, `false` otherwise
 */
declare function isFile<T extends Awaitable<boolean>>(this: void, id: unknown, fs?: FileSystem | null | undefined): T;

/**
 * @file isImportsSubpath
 * @module mlly/lib/isImportsSubpath
 */

/**
 * Check if `value` is an [`imports`][subpath-imports] subpath.
 *
 * ::: warning
 * Only checks specifier syntax.
 * Does **not** guarantee the specifier references an existing module.
 * :::
 *
 * [subpath-imports]: https://nodejs.org/api/packages.html#subpath-imports
 *
 * @see {@linkcode ImportsSubpath}
 *
 * @this {void}
 *
 * @param {unknown} value
 *  The value to check
 * @return {value is ImportsSubpath}
 *  `true` if `value` is `imports` subpath, `false` otherwise
 */
declare function isImportsSubpath(this: void, value: unknown): value is ImportsSubpath;

/**
 * @file isModuleId
 * @module mlly/lib/isModuleId
 */

/**
 * Check if `value` is a module id.
 *
 * ::: warning
 * Does **not** guarantee `value` references an existing file or directory.
 * :::
 *
 * @see {@linkcode ModuleId}
 *
 * @this {void}
 *
 * @param {unknown} value
 *  The value to check
 * @return {value is ModuleId}
 *  `true` if `value` is module id, `false` otherwise
 */
declare function isModuleId(this: void, value: unknown): value is ModuleId;

/**
 * @file isRelativeSpecifier
 * @module mlly/lib/isRelativeSpecifier
 */
/**
 * Check if `value` is a *relative specifier*.
 *
 * ::: warning
 * Only checks specifier syntax.
 * Does **not** guarantee the specifier references an existing module.
 * :::
 *
 * @see https://nodejs.org/api/esm.html#terminology
 *
 * @this {void}
 *
 * @param {unknown} value
 *  The value to check
 * @return {boolean}
 *  `true` if `value` is relative specifier, `false` otherwise
 */
declare function isRelativeSpecifier(this: void, value: unknown): boolean;

/**
 * @file lookupPackageScope
 * @module mlly/lib/lookupPackageScope
 */

/**
 * Get the package scope URL for a module `url`.
 *
 * @see {@linkcode EmptyString}
 *
 * @this {void}
 *
 * @param {EmptyString | null | undefined} url
 *  The URL of the module to scope
 * @param {ModuleId | null | undefined} [end]
 *  The URL of the directory to end search at, defaults to {@linkcode root}
 * @param {FileSystem | null | undefined} [fs]
 *  The file system API
 * @return {null}
 *  The URL of nearest directory containing a `package.json` file
 */
declare function lookupPackageScope(this: void, url: EmptyString | null | undefined, end?: ModuleId | null | undefined, fs?: FileSystem | null | undefined): null;
/**
 * Get the package scope URL for a module `url`.
 *
 * Implements the `LOOKUP_PACKAGE_SCOPE` algorithm.
 *
 * > 👉 **Note**: Returns a promise if `fs.stat` is async.
 *
 * @see {@linkcode Awaitable}
 * @see {@linkcode FileSystem}
 * @see {@linkcode ModuleId}
 *
 * @template {Awaitable<URL | null>} T
 *  The resolved package scope URL
 *
 * @this {void}
 *
 * @param {ModuleId | null | undefined} url
 *  The URL of the module to scope
 * @param {ModuleId | null | undefined} [end]
 *  The URL of the directory to end search at, defaults to {@linkcode root}
 * @param {FileSystem | null | undefined} [fs]
 *  The file system API
 * @return {T}
 *  The URL of nearest directory containing a `package.json` file
 */
declare function lookupPackageScope<T extends Awaitable<URL | null>>(this: void, url: ModuleId | null | undefined, end?: ModuleId | null | undefined, fs?: FileSystem | null | undefined): T;

/**
 * @file patternKeyCompare
 * @module mlly/lib/patternKeyCompare
 */

/**
 * Compare two pattern keys and return a value indicating their order.
 *
 * Implements the `PATTERN_KEY_COMPARE` algorithm.
 *
 * @see {@linkcode PatternKeyComparison}
 *
 * @this {void}
 *
 * @param {string} a
 *  The first key
 * @param {string} b
 *  The key to compare against `a`
 * @return {PatternKeyComparison}
 *  The pattern key comparsion result
 */
declare function patternKeyCompare(this: void, a: string, b: string): PatternKeyComparison;
declare namespace patternKeyCompare {
    var EQUAL: 0;
    var GREATER_THAN: 1;
    var LESS_THAN: -1;
}

/**
 * @file patternMatch
 * @module mlly/lib/patternMatch
 */

/**
 * Get a subpath pattern match for `matchKey`.
 *
 * @see {@linkcode PatternMatch}
 *
 * @this {void}
 *
 * @param {string} matchKey
 *  The key to expand
 * @param {unknown} matchObject
 *  The match keys object
 * @return {PatternMatch | null}
 *  List, where the first item is the key of a package exports
 *  or imports target object, and the last is a subpath pattern match
 */
declare function patternMatch(this: void, matchKey: string, matchObject: unknown): PatternMatch | null;

/**
 * @file readPackageJson
 * @module mlly/lib/readPackageJson
 */

/**
 * Read a `package.json` file.
 *
 * @see {@linkcode EmptyString}
 *
 * @this {void}
 *
 * @param {EmptyString | null | undefined} id
 *  The URL of the package directory, the `package.json` file,
 *  or a module in the same directory as a `package.json`
 * @param {string | null | undefined} [specifier]
 *  The module specifier that initiated the reading of the `package.json` file
 *  > 👉 **Note**: Should be a `file:` URL if `parent` is not a URL
 * @param {ModuleId | null | undefined} [parent]
 *  The URL of the parent module
 * @param {FileSystem | null | undefined} [fs]
 *  The file system API
 * @return {null}
 *  The parsed file contents
 */
declare function readPackageJson(this: void, id: EmptyString | null | undefined, specifier?: string | null | undefined, parent?: ModuleId | null | undefined, fs?: FileSystem | null | undefined): null;
/**
 * Read a `package.json` file.
 *
 * Implements the `READ_PACKAGE_JSON` algorithm.
 *
 * > 👉 **Note**: Returns a promise if `fs.readFile` or `fs.stat` is async.
 *
 * @see {@linkcode Awaitable}
 * @see {@linkcode ErrInvalidPackageConfig}
 * @see {@linkcode FileSystem}
 * @see {@linkcode ModuleId}
 * @see {@linkcode PackageJson}
 *
 * @template {Awaitable<PackageJson | null>} T
 *  The parsed file contents
 *
 * @this {void}
 *
 * @param {ModuleId | null | undefined} id
 *  The URL of the package directory, the `package.json` file,
 *  or a module in the same directory as a `package.json`
 * @param {string | null | undefined} [specifier]
 *  The module specifier that initiated the reading of the `package.json` file
 *  > 👉 **Note**: Should be a `file:` URL if `parent` is not a URL
 * @param {ModuleId | null | undefined} [parent]
 *  The URL of the parent module
 * @param {FileSystem | null | undefined} [fs]
 *  The file system API
 * @return {T}
 *  The parsed file contents
 * @throws {ErrInvalidPackageConfig}
 *  If `package.json` file does not parse as valid JSON
 *  or package manifest object is not a JSON object
 */
declare function readPackageJson<T extends Awaitable<PackageJson | null>>(this: void, id: ModuleId | null | undefined, specifier?: string | null | undefined, parent?: ModuleId | null | undefined, fs?: FileSystem | null | undefined): T;

/**
 * @file resolveAlias
 * @module mlly/lib/resolveAlias
 */

/**
 * Resolve an aliased `specifier`.
 *
 * @see {@linkcode ResolveAliasOptions}
 *
 * @this {void}
 *
 * @param {string} specifier
 *  The specifier using an alias
 * @param {ResolveAliasOptions | null | undefined} [options]
 *  Options for alias resolution
 * @return {string | null}
 *  The specifier of the aliased module
 */
declare function resolveAlias(this: void, specifier: string, options?: ResolveAliasOptions | null | undefined): string | null;

/**
 * @file resolveModule
 * @module mlly/lib/resolveModule
 */

/**
 * Resolve a module `specifier`.
 *
 * Implements the `ESM_RESOLVE` algorithm, mostly 😉.
 *
 * Adds support for:
 *
 * - Extensionless and directory index resolution
 * - Path alias resolution
 * - Rewrite file extensions
 * - Scopeless `@types/*` resolution (i.e. `unist` -> `@types/unist`)
 *
 * > 👉 **Note**: Returns a promise if {@linkcode moduleResolve}
 * > returns a promise.
 *
 * @see {@linkcode Awaitable}
 * @see {@linkcode ModuleId}
 * @see {@linkcode NodeError}
 * @see {@linkcode ResolveModuleOptions}
 *
 * @template {Awaitable<URL>} T
 *  The resolved URL
 *
 * @this {void}
 *
 * @param {ModuleId} specifier
 *  The module specifier to resolve
 * @param {ModuleId} parent
 *  The URL of the parent module
 * @param {ResolveModuleOptions | null | undefined} [options]
 *  Options for module resolution
 * @return {T}
 *  The resolved URL
 * @throws {NodeError}
 */
declare function resolveModule<T extends Awaitable<URL>>(this: void, specifier: ModuleId, parent: ModuleId, options?: ResolveModuleOptions | null | undefined): T;

/**
 * @file resolver
 * @module mlly/lib/resolver
 */

declare module '@flex-development/errnode' {
    interface ErrUnsupportedDirImport {
        /**
         * The directory URL.
         */
        url?: string | null | undefined;
    }
}

/**
 * Resolve a [`main`][main]-like package entry point.
 *
 * Implements the `LEGACY_MAIN_RESOLVE` algorithm.
 *
 * > 👉 **Note**: Returns a promise if `fs.stat` is async.
 *
 * [main]: https://github.com/nodejs/node/blob/v22.9.0/doc/api/packages.md#main
 *
 * @see {@linkcode Awaitable}
 * @see {@linkcode ErrModuleNotFound}
 * @see {@linkcode FileSystem}
 * @see {@linkcode List}
 * @see {@linkcode MainField}
 * @see {@linkcode ModuleId}
 * @see {@linkcode PackageJson}
 *
 * @template {Awaitable<URL>} T
 *  The resolved entry point URL
 *
 * @this {void}
 *
 * @param {ModuleId} packageUrl
 *  The URL of the package directory, the `package.json` file,
 *  or a module in the same directory as a `package.json`
 * @param {PackageJson | null | undefined} [manifest]
 *  The package manifest
 * @param {List<MainField> | null | undefined} [mainFields]
 *  The list of legacy main fields
 * @param {ModuleId | null | undefined} [parent]
 *  The URL of the parent module
 * @param {FileSystem | null | undefined} [fs]
 *  The file system API
 * @return {Awaitable<URL>}
 *  The resolved entry point URL
 * @throws {ErrModuleNotFound}
 *  If the entry point cannot be resolved
 */
declare function legacyMainResolve<T extends Awaitable<URL>>(this: void, packageUrl: ModuleId, manifest?: PackageJson | null | undefined, mainFields?: List<MainField> | null | undefined, parent?: ModuleId | null | undefined, fs?: FileSystem | null | undefined): T;
/**
 * Resolve a module `specifier`.
 *
 * Implements the `ESM_RESOLVE` algorithm.
 *
 * > 👉 **Note**: Returns a promise if `fs.realpath` or `fs.stat` is async,
 * > or one of the following methods returns a promise:
 * > {@linkcode packageImportsResolve}, {@linkcode packageResolve}.
 *
 * @see {@linkcode Awaitable}
 * @see {@linkcode Condition}
 * @see {@linkcode ErrInvalidModuleSpecifier}
 * @see {@linkcode ErrModuleNotFound}
 * @see {@linkcode ErrUnsupportedDirImport}
 * @see {@linkcode FileSystem}
 * @see {@linkcode List}
 * @see {@linkcode ModuleId}
 *
 * @template {Awaitable<URL>} T
 *  The resolved URL
 *
 * @this {void}
 *
 * @param {string} specifier
 *  The module specifier to resolve
 * @param {ModuleId} parent
 *  The URL of the parent module
 * @param {List<Condition> | null | undefined} [conditions]
 *  The list of export/import conditions
 * @param {List<MainField> | null | undefined} [mainFields]
 *  The list of legacy main fields
 * @param {boolean | null | undefined} [preserveSymlinks]
 *  Whether to keep symlinks instead of resolving them
 * @param {FileSystem | null | undefined} [fs]
 *  The file system API
 * @return {T}
 *  The resolved URL
 * @throws {ErrInvalidModuleSpecifier}
 * @throws {ErrModuleNotFound}
 * @throws {ErrUnsupportedDirImport}
 */
declare function moduleResolve<T extends Awaitable<URL>>(this: void, specifier: string, parent: ModuleId, conditions?: List<Condition> | null | undefined, mainFields?: List<MainField> | null | undefined, preserveSymlinks?: boolean | null | undefined, fs?: FileSystem | null | undefined): T;
/**
 * Resolve a package export.
 *
 * Implements the `PACKAGE_EXPORTS_RESOLVE` algorithm.
 *
 * > 👉 **Note**: Never returns a promise.
 *
 * @see {@linkcode Awaitable}
 * @see {@linkcode Condition}
 * @see {@linkcode ErrInvalidPackageConfig}
 * @see {@linkcode ErrPackagePathNotExported}
 * @see {@linkcode Exports}
 * @see {@linkcode FileSystem}
 * @see {@linkcode Imports}
 * @see {@linkcode List}
 * @see {@linkcode ModuleId}
 *
 * @template {Awaitable<URL>} T
 *  The resolved package export URL
 *
 * @this {void}
 *
 * @param {ModuleId} packageUrl
 *  The URL of the package directory, the `package.json` file,
 *  or a module in the same directory as a `package.json`
 * @param {string} subpath
 *  The package subpath
 * @param {Exports | undefined} exports
 *  The package exports
 * @param {List<Condition> | null | undefined} [conditions]
 *  The list of export/import conditions
 * @param {ModuleId | null | undefined} [parent]
 *  The URL of the parent module
 * @param {FileSystem | null | undefined} [fs]
 *  The file system API
 * @return {Awaitable<URL>}
 *  The resolved package export URL
 * @throws {ErrInvalidPackageConfig}
 * @throws {ErrPackagePathNotExported}
 */
declare function packageExportsResolve<T extends Awaitable<URL>>(this: void, packageUrl: ModuleId, subpath: string, // eslint-disable-next-line unicorn/prefer-module
exports: Exports | undefined, conditions?: List<Condition> | null | undefined, parent?: ModuleId | null | undefined, fs?: FileSystem | null | undefined): T;
/**
 * Resolve a package export or import.
 *
 * Implements the `PACKAGE_IMPORTS_EXPORTS_RESOLVE` algorithm.
 *
 * > 👉 **Note**: Returns a promise if {@linkcode packageTargetResolve}
 * > returns a promise.
 *
 * @see {@linkcode Awaitable}
 * @see {@linkcode Condition}
 * @see {@linkcode ExportsObject}
 * @see {@linkcode FileSystem}
 * @see {@linkcode Imports}
 * @see {@linkcode List}
 * @see {@linkcode ModuleId}
 *
 * @template {Awaitable<URL | null | undefined>} T
 *  The resolved package export or import URL
 *
 * @this {void}
 *
 * @param {string} matchKey
 *  The package subpath extracted from a module specifier,
 *  or a dot character (`.`)
 * @param {ExportsObject | Imports | null | undefined} matchObject
 *  The package exports or imports
 * @param {ModuleId} packageUrl
 *  The URL of the directory containing the `package.json` file
 * @param {boolean | null | undefined} [isImports]
 *  Whether `matchObject` is internal to the package
 * @param {List<Condition> | null | undefined} [conditions]
 *  The list of export/import conditions
 * @param {List<MainField> | null | undefined} [mainFields]
 *  The list of legacy main fields
 * @param {ModuleId | null | undefined} [parent]
 *  The URL of the parent module
 * @param {FileSystem | null | undefined} [fs]
 *  The file system API
 * @return {T}
 *  The resolved package export or import URL
 */
declare function packageImportsExportsResolve<T extends Awaitable<URL | null | undefined>>(this: void, matchKey: string, matchObject: ExportsObject | Imports | null | undefined, packageUrl: ModuleId, isImports?: boolean | null | undefined, conditions?: List<Condition> | null | undefined, mainFields?: List<MainField> | null | undefined, parent?: ModuleId | null | undefined, fs?: FileSystem | null | undefined): T;
/**
 * Resolve a package import.
 *
 * Implements the `PACKAGE_IMPORTS_RESOLVE` algorithm.
 *
 * > 👉 **Note**: Returns a promise if {@linkcode lookupPackageScope},
 * > {@linkcode packageImportsExportsResolve}, or {@linkcode readPackageJson}
 * > returns a promise.
 *
 * @see {@linkcode Awaitable}
 * @see {@linkcode Condition}
 * @see {@linkcode ErrInvalidModuleSpecifier}
 * @see {@linkcode ErrPackageImportNotDefined}
 * @see {@linkcode FileSystem}
 * @see {@linkcode List}
 * @see {@linkcode ModuleId}
 *
 * @template {Awaitable<URL>} T
 *  The resolved package import URL
 *
 * @this {void}
 *
 * @param {string} specifier
 *  The import specifier to resolve
 * @param {ModuleId} parent
 *  The URL of the parent module
 * @param {List<Condition> | null | undefined} [conditions]
 *  The list of export/import conditions
 * @param {List<MainField> | null | undefined} [mainFields]
 *  The list of legacy main fields
 * @param {FileSystem | null | undefined} [fs]
 *  The file system API
 * @return {T}
 *  The resolved package import URL
 * @throws {ErrInvalidModuleSpecifier}
 * @throws {ErrPackageImportNotDefined}
 */
declare function packageImportsResolve<T extends Awaitable<URL>>(this: void, specifier: string, parent: ModuleId, conditions?: List<Condition> | null | undefined, mainFields?: List<MainField> | null | undefined, fs?: FileSystem | null | undefined): T;
/**
 * Resolve a *bare specifier*.
 *
 * Implements the `PACKAGE_RESOLVE` algorithm.
 *
 * > *Bare specifiers* like `'some-package'` or `'some-package/shuffle'` refer
 * > to the main entry point of a package by package name, or a specific feature
 * > module within a package prefixed by the package name. Including the file
 * > extension is only necessary for packages without an [`"exports"`][exports]
 * > field.
 *
 * > 👉 **Note**: Returns a promise if `fs.stat` is async or one of the
 * > following methods returns a promise: {@linkcode legacyMainResolve},
 * > {@linkcode packageExportsResolve}, {@linkcode packageSelfResolve},
 * > {@linkcode readPackageJson}.
 *
 * [exports]: https://nodejs.org/api/packages.html#exports
 *
 * @see {@linkcode Awaitable}
 * @see {@linkcode Condition}
 * @see {@linkcode ErrInvalidModuleSpecifier}
 * @see {@linkcode ErrModuleNotFound}
 * @see {@linkcode FileSystem}
 * @see {@linkcode List}
 * @see {@linkcode MainField}
 * @see {@linkcode ModuleId}
 *
 * @template {Awaitable<URL>} T
 *  The resolved package URL
 *
 * @this {void}
 *
 * @param {string} specifier
 *  The package specifier
 * @param {ModuleId} parent
 *  The URL of the parent module
 * @param {List<Condition> | null | undefined} [conditions]
 *  The list of export conditions
 * @param {List<MainField> | null | undefined} [mainFields]
 *  The list of legacy main fields
 * @param {FileSystem | null | undefined} [fs]
 *  The file system API
 * @return {T}
 *  The resolved package URL
 * @throws {ErrInvalidModuleSpecifier}
 * @throws {ErrModuleNotFound}
 */
declare function packageResolve<T extends Awaitable<URL>>(this: void, specifier: string, parent: ModuleId, conditions?: List<Condition> | null | undefined, mainFields?: List<MainField> | null | undefined, fs?: FileSystem | null | undefined): T;
/**
 * Resolve the self-import of a package.
 *
 * Implements the `PACKAGE_SELF_RESOLVE` algorithm.
 *
 * > 👉 **Note**: Returns a promise if {@linkcode lookupPackageScope},
 * > {@linkcode packageExportsResolve}, or {@linkcode readPackageJson}
 * > returns a promise.
 *
 * @see {@linkcode Awaitable}
 * @see {@linkcode Condition}
 * @see {@linkcode FileSystem}
 * @see {@linkcode List}
 * @see {@linkcode ModuleId}
 *
 * @template {Awaitable<URL | undefined>} T
 *  The resolved package URL
 *
 * @this {void}
 *
 * @param {string} name
 *  The package name
 * @param {string} subpath
 *  The package subpath
 * @param {ModuleId} parent
 *  The URL of the parent module
 * @param {List<Condition> | null | undefined} [conditions]
 *  The list of export conditions
 * @param {FileSystem | null | undefined} [fs]
 *  The file system API
 * @return {T}
 *  The resolved package URL
 */
declare function packageSelfResolve<T extends Awaitable<URL | undefined>>(this: void, name: string, subpath: string, parent: ModuleId, conditions?: List<Condition> | null | undefined, fs?: FileSystem | null | undefined): T;
/**
 * Resolve a package target.
 *
 * Implements the `PACKAGE_TARGET_RESOLVE` algorithm.
 *
 * > 👉 **Note**: Returns a promise if `target` is internal to the package and
 * > {@linkcode packageResolve} returns a promise.
 *
 * @see {@linkcode Awaitable}
 * @see {@linkcode Condition}
 * @see {@linkcode ErrInvalidPackageConfig}
 * @see {@linkcode ErrInvalidPackageTarget}
 * @see {@linkcode FileSystem}
 * @see {@linkcode List}
 * @see {@linkcode ModuleId}
 * @see {@linkcode Target}
 *
 * @template {Awaitable<URL | null | undefined>} T
 *  The resolved package target URL
 *
 * @this {void}
 *
 * @param {ModuleId} packageUrl
 *  The URL of the directory containing the `package.json` file
 * @param {unknown} target
 *  The package target (i.e. a `exports`/`imports` value)
 * @param {string} subpath
 *  The package subpath (i.e. a `exports`/`imports` key)
 * @param {string | null | undefined} [patternMatch]
 *  The `subpath` pattern match
 * @param {boolean | null | undefined} [isImports]
 *  Whether `target` is internal to the package
 * @param {List<Condition> | null | undefined} [conditions]
 *  The list of export/import conditions
 * @param {List<MainField> | null | undefined} [mainFields]
 *  The list of legacy main fields
 * @param {ModuleId | null | undefined} [parent]
 *  The URL of the parent module
 * @param {FileSystem | null | undefined} [fs]
 *  The file system API
 * @return {T}
 *  The resolved package target URL
 * @throws {ErrInvalidPackageConfig}
 * @throws {ErrInvalidPackageTarget}
 */
declare function packageTargetResolve<T extends Awaitable<URL | null | undefined>>(this: void, packageUrl: ModuleId, target: unknown, subpath: string, patternMatch?: string | null | undefined, isImports?: boolean | null | undefined, conditions?: List<Condition> | null | undefined, mainFields?: List<MainField> | null | undefined, parent?: ModuleId | null | undefined, fs?: FileSystem | null | undefined): T;

declare const resolver_d_legacyMainResolve: typeof legacyMainResolve;
declare const resolver_d_moduleResolve: typeof moduleResolve;
declare const resolver_d_packageExportsResolve: typeof packageExportsResolve;
declare const resolver_d_packageImportsExportsResolve: typeof packageImportsExportsResolve;
declare const resolver_d_packageImportsResolve: typeof packageImportsResolve;
declare const resolver_d_packageResolve: typeof packageResolve;
declare const resolver_d_packageSelfResolve: typeof packageSelfResolve;
declare const resolver_d_packageTargetResolve: typeof packageTargetResolve;
declare namespace resolver_d {
  export {
    resolver_d_legacyMainResolve as legacyMainResolve,
    resolver_d_moduleResolve as moduleResolve,
    resolver_d_packageExportsResolve as packageExportsResolve,
    resolver_d_packageImportsExportsResolve as packageImportsExportsResolve,
    resolver_d_packageImportsResolve as packageImportsResolve,
    resolver_d_packageResolve as packageResolve,
    resolver_d_packageSelfResolve as packageSelfResolve,
    resolver_d_packageTargetResolve as packageTargetResolve,
  };
}

/**
 * @file root
 * @module mlly/lib/root
 */
/**
 * The URL of the file system root.
 *
 * @const {URL} root
 */
declare const root: URL;

/**
 * @file toRelativeSpecifier
 * @module mlly/lib/toRelativeSpecifier
 */

/**
 * Turn `url` into a *relative specifier*.
 *
 * ::: info
 * The relative specifier will only have a file extension
 * if `specifier` also has an extension.
 * :::
 *
 * @see {@linkcode ModuleId}
 * @see https://nodejs.org/api/esm.html#terminology
 *
 * @this {void}
 *
 * @param {ModuleId} url
 *  The `file:` URL to convert
 * @param {ModuleId} parent
 *  The parent module id
 * @return {string}
 *  The relative specifier
 */
declare function toRelativeSpecifier(this: void, url: ModuleId, parent: ModuleId): string;

/**
 * @file toUrl
 * @module mlly/lib/toUrl
 */

/**
 * Convert `id` to a {@linkcode URL}.
 *
 * > 👉 **Note**: If `id` cannot be parsed as a `URL`, and is also not a
 * > [builtin module][builtin-module], it will be assumed to be a path and
 * > converted to a [`file:` URL][file-url].
 *
 * [builtin-module]: https://nodejs.org/api/esm.html#builtin-modules
 * [file-url]: https://nodejs.org/api/esm.html#file-urls
 *
 * @this {void}
 *
 * @param {ModuleId} id
 *  The module id to convert
 * @param {ModuleId | null | undefined} [parent]
 *  The base URL to resolve against if `id` is not absolute
 * @return {URL}
 *  The new URL
 */
declare function toUrl(this: void, id: ModuleId, parent?: ModuleId | null | undefined): URL;

/**
 * @file Type Aliases - Awaitable
 * @module mlly/types/Awaitable
 */
/**
 * Create a union of `T` and `T` as a promise-like object.
 *
 * @template {any} T
 *  The value
 */
type Awaitable<T> = PromiseLike<T> | T;

/**
 * @file Type Aliases - BufferEncoding
 * @module mlly/types/BufferEncoding
 */

/**
 * Union of values that can occur where a buffer encoding is expected.
 *
 * To register new encodings, augment {@linkcode BufferEncodingMap}.
 * They will be added to this union automatically.
 */
type BufferEncoding = BufferEncodingMap[keyof BufferEncodingMap];

/**
 * @file Type Aliases - Condition
 * @module mlly/types/Condition
 */

/**
 * Union of values that can occur where a export/import condition is expected.
 *
 * To register new conditions, augment {@linkcode ConditionMap}.
 * They will be added to this union automatically.
 */
type Condition = ConditionMap[keyof ConditionMap];

/**
 * @file Type Aliases - Dot
 * @module mlly/types/Dot
 */
/**
 * A dot character (`'.'`).
 */
type Dot = '.';

/**
 * @file Type Aliases - EmptyArray
 * @module mlly/types/EmptyArray
 */
/**
 * An empty array.
 */
type EmptyArray = [];

/**
 * @file Type Aliases - EmptyObject
 * @module mlly/types/EmptyObject
 */
/**
 * The empty object symbol.
 *
 * @internal
 *
 * @const {symbol} tag
 */
declare const tag: unique symbol;
/**
 * An empty object.
 */
type EmptyObject = {
    [tag]?: never;
};

/**
 * @file Type Aliases - EmptyString
 * @module mlly/types/EmptyString
 */
/**
 * An empty string.
 */
type EmptyString = '';

/**
 * @file Type Aliases - Ext
 * @module mlly/types/Ext
 */

/**
 * A file extension.
 *
 * @see {@linkcode Dot}
 */
type Ext = `${Dot}${string}`;

/**
 * @file Type Aliases - ExtensionRewrites
 * @module mlly/types/ExtensionRewrites
 */

/**
 * Record, where each key is the file extension of a module specifier and
 * each value is a replacement file extension.
 *
 * > 👉 **Note**: Replacement file extensions are normalized and do not need to
 * > begin with a dot character (`'.'`); falsy values will remove an extension.
 *
 * @see {@linkcode EmptyString}
 * @see {@linkcode Ext}
 */
type ExtensionRewrites = {
    [K in EmptyString | Ext]?: string | false | null | undefined;
};

/**
 * @file Type Aliases - FileContent
 * @module mlly/types/FileContent
 */
/**
 * Union of values that can occur where file content is expected.
 *
 * @see {@linkcode Uint8Array}
 */
type FileContent = Uint8Array | string;

/**
 * @file Type Aliases - GetNewExtension
 * @module mlly/types/GetNewExtension
 */
/**
 * Get a new file extension for a `url`.
 *
 * Returning an empty string (`''`), `false`, `null`, or `undefined`
 * will remove the current file extension.
 *
 * ::: info
 * File extensions are normalized and
 * do not need to begin with a dot character (`'.'`).
 * :::
 *
 * @see {@linkcode URL}
 * @see https://github.com/flex-development/pathe/tree/1.0.3#changeextpath-string-ext-nullablestring-string
 *
 * @template {string | false | null | undefined} [T]
 *  The new file extension
 *
 * @param {URL} url
 *  The resolved module URL
 * @param {string} specifier
 *  The module specifier being resolved
 * @return {T}
 *  The new file extension
 */
type GetNewExtension<T extends string | false | null | undefined = string | false | null | undefined> = (this: void, url: URL, specifier: string) => T;

/**
 * @file Type Aliases - GetSourceHandler
 * @module mlly/types/GetSourceHandler
 */

/**
 * Get the source code for a module.
 *
 * @see {@linkcode Awaitable}
 * @see {@linkcode FileContent}
 * @see {@linkcode GetSourceContext}
 * @see {@linkcode URL}
 *
 * @this {GetSourceContext}
 *  The retrieval context
 *
 * @param {URL} url
 *  The module URL
 * @return {Awaitable<FileContent | null | undefined>}
 *  The source code
 */
type GetSourceHandler = (this: GetSourceContext, url: URL) => Awaitable<FileContent | null | undefined>;

/**
 * @file Type Aliases - GetSourceHandlers
 * @module mlly/types/GetSourceHandlers
 */

/**
 * Record, where key is a URL protocol and each value is a source code handler.
 *
 * @see {@linkcode GetSourceHandler}
 * @see {@linkcode Protocol}
 */
type GetSourceHandlers = {
    [H in Protocol]?: GetSourceHandler | null | undefined;
};

/**
 * @file Type Aliases - List
 * @module mlly/types/List
 */
/**
 * A list.
 *
 * @template {any} [T=unknown]
 *  The list item type
 */
type List<T = unknown> = ReadonlySet<T> | readonly T[];

/**
 * @file Type Aliases - MainField
 * @module mlly/types/MainField
 */

/**
 * Union of values that can occur where a main field is expected.
 *
 * To register new fields, augment {@linkcode MainFieldMap}.
 * They will be added to this union automatically.
 */
type MainField = MainFieldMap[keyof MainFieldMap];

/**
 * @file Type Aliases - ModuleFormat
 * @module mlly/types/ModuleFormat
 */

/**
 * Union of values that can occur where a module format is expected.
 *
 * To register new formats, augment {@linkcode ModuleFormatMap}.
 * They will be added to this union automatically.
 */
type ModuleFormat = ModuleFormatMap[keyof ModuleFormatMap];

/**
 * @file Type Aliases - ModuleId
 * @module mlly/types/ModuleId
 */
/**
 * Union of values that can occur where a
 * ECMAScript (ES) module identifier is expected.
 *
 * @see {@linkcode URL}
 */
type ModuleId = URL | string;

/**
 * @file Type Aliases - Numeric
 * @module mlly/types/Numeric
 */
/**
 * String containing only numbers (not including the leading `-` if negative).
 */
type Numeric = `${number}`;

/**
 * @file Type Aliases - PatternKeyComparison
 * @module mlly/types/PatternKeyComparison
 */

/**
 * Union of values that can occur
 * where a `PATTERN_KEY_COMPARE` algorithm result is expected.
 *
 * To register new results, augment {@linkcode PatternKeyComparisonMap}.
 * They will be added to this union automatically.
 */
type PatternKeyComparison = PatternKeyComparisonMap[keyof PatternKeyComparisonMap];

/**
 * @file Type Aliases - PatternMatch
 * @module mlly/types/PatternMatch
 */
/**
 * List, where the first item is the key of a package `exports` or `imports`
 * target object, and the last is a subpath pattern match.
 */
type PatternMatch = [expansionKey: string, patternMatch: string | null];

/**
 * @file Type Aliases - Protocol
 * @module mlly/types/Protocol
 */

/**
 * Union of values that can occur where a URL protocol is expected.
 *
 * To register new protocols, augment {@linkcode ProtocolMap}.
 * They will be added to this union automatically.
 */
type Protocol = ProtocolMap[keyof ProtocolMap];

export { canParseUrl, cwd, defaultConditions, defaultExtensions, defaultMainFields, extensionFormatMap, formats, getSource, isAbsoluteSpecifier, isArrayIndex, isBareSpecifier, isDirectory, isFile, isImportsSubpath, isModuleId, isRelativeSpecifier, legacyMainResolve, lookupPackageScope, moduleResolve, packageExportsResolve, packageImportsExportsResolve, packageImportsResolve, packageResolve, packageSelfResolve, packageTargetResolve, patternKeyCompare, patternMatch, readPackageJson, resolveAlias, resolveModule, resolver_d as resolver, root, toRelativeSpecifier, toUrl };
export type { Aliases, Awaitable, BufferEncoding, BufferEncodingMap, Condition, ConditionMap, Dot, EmptyArray, EmptyObject, EmptyString, Ext, ExtensionRewrites, FileContent, FileSystem, GetNewExtension, GetSourceContext, GetSourceHandler, GetSourceHandlers, GetSourceOptions, IsDirectory, IsFile, List, MainField, MainFieldMap, ModuleFormat, ModuleFormatMap, ModuleId, Numeric, PatternKeyComparison, PatternKeyComparisonMap, PatternMatch, Protocol, ProtocolMap, ReadFile, Realpath, ResolveAliasOptions, ResolveModuleOptions, Stat, Stats };