zod-args-parser 2.0.0-beta.1 → 2.0.0-beta.3

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

@@ -1,4 +1,8 @@
-import { validateSync } from "../../../utilities.ts";
+import { CliError } from "../../../cli-error/cli-error.ts";
+import { ErrorCause } from "../../../cli-error/error-cause.ts";
+import { InternalErrorCode } from "../../../cli-error/error-code/internal-error-code.ts";
+import { ValidationErrorCode } from "../../../cli-error/error-code/validation-error-code.ts";
+import { validateSync } from "../../../utilities/schema-utilities.ts";
 import { validateConflictWith } from "./conflict.ts";
 import { validateExclusive } from "./exclusive.ts";
 import { validateRequires } from "./requires.ts";
@@ -13,35 +17,50 @@ interface ValidateArgument {
   output: OutputTypeWide;
 }
 
-/** @throws {Error} */
+/** @throws {CliError} */
 export function validateArguments({ commandDefinition, context, output }: ValidateArgument) {
   if (!context.arguments) return;
 
   output.arguments ??= {};
 
+  const commandKind = "cliName" in commandDefinition ? "command" : "subcommand";
+  const commandName = "cliName" in commandDefinition ? commandDefinition.cliName : commandDefinition.name;
+
   const argumentsDefinition = commandDefinition.arguments;
   if (!argumentsDefinition) {
-    throw new Error(`Subcommand "${context.subcommand}" does not have arguments`);
+    throw new CliError({
+      cause: ErrorCause.Validation,
+      code: ValidationErrorCode.NoArgumentsToValidate,
+      context: { commandKind, commandName },
+    });
   }
 
   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" });
+    validateRequires({ name: argumentName, commandDefinition, optionOrArgument: argument, context, kind: "option" });
+    validateExclusive({ name: argumentName, optionOrArgument: argument, context, kind: "option" });
+    validateConflictWith({ name: argumentName, optionOrArgument: argument, context, kind: "option" });
   }
 
   const argumentContextEntries = Object.entries(context.arguments);
 
-  for (const [name, { passedValue, stringValue, source, schema }] of argumentContextEntries) {
+  for (const [argumentName, { passedValue, stringValue, source, schema }] of argumentContextEntries) {
     const isProgrammatic = source === "programmatic";
 
-    const argument = argumentsDefinition[name];
+    const argument = argumentsDefinition[argumentName];
     if (!argument) {
-      throw new Error(`Subcommand "${context.subcommand}" does not have the argument "${name}"`);
+      throw new CliError({
+        cause: ErrorCause.Validation,
+        code: ValidationErrorCode.UnknownArgumentValidation,
+        context: { commandKind, commandName, argumentName },
+      });
     }
 
     if (!argument._preparedType) {
-      throw new Error(`internal error: missing prepared type for the argument "${name}"`);
+      throw new CliError({
+        cause: ErrorCause.Internal,
+        code: InternalErrorCode.MissingPreparedTypes,
+        context: { commandKind, commandName, kind: "argument", name: argumentName },
+      });
     }
 
     const safeParseResult = isProgrammatic
@@ -49,11 +68,20 @@ export function validateArguments({ commandDefinition, context, output }: Valida
       : 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(", ")}`,
-      );
+      throw new CliError({
+        cause: ErrorCause.Validation,
+        code: ValidationErrorCode.SchemaValidationFailed,
+        context: {
+          commandKind,
+          commandName,
+          kind: "option",
+          name: argumentName,
+          inputValue: isProgrammatic ? passedValue : stringValue,
+          issues: safeParseResult.issues,
+        },
+      });
     }
 
-    output.arguments[name] = safeParseResult.value;
+    output.arguments[argumentName] = safeParseResult.value;
   }
 }

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

@@ -1,3 +1,6 @@
+import { CliError } from "../../../cli-error/cli-error.ts";
+import { ErrorCause } from "../../../cli-error/error-cause.ts";
+import { ValidationErrorCode } from "../../../cli-error/error-code/validation-error-code.ts";
 import { isOptionOrArgumentExplicitlyPassed } from "./explicitly-passed.ts";
 
 import type { ContextWide } from "../../../types/context-types.ts";
@@ -14,11 +17,11 @@ interface ValidateConflictOptions {
   context: ContextWide;
 
   /** What we're checking */
-  type: "option" | "argument";
+  kind: "option" | "argument";
 }
 
-/** @throws {Error} */
-export function validateConflictWith({ name, optionOrArgument, context, type }: ValidateConflictOptions) {
+/** @throws {CliError} */
+export function validateConflictWith({ name, optionOrArgument, context, kind }: ValidateConflictOptions) {
   const conflictWith = optionOrArgument.conflictWith;
   if (!conflictWith || conflictWith.length === 0) return;
 
@@ -48,21 +51,9 @@ export function validateConflictWith({ name, optionOrArgument, context, type }:
 
   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.`);
+  throw new CliError({
+    cause: ErrorCause.Validation,
+    code: ValidationErrorCode.MutuallyExclusiveConflict,
+    context: { kind, name, conflictedOptions, conflictedArguments },
+  });
 }

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

@@ -1,3 +1,6 @@
+import { CliError } from "../../../cli-error/cli-error.ts";
+import { ErrorCause } from "../../../cli-error/error-cause.ts";
+import { ValidationErrorCode } from "../../../cli-error/error-code/validation-error-code.ts";
 import { isOptionOrArgumentExplicitlyPassed } from "./explicitly-passed.ts";
 
 import type { ContextWide } from "../../../types/context-types.ts";
@@ -14,11 +17,11 @@ interface ValidateExclusiveOptions {
   context: ContextWide;
 
   /** What we're checking */
-  type: "option" | "argument";
+  kind: "option" | "argument";
 }
 
-/** @throws {Error} */
-export function validateExclusive({ name, optionOrArgument, context, type }: ValidateExclusiveOptions) {
+/** @throws {CliError} */
+export function validateExclusive({ name, optionOrArgument, context, kind }: ValidateExclusiveOptions) {
   const exclusive = optionOrArgument.exclusive;
   if (!exclusive) return;
 
@@ -27,15 +30,15 @@ export function validateExclusive({ name, optionOrArgument, context, type }: Val
 
   const requires = optionOrArgument.requires ?? [];
 
-  const mutuallyExclusiveOptions: string[] = [];
-  const mutuallyExclusiveArguments: string[] = [];
+  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 (requires.includes(optionName)) continue; // allow required options
       if (optionContext.source === "default") continue; // not explicitly passed
-      mutuallyExclusiveOptions.push(optionName);
+      conflictedOptions.push(optionName);
     }
   }
 
@@ -44,27 +47,15 @@ export function validateExclusive({ name, optionOrArgument, context, type }: Val
       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);
+      conflictedArguments.push(argumentName);
     }
   }
 
-  if (mutuallyExclusiveOptions.length === 0 && mutuallyExclusiveArguments.length === 0) return;
+  if (conflictedOptions.length === 0 && conflictedArguments.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.`);
+  throw new CliError({
+    cause: ErrorCause.Validation,
+    code: ValidationErrorCode.MutuallyExclusiveConflict,
+    context: { kind, name, conflictedOptions, conflictedArguments },
+  });
 }

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

@@ -1,4 +1,8 @@
-import { validateSync } from "../../../utilities.ts";
+import { CliError } from "../../../cli-error/cli-error.ts";
+import { ErrorCause } from "../../../cli-error/error-cause.ts";
+import { InternalErrorCode } from "../../../cli-error/error-code/internal-error-code.ts";
+import { ValidationErrorCode } from "../../../cli-error/error-code/validation-error-code.ts";
+import { validateSync } from "../../../utilities/schema-utilities.ts";
 import { validateConflictWith } from "./conflict.ts";
 import { validateExclusive } from "./exclusive.ts";
 import { validateRequires } from "./requires.ts";
@@ -13,33 +17,48 @@ interface ValidateOptions {
   output: OutputTypeWide;
 }
 
-/** @throws {Error} */
+/** @throws {CliError} */
 export function validateOptions({ commandDefinition, context, output }: ValidateOptions) {
   if (!context.options) return;
 
   output.options ??= {};
 
+  const commandKind = "cliName" in commandDefinition ? "command" : "subcommand";
+  const commandName = "cliName" in commandDefinition ? commandDefinition.cliName : commandDefinition.name;
+
   const optionsDefinition = commandDefinition.options;
   if (!optionsDefinition) {
-    throw new Error(`subcommand "${context.subcommand}" does not have options`);
+    throw new CliError({
+      cause: ErrorCause.Validation,
+      code: ValidationErrorCode.NoOptionsToValidate,
+      context: { commandKind, commandName },
+    });
   }
 
   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" });
+    validateRequires({ name: optionName, commandDefinition, optionOrArgument: option, context, kind: "option" });
+    validateExclusive({ name: optionName, optionOrArgument: option, context, kind: "option" });
+    validateConflictWith({ name: optionName, optionOrArgument: option, context, kind: "option" });
   }
 
   const optionContextEntries = Object.entries(context.options);
 
-  for (const [optionName, { passedValue, stringValue, flag, source, schema }] of optionContextEntries) {
+  for (const [optionName, { passedValue, stringValue, source, schema }] of optionContextEntries) {
     const option = optionsDefinition[optionName];
     if (!option) {
-      throw new Error(`subcommand "${context.subcommand}" does not have option "${optionName}"`);
+      throw new CliError({
+        cause: ErrorCause.Validation,
+        code: ValidationErrorCode.UnknownOptionValidation,
+        context: { commandKind, commandName, optionName },
+      });
     }
 
     if (!option._preparedType) {
-      throw new Error(`internal error: missing prepared type for option "${optionName}"`);
+      throw new CliError({
+        cause: ErrorCause.Internal,
+        code: InternalErrorCode.MissingPreparedTypes,
+        context: { commandKind, commandName, kind: "option", name: optionName },
+      });
     }
 
     const isProgrammatic = source === "programmatic";
@@ -49,9 +68,18 @@ export function validateOptions({ commandDefinition, context, output }: Validate
       : 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(", ")}`,
-      );
+      throw new CliError({
+        cause: ErrorCause.Validation,
+        code: ValidationErrorCode.SchemaValidationFailed,
+        context: {
+          commandKind,
+          commandName,
+          kind: "option",
+          name: optionName,
+          inputValue: isProgrammatic ? passedValue : stringValue,
+          issues: safeParseResult.issues,
+        },
+      });
     }
 
     output.options[optionName] = safeParseResult.value;

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

@@ -1,3 +1,6 @@
+import { CliError } from "../../../cli-error/cli-error.ts";
+import { ErrorCause } from "../../../cli-error/error-cause.ts";
+import { ValidationErrorCode } from "../../../cli-error/error-code/validation-error-code.ts";
 import {
   isArgumentExplicitlyPassed,
   isOptionExplicitlyPassed,
@@ -21,16 +24,16 @@ interface ValidateRequiresOptions {
   context: ContextWide;
 
   /** What we're checking */
-  type: "option" | "argument";
+  kind: "option" | "argument";
 }
 
-/** @throws {Error} */
+/** @throws {CliError} */
 export function validateRequires({
   name,
   commandDefinition,
   optionOrArgument,
   context,
-  type,
+  kind,
 }: ValidateRequiresOptions) {
   const requires = optionOrArgument.requires;
   if (!requires || requires.length === 0) return;
@@ -62,21 +65,9 @@ export function validateRequires({
 
   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}.`);
+  throw new CliError({
+    cause: ErrorCause.Validation,
+    code: ValidationErrorCode.RequiredDependencyMissing,
+    context: { kind, name, missingArguments, missingOptions },
+  });
 }

package/src/types/definitions-types.ts

@@ -1,7 +1,6 @@
 import type { OutputTypeWide } from "./io-types.ts";
 import type { InferSchemaOutputType, SchemaResult, SchemaType } from "./schema-types.ts";
 import type { CoerceMethod, CoerceTypes } from "./types.ts";
-import type { Widen } from "./utilities-types.ts";
 
 export interface PreparedType {
   schema: SchemaType;
@@ -11,20 +10,49 @@ export interface PreparedType {
   validate: (value: string | undefined) => SchemaResult;
 }
 
-// NOTE:
-// Putting these interfaces (`RequiredCoerce` and `OptionalCoerce`) in a union makes TypeScript treat them as a
-// combined structural type, so JSDoc doesn’t appear on hover.
-
 /** `schema` (generic) with required `coerce` */
 interface RequiredCoerce<Schema extends SchemaType> {
+  /**
+   * The schema to validate the input against.
+   *
+   * Any validation library that supports [`StandardSchemaV1`](https://github.com/standard-schema/standard-schema) and
+   * allows primitive types to be optional or have default values can be used.
+   *
+   * @example
+   *   schema: z.boolean().optional(),
+   *   schema: z.number().default(0),
+   *   schema: z.string(),
+   *   schema: z.array(z.string())
+   */
   schema: Schema;
-  coerce: CoerceMethod<Widen<InferSchemaOutputType<Schema>>>;
+
+  /**
+   * A function to convert the terminal string input into the schema's output type.
+   *
+   * When the expected input type is `string`, this is not required and can be omitted.
+   *
+   * The return type of this function must be the same as the output type of the `schema`.
+   *
+   * @example
+   *   schema: z.boolean(),
+   *   coerce: coerce.boolean
+   *
+   *   schema: z.number(),
+   *   coerce: coerce.number
+   *
+   *   schema: z.string(),
+   *   // coerce is not required in this case
+   *
+   *   schema: z.array(z.string()),
+   *   coerce: coerce.stringArray(",")
+   */
+  coerce: CoerceMethod<InferSchemaOutputType<Schema>>;
 }
 
 /** `schema` (string) with optional `coerce` */
 interface OptionalCoerce {
   schema: SchemaType<string | undefined>;
-  coerce?: CoerceMethod<string | undefined>;
+  coerce?: never;
 }
 
 // Derived from `Subcommand`
@@ -154,7 +182,7 @@ export interface Subcommand {
    *   const myCli = defineCLI({ name: "my-cli", subcommands: [helpCommand] });
    *   myCli.onExecute((result) => console.log(result));
    */
-  _onExecute?: ((result: OutputTypeWide) => void)[];
+  _onExecute?: ((result: OutputTypeWide) => void | Promise<void>)[];
 }
 
 interface OptionMeta extends MetaBase {