meow

  • Version 11.0.0
  • Published
  • 25.3 kB
  • 12 dependencies
  • MIT license

Install

npm i meow
yarn add meow
pnpm add meow

Overview

CLI app helper

Index

Functions

function meow

meow: {
<Flags extends AnyFlags>(
helpMessage: string,
options?: Options<Flags>
): Result<Flags>;
<Flags extends AnyFlags>(options?: Options<Flags>): Result<Flags>;
};
  • Parameter helpMessage

    Shortcut for the help option.

    Example 1

    #!/usr/bin/env node
    import meow from 'meow';
    import foo from './index.js';
    const cli = meow(`
    Usage
    $ foo <input>
    Options
    --rainbow, -r Include a rainbow
    Examples
    $ foo unicorns --rainbow
    ๐ŸŒˆ unicorns ๐ŸŒˆ
    `, {
    importMeta: import.meta,
    flags: {
    rainbow: {
    type: 'boolean',
    alias: 'r'
    }
    }
    });
    //{
    // input: ['unicorns'],
    // flags: {rainbow: true},
    // ...
    //}
    foo(cli.input[0], cli.flags);

Type Aliases

type AnyFlag

type AnyFlag = StringFlag | BooleanFlag | NumberFlag;

    type AnyFlags

    type AnyFlags = Record<string, AnyFlag>;

      type BooleanFlag

      type BooleanFlag = Flag<'boolean', boolean> | Flag<'boolean', boolean[], true>;

        type Flag

        type Flag<Type extends FlagType, Default, IsMultiple = false> = {
        readonly type?: Type;
        readonly alias?: string;
        readonly default?: Default;
        readonly isRequired?: boolean | IsRequiredPredicate;
        readonly isMultiple?: IsMultiple;
        };

          type FlagType

          type FlagType = 'string' | 'boolean' | 'number';

            type IsRequiredPredicate

            type IsRequiredPredicate = (
            flags: Readonly<AnyFlags>,
            input: readonly string[]
            ) => boolean;
            • Callback function to determine if a flag is required during runtime.

              Parameter flags

              Contains the flags converted to camel-case excluding aliases.

              Parameter input

              Contains the non-flag arguments.

              Returns

              True if the flag is required, otherwise false.

            type NumberFlag

            type NumberFlag = Flag<'number', number> | Flag<'number', number[], true>;

              type Options

              type Options<Flags extends AnyFlags> = {
              /**
              Pass in [`import.meta`](https://nodejs.org/dist/latest/docs/api/esm.html#esm_import_meta). This is used to find the correct package.json file.
              */
              readonly importMeta: ImportMeta;
              /**
              Define argument flags.
              The key is the flag name in camel-case 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.
              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.
              - `isMultiple`: Indicates a flag can be set multiple times. Values are turned into an array. (Default: false)
              Multiple values are provided by specifying the flag multiple times, for example, `$ foo -u rainbow -u cat`. Space- or comma-separated values are *not* supported.
              Note that flags are always defined using a camel-case key (`myKey`), but will match arguments in kebab-case (`--my-key`).
              @example
              ```
              flags: {
              unicorn: {
              type: 'string',
              alias: 'u',
              default: ['rainbow', 'cat'],
              isMultiple: true,
              isRequired: (flags, input) => {
              if (flags.otherFlag) {
              return true;
              }
              return false;
              }
              }
              }
              ```
              */
              readonly flags?: Flags;
              /**
              Description to show above the help text. Default: The package.json `"description"` property.
              Set it to `false` to disable it altogether.
              */
              readonly description?: string | false;
              /**
              The help text you want shown.
              The input is reindented and starting/ending newlines are trimmed which means you can use a [template literal](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/template_strings) without having to care about using the correct amount of indent.
              The description will be shown above your help text automatically.
              Set it to `false` to disable it altogether.
              */
              readonly help?: string | false;
              /**
              Set a custom version output. Default: The package.json `"version"` property.
              Set it to `false` to disable it altogether.
              */
              readonly version?: string | false;
              /**
              Automatically show the help text when the `--help` flag is present. Useful to set this value to `false` when a CLI manages child CLIs with their own help text.
              This option is only considered when there is only one argument in `process.argv`.
              */
              readonly autoHelp?: boolean;
              /**
              Automatically show the version text when the `--version` flag is present. Useful to set this value to `false` when a CLI manages child CLIs with their own version text.
              This option is only considered when there is only one argument in `process.argv`.
              */
              readonly autoVersion?: boolean;
              /**
              `package.json` as an `Object`. Default: Closest `package.json` upwards.
              _You most likely don't need this option._
              */
              readonly pkg?: Record<string, unknown>;
              /**
              Custom arguments object.
              @default process.argv.slice(2)
              */
              readonly argv?: readonly string[];
              /**
              Infer the argument type.
              By default, the argument `5` in `$ foo 5` becomes a string. Enabling this would infer it as a number.
              @default false
              */
              readonly inferType?: boolean;
              /**
              Value of `boolean` flags not defined in `argv`.
              If set to `undefined`, the flags not defined in `argv` will be excluded from the result. The `default` value set in `boolean` flags take precedence over `booleanDefault`.
              _Note: If used in conjunction with `isMultiple`, the default flag value is set to `[]`._
              __Caution: Explicitly specifying `undefined` for `booleanDefault` has different meaning from omitting key itself.__
              @example
              ```
              import meow from 'meow';
              const cli = meow(`
              Usage
              $ foo
              Options
              --rainbow, -r Include a rainbow
              --unicorn, -u Include a unicorn
              --no-sparkles Exclude sparkles
              Examples
              $ foo
              ๐ŸŒˆ unicornsโœจ๐ŸŒˆ
              `, {
              importMeta: import.meta,
              booleanDefault: undefined,
              flags: {
              rainbow: {
              type: 'boolean',
              default: true,
              alias: 'r'
              },
              unicorn: {
              type: 'boolean',
              default: false,
              alias: 'u'
              },
              cake: {
              type: 'boolean',
              alias: 'c'
              },
              sparkles: {
              type: 'boolean',
              default: true
              }
              }
              });
              //{
              // flags: {
              // rainbow: true,
              // unicorn: false,
              // sparkles: true
              // },
              // unnormalizedFlags: {
              // rainbow: true,
              // r: true,
              // unicorn: false,
              // u: false,
              // sparkles: true
              // },
              // โ€ฆ
              //}
              ```
              */
              // eslint-disable-next-line @typescript-eslint/ban-types
              readonly booleanDefault?: boolean | null | undefined;
              /**
              Whether to use [hard-rejection](https://github.com/sindresorhus/hard-rejection) or not. Disabling this can be useful if you need to handle `process.on('unhandledRejection')` yourself.
              @default true
              */
              readonly hardRejection?: boolean;
              /**
              Whether to allow unknown flags or not.
              @default true
              */
              readonly allowUnknownFlags?: boolean;
              };

                type PossiblyOptionalFlag

                type PossiblyOptionalFlag<Flag extends AnyFlag, FlagType> = Flag extends {
                isRequired: true;
                }
                ? FlagType
                : Flag extends { default: any }
                ? FlagType
                : FlagType | undefined;

                  type Result

                  type Result<Flags extends AnyFlags> = {
                  /**
                  Non-flag arguments.
                  */
                  input: string[];
                  /**
                  Flags converted to camelCase excluding aliases.
                  */
                  flags: CamelCasedProperties<TypedFlags<Flags>> & Record<string, unknown>;
                  /**
                  Flags converted camelCase including aliases.
                  */
                  unnormalizedFlags: TypedFlags<Flags> & Record<string, unknown>;
                  /**
                  The `package.json` object.
                  */
                  pkg: PackageJson;
                  /**
                  The help text used with `--help`.
                  */
                  help: string;
                  /**
                  Show the help text and exit with code.
                  @param exitCode - The exit code to use. Default: `2`.
                  */
                  showHelp: (exitCode?: number) => never;
                  /**
                  Show the version text and exit.
                  */
                  showVersion: () => void;
                  };

                    type StringFlag

                    type StringFlag = Flag<'string', string> | Flag<'string', string[], true>;

                      type TypedFlag

                      type TypedFlag<Flag extends AnyFlag> = Flag extends { type: 'number' }
                      ? number
                      : Flag extends { type: 'string' }
                      ? string
                      : Flag extends { type: 'boolean' }
                      ? boolean
                      : unknown;

                        type TypedFlags

                        type TypedFlags<Flags extends AnyFlags> = {
                        [F in keyof Flags]: Flags[F] extends { isMultiple: true }
                        ? PossiblyOptionalFlag<Flags[F], Array<TypedFlag<Flags[F]>>>
                        : PossiblyOptionalFlag<Flags[F], TypedFlag<Flags[F]>>;
                        };

                          Package Files (1)

                          Dependencies (12)

                          Dev Dependencies (6)

                          Peer Dependencies (0)

                          No peer dependencies.

                          Badge

                          To add a badge like this onejsDocs.io badgeto your package's README, use the codes available below.

                          You may also use Shields.io to create a custom badge linking to https://www.jsdocs.io/package/meow.

                          • Markdown
                            [![jsDocs.io](https://img.shields.io/badge/jsDocs.io-reference-blue)](https://www.jsdocs.io/package/meow)
                          • HTML
                            <a href="https://www.jsdocs.io/package/meow"><img src="https://img.shields.io/badge/jsDocs.io-reference-blue" alt="jsDocs.io"></a>