Add choices option

index.d.ts

@@ -15,13 +15,14 @@ Callback function to determine if a flag is required during runtime.
 */
 export type IsRequiredPredicate = (flags: Readonly<AnyFlags>, input: readonly string[]) => boolean;
 
-export type Flag<Type extends FlagType, Default, IsMultiple = false> = {
-	readonly type?: Type;
+export type Flag<PrimitiveType extends FlagType, Type, IsMultiple = false> = {
+	readonly type?: PrimitiveType;
 	readonly shortFlag?: string;
-	readonly default?: Default;
+	readonly default?: Type;
 	readonly isRequired?: boolean | IsRequiredPredicate;
 	readonly isMultiple?: IsMultiple;
 	readonly aliases?: string[];
+	readonly choices?: Type extends unknown[] ? Type : Type[];
 };
 
 type StringFlag = Flag<'string', string> | Flag<'string', string[], true>;
@@ -49,6 +50,7 @@ export type Options<Flags extends AnyFlags> = {
 	- `isMultiple`: Indicates a flag can be set multiple times. Values are turned into an array. (Default: false)
 		Multiple values are provided by specifying the flag multiple times, for example, `$ foo -u rainbow -u cat`. Space- or comma-separated values are *not* supported.
 	- `aliases`: Other names for the flag.
+	- `choices`: Limit valid values to a predefined set of choices.
 
 	Note that flags are always defined using a camel-case key (`myKey`), but will match arguments in kebab-case (`--my-key`).
 
@@ -60,6 +62,7 @@ export type Options<Flags extends AnyFlags> = {
 			shortFlag: 'u',
 			default: ['rainbow', 'cat'],
 			isMultiple: true,
+			choices: ['rainbow', 'cat', 'unicorn'],
 			isRequired: (flags, input) => {
 				if (flags.otherFlag) {
 					return true;

index.js

@@ -45,22 +45,106 @@ const getMissingRequiredFlags = (flags, receivedFlags, input) => {
 	return missingRequiredFlags;
 };
 
+const decamelizeFlagKey = flagKey => `--${decamelize(flagKey, {separator: '-'})}`;
+
 const reportMissingRequiredFlags = missingRequiredFlags => {
 	console.error(`Missing required flag${missingRequiredFlags.length > 1 ? 's' : ''}`);
 	for (const flag of missingRequiredFlags) {
-		console.error(`\t--${decamelize(flag.key, {separator: '-'})}${flag.shortFlag ? `, -${flag.shortFlag}` : ''}`);
+		console.error(`\t${decamelizeFlagKey(flag.key)}${flag.shortFlag ? `, -${flag.shortFlag}` : ''}`);
+	}
+};
+
+const joinFlagKeys = (flagKeys, prefix = '--') => `\`${prefix}${flagKeys.join(`\`, \`${prefix}`)}\``;
+
+const validateOptions = options => {
+	const invalidOptionFilters = {
+		flags: {
+			flagsWithDashes: {
+				filter: ([flagKey]) => flagKey.includes('-') && flagKey !== '--',
+				message: flagKeys => `Flag keys may not contain '-'. Invalid flags: ${joinFlagKeys(flagKeys, '')}`,
+			},
+			flagsWithAlias: {
+				filter: ([, flag]) => flag.alias !== undefined,
+				message: flagKeys => `The option \`alias\` has been renamed to \`shortFlag\`. The following flags need to be updated: ${joinFlagKeys(flagKeys)}`,
+			},
+			flagsWithNonArrayChoices: {
+				filter: ([, flag]) => flag.choices !== undefined && !Array.isArray(flag.choices),
+				message: flagKeys => `The option \`choices\` must be an array. Invalid flags: ${joinFlagKeys(flagKeys)}`,
+			},
+			flagsWithChoicesOfDifferentTypes: {
+				filter: ([, flag]) => flag.type && Array.isArray(flag.choices) && flag.choices.some(choice => typeof choice !== flag.type),
+				message(flagKeys) {
+					const flagKeysAndTypes = flagKeys.map(flagKey => `(\`${decamelizeFlagKey(flagKey)}\`, type: '${options.flags[flagKey].type}')`);
+					return `Each value of the option \`choices\` must be of the same type as its flag. Invalid flags: ${flagKeysAndTypes.join(', ')}`;
+				},
+			},
+		},
+	};
+
+	const errorMessages = [];
+
+	for (const [optionKey, filters] of Object.entries(invalidOptionFilters)) {
+		const optionEntries = Object.entries(options[optionKey]);
+
+		for (const {filter, message} of Object.values(filters)) {
+			const invalidOptions = optionEntries.filter(option => filter(option));
+			const invalidOptionKeys = invalidOptions.map(([key]) => key);
+
+			if (invalidOptions.length > 0) {
+				errorMessages.push(message(invalidOptionKeys));
+			}
+		}
+	}
+
+	if (errorMessages.length > 0) {
+		throw new Error(errorMessages.join('\n'));
 	}
 };
 
-const validateOptions = ({flags}) => {
-	const invalidFlags = Object.keys(flags).filter(flagKey => flagKey.includes('-') && flagKey !== '--');
-	if (invalidFlags.length > 0) {
-		throw new Error(`Flag keys may not contain '-': ${invalidFlags.join(', ')}`);
+const validateChoicesByFlag = (flagKey, flagValue, receivedInput) => {
+	const {choices, isRequired} = flagValue;
+
+	if (!choices) {
+		return;
+	}
+
+	const valueMustBeOneOf = `Value must be one of: [\`${choices.join('`, `')}\`]`;
+
+	if (!receivedInput) {
+		if (isRequired) {
+			return `Flag \`${decamelizeFlagKey(flagKey)}\` has no value. ${valueMustBeOneOf}`;
+		}
+
+		return;
+	}
+
+	if (Array.isArray(receivedInput)) {
+		const unknownValues = receivedInput.filter(index => !choices.includes(index));
+
+		if (unknownValues.length > 0) {
+			const valuesText = unknownValues.length > 1 ? 'values' : 'value';
+
+			return `Unknown ${valuesText} for flag \`${decamelizeFlagKey(flagKey)}\`: \`${unknownValues.join('`, `')}\`. ${valueMustBeOneOf}`;
+		}
+	} else if (!choices.includes(receivedInput)) {
+		return `Unknown value for flag \`${decamelizeFlagKey(flagKey)}\`: \`${receivedInput}\`. ${valueMustBeOneOf}`;
+	}
+};
+
+const validateChoices = (flags, receivedFlags) => {
+	const errors = [];
+
+	for (const [flagKey, flagValue] of Object.entries(flags)) {
+		const receivedInput = receivedFlags[flagKey];
+		const errorMessage = validateChoicesByFlag(flagKey, flagValue, receivedInput);
+
+		if (errorMessage) {
+			errors.push(errorMessage);
+		}
 	}
 
-	const flagsWithAlias = Object.keys(flags).filter(flagKey => flags[flagKey].alias !== undefined);
-	if (flagsWithAlias.length > 0) {
-		throw new Error(`The option \`alias\` has been renamed to \`shortFlag\`. The following flags need to be updated: \`${flagsWithAlias.join('`, `')}\``);
+	if (errors.length > 0) {
+		throw new Error(`${errors.join('\n')}`);
 	}
 };
 
@@ -242,6 +326,7 @@ const meow = (helpText, options = {}) => {
 	const unnormalizedFlags = {...flags};
 
 	validateFlags(flags, options);
+	validateChoices(options.flags, flags);
 
 	for (const flagValue of Object.values(options.flags)) {
 		if (Array.isArray(flagValue.aliases)) {

index.test-d.ts

@@ -56,6 +56,7 @@ const result = meow('Help text', {
 		'foo-bar': {type: 'number', aliases: ['foobar', 'fooBar']},
 		bar: {type: 'string', default: ''},
 		abc: {type: 'string', isMultiple: true},
+		baz: {type: 'string', choices: ['rainbow', 'cat', 'unicorn']},
 	},
 });
 
@@ -67,13 +68,15 @@ expectType<boolean | undefined>(result.flags.foo);
 expectType<number | undefined>(result.flags.fooBar);
 expectType<string>(result.flags.bar);
 expectType<string[] | undefined>(result.flags.abc);
+expectType<string | undefined>(result.flags.baz);
 expectType<boolean | undefined>(result.unnormalizedFlags.foo);
 expectType<unknown>(result.unnormalizedFlags.f);
 expectType<number | undefined>(result.unnormalizedFlags['foo-bar']);
 expectType<unknown>(result.unnormalizedFlags.foobar);
 expectType<unknown>(result.unnormalizedFlags.fooBar);
 expectType<string>(result.unnormalizedFlags.bar);
 expectType<string[] | undefined>(result.unnormalizedFlags.abc);
+expectType<string | undefined>(result.unnormalizedFlags.baz);
 
 result.showHelp();
 result.showHelp(1);
@@ -106,3 +109,22 @@ expectAssignable<AnyFlag>({type: 'boolean', isMultiple: true, default: [false]})
 expectError<AnyFlag>({type: 'string', isMultiple: true, default: 'cat'});
 expectError<AnyFlag>({type: 'number', isMultiple: true, default: 42});
 expectError<AnyFlag>({type: 'boolean', isMultiple: true, default: false});
+
+expectAssignable<AnyFlag>({type: 'string', choices: ['cat', 'unicorn']});
+expectAssignable<AnyFlag>({type: 'number', choices: [1, 2]});
+expectAssignable<AnyFlag>({type: 'boolean', choices: [true, false]});
+expectAssignable<AnyFlag>({type: 'string', isMultiple: true, choices: ['cat']});
+expectAssignable<AnyFlag>({type: 'string', isMultiple: false, choices: ['cat']});
+
+expectError<AnyFlag>({type: 'string', choices: 'cat'});
+expectError<AnyFlag>({type: 'number', choices: 1});
+expectError<AnyFlag>({type: 'boolean', choices: true});
+
+expectError<AnyFlag>({type: 'string', choices: [1]});
+expectError<AnyFlag>({type: 'number', choices: ['cat']});
+expectError<AnyFlag>({type: 'boolean', choices: ['cat']});
+
+expectAssignable<AnyFlag>({choices: ['cat']});
+expectAssignable<AnyFlag>({choices: [1]});
+expectAssignable<AnyFlag>({choices: [true]});
+expectError<AnyFlag>({choices: ['cat', 1, true]});

package.json

@@ -60,6 +60,7 @@
 	},
 	"devDependencies": {
 		"ava": "^4.3.3",
+		"common-tags": "^1.8.2",
 		"execa": "^6.1.0",
 		"indent-string": "^5.0.0",
 		"read-pkg": "^7.1.0",

readme.md

@@ -113,6 +113,7 @@ The key is the flag name in camel-case and the value is an object with any of:
 - `isMultiple`: Indicates a flag can be set multiple times. Values are turned into an array. (Default: false)
 	- Multiple values are provided by specifying the flag multiple times, for example, `$ foo -u rainbow -u cat`. Space- or comma-separated values are [currently *not* supported](https://github.com/sindresorhus/meow/issues/164).
 - `aliases`: Other names for the flag.
+- `choices`: Limit valid values to a predefined set of choices.
 
 Note that flags are always defined using a camel-case key (`myKey`), but will match arguments in kebab-case (`--my-key`).
 
@@ -125,6 +126,7 @@ flags: {
 		shortFlag: 'u',
 		default: ['rainbow', 'cat'],
 		isMultiple: true,
+		choices: ['rainbow', 'cat', 'unicorn'],
 		isRequired: (flags, input) => {
 			if (flags.otherFlag) {
 				return true;