from @abdfnx

CLI app messenger & helper

Features

• Parses arguments
• Negates flags when using the --no- prefix
• Outputs version when --version
• Outputs description and supplied help text when --help
• Sets the process title to the binary name defined in package.json

Install

$ npm i @abdfnx/hac_k

Usage

$ ./foo-app.js xbox --xbox

CommonJS

#!/usr/bin/env node
"use strict";
const hac_k = require("hac_k");
const foo = require(".");

const cli = hac_k(
    `
    Usage
      $ foo <input>

    Options
      --xbox, -x  Include a xbox

    Examples
      $ foo consoles --xbox
      🎮 consoles 🎮
`,
    {
        flags: {
            xbox: {
                type: "boolean",
                alias: "x",
            },
        },
    }
);
/*
{
    input: ['consoles'],
    flags: {xbox: true},
    ...
}
*/

foo(cli.input[0], cli.flags);

ES Modules

#!/usr/bin/env node
import { createRequire } from "module";
import foo from "./lib/index.js";

const hac_k = createRequire(import.meta.url)("hac_k");

const cli = hac_k(
    `
    Usage
      $ foo <input>

    Options
      --xbox, -x  Include a xbox

    Examples
      $ foo consoles --xbox
      🎮 consoles 🎮
`,
    {
        flags: {
            xbox: {
                type: "boolean",
                alias: "x",
            },
        },
    }
);
/*
{
    input: ['consoles'],
    flags: {xbox: true},
    ...
}
*/

foo(cli.input[0], cli.flags);

API

hac_k(helpText, options?)

hac_k(options)

Returns an object with:

• input (Array) - Non-flag arguments
• flags (Object) - Flags converted to camelCase excluding aliases
• unnormalizedFlags (Object) - Flags converted to camelCase including aliases
• pkg (Object) - The package.json object
• help (string) - The help text used with --help
• showHelp([exitCode=2]) (Function) - Show the help text and exit with exitCode
• showVersion() (Function) - Show the version text and exit

helpText

Type: string

Shortcut for the help option.

options

Type: object

flags

Type: object

Define argument flags.

The key is the flag name and the value is an object with any of:

• type: Type of value. (Possible values: string boolean number)
• alias: Usually used to define a short flag alias.
• default: Default value when the flag is not specified.
• isRequired: Determine if the flag is required. (Default: false)
  • If it's only known at runtime whether the flag is required or not, you can pass a Function instead of a boolean, which based on the given flags and other non-flag arguments, should decide if the flag is required. Two arguments are passed to the function:
  • The first argument is the flags object, which contains the flags converted to camel-case excluding aliases.
  • The second argument is the input string array, which contains the non-flag arguments.
  • The function should return a boolean, true if the flag is required, otherwise false.

Example:

flags: {
    xbox_ninja_cat: {
        type: 'string',
        alias: 'xnc',
        default: ['xbox', 'ninja_cat'],
        isMultiple: true,
        isRequired: (flags, input) => {
            if (flags.otherFlag) {
                return true;
            }

            return false;
        }
    }
}

Caution: Explicitly specifying undefined for booleanDefault has different meaning from omitting key itself.

Example:

const hac_k = require("hac_k");

const cli = hac_k(
    `
    Usage
      $ foo

    Options
      --xbox, -x  Include xbox
      --ninja_cat, -nc  Include a ninja_cat

    Examples
      $ foo
      🎮 consoles 🎮
`,
    {
        booleanDefault: undefined,
        flags: {
            xbox: {
                type: "boolean",
                default: true,
                alias: "x",
            },
            ninja_cat: {
                type: "boolean",
                default: false,
                alias: "nc",
            },
            football: {
                type: "boolean",
                alias: "f",
            },
        },
    }
);
/*
{
    flags: {
        xbox: true,
        ninja_cat: true,
        footbal: true
    },
    unnormalizedFlags: {
        xbox: true,
        x: true,
        ninja_cat: true,
        nc: true,
        f: true
    },
    …
}
*/

Promises

hac_k will make unhandled rejected promises fail hard instead of the default silent fail. Meaning you don't have to manually .catch() promises used in your CLI.

---