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

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

@@ -1,4 +1,8 @@
-/** @throws {TypeError} */
+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";
+
+/** @throws {CliError} */
 export function stringToBoolean(string: string): boolean {
   if (string.toLowerCase() === "true") {
     return true;
@@ -8,24 +12,79 @@ export function stringToBoolean(string: string): boolean {
     return false;
   }
 
-  throw new TypeError(`Invalid boolean value: ${string}`);
+  throw new CliError({
+    cause: ErrorCause.Validation,
+    code: ValidationErrorCode.CoercionFailed,
+    context: { coerceToType: "boolean", providedValue: string },
+  });
 }
 
-/** @throws {TypeError} */
-export function stringToNumber(string: string): number {
-  const trimmed = string.trim();
+/**
+ * Converts a string to a finite number.
+ *
+ * @throws {CliError} If input is empty, invalid, or not a finite number.
+ */
+export function stringToNumber(value: string): number {
+  const input = value.trim();
+  if (!/^[-+]?[0-9]+(?:\.[0-9]+)?$/.test(input)) {
+    throw new CliError({
+      cause: ErrorCause.Validation,
+      code: ValidationErrorCode.CoercionFailed,
+      context: { coerceToType: "number", providedValue: value },
+    });
+  }
 
-  // Reject empty, whitespace-only, or signs without digits
-  if (trimmed === "" || trimmed === "+" || trimmed === "-") {
-    throw new TypeError(`Invalid number: "${string}"`);
+  const number = Number(input);
+  if (!Number.isFinite(number)) {
+    throw new CliError({
+      cause: ErrorCause.Validation,
+      code: ValidationErrorCode.CoercionFailed,
+      context: { coerceToType: "number", providedValue: value },
+    });
   }
 
-  const result = Number(trimmed);
+  return number;
+}
 
-  // Reject NaN, Infinity, and -Infinity
-  if (!Number.isFinite(result)) {
-    throw new TypeError(`Invalid number: "${string}"`);
+/**
+ * Converts a string to a bigint.
+ *
+ * @throws {CliError} If input is empty or not a valid bigint.
+ */
+export function stringToBigint(value: string): bigint {
+  const input = value.trim();
+  if (!/^[+-]?[0-9]+$/.test(input)) {
+    throw new CliError({
+      cause: ErrorCause.Validation,
+      code: ValidationErrorCode.CoercionFailed,
+      context: { coerceToType: "bigint", providedValue: value },
+    });
   }
 
-  return result;
+  try {
+    return BigInt(input);
+  } catch {
+    throw new CliError({
+      cause: ErrorCause.Validation,
+      code: ValidationErrorCode.CoercionFailed,
+      context: { coerceToType: "bigint", providedValue: value },
+    });
+  }
+}
+
+/**
+ * Converts a string to a valid Date object.
+ *
+ * @throws {CliError} If input is not a valid date string.
+ */
+export function stringToDate(value: string): Date {
+  const date = new Date(value);
+  if (Number.isNaN(date.getTime())) {
+    throw new CliError({
+      cause: ErrorCause.Validation,
+      code: ValidationErrorCode.CoercionFailed,
+      context: { coerceToType: "date", providedValue: value },
+    });
+  }
+  return date;
 }

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

@@ -4,12 +4,12 @@ export function stringToStringSet(stringValue: string, separator: string = ","):
   return new Set(stringToStringArray(stringValue, separator));
 }
 
-/** @throws {TypeError} - Because of `stringToNumber` */
+/** @throws {CliError} - Because of `stringToNumber` */
 export function stringToNumberSet(stringValue: string, separator: string = ","): Set<number> {
   return new Set(stringToNumberArray(stringValue, separator));
 }
 
-/** @throws {TypeError} - Because of `stringToBoolean` */
+/** @throws {CliError} - Because of `stringToBoolean` */
 export function stringToBooleanSet(stringValue: string, separator: string = ","): Set<boolean> {
   return new Set(stringToBooleanArray(stringValue, separator));
 }

package/src/definitions/define-arguments.ts

@@ -1,4 +1,4 @@
-import { prepareDefinitionTypes } from "../utilities.ts";
+import { prepareDefinitionTypes } from "../utilities/schema-utilities.ts";
 
 import type { Argument } from "../types/definitions-types.ts";
 

package/src/definitions/define-cli.ts

@@ -1,9 +1,12 @@
+import { CliError } from "../cli-error/cli-error.ts";
+import { ErrorCause } from "../cli-error/error-cause.ts";
+import { DefinitionErrorCode } from "../cli-error/error-code/definition-error-code.ts";
 import { generateCliHelpMessage } from "../help-message/generate-for-cli.ts";
 import { generateSubcommandHelpMessage } from "../help-message/generate-for-subcommand.ts";
 import { buildObjectContext } from "../parse/context/object-context-builder.ts";
 import { safeParse, safeParseAsync } from "../parse/safe-parse.ts";
 import { validate } from "../parse/validation/validate-context.ts";
-import { prepareDefinitionTypes } from "../utilities.ts";
+import { prepareDefinitionTypes } from "../utilities/schema-utilities.ts";
 
 import type { Argument, Cli, Option, Subcommand } from "../types/definitions-types.ts";
 import type { PrintHelpOptions } from "../types/help-message-types.ts";
@@ -40,66 +43,98 @@ type CliInput<T extends Cli> = {
 };
 
 export function defineCLI<T extends Cli>(input: CliInput<T> & Cli) {
-  const cliSchema = input as Prettify<T & AttachedMethods<T> & ValidateMethods<T>>;
+  const cliDefinition = input as T;
 
-  prepareDefinitionTypes(cliSchema.options);
-  prepareDefinitionTypes(cliSchema.arguments);
+  prepareDefinitionTypes(cliDefinition.options);
+  prepareDefinitionTypes(cliDefinition.arguments);
 
-  if (cliSchema.subcommands) {
-    for (const subcommand of Object.values(cliSchema.subcommands)) {
+  if (cliDefinition.subcommands) {
+    for (const subcommand of Object.values(cliDefinition.subcommands)) {
       prepareDefinitionTypes(subcommand.options);
       prepareDefinitionTypes(subcommand.arguments);
     }
   }
 
   const onExecute = (handler: (Cli["_onExecute"] & {})[number]) => {
-    cliSchema._onExecute ??= [];
-    cliSchema._onExecute.push(handler);
+    cliDefinition._onExecute ??= [];
+    cliDefinition._onExecute.push(handler);
 
     return () => {
-      const handlerIndex = cliSchema._onExecute?.indexOf(handler);
+      const handlerIndex = cliDefinition._onExecute?.indexOf(handler);
       if (!handlerIndex || handlerIndex < 0) return;
-      cliSchema._onExecute?.splice(handlerIndex, 1);
+      cliDefinition._onExecute?.splice(handlerIndex, 1);
     };
   };
 
   const execute: AttachedMethodsWide["execute"] = inputValues => {
     inputValues ??= {};
-    if (!cliSchema._onExecute) throw new Error("Action is not defined");
-    const context = buildObjectContext(inputValues, cliSchema);
-    const validateResult = validate(context, cliSchema);
 
-    if (cliSchema._onExecute) {
-      for (const handler of cliSchema._onExecute) {
-        handler(validateResult);
-      }
+    const handlers = cliDefinition._onExecute;
+    if (!handlers) {
+      throw new CliError({
+        cause: ErrorCause.Definition,
+        code: DefinitionErrorCode.MissingOnExecute,
+        context: { commandKind: "command", commandName: cliDefinition.cliName },
+      });
+    }
+
+    const context = buildObjectContext(inputValues, cliDefinition);
+    const validateResult = validate(context, cliDefinition);
+
+    for (const handler of handlers) {
+      void handler(validateResult);
+    }
+  };
+
+  const executeAsync: AttachedMethodsWide["executeAsync"] = async inputValues => {
+    inputValues ??= {};
+
+    const handlers = cliDefinition._onExecute;
+
+    if (!handlers) {
+      throw new CliError({
+        cause: ErrorCause.Definition,
+        code: DefinitionErrorCode.MissingOnExecute,
+        context: { commandKind: "command", commandName: cliDefinition.cliName },
+      });
     }
+
+    const context = buildObjectContext(inputValues, cliDefinition);
+    const validateResult = validate(context, cliDefinition);
+
+    await Promise.all(handlers.map(async handler => await handler(validateResult)));
   };
 
   // Add print methods for CLI schema and its subcommands
   const generateHelpMethods: Pick<AttachedMethodsWide, "generateCliHelpMessage" | "generateSubcommandHelpMessage"> = {
     generateCliHelpMessage(options?: PrintHelpOptions) {
-      return generateCliHelpMessage(cliSchema, options);
+      return generateCliHelpMessage(cliDefinition, options);
     },
     generateSubcommandHelpMessage(subcommandName: string, options?: PrintHelpOptions) {
-      const foundSubcommand = cliSchema.subcommands?.find(s => s.name === subcommandName);
-      if (!foundSubcommand) throw new Error(`Subcommand ${subcommandName} not found`);
-      return generateSubcommandHelpMessage(foundSubcommand, options, cliSchema.cliName);
+      const foundSubcommand = cliDefinition.subcommands?.find(s => s.name === subcommandName);
+      if (!foundSubcommand) {
+        throw new CliError({
+          cause: ErrorCause.Definition,
+          code: DefinitionErrorCode.SubcommandHelpNotFound,
+          context: { cliName: cliDefinition.cliName, subcommandName },
+        });
+      }
+      return generateSubcommandHelpMessage(foundSubcommand, options, cliDefinition.cliName);
     },
   };
 
-  Object.assign(cliSchema, generateHelpMethods);
+  Object.assign(cliDefinition, generateHelpMethods);
 
-  if (cliSchema.subcommands) {
-    for (const subcommandSchema of cliSchema.subcommands) {
+  if (cliDefinition.subcommands) {
+    for (const subcommandSchema of cliDefinition.subcommands) {
       Object.assign(subcommandSchema, generateHelpMethods);
     }
   }
 
-  return Object.assign(cliSchema, {
-    execute,
-    onExecute,
-    run: (stringOrArgv: string | string[]) => safeParse(stringOrArgv, cliSchema),
-    runAsync: (stringOrArgv: string | string[]) => safeParseAsync(stringOrArgv, cliSchema),
-  });
+  const run = (stringOrArgv: string | string[]) => safeParse(stringOrArgv, cliDefinition);
+  const runAsync = (stringOrArgv: string | string[]) => safeParseAsync(stringOrArgv, cliDefinition);
+
+  return Object.assign(cliDefinition, { onExecute, execute, executeAsync, run, runAsync }) as Prettify<
+    T & AttachedMethods<T> & ValidateMethods<T>
+  >;
 }

package/src/definitions/define-options.ts

@@ -1,4 +1,4 @@
-import { prepareDefinitionTypes } from "../utilities.ts";
+import { prepareDefinitionTypes } from "../utilities/schema-utilities.ts";
 
 import type { Option } from "../types/definitions-types.ts";
 

package/src/definitions/define-subcommand.ts

@@ -1,6 +1,9 @@
+import { CliError } from "../cli-error/cli-error.ts";
+import { ErrorCause } from "../cli-error/error-cause.ts";
+import { DefinitionErrorCode } from "../cli-error/error-code/definition-error-code.ts";
 import { buildObjectContext } from "../parse/context/object-context-builder.ts";
 import { validate } from "../parse/validation/validate-context.ts";
-import { prepareDefinitionTypes } from "../utilities.ts";
+import { prepareDefinitionTypes } from "../utilities/schema-utilities.ts";
 
 import type { Argument, Option, Subcommand } from "../types/definitions-types.ts";
 import type { AttachedMethods, AttachedMethodsWide } from "../types/types.ts";
@@ -24,34 +27,61 @@ type SubcommandInput<T extends Subcommand> = {
 };
 
 export function defineSubcommand<T extends Subcommand>(input: SubcommandInput<T> & Subcommand) {
-  const subcommandSchema = input as Prettify<T & AttachedMethods<T>>;
+  const subcommandDefinition = input as T;
 
-  prepareDefinitionTypes(subcommandSchema.options);
-  prepareDefinitionTypes(subcommandSchema.arguments);
+  prepareDefinitionTypes(subcommandDefinition.options);
+  prepareDefinitionTypes(subcommandDefinition.arguments);
 
   const onExecute = (handler: (Subcommand["_onExecute"] & {})[number]) => {
-    subcommandSchema._onExecute ??= [];
-    subcommandSchema._onExecute.push(handler);
+    subcommandDefinition._onExecute ??= [];
+    subcommandDefinition._onExecute.push(handler);
 
     return () => {
-      const handlerIndex = subcommandSchema._onExecute?.indexOf(handler);
+      const handlerIndex = subcommandDefinition._onExecute?.indexOf(handler);
       if (!handlerIndex || handlerIndex < 0) return;
-      subcommandSchema._onExecute?.splice(handlerIndex, 1);
+      subcommandDefinition._onExecute?.splice(handlerIndex, 1);
     };
   };
 
   const execute: AttachedMethodsWide["execute"] = inputValues => {
     inputValues ??= {};
-    if (!subcommandSchema._onExecute) throw new Error("Action is not defined");
-    const context = buildObjectContext(inputValues, subcommandSchema);
-    const validateResult = validate(context, subcommandSchema);
-
-    if (subcommandSchema._onExecute) {
-      for (const handler of subcommandSchema._onExecute) {
-        handler(validateResult);
-      }
+
+    const handlers = subcommandDefinition._onExecute;
+
+    if (!handlers) {
+      throw new CliError({
+        cause: ErrorCause.Definition,
+        code: DefinitionErrorCode.MissingOnExecute,
+        context: { commandKind: "subcommand", commandName: subcommandDefinition.name },
+      });
     }
+
+    const context = buildObjectContext(inputValues, subcommandDefinition);
+    const validateResult = validate(context, subcommandDefinition);
+
+    for (const handler of handlers) {
+      void handler(validateResult);
+    }
+  };
+
+  const executeAsync: AttachedMethodsWide["executeAsync"] = async inputValues => {
+    inputValues ??= {};
+
+    const handlers = subcommandDefinition._onExecute;
+
+    if (!handlers) {
+      throw new CliError({
+        cause: ErrorCause.Definition,
+        code: DefinitionErrorCode.MissingOnExecute,
+        context: { commandKind: "subcommand", commandName: subcommandDefinition.name },
+      });
+    }
+
+    const context = buildObjectContext(inputValues, subcommandDefinition);
+    const validateResult = validate(context, subcommandDefinition);
+
+    await Promise.all(handlers.map(async handler => await handler(validateResult)));
   };
 
-  return Object.assign(subcommandSchema, { onExecute, execute });
+  return Object.assign(subcommandDefinition, { onExecute, execute, executeAsync }) as Prettify<T & AttachedMethods<T>>;
 }