@optique/core 0.10.0-dev.330 → 0.10.0-dev.331

package/dist/annotations.cjs

@@ -0,0 +1,41 @@
+
+//#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");
+/**
+* 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;
+}
+
+//#endregion
+exports.annotationKey = annotationKey;
+exports.getAnnotations = getAnnotations;

package/dist/annotations.d.cts

@@ -0,0 +1,60 @@
+//#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;
+/**
+ * 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;
+//#endregion
+export { Annotations, ParseOptions, annotationKey, getAnnotations };

package/dist/annotations.d.ts

@@ -0,0 +1,60 @@
+//#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;
+/**
+ * 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;
+//#endregion
+export { Annotations, ParseOptions, annotationKey, getAnnotations };

package/dist/annotations.js

@@ -0,0 +1,39 @@
+//#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");
+/**
+* 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;
+}
+
+//#endregion
+export { annotationKey, getAnnotations };

package/dist/index.cjs

@@ -1,3 +1,4 @@
+const require_annotations = require('./annotations.cjs');
 const require_message = require('./message.cjs');
 const require_completion = require('./completion.cjs');
 const require_dependency = require('./dependency.cjs');
@@ -15,6 +16,7 @@ exports.DependencyRegistry = require_dependency.DependencyRegistry;
 exports.DuplicateOptionError = require_constructs.DuplicateOptionError;
 exports.RunParserError = require_facade.RunParserError;
 exports.WithDefaultError = require_modifiers.WithDefaultError;
+exports.annotationKey = require_annotations.annotationKey;
 exports.argument = require_primitives.argument;
 exports.bash = require_completion.bash;
 exports.choice = require_valueparser.choice;
@@ -50,6 +52,7 @@ exports.formatDocPage = require_doc.formatDocPage;
 exports.formatMessage = require_message.formatMessage;
 exports.formatUsage = require_usage.formatUsage;
 exports.formatUsageTerm = require_usage.formatUsageTerm;
+exports.getAnnotations = require_annotations.getAnnotations;
 exports.getDefaultValuesFunction = require_dependency.getDefaultValuesFunction;
 exports.getDependencyIds = require_dependency.getDependencyIds;
 exports.getDocPage = require_parser.getDocPage;

package/dist/index.d.cts

@@ -1,3 +1,4 @@
+import { Annotations, ParseOptions, annotationKey, getAnnotations } from "./annotations.cjs";
 import { NonEmptyString, ensureNonEmptyString, isNonEmptyString } from "./nonempty.cjs";
 import { Message, MessageFormatOptions, MessageTerm, ValueSetOptions, commandLine, envVar, formatMessage, link, message, metavar, optionName, optionNames, text, value, valueSet, values } from "./message.cjs";
 import { OptionName, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, extractArgumentMetavars, extractCommandNames, extractOptionNames, formatUsage, formatUsageTerm, normalizeUsage } from "./usage.cjs";
@@ -10,4 +11,4 @@ import { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOpti
 import { CombineModes, DocState, InferMode, InferValue, Mode, ModeIterable, ModeValue, Parser, ParserContext, ParserResult, Result, Suggestion, getDocPage, getDocPageAsync, getDocPageSync, parse, parseAsync, parseSync, suggest, suggestAsync, suggestSync } from "./parser.cjs";
 import { ShellCompletion, bash, fish, nu, pwsh, zsh } from "./completion.cjs";
 import { RunOptions, RunParserError, runParser, runParserAsync, runParserSync } from "./facade.cjs";
-export { AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandOptions, ConditionalErrorOptions, ConditionalOptions, DeferredParseState, DependencyError, DependencyMode, DependencyRegistry, DependencySource, DependencySourceState, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DuplicateOptionError, FlagErrorOptions, FlagOptions, FloatOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OrErrorOptions, OrOptions, Parser, ParserContext, ParserResult, PassThroughFormat, PassThroughOptions, PendingDependencySourceState, ResolvedDependency, Result, RunOptions, RunParserError, ShellCompletion, ShowDefaultOptions, StringOptions, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, argument, bash, choice, command, commandLine, concat, conditional, constant, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractOptionNames, fish, flag, float, formatDependencyError, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getDefaultValuesFunction, getDependencyIds, getDocPage, getDocPageAsync, getDocPageSync, group, integer, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isNonEmptyString, isPendingDependencySourceState, isValueParser, isWrappedDependencySource, link, locale, longestMatch, map, merge, message, metavar, multiple, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, parseWithDependency, passThrough, pendingDependencySourceStateMarker, pwsh, runParser, runParserAsync, runParserSync, string, suggest, suggestAsync, suggestSync, suggestWithDependency, text, transformsDependencyValue, transformsDependencyValueMarker, tuple, url, uuid, value, valueSet, values, withDefault, wrappedDependencySourceMarker, zsh };
+export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandOptions, ConditionalErrorOptions, ConditionalOptions, DeferredParseState, DependencyError, DependencyMode, DependencyRegistry, DependencySource, DependencySourceState, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DuplicateOptionError, FlagErrorOptions, FlagOptions, FloatOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OrErrorOptions, OrOptions, type ParseOptions, Parser, ParserContext, ParserResult, PassThroughFormat, PassThroughOptions, PendingDependencySourceState, ResolvedDependency, Result, RunOptions, RunParserError, ShellCompletion, ShowDefaultOptions, StringOptions, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, annotationKey, argument, bash, choice, command, commandLine, concat, conditional, constant, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractOptionNames, fish, flag, float, formatDependencyError, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDefaultValuesFunction, getDependencyIds, getDocPage, getDocPageAsync, getDocPageSync, group, integer, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isNonEmptyString, isPendingDependencySourceState, isValueParser, isWrappedDependencySource, link, locale, longestMatch, map, merge, message, metavar, multiple, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, parseWithDependency, passThrough, pendingDependencySourceStateMarker, pwsh, runParser, runParserAsync, runParserSync, string, suggest, suggestAsync, suggestSync, suggestWithDependency, text, transformsDependencyValue, transformsDependencyValueMarker, tuple, url, uuid, value, valueSet, values, withDefault, wrappedDependencySourceMarker, zsh };

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+import { Annotations, ParseOptions, annotationKey, getAnnotations } from "./annotations.js";
 import { NonEmptyString, ensureNonEmptyString, isNonEmptyString } from "./nonempty.js";
 import { Message, MessageFormatOptions, MessageTerm, ValueSetOptions, commandLine, envVar, formatMessage, link, message, metavar, optionName, optionNames, text, value, valueSet, values } from "./message.js";
 import { OptionName, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, extractArgumentMetavars, extractCommandNames, extractOptionNames, formatUsage, formatUsageTerm, normalizeUsage } from "./usage.js";
@@ -10,4 +11,4 @@ import { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOpti
 import { CombineModes, DocState, InferMode, InferValue, Mode, ModeIterable, ModeValue, Parser, ParserContext, ParserResult, Result, Suggestion, getDocPage, getDocPageAsync, getDocPageSync, parse, parseAsync, parseSync, suggest, suggestAsync, suggestSync } from "./parser.js";
 import { ShellCompletion, bash, fish, nu, pwsh, zsh } from "./completion.js";
 import { RunOptions, RunParserError, runParser, runParserAsync, runParserSync } from "./facade.js";
-export { AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandOptions, ConditionalErrorOptions, ConditionalOptions, DeferredParseState, DependencyError, DependencyMode, DependencyRegistry, DependencySource, DependencySourceState, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DuplicateOptionError, FlagErrorOptions, FlagOptions, FloatOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OrErrorOptions, OrOptions, Parser, ParserContext, ParserResult, PassThroughFormat, PassThroughOptions, PendingDependencySourceState, ResolvedDependency, Result, RunOptions, RunParserError, ShellCompletion, ShowDefaultOptions, StringOptions, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, argument, bash, choice, command, commandLine, concat, conditional, constant, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractOptionNames, fish, flag, float, formatDependencyError, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getDefaultValuesFunction, getDependencyIds, getDocPage, getDocPageAsync, getDocPageSync, group, integer, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isNonEmptyString, isPendingDependencySourceState, isValueParser, isWrappedDependencySource, link, locale, longestMatch, map, merge, message, metavar, multiple, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, parseWithDependency, passThrough, pendingDependencySourceStateMarker, pwsh, runParser, runParserAsync, runParserSync, string, suggest, suggestAsync, suggestSync, suggestWithDependency, text, transformsDependencyValue, transformsDependencyValueMarker, tuple, url, uuid, value, valueSet, values, withDefault, wrappedDependencySourceMarker, zsh };
+export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandOptions, ConditionalErrorOptions, ConditionalOptions, DeferredParseState, DependencyError, DependencyMode, DependencyRegistry, DependencySource, DependencySourceState, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DuplicateOptionError, FlagErrorOptions, FlagOptions, FloatOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OrErrorOptions, OrOptions, type ParseOptions, Parser, ParserContext, ParserResult, PassThroughFormat, PassThroughOptions, PendingDependencySourceState, ResolvedDependency, Result, RunOptions, RunParserError, ShellCompletion, ShowDefaultOptions, StringOptions, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, annotationKey, argument, bash, choice, command, commandLine, concat, conditional, constant, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractOptionNames, fish, flag, float, formatDependencyError, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDefaultValuesFunction, getDependencyIds, getDocPage, getDocPageAsync, getDocPageSync, group, integer, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isNonEmptyString, isPendingDependencySourceState, isValueParser, isWrappedDependencySource, link, locale, longestMatch, map, merge, message, metavar, multiple, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, parseWithDependency, passThrough, pendingDependencySourceStateMarker, pwsh, runParser, runParserAsync, runParserSync, string, suggest, suggestAsync, suggestSync, suggestWithDependency, text, transformsDependencyValue, transformsDependencyValueMarker, tuple, url, uuid, value, valueSet, values, withDefault, wrappedDependencySourceMarker, zsh };

package/dist/index.js

@@ -1,3 +1,4 @@
+import { annotationKey, getAnnotations } from "./annotations.js";
 import { commandLine, envVar, formatMessage, link, message, metavar, optionName, optionNames, text, value, valueSet, values } from "./message.js";
 import { bash, fish, nu, pwsh, zsh } from "./completion.js";
 import { DependencyRegistry, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, formatDependencyError, getDefaultValuesFunction, getDependencyIds, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isPendingDependencySourceState, isWrappedDependencySource, parseWithDependency, pendingDependencySourceStateMarker, suggestWithDependency, transformsDependencyValue, transformsDependencyValueMarker, wrappedDependencySourceMarker } from "./dependency.js";
@@ -11,4 +12,4 @@ import { argument, command, constant, flag, option, passThrough } from "./primit
 import { getDocPage, getDocPageAsync, getDocPageSync, parse, parseAsync, parseSync, suggest, suggestAsync, suggestSync } from "./parser.js";
 import { RunParserError, runParser, runParserAsync, runParserSync } from "./facade.js";
 
-export { DependencyRegistry, DuplicateOptionError, RunParserError, WithDefaultError, argument, bash, choice, command, commandLine, concat, conditional, constant, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractOptionNames, fish, flag, float, formatDependencyError, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getDefaultValuesFunction, getDependencyIds, getDocPage, getDocPageAsync, getDocPageSync, group, integer, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isNonEmptyString, isPendingDependencySourceState, isValueParser, isWrappedDependencySource, link, locale, longestMatch, map, merge, message, metavar, multiple, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, parseWithDependency, passThrough, pendingDependencySourceStateMarker, pwsh, runParser, runParserAsync, runParserSync, string, suggest, suggestAsync, suggestSync, suggestWithDependency, text, transformsDependencyValue, transformsDependencyValueMarker, tuple, url, uuid, value, valueSet, values, withDefault, wrappedDependencySourceMarker, zsh };
+export { DependencyRegistry, DuplicateOptionError, RunParserError, WithDefaultError, annotationKey, argument, bash, choice, command, commandLine, concat, conditional, constant, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractOptionNames, fish, flag, float, formatDependencyError, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDefaultValuesFunction, getDependencyIds, getDocPage, getDocPageAsync, getDocPageSync, group, integer, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isNonEmptyString, isPendingDependencySourceState, isValueParser, isWrappedDependencySource, link, locale, longestMatch, map, merge, message, metavar, multiple, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, parseWithDependency, passThrough, pendingDependencySourceStateMarker, pwsh, runParser, runParserAsync, runParserSync, string, suggest, suggestAsync, suggestSync, suggestWithDependency, text, transformsDependencyValue, transformsDependencyValueMarker, tuple, url, uuid, value, valueSet, values, withDefault, wrappedDependencySourceMarker, zsh };

package/dist/parser.cjs

@@ -1,3 +1,4 @@
+const require_annotations = require('./annotations.cjs');
 const require_message = require('./message.cjs');
 const require_usage = require('./usage.cjs');
 const require_constructs = require('./constructs.cjs');
@@ -18,18 +19,25 @@ const require_primitives = require('./primitives.cjs');
 *               arguments.  Must be a synchronous parser.
 * @param args The array of command-line arguments to parse.  Usually this is
 *             `process.argv.slice(2)` in Node.js or `Deno.args` in Deno.
+* @param options Optional {@link ParseOptions} for customizing parsing behavior.
 * @returns A {@link Result} object indicating whether the parsing was
 *          successful or not.  If successful, it contains the parsed value of
 *          type `T`.  If not, it contains an error message describing the
 *          failure.
 * @since 0.9.0 Renamed from the original `parse` function which now delegates
 *              to this for sync parsers.
+* @since 0.10.0 Added optional `options` parameter for annotations support.
 */
-function parseSync(parser, args) {
+function parseSync(parser, args, options) {
+	let initialState = parser.initialState;
+	if (options?.annotations) initialState = {
+		...typeof initialState === "object" && initialState !== null ? initialState : {},
+		[require_annotations.annotationKey]: options.annotations
+	};
 	let context = {
 		buffer: args,
 		optionsTerminated: false,
-		state: parser.initialState,
+		state: initialState,
 		usage: parser.usage
 	};
 	do {
@@ -67,15 +75,22 @@ function parseSync(parser, args) {
 *               arguments.
 * @param args The array of command-line arguments to parse.  Usually this is
 *             `process.argv.slice(2)` in Node.js or `Deno.args` in Deno.
+* @param options Optional {@link ParseOptions} for customizing parsing behavior.
 * @returns A Promise that resolves to a {@link Result} object indicating
 *          whether the parsing was successful or not.
 * @since 0.9.0
+* @since 0.10.0 Added optional `options` parameter for annotations support.
 */
-async function parseAsync(parser, args) {
+async function parseAsync(parser, args, options) {
+	let initialState = parser.initialState;
+	if (options?.annotations) initialState = {
+		...typeof initialState === "object" && initialState !== null ? initialState : {},
+		[require_annotations.annotationKey]: options.annotations
+	};
 	let context = {
 		buffer: args,
 		optionsTerminated: false,
-		state: parser.initialState,
+		state: initialState,
 		usage: parser.usage
 	};
 	do {
@@ -117,12 +132,14 @@ async function parseAsync(parser, args) {
 *               arguments.
 * @param args The array of command-line arguments to parse.  Usually this is
 *             `process.argv.slice(2)` in Node.js or `Deno.args` in Deno.
+* @param options Optional {@link ParseOptions} for customizing parsing behavior.
 * @returns A {@link Result} object (for sync) or Promise thereof (for async)
 *          indicating whether the parsing was successful or not.
+* @since 0.10.0 Added optional `options` parameter for annotations support.
 */
-function parse(parser, args) {
-	if (parser.$mode === "async") return parseAsync(parser, args);
-	return parseSync(parser, args);
+function parse(parser, args, options) {
+	if (parser.$mode === "async") return parseAsync(parser, args, options);
+	return parseSync(parser, args, options);
 }
 /**
 * Generates command-line suggestions based on current parsing state.
@@ -138,6 +155,7 @@ function parse(parser, args) {
 * @param args The array of command-line arguments including the partial
 *             argument to complete.  The last element is treated as
 *             the prefix for suggestions.
+* @param options Optional {@link ParseOptions} for customizing parsing behavior.
 * @returns An array of {@link Suggestion} objects containing completion
 *          candidates.
 * @example
@@ -157,14 +175,20 @@ function parse(parser, args) {
 * ```
 * @since 0.6.0
 * @since 0.9.0 Renamed from the original `suggest` function.
+* @since 0.10.0 Added optional `options` parameter for annotations support.
 */
-function suggestSync(parser, args) {
+function suggestSync(parser, args, options) {
 	const allButLast = args.slice(0, -1);
 	const prefix = args[args.length - 1];
+	let initialState = parser.initialState;
+	if (options?.annotations) initialState = {
+		...typeof initialState === "object" && initialState !== null ? initialState : {},
+		[require_annotations.annotationKey]: options.annotations
+	};
 	let context = {
 		buffer: allButLast,
 		optionsTerminated: false,
-		state: parser.initialState,
+		state: initialState,
 		usage: parser.usage
 	};
 	while (context.buffer.length > 0) {
@@ -190,17 +214,24 @@ function suggestSync(parser, args) {
 * @param args The array of command-line arguments including the partial
 *             argument to complete.  The last element is treated as
 *             the prefix for suggestions.
+* @param options Optional {@link ParseOptions} for customizing parsing behavior.
 * @returns A Promise that resolves to an array of {@link Suggestion} objects
 *          containing completion candidates.
 * @since 0.9.0
+* @since 0.10.0 Added optional `options` parameter for annotations support.
 */
-async function suggestAsync(parser, args) {
+async function suggestAsync(parser, args, options) {
 	const allButLast = args.slice(0, -1);
 	const prefix = args[args.length - 1];
+	let initialState = parser.initialState;
+	if (options?.annotations) initialState = {
+		...typeof initialState === "object" && initialState !== null ? initialState : {},
+		[require_annotations.annotationKey]: options.annotations
+	};
 	let context = {
 		buffer: allButLast,
 		optionsTerminated: false,
-		state: parser.initialState,
+		state: initialState,
 		usage: parser.usage
 	};
 	while (context.buffer.length > 0) {
@@ -235,13 +266,15 @@ async function suggestAsync(parser, args) {
 * @param args The array of command-line arguments including the partial
 *             argument to complete.  The last element is treated as
 *             the prefix for suggestions.
+* @param options Optional {@link ParseOptions} for customizing parsing behavior.
 * @returns An array of {@link Suggestion} objects (for sync) or Promise thereof
 *          (for async) containing completion candidates.
 * @since 0.6.0
+* @since 0.10.0 Added optional `options` parameter for annotations support.
 */
-function suggest(parser, args) {
-	if (parser.$mode === "async") return suggestAsync(parser, args);
-	return suggestSync(parser, args);
+function suggest(parser, args, options) {
+	if (parser.$mode === "async") return suggestAsync(parser, args, options);
+	return suggestSync(parser, args, options);
 }
 /**
 * Recursively searches for a command within nested exclusive usage terms.
@@ -272,11 +305,13 @@ function findCommandInExclusive(term, commandName) {
 *
 * @param parser The sync parser to generate documentation for.
 * @param args Optional array of command-line arguments for context.
+* @param options Optional {@link ParseOptions} for customizing parsing behavior.
 * @returns A {@link DocPage} or `undefined`.
 * @since 0.9.0
+* @since 0.10.0 Added optional `options` parameter for annotations support.
 */
-function getDocPageSync(parser, args = []) {
-	return getDocPageSyncImpl(parser, args);
+function getDocPageSync(parser, args = [], options) {
+	return getDocPageSyncImpl(parser, args, options);
 }
 /**
 * Generates a documentation page for any parser, returning a Promise.
@@ -287,25 +322,32 @@ function getDocPageSync(parser, args = []) {
 *
 * @param parser The parser to generate documentation for.
 * @param args Optional array of command-line arguments for context.
+* @param options Optional {@link ParseOptions} for customizing parsing behavior.
 * @returns A Promise of {@link DocPage} or `undefined`.
 * @since 0.9.0
+* @since 0.10.0 Added optional `options` parameter for annotations support.
 */
-function getDocPageAsync(parser, args = []) {
-	if (parser.$mode === "sync") return Promise.resolve(getDocPageSyncImpl(parser, args));
-	return getDocPageAsyncImpl(parser, args);
+function getDocPageAsync(parser, args = [], options) {
+	if (parser.$mode === "sync") return Promise.resolve(getDocPageSyncImpl(parser, args, options));
+	return getDocPageAsyncImpl(parser, args, options);
 }
-function getDocPage(parser, args = []) {
-	if (parser.$mode === "sync") return getDocPageSyncImpl(parser, args);
-	return getDocPageAsyncImpl(parser, args);
+function getDocPage(parser, args = [], options) {
+	if (parser.$mode === "sync") return getDocPageSyncImpl(parser, args, options);
+	return getDocPageAsyncImpl(parser, args, options);
 }
 /**
 * Internal sync implementation of getDocPage.
 */
-function getDocPageSyncImpl(parser, args) {
+function getDocPageSyncImpl(parser, args, options) {
+	let initialState = parser.initialState;
+	if (options?.annotations) initialState = {
+		...typeof initialState === "object" && initialState !== null ? initialState : {},
+		[require_annotations.annotationKey]: options.annotations
+	};
 	let context = {
 		buffer: args,
 		optionsTerminated: false,
-		state: parser.initialState,
+		state: initialState,
 		usage: parser.usage
 	};
 	do {
@@ -318,11 +360,16 @@ function getDocPageSyncImpl(parser, args) {
 /**
 * Internal async implementation of getDocPage.
 */
-async function getDocPageAsyncImpl(parser, args) {
+async function getDocPageAsyncImpl(parser, args, options) {
+	let initialState = parser.initialState;
+	if (options?.annotations) initialState = {
+		...typeof initialState === "object" && initialState !== null ? initialState : {},
+		[require_annotations.annotationKey]: options.annotations
+	};
 	let context = {
 		buffer: args,
 		optionsTerminated: false,
-		state: parser.initialState,
+		state: initialState,
 		usage: parser.usage
 	};
 	do {

package/dist/parser.d.cts

@@ -1,3 +1,4 @@
+import { ParseOptions } from "./annotations.cjs";
 import { Message } from "./message.cjs";
 import { Usage } from "./usage.cjs";
 import { DocFragments, DocPage } from "./doc.cjs";
@@ -325,14 +326,16 @@ type Result<T> = {
  *               arguments.  Must be a synchronous parser.
  * @param args The array of command-line arguments to parse.  Usually this is
  *             `process.argv.slice(2)` in Node.js or `Deno.args` in Deno.
+ * @param options Optional {@link ParseOptions} for customizing parsing behavior.
  * @returns A {@link Result} object indicating whether the parsing was
  *          successful or not.  If successful, it contains the parsed value of
  *          type `T`.  If not, it contains an error message describing the
  *          failure.
  * @since 0.9.0 Renamed from the original `parse` function which now delegates
  *              to this for sync parsers.
+ * @since 0.10.0 Added optional `options` parameter for annotations support.
  */
-declare function parseSync<T>(parser: Parser<"sync", T, unknown>, args: readonly string[]): Result<T>;
+declare function parseSync<T>(parser: Parser<"sync", T, unknown>, args: readonly string[], options?: ParseOptions): Result<T>;
 /**
  * Parses an array of command-line arguments using the provided combined parser.
  * This function processes the input arguments, applying the parser to each
@@ -346,11 +349,13 @@ declare function parseSync<T>(parser: Parser<"sync", T, unknown>, args: readonly
  *               arguments.
  * @param args The array of command-line arguments to parse.  Usually this is
  *             `process.argv.slice(2)` in Node.js or `Deno.args` in Deno.
+ * @param options Optional {@link ParseOptions} for customizing parsing behavior.
  * @returns A Promise that resolves to a {@link Result} object indicating
  *          whether the parsing was successful or not.
  * @since 0.9.0
+ * @since 0.10.0 Added optional `options` parameter for annotations support.
  */
-declare function parseAsync<T>(parser: Parser<Mode, T, unknown>, args: readonly string[]): Promise<Result<T>>;
+declare function parseAsync<T>(parser: Parser<Mode, T, unknown>, args: readonly string[], options?: ParseOptions): Promise<Result<T>>;
 /**
  * Parses an array of command-line arguments using the provided combined parser.
  * This function processes the input arguments, applying the parser to each
@@ -368,10 +373,12 @@ declare function parseAsync<T>(parser: Parser<Mode, T, unknown>, args: readonly
  *               arguments.
  * @param args The array of command-line arguments to parse.  Usually this is
  *             `process.argv.slice(2)` in Node.js or `Deno.args` in Deno.
+ * @param options Optional {@link ParseOptions} for customizing parsing behavior.
  * @returns A {@link Result} object (for sync) or Promise thereof (for async)
  *          indicating whether the parsing was successful or not.
+ * @since 0.10.0 Added optional `options` parameter for annotations support.
  */
-declare function parse<M extends Mode, T>(parser: Parser<M, T, unknown>, args: readonly string[]): ModeValue<M, Result<T>>;
+declare function parse<M extends Mode, T>(parser: Parser<M, T, unknown>, args: readonly string[], options?: ParseOptions): ModeValue<M, Result<T>>;
 /**
  * Generates command-line suggestions based on current parsing state.
  * This function processes the input arguments up to the last argument,
@@ -386,6 +393,7 @@ declare function parse<M extends Mode, T>(parser: Parser<M, T, unknown>, args: r
  * @param args The array of command-line arguments including the partial
  *             argument to complete.  The last element is treated as
  *             the prefix for suggestions.
+ * @param options Optional {@link ParseOptions} for customizing parsing behavior.
  * @returns An array of {@link Suggestion} objects containing completion
  *          candidates.
  * @example
@@ -405,8 +413,9 @@ declare function parse<M extends Mode, T>(parser: Parser<M, T, unknown>, args: r
  * ```
  * @since 0.6.0
  * @since 0.9.0 Renamed from the original `suggest` function.
+ * @since 0.10.0 Added optional `options` parameter for annotations support.
  */
-declare function suggestSync<T>(parser: Parser<"sync", T, unknown>, args: readonly [string, ...readonly string[]]): readonly Suggestion[];
+declare function suggestSync<T>(parser: Parser<"sync", T, unknown>, args: readonly [string, ...readonly string[]], options?: ParseOptions): readonly Suggestion[];
 /**
  * Generates command-line suggestions based on current parsing state.
  * This function processes the input arguments up to the last argument,
@@ -421,11 +430,13 @@ declare function suggestSync<T>(parser: Parser<"sync", T, unknown>, args: readon
  * @param args The array of command-line arguments including the partial
  *             argument to complete.  The last element is treated as
  *             the prefix for suggestions.
+ * @param options Optional {@link ParseOptions} for customizing parsing behavior.
  * @returns A Promise that resolves to an array of {@link Suggestion} objects
  *          containing completion candidates.
  * @since 0.9.0
+ * @since 0.10.0 Added optional `options` parameter for annotations support.
  */
-declare function suggestAsync<T>(parser: Parser<Mode, T, unknown>, args: readonly [string, ...readonly string[]]): Promise<readonly Suggestion[]>;
+declare function suggestAsync<T>(parser: Parser<Mode, T, unknown>, args: readonly [string, ...readonly string[]], options?: ParseOptions): Promise<readonly Suggestion[]>;
 /**
  * Generates command-line suggestions based on current parsing state.
  * This function processes the input arguments up to the last argument,
@@ -443,11 +454,13 @@ declare function suggestAsync<T>(parser: Parser<Mode, T, unknown>, args: readonl
  * @param args The array of command-line arguments including the partial
  *             argument to complete.  The last element is treated as
  *             the prefix for suggestions.
+ * @param options Optional {@link ParseOptions} for customizing parsing behavior.
  * @returns An array of {@link Suggestion} objects (for sync) or Promise thereof
  *          (for async) containing completion candidates.
  * @since 0.6.0
+ * @since 0.10.0 Added optional `options` parameter for annotations support.
  */
-declare function suggest<M extends Mode, T>(parser: Parser<M, T, unknown>, args: readonly [string, ...readonly string[]]): ModeValue<M, readonly Suggestion[]>;
+declare function suggest<M extends Mode, T>(parser: Parser<M, T, unknown>, args: readonly [string, ...readonly string[]], options?: ParseOptions): ModeValue<M, readonly Suggestion[]>;
 /**
  * Generates a documentation page for a synchronous parser.
  *
@@ -457,10 +470,12 @@ declare function suggest<M extends Mode, T>(parser: Parser<M, T, unknown>, args:
  *
  * @param parser The sync parser to generate documentation for.
  * @param args Optional array of command-line arguments for context.
+ * @param options Optional {@link ParseOptions} for customizing parsing behavior.
  * @returns A {@link DocPage} or `undefined`.
  * @since 0.9.0
+ * @since 0.10.0 Added optional `options` parameter for annotations support.
  */
-declare function getDocPageSync(parser: Parser<"sync", unknown, unknown>, args?: readonly string[]): DocPage | undefined;
+declare function getDocPageSync(parser: Parser<"sync", unknown, unknown>, args?: readonly string[], options?: ParseOptions): DocPage | undefined;
 /**
  * Generates a documentation page for any parser, returning a Promise.
  *
@@ -470,10 +485,12 @@ declare function getDocPageSync(parser: Parser<"sync", unknown, unknown>, args?:
  *
  * @param parser The parser to generate documentation for.
  * @param args Optional array of command-line arguments for context.
+ * @param options Optional {@link ParseOptions} for customizing parsing behavior.
  * @returns A Promise of {@link DocPage} or `undefined`.
  * @since 0.9.0
+ * @since 0.10.0 Added optional `options` parameter for annotations support.
  */
-declare function getDocPageAsync(parser: Parser<Mode, unknown, unknown>, args?: readonly string[]): Promise<DocPage | undefined>;
+declare function getDocPageAsync(parser: Parser<Mode, unknown, unknown>, args?: readonly string[], options?: ParseOptions): Promise<DocPage | undefined>;
 /**
  * Generates a documentation page for a parser based on its current state after
  * attempting to parse the provided arguments. This function is useful for
@@ -492,6 +509,7 @@ declare function getDocPageAsync(parser: Parser<Mode, unknown, unknown>, args?:
  * @param args Optional array of command-line arguments that have been parsed
  *             so far. Defaults to an empty array. This is used to determine
  *             the current parsing context and generate contextual documentation.
+ * @param options Optional {@link ParseOptions} for customizing parsing behavior.
  * @returns For sync parsers, returns a {@link DocPage} directly.
  *          For async parsers, returns a Promise of {@link DocPage}.
  *          Returns `undefined` if no documentation can be generated.
@@ -510,9 +528,10 @@ declare function getDocPageAsync(parser: Parser<Mode, unknown, unknown>, args?:
  * const asyncDoc = await getDocPage(asyncParser);
  * ```
  * @since 0.9.0 Updated to support async parsers.
+ * @since 0.10.0 Added optional `options` parameter for annotations support.
  */
-declare function getDocPage(parser: Parser<"sync", unknown, unknown>, args?: readonly string[]): DocPage | undefined;
-declare function getDocPage(parser: Parser<"async", unknown, unknown>, args?: readonly string[]): Promise<DocPage | undefined>;
-declare function getDocPage<M extends Mode>(parser: Parser<M, unknown, unknown>, args?: readonly string[]): ModeValue<M, DocPage | undefined>;
+declare function getDocPage(parser: Parser<"sync", unknown, unknown>, args?: readonly string[], options?: ParseOptions): DocPage | undefined;
+declare function getDocPage(parser: Parser<"async", unknown, unknown>, args?: readonly string[], options?: ParseOptions): Promise<DocPage | undefined>;
+declare function getDocPage<M extends Mode>(parser: Parser<M, unknown, unknown>, args?: readonly string[], options?: ParseOptions): ModeValue<M, DocPage | undefined>;
 //#endregion
-export { ArgumentErrorOptions, ArgumentOptions, CombineModes, CommandErrorOptions, CommandOptions, ConditionalErrorOptions, ConditionalOptions, DocState, DuplicateOptionError, FlagErrorOptions, FlagOptions, InferMode, InferValue, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionOptions, OptionState, OrErrorOptions, OrOptions, Parser, ParserContext, ParserResult, PassThroughFormat, PassThroughOptions, Result, Suggestion, TupleOptions, WithDefaultError, WithDefaultOptions, argument, command, concat, conditional, constant, flag, getDocPage, getDocPageAsync, getDocPageSync, group, longestMatch, map, merge, multiple, nonEmpty, object, option, optional, or, parse, parseAsync, parseSync, passThrough, suggest, suggestAsync, suggestSync, tuple, withDefault };
+export { ArgumentErrorOptions, ArgumentOptions, CombineModes, CommandErrorOptions, CommandOptions, ConditionalErrorOptions, ConditionalOptions, DocState, DuplicateOptionError, FlagErrorOptions, FlagOptions, InferMode, InferValue, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionOptions, OptionState, OrErrorOptions, OrOptions, type ParseOptions, Parser, ParserContext, ParserResult, PassThroughFormat, PassThroughOptions, Result, Suggestion, TupleOptions, WithDefaultError, WithDefaultOptions, argument, command, concat, conditional, constant, flag, getDocPage, getDocPageAsync, getDocPageSync, group, longestMatch, map, merge, multiple, nonEmpty, object, option, optional, or, parse, parseAsync, parseSync, passThrough, suggest, suggestAsync, suggestSync, tuple, withDefault };

package/dist/parser.d.ts

@@ -1,3 +1,4 @@
+import { ParseOptions } from "./annotations.js";
 import { Message } from "./message.js";
 import { Usage } from "./usage.js";
 import { DocFragments, DocPage } from "./doc.js";
@@ -325,14 +326,16 @@ type Result<T> = {
  *               arguments.  Must be a synchronous parser.
  * @param args The array of command-line arguments to parse.  Usually this is
  *             `process.argv.slice(2)` in Node.js or `Deno.args` in Deno.
+ * @param options Optional {@link ParseOptions} for customizing parsing behavior.
  * @returns A {@link Result} object indicating whether the parsing was
  *          successful or not.  If successful, it contains the parsed value of
  *          type `T`.  If not, it contains an error message describing the
  *          failure.
  * @since 0.9.0 Renamed from the original `parse` function which now delegates
  *              to this for sync parsers.
+ * @since 0.10.0 Added optional `options` parameter for annotations support.
  */
-declare function parseSync<T>(parser: Parser<"sync", T, unknown>, args: readonly string[]): Result<T>;
+declare function parseSync<T>(parser: Parser<"sync", T, unknown>, args: readonly string[], options?: ParseOptions): Result<T>;
 /**
  * Parses an array of command-line arguments using the provided combined parser.
  * This function processes the input arguments, applying the parser to each
@@ -346,11 +349,13 @@ declare function parseSync<T>(parser: Parser<"sync", T, unknown>, args: readonly
  *               arguments.
  * @param args The array of command-line arguments to parse.  Usually this is
  *             `process.argv.slice(2)` in Node.js or `Deno.args` in Deno.
+ * @param options Optional {@link ParseOptions} for customizing parsing behavior.
  * @returns A Promise that resolves to a {@link Result} object indicating
  *          whether the parsing was successful or not.
  * @since 0.9.0
+ * @since 0.10.0 Added optional `options` parameter for annotations support.
  */
-declare function parseAsync<T>(parser: Parser<Mode, T, unknown>, args: readonly string[]): Promise<Result<T>>;
+declare function parseAsync<T>(parser: Parser<Mode, T, unknown>, args: readonly string[], options?: ParseOptions): Promise<Result<T>>;
 /**
  * Parses an array of command-line arguments using the provided combined parser.
  * This function processes the input arguments, applying the parser to each
@@ -368,10 +373,12 @@ declare function parseAsync<T>(parser: Parser<Mode, T, unknown>, args: readonly
  *               arguments.
  * @param args The array of command-line arguments to parse.  Usually this is
  *             `process.argv.slice(2)` in Node.js or `Deno.args` in Deno.
+ * @param options Optional {@link ParseOptions} for customizing parsing behavior.
  * @returns A {@link Result} object (for sync) or Promise thereof (for async)
  *          indicating whether the parsing was successful or not.
+ * @since 0.10.0 Added optional `options` parameter for annotations support.
  */
-declare function parse<M extends Mode, T>(parser: Parser<M, T, unknown>, args: readonly string[]): ModeValue<M, Result<T>>;
+declare function parse<M extends Mode, T>(parser: Parser<M, T, unknown>, args: readonly string[], options?: ParseOptions): ModeValue<M, Result<T>>;
 /**
  * Generates command-line suggestions based on current parsing state.
  * This function processes the input arguments up to the last argument,
@@ -386,6 +393,7 @@ declare function parse<M extends Mode, T>(parser: Parser<M, T, unknown>, args: r
  * @param args The array of command-line arguments including the partial
  *             argument to complete.  The last element is treated as
  *             the prefix for suggestions.
+ * @param options Optional {@link ParseOptions} for customizing parsing behavior.
  * @returns An array of {@link Suggestion} objects containing completion
  *          candidates.
  * @example
@@ -405,8 +413,9 @@ declare function parse<M extends Mode, T>(parser: Parser<M, T, unknown>, args: r
  * ```
  * @since 0.6.0
  * @since 0.9.0 Renamed from the original `suggest` function.
+ * @since 0.10.0 Added optional `options` parameter for annotations support.
  */
-declare function suggestSync<T>(parser: Parser<"sync", T, unknown>, args: readonly [string, ...readonly string[]]): readonly Suggestion[];
+declare function suggestSync<T>(parser: Parser<"sync", T, unknown>, args: readonly [string, ...readonly string[]], options?: ParseOptions): readonly Suggestion[];
 /**
  * Generates command-line suggestions based on current parsing state.
  * This function processes the input arguments up to the last argument,
@@ -421,11 +430,13 @@ declare function suggestSync<T>(parser: Parser<"sync", T, unknown>, args: readon
  * @param args The array of command-line arguments including the partial
  *             argument to complete.  The last element is treated as
  *             the prefix for suggestions.
+ * @param options Optional {@link ParseOptions} for customizing parsing behavior.
  * @returns A Promise that resolves to an array of {@link Suggestion} objects
  *          containing completion candidates.
  * @since 0.9.0
+ * @since 0.10.0 Added optional `options` parameter for annotations support.
  */
-declare function suggestAsync<T>(parser: Parser<Mode, T, unknown>, args: readonly [string, ...readonly string[]]): Promise<readonly Suggestion[]>;
+declare function suggestAsync<T>(parser: Parser<Mode, T, unknown>, args: readonly [string, ...readonly string[]], options?: ParseOptions): Promise<readonly Suggestion[]>;
 /**
  * Generates command-line suggestions based on current parsing state.
  * This function processes the input arguments up to the last argument,
@@ -443,11 +454,13 @@ declare function suggestAsync<T>(parser: Parser<Mode, T, unknown>, args: readonl
  * @param args The array of command-line arguments including the partial
  *             argument to complete.  The last element is treated as
  *             the prefix for suggestions.
+ * @param options Optional {@link ParseOptions} for customizing parsing behavior.
  * @returns An array of {@link Suggestion} objects (for sync) or Promise thereof
  *          (for async) containing completion candidates.
  * @since 0.6.0
+ * @since 0.10.0 Added optional `options` parameter for annotations support.
  */
-declare function suggest<M extends Mode, T>(parser: Parser<M, T, unknown>, args: readonly [string, ...readonly string[]]): ModeValue<M, readonly Suggestion[]>;
+declare function suggest<M extends Mode, T>(parser: Parser<M, T, unknown>, args: readonly [string, ...readonly string[]], options?: ParseOptions): ModeValue<M, readonly Suggestion[]>;
 /**
  * Generates a documentation page for a synchronous parser.
  *
@@ -457,10 +470,12 @@ declare function suggest<M extends Mode, T>(parser: Parser<M, T, unknown>, args:
  *
  * @param parser The sync parser to generate documentation for.
  * @param args Optional array of command-line arguments for context.
+ * @param options Optional {@link ParseOptions} for customizing parsing behavior.
  * @returns A {@link DocPage} or `undefined`.
  * @since 0.9.0
+ * @since 0.10.0 Added optional `options` parameter for annotations support.
  */
-declare function getDocPageSync(parser: Parser<"sync", unknown, unknown>, args?: readonly string[]): DocPage | undefined;
+declare function getDocPageSync(parser: Parser<"sync", unknown, unknown>, args?: readonly string[], options?: ParseOptions): DocPage | undefined;
 /**
  * Generates a documentation page for any parser, returning a Promise.
  *
@@ -470,10 +485,12 @@ declare function getDocPageSync(parser: Parser<"sync", unknown, unknown>, args?:
  *
  * @param parser The parser to generate documentation for.
  * @param args Optional array of command-line arguments for context.
+ * @param options Optional {@link ParseOptions} for customizing parsing behavior.
  * @returns A Promise of {@link DocPage} or `undefined`.
  * @since 0.9.0
+ * @since 0.10.0 Added optional `options` parameter for annotations support.
  */
-declare function getDocPageAsync(parser: Parser<Mode, unknown, unknown>, args?: readonly string[]): Promise<DocPage | undefined>;
+declare function getDocPageAsync(parser: Parser<Mode, unknown, unknown>, args?: readonly string[], options?: ParseOptions): Promise<DocPage | undefined>;
 /**
  * Generates a documentation page for a parser based on its current state after
  * attempting to parse the provided arguments. This function is useful for
@@ -492,6 +509,7 @@ declare function getDocPageAsync(parser: Parser<Mode, unknown, unknown>, args?:
  * @param args Optional array of command-line arguments that have been parsed
  *             so far. Defaults to an empty array. This is used to determine
  *             the current parsing context and generate contextual documentation.
+ * @param options Optional {@link ParseOptions} for customizing parsing behavior.
  * @returns For sync parsers, returns a {@link DocPage} directly.
  *          For async parsers, returns a Promise of {@link DocPage}.
  *          Returns `undefined` if no documentation can be generated.
@@ -510,9 +528,10 @@ declare function getDocPageAsync(parser: Parser<Mode, unknown, unknown>, args?:
  * const asyncDoc = await getDocPage(asyncParser);
  * ```
  * @since 0.9.0 Updated to support async parsers.
+ * @since 0.10.0 Added optional `options` parameter for annotations support.
  */
-declare function getDocPage(parser: Parser<"sync", unknown, unknown>, args?: readonly string[]): DocPage | undefined;
-declare function getDocPage(parser: Parser<"async", unknown, unknown>, args?: readonly string[]): Promise<DocPage | undefined>;
-declare function getDocPage<M extends Mode>(parser: Parser<M, unknown, unknown>, args?: readonly string[]): ModeValue<M, DocPage | undefined>;
+declare function getDocPage(parser: Parser<"sync", unknown, unknown>, args?: readonly string[], options?: ParseOptions): DocPage | undefined;
+declare function getDocPage(parser: Parser<"async", unknown, unknown>, args?: readonly string[], options?: ParseOptions): Promise<DocPage | undefined>;
+declare function getDocPage<M extends Mode>(parser: Parser<M, unknown, unknown>, args?: readonly string[], options?: ParseOptions): ModeValue<M, DocPage | undefined>;
 //#endregion
-export { ArgumentErrorOptions, ArgumentOptions, CombineModes, CommandErrorOptions, CommandOptions, ConditionalErrorOptions, ConditionalOptions, DocState, DuplicateOptionError, FlagErrorOptions, FlagOptions, InferMode, InferValue, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionOptions, OptionState, OrErrorOptions, OrOptions, Parser, ParserContext, ParserResult, PassThroughFormat, PassThroughOptions, Result, Suggestion, TupleOptions, WithDefaultError, WithDefaultOptions, argument, command, concat, conditional, constant, flag, getDocPage, getDocPageAsync, getDocPageSync, group, longestMatch, map, merge, multiple, nonEmpty, object, option, optional, or, parse, parseAsync, parseSync, passThrough, suggest, suggestAsync, suggestSync, tuple, withDefault };
+export { ArgumentErrorOptions, ArgumentOptions, CombineModes, CommandErrorOptions, CommandOptions, ConditionalErrorOptions, ConditionalOptions, DocState, DuplicateOptionError, FlagErrorOptions, FlagOptions, InferMode, InferValue, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionOptions, OptionState, OrErrorOptions, OrOptions, type ParseOptions, Parser, ParserContext, ParserResult, PassThroughFormat, PassThroughOptions, Result, Suggestion, TupleOptions, WithDefaultError, WithDefaultOptions, argument, command, concat, conditional, constant, flag, getDocPage, getDocPageAsync, getDocPageSync, group, longestMatch, map, merge, multiple, nonEmpty, object, option, optional, or, parse, parseAsync, parseSync, passThrough, suggest, suggestAsync, suggestSync, tuple, withDefault };

package/dist/parser.js

@@ -1,3 +1,4 @@
+import { annotationKey } from "./annotations.js";
 import { message } from "./message.js";
 import { normalizeUsage } from "./usage.js";
 import { DuplicateOptionError, concat, conditional, group, longestMatch, merge, object, or, tuple } from "./constructs.js";
@@ -18,18 +19,25 @@ import { argument, command, constant, flag, option, passThrough } from "./primit
 *               arguments.  Must be a synchronous parser.
 * @param args The array of command-line arguments to parse.  Usually this is
 *             `process.argv.slice(2)` in Node.js or `Deno.args` in Deno.
+* @param options Optional {@link ParseOptions} for customizing parsing behavior.
 * @returns A {@link Result} object indicating whether the parsing was
 *          successful or not.  If successful, it contains the parsed value of
 *          type `T`.  If not, it contains an error message describing the
 *          failure.
 * @since 0.9.0 Renamed from the original `parse` function which now delegates
 *              to this for sync parsers.
+* @since 0.10.0 Added optional `options` parameter for annotations support.
 */
-function parseSync(parser, args) {
+function parseSync(parser, args, options) {
+	let initialState = parser.initialState;
+	if (options?.annotations) initialState = {
+		...typeof initialState === "object" && initialState !== null ? initialState : {},
+		[annotationKey]: options.annotations
+	};
 	let context = {
 		buffer: args,
 		optionsTerminated: false,
-		state: parser.initialState,
+		state: initialState,
 		usage: parser.usage
 	};
 	do {
@@ -67,15 +75,22 @@ function parseSync(parser, args) {
 *               arguments.
 * @param args The array of command-line arguments to parse.  Usually this is
 *             `process.argv.slice(2)` in Node.js or `Deno.args` in Deno.
+* @param options Optional {@link ParseOptions} for customizing parsing behavior.
 * @returns A Promise that resolves to a {@link Result} object indicating
 *          whether the parsing was successful or not.
 * @since 0.9.0
+* @since 0.10.0 Added optional `options` parameter for annotations support.
 */
-async function parseAsync(parser, args) {
+async function parseAsync(parser, args, options) {
+	let initialState = parser.initialState;
+	if (options?.annotations) initialState = {
+		...typeof initialState === "object" && initialState !== null ? initialState : {},
+		[annotationKey]: options.annotations
+	};
 	let context = {
 		buffer: args,
 		optionsTerminated: false,
-		state: parser.initialState,
+		state: initialState,
 		usage: parser.usage
 	};
 	do {
@@ -117,12 +132,14 @@ async function parseAsync(parser, args) {
 *               arguments.
 * @param args The array of command-line arguments to parse.  Usually this is
 *             `process.argv.slice(2)` in Node.js or `Deno.args` in Deno.
+* @param options Optional {@link ParseOptions} for customizing parsing behavior.
 * @returns A {@link Result} object (for sync) or Promise thereof (for async)
 *          indicating whether the parsing was successful or not.
+* @since 0.10.0 Added optional `options` parameter for annotations support.
 */
-function parse(parser, args) {
-	if (parser.$mode === "async") return parseAsync(parser, args);
-	return parseSync(parser, args);
+function parse(parser, args, options) {
+	if (parser.$mode === "async") return parseAsync(parser, args, options);
+	return parseSync(parser, args, options);
 }
 /**
 * Generates command-line suggestions based on current parsing state.
@@ -138,6 +155,7 @@ function parse(parser, args) {
 * @param args The array of command-line arguments including the partial
 *             argument to complete.  The last element is treated as
 *             the prefix for suggestions.
+* @param options Optional {@link ParseOptions} for customizing parsing behavior.
 * @returns An array of {@link Suggestion} objects containing completion
 *          candidates.
 * @example
@@ -157,14 +175,20 @@ function parse(parser, args) {
 * ```
 * @since 0.6.0
 * @since 0.9.0 Renamed from the original `suggest` function.
+* @since 0.10.0 Added optional `options` parameter for annotations support.
 */
-function suggestSync(parser, args) {
+function suggestSync(parser, args, options) {
 	const allButLast = args.slice(0, -1);
 	const prefix = args[args.length - 1];
+	let initialState = parser.initialState;
+	if (options?.annotations) initialState = {
+		...typeof initialState === "object" && initialState !== null ? initialState : {},
+		[annotationKey]: options.annotations
+	};
 	let context = {
 		buffer: allButLast,
 		optionsTerminated: false,
-		state: parser.initialState,
+		state: initialState,
 		usage: parser.usage
 	};
 	while (context.buffer.length > 0) {
@@ -190,17 +214,24 @@ function suggestSync(parser, args) {
 * @param args The array of command-line arguments including the partial
 *             argument to complete.  The last element is treated as
 *             the prefix for suggestions.
+* @param options Optional {@link ParseOptions} for customizing parsing behavior.
 * @returns A Promise that resolves to an array of {@link Suggestion} objects
 *          containing completion candidates.
 * @since 0.9.0
+* @since 0.10.0 Added optional `options` parameter for annotations support.
 */
-async function suggestAsync(parser, args) {
+async function suggestAsync(parser, args, options) {
 	const allButLast = args.slice(0, -1);
 	const prefix = args[args.length - 1];
+	let initialState = parser.initialState;
+	if (options?.annotations) initialState = {
+		...typeof initialState === "object" && initialState !== null ? initialState : {},
+		[annotationKey]: options.annotations
+	};
 	let context = {
 		buffer: allButLast,
 		optionsTerminated: false,
-		state: parser.initialState,
+		state: initialState,
 		usage: parser.usage
 	};
 	while (context.buffer.length > 0) {
@@ -235,13 +266,15 @@ async function suggestAsync(parser, args) {
 * @param args The array of command-line arguments including the partial
 *             argument to complete.  The last element is treated as
 *             the prefix for suggestions.
+* @param options Optional {@link ParseOptions} for customizing parsing behavior.
 * @returns An array of {@link Suggestion} objects (for sync) or Promise thereof
 *          (for async) containing completion candidates.
 * @since 0.6.0
+* @since 0.10.0 Added optional `options` parameter for annotations support.
 */
-function suggest(parser, args) {
-	if (parser.$mode === "async") return suggestAsync(parser, args);
-	return suggestSync(parser, args);
+function suggest(parser, args, options) {
+	if (parser.$mode === "async") return suggestAsync(parser, args, options);
+	return suggestSync(parser, args, options);
 }
 /**
 * Recursively searches for a command within nested exclusive usage terms.
@@ -272,11 +305,13 @@ function findCommandInExclusive(term, commandName) {
 *
 * @param parser The sync parser to generate documentation for.
 * @param args Optional array of command-line arguments for context.
+* @param options Optional {@link ParseOptions} for customizing parsing behavior.
 * @returns A {@link DocPage} or `undefined`.
 * @since 0.9.0
+* @since 0.10.0 Added optional `options` parameter for annotations support.
 */
-function getDocPageSync(parser, args = []) {
-	return getDocPageSyncImpl(parser, args);
+function getDocPageSync(parser, args = [], options) {
+	return getDocPageSyncImpl(parser, args, options);
 }
 /**
 * Generates a documentation page for any parser, returning a Promise.
@@ -287,25 +322,32 @@ function getDocPageSync(parser, args = []) {
 *
 * @param parser The parser to generate documentation for.
 * @param args Optional array of command-line arguments for context.
+* @param options Optional {@link ParseOptions} for customizing parsing behavior.
 * @returns A Promise of {@link DocPage} or `undefined`.
 * @since 0.9.0
+* @since 0.10.0 Added optional `options` parameter for annotations support.
 */
-function getDocPageAsync(parser, args = []) {
-	if (parser.$mode === "sync") return Promise.resolve(getDocPageSyncImpl(parser, args));
-	return getDocPageAsyncImpl(parser, args);
+function getDocPageAsync(parser, args = [], options) {
+	if (parser.$mode === "sync") return Promise.resolve(getDocPageSyncImpl(parser, args, options));
+	return getDocPageAsyncImpl(parser, args, options);
 }
-function getDocPage(parser, args = []) {
-	if (parser.$mode === "sync") return getDocPageSyncImpl(parser, args);
-	return getDocPageAsyncImpl(parser, args);
+function getDocPage(parser, args = [], options) {
+	if (parser.$mode === "sync") return getDocPageSyncImpl(parser, args, options);
+	return getDocPageAsyncImpl(parser, args, options);
 }
 /**
 * Internal sync implementation of getDocPage.
 */
-function getDocPageSyncImpl(parser, args) {
+function getDocPageSyncImpl(parser, args, options) {
+	let initialState = parser.initialState;
+	if (options?.annotations) initialState = {
+		...typeof initialState === "object" && initialState !== null ? initialState : {},
+		[annotationKey]: options.annotations
+	};
 	let context = {
 		buffer: args,
 		optionsTerminated: false,
-		state: parser.initialState,
+		state: initialState,
 		usage: parser.usage
 	};
 	do {
@@ -318,11 +360,16 @@ function getDocPageSyncImpl(parser, args) {
 /**
 * Internal async implementation of getDocPage.
 */
-async function getDocPageAsyncImpl(parser, args) {
+async function getDocPageAsyncImpl(parser, args, options) {
+	let initialState = parser.initialState;
+	if (options?.annotations) initialState = {
+		...typeof initialState === "object" && initialState !== null ? initialState : {},
+		[annotationKey]: options.annotations
+	};
 	let context = {
 		buffer: args,
 		optionsTerminated: false,
-		state: parser.initialState,
+		state: initialState,
 		usage: parser.usage
 	};
 	do {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "0.10.0-dev.330+04823df7",
+  "version": "0.10.0-dev.331+425449c7",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",
@@ -51,6 +51,14 @@
       "import": "./dist/index.js",
       "require": "./dist/index.cjs"
     },
+    "./annotations": {
+      "types": {
+        "import": "./dist/annotations.d.ts",
+        "require": "./dist/annotations.d.cts"
+      },
+      "import": "./dist/annotations.js",
+      "require": "./dist/annotations.cjs"
+    },
     "./completion": {
       "types": {
         "import": "./dist/completion.d.ts",