@optique/core 1.4.0-dev.2670 → 1.4.0-dev.2671

package/dist/valueparser.cjs

@@ -161,15 +161,24 @@ function choice(choices, options = {}) {
 	const stringChoices = Object.freeze([...new Set(choices)]);
 	const stringOptions = options;
 	checkBooleanOption(stringOptions, "caseInsensitive");
+	const customKey = stringOptions.key;
+	if (customKey !== void 0 && typeof customKey !== "function") throw new TypeError("Expected key to be a function.");
+	if (customKey !== void 0 && stringOptions.caseInsensitive !== void 0) throw new TypeError("Cannot use key with caseInsensitive.");
 	const caseInsensitive = stringOptions.caseInsensitive ?? false;
-	const normalizedValues = caseInsensitive ? stringChoices.map((v) => v.toLowerCase()) : stringChoices;
-	if (caseInsensitive) {
+	const matchingKey = customKey ?? (caseInsensitive ? (text$1) => text$1.toLowerCase() : (text$1) => text$1);
+	function getMatchingKey(text$1) {
+		const result = matchingKey(text$1);
+		if (typeof result !== "string") throw new TypeError("Expected key to return a string.");
+		return result;
+	}
+	const matchingKeys = stringChoices.map(getMatchingKey);
+	if (caseInsensitive || customKey !== void 0) {
 		const seen = /* @__PURE__ */ new Map();
 		for (let i = 0; i < stringChoices.length; i++) {
-			const nv = normalizedValues[i];
+			const nv = matchingKeys[i];
 			const original = stringChoices[i];
 			const prev = seen.get(nv);
-			if (prev !== void 0 && prev !== original) throw new TypeError(`Ambiguous choices for case-insensitive matching: ${JSON.stringify(prev)} and ${JSON.stringify(original)} both normalize to ${JSON.stringify(nv)}.`);
+			if (prev !== void 0 && prev !== original) throw new TypeError(`Ambiguous choices for ${caseInsensitive ? "case-insensitive" : "custom key"} matching: ${JSON.stringify(prev)} and ${JSON.stringify(original)} both normalize to ${JSON.stringify(nv)}.`);
 			seen.set(nv, original);
 		}
 	}
@@ -200,8 +209,7 @@ function choice(choices, options = {}) {
 		placeholder: choices[0],
 		choices: stringChoices,
 		parse(input) {
-			const normalizedInput = caseInsensitive ? input.toLowerCase() : input;
-			const index = normalizedValues.indexOf(normalizedInput);
+			const index = matchingKeys.indexOf(getMatchingKey(input));
 			if (index < 0) return {
 				success: false,
 				error: formatStringChoiceError(input, stringChoices, stringInvalidChoice, snapshotSuggest)
@@ -215,11 +223,8 @@ function choice(choices, options = {}) {
 			return String(value);
 		},
 		suggest(prefix) {
-			const normalizedPrefix = caseInsensitive ? prefix.toLowerCase() : prefix;
-			return stringChoices.filter((value) => {
-				const normalizedValue = caseInsensitive ? value.toLowerCase() : value;
-				return normalizedValue.startsWith(normalizedPrefix);
-			}).map((value) => ({
+			const matchingPrefix = getMatchingKey(prefix);
+			return stringChoices.filter((_value, index) => matchingKeys[index].startsWith(matchingPrefix)).map((value) => ({
 				kind: "literal",
 				text: value
 			}));

package/dist/valueparser.d.cts

@@ -270,6 +270,15 @@ interface ChoiceOptionsString extends ChoiceOptionsBase {
    * @default `false`
    */
   readonly caseInsensitive?: boolean;
+  /**
+   * Maps both the input and declared choices to keys for matching.  Parsing
+   * and completion still return the declared spelling.  Cannot be combined
+   * with `caseInsensitive`; include case folding in this function instead.
+   *
+   * The function should preserve prefixes when completion is needed.
+   * @since 1.4.0
+   */
+  readonly key?: (text: string) => string;
   /**
    * Controls whether the error message for an invalid value includes a
    * "Did you mean …?" hint based on Levenshtein distance.
@@ -384,6 +393,9 @@ declare function isValueParser<M extends Mode, T>(object: unknown): object is Va
  * @throws {TypeError} If `caseInsensitive` is not a boolean.
  * @throws {TypeError} If `caseInsensitive` is `true` and multiple choices
  *         normalize to the same lowercase value.
+ * @throws {TypeError} If `key` is not a function, is combined with
+ *         `caseInsensitive`, returns a non-string key, or gives distinct
+ *         choices the same key.
  */
 declare function choice<const T extends string>(choices: readonly T[], options?: ChoiceOptionsString): ValueParser<"sync", T>;
 /**

package/dist/valueparser.d.ts

@@ -270,6 +270,15 @@ interface ChoiceOptionsString extends ChoiceOptionsBase {
    * @default `false`
    */
   readonly caseInsensitive?: boolean;
+  /**
+   * Maps both the input and declared choices to keys for matching.  Parsing
+   * and completion still return the declared spelling.  Cannot be combined
+   * with `caseInsensitive`; include case folding in this function instead.
+   *
+   * The function should preserve prefixes when completion is needed.
+   * @since 1.4.0
+   */
+  readonly key?: (text: string) => string;
   /**
    * Controls whether the error message for an invalid value includes a
    * "Did you mean …?" hint based on Levenshtein distance.
@@ -384,6 +393,9 @@ declare function isValueParser<M extends Mode, T>(object: unknown): object is Va
  * @throws {TypeError} If `caseInsensitive` is not a boolean.
  * @throws {TypeError} If `caseInsensitive` is `true` and multiple choices
  *         normalize to the same lowercase value.
+ * @throws {TypeError} If `key` is not a function, is combined with
+ *         `caseInsensitive`, returns a non-string key, or gives distinct
+ *         choices the same key.
  */
 declare function choice<const T extends string>(choices: readonly T[], options?: ChoiceOptionsString): ValueParser<"sync", T>;
 /**

package/dist/valueparser.js

@@ -161,15 +161,24 @@ function choice(choices, options = {}) {
 	const stringChoices = Object.freeze([...new Set(choices)]);
 	const stringOptions = options;
 	checkBooleanOption(stringOptions, "caseInsensitive");
+	const customKey = stringOptions.key;
+	if (customKey !== void 0 && typeof customKey !== "function") throw new TypeError("Expected key to be a function.");
+	if (customKey !== void 0 && stringOptions.caseInsensitive !== void 0) throw new TypeError("Cannot use key with caseInsensitive.");
 	const caseInsensitive = stringOptions.caseInsensitive ?? false;
-	const normalizedValues = caseInsensitive ? stringChoices.map((v) => v.toLowerCase()) : stringChoices;
-	if (caseInsensitive) {
+	const matchingKey = customKey ?? (caseInsensitive ? (text$1) => text$1.toLowerCase() : (text$1) => text$1);
+	function getMatchingKey(text$1) {
+		const result = matchingKey(text$1);
+		if (typeof result !== "string") throw new TypeError("Expected key to return a string.");
+		return result;
+	}
+	const matchingKeys = stringChoices.map(getMatchingKey);
+	if (caseInsensitive || customKey !== void 0) {
 		const seen = /* @__PURE__ */ new Map();
 		for (let i = 0; i < stringChoices.length; i++) {
-			const nv = normalizedValues[i];
+			const nv = matchingKeys[i];
 			const original = stringChoices[i];
 			const prev = seen.get(nv);
-			if (prev !== void 0 && prev !== original) throw new TypeError(`Ambiguous choices for case-insensitive matching: ${JSON.stringify(prev)} and ${JSON.stringify(original)} both normalize to ${JSON.stringify(nv)}.`);
+			if (prev !== void 0 && prev !== original) throw new TypeError(`Ambiguous choices for ${caseInsensitive ? "case-insensitive" : "custom key"} matching: ${JSON.stringify(prev)} and ${JSON.stringify(original)} both normalize to ${JSON.stringify(nv)}.`);
 			seen.set(nv, original);
 		}
 	}
@@ -200,8 +209,7 @@ function choice(choices, options = {}) {
 		placeholder: choices[0],
 		choices: stringChoices,
 		parse(input) {
-			const normalizedInput = caseInsensitive ? input.toLowerCase() : input;
-			const index = normalizedValues.indexOf(normalizedInput);
+			const index = matchingKeys.indexOf(getMatchingKey(input));
 			if (index < 0) return {
 				success: false,
 				error: formatStringChoiceError(input, stringChoices, stringInvalidChoice, snapshotSuggest)
@@ -215,11 +223,8 @@ function choice(choices, options = {}) {
 			return String(value);
 		},
 		suggest(prefix) {
-			const normalizedPrefix = caseInsensitive ? prefix.toLowerCase() : prefix;
-			return stringChoices.filter((value) => {
-				const normalizedValue = caseInsensitive ? value.toLowerCase() : value;
-				return normalizedValue.startsWith(normalizedPrefix);
-			}).map((value) => ({
+			const matchingPrefix = getMatchingKey(prefix);
+			return stringChoices.filter((_value, index) => matchingKeys[index].startsWith(matchingPrefix)).map((value) => ({
 				kind: "literal",
 				text: value
 			}));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.4.0-dev.2670",
+  "version": "1.4.0-dev.2671",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",
@@ -237,7 +237,7 @@
   },
   "sideEffects": false,
   "devDependencies": {
-    "@optique/env": "1.4.0-dev.2670+3fbd83fc",
+    "@optique/env": "1.4.0-dev.2671+ac89a35b",
     "@types/node": "^24.0.0",
     "fast-check": "^4.7.0",
     "tsdown": "^0.13.0",

package/skills/optique/SKILL.md

@@ -43,9 +43,9 @@ Core rules
  -  Use value parsers such as `integer()`, `choice()`, `biject()`, `regExp()`,
     `url()`, `origin()`, and `uuid()` instead of validating raw strings after
     parsing. Use `regExp({ flags })` for user-supplied sources, `biject()` for
-    one-to-one string-to-value choices, and `transform()` when an existing
-    value parser accepts the spelling but your app needs a different result
-    type. Use `normalizeInput()` for raw-string cleanup before validation and
+    one-to-one mappings, `transform()` for mapped results, and
+    `choice(values, { key })` for custom string matching that returns the
+    declared spelling. Use `normalizeInput()` for raw-string cleanup and
     `path()` from `@optique/run/valueparser` for file-system paths. Write a
     custom value parser only when these tools do not cover the domain.
  -  Since 1.4.0, `-p8080`/`-vp8080` accept attached values. Values consume