@optique/core 1.0.0-dev.1841 → 1.0.0-dev.1846

package/dist/annotations.cjs

@@ -45,12 +45,297 @@ const annotationWrapperKeys = new Set([
 	annotationWrapperKey
 ]);
 const injectedAnnotationWrappers = /* @__PURE__ */ new WeakSet();
+const protectedAnnotationTargets = /* @__PURE__ */ new WeakMap();
+const annotationProtectionCache = /* @__PURE__ */ new WeakMap();
+function throwReadonlyAnnotationMutation() {
+	throw new TypeError("Cannot mutate read-only annotation data.");
+}
+function registerProtectedAnnotationView(target, view) {
+	annotationProtectionCache.set(target, view);
+	protectedAnnotationTargets.set(view, target);
+	return view;
+}
+function isProtectedAnnotationView(value) {
+	return value != null && typeof value === "object" && protectedAnnotationTargets.has(value);
+}
+function unwrapProtectedAnnotationTarget(value) {
+	if (value == null || typeof value !== "object") return value;
+	return protectedAnnotationTargets.get(value) ?? value;
+}
+function cacheProtectedMethod(cache, key, factory) {
+	const cached = cache.get(key);
+	if (cached !== void 0) return cached;
+	const created = factory();
+	cache.set(key, created);
+	return created;
+}
+function defineProtectedDataProperty(target, key, descriptor) {
+	const value = protectAnnotationValue(descriptor.value);
+	Object.defineProperty(target, key, {
+		configurable: descriptor.configurable,
+		enumerable: descriptor.enumerable,
+		get: () => value,
+		set: () => throwReadonlyAnnotationMutation()
+	});
+}
+function createProtectedObjectView(target) {
+	if (Array.isArray(target)) {
+		const view$1 = new Array(target.length);
+		for (const key of Reflect.ownKeys(target)) {
+			if (key === "length") continue;
+			const descriptor = Object.getOwnPropertyDescriptor(target, key);
+			if (descriptor == null) continue;
+			if ("value" in descriptor) {
+				defineProtectedDataProperty(view$1, key, descriptor);
+				continue;
+			}
+			Object.defineProperty(view$1, key, {
+				configurable: descriptor.configurable,
+				enumerable: descriptor.enumerable,
+				get: descriptor.get == null ? void 0 : () => protectAnnotationValue(descriptor.get.call(target)),
+				set: () => throwReadonlyAnnotationMutation()
+			});
+		}
+		return registerProtectedAnnotationView(target, Object.freeze(view$1));
+	}
+	const view = Object.create(Object.getPrototypeOf(target));
+	for (const key of Reflect.ownKeys(target)) {
+		const descriptor = Object.getOwnPropertyDescriptor(target, key);
+		if (descriptor == null) continue;
+		if ("value" in descriptor) {
+			defineProtectedDataProperty(view, key, descriptor);
+			continue;
+		}
+		Object.defineProperty(view, key, {
+			configurable: descriptor.configurable,
+			enumerable: descriptor.enumerable,
+			get: descriptor.get == null ? void 0 : () => protectAnnotationValue(descriptor.get.call(target)),
+			set: () => throwReadonlyAnnotationMutation()
+		});
+	}
+	return registerProtectedAnnotationView(target, Object.freeze(view));
+}
+function createProtectedMapView(target) {
+	const methodCache = /* @__PURE__ */ new Map();
+	const view = new Proxy(target, {
+		get(target$1, key) {
+			if (key === "size") return target$1.size;
+			if (key === "set" || key === "delete" || key === "clear") return cacheProtectedMethod(methodCache, key, () => (..._args) => throwReadonlyAnnotationMutation());
+			if (key === "get") return cacheProtectedMethod(methodCache, key, () => (lookup) => protectAnnotationValue(target$1.get(unwrapProtectedAnnotationTarget(lookup))));
+			if (key === "has") return cacheProtectedMethod(methodCache, key, () => (lookup) => target$1.has(unwrapProtectedAnnotationTarget(lookup)));
+			if (key === "forEach") return cacheProtectedMethod(methodCache, key, () => (callback, thisArg) => target$1.forEach((value$1, mapKey) => {
+				callback.call(thisArg, protectAnnotationValue(value$1), protectAnnotationValue(mapKey), view);
+			}));
+			if (key === "keys") return cacheProtectedMethod(methodCache, key, () => function* () {
+				for (const value$1 of target$1.keys()) yield protectAnnotationValue(value$1);
+			});
+			if (key === "values") return cacheProtectedMethod(methodCache, key, () => function* () {
+				for (const value$1 of target$1.values()) yield protectAnnotationValue(value$1);
+			});
+			if (key === "entries" || key === Symbol.iterator) return cacheProtectedMethod(methodCache, key, () => function* () {
+				for (const [entryKey, entryValue] of target$1.entries()) yield [protectAnnotationValue(entryKey), protectAnnotationValue(entryValue)];
+			});
+			const value = Reflect.get(target$1, key, target$1);
+			return typeof value === "function" ? value.bind(target$1) : value;
+		},
+		set() {
+			throwReadonlyAnnotationMutation();
+		},
+		defineProperty() {
+			throwReadonlyAnnotationMutation();
+		},
+		deleteProperty() {
+			throwReadonlyAnnotationMutation();
+		},
+		setPrototypeOf() {
+			throwReadonlyAnnotationMutation();
+		},
+		preventExtensions() {
+			throwReadonlyAnnotationMutation();
+		}
+	});
+	return registerProtectedAnnotationView(target, view);
+}
+function createProtectedSetView(target) {
+	const methodCache = /* @__PURE__ */ new Map();
+	const view = new Proxy(target, {
+		get(target$1, key) {
+			if (key === "size") return target$1.size;
+			if (key === "add" || key === "delete" || key === "clear") return cacheProtectedMethod(methodCache, key, () => (..._args) => throwReadonlyAnnotationMutation());
+			if (key === "has") return cacheProtectedMethod(methodCache, key, () => (lookup) => target$1.has(unwrapProtectedAnnotationTarget(lookup)));
+			if (key === "forEach") return cacheProtectedMethod(methodCache, key, () => (callback, thisArg) => target$1.forEach((value$1) => {
+				const protectedValue = protectAnnotationValue(value$1);
+				callback.call(thisArg, protectedValue, protectedValue, view);
+			}));
+			if (key === "keys" || key === "values" || key === Symbol.iterator) return cacheProtectedMethod(methodCache, key, () => function* () {
+				for (const value$1 of target$1.values()) yield protectAnnotationValue(value$1);
+			});
+			if (key === "entries") return cacheProtectedMethod(methodCache, key, () => function* () {
+				for (const value$1 of target$1.values()) {
+					const protectedValue = protectAnnotationValue(value$1);
+					yield [protectedValue, protectedValue];
+				}
+			});
+			const value = Reflect.get(target$1, key, target$1);
+			return typeof value === "function" ? value.bind(target$1) : value;
+		},
+		set() {
+			throwReadonlyAnnotationMutation();
+		},
+		defineProperty() {
+			throwReadonlyAnnotationMutation();
+		},
+		deleteProperty() {
+			throwReadonlyAnnotationMutation();
+		},
+		setPrototypeOf() {
+			throwReadonlyAnnotationMutation();
+		},
+		preventExtensions() {
+			throwReadonlyAnnotationMutation();
+		}
+	});
+	return registerProtectedAnnotationView(target, view);
+}
+function createProtectedDateView(target) {
+	const methodCache = /* @__PURE__ */ new Map();
+	const view = new Proxy(target, {
+		get(target$1, key) {
+			const value = Reflect.get(target$1, key, target$1);
+			if (typeof key === "string" && key.startsWith("set")) return cacheProtectedMethod(methodCache, key, () => (..._args) => throwReadonlyAnnotationMutation());
+			return typeof value === "function" ? value.bind(target$1) : value;
+		},
+		set() {
+			throwReadonlyAnnotationMutation();
+		},
+		defineProperty() {
+			throwReadonlyAnnotationMutation();
+		},
+		deleteProperty() {
+			throwReadonlyAnnotationMutation();
+		},
+		setPrototypeOf() {
+			throwReadonlyAnnotationMutation();
+		},
+		preventExtensions() {
+			throwReadonlyAnnotationMutation();
+		}
+	});
+	return registerProtectedAnnotationView(target, view);
+}
+function createProtectedRegExpView(target) {
+	const methodCache = /* @__PURE__ */ new Map();
+	const view = new Proxy(target, {
+		get(target$1, key) {
+			const value = Reflect.get(target$1, key, target$1);
+			if (key === "compile") return cacheProtectedMethod(methodCache, key, () => (..._args) => throwReadonlyAnnotationMutation());
+			return typeof value === "function" ? value.bind(target$1) : value;
+		},
+		set() {
+			throwReadonlyAnnotationMutation();
+		},
+		defineProperty() {
+			throwReadonlyAnnotationMutation();
+		},
+		deleteProperty() {
+			throwReadonlyAnnotationMutation();
+		},
+		setPrototypeOf() {
+			throwReadonlyAnnotationMutation();
+		},
+		preventExtensions() {
+			throwReadonlyAnnotationMutation();
+		}
+	});
+	return registerProtectedAnnotationView(target, view);
+}
+function createProtectedURLSearchParamsView(target) {
+	const methodCache = /* @__PURE__ */ new Map();
+	const view = new Proxy(target, {
+		get(target$1, key) {
+			if (key === "append" || key === "delete" || key === "set" || key === "sort") return cacheProtectedMethod(methodCache, key, () => (..._args) => throwReadonlyAnnotationMutation());
+			if (key === "forEach") return cacheProtectedMethod(methodCache, key, () => (callback, thisArg) => target$1.forEach((value$1, name) => {
+				callback.call(thisArg, value$1, name, view);
+			}));
+			if (key === "keys" || key === "values") return cacheProtectedMethod(methodCache, key, () => function* () {
+				const iterator = key === "keys" ? target$1.keys() : target$1.values();
+				for (const value$1 of iterator) yield value$1;
+			});
+			if (key === "entries" || key === Symbol.iterator) return cacheProtectedMethod(methodCache, key, () => function* () {
+				for (const entry of target$1.entries()) yield entry;
+			});
+			const value = Reflect.get(target$1, key, target$1);
+			return typeof value === "function" ? value.bind(target$1) : value;
+		},
+		set() {
+			throwReadonlyAnnotationMutation();
+		},
+		defineProperty() {
+			throwReadonlyAnnotationMutation();
+		},
+		deleteProperty() {
+			throwReadonlyAnnotationMutation();
+		},
+		setPrototypeOf() {
+			throwReadonlyAnnotationMutation();
+		},
+		preventExtensions() {
+			throwReadonlyAnnotationMutation();
+		}
+	});
+	return registerProtectedAnnotationView(target, view);
+}
+function createProtectedURLView(target) {
+	const view = new Proxy(target, {
+		get(target$1, key) {
+			if (key === "searchParams") return protectAnnotationValue(target$1.searchParams);
+			const value = Reflect.get(target$1, key, target$1);
+			return typeof value === "function" ? value.bind(target$1) : value;
+		},
+		set() {
+			throwReadonlyAnnotationMutation();
+		},
+		defineProperty() {
+			throwReadonlyAnnotationMutation();
+		},
+		deleteProperty() {
+			throwReadonlyAnnotationMutation();
+		},
+		setPrototypeOf() {
+			throwReadonlyAnnotationMutation();
+		},
+		preventExtensions() {
+			throwReadonlyAnnotationMutation();
+		}
+	});
+	return registerProtectedAnnotationView(target, view);
+}
+function protectAnnotationValue(value) {
+	if (value == null || typeof value !== "object") return value;
+	const target = value;
+	if (isProtectedAnnotationView(value)) return value;
+	const cached = annotationProtectionCache.get(target);
+	if (cached !== void 0) return cached;
+	if (target instanceof Map) return createProtectedMapView(target);
+	if (target instanceof Set) return createProtectedSetView(target);
+	if (target instanceof Date) return createProtectedDateView(target);
+	if (target instanceof RegExp) return createProtectedRegExpView(target);
+	if (typeof URLSearchParams === "function" && target instanceof URLSearchParams) return createProtectedURLSearchParamsView(target);
+	if (typeof URL === "function" && target instanceof URL) return createProtectedURLView(target);
+	if (Array.isArray(target)) return createProtectedObjectView(target);
+	const proto = Object.getPrototypeOf(target);
+	if (proto === Object.prototype || proto === null) return createProtectedObjectView(target);
+	return value;
+}
 /**
 * Extracts annotations from parser state.
 *
 * @param state Parser state that may contain annotations
-* @returns Annotations object or undefined if no annotations are present
+* @returns Read-only annotations view or undefined if no annotations are
+*          present
 * @since 0.10.0
+* @since 1.0.0 Returns protected read-only annotation views instead of
+*              caller-owned objects.
 *
 * @example
 * ```typescript
@@ -62,7 +347,7 @@ function getAnnotations(state) {
 	if (state == null || typeof state !== "object") return void 0;
 	const stateObj = state;
 	const annotations = stateObj[annotationKey];
-	if (annotations != null && typeof annotations === "object") return annotations;
+	if (annotations != null && typeof annotations === "object") return protectAnnotationValue(annotations);
 	return void 0;
 }
 /**
@@ -163,11 +448,12 @@ function hasMeaningfulAnnotations(annotations) {
 */
 function injectAnnotations(state, annotations) {
 	if (!hasMeaningfulAnnotations(annotations)) return state;
+	const protectedAnnotations = protectAnnotationValue(annotations);
 	if (state == null || typeof state !== "object") {
 		const wrapper = {};
 		Object.defineProperties(wrapper, {
 			[annotationKey]: {
-				value: annotations,
+				value: protectedAnnotations,
 				enumerable: true,
 				writable: true,
 				configurable: true
@@ -190,40 +476,40 @@ function injectAnnotations(state, annotations) {
 	}
 	if (Array.isArray(state)) {
 		const cloned$1 = [...state];
-		cloned$1[annotationKey] = annotations;
+		cloned$1[annotationKey] = protectedAnnotations;
 		return cloned$1;
 	}
 	if (isInjectedAnnotationWrapper(state)) {
-		state[annotationKey] = annotations;
+		state[annotationKey] = protectedAnnotations;
 		return state;
 	}
 	if (state instanceof Date) {
 		const cloned$1 = new Date(state.getTime());
-		cloned$1[annotationKey] = annotations;
+		cloned$1[annotationKey] = protectedAnnotations;
 		return cloned$1;
 	}
 	if (state instanceof Map) {
 		const cloned$1 = new Map(state);
-		cloned$1[annotationKey] = annotations;
+		cloned$1[annotationKey] = protectedAnnotations;
 		return cloned$1;
 	}
 	if (state instanceof Set) {
 		const cloned$1 = new Set(state);
-		cloned$1[annotationKey] = annotations;
+		cloned$1[annotationKey] = protectedAnnotations;
 		return cloned$1;
 	}
 	if (state instanceof RegExp) {
 		const cloned$1 = new RegExp(state);
-		cloned$1[annotationKey] = annotations;
+		cloned$1[annotationKey] = protectedAnnotations;
 		return cloned$1;
 	}
 	const proto = Object.getPrototypeOf(state);
 	if (proto === Object.prototype || proto === null) return {
 		...state,
-		[annotationKey]: annotations
+		[annotationKey]: protectedAnnotations
 	};
 	const cloned = Object.create(proto, Object.getOwnPropertyDescriptors(state));
-	cloned[annotationKey] = annotations;
+	cloned[annotationKey] = protectedAnnotations;
 	return cloned;
 }
 /**

package/dist/annotations.d.cts

@@ -50,6 +50,20 @@ declare const annotationWrapperKey: unique symbol;
  * @since 0.10.0
  */
 type Annotations = Record<symbol, unknown>;
+/**
+ * Read-only annotation view returned from parser state.
+ *
+ * Top-level annotation records are exposed as read-only objects, and supported
+ * nested container values (plain objects, arrays, `Map`, `Set`, `Date`,
+ * `RegExp`, `URL`, and `URLSearchParams`) are surfaced through protected
+ * views that throw on ordinary mutation attempts.
+ *
+ * Opaque live objects and functions remain reference-preserving.
+ *
+ * @since 1.0.0
+ */
+type ReadonlyAnnotations = Readonly<Annotations>;
+type AnnotationInput = Annotations | ReadonlyAnnotations;
 /**
  * Options for parse functions.
  * @since 0.10.0
@@ -58,6 +72,9 @@ interface ParseOptions {
   /**
    * Annotations to attach to the parsing session.
    * Parsers can access these annotations via getAnnotations(state).
+   *
+   * Optique treats these values as immutable input and exposes them back to
+   * parsers only through protected read-only views.
    */
   annotations?: Annotations;
 }
@@ -65,8 +82,11 @@ interface ParseOptions {
  * Extracts annotations from parser state.
  *
  * @param state Parser state that may contain annotations
- * @returns Annotations object or undefined if no annotations are present
+ * @returns Read-only annotations view or undefined if no annotations are
+ *          present
  * @since 0.10.0
+ * @since 1.0.0 Returns protected read-only annotation views instead of
+ *              caller-owned objects.
  *
  * @example
  * ```typescript
@@ -74,7 +94,7 @@ interface ParseOptions {
  * const myData = annotations?.[myDataKey];
  * ```
  */
-declare function getAnnotations(state: unknown): Annotations | undefined;
+declare function getAnnotations(state: unknown): ReadonlyAnnotations | undefined;
 /**
  * Reattaches annotations to a freshly created array state.
  *
@@ -112,7 +132,7 @@ declare function inheritAnnotations<T>(source: unknown, target: T): T;
  * @returns `true` when the record has at least one own symbol key.
  * @internal
  */
-declare function hasMeaningfulAnnotations(annotations: Annotations | null | undefined): annotations is Annotations;
+declare function hasMeaningfulAnnotations(annotations: AnnotationInput | null | undefined): annotations is AnnotationInput;
 /**
  * Injects annotations into parser state while preserving state shape.
  *
@@ -129,7 +149,7 @@ declare function hasMeaningfulAnnotations(annotations: Annotations | null | unde
  * @returns Annotated state.
  * @internal
  */
-declare function injectAnnotations<TState>(state: TState, annotations: Annotations): TState;
+declare function injectAnnotations<TState>(state: TState, annotations: AnnotationInput): TState;
 /**
  * Unwraps a primitive-state annotation wrapper injected by Optique internals.
  *
@@ -149,4 +169,4 @@ declare function unwrapInjectedAnnotationWrapper<T>(value: T): T;
  */
 declare function isInjectedAnnotationWrapper(value: unknown): boolean;
 //#endregion
-export { Annotations, ParseOptions, 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, unwrapInjectedAnnotationWrapper };

package/dist/annotations.d.ts

@@ -50,6 +50,20 @@ declare const annotationWrapperKey: unique symbol;
  * @since 0.10.0
  */
 type Annotations = Record<symbol, unknown>;
+/**
+ * Read-only annotation view returned from parser state.
+ *
+ * Top-level annotation records are exposed as read-only objects, and supported
+ * nested container values (plain objects, arrays, `Map`, `Set`, `Date`,
+ * `RegExp`, `URL`, and `URLSearchParams`) are surfaced through protected
+ * views that throw on ordinary mutation attempts.
+ *
+ * Opaque live objects and functions remain reference-preserving.
+ *
+ * @since 1.0.0
+ */
+type ReadonlyAnnotations = Readonly<Annotations>;
+type AnnotationInput = Annotations | ReadonlyAnnotations;
 /**
  * Options for parse functions.
  * @since 0.10.0
@@ -58,6 +72,9 @@ interface ParseOptions {
   /**
    * Annotations to attach to the parsing session.
    * Parsers can access these annotations via getAnnotations(state).
+   *
+   * Optique treats these values as immutable input and exposes them back to
+   * parsers only through protected read-only views.
    */
   annotations?: Annotations;
 }
@@ -65,8 +82,11 @@ interface ParseOptions {
  * Extracts annotations from parser state.
  *
  * @param state Parser state that may contain annotations
- * @returns Annotations object or undefined if no annotations are present
+ * @returns Read-only annotations view or undefined if no annotations are
+ *          present
  * @since 0.10.0
+ * @since 1.0.0 Returns protected read-only annotation views instead of
+ *              caller-owned objects.
  *
  * @example
  * ```typescript
@@ -74,7 +94,7 @@ interface ParseOptions {
  * const myData = annotations?.[myDataKey];
  * ```
  */
-declare function getAnnotations(state: unknown): Annotations | undefined;
+declare function getAnnotations(state: unknown): ReadonlyAnnotations | undefined;
 /**
  * Reattaches annotations to a freshly created array state.
  *
@@ -112,7 +132,7 @@ declare function inheritAnnotations<T>(source: unknown, target: T): T;
  * @returns `true` when the record has at least one own symbol key.
  * @internal
  */
-declare function hasMeaningfulAnnotations(annotations: Annotations | null | undefined): annotations is Annotations;
+declare function hasMeaningfulAnnotations(annotations: AnnotationInput | null | undefined): annotations is AnnotationInput;
 /**
  * Injects annotations into parser state while preserving state shape.
  *
@@ -129,7 +149,7 @@ declare function hasMeaningfulAnnotations(annotations: Annotations | null | unde
  * @returns Annotated state.
  * @internal
  */
-declare function injectAnnotations<TState>(state: TState, annotations: Annotations): TState;
+declare function injectAnnotations<TState>(state: TState, annotations: AnnotationInput): TState;
 /**
  * Unwraps a primitive-state annotation wrapper injected by Optique internals.
  *
@@ -149,4 +169,4 @@ declare function unwrapInjectedAnnotationWrapper<T>(value: T): T;
  */
 declare function isInjectedAnnotationWrapper(value: unknown): boolean;
 //#endregion
-export { Annotations, ParseOptions, 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, unwrapInjectedAnnotationWrapper };

package/dist/annotations.js

@@ -44,12 +44,297 @@ const annotationWrapperKeys = new Set([
 	annotationWrapperKey
 ]);
 const injectedAnnotationWrappers = /* @__PURE__ */ new WeakSet();
+const protectedAnnotationTargets = /* @__PURE__ */ new WeakMap();
+const annotationProtectionCache = /* @__PURE__ */ new WeakMap();
+function throwReadonlyAnnotationMutation() {
+	throw new TypeError("Cannot mutate read-only annotation data.");
+}
+function registerProtectedAnnotationView(target, view) {
+	annotationProtectionCache.set(target, view);
+	protectedAnnotationTargets.set(view, target);
+	return view;
+}
+function isProtectedAnnotationView(value) {
+	return value != null && typeof value === "object" && protectedAnnotationTargets.has(value);
+}
+function unwrapProtectedAnnotationTarget(value) {
+	if (value == null || typeof value !== "object") return value;
+	return protectedAnnotationTargets.get(value) ?? value;
+}
+function cacheProtectedMethod(cache, key, factory) {
+	const cached = cache.get(key);
+	if (cached !== void 0) return cached;
+	const created = factory();
+	cache.set(key, created);
+	return created;
+}
+function defineProtectedDataProperty(target, key, descriptor) {
+	const value = protectAnnotationValue(descriptor.value);
+	Object.defineProperty(target, key, {
+		configurable: descriptor.configurable,
+		enumerable: descriptor.enumerable,
+		get: () => value,
+		set: () => throwReadonlyAnnotationMutation()
+	});
+}
+function createProtectedObjectView(target) {
+	if (Array.isArray(target)) {
+		const view$1 = new Array(target.length);
+		for (const key of Reflect.ownKeys(target)) {
+			if (key === "length") continue;
+			const descriptor = Object.getOwnPropertyDescriptor(target, key);
+			if (descriptor == null) continue;
+			if ("value" in descriptor) {
+				defineProtectedDataProperty(view$1, key, descriptor);
+				continue;
+			}
+			Object.defineProperty(view$1, key, {
+				configurable: descriptor.configurable,
+				enumerable: descriptor.enumerable,
+				get: descriptor.get == null ? void 0 : () => protectAnnotationValue(descriptor.get.call(target)),
+				set: () => throwReadonlyAnnotationMutation()
+			});
+		}
+		return registerProtectedAnnotationView(target, Object.freeze(view$1));
+	}
+	const view = Object.create(Object.getPrototypeOf(target));
+	for (const key of Reflect.ownKeys(target)) {
+		const descriptor = Object.getOwnPropertyDescriptor(target, key);
+		if (descriptor == null) continue;
+		if ("value" in descriptor) {
+			defineProtectedDataProperty(view, key, descriptor);
+			continue;
+		}
+		Object.defineProperty(view, key, {
+			configurable: descriptor.configurable,
+			enumerable: descriptor.enumerable,
+			get: descriptor.get == null ? void 0 : () => protectAnnotationValue(descriptor.get.call(target)),
+			set: () => throwReadonlyAnnotationMutation()
+		});
+	}
+	return registerProtectedAnnotationView(target, Object.freeze(view));
+}
+function createProtectedMapView(target) {
+	const methodCache = /* @__PURE__ */ new Map();
+	const view = new Proxy(target, {
+		get(target$1, key) {
+			if (key === "size") return target$1.size;
+			if (key === "set" || key === "delete" || key === "clear") return cacheProtectedMethod(methodCache, key, () => (..._args) => throwReadonlyAnnotationMutation());
+			if (key === "get") return cacheProtectedMethod(methodCache, key, () => (lookup) => protectAnnotationValue(target$1.get(unwrapProtectedAnnotationTarget(lookup))));
+			if (key === "has") return cacheProtectedMethod(methodCache, key, () => (lookup) => target$1.has(unwrapProtectedAnnotationTarget(lookup)));
+			if (key === "forEach") return cacheProtectedMethod(methodCache, key, () => (callback, thisArg) => target$1.forEach((value$1, mapKey) => {
+				callback.call(thisArg, protectAnnotationValue(value$1), protectAnnotationValue(mapKey), view);
+			}));
+			if (key === "keys") return cacheProtectedMethod(methodCache, key, () => function* () {
+				for (const value$1 of target$1.keys()) yield protectAnnotationValue(value$1);
+			});
+			if (key === "values") return cacheProtectedMethod(methodCache, key, () => function* () {
+				for (const value$1 of target$1.values()) yield protectAnnotationValue(value$1);
+			});
+			if (key === "entries" || key === Symbol.iterator) return cacheProtectedMethod(methodCache, key, () => function* () {
+				for (const [entryKey, entryValue] of target$1.entries()) yield [protectAnnotationValue(entryKey), protectAnnotationValue(entryValue)];
+			});
+			const value = Reflect.get(target$1, key, target$1);
+			return typeof value === "function" ? value.bind(target$1) : value;
+		},
+		set() {
+			throwReadonlyAnnotationMutation();
+		},
+		defineProperty() {
+			throwReadonlyAnnotationMutation();
+		},
+		deleteProperty() {
+			throwReadonlyAnnotationMutation();
+		},
+		setPrototypeOf() {
+			throwReadonlyAnnotationMutation();
+		},
+		preventExtensions() {
+			throwReadonlyAnnotationMutation();
+		}
+	});
+	return registerProtectedAnnotationView(target, view);
+}
+function createProtectedSetView(target) {
+	const methodCache = /* @__PURE__ */ new Map();
+	const view = new Proxy(target, {
+		get(target$1, key) {
+			if (key === "size") return target$1.size;
+			if (key === "add" || key === "delete" || key === "clear") return cacheProtectedMethod(methodCache, key, () => (..._args) => throwReadonlyAnnotationMutation());
+			if (key === "has") return cacheProtectedMethod(methodCache, key, () => (lookup) => target$1.has(unwrapProtectedAnnotationTarget(lookup)));
+			if (key === "forEach") return cacheProtectedMethod(methodCache, key, () => (callback, thisArg) => target$1.forEach((value$1) => {
+				const protectedValue = protectAnnotationValue(value$1);
+				callback.call(thisArg, protectedValue, protectedValue, view);
+			}));
+			if (key === "keys" || key === "values" || key === Symbol.iterator) return cacheProtectedMethod(methodCache, key, () => function* () {
+				for (const value$1 of target$1.values()) yield protectAnnotationValue(value$1);
+			});
+			if (key === "entries") return cacheProtectedMethod(methodCache, key, () => function* () {
+				for (const value$1 of target$1.values()) {
+					const protectedValue = protectAnnotationValue(value$1);
+					yield [protectedValue, protectedValue];
+				}
+			});
+			const value = Reflect.get(target$1, key, target$1);
+			return typeof value === "function" ? value.bind(target$1) : value;
+		},
+		set() {
+			throwReadonlyAnnotationMutation();
+		},
+		defineProperty() {
+			throwReadonlyAnnotationMutation();
+		},
+		deleteProperty() {
+			throwReadonlyAnnotationMutation();
+		},
+		setPrototypeOf() {
+			throwReadonlyAnnotationMutation();
+		},
+		preventExtensions() {
+			throwReadonlyAnnotationMutation();
+		}
+	});
+	return registerProtectedAnnotationView(target, view);
+}
+function createProtectedDateView(target) {
+	const methodCache = /* @__PURE__ */ new Map();
+	const view = new Proxy(target, {
+		get(target$1, key) {
+			const value = Reflect.get(target$1, key, target$1);
+			if (typeof key === "string" && key.startsWith("set")) return cacheProtectedMethod(methodCache, key, () => (..._args) => throwReadonlyAnnotationMutation());
+			return typeof value === "function" ? value.bind(target$1) : value;
+		},
+		set() {
+			throwReadonlyAnnotationMutation();
+		},
+		defineProperty() {
+			throwReadonlyAnnotationMutation();
+		},
+		deleteProperty() {
+			throwReadonlyAnnotationMutation();
+		},
+		setPrototypeOf() {
+			throwReadonlyAnnotationMutation();
+		},
+		preventExtensions() {
+			throwReadonlyAnnotationMutation();
+		}
+	});
+	return registerProtectedAnnotationView(target, view);
+}
+function createProtectedRegExpView(target) {
+	const methodCache = /* @__PURE__ */ new Map();
+	const view = new Proxy(target, {
+		get(target$1, key) {
+			const value = Reflect.get(target$1, key, target$1);
+			if (key === "compile") return cacheProtectedMethod(methodCache, key, () => (..._args) => throwReadonlyAnnotationMutation());
+			return typeof value === "function" ? value.bind(target$1) : value;
+		},
+		set() {
+			throwReadonlyAnnotationMutation();
+		},
+		defineProperty() {
+			throwReadonlyAnnotationMutation();
+		},
+		deleteProperty() {
+			throwReadonlyAnnotationMutation();
+		},
+		setPrototypeOf() {
+			throwReadonlyAnnotationMutation();
+		},
+		preventExtensions() {
+			throwReadonlyAnnotationMutation();
+		}
+	});
+	return registerProtectedAnnotationView(target, view);
+}
+function createProtectedURLSearchParamsView(target) {
+	const methodCache = /* @__PURE__ */ new Map();
+	const view = new Proxy(target, {
+		get(target$1, key) {
+			if (key === "append" || key === "delete" || key === "set" || key === "sort") return cacheProtectedMethod(methodCache, key, () => (..._args) => throwReadonlyAnnotationMutation());
+			if (key === "forEach") return cacheProtectedMethod(methodCache, key, () => (callback, thisArg) => target$1.forEach((value$1, name) => {
+				callback.call(thisArg, value$1, name, view);
+			}));
+			if (key === "keys" || key === "values") return cacheProtectedMethod(methodCache, key, () => function* () {
+				const iterator = key === "keys" ? target$1.keys() : target$1.values();
+				for (const value$1 of iterator) yield value$1;
+			});
+			if (key === "entries" || key === Symbol.iterator) return cacheProtectedMethod(methodCache, key, () => function* () {
+				for (const entry of target$1.entries()) yield entry;
+			});
+			const value = Reflect.get(target$1, key, target$1);
+			return typeof value === "function" ? value.bind(target$1) : value;
+		},
+		set() {
+			throwReadonlyAnnotationMutation();
+		},
+		defineProperty() {
+			throwReadonlyAnnotationMutation();
+		},
+		deleteProperty() {
+			throwReadonlyAnnotationMutation();
+		},
+		setPrototypeOf() {
+			throwReadonlyAnnotationMutation();
+		},
+		preventExtensions() {
+			throwReadonlyAnnotationMutation();
+		}
+	});
+	return registerProtectedAnnotationView(target, view);
+}
+function createProtectedURLView(target) {
+	const view = new Proxy(target, {
+		get(target$1, key) {
+			if (key === "searchParams") return protectAnnotationValue(target$1.searchParams);
+			const value = Reflect.get(target$1, key, target$1);
+			return typeof value === "function" ? value.bind(target$1) : value;
+		},
+		set() {
+			throwReadonlyAnnotationMutation();
+		},
+		defineProperty() {
+			throwReadonlyAnnotationMutation();
+		},
+		deleteProperty() {
+			throwReadonlyAnnotationMutation();
+		},
+		setPrototypeOf() {
+			throwReadonlyAnnotationMutation();
+		},
+		preventExtensions() {
+			throwReadonlyAnnotationMutation();
+		}
+	});
+	return registerProtectedAnnotationView(target, view);
+}
+function protectAnnotationValue(value) {
+	if (value == null || typeof value !== "object") return value;
+	const target = value;
+	if (isProtectedAnnotationView(value)) return value;
+	const cached = annotationProtectionCache.get(target);
+	if (cached !== void 0) return cached;
+	if (target instanceof Map) return createProtectedMapView(target);
+	if (target instanceof Set) return createProtectedSetView(target);
+	if (target instanceof Date) return createProtectedDateView(target);
+	if (target instanceof RegExp) return createProtectedRegExpView(target);
+	if (typeof URLSearchParams === "function" && target instanceof URLSearchParams) return createProtectedURLSearchParamsView(target);
+	if (typeof URL === "function" && target instanceof URL) return createProtectedURLView(target);
+	if (Array.isArray(target)) return createProtectedObjectView(target);
+	const proto = Object.getPrototypeOf(target);
+	if (proto === Object.prototype || proto === null) return createProtectedObjectView(target);
+	return value;
+}
 /**
 * Extracts annotations from parser state.
 *
 * @param state Parser state that may contain annotations
-* @returns Annotations object or undefined if no annotations are present
+* @returns Read-only annotations view or undefined if no annotations are
+*          present
 * @since 0.10.0
+* @since 1.0.0 Returns protected read-only annotation views instead of
+*              caller-owned objects.
 *
 * @example
 * ```typescript
@@ -61,7 +346,7 @@ function getAnnotations(state) {
 	if (state == null || typeof state !== "object") return void 0;
 	const stateObj = state;
 	const annotations = stateObj[annotationKey];
-	if (annotations != null && typeof annotations === "object") return annotations;
+	if (annotations != null && typeof annotations === "object") return protectAnnotationValue(annotations);
 	return void 0;
 }
 /**
@@ -162,11 +447,12 @@ function hasMeaningfulAnnotations(annotations) {
 */
 function injectAnnotations(state, annotations) {
 	if (!hasMeaningfulAnnotations(annotations)) return state;
+	const protectedAnnotations = protectAnnotationValue(annotations);
 	if (state == null || typeof state !== "object") {
 		const wrapper = {};
 		Object.defineProperties(wrapper, {
 			[annotationKey]: {
-				value: annotations,
+				value: protectedAnnotations,
 				enumerable: true,
 				writable: true,
 				configurable: true
@@ -189,40 +475,40 @@ function injectAnnotations(state, annotations) {
 	}
 	if (Array.isArray(state)) {
 		const cloned$1 = [...state];
-		cloned$1[annotationKey] = annotations;
+		cloned$1[annotationKey] = protectedAnnotations;
 		return cloned$1;
 	}
 	if (isInjectedAnnotationWrapper(state)) {
-		state[annotationKey] = annotations;
+		state[annotationKey] = protectedAnnotations;
 		return state;
 	}
 	if (state instanceof Date) {
 		const cloned$1 = new Date(state.getTime());
-		cloned$1[annotationKey] = annotations;
+		cloned$1[annotationKey] = protectedAnnotations;
 		return cloned$1;
 	}
 	if (state instanceof Map) {
 		const cloned$1 = new Map(state);
-		cloned$1[annotationKey] = annotations;
+		cloned$1[annotationKey] = protectedAnnotations;
 		return cloned$1;
 	}
 	if (state instanceof Set) {
 		const cloned$1 = new Set(state);
-		cloned$1[annotationKey] = annotations;
+		cloned$1[annotationKey] = protectedAnnotations;
 		return cloned$1;
 	}
 	if (state instanceof RegExp) {
 		const cloned$1 = new RegExp(state);
-		cloned$1[annotationKey] = annotations;
+		cloned$1[annotationKey] = protectedAnnotations;
 		return cloned$1;
 	}
 	const proto = Object.getPrototypeOf(state);
 	if (proto === Object.prototype || proto === null) return {
 		...state,
-		[annotationKey]: annotations
+		[annotationKey]: protectedAnnotations
 	};
 	const cloned = Object.create(proto, Object.getOwnPropertyDescriptors(state));
-	cloned[annotationKey] = annotations;
+	cloned[annotationKey] = protectedAnnotations;
 	return cloned;
 }
 /**

package/dist/context.d.cts

@@ -1,4 +1,4 @@
-import { Annotations } from "./annotations.cjs";
+import { Annotations, ReadonlyAnnotations } from "./annotations.cjs";
 
 //#region src/context.d.ts
 
@@ -232,4 +232,4 @@ interface SourceContext<TRequiredOptions = void> {
   [Symbol.asyncDispose]?(): void | PromiseLike<void>;
 }
 //#endregion
-export { type Annotations, ParserValuePlaceholder, SourceContext, SourceContextPhase, SourceContextPhase1Request, SourceContextPhase2Request, SourceContextRequest };
+export { type Annotations, ParserValuePlaceholder, type ReadonlyAnnotations, SourceContext, SourceContextPhase, SourceContextPhase1Request, SourceContextPhase2Request, SourceContextRequest };

package/dist/context.d.ts

@@ -1,4 +1,4 @@
-import { Annotations } from "./annotations.js";
+import { Annotations, ReadonlyAnnotations } from "./annotations.js";
 
 //#region src/context.d.ts
 
@@ -232,4 +232,4 @@ interface SourceContext<TRequiredOptions = void> {
   [Symbol.asyncDispose]?(): void | PromiseLike<void>;
 }
 //#endregion
-export { type Annotations, ParserValuePlaceholder, SourceContext, SourceContextPhase, SourceContextPhase1Request, SourceContextPhase2Request, SourceContextRequest };
+export { type Annotations, ParserValuePlaceholder, type ReadonlyAnnotations, SourceContext, SourceContextPhase, SourceContextPhase1Request, SourceContextPhase2Request, SourceContextRequest };

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { Annotations, ParseOptions, annotationKey, getAnnotations } from "./annotations.cjs";
+import { Annotations, ParseOptions, ReadonlyAnnotations, annotationKey, getAnnotations } from "./annotations.cjs";
 import { NonEmptyString, ensureNonEmptyString, isNonEmptyString } from "./nonempty.cjs";
 import { Message, MessageFormatOptions, MessageTerm, ValueSetOptions, commandLine, envVar, formatMessage, lineBreak, link, message, metavar, optionName, optionNames, text, value, valueSet, values } from "./message.cjs";
 import { HiddenVisibility, OptionName, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, cloneUsage, cloneUsageTerm, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, formatUsage, formatUsageTerm, isDocHidden, isSuggestionHidden, isUsageHidden, mergeHidden, normalizeUsage } from "./usage.cjs";
@@ -12,4 +12,4 @@ import { ShellCompletion, bash, fish, nu, pwsh, zsh } from "./completion.cjs";
 import { ParserValuePlaceholder, SourceContext, SourceContextRequest } from "./context.cjs";
 import { AnyDependencySource, CombineMode, CombinedDependencyMode, DeferredParseState, DependencyError, DependencyMode, DependencyRegistry, DependencySource, DependencySourceState, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, PendingDependencySourceState, ResolvedDependency, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, defaultDependencyValueSnapshot, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, formatDependencyError, getDefaultValuesFunction, getDependencyIds, getSnapshottedDefaultDependencyValues, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isPendingDependencySourceState, isWrappedDependencySource, parseWithDependency, pendingDependencySourceStateMarker, singleDefaultValue, snapshotDefaultDependencyValues, suggestWithDependency, transformsDependencyValue, transformsDependencyValueMarker, wrappedDependencySourceMarker } from "./dependency.cjs";
 import { CommandSubConfig, ContextOptionsParam, ExtractRequiredOptions, OptionSubConfig, RunOptions, RunParserError, RunWithOptions, SubstituteParserValue, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync } from "./facade.cjs";
-export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandOptions, CommandSubConfig, ConditionalErrorOptions, ConditionalOptions, ContextOptionsParam, DeferredMap, DeferredParseState, DependencyError, DependencyMode, DependencyRegistry, DependencySource, DependencySourceState, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EmailOptions, ExecutionContext, ExecutionPhase, ExtractRequiredOptions, FlagErrorOptions, FlagOptions, FloatOptions, GroupOptions, HiddenVisibility, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OptionSubConfig, OrErrorOptions, OrOptions, ParseFrame, type ParseOptions, Parser, ParserContext, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PendingDependencySourceState, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, ResolvedDependency, Result, RunOptions, RunParserError, RunWithOptions, ShellCompletion, ShowChoicesOptions, ShowDefaultOptions, SocketAddressOptions, SocketAddressValue, SourceContext, SourceContextRequest, StringOptions, SubstituteParserValue, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, annotationKey, annotationWrapperRequiresSourceBindingKey, argument, bash, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, command, commandLine, composeWrappedSourceMetadata, concat, conditional, constant, createDeferredParseState, createDependencySourceState, createParserContext, createPendingDependencySourceState, deduplicateDocEntries, deduplicateDocFragments, defaultDependencyValueSnapshot, defaultValues, deferredParseMarker, defineInheritedAnnotationParser, defineSourceBindingOnlyAnnotationCompletionParser, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, fail, fish, flag, float, formatDependencyError, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDefaultValuesFunction, getDelegatingSuggestRuntimeNodes, getDependencyIds, getDocPage, getDocPageAsync, getDocPageSync, getParserSuggestRuntimeNodes, getSnapshottedDefaultDependencyValues, group, hostname, inheritParentAnnotationsKey, integer, ip, ipv4, ipv6, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isPendingDependencySourceState, isSuggestionHidden, isUsageHidden, isValueParser, isWrappedDependencySource, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, parseWithDependency, passThrough, pendingDependencySourceStateMarker, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, singleDefaultValue, snapshotDefaultDependencyValues, socketAddress, string, suggest, suggestAsync, suggestSync, suggestWithDependency, text, transformsDependencyValue, transformsDependencyValueMarker, tuple, unmatchedNonCliDependencySourceStateMarker, url, uuid, value, valueSet, values, withDefault, wrappedDependencySourceMarker, zsh };
+export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandOptions, CommandSubConfig, ConditionalErrorOptions, ConditionalOptions, ContextOptionsParam, DeferredMap, DeferredParseState, DependencyError, DependencyMode, DependencyRegistry, DependencySource, DependencySourceState, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EmailOptions, ExecutionContext, ExecutionPhase, ExtractRequiredOptions, FlagErrorOptions, FlagOptions, FloatOptions, GroupOptions, HiddenVisibility, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OptionSubConfig, OrErrorOptions, OrOptions, ParseFrame, type ParseOptions, Parser, ParserContext, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PendingDependencySourceState, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, type ReadonlyAnnotations, ResolvedDependency, Result, RunOptions, RunParserError, RunWithOptions, ShellCompletion, ShowChoicesOptions, ShowDefaultOptions, SocketAddressOptions, SocketAddressValue, SourceContext, SourceContextRequest, StringOptions, SubstituteParserValue, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, annotationKey, annotationWrapperRequiresSourceBindingKey, argument, bash, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, command, commandLine, composeWrappedSourceMetadata, concat, conditional, constant, createDeferredParseState, createDependencySourceState, createParserContext, createPendingDependencySourceState, deduplicateDocEntries, deduplicateDocFragments, defaultDependencyValueSnapshot, defaultValues, deferredParseMarker, defineInheritedAnnotationParser, defineSourceBindingOnlyAnnotationCompletionParser, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, fail, fish, flag, float, formatDependencyError, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDefaultValuesFunction, getDelegatingSuggestRuntimeNodes, getDependencyIds, getDocPage, getDocPageAsync, getDocPageSync, getParserSuggestRuntimeNodes, getSnapshottedDefaultDependencyValues, group, hostname, inheritParentAnnotationsKey, integer, ip, ipv4, ipv6, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isPendingDependencySourceState, isSuggestionHidden, isUsageHidden, isValueParser, isWrappedDependencySource, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, parseWithDependency, passThrough, pendingDependencySourceStateMarker, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, singleDefaultValue, snapshotDefaultDependencyValues, socketAddress, string, suggest, suggestAsync, suggestSync, suggestWithDependency, text, transformsDependencyValue, transformsDependencyValueMarker, tuple, unmatchedNonCliDependencySourceStateMarker, url, uuid, value, valueSet, values, withDefault, wrappedDependencySourceMarker, zsh };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { Annotations, ParseOptions, annotationKey, getAnnotations } from "./annotations.js";
+import { Annotations, ParseOptions, ReadonlyAnnotations, annotationKey, getAnnotations } from "./annotations.js";
 import { NonEmptyString, ensureNonEmptyString, isNonEmptyString } from "./nonempty.js";
 import { Message, MessageFormatOptions, MessageTerm, ValueSetOptions, commandLine, envVar, formatMessage, lineBreak, link, message, metavar, optionName, optionNames, text, value, valueSet, values } from "./message.js";
 import { HiddenVisibility, OptionName, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, cloneUsage, cloneUsageTerm, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, formatUsage, formatUsageTerm, isDocHidden, isSuggestionHidden, isUsageHidden, mergeHidden, normalizeUsage } from "./usage.js";
@@ -12,4 +12,4 @@ import { ShellCompletion, bash, fish, nu, pwsh, zsh } from "./completion.js";
 import { ParserValuePlaceholder, SourceContext, SourceContextRequest } from "./context.js";
 import { AnyDependencySource, CombineMode, CombinedDependencyMode, DeferredParseState, DependencyError, DependencyMode, DependencyRegistry, DependencySource, DependencySourceState, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, PendingDependencySourceState, ResolvedDependency, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, defaultDependencyValueSnapshot, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, formatDependencyError, getDefaultValuesFunction, getDependencyIds, getSnapshottedDefaultDependencyValues, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isPendingDependencySourceState, isWrappedDependencySource, parseWithDependency, pendingDependencySourceStateMarker, singleDefaultValue, snapshotDefaultDependencyValues, suggestWithDependency, transformsDependencyValue, transformsDependencyValueMarker, wrappedDependencySourceMarker } from "./dependency.js";
 import { CommandSubConfig, ContextOptionsParam, ExtractRequiredOptions, OptionSubConfig, RunOptions, RunParserError, RunWithOptions, SubstituteParserValue, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync } from "./facade.js";
-export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandOptions, CommandSubConfig, ConditionalErrorOptions, ConditionalOptions, ContextOptionsParam, DeferredMap, DeferredParseState, DependencyError, DependencyMode, DependencyRegistry, DependencySource, DependencySourceState, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EmailOptions, ExecutionContext, ExecutionPhase, ExtractRequiredOptions, FlagErrorOptions, FlagOptions, FloatOptions, GroupOptions, HiddenVisibility, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OptionSubConfig, OrErrorOptions, OrOptions, ParseFrame, type ParseOptions, Parser, ParserContext, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PendingDependencySourceState, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, ResolvedDependency, Result, RunOptions, RunParserError, RunWithOptions, ShellCompletion, ShowChoicesOptions, ShowDefaultOptions, SocketAddressOptions, SocketAddressValue, SourceContext, SourceContextRequest, StringOptions, SubstituteParserValue, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, annotationKey, annotationWrapperRequiresSourceBindingKey, argument, bash, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, command, commandLine, composeWrappedSourceMetadata, concat, conditional, constant, createDeferredParseState, createDependencySourceState, createParserContext, createPendingDependencySourceState, deduplicateDocEntries, deduplicateDocFragments, defaultDependencyValueSnapshot, defaultValues, deferredParseMarker, defineInheritedAnnotationParser, defineSourceBindingOnlyAnnotationCompletionParser, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, fail, fish, flag, float, formatDependencyError, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDefaultValuesFunction, getDelegatingSuggestRuntimeNodes, getDependencyIds, getDocPage, getDocPageAsync, getDocPageSync, getParserSuggestRuntimeNodes, getSnapshottedDefaultDependencyValues, group, hostname, inheritParentAnnotationsKey, integer, ip, ipv4, ipv6, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isPendingDependencySourceState, isSuggestionHidden, isUsageHidden, isValueParser, isWrappedDependencySource, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, parseWithDependency, passThrough, pendingDependencySourceStateMarker, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, singleDefaultValue, snapshotDefaultDependencyValues, socketAddress, string, suggest, suggestAsync, suggestSync, suggestWithDependency, text, transformsDependencyValue, transformsDependencyValueMarker, tuple, unmatchedNonCliDependencySourceStateMarker, url, uuid, value, valueSet, values, withDefault, wrappedDependencySourceMarker, zsh };
+export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandOptions, CommandSubConfig, ConditionalErrorOptions, ConditionalOptions, ContextOptionsParam, DeferredMap, DeferredParseState, DependencyError, DependencyMode, DependencyRegistry, DependencySource, DependencySourceState, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EmailOptions, ExecutionContext, ExecutionPhase, ExtractRequiredOptions, FlagErrorOptions, FlagOptions, FloatOptions, GroupOptions, HiddenVisibility, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OptionSubConfig, OrErrorOptions, OrOptions, ParseFrame, type ParseOptions, Parser, ParserContext, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PendingDependencySourceState, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, type ReadonlyAnnotations, ResolvedDependency, Result, RunOptions, RunParserError, RunWithOptions, ShellCompletion, ShowChoicesOptions, ShowDefaultOptions, SocketAddressOptions, SocketAddressValue, SourceContext, SourceContextRequest, StringOptions, SubstituteParserValue, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, annotationKey, annotationWrapperRequiresSourceBindingKey, argument, bash, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, command, commandLine, composeWrappedSourceMetadata, concat, conditional, constant, createDeferredParseState, createDependencySourceState, createParserContext, createPendingDependencySourceState, deduplicateDocEntries, deduplicateDocFragments, defaultDependencyValueSnapshot, defaultValues, deferredParseMarker, defineInheritedAnnotationParser, defineSourceBindingOnlyAnnotationCompletionParser, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, fail, fish, flag, float, formatDependencyError, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDefaultValuesFunction, getDelegatingSuggestRuntimeNodes, getDependencyIds, getDocPage, getDocPageAsync, getDocPageSync, getParserSuggestRuntimeNodes, getSnapshottedDefaultDependencyValues, group, hostname, inheritParentAnnotationsKey, integer, ip, ipv4, ipv6, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isPendingDependencySourceState, isSuggestionHidden, isUsageHidden, isValueParser, isWrappedDependencySource, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, parseWithDependency, passThrough, pendingDependencySourceStateMarker, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, singleDefaultValue, snapshotDefaultDependencyValues, socketAddress, string, suggest, suggestAsync, suggestSync, suggestWithDependency, text, transformsDependencyValue, transformsDependencyValueMarker, tuple, unmatchedNonCliDependencySourceStateMarker, url, uuid, value, valueSet, values, withDefault, wrappedDependencySourceMarker, zsh };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.0.0-dev.1841+7b330b10",
+  "version": "1.0.0-dev.1846+e6b02260",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",