@optique/core 0.10.7 → 1.0.0-dev.1109

package/README.md

@@ -1,9 +1,6 @@
 @optique/core
 =============
 
-> [!WARNING]
-> The API is stabilizing, but may change before the 1.0 release.
-
 The core package of Optique which provides the shared types and parser
 combinators. It is designed to be used in universal JavaScript runtimes,
 including Node.js, Deno, Bun, edge functions, and web browsers—although
@@ -38,7 +35,8 @@ Quick example
 
 ~~~~ typescript
 import { runParser } from "@optique/core/facade";
-import { object, option, argument } from "@optique/core/parser";
+import { option, argument } from "@optique/core/primitives";
+import { object } from "@optique/core/constructs";
 import { string, integer } from "@optique/core/valueparser";
 import process from "node:process";
 
@@ -49,8 +47,8 @@ const parser = object({
 });
 
 const config = runParser(parser, "myapp", process.argv.slice(2), {
-  help: "both",
-  onError: process.exit,
+  help: { command: true, option: true },
+  onError: (exitCode) => process.exit(exitCode),
 });
 
 console.log(`Hello ${config.name}!`);

package/dist/annotations.cjs

@@ -16,6 +16,36 @@
 */
 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
@@ -35,7 +65,185 @@ function getAnnotations(state) {
 	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);
+}
 
 //#endregion
+exports.annotateFreshArray = annotateFreshArray;
 exports.annotationKey = annotationKey;
-exports.getAnnotations = getAnnotations;
+exports.annotationStateValueKey = annotationStateValueKey;
+exports.annotationWrapperKey = annotationWrapperKey;
+exports.firstPassAnnotationKey = firstPassAnnotationKey;
+exports.getAnnotations = getAnnotations;
+exports.inheritAnnotations = inheritAnnotations;
+exports.injectAnnotations = injectAnnotations;
+exports.isInjectedAnnotationWrapper = isInjectedAnnotationWrapper;
+exports.unwrapInjectedAnnotationWrapper = unwrapInjectedAnnotationWrapper;

package/dist/annotations.d.cts

@@ -14,6 +14,25 @@
  * @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
@@ -56,5 +75,63 @@ interface ParseOptions {
  * ```
  */
 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, annotationKey, getAnnotations };
+export { Annotations, ParseOptions, annotateFreshArray, annotationKey, annotationStateValueKey, annotationWrapperKey, firstPassAnnotationKey, getAnnotations, inheritAnnotations, injectAnnotations, isInjectedAnnotationWrapper, unwrapInjectedAnnotationWrapper };

package/dist/annotations.d.ts

@@ -14,6 +14,25 @@
  * @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
@@ -56,5 +75,63 @@ interface ParseOptions {
  * ```
  */
 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, annotationKey, getAnnotations };
+export { Annotations, ParseOptions, annotateFreshArray, annotationKey, annotationStateValueKey, annotationWrapperKey, firstPassAnnotationKey, getAnnotations, inheritAnnotations, injectAnnotations, isInjectedAnnotationWrapper, unwrapInjectedAnnotationWrapper };

package/dist/annotations.js

@@ -15,6 +15,36 @@
 */
 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
@@ -34,6 +64,176 @@ function getAnnotations(state) {
 	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);
+}
 
 //#endregion
-export { annotationKey, getAnnotations };
+export { annotateFreshArray, annotationKey, annotationStateValueKey, annotationWrapperKey, firstPassAnnotationKey, getAnnotations, inheritAnnotations, injectAnnotations, isInjectedAnnotationWrapper, unwrapInjectedAnnotationWrapper };