zod-args-parser 1.0.0

package/src/types.ts

@@ -0,0 +1,286 @@
+import type { z } from "zod";
+
+export type Subcommand = {
+  /**
+   * - The subcommand name, use `kebab-case`.
+   * - Make sure to not duplicate commands and aliases.
+   *
+   * @example
+   *   name: "test";
+   *   name: "run-app";
+   */
+  name: string;
+
+  /**
+   * - The action is executed with the result of the parsed arguments.
+   * - To get typescript types use `setAction` instead of this.
+   *
+   * @example
+   *   const helpCommand = createSubcommand({ name: "help", options: [...] });
+   *   helpCommand.setAction(res => console.log(res));
+   */
+  action?: (results?: any) => void;
+
+  /**
+   * - The description of the subcommand.
+   * - Used for generating the help message.
+   */
+  description?: string;
+
+  /** - Used for generating the help message. */
+  placeholder?: string;
+
+  /**
+   * - Provide an example to show to the user.
+   * - Used for generating the help message.
+   */
+  example?: string;
+
+  /**
+   * - The aliases of the subcommand.
+   * - Make sure to not duplicate aliases and commands.
+   */
+  aliases?: string[];
+
+  /**
+   * - Allows positional arguments for this subcommand.
+   * - Unlike `arguments`, which are strictly typed, positional arguments are untyped and represented as a string array of
+   *   variable length.
+   * - When enabled and `arguments` are provided, `arguments` will be parsed first. Any remaining arguments will be
+   *   considered positional arguments and added to the `positional` property in the result.
+   */
+  allowPositional?: boolean;
+
+  /**
+   * - The options of the command.
+   * - Those options are specific to this subcommand.
+   */
+  options?: [Option, ...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.
+   * - It is recommended to not use optional arguments as the parser will fill the arguments by order and can't determine
+   *   which arguments are optional.
+   */
+  arguments?: [Argument, ...Argument[]];
+};
+
+export type Cli = Prettify<
+  Omit<Subcommand, "name"> & {
+    /** - The name of the CLI program. */
+    cliName: string;
+
+    /**
+     * - The usage of the CLI program.
+     * - Used for generating the help message.
+     */
+    usage?: string;
+  }
+>;
+
+export type Option = {
+  /**
+   * - The name of the option, use `CamelCase`.
+   * - For example: the syntax for the option `rootPath` is `--root-path`.
+   */
+  name: string;
+
+  /**
+   * - The will be used to validate the user input.
+   *
+   * @example
+   *   type: z.boolean().default(false);
+   *   type: z.coerce.number(); // will be coerced to number by Zod
+   *   type: z.preprocess(parseStringToArrFn, z.array(z.coerce.number())); // array of numbers
+   *
+   * @see https://zod.dev/?id=types
+   */
+  type: z.ZodTypeAny;
+
+  /**
+   * - The description of the option.
+   * - Used for generating the help message.
+   */
+  description?: string;
+
+  /** - Used for generating the help message. */
+  placeholder?: string;
+
+  /**
+   * - The example of using the option.
+   * - Used for generating the help message.
+   */
+  example?: string;
+
+  /**
+   * - The aliases of the option, use `CamelCase`.
+   * - Here you can specify short names or flags.
+   * - Make sure to not duplicate aliases.
+   */
+  aliases?: [string, ...string[]];
+};
+
+export type Argument = {
+  /** - The name of the argument. */
+  name: string;
+
+  /**
+   * - The will be used to validate the user input.
+   *
+   * @example
+   *   type: z.boolean();
+   *   type: z.coerce.number(); // will be coerced to number by Zod
+   *   type: z.preprocess(ParseStringToArrFn, z.array(z.coerce.number())); // array of numbers
+   *
+   * @see https://zod.dev/?id=types
+   */
+  type: z.ZodTypeAny;
+
+  /**
+   * - The description of the argument.
+   * - Used for generating the help message.
+   */
+  description?: string;
+
+  /**
+   * - The example of using the argument.
+   * - Used for generating the help message.
+   */
+  example?: string;
+};
+
+export type ColorFnType = (...text: unknown[]) => string;
+
+export type PrintHelpOpt = {
+  /**
+   * - **Optional** `boolean`
+   * - Whether to print colors or not.
+   * - Default: `true`
+   */
+  colors?: boolean;
+
+  /**
+   * - **Optional** `object`
+   * - The colors to use for the help message.
+   */
+  customColors?: {
+    title?: ColorFnType;
+    description?: ColorFnType;
+    default?: ColorFnType;
+    optional?: ColorFnType;
+    exampleTitle?: ColorFnType;
+    example?: ColorFnType;
+    command?: ColorFnType;
+    option?: ColorFnType;
+    argument?: ColorFnType;
+    placeholder?: ColorFnType;
+    punctuation?: ColorFnType;
+  };
+};
+
+export type _Info = {
+  /**
+   * - The raw argument as it was passed in
+   * - For options that have a default value and are not passed in, the raw argument will be `undefined`
+   */
+  rawArg?: string;
+  /**
+   * - The raw value of the argument as it was passed in
+   * - It will be empty string for `boolean` options. E.g. `--help` or `-h`
+   * - For options that have a default value and are not passed in, the raw value will be `undefined`
+   */
+  rawValue?: string;
+  /**
+   * - The source value of the argument:
+   * - `cli`: The argument was passed in by the user
+   * - `default`: The argument was not passed in and has a default value
+   */
+  source: "cli" | "default";
+};
+
+/**
+ * - Infer the options type from a subcommand.
+ *
+ * @example
+ *   const subcommand = createSubcommand({ name: "build", options: [...] });
+ *   type OptionsType = InferOptionsType<typeof subcommand>;
+ */
+export type InferOptionsType<T extends Partial<Subcommand>> = T["options"] extends infer U extends Option[]
+  ? ToOptional<{ [K in U[number]["name"]]: z.infer<Extract<U[number], { name: K }>["type"]> }>
+  : undefined;
+
+/**
+ * - Infer the arguments type from a subcommand.
+ *
+ * @example
+ *   const subcommand = createSubcommand({ name: "build", arguments: [...] });
+ *   type ArgumentsType = InferArgumentsType<typeof subcommand>;
+ */
+export type InferArgumentsType<T extends Partial<Subcommand>> = T["arguments"] extends infer U extends Argument[]
+  ? { [K in keyof U]: U[K] extends { type: z.ZodTypeAny } ? z.infer<U[K]["type"]> : never }
+  : undefined;
+
+/** `{ some props } & { other props }` => `{ some props, other props }` */
+export type Prettify<T> = { [K in keyof T]: T[K] } & {};
+
+/** Allow string type for literal union and get auto completion */
+export type LiteralUnion<T extends string> = T | (string & {});
+
+/** Extract the undefined properties from an object */
+type UndefinedProperties<T> = { [P in keyof T]-?: undefined extends T[P] ? P : never }[keyof T];
+
+/** Make undefined properties optional? */
+type ToOptional<T> = Prettify<
+  Partial<Pick<T, UndefinedProperties<T>>> & Pick<T, Exclude<keyof T, UndefinedProperties<T>>>
+>;
+
+export type OptionsArr2RecordType<T extends Option[] | undefined> = T extends Option[]
+  ? ToOptional<{ [K in T[number]["name"]]: z.infer<Extract<T[number], { name: K }>["type"]> }>
+  : object;
+
+export type ArgumentsArr2ArrType<T extends Argument[] | undefined> = T extends Argument[]
+  ? { arguments: { [K in keyof T]: T[K] extends { type: z.ZodTypeAny } ? z.infer<T[K]["type"]> : never } }
+  : object;
+
+export type Positional<S extends Partial<Subcommand>> = S["allowPositional"] extends true ? { positional: string[] } : object;
+
+export type Info<T extends Option[] | undefined> = T extends Option[]
+  ? {
+      _info: ToOptional<{
+        [K in T[number]["name"]]: Extract<T[number], { name: K }> extends infer U extends Option
+          ? undefined extends z.infer<U["type"]>
+            ? undefined | Prettify<_Info & U> // if optional add undefined
+            : Prettify<_Info & U>
+          : never;
+      }>;
+    }
+  : object;
+
+export type NoSubcommand = { name: undefined };
+
+export type ParseResult<S extends Partial<Subcommand>[]> = {
+  [K in keyof S]: Prettify<
+    { subcommand: S[K]["name"] } & Positional<S[K]> &
+      Info<S[K]["options"]> &
+      OptionsArr2RecordType<S[K]["options"]> &
+      ArgumentsArr2ArrType<S[K]["arguments"]>
+  >;
+}[number];
+
+export type PrintMethods<N extends Subcommand["name"] | undefined> = {
+  printCliHelp: (options?: PrintHelpOpt) => void;
+  printSubcommandHelp: (subcommand: LiteralUnion<NonNullable<N>>, options?: PrintHelpOpt) => void;
+};
+
+export type UnSafeParseResult<S extends Partial<Subcommand>[]> = Prettify<
+  ParseResult<S> & PrintMethods<S[number]["name"]>
+>;
+
+export type SafeParseResult<S extends Partial<Subcommand>[]> = Prettify<
+  ({ success: false; error: Error } | { success: true; data: ParseResult<S> }) & PrintMethods<S[number]["name"]>
+>;
+
+export type ActionFn<T extends Subcommand | Cli> = {
+  setAction: (actions: (res: UnSafeParseResult<[T]>) => void) => void;
+};

package/src/utils.ts

@@ -0,0 +1,154 @@
+import assert from "node:assert";
+import { z } from "zod";
+
+/**
+ * @param name - Should start with `'--'`
+ * @returns - The transformed name E.g. `--input-dir` -> `InputDir`
+ */
+export function transformArg(name: string): string {
+  assert(name.startsWith("-"), `[transformArg] Invalid arg name: ${name}`);
+  name = name.startsWith("--") ? name.substring(2) : name.substring(1);
+  return name.replace(/-([a-z])/g, g => g[1].toUpperCase());
+}
+
+/** - Reverse of `transformArg`. E.g. `InputDir` -> `--input-dir` , `i` -> `-i` */
+export function transformOptionToArg(name: string): string {
+  name = name.replace(/^[A-Z]/g, g => g.toLowerCase()); // first letter always lower case
+  if (name.length === 1) return `-${name}`;
+  return `--${name.replace(/[A-Z]/g, g => "-" + g.toLowerCase())}`;
+}
+
+/** - Check if an arg string is a short arg. E.g. `-i` -> `true` */
+export function isFlagArg(name: string): boolean {
+  return /^-[a-z]$/.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) || name.startsWith("--");
+}
+
+/**
+ * - Transform option name to no name. E.g. `include` -> `noInclude`
+ * - For short name like `-i` it will be ignored
+ */
+export function noName(name: string): string {
+  if (name.length === 1) return name;
+  return "no" + name.replace(/^[a-z]/, g => g.toUpperCase());
+}
+
+/** - Convert string to boolean. E.g. `"true"` -> `true` , `"false"` -> `false` */
+export function stringToBoolean(str: string): boolean {
+  if (str.toLowerCase() === "true") return true;
+  if (str.toLowerCase() === "false") return false;
+  throw new Error(`[stringToBoolean] Invalid boolean value: "${str}"; Expected "true" or "false"`);
+}
+
+export function getOrdinalPlacement(index: number): string {
+  if (index < 0) return "";
+
+  const suffixes = ["th", "st", "nd", "rd"];
+  const lastDigit = index % 10;
+  const lastTwoDigits = index % 100;
+
+  const suffix =
+    lastDigit === 1 && lastTwoDigits !== 11
+      ? suffixes[1]
+      : lastDigit === 2 && lastTwoDigits !== 12
+        ? suffixes[2]
+        : lastDigit === 3 && lastTwoDigits !== 13
+          ? suffixes[3]
+          : suffixes[0];
+
+  return `${index + 1}${suffix}`;
+}
+
+/** - Check if a schema is a boolean */
+export function isBooleanSchema(schema: z.ZodTypeAny): boolean {
+  let type = schema;
+  while (type) {
+    if (type instanceof z.ZodBoolean) {
+      return true;
+    }
+
+    if (type instanceof z.ZodLiteral) {
+      return type.value === true || type.value === false;
+    }
+
+    type = type._def.innerType;
+  }
+
+  return false;
+}
+
+export function getDefaultValueFromSchema(schema: z.ZodTypeAny): unknown | undefined {
+  let type = schema;
+  while (type) {
+    if (type instanceof z.ZodDefault) {
+      const defaultValue = type._def.defaultValue();
+      return defaultValue;
+    }
+
+    type = type._def.innerType;
+  }
+
+  return undefined;
+}
+
+/** - Decouple flags E.g. `-rf` -> `-r, -f` */
+export function decoupleFlags(args: string[]): string[] {
+  const flagsRe = /^-[a-z]{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;
+}
+
+/** Print */
+export function print(...messages: string[]) {
+  return process.stdout.write(messages.join(" "));
+}
+
+/** Print line */
+export function println(...messages: string[]) {
+  messages = messages.filter(Boolean);
+  return console.log(...messages);
+}
+
+/** New line */
+export function ln(count: number) {
+  return "\n".repeat(count);
+}
+
+/** Space */
+export function indent(count: number) {
+  return " ".repeat(count);
+}
+
+/** Add indent before each new line */
+export function addIndentLn(message: string, indent: string = "") {
+  return message.replace(/\n/g, `\n${indent}`);
+}
+
+/** Concat strings */
+export function concat(...messages: string[]) {
+  messages = messages.filter(Boolean);
+  return messages.join(" ");
+}