zod-args-parser 1.0.0

package/src/help.ts

@@ -0,0 +1,340 @@
+import chalk from "chalk";
+import { concat, getDefaultValueFromSchema, indent, ln, print, println, transformOptionToArg } from "./utils.js";
+
+import type { Argument, Cli, Option, PrintHelpOpt, Subcommand } from "./types.js";
+
+/** Colors */
+const colors: NonNullable<Required<PrintHelpOpt["customColors"]>> = {
+  title: chalk.bold.blue,
+  description: chalk.white,
+  default: chalk.dim.italic,
+  optional: chalk.dim.italic,
+  exampleTitle: chalk.yellow,
+  example: chalk.dim.italic,
+  command: chalk.yellow,
+  option: chalk.cyan,
+  argument: chalk.green,
+  placeholder: chalk.hex("#FF9800"),
+  punctuation: chalk.white.dim,
+};
+
+type PreparedToPrint = {
+  names: string;
+  description: string;
+  placeholder?: string;
+  example?: string;
+  default?: string;
+  optional?: string;
+};
+
+function printCliHelp(params: [Cli, ...Subcommand[]], printOptions: PrintHelpOpt = {}) {
+  printOptions.colors ??= true;
+
+  const noColors = new Proxy(colors, {
+    get: () => {
+      return (...str: string[]) => str.join(" ");
+    },
+  });
+
+  const c = printOptions.colors ? colors : noColors;
+
+  if (printOptions.customColors) {
+    Object.assign(c, printOptions.customColors);
+  }
+
+  const isFirstParamCli = "cliName" in params[0];
+  const cliOptions = (isFirstParamCli ? params.shift() : {}) as Cli;
+  const subcommands = params as Subcommand[];
+
+  /** Print a styled title */
+  const printTitle = (title: string) => {
+    print(c.title(` ${title.toUpperCase()} `));
+  };
+
+  // Print CLI usage
+  const cliName = cliOptions.cliName ?? "";
+  const usage =
+    cliOptions.usage ??
+    concat(
+      c.punctuation("$"),
+      cliName,
+      subcommands.length ? c.command("[command]") : "",
+      cliOptions.options?.length ? c.option("[options]") : "",
+      cliOptions.arguments?.length || cliOptions.allowPositional ? c.argument("<arguments>") : "",
+    );
+  printTitle("Usage");
+  println();
+  println(indent(2), usage, ln(1));
+
+  // Print CLI description
+  if (cliOptions.description) {
+    printTitle("Description");
+    println();
+    println(indent(2), c.description(cliOptions.description), ln(1));
+  }
+
+  let longest = 0;
+
+  // Prepare CLI options
+  const [optionsToPrint, longestOptionIndent] = prepareOptionsToPrint(cliOptions.options);
+  if (longestOptionIndent > longest) longest = longestOptionIndent;
+
+  // Prepare CLI commands
+  const [commandsToPrint, longestSubcommandIndent] = prepareCommandsToPrint(subcommands);
+  if (longestSubcommandIndent > longest) longest = longestSubcommandIndent;
+
+  // Prepare CLI arguments
+  const [argsToPrint, longestArgIndent] = prepareArgumentsToPrint(cliOptions.arguments);
+  if (longestArgIndent > longest) longest = longestArgIndent;
+
+  // Print CLI options
+  printPreparedOptions(optionsToPrint, c, longest);
+
+  // Print CLI commands
+  printPreparedCommands(commandsToPrint, c, longest);
+
+  // Print CLI arguments
+  printPreparedArguments(argsToPrint, c, longest);
+
+  // Print CLI example
+  if (cliOptions.example) {
+    printTitle("Example");
+    println();
+    const normalizeExample = cliOptions.example.replace(/\n/g, "\n" + indent(3));
+    println(indent(2), c.example(normalizeExample), ln(1));
+  }
+}
+
+function printSubcommandHelp(subcommand: Subcommand, printOptions: PrintHelpOpt = {}, cliName = "") {
+  printOptions.colors ??= true;
+
+  const noColors = new Proxy(colors, {
+    get: () => {
+      return (...str: string[]) => str.join(" ");
+    },
+  });
+
+  const c = printOptions.colors ? colors : noColors;
+
+  if (printOptions.customColors) {
+    Object.assign(c, printOptions.customColors);
+  }
+
+  /** Print a styled title */
+  const printTitle = (title: string) => {
+    print(c.title(` ${title.toUpperCase()} `));
+  };
+
+  // Print command usage
+  const usage = concat(
+    c.punctuation("$"),
+    cliName,
+    c.command(subcommand.name),
+    subcommand.options?.length ? c.option("[options]") : "",
+    subcommand.arguments?.length || subcommand.allowPositional ? c.argument("<arguments>") : "",
+  );
+  printTitle("Usage");
+  println();
+  println(indent(2), usage, ln(1));
+
+  // Print command description
+  if (subcommand.description) {
+    printTitle("Description");
+    println();
+    const normalizeDesc = subcommand.description.replace(/\n/g, "\n" + indent(3));
+    println(indent(2), c.description(normalizeDesc), ln(1));
+  }
+
+  let longest = 0;
+
+  // Prepare command options
+  const [optionsToPrint, longestOptionIndent] = prepareOptionsToPrint(subcommand.options);
+  if (longestOptionIndent > longest) longest = longestOptionIndent;
+
+  // Prepare command arguments
+  const [argsToPrint, longestArgIndent] = prepareArgumentsToPrint(subcommand.arguments);
+  if (longestArgIndent > longest) longest = longestArgIndent;
+
+  // Print command options
+  printPreparedOptions(optionsToPrint, c, longest);
+
+  // Print command arguments
+  printPreparedArguments(argsToPrint, c, longest);
+
+  // Print command example
+  if (subcommand.example) {
+    printTitle("Example");
+    println();
+    const normalizeExample = subcommand.example.replace(/\n/g, "\n" + indent(3));
+    println(indent(2), c.example(normalizeExample), ln(1));
+  }
+}
+
+// * Prepare
+function prepareOptionsToPrint(options: Option[] | undefined): [PreparedToPrint[], number] {
+  if (!options || !options.length) return [[], 0];
+
+  const optionsToPrint: PreparedToPrint[] = [];
+  let longest = 0;
+
+  for (const option of options) {
+    const nameWithAliases = option.aliases ? [...option.aliases, option.name] : [option.name];
+    const names = Array.from(new Set(nameWithAliases.map(name => transformOptionToArg(name)))).join(", ");
+
+    const defaultValue = getDefaultValueFromSchema(option.type);
+
+    const placeholder = option.placeholder ?? " ";
+    optionsToPrint.push({
+      names,
+      placeholder,
+      description: option.description ?? option.type.description ?? "",
+      default: typeof defaultValue !== "undefined" ? `(default: ${JSON.stringify(defaultValue)})` : "",
+      optional: option.type.isOptional() ? "[optional]" : "",
+      example: option.example ?? "",
+    });
+
+    const optLength = names.length + placeholder.length;
+
+    if (optLength > longest) longest = optLength;
+  }
+
+  return [optionsToPrint, longest];
+}
+
+function prepareCommandsToPrint(subcommands: Subcommand[] | undefined): [PreparedToPrint[], number] {
+  if (!subcommands || !subcommands.length) return [[], 0];
+
+  const commandsToPrint: PreparedToPrint[] = [];
+  let longest = 0;
+
+  for (const subcommand of subcommands) {
+    const { name, aliases, description } = subcommand;
+    const names = Array.from(new Set([...(aliases ?? []), name])).join(", ");
+
+    const placeholder =
+      subcommand.placeholder ?? (subcommand.options ? "[options]" : subcommand.allowPositional ? "<args>" : " ");
+
+    commandsToPrint.push({ names, placeholder, description: description ?? "" });
+
+    const cmdLength = names.length + placeholder.length;
+    if (cmdLength > longest) longest = cmdLength;
+  }
+
+  return [commandsToPrint, longest];
+}
+
+function prepareArgumentsToPrint(args: Argument[] | undefined): [PreparedToPrint[], number] {
+  if (!args || !args.length) return [[], 0];
+
+  const argsToPrint: PreparedToPrint[] = [];
+  let longest = 0;
+
+  for (const arg of args) {
+    const defaultValue = getDefaultValueFromSchema(arg.type);
+
+    argsToPrint.push({
+      names: arg.name,
+      description: arg.description ?? "",
+      default: typeof defaultValue !== "undefined" ? `(default: ${JSON.stringify(defaultValue)})` : "",
+      optional: arg.type.isOptional() ? "[optional]" : "",
+      example: arg.example ?? "",
+    });
+
+    const cmdLength = arg.name.length;
+    if (cmdLength > longest) longest = cmdLength;
+  }
+
+  return [argsToPrint, longest];
+}
+
+// * Print
+function printPreparedOptions(optionsToPrint: PreparedToPrint[], c: typeof colors, longest: number) {
+  if (!optionsToPrint.length) return;
+
+  print(c.title(" OPTIONS "));
+
+  println();
+
+  for (const { names, placeholder, description, example, optional, default: def } of optionsToPrint) {
+    const optLength = names.length + (placeholder?.length ?? 0);
+    const spacing = longest + 1 - optLength;
+    const normalizeDesc = description.replace(/\n/g, "\n" + indent(longest + 7) + c.punctuation("└"));
+
+    const coloredNames = names
+      .split(/(,)/)
+      .map(name => (name === "," ? c.punctuation(name) : c.option(name)))
+      .join("");
+
+    println(
+      indent(2),
+      coloredNames,
+      c.placeholder(placeholder),
+      indent(spacing),
+      c.description(normalizeDesc),
+      def ? c.default(def) : c.optional(optional),
+    );
+
+    if (example) {
+      const normalizeExample = example.replace(/\n/g, "\n" + indent(longest + 17));
+      println(indent(longest + 6), c.punctuation("└") + c.exampleTitle("Example:"), c.example(normalizeExample));
+    }
+  }
+
+  println();
+}
+
+function printPreparedCommands(commandsToPrint: PreparedToPrint[], c: typeof colors, longest: number) {
+  if (!commandsToPrint.length) return;
+
+  print(c.title(" COMMANDS "));
+
+  println();
+
+  for (const { names, placeholder, description } of commandsToPrint) {
+    const optLength = names.length + (placeholder?.length ?? 0);
+    const spacing = longest + 1 - optLength;
+    const normalizeDesc = description.replace(/\n/g, "\n" + indent(longest + 7));
+
+    const coloredNames = names
+      .split(/(,)/)
+      .map(name => (name === "," ? c.punctuation(name) : c.command(name)))
+      .join("");
+
+    println(indent(2), coloredNames, c.placeholder(placeholder), indent(spacing), c.description(normalizeDesc));
+  }
+
+  println();
+}
+
+function printPreparedArguments(argsToPrint: PreparedToPrint[], c: typeof colors, longest: number) {
+  if (!argsToPrint.length) return;
+
+  print(c.title(" ARGUMENTS "));
+
+  println();
+
+  for (const { names, description, example, optional, default: def } of argsToPrint) {
+    const spacing = longest + 2 - names.length;
+    const normalizeDesc = description.replace(/\n/g, "\n" + indent(longest + 6) + c.punctuation("└"));
+
+    println(
+      indent(2),
+      c.argument(names),
+      indent(spacing),
+      c.description(normalizeDesc),
+      def ? c.default(def) : c.optional(optional),
+    );
+
+    if (example) {
+      const normalizeExample = example.replace(/\n/g, "\n" + indent(longest + 16));
+      println(indent(longest + 5), c.punctuation("└") + c.exampleTitle("Example:"), c.example(normalizeExample));
+    }
+  }
+
+  println();
+}
+
+export const help = {
+  printCliHelp,
+  printSubcommandHelp,
+};

package/src/index.ts

@@ -0,0 +1,22 @@
+import { help } from "./help.js";
+import { parse, safeParse } from "./parser.js";
+
+import type { ActionFn, Cli, Prettify, Subcommand, UnSafeParseResult } from "./types.js";
+
+function createSubcommand<const T extends Subcommand>(input: T & Subcommand): Prettify<T & ActionFn<T>> {
+  return Object.assign(input, {
+    setAction: (action: (res: UnSafeParseResult<[T]>) => void) => (input.action = action),
+  });
+}
+
+function createCli<const T extends Cli>(input: T & Cli): Prettify<T & ActionFn<T>> {
+  return Object.assign(input, {
+    setAction: (action: (res: UnSafeParseResult<[T]>) => void) => (input.action = action),
+  });
+}
+
+const { printCliHelp, printSubcommandHelp } = help;
+
+export { createCli, createSubcommand, parse, printCliHelp, printSubcommandHelp, safeParse };
+
+export type * from "./types.js";

package/src/parser.ts

@@ -0,0 +1,299 @@
+import { help } from "./help.js";
+import {
+  decoupleFlags,
+  getOrdinalPlacement,
+  isBooleanSchema,
+  isFlagArg,
+  isOptionArg,
+  noName,
+  stringToBoolean,
+  transformArg,
+  transformOptionToArg,
+} from "./utils.js";
+
+import type {
+  Cli,
+  NoSubcommand,
+  Option,
+  PrintHelpOpt,
+  SafeParseResult,
+  Subcommand,
+  UnSafeParseResult,
+} from "./types.js";
+
+export function parse<T extends Subcommand[]>(argsv: string[], ...params: T): UnSafeParseResult<T>;
+export function parse<T extends Subcommand[], U extends Cli>(
+  argsv: string[],
+  ...params: [U, ...T]
+): UnSafeParseResult<[...T, NoSubcommand & U]>;
+
+export function parse<T extends Subcommand[], U extends Cli>(argsv: string[], ...params: [U, ...T]) {
+  const cliOptions = ("cliName" in params[0] ? params[0] : {}) as U;
+  const subcommandArr = params as unknown as T;
+  const allSubcommands = new Set<string>(subcommandArr.flatMap(c => [c.name, ...(c.aliases || [])]));
+
+  // decouple flags E.g. `-rf` -> `-r, -f`
+  argsv = decoupleFlags(argsv);
+
+  type ResultObj = Record<string, unknown> & {
+    subcommand: string | undefined;
+    positional?: string[];
+    arguments?: unknown[];
+    _info?: Record<string, { rawArg?: string; rawValue?: string; source: "cli" | "default" }>;
+    printCliHelp: (options?: PrintHelpOpt) => void;
+    printSubcommandHelp: (subcommand: any, options?: PrintHelpOpt) => void;
+  };
+
+  const results: ResultObj = {
+    subcommand: undefined,
+    printCliHelp(opt) {
+      help.printCliHelp(params, opt);
+    },
+    printSubcommandHelp(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 addRawArg = (optionName: string, rawArg: string) => {
+    if (!results._info) results._info = {};
+    if (!results._info[optionName]) results._info[optionName] = Object.create({});
+    results._info[optionName].rawArg = rawArg;
+  };
+
+  const addRawValue = (optionName: string, rawValue: string) => {
+    if (!results._info) results._info = {};
+    if (!results._info[optionName]) results._info[optionName] = Object.create({});
+    results._info[optionName].rawValue = rawValue;
+  };
+
+  const addSource = (optionName: string, source: "cli" | "default") => {
+    if (!results._info) results._info = {};
+    if (!results._info[optionName]) results._info[optionName] = Object.create({});
+    results._info[optionName].source = source;
+  };
+
+  const fillOption = (optionName: string, value: Option) => {
+    if (!results._info) results._info = {};
+    if (!results._info[optionName]) results._info[optionName] = Object.create({});
+    Object.assign(results._info[optionName], value);
+  };
+
+  for (let i = 0; i < argsv.length; i++) {
+    const arg = argsv[i];
+
+    // * subcommand
+    if (i === 0) {
+      results.subcommand = allSubcommands.has(arg) ? arg : undefined;
+
+      // add positional and arguments array
+      const subcommandProps = subcommandArr.find(c => c.name === results.subcommand);
+      if (subcommandProps?.allowPositional) results.positional = [];
+      if (subcommandProps?.arguments?.length) results.arguments = [];
+
+      if (results.subcommand) continue;
+    }
+
+    // * option
+    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}"`);
+      }
+
+      const subcommandProps = subcommandArr.find(c => c.name === results.subcommand);
+      if (!subcommandProps) throw new Error(`Unknown subcommand: "${results.subcommand}"`);
+
+      if (!subcommandProps.options) {
+        const msg = !results.subcommand
+          ? "options are not allowed here"
+          : `subcommand "${results.subcommand}" does not allow options`;
+        throw new Error(`Error: ${msg}: "${argument}"`);
+      }
+
+      const optionName = transformArg(argument);
+      if (optionName in results) throw new Error(`Duplicate option: "${argument}"`);
+
+      const isNegative = argument.startsWith("--no-");
+
+      const option = subcommandProps.options.find(o => {
+        if (o.name === optionName) return true;
+        if (isNegative && noName(o.name) === optionName) return true;
+
+        if (!o.aliases) return false;
+        if (o.aliases.includes(optionName)) return true;
+        if (isNegative && o.aliases.map(noName).includes(optionName)) return true;
+
+        return false;
+      });
+
+      if (!option) {
+        throw new Error(`Unknown option: "${argument}"`);
+      }
+
+      const isTypeBoolean = isBooleanSchema(option.type);
+      const nextArg = argsv[i + 1];
+
+      let optionValue: string | boolean = argWithEquals ? argValue : nextArg;
+
+      if (isTypeBoolean) {
+        if (argWithEquals) {
+          const parsedBoolean = stringToBoolean(argValue);
+          optionValue = isNegative ? !parsedBoolean : parsedBoolean;
+        } else {
+          optionValue = !isNegative;
+        }
+      }
+
+      if (typeof optionValue === "undefined") {
+        throw new Error(`Expected a value for "${argument}" but got nothing`);
+      }
+
+      if (!argWithEquals && isOptionArg(optionValue)) {
+        throw new Error(`Expected a value for "${argument}" but got an argument "${nextArg}"`);
+      }
+
+      const res = option.type.safeParse(optionValue);
+      if (!res.success) {
+        throw new Error(`Invalid value "${optionValue}" for "${argument}": ${res.error.errors[0].message}`);
+      }
+
+      results[option.name] = res.data;
+      addRawArg(option.name, argument);
+      const rawVal = argWithEquals ? argValue : isTypeBoolean ? "" : nextArg;
+      addRawValue(option.name, rawVal);
+      fillOption(option.name, option);
+
+      if (!argWithEquals && !isTypeBoolean) i++;
+      continue;
+    }
+
+    const subcommandProps = subcommandArr.find(c => c.name === results.subcommand);
+
+    // * arguments
+    if (subcommandProps?.arguments?.length) {
+      if (!results.arguments) results.arguments = [];
+
+      const currentArgCount = results.arguments.length;
+
+      if (currentArgCount < subcommandProps.arguments.length) {
+        const argType = subcommandProps.arguments[currentArgCount].type;
+
+        let argValue: string | boolean = arg;
+        const isTypeBoolean = isBooleanSchema(argType);
+        if (isTypeBoolean) argValue = stringToBoolean(argValue);
+
+        const res = argType.safeParse(argValue);
+        if (!res.success) {
+          throw new Error(
+            `The ${getOrdinalPlacement(currentArgCount)} argument "${arg}" is invalid: ${res.error.errors[0].message}`,
+          );
+        }
+
+        results.arguments.push(res.data);
+        continue;
+      }
+    }
+
+    // * positional
+    if (subcommandProps?.allowPositional) {
+      if (!results.positional) results.positional = [];
+      results.positional.push(arg);
+      continue;
+    }
+
+    const msg = !results.subcommand ? "here" : `for subcommand "${results.subcommand}"`;
+    throw new Error(`Unexpected argument "${arg}": positional arguments are not allowed ${msg}`);
+  }
+
+  // check for missing options - set defaults - add _source
+  const subcommandProps = subcommandArr.find(c => c.name === results.subcommand);
+  if (subcommandProps?.options?.length) {
+    for (const option of subcommandProps.options) {
+      if (option.name in results) {
+        addSource(option.name, "cli");
+        fillOption(option.name, option);
+        continue;
+      }
+
+      if (option.type.isOptional()) {
+        const hasDefault = typeof option.type._def.defaultValue === "function";
+        if (!hasDefault) continue;
+        results[option.name] = option.type._def.defaultValue();
+        addSource(option.name, "default");
+        fillOption(option.name, option);
+        continue;
+      }
+
+      throw new Error(`Missing required option: ${transformOptionToArg(option.name)}`);
+    }
+  }
+
+  // check for arguments - set defaults
+  if (subcommandProps?.arguments?.length) {
+    const currentArgCount = results.arguments?.length ?? 0;
+    const subcommandArgCount = subcommandProps.arguments.length;
+
+    // missing arguments
+    if (currentArgCount < subcommandArgCount) {
+      for (let i = currentArgCount; i < subcommandArgCount; i++) {
+        const argumentType = subcommandProps.arguments[i].type;
+        const hasDefault = typeof argumentType._def.defaultValue === "function";
+        if (hasDefault && results.arguments) {
+          results.arguments.push(argumentType._def.defaultValue());
+          continue;
+        }
+
+        if (argumentType.isOptional()) continue;
+
+        throw new Error(`the ${getOrdinalPlacement(i)} argument is required: "${subcommandProps.arguments[i].name}"`);
+      }
+    }
+  }
+
+  if (subcommandProps?.action) {
+    subcommandProps.action(results);
+  }
+
+  return results as UnSafeParseResult<[...T, NoSubcommand & U]>;
+}
+
+export function safeParse<T extends Subcommand[]>(argsv: string[], ...params: T): SafeParseResult<T>;
+export function safeParse<T extends Subcommand[], U extends Cli>(
+  argsv: string[],
+  ...params: [U, ...T]
+): SafeParseResult<[...T, NoSubcommand & U]>;
+
+export function safeParse<T extends Subcommand[], U extends Cli>(argsv: string[], ...params: [U, ...T]) {
+  const cliOptions = ("cliName" in params[0] ? params[0] : {}) as U;
+  const subcommandArr = params as Subcommand[];
+
+  const printCliHelp = (opt?: PrintHelpOpt) => help.printCliHelp(params, opt);
+  const printSubcommandHelp = (subcommandStr: NonNullable<T[number]["name"]>, opt?: PrintHelpOpt) => {
+    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);
+  };
+
+  try {
+    const data = parse(argsv, ...params);
+    // @ts-expect-error error
+    delete data.printCliHelp;
+    // @ts-expect-error error
+    delete data.printSubcommandHelp;
+
+    return {
+      success: true,
+      data: data as Omit<typeof data, "printCliHelp" | "printSubcommandHelp">,
+      printCliHelp,
+      printSubcommandHelp,
+    };
+  } catch (e) {
+    return { success: false, error: e as Error, printCliHelp, printSubcommandHelp };
+  }
+}