craigmulligan / js-fire

A javascript clone of google/python-fire 🔥

js-fire

A javascript implementation of google/python-fire

js-fire is a library for automatically generating command line interfaces (CLIs) from most js objects.

• js Fire is a simple way to create a CLI in js.
• js Fire helps with exploring existing code or turning other people's code into a CLI.
• js Fire makes transitioning between Bash and js easier.

Installation

yarn add js-fire

npm install js-fire

js-fire is exposed as both an API and a CLI.

API Usage

You can call Fire on any functions and objects:

Here's an example of calling Fire on a object, you can infinitely nest objects to create subcommands.

const fire = require("js-fire");

const calculator = {
  __description__: "I am a math machine",
  double: (number) => {
    // I double things
    return 2 * number;
  },
  add: (n1 = Math.PI, n2) => {
    return n1 + n2;
  },
  misc: {
    year: () => "1999",
    brand: () => "casio",
    hello: (name) => `hello ${name}`,
  },
};

fire(calculator);

Then, from the command line, you can run:

node calculator.js double --number=15  # 30

node calculator.js misc hello hobochild  # 'hello hobochild'

Automactic --help command.

node calculator.js --help

USAGE:
	node calculator.js

DESCRIPTION:
	I am a math machine

COMMANDS:

	half  --number=<number>
	double  --number=<number>
	add  --n1=3.141592653589793  --n2=<n2>

	misc
		year
		brand
		hello  --name=<name>

Automatic --interactive mode:

For additional examples, see /examples.

CLI Usage

js-fire exposes a CLI that takes modulePath and passes it to js-fire.

USAGE:
	js-fire  --modulePath=<modulePath>

Example

So you can js-fire on most js modules.

js-fire fs -- writeFileSync --path=hello.txt --data="hiii"

You can also use interactive and help mode to explore a modules api:

js-fire fs -- -h

USAGE:
	js-fire

COMMANDS:

	appendFile <flags> --path=<path>  --data=<data>  --options=<options>  --callback=<callback>
	appendFileSync <flags> --path=<path>  --data=<data>  --options=<options>
	access <flags> --path=<path>  --mode=<mode>  --callback=<callback>
	accessSync <flags> --path=<path>  --mode=<mode>
	chown <flags> --path=<path>  --uid=<uid>  --gid=<gid>  --callback=<callback>
	chownSync <flags> --path=<path>  --uid=<uid>  --gid=<gid>
	chmod <flags> --path=<path>  --mode=<mode>  --callback=<callback>
	chmodSync <flags> --path=<path>  --mode=<mode>
	close <flags> --fd=<fd>  --callback=<callback>
	closeSync <flags> --fd=<fd>
	copyFile <flags> --src=<src>  --dest=<dest>  --flags=<flags>  --callback=<callback>
	copyFileSync <flags> --src=<src>  --dest=<dest>  --flags=<flags>
	createReadStream <flags> --path=<path>  --options=<options>
	createWriteStream <flags> --path=<path>  --options=<options>
	exists <flags> --path=<path>  --callback=<callback>
	existsSync <flags> --path=<path>
  ...

js-fire's Issues

add auto-complete

Thinking about this you actually probably just want a quick prompter for suggestions kind of like a repl rather than faffing with shell configs and alias.

Feature request: Fancy error on command not found and a none 0 exit code

Could js-fire return a none 0 exit code when it fails to find a command to run and maybe pint a fancy error and the help(--help) screen and exit with 1 so that scripts can detect failure?

const fire = require('js-fire')

const calculator = {
  misc: {
    year: () => {
      return (new Date()).getFullYear().toString();
    },
  },
}

fire(calculator)

Output this

➜  js-fire node calculator.js misc; echo "exit code $?"
Error: No command found for "misc"
    at repl:1:13
   .... stack trace
USAGE:                                                                                                                
        node calculator.js                                                                                            
                                                                                                                      
COMMANDS:                                                                                                             
                                                                                                                      
                                                                                                                      
        misc                                                                                                          
                year <flags> --new Date.getFullYear.toString=<new Date.getFullYear.toString>    
exit code 1

Instead of this

➜  js-fire node calculator.js misc; echo "exit code $?"
(node:28808) UnhandledPromiseRejectionWarning: RangeError: Maximum call stack size exceeded
    at handleObject (/home/agirorn/code-play/js-fire/node_modules/js-fire/index.js:230:44)
    at handleObject (/home/agirorn/code-play/js-fire/node_modules/js-fire/index.js:227:12)
    at handleObject (/home/agirorn/code-play/js-fire/node_modules/js-fire/index.js:227:12)
    at handleObject (/home/agirorn/code-play/js-fire/node_modules/js-fire/index.js:227:12)
    at handleObject (/home/agirorn/code-play/js-fire/node_modules/js-fire/index.js:227:12)
    at handleObject (/home/agirorn/code-play/js-fire/node_modules/js-fire/index.js:227:12)
    at handleObject (/home/agirorn/code-play/js-fire/node_modules/js-fire/index.js:227:12)
    at handleObject (/home/agirorn/code-play/js-fire/node_modules/js-fire/index.js:227:12)
    at handleObject (/home/agirorn/code-play/js-fire/node_modules/js-fire/index.js:227:12)
    at handleObject (/home/agirorn/code-play/js-fire/node_modules/js-fire/index.js:227:12)
(node:28808) UnhandledPromiseRejectionWarning: Unhandled promise rejection. This error originated either by throwing inside of an async function without a catch block, or by rejecting a promise which was not handled with .catch(). (rejection id: 1)
(node:28808) [DEP0018] DeprecationWarning: Unhandled promise rejections are deprecated. In the future, promise rejections that are not handled will terminate the Node.js process with a non-zero exit code.
exit code 0

Create similarity check for flag typos

We now have a check for subcommand typos - we should also check flag inputs and do a did you mean x flag? output with exit code 1.

Expose it as a cli

an amazing idea from Reddit from astralradish

Would be interesting if you could use expand this to allow node-fire to be used as a CLI itself, taking a file which exported a function or object as a parameter: i.e. node-fire calculator.js double --number=15 # 30

Basically a runtime equivalent without having to build an entirely new module from it.

Maybe even taking a module as a parameter:

node-fire fs-extra readDirSync /

Add flag descriptions based on inline comments

Default value as string or pointer

Currently when a default value is a string we trim it so does not matter becomes doesnotmatter in the help text.

We don't currently support pointers as default values in helpText - we should see how python-fire supports those.

Add interactive-mode

The async/await function is supported?

Use VHS for prompt tests

Looks like it could be useful for auto-generating docs + e2e tests.

Improve introspect regex

need more tests to catch edge cases on the argument matching regex pattern.

recursion on objects & classes

Should consider supporting an arbitrary nesting of objects aka subcommands.

Automatically load module.exports if nothing is explicitly passed.

Unsure if this would make things v complicated but maybe a convenient feature.

Some users are using npm linking it so Usage text should some how know this.

In some cases - https://github.com/panva/jwterminal js-fire is being used as a cli - so so its linked with an alias in this case the usage text should read <cmd> not node <cmd> I also need to check if that has any knock on effects for positional args.

add --help

Add CI