resolve-pkg-maps

resolve-pkg-maps

Utils to resolve package.json subpath & conditional exports/imports in resolvers.

Implements the ESM resolution algorithm. Tested against Node.js for accuracy.

_{Support this project by ⭐️ starring and sharing it. Follow me to see what other cool projects I'm working on! ❤️}

Usage

Resolving exports

utils/package.json

{
    // ...
    "exports": {
        "./reverse": {
            "require": "./file.cjs",
            "default": "./file.mjs"
        }
    },
    // ...
}

import { resolveExports } from 'resolve-pkg-maps'

const [packageName, packageSubpath] = parseRequest('utils/reverse')

const resolvedPaths: string[] = resolveExports(
    getPackageJson(packageName).exports,
    packageSubpath,
    ['import', ...otherConditions]
)
// => ['./file.mjs']

Resolving imports

package.json

{
    // ...
    "imports": {
        "#supports-color": {
            "node": "./index.js",
            "default": "./browser.js"
        }
    },
    // ...
}

import { resolveImports } from 'resolve-pkg-maps'

const resolvedPaths: string[] = resolveImports(
    getPackageJson('.').imports,
    '#supports-color',
    ['node', ...otherConditions]
)
// => ['./index.js']

API

resolveExports(exports, request, conditions)

Returns: string[]

Resolves the request based on exports and conditions. Returns an array of paths (e.g. in case a fallback array is matched).

exports

Type:

type Exports = PathOrMap | readonly PathOrMap[]

type PathOrMap = string | PathConditionsMap

type PathConditionsMap = {
    [condition: string]: PathConditions | null
}

The exports property value in package.json.

request

Type: string

The package subpath to resolve. Assumes a normalized path is passed in (eg. repeating slashes //).

It should not start with / or ./.

Example: if the full import path is some-package/subpath/file, the request is subpath/file.

conditions

Type: readonly string[]

An array of conditions to use when resolving the request. For reference, Node.js's default conditions are ['node', 'import'].

The order of this array does not matter; the order of condition keys in the export map is what matters instead.

Not all conditions in the array need to be met to resolve the request. It just needs enough to resolve to a path.

---

resolveImports(imports, request, conditions)

Returns: string[]

Resolves the request based on imports and conditions. Returns an array of paths (e.g. in case a fallback array is matched).

imports

Type:

type Imports = {
    [condition: string]: PathOrMap | readonly PathOrMap[] | null
}

type PathOrMap = string | Imports

The imports property value in package.json.

request

Type: string

The request resolve. Assumes a normalized path is passed in (eg. repeating slashes //).

Note: In Node.js, imports resolutions are limited to requests prefixed with #. However, this package does not enforce that requirement in case you want to add custom support for non-prefixed entries.

conditions

Type: readonly string[]

An array of conditions to use when resolving the request. For reference, Node.js's default conditions are ['node', 'import'].

The order of this array does not matter; the order of condition keys in the import map is what matters instead.

Not all conditions in the array need to be met to resolve the request. It just needs enough to resolve to a path.

---

Errors

ERR_PACKAGE_PATH_NOT_EXPORTED

• If the request is not exported by the export map

ERR_PACKAGE_IMPORT_NOT_DEFINED

• If the request is not defined by the import map

ERR_INVALID_PACKAGE_CONFIG

• If an object contains properties that are both paths and conditions (e.g. start with and without .)
• If an object contains numeric properties

ERR_INVALID_PACKAGE_TARGET

• If a resolved exports path is not a valid path (e.g. not relative or has protocol)
• If a resolved path includes .. or node_modules
• If a resolved path is a type that cannot be parsed

FAQ

Why do the APIs return an array of paths?

exports/imports supports passing in a fallback array to provide fallback paths if the previous one is invalid:

{
    "exports": {
        "./feature": [
            "./file.js",
            "./fallback.js"
        ]
    }
}

Node.js's implementation picks the first valid path (without attempting to resolve it) and throws an error if it can't be resolved. Node.js's fallback array is designed for forward compatibility with features (e.g. protocols) that can be immediately/inexpensively validated:

{
    "exports": {
        "./core-polyfill": ["std:core-module", "./core-polyfill.js"]
    }
}

However, Webpack and TypeScript have deviated from this behavior and attempts to resolve the next path if a path cannot be resolved.

By returning an array of matched paths instead of just the first one, the user can decide which behavior to adopt.

How is it different from resolve.exports?

resolve.exports only resolves exports, whereas this package resolves both exports & imports. This comparison will only cover resolving exports.

• Despite it's name, resolve.exports handles more than just exports. It takes in the entire package.json object to handle resolving . and self-references. This package only accepts exports/imports maps from package.json and is scoped to only resolving what's defined in the maps.

• resolve.exports accepts the full request (e.g. foo/bar), whereas this package only accepts the requested subpath (e.g. bar).

• resolve.exports only returns the first result in a fallback array. This package returns an array of results for the user to decide how to handle it.

• resolve.exports supports subpath folder mapping (deprecated in Node.js v16 & removed in v17) but seems to have a bug. This package does not support subpath folder mapping because Node.js has removed it in favor of using subpath patterns.

• Neither resolvers rely on a file-system

This package also addresses many of the bugs in resolve.exports, demonstrated in this test.