esm-cli

ECMAScript modules launcher in Node 6+

Lunch ES modules using command line interpreter, accessing a specific export function or data, and passing parameters.

Install

Just install module as a global command with npm npm install -g esm-cli

Or you can install it globaly directly from a git clone:

git clone https://git.p2p.legal/dig/esm-cli
cd esm-cli
npm install -g .

You should get acces to a global esm command.

Usage

With esm-cli you can instanciate a full ES module file, executing it's content, and retreive an exported variable or execute an exported function. It understand returned promises or async functions.

esm path/to/esm_file:export_name [params]

In this exemple, the file ./path/to/esm_file.js is executed and the exported function is executed passing the parsed params:
await export_name( [params] )

Note: .js extension is not needed (nodejs resolver).

Get exported variables

Let's write a simple ES module (myModule.js):

export default 42
export var user_config = {
    some: "json"
}

And let's use it in cli:

esm myModule
> 42

In a bash file you can invoke some text return using command subsitutions:

#!/usr/bin/env bash
es_var=$(esm myModule)
echo "EcmaScript said: $es_var"

If only a path to the file is provided, the default export is returned if any.

You can access any named exports:

esm myModule:user_config
> { "some": "json" }

Use exported functions

When the exported "thing" is a function (async or not), it is executed passing command line parameters if given.

Imagine a simple ES module library (myLib.js):

export default function hello()
{
    console.log( 'Hello world !' )
}
export function greet( params ) {
    return `Hello ${params[0]}`
}

Then you can write:

esm myLib
> Hello world !

esm myLib:greet Pierre
> Hello Pierre !!

Promise/async support

If the returned result is a promise, because explicitly returned, or from an async function, esm-cli will take care of waiting it's resolution returning the resolved value (gently catching rejections showing nothing).

Parameters parsing

Command line parameters are parsed into an Array before it is given to a called function.
This Array contains a list of strings corresponding to each string given without hyphen -:

(myLib.js)

export function showParams( params )
{
    console.log( params )
}

esm myLib:showParams param1 param2 param3
> [ "param1", "param2", "param3" ]

... and this array is augmented with properties corresponding to hyphen params, with value or "true" if not:

esm myLib:showParams param1 param2 param3 -s --t -foo --bar -baz:42 --val=some
> [ "param1", "param2", "param3", s: true, t: true, foo: true, bar: true, baz: 42, val: "some" ]

Note: order don't matters...

You can then use ES destructuration to filter named paremeters:

export function myAwesomeFunction( [ first, second, , forth ] ) // Array destructuration gets simple params
{
    console.log( first, second, forth )
}
export function myAwesomeFunction2( { foo, val, baz } ) // Object destructuration gets named params
{
    console.log( foo, val, baz )
}
export function myAwesomeFunction3( { 0:param1, 3:param4, foo, val, baz } ) // Object destructuration for both, using index name
{
    console.log( param1, param4, foo, val, baz )
}

To call this kind of function in js:

myAwesomeFunction3({ 0: "first", 3: "forth", foo: true })