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

package/src/cli-error/error-message/definition-error-message.ts

@@ -0,0 +1,144 @@
+import { DefinitionErrorCode } from "../error-code/definition-error-code.ts";
+
+import type { CliErrorOptionByCause } from "../../types/error-types.ts";
+
+export function definitionErrorMessage({ code, context }: CliErrorOptionByCause<"Definition">) {
+  if (code === DefinitionErrorCode.MissingDefinitionName) {
+    const propertyName = context.commandKind === "command" ? "cliName" : "name";
+    return `invalid ${context.commandKind} definition: "${propertyName}" property is required.`;
+  }
+
+  if (code === DefinitionErrorCode.EmptyDefinitionGroup) {
+    return (
+      `invalid ${context.commandKind} definition "${context.commandName}": ` +
+      `"${context.kind}" property is optional but cannot be empty.`
+    );
+  }
+
+  if (code === DefinitionErrorCode.MissingSchema) {
+    return (
+      `invalid ${context.commandKind} definition "${context.commandName}": ` +
+      `the ${context.kind} "${context.name}" is missing the "schema" property.`
+    );
+  }
+
+  if (code === DefinitionErrorCode.InvalidDefinitionOptionName) {
+    if (context.negatedAliasName) {
+      return (
+        `invalid ${context.commandKind} definition "${context.commandName}": ` +
+        `the option "${context.optionName}" has the alias "${context.negatedAliasName}" which cannot be named as a negated option.`
+      );
+    }
+
+    return (
+      `invalid ${context.commandKind} definition "${context.commandName}": ` +
+      `the option "${context.optionName}" cannot be named as a negated option.`
+    );
+  }
+
+  if (code === DefinitionErrorCode.InvalidDefinitionArgumentName) {
+    return (
+      `invalid ${context.commandKind} definition "${context.commandName}": ` +
+      `the argument "${context.name}" cannot be a number..`
+    );
+  }
+
+  if (code === DefinitionErrorCode.DuplicateDefinitionName) {
+    const foundIn = context.foundInName
+      ? `conflict with the ${context.foundInKind} "${context.foundInName}" alias name`
+      : `conflict with other ${context.foundInKind} name`;
+
+    if (context.duplicatedAlias) {
+      return (
+        `invalid ${context.commandKind} definition "${context.commandName}": ` +
+        `the ${context.kind} "${context.name}" has the alias "${context.duplicatedAlias}" which ${foundIn}.`
+      );
+    }
+
+    return (
+      `invalid ${context.commandKind} definition "${context.commandName}": ` +
+      `the ${context.kind} "${context.name}" name ${foundIn}.`
+    );
+  }
+
+  if (code === DefinitionErrorCode.EmptyStringAliasName) {
+    if (context.optionName) {
+      return (
+        `invalid ${context.commandKind} definition "${context.commandName}": ` +
+        `the option "${context.optionName}" has an empty string alias name.`
+      );
+    }
+
+    return (
+      `invalid ${context.commandKind} definition "${context.commandName}": ` + `empty string alias name is not allowed.`
+    );
+  }
+
+  if (code === DefinitionErrorCode.SelfRequire) {
+    return (
+      `invalid ${context.commandKind} definition "${context.commandName}": ` +
+      `the ${context.kind} "${context.name}" cannot require itself.`
+    );
+  }
+
+  if (code === DefinitionErrorCode.UnknownRequireName) {
+    return (
+      `invalid ${context.commandKind} definition "${context.commandName}": ` +
+      `the ${context.kind} "${context.name}" requires a non-existent name "${context.requiredName}".`
+    );
+  }
+
+  if (code === DefinitionErrorCode.SelfConflict) {
+    return (
+      `invalid ${context.commandKind} definition "${context.commandName}": ` +
+      `the ${context.kind} "${context.name}" cannot conflict with itself.`
+    );
+  }
+
+  if (code === DefinitionErrorCode.UnknownConflictName) {
+    return (
+      `invalid ${context.commandKind} definition "${context.commandName}": ` +
+      `the ${context.kind} "${context.name}" conflicts with a non-existent name "${context.requiredName}".`
+    );
+  }
+
+  if (code === DefinitionErrorCode.DefinitionRequiresConflictOverlap) {
+    const s = context.intersectedNames.length > 1 ? "s" : "";
+    return (
+      `invalid ${context.commandKind} definition "${context.commandName}": ` +
+      `the ${context.kind} "${context.name}" has overlapping 'requires' and 'conflictsWith' name${s}: ` +
+      context.intersectedNames.join(", ")
+    );
+  }
+
+  if (code === DefinitionErrorCode.InvalidOptionalArgumentDefinition) {
+    if (context.allowPositionals) {
+      return (
+        `invalid ${context.commandKind} definition "${context.commandName}": ` +
+        `the argument "${context.name}" cannot be optional when "allowPositionals" is enabled.`
+      );
+    }
+
+    return (
+      `invalid ${context.commandKind} definition "${context.commandName}": ` +
+      `the argument "${context.name}" cannot be optional unless it is the last argument.`
+    );
+  }
+
+  if (code === DefinitionErrorCode.MissingOnExecute) {
+    return (
+      `trying to execute ${context.commandKind} "${context.commandName}" ` +
+      `which does not have an "onExecute" handler.`
+    );
+  }
+
+  if (code === DefinitionErrorCode.SubcommandHelpNotFound) {
+    return (
+      `cannot generate help message for subcommand "${context.subcommandName}" ` +
+      `because it does not exist in CLI "${context.cliName}".`
+    );
+  }
+
+  const executiveCheck: never = code;
+  return executiveCheck;
+}

package/src/cli-error/error-message/internal-error-message.ts

@@ -0,0 +1,19 @@
+import { InternalErrorCode } from "../error-code/internal-error-code.ts";
+
+import type { CliErrorOptionByCause } from "../../types/error-types.ts";
+
+export function internalErrorMessage({ code, context }: CliErrorOptionByCause<"Internal">) {
+  if (code === InternalErrorCode.MissingPreparedTypes) {
+    return (
+      `internal error: missing prepared type ` +
+      `for option "${context.name}" in ${context.commandKind} "${context.commandName}"`
+    );
+  }
+
+  if (code === InternalErrorCode.CannotFindCliDefinition) {
+    return `internal error: cannot find cli definition "${context.cliName}"`;
+  }
+
+  const executiveCheck: never = code;
+  return executiveCheck;
+}

package/src/cli-error/error-message/parse-error-message.ts

@@ -0,0 +1,76 @@
+import { ParseErrorCode } from "../error-code/parse-error-code.ts";
+
+import type { CliErrorOptionByCause } from "../../types/error-types.ts";
+
+export function parseErrorMessage({ code, context }: CliErrorOptionByCause<"Parse">) {
+  if (code === ParseErrorCode.UnknownSubcommand) {
+    return `parsing error: unknown subcommand "${context.commandName}".`;
+  }
+
+  if (code === ParseErrorCode.CommandWithoutOptions) {
+    return (
+      `parsing error: the ${context.commandKind} "${context.commandName}" ` +
+      `does not allow options, but received "${context.optionName}".`
+    );
+  }
+
+  if (code === ParseErrorCode.UnknownOption) {
+    return (
+      `parsing error: unknown option "${context.optionName}" ` +
+      `for the ${context.commandKind} "${context.commandName}".`
+    );
+  }
+
+  if (code === ParseErrorCode.DuplicateOptionProvided) {
+    return (
+      `parsing error: duplicate option "${context.optionName}" ` +
+      `provided for the ${context.commandKind} "${context.commandName}".`
+    );
+  }
+
+  if (code === ParseErrorCode.InvalidNegationForNonBooleanOption) {
+    return (
+      `parsing error: option "${context.optionName}" cannot be negated ` +
+      `because it is not a boolean option for the ${context.commandKind} "${context.commandName}".`
+    );
+  }
+
+  if (code === ParseErrorCode.PositionalArgumentNotAllowed) {
+    return (
+      `parsing error: positional argument "${context.argumentName}" ` +
+      `is not allowed for the ${context.commandKind} "${context.commandName}".`
+    );
+  }
+
+  if (code === ParseErrorCode.MissingRequiredOption) {
+    return (
+      `parsing error: missing required option "${context.optionName}" ` +
+      `for the ${context.commandKind} "${context.commandName}".`
+    );
+  }
+
+  if (code === ParseErrorCode.MissingRequiredArgument) {
+    return (
+      `parsing error: missing required argument "${context.argumentName}" ` +
+      `for the ${context.commandKind} "${context.commandName}".`
+    );
+  }
+
+  if (code === ParseErrorCode.OptionMissingValue) {
+    return (
+      `parsing error: the option "${context.optionName}" ` +
+      `for the ${context.commandKind} "${context.commandName}" expects a value but received none.`
+    );
+  }
+
+  if (code === ParseErrorCode.FlagAssignedValue) {
+    return (
+      `parsing error: ` +
+      `flag option "${context.flag}" in ${context.commandKind} "${context.commandName}" ` +
+      `cannot be assigned a value using "=" (provided: "${context.value}").`
+    );
+  }
+
+  const executiveCheck: never = code;
+  return executiveCheck;
+}

package/src/cli-error/error-message/validation-error-message.ts

@@ -0,0 +1,104 @@
+import { prettifyError } from "../../utilities/schema-utilities.ts";
+import { ValidationErrorCode } from "../error-code/validation-error-code.ts";
+
+import type { CliErrorOptionByCause } from "../../types/error-types.ts";
+
+export function validationErrorMessage({ code, context }: CliErrorOptionByCause<"Validation">) {
+  if (code === ValidationErrorCode.NoOptionsToValidate) {
+    return (
+      `validation error: trying to validate options ` +
+      `for ${context.commandKind} "${context.commandName}" which does not define any.`
+    );
+  }
+
+  if (code === ValidationErrorCode.NoArgumentsToValidate) {
+    return (
+      `validation error: trying to validate typed arguments ` +
+      `for ${context.commandKind} "${context.commandName}" which does not define any.`
+    );
+  }
+
+  if (code === ValidationErrorCode.UnknownOptionValidation) {
+    return (
+      `validation error: trying to validate a non-existent option "${context.optionName}" ` +
+      `for ${context.commandKind} "${context.commandName}".`
+    );
+  }
+
+  if (code === ValidationErrorCode.UnknownArgumentValidation) {
+    return (
+      `validation error: trying to validate a non-existent typed argument "${context.argumentName}" ` +
+      `for ${context.commandKind} "${context.commandName}".`
+    );
+  }
+
+  if (code === ValidationErrorCode.SchemaValidationFailed) {
+    return (
+      `validation error: ` +
+      `the ${context.kind} "${context.name}" for ${context.commandKind} "${context.commandName}" failed to validate ` +
+      `"${typeof context.inputValue === "string" ? context.inputValue : JSON.stringify(context.inputValue)}": ` +
+      prettifyError(context.issues)
+    );
+  }
+
+  if (code === ValidationErrorCode.MutuallyExclusiveConflict) {
+    const parts: string[] = [];
+
+    if (context.conflictedOptions.length > 0) {
+      const formatted = context.conflictedOptions.map(o => `"${o}"`).join(", ");
+      const s = context.conflictedOptions.length > 1 ? "s" : "";
+      parts.push(`option${s} ${formatted}`);
+    }
+
+    if (context.conflictedArguments.length > 0) {
+      const formatted = context.conflictedArguments.map(a => `"${a}"`).join(", ");
+      const s = context.conflictedArguments.length > 1 ? "s" : "";
+      parts.push(`argument${s} ${formatted}`);
+    }
+
+    return (
+      `validation error: the ${context.kind} "${context.name}" ` +
+      `cannot be used with the ${parts.join(" and ")} because they are mutually exclusive.`
+    );
+  }
+
+  if (code === ValidationErrorCode.RequiredDependencyMissing) {
+    const parts: string[] = [];
+
+    if (context.missingOptions.length > 0) {
+      const formatted = context.missingOptions.map(o => `"${o}"`).join(", ");
+      const s = context.missingOptions.length > 1 ? "s" : "";
+      parts.push(`option${s} ${formatted}`);
+    }
+
+    if (context.missingArguments.length > 0) {
+      const formatted = context.missingArguments.map(a => `"${a}"`).join(", ");
+      const s = context.missingArguments.length > 1 ? "s" : "";
+      parts.push(`argument${s} ${formatted}`);
+    }
+
+    return (
+      `validation error: the ${context.kind} "${context.name}" ` +
+      `cannot be used without the required "${parts.join(" and ")}".`
+    );
+  }
+
+  if (code === ValidationErrorCode.AsyncSchemaNotSupported) {
+    return (
+      `validation error: cannot validate async schema: ` +
+      `received ${typeof context.value === "string" ? context.value : JSON.stringify(context.value)}`
+    );
+  }
+
+  if (code === ValidationErrorCode.CoercionFailed) {
+    return (
+      `validation error: ` +
+      `failed to coerce the value ` +
+      `"${typeof context.providedValue === "string" ? context.providedValue : JSON.stringify(context.providedValue)}" ` +
+      `of type "${typeof context.providedValue}" to type "${context.coerceToType}".`
+    );
+  }
+
+  const executiveCheck: never = code;
+  return executiveCheck;
+}

package/src/coerce/coerce-methods.ts

@@ -1,75 +1,230 @@
+import { walkObject } from "../utilities/utilities.ts";
 import { stringToBooleanArray, stringToNumberArray, stringToStringArray } from "./string-to-array.ts";
-import { stringToBoolean, stringToNumber } from "./string-to-primitive.ts";
+import { stringToBigint, stringToBoolean, stringToNumber } from "./string-to-primitive.ts";
 import { stringToBooleanSet, stringToNumberSet, stringToStringSet } from "./string-to-set.ts";
 
-import type { CoerceMethod } from "../types/types.ts";
+import type { ObjectCoerceMethodOptions } from "../types/types.ts";
 
-const string: CoerceMethod<string> = terminalInput => terminalInput;
-string.type = "string";
-
-const boolean: CoerceMethod<boolean> = terminalInput => stringToBoolean(terminalInput);
+const string = <T extends string | undefined>(terminalInput: string): T => terminalInput as T;
+const number = <T extends number | undefined>(terminalInput: string): T => stringToNumber(terminalInput) as T;
+const bigint = <T extends bigint | undefined>(terminalInput: string): T => stringToBigint(terminalInput) as T;
+const json = <T>(terminalInput: string): T => JSON.parse(terminalInput) as T;
+const boolean = <T extends boolean | undefined>(terminalInput: string): T => stringToBoolean(terminalInput) as T;
 boolean.type = "boolean";
 
-const number: CoerceMethod<number> = terminalInput => stringToNumber(terminalInput);
-number.type = "number";
-
-const json = <T>(reviver?: (this: any, key: string, value: any) => any): CoerceMethod<T> => {
-  const coerceMethod: CoerceMethod<T> = terminalInput => JSON.parse(terminalInput, reviver) as T;
-  coerceMethod.type = "unknown";
-  return coerceMethod;
-};
-
-const stringArray = (separator: string): CoerceMethod<string[]> => {
-  const coerceMethod: CoerceMethod<string[]> = terminalInput => stringToStringArray(terminalInput, separator);
-  coerceMethod.type = "string[]";
-  return coerceMethod;
+const stringArray = (separator: string) => {
+  return <T extends string[] | undefined>(terminalInput: string): T =>
+    stringToStringArray(terminalInput, separator) as T;
 };
 
 const numberArray = (separator: string) => {
-  const coerceMethod: CoerceMethod<number[]> = terminalInput => stringToNumberArray(terminalInput, separator);
-  coerceMethod.type = "number[]";
-  return coerceMethod;
+  return <T extends number[] | undefined>(terminalInput: string): T =>
+    stringToNumberArray(terminalInput, separator) as T;
 };
 
 const booleanArray = (separator: string) => {
-  const coerceMethod: CoerceMethod<boolean[]> = terminalInput => stringToBooleanArray(terminalInput, separator);
-  coerceMethod.type = "boolean[]";
-  return coerceMethod;
+  return <T extends boolean[] | undefined>(terminalInput: string): T =>
+    stringToBooleanArray(terminalInput, separator) as T;
 };
 
 const stringSet = (separator: string) => {
-  const coerceMethod: CoerceMethod<Set<string>> = terminalInput => stringToStringSet(terminalInput, separator);
-  coerceMethod.type = "set<string>";
-  return coerceMethod;
+  return <T extends Set<string> | undefined>(terminalInput: string): T =>
+    stringToStringSet(terminalInput, separator) as T;
 };
 
 const numberSet = (separator: string) => {
-  const coerceMethod: CoerceMethod<Set<number>> = terminalInput => stringToNumberSet(terminalInput, separator);
-  coerceMethod.type = "set<number>";
-  return coerceMethod;
+  return <T extends Set<number> | undefined>(terminalInput: string): T =>
+    stringToNumberSet(terminalInput, separator) as T;
 };
 
 const booleanSet = (separator: string) => {
-  const coerceMethod: CoerceMethod<Set<boolean>> = terminalInput => stringToBooleanSet(terminalInput, separator);
-  coerceMethod.type = "set<boolean>";
+  return <T extends Set<boolean> | undefined>(terminalInput: string): T =>
+    stringToBooleanSet(terminalInput, separator) as T;
+};
+
+const object = (options: ObjectCoerceMethodOptions = {}) => {
+  const coerceMethod = <T extends Record<string, unknown> | undefined>(terminalInput: string): T => {
+    const object = JSON.parse(terminalInput) as T;
+
+    if (!options.coerceBoolean && !options.coerceNumber && !options.coerceBigint && !options.coerceDate) {
+      return object;
+    }
+
+    walkObject(object!, (_, value, path) => {
+      if (typeof value !== "string") return value;
+
+      const shouldCoerce = (boolOrArray: boolean | string[] | undefined) => {
+        if (!boolOrArray) return false;
+        if (typeof boolOrArray === "boolean") return boolOrArray;
+        return boolOrArray.includes(path);
+      };
+
+      if (shouldCoerce(options.coerceBoolean)) {
+        try {
+          return stringToBoolean(value);
+        } catch {
+          return value;
+        }
+      }
+
+      if (shouldCoerce(options.coerceNumber)) {
+        try {
+          return stringToNumber(value);
+        } catch {
+          return value;
+        }
+      }
+
+      if (shouldCoerce(options.coerceBigint)) {
+        try {
+          return BigInt(value);
+        } catch {
+          return value;
+        }
+      }
+
+      if (shouldCoerce(options.coerceDate)) {
+        try {
+          return new Date(value);
+        } catch {
+          return value;
+        }
+      }
+
+      return value;
+    });
+
+    return object;
+  };
+
   return coerceMethod;
 };
 
 export const coerce = {
+  /**
+   * Since the terminal input is a string, this method does nothing.
+   *
+   * @since 2.0.0
+   * @see {@link https://github.com/alabsi91/zod-args-parser/blob/main/docs/api-reference.md#coerce-helpers}
+   */
   string,
+
+  /**
+   * Coerces a string matching `"true"` or `"false"` (case-insensitive) to a boolean value.
+   *
+   * @since 2.0.0
+   * @throws {CliError} If input is not a valid boolean string.
+   * @see {@link https://github.com/alabsi91/zod-args-parser/blob/main/docs/api-reference.md#coerce-helpers}
+   */
   boolean,
+
+  /**
+   * Coerces a string matching a number to a number value.
+   *
+   * @since 2.0.0
+   * @throws {CliError} If input is empty or not a valid number.
+   * @see {@link https://github.com/alabsi91/zod-args-parser/blob/main/docs/api-reference.md#coerce-helpers}
+   */
   number,
-  /** @param separator - The separator to use to split the string. **Default** is `","` */
+
+  /**
+   * Coerces a string matching a number to a bigint value.
+   *
+   * @since 2.0.0
+   * @throws {CliError} If input is empty or not a valid bigint.
+   * @see {@link https://github.com/alabsi91/zod-args-parser/blob/main/docs/api-reference.md#coerce-helpers}
+   */
+  bigint,
+
+  /**
+   * Coerces a JSON string into a JavaScript object, optionally converting certain string values into native types such
+   * as booleans, numbers, bigints, or dates.
+   *
+   * Each coercion option attempts conversion and silently falls back to the original string if the value cannot be
+   * converted.
+   *
+   * @since 2.0.0
+   * @throws {SyntaxError} If input is not a valid JSON string.
+   * @see {@link https://github.com/alabsi91/zod-args-parser/blob/main/README.md##structured-object-options}
+   * @see {@link https://github.com/alabsi91/zod-args-parser/blob/main/docs/api-reference.md#coerce-helpers}
+   */
+  object,
+
+  /**
+   * Converts a string to an array of strings by splitting it on the specified separator.
+   *
+   * @since 2.0.0
+   * @param separator - The separator to use to split the string.`
+   * @see {@link https://github.com/alabsi91/zod-args-parser/blob/main/docs/api-reference.md#coerce-helpers}
+   */
   stringArray,
-  /** @param separator - The separator to use to split the string. **Default** is `","` */
+
+  /**
+   * Converts a string to an array of numbers by splitting it on the specified separator.
+   *
+   * Items that match the number regex will be converted to numbers.
+   *
+   * @since 2.0.0
+   * @param separator - The separator to use to split the string.`
+   * @throws {CliError} - When an item cannot be converted to a number
+   * @see {@link https://github.com/alabsi91/zod-args-parser/blob/main/docs/api-reference.md#coerce-helpers}
+   */
   numberArray,
-  /** @param separator - The separator to use to split the string. **Default** is `","` */
+
+  /**
+   * Converts a string to an array of booleans by splitting it on the specified separator.
+   *
+   * Items that match `"true"` or `"false"` (case-insensitive) will be converted to booleans.
+   *
+   * @since 2.0.0
+   * @param separator - The separator to use to split the string.`
+   * @throws {CliError} - When an item cannot be converted to a boolean
+   * @see {@link https://github.com/alabsi91/zod-args-parser/blob/main/docs/api-reference.md#coerce-helpers}
+   */
   booleanArray,
-  /** @param separator - The separator to use to split the string. **Default** is `","` */
+
+  /**
+   * Converts a string to a set of strings by splitting it on the specified separator.
+   *
+   * Items that match the number regex will be converted to numbers.
+   *
+   * @since 2.0.0
+   * @param separator - The separator to use to split the string.`
+   * @throws {CliError} - When an item cannot be converted to a number
+   * @see {@link https://github.com/alabsi91/zod-args-parser/blob/main/docs/api-reference.md#coerce-helpers}
+   */
   stringSet,
-  /** @param separator - The separator to use to split the string. **Default** is `","` */
+
+  /**
+   * Converts a string to a set of numbers by splitting it on the specified separator.
+   *
+   * Items that match the number regex will be converted to numbers.
+   *
+   * @since 2.0.0
+   * @param separator - The separator to use to split the string.
+   * @throws {CliError} - When an item cannot be converted to a number
+   * @see {@link https://github.com/alabsi91/zod-args-parser/blob/main/docs/api-reference.md#coerce-helpers}
+   */
   numberSet,
-  /** @param separator - The separator to use to split the string. **Default** is `","` */
+
+  /**
+   * Converts a string to a set of booleans by splitting it on the specified separator.
+   *
+   * Items that match `"true"` or `"false"` (case-insensitive) will be converted to booleans.
+   *
+   * @since 2.0.0
+   * @param separator - The separator to use to split the string.
+   * @throws {CliError} - When an item cannot be converted to a boolean
+   * @see {@link https://github.com/alabsi91/zod-args-parser/blob/main/docs/api-reference.md#coerce-helpers}
+   */
   booleanSet,
+
+  /**
+   * Parses a JSON string into a JavaScript object.
+   *
+   * @since 2.0.0
+   * @throws {SyntaxError} If input is not a valid JSON string.
+   * @see {@link https://github.com/alabsi91/zod-args-parser/blob/main/docs/api-reference.md#coerce-helpers}
+   */
   json,
 };

package/src/coerce/string-to-array.ts

@@ -7,12 +7,12 @@ export function stringToStringArray(stringValue: string, separator: string = ","
     .filter(Boolean);
 }
 
-/** @throws {TypeError} - Because of `stringToNumber` */
+/** @throws {CliError} - Because of `stringToNumber` */
 export function stringToNumberArray(stringValue: string, separator: string = ","): number[] {
   return stringToStringArray(stringValue, separator).map(element => stringToNumber(element));
 }
 
-/** @throws {TypeError} - Because of `stringToBoolean` */
+/** @throws {CliError} - Because of `stringToBoolean` */
 export function stringToBooleanArray(stringValue: string, separator: string = ","): boolean[] {
   return stringToStringArray(stringValue, separator).map(element => stringToBoolean(element));
 }