@optique/core 1.0.0-dev.908 → 1.0.0

package/dist/annotations.d.cts

@@ -1,137 +1,2 @@
-//#region src/annotations.d.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
- */
-declare const annotationKey: unique symbol;
-/**
- * Internal marker attached during the first pass of `runWith()` so wrappers
- * with side effects can defer work until dynamic contexts have resolved.
- *
- * @internal
- */
-declare const firstPassAnnotationKey: 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
- * 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).
-   */
-  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
- */
-declare function annotateFreshArray<T>(source: unknown, target: readonly T[]): readonly T[];
-/**
- * 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, annotateFreshArray, annotationKey, annotationStateValueKey, annotationWrapperKey, firstPassAnnotationKey, getAnnotations, inheritAnnotations, injectAnnotations, isInjectedAnnotationWrapper, unwrapInjectedAnnotationWrapper };
+import { Annotations, ParseOptions, getAnnotations } from "./internal/annotations.cjs";
+export { type Annotations, type ParseOptions, getAnnotations };

package/dist/annotations.d.ts

@@ -1,137 +1,2 @@
-//#region src/annotations.d.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
- */
-declare const annotationKey: unique symbol;
-/**
- * Internal marker attached during the first pass of `runWith()` so wrappers
- * with side effects can defer work until dynamic contexts have resolved.
- *
- * @internal
- */
-declare const firstPassAnnotationKey: 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
- * 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).
-   */
-  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
- */
-declare function annotateFreshArray<T>(source: unknown, target: readonly T[]): readonly T[];
-/**
- * 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, annotateFreshArray, annotationKey, annotationStateValueKey, annotationWrapperKey, firstPassAnnotationKey, getAnnotations, inheritAnnotations, injectAnnotations, isInjectedAnnotationWrapper, unwrapInjectedAnnotationWrapper };
+import { Annotations, ParseOptions, getAnnotations } from "./internal/annotations.js";
+export { type Annotations, type ParseOptions, getAnnotations };

package/dist/annotations.js

@@ -1,239 +1,3 @@
-//#region src/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 dynamic 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();
-/**
-* 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.
-*
-* @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);
-}
+import { getAnnotations } from "./internal/annotations.js";
 
-//#endregion
-export { annotateFreshArray, annotationKey, annotationStateValueKey, annotationWrapperKey, firstPassAnnotationKey, getAnnotations, inheritAnnotations, injectAnnotations, isInjectedAnnotationWrapper, unwrapInjectedAnnotationWrapper };
+export { getAnnotations };