zod-args-parser 1.2.8 → 2.0.0-beta.0

package/src/{parser/parse/parser-helpers.ts → parse/parser-utilities.ts}

@@ -1,22 +1,33 @@
-import type { Option, Subcommand } from "../../types.js";
+import type { Cli, Option, Subcommand } from "../types/definitions-types.ts";
 
 /**
  * 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 subcommandName - 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, subcommandArray: Subcommand[]): Subcommand | undefined {
-  return subcommandArray.find(c => {
+export function findSubcommandDefinition(
+  subcommandName: string | undefined,
+  cliDefinition: Cli,
+): Subcommand | Cli | undefined {
+  if (subcommandName === undefined) {
+    return cliDefinition;
+  }
+
+  if (!cliDefinition.subcommands) {
+    return;
+  }
+
+  return cliDefinition.subcommands.find(c => {
     // match for undefined too
-    if (c.name === subCmdName) {
+    if (c.name === subcommandName) {
       return true;
     }
 
     // match for aliases
-    return subCmdName && c.aliases && c.aliases.includes(subCmdName);
+    return subcommandName && c.aliases && c.aliases.includes(subcommandName);
   });
 }
 
@@ -25,32 +36,34 @@ export function findSubcommand(subCmdName: string | undefined, subcommandArray:
  *
  * 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 optionArgument - 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(optionArgument: string, options: [Option, ...Option[]]): Option | undefined {
+export function findOption(optionArgument: string, options: Record<string, Option>): [string, Option] | undefined {
   const validVariableNames = optionArgumentToVariableNames(optionArgument);
-  const isNegative = optionArgument.startsWith("--no-");
+  const isNegated = optionArgument.startsWith("--no-");
 
-  const option = options.find(o => {
-    if (validVariableNames.has(o.name)) {
+  const option = Object.entries(options).find(([optionName, option]) => {
+    if (validVariableNames.has(optionName)) {
       return true;
     }
 
-    if (isNegative && validVariableNames.has(negateOption(o.name))) {
+    const isBool = option._preparedType && option._preparedType.coerceTo === "boolean";
+
+    if (isNegated && isBool && validVariableNames.has(negateOption(optionName))) {
       return true;
     }
 
-    if (!o.aliases) {
+    if (!option.aliases) {
       return false;
     }
 
-    if (o.aliases.some(a => validVariableNames.has(a))) {
+    if (option.aliases.some(a => validVariableNames.has(a))) {
       return true;
     }
 
-    if (isNegative && o.aliases.map(alias => negateOption(alias)).some(a => validVariableNames.has(a))) {
+    if (isNegated && isBool && option.aliases.map(alias => negateOption(alias)).some(a => validVariableNames.has(a))) {
       return true;
     }
 
@@ -85,13 +98,20 @@ export function decoupleFlags(arguments_: string[]): string[] {
 }
 
 /**
- * - Transforms an option argument name to a valid JavaScript variable name
+ * Transforms an option name to a set of variants: `camelCase`, `PascalCase`, `snake_case`, `SCREAMING_SNAKE_CASE`.
+ *
+ * **Example** for `--input-dir`
+ *
+ * - CamelCase: `inputDir`
+ * - PascalCase: `InputDir`
+ * - Snake_case: `input_dir`
+ * - SCREAMING_SNAKE_CASE: `INPUT_DIR`
  *
  * @param name - Should start with `'--'` or `'-'`
  */
 export function optionArgumentToVariableNames(name: string): Set<string> {
   if (!name.startsWith("-")) {
-    throw new Error(`[parseArgOptionName] Invalid arg name: ${name}`, { cause: "zod-args-parser" });
+    throw new Error(`invalid option name: ${name}`);
   }
 
   name = name.startsWith("--") ? name.slice(2) : name.slice(1); // remove prefix
@@ -136,14 +156,12 @@ export function isOptionArgument(name: string | boolean): boolean {
 }
 
 /**
- * - Transform option name to no name. E.g. `include` -> `noInclude`
- * - For short name like `-i` it will be ignored
+ * Transform option name to no name.
+ *
+ * - `verbose` -> `noVerbose`
+ * - `v` -> `noV`
  */
 export function negateOption(name: string): string {
-  if (name.length === 1) {
-    return name;
-  }
-
   return "no" + name.replace(/^[a-z]/, g => g.toUpperCase());
 }
 
@@ -155,12 +173,15 @@ export function transformOptionToArgument(name: string): string {
   }
 
   // snake_case, SCREAMING_SNAKE_CASE
-  if (name.includes("_") || /[A-Z]+$/.test(name)) {
+  if (/^[a-z_]+$/.test(name) || /^[A-Z_]+$/.test(name)) {
     name = name.replace(/_/g, "-");
     return `--${name.toLowerCase()}`;
   }
 
   // camelCase, PascalCase
-  name = name.replace(/[A-Z]/g, (match, index: number) => (index > 0 ? "-" + match : match)); // add "-" before camel case letters except for the first letter
+
+  // add "-" before camel case letters except for the first letter
+  name = name.replace(/[A-Z]/g, (match, index: number) => (index > 0 ? "-" + match : match));
+
   return `--${name.toLowerCase()}`;
 }

package/src/parse/safe-parse.ts

@@ -0,0 +1,76 @@
+import { validateCliDefinition } from "../definitions/validate-cli-definition.ts";
+import { parseArgv } from "../utilities.ts";
+import { buildCliContext } from "./context/cli-context-builder.ts";
+import { findSubcommandDefinition } from "./parser-utilities.ts";
+import { validate } from "./validation/validate-context.ts";
+
+import type { Cli } from "../types/definitions-types.ts";
+import type { CliParseResultWide } from "../types/types.ts";
+
+export function safeParse(stringOrArgv: string | string[], cliDefinition: Cli): CliParseResultWide {
+  const core = safeParseCore(stringOrArgv, cliDefinition);
+  if (core.error) return { error: core.error };
+
+  const { validateResult, subcommandObject } = core;
+
+  // Fire action (throw errors caused by the usage of the action hook)
+  if (subcommandObject._onExecute) {
+    for (const handler of subcommandObject._onExecute) {
+      handler(validateResult);
+    }
+  }
+
+  return { error: undefined, value: validateResult };
+}
+
+export async function safeParseAsync(stringOrArgv: string | string[], cliDefinition: Cli): Promise<CliParseResultWide> {
+  const core = safeParseCore(stringOrArgv, cliDefinition);
+  if (core.error) return { error: core.error };
+
+  const { validateResult, subcommandObject } = core;
+
+  // Fire action (throw errors caused by the usage of the action hook)
+  if (subcommandObject._onExecute) {
+    for (const handler of subcommandObject._onExecute) {
+      // eslint-disable-next-line @typescript-eslint/await-thenable
+      await handler(validateResult);
+    }
+  }
+
+  return { error: undefined, value: validateResult };
+}
+
+function safeParseCore(stringOrArgv: string | string[], cliDefinition: Cli) {
+  const argv = typeof stringOrArgv === "string" ? parseArgv(stringOrArgv) : stringOrArgv;
+
+  // validate cli definition
+  try {
+    validateCliDefinition(cliDefinition);
+  } catch (error) {
+    return { error: error as Error };
+  }
+
+  // Parse
+  let cliContext;
+  try {
+    cliContext = buildCliContext(argv, cliDefinition);
+  } catch (error) {
+    return { error: error as Error };
+  }
+
+  const subcommandObject = findSubcommandDefinition(cliContext.subcommand, cliDefinition);
+  if (!subcommandObject) {
+    const error = new Error(`Subcommand "${cliContext.subcommand}" does not exist`);
+    return { error };
+  }
+
+  // Validate context
+  let validateResult;
+  try {
+    validateResult = validate(cliContext, subcommandObject);
+  } catch (error) {
+    return { error: error as Error };
+  }
+
+  return { error: undefined, validateResult, subcommandObject };
+}

package/src/parse/validation/validate-context.ts

@@ -0,0 +1,23 @@
+import { validateArguments } from "./validators/arguments.ts";
+import { validateOptions } from "./validators/options.ts";
+
+import type { ContextWide } from "../../types/context-types.ts";
+import type { Cli, Subcommand } from "../../types/definitions-types.ts";
+import type { OutputTypeWide } from "../../types/io-types.ts";
+
+/** @throws {Error} */
+export function validate(context: ContextWide, commandDefinition: Subcommand | Cli) {
+  const output: OutputTypeWide = {
+    subcommand: context.subcommand,
+    positionals: context.positionals,
+    context: context,
+  };
+
+  // validate options
+  validateOptions({ commandDefinition, context, output });
+
+  // validate arguments
+  validateArguments({ commandDefinition, context, output });
+
+  return output;
+}

package/src/parse/validation/validators/arguments.ts

@@ -0,0 +1,59 @@
+import { validateSync } from "../../../utilities.ts";
+import { validateConflictWith } from "./conflict.ts";
+import { validateExclusive } from "./exclusive.ts";
+import { validateRequires } from "./requires.ts";
+
+import type { ContextWide } from "../../../types/context-types.ts";
+import type { Cli, Subcommand } from "../../../types/definitions-types.ts";
+import type { OutputTypeWide } from "../../../types/io-types.ts";
+
+interface ValidateArgument {
+  commandDefinition: Subcommand | Cli;
+  context: ContextWide;
+  output: OutputTypeWide;
+}
+
+/** @throws {Error} */
+export function validateArguments({ commandDefinition, context, output }: ValidateArgument) {
+  if (!context.arguments) return;
+
+  output.arguments ??= {};
+
+  const argumentsDefinition = commandDefinition.arguments;
+  if (!argumentsDefinition) {
+    throw new Error(`Subcommand "${context.subcommand}" does not have arguments`);
+  }
+
+  for (const [argumentName, argument] of Object.entries(argumentsDefinition)) {
+    validateRequires({ name: argumentName, commandDefinition, optionOrArgument: argument, context, type: "option" });
+    validateExclusive({ name: argumentName, optionOrArgument: argument, context, type: "option" });
+    validateConflictWith({ name: argumentName, optionOrArgument: argument, context, type: "option" });
+  }
+
+  const argumentContextEntries = Object.entries(context.arguments);
+
+  for (const [name, { passedValue, stringValue, source, schema }] of argumentContextEntries) {
+    const isProgrammatic = source === "programmatic";
+
+    const argument = argumentsDefinition[name];
+    if (!argument) {
+      throw new Error(`Subcommand "${context.subcommand}" does not have the argument "${name}"`);
+    }
+
+    if (!argument._preparedType) {
+      throw new Error(`internal error: missing prepared type for the argument "${name}"`);
+    }
+
+    const safeParseResult = isProgrammatic
+      ? validateSync(schema, passedValue)
+      : argument._preparedType.validate(stringValue);
+
+    if (safeParseResult.issues) {
+      throw new Error(
+        `The argument ${name} argument ${isProgrammatic ? "" : `"${stringValue}"`} is invalid: ${safeParseResult.issues.map(issue => issue.message).join(", ")}`,
+      );
+    }
+
+    output.arguments[name] = safeParseResult.value;
+  }
+}

package/src/parse/validation/validators/conflict.ts

@@ -0,0 +1,68 @@
+import { isOptionOrArgumentExplicitlyPassed } from "./explicitly-passed.ts";
+
+import type { ContextWide } from "../../../types/context-types.ts";
+import type { Argument, Option } from "../../../types/definitions-types.ts";
+
+interface ValidateConflictOptions {
+  /** The option or argument name to check its `requires` */
+  name: string;
+
+  /** The option or argument to check */
+  optionOrArgument: Option | Argument;
+
+  /** The parsed context */
+  context: ContextWide;
+
+  /** What we're checking */
+  type: "option" | "argument";
+}
+
+/** @throws {Error} */
+export function validateConflictWith({ name, optionOrArgument, context, type }: ValidateConflictOptions) {
+  const conflictWith = optionOrArgument.conflictWith;
+  if (!conflictWith || conflictWith.length === 0) return;
+
+  // Check if the options/argument is passed
+  if (!isOptionOrArgumentExplicitlyPassed(name, context)) return;
+
+  const conflictedOptions: string[] = [];
+  const conflictedArguments: string[] = [];
+
+  if (context.options) {
+    for (const [optionName, optionContext] of Object.entries(context.options)) {
+      if (optionName === name) continue; // don't check self
+      if (!conflictWith.includes(optionName)) continue; // not a conflict
+      if (optionContext.source === "default") continue; // not explicitly passed
+      conflictedOptions.push(optionName);
+    }
+  }
+
+  if (context.arguments) {
+    for (const [argumentName, argumentContext] of Object.entries(context.arguments)) {
+      if (argumentName === name) continue; // don't check self
+      if (!conflictWith.includes(argumentName)) continue; // not a conflict
+      if (argumentContext.source === "default") continue; // not explicitly passed
+      conflictedArguments.push(argumentName);
+    }
+  }
+
+  if (conflictedOptions.length === 0 && conflictedArguments.length === 0) return; // OK
+
+  const parts: string[] = [];
+
+  if (conflictedOptions.length > 0) {
+    const formatted = conflictedOptions.map(o => `"${o}"`).join(", ");
+    const s = conflictedOptions.length > 1 ? "s" : "";
+    parts.push(`option${s} ${formatted}`);
+  }
+
+  if (conflictedArguments.length > 0) {
+    const formatted = conflictedArguments.map(a => `"${a}"`).join(", ");
+    const s = conflictedArguments.length > 1 ? "s" : "";
+    parts.push(`argument${s} ${formatted}`);
+  }
+
+  const joinedParts = parts.join(" and ");
+
+  throw new Error(`${type} "${name}" cannot be used with the ${joinedParts} because they are mutually exclusive.`);
+}

package/src/parse/validation/validators/exclusive.ts

@@ -0,0 +1,70 @@
+import { isOptionOrArgumentExplicitlyPassed } from "./explicitly-passed.ts";
+
+import type { ContextWide } from "../../../types/context-types.ts";
+import type { Argument, Option } from "../../../types/definitions-types.ts";
+
+interface ValidateExclusiveOptions {
+  /** The option or argument name to check its `requires` */
+  name: string;
+
+  /** The option or argument to check */
+  optionOrArgument: Option | Argument;
+
+  /** The parsed context */
+  context: ContextWide;
+
+  /** What we're checking */
+  type: "option" | "argument";
+}
+
+/** @throws {Error} */
+export function validateExclusive({ name, optionOrArgument, context, type }: ValidateExclusiveOptions) {
+  const exclusive = optionOrArgument.exclusive;
+  if (!exclusive) return;
+
+  // Check if the options/argument is passed
+  if (!isOptionOrArgumentExplicitlyPassed(name, context)) return;
+
+  const requires = optionOrArgument.requires ?? [];
+
+  const mutuallyExclusiveOptions: string[] = [];
+  const mutuallyExclusiveArguments: string[] = [];
+
+  if (context.options) {
+    for (const [optionName, optionContext] of Object.entries(context.options)) {
+      if (optionName === name) continue; // don't check self
+      if (requires.includes(optionName)) continue; // allow required options
+      if (optionContext.source === "default") continue; // not explicitly passed
+      mutuallyExclusiveOptions.push(optionName);
+    }
+  }
+
+  if (context.arguments) {
+    for (const [argumentName, argumentContext] of Object.entries(context.arguments)) {
+      if (argumentName === name) continue; // don't check self
+      if (requires.includes(argumentName)) continue; // allow required arguments
+      if (argumentContext.source === "default") continue; // not explicitly passed
+      mutuallyExclusiveArguments.push(argumentName);
+    }
+  }
+
+  if (mutuallyExclusiveOptions.length === 0 && mutuallyExclusiveArguments.length === 0) return;
+
+  const parts: string[] = [];
+
+  if (mutuallyExclusiveOptions.length > 0) {
+    const formatted = mutuallyExclusiveOptions.map(o => `"${o}"`).join(", ");
+    const s = mutuallyExclusiveOptions.length > 1 ? "s" : "";
+    parts.push(`option${s} ${formatted}`);
+  }
+
+  if (mutuallyExclusiveArguments.length > 0) {
+    const formatted = mutuallyExclusiveArguments.map(a => `"${a}"`).join(", ");
+    const s = mutuallyExclusiveArguments.length > 1 ? "s" : "";
+    parts.push(`argument${s} ${formatted}`);
+  }
+
+  const joinedParts = parts.join(" and ");
+
+  throw new Error(`${type} "${name}" cannot be used with the ${joinedParts} because they are mutually exclusive.`);
+}

package/src/parse/validation/validators/explicitly-passed.ts

@@ -0,0 +1,15 @@
+import type { ContextWide } from "../../../types/context-types.ts";
+
+export function isArgumentExplicitlyPassed(name: string, context: ContextWide) {
+  if (!context.arguments) return false;
+  return name in context.arguments && context.arguments[name].source !== "default";
+}
+
+export function isOptionExplicitlyPassed(name: string, context: ContextWide) {
+  if (!context.options) return false;
+  return name in context.options && context.options[name].source !== "default";
+}
+
+export function isOptionOrArgumentExplicitlyPassed(name: string, context: ContextWide) {
+  return isOptionExplicitlyPassed(name, context) || isArgumentExplicitlyPassed(name, context);
+}

package/src/parse/validation/validators/options.ts

@@ -0,0 +1,59 @@
+import { validateSync } from "../../../utilities.ts";
+import { validateConflictWith } from "./conflict.ts";
+import { validateExclusive } from "./exclusive.ts";
+import { validateRequires } from "./requires.ts";
+
+import type { ContextWide } from "../../../types/context-types.ts";
+import type { Cli, Subcommand } from "../../../types/definitions-types.ts";
+import type { OutputTypeWide } from "../../../types/io-types.ts";
+
+interface ValidateOptions {
+  commandDefinition: Subcommand | Cli;
+  context: ContextWide;
+  output: OutputTypeWide;
+}
+
+/** @throws {Error} */
+export function validateOptions({ commandDefinition, context, output }: ValidateOptions) {
+  if (!context.options) return;
+
+  output.options ??= {};
+
+  const optionsDefinition = commandDefinition.options;
+  if (!optionsDefinition) {
+    throw new Error(`subcommand "${context.subcommand}" does not have options`);
+  }
+
+  for (const [optionName, option] of Object.entries(optionsDefinition)) {
+    validateRequires({ name: optionName, commandDefinition, optionOrArgument: option, context, type: "option" });
+    validateExclusive({ name: optionName, optionOrArgument: option, context, type: "option" });
+    validateConflictWith({ name: optionName, optionOrArgument: option, context, type: "option" });
+  }
+
+  const optionContextEntries = Object.entries(context.options);
+
+  for (const [optionName, { passedValue, stringValue, flag, source, schema }] of optionContextEntries) {
+    const option = optionsDefinition[optionName];
+    if (!option) {
+      throw new Error(`subcommand "${context.subcommand}" does not have option "${optionName}"`);
+    }
+
+    if (!option._preparedType) {
+      throw new Error(`internal error: missing prepared type for option "${optionName}"`);
+    }
+
+    const isProgrammatic = source === "programmatic";
+
+    const safeParseResult = isProgrammatic
+      ? validateSync(schema, passedValue)
+      : option._preparedType.validate(stringValue);
+
+    if (safeParseResult.issues) {
+      throw new Error(
+        `invalid value ${isProgrammatic ? "" : `"${stringValue}"`} for "${isProgrammatic ? optionName : flag}": ${safeParseResult.issues.map(issue => issue.message).join(", ")}`,
+      );
+    }
+
+    output.options[optionName] = safeParseResult.value;
+  }
+}

package/src/parse/validation/validators/requires.ts

@@ -0,0 +1,82 @@
+import {
+  isArgumentExplicitlyPassed,
+  isOptionExplicitlyPassed,
+  isOptionOrArgumentExplicitlyPassed,
+} from "./explicitly-passed.ts";
+
+import type { ContextWide } from "../../../types/context-types.ts";
+import type { Argument, Cli, Option, Subcommand } from "../../../types/definitions-types.ts";
+
+interface ValidateRequiresOptions {
+  /** The option or argument name to check its `requires` */
+  name: string;
+
+  /** The subcommand or cli configuration */
+  commandDefinition: Subcommand | Cli;
+
+  /** The option or argument to check */
+  optionOrArgument: Option | Argument;
+
+  /** The parsed context */
+  context: ContextWide;
+
+  /** What we're checking */
+  type: "option" | "argument";
+}
+
+/** @throws {Error} */
+export function validateRequires({
+  name,
+  commandDefinition,
+  optionOrArgument,
+  context,
+  type,
+}: ValidateRequiresOptions) {
+  const requires = optionOrArgument.requires;
+  if (!requires || requires.length === 0) return;
+
+  // Check if the options/argument is passed
+  if (!isOptionOrArgumentExplicitlyPassed(name, context)) return;
+
+  const optionsDefinition = commandDefinition.options ?? {};
+
+  const missingOptions: string[] = [];
+  const missingArguments: string[] = [];
+
+  for (const requiredName of requires) {
+    const isOption = requiredName in optionsDefinition;
+
+    const provided = isOption
+      ? isOptionExplicitlyPassed(requiredName, context)
+      : isArgumentExplicitlyPassed(requiredName, context);
+
+    if (provided) continue;
+
+    if (isOption) {
+      missingOptions.push(requiredName);
+      continue;
+    }
+
+    missingArguments.push(requiredName);
+  }
+
+  if (missingOptions.length === 0 && missingArguments.length === 0) return; // OK
+
+  const parts: string[] = [];
+
+  if (missingOptions.length > 0) {
+    const formatted = missingOptions.map(o => `"${o}"`).join(", ");
+    const s = missingOptions.length > 1 ? "s" : "";
+    parts.push(`option${s} ${formatted}`);
+  }
+
+  if (missingArguments.length > 0) {
+    const formatted = missingArguments.map(a => `"${a}"`).join(", ");
+    const s = missingArguments.length > 1 ? "s" : "";
+    parts.push(`argument${s} ${formatted}`);
+  }
+
+  const joinedParts = parts.join(" and ");
+
+  throw new Error(`${type} "${name}" cannot be used without the required ${joinedParts}.`);
+}