@optique/core 0.1.0-dev.1

package/dist/valueparser.d.cts

@@ -0,0 +1,332 @@
+import { Message } from "./message.cjs";
+
+//#region src/valueparser.d.ts
+
+/**
+ * Interface for parsing CLI option values and arguments.
+ *
+ * A `ValueParser` is responsible for converting string input (typically from
+ * CLI arguments or option values) into strongly-typed values of type {@link T}.
+ *
+ * @template T The type of value this parser produces.
+ */
+interface ValueParser<T> {
+  /**
+   * The metavariable name for this parser.  Used in help messages
+   * to indicate what kind of value this parser expects.  Usually
+   * a single word in uppercase, like `PORT` or `FILE`.
+   */
+  readonly metavar: string;
+  /**
+   * Parses a string input into a value of type {@link 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.
+   */
+  parse(input: string): ValueParserResult<T>;
+  /**
+   * Formats a value of type {@link T} into a string representation.
+   * This is useful for displaying the value in help messages or
+   * documentation.
+   *
+   * @param value The value to format.
+   * @returns A string representation of the value.
+   */
+  format(value: T): string;
+}
+/**
+ * Result type returned by {@link ValueParser#parse}.
+ *
+ * This is a discriminated union that represents either a successful parse
+ * with the resulting value, or a failed parse with an error message.
+ *
+ * @template T The type of the successfully parsed value.
+ */
+type ValueParserResult<T> = {
+  /** Indicates that the parsing operation was successful. */
+  readonly success: true;
+  /** The successfully parsed value of type {@link T}. */
+  readonly value: T;
+} | {
+  /** Indicates that the parsing operation failed. */
+  readonly success: false;
+  /** The error message describing why the parsing failed. */
+  readonly error: Message;
+};
+/**
+ * Options for creating a string parser.
+ */
+interface StringOptions {
+  /**
+   * The metavariable name for this parser.  This is used in help messages to
+   * indicate what kind of value this parser expects.  Usually a single
+   * word in uppercase, like `HOST` or `NAME`.
+   * @default `"STRING"`
+   */
+  readonly metavar?: string;
+  /**
+   * Optional regular expression pattern that the string must match.
+   */
+  readonly pattern?: RegExp;
+}
+/**
+ * Options for creating a {@link choice} parser.
+ */
+interface ChoiceOptions {
+  /**
+   * The metavariable name for this parser.  This is used in help messages to
+   * indicate what kind of value this parser expects.  Usually a single
+   * word in uppercase, like `TYPE` or `MODE`.
+   * @default `"TYPE"`
+   */
+  readonly metavar?: string;
+  /**
+   * If `true`, the parser will perform case-insensitive matching
+   * against the enumerated values. This means that input like "value",
+   * "Value", or "VALUE" will all match the same enumerated value.
+   * If `false`, the matching will be case-sensitive.
+   * @default `false`
+   */
+  readonly caseInsensitive?: boolean;
+}
+/**
+ * A predicate function that checks if an object is a {@link ValueParser}.
+ * @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>;
+/**
+ * Creates a {@link ValueParser} that accepts one of multiple
+ * string values, so-called enumerated values.
+ *
+ * This parser validates that the input string matches one of
+ * the specified values. If the input does not match any of the values,
+ * it returns an error message indicating the valid options.
+ * @param values An array of valid string values that this parser can accept.
+ * @param options Configuration options for the choice parser.
+ * @returns A {@link ValueParser} that checks if the input matches one of the
+ *          specified values.
+ */
+declare function choice<const T extends string>(values: readonly T[], options?: ChoiceOptions): ValueParser<T>;
+/**
+ * Creates a {@link ValueParser} for strings.
+ *
+ * This parser validates that the input is a string and optionally checks
+ * if it matches a specified regular expression pattern.
+ * @param options Configuration options for the string parser.
+ * @returns A {@link ValueParser} that parses strings according to the
+ *          specified options.
+ */
+declare function string(options?: StringOptions): ValueParser<string>;
+/**
+ * Options for creating an integer parser that returns a JavaScript `number`.
+ *
+ * This interface is used when you want to parse integers as regular JavaScript
+ * numbers (which are safe up to `Number.MAX_SAFE_INTEGER`).
+ */
+interface IntegerOptionsNumber {
+  /**
+   * The type of integer to parse.
+   * @default `"number"`
+   */
+  readonly type?: "number";
+  /**
+   * The metavariable name for this parser.  This is used in help messages to
+   * indicate what kind of value this parser expects.  Usually a single
+   * word in uppercase, like `PORT`.
+   * @default `"INTEGER"`
+   */
+  readonly metavar?: string;
+  /**
+   * Minimum allowed value (inclusive). If not specified,
+   * no minimum is enforced.
+   */
+  readonly min?: number;
+  /**
+   * Maximum allowed value (inclusive). If not specified,
+   * no maximum is enforced.
+   */
+  readonly max?: number;
+}
+/**
+ * Options for creating an integer parser that returns a `bigint`.
+ *
+ * This interface is used when you need to parse very large integers that
+ * exceed JavaScript's safe integer range.
+ */
+interface IntegerOptionsBigInt {
+  /** Must be set to `"bigint"` to create a `bigint` parser. */
+  readonly type: "bigint";
+  /**
+   * The metavariable name for this parser.  This is used in help messages to
+   * indicate what kind of value this parser expects.  Usually a single
+   * word in uppercase, like `PORT`.
+   * @default `"INTEGER"`
+   */
+  readonly metavar?: string;
+  /**
+   * Minimum allowed value (inclusive). If not specified,
+   * no minimum is enforced.
+   */
+  readonly min?: bigint;
+  /**
+   * Maximum allowed value (inclusive). If not specified,
+   * no maximum is enforced.
+   */
+  readonly max?: bigint;
+}
+/**
+ * Creates a ValueParser for integers that returns JavaScript numbers.
+ *
+ * @param options Configuration options for the integer parser.
+ * @returns A {@link ValueParser} that parses strings into numbers.
+ */
+declare function integer(options?: IntegerOptionsNumber): ValueParser<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>;
+/**
+ * Options for creating a {@link float} parser.
+ */
+interface FloatOptions {
+  /**
+   * The metavariable name for this parser.  This is used in help messages to
+   * indicate what kind of value this parser expects.  Usually a single
+   * word in uppercase, like `RATE` or `PRICE`.
+   * @default `"NUMBER"`
+   */
+  readonly metavar?: string;
+  /**
+   * Minimum allowed value (inclusive). If not specified,
+   * no minimum is enforced.
+   */
+  readonly min?: number;
+  /**
+   * Maximum allowed value (inclusive). If not specified,
+   * no maximum is enforced.
+   */
+  readonly max?: number;
+  /**
+   * If `true`, allows the special value `NaN` (not a number).
+   * This is useful for cases where `NaN` is a valid input,
+   * such as in some scientific calculations.
+   * @default `false`
+   */
+  readonly allowNaN?: boolean;
+  /**
+   * If `true`, allows the special values `Infinity` and `-Infinity`.
+   * This is useful for cases where infinite values are valid inputs,
+   * such as in mathematical calculations or limits.
+   * @default `false`
+   */
+  readonly allowInfinity?: boolean;
+}
+/**
+ * Creates a {@link ValueParser} for floating-point numbers.
+ *
+ * This parser validates that the input is a valid floating-point number
+ * and optionally enforces minimum and maximum value constraints.
+ * @param options Configuration options for the float parser.
+ * @returns A {@link ValueParser} that parses strings into floating-point
+ *          numbers.
+ */
+declare function float(options?: FloatOptions): ValueParser<number>;
+/**
+ * Options for creating a {@link url} parser.
+ */
+interface UrlOptions {
+  /**
+   * The metavariable name for this parser.  This is used in help messages to
+   * indicate what kind of value this parser expects.  Usually a single
+   * word in uppercase, like `URL` or `ENDPOINT`.
+   * @default `"URL"`
+   */
+  readonly metavar?: string;
+  /**
+   * List of allowed URL protocols (e.g., `["http:", "https:"]`).
+   * If specified, the parsed URL must use one of these protocols.
+   * Protocol names should include the trailing colon (e.g., `"https:"`).
+   * If not specified, any protocol is allowed.
+   */
+  readonly allowedProtocols?: readonly string[];
+}
+/**
+ * Creates a {@link ValueParser} for URL values.
+ *
+ * This parser validates that the input is a well-formed URL and optionally
+ * restricts the allowed protocols. The parsed result is a JavaScript `URL`
+ * object.
+ * @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>;
+/**
+ * Options for creating a {@link locale} parser.
+ */
+interface LocaleOptions {
+  /**
+   * The metavariable name for this parser.  This is used in help messages to
+   * indicate what kind of value this parser expects.  Usually a single
+   * word in uppercase, like `LOCALE` or `LANG`.
+   * @default `"LOCALE"`
+   */
+  readonly metavar?: string;
+}
+/**
+ * Creates a {@link ValueParser} for locale values.
+ *
+ * This parser validates that the input is a well-formed locale identifier
+ * according to the Unicode Locale Identifier standard (BCP 47).
+ * The parsed result is a JavaScript `Intl.Locale` object.
+ * @param options Configuration options for the locale parser.
+ * @returns A {@link ValueParser} that converts string input to `Intl.Locale`
+ *          objects.
+ */
+declare function locale(options?: LocaleOptions): ValueParser<Intl.Locale>;
+/**
+ * Type representing a UUID string.
+ *
+ * A UUID is a 36-character string in the format:
+ * `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`
+ * where each `x` is a hexadecimal digit.
+ */
+type Uuid = `${string}-${string}-${string}-${string}-${string}`;
+/**
+ * Options for creating a {@link uuid} parser.
+ */
+interface UuidOptions {
+  /**
+   * The metavariable name for this parser.  This is used in help messages to
+   * indicate what kind of value this parser expects.  Usually a single
+   * word in uppercase, like `UUID` or `ID`.
+   * @default `"UUID"`
+   */
+  readonly metavar?: string;
+  /**
+   * List of allowed UUID versions (e.g., `[4, 5]` for UUIDs version 4 and 5).
+   * If specified, the parser will validate that the UUID matches one of the
+   * allowed versions. If not specified, any valid UUID format is accepted.
+   */
+  readonly allowedVersions?: readonly number[];
+}
+/**
+ * Creates a {@link ValueParser} for UUID values.
+ *
+ * This parser validates that the input is a well-formed UUID string in the
+ * standard format: `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` where each `x`
+ * is a hexadecimal digit.  The parser can optionally restrict to specific
+ * UUID versions.
+ *
+ * @param options Configuration options for the UUID parser.
+ * @returns A {@link ValueParser} that converts string input to {@link Uuid}
+ *          strings.
+ */
+declare function uuid(options?: UuidOptions): ValueParser<Uuid>;
+//#endregion
+export { ChoiceOptions, FloatOptions, IntegerOptionsBigInt, IntegerOptionsNumber, LocaleOptions, StringOptions, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, choice, float, integer, isValueParser, locale, string, url, uuid };

package/dist/valueparser.d.ts

@@ -0,0 +1,332 @@
+import { Message } from "./message.js";
+
+//#region src/valueparser.d.ts
+
+/**
+ * Interface for parsing CLI option values and arguments.
+ *
+ * A `ValueParser` is responsible for converting string input (typically from
+ * CLI arguments or option values) into strongly-typed values of type {@link T}.
+ *
+ * @template T The type of value this parser produces.
+ */
+interface ValueParser<T> {
+  /**
+   * The metavariable name for this parser.  Used in help messages
+   * to indicate what kind of value this parser expects.  Usually
+   * a single word in uppercase, like `PORT` or `FILE`.
+   */
+  readonly metavar: string;
+  /**
+   * Parses a string input into a value of type {@link 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.
+   */
+  parse(input: string): ValueParserResult<T>;
+  /**
+   * Formats a value of type {@link T} into a string representation.
+   * This is useful for displaying the value in help messages or
+   * documentation.
+   *
+   * @param value The value to format.
+   * @returns A string representation of the value.
+   */
+  format(value: T): string;
+}
+/**
+ * Result type returned by {@link ValueParser#parse}.
+ *
+ * This is a discriminated union that represents either a successful parse
+ * with the resulting value, or a failed parse with an error message.
+ *
+ * @template T The type of the successfully parsed value.
+ */
+type ValueParserResult<T> = {
+  /** Indicates that the parsing operation was successful. */
+  readonly success: true;
+  /** The successfully parsed value of type {@link T}. */
+  readonly value: T;
+} | {
+  /** Indicates that the parsing operation failed. */
+  readonly success: false;
+  /** The error message describing why the parsing failed. */
+  readonly error: Message;
+};
+/**
+ * Options for creating a string parser.
+ */
+interface StringOptions {
+  /**
+   * The metavariable name for this parser.  This is used in help messages to
+   * indicate what kind of value this parser expects.  Usually a single
+   * word in uppercase, like `HOST` or `NAME`.
+   * @default `"STRING"`
+   */
+  readonly metavar?: string;
+  /**
+   * Optional regular expression pattern that the string must match.
+   */
+  readonly pattern?: RegExp;
+}
+/**
+ * Options for creating a {@link choice} parser.
+ */
+interface ChoiceOptions {
+  /**
+   * The metavariable name for this parser.  This is used in help messages to
+   * indicate what kind of value this parser expects.  Usually a single
+   * word in uppercase, like `TYPE` or `MODE`.
+   * @default `"TYPE"`
+   */
+  readonly metavar?: string;
+  /**
+   * If `true`, the parser will perform case-insensitive matching
+   * against the enumerated values. This means that input like "value",
+   * "Value", or "VALUE" will all match the same enumerated value.
+   * If `false`, the matching will be case-sensitive.
+   * @default `false`
+   */
+  readonly caseInsensitive?: boolean;
+}
+/**
+ * A predicate function that checks if an object is a {@link ValueParser}.
+ * @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>;
+/**
+ * Creates a {@link ValueParser} that accepts one of multiple
+ * string values, so-called enumerated values.
+ *
+ * This parser validates that the input string matches one of
+ * the specified values. If the input does not match any of the values,
+ * it returns an error message indicating the valid options.
+ * @param values An array of valid string values that this parser can accept.
+ * @param options Configuration options for the choice parser.
+ * @returns A {@link ValueParser} that checks if the input matches one of the
+ *          specified values.
+ */
+declare function choice<const T extends string>(values: readonly T[], options?: ChoiceOptions): ValueParser<T>;
+/**
+ * Creates a {@link ValueParser} for strings.
+ *
+ * This parser validates that the input is a string and optionally checks
+ * if it matches a specified regular expression pattern.
+ * @param options Configuration options for the string parser.
+ * @returns A {@link ValueParser} that parses strings according to the
+ *          specified options.
+ */
+declare function string(options?: StringOptions): ValueParser<string>;
+/**
+ * Options for creating an integer parser that returns a JavaScript `number`.
+ *
+ * This interface is used when you want to parse integers as regular JavaScript
+ * numbers (which are safe up to `Number.MAX_SAFE_INTEGER`).
+ */
+interface IntegerOptionsNumber {
+  /**
+   * The type of integer to parse.
+   * @default `"number"`
+   */
+  readonly type?: "number";
+  /**
+   * The metavariable name for this parser.  This is used in help messages to
+   * indicate what kind of value this parser expects.  Usually a single
+   * word in uppercase, like `PORT`.
+   * @default `"INTEGER"`
+   */
+  readonly metavar?: string;
+  /**
+   * Minimum allowed value (inclusive). If not specified,
+   * no minimum is enforced.
+   */
+  readonly min?: number;
+  /**
+   * Maximum allowed value (inclusive). If not specified,
+   * no maximum is enforced.
+   */
+  readonly max?: number;
+}
+/**
+ * Options for creating an integer parser that returns a `bigint`.
+ *
+ * This interface is used when you need to parse very large integers that
+ * exceed JavaScript's safe integer range.
+ */
+interface IntegerOptionsBigInt {
+  /** Must be set to `"bigint"` to create a `bigint` parser. */
+  readonly type: "bigint";
+  /**
+   * The metavariable name for this parser.  This is used in help messages to
+   * indicate what kind of value this parser expects.  Usually a single
+   * word in uppercase, like `PORT`.
+   * @default `"INTEGER"`
+   */
+  readonly metavar?: string;
+  /**
+   * Minimum allowed value (inclusive). If not specified,
+   * no minimum is enforced.
+   */
+  readonly min?: bigint;
+  /**
+   * Maximum allowed value (inclusive). If not specified,
+   * no maximum is enforced.
+   */
+  readonly max?: bigint;
+}
+/**
+ * Creates a ValueParser for integers that returns JavaScript numbers.
+ *
+ * @param options Configuration options for the integer parser.
+ * @returns A {@link ValueParser} that parses strings into numbers.
+ */
+declare function integer(options?: IntegerOptionsNumber): ValueParser<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>;
+/**
+ * Options for creating a {@link float} parser.
+ */
+interface FloatOptions {
+  /**
+   * The metavariable name for this parser.  This is used in help messages to
+   * indicate what kind of value this parser expects.  Usually a single
+   * word in uppercase, like `RATE` or `PRICE`.
+   * @default `"NUMBER"`
+   */
+  readonly metavar?: string;
+  /**
+   * Minimum allowed value (inclusive). If not specified,
+   * no minimum is enforced.
+   */
+  readonly min?: number;
+  /**
+   * Maximum allowed value (inclusive). If not specified,
+   * no maximum is enforced.
+   */
+  readonly max?: number;
+  /**
+   * If `true`, allows the special value `NaN` (not a number).
+   * This is useful for cases where `NaN` is a valid input,
+   * such as in some scientific calculations.
+   * @default `false`
+   */
+  readonly allowNaN?: boolean;
+  /**
+   * If `true`, allows the special values `Infinity` and `-Infinity`.
+   * This is useful for cases where infinite values are valid inputs,
+   * such as in mathematical calculations or limits.
+   * @default `false`
+   */
+  readonly allowInfinity?: boolean;
+}
+/**
+ * Creates a {@link ValueParser} for floating-point numbers.
+ *
+ * This parser validates that the input is a valid floating-point number
+ * and optionally enforces minimum and maximum value constraints.
+ * @param options Configuration options for the float parser.
+ * @returns A {@link ValueParser} that parses strings into floating-point
+ *          numbers.
+ */
+declare function float(options?: FloatOptions): ValueParser<number>;
+/**
+ * Options for creating a {@link url} parser.
+ */
+interface UrlOptions {
+  /**
+   * The metavariable name for this parser.  This is used in help messages to
+   * indicate what kind of value this parser expects.  Usually a single
+   * word in uppercase, like `URL` or `ENDPOINT`.
+   * @default `"URL"`
+   */
+  readonly metavar?: string;
+  /**
+   * List of allowed URL protocols (e.g., `["http:", "https:"]`).
+   * If specified, the parsed URL must use one of these protocols.
+   * Protocol names should include the trailing colon (e.g., `"https:"`).
+   * If not specified, any protocol is allowed.
+   */
+  readonly allowedProtocols?: readonly string[];
+}
+/**
+ * Creates a {@link ValueParser} for URL values.
+ *
+ * This parser validates that the input is a well-formed URL and optionally
+ * restricts the allowed protocols. The parsed result is a JavaScript `URL`
+ * object.
+ * @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>;
+/**
+ * Options for creating a {@link locale} parser.
+ */
+interface LocaleOptions {
+  /**
+   * The metavariable name for this parser.  This is used in help messages to
+   * indicate what kind of value this parser expects.  Usually a single
+   * word in uppercase, like `LOCALE` or `LANG`.
+   * @default `"LOCALE"`
+   */
+  readonly metavar?: string;
+}
+/**
+ * Creates a {@link ValueParser} for locale values.
+ *
+ * This parser validates that the input is a well-formed locale identifier
+ * according to the Unicode Locale Identifier standard (BCP 47).
+ * The parsed result is a JavaScript `Intl.Locale` object.
+ * @param options Configuration options for the locale parser.
+ * @returns A {@link ValueParser} that converts string input to `Intl.Locale`
+ *          objects.
+ */
+declare function locale(options?: LocaleOptions): ValueParser<Intl.Locale>;
+/**
+ * Type representing a UUID string.
+ *
+ * A UUID is a 36-character string in the format:
+ * `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`
+ * where each `x` is a hexadecimal digit.
+ */
+type Uuid = `${string}-${string}-${string}-${string}-${string}`;
+/**
+ * Options for creating a {@link uuid} parser.
+ */
+interface UuidOptions {
+  /**
+   * The metavariable name for this parser.  This is used in help messages to
+   * indicate what kind of value this parser expects.  Usually a single
+   * word in uppercase, like `UUID` or `ID`.
+   * @default `"UUID"`
+   */
+  readonly metavar?: string;
+  /**
+   * List of allowed UUID versions (e.g., `[4, 5]` for UUIDs version 4 and 5).
+   * If specified, the parser will validate that the UUID matches one of the
+   * allowed versions. If not specified, any valid UUID format is accepted.
+   */
+  readonly allowedVersions?: readonly number[];
+}
+/**
+ * Creates a {@link ValueParser} for UUID values.
+ *
+ * This parser validates that the input is a well-formed UUID string in the
+ * standard format: `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` where each `x`
+ * is a hexadecimal digit.  The parser can optionally restrict to specific
+ * UUID versions.
+ *
+ * @param options Configuration options for the UUID parser.
+ * @returns A {@link ValueParser} that converts string input to {@link Uuid}
+ *          strings.
+ */
+declare function uuid(options?: UuidOptions): ValueParser<Uuid>;
+//#endregion
+export { ChoiceOptions, FloatOptions, IntegerOptionsBigInt, IntegerOptionsNumber, LocaleOptions, StringOptions, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, choice, float, integer, isValueParser, locale, string, url, uuid };