@optique/core 1.0.0-dev.1547 → 1.0.0-dev.1555

package/dist/modifiers.js

@@ -118,7 +118,7 @@ function optional(parser) {
 	const wrappedDependencyMarker = innerHasWrappedDependency ? { [wrappedDependencySourceMarker]: parser[wrappedDependencySourceMarker] } : innerHasDirectDependency ? { [wrappedDependencySourceMarker]: syncParser.initialState } : {};
 	const hasWrappedDependencySource = wrappedDependencySourceMarker in wrappedDependencyMarker;
 	const wrappedPendingState = hasWrappedDependencySource ? wrappedDependencyMarker[wrappedDependencySourceMarker] : void 0;
-	return {
+	const optionalParser = {
 		$mode: parser.$mode,
 		$valueType: [],
 		$stateType: [],
@@ -175,6 +175,18 @@ function optional(parser) {
 			return syncParser.getDocFragments(innerState, defaultValue);
 		}
 	};
+	if (typeof parser.normalizeValue === "function") {
+		const innerNormalize = parser.normalizeValue.bind(parser);
+		Object.defineProperty(optionalParser, "normalizeValue", {
+			value(v) {
+				if (v == null) return v;
+				return innerNormalize(v);
+			},
+			configurable: true,
+			enumerable: false
+		});
+	}
+	return optionalParser;
 }
 /**
 * Error type for structured error messages in {@link withDefault} default value callbacks.
@@ -257,12 +269,19 @@ function withDefault(parser, defaultValue, options) {
 			return dispatchByMode(parser.$mode, () => parseOptionalStyleSync(context, syncParser), () => parseOptionalStyleAsync(context, parser));
 		},
 		complete(state) {
+			function evaluateDefault() {
+				const raw = typeof defaultValue === "function" ? defaultValue() : defaultValue;
+				if (typeof parser.normalizeValue === "function") try {
+					return parser.normalizeValue(raw);
+				} catch {}
+				return raw;
+			}
 			if (!Array.isArray(state)) {
 				if (transformsDependencyValue(parser)) {
 					const innerResult = dispatchByMode(parser.$mode, () => syncParser.complete(void 0), () => parser.complete(void 0));
 					const handleInnerResult = (res) => {
 						if (isDependencySourceState(res)) try {
-							const value = typeof defaultValue === "function" ? defaultValue() : defaultValue;
+							const value = evaluateDefault();
 							return createDependencySourceState({
 								success: true,
 								value
@@ -274,7 +293,7 @@ function withDefault(parser, defaultValue, options) {
 							};
 						}
 						try {
-							const value = typeof defaultValue === "function" ? defaultValue() : defaultValue;
+							const value = evaluateDefault();
 							return {
 								success: true,
 								value
@@ -289,7 +308,7 @@ function withDefault(parser, defaultValue, options) {
 					return mapModeValue(parser.$mode, innerResult, handleInnerResult);
 				}
 				if (isWrappedDependencySource(parser)) try {
-					const value = typeof defaultValue === "function" ? defaultValue() : defaultValue;
+					const value = evaluateDefault();
 					const pendingState = parser[wrappedDependencySourceMarker];
 					return createDependencySourceState({
 						success: true,
@@ -306,7 +325,7 @@ function withDefault(parser, defaultValue, options) {
 					return innerResult;
 				}
 				try {
-					const value = typeof defaultValue === "function" ? defaultValue() : defaultValue;
+					const value = evaluateDefault();
 					return {
 						success: true,
 						value
@@ -323,7 +342,7 @@ function withDefault(parser, defaultValue, options) {
 					const innerResult = dispatchByMode(parser.$mode, () => syncParser.complete(state), () => parser.complete(state));
 					const handleInnerResult = (res) => {
 						if (isDependencySourceState(res)) try {
-							const value = typeof defaultValue === "function" ? defaultValue() : defaultValue;
+							const value = evaluateDefault();
 							return createDependencySourceState({
 								success: true,
 								value
@@ -335,7 +354,7 @@ function withDefault(parser, defaultValue, options) {
 							};
 						}
 						try {
-							const value = typeof defaultValue === "function" ? defaultValue() : defaultValue;
+							const value = evaluateDefault();
 							return {
 								success: true,
 								value
@@ -350,7 +369,7 @@ function withDefault(parser, defaultValue, options) {
 					return mapModeValue(parser.$mode, innerResult, handleInnerResult);
 				}
 				try {
-					const value = typeof defaultValue === "function" ? defaultValue() : defaultValue;
+					const value = evaluateDefault();
 					return createDependencySourceState({
 						success: true,
 						value
@@ -373,7 +392,11 @@ function withDefault(parser, defaultValue, options) {
 				kind: "available",
 				state: state.state[0]
 			};
-			const fragments = syncParser.getDocFragments(innerState, getDocDefaultValue(upperDefaultValue));
+			let docDefault = getDocDefaultValue(upperDefaultValue);
+			if (docDefault != null && typeof parser.normalizeValue === "function") try {
+				docDefault = parser.normalizeValue(docDefault);
+			} catch {}
+			const fragments = syncParser.getDocFragments(innerState, docDefault);
 			if (options?.message) {
 				const modifiedFragments = fragments.fragments.map((fragment) => {
 					if (fragment.type === "entry") return {
@@ -397,6 +420,20 @@ function withDefault(parser, defaultValue, options) {
 		configurable: true,
 		enumerable: false
 	});
+	if (typeof parser.normalizeValue === "function") {
+		const innerNormalize = parser.normalizeValue.bind(parser);
+		Object.defineProperty(withDefaultParser, "normalizeValue", {
+			value(v) {
+				try {
+					return innerNormalize(v);
+				} catch {
+					return v;
+				}
+			},
+			configurable: true,
+			enumerable: false
+		});
+	}
 	return withDefaultParser;
 }
 /**
@@ -510,6 +547,7 @@ function map(parser, transform) {
 			return parser.getDocFragments(state, void 0);
 		}
 	};
+	delete mappedParser.normalizeValue;
 	if ("placeholder" in parser) Object.defineProperty(mappedParser, "placeholder", {
 		get() {
 			try {
@@ -828,6 +866,27 @@ function multiple(parser, options = {}) {
 		configurable: true,
 		enumerable: false
 	});
+	if (typeof parser.normalizeValue === "function") {
+		const innerNormalize = parser.normalizeValue.bind(parser);
+		Object.defineProperty(resultParser, "normalizeValue", {
+			value(values) {
+				if (!Array.isArray(values)) return values;
+				let changed = false;
+				const result = values.map((v) => {
+					try {
+						const n = innerNormalize(v);
+						if (n !== v) changed = true;
+						return n;
+					} catch {
+						return v;
+					}
+				});
+				return changed ? result : values;
+			},
+			configurable: true,
+			enumerable: false
+		});
+	}
 	return resultParser;
 }
 /**
@@ -916,6 +975,11 @@ function nonEmpty(parser) {
 		configurable: true,
 		enumerable: false
 	});
+	if (typeof parser.normalizeValue === "function") Object.defineProperty(nonEmptyParser, "normalizeValue", {
+		value: parser.normalizeValue.bind(parser),
+		configurable: true,
+		enumerable: false
+	});
 	return nonEmptyParser;
 }
 

package/dist/parser.d.cts

@@ -225,6 +225,26 @@ interface Parser<M extends Mode = "sync", TValue = unknown, TState = unknown> {
    * @since 1.0.0
    */
   shouldDeferCompletion?(state: TState): boolean;
+  /**
+   * Normalizes a parsed value according to the underlying value parser's
+   * configuration.  When present, {@link withDefault} calls this method
+   * on default values so that runtime defaults match the representation
+   * that the value parser's `parse()` would produce.
+   *
+   * Primitive parsers ({@link option}, {@link argument}) implement this
+   * by delegating to {@link ValueParser.normalize}.  Combinator wrappers
+   * ({@link optional}, {@link withDefault}) forward it from inner parsers.
+   *
+   * Exclusive combinators ({@link or}, `longestMatch()`) and
+   * multi-source combinators (`merge()`) intentionally do *not*
+   * implement this method because the active branch or key ownership
+   * is unknown at default time.
+   *
+   * @param value The value to normalize.
+   * @returns The normalized value.
+   * @since 1.0.0
+   */
+  normalizeValue?(value: TValue): TValue;
 }
 /**
  * The context of the parser, which includes the input buffer and the state.

package/dist/parser.d.ts

@@ -225,6 +225,26 @@ interface Parser<M extends Mode = "sync", TValue = unknown, TState = unknown> {
    * @since 1.0.0
    */
   shouldDeferCompletion?(state: TState): boolean;
+  /**
+   * Normalizes a parsed value according to the underlying value parser's
+   * configuration.  When present, {@link withDefault} calls this method
+   * on default values so that runtime defaults match the representation
+   * that the value parser's `parse()` would produce.
+   *
+   * Primitive parsers ({@link option}, {@link argument}) implement this
+   * by delegating to {@link ValueParser.normalize}.  Combinator wrappers
+   * ({@link optional}, {@link withDefault}) forward it from inner parsers.
+   *
+   * Exclusive combinators ({@link or}, `longestMatch()`) and
+   * multi-source combinators (`merge()`) intentionally do *not*
+   * implement this method because the active branch or key ownership
+   * is unknown at default time.
+   *
+   * @param value The value to normalize.
+   * @returns The normalized value.
+   * @since 1.0.0
+   */
+  normalizeValue?(value: TValue): TValue;
 }
 /**
  * The context of the parser, which includes the input buffer and the state.

package/dist/primitives.cjs

@@ -564,6 +564,20 @@ function option(...args) {
 			return `option(${optionNames$1.map((o) => JSON.stringify(o)).join(", ")})`;
 		}
 	};
+	if (valueParser != null && typeof valueParser.normalize === "function") {
+		const normalize = valueParser.normalize.bind(valueParser);
+		Object.defineProperty(result, "normalizeValue", {
+			value(v) {
+				try {
+					return normalize(v);
+				} catch {
+					return v;
+				}
+			},
+			configurable: true,
+			enumerable: false
+		});
+	}
 	if (valueParser != null) Object.defineProperty(result, "placeholder", {
 		get() {
 			try {
@@ -918,6 +932,20 @@ function argument(valueParser, options = {}) {
 			return `argument()`;
 		}
 	};
+	if (typeof valueParser.normalize === "function") {
+		const normalize = valueParser.normalize.bind(valueParser);
+		Object.defineProperty(result, "normalizeValue", {
+			value(v) {
+				try {
+					return normalize(v);
+				} catch {
+					return v;
+				}
+			},
+			configurable: true,
+			enumerable: false
+		});
+	}
 	Object.defineProperty(result, "placeholder", {
 		get() {
 			try {
@@ -1136,6 +1164,11 @@ function command(name, parser, options = {}) {
 			return `command(${JSON.stringify(name)})`;
 		}
 	};
+	if (typeof parser.normalizeValue === "function") Object.defineProperty(result, "normalizeValue", {
+		value: parser.normalizeValue.bind(parser),
+		configurable: true,
+		enumerable: false
+	});
 	return result;
 }
 /**

package/dist/primitives.js

@@ -564,6 +564,20 @@ function option(...args) {
 			return `option(${optionNames$1.map((o) => JSON.stringify(o)).join(", ")})`;
 		}
 	};
+	if (valueParser != null && typeof valueParser.normalize === "function") {
+		const normalize = valueParser.normalize.bind(valueParser);
+		Object.defineProperty(result, "normalizeValue", {
+			value(v) {
+				try {
+					return normalize(v);
+				} catch {
+					return v;
+				}
+			},
+			configurable: true,
+			enumerable: false
+		});
+	}
 	if (valueParser != null) Object.defineProperty(result, "placeholder", {
 		get() {
 			try {
@@ -918,6 +932,20 @@ function argument(valueParser, options = {}) {
 			return `argument()`;
 		}
 	};
+	if (typeof valueParser.normalize === "function") {
+		const normalize = valueParser.normalize.bind(valueParser);
+		Object.defineProperty(result, "normalizeValue", {
+			value(v) {
+				try {
+					return normalize(v);
+				} catch {
+					return v;
+				}
+			},
+			configurable: true,
+			enumerable: false
+		});
+	}
 	Object.defineProperty(result, "placeholder", {
 		get() {
 			try {
@@ -1136,6 +1164,11 @@ function command(name, parser, options = {}) {
 			return `command(${JSON.stringify(name)})`;
 		}
 	};
+	if (typeof parser.normalizeValue === "function") Object.defineProperty(result, "normalizeValue", {
+		value: parser.normalizeValue.bind(parser),
+		configurable: true,
+		enumerable: false
+	});
 	return result;
 }
 /**

package/dist/program.cjs

@@ -1,3 +1,4 @@
+const require_validate = require('./validate.cjs');
 
 //#region src/program.ts
 /**
@@ -11,6 +12,8 @@
 * @template T - The type of value produced by the parser.
 * @param program - The program definition with parser and metadata.
 * @returns The same program object with inferred types.
+* @throws {TypeError} If `program.metadata.name` is not a string, is empty,
+*         is whitespace-only, or contains control characters.
 *
 * @example
 * ```typescript
@@ -37,6 +40,7 @@
 * @since 1.0.0
 */
 function defineProgram(program) {
+	require_validate.validateProgramName(program.metadata.name);
 	return program;
 }
 

package/dist/program.d.cts

@@ -94,6 +94,8 @@ interface Program<M extends Mode, T> {
  * @template T - The type of value produced by the parser.
  * @param program - The program definition with parser and metadata.
  * @returns The same program object with inferred types.
+ * @throws {TypeError} If `program.metadata.name` is not a string, is empty,
+ *         is whitespace-only, or contains control characters.
  *
  * @example
  * ```typescript

package/dist/program.d.ts

@@ -94,6 +94,8 @@ interface Program<M extends Mode, T> {
  * @template T - The type of value produced by the parser.
  * @param program - The program definition with parser and metadata.
  * @returns The same program object with inferred types.
+ * @throws {TypeError} If `program.metadata.name` is not a string, is empty,
+ *         is whitespace-only, or contains control characters.
  *
  * @example
  * ```typescript

package/dist/program.js

@@ -1,3 +1,5 @@
+import { validateProgramName } from "./validate.js";
+
 //#region src/program.ts
 /**
 * Defines a CLI program with a parser and metadata.
@@ -10,6 +12,8 @@
 * @template T - The type of value produced by the parser.
 * @param program - The program definition with parser and metadata.
 * @returns The same program object with inferred types.
+* @throws {TypeError} If `program.metadata.name` is not a string, is empty,
+*         is whitespace-only, or contains control characters.
 *
 * @example
 * ```typescript
@@ -36,6 +40,7 @@
 * @since 1.0.0
 */
 function defineProgram(program) {
+	validateProgramName(program.metadata.name);
 	return program;
 }