mlly

What is mlly?

The mlly npm package is a utility library for working with ES module syntax. It provides functions to analyze and manipulate module specifiers and import/export statements.

What are mlly's main functionalities?

Analyzing import/export statements

This feature allows you to analyze the import and export statements within a given piece of code. It returns an object with details about the imports and exports found.

import { analyzeModule } from 'mlly';
const code = `import { foo } from 'bar';`;
const analysis = analyzeModule(code);

Resolving import/export specifiers

This feature helps in resolving the full path of an import specifier based on the current file's location. It is useful for resolving relative paths.

import { resolveImport } from 'mlly';
const resolved = resolveImport('./foo.js', '/path/to/module.js');

Checking for dynamic imports

This feature checks if a given piece of code contains dynamic imports, which are imports that occur within the execution context rather than statically at the top of the file.

import { hasDynamicImport } from 'mlly';
const code = `const module = import('./module.js');`;
const hasDynamic = hasDynamicImport(code);

Other packages similar to mlly

es-module-lexer

This package provides a lexer for ES module syntax, allowing for the analysis of import/export statements. It is similar to mlly in that it can be used to parse and understand module structures, but it is implemented as a low-level lexer written in WebAssembly for performance.

acorn

Acorn is a JavaScript parser that can be used to analyze and manipulate JavaScript code, including ES modules. While mlly is focused on module syntax, Acorn provides a more general-purpose parsing solution that can handle a wide range of JavaScript features.

rollup

Rollup is a module bundler for JavaScript that includes features for analyzing and bundling ES modules. It is more complex and feature-rich than mlly, offering a complete solution for bundling modules for production use, whereas mlly is more focused on module analysis and manipulation.

README

🤝 mlly

Missing ECMAScript module utils for Node.js

Install

This package is ESM only. Node.js 12+ is needed to use it and it must be imported instead of required.

Install npm package:

# using yarn
yarn add mlly

# using npm
npm install mlly

Import utils:

import {} from 'mlly'

CommonJS Context

createCommonJS

This utility creates a compatible CommonJS context that is missing in ECMAScript modules.

import { createCommonJS } from 'mlly'

const { __dirname, __filename, require } = createCommonJS(import.meta)

Resolving Modules

resolve

Resolve a module by respecting ECMAScript Resolver algorithm (internally using wooorm/import-meta-resolve that exposes Node.js implementation).

Additionally supports resolving without extension and /index similar to CommonJS.

import { resolve } from 'mlly'

// file:///home/user/project/module.mjs
console.log(await resolve('./module.mjs', { from: import.meta.url }))

Resolve options:

• from: URL or string (default is pwd())
• conditions: Array of conditions used for resolution algorithm (default is ['node', 'import'])
• extensions: Array of additional extensions to check if import failed (default is ['.mjs', '.cjs', '.js', '.json'])

resolvePath

Similar to resolve but returns a path instead of URL using fileURLToPath.

import { resolvePath } from 'mlly'

// //home/user/project/module.mjs
console.log(await resolvePath('./module.mjs', { from: import.meta.url }))

createResolve

Create a resolve function with defaults.

import { createResolve } from 'mlly'

const _resolve = createResolve({ from: import.meta.url })

// file:///home/user/project/module.mjs
console.log(await _resolve('./module.mjs'))

Example: Ponyfill import.meta.resolve:

import { createResolve } from 'mlly'

import.meta.resolve = createResolve({ from: import.meta.url })

resolveImports

Resolve all static and dynamic imports with relative paths to full resolved path.

import { resolveImports } from 'mlly'

// import foo from 'file:///home/user/project/bar.mjs'
console.log(await resolveImports(`import foo from './bar.mjs'`, { from: import.meta.url }))

Evaluating Moduls

loadModule

Dynamically loads a module by evaluating source code.

import { loadModule } from 'mlly'

await loadModule('./hello.mjs', { from: import.meta.url })

Options are same as evalModule.

evalModule

Evaluates JavaScript module code using dynamic imports with data: using toDataURL.

import { evalModule } from 'mlly'

await evalModule(`console.log("Hello World!")`)

await evalModule(`
  import { reverse } from './utils.mjs'
  console.log(reverse('!emosewa si sj'))
`, { from: import.meta.url })

Options:

• [all resolve options]
• url: File URL

readModule

Resolve module path and read source contents. (currently only file protocol supported)

import { resolve, readModule } from 'mlly'

const indexPath = await resolve('./index.mjs', { from: import.meta.url })

// { code: '...", url: '...' }
console.log(await readModule(indexPath))

Options are same as resolve.

toDataURL

Convert code to data: URL using base64 encoding.

All relative imports will be automatically resolved with from param using resolveImports.

If url option is provided, all usages of import.meta.url will be rewritten too.

import { toDataURL } from 'mlly'

console.log(await toDataURL(`
  // This is an example
  console.log('Hello world')
`))

Options are same as evalModule.

Other utils

fileURLToPath

Similar to url.fileURLToPath but also converts windows backslash \ to unix slash / and handles if input is already a path.

import { fileURLToPath } from 'mlly'

// /foo/bar.js
console.log(fileURLToPath('file:///foo/bar.js'))

// C:/path
console.log(fileURLToPath('file:///C:/path/'))

normalizeid

Ensures id has either of node:, data:, http:, https: or file: protocols.

import { ensureProtocol } from 'mlly'

// file:///foo/bar.js
console.log(normalizeid('/foo/bar.js'))

License

MIT