173 lines
4.3 KiB
Markdown
173 lines
4.3 KiB
Markdown
# 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
|
|
```
|