zod-args-parser 1.0.16 → 1.2.0

package/src/metadata/metadata-types.ts

@@ -0,0 +1,114 @@
+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

@@ -0,0 +1,89 @@
+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 OptionsArr2Record<T extends Option[] | undefined> = T extends Option[]
+  ? { [K in T[number]["name"]]: ParsedOption<Extract<T[number], { name: K }>["type"], K> }
+  : Record<never, never>;
+
+type ArgumentsArr2ArrType<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: OptionsArr2Record<S[K]["options"]>;
+    arguments: ArgumentsArr2ArrType<S[K]["arguments"]>;
+  }>;
+}[number];
+
+export type ParseCtx = {
+  subcommand: string | undefined;
+  options: Record<string, ParsedOption>;
+  arguments?: ParsedArgument[];
+  positional?: string[];
+};

package/src/parser/parse/parse.ts

@@ -0,0 +1,227 @@
+import { generateOrdinalSuffix } from "../../utils.js";
+import { isBooleanSchema, isOptionalSchema, schemaDefaultValue } from "../../zod-utils.js";
+import {
+  decoupleFlags,
+  findOption,
+  findSubcommand,
+  isFlagArg,
+  isOptionArg,
+  transformOptionToArg,
+} from "./parser-helpers.js";
+
+import type { Cli, Subcommand } from "../../types.js";
+import type { ParseCtx } from "./parse-types.js";
+
+export function parse(argv: string[], ...params: [Cli, ...Subcommand[]]) {
+  const subcommandArr = params as Subcommand[];
+  const allSubcommands = new Set<string>(subcommandArr.flatMap(c => [c.name, ...(c.aliases || [])]));
+
+  argv = decoupleFlags(argv); // decouple flags E.g. `-rf` -> `-r, -f`
+
+  const results: ParseCtx = {
+    subcommand: undefined,
+    options: {},
+  };
+
+  /** - Get current subcommand object */
+  const getSubcommandObj = () => findSubcommand(results.subcommand, subcommandArr);
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+
+    // * Subcommand check
+    if (i === 0) {
+      results.subcommand = allSubcommands.has(arg) ? arg : undefined;
+
+      // add positional and arguments arrays
+      const subcommandObj = getSubcommandObj();
+      if (subcommandObj && subcommandObj.allowPositional) {
+        results.positional = [];
+      }
+
+      if (subcommandObj && subcommandObj.arguments?.length) {
+        results.arguments = [];
+      }
+
+      // First argument is a subcommand. Skip to the next argument
+      if (results.subcommand) continue;
+    }
+
+    // * Option check
+
+    // Check for `--option=value` or `--option value`
+    const argAndValue = arg.split("=").filter(Boolean);
+    const argWithEquals = arg.includes("=");
+    const argument = argAndValue[0];
+    const argValue: string | undefined = argAndValue[1];
+
+    if (isOptionArg(argument)) {
+      if (isFlagArg(argument) && argWithEquals) {
+        throw new Error(`Flag arguments cannot be assigned using "=": "${arg}"`, { cause: "zod-args-parser" });
+      }
+
+      const subcommandObj = getSubcommandObj();
+      if (!subcommandObj) {
+        throw new Error(`Unknown subcommand: "${results.subcommand}"`, { cause: "zod-args-parser" });
+      }
+
+      if (!subcommandObj.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, subcommandObj.options);
+      if (!option) {
+        throw new Error(`Unknown option: "${argument}"`, { cause: "zod-args-parser" });
+      }
+
+      if (option.name in results.options) {
+        throw new Error(`Duplicated option: "${argument}"`, { cause: "zod-args-parser" });
+      }
+
+      const isTypeBoolean = isBooleanSchema(option.type);
+      const nextArg = argv[i + 1];
+
+      let optionValue: string | boolean = argWithEquals ? argValue : nextArg;
+
+      // infer value for boolean options
+      if (isTypeBoolean && !argWithEquals) {
+        optionValue = "true";
+      }
+
+      if (typeof optionValue === "undefined") {
+        throw new Error(`Expected a value for "${argument}" but got nothing`, { cause: "zod-args-parser" });
+      }
+
+      if (!argWithEquals && isOptionArg(optionValue)) {
+        throw new Error(`Expected a value for "${argument}" but got an argument "${nextArg}"`, {
+          cause: "zod-args-parser",
+        });
+      }
+
+      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 (!argWithEquals && !isTypeBoolean) {
+        i++;
+      }
+
+      continue;
+    }
+
+    const subcommandObj = getSubcommandObj();
+
+    // * Arguments check
+    if (subcommandObj?.arguments?.length) {
+      if (!results.arguments) {
+        results.arguments = [];
+      }
+
+      const currentArgCount = results.arguments.length;
+
+      // Any extra arguments are possibly positional
+      if (currentArgCount < subcommandObj.arguments.length) {
+        const argType = subcommandObj.arguments[currentArgCount].type;
+        results.arguments.push({
+          schema: argType,
+          rawValue: arg,
+          source: "cli",
+        });
+        continue;
+      }
+    }
+
+    // * Positional check
+    if (subcommandObj?.allowPositional) {
+      if (!results.positional) {
+        results.positional = [];
+      }
+
+      results.positional.push(arg);
+      continue;
+    }
+
+    // * Unexpected
+    if (!results.subcommand) {
+      throw new Error(`Unexpected argument "${arg}": positional arguments are not allowed here`, {
+        cause: "zod-args-parser",
+      });
+    }
+
+    throw new Error(
+      `Unexpected argument "${arg}": positional arguments are not allowed for subcommand "${results.subcommand}"`,
+      { cause: "zod-args-parser" },
+    );
+  }
+
+  // * Check for missing options - set defaults - add `source`
+  const subcommandObj = getSubcommandObj();
+  if (!subcommandObj) {
+    throw new Error(`Unknown subcommand: "${results.subcommand}"`, { cause: "zod-args-parser" });
+  }
+
+  // Options
+  if (subcommandObj.options?.length) {
+    for (const option of subcommandObj.options) {
+      // option already exists
+      if (option.name in results.options) continue;
+
+      const optional = isOptionalSchema(option.type);
+      const defaultValue = schemaDefaultValue(option.type);
+
+      if (optional) {
+        if (typeof defaultValue === "undefined") {
+          continue;
+        }
+
+        results.options[option.name] = { name: option.name, schema: option.type, source: "default" };
+        continue;
+      }
+
+      throw new Error(`Missing required option: ${transformOptionToArg(option.name)}`, { cause: "zod-args-parser" });
+    }
+  }
+
+  // Arguments
+  if (subcommandObj.arguments?.length) {
+    const currentArgCount = results.arguments?.length ?? 0;
+    const subcommandArgCount = subcommandObj.arguments.length;
+
+    // missing arguments
+    if (currentArgCount < subcommandArgCount) {
+      for (let i = currentArgCount; i < subcommandArgCount; i++) {
+        const argumentType = subcommandObj.arguments[i].type;
+        const optional = isOptionalSchema(argumentType);
+        const defaultValue = schemaDefaultValue(argumentType);
+
+        if (optional) {
+          if (typeof defaultValue === "undefined") {
+            continue;
+          }
+
+          if (!results.arguments) results.arguments = [];
+
+          results.arguments.push({ schema: argumentType, source: "default" });
+          continue;
+        }
+
+        throw new Error(`the ${generateOrdinalSuffix(i)} argument is required: "${subcommandObj.arguments[i].name}"`, {
+          cause: "zod-args-parser",
+        });
+      }
+    }
+  }
+
+  return results;
+}

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

@@ -0,0 +1,167 @@
+import type { Option, Subcommand } from "../../types.js";
+
+/**
+ * Retrieves a subcommand object from an array of subcommands by matching the provided subcommand name against the
+ * subcommand's name or its aliases.
+ *
+ * @param subCmdName - The name or alias of the subcommand to search for.
+ * @param subcommandArr - An array of `Subcommand` objects to search within.
+ * @returns The matching `Subcommand` object if found; otherwise, `undefined`.
+ */
+export function findSubcommand(subCmdName: string | undefined, subcommandArr: Subcommand[]): Subcommand | undefined {
+  return subcommandArr.find(c => {
+    // match for undefined too
+    if (c.name === subCmdName) {
+      return true;
+    }
+
+    // match for aliases
+    return subCmdName && c.aliases && c.aliases.includes(subCmdName);
+  });
+}
+
+/**
+ * Finds and returns an `Option` object from the provided list that matches the given argument string.
+ *
+ * The function supports matching by option name, aliases, and their negated forms (e.g., `--no-` prefix).
+ *
+ * @param optionArg - The argument string to match (e.g., `--foo`, `--no-bar`, `-f`).
+ * @param options - An array of `Option` objects to search through.
+ * @returns The matching `Option` object if found; otherwise, `undefined`.
+ */
+export function findOption(optionArg: string, options: [Option, ...Option[]]): Option | undefined {
+  const validVarNames = optionArgToVarNames(optionArg);
+  const isNegative = optionArg.startsWith("--no-");
+
+  const option = options.find(o => {
+    if (validVarNames.has(o.name)) {
+      return true;
+    }
+
+    if (isNegative && validVarNames.has(negateOption(o.name))) {
+      return true;
+    }
+
+    if (!o.aliases) {
+      return false;
+    }
+
+    if (o.aliases.some(a => validVarNames.has(a))) {
+      return true;
+    }
+
+    if (isNegative && o.aliases.map(negateOption).some(a => validVarNames.has(a))) {
+      return true;
+    }
+
+    return false;
+  });
+
+  return option;
+}
+
+/** - Decouple flags E.g. `-rf` -> `-r, -f` */
+export function decoupleFlags(args: string[]): string[] {
+  const flagsRe = /^-[a-z0-9]{2,}$/i;
+
+  const result = [];
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    const isCoupled = flagsRe.test(arg);
+
+    if (!isCoupled) {
+      result.push(arg);
+      continue;
+    }
+
+    const decoupledArr = arg
+      .substring(1)
+      .split("")
+      .map(c => "-" + c);
+
+    result.push(...decoupledArr);
+  }
+
+  return result;
+}
+
+/**
+ * - Transforms an option argument name to a valid JavaScript variable name
+ *
+ * @param name - Should start with `'--'` or `'-'`
+ */
+export function optionArgToVarNames(name: string): Set<string> {
+  if (!name.startsWith("-")) {
+    throw new Error(`[parseArgOptionName] Invalid arg name: ${name}`, { cause: "zod-args-parser" });
+  }
+
+  name = name.startsWith("--") ? name.substring(2) : name.substring(1); // remove prefix
+  name = name.toLowerCase(); // lowercase
+
+  const results = new Set<string>();
+
+  // camelCase
+  const camelCase = name.replace(/-(.)/g, m => m[1].toUpperCase());
+  results.add(camelCase);
+
+  // PascalCase (UpperCamelCase)
+  results.add(camelCase.replace(/^(.)/, m => m.toUpperCase()));
+
+  // snake_case
+  const snake_case = name.replace(/-(.)/g, g => "_" + g[1]);
+  results.add(snake_case);
+
+  // SCREAMING_SNAKE_CASE
+  results.add(snake_case.toUpperCase());
+
+  return results;
+}
+
+/** - Check if an arg string is a short arg. E.g. `-i` -> `true` */
+export function isFlagArg(name: string): boolean {
+  return /^-[A-Za-z]$/.test(name);
+}
+
+/** - Check if an arg string is a long arg. E.g. `--input-dir` -> `true` */
+function isLongArg(name: string): boolean {
+  return /^--[A-Za-z-]+[A-Za-z0-9]$/.test(name);
+}
+
+/** - Check if an arg string is an options arg. E.g. `--input-dir` -> `true` , `-i` -> `true` */
+export function isOptionArg(name: string | boolean): boolean {
+  if (typeof name !== "string") {
+    return false;
+  }
+
+  return isFlagArg(name) || isLongArg(name);
+}
+
+/**
+ * - Transform option name to no name. E.g. `include` -> `noInclude`
+ * - For short name like `-i` it will be ignored
+ */
+export function negateOption(name: string): string {
+  if (name.length === 1) {
+    return name;
+  }
+
+  return "no" + name.replace(/^[a-z]/, g => g.toUpperCase());
+}
+
+/** - Reverse of `transformArg`. E.g. `InputDir` -> `--input-dir` , `i` -> `-i` */
+export function transformOptionToArg(name: string): string {
+  // single letter option name
+  if (name.length === 1) {
+    return `-${name.toLowerCase()}`;
+  }
+
+  // snake_case, SCREAMING_SNAKE_CASE
+  if (name.includes("_") || /[A-Z]+$/.test(name)) {
+    name = name.replace(/_/g, "-");
+    return `--${name.toLowerCase()}`;
+  }
+
+  // camelCase, PascalCase
+  name = name.replace(/[A-Z]/g, (m, i) => (i ? "-" + m : m)); // add "-" before camel case letters except for the first letter
+  return `--${name.toLowerCase()}`;
+}

package/src/parser/safe-parse.ts

@@ -1,5 +1,6 @@
-import * as help from "../help-message/print-help-message.js";
-import { parse } from "./parse.js";
+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";
 
@@ -14,15 +15,65 @@ export function safeParse<T extends Subcommand[], U extends Cli>(
   type PrintCli = PrintTypes["printCliHelp"];
   type PrintSubcommand = PrintTypes["printSubcommandHelp"];
 
-  const printCliHelp: PrintCli = opt => help.printCliHelp(params, opt);
-  const printSubcommandHelp: PrintSubcommand = (subcommandStr, opt) => {
-    const subcommand = subcommandArr.find(c => c.name === subcommandStr);
-    if (!subcommand) return console.error(`Cannot print help for subcommand "${subcommandStr}" as it does not exist`);
-    help.printSubcommandHelp(subcommand, opt, cliOptions.cliName);
+  const printCliHelp: PrintCli = style => help.printCliHelp(params, style);
+
+  const printSubcommandHelp: PrintSubcommand = (subCmdName, style) => {
+    const subcommand = findSubcommand(subCmdName, subcommandArr);
+    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, ...params);
+    // @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 (e) {
+    if (!(e instanceof Error) || e.cause !== "zod-args-parser") throw e;
+    return {
+      success: false,
+      error: e as Error,
+      printCliHelp,
+      printSubcommandHelp,
+    } as SafeParseResult<[...T, NoSubcommand & U]>;
+  }
+}
+
+export async function safeParseAsync<T extends Subcommand[], U extends Cli>(
+  argsv: string[],
+  ...params: [U, ...T]
+): Promise<SafeParseResult<[...T, NoSubcommand & U]>> {
+  const cliOptions = ("cliName" in params[0] ? params[0] : {}) as U;
+  const subcommandArr = params as Subcommand[];
+
+  type PrintTypes = PrintMethods<T[number]["name"]>;
+  type PrintCli = PrintTypes["printCliHelp"];
+  type PrintSubcommand = PrintTypes["printSubcommandHelp"];
+
+  const printCliHelp: PrintCli = style => help.printCliHelp(params, style);
+
+  const printSubcommandHelp: PrintSubcommand = (subCmdName, style) => {
+    const subcommand = findSubcommand(subCmdName, subcommandArr);
+    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 = parse(argsv, ...params);
+    const data = await unsafeParseAsync(argsv, ...params);
     // @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.
@@ -35,6 +86,7 @@ export function safeParse<T extends Subcommand[], U extends Cli>(
       printSubcommandHelp,
     } as SafeParseResult<[...T, NoSubcommand & U]>;
   } catch (e) {
+    if (!(e instanceof Error) || e.cause !== "zod-args-parser") throw e;
     return {
       success: false,
       error: e as Error,