zield

CLI utility for my scripts

Usage no npm install needed!

<script type="module">
  import zield from 'https://cdn.skypack.dev/zield';
</script>

README

Zield

Travis CI node npm PRs

CLI utility for my scripts

Contents

Install

  • Via NPM
$ npm install zield
  • Via Yarn
$ yarn add zield

API

zield

Create a file: (e.g) cli.js

#!/usr/bin/env node
const zield = require('zield');

zield.setup(p => {
    // Setup global flags
    p.flags('--env').as('-e').string('development').describe('Set [NODE_ENV] value');
    p.flags('--verbose').as('-v').describe('Verbose the output console');
});

// Add default task
zield.task(p => {
    p.run(proc => {
        console.log('running default task...');
        console.log('--verbose: %s', proc.get('--verbose'));
        console.log('--env: %s', proc.get('--env'));
    });
});

// Add task
zield.task('build', 'Build app', p => {
    p.argv('[source]').describe('Source directory');
    p.flags('--out-dir').as('-D').string('dist').describe('Set the output directory');
    p.run(proc => {
        console.log('running build task...');
        console.log('argv: %O', proc.argv);
        console.log('flags: %O', proc.get(['--out-dir', '--env']));
    });
});

Running Task

$ node cli.js --verbose --env test -- --foo --bar baz
running default task
...

$ node cli.js build src --env production --out-dir release --verbose
running build task
...

Help message

By default it will show the help messages if default task is not override.

$ node cli.js --help
...

$ node cli.js build --help
...

.setup(fn)

Setup global flags.

  • Types:
    • .setup(fn: Function)
  • Params:
    • fn: <Function> (required) - A function with p (program) object.
  • Returns: void
  • Example:
    zield.setup(p => {
        p.flags('--env').as('-e').string('development').describe('Set [NODE_ENV] value');
        p.flags('--verbose').as('-V').describe('Verbose the output console');
    });
    

.task([name,] [description,] fn)

Add a new command task.

  • Types:
    • .task(name: string, description: string, fn: Function)
    • .task(name: string, fn: Function)
    • .task(fn: Function)
  • Params:
    • name: <string> (optional) - The task name.
    • description: <string> (optional) - Task description will show in CLI.
    • fn: <Function> (required) - A function with p (program) object to handle the task.
  • Returns: void
  • Example:
    zield.task(p => {
        // Task without name and description [default]
    });
    zield.task('foo-task', p => {
        // Task without description
    });
    zield.task('bar-task', 'Task description', p => {
        // Task with name and description
    });
    

Program Implementation

Define argv and flags attribute.

p.argv(input)

  • Types:
    • p.argv(input: string)
  • Params:
    • input: <string> (required)
  • Returns: <ArgvAttribute> instance.

p.flags(input)

  • Types:
    • p.flags(input: string)
  • Params:
    • input: <string> (required)
  • Returns: <FlagAttribute> instance.

p.use([...fnHandler])

  • Types:
    • p.use(...fnHandler: Function[])
  • Params:
    • ...fnHandler: <Function[]> (required) - Functions process handler.

p.run([...fnHandler])

  • Types:
    • p.run(...fnHandler: Function[])
  • Params:
    • ...fnHandler: <Function[]> (required) - Functions process handler.

Process Handler

p.use((proc, next) => { /* ... */ });
p.run((proc, next) => { /* ... */ });

proc.<method|property>

proc['--']
  • Property:
    • Value: <string[]> - All arguments after the end.
proc.argv
  • Property:
    • Value: <string[]> - All input arguments.
proc.get(flag)
  • Types:
    • proc.get(flag: string | string[])
  • Params:
    • flag: <string | string[]> (required) - Get a value of flag.
  • Returns: <any | any[]>
  • Example:
    p.run(proc => {
        console.log(proc.get('--verbose'));
        // Get multiple values
        const [outDir, isProduction, isVerbose] = proc.get(['--out-dir', '--production', '--verbose']);
        console.log('outDir: %s', outDir);
        console.log('isProduction: %o', isProduction);
        console.log('isVerbose: %o', isVerbose);
    });
    
proc.log(input)
  • Types:
    • proc.log(str: string | Buffer, ...input: any[])
  • Params:
    • str: <string | Error | Buffer> (required) - Get value of flag.
    • input: <any[]> (optional) - Get value of flag.
  • Returns: void
  • Example:
    p.run(proc => {
        proc.log('%s', '🍰');
    });
    
    
proc.fatal(input)
  • Types:
    • proc.fatal(str: string | Error | Buffer, ...input: any[])
  • Params:
    • str: <string | Error | Buffer> (required) - Get a value of flag.
    • input: <any[]> (optional) - Get a value of flag.
  • Returns: void
  • Example:
    p.run(proc => {
        proc.fatal(new Error('💀'));
    });
    
proc.stdout
proc.stderr
  • Type: NodeJS.WritableStream.
  • Example:
    const cp = require('child_process');
    
    p.run(proc => {
        const docker = cp.spawn('docker', ['logs', '-f', 'nginx'], {stdio: 'pipe'});
        docker.stdout.pipe(proc.stdout);
        docker.stderr.pipe(proc.stderr);
    });
    

next()

  • Returns: void
  • Example:
    function runProcess(name, ms) {
        const ms = (min = 1000, max = 5000) => Math.floor(Math.random() * ((max + 1) - min) + min);
        return (proc, next) => {
            console.log('[start] %s', name);
            setTimeout(() => {
                console.log('[end]   %s', name);
                next();
            }, ms() /* 1000..5000 */ );
        };
    }
    p.use((proc, next) => {
       console.log('process start');
       next();
    });
    p.use(runProcess('process - 1'));
    p.use(runProcess('process - 2'));
    p.use(runProcess('process - 3'), runProcess('process - 4'));
    p.run((proc, next) => {
       console.log('process done');
    });
    

Argv Instance

p.argv('[source]').describe('...');

.describe(input)

  • Params:
    • input: <string> (required) - Set arguments description.
  • Returns: <ArgvAttribute> instance.

Flag Instance

p.flags('--out-dir').as('-D').string('path/to/dist').describe('...');
p.flags('--production').as('-p').boolean().describe('...');
p.flags('--concurrency').number(4).describe('...');

.as([...aliases])

  • Params:
    • aliases: <string | string[]> (required) - An aliases of flag.
  • Returns: <FlagAttribute> instance.

.string(value)

  • Params:
    • value: <string> (optional) - Set the default value as type string.
      • Default: undefined
  • Returns: <FlagAttribute> instance.

.number(value)

  • Params:
    • value: <number> (optional) - Set the default value as type number.
      • Default: undefined
  • Returns: <FlagAttribute> instance.

.boolean(value)

  • Params:
    • value: <boolean> (optional) - Set the default value as type boolean.
      • Default: false
  • Returns: <FlagAttribute> instance.

.describe(input)

  • Params:
    • input: <string> (required) - Set flag description.
  • Returns: <FlagAttribute> instance.

License

MIT © Guntur Poetra