[email protected]

New Features

• Add param.enumString utility to easily specify a parameter that can only have one of a list of defined values. (#14)

  Usage:

  import {startChain, param, parse} from 'parameter-reducers';
  
  const params = startChain().addParam(
    param.enumString(['-l', '--level'], 'level', [
      'info',
      'warn',
      'error',
    ] as const),
  );
  
  const {level = 'error'} = parse(params, process.argv.slice(2)).extract();
  
  if (level === 'info') {
    console.info('Some info');
  }
  if (level === 'info' || 'warn') {
    console.warn('Some warning');
  }
  console.warn('Some error');

• Add param.positionalEnumString utility to easily specify a positional parameter that can only have one of a list of defined values. (#14)

  Usage:

  import {startChain, param, parse} from 'parameter-reducers';
  
  const params = startChain().addParam(
    param.positionalEnumString('env', ['staging', 'production'] as const),
  );
  
  const {env = 'staging'} = parse(params, process.argv.slice(2)).extract();
  
  if (env === 'staging') {
    console.info('Deploying to staging');
  }
  if (env === 'production') {
    console.warn('Deploying to production');
  }

[email protected]

Breaking Changes

• Parameters are now passed in the opposite order of precedence (#5)

  This means that if you were previously doing:

  startChain()
    .addParam(param.string(['--input'], 'input'))
    .addParam(param.flag(['--input'], 'input'));

  You used to get input as a boolean flag, and now you get input as a string.

  You might previously have been using this to merge chains:

  const sharedParams = startChain()
    .addParam(param.string(['-v', '--version'], 'version'));
  
  const overriddenParams = startChain()
    .addParam(sharedParams)
    .addParam(params.flag(['-v', '--verbose'], 'verbose'));

  Where before the -v shorthand would become verbose in overriddenParams, it now continues to mean version. You can fix this by just inverting the order for overriddenParams:

  const sharedParams = startChain()
    .addParam(param.string(['-v', '--version'], 'version'));
  
  const overriddenParams = startChain()
    .addParam(params.flag(['-v', '--verbose'], 'verbose'))
    .addParam(sharedParams);

• All boolean flags create a --no-flag variant automatically (#5)

  If you use:

  startChain()
    .addParam(param.flag(['-f', '--force'], 'force'));

  It is now possible to explicitly set it to false by passing either --no-f or --no-force.

  In spite of this capability, it's still best practice to always default flags to false, as this makes them easier to understand. The only time you might want to allow this is to override a setting that is enabled via an environment variable or config file.

New Features

• The .extract() helper makes it quicker and easier to get the results (#5)

  If you don't want to customise the error messages at all, you can call parseResult.extract(). If there is an error, it will log:

  🚨 ${reason}
  

  If there is an unrecognised parameter/option it will log:

  🚨 Unrecognized option ${value}.
  

  If everything is valid, it will return the parsed results ready for destructuring.

• You can now use positional parameters (#5)

  If you have one or more parameter that you doesn't need the added clarity of a name/flag, you can use positional parameters. e.g.

  const params = startChain()
    .addParameter(param.flag(['-r', '--recursive'], 'recursive'))
    .addParameter(param.flag(['-f', '--force'], 'force'))
    .addParameter(param.positionalString('dirname'));
  
  const {
    recursive,
    force,
    dirname,
  } = parse(params, process.argv.slice(2)).extract();

  Can be used like:

  delete -rf path/to/delete
  

  Positional parameters can appear in any location relative to the named parameters, but if you have multiple positional parameters, they must be in order.

  If you need greater control, this release also adds:

  • parsedPositionalString
  • positionalStringList
  • parsedPositionalStringList

• add helpers for valid and invalid values (#4)

  Using the valid and invalid helpers provides marginally better type safety over just directly returning objects. Returning plain objects with the relevant properties is still fully supported.

[email protected]

Bug Fixes

• Return a type that supports type narrowing from the parse function (#2)

[email protected]

New Features

• Add initial code (#1)