@optique/core 1.2.0-dev.2298 → 1.2.0-dev.2302

package/dist/valueparser.cjs

@@ -1,9 +1,34 @@
 const require_message = require('./message.cjs');
+const require_mode_dispatch = require('./internal/mode-dispatch.cjs');
 const require_internal_dependency = require('./internal/dependency.cjs');
 const require_suggestion = require('./suggestion.cjs');
 const require_nonempty = require('./nonempty.cjs');
 
 //#region src/valueparser.ts
+function transformValueParserResult(result, mapping) {
+	if (!result.success) return result;
+	const preserveSnapshot = (mapped) => {
+		const snapshot = require_internal_dependency.getSnapshottedDefaultDependencyValues(result);
+		return snapshot == null ? mapped : require_internal_dependency.snapshotDefaultDependencyValues(mapped, snapshot);
+	};
+	if (result.deferred) try {
+		return preserveSnapshot({
+			success: true,
+			value: mapping.map(result.value),
+			deferred: true
+		});
+	} catch {
+		return preserveSnapshot({
+			success: true,
+			value: void 0,
+			deferred: true
+		});
+	}
+	return preserveSnapshot({
+		success: true,
+		value: mapping.map(result.value)
+	});
+}
 /**
 * A predicate function that checks if an object is a {@link ValueParser}.
 * @param object The object to check.
@@ -191,6 +216,187 @@ function choice(choices, options = {}) {
 		}
 	};
 }
+function biject(mapping) {
+	if (Array.isArray(mapping)) throw new TypeError("Expected biject mapping to be a non-array object.");
+	const keys = [];
+	for (const key in mapping) if (Object.prototype.hasOwnProperty.call(mapping, key)) keys.push(key);
+	if (keys.length < 1) throw new RangeError("Expected at least one biject entry.");
+	const source = choice(keys);
+	const forward = /* @__PURE__ */ new Map();
+	const reverse = /* @__PURE__ */ new Map();
+	for (const key of keys) {
+		const value = mapping[key];
+		if (reverse.has(value)) throw new RangeError(`Duplicate biject value for key ${JSON.stringify(key)}.`);
+		forward.set(key, value);
+		reverse.set(value, key);
+	}
+	const parser = transform(source, {
+		map(value) {
+			return forward.get(value);
+		},
+		unmap(value) {
+			const key = reverse.get(value);
+			if (key !== void 0) return key;
+			try {
+				return String(value);
+			} catch {
+				return "";
+			}
+		}
+	});
+	Object.defineProperty(parser, "validate", {
+		value(value) {
+			if (reverse.has(value)) return {
+				success: true,
+				value
+			};
+			let input;
+			try {
+				input = String(value);
+			} catch {
+				input = "";
+			}
+			const result = source.parse(input);
+			if (!result.success) return result;
+			return {
+				success: false,
+				error: formatDefaultChoiceError(input, keys)
+			};
+		},
+		configurable: true,
+		enumerable: true
+	});
+	return parser;
+}
+/**
+* Creates a value parser that transforms the result of another value parser.
+*
+* This is useful when an existing value parser already describes the accepted
+* CLI spelling, suggestions, and error messages, but your application wants a
+* different result type.  For example, a string `choice()` can be transformed
+* into an internal enum, tagged object, or other domain type.
+*
+* Unlike parser-level `map()`, value parser transformation needs an inverse
+* mapping.  The `unmap` function lets the transformed parser format values,
+* validate fallback/default values, and reuse the wrapped parser's metadata
+* without guessing how to serialize the transformed type.
+*
+* Transform functions are synchronous.  If the wrapped parser is async, the
+* returned parser is async too, but `map` and `unmap` still run synchronously
+* after the wrapped parser resolves.
+*
+* @template M The execution mode of the wrapped parser.
+* @template T The value type produced by the wrapped parser.
+* @template U The value type produced by the transformed parser.
+* @param parser The value parser to transform.
+* @param mapping Mapping functions between the wrapped and transformed value
+*                types.
+* @returns A value parser that accepts the same input as `parser` and produces
+*          transformed values.
+* @since 1.2.0
+*/
+function transform(parser, mapping) {
+	const normalize = parser.normalize?.bind(parser);
+	const suggest = parser.suggest?.bind(parser);
+	const transformedChoices = parser.choices == null ? void 0 : Object.freeze(parser.choices.map((choice$1) => mapping.map(choice$1)));
+	const transformed = {
+		mode: parser.mode,
+		metavar: parser.metavar,
+		placeholder: void 0,
+		...transformedChoices == null ? {} : { choices: transformedChoices },
+		parse(input) {
+			return require_mode_dispatch.mapModeValue(parser.mode, parser.parse(input), (result) => transformValueParserResult(result, mapping));
+		},
+		format(value) {
+			return parser.format(mapping.unmap(value));
+		},
+		...normalize == null ? {} : { normalize(value) {
+			return mapping.map(normalize(mapping.unmap(value)));
+		} },
+		...suggest == null ? {} : { suggest(prefix) {
+			return suggest(prefix);
+		} }
+	};
+	Object.defineProperty(transformed, "placeholder", {
+		get() {
+			try {
+				return mapping.map(parser.placeholder);
+			} catch {
+				return void 0;
+			}
+		},
+		configurable: true,
+		enumerable: false
+	});
+	if (typeof parser.validate === "function") {
+		const validate = parser.validate.bind(parser);
+		Object.defineProperty(transformed, "validate", {
+			value(value) {
+				const result = validate(mapping.unmap(value));
+				return result.success ? {
+					success: true,
+					value: mapping.map(result.value)
+				} : result;
+			},
+			configurable: true,
+			enumerable: true
+		});
+	} else if (parser.mode === "sync") {
+		const syncParser = parser;
+		Object.defineProperty(transformed, "validate", {
+			value(value) {
+				const result = syncParser.parse(syncParser.format(mapping.unmap(value)));
+				return result.success ? {
+					success: true,
+					value: mapping.map(result.value)
+				} : result;
+			},
+			configurable: true,
+			enumerable: true
+		});
+	}
+	if (require_internal_dependency.isDerivedValueParser(parser)) preserveTransformedDerivedMetadata(transformed, parser, mapping);
+	return transformed;
+}
+function preserveTransformedDerivedMetadata(transformed, parser, mapping) {
+	Object.defineProperties(transformed, {
+		[require_internal_dependency.derivedValueParserMarker]: {
+			value: true,
+			enumerable: true
+		},
+		[require_internal_dependency.dependencyId]: {
+			value: parser[require_internal_dependency.dependencyId],
+			enumerable: true
+		},
+		[require_internal_dependency.parseWithDependency]: {
+			value(input, dependencyValue) {
+				return require_mode_dispatch.mapMaybePromiseByMode(parser.mode, parser[require_internal_dependency.parseWithDependency](input, dependencyValue), (result) => transformValueParserResult(result, mapping));
+			},
+			enumerable: true
+		}
+	});
+	if (require_internal_dependency.dependencyIds in parser && parser[require_internal_dependency.dependencyIds] != null) Object.defineProperty(transformed, require_internal_dependency.dependencyIds, {
+		value: parser[require_internal_dependency.dependencyIds],
+		enumerable: true
+	});
+	if (require_internal_dependency.defaultValues in parser && parser[require_internal_dependency.defaultValues] != null) Object.defineProperty(transformed, require_internal_dependency.defaultValues, {
+		value: parser[require_internal_dependency.defaultValues],
+		enumerable: true
+	});
+	if (require_internal_dependency.singleDefaultValue in parser && parser[require_internal_dependency.singleDefaultValue] != null) Object.defineProperty(transformed, require_internal_dependency.singleDefaultValue, {
+		value: parser[require_internal_dependency.singleDefaultValue],
+		enumerable: true
+	});
+	if (require_internal_dependency.suggestWithDependency in parser && parser[require_internal_dependency.suggestWithDependency] != null) {
+		const suggest = parser[require_internal_dependency.suggestWithDependency];
+		Object.defineProperty(transformed, require_internal_dependency.suggestWithDependency, {
+			value(prefix, dependencyValue) {
+				return require_mode_dispatch.wrapIterableForMode(parser.mode, suggest(prefix, dependencyValue));
+			},
+			enumerable: true
+		});
+	}
+}
 /**
 * Validates that an option value, if present, is a boolean.
 * Throws a {@link TypeError} if the value is defined but not a boolean.
@@ -6336,6 +6542,7 @@ function plainObjectsEqual(a, b) {
 }
 
 //#endregion
+exports.biject = biject;
 exports.checkBooleanOption = checkBooleanOption;
 exports.checkEnumOption = checkEnumOption;
 exports.choice = choice;
@@ -6364,5 +6571,6 @@ exports.portRange = portRange;
 exports.semVer = semVer;
 exports.socketAddress = socketAddress;
 exports.string = string;
+exports.transform = transform;
 exports.url = url;
 exports.uuid = uuid;

package/dist/valueparser.d.cts

@@ -327,6 +327,36 @@ interface ChoiceOptionsNumber extends ChoiceOptionsBase {
  *             {@link ChoiceOptionsNumber} for number choices.
  */
 type ChoiceOptions = ChoiceOptionsString;
+/**
+ * Mapping functions for the {@link transform} value parser combinator.
+ *
+ * `map` converts values produced by the wrapped parser into the public result
+ * type.  `unmap` converts public values back to the wrapped parser's type so
+ * `format()`, `validate()`, and default-value handling can keep using the
+ * wrapped parser's own validation and formatting rules.
+ *
+ * The two functions should be inverses for the values your CLI accepts:
+ * `unmap(map(input))` should return a value accepted by the wrapped parser,
+ * and `map(unmap(output))` should preserve valid public values.
+ *
+ * @template T The value type produced by the wrapped parser.
+ * @template U The value type produced by the transformed parser.
+ * @since 1.2.0
+ */
+interface TransformMapping<T, U> {
+  /**
+   * Converts a value produced by the wrapped parser into the transformed
+   * parser's public value type.
+   */
+  map(value: T): U;
+  /**
+   * Converts a public transformed value back into the wrapped parser's value
+   * type for formatting and fallback validation.
+   */
+  unmap(value: U): T;
+}
+type BijectKey<T> = Extract<keyof T, string | number>;
+type BijectValue<T> = T[BijectKey<T>];
 /**
  * A predicate function that checks if an object is a {@link ValueParser}.
  * @param object The object to check.
@@ -374,6 +404,58 @@ declare function choice<const T extends string>(choices: readonly T[], options?:
  * @since 0.9.0
  */
 declare function choice<const T extends number>(choices: readonly T[], options?: ChoiceOptionsNumber): ValueParser<"sync", T>;
+/**
+ * Creates a value parser from a one-to-one mapping of CLI spellings to values.
+ *
+ * The mapping's string keys are accepted as command-line input, and each key
+ * is parsed into its corresponding value.  Values must also be unique using
+ * the same equality semantics as `Map` keys, so the parser can format a value
+ * back to the original key.
+ *
+ * This is a convenience wrapper around `choice(Object.keys(mapping))` and
+ * {@link transform}.  It keeps the input-side metadata from `choice()` while
+ * exposing the mapped values as the parser result type.
+ *
+ * @template T The one-to-one mapping from input strings to parsed values.
+ * @param mapping A mapping whose own enumerable string keys are valid inputs.
+ * @returns A value parser that accepts one of the mapping keys and returns the
+ *          corresponding value.
+ * @throws {TypeError} If `mapping` is an array, or if any key is the empty
+ *         string.
+ * @throws {RangeError} If the mapping has no own enumerable string keys, or if
+ *         two keys map to the same value according to `Map` key equality.
+ * @since 1.2.0
+ */
+declare function biject<const T extends readonly unknown[]>(mapping: T): never;
+declare function biject<const T extends object>(mapping: T): ValueParser<"sync", BijectValue<T>>;
+/**
+ * Creates a value parser that transforms the result of another value parser.
+ *
+ * This is useful when an existing value parser already describes the accepted
+ * CLI spelling, suggestions, and error messages, but your application wants a
+ * different result type.  For example, a string `choice()` can be transformed
+ * into an internal enum, tagged object, or other domain type.
+ *
+ * Unlike parser-level `map()`, value parser transformation needs an inverse
+ * mapping.  The `unmap` function lets the transformed parser format values,
+ * validate fallback/default values, and reuse the wrapped parser's metadata
+ * without guessing how to serialize the transformed type.
+ *
+ * Transform functions are synchronous.  If the wrapped parser is async, the
+ * returned parser is async too, but `map` and `unmap` still run synchronously
+ * after the wrapped parser resolves.
+ *
+ * @template M The execution mode of the wrapped parser.
+ * @template T The value type produced by the wrapped parser.
+ * @template U The value type produced by the transformed parser.
+ * @param parser The value parser to transform.
+ * @param mapping Mapping functions between the wrapped and transformed value
+ *                types.
+ * @returns A value parser that accepts the same input as `parser` and produces
+ *          transformed values.
+ * @since 1.2.0
+ */
+declare function transform<M extends Mode, T, U>(parser: ValueParser<M, T>, mapping: TransformMapping<T, U>): ValueParser<M, U>;
 /**
  * Validates that an option value, if present, is a boolean.
  * Throws a {@link TypeError} if the value is defined but not a boolean.
@@ -3197,4 +3279,4 @@ declare function firstOf<const TParsers extends readonly [ValueParser<"sync", un
  */
 declare function firstOf<const TParsers extends readonly ValueParser<"sync", unknown>[]>(parsers: TParsers, options?: FirstOfOptions): ValueParser<"sync", ValueParserValue<TParsers[number]>>;
 //#endregion
-export { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, CronExpression, CronExpressionForOptions, CronOptions, DeferredMap, DomainOptions, EmailOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, KeyValueOptions, LocaleOptions, MacAddressOptions, type Mode, type ModeIterable, type ModeValue, type NonEmptyString, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SocketAddressOptions, SocketAddressValue, StringOptions, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, checkBooleanOption, checkEnumOption, choice, cidr, color, cron, domain, email, ensureNonEmptyString, fileSize, firstOf, float, hostname, integer, ip, ipv4, ipv6, isNonEmptyString, isValueParser, json, keyValue, locale, macAddress, port, portRange, semVer, socketAddress, string, url, uuid };
+export { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, CronExpression, CronExpressionForOptions, CronOptions, DeferredMap, DomainOptions, EmailOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, KeyValueOptions, LocaleOptions, MacAddressOptions, type Mode, type ModeIterable, type ModeValue, type NonEmptyString, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SocketAddressOptions, SocketAddressValue, StringOptions, TransformMapping, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, biject, checkBooleanOption, checkEnumOption, choice, cidr, color, cron, domain, email, ensureNonEmptyString, fileSize, firstOf, float, hostname, integer, ip, ipv4, ipv6, isNonEmptyString, isValueParser, json, keyValue, locale, macAddress, port, portRange, semVer, socketAddress, string, transform, url, uuid };

package/dist/valueparser.d.ts

@@ -327,6 +327,36 @@ interface ChoiceOptionsNumber extends ChoiceOptionsBase {
  *             {@link ChoiceOptionsNumber} for number choices.
  */
 type ChoiceOptions = ChoiceOptionsString;
+/**
+ * Mapping functions for the {@link transform} value parser combinator.
+ *
+ * `map` converts values produced by the wrapped parser into the public result
+ * type.  `unmap` converts public values back to the wrapped parser's type so
+ * `format()`, `validate()`, and default-value handling can keep using the
+ * wrapped parser's own validation and formatting rules.
+ *
+ * The two functions should be inverses for the values your CLI accepts:
+ * `unmap(map(input))` should return a value accepted by the wrapped parser,
+ * and `map(unmap(output))` should preserve valid public values.
+ *
+ * @template T The value type produced by the wrapped parser.
+ * @template U The value type produced by the transformed parser.
+ * @since 1.2.0
+ */
+interface TransformMapping<T, U> {
+  /**
+   * Converts a value produced by the wrapped parser into the transformed
+   * parser's public value type.
+   */
+  map(value: T): U;
+  /**
+   * Converts a public transformed value back into the wrapped parser's value
+   * type for formatting and fallback validation.
+   */
+  unmap(value: U): T;
+}
+type BijectKey<T> = Extract<keyof T, string | number>;
+type BijectValue<T> = T[BijectKey<T>];
 /**
  * A predicate function that checks if an object is a {@link ValueParser}.
  * @param object The object to check.
@@ -374,6 +404,58 @@ declare function choice<const T extends string>(choices: readonly T[], options?:
  * @since 0.9.0
  */
 declare function choice<const T extends number>(choices: readonly T[], options?: ChoiceOptionsNumber): ValueParser<"sync", T>;
+/**
+ * Creates a value parser from a one-to-one mapping of CLI spellings to values.
+ *
+ * The mapping's string keys are accepted as command-line input, and each key
+ * is parsed into its corresponding value.  Values must also be unique using
+ * the same equality semantics as `Map` keys, so the parser can format a value
+ * back to the original key.
+ *
+ * This is a convenience wrapper around `choice(Object.keys(mapping))` and
+ * {@link transform}.  It keeps the input-side metadata from `choice()` while
+ * exposing the mapped values as the parser result type.
+ *
+ * @template T The one-to-one mapping from input strings to parsed values.
+ * @param mapping A mapping whose own enumerable string keys are valid inputs.
+ * @returns A value parser that accepts one of the mapping keys and returns the
+ *          corresponding value.
+ * @throws {TypeError} If `mapping` is an array, or if any key is the empty
+ *         string.
+ * @throws {RangeError} If the mapping has no own enumerable string keys, or if
+ *         two keys map to the same value according to `Map` key equality.
+ * @since 1.2.0
+ */
+declare function biject<const T extends readonly unknown[]>(mapping: T): never;
+declare function biject<const T extends object>(mapping: T): ValueParser<"sync", BijectValue<T>>;
+/**
+ * Creates a value parser that transforms the result of another value parser.
+ *
+ * This is useful when an existing value parser already describes the accepted
+ * CLI spelling, suggestions, and error messages, but your application wants a
+ * different result type.  For example, a string `choice()` can be transformed
+ * into an internal enum, tagged object, or other domain type.
+ *
+ * Unlike parser-level `map()`, value parser transformation needs an inverse
+ * mapping.  The `unmap` function lets the transformed parser format values,
+ * validate fallback/default values, and reuse the wrapped parser's metadata
+ * without guessing how to serialize the transformed type.
+ *
+ * Transform functions are synchronous.  If the wrapped parser is async, the
+ * returned parser is async too, but `map` and `unmap` still run synchronously
+ * after the wrapped parser resolves.
+ *
+ * @template M The execution mode of the wrapped parser.
+ * @template T The value type produced by the wrapped parser.
+ * @template U The value type produced by the transformed parser.
+ * @param parser The value parser to transform.
+ * @param mapping Mapping functions between the wrapped and transformed value
+ *                types.
+ * @returns A value parser that accepts the same input as `parser` and produces
+ *          transformed values.
+ * @since 1.2.0
+ */
+declare function transform<M extends Mode, T, U>(parser: ValueParser<M, T>, mapping: TransformMapping<T, U>): ValueParser<M, U>;
 /**
  * Validates that an option value, if present, is a boolean.
  * Throws a {@link TypeError} if the value is defined but not a boolean.
@@ -3197,4 +3279,4 @@ declare function firstOf<const TParsers extends readonly [ValueParser<"sync", un
  */
 declare function firstOf<const TParsers extends readonly ValueParser<"sync", unknown>[]>(parsers: TParsers, options?: FirstOfOptions): ValueParser<"sync", ValueParserValue<TParsers[number]>>;
 //#endregion
-export { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, CronExpression, CronExpressionForOptions, CronOptions, DeferredMap, DomainOptions, EmailOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, KeyValueOptions, LocaleOptions, MacAddressOptions, type Mode, type ModeIterable, type ModeValue, type NonEmptyString, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SocketAddressOptions, SocketAddressValue, StringOptions, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, checkBooleanOption, checkEnumOption, choice, cidr, color, cron, domain, email, ensureNonEmptyString, fileSize, firstOf, float, hostname, integer, ip, ipv4, ipv6, isNonEmptyString, isValueParser, json, keyValue, locale, macAddress, port, portRange, semVer, socketAddress, string, url, uuid };
+export { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, CronExpression, CronExpressionForOptions, CronOptions, DeferredMap, DomainOptions, EmailOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, KeyValueOptions, LocaleOptions, MacAddressOptions, type Mode, type ModeIterable, type ModeValue, type NonEmptyString, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SocketAddressOptions, SocketAddressValue, StringOptions, TransformMapping, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, biject, checkBooleanOption, checkEnumOption, choice, cidr, color, cron, domain, email, ensureNonEmptyString, fileSize, firstOf, float, hostname, integer, ip, ipv4, ipv6, isNonEmptyString, isValueParser, json, keyValue, locale, macAddress, port, portRange, semVer, socketAddress, string, transform, url, uuid };

package/dist/valueparser.js

@@ -1,9 +1,34 @@
 import { cloneMessage, lineBreak, message, metavar, text, valueSet } from "./message.js";
-import { isDerivedValueParser } from "./internal/dependency.js";
+import { mapMaybePromiseByMode, mapModeValue, wrapIterableForMode } from "./internal/mode-dispatch.js";
+import { defaultValues, dependencyId, dependencyIds, derivedValueParserMarker, getSnapshottedDefaultDependencyValues, isDerivedValueParser, parseWithDependency, singleDefaultValue, snapshotDefaultDependencyValues, suggestWithDependency } from "./internal/dependency.js";
 import { appendValueHint, appendValueSuggestions, deduplicateSuggestions } from "./suggestion.js";
 import { ensureNonEmptyString, isNonEmptyString } from "./nonempty.js";
 
 //#region src/valueparser.ts
+function transformValueParserResult(result, mapping) {
+	if (!result.success) return result;
+	const preserveSnapshot = (mapped) => {
+		const snapshot = getSnapshottedDefaultDependencyValues(result);
+		return snapshot == null ? mapped : snapshotDefaultDependencyValues(mapped, snapshot);
+	};
+	if (result.deferred) try {
+		return preserveSnapshot({
+			success: true,
+			value: mapping.map(result.value),
+			deferred: true
+		});
+	} catch {
+		return preserveSnapshot({
+			success: true,
+			value: void 0,
+			deferred: true
+		});
+	}
+	return preserveSnapshot({
+		success: true,
+		value: mapping.map(result.value)
+	});
+}
 /**
 * A predicate function that checks if an object is a {@link ValueParser}.
 * @param object The object to check.
@@ -191,6 +216,187 @@ function choice(choices, options = {}) {
 		}
 	};
 }
+function biject(mapping) {
+	if (Array.isArray(mapping)) throw new TypeError("Expected biject mapping to be a non-array object.");
+	const keys = [];
+	for (const key in mapping) if (Object.prototype.hasOwnProperty.call(mapping, key)) keys.push(key);
+	if (keys.length < 1) throw new RangeError("Expected at least one biject entry.");
+	const source = choice(keys);
+	const forward = /* @__PURE__ */ new Map();
+	const reverse = /* @__PURE__ */ new Map();
+	for (const key of keys) {
+		const value = mapping[key];
+		if (reverse.has(value)) throw new RangeError(`Duplicate biject value for key ${JSON.stringify(key)}.`);
+		forward.set(key, value);
+		reverse.set(value, key);
+	}
+	const parser = transform(source, {
+		map(value) {
+			return forward.get(value);
+		},
+		unmap(value) {
+			const key = reverse.get(value);
+			if (key !== void 0) return key;
+			try {
+				return String(value);
+			} catch {
+				return "";
+			}
+		}
+	});
+	Object.defineProperty(parser, "validate", {
+		value(value) {
+			if (reverse.has(value)) return {
+				success: true,
+				value
+			};
+			let input;
+			try {
+				input = String(value);
+			} catch {
+				input = "";
+			}
+			const result = source.parse(input);
+			if (!result.success) return result;
+			return {
+				success: false,
+				error: formatDefaultChoiceError(input, keys)
+			};
+		},
+		configurable: true,
+		enumerable: true
+	});
+	return parser;
+}
+/**
+* Creates a value parser that transforms the result of another value parser.
+*
+* This is useful when an existing value parser already describes the accepted
+* CLI spelling, suggestions, and error messages, but your application wants a
+* different result type.  For example, a string `choice()` can be transformed
+* into an internal enum, tagged object, or other domain type.
+*
+* Unlike parser-level `map()`, value parser transformation needs an inverse
+* mapping.  The `unmap` function lets the transformed parser format values,
+* validate fallback/default values, and reuse the wrapped parser's metadata
+* without guessing how to serialize the transformed type.
+*
+* Transform functions are synchronous.  If the wrapped parser is async, the
+* returned parser is async too, but `map` and `unmap` still run synchronously
+* after the wrapped parser resolves.
+*
+* @template M The execution mode of the wrapped parser.
+* @template T The value type produced by the wrapped parser.
+* @template U The value type produced by the transformed parser.
+* @param parser The value parser to transform.
+* @param mapping Mapping functions between the wrapped and transformed value
+*                types.
+* @returns A value parser that accepts the same input as `parser` and produces
+*          transformed values.
+* @since 1.2.0
+*/
+function transform(parser, mapping) {
+	const normalize = parser.normalize?.bind(parser);
+	const suggest = parser.suggest?.bind(parser);
+	const transformedChoices = parser.choices == null ? void 0 : Object.freeze(parser.choices.map((choice$1) => mapping.map(choice$1)));
+	const transformed = {
+		mode: parser.mode,
+		metavar: parser.metavar,
+		placeholder: void 0,
+		...transformedChoices == null ? {} : { choices: transformedChoices },
+		parse(input) {
+			return mapModeValue(parser.mode, parser.parse(input), (result) => transformValueParserResult(result, mapping));
+		},
+		format(value) {
+			return parser.format(mapping.unmap(value));
+		},
+		...normalize == null ? {} : { normalize(value) {
+			return mapping.map(normalize(mapping.unmap(value)));
+		} },
+		...suggest == null ? {} : { suggest(prefix) {
+			return suggest(prefix);
+		} }
+	};
+	Object.defineProperty(transformed, "placeholder", {
+		get() {
+			try {
+				return mapping.map(parser.placeholder);
+			} catch {
+				return void 0;
+			}
+		},
+		configurable: true,
+		enumerable: false
+	});
+	if (typeof parser.validate === "function") {
+		const validate = parser.validate.bind(parser);
+		Object.defineProperty(transformed, "validate", {
+			value(value) {
+				const result = validate(mapping.unmap(value));
+				return result.success ? {
+					success: true,
+					value: mapping.map(result.value)
+				} : result;
+			},
+			configurable: true,
+			enumerable: true
+		});
+	} else if (parser.mode === "sync") {
+		const syncParser = parser;
+		Object.defineProperty(transformed, "validate", {
+			value(value) {
+				const result = syncParser.parse(syncParser.format(mapping.unmap(value)));
+				return result.success ? {
+					success: true,
+					value: mapping.map(result.value)
+				} : result;
+			},
+			configurable: true,
+			enumerable: true
+		});
+	}
+	if (isDerivedValueParser(parser)) preserveTransformedDerivedMetadata(transformed, parser, mapping);
+	return transformed;
+}
+function preserveTransformedDerivedMetadata(transformed, parser, mapping) {
+	Object.defineProperties(transformed, {
+		[derivedValueParserMarker]: {
+			value: true,
+			enumerable: true
+		},
+		[dependencyId]: {
+			value: parser[dependencyId],
+			enumerable: true
+		},
+		[parseWithDependency]: {
+			value(input, dependencyValue) {
+				return mapMaybePromiseByMode(parser.mode, parser[parseWithDependency](input, dependencyValue), (result) => transformValueParserResult(result, mapping));
+			},
+			enumerable: true
+		}
+	});
+	if (dependencyIds in parser && parser[dependencyIds] != null) Object.defineProperty(transformed, dependencyIds, {
+		value: parser[dependencyIds],
+		enumerable: true
+	});
+	if (defaultValues in parser && parser[defaultValues] != null) Object.defineProperty(transformed, defaultValues, {
+		value: parser[defaultValues],
+		enumerable: true
+	});
+	if (singleDefaultValue in parser && parser[singleDefaultValue] != null) Object.defineProperty(transformed, singleDefaultValue, {
+		value: parser[singleDefaultValue],
+		enumerable: true
+	});
+	if (suggestWithDependency in parser && parser[suggestWithDependency] != null) {
+		const suggest = parser[suggestWithDependency];
+		Object.defineProperty(transformed, suggestWithDependency, {
+			value(prefix, dependencyValue) {
+				return wrapIterableForMode(parser.mode, suggest(prefix, dependencyValue));
+			},
+			enumerable: true
+		});
+	}
+}
 /**
 * Validates that an option value, if present, is a boolean.
 * Throws a {@link TypeError} if the value is defined but not a boolean.
@@ -6336,4 +6542,4 @@ function plainObjectsEqual(a, b) {
 }
 
 //#endregion
-export { checkBooleanOption, checkEnumOption, choice, cidr, color, cron, domain, email, ensureNonEmptyString, fileSize, firstOf, float, hostname, integer, ip, ipv4, ipv6, isNonEmptyString, isValueParser, json, keyValue, locale, macAddress, port, portRange, semVer, socketAddress, string, url, uuid };
+export { biject, checkBooleanOption, checkEnumOption, choice, cidr, color, cron, domain, email, ensureNonEmptyString, fileSize, firstOf, float, hostname, integer, ip, ipv4, ipv6, isNonEmptyString, isValueParser, json, keyValue, locale, macAddress, port, portRange, semVer, socketAddress, string, transform, url, uuid };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.2.0-dev.2298",
+  "version": "1.2.0-dev.2302",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",
@@ -225,7 +225,7 @@
     "fast-check": "^4.7.0",
     "tsdown": "^0.13.0",
     "typescript": "^5.8.3",
-    "@optique/env": "1.2.0-dev.2298+a0394b06"
+    "@optique/env": "1.2.0-dev.2302+77665cb5"
   },
   "scripts": {
     "build": "tsdown",