esmod-pmb

Use esm (ES modules, import, export for Node v6) with less boilerplate.

Usage

Let's assume you have an ES module like usage.mjs:

1import dfOnly from './default-export-only';
2import * as named from './named-exports-only';
3
4export default dfOnly;
5export const { foo, answer } = named;

… and you want to use it from old node's CommonJS realm. The esm module can do it:

1module.exports = require('esm')(module)('./usage.mjs')

But that's still a bit too much boilerplate for my taste. Don't waste your time micro-managing the filename and whether you should add .default to the above formula! There's a much easier way:

Make a bridge module with almost the same name, except it ends with .node.js instead of .mjs (thus here, usage.node.js):

1require('esmod-pmb')(module);

It should work out of the box:

1$ nodejs -p "require('./usage.node.js')"
2{ foo: [Getter], answer: [Getter], default: [Getter] }

To see values instead of getters, copy them to another object:

1$ nodejs -p "Object.assign({}, require('./usage.node.js'))"
2{ foo: 23,
3  answer: 42,
4  default: { isDefaultExport: true, bar: 5 } }

For modules that have a default export and no named exports, like default-export-only.mjs:

1export default { isDefaultExport: true, bar: 5 };

… your bridge module will export that as the top level:

1$ nodejs -p "require('./default-export-only.node.js')"
2{ isDefaultExport: true, bar: 5 }
3$ nodejs -p "require('esm')(module)('./default-export-only.mjs')"
4{ default: [Getter] }

API

1// standard:
2require('esmod-pmb')(module);
3
4// custom options:
5require('esmod-pmb')(module, { preferDefaultExport: false });
6
7// detailed:
8var bridgeBuilder = require('esmod-pmb');
9var opt = { reexport: false };
10var esmRequire = bridgeBuilder(module, opt);
11var yourEsModule = esmRequire('./yourmodule.mjs');

This module exports one function:

esmRqr = bridgeBuilder(baseModule[, opt])

Returns an ESM-capable require-like function obtained from esm.

The optional options object opt can be used to modify the default options.

If you need custom options for something you consider "normal"/"usual", please file an issue so we can try to provide better defaults. After all, the purpose of this module is to reduce boilerplate.

That said, bridgeBuilder uses the same options object as esm, so you can use all of its options, and some additional ones:

• reexport: (bool, default: true) Whether bridgeBuilder shall do its main magic:
  1. guess the name of your ES module,
  2. import it,
  3. (skippable) resolve the imported bindings
  4. and "re-export" them, i.e. assign the imported values to baseModule.exports.
  • Set to false to opt-out of the main magic, but still get an esmRqr with the combined options based on this module's defaults.

Options used only when reexport is enabled:

• stripSuffixes: (regexp) and addSuffix (string, default: ".mjs") To guess the ES module filename, the bridgeBuilder removes the part matched by stripSuffixes and appends addSuffix.

• resolveImportedValues: (bool, default: true) Whether to resolve (copy) the imported values. Set to false if you prefer getter functions. Sane modules usually shouldn't mutate their exports, so usually resolving them makes life easier by reducing the amount of magic involved.

• preferDefaultExport: Determines which of the ESM exports shall be re-export into CommonJS land.

  • false = all of them. The re-export will be a dictionary (object). If the ES module only has a default export, the dictionary will contain only one key, default.
  • true = only the default export. If the ES module doesn't have a default export, the re-export will be undefined.
  • 1 (as a number; also the default) = automatic. The re-export will be a dictionary with all exports, except in case there is only one single export and its name is default; in that case, that default export will be re-exported directly.

Known issues

• Needs more/better tests and docs.

 

License

ISC