@gunshi/combinators 0.28.2

package/lib/index.d.ts

@@ -0,0 +1,1073 @@
+//#region ../../node_modules/.pnpm/args-tokens@0.24.1/node_modules/args-tokens/lib/resolver.d.ts
+
+//#region src/resolver.d.ts
+/**
+ * An argument schema definition for command-line argument parsing.
+ *
+ * This schema is similar to the schema of Node.js `util.parseArgs` but with extended features:
+ * - Additional `required` and `description` properties
+ * - Extended `type` support: 'string', 'boolean', 'number', 'enum', 'positional', 'custom'
+ * - Simplified `default` property (single type, not union types)
+ *
+ * @example
+ * Basic string argument:
+ * ```ts
+ * const schema: ArgSchema = {
+ *   type: 'string',
+ *   description: 'Server hostname',
+ *   default: 'localhost'
+ * }
+ * ```
+ *
+ * @example
+ * Required number argument with alias:
+ * ```ts
+ * const schema: ArgSchema = {
+ *   type: 'number',
+ *   short: 'p',
+ *   description: 'Port number to listen on',
+ *   required: true
+ * }
+ * ```
+ *
+ * @example
+ * Enum argument with choices:
+ * ```ts
+ * const schema: ArgSchema = {
+ *   type: 'enum',
+ *   choices: ['info', 'warn', 'error'],
+ *   description: 'Logging level',
+ *   default: 'info'
+ * }
+ * ```
+ */
+interface ArgSchema {
+  /**
+   * Type of the argument value.
+   *
+   * - `'string'`: Text value (default if not specified)
+   * - `'boolean'`: `true`/`false` flag (can be negatable with `--no-` prefix)
+   * - `'number'`: Numeric value (parsed as integer or float)
+   * - `'enum'`: One of predefined string values (requires `choices` property)
+   * - `'positional'`: Non-option argument by position
+   * - `'custom'`: Custom parsing with user-defined `parse` function
+   *
+   * @example
+   * Different argument types:
+   * ```ts
+   * {
+   *   name: { type: 'string' },        // --name value
+   *   verbose: { type: 'boolean' },     // --verbose or --no-verbose
+   *   port: { type: 'number' },         // --port 3000
+   *   level: { type: 'enum', choices: ['debug', 'info'] },
+   *   file: { type: 'positional' },     // first positional arg
+   *   config: { type: 'custom', parse: JSON.parse }
+   * }
+   * ```
+   */
+  type: 'string' | 'boolean' | 'number' | 'enum' | 'positional' | 'custom';
+  /**
+   * Single character alias for the long option name.
+   *
+   * As example, allows users to use `-x` instead of `--extended-option`.
+   * Only valid for non-positional argument types.
+   *
+   * @example
+   * Short alias usage:
+   * ```ts
+   * {
+   *   verbose: {
+   *     type: 'boolean',
+   *     short: 'v'  // Enables both --verbose and -v
+   *   },
+   *   port: {
+   *     type: 'number',
+   *     short: 'p'  // Enables both --port 3000 and -p 3000
+   *   }
+   * }
+   * ```
+   */
+  short?: string;
+  /**
+   * Human-readable description of the argument's purpose.
+   *
+   * Used for help text generation and documentation.
+   * Should be concise but descriptive enough to understand the argument's role.
+   *
+   * @example
+   * Descriptive help text:
+   * ```ts
+   * {
+   *   config: {
+   *     type: 'string',
+   *     description: 'Path to configuration file'
+   *   },
+   *   timeout: {
+   *     type: 'number',
+   *     description: 'Request timeout in milliseconds'
+   *   }
+   * }
+   * ```
+   */
+  description?: string;
+  /**
+   * Marks the argument as required.
+   *
+   * When `true`, the argument must be provided by the user.
+   * If missing, an `ArgResolveError` with type 'required' will be thrown.
+   *
+   * Note: Only `true` is allowed (not `false`) to make intent explicit.
+   *
+   * @example
+   * Required arguments:
+   * ```ts
+   * {
+   *   input: {
+   *     type: 'string',
+   *     required: true,  // Must be provided: --input file.txt
+   *     description: 'Input file path'
+   *   },
+   *   source: {
+   *     type: 'positional',
+   *     required: true   // First positional argument must exist
+   *   }
+   * }
+   * ```
+   */
+  required?: boolean;
+  /**
+   * Allows the argument to accept multiple values.
+   *
+   * When `true`, the resolved value becomes an array.
+   * For options: can be specified multiple times (--tag foo --tag bar)
+   * For positional: collects remaining positional arguments
+   *
+   * Note: Only `true` is allowed (not `false`) to make intent explicit.
+   *
+   * @example
+   * Multiple values:
+   * ```ts
+   * {
+   *   tags: {
+   *     type: 'string',
+   *     multiple: true,  // --tags foo --tags bar → ['foo', 'bar']
+   *     description: 'Tags to apply'
+   *   },
+   *   files: {
+   *     type: 'positional',
+   *     multiple: true   // Collects all remaining positional args
+   *   }
+   * }
+   * ```
+   */
+  multiple?: true;
+  /**
+   * Enables negation for boolean arguments using `--no-` prefix.
+   *
+   * When `true`, allows users to explicitly set the boolean to `false`
+   * using `--no-option-name`. When `false` or omitted, only positive
+   * form is available.
+   *
+   * Only applicable to `type: 'boolean'` arguments.
+   *
+   * @example
+   * Negatable boolean:
+   * ```ts
+   * {
+   *   color: {
+   *     type: 'boolean',
+   *     negatable: true,
+   *     default: true,
+   *     description: 'Enable colorized output'
+   *   }
+   *   // Usage: --color (true), --no-color (false)
+   * }
+   * ```
+   */
+  negatable?: boolean;
+  /**
+   * Array of allowed string values for enum-type arguments.
+   *
+   * Required when `type: 'enum'`. The argument value must be one of these choices,
+   * otherwise an `ArgResolveError` with type 'type' will be thrown.
+   *
+   * Supports both mutable arrays and readonly arrays for type safety.
+   *
+   * @example
+   * Enum choices:
+   * ```ts
+   * {
+   *   logLevel: {
+   *     type: 'enum',
+   *     choices: ['debug', 'info', 'warn', 'error'] as const,
+   *     default: 'info',
+   *     description: 'Logging verbosity level'
+   *   },
+   *   format: {
+   *     type: 'enum',
+   *     choices: ['json', 'yaml', 'toml'],
+   *     description: 'Output format'
+   *   }
+   * }
+   * ```
+   */
+  choices?: string[] | readonly string[];
+  /**
+   * Default value used when the argument is not provided.
+   *
+   * The type must match the argument's `type` property:
+   * - `string` type: string default
+   * - `boolean` type: boolean default
+   * - `number` type: number default
+   * - `enum` type: must be one of the `choices` values
+   * - `positional`/`custom` type: any appropriate default
+   *
+   * @example
+   * Default values by type:
+   * ```ts
+   * {
+   *   host: {
+   *     type: 'string',
+   *     default: 'localhost'  // string default
+   *   },
+   *   verbose: {
+   *     type: 'boolean',
+   *     default: false        // boolean default
+   *   },
+   *   port: {
+   *     type: 'number',
+   *     default: 8080         // number default
+   *   },
+   *   level: {
+   *     type: 'enum',
+   *     choices: ['low', 'high'],
+   *     default: 'low'        // must be in choices
+   *   }
+   * }
+   * ```
+   */
+  default?: string | boolean | number;
+  /**
+   * Converts the argument name from camelCase to kebab-case for CLI usage.
+   *
+   * When `true`, a property like `maxCount` becomes available as `--max-count`.
+   * This allows [CAC](https://github.com/cacjs/cac) user-friendly property names while maintaining CLI conventions.
+   *
+   * Can be overridden globally with `resolveArgs({ toKebab: true })`.
+   *
+   * Note: Only `true` is allowed (not `false`) to make intent explicit.
+   *
+   * @example
+   * Kebab-case conversion:
+   * ```ts
+   * {
+   *   maxRetries: {
+   *     type: 'number',
+   *     toKebab: true,        // Accessible as --max-retries
+   *     description: 'Maximum retry attempts'
+   *   },
+   *   enableLogging: {
+   *     type: 'boolean',
+   *     toKebab: true         // Accessible as --enable-logging
+   *   }
+   * }
+   * ```
+   */
+  toKebab?: true;
+  /**
+   * Names of other options that conflict with this option.
+   *
+   * When this option is used together with any of the conflicting options,
+   * an `ArgResolveError` with type 'conflict' will be thrown.
+   *
+   * Conflicts only need to be defined on one side - if option A defines a conflict
+   * with option B, the conflict is automatically detected when both are used,
+   * regardless of whether B also defines a conflict with A.
+   *
+   * Supports both single option name or array of option names.
+   * Option names must match the property keys in the schema object exactly
+   * (no automatic conversion between camelCase and kebab-case).
+   *
+   * @example
+   * Single conflict (bidirectional definition):
+   * ```ts
+   * {
+   *   summer: {
+   *     type: 'boolean',
+   *     conflicts: 'autumn'  // Cannot use --summer with --autumn
+   *   },
+   *   autumn: {
+   *     type: 'boolean',
+   *     conflicts: 'summer'  // Can define on both sides for clarity
+   *   }
+   * }
+   * ```
+   *
+   * @example
+   * Single conflict (one-way definition):
+   * ```ts
+   * {
+   *   summer: {
+   *     type: 'boolean',
+   *     conflicts: 'autumn'  // Only defined on summer side
+   *   },
+   *   autumn: {
+   *     type: 'boolean'
+   *     // No conflicts defined, but still cannot use with --summer
+   *   }
+   * }
+   * // Usage: --summer --autumn will throw error
+   * // Error: "Optional argument '--summer' conflicts with '--autumn'"
+   * ```
+   *
+   * @example
+   * Multiple conflicts:
+   * ```ts
+   * {
+   *   port: {
+   *     type: 'number',
+   *     conflicts: ['socket', 'pipe'],  // Cannot use with --socket or --pipe
+   *     description: 'TCP port number'
+   *   },
+   *   socket: {
+   *     type: 'string',
+   *     conflicts: ['port', 'pipe'],    // Cannot use with --port or --pipe
+   *     description: 'Unix socket path'
+   *   },
+   *   pipe: {
+   *     type: 'string',
+   *     conflicts: ['port', 'socket'],  // Cannot use with --port or --socket
+   *     description: 'Named pipe path'
+   *   }
+   * }
+   * // These three options are mutually exclusive
+   * ```
+   *
+   * @example
+   * With kebab-case conversion:
+   * ```ts
+   * {
+   *   summerSeason: {
+   *     type: 'boolean',
+   *     toKebab: true,  // Accessible as --summer-season
+   *     conflicts: 'autumnSeason'  // Must use property key, not CLI name
+   *   },
+   *   autumnSeason: {
+   *     type: 'boolean',
+   *     toKebab: true  // Accessible as --autumn-season
+   *   }
+   * }
+   * // Error: "Optional argument '--summer-season' conflicts with '--autumn-season'"
+   * ```
+   */
+  conflicts?: string | string[];
+  /**
+   * Display name hint for help text generation.
+   *
+   * Provides a meaningful type hint for the argument value in help output.
+   * Particularly useful for `type: 'custom'` arguments where the type
+   * name would otherwise be unhelpful.
+   *
+   * @example
+   * Metavar usage:
+   * ```ts
+   * {
+   *   port: {
+   *     type: 'custom',
+   *     parse: (v: string) => parseInt(v, 10),
+   *     metavar: 'integer',
+   *     description: 'Port number (1-65535)'
+   *   }
+   * }
+   * // Help output: --port <integer>  Port number (1-65535)
+   * ```
+   */
+  metavar?: string;
+  /**
+   * Custom parsing function for `type: 'custom'` arguments.
+   *
+   * Required when `type: 'custom'`. Receives the raw string value and must
+   * return the parsed result. Should throw an Error (or subclass) if parsing fails.
+   *
+   * The function's return type becomes the resolved argument type.
+   *
+   * @param value - Raw string value from command line
+   * @returns Parsed value of any type
+   * @throws Error or subclass when value is invalid
+   *
+   * @example
+   * Custom parsing functions:
+   * ```ts
+   * {
+   *   config: {
+   *     type: 'custom',
+   *     parse: (value: string) => {
+   *       try {
+   *         return JSON.parse(value)  // Parse JSON config
+   *       } catch {
+   *         throw new Error('Invalid JSON configuration')
+   *       }
+   *     },
+   *     description: 'JSON configuration object'
+   *   },
+   *   date: {
+   *     type: 'custom',
+   *     parse: (value: string) => {
+   *       const date = new Date(value)
+   *       if (isNaN(date.getTime())) {
+   *         throw new Error('Invalid date format')
+   *       }
+   *       return date
+   *     }
+   *   }
+   * }
+   * ```
+   */
+  parse?: (value: string) => any;
+}
+/**
+ * An object that contains {@link ArgSchema | argument schema}.
+ *
+ * This type is used to define the structure and validation rules for command line arguments.
+ */
+interface Args {
+  [option: string]: ArgSchema;
+}
+/**
+ * An object that contains the values of the arguments.
+ *
+ * @typeParam T - {@link Args | Arguments} which is an object that defines the command line arguments.
+ */
+//#endregion
+//#region ../../node_modules/.pnpm/args-tokens@0.24.1/node_modules/args-tokens/lib/combinators.d.ts
+//#region src/combinators.d.ts
+/**
+* @author kazuya kawaguchi (a.k.a. kazupon)
+* @license MIT
+*/
+/**
+ * A combinator produced by combinator factory functions.
+ *
+ * @typeParam T - The parsed value type.
+ *
+ * @experimental
+ */
+type Combinator<T> = {
+  /**
+   * The parse function that converts a string to the desired type.
+   *
+   * @param value - The input string value.
+   * @returns The parsed value of type T.
+   */
+  parse: (value: string) => T;
+};
+/**
+ * A schema produced by combinator factory functions.
+ * Any {@link ArgSchema} with a parse function qualifies.
+ *
+ * @typeParam T - The parsed value type.
+ *
+ * @experimental
+ */
+type CombinatorSchema<T> = ArgSchema & Combinator<T>;
+/**
+ * Common options shared by all base combinators.
+ *
+ * @experimental
+ */
+interface BaseOptions {
+  /**
+   * Human-readable description for help text generation.
+   */
+  description?: string;
+  /**
+   * Single character short alias.
+   */
+  short?: string;
+  /**
+   * Mark as required.
+   */
+  required?: boolean;
+}
+/**
+ * Options for the {@link string} combinator.
+ *
+ * @experimental
+ */
+interface StringOptions extends BaseOptions {
+  /**
+   * Minimum string length.
+   */
+  minLength?: number;
+  /**
+   * Maximum string length.
+   */
+  maxLength?: number;
+  /**
+   * Regular expression pattern the value must match.
+   */
+  pattern?: RegExp;
+}
+/**
+ * Create a string argument schema with optional validation.
+ *
+ * @param opts - Validation options.
+ * @returns A combinator schema that resolves to string.
+ *
+ * @example
+ * ```ts
+ * const args = {
+ *   name: string({ minLength: 1, maxLength: 50 })
+ * }
+ * ```
+ *
+ * @experimental
+ */
+declare function string(opts?: StringOptions): CombinatorSchema<string>;
+/**
+ * Options for the {@link number} combinator.
+ *
+ * @experimental
+ */
+interface NumberOptions extends BaseOptions {
+  /**
+   * Minimum value (inclusive).
+   */
+  min?: number;
+  /**
+   * Maximum value (inclusive).
+   */
+  max?: number;
+}
+/**
+ * Create a number argument schema with optional range validation.
+ *
+ * Accepts any numeric value (integer or float).
+ *
+ * @param opts - Range options.
+ * @returns A combinator schema that resolves to number.
+ *
+ * @example
+ * ```ts
+ * const args = {
+ *   timeout: number({ min: 0, max: 30000 })
+ * }
+ * ```
+ *
+ * @experimental
+ */
+declare function number(opts?: NumberOptions): CombinatorSchema<number>;
+/**
+ * Options for the {@link integer} combinator.
+ *
+ * @experimental
+ */
+interface IntegerOptions extends BaseOptions {
+  /**
+   * Minimum value (inclusive).
+   */
+  min?: number;
+  /**
+   * Maximum value (inclusive).
+   */
+  max?: number;
+}
+/**
+ * Create an integer argument schema with optional range validation.
+ *
+ * Only accepts integer values (no decimals).
+ *
+ * @param opts - Range options.
+ * @returns A combinator schema that resolves to number (integer).
+ *
+ * @example
+ * ```ts
+ * const args = {
+ *   retries: integer({ min: 0, max: 10 })
+ * }
+ * ```
+ *
+ * @experimental
+ */
+declare function integer(opts?: IntegerOptions): CombinatorSchema<number>;
+/**
+ * Options for the {@link float} combinator.
+ *
+ * @experimental
+ */
+interface FloatOptions extends BaseOptions {
+  /**
+   * Minimum value (inclusive).
+   */
+  min?: number;
+  /**
+   * Maximum value (inclusive).
+   */
+  max?: number;
+}
+/**
+ * Create a floating-point argument schema with optional range validation.
+ *
+ * Rejects `NaN` and `Infinity` values.
+ *
+ * @param opts - Range options.
+ * @returns A combinator schema that resolves to number (float).
+ *
+ * @example
+ * ```ts
+ * const args = {
+ *   ratio: float({ min: 0, max: 1 })
+ * }
+ * ```
+ *
+ * @experimental
+ */
+declare function float(opts?: FloatOptions): CombinatorSchema<number>;
+/**
+ * Options for the {@link boolean} combinator.
+ *
+ * @experimental
+ */
+interface BooleanOptions extends BaseOptions {
+  /**
+   * Enable negation with `--no-` prefix.
+   */
+  negatable?: boolean;
+}
+/**
+ * Create a boolean argument schema.
+ *
+ * Boolean arguments are existence-based. The resolver passes `"true"` or `"false"`
+ * to the parse function based on the presence or negation of the flag.
+ *
+ * @param opts - Boolean options.
+ * @returns A combinator schema for boolean flags.
+ *
+ * @example
+ * ```ts
+ * const args = {
+ *   color: boolean({ negatable: true })
+ * }
+ * // Usage: --color (true), --no-color (false)
+ * ```
+ *
+ * @experimental
+ */
+declare function boolean(opts?: BooleanOptions): CombinatorSchema<boolean>;
+/**
+ * Positional argument schema type.
+ */
+type ArgSchemaPositionalType = {
+  type: 'positional';
+};
+/**
+ * Create a positional argument schema.
+ *
+ * Without a parser, resolves to string.
+ * With a parser (e.g., `positional(integer())`), resolves to the parser's return type.
+ *
+ * @typeParam T - The parser's resolved type.
+ *
+ * @param parser - The parser combinator schema.
+ * @returns A positional argument schema resolving to the parser's type.
+ *
+ * @example
+ * ```ts
+ * const args = {
+ *   command: positional(),           // resolves to string
+ *   port: positional(integer()),     // resolves to number
+ * }
+ * ```
+ *
+ * @experimental
+ */
+declare function positional<T>(parser: CombinatorSchema<T>): CombinatorSchema<T> & ArgSchemaPositionalType;
+/**
+ * Create a positional argument schema.
+ *
+ * Without a parser, resolves to string.
+ * With a parser (e.g., `positional(integer())`), resolves to the parser's return type.
+ *
+ * @param parser - Optional base options (description, short, required).
+ * @returns A positional argument schema resolving to string.
+ *
+ * @example
+ * ```ts
+ * const args = {
+ *   command: positional(),           // resolves to string
+ *   port: positional(integer()),     // resolves to number
+ * }
+ * ```
+ *
+ * @experimental
+ */
+declare function positional(parser?: BaseOptions): ArgSchema & ArgSchemaPositionalType;
+/**
+ * Create an enum-like argument schema with literal type inference.
+ *
+ * Uses `const T` generic to infer literal union types from the values array.
+ *
+ * @typeParam T - The readonly array of allowed string values.
+ *
+ * @param values - Allowed values.
+ * @param opts - Common options (description, short, required).
+ * @returns A combinator schema that resolves to a union of the allowed values.
+ *
+ * @example
+ * ```ts
+ * const args = {
+ *   level: choice(['debug', 'info', 'warn', 'error'] as const)
+ * }
+ * // typeof values.level === 'debug' | 'info' | 'warn' | 'error'
+ * ```
+ *
+ * @experimental
+ */
+declare function choice<const T extends readonly string[]>(values: T, opts?: BaseOptions): CombinatorSchema<T[number]>;
+/**
+ * Options for the {@link combinator} factory function.
+ *
+ * @typeParam T - The parsed value type.
+ *
+ * @experimental
+ */
+interface CombinatorOptions<T> extends BaseOptions {
+  /**
+   * The parse function that converts a string to the desired type.
+   *
+   * @param value - The input string value.
+   * @returns The parsed value of type T.
+   */
+  parse: (value: string) => T;
+  /**
+   * Display name hint for help text generation.
+   *
+   * @default 'custom'
+   */
+  metavar?: string;
+}
+/**
+ * Create a custom argument schema with a user-defined parse function.
+ *
+ * This is the most general custom combinator. Use it when none of the built-in
+ * base combinators ({@link string}, {@link number}, {@link integer},
+ * {@link float}, {@link boolean}, {@link choice}) fit your needs.
+ *
+ * The returned schema has `type: 'custom'`.
+ *
+ * @typeParam T - The parsed value type.
+ *
+ * @param config - Configuration with a parse function and optional metavar.
+ * @returns A combinator schema that resolves to the parse function's return type.
+ *
+ * @example
+ * ```ts
+ * const date = combinator({
+ *   parse: (value) => {
+ *     const d = new Date(value)
+ *     if (isNaN(d.getTime())) {
+ *       throw new Error('Invalid date format')
+ *     }
+ *     return d
+ *   },
+ *   metavar: 'date'
+ * })
+ * ```
+ *
+ * @experimental
+ */
+declare function combinator<T>(config: CombinatorOptions<T>): CombinatorSchema<T>;
+/**
+ * Transform the output of a combinator schema.
+ *
+ * Creates a new schema that applies `transform` to the result of `schema.parse`.
+ * The original schema is not modified.
+ *
+ * @typeParam T - The input schema's parsed type.
+ * @typeParam U - The transformed type.
+ *
+ * @param schema - The base combinator schema.
+ * @param transform - The transformation function.
+ * @returns A new combinator schema that resolves to the transformed type.
+ *
+ * @example
+ * ```ts
+ * const args = {
+ *   doubled: map(integer(), n => n * 2)
+ * }
+ * ```
+ *
+ * @experimental
+ */
+declare function map<T, U>(schema: CombinatorSchema<T>, transform: (value: T) => U): CombinatorSchema<U>;
+/**
+ * Options for the {@link withDefault} combinator.
+ */
+type CombinatorWithDefault<T> = {
+  default: T;
+};
+/**
+ * Set a default value on a combinator schema.
+ *
+ * The original schema is not modified.
+ *
+ * @typeParam T - The schema's parsed type.
+ *
+ * @param schema - The base combinator schema.
+ * @param defaultValue - The default value.
+ * @returns A new schema with the default value set.
+ *
+ * @example
+ * ```ts
+ * const args = {
+ *   port: withDefault(integer({ min: 1, max: 65535 }), 8080)
+ * }
+ * ```
+ *
+ * @experimental
+ */
+declare function withDefault<T extends string | boolean | number>(schema: CombinatorSchema<T>, defaultValue: T): CombinatorSchema<T> & CombinatorWithDefault<T>;
+/**
+ * Options for the {@link multiple} combinator.
+ */
+type CombinatorMultiple = {
+  multiple: true;
+};
+/**
+ * Mark a combinator schema as accepting multiple values.
+ *
+ * The resolved value becomes an array. The original schema is not modified.
+ *
+ * @typeParam T - The schema's parsed type.
+ * @param schema - The base combinator schema.
+ * @returns A new schema with `multiple: true`.
+ *
+ * @example
+ * ```ts
+ * const args = {
+ *   tags: multiple(string())
+ * }
+ * // typeof values.tags === string[]
+ * ```
+ *
+ * @experimental
+ */
+declare function multiple<T>(schema: CombinatorSchema<T>): CombinatorSchema<T> & CombinatorMultiple;
+/**
+ * Options for the {@link required} combinator.
+ */
+type CombinatorRequired = {
+  required: true;
+};
+/**
+ * Mark a combinator schema as required.
+ *
+ * The original schema is not modified.
+ *
+ * @typeParam T - The schema's parsed type.
+ *
+ * @param schema - The base combinator schema.
+ * @returns A new schema with `required: true`.
+ *
+ * @example
+ * ```ts
+ * const args = {
+ *   name: required(string())
+ * }
+ * ```
+ *
+ * @experimental
+ */
+declare function required<T>(schema: CombinatorSchema<T>): CombinatorSchema<T> & CombinatorRequired;
+/**
+ * Options for the {@link short} combinator.
+ */
+type CombinatorShort<S extends string> = {
+  short: S;
+};
+/**
+ * Set a short alias on a combinator schema.
+ *
+ * The original schema is not modified.
+ *
+ * @typeParam T - The schema's parsed type.
+ * @typeParam S - The short alias string literal type.
+ *
+ * @param schema - The base combinator schema.
+ * @param alias - Single character short alias.
+ * @returns A new schema with the short alias set.
+ *
+ * @example
+ * ```ts
+ * const args = {
+ *   verbose: short(boolean(), 'v')
+ * }
+ * // Usage: -v or --verbose
+ * ```
+ *
+ * @experimental
+ */
+declare function short<T, S extends string>(schema: CombinatorSchema<T>, alias: S): CombinatorSchema<T> & CombinatorShort<S>;
+/**
+ * Options for the {@link describe} combinator.
+ */
+type CombinatorDescribe<D extends string> = {
+  description: D;
+};
+/**
+ * Set a description on a combinator schema for help text generation.
+ *
+ * The original schema is not modified.
+ *
+ * @typeParam T - The schema's parsed type.
+ * @typeParam D - The description string literal type.
+ *
+ * @param schema - The base combinator schema.
+ * @param text - Human-readable description.
+ * @returns A new schema with the description set.
+ *
+ * @example
+ * ```ts
+ * const args = {
+ *   port: describe(integer(), 'Port number to listen on')
+ * }
+ * ```
+ *
+ * @experimental
+ */
+declare function describe<T, D extends string>(schema: CombinatorSchema<T>, text: D): CombinatorSchema<T> & CombinatorDescribe<D>;
+/**
+ * Options for the {@link unrequired} combinator.
+ */
+type CombinatorUnrequired = {
+  required: false;
+};
+/**
+ * Mark a combinator schema as not required.
+ *
+ * Useful for overriding a base combinator that was created with `required: true`.
+ * The original schema is not modified.
+ *
+ * @typeParam T - The schema's parsed type.
+ *
+ * @param schema - The base combinator schema.
+ * @returns A new schema with `required: false`.
+ *
+ * @example
+ * ```ts
+ * const args = {
+ *   name: unrequired(string({ required: true }))
+ * }
+ * ```
+ *
+ * @experimental
+ */
+declare function unrequired<T>(schema: CombinatorSchema<T>): CombinatorSchema<T> & CombinatorUnrequired;
+/**
+ * Recursively merge a tuple of {@link Args} types.
+ * Later types override earlier ones on key conflicts.
+ *
+ * @internal
+ */
+type MergeArgs<T extends Args[]> = T extends [infer Only extends Args] ? Only : T extends [infer First extends Args, ...infer Rest extends Args[]] ? Omit<First, keyof MergeArgs<Rest>> & MergeArgs<Rest> : never;
+/**
+ * Type-safe schema factory.
+ *
+ * Returns the input unchanged at runtime, but provides type inference
+ * so that `satisfies Args` is not needed.
+ *
+ * @typeParam T - The exact schema type.
+ *
+ * @param fields - The argument schema object.
+ * @returns The same schema object with its type inferred.
+ *
+ * @example
+ * ```ts
+ * const common = args({
+ *   verbose: boolean(),
+ *   help: short(boolean(), 'h')
+ * })
+ * ```
+ *
+ * @experimental
+ */
+declare function args<T extends Args>(fields: T): T;
+/**
+ * Compose multiple {@link Args} schemas into one.
+ *
+ * On key conflicts the later schema wins (last-write-wins).
+ *
+ * @typeParam A - First schema type.
+ * @typeParam B - Second schema type.
+ *
+ * @param a - First schema.
+ * @param b - Second schema.
+ * @returns A merged schema containing all fields.
+ *
+ * @example
+ * ```ts
+ * const common = args({ verbose: boolean() })
+ * const network = args({ host: required(string()), port: withDefault(integer(), 8080) })
+ * const schema = merge(common, network)
+ * ```
+ *
+ * @experimental
+ */
+declare function merge<A extends Args, B extends Args>(a: A, b: B): Omit<A, keyof B> & B;
+/**
+ * Compose multiple {@link Args} schemas into one.
+ *
+ * @param a - First schema.
+ * @param b - Second schema.
+ * @param c - Third schema.
+ * @returns A merged schema containing all fields.
+ *
+ * @experimental
+ */
+declare function merge<A extends Args, B extends Args, C extends Args>(a: A, b: B, c: C): Omit<Omit<A, keyof B | keyof C> & Omit<B, keyof C>, never> & C;
+/**
+ * Compose multiple {@link Args} schemas into one.
+ *
+ * @param a - First schema.
+ * @param b - Second schema.
+ * @param c - Third schema.
+ * @param d - Fourth schema.
+ * @returns A merged schema containing all fields.
+ *
+ * @experimental
+ */
+declare function merge<A extends Args, B extends Args, C extends Args, D extends Args>(a: A, b: B, c: C, d: D): MergeArgs<[A, B, C, D]>;
+/**
+ * Compose multiple {@link Args} schemas into one.
+ *
+ * @param schemas - The schemas to merge.
+ * @returns A merged schema containing all fields.
+ *
+ * @experimental
+ */
+declare function merge<T extends Args[]>(...schemas: T): MergeArgs<T>;
+/**
+ * Extend a schema by overriding or adding fields.
+ *
+ * Equivalent to `merge(base, overrides)` but communicates the intent of
+ * intentional overrides rather than general composition.
+ *
+ * @typeParam T - Base schema type.
+ * @typeParam U - Overrides schema type.
+ *
+ * @param base - The base schema to extend.
+ * @param overrides - Fields to override or add.
+ * @returns A new schema with overrides applied.
+ *
+ * @example
+ * ```ts
+ * const base = args({ port: withDefault(integer(), 8080) })
+ * const strict = extend(base, { port: required(integer({ min: 1, max: 65535 })) })
+ * ```
+ *
+ * @experimental
+ */
+declare function extend<T extends Args, U extends Args>(base: T, overrides: U): Omit<T, keyof U> & U;
+//#endregion
+//#endregion
+export { BaseOptions, BooleanOptions, Combinator, CombinatorOptions, CombinatorSchema, FloatOptions, IntegerOptions, NumberOptions, StringOptions, args, boolean, choice, combinator, describe, extend, float, integer, map, merge, multiple, number, positional, required, short, string, unrequired, withDefault };