feat: add enum array option type

Adds support for array options with enum choices:

  opt.array(['low', 'medium', 'high'])
  // --priority low --priority high → ['low', 'high']

The enum array validates that each value is in the choices list,
and provides proper type inference as T[].

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: boneskull

src/help.ts

@@ -148,8 +148,13 @@ const buildPositionalsUsage = (schema?: PositionalsSchema): string => {
  */
 const getTypeLabel = (def: OptionDef): string => {
   switch (def.type) {
-    case 'array':
-      return `${def.items}[]`;
+    case 'array': {
+      const arrayDef = def as { choices?: readonly string[]; items?: string };
+      if (arrayDef.choices) {
+        return `(${arrayDef.choices.join(' | ')})[]`;
+      }
+      return `${arrayDef.items ?? 'string'}[]`;
+    }
     case 'boolean':
       return 'boolean';
     case 'count':

src/opt.ts

@@ -13,6 +13,7 @@ import type {
   ArrayOption,
   BooleanOption,
   CountOption,
+  EnumArrayOption,
   EnumOption,
   EnumPositional,
   InferOptions,
@@ -139,15 +140,48 @@ export const opt = {
 
   /**
    * Define an array option (--flag value --flag value2).
+   *
+   * @example
+   *
+   * ```typescript
+   * // Primitive array
+   * opt.array('string'); // --file a.txt --file b.txt → ['a.txt', 'b.txt']
+   * opt.array('number'); // --port 80 --port 443 → [80, 443]
+   *
+   * // Enum array (with choices)
+   * opt.array(['low', 'medium', 'high']); // --priority low --priority high
+   * ```
    */
-  array: (
-    items: 'number' | 'string',
+  array: ((
+    itemsOrChoices: 'number' | 'string' | readonly string[],
     props: Omit<ArrayOption, 'items' | 'type'> = {},
-  ): ArrayOption => ({
-    items,
-    type: 'array',
-    ...props,
-  }),
+  ): ArrayOption | EnumArrayOption<string> => {
+    if (Array.isArray(itemsOrChoices)) {
+      // Enum array
+      return {
+        choices: itemsOrChoices,
+        type: 'array',
+        ...props,
+      } as EnumArrayOption<string>;
+    }
+    // Primitive array
+    return {
+      items: itemsOrChoices,
+      type: 'array',
+      ...props,
+    } as ArrayOption;
+  }) as {
+    // Overload for primitive arrays
+    (
+      items: 'number' | 'string',
+      props?: Omit<ArrayOption, 'items' | 'type'>,
+    ): ArrayOption;
+    // Overload for enum arrays
+    <const T extends readonly string[]>(
+      choices: T,
+      props?: Omit<EnumArrayOption<T[number]>, 'choices' | 'type'>,
+    ): EnumArrayOption<T[number]>;
+  },
 
   /**
    * Define a boolean option.

src/parser.ts

@@ -80,15 +80,30 @@ const coerceValues = (
     // Type coercion
     if (value !== undefined) {
       switch (def.type) {
-        case 'array':
-          if (def.items === 'number' && Array.isArray(value)) {
+        case 'array': {
+          const arrayDef = def as {
+            choices?: readonly string[];
+            items?: string;
+          };
+          if (arrayDef.choices && Array.isArray(value)) {
+            // Enum array - validate each value
+            for (const v of value as string[]) {
+              if (!arrayDef.choices.includes(v)) {
+                throw new Error(
+                  `Invalid value for --${name}: "${v}". Must be one of: ${arrayDef.choices.join(', ')}`,
+                );
+              }
+            }
+            result[name] = value;
+          } else if (arrayDef.items === 'number' && Array.isArray(value)) {
             result[name] = (value as (number | string)[]).map(
               (v: number | string) => (typeof v === 'string' ? Number(v) : v),
             );
           } else {
             result[name] = value;
           }
           break;
+        }
         case 'count':
           // Count options count occurrences
           result[name] = typeof value === 'number' ? value : value ? 1 : 0;

src/types.ts

@@ -23,8 +23,8 @@ import type { ThemeInput } from './theme.js';
  */
 export interface ArrayOption extends OptionBase {
   default?: number[] | string[];
-  /** Element type of the array */
-  items: 'number' | 'string';
+  /** Element type of the array (for primitive arrays) */
+  items?: 'number' | 'string';
   type: 'array';
 }
 
@@ -189,6 +189,16 @@ export interface CreateOptions {
   version?: string;
 }
 
+/**
+ * Enum array option definition (--flag a --flag b with limited choices).
+ */
+export interface EnumArrayOption<T extends string = string> extends OptionBase {
+  /** Valid choices for array elements */
+  choices: readonly T[];
+  default?: T[];
+  type: 'array';
+}
+
 /**
  * Enum option definition with string choices.
  */
@@ -247,13 +257,15 @@ export type InferOption<T extends OptionDef> = T extends BooleanOption
           : T['default'] extends E
             ? E
             : E | undefined
-        : T extends ArrayOption
-          ? T['items'] extends 'number'
-            ? number[]
-            : string[]
-          : T extends CountOption
-            ? number
-            : never;
+        : T extends EnumArrayOption<infer E>
+          ? E[]
+          : T extends ArrayOption
+            ? T['items'] extends 'number'
+              ? number[]
+              : string[]
+            : T extends CountOption
+              ? number
+              : never;
 
 /**
  * Infer values type from an options schema.
@@ -357,6 +369,7 @@ export type OptionDef =
   | ArrayOption
   | BooleanOption
   | CountOption
+  | EnumArrayOption<string>
   | EnumOption<string>
   | NumberOption
   | StringOption;

src/validate.ts

@@ -127,6 +127,37 @@ const validateOption = (
   switch (type) {
     case 'array': {
       const items = opt['items'];
+      const choices = opt['choices'];
+
+      // Enum array (with choices)
+      if (choices !== undefined) {
+        if (!isStringArray(choices) || choices.length === 0) {
+          throw new ValidationError(
+            `${path}.choices`,
+            'must be a non-empty array of strings',
+          );
+        }
+        if (opt['default'] !== undefined) {
+          if (!isStringArray(opt['default'])) {
+            throw new ValidationError(
+              `${path}.default`,
+              'must be an array of strings',
+            );
+          }
+          for (let i = 0; i < opt['default'].length; i++) {
+            const val = opt['default'][i]!;
+            if (!choices.includes(val)) {
+              throw new ValidationError(
+                `${path}.default[${i}]`,
+                `must be one of: ${choices.join(', ')}`,
+              );
+            }
+          }
+        }
+        break;
+      }
+
+      // Primitive array (with items)
       if (typeof items !== 'string') {
         throw new ValidationError(
           `${path}.items`,

test/opt.test.ts

@@ -126,6 +126,18 @@ describe('opt builders', () => {
     });
   });
 
+  it('creates enum array options', () => {
+    const option = opt.array(['low', 'medium', 'high'], {
+      description: 'Priority levels',
+    });
+
+    expect(option, 'to satisfy', {
+      choices: ['low', 'medium', 'high'],
+      description: 'Priority levels',
+      type: 'array',
+    });
+  });
+
   it('creates count options', () => {
     const option = opt.count({ aliases: ['v'] });
 

test/parser.test.ts

@@ -128,6 +128,31 @@ describe('parseSimple', () => {
 
     expect(result.values.ports, 'to deeply equal', [80, 443]);
   });
+
+  it('parses enum array options', () => {
+    const result = parseSimple({
+      args: ['--priority', 'low', '--priority', 'high'],
+      options: {
+        priority: opt.array(['low', 'medium', 'high']),
+      },
+    });
+
+    expect(result.values.priority, 'to deeply equal', ['low', 'high']);
+  });
+
+  it('throws on invalid enum array value', () => {
+    expect(
+      () =>
+        parseSimple({
+          args: ['--priority', 'invalid'],
+          options: {
+            priority: opt.array(['low', 'medium', 'high']),
+          },
+        }),
+      'to throw',
+      /invalid/i,
+    );
+  });
 });
 
 describe('parseSimple positionals', () => {

test/validate.test.ts

@@ -271,6 +271,46 @@ describe('validateOptionsSchema', () => {
     );
   });
 
+  it('validates enum array option choices', () => {
+    expect(
+      () =>
+        validateOptionsSchema({
+          priority: opt.array(['low', 'medium', 'high']),
+        }),
+      'not to throw',
+    );
+  });
+
+  it('validates enum array option default is in choices', () => {
+    expect(
+      () =>
+        validateOptionsSchema({
+          priority: opt.array(['low', 'medium', 'high'], {
+            default: ['low', 'high'],
+          }),
+        }),
+      'not to throw',
+    );
+
+    expect(
+      () =>
+        validateOptionsSchema({
+          priority: {
+            choices: ['low', 'medium', 'high'],
+            default: ['invalid'],
+            type: 'array',
+          },
+        }),
+      'to throw a',
+      Error,
+      'satisfying',
+      {
+        message: /must be one of/,
+        path: 'options.priority.default[0]',
+      },
+    );
+  });
+
   it('validates aliases are single characters', () => {
     expect(
       () =>