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

package/src/index.ts

@@ -20,8 +20,24 @@ export { defineSubcommand } from "./definitions/define-subcommand.ts";
 
 export { coerce } from "./coerce/coerce-methods.ts";
 
+export { CliError } from "./cli-error/cli-error.ts";
+export { ErrorCause } from "./cli-error/error-cause.ts";
+export { DefinitionErrorCode } from "./cli-error/error-code/definition-error-code.ts";
+export { InternalErrorCode } from "./cli-error/error-code/internal-error-code.ts";
+export { ParseErrorCode } from "./cli-error/error-code/parse-error-code.ts";
+export { ValidationErrorCode } from "./cli-error/error-code/validation-error-code.ts";
+
 export type * from "./types/context-types.ts";
 export type * from "./types/definitions-types.ts";
+export type {
+  CliErrorI,
+  CliErrorOptionUnion,
+  DefinitionErrorI,
+  ErrorCauseI,
+  InternalErrorI,
+  ParseErrorI,
+  ValidationErrorI,
+} from "./types/error-types.ts";
 export type * from "./types/help-message-types.ts";
 export type * from "./types/io-types.ts";
 export type * from "./types/metadata-types.ts";

package/src/markdown/generate-markdown.ts

@@ -1,5 +1,5 @@
 import { getCliMetadata } from "../metadata/cli-metadata.ts";
-import { escapeHtmlTags, stripAnsi } from "../utilities.ts";
+import { escapeHtmlTags, stripAnsi } from "../utilities/utilities.ts";
 
 import type { Cli } from "../types/definitions-types.ts";
 import type { ArgumentMetadata, OptionMetadata, SubcommandMetadata } from "../types/metadata-types.ts";
@@ -72,7 +72,6 @@ function renderOptions(optionsMetadata: OptionMetadata[] = [], h: number) {
     if (metadata.hidden) continue;
 
     const aliases = [metadata.nameAsArg].concat(metadata.aliasesAsArgs).join(", ");
-
     const placeholder = metadata.placeholder && ` ${metadata.placeholder}`;
 
     outString += `${"#".repeat(h)} \`${aliases + placeholder}\``;
@@ -92,7 +91,8 @@ function renderOptions(optionsMetadata: OptionMetadata[] = [], h: number) {
     }
 
     if (metadata.defaultValue !== undefined) {
-      outString += `\n**default:** \`${metadata.defaultValueAsString}\`\n`;
+      const nl = outString.endsWith("\n\n") ? "" : "\n";
+      outString += `${nl}**default:** \`${metadata.defaultValueAsString}\`\n`;
     }
 
     if (metadata.example) {
@@ -131,7 +131,8 @@ function renderArguments(argumentsMetadata: ArgumentMetadata[] = [], h: number)
     }
 
     if (metadata.defaultValue !== undefined) {
-      outString += `\n**default:** \`${metadata.defaultValueAsString}\`\n`;
+      const nl = outString.endsWith("\n\n") ? "" : "\n";
+      outString += `${nl}**default:** \`${metadata.defaultValueAsString}\`\n`;
     }
 
     if (metadata.example) {

package/src/metadata/arguments-metadata.ts

@@ -1,4 +1,5 @@
-import { defaultValueAndIsOptional, stringifyValue } from "../utilities.ts";
+import { defaultValueAndIsOptional } from "../utilities/schema-utilities.ts";
+import { stringifyValue } from "../utilities/utilities.ts";
 
 import type { Argument } from "../types/definitions-types.ts";
 import type { ArgumentMetadata } from "../types/metadata-types.ts";

package/src/metadata/options-metadata.ts

@@ -1,5 +1,6 @@
 import { transformOptionToArgument } from "../parse/parser-utilities.ts";
-import { defaultValueAndIsOptional, stringifyValue } from "../utilities.ts";
+import { defaultValueAndIsOptional } from "../utilities/schema-utilities.ts";
+import { stringifyValue } from "../utilities/utilities.ts";
 
 import type { Option } from "../types/definitions-types.ts";
 import type { OptionMetadata } from "../types/metadata-types.ts";

package/src/parse/context/cli-context-builder.ts

@@ -1,10 +1,14 @@
+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 { ParseErrorCode } from "../../cli-error/error-code/parse-error-code.ts";
 import {
   decoupleFlags,
   findOption,
   findSubcommandDefinition,
   isFlagArgument,
   isOptionArgument,
-  transformOptionToArgument,
+  splitAndGetKeys,
 } from "../parser-utilities.ts";
 
 import type { ContextWide } from "../../types/context-types.ts";
@@ -13,9 +17,10 @@ import type { Cli } from "../../types/definitions-types.ts";
 /**
  * Parse argv and create a cli context
  *
- * @throws {Error}
+ * @throws {CliError}
  */
 export function buildCliContext(argv: string[], cliDefinition: Cli) {
+  const cliName = cliDefinition.cliName;
   const subcommandArray = cliDefinition.subcommands ?? [];
   const allSubcommands = new Set<string>(subcommandArray.flatMap(c => [c.name, ...(c.aliases || [])]));
 
@@ -44,70 +49,136 @@ export function buildCliContext(argv: string[], cliDefinition: Cli) {
 
     const argumentAndValue = argvItem.split("=").filter(Boolean); // E.g --option=value -> ["--option", "value"]
     const argumentWithEquals = argvItem.includes("="); // E.g --option=value
-    const argument = argumentAndValue[0];
+    const [argument, keys] = splitAndGetKeys(argumentAndValue[0]); // E.g --option.foo.bar -> ["--option", ["foo", "bar"]]
+    const optionWithKeys = keys.length > 0; // E.g --option.foo.bar
     const argumentValue: string | undefined = argumentAndValue[1];
+    const isNegated = argument.startsWith("--no-");
 
     if (isOptionArgument(argument)) {
+      const commandDefinition = getCommandDefinition();
+      const commandKind = context.subcommand === undefined ? "command" : "subcommand";
+      const commandName = context.subcommand ?? cliName;
+
       if (isFlagArgument(argument) && argumentWithEquals) {
-        throw new Error(`flag arguments cannot be assigned using "=": "${argvItem}"`);
+        throw new CliError({
+          cause: ErrorCause.Parse,
+          code: ParseErrorCode.FlagAssignedValue,
+          context: { commandKind, commandName, flag: argument, value: argumentValue },
+        });
       }
 
-      const commandDefinition = getCommandDefinition();
       if (!commandDefinition) {
-        throw new Error(`unknown subcommand: "${context.subcommand}"`);
+        if (context.subcommand === undefined) {
+          throw new CliError({
+            cause: ErrorCause.Internal,
+            code: InternalErrorCode.CannotFindCliDefinition,
+            context: { cliName },
+          });
+        }
+
+        throw new CliError({
+          cause: ErrorCause.Parse,
+          code: ParseErrorCode.UnknownSubcommand,
+          context: { commandName },
+        });
       }
 
       if (!commandDefinition.options) {
-        if (!context.subcommand) {
-          throw new Error(`options are not allowed here: "${argument}"`);
-        }
-
-        throw new Error(`subcommand "${context.subcommand}" does not accept options: "${argument}"`);
+        throw new CliError({
+          cause: ErrorCause.Parse,
+          code: ParseErrorCode.CommandWithoutOptions,
+          context: { commandKind, commandName, optionName: argument },
+        });
       }
 
       const nameOptionTuple = findOption(argument, commandDefinition.options);
       if (!nameOptionTuple) {
-        throw new Error(`unknown option: "${argument}"`);
+        throw new CliError({
+          cause: ErrorCause.Parse,
+          code: ParseErrorCode.UnknownOption,
+          context: { commandKind, commandName, optionName: argument },
+        });
       }
 
       const [optionName, optionDefinition] = nameOptionTuple;
 
-      if (context.options && optionName in context.options) {
-        throw new Error(`duplicated option: "${argument}"`);
+      if (!optionWithKeys && context.options && optionName in context.options) {
+        throw new CliError({
+          cause: ErrorCause.Parse,
+          code: ParseErrorCode.DuplicateOptionProvided,
+          context: { commandKind, commandName, optionName },
+        });
       }
 
       if (!optionDefinition._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 { schema, optional, defaultValue, coerceTo } = optionDefinition._preparedType;
 
       const nextArgument = argv[index + 1];
 
-      let optionValue: string | boolean = argumentWithEquals ? argumentValue : nextArgument;
+      let optionValue: string | boolean | undefined = argumentWithEquals ? argumentValue : nextArgument;
+
+      const isBoolean = coerceTo === "boolean";
+
+      if (isNegated && !isBoolean) {
+        throw new CliError({
+          cause: ErrorCause.Parse,
+          code: ParseErrorCode.InvalidNegationForNonBooleanOption,
+          context: { commandKind, commandName, optionName },
+        });
+      }
 
       // infer value for boolean options
-      if (coerceTo === "boolean") {
+      if (isBoolean) {
         if (!argumentWithEquals) {
           optionValue = "true";
         }
 
-        const isNegated = argument.startsWith("--no-");
-
         if (isNegated && ["true", "false"].includes(optionValue.toLowerCase())) {
           optionValue = optionValue === "true" ? "false" : "true";
         }
       }
 
-      if (optionValue === undefined) {
-        throw new Error(`expected a value for "${argument}" but got nothing`);
+      if (optionValue === undefined || (!argumentWithEquals && isOptionArgument(optionValue))) {
+        throw new CliError({
+          cause: ErrorCause.Parse,
+          code: ParseErrorCode.OptionMissingValue,
+          context: { commandKind, commandName, optionName },
+        });
       }
 
-      if (!argumentWithEquals && isOptionArgument(optionValue)) {
-        throw new Error(`expected a value for "${argument}" but got an argument "${nextArgument}"`);
+      context.options ??= {};
+
+      // Handle options with keys for type `object`
+      // E.g. `--option.key.nested=value`
+      if (optionWithKeys) {
+        const previousObject = JSON.parse(context.options[optionName]?.stringValue || "{}") as Record<string, any>;
+
+        let current = previousObject;
+        for (let index = 0; index < keys.length; index++) {
+          const key = keys[index];
+
+          if (current[key] === undefined) {
+            current[key] = {};
+          }
+
+          if (index === keys.length - 1) {
+            current[key] = optionValue;
+            continue;
+          }
+
+          current = current[key] as Record<string, any>;
+        }
+
+        optionValue = JSON.stringify(previousObject);
       }
 
-      context.options ??= {};
       context.options[optionName] = {
         schema,
         optional,
@@ -118,7 +189,7 @@ export function buildCliContext(argv: string[], cliDefinition: Cli) {
       };
 
       // Skip to the next argument if it is the current option's value.
-      if (!argumentWithEquals && coerceTo !== "boolean") {
+      if (!argumentWithEquals && !isBoolean) {
         index++;
       }
 
@@ -139,7 +210,16 @@ export function buildCliContext(argv: string[], cliDefinition: Cli) {
         const [name, argumentDefinition] = argumentDefinitionEntries[currentArgumentCount];
 
         if (!argumentDefinition._preparedType) {
-          throw new Error(`internal error: missing prepared type for argument "${currentArgumentCount}"`);
+          throw new CliError({
+            cause: ErrorCause.Internal,
+            code: InternalErrorCode.MissingPreparedTypes,
+            context: {
+              commandKind: context.subcommand ? "subcommand" : "command",
+              commandName: context.subcommand ?? cliName,
+              kind: "argument",
+              name,
+            },
+          });
         }
 
         const { schema, optional, defaultValue } = argumentDefinition._preparedType;
@@ -156,18 +236,32 @@ export function buildCliContext(argv: string[], cliDefinition: Cli) {
       continue;
     }
 
-    if (!context.subcommand) {
-      throw new Error(`unexpected argument "${argvItem}": positionals arguments are not allowed here`);
-    }
-
-    throw new Error(
-      `unexpected argument "${argvItem}": positionals arguments are not allowed for subcommand "${context.subcommand}"`,
-    );
+    throw new CliError({
+      cause: ErrorCause.Parse,
+      code: ParseErrorCode.PositionalArgumentNotAllowed,
+      context: {
+        commandKind: context.subcommand ? "subcommand" : "command",
+        commandName: context.subcommand ?? cliName,
+        argumentName: argvItem,
+      },
+    });
   }
 
   const commandDefinition = getCommandDefinition();
   if (!commandDefinition) {
-    throw new Error(`unknown subcommand: "${context.subcommand}"`);
+    if (context.subcommand === undefined) {
+      throw new CliError({
+        cause: ErrorCause.Internal,
+        code: InternalErrorCode.CannotFindCliDefinition,
+        context: { cliName },
+      });
+    }
+
+    throw new CliError({
+      cause: ErrorCause.Parse,
+      code: ParseErrorCode.UnknownSubcommand,
+      context: { commandName: context.subcommand ?? cliName },
+    });
   }
 
   // Options
@@ -179,7 +273,16 @@ export function buildCliContext(argv: string[], cliDefinition: Cli) {
       if (name in context.options) continue;
 
       if (!optionDefinition._preparedType) {
-        throw new Error(`internal error: missing prepared type for option "${name}"`);
+        throw new CliError({
+          cause: ErrorCause.Internal,
+          code: InternalErrorCode.MissingPreparedTypes,
+          context: {
+            commandKind: context.subcommand ? "subcommand" : "command",
+            commandName: context.subcommand ?? cliName,
+            kind: "option",
+            name,
+          },
+        });
       }
 
       const { schema, optional, defaultValue } = optionDefinition._preparedType;
@@ -195,8 +298,15 @@ export function buildCliContext(argv: string[], cliDefinition: Cli) {
         continue;
       }
 
-      // required option
-      throw new Error(`missing required option: ${transformOptionToArgument(name)}`);
+      throw new CliError({
+        cause: ErrorCause.Parse,
+        code: ParseErrorCode.MissingRequiredOption,
+        context: {
+          commandKind: context.subcommand ? "subcommand" : "command",
+          commandName: context.subcommand ?? cliName,
+          optionName: name,
+        },
+      });
     }
   }
 
@@ -215,7 +325,16 @@ export function buildCliContext(argv: string[], cliDefinition: Cli) {
         const [name, argumentDefinition] = argumentDefinitionEntries[index];
 
         if (!argumentDefinition._preparedType) {
-          throw new Error(`internal error: missing prepared type for the argument "${name}"`);
+          throw new CliError({
+            cause: ErrorCause.Internal,
+            code: InternalErrorCode.MissingPreparedTypes,
+            context: {
+              commandKind: context.subcommand ? "subcommand" : "command",
+              commandName: context.subcommand ?? cliName,
+              kind: "argument",
+              name,
+            },
+          });
         }
 
         const { schema, optional, defaultValue } = argumentDefinition._preparedType;
@@ -232,7 +351,15 @@ export function buildCliContext(argv: string[], cliDefinition: Cli) {
         }
 
         // required argument
-        throw new Error(`The argument "${name}" is required`);
+        throw new CliError({
+          cause: ErrorCause.Parse,
+          code: ParseErrorCode.MissingRequiredArgument,
+          context: {
+            commandKind: context.subcommand ? "subcommand" : "command",
+            commandName: context.subcommand ?? cliName,
+            argumentName: name,
+          },
+        });
       }
     }
   }

package/src/parse/context/object-context-builder.ts

@@ -1,20 +1,21 @@
+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 { ParseErrorCode } from "../../cli-error/error-code/parse-error-code.ts";
+
 import type { ContextWide } from "../../types/context-types.ts";
 import type { Argument, Cli, Option, Subcommand } from "../../types/definitions-types.ts";
 import type { InputTypeWide } from "../../types/io-types.ts";
 
-/** @throws {Error} */
+/** @throws {CliError} */
 export function buildObjectContext(inputValues: InputTypeWide, commandDefinition: Subcommand | Cli) {
   const context: ContextWide = {
     subcommand: "cliName" in commandDefinition ? undefined : commandDefinition.name,
   };
 
-  if (commandDefinition.options) {
-    buildForOptionsOrArguments(commandDefinition.options, context, inputValues.options, "options");
-  }
+  buildForOptionsOrArguments(commandDefinition, context, inputValues.options, "options");
 
-  if (commandDefinition.arguments) {
-    buildForOptionsOrArguments(commandDefinition.arguments, context, inputValues.arguments, "arguments");
-  }
+  buildForOptionsOrArguments(commandDefinition, context, inputValues.arguments, "arguments");
 
   if (commandDefinition.allowPositionals) {
     context.positionals ??= inputValues.positionals;
@@ -24,16 +25,27 @@ export function buildObjectContext(inputValues: InputTypeWide, commandDefinition
 }
 
 function buildForOptionsOrArguments(
-  definitionRecord: Record<string, Option> | Record<string, Argument>,
+  commandDefinition: Subcommand | Cli,
   context: ContextWide,
   inputRecord: Record<string, unknown> | undefined,
   type: "options" | "arguments",
 ) {
-  const definitionEntries = Object.entries(definitionRecord) as [string, Option][] | [string, Argument][];
+  if (!commandDefinition[type]) return;
+
+  const optionOrArgumentDefinitions = commandDefinition[type];
+  const kind = type.slice(0, -1) as "option" | "argument";
+  const commandKind = "cliName" in commandDefinition ? "command" : "subcommand";
+  const commandName = "cliName" in commandDefinition ? commandDefinition.cliName : commandDefinition.name;
+
+  const definitionEntries = Object.entries(optionOrArgumentDefinitions) as [string, Option][] | [string, Argument][];
 
   for (const [name, definition] of definitionEntries) {
     if (!definition._preparedType) {
-      throw new Error(`internal error: missing prepared type for ${type.slice(0, -1)} "${name}"`);
+      throw new CliError({
+        cause: ErrorCause.Internal,
+        code: InternalErrorCode.MissingPreparedTypes,
+        context: { commandKind, commandName, kind, name },
+      });
     }
 
     const { schema, optional, defaultValue } = definition._preparedType;
@@ -53,7 +65,21 @@ function buildForOptionsOrArguments(
 
     // case the value is not passed
     if (!optional) {
-      throw new Error(`the ${type.slice(0, -1)} "${name}" is required`);
+      if (kind === "option") {
+        throw new CliError({
+          cause: ErrorCause.Parse,
+          code: ParseErrorCode.MissingRequiredOption,
+          context: { commandKind, commandName, optionName: name },
+        });
+      }
+
+      if (kind === "argument") {
+        throw new CliError({
+          cause: ErrorCause.Parse,
+          code: ParseErrorCode.MissingRequiredArgument,
+          context: { commandKind, commandName, argumentName: name },
+        });
+      }
     }
 
     // case the value is optional

package/src/parse/parser-utilities.ts

@@ -49,9 +49,7 @@ export function findOption(optionArgument: string, options: Record<string, Optio
       return true;
     }
 
-    const isBool = option._preparedType && option._preparedType.coerceTo === "boolean";
-
-    if (isNegated && isBool && validVariableNames.has(negateOption(optionName))) {
+    if (isNegated && validVariableNames.has(negateOption(optionName))) {
       return true;
     }
 
@@ -63,7 +61,7 @@ export function findOption(optionArgument: string, options: Record<string, Optio
       return true;
     }
 
-    if (isNegated && isBool && option.aliases.map(alias => negateOption(alias)).some(a => validVariableNames.has(a))) {
+    if (isNegated && option.aliases.map(alias => negateOption(alias)).some(a => validVariableNames.has(a))) {
       return true;
     }
 
@@ -110,10 +108,6 @@ export function decoupleFlags(arguments_: string[]): string[] {
  * @param name - Should start with `'--'` or `'-'`
  */
 export function optionArgumentToVariableNames(name: string): Set<string> {
-  if (!name.startsWith("-")) {
-    throw new Error(`invalid option name: ${name}`);
-  }
-
   name = name.startsWith("--") ? name.slice(2) : name.slice(1); // remove prefix
   name = name.toLowerCase(); // lowercase
 
@@ -141,9 +135,14 @@ export function isFlagArgument(name: string): boolean {
   return /^-[A-Za-z]$/.test(name);
 }
 
-/** - Check if an arg string is a long arg. E.g. `--input-dir` -> `true` */
+/**
+ * - Check if an arg string is a long arg.
+ * - `--input-dir` -> `true`
+ * - `-h` -> `false`
+ * - `--db.https` -> `true`
+ */
 function isLongArgument(name: string): boolean {
-  return /^--[A-Za-z-]+[A-Za-z0-9]$/.test(name);
+  return /^--.{2,}/.test(name);
 }
 
 /** - Check if an arg string is an options arg. E.g. `--input-dir` -> `true` , `-i` -> `true` */
@@ -185,3 +184,18 @@ export function transformOptionToArgument(name: string): string {
 
   return `--${name.toLowerCase()}`;
 }
+
+/**
+ * Split an option with keys into name and a set of keys
+ *
+ * - `--foo` -> `[--foo, []]`
+ * - `--foo.bar` -> `[--foo, ["bar"]]`
+ * - `--foo.bar.baz` -> `[--foo, ["bar", "baz"]]`
+ * - `--foo.bar.` -> `[--foo, Set(1) ["bar"]]`
+ */
+export function splitAndGetKeys(option: string): [string, string[]] {
+  const parts = option.split(".");
+  const optionName = parts[0];
+  const keys = parts.slice(1).filter(Boolean);
+  return [optionName, keys];
+}

package/src/parse/safe-parse.ts

@@ -1,5 +1,5 @@
 import { validateCliDefinition } from "../definitions/validate-cli-definition.ts";
-import { parseArgv } from "../utilities.ts";
+import { parseArgv } from "../utilities/parse-argv.ts";
 import { buildCliContext } from "./context/cli-context-builder.ts";
 import { findSubcommandDefinition } from "./parser-utilities.ts";
 import { validate } from "./validation/validate-context.ts";
@@ -16,7 +16,7 @@ export function safeParse(stringOrArgv: string | string[], cliDefinition: Cli):
   // Fire action (throw errors caused by the usage of the action hook)
   if (subcommandObject._onExecute) {
     for (const handler of subcommandObject._onExecute) {
-      handler(validateResult);
+      void handler(validateResult);
     }
   }
 
@@ -31,10 +31,7 @@ export async function safeParseAsync(stringOrArgv: string | string[], cliDefinit
 
   // 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);
-    }
+    await Promise.all(subcommandObject._onExecute.map(async handler => await handler(validateResult)));
   }
 
   return { error: undefined, value: validateResult };

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

@@ -5,7 +5,7 @@ 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} */
+/** @throws {CliError} */
 export function validate(context: ContextWide, commandDefinition: Subcommand | Cli) {
   const output: OutputTypeWide = {
     subcommand: context.subcommand,