@flex-development/mlly 1.0.0-alpha.9 → 1.0.0-beta.2

package/dist/lib/resolve-alias.mjs

@@ -0,0 +1,102 @@
+/**
+ * @file resolveAlias
+ * @module mlly/lib/resolveAlias
+ */
+import chars from '#internal/chars';
+import cwd from '#lib/cwd';
+import isRelativeSpecifier from '#lib/is-relative-specifier';
+import patternMatch from '#lib/pattern-match';
+import toRelativeSpecifier from '#lib/to-relative-specifier';
+import pathe from '@flex-development/pathe';
+import { ok } from 'devlop';
+export default resolveAlias;
+/**
+ * Resolve an aliased `specifier`.
+ *
+ * @see {@linkcode ResolveAliasOptions}
+ *
+ * @this {void}
+ *
+ * @param {string} specifier
+ *  The specifier using an alias
+ * @param {ResolveAliasOptions | null | undefined} [options]
+ *  Alias resolution options
+ * @return {string | null}
+ *  The specifier of the aliased module
+ */
+function resolveAlias(specifier, options) {
+    /**
+     * The expansion key and pattern match.
+     *
+     * @const {PatternMatch | null} match
+     */
+    const match = patternMatch(specifier, options?.aliases);
+    /**
+     * The resolved alias.
+     *
+     * @var {string | null} aliased
+     */
+    let aliased = null;
+    if (match) {
+        ok(options, 'expected `options`');
+        ok(options.aliases, 'expected `options.aliases`');
+        aliased = resolveAliasTarget(options.aliases[match[0]], match[1]);
+        if (typeof aliased === 'string') {
+            /**
+             * The URL of the aliased module.
+             *
+             * @const {URL} url
+             */
+            const url = new URL(aliased, options.cwd ?? cwd());
+            if (options.absolute) {
+                aliased = url.href;
+            }
+            else if (options.parent) {
+                aliased = toRelativeSpecifier(url, options.parent);
+            }
+        }
+    }
+    return aliased;
+}
+/**
+ * Resolve a path alias target.
+ *
+ * @internal
+ *
+ * @this {void}
+ *
+ * @param {unknown} target
+ *  The path alias target to resolve
+ * @param {string | null | undefined} [patternMatch]
+ *  The pattern match, replaces `*` in `target`
+ * @return {string | null}
+ *  The matched alias
+ */
+function resolveAliasTarget(target, patternMatch) {
+    if (typeof target === 'string') {
+        /**
+         * The matched alias.
+         *
+         * @var {string} match
+         */
+        let match = typeof patternMatch === 'string'
+            ? target.replace(chars.asterisk, patternMatch)
+            : target;
+        if (!isRelativeSpecifier(match))
+            match = pathe.dot + pathe.sep + match;
+        return match;
+    }
+    if (Array.isArray(target)) {
+        for (const targetValue of target) {
+            /**
+             * The resolved path alias.
+             *
+             * @const {string | null} resolved
+             */
+            const resolved = resolveAliasTarget(targetValue, patternMatch);
+            if (typeof resolved === 'string')
+                return resolved;
+        }
+    }
+    return null;
+}

package/dist/lib/resolve-module.d.mts

@@ -0,0 +1,43 @@
+/**
+ * @file resolveModule
+ * @module mlly/lib/resolveModule
+ */
+import type { Awaitable, ModuleId, ResolveModuleOptions } from '@flex-development/mlly';
+export default resolveModule;
+/**
+ * Resolve a module `specifier`.
+ *
+ * Implements the `ESM_RESOLVE` algorithm, mostly 😉.
+ *
+ * Adds support for:
+ *
+ * - Changing file extensions
+ * - Directory index resolution
+ * - Extensionless file resolution
+ * - Path alias resolution
+ * - 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 {string} specifier
+ *  The module specifier to resolve
+ * @param {ModuleId} parent
+ *  The URL of the parent module
+ * @param {ResolveModuleOptions | null | undefined} [options]
+ *  Module resolution options
+ * @return {T}
+ *  The resolved URL
+ * @throws {NodeError}
+ */
+declare function resolveModule<T extends Awaitable<URL>>(this: void, specifier: string, parent: ModuleId, options?: ResolveModuleOptions | null | undefined): T;

package/dist/lib/resolve-module.mjs

@@ -0,0 +1,186 @@
+/**
+ * @file resolveModule
+ * @module mlly/lib/resolveModule
+ */
+import constant from '#internal/constant';
+import identity from '#internal/identity';
+import isPromise from '#internal/is-promise';
+import defaultExtensions from '#lib/default-extensions';
+import resolveAlias from '#lib/resolve-alias';
+import { moduleResolve } from '#lib/resolver';
+import { codes, isNodeError } from '@flex-development/errnode';
+import pathe from '@flex-development/pathe';
+export default resolveModule;
+/**
+ * Resolve a module `specifier`.
+ *
+ * Implements the `ESM_RESOLVE` algorithm, mostly 😉.
+ *
+ * Adds support for:
+ *
+ * - Changing file extensions
+ * - Directory index resolution
+ * - Extensionless file resolution
+ * - Path alias resolution
+ * - 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}
+ *
+ * @this {void}
+ *
+ * @param {string} specifier
+ *  The module specifier to resolve
+ * @param {ModuleId} parent
+ *  The URL of the parent module
+ * @param {ResolveModuleOptions | null | undefined} [options]
+ *  Resolution options
+ * @return {Awaitable<URL>}
+ *  The resolved URL
+ * @throws {NodeError}
+ */
+function resolveModule(specifier, parent, options) {
+    /**
+     * The resolved URL.
+     *
+     * @var {Awaitable<URL>} resolved
+     */
+    let resolved;
+    try {
+        resolved = moduleResolve(resolveAlias(specifier, { ...options, parent }) ?? specifier, parent, options?.conditions, options?.mainFields, options?.preserveSymlinks, options?.fs);
+    }
+    catch (e) {
+        return retry(e, specifier, parent, options);
+    }
+    if (isPromise(resolved)) {
+        return resolved.then((url) => changeExt(url, specifier, options?.ext), (e) => retry(e, specifier, parent, options));
+    }
+    return changeExt(resolved, specifier, options?.ext);
+}
+/**
+ * @this {void}
+ *
+ * @param {URL} url
+ *  The resolved URL
+ * @param {string} specifier
+ *  The module specifier being resolved
+ * @param {ChangeExtFn | string | null | undefined} [ext]
+ *  The replacement file extension or a function that returns a file extension
+ * @return {URL}
+ *  The modified `url`
+ */
+function changeExt(url, specifier, ext) {
+    if (url.protocol === 'file:' && ext !== undefined) {
+        url.href = typeof ext === 'function'
+            ? pathe.changeExt(url.href, ext(url, specifier))
+            : pathe.changeExt(url.href, ext);
+        url = new URL(pathe.toPosix(url.href).replace(/\/index$/, pathe.sep));
+    }
+    return url;
+}
+/**
+ * @this {void}
+ *
+ * @param {unknown} e
+ *  The error to handle
+ * @param {string} specifier
+ *  The module specifier to resolve
+ * @param {ModuleId} parent
+ *  The URL of the parent module
+ * @param {ResolveModuleOptions | null | undefined} [options]
+ *  Resolution options
+ * @return {Awaitable<URL>}
+ *  The resolved URL
+ * @throws {NodeError}
+ */
+function retry(e, specifier, parent, options) {
+    /**
+     * The list of error codes to ignore.
+     *
+     * @const {Set<Code>} ignore
+     */
+    const ignore = new Set([
+        codes.ERR_MODULE_NOT_FOUND,
+        codes.ERR_UNSUPPORTED_DIR_IMPORT
+    ]);
+    if (isNodeError(e) && ignore.has(e.code)) {
+        /**
+         * The module extensions to probe for.
+         *
+         * @const {string[]} extensions
+         */
+        const extensions = [...(options?.extensions ?? defaultExtensions)];
+        /**
+         * The promises to resolve.
+         *
+         * > 👉 **Note**: Only used if {@linkcode moduleResolve} returns a promise.
+         *
+         * @const {Awaitable<URL | undefined>} promises
+         */
+        const promises = [];
+        /**
+         * The resolved URL.
+         *
+         * @var {Awaitable<URL>} resolved
+         */
+        let resolved;
+        /**
+         * The module specifiers to try resolving.
+         *
+         * @var {string[]} tries
+         */
+        let tries = [];
+        // add @types resolution attempts if package resolution failed.
+        if (e.code === codes.ERR_MODULE_NOT_FOUND &&
+            !e.url) {
+            tries = [
+                specifier.startsWith('@types/') ? specifier : '@types/' + specifier
+            ].flatMap(specifier => [
+                specifier,
+                specifier + pathe.sep + 'index.d.ts',
+                specifier + pathe.sep + 'index.d.mts',
+                specifier + pathe.sep + 'index.d.cts'
+            ]);
+        }
+        // add extensionless file resolution attempts if file resolution failed.
+        if (e.code === codes.ERR_MODULE_NOT_FOUND &&
+            e.url) {
+            tries = extensions.map(ext => specifier + pathe.formatExt(ext));
+        }
+        // add directory index resolution attempts if directory resolution failed.
+        if (e.code === codes.ERR_UNSUPPORTED_DIR_IMPORT) {
+            tries = extensions.map(ext => {
+                return specifier + pathe.sep + 'index' + pathe.formatExt(ext);
+            });
+        }
+        // try module resolution attempts.
+        for (let attempt of tries) {
+            try {
+                resolved = moduleResolve(attempt, parent, options?.conditions, options?.mainFields, options?.preserveSymlinks, options?.fs);
+                if (!isPromise(resolved)) {
+                    return changeExt(resolved, specifier, options?.ext);
+                }
+            }
+            catch {
+                continue; // swallow error to continue resolution attempts.
+            }
+            // collect promises to resolve.
+            promises.push(resolved.then(identity, constant(undefined)));
+        }
+        if (promises.length) {
+            return Promise.all(promises).then(resolved => {
+                for (const url of resolved) {
+                    if (url)
+                        return changeExt(url, specifier, options?.ext);
+                }
+                throw e; // could not resolve specifier.
+            });
+        }
+    }
+    throw e;
+}

package/dist/lib/resolver.d.mts

@@ -0,0 +1,346 @@
+/**
+ * @file resolver
+ * @module mlly/lib/resolver
+ */
+import type { Awaitable, Condition, FileSystem, List, MainField, ModuleId } from '@flex-development/mlly';
+import type { Exports, ExportsObject, Imports, PackageJson } from '@flex-development/pkg-types';
+declare module '@flex-development/errnode' {
+    interface ErrUnsupportedDirImport {
+        /**
+         * The directory URL.
+         */
+        url?: string | null | undefined;
+    }
+}
+export { legacyMainResolve, moduleResolve, packageExportsResolve, packageImportsExportsResolve, packageImportsResolve, packageResolve, packageSelfResolve, packageTargetResolve };
+/**
+ * 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;