@optique/core 1.0.0-dev.1852 → 1.0.0-dev.1856

package/dist/annotations.cjs

@@ -81,6 +81,29 @@ function defineProtectedDataProperty(context, target, key, descriptor) {
 		set: () => throwReadonlyAnnotationMutation()
 	});
 }
+function copyRegExpMetadata(source, target, transformValue) {
+	const sourcePrototype = Object.getPrototypeOf(source);
+	if (Object.getPrototypeOf(target) !== sourcePrototype) Object.setPrototypeOf(target, sourcePrototype);
+	for (const key of Reflect.ownKeys(source)) {
+		if (key === "lastIndex") continue;
+		const descriptor = Object.getOwnPropertyDescriptor(source, key);
+		if (descriptor == null) continue;
+		if ("value" in descriptor && transformValue != null) {
+			Object.defineProperty(target, key, {
+				...descriptor,
+				value: transformValue(descriptor.value)
+			});
+			continue;
+		}
+		Object.defineProperty(target, key, descriptor);
+	}
+	target.lastIndex = source.lastIndex;
+}
+function cloneRegExpShape(source) {
+	const cloned = new RegExp(source);
+	copyRegExpMetadata(source, cloned);
+	return cloned;
+}
 function createProtectedObjectView(target, context) {
 	if (Array.isArray(target)) {
 		const view$1 = new Array(target.length);
@@ -231,12 +254,13 @@ function createProtectedDateView(target, context) {
 function createProtectedRegExpView(target, context) {
 	const methodCache = /* @__PURE__ */ new Map();
 	const cloned = new RegExp(target);
-	cloned.lastIndex = target.lastIndex;
 	const view = new Proxy(cloned, {
 		get(clonedTarget, key) {
-			const value = Reflect.get(clonedTarget, key, clonedTarget);
 			if (key === "compile") return cacheProtectedMethod(methodCache, key, () => (..._args) => throwReadonlyAnnotationMutation());
-			return typeof value === "function" ? value.bind(clonedTarget) : value;
+			const ownDescriptor = Object.getOwnPropertyDescriptor(clonedTarget, key);
+			if (ownDescriptor != null && "value" in ownDescriptor) return ownDescriptor.value;
+			const value = Reflect.get(clonedTarget, key, clonedTarget);
+			return typeof value === "function" ? value.bind(clonedTarget) : protectAnnotationValue(value, context);
 		},
 		set() {
 			throwReadonlyAnnotationMutation();
@@ -254,7 +278,9 @@ function createProtectedRegExpView(target, context) {
 			throwReadonlyAnnotationMutation();
 		}
 	});
-	return registerProtectedAnnotationView(context, target, view);
+	registerProtectedAnnotationView(context, target, view);
+	copyRegExpMetadata(target, cloned, (value) => protectAnnotationValue(value, context));
+	return view;
 }
 function createProtectedURLSearchParamsView(target, context) {
 	const methodCache = /* @__PURE__ */ new Map();
@@ -335,6 +361,20 @@ function protectAnnotationValue(value, context) {
 	return value;
 }
 /**
+* Normalizes annotation input for a fresh parse run.
+*
+* When callers feed a protected annotation view returned by `getAnnotations()`
+* back into a new parse entrypoint, Optique unwraps it to the caller-owned
+* record first so the new run gets its own protected views.
+*
+* @param annotations The caller-supplied annotations input.
+* @returns The raw annotation record to inject for the new run.
+* @internal
+*/
+function normalizeRunAnnotationInput(annotations) {
+	return isProtectedAnnotationView(annotations) ? unwrapProtectedAnnotationTarget(annotations) : annotations;
+}
+/**
 * Extracts annotations from parser state.
 *
 * @param state Parser state that may contain annotations
@@ -423,8 +463,7 @@ function inheritAnnotations(source, target) {
 		return cloned$1;
 	}
 	if (target instanceof RegExp) {
-		const cloned$1 = new RegExp(target);
-		cloned$1.lastIndex = target.lastIndex;
+		const cloned$1 = cloneRegExpShape(target);
 		cloned$1[annotationKey] = annotations;
 		return cloned$1;
 	}
@@ -517,8 +556,7 @@ function injectAnnotations(state, annotations) {
 		return cloned$1;
 	}
 	if (state instanceof RegExp) {
-		const cloned$1 = new RegExp(state);
-		cloned$1.lastIndex = state.lastIndex;
+		const cloned$1 = cloneRegExpShape(state);
 		cloned$1[annotationKey] = protectedAnnotations;
 		return cloned$1;
 	}
@@ -570,4 +608,5 @@ exports.hasMeaningfulAnnotations = hasMeaningfulAnnotations;
 exports.inheritAnnotations = inheritAnnotations;
 exports.injectAnnotations = injectAnnotations;
 exports.isInjectedAnnotationWrapper = isInjectedAnnotationWrapper;
+exports.normalizeRunAnnotationInput = normalizeRunAnnotationInput;
 exports.unwrapInjectedAnnotationWrapper = unwrapInjectedAnnotationWrapper;

package/dist/annotations.d.cts

@@ -64,6 +64,18 @@ type Annotations = Record<symbol, unknown>;
  */
 type ReadonlyAnnotations = Readonly<Annotations>;
 type AnnotationInput = Annotations | ReadonlyAnnotations;
+/**
+ * Normalizes annotation input for a fresh parse run.
+ *
+ * When callers feed a protected annotation view returned by `getAnnotations()`
+ * back into a new parse entrypoint, Optique unwraps it to the caller-owned
+ * record first so the new run gets its own protected views.
+ *
+ * @param annotations The caller-supplied annotations input.
+ * @returns The raw annotation record to inject for the new run.
+ * @internal
+ */
+declare function normalizeRunAnnotationInput(annotations: AnnotationInput): AnnotationInput;
 /**
  * Options for parse functions.
  * @since 0.10.0
@@ -76,7 +88,7 @@ interface ParseOptions {
    * Optique treats these values as immutable input and exposes them back to
    * parsers only through protected read-only views.
    */
-  annotations?: Annotations;
+  annotations?: Annotations | ReadonlyAnnotations;
 }
 /**
  * Extracts annotations from parser state.
@@ -169,4 +181,4 @@ declare function unwrapInjectedAnnotationWrapper<T>(value: T): T;
  */
 declare function isInjectedAnnotationWrapper(value: unknown): boolean;
 //#endregion
-export { Annotations, ParseOptions, ReadonlyAnnotations, annotateFreshArray, annotationKey, annotationStateValueKey, annotationWrapperKey, firstPassAnnotationKey, getAnnotations, hasMeaningfulAnnotations, inheritAnnotations, injectAnnotations, isInjectedAnnotationWrapper, unwrapInjectedAnnotationWrapper };
+export { Annotations, ParseOptions, ReadonlyAnnotations, annotateFreshArray, annotationKey, annotationStateValueKey, annotationWrapperKey, firstPassAnnotationKey, getAnnotations, hasMeaningfulAnnotations, inheritAnnotations, injectAnnotations, isInjectedAnnotationWrapper, normalizeRunAnnotationInput, unwrapInjectedAnnotationWrapper };

package/dist/annotations.d.ts

@@ -64,6 +64,18 @@ type Annotations = Record<symbol, unknown>;
  */
 type ReadonlyAnnotations = Readonly<Annotations>;
 type AnnotationInput = Annotations | ReadonlyAnnotations;
+/**
+ * Normalizes annotation input for a fresh parse run.
+ *
+ * When callers feed a protected annotation view returned by `getAnnotations()`
+ * back into a new parse entrypoint, Optique unwraps it to the caller-owned
+ * record first so the new run gets its own protected views.
+ *
+ * @param annotations The caller-supplied annotations input.
+ * @returns The raw annotation record to inject for the new run.
+ * @internal
+ */
+declare function normalizeRunAnnotationInput(annotations: AnnotationInput): AnnotationInput;
 /**
  * Options for parse functions.
  * @since 0.10.0
@@ -76,7 +88,7 @@ interface ParseOptions {
    * Optique treats these values as immutable input and exposes them back to
    * parsers only through protected read-only views.
    */
-  annotations?: Annotations;
+  annotations?: Annotations | ReadonlyAnnotations;
 }
 /**
  * Extracts annotations from parser state.
@@ -169,4 +181,4 @@ declare function unwrapInjectedAnnotationWrapper<T>(value: T): T;
  */
 declare function isInjectedAnnotationWrapper(value: unknown): boolean;
 //#endregion
-export { Annotations, ParseOptions, ReadonlyAnnotations, annotateFreshArray, annotationKey, annotationStateValueKey, annotationWrapperKey, firstPassAnnotationKey, getAnnotations, hasMeaningfulAnnotations, inheritAnnotations, injectAnnotations, isInjectedAnnotationWrapper, unwrapInjectedAnnotationWrapper };
+export { Annotations, ParseOptions, ReadonlyAnnotations, annotateFreshArray, annotationKey, annotationStateValueKey, annotationWrapperKey, firstPassAnnotationKey, getAnnotations, hasMeaningfulAnnotations, inheritAnnotations, injectAnnotations, isInjectedAnnotationWrapper, normalizeRunAnnotationInput, unwrapInjectedAnnotationWrapper };

package/dist/annotations.js

@@ -80,6 +80,29 @@ function defineProtectedDataProperty(context, target, key, descriptor) {
 		set: () => throwReadonlyAnnotationMutation()
 	});
 }
+function copyRegExpMetadata(source, target, transformValue) {
+	const sourcePrototype = Object.getPrototypeOf(source);
+	if (Object.getPrototypeOf(target) !== sourcePrototype) Object.setPrototypeOf(target, sourcePrototype);
+	for (const key of Reflect.ownKeys(source)) {
+		if (key === "lastIndex") continue;
+		const descriptor = Object.getOwnPropertyDescriptor(source, key);
+		if (descriptor == null) continue;
+		if ("value" in descriptor && transformValue != null) {
+			Object.defineProperty(target, key, {
+				...descriptor,
+				value: transformValue(descriptor.value)
+			});
+			continue;
+		}
+		Object.defineProperty(target, key, descriptor);
+	}
+	target.lastIndex = source.lastIndex;
+}
+function cloneRegExpShape(source) {
+	const cloned = new RegExp(source);
+	copyRegExpMetadata(source, cloned);
+	return cloned;
+}
 function createProtectedObjectView(target, context) {
 	if (Array.isArray(target)) {
 		const view$1 = new Array(target.length);
@@ -230,12 +253,13 @@ function createProtectedDateView(target, context) {
 function createProtectedRegExpView(target, context) {
 	const methodCache = /* @__PURE__ */ new Map();
 	const cloned = new RegExp(target);
-	cloned.lastIndex = target.lastIndex;
 	const view = new Proxy(cloned, {
 		get(clonedTarget, key) {
-			const value = Reflect.get(clonedTarget, key, clonedTarget);
 			if (key === "compile") return cacheProtectedMethod(methodCache, key, () => (..._args) => throwReadonlyAnnotationMutation());
-			return typeof value === "function" ? value.bind(clonedTarget) : value;
+			const ownDescriptor = Object.getOwnPropertyDescriptor(clonedTarget, key);
+			if (ownDescriptor != null && "value" in ownDescriptor) return ownDescriptor.value;
+			const value = Reflect.get(clonedTarget, key, clonedTarget);
+			return typeof value === "function" ? value.bind(clonedTarget) : protectAnnotationValue(value, context);
 		},
 		set() {
 			throwReadonlyAnnotationMutation();
@@ -253,7 +277,9 @@ function createProtectedRegExpView(target, context) {
 			throwReadonlyAnnotationMutation();
 		}
 	});
-	return registerProtectedAnnotationView(context, target, view);
+	registerProtectedAnnotationView(context, target, view);
+	copyRegExpMetadata(target, cloned, (value) => protectAnnotationValue(value, context));
+	return view;
 }
 function createProtectedURLSearchParamsView(target, context) {
 	const methodCache = /* @__PURE__ */ new Map();
@@ -334,6 +360,20 @@ function protectAnnotationValue(value, context) {
 	return value;
 }
 /**
+* Normalizes annotation input for a fresh parse run.
+*
+* When callers feed a protected annotation view returned by `getAnnotations()`
+* back into a new parse entrypoint, Optique unwraps it to the caller-owned
+* record first so the new run gets its own protected views.
+*
+* @param annotations The caller-supplied annotations input.
+* @returns The raw annotation record to inject for the new run.
+* @internal
+*/
+function normalizeRunAnnotationInput(annotations) {
+	return isProtectedAnnotationView(annotations) ? unwrapProtectedAnnotationTarget(annotations) : annotations;
+}
+/**
 * Extracts annotations from parser state.
 *
 * @param state Parser state that may contain annotations
@@ -422,8 +462,7 @@ function inheritAnnotations(source, target) {
 		return cloned$1;
 	}
 	if (target instanceof RegExp) {
-		const cloned$1 = new RegExp(target);
-		cloned$1.lastIndex = target.lastIndex;
+		const cloned$1 = cloneRegExpShape(target);
 		cloned$1[annotationKey] = annotations;
 		return cloned$1;
 	}
@@ -516,8 +555,7 @@ function injectAnnotations(state, annotations) {
 		return cloned$1;
 	}
 	if (state instanceof RegExp) {
-		const cloned$1 = new RegExp(state);
-		cloned$1.lastIndex = state.lastIndex;
+		const cloned$1 = cloneRegExpShape(state);
 		cloned$1[annotationKey] = protectedAnnotations;
 		return cloned$1;
 	}
@@ -559,4 +597,4 @@ function isInjectedAnnotationWrapper(value) {
 }
 
 //#endregion
-export { annotateFreshArray, annotationKey, annotationStateValueKey, annotationWrapperKey, firstPassAnnotationKey, getAnnotations, hasMeaningfulAnnotations, inheritAnnotations, injectAnnotations, isInjectedAnnotationWrapper, unwrapInjectedAnnotationWrapper };
+export { annotateFreshArray, annotationKey, annotationStateValueKey, annotationWrapperKey, firstPassAnnotationKey, getAnnotations, hasMeaningfulAnnotations, inheritAnnotations, injectAnnotations, isInjectedAnnotationWrapper, normalizeRunAnnotationInput, unwrapInjectedAnnotationWrapper };

package/dist/parser.cjs

@@ -69,7 +69,7 @@ function createParserContext(frame, exec) {
 function injectAnnotationsIntoState(state, options) {
 	const annotations = options?.annotations;
 	if (!require_annotations.hasMeaningfulAnnotations(annotations)) return state;
-	return require_annotations.injectAnnotations(state, annotations);
+	return require_annotations.injectAnnotations(state, require_annotations.normalizeRunAnnotationInput(annotations));
 }
 /**
 * Parses an array of command-line arguments using the provided combined parser.

package/dist/parser.js

@@ -1,4 +1,4 @@
-import { hasMeaningfulAnnotations, injectAnnotations, isInjectedAnnotationWrapper, unwrapInjectedAnnotationWrapper } from "./annotations.js";
+import { hasMeaningfulAnnotations, injectAnnotations, isInjectedAnnotationWrapper, normalizeRunAnnotationInput, unwrapInjectedAnnotationWrapper } from "./annotations.js";
 import { cloneMessage, message } from "./message.js";
 import { cloneUsage, normalizeUsage } from "./usage.js";
 import { cloneDocEntry, isDocEntryHidden } from "./doc.js";
@@ -69,7 +69,7 @@ function createParserContext(frame, exec) {
 function injectAnnotationsIntoState(state, options) {
 	const annotations = options?.annotations;
 	if (!hasMeaningfulAnnotations(annotations)) return state;
-	return injectAnnotations(state, annotations);
+	return injectAnnotations(state, normalizeRunAnnotationInput(annotations));
 }
 /**
 * Parses an array of command-line arguments using the provided combined parser.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.0.0-dev.1852+6dd8742f",
+  "version": "1.0.0-dev.1856+acef001b",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",