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

package/dist/facade.d.cts

@@ -2,6 +2,7 @@ import { Message } from "./message.cjs";
 import { ShowDefaultOptions } from "./doc.cjs";
 import { InferMode, InferValue, Mode, ModeValue, Parser } from "./parser.cjs";
 import { ShellCompletion } from "./completion.cjs";
+import { SourceContext } from "./context.cjs";
 import { Program } from "./program.cjs";
 
 //#region src/facade.d.ts
@@ -282,5 +283,104 @@ declare function runParserAsync<TParser extends Parser<Mode, unknown, unknown>,
 declare class RunParserError extends Error {
   constructor(message: string);
 }
+/**
+ * Options for runWith functions.
+ * Extends RunOptions with additional context-related settings.
+ *
+ * @template THelp The return type when help is shown.
+ * @template TError The return type when an error occurs.
+ * @since 0.10.0
+ */
+interface RunWithOptions<THelp, TError> extends RunOptions<THelp, TError> {
+  /**
+   * Command-line arguments to parse. If not provided, defaults to
+   * `process.argv.slice(2)` on Node.js/Bun or `Deno.args` on Deno.
+   */
+  readonly args?: readonly string[];
+}
+/**
+ * Runs a parser with multiple source contexts.
+ *
+ * This function automatically handles static and dynamic contexts with proper
+ * priority. Earlier contexts in the array override later ones.
+ *
+ * The function uses a smart two-phase approach:
+ *
+ * 1. *Phase 1*: Collect annotations from all contexts (static contexts return
+ *    their data, dynamic contexts may return empty).
+ * 2. *First parse*: Parse with Phase 1 annotations.
+ * 3. *Phase 2*: Call `getAnnotations(parsed)` on all contexts with the first
+ *    parse result.
+ * 4. *Second parse*: Parse again with merged annotations from both phases.
+ *
+ * If all contexts are static (no dynamic contexts), the second parse is skipped
+ * for optimization.
+ *
+ * @template TParser The parser type.
+ * @template THelp Return type when help is shown.
+ * @template TError Return type when an error occurs.
+ * @param parser The parser to execute.
+ * @param programName Name of the program for help/error output.
+ * @param contexts Source contexts to use (priority: earlier overrides later).
+ * @param options Run options including args, help, version, etc.
+ * @returns Promise that resolves to the parsed result.
+ * @since 0.10.0
+ *
+ * @example
+ * ```typescript
+ * import { runWith } from "@optique/core/facade";
+ * import type { SourceContext } from "@optique/core/context";
+ *
+ * const envContext: SourceContext = {
+ *   id: Symbol.for("@myapp/env"),
+ *   getAnnotations() {
+ *     return { [Symbol.for("@myapp/env")]: process.env };
+ *   }
+ * };
+ *
+ * const result = await runWith(
+ *   parser,
+ *   "myapp",
+ *   [envContext],
+ *   { args: process.argv.slice(2) }
+ * );
+ * ```
+ */
+declare function runWith<TParser extends Parser<Mode, unknown, unknown>, THelp = void, TError = never>(parser: TParser, programName: string, contexts: readonly SourceContext[], options?: RunWithOptions<THelp, TError>): Promise<InferValue<TParser>>;
+/**
+ * Runs a synchronous parser with multiple source contexts.
+ *
+ * This is the sync-only variant of {@link runWith}. All contexts must return
+ * annotations synchronously (not Promises).
+ *
+ * @template TParser The sync parser type.
+ * @template THelp Return type when help is shown.
+ * @template TError Return type when an error occurs.
+ * @param parser The synchronous parser to execute.
+ * @param programName Name of the program for help/error output.
+ * @param contexts Source contexts to use (priority: earlier overrides later).
+ * @param options Run options including args, help, version, etc.
+ * @returns The parsed result.
+ * @throws Error if any context returns a Promise.
+ * @since 0.10.0
+ */
+declare function runWithSync<TParser extends Parser<"sync", unknown, unknown>, THelp = void, TError = never>(parser: TParser, programName: string, contexts: readonly SourceContext[], options?: RunWithOptions<THelp, TError>): InferValue<TParser>;
+/**
+ * Runs any parser asynchronously with multiple source contexts.
+ *
+ * This function accepts parsers of any mode (sync or async) and always
+ * returns a Promise. Use this when working with async contexts or parsers.
+ *
+ * @template TParser The parser type.
+ * @template THelp Return type when help is shown.
+ * @template TError Return type when an error occurs.
+ * @param parser The parser to execute.
+ * @param programName Name of the program for help/error output.
+ * @param contexts Source contexts to use (priority: earlier overrides later).
+ * @param options Run options including args, help, version, etc.
+ * @returns Promise that resolves to the parsed result.
+ * @since 0.10.0
+ */
+declare function runWithAsync<TParser extends Parser<Mode, unknown, unknown>, THelp = void, TError = never>(parser: TParser, programName: string, contexts: readonly SourceContext[], options?: RunWithOptions<THelp, TError>): Promise<InferValue<TParser>>;
 //#endregion
-export { RunOptions, RunParserError, runParser, runParserAsync, runParserSync };
+export { RunOptions, RunParserError, RunWithOptions, type SourceContext, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync };

package/dist/facade.d.ts

@@ -2,6 +2,7 @@ import { Message } from "./message.js";
 import { ShowDefaultOptions } from "./doc.js";
 import { InferMode, InferValue, Mode, ModeValue, Parser } from "./parser.js";
 import { ShellCompletion } from "./completion.js";
+import { SourceContext } from "./context.js";
 import { Program } from "./program.js";
 
 //#region src/facade.d.ts
@@ -282,5 +283,104 @@ declare function runParserAsync<TParser extends Parser<Mode, unknown, unknown>,
 declare class RunParserError extends Error {
   constructor(message: string);
 }
+/**
+ * Options for runWith functions.
+ * Extends RunOptions with additional context-related settings.
+ *
+ * @template THelp The return type when help is shown.
+ * @template TError The return type when an error occurs.
+ * @since 0.10.0
+ */
+interface RunWithOptions<THelp, TError> extends RunOptions<THelp, TError> {
+  /**
+   * Command-line arguments to parse. If not provided, defaults to
+   * `process.argv.slice(2)` on Node.js/Bun or `Deno.args` on Deno.
+   */
+  readonly args?: readonly string[];
+}
+/**
+ * Runs a parser with multiple source contexts.
+ *
+ * This function automatically handles static and dynamic contexts with proper
+ * priority. Earlier contexts in the array override later ones.
+ *
+ * The function uses a smart two-phase approach:
+ *
+ * 1. *Phase 1*: Collect annotations from all contexts (static contexts return
+ *    their data, dynamic contexts may return empty).
+ * 2. *First parse*: Parse with Phase 1 annotations.
+ * 3. *Phase 2*: Call `getAnnotations(parsed)` on all contexts with the first
+ *    parse result.
+ * 4. *Second parse*: Parse again with merged annotations from both phases.
+ *
+ * If all contexts are static (no dynamic contexts), the second parse is skipped
+ * for optimization.
+ *
+ * @template TParser The parser type.
+ * @template THelp Return type when help is shown.
+ * @template TError Return type when an error occurs.
+ * @param parser The parser to execute.
+ * @param programName Name of the program for help/error output.
+ * @param contexts Source contexts to use (priority: earlier overrides later).
+ * @param options Run options including args, help, version, etc.
+ * @returns Promise that resolves to the parsed result.
+ * @since 0.10.0
+ *
+ * @example
+ * ```typescript
+ * import { runWith } from "@optique/core/facade";
+ * import type { SourceContext } from "@optique/core/context";
+ *
+ * const envContext: SourceContext = {
+ *   id: Symbol.for("@myapp/env"),
+ *   getAnnotations() {
+ *     return { [Symbol.for("@myapp/env")]: process.env };
+ *   }
+ * };
+ *
+ * const result = await runWith(
+ *   parser,
+ *   "myapp",
+ *   [envContext],
+ *   { args: process.argv.slice(2) }
+ * );
+ * ```
+ */
+declare function runWith<TParser extends Parser<Mode, unknown, unknown>, THelp = void, TError = never>(parser: TParser, programName: string, contexts: readonly SourceContext[], options?: RunWithOptions<THelp, TError>): Promise<InferValue<TParser>>;
+/**
+ * Runs a synchronous parser with multiple source contexts.
+ *
+ * This is the sync-only variant of {@link runWith}. All contexts must return
+ * annotations synchronously (not Promises).
+ *
+ * @template TParser The sync parser type.
+ * @template THelp Return type when help is shown.
+ * @template TError Return type when an error occurs.
+ * @param parser The synchronous parser to execute.
+ * @param programName Name of the program for help/error output.
+ * @param contexts Source contexts to use (priority: earlier overrides later).
+ * @param options Run options including args, help, version, etc.
+ * @returns The parsed result.
+ * @throws Error if any context returns a Promise.
+ * @since 0.10.0
+ */
+declare function runWithSync<TParser extends Parser<"sync", unknown, unknown>, THelp = void, TError = never>(parser: TParser, programName: string, contexts: readonly SourceContext[], options?: RunWithOptions<THelp, TError>): InferValue<TParser>;
+/**
+ * Runs any parser asynchronously with multiple source contexts.
+ *
+ * This function accepts parsers of any mode (sync or async) and always
+ * returns a Promise. Use this when working with async contexts or parsers.
+ *
+ * @template TParser The parser type.
+ * @template THelp Return type when help is shown.
+ * @template TError Return type when an error occurs.
+ * @param parser The parser to execute.
+ * @param programName Name of the program for help/error output.
+ * @param contexts Source contexts to use (priority: earlier overrides later).
+ * @param options Run options including args, help, version, etc.
+ * @returns Promise that resolves to the parsed result.
+ * @since 0.10.0
+ */
+declare function runWithAsync<TParser extends Parser<Mode, unknown, unknown>, THelp = void, TError = never>(parser: TParser, programName: string, contexts: readonly SourceContext[], options?: RunWithOptions<THelp, TError>): Promise<InferValue<TParser>>;
 //#endregion
-export { RunOptions, RunParserError, runParser, runParserAsync, runParserSync };
+export { RunOptions, RunParserError, RunWithOptions, type SourceContext, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync };

package/dist/facade.js

@@ -1,3 +1,4 @@
+import { annotationKey } from "./annotations.js";
 import { commandLine, formatMessage, message, optionName, text, value } from "./message.js";
 import { bash, fish, nu, pwsh, zsh } from "./completion.js";
 import { formatUsage } from "./usage.js";
@@ -658,6 +659,238 @@ var RunParserError = class extends Error {
 function indentLines(text$1, indent) {
 	return text$1.split("\n").join("\n" + " ".repeat(indent));
 }
+/**
+* Merges multiple annotation objects, with earlier contexts having priority.
+*
+* When the same symbol key exists in multiple annotations, the value from
+* the earlier context (lower index in the array) takes precedence.
+*
+* @param annotationsList Array of annotations to merge.
+* @returns Merged annotations object.
+*/
+function mergeAnnotations(annotationsList) {
+	const result = {};
+	for (let i = annotationsList.length - 1; i >= 0; i--) {
+		const annotations = annotationsList[i];
+		for (const key of Object.getOwnPropertySymbols(annotations)) result[key] = annotations[key];
+	}
+	return result;
+}
+/**
+* Collects annotations from all contexts.
+*
+* @param contexts Source contexts to collect annotations from.
+* @param parsed Optional parsed result from a previous parse pass.
+* @returns Promise that resolves to merged annotations.
+*/
+async function collectAnnotations(contexts, parsed) {
+	const annotationsList = [];
+	for (const context of contexts) {
+		const result = context.getAnnotations(parsed);
+		if (result instanceof Promise) annotationsList.push(await result);
+		else annotationsList.push(result);
+	}
+	return mergeAnnotations(annotationsList);
+}
+/**
+* Collects annotations from all contexts synchronously.
+*
+* @param contexts Source contexts to collect annotations from.
+* @param parsed Optional parsed result from a previous parse pass.
+* @returns Merged annotations.
+* @throws Error if any context returns a Promise.
+*/
+function collectAnnotationsSync(contexts, parsed) {
+	const annotationsList = [];
+	for (const context of contexts) {
+		const result = context.getAnnotations(parsed);
+		if (result instanceof Promise) throw new Error(`Context ${String(context.id)} returned a Promise in sync mode. Use runWith() or runWithAsync() for async contexts.`);
+		annotationsList.push(result);
+	}
+	return mergeAnnotations(annotationsList);
+}
+/**
+* Checks if any context has dynamic behavior (returns different annotations
+* when called with parsed results).
+*
+* A context is considered dynamic if:
+* - It returns a Promise
+* - It returns empty annotations without parsed results but may return
+*   non-empty annotations with parsed results
+*
+* @param contexts Source contexts to check.
+* @returns `true` if any context appears to be dynamic.
+*/
+function hasDynamicContexts(contexts) {
+	for (const context of contexts) {
+		const result = context.getAnnotations();
+		if (result instanceof Promise) return true;
+		if (Object.getOwnPropertySymbols(result).length === 0) return true;
+	}
+	return false;
+}
+/**
+* Runs a parser with multiple source contexts.
+*
+* This function automatically handles static and dynamic contexts with proper
+* priority. Earlier contexts in the array override later ones.
+*
+* The function uses a smart two-phase approach:
+*
+* 1. *Phase 1*: Collect annotations from all contexts (static contexts return
+*    their data, dynamic contexts may return empty).
+* 2. *First parse*: Parse with Phase 1 annotations.
+* 3. *Phase 2*: Call `getAnnotations(parsed)` on all contexts with the first
+*    parse result.
+* 4. *Second parse*: Parse again with merged annotations from both phases.
+*
+* If all contexts are static (no dynamic contexts), the second parse is skipped
+* for optimization.
+*
+* @template TParser The parser type.
+* @template THelp Return type when help is shown.
+* @template TError Return type when an error occurs.
+* @param parser The parser to execute.
+* @param programName Name of the program for help/error output.
+* @param contexts Source contexts to use (priority: earlier overrides later).
+* @param options Run options including args, help, version, etc.
+* @returns Promise that resolves to the parsed result.
+* @since 0.10.0
+*
+* @example
+* ```typescript
+* import { runWith } from "@optique/core/facade";
+* import type { SourceContext } from "@optique/core/context";
+*
+* const envContext: SourceContext = {
+*   id: Symbol.for("@myapp/env"),
+*   getAnnotations() {
+*     return { [Symbol.for("@myapp/env")]: process.env };
+*   }
+* };
+*
+* const result = await runWith(
+*   parser,
+*   "myapp",
+*   [envContext],
+*   { args: process.argv.slice(2) }
+* );
+* ```
+*/
+async function runWith(parser, programName, contexts, options) {
+	const args = options?.args ?? [];
+	if (contexts.length === 0) {
+		if (parser.$mode === "async") return runParser(parser, programName, args, options);
+		return Promise.resolve(runParser(parser, programName, args, options));
+	}
+	const phase1Annotations = await collectAnnotations(contexts);
+	const needsTwoPhase = hasDynamicContexts(contexts);
+	if (!needsTwoPhase) {
+		const augmentedParser = injectAnnotationsIntoParser(parser, phase1Annotations);
+		if (parser.$mode === "async") return runParser(augmentedParser, programName, args, options);
+		return Promise.resolve(runParser(augmentedParser, programName, args, options));
+	}
+	const augmentedParser1 = injectAnnotationsIntoParser(parser, phase1Annotations);
+	let firstPassResult;
+	try {
+		if (parser.$mode === "async") firstPassResult = await parseAsync(augmentedParser1, args);
+		else firstPassResult = parseSync(augmentedParser1, args);
+		if (typeof firstPassResult === "object" && firstPassResult !== null && "success" in firstPassResult) {
+			const result = firstPassResult;
+			if (result.success) firstPassResult = result.value;
+			else {
+				const augmentedParser = injectAnnotationsIntoParser(parser, phase1Annotations);
+				if (parser.$mode === "async") return runParser(augmentedParser, programName, args, options);
+				return Promise.resolve(runParser(augmentedParser, programName, args, options));
+			}
+		}
+	} catch {
+		const augmentedParser = injectAnnotationsIntoParser(parser, phase1Annotations);
+		if (parser.$mode === "async") return runParser(augmentedParser, programName, args, options);
+		return Promise.resolve(runParser(augmentedParser, programName, args, options));
+	}
+	const phase2Annotations = await collectAnnotations(contexts, firstPassResult);
+	const finalAnnotations = mergeAnnotations([phase1Annotations, phase2Annotations]);
+	const augmentedParser2 = injectAnnotationsIntoParser(parser, finalAnnotations);
+	if (parser.$mode === "async") return runParser(augmentedParser2, programName, args, options);
+	return Promise.resolve(runParser(augmentedParser2, programName, args, options));
+}
+/**
+* Runs a synchronous parser with multiple source contexts.
+*
+* This is the sync-only variant of {@link runWith}. All contexts must return
+* annotations synchronously (not Promises).
+*
+* @template TParser The sync parser type.
+* @template THelp Return type when help is shown.
+* @template TError Return type when an error occurs.
+* @param parser The synchronous parser to execute.
+* @param programName Name of the program for help/error output.
+* @param contexts Source contexts to use (priority: earlier overrides later).
+* @param options Run options including args, help, version, etc.
+* @returns The parsed result.
+* @throws Error if any context returns a Promise.
+* @since 0.10.0
+*/
+function runWithSync(parser, programName, contexts, options) {
+	const args = options?.args ?? [];
+	if (contexts.length === 0) return runParser(parser, programName, args, options);
+	const phase1Annotations = collectAnnotationsSync(contexts);
+	const needsTwoPhase = hasDynamicContexts(contexts);
+	if (!needsTwoPhase) {
+		const augmentedParser = injectAnnotationsIntoParser(parser, phase1Annotations);
+		return runParser(augmentedParser, programName, args, options);
+	}
+	const augmentedParser1 = injectAnnotationsIntoParser(parser, phase1Annotations);
+	let firstPassResult;
+	try {
+		const result = parseSync(augmentedParser1, args);
+		if (result.success) firstPassResult = result.value;
+		else return runParser(augmentedParser1, programName, args, options);
+	} catch {
+		return runParser(augmentedParser1, programName, args, options);
+	}
+	const phase2Annotations = collectAnnotationsSync(contexts, firstPassResult);
+	const finalAnnotations = mergeAnnotations([phase1Annotations, phase2Annotations]);
+	const augmentedParser2 = injectAnnotationsIntoParser(parser, finalAnnotations);
+	return runParser(augmentedParser2, programName, args, options);
+}
+/**
+* Runs any parser asynchronously with multiple source contexts.
+*
+* This function accepts parsers of any mode (sync or async) and always
+* returns a Promise. Use this when working with async contexts or parsers.
+*
+* @template TParser The parser type.
+* @template THelp Return type when help is shown.
+* @template TError Return type when an error occurs.
+* @param parser The parser to execute.
+* @param programName Name of the program for help/error output.
+* @param contexts Source contexts to use (priority: earlier overrides later).
+* @param options Run options including args, help, version, etc.
+* @returns Promise that resolves to the parsed result.
+* @since 0.10.0
+*/
+function runWithAsync(parser, programName, contexts, options) {
+	return runWith(parser, programName, contexts, options);
+}
+/**
+* Creates a new parser with annotations injected into its initial state.
+*
+* @param parser The original parser.
+* @param annotations Annotations to inject.
+* @returns A new parser with annotations in its initial state.
+*/
+function injectAnnotationsIntoParser(parser, annotations) {
+	const newInitialState = {
+		...parser.initialState,
+		[annotationKey]: annotations
+	};
+	return {
+		...parser,
+		initialState: newInitialState
+	};
+}
 
 //#endregion
-export { RunParserError, runParser, runParserAsync, runParserSync };
+export { RunParserError, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync };

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;
@@ -92,6 +95,9 @@ exports.pwsh = require_completion.pwsh;
 exports.runParser = require_facade.runParser;
 exports.runParserAsync = require_facade.runParserAsync;
 exports.runParserSync = require_facade.runParserSync;
+exports.runWith = require_facade.runWith;
+exports.runWithAsync = require_facade.runWithAsync;
+exports.runWithSync = require_facade.runWithSync;
 exports.string = require_valueparser.string;
 exports.suggest = require_parser.suggest;
 exports.suggestAsync = require_parser.suggestAsync;

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";
@@ -9,5 +10,6 @@ import { AnyDependencySource, CombineMode, CombinedDependencyMode, DeferredParse
 import { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, OptionErrorOptions, OptionOptions, OptionState, PassThroughFormat, PassThroughOptions, argument, command, constant, flag, option, passThrough } from "./primitives.cjs";
 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 };
+import { SourceContext } from "./context.cjs";
+import { RunOptions, RunParserError, RunWithOptions, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync } from "./facade.cjs";
+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, RunWithOptions, ShellCompletion, ShowDefaultOptions, SourceContext, 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, runWith, runWithAsync, runWithSync, 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";
@@ -9,5 +10,6 @@ import { AnyDependencySource, CombineMode, CombinedDependencyMode, DeferredParse
 import { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, OptionErrorOptions, OptionOptions, OptionState, PassThroughFormat, PassThroughOptions, argument, command, constant, flag, option, passThrough } from "./primitives.js";
 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 };
+import { SourceContext } from "./context.js";
+import { RunOptions, RunParserError, RunWithOptions, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync } from "./facade.js";
+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, RunWithOptions, ShellCompletion, ShowDefaultOptions, SourceContext, 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, runWith, runWithAsync, runWithSync, 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";
@@ -9,6 +10,6 @@ import { ensureNonEmptyString, isNonEmptyString } from "./nonempty.js";
 import { choice, float, integer, isValueParser, locale, string, url, uuid } from "./valueparser.js";
 import { argument, command, constant, flag, option, passThrough } from "./primitives.js";
 import { getDocPage, getDocPageAsync, getDocPageSync, parse, parseAsync, parseSync, suggest, suggestAsync, suggestSync } from "./parser.js";
-import { RunParserError, runParser, runParserAsync, runParserSync } from "./facade.js";
+import { RunParserError, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync } 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, runWith, runWithAsync, runWithSync, string, suggest, suggestAsync, suggestSync, suggestWithDependency, text, transformsDependencyValue, transformsDependencyValueMarker, tuple, url, uuid, value, valueSet, values, withDefault, wrappedDependencySourceMarker, zsh };