@optique/core 1.0.0-dev.552 → 1.0.0-dev.556

package/dist/annotations.cjs

@@ -59,6 +59,24 @@ function getAnnotations(state) {
 	return void 0;
 }
 /**
+* Reattaches annotations to a freshly created array state.
+*
+* Array spread copies elements but drops symbol properties, so parsers that
+* rebuild array states need to copy annotations back explicitly.
+*
+* @param source The original state that may carry annotations.
+* @param target The freshly created array state.
+* @returns The target array, with annotations copied when available.
+* @internal
+*/
+function annotateFreshArray(source, target) {
+	const annotations = getAnnotations(source);
+	if (annotations === void 0) return target;
+	const annotated = target;
+	annotated[annotationKey] = annotations;
+	return annotated;
+}
+/**
 * Propagates annotations from one parser state to another.
 *
 * This is mainly used by parsers that rebuild array states with spread syntax.
@@ -212,6 +230,7 @@ function isInjectedAnnotationWrapper(value) {
 }
 
 //#endregion
+exports.annotateFreshArray = annotateFreshArray;
 exports.annotationKey = annotationKey;
 exports.annotationStateValueKey = annotationStateValueKey;
 exports.annotationWrapperKey = annotationWrapperKey;

package/dist/annotations.d.cts

@@ -68,6 +68,18 @@ interface ParseOptions {
  * ```
  */
 declare function getAnnotations(state: unknown): Annotations | undefined;
+/**
+ * Reattaches annotations to a freshly created array state.
+ *
+ * Array spread copies elements but drops symbol properties, so parsers that
+ * rebuild array states need to copy annotations back explicitly.
+ *
+ * @param source The original state that may carry annotations.
+ * @param target The freshly created array state.
+ * @returns The target array, with annotations copied when available.
+ * @internal
+ */
+declare function annotateFreshArray<T>(source: unknown, target: readonly T[]): readonly T[];
 /**
  * Propagates annotations from one parser state to another.
  *
@@ -115,4 +127,4 @@ declare function unwrapInjectedAnnotationWrapper<T>(value: T): T;
  */
 declare function isInjectedAnnotationWrapper(value: unknown): boolean;
 //#endregion
-export { Annotations, ParseOptions, annotationKey, annotationStateValueKey, annotationWrapperKey, getAnnotations, inheritAnnotations, injectAnnotations, isInjectedAnnotationWrapper, unwrapInjectedAnnotationWrapper };
+export { Annotations, ParseOptions, annotateFreshArray, annotationKey, annotationStateValueKey, annotationWrapperKey, getAnnotations, inheritAnnotations, injectAnnotations, isInjectedAnnotationWrapper, unwrapInjectedAnnotationWrapper };

package/dist/annotations.d.ts

@@ -68,6 +68,18 @@ interface ParseOptions {
  * ```
  */
 declare function getAnnotations(state: unknown): Annotations | undefined;
+/**
+ * Reattaches annotations to a freshly created array state.
+ *
+ * Array spread copies elements but drops symbol properties, so parsers that
+ * rebuild array states need to copy annotations back explicitly.
+ *
+ * @param source The original state that may carry annotations.
+ * @param target The freshly created array state.
+ * @returns The target array, with annotations copied when available.
+ * @internal
+ */
+declare function annotateFreshArray<T>(source: unknown, target: readonly T[]): readonly T[];
 /**
  * Propagates annotations from one parser state to another.
  *
@@ -115,4 +127,4 @@ declare function unwrapInjectedAnnotationWrapper<T>(value: T): T;
  */
 declare function isInjectedAnnotationWrapper(value: unknown): boolean;
 //#endregion
-export { Annotations, ParseOptions, annotationKey, annotationStateValueKey, annotationWrapperKey, getAnnotations, inheritAnnotations, injectAnnotations, isInjectedAnnotationWrapper, unwrapInjectedAnnotationWrapper };
+export { Annotations, ParseOptions, annotateFreshArray, annotationKey, annotationStateValueKey, annotationWrapperKey, getAnnotations, inheritAnnotations, injectAnnotations, isInjectedAnnotationWrapper, unwrapInjectedAnnotationWrapper };

package/dist/annotations.js

@@ -58,6 +58,24 @@ function getAnnotations(state) {
 	return void 0;
 }
 /**
+* Reattaches annotations to a freshly created array state.
+*
+* Array spread copies elements but drops symbol properties, so parsers that
+* rebuild array states need to copy annotations back explicitly.
+*
+* @param source The original state that may carry annotations.
+* @param target The freshly created array state.
+* @returns The target array, with annotations copied when available.
+* @internal
+*/
+function annotateFreshArray(source, target) {
+	const annotations = getAnnotations(source);
+	if (annotations === void 0) return target;
+	const annotated = target;
+	annotated[annotationKey] = annotations;
+	return annotated;
+}
+/**
 * Propagates annotations from one parser state to another.
 *
 * This is mainly used by parsers that rebuild array states with spread syntax.
@@ -211,4 +229,4 @@ function isInjectedAnnotationWrapper(value) {
 }
 
 //#endregion
-export { annotationKey, annotationStateValueKey, annotationWrapperKey, getAnnotations, inheritAnnotations, injectAnnotations, isInjectedAnnotationWrapper, unwrapInjectedAnnotationWrapper };
+export { annotateFreshArray, annotationKey, annotationStateValueKey, annotationWrapperKey, getAnnotations, inheritAnnotations, injectAnnotations, isInjectedAnnotationWrapper, unwrapInjectedAnnotationWrapper };

package/dist/constructs.cjs

@@ -1436,9 +1436,10 @@ function tuple(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 function merge(...args) {
 	const label = typeof args[0] === "string" ? args[0] : void 0;
 	const lastArg = args[args.length - 1];
-	const options = lastArg && typeof lastArg === "object" && !("parse" in lastArg) && !("complete" in lastArg) ? lastArg : {};
+	const hasOptions = lastArg != null && typeof lastArg === "object" && !("$valueType" in lastArg);
+	const options = hasOptions ? lastArg : {};
 	const startIndex = typeof args[0] === "string" ? 1 : 0;
-	const endIndex = lastArg && typeof lastArg === "object" && !("parse" in lastArg) && !("complete" in lastArg) ? args.length - 1 : args.length;
+	const endIndex = hasOptions ? args.length - 1 : args.length;
 	const rawParsers = args.slice(startIndex, endIndex);
 	const combinedMode = rawParsers.some((p) => p.$mode === "async") ? "async" : "sync";
 	const isAsync = combinedMode === "async";

package/dist/constructs.d.cts

@@ -127,8 +127,9 @@ type OrArityGuard<TParsers extends readonly unknown[]> = IsTuple<TParsers> exten
  * @template TStateB The type of the state used by the second parser.
  * @param a The first {@link Parser} to try.
  * @param b The second {@link Parser} to try.
- * @returns A {@link Parser} that tries to parse using the provided parsers
- *          in order, returning the result of the first successful parser.
+ * @return A {@link Parser} that tries to parse using the provided parsers
+ *         in order, returning the result of the first successful parser.
+ * @since 0.3.0
  */
 declare function or<MA extends Mode, MB extends Mode, TA, TB, TStateA, TStateB>(a: Parser<MA, TA, TStateA>, b: Parser<MB, TB, TStateB>): Parser<CombineModes<readonly [MA, MB]>, TA | TB, undefined | [0, ParserResult<TStateA>] | [1, ParserResult<TStateB>]>;
 /**
@@ -149,6 +150,7 @@ declare function or<MA extends Mode, MB extends Mode, TA, TB, TStateA, TStateB>(
  * @param c The third {@link Parser} to try.
  * @return A {@link Parser} that tries to parse using the provided parsers
  *         in order, returning the result of the first successful parser.
+ * @since 0.3.0
  */
 declare function or<MA extends Mode, MB extends Mode, MC extends Mode, TA, TB, TC, TStateA, TStateB, TStateC>(a: Parser<MA, TA, TStateA>, b: Parser<MB, TB, TStateB>, c: Parser<MC, TC, TStateC>): Parser<CombineModes<readonly [MA, MB, MC]>, TA | TB | TC, undefined | [0, ParserResult<TStateA>] | [1, ParserResult<TStateB>] | [2, ParserResult<TStateC>]>;
 /**
@@ -173,6 +175,7 @@ declare function or<MA extends Mode, MB extends Mode, MC extends Mode, TA, TB, T
  * @param d The fourth {@link Parser} to try.
  * @return A {@link Parser} that tries to parse using the provided parsers
  *         in order, returning the result of the first successful parser.
+ * @since 0.3.0
  */
 declare function or<MA extends Mode, MB extends Mode, MC extends Mode, MD extends Mode, TA, TB, TC, TD, TStateA, TStateB, TStateC, TStateD>(a: Parser<MA, TA, TStateA>, b: Parser<MB, TB, TStateB>, c: Parser<MC, TC, TStateC>, d: Parser<MD, TD, TStateD>): Parser<CombineModes<readonly [MA, MB, MC, MD]>, TA | TB | TC | TD, undefined | [0, ParserResult<TStateA>] | [1, ParserResult<TStateB>] | [2, ParserResult<TStateC>] | [3, ParserResult<TStateD>]>;
 /**
@@ -779,7 +782,7 @@ interface LongestMatchOptions {
   errors?: LongestMatchErrorOptions;
 }
 /**
- * Options for customizing error messages in the {@link longesMatch} parser.
+ * Options for customizing error messages in the {@link longestMatch} parser.
  * @since 0.5.0
  */
 interface LongestMatchErrorOptions {
@@ -883,6 +886,28 @@ declare function longestMatch<const TParsers extends readonly Parser<Mode, unkno
  * @since 0.3.0
  */
 declare function longestMatch<const TParsers extends readonly Parser<Mode, unknown, unknown>[]>(...parsers: TParsers & LongestMatchArityGuard<TParsers>): Parser<CombineModes<{ readonly [K in keyof TParsers]: ExtractMode<TParsers[K]> }>, InferValue<TParsers[number]>, LongestMatchState<TParsers>>;
+/**
+ * Creates a parser that selects the successful branch that consumed
+ * the most input tokens from a homogeneous parser list.
+ *
+ * This overload is intended for spread arrays whose element types are
+ * homogeneous enough that callers only need the shared value type.
+ *
+ * @param parsers Parsers to evaluate and compare by consumed input.
+ * @returns A parser that preserves the shared parser mode and value type.
+ * @since 1.0.0
+ */
+declare function longestMatch<M extends Mode, TValue, TState, const TParsers extends readonly Parser<M, TValue, TState>[]>(...parsers: TParsers & LongestMatchArityGuard<TParsers>): Parser<M, TValue, unknown>;
+/**
+ * Creates a parser that selects the successful branch that consumed
+ * the most input tokens from a homogeneous parser list, with custom
+ * error options.
+ *
+ * @param rest Parsers to compare, followed by error customization options.
+ * @returns A parser that preserves the shared parser mode and value type.
+ * @since 1.0.0
+ */
+declare function longestMatch<M extends Mode, TValue, TState, const TParsers extends readonly Parser<M, TValue, TState>[]>(...rest: [...parsers: TParsers, options: LongestMatchTailOptions] & LongestMatchArityGuard<TParsers>): Parser<M, TValue, unknown>;
 /**
  * Options for the {@link object} parser.
  * @since 0.5.0

package/dist/constructs.d.ts

@@ -127,8 +127,9 @@ type OrArityGuard<TParsers extends readonly unknown[]> = IsTuple<TParsers> exten
  * @template TStateB The type of the state used by the second parser.
  * @param a The first {@link Parser} to try.
  * @param b The second {@link Parser} to try.
- * @returns A {@link Parser} that tries to parse using the provided parsers
- *          in order, returning the result of the first successful parser.
+ * @return A {@link Parser} that tries to parse using the provided parsers
+ *         in order, returning the result of the first successful parser.
+ * @since 0.3.0
  */
 declare function or<MA extends Mode, MB extends Mode, TA, TB, TStateA, TStateB>(a: Parser<MA, TA, TStateA>, b: Parser<MB, TB, TStateB>): Parser<CombineModes<readonly [MA, MB]>, TA | TB, undefined | [0, ParserResult<TStateA>] | [1, ParserResult<TStateB>]>;
 /**
@@ -149,6 +150,7 @@ declare function or<MA extends Mode, MB extends Mode, TA, TB, TStateA, TStateB>(
  * @param c The third {@link Parser} to try.
  * @return A {@link Parser} that tries to parse using the provided parsers
  *         in order, returning the result of the first successful parser.
+ * @since 0.3.0
  */
 declare function or<MA extends Mode, MB extends Mode, MC extends Mode, TA, TB, TC, TStateA, TStateB, TStateC>(a: Parser<MA, TA, TStateA>, b: Parser<MB, TB, TStateB>, c: Parser<MC, TC, TStateC>): Parser<CombineModes<readonly [MA, MB, MC]>, TA | TB | TC, undefined | [0, ParserResult<TStateA>] | [1, ParserResult<TStateB>] | [2, ParserResult<TStateC>]>;
 /**
@@ -173,6 +175,7 @@ declare function or<MA extends Mode, MB extends Mode, MC extends Mode, TA, TB, T
  * @param d The fourth {@link Parser} to try.
  * @return A {@link Parser} that tries to parse using the provided parsers
  *         in order, returning the result of the first successful parser.
+ * @since 0.3.0
  */
 declare function or<MA extends Mode, MB extends Mode, MC extends Mode, MD extends Mode, TA, TB, TC, TD, TStateA, TStateB, TStateC, TStateD>(a: Parser<MA, TA, TStateA>, b: Parser<MB, TB, TStateB>, c: Parser<MC, TC, TStateC>, d: Parser<MD, TD, TStateD>): Parser<CombineModes<readonly [MA, MB, MC, MD]>, TA | TB | TC | TD, undefined | [0, ParserResult<TStateA>] | [1, ParserResult<TStateB>] | [2, ParserResult<TStateC>] | [3, ParserResult<TStateD>]>;
 /**
@@ -779,7 +782,7 @@ interface LongestMatchOptions {
   errors?: LongestMatchErrorOptions;
 }
 /**
- * Options for customizing error messages in the {@link longesMatch} parser.
+ * Options for customizing error messages in the {@link longestMatch} parser.
  * @since 0.5.0
  */
 interface LongestMatchErrorOptions {
@@ -883,6 +886,28 @@ declare function longestMatch<const TParsers extends readonly Parser<Mode, unkno
  * @since 0.3.0
  */
 declare function longestMatch<const TParsers extends readonly Parser<Mode, unknown, unknown>[]>(...parsers: TParsers & LongestMatchArityGuard<TParsers>): Parser<CombineModes<{ readonly [K in keyof TParsers]: ExtractMode<TParsers[K]> }>, InferValue<TParsers[number]>, LongestMatchState<TParsers>>;
+/**
+ * Creates a parser that selects the successful branch that consumed
+ * the most input tokens from a homogeneous parser list.
+ *
+ * This overload is intended for spread arrays whose element types are
+ * homogeneous enough that callers only need the shared value type.
+ *
+ * @param parsers Parsers to evaluate and compare by consumed input.
+ * @returns A parser that preserves the shared parser mode and value type.
+ * @since 1.0.0
+ */
+declare function longestMatch<M extends Mode, TValue, TState, const TParsers extends readonly Parser<M, TValue, TState>[]>(...parsers: TParsers & LongestMatchArityGuard<TParsers>): Parser<M, TValue, unknown>;
+/**
+ * Creates a parser that selects the successful branch that consumed
+ * the most input tokens from a homogeneous parser list, with custom
+ * error options.
+ *
+ * @param rest Parsers to compare, followed by error customization options.
+ * @returns A parser that preserves the shared parser mode and value type.
+ * @since 1.0.0
+ */
+declare function longestMatch<M extends Mode, TValue, TState, const TParsers extends readonly Parser<M, TValue, TState>[]>(...rest: [...parsers: TParsers, options: LongestMatchTailOptions] & LongestMatchArityGuard<TParsers>): Parser<M, TValue, unknown>;
 /**
  * Options for the {@link object} parser.
  * @since 0.5.0

package/dist/constructs.js

@@ -1436,9 +1436,10 @@ function tuple(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 function merge(...args) {
 	const label = typeof args[0] === "string" ? args[0] : void 0;
 	const lastArg = args[args.length - 1];
-	const options = lastArg && typeof lastArg === "object" && !("parse" in lastArg) && !("complete" in lastArg) ? lastArg : {};
+	const hasOptions = lastArg != null && typeof lastArg === "object" && !("$valueType" in lastArg);
+	const options = hasOptions ? lastArg : {};
 	const startIndex = typeof args[0] === "string" ? 1 : 0;
-	const endIndex = lastArg && typeof lastArg === "object" && !("parse" in lastArg) && !("complete" in lastArg) ? args.length - 1 : args.length;
+	const endIndex = hasOptions ? args.length - 1 : args.length;
 	const rawParsers = args.slice(startIndex, endIndex);
 	const combinedMode = rawParsers.some((p) => p.$mode === "async") ? "async" : "sync";
 	const isAsync = combinedMode === "async";

package/dist/context.cjs

@@ -4,8 +4,9 @@
 * Checks whether a context is static (returns annotations without needing
 * parsed results).
 *
-* A context is considered static if `getAnnotations()` called without
-* arguments returns a non-empty annotations object synchronously.
+* A context is considered static if it declares `mode: "static"` or if
+* `getAnnotations()` called without arguments returns a non-empty
+* annotations object synchronously.
 *
 * @param context The source context to check.
 * @returns `true` if the context is static, `false` otherwise.

package/dist/context.d.cts

@@ -154,8 +154,9 @@ interface SourceContext<TRequiredOptions = void> {
  * Checks whether a context is static (returns annotations without needing
  * parsed results).
  *
- * A context is considered static if `getAnnotations()` called without
- * arguments returns a non-empty annotations object synchronously.
+ * A context is considered static if it declares `mode: "static"` or if
+ * `getAnnotations()` called without arguments returns a non-empty
+ * annotations object synchronously.
  *
  * @param context The source context to check.
  * @returns `true` if the context is static, `false` otherwise.

package/dist/context.d.ts

@@ -154,8 +154,9 @@ interface SourceContext<TRequiredOptions = void> {
  * Checks whether a context is static (returns annotations without needing
  * parsed results).
  *
- * A context is considered static if `getAnnotations()` called without
- * arguments returns a non-empty annotations object synchronously.
+ * A context is considered static if it declares `mode: "static"` or if
+ * `getAnnotations()` called without arguments returns a non-empty
+ * annotations object synchronously.
  *
  * @param context The source context to check.
  * @returns `true` if the context is static, `false` otherwise.

package/dist/context.js

@@ -3,8 +3,9 @@
 * Checks whether a context is static (returns annotations without needing
 * parsed results).
 *
-* A context is considered static if `getAnnotations()` called without
-* arguments returns a non-empty annotations object synchronously.
+* A context is considered static if it declares `mode: "static"` or if
+* `getAnnotations()` called without arguments returns a non-empty
+* annotations object synchronously.
 *
 * @param context The source context to check.
 * @returns `true` if the context is static, `false` otherwise.

package/dist/facade.cjs

@@ -339,7 +339,6 @@ function classifyResult(result, args, helpOptionNames, helpCommandNames, version
 		const hasHelpOption = helpOptionNames.some((n) => args.includes(n));
 		const hasHelpCommand = args.length > 0 && helpCommandNames.includes(args[0]);
 		const hasCompletionCommand = args.length > 0 && completionCommandNames.includes(args[0]);
-		if (hasVersionOption && hasHelpOption && !hasVersionCommand && !hasHelpCommand) {}
 		if (hasVersionCommand && hasHelpOption && parsedValue.helpFlag) return {
 			type: "help",
 			commands: [args[0]]
@@ -870,13 +869,8 @@ async function collectPhase1Annotations(contexts, options) {
 	let hasDynamic = false;
 	for (const context of contexts) {
 		const result = context.getAnnotations(void 0, options);
-		if (result instanceof Promise) {
-			hasDynamic = true;
-			annotationsList.push(await result);
-		} else {
-			if (Object.getOwnPropertySymbols(result).length === 0) hasDynamic = true;
-			annotationsList.push(result);
-		}
+		hasDynamic ||= needsTwoPhaseContext(context, result);
+		annotationsList.push(result instanceof Promise ? await result : result);
 	}
 	return {
 		annotations: mergeAnnotations(annotationsList),
@@ -914,7 +908,7 @@ function collectPhase1AnnotationsSync(contexts, options) {
 	for (const context of contexts) {
 		const result = context.getAnnotations(void 0, options);
 		if (result instanceof Promise) throw new Error(`Context ${String(context.id)} returned a Promise in sync mode. Use runWith() or runWithAsync() for async contexts.`);
-		if (Object.getOwnPropertySymbols(result).length === 0) hasDynamic = true;
+		hasDynamic ||= needsTwoPhaseContext(context, result);
 		annotationsList.push(result);
 	}
 	return {
@@ -923,6 +917,18 @@ function collectPhase1AnnotationsSync(contexts, options) {
 	};
 }
 /**
+* Determines whether a context requires a second parse pass.
+*
+* Explicit `mode` declarations take precedence over legacy heuristics so
+* static contexts are not forced into two-phase parsing when they return
+* empty annotations or a Promise.
+*/
+function needsTwoPhaseContext(context, result) {
+	if (context.mode !== void 0) return context.mode === "dynamic";
+	if (result instanceof Promise) return true;
+	return Object.getOwnPropertySymbols(result).length === 0;
+}
+/**
 * Collects annotations from all contexts synchronously.
 *
 * @param contexts Source contexts to collect annotations from.

package/dist/facade.js

@@ -339,7 +339,6 @@ function classifyResult(result, args, helpOptionNames, helpCommandNames, version
 		const hasHelpOption = helpOptionNames.some((n) => args.includes(n));
 		const hasHelpCommand = args.length > 0 && helpCommandNames.includes(args[0]);
 		const hasCompletionCommand = args.length > 0 && completionCommandNames.includes(args[0]);
-		if (hasVersionOption && hasHelpOption && !hasVersionCommand && !hasHelpCommand) {}
 		if (hasVersionCommand && hasHelpOption && parsedValue.helpFlag) return {
 			type: "help",
 			commands: [args[0]]
@@ -870,13 +869,8 @@ async function collectPhase1Annotations(contexts, options) {
 	let hasDynamic = false;
 	for (const context of contexts) {
 		const result = context.getAnnotations(void 0, options);
-		if (result instanceof Promise) {
-			hasDynamic = true;
-			annotationsList.push(await result);
-		} else {
-			if (Object.getOwnPropertySymbols(result).length === 0) hasDynamic = true;
-			annotationsList.push(result);
-		}
+		hasDynamic ||= needsTwoPhaseContext(context, result);
+		annotationsList.push(result instanceof Promise ? await result : result);
 	}
 	return {
 		annotations: mergeAnnotations(annotationsList),
@@ -914,7 +908,7 @@ function collectPhase1AnnotationsSync(contexts, options) {
 	for (const context of contexts) {
 		const result = context.getAnnotations(void 0, options);
 		if (result instanceof Promise) throw new Error(`Context ${String(context.id)} returned a Promise in sync mode. Use runWith() or runWithAsync() for async contexts.`);
-		if (Object.getOwnPropertySymbols(result).length === 0) hasDynamic = true;
+		hasDynamic ||= needsTwoPhaseContext(context, result);
 		annotationsList.push(result);
 	}
 	return {
@@ -923,6 +917,18 @@ function collectPhase1AnnotationsSync(contexts, options) {
 	};
 }
 /**
+* Determines whether a context requires a second parse pass.
+*
+* Explicit `mode` declarations take precedence over legacy heuristics so
+* static contexts are not forced into two-phase parsing when they return
+* empty annotations or a Promise.
+*/
+function needsTwoPhaseContext(context, result) {
+	if (context.mode !== void 0) return context.mode === "dynamic";
+	if (result instanceof Promise) return true;
+	return Object.getOwnPropertySymbols(result).length === 0;
+}
+/**
 * Collects annotations from all contexts synchronously.
 *
 * @param contexts Source contexts to collect annotations from.

package/dist/mode-dispatch.cjs

@@ -18,6 +18,11 @@ function dispatchByMode(mode, syncFn, asyncFn) {
 	if (mode === "async") return asyncFn();
 	return syncFn();
 }
+function wrapForMode(mode, value) {
+	if (mode === "async") return Promise.resolve(value);
+	if (value instanceof Promise) throw new TypeError("Synchronous mode cannot wrap Promise value.");
+	return value;
+}
 /**
 * Maps a mode-wrapped value while preserving its execution mode.
 *
@@ -30,6 +35,7 @@ function dispatchByMode(mode, syncFn, asyncFn) {
 */
 function mapModeValue(mode, value, mapFn) {
 	if (mode === "async") return Promise.resolve(value).then(mapFn);
+	if (value instanceof Promise) throw new TypeError("Synchronous mode cannot map Promise value.");
 	return mapFn(value);
 }
 /**
@@ -50,4 +56,5 @@ function dispatchIterableByMode(mode, syncFn, asyncFn) {
 //#endregion
 exports.dispatchByMode = dispatchByMode;
 exports.dispatchIterableByMode = dispatchIterableByMode;
-exports.mapModeValue = mapModeValue;
+exports.mapModeValue = mapModeValue;
+exports.wrapForMode = wrapForMode;

package/dist/mode-dispatch.d.cts

@@ -0,0 +1,55 @@
+import { Mode, ModeIterable, ModeValue } from "./parser.cjs";
+
+//#region src/mode-dispatch.d.ts
+
+/**
+ * Dispatches to sync or async implementation based on mode.
+ *
+ * This function encapsulates the necessary type assertions when branching
+ * on runtime mode values. TypeScript cannot narrow `ModeValue<M, T>` based
+ * on `mode === "async"` checks, so we must use type assertions.
+ *
+ * @param mode The execution mode.
+ * @param syncFn Function to call for sync execution.
+ * @param asyncFn Function to call for async execution.
+ * @returns The result with correct mode wrapping.
+ * @internal
+ * @since 0.10.0
+ */
+declare function dispatchByMode<M extends Mode, T>(mode: M, syncFn: () => T, asyncFn: () => Promise<T>): ModeValue<M, T>;
+/**
+ * Wraps a value so it matches the parser execution mode.
+ *
+ * @param mode The execution mode.
+ * @param value The value to wrap.
+ * @returns The wrapped value with correct mode semantics.
+ * @internal
+ * @since 1.0.0
+ */
+declare function wrapForMode<T>(mode: "sync", value: T | Promise<T>): T;
+declare function wrapForMode<T>(mode: "async", value: T | Promise<T>): Promise<T>;
+declare function wrapForMode<M extends Mode, T>(mode: M, value: T | Promise<T>): ModeValue<M, T>;
+/**
+ * Maps a mode-wrapped value while preserving its execution mode.
+ *
+ * @param mode The execution mode.
+ * @param value The mode-wrapped value to transform.
+ * @param mapFn Mapping function applied to the unwrapped value.
+ * @returns The mapped value with correct mode wrapping.
+ * @internal
+ * @since 1.0.0
+ */
+declare function mapModeValue<M extends Mode, T, U>(mode: M, value: ModeValue<M, T>, mapFn: (value: T) => U): ModeValue<M, U>;
+/**
+ * Dispatches iterable to sync or async implementation based on mode.
+ *
+ * @param mode The execution mode.
+ * @param syncFn Function returning sync iterable.
+ * @param asyncFn Function returning async iterable.
+ * @returns The iterable with correct mode wrapping.
+ * @internal
+ * @since 0.10.0
+ */
+declare function dispatchIterableByMode<M extends Mode, T>(mode: M, syncFn: () => Iterable<T>, asyncFn: () => AsyncIterable<T>): ModeIterable<M, T>;
+//#endregion
+export { dispatchByMode, dispatchIterableByMode, mapModeValue, wrapForMode };

package/dist/mode-dispatch.d.ts

@@ -0,0 +1,55 @@
+import { Mode, ModeIterable, ModeValue } from "./parser.js";
+
+//#region src/mode-dispatch.d.ts
+
+/**
+ * Dispatches to sync or async implementation based on mode.
+ *
+ * This function encapsulates the necessary type assertions when branching
+ * on runtime mode values. TypeScript cannot narrow `ModeValue<M, T>` based
+ * on `mode === "async"` checks, so we must use type assertions.
+ *
+ * @param mode The execution mode.
+ * @param syncFn Function to call for sync execution.
+ * @param asyncFn Function to call for async execution.
+ * @returns The result with correct mode wrapping.
+ * @internal
+ * @since 0.10.0
+ */
+declare function dispatchByMode<M extends Mode, T>(mode: M, syncFn: () => T, asyncFn: () => Promise<T>): ModeValue<M, T>;
+/**
+ * Wraps a value so it matches the parser execution mode.
+ *
+ * @param mode The execution mode.
+ * @param value The value to wrap.
+ * @returns The wrapped value with correct mode semantics.
+ * @internal
+ * @since 1.0.0
+ */
+declare function wrapForMode<T>(mode: "sync", value: T | Promise<T>): T;
+declare function wrapForMode<T>(mode: "async", value: T | Promise<T>): Promise<T>;
+declare function wrapForMode<M extends Mode, T>(mode: M, value: T | Promise<T>): ModeValue<M, T>;
+/**
+ * Maps a mode-wrapped value while preserving its execution mode.
+ *
+ * @param mode The execution mode.
+ * @param value The mode-wrapped value to transform.
+ * @param mapFn Mapping function applied to the unwrapped value.
+ * @returns The mapped value with correct mode wrapping.
+ * @internal
+ * @since 1.0.0
+ */
+declare function mapModeValue<M extends Mode, T, U>(mode: M, value: ModeValue<M, T>, mapFn: (value: T) => U): ModeValue<M, U>;
+/**
+ * Dispatches iterable to sync or async implementation based on mode.
+ *
+ * @param mode The execution mode.
+ * @param syncFn Function returning sync iterable.
+ * @param asyncFn Function returning async iterable.
+ * @returns The iterable with correct mode wrapping.
+ * @internal
+ * @since 0.10.0
+ */
+declare function dispatchIterableByMode<M extends Mode, T>(mode: M, syncFn: () => Iterable<T>, asyncFn: () => AsyncIterable<T>): ModeIterable<M, T>;
+//#endregion
+export { dispatchByMode, dispatchIterableByMode, mapModeValue, wrapForMode };

package/dist/mode-dispatch.js

@@ -17,6 +17,11 @@ function dispatchByMode(mode, syncFn, asyncFn) {
 	if (mode === "async") return asyncFn();
 	return syncFn();
 }
+function wrapForMode(mode, value) {
+	if (mode === "async") return Promise.resolve(value);
+	if (value instanceof Promise) throw new TypeError("Synchronous mode cannot wrap Promise value.");
+	return value;
+}
 /**
 * Maps a mode-wrapped value while preserving its execution mode.
 *
@@ -29,6 +34,7 @@ function dispatchByMode(mode, syncFn, asyncFn) {
 */
 function mapModeValue(mode, value, mapFn) {
 	if (mode === "async") return Promise.resolve(value).then(mapFn);
+	if (value instanceof Promise) throw new TypeError("Synchronous mode cannot map Promise value.");
 	return mapFn(value);
 }
 /**
@@ -47,4 +53,4 @@ function dispatchIterableByMode(mode, syncFn, asyncFn) {
 }
 
 //#endregion
-export { dispatchByMode, dispatchIterableByMode, mapModeValue };
+export { dispatchByMode, dispatchIterableByMode, mapModeValue, wrapForMode };

package/dist/modifiers.cjs

@@ -411,13 +411,6 @@ function multiple(parser, options = {}) {
 	const syncParser = parser;
 	const { min = 0, max = Infinity } = options;
 	const unwrapInjectedWrapper = require_annotations.unwrapInjectedAnnotationWrapper;
-	const annotateFreshArray = (source, target) => {
-		const annotations = require_annotations.getAnnotations(source);
-		if (annotations === void 0) return target;
-		const annotated = target;
-		annotated[require_annotations.annotationKey] = annotations;
-		return annotated;
-	};
 	const completeSyncWithUnwrappedFallback = (state) => {
 		try {
 			return syncParser.complete(state);
@@ -488,7 +481,7 @@ function multiple(parser, options = {}) {
 			success: true,
 			next: {
 				...result.next,
-				state: annotateFreshArray(context.state, [...added ? context.state : context.state.slice(0, -1), nextItemState])
+				state: require_annotations.annotateFreshArray(context.state, [...added ? context.state : context.state.slice(0, -1), nextItemState])
 			},
 			consumed: result.consumed
 		};
@@ -515,7 +508,7 @@ function multiple(parser, options = {}) {
 			success: true,
 			next: {
 				...result.next,
-				state: annotateFreshArray(context.state, [...added ? context.state : context.state.slice(0, -1), nextItemState])
+				state: require_annotations.annotateFreshArray(context.state, [...added ? context.state : context.state.slice(0, -1), nextItemState])
 			},
 			consumed: result.consumed
 		};

package/dist/modifiers.js

@@ -1,4 +1,4 @@
-import { annotationKey, getAnnotations, inheritAnnotations, isInjectedAnnotationWrapper, unwrapInjectedAnnotationWrapper } from "./annotations.js";
+import { annotateFreshArray, inheritAnnotations, isInjectedAnnotationWrapper, unwrapInjectedAnnotationWrapper } from "./annotations.js";
 import { formatMessage, message, text } from "./message.js";
 import { createDependencySourceState, dependencyId, isDependencySourceState, isPendingDependencySourceState, isWrappedDependencySource, transformsDependencyValue, transformsDependencyValueMarker, wrappedDependencySourceMarker } from "./dependency.js";
 import { dispatchByMode, dispatchIterableByMode, mapModeValue } from "./mode-dispatch.js";
@@ -411,13 +411,6 @@ function multiple(parser, options = {}) {
 	const syncParser = parser;
 	const { min = 0, max = Infinity } = options;
 	const unwrapInjectedWrapper = unwrapInjectedAnnotationWrapper;
-	const annotateFreshArray = (source, target) => {
-		const annotations = getAnnotations(source);
-		if (annotations === void 0) return target;
-		const annotated = target;
-		annotated[annotationKey] = annotations;
-		return annotated;
-	};
 	const completeSyncWithUnwrappedFallback = (state) => {
 		try {
 			return syncParser.complete(state);

package/dist/primitives.cjs

@@ -1116,13 +1116,6 @@ function passThrough(options = {}) {
 	const format = options.format ?? "equalsOnly";
 	const optionPattern = /^-[a-z0-9-]|^--[a-z0-9-]+/i;
 	const equalsOptionPattern = /^--[a-z0-9-]+=/i;
-	const annotateFreshArray = (source, target) => {
-		const annotations = require_annotations.getAnnotations(source);
-		if (annotations === void 0) return target;
-		const annotated = target;
-		annotated[require_annotations.annotationKey] = annotations;
-		return annotated;
-	};
 	return {
 		$valueType: [],
 		$stateType: [],
@@ -1147,7 +1140,7 @@ function passThrough(options = {}) {
 					next: {
 						...context,
 						buffer: [],
-						state: annotateFreshArray(context.state, [...context.state, ...captured])
+						state: require_annotations.annotateFreshArray(context.state, [...context.state, ...captured])
 					},
 					consumed: captured
 				};
@@ -1168,7 +1161,7 @@ function passThrough(options = {}) {
 					next: {
 						...context,
 						buffer: context.buffer.slice(1),
-						state: annotateFreshArray(context.state, [...context.state, token])
+						state: require_annotations.annotateFreshArray(context.state, [...context.state, token])
 					},
 					consumed: [token]
 				};
@@ -1184,7 +1177,7 @@ function passThrough(options = {}) {
 					next: {
 						...context,
 						buffer: context.buffer.slice(1),
-						state: annotateFreshArray(context.state, [...context.state, token])
+						state: require_annotations.annotateFreshArray(context.state, [...context.state, token])
 					},
 					consumed: [token]
 				};
@@ -1194,7 +1187,7 @@ function passThrough(options = {}) {
 					next: {
 						...context,
 						buffer: context.buffer.slice(2),
-						state: annotateFreshArray(context.state, [
+						state: require_annotations.annotateFreshArray(context.state, [
 							...context.state,
 							token,
 							nextToken
@@ -1207,7 +1200,7 @@ function passThrough(options = {}) {
 					next: {
 						...context,
 						buffer: context.buffer.slice(1),
-						state: annotateFreshArray(context.state, [...context.state, token])
+						state: require_annotations.annotateFreshArray(context.state, [...context.state, token])
 					},
 					consumed: [token]
 				};

package/dist/primitives.js

@@ -1,4 +1,4 @@
-import { annotationKey, getAnnotations } from "./annotations.js";
+import { annotateFreshArray, getAnnotations } from "./annotations.js";
 import { message, metavar, optionName, optionNames, text, valueSet } from "./message.js";
 import { createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, dependencyId, getDefaultValuesFunction, getDependencyIds, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isPendingDependencySourceState, suggestWithDependency } from "./dependency.js";
 import { dispatchIterableByMode } from "./mode-dispatch.js";
@@ -1116,13 +1116,6 @@ function passThrough(options = {}) {
 	const format = options.format ?? "equalsOnly";
 	const optionPattern = /^-[a-z0-9-]|^--[a-z0-9-]+/i;
 	const equalsOptionPattern = /^--[a-z0-9-]+=/i;
-	const annotateFreshArray = (source, target) => {
-		const annotations = getAnnotations(source);
-		if (annotations === void 0) return target;
-		const annotated = target;
-		annotated[annotationKey] = annotations;
-		return annotated;
-	};
 	return {
 		$valueType: [],
 		$stateType: [],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.0.0-dev.552+30c7ea22",
+  "version": "1.0.0-dev.556+f691dcba",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",
@@ -115,6 +115,14 @@
       "import": "./dist/message.js",
       "require": "./dist/message.cjs"
     },
+    "./mode-dispatch": {
+      "types": {
+        "import": "./dist/mode-dispatch.d.ts",
+        "require": "./dist/mode-dispatch.d.cts"
+      },
+      "import": "./dist/mode-dispatch.js",
+      "require": "./dist/mode-dispatch.cjs"
+    },
     "./modifiers": {
       "types": {
         "import": "./dist/modifiers.d.ts",