API Reference ​

CONDITIONS ​

Default export conditions.

const CONDITIONS: Set<string> = new Set(['node', 'import'])

See Also ​

• https://nodejs.org/api/packages.html#conditional-exports

EXTENSION_FORMAT_MAP ​

Default file extension to module formats map.

const EXTENSION_FORMAT_MAP: Map<Ext, Format> = new Map<Ext, Format>([
  ['.cjs', Format.COMMONJS],
  ['.cts', Format.COMMONJS],
  ['.d.cts', Format.COMMONJS],
  ['.d.mts', Format.MODULE],
  ['.d.ts', Format.MODULE],
  ['.js', Format.MODULE],
  ['.json', Format.JSON],
  ['.jsx', Format.MODULE],
  ['.mjs', Format.MODULE],
  ['.mts', Format.MODULE],
  ['.node', Format.COMMONJS],
  ['.ts', Format.MODULE],
  ['.tsx', Format.MODULE],
  ['.wasm', Format.WASM]
])

See Also ​

• Ext
• Format

PATTERN_CHARACTER ​

Character representing a subpath pattern.

const PATTERN_CHARACTER: string = '*'

RESOLVE_EXTENSIONS ​

Default resolvable file extensions.

const RESOLVE_EXTENSIONS: Set<Ext> = new Set([
  '.mjs',
  '.mts',
  '.cjs',
  '.cts',
  '.js',
  '.ts',
  '.jsx',
  '.tsx',
  '.css',
  '.json',
  '.node',
  '.wasm',
  '.d.mts',
  '.d.cts',
  '.d.ts'
])

See Also ​

• Ext

compareSubpaths ​

Returns a number indicating if a subpath pattern is equal to, greater than, or less than another subpath pattern.

• -1: subpath2 is less than subpath1
• 0: subpath2 is equal to subpath1
• 1: subpath2 is greater than subpath1

Implements the PATTERN_KEY_COMPARE algorithm.

See Also ​

• https://nodejs.org/api/esm.html#resolution-algorithm

Params ​

Returns ​

CompareResult   Comparsion result

detectSyntax ​

Detects if code contains CommonJS syntax, ESM syntax, or a mixture of both.

Ignores matches in comments.

See Also ​

• hasCJSSyntax
• hasESMSyntax

Params ​

Returns ​

{ cjs: boolean; esm: boolean; mixed: boolean }   Detection result

extractStatements ​

Finds all export, import, and/or require statements in code.

Ignores matches in comments.

See Also ​

• findDynamicImports
• findExports
• findRequires
• findStaticImports

Params ​

Returns ​

Statement[]   Extracted statements

fillModules ​

Ensures all absolute and relative module specifiers in the given piece of source code are fully specified.

Ignores specifiers that already have file extensions.

See Also ​

• FillModuleOptions
• https://nodejs.org/api/esm.html#mandatory-file-extensions
• https://nodejs.org/api/esm.html#terminology

Params ​

Returns ​

Promise<string>   code with fully specified module specifiers

findDynamicImports ​

Finds all dynamic import statements in code. Ignores matches in comments.

See Also ​

• DynamicImport
• https://regex101.com/r/PTPAvU
• https://developer.mozilla.org/docs/Web/JavaScript/Reference/Operators/import

Params ​

Returns ​

DynamicImport[]   Dynamic import statement objects

findExports ​

Finds all export statements in code. Ignores matches in comments.

See Also ​

• ExportStatement
• https://regex101.com/r/JtvRUt
• https://regex101.com/r/8HpMrA
• https://regex101.com/r/G7GhEt
• https://regex101.com/r/KQEDdZ
• https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/export

Params ​

Returns ​

ExportStatement[]   Export statement objects

findRequires ​

Finds all require statements in code. Ignores matches in comments.

See Also ​

• RequireStatement
• https://regex101.com/r/uCqSYB
• https://nodejs.org/api/modules.html#requireid

Params ​

Returns ​

RequireStatement[]   Require statement objects

findStaticImports ​

Finds all static import statements in code. Ignores matches in comments.

See Also ​

• StaticImport
• https://regex101.com/r/wlYQUN
• https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/import

Params ​

Returns ​

StaticImport[]   Static import statement objects

findSubpath ​

Finds the subpath defined in context, a package.json exports or imports field, that maps to the given package target.

Supports extensionless targets and targets without explicit '/index' usage. Returns null if a subpath is not found.

See Also ​

• Exports
• FindSubpathOptions
• Imports
• https://nodejs.org/api/packages.html#subpath-exports
• https://nodejs.org/api/packages.html#subpath-imports

Params ​

Returns ​

Nullable<string>   Subpath defined in context or null

getFormat ​

Retrieves a module format for the given module id.

See Also ​

• Format
• GetFormatOptions
• ModuleId

Params ​

Returns ​

Promise<Nilable<Format>>   Module format, null, or undefined

getSource ​

Retrieves source code for the given module id.

See Also ​

• GetSourceOptions
• ModuleId
• https://nodejs.org/docs/latest-v19.x/api/esm.html#loadurl-context-nextload

Params ​

Returns ​

Promise<Optional<Uint8Array | string>>   Source code for id

hasCJSSyntax ​

Detects if code contains CommonJS syntax. Ignores matches in comments.

Syntax patterns:

• __dirname
• __filename
• await import
• exports
• module.exports
• require
• require.*

See Also ​

• https://regex101.com/r/Co77SJ

Params ​

Returns ​

boolean   true if code contains cjs syntax, false otherwise

hasESMSyntax ​

Detects if code contains ESM syntax. Ignores matches in comments.

Syntax patterns:

• export (declaration, default, named, star)
• import (default, dynamic, named, star)
• import.meta.(env|resolve|url)

See Also ​

• https://regex101.com/r/xfreyy

Params ​

Returns ​

boolean   true if code contains esm syntax, false otherwise

isAbsoluteSpecifier ​

Checks if the given specifier is an absolute specifier.

See Also ​

• https://nodejs.org/api/esm.html#terminology

Params ​

Returns ​

boolean   true if specifier is absolute specifier

isBareSpecifier ​

Checks if the given specifier is a bare specifier.

See Also ​

• https://nodejs.org/api/esm.html#terminology

Params ​

Returns ​

boolean   true if specifier is bare specifier

isDirectory ​

Checks if a directory exists at the given module id.

Params ​

Returns ​

boolean   true if directory exists at id

isExportsSugar ​

Checks if the given package exports value is using exports sugar.

See Also ​

• Exports
• ModuleId

Params ​

Returns ​

boolean   true if exports is using exports sugar

isFile ​

Checks if a file exists at the given module id.

Params ​

Returns ​

boolean   true if file exists at id

isRelativeSpecifier ​

Checks if the given specifier is a relative specifier.

See Also ​

• https://nodejs.org/api/esm.html#terminology

Params ​

Returns ​

boolean   true if specifier is relative specifier

lookupPackageScope ​

Finds a package.json file for the given module id. Ends the search at the given end point after checking for a package.json file.

Returns null if a package.json file is not found.

See Also ​

• ModuleId
• PackageScope

Params ​

Returns ​

?PackageScope   Package scope result or null

parseDataURL ​

Parses a data: URL.

If valid, returns an object representing the given url.

Note: A MIME type string is required.

See Also ​

• https://nodejs.org/api/esm.html#data-imports

Params ​

Returns ​

ParsedDataUrl   Object representing url

parseModuleId ​

Creates an object representation the given module id.

See Also ​

• ModuleId
• ParseModuleIdOptions
• ParsedModuleId

Params ​

Returns ​

ParsedModuleId   Object representing id

parseSubpath ​

Creates an object representation of a subpath export or import from the given module specifier after ensuring the subpath defined in specifier is also defined in the given package context, a package.json exports or imports field.

See Also ​

• Exports
• Imports
• ParseSubpathOptions
• ParsedSubpath
• https://nodejs.org/api/packages.html#subpath-exports
• https://nodejs.org/api/packages.html#subpath-imports

Params ​

Returns ​

ParsedSubpath   Object representing package subpath

readPackageJson ​

Reads a package.json file from the given directory.

Returns null if a file is not found.

See Also ​

• ModuleId
• PackageJson

Params ​

Returns ​

?PackageJson   package.json object or null if file is not found

resolveAlias ​

Resolves a path alias in the given module specifier; does nothing if a path match isn't found.

See Also ​

• ResolveAliasOptions

Params ​

Returns ​

Promise<string>   Resolved specifier or original module specifier

resolveAliases ​

Resolves path aliases in the given piece of source code.

See Also ​

• ResolveAliasOptions
• resolveAlias

Params ​

Returns ​

Promise<string>   code unmodified or with path aliases resolved

resolveModule ​

Resolves specifier according to the ESM Resolver algorithm, mostly 😉.

Adds support for:

• Extensionless file and directory index resolution
• Replacing file extensions

Other differences between Node.js:

• Subpath import targets (that are strings) must be relative to the current working directory (e.g. './src/index.ts', './src/*.ts') or start with a valid NPM package name. See nodejs/node#40579 for details.

See Also ​

• NodeError
• ResolveModuleOptions
• URL

Params ​

Returns ​

Promise<URL>   Resolved module URL

resolveModules ​

Converts all module specifiers in code to absolute specifiers.

See Also ​

• ResolveModuleOptions
• https://nodejs.org/api/esm.html#terminology

Params ​

Returns ​

Promise<string>   code with module specifiers fully resolved

toAbsoluteSpecifier ​

Converts specifier into an absolute specifier.

See Also ​

• ModuleId
• https://nodejs.org/api/esm.html#terminology

Params ​

Returns ​

string   specifier as absolute specifier (file url)

toBareSpecifier ​

Converts the given module specifier into a bare specifier.

The new specifier is not guaranteed to resolve to an existing module, nor is it guaranteed to have a file extension, but it is guaranteed to be a package path containing a valid subpath export if the specifier's parent package uses package exports. If the parent package does not use exports, the new specifier is only guaranteed to begin with a valid NPM package name or Node.js builtin module name.

The given module specifier should be absolute, syntactically bare (i.e. not begin with '/' or '.'), or relative to the current working directory (e.g. './dist/index.mjs').

See Also ​

• CONDITIONS
• ModuleId
• https://nodejs.org/api/esm.html#terminology

Params ​

Returns ​

string   specifier as bare specifier

toDataURL ​

Converts code into a data: URL using base64 encoding.

See Also ​

• MimeType
• https://nodejs.org/api/esm.html#esm_data_imports

Params ​

Returns ​

string   code as data: URL

toNodeURL ​

Converts the given module specifier to a node: URL.

See Also ​

• https://nodejs.org/api/esm.html#node-imports

Params ​

Returns ​

string   specifier as node: URL

toRelativeSpecifier ​

Converts specifier into a relative specifier.

See Also ​

• ModuleId
• https://nodejs.org/api/esm.html#terminology

Params ​

Returns ​

string   specifier as relative specifier

toURL ​

Converts the given module id to an instance of URL.

See Also ​

• ModuleId

Params ​

Returns ​

URL   id as instance of URL

validateAssertions ​

Test a module's import assertions.

See Also ​

• Format
• ImportAssertions
• ModuleId

Params ​

Returns ​

true   true if assertions are valid

validateExports ​

Validates the given package exports configuration and schema.

See Also ​

• Exports
• ModuleId

Params ​

Returns ​

true   true if exports configuration and schema are valid