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

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright 2025 Hong Minhee
+Copyright 2025–2026 Hong Minhee
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of
 this software and associated documentation files (the "Software"), to deal in

package/dist/index.cjs

@@ -6,6 +6,4 @@ 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.runAsync = require_run.runAsync;
-exports.runSync = require_run.runSync;
+exports.run = require_run.run;

package/dist/index.d.cts

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

package/dist/index.d.ts

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

package/dist/index.js

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

package/dist/run.cjs

@@ -4,43 +4,70 @@ 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 synchronous command-line parser with automatic process integration.
+* Runs a 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.
+* 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.
 *
-* @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.
+* The function will automatically:
 *
-* 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.
+* - 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
 *
 * @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
+*                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
+* ```
 */
-function runAsync(parser, options = {}) {
-	const result = runImpl(parser, options);
-	return Promise.resolve(result);
-}
-function runImpl(parser, options = {}) {
+function run(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,
@@ -81,6 +108,4 @@ function runImpl(parser, options = {}) {
 }
 
 //#endregion
-exports.run = run;
-exports.runAsync = runAsync;
-exports.runSync = runSync;
+exports.run = run;

package/dist/run.d.cts

@@ -1,5 +1,5 @@
 import { ShellCompletion } from "@optique/core/completion";
-import { InferMode, InferValue, Mode, ModeValue, Parser } from "@optique/core/parser";
+import { InferValue, Parser } from "@optique/core/parser";
 import { ShowDefaultOptions } from "@optique/core/doc";
 import { Message } from "@optique/core/message";
 
@@ -187,36 +187,6 @@ interface RunOptions {
  * // myapp --format=<TAB>                                # Use completion
  * ```
  */
-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>>;
+declare function run<T extends Parser<unknown, unknown>>(parser: T, options?: RunOptions): InferValue<T>;
 //#endregion
-export { RunOptions, run, runAsync, runSync };
+export { RunOptions, run };

package/dist/run.d.ts

@@ -1,6 +1,6 @@
 import { Message } from "@optique/core/message";
 import { ShellCompletion } from "@optique/core/completion";
-import { InferMode, InferValue, Mode, ModeValue, Parser } from "@optique/core/parser";
+import { InferValue, Parser } from "@optique/core/parser";
 import { ShowDefaultOptions } from "@optique/core/doc";
 
 //#region src/run.d.ts
@@ -187,36 +187,6 @@ interface RunOptions {
  * // myapp --format=<TAB>                                # Use completion
  * ```
  */
-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>>;
+declare function run<T extends Parser<unknown, unknown>>(parser: T, options?: RunOptions): InferValue<T>;
 //#endregion
-export { RunOptions, run, runAsync, runSync };
+export { RunOptions, run };

package/dist/run.js

@@ -3,43 +3,70 @@ import path from "node:path";
 import process from "node:process";
 
 //#region src/run.ts
-function run(parser, options = {}) {
-	return runImpl(parser, options);
-}
 /**
-* Runs a synchronous command-line parser with automatic process integration.
+* Runs a 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.
+* 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.
 *
-* @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.
+* The function will automatically:
 *
-* 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.
+* - 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
 *
 * @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
+*                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
+* ```
 */
-function runAsync(parser, options = {}) {
-	const result = runImpl(parser, options);
-	return Promise.resolve(result);
-}
-function runImpl(parser, options = {}) {
+function run(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,
@@ -80,4 +107,4 @@ function runImpl(parser, options = {}) {
 }
 
 //#endregion
-export { run, runAsync, runSync };
+export { run };

package/dist/valueparser.cjs

@@ -46,7 +46,6 @@ 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<"sync", string>;
+declare function path(options?: PathOptions): ValueParser<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<"sync", string>;
+declare function path(options?: PathOptions): ValueParser<string>;
 //#endregion
 export { PathErrorOptions, PathOptions, PathOptionsBase, PathOptionsMustExist, PathOptionsMustNotExist, PathOptionsNoExistenceCheck, path };

package/dist/valueparser.js

@@ -45,7 +45,6 @@ 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.206+78abd1b3",
+  "version": "0.9.0-dev.211+322b48ee",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",
@@ -70,7 +70,7 @@
   },
   "sideEffects": false,
   "dependencies": {
-    "@optique/core": "0.9.0-dev.206+78abd1b3"
+    "@optique/core": "0.9.0-dev.211+322b48ee"
   },
   "devDependencies": {
     "@types/node": "^20.19.9",