@abdfnx/hac_k
    TypeScript icon, indicating that this package has built-in type declarations

    1.0.2 • Public • Published

    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.


    Install

    npm i @abdfnx/hac_k

    DownloadsWeekly Downloads

    18

    Version

    1.0.2

    License

    MIT

    Unpacked Size

    19.7 kB

    Total Files

    5

    Last publish

    Collaborators

    • avatar