@optique/core 1.0.0-dev.1684 → 1.0.0-dev.1688

package/dist/facade.cjs

@@ -1180,6 +1180,53 @@ function disposeContextsSync(contexts) {
 	if (errors.length > 1) throw new AggregateError(errors, "Failed to dispose one or more source contexts.");
 }
 /**
+* Body of {@link runWith}, extracted so that the caller can handle
+* disposal outside a `finally` block (avoiding `no-unsafe-finally` lint).
+*/
+async function runWithBody(parser, programName, contexts, args, options) {
+	require_validate.validateContextIds(contexts);
+	if (needsEarlyExit(args, options)) {
+		if (parser.$mode === "async") return runParser(parser, programName, args, options);
+		return Promise.resolve(runParser(parser, programName, args, options));
+	}
+	const ctxOptions = options.contextOptions;
+	const { annotations: phase1Annotations, annotationsList: phase1AnnotationsList, hasDynamic: needsTwoPhase } = await collectPhase1Annotations(contexts, ctxOptions);
+	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;
+	let firstPassDeferred;
+	let firstPassDeferredKeys;
+	let firstPassFailed = false;
+	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;
+				firstPassDeferred = result.deferred;
+				firstPassDeferredKeys = result.deferredKeys;
+			} else firstPassFailed = true;
+		}
+	} catch {
+		firstPassFailed = true;
+	}
+	if (firstPassFailed) {
+		const augmentedParser = injectAnnotationsIntoParser(parser, phase1Annotations);
+		if (parser.$mode === "async") return runParser(augmentedParser, programName, args, options);
+		return Promise.resolve(runParser(augmentedParser, programName, args, options));
+	}
+	const { annotationsList: phase2AnnotationsList } = await collectAnnotations(contexts, firstPassResult, ctxOptions, firstPassDeferred, firstPassDeferredKeys);
+	const finalAnnotations = mergeTwoPhaseAnnotations(phase1AnnotationsList, phase2AnnotationsList);
+	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 parser with multiple source contexts.
 *
 * This function automatically handles static and dynamic contexts with proper
@@ -1207,6 +1254,9 @@ function disposeContextsSync(contexts) {
 * @returns Promise that resolves to the parsed result.
 * @throws {TypeError} If two or more contexts share the same
 * {@link SourceContext.id}.
+* @throws {SuppressedError} If parsing fails and a context's disposal also
+* throws.  The original parse error is available via `.suppressed` and the
+* disposal error via `.error`.
 * @since 0.10.0
 *
 * @example
@@ -1229,49 +1279,6 @@ function disposeContextsSync(contexts) {
 * );
 * ```
 */
-async function runWithBody(parser, programName, contexts, args, options) {
-	require_validate.validateContextIds(contexts);
-	if (needsEarlyExit(args, options)) {
-		if (parser.$mode === "async") return runParser(parser, programName, args, options);
-		return Promise.resolve(runParser(parser, programName, args, options));
-	}
-	const ctxOptions = options.contextOptions;
-	const { annotations: phase1Annotations, annotationsList: phase1AnnotationsList, hasDynamic: needsTwoPhase } = await collectPhase1Annotations(contexts, ctxOptions);
-	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;
-	let firstPassDeferred;
-	let firstPassDeferredKeys;
-	let firstPassFailed = false;
-	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;
-				firstPassDeferred = result.deferred;
-				firstPassDeferredKeys = result.deferredKeys;
-			} else firstPassFailed = true;
-		}
-	} catch {
-		firstPassFailed = true;
-	}
-	if (firstPassFailed) {
-		const augmentedParser = injectAnnotationsIntoParser(parser, phase1Annotations);
-		if (parser.$mode === "async") return runParser(augmentedParser, programName, args, options);
-		return Promise.resolve(runParser(augmentedParser, programName, args, options));
-	}
-	const { annotationsList: phase2AnnotationsList } = await collectAnnotations(contexts, firstPassResult, ctxOptions, firstPassDeferred, firstPassDeferredKeys);
-	const finalAnnotations = mergeTwoPhaseAnnotations(phase1AnnotationsList, phase2AnnotationsList);
-	const augmentedParser2 = injectAnnotationsIntoParser(parser, finalAnnotations);
-	if (parser.$mode === "async") return runParser(augmentedParser2, programName, args, options);
-	return Promise.resolve(runParser(augmentedParser2, programName, args, options));
-}
 async function runWith(parser, programName, contexts, options) {
 	const args = options?.args ?? [];
 	if (contexts.length === 0) {
@@ -1348,6 +1355,9 @@ function runWithSyncBody(parser, programName, contexts, args, options) {
 * {@link SourceContext.id}.
 * @throws {Error} If any context returns a Promise or if a context's
 * `[Symbol.asyncDispose]` returns a Promise.
+* @throws {SuppressedError} If parsing fails and a context's disposal also
+* throws.  The original parse error is available via `.suppressed` and the
+* disposal error via `.error`.
 * @since 0.10.0
 */
 function runWithSync(parser, programName, contexts, options) {
@@ -1388,6 +1398,9 @@ function runWithSync(parser, programName, contexts, options) {
 * @returns Promise that resolves to the parsed result.
 * @throws {TypeError} If two or more contexts share the same
 * {@link SourceContext.id}.
+* @throws {SuppressedError} If parsing fails and a context's disposal also
+* throws.  The original parse error is available via `.suppressed` and the
+* disposal error via `.error`.
 * @since 0.10.0
 */
 function runWithAsync(parser, programName, contexts, options) {

package/dist/facade.d.cts

@@ -402,6 +402,59 @@ type ContextOptionsParam<TContexts extends readonly SourceContext<unknown>[], TV
 } : {
   readonly contextOptions: ExtractRequiredOptions<TContexts, TValue>;
 };
+/**
+ * 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.
+ * @throws {TypeError} If two or more contexts share the same
+ * {@link SourceContext.id}.
+ * @throws {SuppressedError} If parsing fails and a context's disposal also
+ * throws.  The original parse error is available via `.suppressed` and the
+ * disposal error via `.error`.
+ * @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>, TContexts extends readonly SourceContext<unknown>[], THelp = void, TError = never>(parser: TParser, programName: string, contexts: TContexts, options: RunWithOptions<THelp, TError> & ContextOptionsParam<TContexts, InferValue<TParser>>): Promise<InferValue<TParser>>;
 /**
  * Runs a synchronous parser with multiple source contexts.
@@ -423,6 +476,9 @@ declare function runWith<TParser extends Parser<Mode, unknown, unknown>, TContex
  * {@link SourceContext.id}.
  * @throws {Error} If any context returns a Promise or if a context's
  * `[Symbol.asyncDispose]` returns a Promise.
+ * @throws {SuppressedError} If parsing fails and a context's disposal also
+ * throws.  The original parse error is available via `.suppressed` and the
+ * disposal error via `.error`.
  * @since 0.10.0
  */
 declare function runWithSync<TParser extends Parser<"sync", unknown, unknown>, TContexts extends readonly SourceContext<unknown>[], THelp = void, TError = never>(parser: TParser, programName: string, contexts: TContexts, options: RunWithOptions<THelp, TError> & ContextOptionsParam<TContexts, InferValue<TParser>>): InferValue<TParser>;
@@ -442,6 +498,9 @@ declare function runWithSync<TParser extends Parser<"sync", unknown, unknown>, T
  * @returns Promise that resolves to the parsed result.
  * @throws {TypeError} If two or more contexts share the same
  * {@link SourceContext.id}.
+ * @throws {SuppressedError} If parsing fails and a context's disposal also
+ * throws.  The original parse error is available via `.suppressed` and the
+ * disposal error via `.error`.
  * @since 0.10.0
  */
 declare function runWithAsync<TParser extends Parser<Mode, unknown, unknown>, TContexts extends readonly SourceContext<unknown>[], THelp = void, TError = never>(parser: TParser, programName: string, contexts: TContexts, options: RunWithOptions<THelp, TError> & ContextOptionsParam<TContexts, InferValue<TParser>>): Promise<InferValue<TParser>>;

package/dist/facade.d.ts

@@ -402,6 +402,59 @@ type ContextOptionsParam<TContexts extends readonly SourceContext<unknown>[], TV
 } : {
   readonly contextOptions: ExtractRequiredOptions<TContexts, TValue>;
 };
+/**
+ * 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.
+ * @throws {TypeError} If two or more contexts share the same
+ * {@link SourceContext.id}.
+ * @throws {SuppressedError} If parsing fails and a context's disposal also
+ * throws.  The original parse error is available via `.suppressed` and the
+ * disposal error via `.error`.
+ * @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>, TContexts extends readonly SourceContext<unknown>[], THelp = void, TError = never>(parser: TParser, programName: string, contexts: TContexts, options: RunWithOptions<THelp, TError> & ContextOptionsParam<TContexts, InferValue<TParser>>): Promise<InferValue<TParser>>;
 /**
  * Runs a synchronous parser with multiple source contexts.
@@ -423,6 +476,9 @@ declare function runWith<TParser extends Parser<Mode, unknown, unknown>, TContex
  * {@link SourceContext.id}.
  * @throws {Error} If any context returns a Promise or if a context's
  * `[Symbol.asyncDispose]` returns a Promise.
+ * @throws {SuppressedError} If parsing fails and a context's disposal also
+ * throws.  The original parse error is available via `.suppressed` and the
+ * disposal error via `.error`.
  * @since 0.10.0
  */
 declare function runWithSync<TParser extends Parser<"sync", unknown, unknown>, TContexts extends readonly SourceContext<unknown>[], THelp = void, TError = never>(parser: TParser, programName: string, contexts: TContexts, options: RunWithOptions<THelp, TError> & ContextOptionsParam<TContexts, InferValue<TParser>>): InferValue<TParser>;
@@ -442,6 +498,9 @@ declare function runWithSync<TParser extends Parser<"sync", unknown, unknown>, T
  * @returns Promise that resolves to the parsed result.
  * @throws {TypeError} If two or more contexts share the same
  * {@link SourceContext.id}.
+ * @throws {SuppressedError} If parsing fails and a context's disposal also
+ * throws.  The original parse error is available via `.suppressed` and the
+ * disposal error via `.error`.
  * @since 0.10.0
  */
 declare function runWithAsync<TParser extends Parser<Mode, unknown, unknown>, TContexts extends readonly SourceContext<unknown>[], THelp = void, TError = never>(parser: TParser, programName: string, contexts: TContexts, options: RunWithOptions<THelp, TError> & ContextOptionsParam<TContexts, InferValue<TParser>>): Promise<InferValue<TParser>>;

package/dist/facade.js

@@ -1180,6 +1180,53 @@ function disposeContextsSync(contexts) {
 	if (errors.length > 1) throw new AggregateError(errors, "Failed to dispose one or more source contexts.");
 }
 /**
+* Body of {@link runWith}, extracted so that the caller can handle
+* disposal outside a `finally` block (avoiding `no-unsafe-finally` lint).
+*/
+async function runWithBody(parser, programName, contexts, args, options) {
+	validateContextIds(contexts);
+	if (needsEarlyExit(args, options)) {
+		if (parser.$mode === "async") return runParser(parser, programName, args, options);
+		return Promise.resolve(runParser(parser, programName, args, options));
+	}
+	const ctxOptions = options.contextOptions;
+	const { annotations: phase1Annotations, annotationsList: phase1AnnotationsList, hasDynamic: needsTwoPhase } = await collectPhase1Annotations(contexts, ctxOptions);
+	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;
+	let firstPassDeferred;
+	let firstPassDeferredKeys;
+	let firstPassFailed = false;
+	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;
+				firstPassDeferred = result.deferred;
+				firstPassDeferredKeys = result.deferredKeys;
+			} else firstPassFailed = true;
+		}
+	} catch {
+		firstPassFailed = true;
+	}
+	if (firstPassFailed) {
+		const augmentedParser = injectAnnotationsIntoParser(parser, phase1Annotations);
+		if (parser.$mode === "async") return runParser(augmentedParser, programName, args, options);
+		return Promise.resolve(runParser(augmentedParser, programName, args, options));
+	}
+	const { annotationsList: phase2AnnotationsList } = await collectAnnotations(contexts, firstPassResult, ctxOptions, firstPassDeferred, firstPassDeferredKeys);
+	const finalAnnotations = mergeTwoPhaseAnnotations(phase1AnnotationsList, phase2AnnotationsList);
+	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 parser with multiple source contexts.
 *
 * This function automatically handles static and dynamic contexts with proper
@@ -1207,6 +1254,9 @@ function disposeContextsSync(contexts) {
 * @returns Promise that resolves to the parsed result.
 * @throws {TypeError} If two or more contexts share the same
 * {@link SourceContext.id}.
+* @throws {SuppressedError} If parsing fails and a context's disposal also
+* throws.  The original parse error is available via `.suppressed` and the
+* disposal error via `.error`.
 * @since 0.10.0
 *
 * @example
@@ -1229,49 +1279,6 @@ function disposeContextsSync(contexts) {
 * );
 * ```
 */
-async function runWithBody(parser, programName, contexts, args, options) {
-	validateContextIds(contexts);
-	if (needsEarlyExit(args, options)) {
-		if (parser.$mode === "async") return runParser(parser, programName, args, options);
-		return Promise.resolve(runParser(parser, programName, args, options));
-	}
-	const ctxOptions = options.contextOptions;
-	const { annotations: phase1Annotations, annotationsList: phase1AnnotationsList, hasDynamic: needsTwoPhase } = await collectPhase1Annotations(contexts, ctxOptions);
-	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;
-	let firstPassDeferred;
-	let firstPassDeferredKeys;
-	let firstPassFailed = false;
-	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;
-				firstPassDeferred = result.deferred;
-				firstPassDeferredKeys = result.deferredKeys;
-			} else firstPassFailed = true;
-		}
-	} catch {
-		firstPassFailed = true;
-	}
-	if (firstPassFailed) {
-		const augmentedParser = injectAnnotationsIntoParser(parser, phase1Annotations);
-		if (parser.$mode === "async") return runParser(augmentedParser, programName, args, options);
-		return Promise.resolve(runParser(augmentedParser, programName, args, options));
-	}
-	const { annotationsList: phase2AnnotationsList } = await collectAnnotations(contexts, firstPassResult, ctxOptions, firstPassDeferred, firstPassDeferredKeys);
-	const finalAnnotations = mergeTwoPhaseAnnotations(phase1AnnotationsList, phase2AnnotationsList);
-	const augmentedParser2 = injectAnnotationsIntoParser(parser, finalAnnotations);
-	if (parser.$mode === "async") return runParser(augmentedParser2, programName, args, options);
-	return Promise.resolve(runParser(augmentedParser2, programName, args, options));
-}
 async function runWith(parser, programName, contexts, options) {
 	const args = options?.args ?? [];
 	if (contexts.length === 0) {
@@ -1348,6 +1355,9 @@ function runWithSyncBody(parser, programName, contexts, args, options) {
 * {@link SourceContext.id}.
 * @throws {Error} If any context returns a Promise or if a context's
 * `[Symbol.asyncDispose]` returns a Promise.
+* @throws {SuppressedError} If parsing fails and a context's disposal also
+* throws.  The original parse error is available via `.suppressed` and the
+* disposal error via `.error`.
 * @since 0.10.0
 */
 function runWithSync(parser, programName, contexts, options) {
@@ -1388,6 +1398,9 @@ function runWithSync(parser, programName, contexts, options) {
 * @returns Promise that resolves to the parsed result.
 * @throws {TypeError} If two or more contexts share the same
 * {@link SourceContext.id}.
+* @throws {SuppressedError} If parsing fails and a context's disposal also
+* throws.  The original parse error is available via `.suppressed` and the
+* disposal error via `.error`.
 * @since 0.10.0
 */
 function runWithAsync(parser, programName, contexts, options) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.0.0-dev.1684+b4ee4c18",
+  "version": "1.0.0-dev.1688+badbb89a",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",