esm-cli/README.md

# 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](#parameters-parsing):  
`await export_name( [params] )`

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

### Get exported variables

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

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

And let's use it in cli:

```bash
esm myModule
> 42
```

In a bash file you can invoke some text return using command subsitutions:
```bash
#!/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:
```bash
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):

```javascript
export default function hello()
{
    console.log( 'Hello world !' )
}
export function greet( params ) {
    return `Hello ${params[0]}`
}
```
Then you can write:
```bash
esm myLib
> Hello world !
```
```bash
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)
```javascript
export function showParams( params )
{
    console.log( params )
}
```

```bash
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:
```bash
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:

```javascript
// 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:
```javascript
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

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