zod-args-parser 1.0.16 → 1.2.0

package/src/parser/unsafe-parse.ts

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

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

@@ -0,0 +1,21 @@
+import type { Argument, Option, Prettify, Schema, Subcommand, ToOptional, ZodInfer } from "../../types.js";
+import type { ParseResult } from "../parse/parse-types.js";
+
+type OptionsArr2RecordType<T extends Option[] | undefined> = T extends Option[]
+  ? ToOptional<{ [K in T[number]["name"]]: ZodInfer<Extract<T[number], { name: K }>["type"]> }>
+  : object;
+
+type ArgumentsArr2ArrType<T extends Argument[] | undefined> = T extends Argument[]
+  ? { [K in keyof T]: T[K] extends { type: Schema } ? ZodInfer<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: ArgumentsArr2ArrType<S[K]["arguments"]>;
+      positional: S[K]["allowPositional"] extends true ? string[] : never;
+      ctx: ParseResult<S>;
+    } & OptionsArr2RecordType<S[K]["options"]>
+  >;
+}[number];

package/src/parser/validate/validate.ts

@@ -0,0 +1,66 @@
+import { prettifyError } from "zod/v4";
+
+import { generateOrdinalSuffix, stringToBoolean } from "../../utils.js";
+import { isBooleanSchema, safeParseSchema } from "../../zod-utils.js";
+
+import type { ParseCtx } from "../parse/parse-types.js";
+
+/** The return result object temporarily type. used inside the `parse` function */
+type ResultsTempType = Record<string, unknown> & {
+  subcommand: string | undefined;
+  positional?: string[];
+  arguments?: unknown[];
+  ctx: ParseCtx;
+};
+
+export function validate(parsedData: ParseCtx) {
+  const results: ResultsTempType = {
+    subcommand: parsedData.subcommand,
+    positional: parsedData.positional,
+    ctx: parsedData,
+  };
+
+  // validate options
+  for (const [optionName, { schema, rawValue, flag }] of Object.entries(parsedData.options)) {
+    let optionsValue: string | boolean | undefined = rawValue;
+
+    // infer boolean value if possible
+    if (flag && rawValue && isBooleanSchema(schema)) {
+      const booleanValue = stringToBoolean(rawValue);
+      if (typeof booleanValue === "boolean") {
+        const isNegated = flag.startsWith("--no");
+        optionsValue = isNegated ? !booleanValue : booleanValue;
+      }
+    }
+
+    const res = safeParseSchema(schema, optionsValue);
+    if (!res.success) {
+      throw new Error(`Invalid value "${rawValue}" for "${flag}": ${prettifyError(res.error)}`, {
+        cause: "zod-args-parser",
+      });
+    }
+
+    results[optionName] = res.data;
+  }
+
+  // validate arguments
+  if (parsedData.arguments) {
+    if (!results.arguments) results.arguments = [];
+
+    for (const { schema, rawValue } of parsedData.arguments) {
+      const argValue = rawValue && isBooleanSchema(schema) ? stringToBoolean(rawValue) : rawValue;
+
+      const res = safeParseSchema(schema, argValue);
+      if (!res.success) {
+        throw new Error(
+          `The ${generateOrdinalSuffix(results.arguments.length)} argument "${rawValue}" is invalid: ${prettifyError(res.error)}`,
+          { cause: "zod-args-parser" },
+        );
+      }
+
+      results.arguments.push(res.data);
+    }
+  }
+
+  return results;
+}

package/src/types.ts

@@ -1,124 +1,17 @@
-import type { z } from "zod";
+import type * as Z3 from "zod/v3";
+import type * as Z4 from "zod/v4/core";
+import type { ParseResult } from "./parser/parse/parse-types.js";
+import type { ValidateResult } from "./parser/validate/validate-type.js";
 
-export interface CliMetadata {
-  /** The name of the cli program. */
-  readonly name: string;
+export type SchemaV3 = Z3.ZodTypeAny;
+export type SchemaV4 = Z4.$ZodType;
+export type Schema = SchemaV3 | SchemaV4;
 
-  /** - The description of the cli program. Empty string if not provided */
-  readonly description: string;
-
-  /** - The placeholder of the option. Empty string if not provided */
-  readonly placeholder: 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: z.ZodTypeAny;
-}
-
-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: z.ZodTypeAny;
-}
+export type ZodInfer<T extends Schema> = T extends SchemaV4 ? Z4.infer<T> : T extends SchemaV3 ? Z3.infer<T> : never;
 
 export type Subcommand = {
   /**
-   * - The subcommand name, use `kebab-case`.
+   * - The subcommand name
    * - Make sure to not duplicate commands and aliases.
    *
    * @example
@@ -182,11 +75,21 @@ export type Subcommand = {
    *   const helpCommand = createSubcommand({ name: "help", options: [...] });
    *   helpCommand.setAction(res => console.log(res));
    */
-  action?: (results?: any) => void;
+  action?: (results?: any) => any;
+
+  /**
+   * - The preValidation hook is executed before the action.
+   * - To get typescript types use `setPreValidationHook` instead of this.
+   *
+   * @example
+   *   const helpCommand = createSubcommand({ name: "help", options: [...] });
+   *   helpCommand.setPreValidationHook(ctx => console.log(ctx));
+   */
+  preValidation?: (ctx?: any) => any;
 };
 
 export type Cli = Prettify<
-  Omit<Subcommand, "name"> & {
+  Omit<Subcommand, "name" | "aliases" | "placeholder"> & {
     /** - The name of the CLI program. */
     cliName: string;
   }
@@ -194,22 +97,22 @@ export type Cli = Prettify<
 
 export type Option = {
   /**
-   * - The name of the option, use `CamelCase`.
-   * - For example: the syntax for the option `rootPath` is `--root-path`.
+   * The name of the option, 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`
    */
   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
+   * @see https://zod.dev/api
    */
-  type: z.ZodTypeAny;
+  type: Schema;
 
   /**
    * - The description of the option.
@@ -241,14 +144,9 @@ export type Argument = {
   /**
    * - 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
+   * @see https://zod.dev/api
    */
-  type: z.ZodTypeAny;
+  type: Schema;
 
   /**
    * - The description of the argument.
@@ -265,52 +163,21 @@ export type Argument = {
 
 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";
-};
+/** - The colors to use for the help message. */
+export type HelpMsgStyle = Record<
+  | "title"
+  | "description"
+  | "default"
+  | "optional"
+  | "exampleTitle"
+  | "example"
+  | "command"
+  | "option"
+  | "argument"
+  | "placeholder"
+  | "punctuation",
+  ColorFnType
+>;
 
 /**
  * - Infer the options type from a subcommand.
@@ -320,7 +187,7 @@ export type _Info = {
  *   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"]> }>
+  ? ToOptional<{ [K in U[number]["name"]]: ZodInfer<Extract<U[number], { name: K }>["type"]> }>
   : undefined;
 
 /**
@@ -331,7 +198,7 @@ export type InferOptionsType<T extends Partial<Subcommand>> = T["options"] exten
  *   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 }
+  ? { [K in keyof U]: U[K] extends { type: Schema } ? ZodInfer<U[K]["type"]> : never }
   : undefined;
 
 /** `{ some props } & { other props }` => `{ some props, other props }` */
@@ -341,68 +208,36 @@ export type Prettify<T> = { [K in keyof T]: T[K] } & {};
 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];
+export type UndefinedProperties<T> = { [P in keyof T]-?: undefined extends T[P] ? P : never }[keyof T];
 
 /** Make undefined properties optional? */
-type ToOptional<T> = Prettify<
+export 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"]> = {
-  printCliHelp: (options?: PrintHelpOpt) => void;
-  printSubcommandHelp: (subcommand: LiteralUnion<NonNullable<N>>, options?: PrintHelpOpt) => void;
+  printCliHelp: (style?: Partial<HelpMsgStyle>) => void;
+  printSubcommandHelp: (subcommand: LiteralUnion<NonNullable<N>>, style?: Partial<HelpMsgStyle>) => void;
 };
 
-export type UnSafeParseResult<S extends Partial<Subcommand>[]> =
+export type UnsafeParseResult<S extends Partial<Subcommand>[]> =
   CheckDuplicatedSubcommands<S> extends infer E extends string
     ? E
-    : Prettify<ParseResult<S> & PrintMethods<NonNullable<S[number]["name"]>>>;
+    : Prettify<ValidateResult<S> & PrintMethods<NonNullable<S[number]["name"]>>>;
 
 export type SafeParseResult<S extends Partial<Subcommand>[]> =
   CheckDuplicatedSubcommands<S> extends infer E extends string
     ? E
     : Prettify<
-        ({ success: false; error: Error } | { success: true; data: ParseResult<S> }) &
+        ({ success: false; error: Error } | { success: true; data: ValidateResult<S> }) &
           PrintMethods<NonNullable<S[number]["name"]>>
       >;
 
-export type ActionFn<T extends Subcommand | Cli> = {
-  setAction: (actions: (res: UnSafeParseResult<[T]>) => void) => void;
+export type ActionsFn<T extends Subcommand | Cli> = {
+  setAction: (actions: (res: UnsafeParseResult<[T]>) => void) => void;
+  setPreValidationHook: (hookFn: (ctx: ParseResult<[T]>) => void) => void;
 };
 
 /** - Combine `name` and `aliases` to a `string[]` */
@@ -430,20 +265,51 @@ type IsDuplicatesInArr<Input extends any[]> = Input extends [infer Item, ...infe
 /**
  * - Check if there are duplicated options including aliases in `subcommand`
  * - Return an error message if duplicated is found
- * - Return `subcommand` if not found
+ * - Return `undefined` if not found
  */
 export type CheckDuplicatedOptions<T extends { options?: Option[] }> = T["options"] extends infer O extends Option[]
-  ? IsDuplicatesInArr<MapNameAndAliases2StrArr<O>> extends infer D extends string
-    ? `>>> Error: Duplicated Options \`${D}\` <<<`
-    : T
-  : T;
+  ? IsDuplicatesInArr<MapNameAndAliases2StrArr<O>> extends infer Name extends string
+    ? `>>> Error: Duplicated Options. Check the options with the name \`${Name}\` <<<`
+    : undefined
+  : undefined;
 
 /**
  * - Check for duplicated subcommands including aliases
  * - Return an error message if duplicated is found
- * - Return the `subcommand[]` if no error
+ * - Return the `undefined` if no error
+ */
+type CheckDuplicatedSubcommands<T extends Partial<Subcommand>[]> =
+  IsDuplicatesInArr<MapNameAndAliases2StrArr<T>> extends infer Name extends string
+    ? `>>> Error: Duplicated Subcommand. Check the subcommands with the name \`${Name}\` <<<`
+    : undefined;
+
+/**
+ * - Check for duplicated arguments
+ * - Return an error message if duplicated is found
+ * - Return the `undefined` if no error
+ */
+export type CheckDuplicatedArguments<T extends { arguments?: Argument[] }> = T["arguments"] extends infer A extends
+  Argument[]
+  ? IsDuplicatesInArr<MapNameAndAliases2StrArr<A>> extends infer Name extends string
+    ? `>>> Error: Duplicated Arguments. Check the arguments with the name \`${Name}\` <<<`
+    : undefined
+  : undefined;
+
+type OptionalUnion = Z3.ZodOptional<Z3.ZodAny> | Z4.$ZodOptional | Z3.ZodDefault<Z3.ZodAny> | Z4.$ZodDefault;
+
+/**
+ * - Insures that only the last argument is optional
+ * - Insures no optional arguments are allowed when `allowPositional` is enabled
  */
-export type CheckDuplicatedSubcommands<T extends Partial<Subcommand>[]> =
-  IsDuplicatesInArr<MapNameAndAliases2StrArr<T>> extends infer D extends string
-    ? `>>> Error: Duplicated Subcommand \`${D}\` <<<`
+export type CheckArgumentsOptional<T extends { allowPositional?: boolean; arguments?: readonly Argument[] }> =
+  T["arguments"] extends readonly [...infer Rest, infer Last]
+    ? Last extends { type: OptionalUnion }
+      ? T["allowPositional"] extends true
+        ? `>>> Error: Cannot have optional arguments when \`allowPositional\` is enabled. The argument \`${Last extends { name: string } ? Last["name"] : ""}\` should not be optional <<<`
+        : T
+      : Extract<Rest[number], { type: OptionalUnion }> extends never
+        ? T
+        : T["allowPositional"] extends true
+          ? `>>> Error: Cannot have optional arguments when \`allowPositional\` is enabled. The argument \`${Rest[number] extends { name: string } ? Rest[number]["name"] : ""}\` should not be optional <<<`
+          : `>>> Error: Only the last argument may be optional. The argument \`${Rest[number] extends { name: string } ? Rest[number]["name"] : ""}\` should not be optional <<<`
     : T;