@optique/core 1.0.0-dev.1901 → 1.0.0-dev.1970

package/dist/annotation-state.cjs

@@ -1,5 +1,5 @@
-const require_annotations = require('./annotations.cjs');
-const require_parser = require('./parser.cjs');
+const require_annotations = require('./internal/annotations.cjs');
+const require_parser = require('./internal/parser.cjs');
 
 //#region src/annotation-state.ts
 /**
@@ -11,6 +11,7 @@ const require_parser = require('./parser.cjs');
 * @internal
 */
 const annotationViewTargets = /* @__PURE__ */ new WeakMap();
+const delegatedAnnotationCloneTargets = /* @__PURE__ */ new WeakMap();
 /**
 * Unwraps an annotation-view proxy to its original target object.
 *
@@ -23,14 +24,18 @@ function unwrapAnnotationView(value) {
 	if (value == null || typeof value !== "object") return value;
 	return annotationViewTargets.get(value) ?? value;
 }
+function unwrapDelegatedAnnotationClone(value) {
+	if (value == null || typeof value !== "object") return value;
+	return delegatedAnnotationCloneTargets.get(value) ?? value;
+}
 /**
-* Creates a proxy that exposes annotations without changing the target shape.
+* Creates an annotation-aware proxy without changing the target shape.
 *
 * @param state The object state to expose through an annotation-aware view.
 * @param annotations The annotations to surface through the proxy.
 * @returns A proxy over the unwrapped target object that reports the supplied
 *          annotations while preserving the target's structural behavior.
-* @internal
+* @since 1.0.0
 */
 function withAnnotationView(state, annotations) {
 	const target = unwrapAnnotationView(state);
@@ -59,61 +64,90 @@ function normalizeInjectedAnnotationState(state) {
 	return require_annotations.unwrapInjectedAnnotationWrapper(state);
 }
 function isNonPlainDelegatedObject(state) {
-	if (Array.isArray(state) || state instanceof Date || state instanceof Map || state instanceof Set || state instanceof RegExp) return false;
 	const proto = Object.getPrototypeOf(state);
+	if (proto === Array.prototype || proto === Date.prototype || proto === Map.prototype || proto === Set.prototype || proto === RegExp.prototype) return false;
 	return proto !== Object.prototype && proto !== null;
 }
+function inheritDelegatedAnnotations(parentState, childState) {
+	const target = normalizeDelegatedAnnotationState(childState);
+	const delegatedState = require_annotations.inheritAnnotations(parentState, target);
+	if (delegatedState !== target) delegatedAnnotationCloneTargets.set(delegatedState, target);
+	return delegatedState;
+}
 /**
 * Removes Optique's internal annotation carriers from a delegated state.
 *
-* This unwraps both primitive-state annotation wrappers and annotation-view
-* proxies used for non-plain object states.
+* This unwraps primitive-state annotation wrappers, tracked delegated clones,
+* and annotation-view proxies used for object states.
 *
 * @param state The delegated state to normalize.
 * @returns The original underlying state value.
 * @internal
 */
 function normalizeDelegatedAnnotationState(state) {
-	return normalizeInjectedAnnotationState(unwrapAnnotationView(state));
+	return normalizeInjectedAnnotationState(unwrapDelegatedAnnotationClone(unwrapAnnotationView(state)));
 }
 /**
 * Returns whether the given state uses an internal delegated annotation carrier.
 *
 * @param state The candidate state to inspect.
-* @returns `true` when the state is an injected primitive wrapper or an
-*          annotation-view proxy.
+* @returns `true` when the state is an injected primitive wrapper, a tracked
+*          delegated clone, or an annotation-view proxy.
 * @internal
 */
 function hasDelegatedAnnotationCarrier(state) {
-	return state != null && typeof state === "object" && (require_annotations.isInjectedAnnotationWrapper(state) || annotationViewTargets.has(state));
+	return state != null && typeof state === "object" && (require_annotations.isInjectedAnnotationWrapper(state) || delegatedAnnotationCloneTargets.has(state) || annotationViewTargets.has(state));
+}
+function getOrCreateNestedNormalizationClone(entry) {
+	entry.clone ??= entry.createClone();
+	return entry.clone;
 }
-function isPendingNestedNormalizationAlias(originalValue, normalizedValue, seen) {
-	if (originalValue == null || typeof originalValue !== "object") return false;
+function getPendingNestedNormalizationEntry(originalValue, normalizedValue, seen) {
+	if (originalValue == null || typeof originalValue !== "object") return void 0;
 	const entry = seen.get(originalValue);
-	return entry != null && !entry.finalized && entry.clone === normalizedValue;
+	return entry != null && entry.clone != null && entry.clone === normalizedValue && (!entry.finalized || entry.preferCloneOnRead) ? entry : void 0;
 }
 function createPendingNestedNormalizationClone(source) {
-	return Array.isArray(source) ? [] : Object.create(Object.getPrototypeOf(source));
+	if (!Array.isArray(source)) return Object.create(Object.getPrototypeOf(source));
+	if (Object.getPrototypeOf(source) === Array.prototype) return [];
+	try {
+		return source.slice(0, 0);
+	} catch {
+		return [];
+	}
+}
+function createPendingNestedNormalizationCollectionClone(source) {
+	const proto = Object.getPrototypeOf(source);
+	if (source instanceof Map && proto === Map.prototype) return /* @__PURE__ */ new Map();
+	if (source instanceof Set && proto === Set.prototype) return /* @__PURE__ */ new Set();
+	const Constructor = source.constructor;
+	if (typeof Constructor === "function") try {
+		return new Constructor();
+	} catch {}
+	return source instanceof Map ? /* @__PURE__ */ new Map() : /* @__PURE__ */ new Set();
 }
-function normalizeNestedDelegatedStructuredState(source, seen) {
-	const clone = createPendingNestedNormalizationClone(source);
+function normalizeNestedDelegatedStructuredState(source, seen, preferPendingClone) {
 	const entry = {
-		clone,
+		clone: void 0,
+		createClone: () => createPendingNestedNormalizationClone(source),
 		finalized: false,
-		result: clone
+		result: source,
+		preferCloneOnRead: false
 	};
 	seen.set(source, entry);
 	const overrides = /* @__PURE__ */ new Map();
 	let changed = false;
+	let hasPendingAliasOverride = false;
 	for (const key of Reflect.ownKeys(source)) {
 		const descriptor = Object.getOwnPropertyDescriptor(source, key);
 		if (descriptor == null || !("value" in descriptor)) continue;
-		const nextValue = normalizeNestedDelegatedAnnotationState(descriptor.value, seen);
+		const nextValue = normalizeNestedDelegatedAnnotationState(descriptor.value, seen, true);
 		if (nextValue === descriptor.value) continue;
 		overrides.set(key, nextValue);
-		if (!isPendingNestedNormalizationAlias(descriptor.value, nextValue, seen)) changed = true;
+		if (getPendingNestedNormalizationEntry(descriptor.value, nextValue, seen) == null) changed = true;
+		else hasPendingAliasOverride = true;
 	}
-	if (!changed) {
+	if (!changed && !hasPendingAliasOverride) {
 		entry.finalized = true;
 		entry.result = source;
 		return source;
@@ -127,41 +161,50 @@ function normalizeNestedDelegatedStructuredState(source, seen) {
 			value: nextValue
 		};
 	}
+	const clone = getOrCreateNestedNormalizationClone(entry);
 	Object.defineProperties(clone, descriptors);
 	entry.finalized = true;
-	entry.result = clone;
-	return clone;
+	entry.preferCloneOnRead = !changed && hasPendingAliasOverride;
+	entry.result = changed ? clone : source;
+	return changed || preferPendingClone ? clone : source;
 }
-function normalizeNestedDelegatedMapState(source, seen) {
-	const clone = /* @__PURE__ */ new Map();
+function normalizeNestedDelegatedMapState(source, seen, preferPendingClone) {
 	const entry = {
-		clone,
+		clone: void 0,
+		createClone: () => createPendingNestedNormalizationCollectionClone(source),
 		finalized: false,
-		result: clone
+		result: source,
+		preferCloneOnRead: false
 	};
 	seen.set(source, entry);
 	const normalizedEntries = [];
 	const overrides = /* @__PURE__ */ new Map();
 	let changed = false;
+	let hasPendingAliasOverride = false;
 	for (const [key, value] of source) {
-		const nextKey = normalizeNestedDelegatedAnnotationState(key, seen);
-		const nextValue = normalizeNestedDelegatedAnnotationState(value, seen);
+		const nextKey = normalizeNestedDelegatedAnnotationState(key, seen, true);
+		const nextValue = normalizeNestedDelegatedAnnotationState(value, seen, true);
 		normalizedEntries.push([nextKey, nextValue]);
-		if (!isPendingNestedNormalizationAlias(key, nextKey, seen) && nextKey !== key || !isPendingNestedNormalizationAlias(value, nextValue, seen) && nextValue !== value) changed = true;
+		if (nextKey !== key) if (getPendingNestedNormalizationEntry(key, nextKey, seen) == null) changed = true;
+		else hasPendingAliasOverride = true;
+		if (nextValue !== value) if (getPendingNestedNormalizationEntry(value, nextValue, seen) == null) changed = true;
+		else hasPendingAliasOverride = true;
 	}
 	for (const key of Reflect.ownKeys(source)) {
 		const descriptor = Object.getOwnPropertyDescriptor(source, key);
 		if (descriptor == null || !("value" in descriptor)) continue;
-		const nextValue = normalizeNestedDelegatedAnnotationState(descriptor.value, seen);
+		const nextValue = normalizeNestedDelegatedAnnotationState(descriptor.value, seen, true);
 		if (nextValue === descriptor.value) continue;
 		overrides.set(key, nextValue);
-		if (!isPendingNestedNormalizationAlias(descriptor.value, nextValue, seen)) changed = true;
+		if (getPendingNestedNormalizationEntry(descriptor.value, nextValue, seen) == null) changed = true;
+		else hasPendingAliasOverride = true;
 	}
-	if (!changed) {
+	if (!changed && !hasPendingAliasOverride) {
 		entry.finalized = true;
 		entry.result = source;
 		return source;
 	}
+	const clone = getOrCreateNestedNormalizationClone(entry);
 	for (const [key, value] of normalizedEntries) clone.set(key, value);
 	const descriptors = Object.getOwnPropertyDescriptors(source);
 	for (const [key, nextValue] of overrides) {
@@ -174,38 +217,45 @@ function normalizeNestedDelegatedMapState(source, seen) {
 	}
 	Object.defineProperties(clone, descriptors);
 	entry.finalized = true;
-	entry.result = clone;
-	return clone;
+	entry.preferCloneOnRead = !changed && hasPendingAliasOverride;
+	entry.result = changed ? clone : source;
+	return changed || preferPendingClone ? clone : source;
 }
-function normalizeNestedDelegatedSetState(source, seen) {
-	const clone = /* @__PURE__ */ new Set();
+function normalizeNestedDelegatedSetState(source, seen, preferPendingClone) {
 	const entry = {
-		clone,
+		clone: void 0,
+		createClone: () => createPendingNestedNormalizationCollectionClone(source),
 		finalized: false,
-		result: clone
+		result: source,
+		preferCloneOnRead: false
 	};
 	seen.set(source, entry);
 	const normalizedValues = [];
 	const overrides = /* @__PURE__ */ new Map();
 	let changed = false;
+	let hasPendingAliasOverride = false;
 	for (const value of source) {
-		const nextValue = normalizeNestedDelegatedAnnotationState(value, seen);
+		const nextValue = normalizeNestedDelegatedAnnotationState(value, seen, true);
 		normalizedValues.push(nextValue);
-		if (nextValue !== value && !isPendingNestedNormalizationAlias(value, nextValue, seen)) changed = true;
+		if (nextValue === value) continue;
+		if (getPendingNestedNormalizationEntry(value, nextValue, seen) == null) changed = true;
+		else hasPendingAliasOverride = true;
 	}
 	for (const key of Reflect.ownKeys(source)) {
 		const descriptor = Object.getOwnPropertyDescriptor(source, key);
 		if (descriptor == null || !("value" in descriptor)) continue;
-		const nextValue = normalizeNestedDelegatedAnnotationState(descriptor.value, seen);
+		const nextValue = normalizeNestedDelegatedAnnotationState(descriptor.value, seen, true);
 		if (nextValue === descriptor.value) continue;
 		overrides.set(key, nextValue);
-		if (!isPendingNestedNormalizationAlias(descriptor.value, nextValue, seen)) changed = true;
+		if (getPendingNestedNormalizationEntry(descriptor.value, nextValue, seen) == null) changed = true;
+		else hasPendingAliasOverride = true;
 	}
-	if (!changed) {
+	if (!changed && !hasPendingAliasOverride) {
 		entry.finalized = true;
 		entry.result = source;
 		return source;
 	}
+	const clone = getOrCreateNestedNormalizationClone(entry);
 	for (const value of normalizedValues) clone.add(value);
 	const descriptors = Object.getOwnPropertyDescriptors(source);
 	for (const [key, nextValue] of overrides) {
@@ -218,8 +268,9 @@ function normalizeNestedDelegatedSetState(source, seen) {
 	}
 	Object.defineProperties(clone, descriptors);
 	entry.finalized = true;
-	entry.result = clone;
-	return clone;
+	entry.preferCloneOnRead = !changed && hasPendingAliasOverride;
+	entry.result = changed ? clone : source;
+	return changed || preferPendingClone ? clone : source;
 }
 /**
 * Recursively removes delegated annotation carriers from plain-object, array,
@@ -237,27 +288,30 @@ function normalizeNestedDelegatedSetState(source, seen) {
 *          normalized clone with delegated carriers removed.
 * @internal
 */
-function normalizeNestedDelegatedAnnotationState(value, seen = /* @__PURE__ */ new WeakMap()) {
+function normalizeNestedDelegatedAnnotationState(value, seen = /* @__PURE__ */ new WeakMap(), preferPendingClone = false) {
 	const normalized = normalizeDelegatedAnnotationState(value);
 	if (normalized == null || typeof normalized !== "object") return normalized;
 	const source = normalized;
 	const existing = seen.get(source);
-	if (existing != null) return existing.finalized ? existing.result : existing.clone;
-	if (Array.isArray(source)) return normalizeNestedDelegatedStructuredState(source, seen);
-	if (source instanceof Map) return normalizeNestedDelegatedMapState(source, seen);
-	if (source instanceof Set) return normalizeNestedDelegatedSetState(source, seen);
+	if (existing != null) {
+		if (!existing.finalized) return getOrCreateNestedNormalizationClone(existing);
+		return preferPendingClone && existing.preferCloneOnRead ? getOrCreateNestedNormalizationClone(existing) : existing.result;
+	}
+	if (Array.isArray(source)) return normalizeNestedDelegatedStructuredState(source, seen, preferPendingClone);
+	if (source instanceof Map) return normalizeNestedDelegatedMapState(source, seen, preferPendingClone);
+	if (source instanceof Set) return normalizeNestedDelegatedSetState(source, seen, preferPendingClone);
 	const proto = Object.getPrototypeOf(source);
 	if (proto !== Object.prototype && proto !== null) return normalized;
-	return normalizeNestedDelegatedStructuredState(source, seen);
+	return normalizeNestedDelegatedStructuredState(source, seen, preferPendingClone);
 }
 /**
 * Creates a short-lived delegated state that exposes the parent's annotations
 * regardless of the child state's runtime shape.
 *
-* Primitive and nullish states use `injectAnnotations()`, plain objects and
-* built-ins use `inheritAnnotations()`, and non-plain objects use an
-* annotation-view proxy so class invariants such as private fields remain
-* intact.
+* Primitive and nullish states use `injectAnnotations()`, clone-based object
+* delegation is tracked so it can be normalized back out later, and non-plain
+* objects use an annotation-view proxy so class invariants such as private
+* fields remain intact.
 *
 * @param parentState The state carrying the annotations to delegate.
 * @param childState The child state that should observe those annotations.
@@ -268,10 +322,10 @@ function getDelegatedAnnotationState(parentState, childState) {
 	const annotations = require_annotations.getAnnotations(parentState);
 	if (annotations === void 0) return childState;
 	if (require_annotations.isInjectedAnnotationWrapper(childState)) return require_annotations.injectAnnotations(normalizeInjectedAnnotationState(childState), annotations);
-	if (require_annotations.getAnnotations(childState) === annotations) return childState;
 	if (childState == null || typeof childState !== "object") return require_annotations.injectAnnotations(childState, annotations);
+	if (require_annotations.getAnnotations(childState) === annotations && (delegatedAnnotationCloneTargets.has(childState) || annotationViewTargets.has(childState))) return childState;
 	if (isNonPlainDelegatedObject(childState)) return withAnnotationView(childState, annotations);
-	return require_annotations.inheritAnnotations(parentState, childState);
+	return inheritDelegatedAnnotations(parentState, childState);
 }
 /**
 * Returns whether a state is still at the initial sentinel after normalizing
@@ -367,4 +421,5 @@ exports.normalizeDelegatedAnnotationState = normalizeDelegatedAnnotationState;
 exports.normalizeInjectedAnnotationState = normalizeInjectedAnnotationState;
 exports.normalizeNestedDelegatedAnnotationState = normalizeNestedDelegatedAnnotationState;
 exports.reconcileObjectChildState = reconcileObjectChildState;
-exports.unwrapAnnotationView = unwrapAnnotationView;
+exports.unwrapAnnotationView = unwrapAnnotationView;
+exports.withAnnotationView = withAnnotationView;

package/dist/annotation-state.d.cts

@@ -0,0 +1,24 @@
+import { Annotations } from "./internal/annotations.cjs";
+
+//#region src/annotation-state.d.ts
+
+/**
+ * Creates an annotation-aware proxy without changing the target shape.
+ *
+ * @param state The object state to expose through an annotation-aware view.
+ * @param annotations The annotations to surface through the proxy.
+ * @returns A proxy over the unwrapped target object that reports the supplied
+ *          annotations while preserving the target's structural behavior.
+ * @since 1.0.0
+ */
+declare function withAnnotationView<T extends object>(state: T, annotations: Annotations): T;
+/**
+ * Removes Optique's internal primitive-state annotation wrapper when present.
+ *
+ * @param state The parser state to normalize.
+ * @returns The wrapped primitive sentinel when the input is an injected
+ *          annotation wrapper; otherwise the original input unchanged.
+ * @internal
+ */
+//#endregion
+export { withAnnotationView };

package/dist/annotation-state.d.ts

@@ -0,0 +1,24 @@
+import { Annotations } from "./internal/annotations.js";
+
+//#region src/annotation-state.d.ts
+
+/**
+ * Creates an annotation-aware proxy without changing the target shape.
+ *
+ * @param state The object state to expose through an annotation-aware view.
+ * @param annotations The annotations to surface through the proxy.
+ * @returns A proxy over the unwrapped target object that reports the supplied
+ *          annotations while preserving the target's structural behavior.
+ * @since 1.0.0
+ */
+declare function withAnnotationView<T extends object>(state: T, annotations: Annotations): T;
+/**
+ * Removes Optique's internal primitive-state annotation wrapper when present.
+ *
+ * @param state The parser state to normalize.
+ * @returns The wrapped primitive sentinel when the input is an injected
+ *          annotation wrapper; otherwise the original input unchanged.
+ * @internal
+ */
+//#endregion
+export { withAnnotationView };