Global

Members

esmModules :ESMModules|null

Source:

This variable is used to cache the result of require for chalk and avoid having to do it multiple times.

Type:

(constant) path

Source:

Some comment about the function.

util

Source:

exports - Replace module.exports calls with es6 exports

Methods

addErrorHandler() → {function}

Source:

Adds an error handler to the process so if something fails, it will be logged with a nice style and a custom emssage.

Returns:

To remove the listeners.

Type
function

(async) addPackageJSON(output) → {Promise}

Source:

Adds a package.json with type set to module on the output directory. This is so Node can properly resolve the ESM files.

Parameters:
Name Type Description
output string

The output directory the tool will use.
Returns:
Type
Promise

(async) copyFiles(input, output, useExtension, forceDirectorynullable, ignorenullable) → {Promise.<Array.<CJS2ESMCopiedFile>>}

Source:

Copies all the files the tool will transpile.

Parameters:
Name Type Attributes Description
input Array.<string>

The list of source paths where the files are located.
output string

The output path where all the files will be transpiled to.
useExtension ModuleExtension

The extension the modules should use.
forceDirectory boolean <nullable>

By default, if input has only one directory, the only thing copied will be its contents, instead of the directory itself; this parameter can be used to force it and always copy the directory.
ignore Array.<string> <nullable>

A list of expressions for paths that should be ignored.
Returns:
Type
Promise.<Array.<CJS2ESMCopiedFile>>

createReplacementForFolder(absPath, importPath) → (nullable) {string}

Source:

Creates the replacement path for an import statement for a folder. It validates if the folder has a package.json, to keep it as it is, and if it fails, it tries to find an index files, .mjs or .js.

Parameters:
Name Type Description
absPath string

The absolute path for the folder.
importPath string

The path as it is on the import statement.
Returns:

If there's no package.json and no index was found, the function will return null.

Type
string

(async) ensureOutput(output) → {Promise}

Source:

Ensures the output directory exists and it's empty. If the directory exists, it removes it and then creates it again.

Parameters:
Name Type Description
output string

The output directory the tool will use.
Returns:
Type
Promise

(async) findFile(list, directory) → {Promise.<?string>}

Source:

Given a list of file names and a directory, the function will try find the first file that exists.

Parameters:
Name Type Description
list Array.<string>

The list of files to test.
directory string

The base directory where the paths will be tested.
Returns:
Type
Promise.<?string>

findFileSync(list, directory) → (nullable) {string}

Source:

Given a list of file names and a directory, the function will try to find the first file that exists.

Parameters:
Name Type Description
list Array.<string>

The list of files to test.
directory string

The base directory where the paths will be tested.
Returns:
Type
string

(async) getAbsPathInfo(absPath) → {Promise.<?AbsPathInfo>}

Source:

Given an the aboslute path for an import/require statement, the method will validate if its for a folder, a file, and if it's for a file, it will complete its extension in case it's missing.

Parameters:
Name Type Description
absPath string

The absolute path for the resource.
Returns:
Type
Promise.<?AbsPathInfo>

getAbsPathInfoSync(absPath) → (nullable) {AbsPathInfo}

Source:

Given an the aboslute path for an import/require statement, the method will validate if its for a folder, a file, and if it's for a file, it will complete its extension in case it's missing.

Parameters:
Name Type Description
absPath string

The absolute path for the resource.
Returns:
Type
AbsPathInfo

getChalk() → {Object}

Source:

Get a reference for chalk module.

Returns:
Type
Object

(async) getConfiguration() → {Promise.<CJS2ESMOptions>}

Source:

Loads the configuration for the project.

Returns:
Type
Promise.<CJS2ESMOptions>

log(color, …args)

Source:

Logs messages prefixed with the name of the project and with a specified color. Yes, this is a proxy-like function for console.log with chalk.

Parameters:
Name Type Attributes Description
color string

The color from chalk that should be used.
args Array.<string> <repeatable>

The list of messages to log.

(async) prepare() → {Promise.<void>}

Source:

Setups everything necessary for the library to work.

Returns:
Type
Promise.<void>

requireModule(modulePath) → {Object}

Source:

This function is just a proxy for require and it only exists to make testing the tool easier: the test for this is just that returns the same as require, but on the files that use it, with mocking this funcion is enough and there won't be any need for resetModules.

Parameters:
Name Type Description
modulePath string

The path to the module to be required.
Returns:
Type
Object

transform(file, api, options) → {string}

Source:

This is the transformation for jscodeshift the tool uses to modify import statements, add missing .mjs extensions and change paths if needed.

Parameters:
Name Type Description
file FileInfo

The information of the file to transform.
api API

The API that expose jscodeshift, with utilities for the transformation.
options TransformOptions

These options are sent by jscodeshift, but the tool injected its own options so the transformation can access to the settings related to the extension.
Returns:
Type
string

(async) transformOutput(files, options) → {Promise}

Source:

Transforms all files from the output directory into ES Modules.

Parameters:
Name Type Description
files Array.<CJS2ESMCopiedFile>

The list of files that were copied to the output directory.
options CJS2ESMOptions

The options of the tool, so they can be sent to the transformers.
Throws:

If there's a problem while transforming a file.

Type
Error
Returns:
Type
Promise

(async) updatePackageJSON(files) → {Promise}

Source:

Updates the project package.json by adding a module property that points to the transformed version of the current main property.

Parameters:
Name Type Description
files Array.<CJS2ESMCopiedFile>

The list of files that were copied, so the function can find the transformed path for the main file.
Throws:

If the function can't find the transformed version of the main file.

Type
Error
Returns:
Type
Promise

Type Definitions

AbsPathInfo

Source:
Properties:
Name Type Attributes Description
path string

The complete, absolute, path to the file/folder.
isFile boolean

Whether or not the path is for a file.
extension string <nullable>

If the path is for a file, this will be its extension.
Type:

CJS2CodemodOptions

Source:
Properties:
Name Type Attributes Description
path string <nullable>

The path, relative to the cwd, to the transformations directory. By default, 5to6-codemod, relative to this module.
files Array.<string> <nullable>

The list of transformations to use, without extension, as .js will be used. If not defined, empty, or not an array, it will use the defaults: cjs, exportsand named-export-generation`.
Type:

CJS2ESMCopiedFile

Source:
Properties:
Name Type Description
from string

The absolute path from where the file was copied.
to string

The absolute path to where the file was copied to. It may include a change of extension if it was configured on the tool.
Type:

CJS2ESMExtensionOptions

Source:
Properties:
Name Type Description
use ModuleExtension

Which extension should be used.
ignore Array.<string>

A list of expressions (strings that will be converted on RegExp) to ignore import statements when validating the use of extensions.
Type:

CJS2ESMModuleOption

Source:
Properties:
Name Type Attributes Description
name string

The name of the module, or the beginning of an import path. This will be converted into a RegExp, so it can be a expression too.
find string <nullable>

Optionally, instead of replacing name on the path, this property can be used to define a custom RegExp string.
path string

The custom path for the ESM version.
Type:

CJS2ESMOptions

Source:
Properties:
Name Type Attributes Description
input Array.<string>

The list of directories that should be transformed.
output string

The directory where the transformed code should be placed.
forceDirectory boolean <nullable>

By default, if input has only one directory, the only thing copied will be its contents, instead of the directory itself; this flag can be used to force force it and always copy the directory.
modules Array.<CJS2ESMModuleOption>

Special configurations for modules with ESM versions.
extension CJS2ESMExtensionOptions

How should the tool handle the file extensions.
addModuleEntry boolean

Whether or not to modify the project package.json and add a module property with the path to the transformed entry file. This will only work if the project has a main property and the file it points to was transformed.
addPackageJson boolean

Whether or not to add a package.json with type set to module on the output directory.
filesWithShebang Array.<string>

The list of files that have a shebang, as the tool needs to remove it before transforming them in order to avoid issues with the parsers. The list are strings that will be converted on into RegExps, so they can be a parts of the path, or expressions.
codemod CJS2ESMOptions <nullable>

Options to customize integration with the codemod tool, for the transformations.
Type:

ModuleExtension

Source:
Type:
  • 'js' | 'mjs'

TransformOptions

Source:
Properties:
Name Type Description
cjs2esm CJS2ESMOptions

The options sent to the main tool. Needed to validate how the extension should be handled.
Type: