dargs

import dargs from "dargs";

const dargs = require("dargs");

import dargs from "dargs";

const options = {
  _: ['some', 'option'],          // Values in '_' will be appended to the end
  '--': ['separated', 'option'],  // Values in '--' will be put at the very end after the escape option (`--`)
  foo: 'bar',
  hello: true,                    // Results in only the key being used
  cake: false,                    // Prepends `no-` before the key
  camelCase: 5,                   // CamelCase is slugged to `camel-case`
  multiple: ['value', 'value2'],  // Converted to multiple arguments
  pieKind: 'cherry'
};

const result = dargs(options);
// [
//   '--foo=bar',
//   '--hello',
//   '--no-cake',
//   '--camel-case=5',
//   '--multiple=value',
//   '--multiple=value2',
//   '--pie-kind=cherry',
//   'some',
//   'option',
//   '--',
//   'separated',
//   'option'
// ]

/**
 * Convert an object of options into an array of command-line arguments
 * @param {Object} object - Object to convert to command-line arguments
 * @param {Options} [options] - Optional configuration options
 * @returns {string[]} Array of command-line arguments
 * @throws {TypeError} When '_' or '--' keys have non-Array values
 */
function dargs(
  object: {
    '--'?: string[];
    _?: string[];
  } & Record<string, string | boolean | number | readonly string[]>,
  options?: Options
): string[];

import dargs from "dargs";

// Basic conversion
const args = dargs({
  verbose: true,
  quiet: false,
  file: 'input.txt',
  count: 42
});
// Result: ['--verbose', '--no-quiet', '--file=input.txt', '--count=42']

// With arrays
const args2 = dargs({
  include: ['*.js', '*.ts'],
  exclude: ['node_modules']
});
// Result: ['--include=*.js', '--include=*.ts', '--exclude=node_modules']

// With special keys
const args3 = dargs({
  _: ['input.txt', 'output.txt'],
  '--': ['--verbose', '--debug'],
  force: true
});
// Result: ['--force', 'input.txt', 'output.txt', '--', '--verbose', '--debug']

interface Options {
  /** Keys or regex of keys to exclude. Takes precedence over includes. */
  excludes?: ReadonlyArray<string | RegExp>;
  
  /** Keys or regex of keys to include. */
  includes?: ReadonlyArray<string | RegExp>;
  
  /** 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 (never using equals format). Keys are still affected by includes and excludes. */
  aliases?: Record<string, string>;
  
  /** 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. @default true */
  useEquals?: boolean;
  
  /** Make a single character option key {a: true} become a short flag -a instead of --a. @default true */
  shortFlag?: boolean;
  
  /** Exclude true values. Can be useful when dealing with argument parsers that only expect negated arguments like --no-foo. @default false */
  ignoreTrue?: boolean;
  
  /** Exclude false values. Can be useful when dealing with strict argument parsers that throw on unknown arguments like --no-foo. @default false */
  ignoreFalse?: boolean;
  
  /** By default, camel-cased keys will be hyphenated. Enabling this will bypass the conversion process. @default false */
  allowCamelCase?: boolean;
}

// Exclude specific keys
const args = dargs({ foo: 'bar', secret: 'hidden', debug: true }, {
  excludes: ['secret', /.*Kind$/]
});
// Result: ['--foo=bar', '--debug']

// Include only specific keys  
const args2 = dargs({ foo: 'bar', baz: 'qux', debug: true }, {
  includes: ['foo', 'debug']
});
// Result: ['--foo=bar', '--debug']

// Use aliases for short flags
const args3 = dargs({ file: 'input.txt', verbose: true }, {
  aliases: { file: 'f', verbose: 'v' }
});
// Result: ['-f', 'input.txt', '-v']

// Disable equals separator
const args4 = dargs({ foo: 'bar', count: 5 }, {
  useEquals: false
});
// Result: ['--foo', 'bar', '--count', '5']

// Disable short flags
const args5 = dargs({ a: true, verbose: true }, {
  shortFlag: false
});
// Result: ['--a', '--verbose']

// Preserve camelCase
const args6 = dargs({ fooBar: 'baz', myVar: 123 }, {
  allowCamelCase: true
});
// Result: ['--fooBar=baz', '--myVar=123']
// (default would be: ['--foo-bar=baz', '--my-var=123'])

// Ignore boolean values
const args7 = dargs({ enabled: true, disabled: false, file: 'test' }, {
  ignoreTrue: true,
  ignoreFalse: true
});
// Result: ['--file=test']

// These will throw TypeError
try {
  dargs({ _: 'not-an-array' });
} catch (error) {
  console.log(error instanceof TypeError); // true
}

try {
  dargs({ '--': 'not-an-array' });  
} catch (error) {
  console.log(error instanceof TypeError); // true
}