@optique/core 0.9.0-dev.224 → 0.9.0-dev.225

package/dist/valueparser.cjs

@@ -8,7 +8,7 @@ const require_nonempty = require('./nonempty.cjs');
 * @return `true` if the object is a {@link ValueParser}, `false` otherwise.
 */
 function isValueParser(object) {
-	return typeof object === "object" && object != null && "metavar" in object && typeof object.metavar === "string" && "parse" in object && typeof object.parse === "function" && "format" in object && typeof object.format === "function";
+	return typeof object === "object" && object != null && "$mode" in object && (object.$mode === "sync" || object.$mode === "async") && "metavar" in object && typeof object.metavar === "string" && "parse" in object && typeof object.parse === "function" && "format" in object && typeof object.format === "function";
 }
 /**
 * Implementation of the choice parser for both string and number types.
@@ -21,6 +21,7 @@ function choice(choices, options = {}) {
 		const numberChoices = choices;
 		const numberOptions = options;
 		return {
+			$mode: "sync",
 			metavar,
 			parse(input) {
 				const parsed = Number(input);
@@ -53,6 +54,7 @@ function choice(choices, options = {}) {
 	const stringOptions = options;
 	const normalizedValues = stringOptions.caseInsensitive ? stringChoices.map((v) => v.toLowerCase()) : stringChoices;
 	return {
+		$mode: "sync",
 		metavar,
 		parse(input) {
 			const normalizedInput = stringOptions.caseInsensitive ? input.toLowerCase() : input;
@@ -120,6 +122,7 @@ function string(options = {}) {
 	const metavar = options.metavar ?? "STRING";
 	require_nonempty.ensureNonEmptyString(metavar);
 	return {
+		$mode: "sync",
 		metavar,
 		parse(input) {
 			if (options.pattern != null && !options.pattern.test(input)) return {
@@ -174,6 +177,7 @@ function integer(options) {
 		const metavar$1 = options.metavar ?? "INTEGER";
 		require_nonempty.ensureNonEmptyString(metavar$1);
 		return {
+			$mode: "sync",
 			metavar: metavar$1,
 			parse(input) {
 				let value;
@@ -207,6 +211,7 @@ function integer(options) {
 	const metavar = options?.metavar ?? "INTEGER";
 	require_nonempty.ensureNonEmptyString(metavar);
 	return {
+		$mode: "sync",
 		metavar,
 		parse(input) {
 			if (!input.match(/^-?\d+$/)) return {
@@ -246,6 +251,7 @@ function float(options = {}) {
 	const metavar = options.metavar ?? "NUMBER";
 	require_nonempty.ensureNonEmptyString(metavar);
 	return {
+		$mode: "sync",
 		metavar,
 		parse(input) {
 			let value;
@@ -295,6 +301,7 @@ function url(options = {}) {
 	const metavar = options.metavar ?? "URL";
 	require_nonempty.ensureNonEmptyString(metavar);
 	return {
+		$mode: "sync",
 		metavar,
 		parse(input) {
 			if (!URL.canParse(input)) return {
@@ -339,6 +346,7 @@ function locale(options = {}) {
 	const metavar = options.metavar ?? "LOCALE";
 	require_nonempty.ensureNonEmptyString(metavar);
 	return {
+		$mode: "sync",
 		metavar,
 		parse(input) {
 			let locale$1;
@@ -608,6 +616,7 @@ function uuid(options = {}) {
 	const metavar = options.metavar ?? "UUID";
 	require_nonempty.ensureNonEmptyString(metavar);
 	return {
+		$mode: "sync",
 		metavar,
 		parse(input) {
 			if (!uuidRegex.test(input)) return {

package/dist/valueparser.d.cts

@@ -1,6 +1,6 @@
 import { NonEmptyString, ensureNonEmptyString, isNonEmptyString } from "./nonempty.cjs";
 import { Message } from "./message.cjs";
-import { Suggestion } from "./parser.cjs";
+import { Mode, ModeIterable, ModeValue, Suggestion } from "./parser.cjs";
 
 //#region src/valueparser.d.ts
 
@@ -10,9 +10,20 @@ import { Suggestion } from "./parser.cjs";
  * A `ValueParser` is responsible for converting string input (typically from
  * CLI arguments or option values) into strongly-typed values of type {@link T}.
  *
+ * @template M The execution mode of the parser (`"sync"` or `"async"`).
  * @template T The type of value this parser produces.
+ * @since 0.9.0 Added the `M` type parameter for sync/async mode support.
  */
-interface ValueParser<T> {
+interface ValueParser<M extends Mode = "sync", T = unknown> {
+  /**
+   * The execution mode of this value parser.
+   *
+   * - `"sync"`: The `parse` method returns values directly.
+   * - `"async"`: The `parse` method returns Promises.
+   *
+   * @since 0.9.0
+   */
+  readonly $mode: M;
   /**
    * The metavariable name for this parser.  Used in help messages
    * to indicate what kind of value this parser expects.  Usually
@@ -25,9 +36,10 @@ interface ValueParser<T> {
    * @param input The string input to parse
    *              (e.g., the `value` part of `--option=value`).
    * @returns A result object indicating success or failure with an error
-   *          message.
+   *          message.  In async mode, returns a Promise that resolves to
+   *          the result.
    */
-  parse(input: string): ValueParserResult<T>;
+  parse(input: string): ModeValue<M, ValueParserResult<T>>;
   /**
    * Formats a value of type {@link T} into a string representation.
    * This is useful for displaying the value in help messages or
@@ -43,9 +55,10 @@ interface ValueParser<T> {
    *
    * @param prefix The current input prefix to complete.
    * @returns An iterable of suggestion objects.
+   *          In async mode, returns an AsyncIterable.
    * @since 0.6.0
    */
-  suggest?(prefix: string): Iterable<Suggestion>;
+  suggest?(prefix: string): ModeIterable<M, Suggestion>;
 }
 /**
  * Result type returned by {@link ValueParser#parse}.
@@ -171,7 +184,7 @@ type ChoiceOptions = ChoiceOptionsString;
  * @param object The object to check.
  * @return `true` if the object is a {@link ValueParser}, `false` otherwise.
  */
-declare function isValueParser<T>(object: unknown): object is ValueParser<T>;
+declare function isValueParser<M extends Mode, T>(object: unknown): object is ValueParser<M, T>;
 /**
  * Creates a {@link ValueParser} that accepts one of multiple
  * string values, so-called enumerated values.
@@ -184,7 +197,7 @@ declare function isValueParser<T>(object: unknown): object is ValueParser<T>;
  * @returns A {@link ValueParser} that checks if the input matches one of the
  *          specified values.
  */
-declare function choice<const T extends string>(choices: readonly T[], options?: ChoiceOptionsString): ValueParser<T>;
+declare function choice<const T extends string>(choices: readonly T[], options?: ChoiceOptionsString): ValueParser<"sync", T>;
 /**
  * Creates a {@link ValueParser} that accepts one of multiple
  * number values.
@@ -198,7 +211,7 @@ declare function choice<const T extends string>(choices: readonly T[], options?:
  *          specified values.
  * @since 0.9.0
  */
-declare function choice<const T extends number>(choices: readonly T[], options?: ChoiceOptionsNumber): ValueParser<T>;
+declare function choice<const T extends number>(choices: readonly T[], options?: ChoiceOptionsNumber): ValueParser<"sync", T>;
 /**
  * Creates a {@link ValueParser} for strings.
  *
@@ -213,7 +226,7 @@ declare function choice<const T extends number>(choices: readonly T[], options?:
  * @returns A {@link ValueParser} that parses strings according to the
  *          specified options.
  */
-declare function string(options?: StringOptions): ValueParser<string>;
+declare function string(options?: StringOptions): ValueParser<"sync", string>;
 /**
  * Options for creating an integer parser that returns a JavaScript `number`.
  *
@@ -325,14 +338,14 @@ interface IntegerOptionsBigInt {
  * @param options Configuration options for the integer parser.
  * @returns A {@link ValueParser} that parses strings into numbers.
  */
-declare function integer(options?: IntegerOptionsNumber): ValueParser<number>;
+declare function integer(options?: IntegerOptionsNumber): ValueParser<"sync", number>;
 /**
  * Creates a ValueParser for integers that returns `bigint` values.
  *
  * @param options Configuration options for the `bigint` parser.
  * @returns A {@link ValueParser} that parses strings into `bigint` values.
  */
-declare function integer(options: IntegerOptionsBigInt): ValueParser<bigint>;
+declare function integer(options: IntegerOptionsBigInt): ValueParser<"sync", bigint>;
 /**
  * Options for creating a {@link float} parser.
  */
@@ -402,7 +415,7 @@ interface FloatOptions {
  * @returns A {@link ValueParser} that parses strings into floating-point
  *          numbers.
  */
-declare function float(options?: FloatOptions): ValueParser<number>;
+declare function float(options?: FloatOptions): ValueParser<"sync", number>;
 /**
  * Options for creating a {@link url} parser.
  */
@@ -449,7 +462,7 @@ interface UrlOptions {
  * @param options Configuration options for the URL parser.
  * @returns A {@link ValueParser} that converts string input to `URL` objects.
  */
-declare function url(options?: UrlOptions): ValueParser<URL>;
+declare function url(options?: UrlOptions): ValueParser<"sync", URL>;
 /**
  * Options for creating a {@link locale} parser.
  */
@@ -484,7 +497,7 @@ interface LocaleOptions {
  * @returns A {@link ValueParser} that converts string input to `Intl.Locale`
  *          objects.
  */
-declare function locale(options?: LocaleOptions): ValueParser<Intl.Locale>;
+declare function locale(options?: LocaleOptions): ValueParser<"sync", Intl.Locale>;
 /**
  * Type representing a UUID string.
  *
@@ -541,6 +554,6 @@ interface UuidOptions {
  * @returns A {@link ValueParser} that converts string input to {@link Uuid}
  *          strings.
  */
-declare function uuid(options?: UuidOptions): ValueParser<Uuid>;
+declare function uuid(options?: UuidOptions): ValueParser<"sync", Uuid>;
 //#endregion
-export { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, FloatOptions, IntegerOptionsBigInt, IntegerOptionsNumber, LocaleOptions, type NonEmptyString, StringOptions, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, choice, ensureNonEmptyString, float, integer, isNonEmptyString, isValueParser, locale, string, url, uuid };
+export { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, FloatOptions, IntegerOptionsBigInt, IntegerOptionsNumber, LocaleOptions, type Mode, type ModeIterable, type ModeValue, type NonEmptyString, StringOptions, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, choice, ensureNonEmptyString, float, integer, isNonEmptyString, isValueParser, locale, string, url, uuid };

package/dist/valueparser.d.ts

@@ -1,6 +1,6 @@
 import { NonEmptyString, ensureNonEmptyString, isNonEmptyString } from "./nonempty.js";
 import { Message } from "./message.js";
-import { Suggestion } from "./parser.js";
+import { Mode, ModeIterable, ModeValue, Suggestion } from "./parser.js";
 
 //#region src/valueparser.d.ts
 
@@ -10,9 +10,20 @@ import { Suggestion } from "./parser.js";
  * A `ValueParser` is responsible for converting string input (typically from
  * CLI arguments or option values) into strongly-typed values of type {@link T}.
  *
+ * @template M The execution mode of the parser (`"sync"` or `"async"`).
  * @template T The type of value this parser produces.
+ * @since 0.9.0 Added the `M` type parameter for sync/async mode support.
  */
-interface ValueParser<T> {
+interface ValueParser<M extends Mode = "sync", T = unknown> {
+  /**
+   * The execution mode of this value parser.
+   *
+   * - `"sync"`: The `parse` method returns values directly.
+   * - `"async"`: The `parse` method returns Promises.
+   *
+   * @since 0.9.0
+   */
+  readonly $mode: M;
   /**
    * The metavariable name for this parser.  Used in help messages
    * to indicate what kind of value this parser expects.  Usually
@@ -25,9 +36,10 @@ interface ValueParser<T> {
    * @param input The string input to parse
    *              (e.g., the `value` part of `--option=value`).
    * @returns A result object indicating success or failure with an error
-   *          message.
+   *          message.  In async mode, returns a Promise that resolves to
+   *          the result.
    */
-  parse(input: string): ValueParserResult<T>;
+  parse(input: string): ModeValue<M, ValueParserResult<T>>;
   /**
    * Formats a value of type {@link T} into a string representation.
    * This is useful for displaying the value in help messages or
@@ -43,9 +55,10 @@ interface ValueParser<T> {
    *
    * @param prefix The current input prefix to complete.
    * @returns An iterable of suggestion objects.
+   *          In async mode, returns an AsyncIterable.
    * @since 0.6.0
    */
-  suggest?(prefix: string): Iterable<Suggestion>;
+  suggest?(prefix: string): ModeIterable<M, Suggestion>;
 }
 /**
  * Result type returned by {@link ValueParser#parse}.
@@ -171,7 +184,7 @@ type ChoiceOptions = ChoiceOptionsString;
  * @param object The object to check.
  * @return `true` if the object is a {@link ValueParser}, `false` otherwise.
  */
-declare function isValueParser<T>(object: unknown): object is ValueParser<T>;
+declare function isValueParser<M extends Mode, T>(object: unknown): object is ValueParser<M, T>;
 /**
  * Creates a {@link ValueParser} that accepts one of multiple
  * string values, so-called enumerated values.
@@ -184,7 +197,7 @@ declare function isValueParser<T>(object: unknown): object is ValueParser<T>;
  * @returns A {@link ValueParser} that checks if the input matches one of the
  *          specified values.
  */
-declare function choice<const T extends string>(choices: readonly T[], options?: ChoiceOptionsString): ValueParser<T>;
+declare function choice<const T extends string>(choices: readonly T[], options?: ChoiceOptionsString): ValueParser<"sync", T>;
 /**
  * Creates a {@link ValueParser} that accepts one of multiple
  * number values.
@@ -198,7 +211,7 @@ declare function choice<const T extends string>(choices: readonly T[], options?:
  *          specified values.
  * @since 0.9.0
  */
-declare function choice<const T extends number>(choices: readonly T[], options?: ChoiceOptionsNumber): ValueParser<T>;
+declare function choice<const T extends number>(choices: readonly T[], options?: ChoiceOptionsNumber): ValueParser<"sync", T>;
 /**
  * Creates a {@link ValueParser} for strings.
  *
@@ -213,7 +226,7 @@ declare function choice<const T extends number>(choices: readonly T[], options?:
  * @returns A {@link ValueParser} that parses strings according to the
  *          specified options.
  */
-declare function string(options?: StringOptions): ValueParser<string>;
+declare function string(options?: StringOptions): ValueParser<"sync", string>;
 /**
  * Options for creating an integer parser that returns a JavaScript `number`.
  *
@@ -325,14 +338,14 @@ interface IntegerOptionsBigInt {
  * @param options Configuration options for the integer parser.
  * @returns A {@link ValueParser} that parses strings into numbers.
  */
-declare function integer(options?: IntegerOptionsNumber): ValueParser<number>;
+declare function integer(options?: IntegerOptionsNumber): ValueParser<"sync", number>;
 /**
  * Creates a ValueParser for integers that returns `bigint` values.
  *
  * @param options Configuration options for the `bigint` parser.
  * @returns A {@link ValueParser} that parses strings into `bigint` values.
  */
-declare function integer(options: IntegerOptionsBigInt): ValueParser<bigint>;
+declare function integer(options: IntegerOptionsBigInt): ValueParser<"sync", bigint>;
 /**
  * Options for creating a {@link float} parser.
  */
@@ -402,7 +415,7 @@ interface FloatOptions {
  * @returns A {@link ValueParser} that parses strings into floating-point
  *          numbers.
  */
-declare function float(options?: FloatOptions): ValueParser<number>;
+declare function float(options?: FloatOptions): ValueParser<"sync", number>;
 /**
  * Options for creating a {@link url} parser.
  */
@@ -449,7 +462,7 @@ interface UrlOptions {
  * @param options Configuration options for the URL parser.
  * @returns A {@link ValueParser} that converts string input to `URL` objects.
  */
-declare function url(options?: UrlOptions): ValueParser<URL>;
+declare function url(options?: UrlOptions): ValueParser<"sync", URL>;
 /**
  * Options for creating a {@link locale} parser.
  */
@@ -484,7 +497,7 @@ interface LocaleOptions {
  * @returns A {@link ValueParser} that converts string input to `Intl.Locale`
  *          objects.
  */
-declare function locale(options?: LocaleOptions): ValueParser<Intl.Locale>;
+declare function locale(options?: LocaleOptions): ValueParser<"sync", Intl.Locale>;
 /**
  * Type representing a UUID string.
  *
@@ -541,6 +554,6 @@ interface UuidOptions {
  * @returns A {@link ValueParser} that converts string input to {@link Uuid}
  *          strings.
  */
-declare function uuid(options?: UuidOptions): ValueParser<Uuid>;
+declare function uuid(options?: UuidOptions): ValueParser<"sync", Uuid>;
 //#endregion
-export { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, FloatOptions, IntegerOptionsBigInt, IntegerOptionsNumber, LocaleOptions, type NonEmptyString, StringOptions, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, choice, ensureNonEmptyString, float, integer, isNonEmptyString, isValueParser, locale, string, url, uuid };
+export { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, FloatOptions, IntegerOptionsBigInt, IntegerOptionsNumber, LocaleOptions, type Mode, type ModeIterable, type ModeValue, type NonEmptyString, StringOptions, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, choice, ensureNonEmptyString, float, integer, isNonEmptyString, isValueParser, locale, string, url, uuid };

package/dist/valueparser.js

@@ -8,7 +8,7 @@ import { ensureNonEmptyString, isNonEmptyString } from "./nonempty.js";
 * @return `true` if the object is a {@link ValueParser}, `false` otherwise.
 */
 function isValueParser(object) {
-	return typeof object === "object" && object != null && "metavar" in object && typeof object.metavar === "string" && "parse" in object && typeof object.parse === "function" && "format" in object && typeof object.format === "function";
+	return typeof object === "object" && object != null && "$mode" in object && (object.$mode === "sync" || object.$mode === "async") && "metavar" in object && typeof object.metavar === "string" && "parse" in object && typeof object.parse === "function" && "format" in object && typeof object.format === "function";
 }
 /**
 * Implementation of the choice parser for both string and number types.
@@ -21,6 +21,7 @@ function choice(choices, options = {}) {
 		const numberChoices = choices;
 		const numberOptions = options;
 		return {
+			$mode: "sync",
 			metavar,
 			parse(input) {
 				const parsed = Number(input);
@@ -53,6 +54,7 @@ function choice(choices, options = {}) {
 	const stringOptions = options;
 	const normalizedValues = stringOptions.caseInsensitive ? stringChoices.map((v) => v.toLowerCase()) : stringChoices;
 	return {
+		$mode: "sync",
 		metavar,
 		parse(input) {
 			const normalizedInput = stringOptions.caseInsensitive ? input.toLowerCase() : input;
@@ -120,6 +122,7 @@ function string(options = {}) {
 	const metavar = options.metavar ?? "STRING";
 	ensureNonEmptyString(metavar);
 	return {
+		$mode: "sync",
 		metavar,
 		parse(input) {
 			if (options.pattern != null && !options.pattern.test(input)) return {
@@ -174,6 +177,7 @@ function integer(options) {
 		const metavar$1 = options.metavar ?? "INTEGER";
 		ensureNonEmptyString(metavar$1);
 		return {
+			$mode: "sync",
 			metavar: metavar$1,
 			parse(input) {
 				let value;
@@ -207,6 +211,7 @@ function integer(options) {
 	const metavar = options?.metavar ?? "INTEGER";
 	ensureNonEmptyString(metavar);
 	return {
+		$mode: "sync",
 		metavar,
 		parse(input) {
 			if (!input.match(/^-?\d+$/)) return {
@@ -246,6 +251,7 @@ function float(options = {}) {
 	const metavar = options.metavar ?? "NUMBER";
 	ensureNonEmptyString(metavar);
 	return {
+		$mode: "sync",
 		metavar,
 		parse(input) {
 			let value;
@@ -295,6 +301,7 @@ function url(options = {}) {
 	const metavar = options.metavar ?? "URL";
 	ensureNonEmptyString(metavar);
 	return {
+		$mode: "sync",
 		metavar,
 		parse(input) {
 			if (!URL.canParse(input)) return {
@@ -339,6 +346,7 @@ function locale(options = {}) {
 	const metavar = options.metavar ?? "LOCALE";
 	ensureNonEmptyString(metavar);
 	return {
+		$mode: "sync",
 		metavar,
 		parse(input) {
 			let locale$1;
@@ -608,6 +616,7 @@ function uuid(options = {}) {
 	const metavar = options.metavar ?? "UUID";
 	ensureNonEmptyString(metavar);
 	return {
+		$mode: "sync",
 		metavar,
 		parse(input) {
 			if (!uuidRegex.test(input)) return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "0.9.0-dev.224+d01487f2",
+  "version": "0.9.0-dev.225+82a6f132",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",