@optique/core 1.0.0-dev.524 → 1.0.0-dev.555

package/dist/annotations.cjs

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

package/dist/annotations.d.cts

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

package/dist/annotations.d.ts

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

package/dist/annotations.js

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

package/dist/context.cjs

@@ -4,8 +4,9 @@
 * Checks whether a context is static (returns annotations without needing
 * parsed results).
 *
-* A context is considered static if `getAnnotations()` called without
-* arguments returns a non-empty annotations object synchronously.
+* A context is considered static if it declares `mode: "static"` or if
+* `getAnnotations()` called without arguments returns a non-empty
+* annotations object synchronously.
 *
 * @param context The source context to check.
 * @returns `true` if the context is static, `false` otherwise.

package/dist/context.d.cts

@@ -154,8 +154,9 @@ interface SourceContext<TRequiredOptions = void> {
  * Checks whether a context is static (returns annotations without needing
  * parsed results).
  *
- * A context is considered static if `getAnnotations()` called without
- * arguments returns a non-empty annotations object synchronously.
+ * A context is considered static if it declares `mode: "static"` or if
+ * `getAnnotations()` called without arguments returns a non-empty
+ * annotations object synchronously.
  *
  * @param context The source context to check.
  * @returns `true` if the context is static, `false` otherwise.

package/dist/context.d.ts

@@ -154,8 +154,9 @@ interface SourceContext<TRequiredOptions = void> {
  * Checks whether a context is static (returns annotations without needing
  * parsed results).
  *
- * A context is considered static if `getAnnotations()` called without
- * arguments returns a non-empty annotations object synchronously.
+ * A context is considered static if it declares `mode: "static"` or if
+ * `getAnnotations()` called without arguments returns a non-empty
+ * annotations object synchronously.
  *
  * @param context The source context to check.
  * @returns `true` if the context is static, `false` otherwise.

package/dist/context.js

@@ -3,8 +3,9 @@
 * Checks whether a context is static (returns annotations without needing
 * parsed results).
 *
-* A context is considered static if `getAnnotations()` called without
-* arguments returns a non-empty annotations object synchronously.
+* A context is considered static if it declares `mode: "static"` or if
+* `getAnnotations()` called without arguments returns a non-empty
+* annotations object synchronously.
 *
 * @param context The source context to check.
 * @returns `true` if the context is static, `false` otherwise.

package/dist/facade.cjs

@@ -870,13 +870,8 @@ async function collectPhase1Annotations(contexts, options) {
 	let hasDynamic = false;
 	for (const context of contexts) {
 		const result = context.getAnnotations(void 0, options);
-		if (result instanceof Promise) {
-			hasDynamic = true;
-			annotationsList.push(await result);
-		} else {
-			if (Object.getOwnPropertySymbols(result).length === 0) hasDynamic = true;
-			annotationsList.push(result);
-		}
+		hasDynamic ||= needsTwoPhaseContext(context, result);
+		annotationsList.push(result instanceof Promise ? await result : result);
 	}
 	return {
 		annotations: mergeAnnotations(annotationsList),
@@ -914,7 +909,7 @@ function collectPhase1AnnotationsSync(contexts, options) {
 	for (const context of contexts) {
 		const result = context.getAnnotations(void 0, options);
 		if (result instanceof Promise) throw new Error(`Context ${String(context.id)} returned a Promise in sync mode. Use runWith() or runWithAsync() for async contexts.`);
-		if (Object.getOwnPropertySymbols(result).length === 0) hasDynamic = true;
+		hasDynamic ||= needsTwoPhaseContext(context, result);
 		annotationsList.push(result);
 	}
 	return {
@@ -923,6 +918,18 @@ function collectPhase1AnnotationsSync(contexts, options) {
 	};
 }
 /**
+* Determines whether a context requires a second parse pass.
+*
+* Explicit `mode` declarations take precedence over legacy heuristics so
+* static contexts are not forced into two-phase parsing when they return
+* empty annotations or a Promise.
+*/
+function needsTwoPhaseContext(context, result) {
+	if (context.mode !== void 0) return context.mode === "dynamic";
+	if (result instanceof Promise) return true;
+	return Object.getOwnPropertySymbols(result).length === 0;
+}
+/**
 * Collects annotations from all contexts synchronously.
 *
 * @param contexts Source contexts to collect annotations from.
@@ -1122,10 +1129,7 @@ function runWithAsync(parser, programName, contexts, options) {
 * @returns A new parser with annotations in its initial state.
 */
 function injectAnnotationsIntoParser(parser, annotations) {
-	const newInitialState = {
-		...typeof parser.initialState === "object" && parser.initialState !== null ? parser.initialState : {},
-		[require_annotations.annotationKey]: annotations
-	};
+	const newInitialState = require_annotations.injectAnnotations(parser.initialState, annotations);
 	return {
 		...parser,
 		initialState: newInitialState