@optique/core 1.0.0-dev.908 → 1.0.0

package/dist/internal/annotations.cjs

@@ -0,0 +1,316 @@
+
+//#region src/internal/annotations.ts
+/**
+* Runtime context extension system for Optique parsers.
+*
+* This module provides the annotations system that allows external runtime data
+* to be passed to parsers during the parsing session. This enables use cases like
+* config file fallbacks, environment-based validation, and shared context.
+*
+* @module
+* @since 0.10.0
+*/
+/**
+* Annotation key symbol for storing data in parser state.
+* @since 0.10.0
+*/
+const annotationKey = Symbol.for("@optique/core/parser/annotation");
+/**
+* Internal marker attached during the first pass of `runWith()` so wrappers
+* with side effects can defer work until two-pass contexts have resolved.
+*
+* @internal
+*/
+const firstPassAnnotationKey = Symbol.for("@optique/core/parser/firstPass");
+/**
+* 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();
+function hasInjectedAnnotationWrapperShape(value) {
+	const valueRecord = value;
+	if (valueRecord[annotationWrapperKey] !== true) return false;
+	const ownKeys = Reflect.ownKeys(valueRecord);
+	if (ownKeys.length !== 3 || !ownKeys.every((key) => annotationWrapperKeys.has(key))) return false;
+	const annotations = Object.getOwnPropertyDescriptor(value, annotationKey);
+	const wrappedState = Object.getOwnPropertyDescriptor(value, annotationStateValueKey);
+	const wrapper = Object.getOwnPropertyDescriptor(value, annotationWrapperKey);
+	return annotations?.enumerable === true && annotations.writable === true && annotations.configurable === true && annotations.value != null && typeof annotations.value === "object" && wrappedState?.enumerable === false && wrappedState.writable === true && wrappedState.configurable === true && wrapper?.enumerable === false && wrapper.writable === true && wrapper.configurable === true && wrapper.value === true;
+}
+/**
+* Extracts annotations from parser state.
+*
+* @param state Parser state that may contain annotations
+* @returns Annotations object or undefined if no annotations are present
+* @since 0.10.0
+*
+* @example
+* ```typescript
+* const annotations = getAnnotations(state);
+* const myData = annotations?.[myDataKey];
+* ```
+*/
+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;
+	return void 0;
+}
+/**
+* Reattaches annotations to a freshly created array state.
+*
+* Array spread copies elements but drops symbol properties, so parsers that
+* rebuild array states need to copy annotations back explicitly.
+*
+* @param source The original state that may carry annotations.
+* @param target The freshly created array state.
+* @returns The target array, with annotations copied when available.
+* @internal
+*/
+function annotateFreshArray(source, target) {
+	const annotations = getAnnotations(source);
+	if (annotations === void 0) return target;
+	const annotated = target;
+	annotated[annotationKey] = annotations;
+	return annotated;
+}
+/**
+* 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. `inheritAnnotations()`
+* supports primitive and nullish targets via wrapper injection, plus arrays,
+* plain objects, and built-in container/value types that Optique clones
+* explicitly (`Date`, `Map`, `Set`, and `RegExp`). Non-plain custom objects
+* are returned unchanged to avoid mutating shared parser state.
+*
+* @param source The original state that may carry annotations.
+* @param target The new state to receive annotations when it is a supported
+*               target shape.
+* @returns A cloned or wrapped target with annotations copied when available,
+*          or the original unsupported non-plain target unchanged.
+* @since 1.0.0
+*/
+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.lastIndex = target.lastIndex;
+		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;
+}
+/**
+* Returns whether an annotations record carries at least one own symbol key.
+*
+* An annotations object with no own symbol keys is treated as a no-op by the
+* injection pipeline: it should behave identically to omitting the
+* `annotations` option entirely.  `null` and `undefined` are accepted for
+* call-site convenience and always return `false`.
+*
+* @param annotations The annotations record to check.
+* @returns `true` when the record has at least one own symbol key.
+* @internal
+*/
+function hasMeaningfulAnnotations(annotations) {
+	return annotations != null && Object.getOwnPropertySymbols(annotations).length > 0;
+}
+/**
+* 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.
+* - If the `annotations` record is nullish or has no own symbol keys, the
+*   state is returned unchanged.
+*
+* @param state The parser state to annotate.
+* @param annotations The annotations to inject.
+* @returns Annotated state.
+* @since 1.0.0
+*/
+function injectAnnotations(state, annotations) {
+	if (!hasMeaningfulAnnotations(annotations)) return state;
+	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)) {
+		const unwrapped = unwrapInjectedAnnotationWrapper(state);
+		if (unwrapped !== state) return injectAnnotations(unwrapped, annotations);
+		const cloned$1 = Object.create(Object.getPrototypeOf(state), Object.getOwnPropertyDescriptors(state));
+		cloned$1[annotationKey] = annotations;
+		injectedAnnotationWrappers.add(cloned$1);
+		return cloned$1;
+	}
+	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.lastIndex = state.lastIndex;
+		cloned$1[annotationKey] = annotations;
+		return cloned$1;
+	}
+	const proto = Object.getPrototypeOf(state);
+	if (proto === Object.prototype || proto === null) {
+		const cloned$1 = Object.create(proto, Object.getOwnPropertyDescriptors(state));
+		cloned$1[annotationKey] = annotations;
+		return cloned$1;
+	}
+	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;
+	if (!hasInjectedAnnotationWrapperShape(value)) return value;
+	const valueRecord = value;
+	return valueRecord[annotationStateValueKey];
+}
+/**
+* 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) || hasInjectedAnnotationWrapperShape(value));
+}
+/**
+* Returns whether the given value is an injected annotation state wrapper.
+*
+* This is the public name for Optique's primitive-state annotation wrapper
+* predicate.  Use it when custom parsers need to detect whether annotations
+* were attached by wrapping a primitive or nullish state value.
+*
+* @param value Value to check.
+* @returns `true` if the value is an injected annotation state wrapper.
+* @since 1.0.0
+*/
+function isInjectedAnnotationState(value) {
+	return isInjectedAnnotationWrapper(value);
+}
+/**
+* Unwraps an injected annotation state wrapper when present.
+*
+* This is the public name for Optique's primitive-state annotation unwrapping
+* helper.  It returns the original value unchanged for non-wrapper inputs.
+*
+* @param value Value to potentially unwrap.
+* @returns The unwrapped primitive value when the input is an injected
+*          annotation state wrapper; otherwise the original value.
+* @since 1.0.0
+*/
+function unwrapInjectedAnnotationState(value) {
+	return unwrapInjectedAnnotationWrapper(value);
+}
+
+//#endregion
+exports.annotateFreshArray = annotateFreshArray;
+exports.annotationKey = annotationKey;
+exports.getAnnotations = getAnnotations;
+exports.hasMeaningfulAnnotations = hasMeaningfulAnnotations;
+exports.inheritAnnotations = inheritAnnotations;
+exports.injectAnnotations = injectAnnotations;
+exports.isInjectedAnnotationState = isInjectedAnnotationState;
+exports.isInjectedAnnotationWrapper = isInjectedAnnotationWrapper;
+exports.unwrapInjectedAnnotationState = unwrapInjectedAnnotationState;
+exports.unwrapInjectedAnnotationWrapper = unwrapInjectedAnnotationWrapper;

package/dist/internal/annotations.d.cts

@@ -0,0 +1,140 @@
+//#region src/internal/annotations.d.ts
+
+/**
+ * Annotations that can be passed to parsers during execution.
+ * Allows external packages to provide additional data that parsers can access
+ * during complete() or parse() phases.
+ *
+ * @example
+ * ```typescript
+ * const myDataKey = Symbol.for("@my-package/data");
+ * const result = parse(parser, args, {
+ *   annotations: {
+ *     [myDataKey]: { foo: "bar" }
+ *   }
+ * });
+ * ```
+ * @since 0.10.0
+ */
+type Annotations = Record<symbol, unknown>;
+/**
+ * Options for parse functions.
+ * @since 0.10.0
+ */
+interface ParseOptions {
+  /**
+   * Annotations to attach to the parsing session.
+   * Parsers can access these annotations via getAnnotations(state).
+   */
+  readonly annotations?: Annotations;
+}
+/**
+ * Extracts annotations from parser state.
+ *
+ * @param state Parser state that may contain annotations
+ * @returns Annotations object or undefined if no annotations are present
+ * @since 0.10.0
+ *
+ * @example
+ * ```typescript
+ * const annotations = getAnnotations(state);
+ * const myData = annotations?.[myDataKey];
+ * ```
+ */
+declare function getAnnotations(state: unknown): Annotations | undefined;
+/**
+ * Reattaches annotations to a freshly created array state.
+ *
+ * Array spread copies elements but drops symbol properties, so parsers that
+ * rebuild array states need to copy annotations back explicitly.
+ *
+ * @param source The original state that may carry annotations.
+ * @param target The freshly created array state.
+ * @returns The target array, with annotations copied when available.
+ * @internal
+ */
+
+/**
+ * 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. `inheritAnnotations()`
+ * supports primitive and nullish targets via wrapper injection, plus arrays,
+ * plain objects, and built-in container/value types that Optique clones
+ * explicitly (`Date`, `Map`, `Set`, and `RegExp`). Non-plain custom objects
+ * are returned unchanged to avoid mutating shared parser state.
+ *
+ * @param source The original state that may carry annotations.
+ * @param target The new state to receive annotations when it is a supported
+ *               target shape.
+ * @returns A cloned or wrapped target with annotations copied when available,
+ *          or the original unsupported non-plain target unchanged.
+ * @since 1.0.0
+ */
+declare function inheritAnnotations<T>(source: unknown, target: T): T;
+/**
+ * Returns whether an annotations record carries at least one own symbol key.
+ *
+ * An annotations object with no own symbol keys is treated as a no-op by the
+ * injection pipeline: it should behave identically to omitting the
+ * `annotations` option entirely.  `null` and `undefined` are accepted for
+ * call-site convenience and always return `false`.
+ *
+ * @param annotations The annotations record to check.
+ * @returns `true` when the record has at least one own symbol key.
+ * @internal
+ */
+
+/**
+ * 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.
+ * - If the `annotations` record is nullish or has no own symbol keys, the
+ *   state is returned unchanged.
+ *
+ * @param state The parser state to annotate.
+ * @param annotations The annotations to inject.
+ * @returns Annotated state.
+ * @since 1.0.0
+ */
+declare function injectAnnotations<TState>(state: TState, annotations: Annotations | null | undefined): 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
+ */
+
+/**
+ * Returns whether the given value is an injected annotation state wrapper.
+ *
+ * This is the public name for Optique's primitive-state annotation wrapper
+ * predicate.  Use it when custom parsers need to detect whether annotations
+ * were attached by wrapping a primitive or nullish state value.
+ *
+ * @param value Value to check.
+ * @returns `true` if the value is an injected annotation state wrapper.
+ * @since 1.0.0
+ */
+declare function isInjectedAnnotationState(value: unknown): boolean;
+/**
+ * Unwraps an injected annotation state wrapper when present.
+ *
+ * This is the public name for Optique's primitive-state annotation unwrapping
+ * helper.  It returns the original value unchanged for non-wrapper inputs.
+ *
+ * @param value Value to potentially unwrap.
+ * @returns The unwrapped primitive value when the input is an injected
+ *          annotation state wrapper; otherwise the original value.
+ * @since 1.0.0
+ */
+declare function unwrapInjectedAnnotationState<T>(value: T): T;
+//#endregion
+export { Annotations, ParseOptions, getAnnotations, inheritAnnotations, injectAnnotations, isInjectedAnnotationState, unwrapInjectedAnnotationState };

package/dist/internal/annotations.d.ts

@@ -0,0 +1,140 @@
+//#region src/internal/annotations.d.ts
+
+/**
+ * Annotations that can be passed to parsers during execution.
+ * Allows external packages to provide additional data that parsers can access
+ * during complete() or parse() phases.
+ *
+ * @example
+ * ```typescript
+ * const myDataKey = Symbol.for("@my-package/data");
+ * const result = parse(parser, args, {
+ *   annotations: {
+ *     [myDataKey]: { foo: "bar" }
+ *   }
+ * });
+ * ```
+ * @since 0.10.0
+ */
+type Annotations = Record<symbol, unknown>;
+/**
+ * Options for parse functions.
+ * @since 0.10.0
+ */
+interface ParseOptions {
+  /**
+   * Annotations to attach to the parsing session.
+   * Parsers can access these annotations via getAnnotations(state).
+   */
+  readonly annotations?: Annotations;
+}
+/**
+ * Extracts annotations from parser state.
+ *
+ * @param state Parser state that may contain annotations
+ * @returns Annotations object or undefined if no annotations are present
+ * @since 0.10.0
+ *
+ * @example
+ * ```typescript
+ * const annotations = getAnnotations(state);
+ * const myData = annotations?.[myDataKey];
+ * ```
+ */
+declare function getAnnotations(state: unknown): Annotations | undefined;
+/**
+ * Reattaches annotations to a freshly created array state.
+ *
+ * Array spread copies elements but drops symbol properties, so parsers that
+ * rebuild array states need to copy annotations back explicitly.
+ *
+ * @param source The original state that may carry annotations.
+ * @param target The freshly created array state.
+ * @returns The target array, with annotations copied when available.
+ * @internal
+ */
+
+/**
+ * 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. `inheritAnnotations()`
+ * supports primitive and nullish targets via wrapper injection, plus arrays,
+ * plain objects, and built-in container/value types that Optique clones
+ * explicitly (`Date`, `Map`, `Set`, and `RegExp`). Non-plain custom objects
+ * are returned unchanged to avoid mutating shared parser state.
+ *
+ * @param source The original state that may carry annotations.
+ * @param target The new state to receive annotations when it is a supported
+ *               target shape.
+ * @returns A cloned or wrapped target with annotations copied when available,
+ *          or the original unsupported non-plain target unchanged.
+ * @since 1.0.0
+ */
+declare function inheritAnnotations<T>(source: unknown, target: T): T;
+/**
+ * Returns whether an annotations record carries at least one own symbol key.
+ *
+ * An annotations object with no own symbol keys is treated as a no-op by the
+ * injection pipeline: it should behave identically to omitting the
+ * `annotations` option entirely.  `null` and `undefined` are accepted for
+ * call-site convenience and always return `false`.
+ *
+ * @param annotations The annotations record to check.
+ * @returns `true` when the record has at least one own symbol key.
+ * @internal
+ */
+
+/**
+ * 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.
+ * - If the `annotations` record is nullish or has no own symbol keys, the
+ *   state is returned unchanged.
+ *
+ * @param state The parser state to annotate.
+ * @param annotations The annotations to inject.
+ * @returns Annotated state.
+ * @since 1.0.0
+ */
+declare function injectAnnotations<TState>(state: TState, annotations: Annotations | null | undefined): 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
+ */
+
+/**
+ * Returns whether the given value is an injected annotation state wrapper.
+ *
+ * This is the public name for Optique's primitive-state annotation wrapper
+ * predicate.  Use it when custom parsers need to detect whether annotations
+ * were attached by wrapping a primitive or nullish state value.
+ *
+ * @param value Value to check.
+ * @returns `true` if the value is an injected annotation state wrapper.
+ * @since 1.0.0
+ */
+declare function isInjectedAnnotationState(value: unknown): boolean;
+/**
+ * Unwraps an injected annotation state wrapper when present.
+ *
+ * This is the public name for Optique's primitive-state annotation unwrapping
+ * helper.  It returns the original value unchanged for non-wrapper inputs.
+ *
+ * @param value Value to potentially unwrap.
+ * @returns The unwrapped primitive value when the input is an injected
+ *          annotation state wrapper; otherwise the original value.
+ * @since 1.0.0
+ */
+declare function unwrapInjectedAnnotationState<T>(value: T): T;
+//#endregion
+export { Annotations, ParseOptions, getAnnotations, inheritAnnotations, injectAnnotations, isInjectedAnnotationState, unwrapInjectedAnnotationState };