feat: value constraints on flags (#83)

* cleanup types

* narrow on required

* fix types

* format help

* refactor tests

* docs

* additional checks

Author: eegli

.changeset/selfish-waves-worry.md

@@ -0,0 +1,5 @@
+---
+"@eegli/tinyparse": patch
+---
+
+Flag options can now be configured to be one of a set of available values!

docs/reference/help-and-meta.md

@@ -24,26 +24,26 @@ const parser = new Parser()
       shortFlag: '-V',
     },
   })
-  .option('foo', {
-    longFlag: '--foo',
-    shortFlag: '-f',
-    required: true,
-    defaultValue: '',
-    description: 'Foo option',
+  .option('verbose', {
+    longFlag: '--verbose',
+    shortFlag: '-v',
+    defaultValue: false,
+    description: 'Enable verbose mode',
   })
-  .option('bar', {
-    longFlag: '--bar',
-    defaultValue: new Date(),
-    description: 'Bar option',
+  .option('outdir', {
+    longFlag: '--out',
+    defaultValue: '',
+    required: true,
+    description: 'Output directory',
   })
-  .subcommand('baz', {
-    args: ['arg'] as const,
+  .subcommand('fetch', {
+    args: ['url'] as const,
     handler: () => {},
-    description: 'Baz command',
+    description: 'Fetch a URL and save the html',
   })
-  .subparser('fuzz', {
+  .subparser('afetch', {
     parser: new Parser().defaultHandler(),
-    description: 'Fuzz command',
+    description: 'Fetch a URL with more options',
   })
   .defaultHandler()
   .parse(['help'])
@@ -55,20 +55,20 @@ This will print the following to the console:
 ```sh
 A brief description of my-cli
 
-Usage: my-cli [command] <...flags>
+Usage: my-cli [command?] <...flags>
 
 Commands
-    baz <arg>   Baz command
-    fuzz        Fuzz command
-    help        Print this help message
+  afetch        Fetch a URL with more options
+  fetch <url>   Fetch a URL and save the html
+  help          Print this help message
 
 Required flags
-    -f, --foo [string]   Foo option
+  --out [string]            Output directory
 
 Optional flags
-    --bar [date]         Bar option
-    -h, --help           Print this help message
-    -V, --version        Print the version
+  -v, --verbose [boolean]   Enable verbose mode
+  -h, --help                Print this help message
+  -V, --version             Print the version
 ```
 
 When you set your help and metadata configuration, Tinyparse will validate the arguments to make sure there are no conflicts with existing flags or subcommands. Note that subsequent calls to `.setMeta()` will overwrite the previous configuration.

docs/reference/options.md

@@ -13,6 +13,7 @@ const parser = new Parser()
     shortFlag: '-f',
     defaultValue: 0,
     required: true,
+    oneOf: [0, 1],
     description: 'Foo option',
   })
   .defaultHandler();
@@ -21,19 +22,12 @@ const parser = new Parser()
 - `shortFlag` is the short flag _alias_ that will match the option. It must start with `-`
 - `defaultValue` is used as a fallback and to infer the _type_ of the option. To make this possible, it can only be of **four easily checkable types**: `string`, `number`, `boolean` or `Date`
 - `required` indicates whether the option is required or not. If it is required, `defaultValue` will be overwritten (or an error is thrown if it is not present in the user input, see [validation](#validation))
+- `oneOf` allows you to constrain the user input to a set of allowed values - see more below
 - `description` is used to generate the usage text
 
 If and only if the _expected value_ (i.e., `defaultValue`) for a flag is a _number_ or valid Javascript _date string_, Tinyparse will try to convert it accordingly.
 
-## Methods
-
-- **Default option values** - i.e., the values you specify when you setup the parser - can be accessed via the `options` getter method:
-
-  ```ts
-  parser.options; // { foo: 0 }
-  ```
-
-## Validation
+### Validation
 
 Parsing will fail if either a required option is not present or the expected type does not match the input value (here, a string that can be parsed to a number):
 
@@ -44,15 +38,15 @@ parser.parse([]).call();
 // Throws: "Invalid type for --foo. 'zero' is not a valid number"
 parser.parse(['--foo', 'zero']).call();
 
-// Ok - "12" can be parsed as a number
-parser.parse(['--foo', '12']).call();
+// Ok - "1" can be parsed as a number
+parser.parse(['--foo', '1']).call();
 ```
 
 Furthermore, _building_ a parser will fail if you declare the same option or a flag twice. This also holds for any unique identifier (such as a subcommand or subparser).
 
 See the docs about [error handling](reference/error-handling.md) for more.
 
-## Boolean Options
+### Boolean Options
 
 If the default value of an option is a boolean, two special rules apply:
 
@@ -77,10 +71,68 @@ const inputs: string[][] = [
   ['--foo=false'], // false
   ['--foo', 'false'], // false
 ];
+```
+
+### Methods
+
+- **Default option values** - i.e., the values you specify when you setup the parser - can be accessed via the `options` getter method:
+
+```ts
+new Parser()
+  .option('foo', {
+    longFlag: '--foo',
+    defaultValue: 'abc',
+  })
+  .defaultHandler().options; // { foo: "abc" }
+```
+
+## Constraining Option Values
+
+There are many scenarios in which you'd like the user to provide a value from a set of _allowed values_. Consider the following example with an `--output` option that lets the user choose an output format. By setting the `oneOf` property, you can constrain the user input to a set of allowed values. This only has an effect when the default value is a `string` or `number`. Tinyparse is smart enough to have TypeScript infer that `options.output` is either `'json'` or `'yaml'`:
+
+```ts
+const parser = new Parser()
+  .option('output', {
+    longFlag: '--output',
+    defaultValue: 'json',
+    oneOf: ['yaml'],
+  })
+  .defaultHandler(({ options }) => {
+    // Type: "json" | "yaml"
+    console.log(options.output);
+  });
+```
+
+With this approach, the parser will throw an error if the user provides an output format that does not equal the string literals `'json'` (the default) or `'yaml'`:
+
+```ts
+// Throws: Invalid value "csv" for option --output, expected one of: json, yaml
+parser.parse(['--output', 'csv']).call();
+```
+
+It's important to know that **parsing works differently if an option is required** and `oneOf` is set!
+
+- If the option is _optional_, the default value is considered one of the allowed values, as shown above. Type inference also accounts for this
+- If the option is _required_, the default value is guaranteed to be overwritten. Hence, only the manually provided values via `oneOf` are allowed!
+
+In the below example, `--output` can only equal `'yaml'`. TypeScript will infer the type of `options.output` to be `'yaml'`:
+
+```ts
+new Parser()
+  .option('output', {
+    longFlag: '--output',
+    defaultValue: 'json',
+    required: true,
+    oneOf: ['yaml'],
+  })
+  .defaultHandler(({ options }) => {
+    // Type: "yaml"
+    console.log(options.output);
+  })
+  .parse(['--output', 'json'])
+  .call();
 
-for (const input of inputs) {
-  await expect(parser.parse(input).call()).resolves.not.toThrow();
-}
+// Throws: Invalid value "json" for option --output, expected one of: yaml
 ```
 
 ## Good to know

src/commands.ts

@@ -7,6 +7,7 @@ import {
   DowncastFlag,
   ErrorHandler,
   FlagOptions,
+  FlagOptionsExt,
   FlagValue,
   FlagValueRecord,
   MetaOptions,
@@ -44,6 +45,19 @@ export class CommandBuilder<Options, Globals> {
     }
   };
 
+  #validateOneOf = <T>(id: string, type: T, ...options: T[]): void => {
+    const expectedType = typeof type;
+    if (expectedType !== 'string' && expectedType !== 'number') {
+      throw new Error(`OneOf can only be used with string or number`);
+    }
+    const wrongType = options.find((opt) => typeof opt !== expectedType);
+    if (wrongType) {
+      throw new Error(
+        `OneOf for option "${id}" contains invalid type ${typeof wrongType}, expected ${expectedType}`,
+      );
+    }
+  };
+
   #tryRegisterCommandToken = (command?: string) => {
     if (command) {
       this.#validateCommand(command);
@@ -61,8 +75,31 @@ export class CommandBuilder<Options, Globals> {
   /**
    * Add an option (flag)
    */
-  option<K extends string, V extends FlagValue>(key: K, opts: FlagOptions<V>) {
-    const { longFlag, shortFlag } = opts;
+  option<
+    K extends string,
+    V extends FlagValue,
+    R extends boolean,
+    O extends unknown[],
+    Choices = O[number],
+    Values = R extends true ? Choices : V | Choices,
+  >(
+    key: K,
+    opts: FlagOptionsExt<V, R, Choices>,
+  ): CommandBuilder<Options & Record<K, Values>, Globals>;
+  option<K extends string, V extends FlagValue, R extends boolean>(
+    key: K,
+    opts: FlagOptions<V, R>,
+  ): CommandBuilder<Options & Record<K, DowncastFlag<V>>, Globals>;
+  option<K extends string, V extends FlagValue, R extends boolean>(
+    key: K,
+    opts: FlagOptions<V, R>,
+  ) {
+    const { longFlag, shortFlag, oneOf, defaultValue } = opts;
+
+    if (oneOf) {
+      this.#validateOneOf(key, defaultValue, ...oneOf);
+    }
+
     this.#validateOption(key);
     this.#config.options.set(key, opts);
 

src/flags.ts

@@ -2,9 +2,33 @@ import { ValidationError } from './error';
 import { FlagOptions, FlagValue } from './types/internals';
 import Utils, { Type } from './utils';
 
+const assertIsOneOf = <T>({
+  id,
+  value,
+  options,
+  includeDefaultValue,
+  defaultValue,
+}: {
+  id: string;
+  value: T;
+  defaultValue: T;
+  includeDefaultValue?: boolean;
+  options: T[];
+}): void => {
+  if (includeDefaultValue) {
+    // Don't mutate the original array
+    options = options.concat(defaultValue);
+  }
+  if (!options.includes(value)) {
+    const available = options.sort().join(', ');
+    const err = `Invalid value "${value}" for option ${id}, expected one of: ${available}`;
+    throw new ValidationError(err);
+  }
+};
+
 export const collectFlags = (
   inputFlags: Map<string, string | null>,
-  flagOptions: Map<string, FlagOptions>,
+  flagOptions: Map<string, FlagOptions<FlagValue>>,
 ) => {
   const output = new Map<string, FlagValue>();
   for (const [key, opts] of flagOptions) {
@@ -29,11 +53,21 @@ export const collectFlags = (
     const argumentIsNull = flagArg === null;
 
     if (expectedArgType === Type.String) {
-      if (!argumentIsNull) {
-        output.set(key, flagArg as string);
-        continue;
+      if (argumentIsNull) {
+        throw new ValidationError(`${longFlag} expects an argument`);
       }
-      throw new ValidationError(`${longFlag} expects an argument`);
+      if (opts.oneOf) {
+        assertIsOneOf({
+          id: longFlag,
+          value: flagArg,
+          defaultValue: defaultValue,
+          // If the option is required, do not include the default value as a valid value
+          includeDefaultValue: !required,
+          options: opts.oneOf,
+        });
+      }
+      output.set(key, flagArg as string);
+      continue;
     }
     if (expectedArgType === Type.Boolean) {
       if (argumentIsNull) {
@@ -51,15 +85,25 @@ export const collectFlags = (
     }
     if (expectedArgType === Type.Number) {
       const asNumber = Utils.tryToNumber(flagArg as string);
-      if (asNumber) {
-        output.set(key, asNumber);
-        continue;
+      if (!asNumber) {
+        throw new ValidationError(
+          `Invalid type for ${longFlag}. '${
+            flagArg as string
+          }' is not a valid number`,
+        );
       }
-      throw new ValidationError(
-        `Invalid type for ${longFlag}. '${
-          flagArg as string
-        }' is not a valid number`,
-      );
+      if (opts.oneOf) {
+        assertIsOneOf({
+          id: longFlag,
+          value: asNumber,
+          defaultValue: defaultValue,
+
+          includeDefaultValue: !required,
+          options: opts.oneOf,
+        });
+      }
+      output.set(key, asNumber);
+      continue;
     }
     if (expectedArgType === Type.Date) {
       const asDate = Utils.tryToDate(flagArg as string);