zod-args-parser 1.2.8 → 2.0.0-beta.0

package/lib/typescript/types/context-types.d.ts

@@ -0,0 +1,135 @@
+import type { Subcommand } from "./definitions-types.ts";
+import type { Argument, Option } from "./definitions-types.ts";
+import type { InferSchemaInputType, InferSchemaOutputType, SchemaType } from "./schema-types.ts";
+interface ContextBase<S extends SchemaType> {
+    /** The schema that validates this option. */
+    schema: S;
+    /** Whether the schema is optional. */
+    optional: boolean;
+    /** The default value of the schema, if any. */
+    defaultValue: InferSchemaOutputType<S> | undefined;
+}
+interface OptionContextCli<S extends SchemaType> extends ContextBase<S> {
+    /**
+     * The CLI flag as provided by the user (e.g. `--foo` or `-f`).
+     *
+     * **Note:** This is only defined when the source is `terminal`.
+     */
+    flag: string;
+    /**
+     * The raw string value provided directly from the CLI.
+     *
+     * **Note:** This is only defined when the source is `terminal`.
+     */
+    stringValue: string;
+    passedValue?: never;
+    /**
+     * The source of the option:
+     *
+     * - `terminal` — explicitly provided by the command-line interface.
+     * - `default` — not provided by the user; a default value from the schema was used.
+     * - `programmatic` — supplied directly from code (e.g., passed to a function or API).
+     */
+    source: "terminal";
+}
+interface OptionContextDefault<S extends SchemaType> extends ContextBase<S> {
+    flag?: never;
+    stringValue?: never;
+    passedValue?: never;
+    /**
+     * The source of the option:
+     *
+     * - `terminal` — explicitly provided by the command-line interface.
+     * - `default` — not provided by the user; a default value from the schema was used.
+     * - `programmatic` — supplied directly from code (e.g., passed to a function or API).
+     */
+    source: "default";
+}
+interface OptionContextProgrammatic<S extends SchemaType> extends ContextBase<S> {
+    flag?: never;
+    stringValue?: never;
+    /**
+     * The value passed programmatically.
+     *
+     * **NOTE:** This is only defined when the source is `programmatic`.
+     */
+    passedValue: InferSchemaInputType<S>;
+    /**
+     * The source of the option:
+     *
+     * - `terminal` — explicitly provided by the command-line interface.
+     * - `default` — not provided by the user; a default value from the schema was used.
+     * - `programmatic` — supplied directly from code (e.g., passed to a function or API).
+     */
+    source: "programmatic";
+}
+export type OptionContext<S extends SchemaType> = OptionContextCli<S> | OptionContextDefault<S> | OptionContextProgrammatic<S>;
+interface ArgumentContextCli<S extends SchemaType> extends ContextBase<S> {
+    /**
+     * The raw string value provided directly from the CLI.
+     *
+     * **Note:** This is only defined when the source is `terminal`.
+     */
+    stringValue: string;
+    passedValue?: never;
+    /**
+     * The source of the option:
+     *
+     * - `terminal` — explicitly provided by the command-line interface.
+     * - `default` — not provided by the user; a default value from the schema was used.
+     * - `programmatic` — supplied directly from code (e.g., passed to a function or API).
+     */
+    source: "terminal";
+}
+interface ArgumentContextDefault<S extends SchemaType> extends ContextBase<S> {
+    stringValue?: never;
+    passedValue?: never;
+    /**
+     * The source of the option:
+     *
+     * - `terminal` — explicitly provided by the command-line interface.
+     * - `default` — not provided by the user; a default value from the schema was used.
+     * - `programmatic` — supplied directly from code (e.g., passed to a function or API).
+     */
+    source: "default";
+}
+interface ArgumentContextProgrammatic<S extends SchemaType> extends ContextBase<S> {
+    stringValue?: never;
+    /**
+     * The value passed programmatically.
+     *
+     * **NOTE:** This is only defined when the source is `programmatic`.
+     */
+    passedValue: InferSchemaInputType<S>;
+    /**
+     * The source of the option:
+     *
+     * - `terminal` — explicitly provided by the command-line interface.
+     * - `default` — not provided by the user; a default value from the schema was used.
+     * - `programmatic` — supplied directly from code (e.g., passed to a function or API).
+     */
+    source: "programmatic";
+}
+export type ArgumentContext<S extends SchemaType> = ArgumentContextCli<S> | ArgumentContextDefault<S> | ArgumentContextProgrammatic<S>;
+type OptionsRecordToOptionContext<T extends Record<string, Option>> = {
+    [K in keyof T]: OptionContext<T[K]["schema"]>;
+};
+type ArgumentsRecordToArgumentContext<T extends Record<string, Argument>> = {
+    [K in keyof T]: ArgumentContext<T[K]["schema"]>;
+};
+export type Context<S extends readonly Partial<Subcommand>[]> = {
+    [K in keyof S]: {
+        subcommand: S[K]["name"] extends string ? S[K]["name"] : undefined;
+        options: S[K]["options"] extends Record<string, Option> ? OptionsRecordToOptionContext<S[K]["options"]> : never;
+        arguments: S[K]["arguments"] extends Record<string, Argument> ? ArgumentsRecordToArgumentContext<S[K]["arguments"]> : never;
+        positionals: S[K]["allowPositionals"] extends true ? string[] : never;
+    };
+}[number];
+export interface ContextWide {
+    subcommand: string | undefined;
+    options?: Record<string, OptionContext<SchemaType>>;
+    arguments?: Record<string, ArgumentContext<SchemaType>>;
+    positionals?: string[];
+}
+export {};
+//# sourceMappingURL=context-types.d.ts.map

package/lib/typescript/types/context-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-types.d.ts","sourceRoot":"","sources":["../../../src/types/context-types.ts"],"names":[],"mappings":"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"}

package/lib/typescript/types/definitions-types.d.ts

@@ -0,0 +1,294 @@
+import type { OutputTypeWide } from "./io-types.ts";
+import type { InferSchemaOutputType, SchemaResult, SchemaType } from "./schema-types.ts";
+import type { CoerceMethod, CoerceTypes } from "./types.ts";
+import type { Widen } from "./utilities-types.ts";
+export interface PreparedType {
+    schema: SchemaType;
+    coerceTo: CoerceTypes | undefined;
+    optional: boolean;
+    defaultValue: unknown;
+    validate: (value: string | undefined) => SchemaResult;
+}
+/** `schema` (generic) with required `coerce` */
+interface RequiredCoerce<Schema extends SchemaType> {
+    schema: Schema;
+    coerce: CoerceMethod<Widen<InferSchemaOutputType<Schema>>>;
+}
+/** `schema` (string) with optional `coerce` */
+interface OptionalCoerce {
+    schema: SchemaType<string | undefined>;
+    coerce?: CoerceMethod<string | undefined>;
+}
+export interface Cli extends Omit<Subcommand, "name" | "aliases" | "meta"> {
+    /** The name of the CLI program (main command). */
+    cliName: string;
+    /** Array of subcommands. Do not pass them directly instead use `defineSubcommand` */
+    subcommands?: [Subcommand, ...Subcommand[]];
+    /** The metadata for the CLI. */
+    meta?: Omit<SubcommandMeta, "placeholder" | "hidden">;
+}
+interface MetaBase {
+    /**
+     * Short explanation.
+     *
+     * Supports multi-line text and ansi color styles (like `chalk`).
+     *
+     * **NOTE:** For terminal markdown, use `descriptionMarkdown` instead.
+     */
+    description?: string;
+    /**
+     * Enables Markdown formatting for terminal output and generated documentation.
+     *
+     * Most common Markdown features (headings, lists, code, links, etc.) are supported when displayed in a terminal.
+     *
+     * **Terminal help output**
+     *
+     * - If both `description` and `descriptionMarkdown` are provided, only `description` is shown.
+     *
+     * **Markdown file generation**
+     *
+     * - If both fields are provided, only `descriptionMarkdown` is used.
+     */
+    descriptionMarkdown?: string;
+    /**
+     * Example to shown to the user.
+     *
+     * - In markdown, this will be displayed inside a code block.
+     */
+    example?: string;
+    /** Hide this argument from being documented (help message / markdown). This is useful for internal use. */
+    hidden?: boolean;
+}
+interface SubcommandMeta extends MetaBase {
+    /** Text to display as a placeholder for the expected arguments (e.g. `[options] <arg1> <arg2>`). */
+    placeholder?: string;
+    /** E.g. `cliName subcommand [options] <arg1> <arg2>` */
+    usage?: string;
+}
+export interface Subcommand {
+    /**
+     * The subcommand name
+     *
+     * - Make sure there are no duplicates across names and aliases in the same CLI.
+     *
+     * @example
+     *   name: "test-app";
+     *   name: "run-app";
+     */
+    name: string;
+    /**
+     * A list of aliases that can be used to invoke this subcommand.
+     *
+     * **NOTE:** Make sure there are no duplicates across names and aliases in the same CLI.
+     *
+     * @example
+     *   name: "test-app";
+     *   aliases: ["test"];
+     *
+     *   name: "run-app";
+     *   aliases: ["run"];
+     */
+    aliases?: string[];
+    /**
+     * - Allows positionals arguments for this subcommand.
+     * - Unlike `arguments`, which are strictly typed tuples, positionals arguments are untyped and represented as a string
+     *   array of variable length.
+     * - When enabled and typed `arguments` are provided, `arguments` will be parsed first. Any remaining arguments will be
+     *   considered positionals arguments and added to the `positionals` property in the result.
+     */
+    allowPositionals?: boolean;
+    /**
+     * For the option name (the key), use a valid **JavaScript** variable name.\
+     * **Supports:** `camelCase`, `PascalCase`, `snake_case`, and `SCREAMING_SNAKE_CASE`.\
+     * **Examples:**
+     *
+     * - `I` or `i` => `-i`
+     * - `InputDir`, `inputDir`, or `INPUT_DIR` => `--input-dir`
+     * - `Help`, `help`, or `HELP` => `--help`
+     */
+    options?: Record<string, Option>;
+    /**
+     * - Specifies a list of strictly typed arguments.
+     * - The order is important; for example, the first argument will be validated against the first specified type.
+     * - When **`allowPositional`** is **disabled**, the last argument can be optional.
+     * - When **`allowPositional`** is **enabled**, no optional arguments are allowed.
+     *
+     * **IMPORTANT:** The order of arguments matters!
+     */
+    arguments?: Record<string, Argument>;
+    /** Metadata used for help messages and documentation generation */
+    meta?: SubcommandMeta;
+    /**
+     * - A list of functions to execute when the subcommand/CLI is executed.
+     * - Do not use this directly instead use `onExecute` after creating the subcommand/cli.
+     *
+     * @deprecated For internal use only
+     * @example
+     *   const helpCommand = defineSubcommand({ name: "help", options: [...] });
+     *   helpCommand.onExecute((result) => console.log(result));
+     *
+     *   const myCli = defineCLI({ name: "my-cli", subcommands: [helpCommand] });
+     *   myCli.onExecute((result) => console.log(result));
+     */
+    _onExecute?: ((result: OutputTypeWide) => void)[];
+}
+interface OptionMeta extends MetaBase {
+    /** Text to display as a placeholder for the expected value (e.g. `<path>`, `<value>`). */
+    placeholder?: string;
+    /**
+     * Custom default value.
+     *
+     * - Use an empty string to intentionally show no default.
+     */
+    default?: string;
+    /** Override whether this option is considered optional. */
+    optional?: boolean;
+}
+interface OptionBase {
+    /**
+     * For the option alias, use a valid **JavaScript** variable name.\
+     * **Supports:** `camelCase`, `PascalCase`, `snake_case`, and `SCREAMING_SNAKE_CASE`.\
+     * **Examples:**
+     *
+     * - `I` or `i` => `-i`
+     * - `InputDir`, `inputDir`, or `INPUT_DIR` => `--input-dir`
+     * - `Help`, `help`, or `HELP` => `--help`
+     */
+    aliases?: string[];
+    /**
+     * When `true`, this option must appear on its own. It cannot be used together with any other option or argument,
+     * except those explicitly listed in `requires`.
+     *
+     * Only explicitly provided inputs are checked — options or arguments that are present only through default values are
+     * ignored.
+     *
+     * @example
+     *   defineOptions({
+     *     // nothing else can be used with this option (no other options or arguments)
+     *     output: {
+     *       exclusive: true,
+     *     },
+     *   });
+     *
+     *   defineOptions({
+     *     // only `input` (could be an option or argument name) can be used with this option
+     *     output: {
+     *       exclusive: true,
+     *       requires: ["input"],
+     *     },
+     *   });
+     */
+    exclusive?: boolean;
+    /**
+     * Declares other options ir arguments that must be provided when this option is used.
+     *
+     * If this option appears in the parsed input, each entry listed in `requires` must also be present. Default values do
+     * not satisfy this requirement — the user must explicitly provide the required option(s).
+     *
+     * Example:
+     *
+     * @example
+     *   defineOptions({
+     *     // using the option `output` also requires `input` (could be an option or argument name)
+     *     output: {
+     *       requires: ["input"],
+     *     },
+     *   });
+     */
+    requires?: string[];
+    /**
+     * Declares options or arguments that conflict with this option.
+     *
+     * If any entry in `conflictWith` is provided alongside this option, the parser will report an error. Conflicts are
+     * only checked against explicitly supplied values — defaults do not trigger conflicts.
+     *
+     * @example
+     *   defineOptions({
+     *     // the option `help` cannot be used together with `version` (could be an option or argument name)
+     *     help: {
+     *       conflictWith: ["version"],
+     *     },
+     *   });
+     */
+    conflictWith?: string[];
+    /** Used for help message and documentation generation. */
+    meta?: OptionMeta;
+    /** @deprecated For internal use only */
+    _preparedType?: PreparedType;
+}
+export type Option<Schema extends SchemaType = SchemaType> = (OptionBase & RequiredCoerce<Schema>) | (OptionBase & OptionalCoerce);
+interface ArgumentMeta extends MetaBase {
+    /** Override the argument name in the help message and documentation. */
+    name?: string;
+    /**
+     * Custom default value.
+     *
+     * Use an empty string to intentionally show no default.
+     */
+    default?: string;
+    /** Override whether this option is considered optional. */
+    optional?: boolean;
+}
+interface ArgumentBase {
+    /**
+     * When `true`, this argument must appear on its own. It cannot be used together with any other option or argument,
+     * except those explicitly listed in `requires`.
+     *
+     * Only explicitly provided inputs are checked — options or arguments that are present only through default values are
+     * ignored.
+     *
+     * @example
+     *   defineArguments({
+     *     // nothing else can be used with this argument (no other options or arguments)
+     *     output: {
+     *       exclusive: true,
+     *     },
+     *   });
+     *
+     *   defineArguments({
+     *     // only `input` (could be an option or argument name) can be used with this argument
+     *     output: {
+     *       exclusive: true,
+     *       requires: ["input"],
+     *     },
+     *   });
+     */
+    exclusive?: boolean;
+    /**
+     * Declares other options/arguments that must be provided when this argument is used.
+     *
+     * If this argument appears in the parsed input, each entry listed in `requires` must also be present. Default values
+     * do not satisfy this requirement — the user must explicitly provide the required option(s).
+     *
+     * @example
+     *   defineArguments({
+     *     // using the argument `output` also requires `input` (could be an option or argument name)
+     *     output: {
+     *       requires: ["input"],
+     *     },
+     *   });
+     */
+    requires?: string[];
+    /**
+     * Declares options or arguments that conflict with this argument.
+     *
+     * If any entry in `conflictWith` is provided alongside this argument, the parser will report an error. Conflicts are
+     * only checked against explicitly supplied values — defaults do not trigger conflicts.
+     *
+     * @example
+     *   defineArguments({
+     *     // the argument `help` cannot be used together with `version` (could be an option or argument name)
+     *     help: {
+     *       conflictWith: ["version"],
+     *     },
+     *   });
+     */
+    conflictWith?: string[];
+    /** Used for help message and documentation generation. */
+    meta?: ArgumentMeta;
+    /** @deprecated For internal use only */
+    _preparedType?: PreparedType;
+}
+export type Argument<Schema extends SchemaType = SchemaType> = (ArgumentBase & RequiredCoerce<Schema>) | (ArgumentBase & OptionalCoerce);
+export {};
+//# sourceMappingURL=definitions-types.d.ts.map

package/lib/typescript/types/definitions-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"definitions-types.d.ts","sourceRoot":"","sources":["../../../src/types/definitions-types.ts"],"names":[],"mappings":"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"}

package/lib/typescript/types/help-message-types.d.ts

@@ -0,0 +1,134 @@
+export interface PrintHelpOptions {
+    /** The style to use for the help message. */
+    style?: Partial<HelpMessageStyleImpl>;
+    /**
+     * Whether to transform the argument (not option) name to kebab case.
+     *
+     * @default true
+     */
+    kebabCaseArgumentName?: boolean;
+    /**
+     * The renderer to use for the markdown.
+     *
+     * @default terminal
+     */
+    markdownRenderer?: "terminal" | "html";
+    /**
+     * The number of spaces to put before the name of (option/argument/subcommand).
+     *
+     * @default 2
+     */
+    indentBeforeName?: number;
+    /**
+     * The number of spaces to put after the name of (option/argument/subcommand), between the name and the description
+     * (space between columns).
+     *
+     * @default 4
+     */
+    indentAfterName?: number;
+    /**
+     * The number of spaces to put before the placeholder.
+     *
+     * @default 1
+     */
+    indentBeforePlaceholder?: number;
+    /**
+     * The number of spaces to put before a new line:
+     *
+     * - Description new lines.
+     * - Example under description.
+     *
+     * @default 0
+     */
+    newLineIndent?: number;
+    /**
+     * The number of empty lines to put between lines.
+     *
+     * @default 0
+     */
+    emptyLines?: number;
+    /**
+     * The number of empty lines to put before the title.
+     *
+     * @default 1
+     */
+    emptyLinesBeforeTitle?: number;
+    /**
+     * The number of empty lines to put after the title.
+     *
+     * @default 0
+     */
+    emptyLinesAfterTitle?: number;
+    /**
+     * The keyword to use for the example.
+     *
+     * @default "Example:"
+     */
+    exampleKeyword?: string;
+    /**
+     * The keyword to use for the optional.
+     *
+     * @default "(optional)"
+     */
+    optionalKeyword?: string;
+    /**
+     * The keyword to use for the default. where `{{ value }}` will be replaced with the default value.
+     *
+     * @default "(default: {{ value }})"
+     */
+    defaultKeyword?: string;
+    /**
+     * The title to use for the usage.
+     *
+     * @default "USAGE"
+     */
+    usageTitle?: string;
+    /**
+     * The title to use for the description.
+     *
+     * @default "DESCRIPTION"
+     */
+    descriptionTitle?: string;
+    /**
+     * The title to use for the commands.
+     *
+     * @default "COMMANDS"
+     */
+    commandsTitle?: string;
+    /**
+     * The title to use for the options.
+     *
+     * @default "OPTIONS"
+     */
+    optionsTitle?: string;
+    /**
+     * The title to use for the arguments.
+     *
+     * @default "ARGUMENTS"
+     */
+    argumentsTitle?: string;
+    /**
+     * The title to use for the examples.
+     *
+     * @default "EXAMPLE"
+     */
+    exampleTitle?: string;
+}
+export interface ColorFunctionType {
+    (...text: unknown[]): string;
+}
+/** - The colors to use for the help message. */
+export interface HelpMessageStyleImpl {
+    title: ColorFunctionType;
+    description: ColorFunctionType;
+    default: ColorFunctionType;
+    optional: ColorFunctionType;
+    exampleTitle: ColorFunctionType;
+    example: ColorFunctionType;
+    command: ColorFunctionType;
+    option: ColorFunctionType;
+    argument: ColorFunctionType;
+    placeholder: ColorFunctionType;
+    punctuation: ColorFunctionType;
+}
+//# sourceMappingURL=help-message-types.d.ts.map

package/lib/typescript/types/help-message-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"help-message-types.d.ts","sourceRoot":"","sources":["../../../src/types/help-message-types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,gBAAgB;IAC/B,6CAA6C;IAC7C,KAAK,CAAC,EAAE,OAAO,CAAC,oBAAoB,CAAC,CAAC;IAEtC;;;;OAIG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAEhC;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,UAAU,GAAG,MAAM,CAAC;IAEvC;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B;;;;;OAKG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IAEzB;;;;OAIG;IACH,uBAAuB,CAAC,EAAE,MAAM,CAAC;IAEjC;;;;;;;OAOG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;;OAIG;IACH,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAE/B;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAE9B;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IAEzB;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,iBAAiB;IAChC,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,MAAM,CAAC;CAC9B;AAED,gDAAgD;AAChD,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,iBAAiB,CAAC;IACzB,WAAW,EAAE,iBAAiB,CAAC;IAC/B,OAAO,EAAE,iBAAiB,CAAC;IAC3B,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,YAAY,EAAE,iBAAiB,CAAC;IAChC,OAAO,EAAE,iBAAiB,CAAC;IAC3B,OAAO,EAAE,iBAAiB,CAAC;IAC3B,MAAM,EAAE,iBAAiB,CAAC;IAC1B,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,WAAW,EAAE,iBAAiB,CAAC;IAC/B,WAAW,EAAE,iBAAiB,CAAC;CAChC"}

package/lib/typescript/types/io-types.d.ts

@@ -0,0 +1,96 @@
+import type { Context, ContextWide } from "./context-types.ts";
+import type { Argument, Cli, Option, Subcommand } from "./definitions-types.ts";
+import type { InferSchemaInputType, InferSchemaOutputType } from "./schema-types.ts";
+import type { Prettify, ToOptional, AllowUndefinedIfOptional as AddUndefinedIfAllOptional } from "./utilities-types.ts";
+/** Output options type */
+type OptionsOutputType<T extends Record<string, Option>> = Prettify<ToOptional<{
+    [K in keyof T]: InferSchemaOutputType<T[K]["schema"]>;
+}>>;
+/** Input options type */
+type OptionsInputType<T extends Record<string, Option>> = Prettify<ToOptional<{
+    [K in keyof T]: InferSchemaInputType<T[K]["schema"]>;
+}>>;
+/** Output arguments type */
+type ArgumentsOutputType<T extends Record<string, Argument>> = Prettify<ToOptional<{
+    [K in keyof T]: InferSchemaOutputType<T[K]["schema"]>;
+}>>;
+/** Input arguments type */
+type ArgumentsInputType<T extends Record<string, Argument>> = Prettify<ToOptional<{
+    [K in keyof T]: InferSchemaInputType<T[K]["schema"]>;
+}>>;
+/**
+ * - Infer options output type.
+ *
+ * @example
+ *   const myCommand = defineSubcommand({ name: "my-command", options: [...] });
+ *   type MyCommandOptionsOutput = InferOptionsOutputType<typeof myCommand>;
+ */
+export type InferOptionsOutputType<T extends Cli | Subcommand> = T["options"] extends Record<string, Option> ? OptionsOutputType<T["options"]> : undefined;
+/**
+ * - Infer arguments output type.
+ *
+ * @example
+ *   const myCommand = defineSubcommand({ name: "my-command", arguments: [...] });
+ *   type MyCommandArgumentsOutput = InferArgumentsOutputType<typeof myCommand>;
+ */
+export type InferArgumentsOutputType<T extends Cli | Subcommand> = T["arguments"] extends Record<string, Argument> ? ArgumentsOutputType<T["arguments"]> : undefined;
+/**
+ * - Infer arguments input type.
+ *
+ * @example
+ *   const myCommand = defineSubcommand({ name: "my-command", arguments: [...] });
+ *   type MyCommandArgumentsInput = InferArgumentsInputType<typeof myCommand>;
+ */
+export type InferArgumentsInputType<T extends Cli | Subcommand> = T["arguments"] extends Record<string, Argument> ? ArgumentsInputType<T["arguments"]> : undefined;
+/**
+ * - Infer options input type.
+ *
+ * @example
+ *   const myCommand = defineSubcommand({ name: "my-command", options: [...] });
+ *   type MyCommandOptionsInput = inferOptionsInputType<typeof myCommand>;
+ */
+export type inferOptionsInputType<T extends Cli | Subcommand> = T["options"] extends Record<string, Option> ? OptionsInputType<T["options"]> : undefined;
+/**
+ * - Infer options, arguments, and positionals input types from the CLI/subcommand definition.
+ *
+ * @example
+ *   const myCommand = defineSubcommand({ name: "my-command", ... });
+ *   type MyCommandInput = InferInputType<typeof myCommand>;
+ */
+export type InferInputType<T extends Cli | Subcommand> = Prettify<AddUndefinedIfAllOptional<ToOptional<{
+    positionals: T["allowPositionals"] extends true ? string[] : undefined;
+    options: T["options"] extends Record<string, Option> ? AddUndefinedIfAllOptional<OptionsInputType<T["options"]>> : undefined;
+    arguments: T["arguments"] extends Record<string, Argument> ? AddUndefinedIfAllOptional<ArgumentsInputType<T["arguments"]>> : undefined;
+}>>>;
+export interface InputTypeWide {
+    arguments?: Record<string, unknown>;
+    options?: Record<string, unknown>;
+    positionals?: string[];
+}
+/**
+ * - Infer schema output type.
+ *
+ * @example
+ *   const myCommand = defineSubcommand({ name: "my-command", ... });
+ *   type MyCommandOutput = InferOutputType<typeof myCommand>;
+ */
+export type InferOutputType<T extends Cli | Subcommand> = Prettify<{
+    subcommand: "name" extends keyof T ? T["name"] : undefined;
+    options: T["options"] extends Record<string, Option> ? OptionsOutputType<T["options"]> : never;
+    arguments: T["arguments"] extends Record<string, Argument> ? ArgumentsOutputType<T["arguments"]> : never;
+    positionals: T["allowPositionals"] extends true ? string[] : never;
+    context: Context<[T]>;
+}>;
+/** Same as `InferOutputType` but for multiple subcommands/cli */
+export type OutputType<S extends readonly (Cli | Subcommand)[]> = {
+    [K in keyof S]: InferOutputType<S[K]>;
+}[number];
+export interface OutputTypeWide {
+    subcommand: string | undefined;
+    positionals?: string[];
+    arguments?: Record<string, unknown>;
+    options?: Record<string, unknown>;
+    context: ContextWide;
+}
+export {};
+//# sourceMappingURL=io-types.d.ts.map