Zield

CLI utility for my scripts

Contents

• Install
• API
  • zield
    • .setup(fn)
    • .task([name,] [description,] fn)
  • Program Implementation
    • p.argv(input)
    • p.flags(input)
    • p.use([...fnHandler])
    • p.run([...fnHandler])
  • Process Handler
    • proc.<method|property>
      • proc['--']
      • proc.argv
      • proc.get(flag)
      • proc.log(input)
      • proc.fatal(input)
      • proc.stdout
      • proc.stderr
    • next()
  • Argv Instance
    • .describe(input)
  • Flag Instance
    • .as([...aliases])
    • .string(value)
    • .number(value)
    • .boolean(value)
    • .describe(input)

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