⚙️ mlly

ESM utilities for modern tooling — spec-compliant, developer-friendly, and fully typed.

Contents

• What is this?
• Why this package?
• Install
• Quick Start
  • Resolve like Node.js
  • Resolve with custom conditions
  • Resolve a directory index
  • Resolve path aliases
  • Rewrite an extension
  • Use a custom file system
• Use Cases
• Design Goals
• API
  • canParseUrl(input[, base])
  • cwd()
  • defaultConditions
  • defaultExtensions
  • defaultMainFields
  • extensionFormatMap
  • formats
  • getSource<T>(id[, options])
  • isAbsoluteSpecifier(value)
  • isArrayIndex(value)
  • isBareSpecifier(value)
  • isDirectory<T>(id[, fs])
  • isFile<T>(id[, fs])
  • isImportsSubpath(value)
  • isModuleId(value)
  • isRelativeSpecifier(value)
  • legacyMainResolve<T>(packageUrl[, manifest][, mainFields][, parent][, fs])
  • lookupPackageScope<T>(url[, end][, fs])
  • moduleResolve<T>(specifier, parent[, conditions][, mainFields][, preserveSymlinks][, fs])
  • packageExportsResolve<T>(packageUrl, subpath, exports[, conditions][, parent][, fs])
  • packageImportsExportsResolve<T>(matchKey, matchObject, packageUrl[, isImports][, conditions][, mainFields][, parent][, fs])
  • packageImportsResolve<T>(specifier, parent[, conditions][, mainFields][, fs])
  • packageResolve<T>(specifier, parent[, conditions][, mainFields][, fs])
  • packageSelfResolve<T>(name, subpath, parent[, conditions][, fs])
  • packageTargetResolve<T>(packageUrl, target, subpath[, patternMatch][, isImports][, conditions][, mainFields][, parent][, fs])
  • patternKeyCompare(a, b)
  • patternMatch(matchKey, matchObject)
  • readPackageJson<T>(id[, specifier][, parent][, fs])
  • resolveAlias(specifier[, options])
  • resolveModule<T>(specifier, parent[, options])
  • resolver
  • root
  • toRelativeSpecifier(url, parent)
  • toUrl(id[, parent])
• Types
  • Aliases
  • Awaitable<T>
  • BufferEncodingMap
  • BufferEncoding
  • ConditionMap
  • Condition
  • Dot
  • EmptyArray
  • EmptyObject
  • EmptyString
  • Ext
  • ExtensionRewrites
  • FileContent
  • FileSystem
  • GetNewExtension<[T]>
  • GetSourceContext
  • GetSourceHandler
  • GetSourceHandlers
  • GetSourceOptions
  • IsDirectory
  • IsFile
  • List<[T]>
  • MainFieldMap
  • MainField
  • ModuleFormatMap
  • ModuleFormat
  • ModuleId
  • Numeric
  • PatternKeyComparisonMap
  • PatternKeyComparison
  • PatternMatch
  • ProtocolMap
  • Protocol
  • ReadFile
  • Realpath
  • ResolveAliasOptions
  • ResolveModuleOptions
  • Stat
  • Stats
• Additional Documentation
  • Resolution Algorithm
• Sponsors
• Contribute

What is this?

@flex-development/mlly is a set of ECMAScript module (ESM) utilities for building modern, Node.js-compatible tooling. It implements Node's resolution algorithms and provides additional helpers for resolving modules in real-world projects.

Features

• Comply with Node.js resolution algorithms
  • Resolve exports and imports maps (including subpaths + patterns)
  • Support condition-based resolution (development, production, custom conditions, etc.)
  • Support configurable main fields for legacy / fallback entrypoints
• Enhance DX/UX with high-level resolveModule ergonomics on top of spec-compliant resolution
  • Extensionless and directory index resolution
  • Path alias resolution (TypeScript-style mappings)
  • Rewrite file extensions (useful for TS/MTS/CTS, build outputs, or dual publishing)
  • Scopeless @types/* resolution (unist → @types/unist)
• Utilities for specifier classification and conversion
• Work with custom file system adapters (sync/async, in-memory, browser)

Why this package?

Node's ESM support is powerful, but writing tooling around it can be painful.

If you're building a CLI, bundler, runtime tool, or plugin system, you often need to:

• resolve modules the same way Node does
• support exports / imports correctly
• work with custom resolution conditions
• handle extensionless paths, directory indexes, and TypeScript configurations

@flex-development/mlly provides these building blocks in a spec-aligned way, while also bridging gaps in developer experience.

Install

This package is ESM only.

In Node.js (version 20+) with yarn:

yarn add @flex-development/mlly

See Git - Protocols | Yarn  for details regarding installing from Git.

In Deno with esm.sh:

import { resolveModule } from 'https://esm.sh/@flex-development/mlly'

In browsers with esm.sh:

<script type="module">
  import { resolveModule } from 'https://esm.sh/@flex-development/mlly'
</script>

Quick Start

Resolve like Node.js

import { moduleResolve } from '@flex-development/mlly'

/**
 * The resolved URL.
 *
 * @const {URL} resolved
 */
const resolved: URL = moduleResolve('typescript', import.meta.url)

Resolve with custom conditions

import { moduleResolve } from '@flex-development/mlly'

/**
 * The resolved URL.
 *
 * @const {URL} resolved
 */
const resolved: URL = moduleResolve('devlop', import.meta.url, ['development'])

Resolve a directory index

import { resolveModule } from '@flex-development/mlly'

/**
 * The resolved URL.
 *
 * @const {URL} resolved
 */
const resolved: URL = resolveModule('./src/lib', import.meta.url, {
  extensions: ['.mts']
})

Resolve path aliases

import { resolveModule, type Aliases } from '@flex-development/mlly'

/**
 * The path mappings dictionary.
 *
 * @const {Aliases} aliases
 */
const aliases: Aliases = {
  '@/internal': './src/internal',
  '@/internal/*': './src/internal/*'
}

/**
 * The resolved directory URL.
 *
 * @const {URL} directory
 */
const directory: URL = resolveModule('@/internal', import.meta.url, { aliases })

/**
 * The resolved file URL.
 *
 * @const {URL} file
 */
const file: URL = resolveModule('@/internal/fs', import.meta.url, { aliases })

console.dir(directory)
console.dir(file)

Rewrite an extension

import { resolveModule } from '@flex-development/mlly'

/**
 * The resolved URL.
 *
 * @const {URL} resolved
 */
const resolved: URL = resolveModule('./src/index.ts', import.meta.url, {
  ext: { '.cts': '.cjs', '.mts': '.mjs', '.ts': '.js' }
})

Use a custom file system

import vfs from '#internal/vfs' // a virtual, async file system
import { resolveModule } from '@flex-development/mlly'

/**
 * The resolved URL.
 *
 * @const {URL} resolved
 */
const resolved: URL = await resolveModule('react', import.meta.url, { fs: vfs })

👀 See the API reference for lower-level building blocks and resolution primitives.

Use Cases

mlly is designed for developers who need Node-compatible ESM resolution behavior.

Common use cases include:

• CLI tools that load user config files and/or plugins
• Plugin systems that resolve modules relative to a project root
• Bundlers and transpilers that need to interpret exports, imports, and main fields
• Test runners and code execution tools
• Monorepo tooling that resolves workspace dependencies
• Runtime loaders and developer tools that operate on virtual filesystems
• Framework tooling that needs resolution behavior matching Node.js

Design Goals

This package is built around a few core goals:

• Spec-compliant behavior where it matters (resolution rules, exports/imports)
• Developer-friendly ergonomics for real-world projects and workflows
• TypeScript-first APIs with strong typing and predictable return values
• Composable building blocks (low-level primitives + high-level helpers)
• Testability and deterministic behavior across environments

API

mlly exports the identifiers listed below.

There is no default export.

canParseUrl(input[, base])

Check if input can be parsed to a URL.

👉 Note: If input is relative, base is required. If input is absolute, base is ignored.

Parameters

• id (unknown) — the input url
• base (unknown) — the base url to resolve against if input is not absolute

Returns

(boolean) true if input can be parsed to a URL, false otherwise

cwd()

Get the URL of the current working directory.

Returns

(URL) The current working directory URL

defaultConditions

Set<Condition>

The default list of conditions.

defaultExtensions

Set<Ext>

The default list of resolvable file extensions.

defaultMainFields

Set<MainField>

The default list of main fields.

extensionFormatMap

Map<Ext, ModuleFormat>

Map, where each key is a file extension and each value is a default module format.

formats

Default module formats (const enum).

const enum formats {
  builtin = 'builtin',
  commonjs = 'commonjs',
  cts = 'commonjs-typescript',
  json = 'json',
  module = 'module',
  mts = 'module-typescript',
  wasm = 'wasm'
}

getSource<T>(id[, options])

Get the source code for a module.

👉 Note: Returns a promise if the handler for id is async.

Type Parameters

• T (Awaitable<FileContent | null | undefined>) — the module source code

Parameters

• id (ModuleId | null | undefined) — the module id
• options (GetSourceOptions | null | undefined) — source code retrieval options

Returns

(T) The module source code

Throws

• ERR_UNSUPPORTED_ESM_URL_SCHEME

isAbsoluteSpecifier(value)

Check if value is an absolute specifier.

👉 Note: Only checks specifier syntax.
Does not guarantee the specifier references an existing module.

Parameters

• value (unknown) — the value to check

Returns

(boolean) true if value is absolute specifier, false otherwise

isArrayIndex(value)

Check if value is a valid array index.

Parameters

• value (unknown) — the value to check

Returns

(value is Numeric) true if value is valid array index, false otherwise

isBareSpecifier(value)

Check if value is a bare specifier.

👉 Note: Only checks specifier syntax.
Does not guarantee the specifier references an existing module.

Parameters

• value (unknown) — the value to check

Returns

(boolean) true if value is bare specifier, false otherwise

isDirectory<T>(id[, fs])

Check if a directory exists.

👉 Note: Returns a promise if fs.stat is async.

Type Parameters

• T (Awaitable<boolean>) — the result of the check

Parameters

• id (ModuleId) — the module id to check
• fs (FileSystem | null | undefined) — the file system api

Returns

(T) true if directory exists at id, false otherwise

isFile<T>(id[, fs])

Check if a file exists.

👉 Note: Returns a promise if fs.stat is async.

Type Parameters

• T (Awaitable<boolean>) — the result of the check

Parameters

• id (ModuleId) — the module id to check
• fs (FileSystem | null | undefined) — the file system api

Returns

(T) true if file exists at id, false otherwise

isImportsSubpath(value)

Check if value is an imports subpath.

👉 Note: Only checks specifier syntax.
Does not guarantee the specifier references an existing module.

Parameters

• value (unknown) — the value to check

Returns

(value is ImportsSubpath) true if value is imports subpath, false otherwise

isModuleId(value)

Check if value is a module id.

Parameters

• value (unknown) — the value to check

Returns

(value is ModuleId) true if value is module id, false otherwise

isRelativeSpecifier(value)

Check if value is a relative specifier.

👉 Note: Only checks specifier syntax.
Does not guarantee the specifier references an existing module.

Parameters

• value (unknown) — the value to check

Returns

(boolean) true if value is relative specifier, false otherwise

legacyMainResolve<T>(packageUrl[, manifest][, mainFields][, parent][, fs])

Resolve a main-like package entry point.

Implements the LEGACY_MAIN_RESOLVE resolution algorithm.

👉 Note: Returns a promise if fs.stat is async.

Type Parameters

• T (Awaitable<URL>) — the resolved entry point url

Parameters

• packageUrl (ModuleId) — the url of the package directory, the package.json file, or a module in the same directory as a package.json
• manifest (PackageJson | null | undefined) — the package manifest
• mainFields (List<MainField> | null | undefined) — the list of legacy main fields
  • default: defaultMainFields
• parent (ModuleId | null | undefined) — the url of the parent module
• fs (FileSystem | null | undefined) — the file system api

Returns

(T) The resolved entry point URL

Throws

• ERR_MODULE_NOT_FOUND

lookupPackageScope<T>(url[, end][, fs])

Get the package scope URL for a module url.

Implements the LOOKUP_PACKAGE_SCOPE algorithm.

👉 Note: Returns a promise if fs.stat is async.

Overloads

function lookupPackageScope(
  this: void,
  url: EmptyString | null | undefined,
  end?: ModuleId | null | undefined,
  fs?: FileSystem | null | undefined
): null

function lookupPackageScope<T extends Awaitable<URL | null>>(
  this: void,
  url: ModuleId | null | undefined,
  end?: ModuleId | null | undefined,
  fs?: FileSystem | null | undefined
): T

Type Parameters

• T (Awaitable<URL | null>) — the resolved package scope url

Parameters

• id (ModuleId | null | undefined) — the url of the module to scope
• end (ModuleId | null | undefined) — the url of the directory to end search at
  • default: root
• fs (FileSystem | null | undefined) — the file system api

Returns

(T) The URL of nearest directory containing a package.json file

moduleResolve<T>(specifier, parent[, conditions][, mainFields][, preserveSymlinks][, fs])

Resolve a module specifier.

Implements the ESM_RESOLVE algorithm.

👉 Note: Returns a promise if fs.realpath or fs.stat is async, or one the following methods returns a promise: packageImportsResolve, packageResolve.

Type Parameters

• T (Awaitable<URL>) — the resolved url

Parameters

• specifier (string) — the module specifier to resolve
• parent (ModuleId) — the url of the parent module
• conditions (List<Condition> | null | undefined) — the list of export/import conditions
  • default: defaultConditions
• mainFields (List<MainField> | null | undefined) — the list of legacy main fields
  • default: defaultMainFields
• preserveSymlinks (boolean | null | undefined) — whether to keep symlinks instead of resolving them
• fs (FileSystem | null | undefined) — the file system api

Returns

(T) The resolved URL

packageExportsResolve<T>(packageUrl, subpath, exports[, conditions][, parent][, fs])

Resolve a package export.

Implements the PACKAGE_EXPORTS_RESOLVE algorithm.

👉 Note: Never returns a promisee.

Type Parameters

• T (Awaitable<URL>) — the resolved package export url

Parameters

• packageUrl (ModuleId) — the url of the package directory, the package.json file, or a module in the same directory as a package.json
• subpath (string) — the package subpath
• exports (Exports | undefined) — the package exports
• conditions (List<Condition> | null | undefined) — the list of export/import conditions
  • default: defaultConditions
• parent (ModuleId | null | undefined) — the url of the parent module
• fs (FileSystem | null | undefined) — the file system api

Returns

(T) The resolved package export URL

packageImportsExportsResolve<T>(matchKey, matchObject, packageUrl[, isImports][, conditions][, mainFields][, parent][, fs])

Resolve a package export or import.

Implements the PACKAGE_IMPORTS_EXPORTS_RESOLVE algorithm.

👉 Note: Returns a promise if packageTargetResolve, returns a promise.

Type Parameters

• T (Awaitable<URL | null | undefined>) — the resolved package export or import url

Parameters

• matchKey (string) — the package subpath extracted from a module specifier, or a dot character (.)
• matchObject (ExportsObject | Imports | null | undefined) — the package exports or imports
• packageUrl (ModuleId) — the url of the directory containing the package.json file
• isImports (boolean | null | undefined) — whether matchObject is internal to the package
• conditions (List<Condition> | null | undefined) — the list of export/import conditions
  • default: defaultConditions
• mainFields (List<MainField> | null | undefined) — the list of legacy main fields
  • default: defaultMainFields
• parent (ModuleId | null | undefined) — the url of the parent module
• fs (FileSystem | null | undefined) — the file system api

Returns

(T) The resolved package export or import URL

packageImportsResolve<T>(specifier, parent[, conditions][, mainFields][, fs])

Resolve a package import.

Implements the PACKAGE_IMPORTS_RESOLVE algorithm.

👉 Note: Returns a promise if lookupPackageScope, packageImportsExportsResolve, or readPackageJson returns a promise.

Type Parameters

• T (Awaitable<URL>) — the resolved package import url

Parameters

• specifier (string) — the import specifier to resolve
• parent (ModuleId) — the url of the parent module
• conditions (List<Condition> | null | undefined) — the list of export conditions
  • default: defaultConditions
• mainFields (List<MainField> | null | undefined) — the list of legacy main fields
  • default: defaultMainFields
• fs (FileSystem | null | undefined) — the file system api

Returns

(T) The resolved package import URL

Throws

• ERR_INVALID_MODULE_SPECIFIER
• ERR_PACKAGE_IMPORT_NOT_DEFINED

packageResolve<T>(specifier, parent[, conditions][, mainFields][, fs])

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 field.

👉 Note: Returns a promise if fs.stat is async or one of the following methods returns a promise: legacyMainResolve, packageExportsResolve, packageSelfResolve, or readPackageJson.

Type Parameters

• T (Awaitable<URL>) — the resolved package url

Parameters

• specifier (string) — the package specifier
• parent (ModuleId) — the url of the parent module
• conditions (List<Condition> | null | undefined) — the list of export conditions
  • default: defaultConditions
• mainFields (List<MainField> | null | undefined) — the list of legacy main fields
  • default: defaultMainFields
• fs (FileSystem | null | undefined) — the file system api

Returns

(T) The resolved package URL

Throws

• ERR_INVALID_MODULE_SPECIFIER
• ERR_MODULE_NOT_FOUND

packageSelfResolve<T>(name, subpath, parent[, conditions][, fs])

Resolve the self-import of a package.

Implements the PACKAGE_SELF_RESOLVE algorithm.

👉 Note: Returns a promise if lookupPackageScope, packageExportsResolve, or readPackageJson returns a promise.

Type Parameters

• T (Awaitable<URL | undefined>) — the resolved package url

Parameters

• name (string) — the package name
• subpath (string) — the package subpath
• parent (ModuleId) — the url of the parent module
• conditions (List<Condition> | null | undefined) — the list of export conditions
  • default: defaultConditions
• fs (FileSystem | null | undefined) — the file system api

Returns

(T) The resolved package URL

packageTargetResolve<T>(packageUrl, target, subpath[, patternMatch][, isImports][, conditions][, mainFields][, parent][, fs])

Resolve a package target.

Implements the PACKAGE_TARGET_RESOLVE algorithm.

👉 Note: Returns a promise if target is internal to the package and packageResolve returns a promise.

Type Parameters

• T (Awaitable<URL | null | undefined>) — the resolved package target url

Parameters

• packageUrl (ModuleId) — the url of the directory containing the package.json file
• target (unknown) — the package target (i.e. a exports/imports value)
• subpath (string) — the package subpath (i.e. a exports/imports key)
• patternMatch (string | null | undefined) — the subpath pattern match
• isImports (boolean | null | undefined) — whether target is internal to the package
• conditions (List<Condition> | null | undefined) — the list of export/import conditions
  • default: defaultConditions
• mainFields (List<MainField> | null | undefined) — the list of legacy main fields
  • default: defaultMainFields
• parent (ModuleId) — the url of the parent module
• fs (FileSystem | null | undefined) — the file system api

Returns

(T) The resolved package target URL

Throws

• ERR_INVALID_PACKAGE_CONFIG
• ERR_INVALID_PACKAGE_TARGET

patternKeyCompare(a, b)

Compare two pattern keys and return a value indicating their order.

Implements the PATTERN_KEY_COMPARE algorithm.

Parameters

• a (string) — the first key
• b (string) — the key to compare against a

Returns

(PatternKeyComparison) The pattern key comparsion result

patternMatch(matchKey, matchObject)

Get a subpath pattern match for matchKey.

Parameters

• matchKey (string) — the key to expand
• matchObject (unknown) — the match keys object

Returns

(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

readPackageJson<T>(id[, specifier][, parent][, fs])

Read a package.json file.

Implements the READ_PACKAGE_JSON algorithm.

👉 Note: Returns a promise if fs.readFile or fs.stat is async.

Overloads

function readPackageJson(
  this: void,
  id: EmptyString | null | undefined,
  specifier?: string | null | undefined,
  parent?: ModuleId | null | undefined,
  fs?: FileSystem | null | undefined
): null

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

Type Parameters

• T (Awaitable<PackageJson | null>) — the parsed file contents

Parameters

• id (ModuleId | null | undefined) — the url of the package directory, the package.json file, or a module in the same directory as a package.json
• specifier (string | null | undefined) — the module specifier that initiated the reading of the package.json file

  👉 note: should be a file: url if parent is not a url

• parent (ModuleId | null | undefined) — the url of the parent module
• fs (FileSystem | null | undefined) — the file system api

Returns

(T) The parsed file contents

Throws

• ERR_INVALID_PACKAGE_CONFIG

resolveAlias(specifier[, options])

Resolve an aliased specifier.

Parameters

• specifier (string) — the specifier using an alias
• options (ResolveAliasOptions | null | undefined) — options for alias resolution

Returns

(string | null) The specifier of the aliased module

resolveModule<T>(specifier, parent[, options])

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 moduleResolve returns a promise.

Type Parameters

• T (Awaitable<URL>) — the resolved url

Parameters

• specifier (string) — the module specifier to resolve
• parent (ModuleId) — the url of the parent module
• options (ResolveModuleOptions) — options for module resolution

Returns

(T) The resolved URL

resolver

An object containing resolution algorithm implementations.

• legacyMainResolve
• moduleResolve
• packageExportsResolve
• packageImportsExportsResolve
• packageImportsResolve
• packageResolve
• packageSelfResolve
• packageTargetResolve

root

URL

The URL of the file system root.

toRelativeSpecifier(url, parent)

Turn url into a relative specifier.

👉 Note: The relative specifier will only have a file extension if specifier also has an extension.

Parameters

• url (ModuleId) — the file: url to convert
• parent (ModuleId) — the parent module id

Returns

(string) The relative specifier

toUrl(id[, parent])

Convert id to a URL.

👉 Note: If id cannot be parsed as a URL and is also not a builtin module, it will be assumed to be a path and converted to a file: URL.

Parameters

• id (ModuleId) — the module id to convert
• parent (ModuleId | null | undefined) — the base url to resolve against if id is not absolute

Returns

(URL) The new URL

Types

This package is fully typed with TypeScript.

Aliases

Record, where each key is a path alias or pattern and each value is a path mapping configuration (interface).

interface Aliases {
  [alias: string]: (string | null | undefined)[] | string | null | undefined
}

When developing extensions that use additional aliases, augment Aliases to register custom aliases:

declare module '@flex-development/mlly' {
  interface Aliases {
    custom?: string[] | string | null
  }
}

Awaitable<T>

Create a union of T and T as a promise-like object (type).

type Awaitable<T> = PromiseLike<T> | T

Type Parameters

• T (any) — the value

BufferEncodingMap

Registry of character encodings that can be used when working with Buffer objects (interface).

When developing extensions that use additional encodings, augment BufferEncodingMap to register custom encodings:

declare module '@flex-development/mlly' {
  interface BufferEncodingMap {
    custom: 'custom'
  }
}

BufferEncoding

Union of values that can occur where a buffer encoding is expected (type).

To register new encodings, augment BufferEncodingMap. They will be added to this union automatically.

type BufferEncoding = BufferEncodingMap[keyof BufferEncodingMap]

ConditionMap

Registry of export/import conditions (interface).

When developing extensions that use additional conditions, augment ConditionMap to register custom conditions:

declare module '@flex-development/mlly' {
  interface ConditionMap {
    custom: 'custom'
  }
}

Condition

Union of values that can occur where a export/import condition is expected (type).

To register new conditions, augment ConditionMap. They will be added to this union automatically.

type Condition = ConditionMap[keyof ConditionMap]

Dot

A dot character ('.') (type).

type Dot = '.'

EmptyArray

An empty array (type).

type EmptyArray = []

EmptyObject

An empty object (type).

type EmptyObject = { [tag]?: never }

EmptyString

An empty string (type).

type EmptyString = ''

Ext

A file extension (type).

type Ext = `${Dot}${string}`

ExtensionRewrites

Record, where each key is the file extension of a module specifier and each value is a replacement file extension (type).

👉 Note: Replacement file extensions are normalized and do not need to begin with a dot character ('.'); falsy values will remove an extension.

type ExtensionRewrites = {
  [K in EmptyString | Ext]?: string | false | null | undefined
}

FileContent

Union of values that can occur where file content is expected (type).

type FileContent = Uint8Array | string

FileSystem

The file system API (interface).

Properties

• readFile (ReadFile) — read the entire contents of a file
• realpath (Realpath) — compute a canonical pathname by resolving ., .., and symbolic links
• stat (Stat) — get information about a directory or file

GetNewExtension<[T]>

Get a new file extension for a url (type).

Returning an empty string (''), false, null, or undefined will remove the current file extension.

type GetNewExtension<
  T extends string | false | null | undefined =
    | string
    | false
    | null
    | undefined
> = (this: void, url: URL, specifier: string) => T

Type Parameters

• T (string | false | null | undefined, optional) — the new file extension

Parameters

• url (URL) — the resolved module URL
• specifier (string) — the module specifier being resolved

Returns

(T) The new file extension

GetSourceContext

Source code retrieval context (interface).

Extends

• GetSourceOptions

Properties

• fs (FileSystem) — the file system api
• handlers (GetSourceHandlers) — record, where each key is a url protocol and each value is a source code handler
• req (RequestInit) — request options for network based modules
• schemes (Set<string>) — the list of supported url schemes

GetSourceHandler

Get the source code for a module (type).

type GetSourceHandler = (
  this: GetSourceContext,
  url: URL
) => Awaitable<FileContent | null | undefined>

Parameters

• this (GetSourceContext) — the retrieval context
• url (URL) — the module URL

Returns

(Awaitable<FileContent | null | undefined>) The source code

GetSourceHandlers

Record, where key is a URL protocol and each value is a source code handler (type).

type GetSourceHandlers = {
  [H in Protocol]?: GetSourceHandler | null | undefined
}

GetSourceOptions

Options for retrieving source code (interface).

Properties

• encoding? (BufferEncoding | null | undefined) — the encoding of the result

  👉 note: used when the file: handler is called

• format? (ModuleFormat | null | undefined) — the module format hint
• fs? (FileSystem | null | undefined) — the file system api
• handlers? (GetSourceHandlers | null | undefined) — record, where each key is a url protocol and each value is a source code handler
• ignoreErrors? (boolean | null | undefined) — whether to ignore ERR_UNSUPPORTED_ESM_URL_SCHEME if thrown
• req? (RequestInit | null | undefined) — request options for network based modules
• schemes? (List<string> | null | undefined) — the list of supported url schemes
  • default: ['data', 'file', 'http', 'https', 'node']

IsDirectory

Check if a stats object describes a directory (interface).

Returns

(boolean) true if stats describes directory, false otherwise

IsFile

Check if a stats object describes a file (interface).

Returns

(boolean) true if stats describes regular file, false otherwise

List<[T]>

A list (type).

type List<T = unknown> = ReadonlySet<T> | readonly T[]

Type Parameters

• T (any, optional) — the list item type

MainFieldMap

Registry of main fields (interface).

When developing extensions that use additional fields, augment MainFieldMap to register custom fields:

declare module '@flex-development/mlly' {
  interface MainFieldMap {
    unpkg: 'unpkg'
  }
}

MainField

Union of values that can occur where a main field is expected (type).

To register new main fields, augment MainFieldMap. They will be added to this union automatically.

type MainField = MainFieldMap[keyof MainFieldMap]

ModuleFormatMap

Registry of module formats (interface).

When developing extensions that use additional formats, augment ModuleFormatMap to register custom formats:

declare module '@flex-development/mlly' {
  interface ModuleFormatMap {
    custom: 'custom'
  }
}

ModuleFormat

Union of values that can occur where a module format is expected (type).

To register new main formats, augment ModuleFormatMap. They will be added to this union automatically.

type ModuleFormat = ModuleFormatMap[keyof ModuleFormatMap]

ModuleId

Union of values that can occur where a ECMAScript (ES) module identifier is expected (type).

type ModuleId = URL | string

Numeric

A string that can be parsed to a valid number (type).

type Numeric = `${number}`

PatternKeyComparsionMap

Registry of PATTERN_KEY_COMPARE algorithm results (interface).

When developing extensions that use additional results, augment PatternKeyComparsionMap to register custom results:

declare module '@flex-development/mlly' {
  interface PatternKeyComparsionMap {
    afterThree: 3
  }
}

PatternKeyComparsion

Union of values that can occur where a PATTERN_KEY_COMPARE algorithm result is expected (type).

To register new results, augment PatternKeyComparisonMap. They will be added to this union automatically.

type PatternKeyComparison =
  PatternKeyComparisonMap[keyof PatternKeyComparisonMap]

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).

type PatternMatch = [expansionKey: string, patternMatch: string | null]

ProtocolMap

Registry of URL protocols (interface).

When developing extensions that use additional protocols, augment ProtocolMap to register custom protocols:

declare module '@flex-development/mlly' {
  interface ProtocolMap {
    custom: 'custom:'
  }
}

Protocol

Union of values that can occur where a URL protocol is expected (type).

To register new results, augment ProtocolMap. They will be added to this union automatically.

type Protocol = ProtocolMap[keyof ProtocolMap]

ReadFile

Read the entire contents of a file (interface).

Overloads

(id: ModuleId, encoding: BufferEncoding): Awaitable<string>
<T extends Awaitable<FileContent | null | undefined>>(id: ModuleId, encoding?: BufferEncoding | null | undefined): T

Type Parameters

• T (Awaitable<FileContent | null | undefined>, optional) — the file contents
  • default: Awaitable<FileContent>

Parameters

• id (ModuleId) — the module id
• encoding (BufferEncoding) — the encoding of the file contents

Returns

(T) The file contents

Realpath

Compute a canonical pathname by resolving ., .., and symbolic links (interface).

👉 Note: A canonical pathname is not necessarily unique. Hard links and bind mounts can expose an entity through many pathnames.

Type Parameters

• T (Awaitable<string>, optional) — the canonical pathname

Parameters

• id (ModuleId) — the module id

Returns

(T) The canonical pathname

ResolveAliasOptions

Options for path alias resolution (interface).

Properties

• absolute? (boolean | null | undefined) — whether the resolved specifier should be absolute.
  if true, the resolved specifier will be a file: URL
• aliases? (Aliases | null | undefined) — the path mappings dictionary

  👉 note: paths should be relative to cwd

• cwd? (ModuleId | null | undefined) — the url of the directory to resolve non-absolute modules from
  • default: cwd()
• parent? (ModuleId | null | undefined) — the url of the parent module

ResolveModuleOptions

Options for module resolution (interface).

Properties

• aliases? (Aliases | null | undefined) — the path mappings dictionary

  👉 note: paths should be relative to cwd

• conditions? (List<Condition> | null | undefined) — the list of export/import conditions
  • default: defaultConditions

  👉 note: should be sorted by priority

• cwd? (ModuleId | null | undefined) — the url of the directory to resolve path aliases from
  • default: cwd()
• ext? (ExtensionRewrites | GetNewExtension | false | string | 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

• extensions? (List<string> | null | undefined) — the module extensions to probe for
  • default: defaultExtensions

  👉 note: should be sorted by priority

• fs? (FileSystem | null | undefined) — the file system api
• mainFields? (List<MainField> | null | undefined) — the list of legacy main fields
  • default: defaultMainFields

  👉 note: should be sorted by priority

• preserveSymlinks? (boolean | null | undefined) — whether to keep symlinks instead of resolving them

Stat

Get information about a directory or file (interface).

Type Parameters

• T (Awaitable<Stats>, optional) — the info

Parameters

• id (ModuleId) — the module id

Returns

(T) The info

Stats

An object describing a directory or file (interface).

Properties

• isDirectory (IsDirectory) — check if the stats object describes a directory
• isFile (IsFile) — check if the stats object describes a file

Sponsors

If you find this package helpful, consider sponsoring to support maintenance, tests, and long-term stability.

Contribute

See CONTRIBUTING.md.

This project has a code of conduct. By interacting with this repository, organization, or community you agree to abide by its terms.