@optique/run 0.9.0-dev.211 → 0.9.0-dev.215

package/dist/index.cjs

@@ -6,4 +6,6 @@ exports.createPrinter = require_print.createPrinter;
 exports.path = require_valueparser.path;
 exports.print = require_print.print;
 exports.printError = require_print.printError;
-exports.run = require_run.run;
+exports.run = require_run.run;
+exports.runAsync = require_run.runAsync;
+exports.runSync = require_run.runSync;

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { RunOptions, run } from "./run.cjs";
+import { RunOptions, run, runAsync, runSync } from "./run.cjs";
 import { PathErrorOptions, PathOptions, PathOptionsBase, PathOptionsMustExist, PathOptionsMustNotExist, PathOptionsNoExistenceCheck, path } from "./valueparser.cjs";
 import { PrintErrorOptions, PrintOptions, Printer, PrinterOptions, createPrinter, print, printError } from "./print.cjs";
-export { PathErrorOptions, PathOptions, PathOptionsBase, PathOptionsMustExist, PathOptionsMustNotExist, PathOptionsNoExistenceCheck, PrintErrorOptions, PrintOptions, Printer, PrinterOptions, RunOptions, createPrinter, path, print, printError, run };
+export { PathErrorOptions, PathOptions, PathOptionsBase, PathOptionsMustExist, PathOptionsMustNotExist, PathOptionsNoExistenceCheck, PrintErrorOptions, PrintOptions, Printer, PrinterOptions, RunOptions, createPrinter, path, print, printError, run, runAsync, runSync };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { RunOptions, run } from "./run.js";
+import { RunOptions, run, runAsync, runSync } from "./run.js";
 import { PathErrorOptions, PathOptions, PathOptionsBase, PathOptionsMustExist, PathOptionsMustNotExist, PathOptionsNoExistenceCheck, path } from "./valueparser.js";
 import { PrintErrorOptions, PrintOptions, Printer, PrinterOptions, createPrinter, print, printError } from "./print.js";
-export { PathErrorOptions, PathOptions, PathOptionsBase, PathOptionsMustExist, PathOptionsMustNotExist, PathOptionsNoExistenceCheck, PrintErrorOptions, PrintOptions, Printer, PrinterOptions, RunOptions, createPrinter, path, print, printError, run };
+export { PathErrorOptions, PathOptions, PathOptionsBase, PathOptionsMustExist, PathOptionsMustNotExist, PathOptionsNoExistenceCheck, PrintErrorOptions, PrintOptions, Printer, PrinterOptions, RunOptions, createPrinter, path, print, printError, run, runAsync, runSync };

package/dist/index.js

@@ -1,5 +1,5 @@
-import { run } from "./run.js";
+import { run, runAsync, runSync } from "./run.js";
 import { path } from "./valueparser.js";
 import { createPrinter, print, printError } from "./print.js";
 
-export { createPrinter, path, print, printError, run };
+export { createPrinter, path, print, printError, run, runAsync, runSync };

package/dist/run.cjs

@@ -4,70 +4,43 @@ const node_path = require_rolldown_runtime.__toESM(require("node:path"));
 const node_process = require_rolldown_runtime.__toESM(require("node:process"));
 
 //#region src/run.ts
+function run(parser, options = {}) {
+	return runImpl(parser, options);
+}
 /**
-* Runs a command-line parser with automatic process integration.
+* Runs a synchronous command-line parser with automatic process integration.
 *
-* This function provides a convenient high-level interface for parsing
-* command-line arguments in Node.js, Bun, and Deno environments. It
-* automatically handles `process.argv`, `process.exit()`, and terminal
-* output formatting, eliminating the need to manually pass these values
-* as the lower-level `run()` function (from `@optique/core/facade`) requires.
+* This is a type-safe version of {@link run} that only accepts sync parsers.
+* Use this when you know your parser is sync-only to get direct return values
+* without Promise wrappers.
 *
-* The function will automatically:
+* @template T The sync parser type being executed.
+* @param parser The synchronous command-line parser to execute.
+* @param options Configuration options for customizing behavior.
+* @returns The parsed result if successful.
+* @since 0.9.0
+*/
+function runSync(parser, options = {}) {
+	return runImpl(parser, options);
+}
+/**
+* Runs an asynchronous command-line parser with automatic process integration.
 *
-* - Extract arguments from `process.argv`
-* - Detect terminal capabilities for colors and width
-* - Exit the process with appropriate codes on help or error
-* - Format output according to terminal capabilities
+* This function accepts any parser (sync or async) and always returns a
+* Promise. Use this when working with parsers that may contain async
+* value parsers.
 *
 * @template T The parser type being executed.
 * @param parser The command-line parser to execute.
 * @param options Configuration options for customizing behavior.
-*                See {@link RunOptions} for available settings.
-* @returns The parsed result if successful. On help display or parse errors,
-*          the function will call `process.exit()` and not return.
-*
-* @example
-* ```typescript
-* import { object, option, run } from "@optique/run";
-* import { string, integer } from "@optique/core/valueparser";
-*
-* const parser = object({
-*   name: option("-n", "--name", string()),
-*   port: option("-p", "--port", integer()),
-* });
-*
-* // Automatically uses process.argv, handles errors/help, exits on completion
-* const config = run(parser);
-* console.log(`Starting server ${config.name} on port ${config.port}`);
-* ```
-*
-* @example
-* ```typescript
-* // With custom options
-* const result = run(parser, {
-*   programName: "myapp",
-*   help: "both",           // Enable both --help option and help command
-*   completion: "both",     // Enable both completion command and --completion option
-*   colors: true,           // Force colored output
-*   errorExitCode: 2,       // Exit with code 2 on errors
-* });
-* ```
-*
-* @example
-* ```typescript
-* // Shell completion usage
-* const result = run(parser, {
-*   completion: "both",
-* });
-*
-* // Users can then:
-* // myapp completion bash > ~/.bash_completion.d/myapp  # Generate script
-* // source ~/.bash_completion.d/myapp                   # Enable completion
-* // myapp --format=<TAB>                                # Use completion
-* ```
+* @returns A Promise of the parsed result if successful.
+* @since 0.9.0
 */
-function run(parser, options = {}) {
+function runAsync(parser, options = {}) {
+	const result = runImpl(parser, options);
+	return Promise.resolve(result);
+}
+function runImpl(parser, options = {}) {
 	const { programName = node_path.default.basename(node_process.default.argv[1] || "cli"), args = node_process.default.argv.slice(2), colors = node_process.default.stdout.isTTY, maxWidth = node_process.default.stdout.columns, showDefault, help, version, completion, aboveError = "usage", errorExitCode = 1, brief, description, footer } = options;
 	const helpConfig = help ? {
 		mode: help,
@@ -108,4 +81,6 @@ function run(parser, options = {}) {
 }
 
 //#endregion
-exports.run = run;
+exports.run = run;
+exports.runAsync = runAsync;
+exports.runSync = runSync;

package/dist/run.d.cts

@@ -1,5 +1,5 @@
 import { ShellCompletion } from "@optique/core/completion";
-import { InferValue, Parser } from "@optique/core/parser";
+import { InferMode, InferValue, Mode, ModeValue, Parser } from "@optique/core/parser";
 import { ShowDefaultOptions } from "@optique/core/doc";
 import { Message } from "@optique/core/message";
 
@@ -187,6 +187,36 @@ interface RunOptions {
  * // myapp --format=<TAB>                                # Use completion
  * ```
  */
-declare function run<T extends Parser<unknown, unknown>>(parser: T, options?: RunOptions): InferValue<T>;
+declare function run<T extends Parser<"sync", unknown, unknown>>(parser: T, options?: RunOptions): InferValue<T>;
+declare function run<T extends Parser<"async", unknown, unknown>>(parser: T, options?: RunOptions): Promise<InferValue<T>>;
+declare function run<T extends Parser<Mode, unknown, unknown>>(parser: T, options?: RunOptions): ModeValue<InferMode<T>, InferValue<T>>;
+/**
+ * Runs a synchronous command-line parser with automatic process integration.
+ *
+ * This is a type-safe version of {@link run} that only accepts sync parsers.
+ * Use this when you know your parser is sync-only to get direct return values
+ * without Promise wrappers.
+ *
+ * @template T The sync parser type being executed.
+ * @param parser The synchronous command-line parser to execute.
+ * @param options Configuration options for customizing behavior.
+ * @returns The parsed result if successful.
+ * @since 0.9.0
+ */
+declare function runSync<T extends Parser<"sync", unknown, unknown>>(parser: T, options?: RunOptions): InferValue<T>;
+/**
+ * Runs an asynchronous command-line parser with automatic process integration.
+ *
+ * This function accepts any parser (sync or async) and always returns a
+ * Promise. Use this when working with parsers that may contain async
+ * value parsers.
+ *
+ * @template T The parser type being executed.
+ * @param parser The command-line parser to execute.
+ * @param options Configuration options for customizing behavior.
+ * @returns A Promise of the parsed result if successful.
+ * @since 0.9.0
+ */
+declare function runAsync<T extends Parser<Mode, unknown, unknown>>(parser: T, options?: RunOptions): Promise<InferValue<T>>;
 //#endregion
-export { RunOptions, run };
+export { RunOptions, run, runAsync, runSync };

package/dist/run.d.ts

@@ -1,6 +1,6 @@
 import { Message } from "@optique/core/message";
 import { ShellCompletion } from "@optique/core/completion";
-import { InferValue, Parser } from "@optique/core/parser";
+import { InferMode, InferValue, Mode, ModeValue, Parser } from "@optique/core/parser";
 import { ShowDefaultOptions } from "@optique/core/doc";
 
 //#region src/run.d.ts
@@ -187,6 +187,36 @@ interface RunOptions {
  * // myapp --format=<TAB>                                # Use completion
  * ```
  */
-declare function run<T extends Parser<unknown, unknown>>(parser: T, options?: RunOptions): InferValue<T>;
+declare function run<T extends Parser<"sync", unknown, unknown>>(parser: T, options?: RunOptions): InferValue<T>;
+declare function run<T extends Parser<"async", unknown, unknown>>(parser: T, options?: RunOptions): Promise<InferValue<T>>;
+declare function run<T extends Parser<Mode, unknown, unknown>>(parser: T, options?: RunOptions): ModeValue<InferMode<T>, InferValue<T>>;
+/**
+ * Runs a synchronous command-line parser with automatic process integration.
+ *
+ * This is a type-safe version of {@link run} that only accepts sync parsers.
+ * Use this when you know your parser is sync-only to get direct return values
+ * without Promise wrappers.
+ *
+ * @template T The sync parser type being executed.
+ * @param parser The synchronous command-line parser to execute.
+ * @param options Configuration options for customizing behavior.
+ * @returns The parsed result if successful.
+ * @since 0.9.0
+ */
+declare function runSync<T extends Parser<"sync", unknown, unknown>>(parser: T, options?: RunOptions): InferValue<T>;
+/**
+ * Runs an asynchronous command-line parser with automatic process integration.
+ *
+ * This function accepts any parser (sync or async) and always returns a
+ * Promise. Use this when working with parsers that may contain async
+ * value parsers.
+ *
+ * @template T The parser type being executed.
+ * @param parser The command-line parser to execute.
+ * @param options Configuration options for customizing behavior.
+ * @returns A Promise of the parsed result if successful.
+ * @since 0.9.0
+ */
+declare function runAsync<T extends Parser<Mode, unknown, unknown>>(parser: T, options?: RunOptions): Promise<InferValue<T>>;
 //#endregion
-export { RunOptions, run };
+export { RunOptions, run, runAsync, runSync };

package/dist/run.js

@@ -3,70 +3,43 @@ import path from "node:path";
 import process from "node:process";
 
 //#region src/run.ts
+function run(parser, options = {}) {
+	return runImpl(parser, options);
+}
 /**
-* Runs a command-line parser with automatic process integration.
+* Runs a synchronous command-line parser with automatic process integration.
 *
-* This function provides a convenient high-level interface for parsing
-* command-line arguments in Node.js, Bun, and Deno environments. It
-* automatically handles `process.argv`, `process.exit()`, and terminal
-* output formatting, eliminating the need to manually pass these values
-* as the lower-level `run()` function (from `@optique/core/facade`) requires.
+* This is a type-safe version of {@link run} that only accepts sync parsers.
+* Use this when you know your parser is sync-only to get direct return values
+* without Promise wrappers.
 *
-* The function will automatically:
+* @template T The sync parser type being executed.
+* @param parser The synchronous command-line parser to execute.
+* @param options Configuration options for customizing behavior.
+* @returns The parsed result if successful.
+* @since 0.9.0
+*/
+function runSync(parser, options = {}) {
+	return runImpl(parser, options);
+}
+/**
+* Runs an asynchronous command-line parser with automatic process integration.
 *
-* - Extract arguments from `process.argv`
-* - Detect terminal capabilities for colors and width
-* - Exit the process with appropriate codes on help or error
-* - Format output according to terminal capabilities
+* This function accepts any parser (sync or async) and always returns a
+* Promise. Use this when working with parsers that may contain async
+* value parsers.
 *
 * @template T The parser type being executed.
 * @param parser The command-line parser to execute.
 * @param options Configuration options for customizing behavior.
-*                See {@link RunOptions} for available settings.
-* @returns The parsed result if successful. On help display or parse errors,
-*          the function will call `process.exit()` and not return.
-*
-* @example
-* ```typescript
-* import { object, option, run } from "@optique/run";
-* import { string, integer } from "@optique/core/valueparser";
-*
-* const parser = object({
-*   name: option("-n", "--name", string()),
-*   port: option("-p", "--port", integer()),
-* });
-*
-* // Automatically uses process.argv, handles errors/help, exits on completion
-* const config = run(parser);
-* console.log(`Starting server ${config.name} on port ${config.port}`);
-* ```
-*
-* @example
-* ```typescript
-* // With custom options
-* const result = run(parser, {
-*   programName: "myapp",
-*   help: "both",           // Enable both --help option and help command
-*   completion: "both",     // Enable both completion command and --completion option
-*   colors: true,           // Force colored output
-*   errorExitCode: 2,       // Exit with code 2 on errors
-* });
-* ```
-*
-* @example
-* ```typescript
-* // Shell completion usage
-* const result = run(parser, {
-*   completion: "both",
-* });
-*
-* // Users can then:
-* // myapp completion bash > ~/.bash_completion.d/myapp  # Generate script
-* // source ~/.bash_completion.d/myapp                   # Enable completion
-* // myapp --format=<TAB>                                # Use completion
-* ```
+* @returns A Promise of the parsed result if successful.
+* @since 0.9.0
 */
-function run(parser, options = {}) {
+function runAsync(parser, options = {}) {
+	const result = runImpl(parser, options);
+	return Promise.resolve(result);
+}
+function runImpl(parser, options = {}) {
 	const { programName = path.basename(process.argv[1] || "cli"), args = process.argv.slice(2), colors = process.stdout.isTTY, maxWidth = process.stdout.columns, showDefault, help, version, completion, aboveError = "usage", errorExitCode = 1, brief, description, footer } = options;
 	const helpConfig = help ? {
 		mode: help,
@@ -107,4 +80,4 @@ function run(parser, options = {}) {
 }
 
 //#endregion
-export { run };
+export { run, runAsync, runSync };

package/dist/valueparser.cjs

@@ -46,6 +46,7 @@ function path(options = {}) {
 	const mustExist = "mustExist" in options ? options.mustExist : false;
 	const mustNotExist = "mustNotExist" in options ? options.mustNotExist : false;
 	return {
+		$mode: "sync",
 		metavar,
 		parse(input) {
 			if (extensions && extensions.length > 0) {

package/dist/valueparser.d.cts

@@ -169,6 +169,6 @@ type PathOptions = PathOptionsMustExist | PathOptionsMustNotExist | PathOptionsN
  * }));
  * ```
  */
-declare function path(options?: PathOptions): ValueParser<string>;
+declare function path(options?: PathOptions): ValueParser<"sync", string>;
 //#endregion
 export { PathErrorOptions, PathOptions, PathOptionsBase, PathOptionsMustExist, PathOptionsMustNotExist, PathOptionsNoExistenceCheck, path };

package/dist/valueparser.d.ts

@@ -169,6 +169,6 @@ type PathOptions = PathOptionsMustExist | PathOptionsMustNotExist | PathOptionsN
  * }));
  * ```
  */
-declare function path(options?: PathOptions): ValueParser<string>;
+declare function path(options?: PathOptions): ValueParser<"sync", string>;
 //#endregion
 export { PathErrorOptions, PathOptions, PathOptionsBase, PathOptionsMustExist, PathOptionsMustNotExist, PathOptionsNoExistenceCheck, path };

package/dist/valueparser.js

@@ -45,6 +45,7 @@ function path(options = {}) {
 	const mustExist = "mustExist" in options ? options.mustExist : false;
 	const mustNotExist = "mustNotExist" in options ? options.mustNotExist : false;
 	return {
+		$mode: "sync",
 		metavar,
 		parse(input) {
 			if (extensions && extensions.length > 0) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/run",
-  "version": "0.9.0-dev.211+322b48ee",
+  "version": "0.9.0-dev.215+13b302c0",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",
@@ -70,7 +70,7 @@
   },
   "sideEffects": false,
   "dependencies": {
-    "@optique/core": "0.9.0-dev.211+322b48ee"
+    "@optique/core": "0.9.0-dev.215+13b302c0"
   },
   "devDependencies": {
     "@types/node": "^20.19.9",