index.d.ts 7.7 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315
  1. import {PackageJson} from 'type-fest';
  2. declare namespace meow {
  3. type FlagType = 'string' | 'boolean' | 'number';
  4. /**
  5. Callback function to determine if a flag is required during runtime.
  6. @param flags - Contains the flags converted to camel-case excluding aliases.
  7. @param input - Contains the non-flag arguments.
  8. @returns True if the flag is required, otherwise false.
  9. */
  10. type IsRequiredPredicate = (flags: Readonly<AnyFlags>, input: readonly string[]) => boolean;
  11. interface Flag<Type extends FlagType, Default> {
  12. readonly type?: Type;
  13. readonly alias?: string;
  14. readonly default?: Default;
  15. readonly isRequired?: boolean | IsRequiredPredicate;
  16. readonly isMultiple?: boolean;
  17. }
  18. type StringFlag = Flag<'string', string>;
  19. type BooleanFlag = Flag<'boolean', boolean>;
  20. type NumberFlag = Flag<'number', number>;
  21. type AnyFlag = StringFlag | BooleanFlag | NumberFlag;
  22. type AnyFlags = Record<string, AnyFlag>;
  23. interface Options<Flags extends AnyFlags> {
  24. /**
  25. Define argument flags.
  26. The key is the flag name in camel-case and the value is an object with any of:
  27. - `type`: Type of value. (Possible values: `string` `boolean` `number`)
  28. - `alias`: Usually used to define a short flag alias.
  29. - `default`: Default value when the flag is not specified.
  30. - `isRequired`: Determine if the flag is required.
  31. 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.
  32. - `isMultiple`: Indicates a flag can be set multiple times. Values are turned into an array. (Default: false)
  33. 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.
  34. Note that flags are always defined using a camel-case key (`myKey`), but will match arguments in kebab-case (`--my-key`).
  35. @example
  36. ```
  37. flags: {
  38. unicorn: {
  39. type: 'string',
  40. alias: 'u',
  41. default: ['rainbow', 'cat'],
  42. isMultiple: true,
  43. isRequired: (flags, input) => {
  44. if (flags.otherFlag) {
  45. return true;
  46. }
  47. return false;
  48. }
  49. }
  50. }
  51. ```
  52. */
  53. readonly flags?: Flags;
  54. /**
  55. Description to show above the help text. Default: The package.json `"description"` property.
  56. Set it to `false` to disable it altogether.
  57. */
  58. readonly description?: string | false;
  59. /**
  60. The help text you want shown.
  61. 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.
  62. The description will be shown above your help text automatically.
  63. Set it to `false` to disable it altogether.
  64. */
  65. readonly help?: string | false;
  66. /**
  67. Set a custom version output. Default: The package.json `"version"` property.
  68. Set it to `false` to disable it altogether.
  69. */
  70. readonly version?: string | false;
  71. /**
  72. 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.
  73. This option is only considered when there is only one argument in `process.argv`.
  74. */
  75. readonly autoHelp?: boolean;
  76. /**
  77. 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.
  78. This option is only considered when there is only one argument in `process.argv`.
  79. */
  80. readonly autoVersion?: boolean;
  81. /**
  82. `package.json` as an `Object`. Default: Closest `package.json` upwards.
  83. _You most likely don't need this option._
  84. */
  85. readonly pkg?: Record<string, unknown>;
  86. /**
  87. Custom arguments object.
  88. @default process.argv.slice(2)
  89. */
  90. readonly argv?: readonly string[];
  91. /**
  92. Infer the argument type.
  93. By default, the argument `5` in `$ foo 5` becomes a string. Enabling this would infer it as a number.
  94. @default false
  95. */
  96. readonly inferType?: boolean;
  97. /**
  98. Value of `boolean` flags not defined in `argv`.
  99. 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`.
  100. _Note: If used in conjunction with `isMultiple`, the default flag value is set to `[]`._
  101. __Caution: Explicitly specifying `undefined` for `booleanDefault` has different meaning from omitting key itself.__
  102. @example
  103. ```
  104. import meow = require('meow');
  105. const cli = meow(`
  106. Usage
  107. $ foo
  108. Options
  109. --rainbow, -r Include a rainbow
  110. --unicorn, -u Include a unicorn
  111. --no-sparkles Exclude sparkles
  112. Examples
  113. $ foo
  114. 🌈 unicorns✨🌈
  115. `, {
  116. booleanDefault: undefined,
  117. flags: {
  118. rainbow: {
  119. type: 'boolean',
  120. default: true,
  121. alias: 'r'
  122. },
  123. unicorn: {
  124. type: 'boolean',
  125. default: false,
  126. alias: 'u'
  127. },
  128. cake: {
  129. type: 'boolean',
  130. alias: 'c'
  131. },
  132. sparkles: {
  133. type: 'boolean',
  134. default: true
  135. }
  136. }
  137. });
  138. //{
  139. // flags: {
  140. // rainbow: true,
  141. // unicorn: false,
  142. // sparkles: true
  143. // },
  144. // unnormalizedFlags: {
  145. // rainbow: true,
  146. // r: true,
  147. // unicorn: false,
  148. // u: false,
  149. // sparkles: true
  150. // },
  151. // …
  152. //}
  153. ```
  154. */
  155. readonly booleanDefault?: boolean | null | undefined;
  156. /**
  157. 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.
  158. @default true
  159. */
  160. readonly hardRejection?: boolean;
  161. /**
  162. Whether to allow unknown flags or not.
  163. @default true
  164. */
  165. readonly allowUnknownFlags?: boolean;
  166. }
  167. type TypedFlag<Flag extends AnyFlag> =
  168. Flag extends {type: 'number'}
  169. ? number
  170. : Flag extends {type: 'string'}
  171. ? string
  172. : Flag extends {type: 'boolean'}
  173. ? boolean
  174. : unknown;
  175. type PossiblyOptionalFlag<Flag extends AnyFlag, FlagType> =
  176. Flag extends {isRequired: true}
  177. ? FlagType
  178. : Flag extends {default: any}
  179. ? FlagType
  180. : FlagType | undefined;
  181. type TypedFlags<Flags extends AnyFlags> = {
  182. [F in keyof Flags]: Flags[F] extends {isMultiple: true}
  183. ? PossiblyOptionalFlag<Flags[F], Array<TypedFlag<Flags[F]>>>
  184. : PossiblyOptionalFlag<Flags[F], TypedFlag<Flags[F]>>
  185. };
  186. interface Result<Flags extends AnyFlags> {
  187. /**
  188. Non-flag arguments.
  189. */
  190. input: string[];
  191. /**
  192. Flags converted to camelCase excluding aliases.
  193. */
  194. flags: TypedFlags<Flags> & Record<string, unknown>;
  195. /**
  196. Flags converted camelCase including aliases.
  197. */
  198. unnormalizedFlags: TypedFlags<Flags> & Record<string, unknown>;
  199. /**
  200. The `package.json` object.
  201. */
  202. pkg: PackageJson;
  203. /**
  204. The help text used with `--help`.
  205. */
  206. help: string;
  207. /**
  208. Show the help text and exit with code.
  209. @param exitCode - The exit code to use. Default: `2`.
  210. */
  211. showHelp: (exitCode?: number) => void;
  212. /**
  213. Show the version text and exit.
  214. */
  215. showVersion: () => void;
  216. }
  217. }
  218. /**
  219. @param helpMessage - Shortcut for the `help` option.
  220. @example
  221. ```
  222. #!/usr/bin/env node
  223. 'use strict';
  224. import meow = require('meow');
  225. import foo = require('.');
  226. const cli = meow(`
  227. Usage
  228. $ foo <input>
  229. Options
  230. --rainbow, -r Include a rainbow
  231. Examples
  232. $ foo unicorns --rainbow
  233. 🌈 unicorns 🌈
  234. `, {
  235. flags: {
  236. rainbow: {
  237. type: 'boolean',
  238. alias: 'r'
  239. }
  240. }
  241. });
  242. //{
  243. // input: ['unicorns'],
  244. // flags: {rainbow: true},
  245. // ...
  246. //}
  247. foo(cli.input[0], cli.flags);
  248. ```
  249. */
  250. declare function meow<Flags extends meow.AnyFlags>(helpMessage: string, options?: meow.Options<Flags>): meow.Result<Flags>;
  251. declare function meow<Flags extends meow.AnyFlags>(options?: meow.Options<Flags>): meow.Result<Flags>;
  252. export = meow;