machine-as-script - npm Package Compare versions

Comparing version 1.2.0 to 2.0.0

index.js

@@ -11,2 +11,3 @@ /**
 var Machine = require('machine');
+var rttc = require('rttc');
 
@@ -27,2 +28,8 @@
 
+  // Set up namespace for environment variables.
+  var envVarNamespace = '___';
+  if (_.isString(opts.envVarNamespace)) {
+    envVarNamespace = opts.envVarNamespace;
+  }
+
   // Build machine, applying defaults
@@ -52,3 +59,3 @@ var wetMachine = Machine.build(_.extend({
 
-  // Loop over each input and check for command line arguments and/or environment variables.
+  // Loop over each input and set up command line opts for usage docs generated by commander.
   _.each(wetMachine.inputs, function (inputDef, inputName) {
@@ -73,5 +80,2 @@
 
-    // Handle environment variables
-    // todo
-
     // Call out to commander and apply usage
@@ -108,2 +112,14 @@ var optUsage = (function (){
 
+  // Supply environment variables
+  _.each(wetMachine.inputs, function (inputDef, inputName){
+    var envVarData = process.env[envVarNamespace + inputName];
+    if (_.isUndefined(envVarData)) {
+      return;
+    }
+
+    // If environment variable exists, we'll grab its value and
+    // supply it as configuration for this input.
+    inputConfiguration[inputName] = envVarData;
+  });
+
   // Include a special `args` input for convenience--
@@ -122,3 +138,17 @@ // but note that this is an experimental feature that could change.
 
+  // Finally, loop through each of the input configurations and run `rttc.parseHuman()`.
+  inputConfiguration = _.reduce(inputConfiguration, function (memo, val, inputName){
 
+    // Skip special `args` input (unless there's actually an input named `args`.)
+    var inputDef = wetMachine.inputs[inputName];
+    if (!inputDef && inputName === 'args') {
+      return memo;
+    }
+    if (!inputDef) {
+      throw new Error('Unexpected error: received configuration for unknown input ('+inputName+')');
+    }
+    memo[inputName] = rttc.parseHuman(val, rttc.infer(inputDef.example), true);
+    return memo;
+  }, {});
+
   // Set input values from CLI args/opts
@@ -125,0 +155,0 @@ var liveMachine = wetMachine(inputConfiguration);

package.json

 {
   "name": "machine-as-script",
-  "version": "1.2.0",
+  "version": "2.0.0",
   "description": "Run a machine as a command-line script.",
@@ -22,3 +22,4 @@ "scripts": {
     "lodash": "^3.8.0",
-    "machine": "^11.0.1",
+    "machine": "^11.0.3",
+    "rttc": "^8.1.7",
     "yargs": "3.4.5"
@@ -25,0 +26,0 @@ },

README.md

@@ -20,3 +20,5 @@ # machine-as-script
 
-asScript(MPMath.add).exec({
+asScript({
+  machine: MPMath.add
+}).exec({
   success: function (sum){
@@ -41,4 +43,6 @@ console.log('Got result:', sum);
 
-You can use the `args` input to accept serial CLI arguments:
+In addition to specifying inputs as `--` CLI opts, you can configure your script to accept serial CLI arguments.
 
+Just specify `args` as an array of input names, in the expected order:
+
 ```js
@@ -55,13 +59,157 @@ asScript({
 
-Now you can use serial CLI arguments as inputs:
+Now you can use serial CLI arguments to configure the related inputs:
 
 ```sh
-$ node ./add-numbers.js 2 3
-# Got result: 5
+$ node ./add-numbers.js 4 5
+# Got result: 9
 ```
 
+#### Experimental: The `args` input
 
+If you don't already have an input named `args`, when using machine-as-action, your machine's `fn` will receive an array of serial command-line arguments in `inputs.args`.  **THIS IS AN EXPERIMENTAL FEATURE AND COULD CHANGE AT ANY TIME WITHOUT BACKWARDS COMPATIBILITY!!**
 
+
+## Using environment variables
+
+Sometimes (particularly in a production setting, like on Heroku) you want to be able to
+use your machine as a script without specifying command-line arguments or checking in
+credentials or other configuration details to source control.  This is typically accomplished
+using environment variables.
+
+When using `machine-as-script`, as an alternative to CLI opts, you can specify input values
+using environment variables:
+
+```sh
+$ ___a=4 ___b=5 node ./add-numbers.js
+# Got result: 9
+```
+
+Environment variables work exactly like CLI opts, with the same escaping rules for specifying JSON arrays and dictionaries.
+
+#### Setting a namespace
+
+It's usually a good idea to namespace the environment variables specific to your application.
+Especially since many inputs have fairly common names (_as they should!_), it's helpful to use a prefix to avoid conflicts with env variables used by other processes.
+
+The default namespace is 3 underscores (`___`).  In other words, if your machine has an input `foo`, then you could configure that input using the environment variable named `___foo`.
+
+To customize the namespace for your script, just specify an `envVarNamespace`:
+
+```js
+asScript({
+  machine: MPMath.add,
+  envVarNamespace: 'add_numbers__'
+}).exec({
+  success: function (sum){
+    console.log('Got result:', sum);
+  }
+});
+```
+
+Now your custom string will be the expected namespace for environment variables:
+
+```sh
+$ add_numbers__a=4 add_numbers__b=5 node ./add-numbers.js
+# Got result: 9
+```
+
+
+
+#### A note for Windows users
+Also note that [on Windows, the names of environment variables are capitalized/case-insensitive](https://en.wikipedia.org/wiki/Environment_variable#DOS), so you may have difficulties using this approach.  I'm happy to help in the implementation of a workaround if you need this and have any ideas for how to do it (hit me up [on Twitter](http://twitter.com/mikermcneil)).
+
+
+## Configuring non-string values
+
+So it's really easy to see how string input values can be configured using CLI opts, arguments, or environment variables.  But more often than not, when configuring a script, you need to specify an input value that _isn't_ a string-- things like arrays, dictionaries, booleans, and numbers.
+
+This module lets you configure _any_ input value-- even lamdas.  Internally, it uses the [`parseHuman()` method from `rttc`](https://github.com/node-machine/rttc#parsehumanstringfromhuman-typeschemaundefined-unsafemodefalse).  For a more detailed look at the exact rules, check out the README in the rttc repo.  Below, we look at one example for each of the major use cases you're likely to run into.
+
+#### Numeric inputs
+
+```sh
+$ node ./add-numbers.js --a='4' --b='5'
+```
+
+#### Boolean inputs
+
+```sh
+$ node ./divide-numbers.js --a='9' --b='5' --useFloatingPoint='false'
+```
+
+#### Lamda (`->`) inputs
+
+```sh
+$ node ./each.js --array='[]' --iteratee='function (thing){ return thing.foo; }'
+```
+
+#### Dictionary (`{}`) and array (`[]`) inputs
+
+If an input is expecting a dictionary or array (i.e. its example is a dictionary or array), then its value should be specified as JSON.
+
+```sh
+$ node ./count-keys.js --someDictionary='{"this": {"must": ["be","JSON","encoded"]}}'
+```
+
+```sh
+$ node ./count-items.js --someArray='["this","must","be","JSON","encoded","too"]'
+```
+
+#### JSON (`*`) inputs
+
+If an input is expecting generic JSON (i.e. its example is `'*'`), then its value should be specified as JSON-- even if that value is a simple string, number, or boolean.
+
+```sh
+$ node ./is-null.js --value='{w: true, x: null, y: "some string", z: 34}'
+```
+
+```sh
+$ node ./is-null.js --value='["should be json encoded", 4, null]'
+```
+
+```sh
+$ node ./is-null.js --value='"even if it is a string"'
+```
+
+```sh
+$ node ./is-null.js --value='22353'
+```
+
+```sh
+$ node ./is-null.js --value='true'
+```
+
+```sh
+$ node ./is-null.js --value='null'
+```
+
+
+#### Mutable reference (`===`) inputs
+
+Mutable reference inputs works just like JSON (`*`) inputs.  In other words, it isn't possible to explicitly specify `undefined` from the command-line (other than by simple omission.)
+
+To learn more about rttc types, check out the [rttc README on GitHub](https://github.com/node-machine/rttc).
+
+## Misc
+
+#### Escaping your input values
+
+The rules for escaping env vars, CLI opts, and CLI arguments can vary across operating systems.  However, a good reference point is the [escape machine in mp-process](http://node-machine.org/machinepack-process/escape).  That's what the `machinepack` command-line tool uses internally for creating code samples after a machine is run using `mp exec`.
+
+#### Precedence
+
+It's always best to keep things simple.  In keeping with that spirit, you should never _intentionally_ use both environment variables AND CLI opts/args to configure your script. But weird things are unavoidable, and when debugging, it's helpful to know more about the tools you use in case something jumps out.
+
+Starting from the highest precedence, here is a list of how this module prioritizes your input configurations:
+
+1. CLI arguments (`./my-script.js bar`)
+2. Environment variables (`foo=bar ./my-script.js`)
+3. CLI opts (`./my-script.js --foo='bar'`)
+
+
+In other words, if you specify the same input as a CLI argument AND as an environment variable or CLI opt, the CLI argument will always "win".  And if you specify the same input as an environment variable and CLI opt, the environment variable will always win.
+
+
 ## License
 
 MIT © Mike McNeil

New alerts

Environment variable access

Supply chain risk

Package accesses environment variables, which may be a sign of credential stuffing or data theft.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

14142

increased by100.68%

Lines of code

174

increased by18.37%

Number of lines in readme file

213

increased by227.69%

Worsened metrics

Dependency count

6

increased by20%

Number of low supply chain risk alerts

2

increased by100%

Dependency changes

• + Addedrttc@^8.1.7

• Updatedmachine@^11.0.3