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:

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

To call this kind of function in js and create an augmented param array:

import { myAwesomeFunction3 } from 'myLib'

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

Choose the type of result rendered

As default esm-cli uses console.log to render the resulting object to output. It's great to get primitives correctly rendered like strings without ".
But you may sometimes need to get a JSON string representation of object, like when working with stings quoted ans escaped, or to get a complete JSON object.
To do so, you can use the commandline switch =json that can be placed in any order and is not given to the module as param:

> esm myLib
> Hello world!

> esm myLib =json
> "Hello world!"

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

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

Usage with managers

forever

forver -c esm myScript --param option
```