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

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/context.cjs

@@ -0,0 +1,21 @@
+
+//#region src/context.ts
+/**
+* Checks whether a context is static (returns annotations without needing
+* parsed results).
+*
+* A context is considered static if `getAnnotations()` called without
+* arguments returns a non-empty annotations object synchronously.
+*
+* @param context The source context to check.
+* @returns `true` if the context is static, `false` otherwise.
+* @since 0.10.0
+*/
+function isStaticContext(context) {
+	const result = context.getAnnotations();
+	if (result instanceof Promise) return false;
+	return Object.getOwnPropertySymbols(result).length > 0;
+}
+
+//#endregion
+exports.isStaticContext = isStaticContext;

package/dist/context.d.cts

@@ -0,0 +1,87 @@
+import { Annotations } from "./annotations.cjs";
+
+//#region src/context.d.ts
+
+/**
+ * A source context that can provide data to parsers via annotations.
+ *
+ * Source contexts are used to inject external data (like environment variables
+ * or config files) into the parsing process. They can be either:
+ *
+ * - *Static*: Data is immediately available (e.g., environment variables)
+ * - *Dynamic*: Data depends on parsing results (e.g., config files whose path
+ *   is determined by a CLI option)
+ *
+ * @example
+ * ```typescript
+ * // Static context example (environment variables)
+ * const envContext: SourceContext = {
+ *   id: Symbol.for("@myapp/env"),
+ *   getAnnotations() {
+ *     return {
+ *       [Symbol.for("@myapp/env")]: {
+ *         HOST: process.env.HOST,
+ *         PORT: process.env.PORT,
+ *       }
+ *     };
+ *   }
+ * };
+ *
+ * // Dynamic context example (config file)
+ * const configContext: SourceContext = {
+ *   id: Symbol.for("@myapp/config"),
+ *   async getAnnotations(parsed?: unknown) {
+ *     if (!parsed) return {}; // Return empty on first pass
+ *     const result = parsed as { config?: string };
+ *     if (!result.config) return {};
+ *     const data = await loadConfigFile(result.config);
+ *     return {
+ *       [Symbol.for("@myapp/config")]: data
+ *     };
+ *   }
+ * };
+ * ```
+ *
+ * @since 0.10.0
+ */
+interface SourceContext {
+  /**
+   * Unique identifier for this context.
+   *
+   * This symbol is typically the same as the annotation key used by parsers
+   * that consume this context's data.
+   */
+  readonly id: symbol;
+  /**
+   * Get annotations to inject into parsing.
+   *
+   * This method is called twice during `runWith()` execution:
+   *
+   * 1. *First call*: `parsed` is `undefined`. Static contexts should return
+   *    their annotations, while dynamic contexts should return an empty object.
+   * 2. *Second call*: `parsed` contains the result from the first parse pass.
+   *    Dynamic contexts can use this to load external data (e.g., reading
+   *    a config file whose path was determined in the first pass).
+   *
+   * @param parsed Optional parsed result from a previous parse pass.
+   *               Static contexts can ignore this parameter.
+   *               Dynamic contexts use this to extract necessary data.
+   * @returns Annotations to merge into the parsing session. Can be a Promise
+   *          for async operations (e.g., loading config files).
+   */
+  getAnnotations(parsed?: unknown): Promise<Annotations> | Annotations;
+}
+/**
+ * Checks whether a context is static (returns annotations without needing
+ * parsed results).
+ *
+ * A context is considered static if `getAnnotations()` called without
+ * arguments returns a non-empty annotations object synchronously.
+ *
+ * @param context The source context to check.
+ * @returns `true` if the context is static, `false` otherwise.
+ * @since 0.10.0
+ */
+declare function isStaticContext(context: SourceContext): boolean;
+//#endregion
+export { type Annotations, SourceContext, isStaticContext };

package/dist/context.d.ts

@@ -0,0 +1,87 @@
+import { Annotations } from "./annotations.js";
+
+//#region src/context.d.ts
+
+/**
+ * A source context that can provide data to parsers via annotations.
+ *
+ * Source contexts are used to inject external data (like environment variables
+ * or config files) into the parsing process. They can be either:
+ *
+ * - *Static*: Data is immediately available (e.g., environment variables)
+ * - *Dynamic*: Data depends on parsing results (e.g., config files whose path
+ *   is determined by a CLI option)
+ *
+ * @example
+ * ```typescript
+ * // Static context example (environment variables)
+ * const envContext: SourceContext = {
+ *   id: Symbol.for("@myapp/env"),
+ *   getAnnotations() {
+ *     return {
+ *       [Symbol.for("@myapp/env")]: {
+ *         HOST: process.env.HOST,
+ *         PORT: process.env.PORT,
+ *       }
+ *     };
+ *   }
+ * };
+ *
+ * // Dynamic context example (config file)
+ * const configContext: SourceContext = {
+ *   id: Symbol.for("@myapp/config"),
+ *   async getAnnotations(parsed?: unknown) {
+ *     if (!parsed) return {}; // Return empty on first pass
+ *     const result = parsed as { config?: string };
+ *     if (!result.config) return {};
+ *     const data = await loadConfigFile(result.config);
+ *     return {
+ *       [Symbol.for("@myapp/config")]: data
+ *     };
+ *   }
+ * };
+ * ```
+ *
+ * @since 0.10.0
+ */
+interface SourceContext {
+  /**
+   * Unique identifier for this context.
+   *
+   * This symbol is typically the same as the annotation key used by parsers
+   * that consume this context's data.
+   */
+  readonly id: symbol;
+  /**
+   * Get annotations to inject into parsing.
+   *
+   * This method is called twice during `runWith()` execution:
+   *
+   * 1. *First call*: `parsed` is `undefined`. Static contexts should return
+   *    their annotations, while dynamic contexts should return an empty object.
+   * 2. *Second call*: `parsed` contains the result from the first parse pass.
+   *    Dynamic contexts can use this to load external data (e.g., reading
+   *    a config file whose path was determined in the first pass).
+   *
+   * @param parsed Optional parsed result from a previous parse pass.
+   *               Static contexts can ignore this parameter.
+   *               Dynamic contexts use this to extract necessary data.
+   * @returns Annotations to merge into the parsing session. Can be a Promise
+   *          for async operations (e.g., loading config files).
+   */
+  getAnnotations(parsed?: unknown): Promise<Annotations> | Annotations;
+}
+/**
+ * Checks whether a context is static (returns annotations without needing
+ * parsed results).
+ *
+ * A context is considered static if `getAnnotations()` called without
+ * arguments returns a non-empty annotations object synchronously.
+ *
+ * @param context The source context to check.
+ * @returns `true` if the context is static, `false` otherwise.
+ * @since 0.10.0
+ */
+declare function isStaticContext(context: SourceContext): boolean;
+//#endregion
+export { type Annotations, SourceContext, isStaticContext };

package/dist/context.js

@@ -0,0 +1,20 @@
+//#region src/context.ts
+/**
+* Checks whether a context is static (returns annotations without needing
+* parsed results).
+*
+* A context is considered static if `getAnnotations()` called without
+* arguments returns a non-empty annotations object synchronously.
+*
+* @param context The source context to check.
+* @returns `true` if the context is static, `false` otherwise.
+* @since 0.10.0
+*/
+function isStaticContext(context) {
+	const result = context.getAnnotations();
+	if (result instanceof Promise) return false;
+	return Object.getOwnPropertySymbols(result).length > 0;
+}
+
+//#endregion
+export { isStaticContext };

package/dist/facade.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_usage = require('./usage.cjs');
@@ -658,9 +659,244 @@ 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 require_parser.parseAsync(augmentedParser1, args);
+		else firstPassResult = require_parser.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 = require_parser.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,
+		[require_annotations.annotationKey]: annotations
+	};
+	return {
+		...parser,
+		initialState: newInitialState
+	};
+}
 
 //#endregion
 exports.RunParserError = RunParserError;
 exports.runParser = runParser;
 exports.runParserAsync = runParserAsync;
-exports.runParserSync = runParserSync;
+exports.runParserSync = runParserSync;
+exports.runWith = runWith;
+exports.runWithAsync = runWithAsync;
+exports.runWithSync = runWithSync;