@optique/core 1.0.0-dev.562 → 1.0.0-dev.564

package/dist/context.d.cts

@@ -146,7 +146,9 @@ interface SourceContext<TRequiredOptions = void> {
   /**
    * Optional asynchronous cleanup method.  Called by `runWith()` in a
    * `finally` block after parsing completes.  Takes precedence over
-   * `[Symbol.dispose]` in async runners.
+   * `[Symbol.dispose]` in async runners.  `runWithSync()` also calls this
+   * method when `[Symbol.dispose]` is absent, but throws if it returns a
+   * Promise.
    */
   [Symbol.asyncDispose]?(): void | PromiseLike<void>;
 }

package/dist/context.d.ts

@@ -146,7 +146,9 @@ interface SourceContext<TRequiredOptions = void> {
   /**
    * Optional asynchronous cleanup method.  Called by `runWith()` in a
    * `finally` block after parsing completes.  Takes precedence over
-   * `[Symbol.dispose]` in async runners.
+   * `[Symbol.dispose]` in async runners.  `runWithSync()` also calls this
+   * method when `[Symbol.dispose]` is absent, but throws if it returns a
+   * Promise.
    */
   [Symbol.asyncDispose]?(): void | PromiseLike<void>;
 }

package/dist/facade.cjs

@@ -391,20 +391,8 @@ function classifyResult(result, args, helpOptionNames, helpCommandNames, version
 function handleCompletion(completionArgs, programName, parser, completionParser, stdout, stderr, onCompletion, onError, availableShells, colors, maxWidth, completionCommandDisplayName, completionOptionDisplayName, isOptionMode, sectionOrder) {
 	const shellName = completionArgs[0] || "";
 	const args = completionArgs.slice(1);
-	const callOnError = (code) => {
-		try {
-			return onError(code);
-		} catch {
-			return onError();
-		}
-	};
-	const callOnCompletion = (code) => {
-		try {
-			return onCompletion(code);
-		} catch {
-			return onCompletion();
-		}
-	};
+	const callOnError = (code) => onError(code);
+	const callOnCompletion = (code) => onCompletion(code);
 	if (!shellName) {
 		stderr("Error: Missing shell name for completion.\n");
 		if (completionParser) {
@@ -489,20 +477,8 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 	const completionCommandConfig = norm(options.completion?.command);
 	const completionOptionConfig = norm(options.completion?.option);
 	const onCompletion = options.completion?.onShow ?? (() => ({}));
-	const onCompletionResult = (code) => {
-		try {
-			return onCompletion(code);
-		} catch {
-			return onCompletion();
-		}
-	};
-	const onErrorResult = (code) => {
-		try {
-			return onError(code);
-		} catch {
-			return onError();
-		}
-	};
+	const onCompletionResult = (code) => onCompletion(code);
+	const onErrorResult = (code) => onError(code);
 	const helpOptionNames = helpOptionConfig?.names ?? ["--help"];
 	const helpCommandNames = helpCommandConfig?.names ?? ["help"];
 	const versionOptionNames = versionOptionConfig?.names ?? ["--version"];
@@ -565,11 +541,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 			case "success": return classified.value;
 			case "version":
 				stdout(versionValue);
-				try {
-					return onVersion(0);
-				} catch {
-					return onVersion();
-				}
+				return onVersion(0);
 			case "completion": throw new RunParserError("Completion should be handled by early return");
 			case "help": {
 				let helpGeneratorParser;
@@ -649,11 +621,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 							sectionOrder
 						}));
 					}
-					try {
-						return onHelp(0);
-					} catch {
-						return onHelp();
-					}
+					return onHelp(0);
 				};
 				if (classified.commands.length > 0) {
 					let validationContext = {
@@ -965,16 +933,35 @@ function collectAnnotationsSync(contexts, parsed, options) {
 * @param contexts Source contexts to dispose.
 */
 async function disposeContexts(contexts) {
-	for (const context of contexts) if (Symbol.asyncDispose in context && typeof context[Symbol.asyncDispose] === "function") await context[Symbol.asyncDispose]();
-	else if (Symbol.dispose in context && typeof context[Symbol.dispose] === "function") context[Symbol.dispose]();
+	const errors = [];
+	for (const context of contexts) try {
+		if (Symbol.asyncDispose in context && typeof context[Symbol.asyncDispose] === "function") await context[Symbol.asyncDispose]();
+		else if (Symbol.dispose in context && typeof context[Symbol.dispose] === "function") context[Symbol.dispose]();
+	} catch (error) {
+		errors.push(error);
+	}
+	if (errors.length === 1) throw errors[0];
+	if (errors.length > 1) throw new AggregateError(errors, "Failed to dispose one or more source contexts.");
 }
 /**
 * Disposes all contexts that implement `Disposable` synchronously.
+* Falls back to `[Symbol.asyncDispose]` when it completes synchronously.
 *
 * @param contexts Source contexts to dispose.
 */
 function disposeContextsSync(contexts) {
-	for (const context of contexts) if (Symbol.dispose in context && typeof context[Symbol.dispose] === "function") context[Symbol.dispose]();
+	const errors = [];
+	for (const context of contexts) try {
+		if (Symbol.dispose in context && typeof context[Symbol.dispose] === "function") context[Symbol.dispose]();
+		else if (Symbol.asyncDispose in context && typeof context[Symbol.asyncDispose] === "function") {
+			const result = context[Symbol.asyncDispose]();
+			if (typeof result === "object" && result !== null && "then" in result && typeof result.then === "function") throw new TypeError(`Context ${String(context.id)} returned a Promise from Symbol.asyncDispose in sync mode. Use runWith() or runWithAsync() for async disposal.`);
+		}
+	} catch (error) {
+		errors.push(error);
+	}
+	if (errors.length === 1) throw errors[0];
+	if (errors.length > 1) throw new AggregateError(errors, "Failed to dispose one or more source contexts.");
 }
 /**
 * Runs a parser with multiple source contexts.
@@ -1083,7 +1070,8 @@ async function runWith(parser, programName, contexts, options) {
 * @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.
+* @throws Error if any context returns a Promise or if a context's
+* `[Symbol.asyncDispose]` returns a Promise.
 * @since 0.10.0
 */
 function runWithSync(parser, programName, contexts, options) {

package/dist/facade.d.cts

@@ -431,7 +431,8 @@ declare function runWith<TParser extends Parser<Mode, unknown, unknown>, TContex
  * @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.
+ * @throws Error if any context returns a Promise or if a context's
+ * `[Symbol.asyncDispose]` returns a Promise.
  * @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> & ExtractRequiredOptions<TContexts, InferValue<TParser>>): InferValue<TParser>;

package/dist/facade.d.ts

@@ -431,7 +431,8 @@ declare function runWith<TParser extends Parser<Mode, unknown, unknown>, TContex
  * @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.
+ * @throws Error if any context returns a Promise or if a context's
+ * `[Symbol.asyncDispose]` returns a Promise.
  * @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> & ExtractRequiredOptions<TContexts, InferValue<TParser>>): InferValue<TParser>;

package/dist/facade.js

@@ -391,20 +391,8 @@ function classifyResult(result, args, helpOptionNames, helpCommandNames, version
 function handleCompletion(completionArgs, programName, parser, completionParser, stdout, stderr, onCompletion, onError, availableShells, colors, maxWidth, completionCommandDisplayName, completionOptionDisplayName, isOptionMode, sectionOrder) {
 	const shellName = completionArgs[0] || "";
 	const args = completionArgs.slice(1);
-	const callOnError = (code) => {
-		try {
-			return onError(code);
-		} catch {
-			return onError();
-		}
-	};
-	const callOnCompletion = (code) => {
-		try {
-			return onCompletion(code);
-		} catch {
-			return onCompletion();
-		}
-	};
+	const callOnError = (code) => onError(code);
+	const callOnCompletion = (code) => onCompletion(code);
 	if (!shellName) {
 		stderr("Error: Missing shell name for completion.\n");
 		if (completionParser) {
@@ -489,20 +477,8 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 	const completionCommandConfig = norm(options.completion?.command);
 	const completionOptionConfig = norm(options.completion?.option);
 	const onCompletion = options.completion?.onShow ?? (() => ({}));
-	const onCompletionResult = (code) => {
-		try {
-			return onCompletion(code);
-		} catch {
-			return onCompletion();
-		}
-	};
-	const onErrorResult = (code) => {
-		try {
-			return onError(code);
-		} catch {
-			return onError();
-		}
-	};
+	const onCompletionResult = (code) => onCompletion(code);
+	const onErrorResult = (code) => onError(code);
 	const helpOptionNames = helpOptionConfig?.names ?? ["--help"];
 	const helpCommandNames = helpCommandConfig?.names ?? ["help"];
 	const versionOptionNames = versionOptionConfig?.names ?? ["--version"];
@@ -565,11 +541,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 			case "success": return classified.value;
 			case "version":
 				stdout(versionValue);
-				try {
-					return onVersion(0);
-				} catch {
-					return onVersion();
-				}
+				return onVersion(0);
 			case "completion": throw new RunParserError("Completion should be handled by early return");
 			case "help": {
 				let helpGeneratorParser;
@@ -649,11 +621,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 							sectionOrder
 						}));
 					}
-					try {
-						return onHelp(0);
-					} catch {
-						return onHelp();
-					}
+					return onHelp(0);
 				};
 				if (classified.commands.length > 0) {
 					let validationContext = {
@@ -965,16 +933,35 @@ function collectAnnotationsSync(contexts, parsed, options) {
 * @param contexts Source contexts to dispose.
 */
 async function disposeContexts(contexts) {
-	for (const context of contexts) if (Symbol.asyncDispose in context && typeof context[Symbol.asyncDispose] === "function") await context[Symbol.asyncDispose]();
-	else if (Symbol.dispose in context && typeof context[Symbol.dispose] === "function") context[Symbol.dispose]();
+	const errors = [];
+	for (const context of contexts) try {
+		if (Symbol.asyncDispose in context && typeof context[Symbol.asyncDispose] === "function") await context[Symbol.asyncDispose]();
+		else if (Symbol.dispose in context && typeof context[Symbol.dispose] === "function") context[Symbol.dispose]();
+	} catch (error) {
+		errors.push(error);
+	}
+	if (errors.length === 1) throw errors[0];
+	if (errors.length > 1) throw new AggregateError(errors, "Failed to dispose one or more source contexts.");
 }
 /**
 * Disposes all contexts that implement `Disposable` synchronously.
+* Falls back to `[Symbol.asyncDispose]` when it completes synchronously.
 *
 * @param contexts Source contexts to dispose.
 */
 function disposeContextsSync(contexts) {
-	for (const context of contexts) if (Symbol.dispose in context && typeof context[Symbol.dispose] === "function") context[Symbol.dispose]();
+	const errors = [];
+	for (const context of contexts) try {
+		if (Symbol.dispose in context && typeof context[Symbol.dispose] === "function") context[Symbol.dispose]();
+		else if (Symbol.asyncDispose in context && typeof context[Symbol.asyncDispose] === "function") {
+			const result = context[Symbol.asyncDispose]();
+			if (typeof result === "object" && result !== null && "then" in result && typeof result.then === "function") throw new TypeError(`Context ${String(context.id)} returned a Promise from Symbol.asyncDispose in sync mode. Use runWith() or runWithAsync() for async disposal.`);
+		}
+	} catch (error) {
+		errors.push(error);
+	}
+	if (errors.length === 1) throw errors[0];
+	if (errors.length > 1) throw new AggregateError(errors, "Failed to dispose one or more source contexts.");
 }
 /**
 * Runs a parser with multiple source contexts.
@@ -1083,7 +1070,8 @@ async function runWith(parser, programName, contexts, options) {
 * @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.
+* @throws Error if any context returns a Promise or if a context's
+* `[Symbol.asyncDispose]` returns a Promise.
 * @since 0.10.0
 */
 function runWithSync(parser, programName, contexts, options) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.0.0-dev.562+295508a4",
+  "version": "1.0.0-dev.564+e2374449",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",