/**
 * TypeScript type definitions for the bargs CLI argument parser.
 *
 * Defines all public interfaces and types including:
 *
 * - Option definitions (`StringOption`, `BooleanOption`, `EnumOption`, etc.)
 * - Positional definitions (`StringPositional`, `VariadicPositional`, etc.)
 * - Schema types (`OptionsSchema`, `PositionalsSchema`)
 * - Type inference utilities (`InferOptions`, `InferPositionals`)
 * - Parser combinator types (`Parser`, `Command`, `ParseResult`)
 *
 * @packageDocumentation
 */
import type { ThemeInput } from "./theme.js";
/**
 * Array option definition (--flag value --flag value2).
 *
 * @group Option Types
 */
export interface ArrayOption extends OptionBase {
    default?: number[] | string[];
    /** Element type of the array (for primitive arrays) */
    items?: 'number' | 'string';
    type: 'array';
}
/**
 * Boolean option definition.
 *
 * @group Option Types
 */
export interface BooleanOption extends OptionBase {
    default?: boolean;
    type: 'boolean';
}
/**
 * Transform all keys of an object type from kebab-case to camelCase.
 *
 * Used with `camelCaseValues` to provide type-safe camelCase option keys.
 *
 * @example
 *
 * ```typescript
 * type Original = { 'output-dir': string; 'dry-run': boolean };
 * type Camel = CamelCaseKeys<Original>; // { outputDir: string; dryRun: boolean }
 * ```
 *
 * @group Type Utilities
 */
export type CamelCaseKeys<T> = {
    [K in keyof T as KebabToCamel<K & string>]: T[K];
};
/**
 * CLI builder for fluent configuration.
 *
 * @group Parser Types
 */
export interface CliBuilder<TGlobalValues = Record<string, never>, TGlobalPositionals extends readonly unknown[] = readonly []> {
    /**
     * Register a command with a Command object.
     *
     * Note: When using this form, the handler only sees command-local types. Use
     * the (parser, handler) form for merged global+command types.
     */
    command<CV, CP extends readonly unknown[]>(name: string, cmd: Command<CV, CP>, options?: CommandOptions | string): CliBuilder<TGlobalValues, TGlobalPositionals>;
    /**
     * Register a command with a Parser and handler separately.
     *
     * This form provides full type inference for merged global + command types.
     * The handler receives `TGlobalValues & CV` for values.
     */
    command<CV, CP extends readonly unknown[]>(name: string, parser: Parser<CV, CP>, handler: HandlerFn<CV & TGlobalValues, CP>, options?: CommandOptions | string): CliBuilder<TGlobalValues, TGlobalPositionals>;
    /**
     * Register a nested command group using a factory function.
     *
     * This form provides full type inference - the factory receives a builder
     * that already has parent globals typed, so all nested command handlers see
     * the merged types.
     *
     * @example
     *
     * ```typescript
     * bargs('main')
     *   .globals(opt.options({ verbose: opt.boolean() }))
     *   .command(
     *     'remote',
     *     (remote) =>
     *       remote.command('add', addParser, ({ values }) => {
     *         // values.verbose is typed correctly!
     *       }),
     *     'Manage remotes',
     *   );
     * ```
     */
    command<CV, CP extends readonly unknown[]>(name: string, factory: (builder: CliBuilder<TGlobalValues, TGlobalPositionals>) => CliBuilder<CV, CP>, options?: CommandOptions | string): CliBuilder<TGlobalValues, TGlobalPositionals>;
    /**
     * Set the default command by name (must be registered first).
     */
    defaultCommand(name: string): CliBuilder<TGlobalValues, TGlobalPositionals>;
    /**
     * Set the default command with a Command object.
     *
     * Note: When using this form, the handler only sees command-local types. Use
     * the (parser, handler) form for merged global+command types.
     */
    defaultCommand<CV, CP extends readonly unknown[]>(cmd: Command<CV, CP>): CliBuilder<TGlobalValues, TGlobalPositionals>;
    /**
     * Set the default command with a Parser and handler separately.
     *
     * This form provides full type inference for merged global + command types.
     * The handler receives `TGlobalValues & CV` for values.
     */
    defaultCommand<CV, CP extends readonly unknown[]>(parser: Parser<CV, CP>, handler: HandlerFn<CV & TGlobalValues, CP>): CliBuilder<TGlobalValues, TGlobalPositionals>;
    /**
     * Set or extend global options/transforms that apply to all commands.
     *
     * When called on a builder that already has globals (e.g., from a factory),
     * the new globals are merged with existing ones.
     */
    globals<V, P extends readonly unknown[]>(parser: Parser<V, P>): CliBuilder<TGlobalValues & V, readonly [...TGlobalPositionals, ...P]>;
    /**
     * Parse arguments synchronously and run handlers.
     *
     * Throws if any transform or handler returns a Promise.
     */
    parse(args?: string[]): ParseResult<TGlobalValues, TGlobalPositionals> & {
        command?: string;
    };
    /**
     * Parse arguments asynchronously and run handlers.
     *
     * Supports async transforms and handlers.
     */
    parseAsync(args?: string[]): Promise<ParseResult<TGlobalValues, TGlobalPositionals> & {
        command?: string;
    }>;
}
/**
 * Result from CLI execution (extends ParseResult with command name).
 *
 * @group Parser Types
 */
export interface CliResult<TValues = Record<string, unknown>, TPositionals extends readonly unknown[] = readonly unknown[]> extends ParseResult<TValues, TPositionals> {
    /** The command that was executed, if any */
    command?: string;
}
/**
 * Command with handler attached (terminal in the pipeline).
 *
 * @group Parser Types
 */
export interface Command<TValues = Record<string, unknown>, TPositionals extends readonly unknown[] = readonly unknown[]> {
    /** Brand for type discrimination. Do not use directly. */
    readonly __brand: 'Command';
    /** Options schema. Do not use directly. */
    readonly __optionsSchema: OptionsSchema;
    /** Positionals schema. Do not use directly. */
    readonly __positionalsSchema: PositionalsSchema;
    /** Command description for help text */
    readonly description?: string;
    /** The handler function */
    readonly handler: HandlerFn<TValues, TPositionals>;
}
/**
 * Registered command definition.
 *
 * @group Parser Types
 */
export interface CommandDef<TValues = Record<string, unknown>, TPositionals extends readonly unknown[] = readonly unknown[]> {
    /** The command */
    readonly command: Command<TValues, TPositionals>;
    /** Description for help */
    readonly description?: string;
    /** Command name */
    readonly name: string;
}
/**
 * Options for command registration.
 *
 * Used as an alternative to a simple string description when registering
 * commands, allowing additional configuration like aliases.
 *
 * @example
 *
 * ```typescript
 * .command('add', addParser, handler, {
 *   description: 'Add a new item',
 *   aliases: ['a', 'new']
 * })
 * ```
 *
 * @group Parser Types
 */
export interface CommandOptions {
    /**
     * Alternative names for this command.
     *
     * @example
     *
     * ```typescript
     * { "aliases": ["co", "sw"] } // 'checkout' can be invoked as 'co' or 'sw'
     * ```
     */
    aliases?: string[];
    /** Command description displayed in help text */
    description?: string;
}
/**
 * Count option definition (--verbose --verbose = 2).
 *
 * @group Option Types
 */
export interface CountOption extends OptionBase {
    default?: number;
    type: 'count';
}
/**
 * Options for bargs().
 *
 * @group Core API
 */
export interface CreateOptions {
    /**
     * Enable shell completion support.
     *
     * When `true`, the CLI will respond to:
     *
     * - `--completion-script <shell>` - Output shell completion script
     * - `--get-bargs-completions <shell> <...words>` - Return completion candidates
     *
     * Supported shells: bash, zsh, fish
     *
     * @example
     *
     * ```typescript
     * bargs('mytool', { completion: true })
     *   .command('build', ...)
     *   .parseAsync();
     *
     * // Then run: mytool --completion-script bash >> ~/.bashrc
     * ```
     */
    completion?: boolean;
    /** Description shown in help */
    description?: string;
    /** Epilog text shown after help output */
    epilog?: false | string;
    /** Color theme for help output */
    theme?: ThemeInput;
    /** Version string (enables --version flag) */
    version?: string;
}
/**
 * Enum array option definition (--flag a --flag b with limited choices).
 *
 * @group Option Types
 */
export interface EnumArrayOption<T extends string = string> extends OptionBase {
    /** Valid choices for array elements */
    choices: readonly T[];
    default?: T[];
    type: 'array';
}
/**
 * Enum option definition with string choices.
 *
 * @group Option Types
 */
export interface EnumOption<T extends string = string> extends OptionBase {
    choices: readonly T[];
    default?: T;
    type: 'enum';
}
/**
 * Enum positional definition with string choices.
 *
 * @group Positional Types
 */
export interface EnumPositional<T extends string = string> extends PositionalBase {
    choices: readonly T[];
    default?: T;
    type: 'enum';
}
/**
 * Handler function signature.
 *
 * @group Parser Types
 */
export type HandlerFn<TValues, TPositionals extends readonly unknown[]> = (result: ParseResult<TValues, TPositionals>) => Promise<void> | void;
/**
 * Infer the TypeScript type from an option definition.
 *
 * @group Type Utilities
 */
export type InferOption<T extends OptionDef> = T extends BooleanOption ? T['required'] extends true ? boolean : T['default'] extends boolean ? boolean : boolean | undefined : T extends NumberOption ? T['required'] extends true ? number : T['default'] extends number ? number : number | undefined : T extends StringOption ? T['required'] extends true ? string : T['default'] extends string ? string : string | undefined : T extends EnumOption<infer E> ? T['required'] extends true ? E : T['default'] extends E ? E : E | undefined : T extends EnumArrayOption<infer E> ? E[] : T extends ArrayOption ? T['items'] extends 'number' ? number[] : string[] : T extends CountOption ? number : never;
/**
 * Infer values type from an options schema.
 *
 * @group Type Utilities
 */
export type InferOptions<T extends OptionsSchema> = {
    [K in keyof T]: InferOption<T[K]>;
};
/**
 * Infer a single positional's type.
 *
 * @group Type Utilities
 */
export type InferPositional<T extends PositionalDef> = T extends NumberPositional ? T['required'] extends true ? number : T['default'] extends number ? number : number | undefined : T extends StringPositional ? T['required'] extends true ? string : T['default'] extends string ? string : string | undefined : T extends EnumPositional<infer E> ? T['required'] extends true ? E : T['default'] extends E ? E : E | undefined : T extends VariadicPositional ? T['items'] extends 'number' ? number[] : string[] : never;
/**
 * Recursively build a tuple type from a positionals schema array.
 *
 * @group Type Utilities
 */
export type InferPositionals<T extends PositionalsSchema> = T extends readonly [
    infer First,
    ...infer Rest
] ? First extends PositionalDef ? Rest extends PositionalsSchema ? readonly [InferPositional<First>, ...InferPositionals<Rest>] : readonly [InferPositional<First>] : readonly [] : T extends readonly [infer Only] ? Only extends PositionalDef ? readonly [InferPositional<Only>] : readonly [] : T extends readonly [] ? readonly [] : readonly InferPositional<T[number]>[];
/**
 * Infer the output positionals type from a transforms config.
 *
 * @group Type Utilities
 */
export type InferTransformedPositionals<TPositionalsIn extends readonly unknown[], TTransforms> = TTransforms extends {
    positionals: PositionalsTransformFn<any, infer TOut>;
} ? TOut extends readonly unknown[] ? TOut : TPositionalsIn : TPositionalsIn;
/**
 * Infer the output values type from a transforms config.
 *
 * @group Type Utilities
 */
export type InferTransformedValues<TValuesIn, TTransforms> = TTransforms extends {
    values: ValuesTransformFn<any, infer TOut>;
} ? TOut : TValuesIn;
/**
 * Convert a kebab-case string type to camelCase.
 *
 * @example
 *
 * ```typescript
 * type Result = KebabToCamel<'output-dir'>; // 'outputDir'
 * type Nested = KebabToCamel<'my-long-option'>; // 'myLongOption'
 * ```
 *
 * @group Type Utilities
 */
export type KebabToCamel<S extends string> = S extends `${infer T}-${infer U}` ? `${T}${Capitalize<KebabToCamel<U>>}` : S;
/**
 * Number option definition.
 *
 * @group Option Types
 */
export interface NumberOption extends OptionBase {
    default?: number;
    type: 'number';
}
/**
 * Number positional.
 *
 * @group Positional Types
 */
export interface NumberPositional extends PositionalBase {
    default?: number;
    type: 'number';
}
/**
 * Union of all option definitions.
 *
 * @group Option Types
 */
export type OptionDef = ArrayOption | BooleanOption | CountOption | EnumArrayOption<string> | EnumOption<string> | NumberOption | StringOption;
/**
 * Options schema: a record of option names to their definitions.
 *
 * @group Option Types
 */
export type OptionsSchema = Record<string, OptionDef>;
/**
 * Parser represents accumulated parse state with options and positionals
 * schemas. This is a branded type for type-level tracking.
 *
 * @group Parser Types
 */
export interface Parser<TValues = Record<string, unknown>, TPositionals extends readonly unknown[] = readonly unknown[]> {
    /** Brand for type discrimination. Do not use directly. */
    readonly __brand: 'Parser';
    /** Options schema. Do not use directly. */
    readonly __optionsSchema: OptionsSchema;
    /** Phantom type for positionals. Do not use directly. */
    readonly __positionals: TPositionals;
    /** Positionals schema. Do not use directly. */
    readonly __positionalsSchema: PositionalsSchema;
    /** Phantom type for values. Do not use directly. */
    readonly __values: TValues;
}
/**
 * Core parse result shape flowing through the pipeline.
 *
 * @group Parser Types
 */
export interface ParseResult<TValues = Record<string, unknown>, TPositionals extends readonly unknown[] = readonly unknown[]> {
    positionals: TPositionals;
    values: TValues;
}
/**
 * Union of positional definitions.
 *
 * @group Positional Types
 */
export type PositionalDef = EnumPositional<string> | NumberPositional | StringPositional | VariadicPositional;
/**
 * Positionals can be a tuple (ordered) or a single variadic.
 *
 * @group Positional Types
 */
export type PositionalsSchema = readonly PositionalDef[];
/**
 * Positionals transform function.
 *
 * @group Parser Types
 */
export type PositionalsTransformFn<TIn extends readonly unknown[], TOut extends readonly unknown[]> = (positionals: TIn) => Promise<TOut> | TOut;
/**
 * String option definition.
 *
 * @group Option Types
 */
export interface StringOption extends OptionBase {
    default?: string;
    type: 'string';
}
/**
 * String positional.
 *
 * @group Positional Types
 */
export interface StringPositional extends PositionalBase {
    default?: string;
    type: 'string';
}
/**
 * Transforms configuration for modifying parsed results.
 *
 * @group Parser Types
 */
export interface TransformsConfig<TValuesIn, TValuesOut, TPositionalsIn extends readonly unknown[], TPositionalsOut extends readonly unknown[]> {
    /** Transform parsed positionals tuple */
    positionals?: PositionalsTransformFn<TPositionalsIn, TPositionalsOut>;
    /** Transform parsed option values */
    values?: ValuesTransformFn<TValuesIn, TValuesOut>;
}
/**
 * Values transform function.
 *
 * @group Parser Types
 */
export type ValuesTransformFn<TIn, TOut> = (values: TIn) => Promise<TOut> | TOut;
/**
 * Variadic positional (rest args).
 *
 * @group Positional Types
 */
export interface VariadicPositional extends PositionalBase {
    items: 'number' | 'string';
    type: 'variadic';
}
/**
 * Base properties shared by all option definitions.
 */
interface OptionBase {
    /**
     * Short or long aliases for this option.
     *
     * - Single-character aliases (e.g., `'v'`) become short flags (`-v`)
     * - Multi-character aliases (e.g., `'verb'`) become long flags (`--verb`)
     *
     * @example
     *
     * ```typescript
     * opt.boolean({ aliases: ['v', 'verb'] }); // -v, --verb, --verbose
     * ```
     */
    aliases?: string[];
    /** Option description displayed in help text */
    description?: string;
    /** Group name for help text organization */
    group?: string;
    /** Whether this option is hidden from help */
    hidden?: boolean;
    /** Whether this option is required */
    required?: boolean;
}
/**
 * Base properties for positional definitions.
 */
interface PositionalBase {
    description?: string;
    /** Display name for help text (defaults to arg0, arg1, etc.) */
    name?: string;
    required?: boolean;
}
export {};
//# sourceMappingURL=types.d.ts.map