zod-args-parser 2.0.0-alpha.0 → 2.0.0-beta.1

package/src/metadata/metadata-types.ts

@@ -1,114 +0,0 @@
-import type { Schema } from "../types.js";
-
-export interface CliMetadata {
-  /** The name of the cli program. */
-  readonly name: string;
-
-  /** - The description of the cli program. Empty string if not provided */
-  readonly description: string;
-
-  /** - The usage of the cli program. Empty string if not provided */
-  readonly usage: string;
-
-  /** - The example of the cli program. Empty string if not provided */
-  readonly example: string;
-
-  /** - Whether the cli program allows positional arguments. */
-  readonly allowPositional: boolean;
-
-  /** - The options of the cli program. Empty array if not provided */
-  readonly options: OptionMetadata[];
-
-  /** - The arguments of the cli program. Empty array if not provided */
-  readonly arguments: ArgumentMetadata[];
-
-  /** - The subcommands of the cli program. Empty array if not provided */
-  readonly subcommands: SubcommandMetadata[];
-}
-
-export interface SubcommandMetadata {
-  /** The subcommand name. */
-  readonly name: string;
-
-  /** - The aliases of the subcommand. Empty array if not provided */
-  readonly aliases: string[];
-
-  /** - The description of the subcommand. Empty string if not provided */
-  readonly description: string;
-
-  /** - The placeholder of the subcommand. Empty string if not provided */
-  readonly placeholder: string;
-
-  /** - The usage of the subcommand. Empty string if not provided */
-  readonly usage: string;
-
-  /** - The example of the subcommand. Empty string if not provided */
-  readonly example: string;
-
-  /** - Whether the subcommand allows positional arguments. */
-  readonly allowPositional: boolean;
-
-  /** - The options of the subcommand. Empty array if not provided */
-  readonly options: OptionMetadata[];
-
-  /** - The arguments of the subcommand. Empty array if not provided */
-  readonly arguments: ArgumentMetadata[];
-}
-
-export interface OptionMetadata {
-  /** The option name in camelCase. E.g. `optionName` */
-  readonly name: string;
-
-  /** The option name in kebab-case. E.g. `--option-name` */
-  readonly nameAsArg: string;
-
-  /** - The aliases of the option in camelCase. Empty array if not provided. E.g. `[aliasName, ...]` */
-  readonly aliases: string[];
-
-  /** - The aliases of the option in kebab-case. Empty array if not provided. E.g. `[--alias-name, ...]` */
-  readonly aliasesAsArgs: string[];
-
-  /** - The description of the option. Empty string if not provided */
-  readonly description: string;
-
-  /** - The placeholder of the option. Empty string if not provided */
-  readonly placeholder: string;
-
-  /** - The example of the option. Empty string if not provided */
-  readonly example: string;
-
-  /** - The default value of the option. */
-  readonly defaultValue: unknown;
-
-  /** - The default value of the option as string. */
-  readonly defaultValueAsString: string;
-
-  /** - Whether the option is optional. */
-  readonly optional: boolean;
-
-  /** - The zod type of the option. */
-  readonly type: Schema;
-}
-
-export interface ArgumentMetadata {
-  /** The argument name. */
-  readonly name: string;
-
-  /** - The description of the argument. Empty string if not provided */
-  readonly description: string;
-
-  /** - The example of the argument. Empty string if not provided */
-  readonly example: string;
-
-  /** - The default value of the argument. */
-  readonly defaultValue: unknown;
-
-  /** - The default value of the argument as string. */
-  readonly defaultValueAsString: string;
-
-  /** - Whether the argument is optional. */
-  readonly optional: boolean;
-
-  /** - The zod type of the argument. */
-  readonly type: Schema;
-}

package/src/parser/parse/parse-types.ts

@@ -1,89 +0,0 @@
-import type { Argument, Option, Prettify, Schema, Subcommand } from "../../types.js";
-
-type ParsedOption<S extends Schema = Schema, N extends string = string> =
-  | {
-      /** The name of the option as provided by the user. */
-      name: N;
-      /** The CLI flag as provided by the user (e.g. `--foo` or `-f`). */
-      flag: string;
-      /** The schema that validates this option. */
-      schema: S;
-      /** The raw string value supplied for this option from the CLI. */
-      rawValue: string;
-      /**
-       * The source of the option:
-       *
-       * - `cli`: provided explicitly in the CLI
-       * - `default`: not provided, and the schema has a default.
-       */
-      source: "cli";
-    }
-  | {
-      /** The name of the option as provided by the user. */
-      name: N;
-      /** Undefined when the source is `default`. */
-      flag?: never;
-      /** The schema that validates this option. */
-      schema: S;
-      /** Undefined when the source is `default`. */
-      rawValue?: string | undefined;
-      /**
-       * The source of the option:
-       *
-       * - `cli`: provided explicitly in the CLI
-       * - `default`: not provided, and the schema has a default.
-       */
-      source: "default";
-    };
-
-type ParsedArgument<S extends Schema = Schema> =
-  | {
-      /** The raw string value provided directly from the CLI. */
-      rawValue: string;
-      /** The schema that validates this argument. */
-      schema: S;
-      /**
-       * The source of the option:
-       *
-       * - `cli`: provided explicitly in the CLI
-       * - `default`: not provided, and the schema has a default.
-       */
-      source: "cli";
-    }
-  | {
-      /** Undefined when the source is `default`. */
-      rawValue?: never;
-      /** The schema that validates this argument. */
-      schema: S;
-      /**
-       * The source of the option:
-       *
-       * - `cli`: provided explicitly in the CLI
-       * - `default`: not provided, and the schema has a default.
-       */
-      source: "default";
-    };
-
-type OptionsArray2Record<T extends Option[] | undefined> = T extends Option[]
-  ? { [K in T[number]["name"]]: ParsedOption<Extract<T[number], { name: K }>["type"], K> }
-  : Record<never, never>;
-
-type ArgumentsArray2ArrayType<T extends Argument[] | undefined> = T extends Argument[]
-  ? { [K in keyof T]: ParsedArgument<T[K] extends { type: Schema } ? T[K]["type"] : never> }
-  : never;
-
-export type ParseResult<S extends Partial<Subcommand>[]> = {
-  [K in keyof S]: Prettify<{
-    subcommand: S[K]["name"] extends string ? S[K]["name"] : undefined;
-    positional: S[K]["allowPositional"] extends true ? string[] : never;
-    options: S[K]["options"] extends Option[] ? OptionsArray2Record<S[K]["options"]> : never;
-    arguments: ArgumentsArray2ArrayType<S[K]["arguments"]>;
-  }>;
-}[number];
-
-export type ParsedContext = {
-  subcommand: string | undefined;
-  options?: Record<string, ParsedOption>;
-  arguments?: ParsedArgument[];
-  positional?: string[];
-};

package/src/parser/parse/parse.ts

@@ -1,235 +0,0 @@
-import { generateOrdinalSuffix } from "../../utilities.js";
-import { isBooleanSchema, isOptionalSchema, schemaDefaultValue } from "../../zod-utilities.js";
-import {
-  decoupleFlags,
-  findOption,
-  findSubcommand,
-  isFlagArgument,
-  isOptionArgument,
-  transformOptionToArgument,
-} from "./parser-helpers.js";
-
-import type { Cli, Subcommand } from "../../types.js";
-import type { ParsedContext } from "./parse-types.js";
-
-export function parse(argv: string[], ...parameters: [Cli, ...Subcommand[]]) {
-  const subcommandArray = parameters as Subcommand[];
-  const allSubcommands = new Set<string>(subcommandArray.flatMap(c => [c.name, ...(c.aliases || [])]));
-
-  argv = decoupleFlags(argv); // decouple flags E.g. `-rf` -> `-r, -f`
-
-  const results: ParsedContext = {
-    subcommand: undefined,
-  };
-
-  /** - Get current subcommand object */
-  const getSubcommandObject = () => findSubcommand(results.subcommand, subcommandArray);
-
-  for (let index = 0; index < argv.length; index++) {
-    const argument_ = argv[index];
-
-    // * Subcommand check
-    if (index === 0) {
-      results.subcommand = allSubcommands.has(argument_) ? argument_ : undefined;
-
-      // First argument is a subcommand. Skip to the next argument
-      if (results.subcommand) continue;
-    }
-
-    // * Option check
-
-    // Check for `--option=value` or `--option value`
-    const argumentAndValue = argument_.split("=").filter(Boolean);
-    const argumentWithEquals = argument_.includes("=");
-    const argument = argumentAndValue[0];
-    const argumentValue: string | undefined = argumentAndValue[1];
-
-    if (isOptionArgument(argument)) {
-      if (isFlagArgument(argument) && argumentWithEquals) {
-        throw new Error(`Flag arguments cannot be assigned using "=": "${argument_}"`, { cause: "zod-args-parser" });
-      }
-
-      const subcommandObject = getSubcommandObject();
-      if (!subcommandObject) {
-        throw new Error(`Unknown subcommand: "${results.subcommand}"`, { cause: "zod-args-parser" });
-      }
-
-      if (!subcommandObject.options) {
-        if (!results.subcommand) {
-          throw new Error(`Error: options are not allowed here: "${argument}"`, { cause: "zod-args-parser" });
-        }
-
-        throw new Error(`Error: subcommand "${results.subcommand}" does not allow options: "${argument}"`, {
-          cause: "zod-args-parser",
-        });
-      }
-
-      const option = findOption(argument, subcommandObject.options);
-      if (!option) {
-        throw new Error(`Unknown option: "${argument}"`, { cause: "zod-args-parser" });
-      }
-
-      if (results.options && option.name in results.options) {
-        throw new Error(`Duplicated option: "${argument}"`, { cause: "zod-args-parser" });
-      }
-
-      const isTypeBoolean = isBooleanSchema(option.type);
-      const nextArgument = argv[index + 1];
-
-      let optionValue: string | boolean = argumentWithEquals ? argumentValue : nextArgument;
-
-      // infer value for boolean options
-      if (isTypeBoolean && !argumentWithEquals) {
-        optionValue = "true";
-      }
-
-      if (optionValue === undefined) {
-        throw new Error(`Expected a value for "${argument}" but got nothing`, { cause: "zod-args-parser" });
-      }
-
-      if (!argumentWithEquals && isOptionArgument(optionValue)) {
-        throw new Error(`Expected a value for "${argument}" but got an argument "${nextArgument}"`, {
-          cause: "zod-args-parser",
-        });
-      }
-
-      if (!results.options) {
-        results.options = {};
-      }
-
-      results.options[option.name] = {
-        name: option.name,
-        schema: option.type,
-        flag: argument,
-        rawValue: optionValue.toString(),
-        source: "cli",
-      };
-
-      // Skip to the next argument if it is the current option’s value.
-      if (!argumentWithEquals && !isTypeBoolean) {
-        index++;
-      }
-
-      continue;
-    }
-
-    const subcommandObject = getSubcommandObject();
-
-    // * Arguments check
-    if (subcommandObject?.arguments) {
-      if (!results.arguments) {
-        results.arguments = [];
-      }
-
-      const currentArgumentCount = results.arguments.length;
-
-      // Any extra arguments are possibly positional
-      if (currentArgumentCount < subcommandObject.arguments.length) {
-        const argumentType = subcommandObject.arguments[currentArgumentCount].type;
-        results.arguments.push({
-          schema: argumentType,
-          rawValue: argument_,
-          source: "cli",
-        });
-        continue;
-      }
-    }
-
-    // * Positional check
-    if (subcommandObject?.allowPositional) {
-      if (!results.positional) {
-        results.positional = [];
-      }
-
-      results.positional.push(argument_);
-      continue;
-    }
-
-    // * Unexpected
-    if (!results.subcommand) {
-      throw new Error(`Unexpected argument "${argument_}": positional arguments are not allowed here`, {
-        cause: "zod-args-parser",
-      });
-    }
-
-    throw new Error(
-      `Unexpected argument "${argument_}": positional arguments are not allowed for subcommand "${results.subcommand}"`,
-      { cause: "zod-args-parser" },
-    );
-  }
-
-  // * Check for missing options - set defaults - add `source`
-  const subcommandObject = getSubcommandObject();
-  if (!subcommandObject) {
-    throw new Error(`Unknown subcommand: "${results.subcommand}"`, { cause: "zod-args-parser" });
-  }
-
-  // Options
-  if (subcommandObject.options) {
-    if (!results.options) {
-      results.options = {};
-    }
-
-    for (const option of subcommandObject.options) {
-      // option already exists
-      if (results.options && option.name in results.options) continue;
-
-      const optional = isOptionalSchema(option.type);
-      const defaultValue = schemaDefaultValue(option.type);
-
-      if (optional) {
-        if (defaultValue === undefined) {
-          continue;
-        }
-
-        results.options[option.name] = { name: option.name, schema: option.type, source: "default" };
-        continue;
-      }
-
-      throw new Error(`Missing required option: ${transformOptionToArgument(option.name)}`, {
-        cause: "zod-args-parser",
-      });
-    }
-  }
-
-  // Arguments
-  if (subcommandObject.arguments) {
-    if (!results.arguments) {
-      results.arguments = [];
-    }
-
-    const currentArgumentCount = results.arguments.length ?? 0;
-    const subcommandArgumentCount = subcommandObject.arguments.length;
-
-    // missing arguments
-    if (currentArgumentCount < subcommandArgumentCount) {
-      for (let index = currentArgumentCount; index < subcommandArgumentCount; index++) {
-        const argumentType = subcommandObject.arguments[index].type;
-        const optional = isOptionalSchema(argumentType);
-        const defaultValue = schemaDefaultValue(argumentType);
-
-        if (optional) {
-          if (defaultValue === undefined) {
-            continue;
-          }
-
-          if (!results.arguments) results.arguments = [];
-
-          results.arguments.push({ schema: argumentType, source: "default" });
-          continue;
-        }
-
-        throw new Error(
-          `the ${generateOrdinalSuffix(index)} argument is required: "${subcommandObject.arguments[index].name}"`,
-          { cause: "zod-args-parser" },
-        );
-      }
-    }
-  }
-
-  if (subcommandObject.allowPositional && !results.positional) {
-    results.positional = [];
-  }
-
-  return results;
-}

package/src/parser/safe-parse.ts

@@ -1,103 +0,0 @@
-import * as help from "../help-message/format-cli.js";
-import { findSubcommand } from "./parse/parser-helpers.js";
-import { unsafeParse, unsafeParseAsync } from "./unsafe-parse.js";
-
-import type { Cli, NoSubcommand, PrintMethods, SafeParseResult, Subcommand } from "../types.js";
-
-export function safeParse<T extends Subcommand[], U extends Cli>(
-  argsv: string[],
-  ...parameters: [U, ...T]
-): SafeParseResult<[...T, NoSubcommand & U]> {
-  const cliOptions = ("cliName" in parameters[0] ? parameters[0] : {}) as U;
-  const subcommandArray = parameters as Subcommand[];
-
-  type PrintTypes = PrintMethods<T[number]["name"]>;
-  type PrintCli = PrintTypes["printCliHelp"];
-  type PrintSubcommand = PrintTypes["printSubcommandHelp"];
-
-  const printCliHelp: PrintCli = style => help.printCliHelp(parameters, style);
-
-  const printSubcommandHelp: PrintSubcommand = (subCmdName, style) => {
-    const subcommand = findSubcommand(subCmdName, subcommandArray);
-    if (!subcommand) {
-      return console.error(`Cannot print help for subcommand "${subCmdName}" as it does not exist`);
-    }
-
-    help.printSubcommandHelp(subcommand, style, cliOptions.cliName);
-  };
-
-  try {
-    const data = unsafeParse(argsv, ...parameters);
-    // @ts-expect-error The operand of a 'delete' operator must be optional.
-    delete data.printCliHelp;
-    // @ts-expect-errorThe operand of a 'delete' operator must be optional.
-    delete data.printSubcommandHelp;
-
-    return {
-      success: true,
-      data: data as Omit<typeof data, "printCliHelp" | "printSubcommandHelp">,
-      printCliHelp,
-      printSubcommandHelp,
-    } as SafeParseResult<[...T, NoSubcommand & U]>;
-  } catch (error) {
-    if (!(error instanceof Error) || error.cause !== "zod-args-parser") {
-      throw error;
-    }
-
-    return {
-      success: false,
-      error,
-      printCliHelp,
-      printSubcommandHelp,
-    } as SafeParseResult<[...T, NoSubcommand & U]>;
-  }
-}
-
-export async function safeParseAsync<T extends Subcommand[], U extends Cli>(
-  argsv: string[],
-  ...parameters: [U, ...T]
-): Promise<SafeParseResult<[...T, NoSubcommand & U]>> {
-  const cliOptions = ("cliName" in parameters[0] ? parameters[0] : {}) as U;
-  const subcommandArray = parameters as Subcommand[];
-
-  type PrintTypes = PrintMethods<T[number]["name"]>;
-  type PrintCli = PrintTypes["printCliHelp"];
-  type PrintSubcommand = PrintTypes["printSubcommandHelp"];
-
-  const printCliHelp: PrintCli = style => help.printCliHelp(parameters, style);
-
-  const printSubcommandHelp: PrintSubcommand = (subCmdName, style) => {
-    const subcommand = findSubcommand(subCmdName, subcommandArray);
-    if (!subcommand) {
-      return console.error(`Cannot print help for subcommand "${subCmdName}" as it does not exist`);
-    }
-
-    help.printSubcommandHelp(subcommand, style, cliOptions.cliName);
-  };
-
-  try {
-    const data = await unsafeParseAsync(argsv, ...parameters);
-    // @ts-expect-error The operand of a 'delete' operator must be optional.
-    delete data.printCliHelp;
-    // @ts-expect-errorThe operand of a 'delete' operator must be optional.
-    delete data.printSubcommandHelp;
-
-    return {
-      success: true,
-      data: data as Omit<typeof data, "printCliHelp" | "printSubcommandHelp">,
-      printCliHelp,
-      printSubcommandHelp,
-    } as SafeParseResult<[...T, NoSubcommand & U]>;
-  } catch (error) {
-    if (!(error instanceof Error) || error.cause !== "zod-args-parser") {
-      throw error;
-    }
-
-    return {
-      success: false,
-      error,
-      printCliHelp,
-      printSubcommandHelp,
-    } as SafeParseResult<[...T, NoSubcommand & U]>;
-  }
-}

package/src/parser/unsafe-parse.ts

@@ -1,98 +0,0 @@
-import * as help from "../help-message/format-cli.js";
-import { parse } from "./parse/parse.js";
-import { findSubcommand } from "./parse/parser-helpers.js";
-import { validate } from "./validate/validate.js";
-
-import type { Cli, HelpMessageStyle, NoSubcommand, Subcommand, UnsafeParseResult } from "../types.js";
-
-export function unsafeParse<T extends Subcommand[], U extends Cli>(
-  argv: string[],
-  ...parameters: [U, ...T]
-): UnsafeParseResult<[...T, NoSubcommand & U]> {
-  const cliOptions = ("cliName" in parameters[0] ? parameters[0] : {}) as U;
-  const subcommandArray = parameters as unknown as T;
-
-  // Parse
-  const parsedData = parse(argv, ...parameters);
-
-  const subcommandObject = findSubcommand(parsedData.subcommand, subcommandArray);
-  if (!subcommandObject) {
-    throw new Error(`Subcommand "${parsedData.subcommand}" does not exist`, { cause: "zod-args-parser" });
-  }
-
-  // Fire preValidation hook
-  if (subcommandObject.preValidation) {
-    subcommandObject.preValidation(parsedData);
-  }
-
-  // Validate
-  const validateResult = validate(parsedData);
-
-  Object.assign(validateResult, {
-    printCliHelp(style?: Partial<HelpMessageStyle>) {
-      help.printCliHelp(parameters, style);
-    },
-    printSubcommandHelp(subCmdName: string, style?: Partial<HelpMessageStyle>) {
-      const subcommandObject = findSubcommand(subCmdName, subcommandArray);
-      if (!subcommandObject) {
-        console.error(`Cannot print help for subcommand "${subCmdName}" as it does not exist`);
-        return;
-      }
-
-      help.printSubcommandHelp(subcommandObject, style, cliOptions.cliName);
-    },
-  });
-
-  // Fire action
-  if (subcommandObject.action) {
-    subcommandObject.action(validateResult);
-  }
-
-  return validateResult as UnsafeParseResult<[...T, NoSubcommand & U]>;
-}
-
-export async function unsafeParseAsync<T extends Subcommand[], U extends Cli>(
-  argv: string[],
-  ...parameters: [U, ...T]
-): Promise<UnsafeParseResult<[...T, NoSubcommand & U]>> {
-  const cliOptions = ("cliName" in parameters[0] ? parameters[0] : {}) as U;
-  const subcommandArray = parameters as unknown as T;
-
-  // Parse
-  const parsedData = parse(argv, ...parameters);
-
-  const subcommandObject = findSubcommand(parsedData.subcommand, subcommandArray);
-  if (!subcommandObject) {
-    throw new Error(`Subcommand "${parsedData.subcommand}" does not exist`, { cause: "zod-args-parser" });
-  }
-
-  // Fire preValidation hook
-  if (subcommandObject.preValidation) {
-    await subcommandObject.preValidation(parsedData);
-  }
-
-  // Validate
-  const validateResult = validate(parsedData);
-
-  Object.assign(validateResult, {
-    printCliHelp(style?: Partial<HelpMessageStyle>) {
-      help.printCliHelp(parameters, style);
-    },
-    printSubcommandHelp(subCmdName: string, style?: Partial<HelpMessageStyle>) {
-      const subcommandObject = findSubcommand(subCmdName, subcommandArray);
-      if (!subcommandObject) {
-        console.error(`Cannot print help for subcommand "${subCmdName}" as it does not exist`);
-        return;
-      }
-
-      help.printSubcommandHelp(subcommandObject, style, cliOptions.cliName);
-    },
-  });
-
-  // Fire action
-  if (subcommandObject.action) {
-    await subcommandObject.action(validateResult);
-  }
-
-  return validateResult as UnsafeParseResult<[...T, NoSubcommand & U]>;
-}

package/src/parser/validate/validate-type.ts

@@ -1,20 +0,0 @@
-import type { Argument, Option, Prettify, Schema, Subcommand, ToOptional, ZodInferOutput } from "../../types.js";
-import type { ParseResult } from "../parse/parse-types.js";
-
-type OptionsArray2RecordType<T extends Option[] | undefined> = T extends Option[]
-  ? ToOptional<{ [K in T[number]["name"]]: ZodInferOutput<Extract<T[number], { name: K }>["type"]> }>
-  : object;
-
-type ArgumentsArray2ArrayType<T extends Argument[] | undefined> = T extends Argument[]
-  ? { [K in keyof T]: T[K] extends { type: Schema } ? ZodInferOutput<T[K]["type"]> : never }
-  : never;
-
-export type ValidateResult<S extends Partial<Subcommand>[]> = {
-  [K in keyof S]: Prettify<{
-    subcommand: S[K]["name"] extends string ? S[K]["name"] : undefined;
-    arguments: ArgumentsArray2ArrayType<S[K]["arguments"]>;
-    positional: S[K]["allowPositional"] extends true ? string[] : never;
-    options: S[K]["options"] extends Option[] ? OptionsArray2RecordType<S[K]["options"]> : never;
-    ctx: ParseResult<S>;
-  }>;
-}[number];