⚙️ mlly

ECMAScript module utilities.

Contents

• What is this?
• Install
• Use
• 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
  • ChangeExtFn<[Ext]>
  • ConditionMap
  • Condition
  • Dot
  • EmptyArray
  • EmptyObject
  • EmptyString
  • Ext
  • FileContent
  • FileSystem
  • 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
• Contribute

What is this?

mlly is a set of ECMAScript module (ESM) utilities.
It exposes several tools to bridge the gap between developer experience and the current state of ECMAScript modules.

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>

Use

import {
  lookupPackageScope,
  readPackageJson,
  resolveModule,
  type FileSystem
} from '@flex-development/mlly'
import pkg from '@flex-development/mlly/package.json' with { type: 'json' }
import type { PackageJson } from '@flex-development/pkg-types'
import nfs from 'node:fs'

/**
 * A file system API with both asynchronous and synchronous methods.
 *
 * @const {FileSystem} fs
 */
const fs: FileSystem = {
  readFile: nfs.promises.readFile,
  realpath: nfs.promises.realpath,
  stat: nfs.statSync
}

/**
 * The URL of the package directory.
 *
 * @const {URL | null} scope
 */
const scope: URL | null = lookupPackageScope(import.meta.url, null, fs)

console.dir(scope) // file:///Users/lex/Projects/flex-development/mlly/

/**
 * The package manifest.
 *
 * @const {PackageJson | null} manifest
 */
const manifest: PackageJson | null = await readPackageJson(
  scope,
  null,
  import.meta.url,
  fs
)

console.dir(manifest?.name === pkg.name) // true
console.dir(manifest) // `pkg`

/**
 * A fully resolved URL.
 *
 * @const {URL} resolved
 */
const resolved = resolveModule(pkg.name, import.meta.url, {
  conditions: new Set(['mlly']),
  ext: null
})

console.dir(resolved) // file:///Users/lex/Projects/flex-development/mlly/src/

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) — alias resolution options

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:

• 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 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) — module resolution options

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]

ChangeExtFn<[Ext]>

Get a new file extension for url (type).

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

type ChangeExtFn<
  Ext extends string | null | undefined = string | null | undefined
> = (this: void, url: URL, specifier: string) => Ext

Type Parameters

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

Parameters

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

Returns

(Ext) The new file extension

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}`

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

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) — 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 path alias 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? (ChangeExtFn | string | null | undefined) — a replacement file extension or a function that returns a file extension.

  👉 note: an empty string ('') or null will remove a file 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

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.