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

package/dist/internal/annotations.d.cts

@@ -1,5 +1,38 @@
 //#region src/internal/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 two-pass 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
@@ -53,7 +86,7 @@ declare function getAnnotations(state: unknown): Annotations | undefined;
  * @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.
  *
@@ -85,7 +118,7 @@ declare function inheritAnnotations<T>(source: unknown, target: T): T;
  * @returns `true` when the record has at least one own symbol key.
  * @internal
  */
-
+declare function hasMeaningfulAnnotations(annotations: Annotations | null | undefined): annotations is Annotations;
 /**
  * Injects annotations into parser state while preserving state shape.
  *
@@ -111,7 +144,16 @@ declare function injectAnnotations<TState>(state: TState, annotations: Annotatio
  *          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;
 /**
  * Returns whether the given value is an injected annotation state wrapper.
  *
@@ -137,4 +179,4 @@ declare function isInjectedAnnotationState(value: unknown): boolean;
  */
 declare function unwrapInjectedAnnotationState<T>(value: T): T;
 //#endregion
-export { Annotations, ParseOptions, getAnnotations, inheritAnnotations, injectAnnotations, isInjectedAnnotationState, unwrapInjectedAnnotationState };
+export { Annotations, ParseOptions, annotateFreshArray, annotationKey, annotationStateValueKey, annotationWrapperKey, firstPassAnnotationKey, getAnnotations, hasMeaningfulAnnotations, inheritAnnotations, injectAnnotations, isInjectedAnnotationState, isInjectedAnnotationWrapper, unwrapInjectedAnnotationState, unwrapInjectedAnnotationWrapper };

package/dist/internal/annotations.d.ts

@@ -1,5 +1,38 @@
 //#region src/internal/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 two-pass 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
@@ -53,7 +86,7 @@ declare function getAnnotations(state: unknown): Annotations | undefined;
  * @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.
  *
@@ -85,7 +118,7 @@ declare function inheritAnnotations<T>(source: unknown, target: T): T;
  * @returns `true` when the record has at least one own symbol key.
  * @internal
  */
-
+declare function hasMeaningfulAnnotations(annotations: Annotations | null | undefined): annotations is Annotations;
 /**
  * Injects annotations into parser state while preserving state shape.
  *
@@ -111,7 +144,16 @@ declare function injectAnnotations<TState>(state: TState, annotations: Annotatio
  *          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;
 /**
  * Returns whether the given value is an injected annotation state wrapper.
  *
@@ -137,4 +179,4 @@ declare function isInjectedAnnotationState(value: unknown): boolean;
  */
 declare function unwrapInjectedAnnotationState<T>(value: T): T;
 //#endregion
-export { Annotations, ParseOptions, getAnnotations, inheritAnnotations, injectAnnotations, isInjectedAnnotationState, unwrapInjectedAnnotationState };
+export { Annotations, ParseOptions, annotateFreshArray, annotationKey, annotationStateValueKey, annotationWrapperKey, firstPassAnnotationKey, getAnnotations, hasMeaningfulAnnotations, inheritAnnotations, injectAnnotations, isInjectedAnnotationState, isInjectedAnnotationWrapper, unwrapInjectedAnnotationState, unwrapInjectedAnnotationWrapper };

package/dist/internal/annotations.js

@@ -303,4 +303,4 @@ function unwrapInjectedAnnotationState(value) {
 }
 
 //#endregion
-export { annotateFreshArray, annotationKey, getAnnotations, hasMeaningfulAnnotations, inheritAnnotations, injectAnnotations, isInjectedAnnotationState, isInjectedAnnotationWrapper, unwrapInjectedAnnotationState, unwrapInjectedAnnotationWrapper };
+export { annotateFreshArray, annotationKey, annotationStateValueKey, annotationWrapperKey, firstPassAnnotationKey, getAnnotations, hasMeaningfulAnnotations, inheritAnnotations, injectAnnotations, isInjectedAnnotationState, isInjectedAnnotationWrapper, unwrapInjectedAnnotationState, unwrapInjectedAnnotationWrapper };

package/dist/internal/command-alias.cjs

@@ -0,0 +1,16 @@
+
+//#region src/internal/command-alias.ts
+/**
+* Internal key used to bypass duplicate leading command name validation when
+* composing built-in meta commands with user parsers.
+*/
+const allowDuplicateLeadingCommandNamesKey = Symbol("allowDuplicateLeadingCommandNames");
+/**
+* Internal command() option key for aliases that are accepted by parsing but
+* omitted from completion and typo-suggestion display.
+*/
+const hiddenCommandAliasesKey = Symbol("hiddenCommandAliases");
+
+//#endregion
+exports.allowDuplicateLeadingCommandNamesKey = allowDuplicateLeadingCommandNamesKey;
+exports.hiddenCommandAliasesKey = hiddenCommandAliasesKey;

package/dist/internal/command-alias.js

@@ -0,0 +1,14 @@
+//#region src/internal/command-alias.ts
+/**
+* Internal key used to bypass duplicate leading command name validation when
+* composing built-in meta commands with user parsers.
+*/
+const allowDuplicateLeadingCommandNamesKey = Symbol("allowDuplicateLeadingCommandNames");
+/**
+* Internal command() option key for aliases that are accepted by parsing but
+* omitted from completion and typo-suggestion display.
+*/
+const hiddenCommandAliasesKey = Symbol("hiddenCommandAliases");
+
+//#endregion
+export { allowDuplicateLeadingCommandNamesKey, hiddenCommandAliasesKey };

package/dist/internal/dependency.cjs

@@ -885,6 +885,37 @@ function getDefaultValuesFunction(parser) {
 	return void 0;
 }
 /**
+* Creates a deferred parse state for a DerivedValueParser.
+*
+* @template T The type of value the parser will produce.
+* @template S The type of the source dependency value.
+* @param rawInput The raw input string to be parsed.
+* @param parser The DerivedValueParser that will parse the input.
+* @param preliminaryResult The parse result using default dependency value.
+* @returns A DeferredParseState object.
+* @since 0.10.0
+*/
+function createDeferredParseState(rawInput, parser, preliminaryResult) {
+	const multipleIds = dependencyIds in parser ? parser[dependencyIds] : void 0;
+	const defaultValuesFn = getDefaultValuesFunction(parser);
+	let defaultVals = getSnapshottedDefaultDependencyValues(preliminaryResult);
+	if (defaultVals != null) defaultVals = [...defaultVals];
+	if (defaultVals == null && defaultValuesFn != null) try {
+		defaultVals = [...defaultValuesFn()];
+	} catch {
+		defaultVals = void 0;
+	}
+	return {
+		[deferredParseMarker]: true,
+		rawInput,
+		parser,
+		dependencyId: parser[dependencyId],
+		dependencyIds: multipleIds,
+		defaultValues: defaultVals,
+		preliminaryResult
+	};
+}
+/**
 * A unique symbol used to identify dependency source parse states.
 * @since 0.10.0
 */
@@ -931,6 +962,19 @@ function isPendingDependencySourceState(value) {
 	return typeof value === "object" && value !== null && pendingDependencySourceStateMarker in value && value[pendingDependencySourceStateMarker] === true;
 }
 /**
+* Creates a pending dependency source state.
+*
+* @param depId The dependency ID.
+* @returns A PendingDependencySourceState object.
+* @since 0.10.0
+*/
+function createPendingDependencySourceState(depId) {
+	return {
+		[pendingDependencySourceStateMarker]: true,
+		[dependencyId]: depId
+	};
+}
+/**
 * A unique symbol used to identify parsers that wrap a dependency source.
 * This is used by withDefault to indicate it contains an inner parser
 * with a PendingDependencySourceState initialState.
@@ -950,6 +994,16 @@ const wrappedDependencySourceMarker = Symbol.for("@optique/core/dependency/wrapp
 */
 const transformsDependencyValueMarker = Symbol.for("@optique/core/dependency/transformsDependencyValueMarker");
 /**
+* Checks if a parser transforms the dependency value (has transformsDependencyValueMarker).
+*
+* @param parser The parser to check.
+* @returns `true` if the parser transforms the dependency value.
+* @since 0.10.0
+*/
+function transformsDependencyValue(parser) {
+	return typeof parser === "object" && parser !== null && transformsDependencyValueMarker in parser && parser[transformsDependencyValueMarker] === true;
+}
+/**
 * Checks if a parser wraps a dependency source (has wrappedDependencySourceMarker).
 *
 * @param parser The parser to check.
@@ -959,16 +1013,89 @@ const transformsDependencyValueMarker = Symbol.for("@optique/core/dependency/tra
 function isWrappedDependencySource(parser) {
 	return typeof parser === "object" && parser !== null && wrappedDependencySourceMarker in parser;
 }
+/**
+* A registry for storing resolved dependency values during parsing.
+* This is used to pass dependency values from DependencySource options
+* to DerivedValueParser options.
+* @since 0.10.0
+*/
+var DependencyRegistry = class DependencyRegistry {
+	values = /* @__PURE__ */ new Map();
+	/**
+	* Registers a resolved dependency value.
+	* @param id The dependency ID.
+	* @param value The resolved value.
+	*/
+	set(id, value) {
+		this.values.set(id, value);
+	}
+	/**
+	* Gets a resolved dependency value.
+	* @param id The dependency ID.
+	* @returns The resolved value, or undefined if not found.
+	*/
+	get(id) {
+		return this.values.get(id);
+	}
+	/**
+	* Checks if a dependency has been resolved.
+	* @param id The dependency ID.
+	* @returns `true` if the dependency has been resolved.
+	*/
+	has(id) {
+		return this.values.has(id);
+	}
+	/**
+	* Creates a copy of the registry.
+	*/
+	clone() {
+		const copy = new DependencyRegistry();
+		for (const [id, value] of this.values) copy.values.set(id, value);
+		return copy;
+	}
+};
+/**
+* Formats a {@link DependencyError} into a human-readable {@link Message}.
+*
+* @param error The dependency error to format.
+* @returns A Message describing the error.
+* @since 0.10.0
+*/
+function formatDependencyError(error) {
+	switch (error.kind) {
+		case "duplicate": return [{
+			type: "text",
+			text: `Dependency used in multiple locations: ${error.locations.join(", ")}.`
+		}];
+		case "unresolved": return [{
+			type: "text",
+			text: `Unresolved dependency for ${error.derivedParserMetavar}: the dependency was not provided.`
+		}];
+		case "circular": return [{
+			type: "text",
+			text: `Circular dependency detected.`
+		}];
+	}
+}
 
 //#endregion
+exports.DependencyRegistry = DependencyRegistry;
+exports.createDeferredParseState = createDeferredParseState;
 exports.createDependencySourceState = createDependencySourceState;
+exports.createPendingDependencySourceState = createPendingDependencySourceState;
+exports.defaultDependencyValueSnapshot = defaultDependencyValueSnapshot;
 exports.defaultValues = defaultValues;
+exports.deferredParseMarker = deferredParseMarker;
 exports.dependency = dependency;
 exports.dependencyId = dependencyId;
 exports.dependencyIds = dependencyIds;
+exports.dependencySourceMarker = dependencySourceMarker;
+exports.dependencySourceStateMarker = dependencySourceStateMarker;
 exports.deriveFrom = deriveFrom;
 exports.deriveFromAsync = deriveFromAsync;
 exports.deriveFromSync = deriveFromSync;
+exports.derivedValueParserMarker = derivedValueParserMarker;
+exports.formatDependencyError = formatDependencyError;
 exports.getDefaultValuesFunction = getDefaultValuesFunction;
 exports.getDependencyIds = getDependencyIds;
 exports.getSnapshottedDefaultDependencyValues = getSnapshottedDefaultDependencyValues;
@@ -979,6 +1106,10 @@ exports.isDerivedValueParser = isDerivedValueParser;
 exports.isPendingDependencySourceState = isPendingDependencySourceState;
 exports.isWrappedDependencySource = isWrappedDependencySource;
 exports.parseWithDependency = parseWithDependency;
+exports.pendingDependencySourceStateMarker = pendingDependencySourceStateMarker;
 exports.singleDefaultValue = singleDefaultValue;
+exports.snapshotDefaultDependencyValues = snapshotDefaultDependencyValues;
 exports.suggestWithDependency = suggestWithDependency;
+exports.transformsDependencyValue = transformsDependencyValue;
+exports.transformsDependencyValueMarker = transformsDependencyValueMarker;
 exports.wrappedDependencySourceMarker = wrappedDependencySourceMarker;