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

package/dist/annotations.cjs

@@ -16,6 +16,29 @@
 */
 const annotationKey = Symbol.for("@optique/core/parser/annotation");
 /**
+* Internal key for preserving primitive parser state values when annotations
+* are injected into non-object states.
+* @internal
+*/
+const annotationStateValueKey = Symbol.for("@optique/core/parser/annotationStateValue");
+/**
+* Internal marker key that indicates annotation wrapping was injected by
+* Optique internals for non-object states.
+* @internal
+*/
+const annotationWrapperKey = Symbol.for("@optique/core/parser/annotationWrapper");
+/**
+* Internal symbol keys that define Optique's primitive-state annotation
+* wrapper shape.
+* @internal
+*/
+const annotationWrapperKeys = new Set([
+	annotationKey,
+	annotationStateValueKey,
+	annotationWrapperKey
+]);
+const injectedAnnotationWrappers = /* @__PURE__ */ new WeakSet();
+/**
 * Extracts annotations from parser state.
 *
 * @param state Parser state that may contain annotations
@@ -35,7 +58,165 @@ function getAnnotations(state) {
 	if (annotations != null && typeof annotations === "object") return annotations;
 	return void 0;
 }
+/**
+* Propagates annotations from one parser state to another.
+*
+* This is mainly used by parsers that rebuild array states with spread syntax.
+* Array spread copies elements but drops custom symbol properties, so we need
+* to reattach annotations explicitly when present.
+*
+* @param source The original state that may carry annotations.
+* @param target The new state to receive annotations.
+* @returns The target state, with annotations copied when available.
+* @internal
+*/
+function inheritAnnotations(source, target) {
+	const annotations = getAnnotations(source);
+	if (annotations === void 0) return target;
+	if (target == null || typeof target !== "object") return injectAnnotations(target, annotations);
+	if (isInjectedAnnotationWrapper(target)) return injectAnnotations(target, annotations);
+	if (Array.isArray(target)) {
+		const cloned$1 = [...target];
+		cloned$1[annotationKey] = annotations;
+		return cloned$1;
+	}
+	if (target instanceof Date) {
+		const cloned$1 = new Date(target.getTime());
+		cloned$1[annotationKey] = annotations;
+		return cloned$1;
+	}
+	if (target instanceof Map) {
+		const cloned$1 = new Map(target);
+		cloned$1[annotationKey] = annotations;
+		return cloned$1;
+	}
+	if (target instanceof Set) {
+		const cloned$1 = new Set(target);
+		cloned$1[annotationKey] = annotations;
+		return cloned$1;
+	}
+	if (target instanceof RegExp) {
+		const cloned$1 = new RegExp(target);
+		cloned$1[annotationKey] = annotations;
+		return cloned$1;
+	}
+	if (Object.getPrototypeOf(target) !== Object.prototype && Object.getPrototypeOf(target) !== null) return target;
+	const cloned = Object.create(Object.getPrototypeOf(target), Object.getOwnPropertyDescriptors(target));
+	cloned[annotationKey] = annotations;
+	return cloned;
+}
+/**
+* Injects annotations into parser state while preserving state shape.
+*
+* - Primitive, null, and undefined states are wrapped with internal metadata.
+* - Array states are cloned and annotated without mutating the original.
+* - Plain object states are shallow-cloned with annotations attached.
+* - Built-in object states (Date/Map/Set/RegExp) are cloned by constructor.
+* - Other non-plain object states are cloned via prototype/descriptors.
+*
+* @param state The parser state to annotate.
+* @param annotations The annotations to inject.
+* @returns Annotated state.
+* @internal
+*/
+function injectAnnotations(state, annotations) {
+	if (state == null || typeof state !== "object") {
+		const wrapper = {};
+		Object.defineProperties(wrapper, {
+			[annotationKey]: {
+				value: annotations,
+				enumerable: true,
+				writable: true,
+				configurable: true
+			},
+			[annotationStateValueKey]: {
+				value: state,
+				enumerable: false,
+				writable: true,
+				configurable: true
+			},
+			[annotationWrapperKey]: {
+				value: true,
+				enumerable: false,
+				writable: true,
+				configurable: true
+			}
+		});
+		injectedAnnotationWrappers.add(wrapper);
+		return wrapper;
+	}
+	if (Array.isArray(state)) {
+		const cloned$1 = [...state];
+		cloned$1[annotationKey] = annotations;
+		return cloned$1;
+	}
+	if (isInjectedAnnotationWrapper(state)) {
+		state[annotationKey] = annotations;
+		return state;
+	}
+	if (state instanceof Date) {
+		const cloned$1 = new Date(state.getTime());
+		cloned$1[annotationKey] = annotations;
+		return cloned$1;
+	}
+	if (state instanceof Map) {
+		const cloned$1 = new Map(state);
+		cloned$1[annotationKey] = annotations;
+		return cloned$1;
+	}
+	if (state instanceof Set) {
+		const cloned$1 = new Set(state);
+		cloned$1[annotationKey] = annotations;
+		return cloned$1;
+	}
+	if (state instanceof RegExp) {
+		const cloned$1 = new RegExp(state);
+		cloned$1[annotationKey] = annotations;
+		return cloned$1;
+	}
+	const proto = Object.getPrototypeOf(state);
+	if (proto === Object.prototype || proto === null) return {
+		...state,
+		[annotationKey]: annotations
+	};
+	const cloned = Object.create(proto, Object.getOwnPropertyDescriptors(state));
+	cloned[annotationKey] = annotations;
+	return cloned;
+}
+/**
+* Unwraps a primitive-state annotation wrapper injected by Optique internals.
+*
+* @param value Value to potentially unwrap.
+* @returns The unwrapped primitive value when the input is an injected wrapper;
+*          otherwise the original value.
+* @internal
+*/
+function unwrapInjectedAnnotationWrapper(value) {
+	if (value == null || typeof value !== "object") return value;
+	const valueRecord = value;
+	if (valueRecord[annotationWrapperKey] !== true) return value;
+	const ownKeys = Reflect.ownKeys(valueRecord);
+	if (ownKeys.length === 3 && ownKeys.every((key) => annotationWrapperKeys.has(key)) && isInjectedAnnotationWrapper(value)) return valueRecord[annotationStateValueKey];
+	return value;
+}
+/**
+* Returns whether the given value is an internal primitive-state annotation
+* wrapper that was injected by Optique.
+*
+* @param value Value to check.
+* @returns `true` if the value is an injected internal wrapper.
+* @internal
+*/
+function isInjectedAnnotationWrapper(value) {
+	return value != null && typeof value === "object" && injectedAnnotationWrappers.has(value);
+}
 
 //#endregion
 exports.annotationKey = annotationKey;
-exports.getAnnotations = getAnnotations;
+exports.annotationStateValueKey = annotationStateValueKey;
+exports.annotationWrapperKey = annotationWrapperKey;
+exports.getAnnotations = getAnnotations;
+exports.inheritAnnotations = inheritAnnotations;
+exports.injectAnnotations = injectAnnotations;
+exports.isInjectedAnnotationWrapper = isInjectedAnnotationWrapper;
+exports.unwrapInjectedAnnotationWrapper = unwrapInjectedAnnotationWrapper;

package/dist/annotations.d.cts

@@ -14,6 +14,18 @@
  * @since 0.10.0
  */
 declare const annotationKey: unique symbol;
+/**
+ * Internal key for preserving primitive parser state values when annotations
+ * are injected into non-object states.
+ * @internal
+ */
+declare const annotationStateValueKey: unique symbol;
+/**
+ * Internal marker key that indicates annotation wrapping was injected by
+ * Optique internals for non-object states.
+ * @internal
+ */
+declare const annotationWrapperKey: unique symbol;
 /**
  * Annotations that can be passed to parsers during execution.
  * Allows external packages to provide additional data that parsers can access
@@ -56,5 +68,51 @@ interface ParseOptions {
  * ```
  */
 declare function getAnnotations(state: unknown): Annotations | undefined;
+/**
+ * Propagates annotations from one parser state to another.
+ *
+ * This is mainly used by parsers that rebuild array states with spread syntax.
+ * Array spread copies elements but drops custom symbol properties, so we need
+ * to reattach annotations explicitly when present.
+ *
+ * @param source The original state that may carry annotations.
+ * @param target The new state to receive annotations.
+ * @returns The target state, with annotations copied when available.
+ * @internal
+ */
+declare function inheritAnnotations<T>(source: unknown, target: T): T;
+/**
+ * Injects annotations into parser state while preserving state shape.
+ *
+ * - Primitive, null, and undefined states are wrapped with internal metadata.
+ * - Array states are cloned and annotated without mutating the original.
+ * - Plain object states are shallow-cloned with annotations attached.
+ * - Built-in object states (Date/Map/Set/RegExp) are cloned by constructor.
+ * - Other non-plain object states are cloned via prototype/descriptors.
+ *
+ * @param state The parser state to annotate.
+ * @param annotations The annotations to inject.
+ * @returns Annotated state.
+ * @internal
+ */
+declare function injectAnnotations<TState>(state: TState, annotations: Annotations): TState;
+/**
+ * Unwraps a primitive-state annotation wrapper injected by Optique internals.
+ *
+ * @param value Value to potentially unwrap.
+ * @returns The unwrapped primitive value when the input is an injected wrapper;
+ *          otherwise the original value.
+ * @internal
+ */
+declare function unwrapInjectedAnnotationWrapper<T>(value: T): T;
+/**
+ * Returns whether the given value is an internal primitive-state annotation
+ * wrapper that was injected by Optique.
+ *
+ * @param value Value to check.
+ * @returns `true` if the value is an injected internal wrapper.
+ * @internal
+ */
+declare function isInjectedAnnotationWrapper(value: unknown): boolean;
 //#endregion
-export { Annotations, ParseOptions, annotationKey, getAnnotations };
+export { Annotations, ParseOptions, annotationKey, annotationStateValueKey, annotationWrapperKey, getAnnotations, inheritAnnotations, injectAnnotations, isInjectedAnnotationWrapper, unwrapInjectedAnnotationWrapper };

package/dist/annotations.d.ts

@@ -14,6 +14,18 @@
  * @since 0.10.0
  */
 declare const annotationKey: unique symbol;
+/**
+ * Internal key for preserving primitive parser state values when annotations
+ * are injected into non-object states.
+ * @internal
+ */
+declare const annotationStateValueKey: unique symbol;
+/**
+ * Internal marker key that indicates annotation wrapping was injected by
+ * Optique internals for non-object states.
+ * @internal
+ */
+declare const annotationWrapperKey: unique symbol;
 /**
  * Annotations that can be passed to parsers during execution.
  * Allows external packages to provide additional data that parsers can access
@@ -56,5 +68,51 @@ interface ParseOptions {
  * ```
  */
 declare function getAnnotations(state: unknown): Annotations | undefined;
+/**
+ * Propagates annotations from one parser state to another.
+ *
+ * This is mainly used by parsers that rebuild array states with spread syntax.
+ * Array spread copies elements but drops custom symbol properties, so we need
+ * to reattach annotations explicitly when present.
+ *
+ * @param source The original state that may carry annotations.
+ * @param target The new state to receive annotations.
+ * @returns The target state, with annotations copied when available.
+ * @internal
+ */
+declare function inheritAnnotations<T>(source: unknown, target: T): T;
+/**
+ * Injects annotations into parser state while preserving state shape.
+ *
+ * - Primitive, null, and undefined states are wrapped with internal metadata.
+ * - Array states are cloned and annotated without mutating the original.
+ * - Plain object states are shallow-cloned with annotations attached.
+ * - Built-in object states (Date/Map/Set/RegExp) are cloned by constructor.
+ * - Other non-plain object states are cloned via prototype/descriptors.
+ *
+ * @param state The parser state to annotate.
+ * @param annotations The annotations to inject.
+ * @returns Annotated state.
+ * @internal
+ */
+declare function injectAnnotations<TState>(state: TState, annotations: Annotations): TState;
+/**
+ * Unwraps a primitive-state annotation wrapper injected by Optique internals.
+ *
+ * @param value Value to potentially unwrap.
+ * @returns The unwrapped primitive value when the input is an injected wrapper;
+ *          otherwise the original value.
+ * @internal
+ */
+declare function unwrapInjectedAnnotationWrapper<T>(value: T): T;
+/**
+ * Returns whether the given value is an internal primitive-state annotation
+ * wrapper that was injected by Optique.
+ *
+ * @param value Value to check.
+ * @returns `true` if the value is an injected internal wrapper.
+ * @internal
+ */
+declare function isInjectedAnnotationWrapper(value: unknown): boolean;
 //#endregion
-export { Annotations, ParseOptions, annotationKey, getAnnotations };
+export { Annotations, ParseOptions, annotationKey, annotationStateValueKey, annotationWrapperKey, getAnnotations, inheritAnnotations, injectAnnotations, isInjectedAnnotationWrapper, unwrapInjectedAnnotationWrapper };

package/dist/annotations.js

@@ -15,6 +15,29 @@
 */
 const annotationKey = Symbol.for("@optique/core/parser/annotation");
 /**
+* Internal key for preserving primitive parser state values when annotations
+* are injected into non-object states.
+* @internal
+*/
+const annotationStateValueKey = Symbol.for("@optique/core/parser/annotationStateValue");
+/**
+* Internal marker key that indicates annotation wrapping was injected by
+* Optique internals for non-object states.
+* @internal
+*/
+const annotationWrapperKey = Symbol.for("@optique/core/parser/annotationWrapper");
+/**
+* Internal symbol keys that define Optique's primitive-state annotation
+* wrapper shape.
+* @internal
+*/
+const annotationWrapperKeys = new Set([
+	annotationKey,
+	annotationStateValueKey,
+	annotationWrapperKey
+]);
+const injectedAnnotationWrappers = /* @__PURE__ */ new WeakSet();
+/**
 * Extracts annotations from parser state.
 *
 * @param state Parser state that may contain annotations
@@ -34,6 +57,158 @@ function getAnnotations(state) {
 	if (annotations != null && typeof annotations === "object") return annotations;
 	return void 0;
 }
+/**
+* Propagates annotations from one parser state to another.
+*
+* This is mainly used by parsers that rebuild array states with spread syntax.
+* Array spread copies elements but drops custom symbol properties, so we need
+* to reattach annotations explicitly when present.
+*
+* @param source The original state that may carry annotations.
+* @param target The new state to receive annotations.
+* @returns The target state, with annotations copied when available.
+* @internal
+*/
+function inheritAnnotations(source, target) {
+	const annotations = getAnnotations(source);
+	if (annotations === void 0) return target;
+	if (target == null || typeof target !== "object") return injectAnnotations(target, annotations);
+	if (isInjectedAnnotationWrapper(target)) return injectAnnotations(target, annotations);
+	if (Array.isArray(target)) {
+		const cloned$1 = [...target];
+		cloned$1[annotationKey] = annotations;
+		return cloned$1;
+	}
+	if (target instanceof Date) {
+		const cloned$1 = new Date(target.getTime());
+		cloned$1[annotationKey] = annotations;
+		return cloned$1;
+	}
+	if (target instanceof Map) {
+		const cloned$1 = new Map(target);
+		cloned$1[annotationKey] = annotations;
+		return cloned$1;
+	}
+	if (target instanceof Set) {
+		const cloned$1 = new Set(target);
+		cloned$1[annotationKey] = annotations;
+		return cloned$1;
+	}
+	if (target instanceof RegExp) {
+		const cloned$1 = new RegExp(target);
+		cloned$1[annotationKey] = annotations;
+		return cloned$1;
+	}
+	if (Object.getPrototypeOf(target) !== Object.prototype && Object.getPrototypeOf(target) !== null) return target;
+	const cloned = Object.create(Object.getPrototypeOf(target), Object.getOwnPropertyDescriptors(target));
+	cloned[annotationKey] = annotations;
+	return cloned;
+}
+/**
+* Injects annotations into parser state while preserving state shape.
+*
+* - Primitive, null, and undefined states are wrapped with internal metadata.
+* - Array states are cloned and annotated without mutating the original.
+* - Plain object states are shallow-cloned with annotations attached.
+* - Built-in object states (Date/Map/Set/RegExp) are cloned by constructor.
+* - Other non-plain object states are cloned via prototype/descriptors.
+*
+* @param state The parser state to annotate.
+* @param annotations The annotations to inject.
+* @returns Annotated state.
+* @internal
+*/
+function injectAnnotations(state, annotations) {
+	if (state == null || typeof state !== "object") {
+		const wrapper = {};
+		Object.defineProperties(wrapper, {
+			[annotationKey]: {
+				value: annotations,
+				enumerable: true,
+				writable: true,
+				configurable: true
+			},
+			[annotationStateValueKey]: {
+				value: state,
+				enumerable: false,
+				writable: true,
+				configurable: true
+			},
+			[annotationWrapperKey]: {
+				value: true,
+				enumerable: false,
+				writable: true,
+				configurable: true
+			}
+		});
+		injectedAnnotationWrappers.add(wrapper);
+		return wrapper;
+	}
+	if (Array.isArray(state)) {
+		const cloned$1 = [...state];
+		cloned$1[annotationKey] = annotations;
+		return cloned$1;
+	}
+	if (isInjectedAnnotationWrapper(state)) {
+		state[annotationKey] = annotations;
+		return state;
+	}
+	if (state instanceof Date) {
+		const cloned$1 = new Date(state.getTime());
+		cloned$1[annotationKey] = annotations;
+		return cloned$1;
+	}
+	if (state instanceof Map) {
+		const cloned$1 = new Map(state);
+		cloned$1[annotationKey] = annotations;
+		return cloned$1;
+	}
+	if (state instanceof Set) {
+		const cloned$1 = new Set(state);
+		cloned$1[annotationKey] = annotations;
+		return cloned$1;
+	}
+	if (state instanceof RegExp) {
+		const cloned$1 = new RegExp(state);
+		cloned$1[annotationKey] = annotations;
+		return cloned$1;
+	}
+	const proto = Object.getPrototypeOf(state);
+	if (proto === Object.prototype || proto === null) return {
+		...state,
+		[annotationKey]: annotations
+	};
+	const cloned = Object.create(proto, Object.getOwnPropertyDescriptors(state));
+	cloned[annotationKey] = annotations;
+	return cloned;
+}
+/**
+* Unwraps a primitive-state annotation wrapper injected by Optique internals.
+*
+* @param value Value to potentially unwrap.
+* @returns The unwrapped primitive value when the input is an injected wrapper;
+*          otherwise the original value.
+* @internal
+*/
+function unwrapInjectedAnnotationWrapper(value) {
+	if (value == null || typeof value !== "object") return value;
+	const valueRecord = value;
+	if (valueRecord[annotationWrapperKey] !== true) return value;
+	const ownKeys = Reflect.ownKeys(valueRecord);
+	if (ownKeys.length === 3 && ownKeys.every((key) => annotationWrapperKeys.has(key)) && isInjectedAnnotationWrapper(value)) return valueRecord[annotationStateValueKey];
+	return value;
+}
+/**
+* Returns whether the given value is an internal primitive-state annotation
+* wrapper that was injected by Optique.
+*
+* @param value Value to check.
+* @returns `true` if the value is an injected internal wrapper.
+* @internal
+*/
+function isInjectedAnnotationWrapper(value) {
+	return value != null && typeof value === "object" && injectedAnnotationWrappers.has(value);
+}
 
 //#endregion
-export { annotationKey, getAnnotations };
+export { annotationKey, annotationStateValueKey, annotationWrapperKey, getAnnotations, inheritAnnotations, injectAnnotations, isInjectedAnnotationWrapper, unwrapInjectedAnnotationWrapper };

package/dist/constructs.cjs

@@ -837,8 +837,11 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 	const parserKeys = Reflect.ownKeys(parsers);
 	const parserPairs = parserKeys.map((k) => [k, parsers[k]]);
 	parserPairs.sort(([_, parserA], [__, parserB]) => parserB.priority - parserA.priority);
-	const initialState = {};
-	for (const key of parserKeys) initialState[key] = parsers[key].initialState;
+	const createInitialState = () => {
+		const state = {};
+		for (const key of parserKeys) state[key] = parsers[key].initialState;
+		return state;
+	};
 	if (!options.allowDuplicates) checkDuplicateOptionNames(parserPairs.map(([field, parser]) => [field, parser.usage]));
 	const noMatchContext = analyzeNoMatchContext(parserKeys.map((k) => parsers[k]));
 	const combinedMode = parserKeys.some((k) => parsers[k].$mode === "async") ? "async" : "sync";
@@ -974,7 +977,9 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 		$stateType: [],
 		priority: Math.max(...parserKeys.map((k) => parsers[k].priority)),
 		usage: applyHiddenToUsage(parserPairs.flatMap(([_, p]) => p.usage), options.hidden),
-		initialState,
+		get initialState() {
+			return createInitialState();
+		},
 		parse(context) {
 			return require_mode_dispatch.dispatchByMode(combinedMode, () => parseSync(context), () => parseAsync(context));
 		},

package/dist/constructs.js

@@ -837,8 +837,11 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 	const parserKeys = Reflect.ownKeys(parsers);
 	const parserPairs = parserKeys.map((k) => [k, parsers[k]]);
 	parserPairs.sort(([_, parserA], [__, parserB]) => parserB.priority - parserA.priority);
-	const initialState = {};
-	for (const key of parserKeys) initialState[key] = parsers[key].initialState;
+	const createInitialState = () => {
+		const state = {};
+		for (const key of parserKeys) state[key] = parsers[key].initialState;
+		return state;
+	};
 	if (!options.allowDuplicates) checkDuplicateOptionNames(parserPairs.map(([field, parser]) => [field, parser.usage]));
 	const noMatchContext = analyzeNoMatchContext(parserKeys.map((k) => parsers[k]));
 	const combinedMode = parserKeys.some((k) => parsers[k].$mode === "async") ? "async" : "sync";
@@ -974,7 +977,9 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 		$stateType: [],
 		priority: Math.max(...parserKeys.map((k) => parsers[k].priority)),
 		usage: applyHiddenToUsage(parserPairs.flatMap(([_, p]) => p.usage), options.hidden),
-		initialState,
+		get initialState() {
+			return createInitialState();
+		},
 		parse(context) {
 			return dispatchByMode(combinedMode, () => parseSync(context), () => parseAsync(context));
 		},

package/dist/facade.cjs

@@ -1122,10 +1122,7 @@ function runWithAsync(parser, programName, contexts, options) {
 * @returns A new parser with annotations in its initial state.
 */
 function injectAnnotationsIntoParser(parser, annotations) {
-	const newInitialState = {
-		...typeof parser.initialState === "object" && parser.initialState !== null ? parser.initialState : {},
-		[require_annotations.annotationKey]: annotations
-	};
+	const newInitialState = require_annotations.injectAnnotations(parser.initialState, annotations);
 	return {
 		...parser,
 		initialState: newInitialState

package/dist/facade.js

@@ -1,4 +1,4 @@
-import { annotationKey } from "./annotations.js";
+import { injectAnnotations } from "./annotations.js";
 import { commandLine, formatMessage, lineBreak, message, optionName, text, value } from "./message.js";
 import { bash, fish, nu, pwsh, zsh } from "./completion.js";
 import { dispatchByMode } from "./mode-dispatch.js";
@@ -1122,10 +1122,7 @@ function runWithAsync(parser, programName, contexts, options) {
 * @returns A new parser with annotations in its initial state.
 */
 function injectAnnotationsIntoParser(parser, annotations) {
-	const newInitialState = {
-		...typeof parser.initialState === "object" && parser.initialState !== null ? parser.initialState : {},
-		[annotationKey]: annotations
-	};
+	const newInitialState = injectAnnotations(parser.initialState, annotations);
 	return {
 		...parser,
 		initialState: newInitialState