index.d.ts 3.6 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158
  1. declare namespace dargs {
  2. interface Options {
  3. /**
  4. Keys or regex of keys to exclude. Takes precedence over `includes`.
  5. */
  6. excludes?: ReadonlyArray<string | RegExp>;
  7. /**
  8. Keys or regex of keys to include.
  9. */
  10. includes?: ReadonlyArray<string | RegExp>;
  11. /**
  12. Maps keys in `input` to an aliased name. Matching keys are converted to arguments with a single dash (`-`) in front of the aliased key and the value in a separate array item. Keys are still affected by `includes` and `excludes`.
  13. */
  14. aliases?: {[key: string]: string};
  15. /**
  16. Setting this to `false` makes it return the key and value as separate array items instead of using a `=` separator in one item. This can be useful for tools that doesn't support `--foo=bar` style flags.
  17. @default true
  18. @example
  19. ```
  20. import dargs = require('dargs');
  21. console.log(dargs({foo: 'bar'}, {useEquals: false}));
  22. // [
  23. // '--foo', 'bar'
  24. // ]
  25. ```
  26. */
  27. useEquals?: boolean;
  28. /**
  29. Make a single character option key `{a: true}` become a short flag `-a` instead of `--a`.
  30. @default true
  31. @example
  32. ```
  33. import dargs = require('dargs');
  34. console.log(dargs({a: true}));
  35. //=> ['-a']
  36. console.log(dargs({a: true}, {shortFlag: false}));
  37. //=> ['--a']
  38. ```
  39. */
  40. shortFlag?: boolean;
  41. /**
  42. Exclude `false` values. Can be useful when dealing with strict argument parsers that throw on unknown arguments like `--no-foo`.
  43. @default false
  44. */
  45. ignoreFalse?: boolean;
  46. /**
  47. By default, camel-cased keys will be hyphenated. Enabling this will bypass the conversion process.
  48. @default false
  49. @example
  50. ```
  51. import dargs = require('dargs');
  52. console.log(dargs({fooBar: 'baz'}));
  53. //=> ['--foo-bar', 'baz']
  54. console.log(dargs({fooBar: 'baz'}, {allowCamelCase: true}));
  55. //=> ['--fooBar', 'baz']
  56. ```
  57. */
  58. allowCamelCase?: boolean;
  59. }
  60. }
  61. /**
  62. Reverse [`minimist`](https://github.com/substack/minimist). Convert an object of options into an array of command-line arguments.
  63. @param object - Object to convert to command-line arguments.
  64. @example
  65. ```
  66. import dargs = require('dargs');
  67. const input = {
  68. _: ['some', 'option'], // Values in '_' will be appended to the end of the generated argument list
  69. '--': ['separated', 'option'], // Values in '--' will be put at the very end of the argument list after the escape option (`--`)
  70. foo: 'bar',
  71. hello: true, // Results in only the key being used
  72. cake: false, // Prepends `no-` before the key
  73. camelCase: 5, // CamelCase is slugged to `camel-case`
  74. multiple: ['value', 'value2'], // Converted to multiple arguments
  75. pieKind: 'cherry',
  76. sad: ':('
  77. };
  78. const excludes = ['sad', /.*Kind$/]; // Excludes and includes accept regular expressions
  79. const includes = ['camelCase', 'multiple', 'sad', /^pie.+/];
  80. const aliases = {file: 'f'};
  81. console.log(dargs(input, {excludes}));
  82. // [
  83. // '--foo=bar',
  84. // '--hello',
  85. // '--no-cake',
  86. // '--camel-case=5',
  87. // '--multiple=value',
  88. // '--multiple=value2',
  89. // 'some',
  90. // 'option',
  91. // '--',
  92. // 'separated',
  93. // 'option'
  94. // ]
  95. console.log(dargs(input, {excludes, includes}));
  96. // [
  97. // '--camel-case=5',
  98. // '--multiple=value',
  99. // '--multiple=value2'
  100. // ]
  101. console.log(dargs(input, {includes}));
  102. // [
  103. // '--camel-case=5',
  104. // '--multiple=value',
  105. // '--multiple=value2',
  106. // '--pie-kind=cherry',
  107. // '--sad=:('
  108. // ]
  109. console.log(dargs({
  110. foo: 'bar',
  111. hello: true,
  112. file: 'baz'
  113. }, {aliases}));
  114. // [
  115. // '--foo=bar',
  116. // '--hello',
  117. // '-f', 'baz'
  118. // ]
  119. ```
  120. */
  121. declare function dargs(
  122. object: {
  123. '--'?: string[];
  124. _?: string[];
  125. } & {[key: string]: string | boolean | number | readonly string[]},
  126. options?: dargs.Options
  127. ): string[];
  128. export = dargs;