@optique/core 1.1.0-dev.2096 → 1.1.0-dev.2146

package/dist/annotation-state.cjs

@@ -1,5 +1,5 @@
-const require_annotations = require('./internal/annotations.cjs');
-const require_parser = require('./internal/parser.cjs');
+const require_internal_annotations = require('./internal/annotations.cjs');
+const require_internal_parser = require('./internal/parser.cjs');
 
 //#region src/annotation-state.ts
 /**
@@ -41,12 +41,12 @@ function withAnnotationView(state, annotations) {
 	const target = unwrapAnnotationView(state);
 	const view = new Proxy(target, {
 		get(target$1, key) {
-			if (key === require_annotations.annotationKey) return annotations;
+			if (key === require_internal_annotations.annotationKey) return annotations;
 			const value = Reflect.get(target$1, key, target$1);
 			return typeof value === "function" ? value.bind(target$1) : value;
 		},
 		has(target$1, key) {
-			return key === require_annotations.annotationKey || Reflect.has(target$1, key);
+			return key === require_internal_annotations.annotationKey || Reflect.has(target$1, key);
 		}
 	});
 	annotationViewTargets.set(view, target);
@@ -61,7 +61,7 @@ function withAnnotationView(state, annotations) {
 * @internal
 */
 function normalizeInjectedAnnotationState(state) {
-	return require_annotations.unwrapInjectedAnnotationWrapper(state);
+	return require_internal_annotations.unwrapInjectedAnnotationWrapper(state);
 }
 function isNonPlainDelegatedObject(state) {
 	const proto = Object.getPrototypeOf(state);
@@ -70,7 +70,7 @@ function isNonPlainDelegatedObject(state) {
 }
 function inheritDelegatedAnnotations(parentState, childState) {
 	const target = normalizeDelegatedAnnotationState(childState);
-	const delegatedState = require_annotations.inheritAnnotations(parentState, target);
+	const delegatedState = require_internal_annotations.inheritAnnotations(parentState, target);
 	if (delegatedState !== target) delegatedAnnotationCloneTargets.set(delegatedState, target);
 	return delegatedState;
 }
@@ -96,7 +96,7 @@ function normalizeDelegatedAnnotationState(state) {
 * @internal
 */
 function hasDelegatedAnnotationCarrier(state) {
-	return state != null && typeof state === "object" && (require_annotations.isInjectedAnnotationWrapper(state) || delegatedAnnotationCloneTargets.has(state) || annotationViewTargets.has(state));
+	return state != null && typeof state === "object" && (require_internal_annotations.isInjectedAnnotationWrapper(state) || delegatedAnnotationCloneTargets.has(state) || annotationViewTargets.has(state));
 }
 function getOrCreateNestedNormalizationClone(entry) {
 	entry.clone ??= entry.createClone();
@@ -319,11 +319,11 @@ function normalizeNestedDelegatedAnnotationState(value, seen = /* @__PURE__ */ n
 * @internal
 */
 function getDelegatedAnnotationState(parentState, childState) {
-	const annotations = require_annotations.getAnnotations(parentState);
+	const annotations = require_internal_annotations.getAnnotations(parentState);
 	if (annotations === void 0) return childState;
-	if (require_annotations.isInjectedAnnotationWrapper(childState)) return require_annotations.injectAnnotations(normalizeInjectedAnnotationState(childState), annotations);
-	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 (require_internal_annotations.isInjectedAnnotationWrapper(childState)) return require_internal_annotations.injectAnnotations(normalizeInjectedAnnotationState(childState), annotations);
+	if (childState == null || typeof childState !== "object") return require_internal_annotations.injectAnnotations(childState, annotations);
+	if (require_internal_annotations.getAnnotations(childState) === annotations && (delegatedAnnotationCloneTargets.has(childState) || annotationViewTargets.has(childState))) return childState;
 	if (isNonPlainDelegatedObject(childState)) return withAnnotationView(childState, annotations);
 	return inheritDelegatedAnnotations(parentState, childState);
 }
@@ -356,15 +356,15 @@ function isAnnotationWrappedInitialState(state) {
 * @internal
 */
 function getWrappedChildParseState(parentState, childState, parser) {
-	const annotations = require_annotations.getAnnotations(parentState);
-	const shouldInheritAnnotations = Reflect.get(parser, require_parser.inheritParentAnnotationsKey) === true;
+	const annotations = require_internal_annotations.getAnnotations(parentState);
+	const shouldInheritAnnotations = Reflect.get(parser, require_internal_parser.inheritParentAnnotationsKey) === true;
 	if (childState == null) {
-		if (annotations !== void 0 && shouldInheritAnnotations) return require_annotations.injectAnnotations(childState, annotations);
+		if (annotations !== void 0 && shouldInheritAnnotations) return require_internal_annotations.injectAnnotations(childState, annotations);
 		return childState;
 	}
-	if (annotations === void 0 || typeof childState !== "object" || require_annotations.getAnnotations(childState) === annotations || !shouldInheritAnnotations) return childState;
-	const injectedState = require_annotations.injectAnnotations(childState, annotations);
-	return require_annotations.getAnnotations(injectedState) === annotations ? injectedState : childState;
+	if (annotations === void 0 || typeof childState !== "object" || require_internal_annotations.getAnnotations(childState) === annotations || !shouldInheritAnnotations) return childState;
+	const injectedState = require_internal_annotations.injectAnnotations(childState, annotations);
+	return require_internal_annotations.getAnnotations(injectedState) === annotations ? injectedState : childState;
 }
 /**
 * Propagates parent annotations into a child state while preserving the child
@@ -380,16 +380,16 @@ function getWrappedChildParseState(parentState, childState, parser) {
 * @internal
 */
 function getWrappedChildState(parentState, childState, parser) {
-	const annotations = require_annotations.getAnnotations(parentState);
-	const shouldInheritAnnotations = Reflect.get(parser, require_parser.inheritParentAnnotationsKey) === true;
+	const annotations = require_internal_annotations.getAnnotations(parentState);
+	const shouldInheritAnnotations = Reflect.get(parser, require_internal_parser.inheritParentAnnotationsKey) === true;
 	if (childState == null) {
-		if (annotations !== void 0 && shouldInheritAnnotations) return require_annotations.injectAnnotations(childState, annotations);
+		if (annotations !== void 0 && shouldInheritAnnotations) return require_internal_annotations.injectAnnotations(childState, annotations);
 		return childState;
 	}
-	if (annotations === void 0 || typeof childState !== "object" || require_annotations.getAnnotations(childState) === annotations) return childState;
+	if (annotations === void 0 || typeof childState !== "object" || require_internal_annotations.getAnnotations(childState) === annotations) return childState;
 	if (shouldInheritAnnotations) {
-		const injectedState = require_annotations.injectAnnotations(childState, annotations);
-		if (require_annotations.getAnnotations(injectedState) === annotations) return injectedState;
+		const injectedState = require_internal_annotations.injectAnnotations(childState, annotations);
+		if (require_internal_annotations.getAnnotations(injectedState) === annotations) return injectedState;
 	}
 	return withAnnotationView(childState, annotations);
 }
@@ -405,9 +405,9 @@ function getWrappedChildState(parentState, childState, parser) {
 * @internal
 */
 function reconcileObjectChildState(parentState, childState) {
-	const annotations = require_annotations.getAnnotations(parentState);
-	if (annotations === void 0 || childState == null || typeof childState !== "object" || require_annotations.getAnnotations(childState) === annotations) return childState;
-	return require_annotations.inheritAnnotations(parentState, childState);
+	const annotations = require_internal_annotations.getAnnotations(parentState);
+	if (annotations === void 0 || childState == null || typeof childState !== "object" || require_internal_annotations.getAnnotations(childState) === annotations) return childState;
+	return require_internal_annotations.inheritAnnotations(parentState, childState);
 }
 
 //#endregion

package/dist/annotation-state.d.cts

@@ -1,7 +1,26 @@
 import { Annotations } from "./internal/annotations.cjs";
+import { Mode, Parser } from "./internal/parser.cjs";
 
 //#region src/annotation-state.d.ts
 
+/**
+ * Shared targets for annotation-view proxies.
+ *
+ * Maps a proxy returned by {@link withAnnotationView} back to its original
+ * target object.
+ *
+ * @internal
+ */
+declare const annotationViewTargets: WeakMap<object, object>;
+/**
+ * Unwraps an annotation-view proxy to its original target object.
+ *
+ * @param value The candidate value that may be an annotation-view proxy.
+ * @returns The original target object when the input is a tracked
+ *          annotation-view proxy; otherwise the input value unchanged.
+ * @internal
+ */
+declare function unwrapAnnotationView<T>(value: T): T;
 /**
  * Creates an annotation-aware proxy without changing the target shape.
  *
@@ -20,5 +39,118 @@ declare function withAnnotationView<T extends object>(state: T, annotations: Ann
  *          annotation wrapper; otherwise the original input unchanged.
  * @internal
  */
+declare function normalizeInjectedAnnotationState<T>(state: T): T;
+/**
+ * Removes Optique's internal annotation carriers from a delegated state.
+ *
+ * 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
+ */
+declare function normalizeDelegatedAnnotationState<T>(state: T): T;
+/**
+ * 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, a tracked
+ *          delegated clone, or an annotation-view proxy.
+ * @internal
+ */
+declare function hasDelegatedAnnotationCarrier(state: unknown): boolean;
+interface NestedNormalizationEntry {
+  clone: object | undefined;
+  createClone: () => object;
+  finalized: boolean;
+  result: object;
+  preferCloneOnRead: boolean;
+}
+/**
+ * Recursively removes delegated annotation carriers from plain-object, array,
+ * and built-in collection structures.
+ *
+ * Nested plain objects, arrays, Maps, and Sets are shallow-cloned only when a
+ * delegated carrier is found below them. Other non-plain objects are unwrapped
+ * at the top level and then preserved as-is to avoid mutating or reconstructing
+ * class instances.
+ *
+ * @param value The candidate value to normalize.
+ * @param seen Tracks already-normalized objects so cyclic values keep their
+ *             shape.
+ * @returns The original value when no delegated carriers are present, or a
+ *          normalized clone with delegated carriers removed.
+ * @internal
+ */
+declare function normalizeNestedDelegatedAnnotationState<T>(value: T, seen?: WeakMap<object, NestedNormalizationEntry>, preferPendingClone?: boolean): T;
+/**
+ * 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()`, 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.
+ * @returns A delegated child state that exposes the parent's annotations.
+ * @internal
+ */
+declare function getDelegatedAnnotationState<TState>(parentState: unknown, childState: TState): TState;
+/**
+ * Returns whether a state is still at the initial sentinel after normalizing
+ * Optique's injected annotation wrapper.
+ *
+ * This treats plain `undefined` and annotation-wrapped `undefined` the same.
+ *
+ * @param state The parser state to inspect.
+ * @returns `true` when the normalized state is still `undefined`;
+ *          otherwise `false`.
+ * @internal
+ */
+declare function isAnnotationWrappedInitialState(state: unknown): boolean;
+/**
+ * Propagates parent annotations into a child parse state when the child parser
+ * explicitly opts into parent annotation inheritance.
+ *
+ * @param parentState The parent parser state that may carry annotations.
+ * @param childState The child parse state that may receive inherited
+ *                   annotations.
+ * @param parser The child parser whose inheritance marker controls whether
+ *               wrapper injection is allowed.
+ * @returns The original child state when no injection is needed or possible,
+ *          or an annotation-injected child state that preserves the original
+ *          sentinel or object shape when inheritance applies.
+ * @internal
+ */
+declare function getWrappedChildParseState<TState>(parentState: unknown, childState: TState, parser: Parser<Mode, unknown, unknown>): TState;
+/**
+ * Propagates parent annotations into a child state while preserving the child
+ * state's shape for parsers that do not opt into full wrapper injection.
+ *
+ * @param parentState The parent parser state that may carry annotations.
+ * @param childState The child state that may receive inherited annotations.
+ * @param parser The child parser whose inheritance marker controls whether
+ *               full wrapper injection is allowed.
+ * @returns The original child state when no wrapping is needed, an
+ *          annotation-injected child state when inheritance applies, or an
+ *          annotation-view proxy that preserves the child's object shape.
+ * @internal
+ */
+declare function getWrappedChildState<TState>(parentState: unknown, childState: TState, parser: Parser<Mode, unknown, unknown>): TState;
+/**
+ * Reconciles object-owned child state with parent annotations using the same
+ * shared object-state inheritance rule across parser families.
+ *
+ * @param parentState The parent parser state that may carry annotations.
+ * @param childState The object-owned child state to reconcile.
+ * @returns The original child state when no reconciliation is needed, or a
+ *          child state with inherited annotations when the object state should
+ *          carry the parent's annotations.
+ * @internal
+ */
+declare function reconcileObjectChildState<TState>(parentState: unknown, childState: TState): TState;
 //#endregion
-export { withAnnotationView };
+export { annotationViewTargets, getDelegatedAnnotationState, getWrappedChildParseState, getWrappedChildState, hasDelegatedAnnotationCarrier, isAnnotationWrappedInitialState, normalizeDelegatedAnnotationState, normalizeInjectedAnnotationState, normalizeNestedDelegatedAnnotationState, reconcileObjectChildState, unwrapAnnotationView, withAnnotationView };

package/dist/annotation-state.d.ts

@@ -1,7 +1,26 @@
 import { Annotations } from "./internal/annotations.js";
+import { Mode, Parser } from "./internal/parser.js";
 
 //#region src/annotation-state.d.ts
 
+/**
+ * Shared targets for annotation-view proxies.
+ *
+ * Maps a proxy returned by {@link withAnnotationView} back to its original
+ * target object.
+ *
+ * @internal
+ */
+declare const annotationViewTargets: WeakMap<object, object>;
+/**
+ * Unwraps an annotation-view proxy to its original target object.
+ *
+ * @param value The candidate value that may be an annotation-view proxy.
+ * @returns The original target object when the input is a tracked
+ *          annotation-view proxy; otherwise the input value unchanged.
+ * @internal
+ */
+declare function unwrapAnnotationView<T>(value: T): T;
 /**
  * Creates an annotation-aware proxy without changing the target shape.
  *
@@ -20,5 +39,118 @@ declare function withAnnotationView<T extends object>(state: T, annotations: Ann
  *          annotation wrapper; otherwise the original input unchanged.
  * @internal
  */
+declare function normalizeInjectedAnnotationState<T>(state: T): T;
+/**
+ * Removes Optique's internal annotation carriers from a delegated state.
+ *
+ * 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
+ */
+declare function normalizeDelegatedAnnotationState<T>(state: T): T;
+/**
+ * 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, a tracked
+ *          delegated clone, or an annotation-view proxy.
+ * @internal
+ */
+declare function hasDelegatedAnnotationCarrier(state: unknown): boolean;
+interface NestedNormalizationEntry {
+  clone: object | undefined;
+  createClone: () => object;
+  finalized: boolean;
+  result: object;
+  preferCloneOnRead: boolean;
+}
+/**
+ * Recursively removes delegated annotation carriers from plain-object, array,
+ * and built-in collection structures.
+ *
+ * Nested plain objects, arrays, Maps, and Sets are shallow-cloned only when a
+ * delegated carrier is found below them. Other non-plain objects are unwrapped
+ * at the top level and then preserved as-is to avoid mutating or reconstructing
+ * class instances.
+ *
+ * @param value The candidate value to normalize.
+ * @param seen Tracks already-normalized objects so cyclic values keep their
+ *             shape.
+ * @returns The original value when no delegated carriers are present, or a
+ *          normalized clone with delegated carriers removed.
+ * @internal
+ */
+declare function normalizeNestedDelegatedAnnotationState<T>(value: T, seen?: WeakMap<object, NestedNormalizationEntry>, preferPendingClone?: boolean): T;
+/**
+ * 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()`, 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.
+ * @returns A delegated child state that exposes the parent's annotations.
+ * @internal
+ */
+declare function getDelegatedAnnotationState<TState>(parentState: unknown, childState: TState): TState;
+/**
+ * Returns whether a state is still at the initial sentinel after normalizing
+ * Optique's injected annotation wrapper.
+ *
+ * This treats plain `undefined` and annotation-wrapped `undefined` the same.
+ *
+ * @param state The parser state to inspect.
+ * @returns `true` when the normalized state is still `undefined`;
+ *          otherwise `false`.
+ * @internal
+ */
+declare function isAnnotationWrappedInitialState(state: unknown): boolean;
+/**
+ * Propagates parent annotations into a child parse state when the child parser
+ * explicitly opts into parent annotation inheritance.
+ *
+ * @param parentState The parent parser state that may carry annotations.
+ * @param childState The child parse state that may receive inherited
+ *                   annotations.
+ * @param parser The child parser whose inheritance marker controls whether
+ *               wrapper injection is allowed.
+ * @returns The original child state when no injection is needed or possible,
+ *          or an annotation-injected child state that preserves the original
+ *          sentinel or object shape when inheritance applies.
+ * @internal
+ */
+declare function getWrappedChildParseState<TState>(parentState: unknown, childState: TState, parser: Parser<Mode, unknown, unknown>): TState;
+/**
+ * Propagates parent annotations into a child state while preserving the child
+ * state's shape for parsers that do not opt into full wrapper injection.
+ *
+ * @param parentState The parent parser state that may carry annotations.
+ * @param childState The child state that may receive inherited annotations.
+ * @param parser The child parser whose inheritance marker controls whether
+ *               full wrapper injection is allowed.
+ * @returns The original child state when no wrapping is needed, an
+ *          annotation-injected child state when inheritance applies, or an
+ *          annotation-view proxy that preserves the child's object shape.
+ * @internal
+ */
+declare function getWrappedChildState<TState>(parentState: unknown, childState: TState, parser: Parser<Mode, unknown, unknown>): TState;
+/**
+ * Reconciles object-owned child state with parent annotations using the same
+ * shared object-state inheritance rule across parser families.
+ *
+ * @param parentState The parent parser state that may carry annotations.
+ * @param childState The object-owned child state to reconcile.
+ * @returns The original child state when no reconciliation is needed, or a
+ *          child state with inherited annotations when the object state should
+ *          carry the parent's annotations.
+ * @internal
+ */
+declare function reconcileObjectChildState<TState>(parentState: unknown, childState: TState): TState;
 //#endregion
-export { withAnnotationView };
+export { annotationViewTargets, getDelegatedAnnotationState, getWrappedChildParseState, getWrappedChildState, hasDelegatedAnnotationCarrier, isAnnotationWrappedInitialState, normalizeDelegatedAnnotationState, normalizeInjectedAnnotationState, normalizeNestedDelegatedAnnotationState, reconcileObjectChildState, unwrapAnnotationView, withAnnotationView };

package/dist/annotations.cjs

@@ -1,3 +1,3 @@
-const require_annotations = require('./internal/annotations.cjs');
+const require_internal_annotations = require('./internal/annotations.cjs');
 
-exports.getAnnotations = require_annotations.getAnnotations;
+exports.getAnnotations = require_internal_annotations.getAnnotations;