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

package/src/types/error-types.ts

@@ -0,0 +1,326 @@
+import type { SchemaType } from "./schema-types.ts";
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+
+export interface ErrorCauseI {
+  /** Unexpected errors caused by the library itself */
+  readonly Internal: keyof InternalErrorI;
+
+  /** Errors occurring while parsing terminal arguments, usually due to user input */
+  readonly Parse: keyof ParseErrorI;
+
+  /** Errors occurring during validation of parsed arguments, usually due to user input */
+  readonly Validation: keyof ValidationErrorI;
+
+  /** Errors caused by incorrect CLI or subcommand definitions */
+  readonly Definition: keyof DefinitionErrorI;
+}
+
+export interface InternalErrorI {
+  /** The option or argument definition has undefined `_preparedType` */
+  readonly MissingPreparedTypes: {
+    readonly commandKind: "command" | "subcommand";
+    readonly commandName: string;
+    readonly kind: "option" | "argument";
+    readonly name: string;
+  };
+
+  /** Occurs when attempting to access an undefined subcommand, which should return a CLI definition. */
+  readonly CannotFindCliDefinition: {
+    readonly cliName: string;
+  };
+}
+
+export interface DefinitionErrorI {
+  /** The CLI or subcommand definition is missing the required `name` or `cliName` property. */
+  readonly MissingDefinitionName: {
+    readonly commandKind: "command" | "subcommand";
+  };
+
+  /** Calling */
+  readonly MissingOnExecute: {
+    readonly commandKind: "command" | "subcommand";
+    readonly commandName: string;
+  };
+
+  /** An option or argument definition is missing the required `schema` property. */
+  readonly MissingSchema: {
+    readonly commandKind: "command" | "subcommand";
+    readonly commandName: string;
+    readonly kind: "option" | "argument";
+    readonly name: string;
+  };
+
+  /** The `options` record, `arguments` record, or `subcommands` array is defined but empty. */
+  readonly EmptyDefinitionGroup: {
+    readonly commandKind: "command" | "subcommand";
+    readonly commandName: string;
+    readonly kind: "option" | "argument" | "subcommands";
+  };
+
+  /** An option or alias name is written as a negated name (e.g., `noFoo` → `--no-foo`). */
+  readonly InvalidDefinitionOptionName: {
+    readonly commandKind: "command" | "subcommand";
+    readonly commandName: string;
+    readonly optionName: string;
+    readonly negatedAliasName?: string | undefined;
+  };
+
+  /** An option, option alias, or argument name is duplicated within the same CLI or subcommand. */
+  readonly DuplicateDefinitionName: {
+    readonly commandKind: "command" | "subcommand";
+    readonly commandName: string;
+    readonly kind: "option" | "subcommand";
+    readonly name: string;
+
+    /** Present when the checked name is an alias. */
+    readonly duplicatedAlias?: string | undefined;
+
+    /** Where the duplicated name was found. */
+    readonly foundInKind: "option" | "argument" | "subcommand";
+
+    /** Present when the duplicate was found inside aliases of another kind. */
+    readonly foundInName?: string;
+  };
+
+  /** Argument names cannot be numeric. */
+  readonly InvalidDefinitionArgumentName: {
+    readonly commandKind: "command" | "subcommand";
+    readonly commandName: string;
+    readonly name: string;
+  };
+
+  /**
+   * Argument optionality rules:
+   *
+   * - When `allowPositionals` is enabled, typed arguments cannot be optional.
+   * - Otherwise, only the last typed argument may be optional.
+   */
+  readonly InvalidOptionalArgumentDefinition: {
+    readonly commandKind: "command" | "subcommand";
+    readonly commandName: string;
+    readonly name: string;
+    readonly allowPositionals: boolean;
+  };
+
+  /** The option has an `aliases` array containing an empty string. */
+  readonly EmptyStringAliasName: {
+    readonly commandKind: "command" | "subcommand";
+    readonly commandName: string;
+    readonly optionName?: string;
+  };
+
+  /** The option or argument definition incorrectly requires itself. */
+  readonly SelfRequire: {
+    readonly commandKind: "command" | "subcommand";
+    readonly commandName: string;
+    readonly kind: "option" | "argument";
+    readonly name: string;
+  };
+
+  /** The `requires` list contains a name that does not exist. */
+  readonly UnknownRequireName: {
+    readonly commandKind: "command" | "subcommand";
+    readonly commandName: string;
+    readonly kind: "option" | "argument";
+    readonly name: string;
+    readonly requiredName: string;
+  };
+
+  /** The `conflictWith` list contains the same name as the definition itself. */
+  readonly SelfConflict: DefinitionErrorI["SelfRequire"];
+
+  /** The `conflictWith` list contains a name that does not exist. */
+  readonly UnknownConflictName: DefinitionErrorI["UnknownRequireName"];
+
+  /** The `requires` list overlaps with the `conflictWith` list. */
+  readonly DefinitionRequiresConflictOverlap: {
+    readonly commandKind: "command" | "subcommand";
+    readonly commandName: string;
+    readonly kind: "option" | "argument";
+    readonly name: string;
+    readonly intersectedNames: readonly string[];
+  };
+
+  /** Triggered when attempting to generate a help message for a subcommand that does not exist in the CLI definition. */
+  readonly SubcommandHelpNotFound: {
+    readonly cliName: string;
+    readonly subcommandName: string;
+  };
+}
+
+export interface ParseErrorI {
+  /** The parser could not find a matching command in the CLI definition */
+  readonly UnknownSubcommand: {
+    readonly commandName: string;
+  };
+
+  /** Received an option for a cli or subcommand but no options were defined */
+  readonly CommandWithoutOptions: {
+    readonly commandKind: "command" | "subcommand";
+    readonly commandName: string;
+    readonly optionName: string;
+  };
+
+  /** The cli or subcommand define options but could not find a matching option */
+  readonly UnknownOption: {
+    readonly commandKind: "command" | "subcommand";
+    readonly commandName: string;
+    readonly optionName: string;
+  };
+
+  /** Triggered when a duplicate option is supplied to a command or subcommand. */
+  readonly DuplicateOptionProvided: {
+    readonly commandKind: "command" | "subcommand";
+    readonly commandName: string;
+    readonly optionName: string;
+  };
+
+  /** Triggered when a non-boolean option is incorrectly used with a negation prefix. */
+  readonly InvalidNegationForNonBooleanOption: {
+    readonly commandKind: "command" | "subcommand";
+    readonly commandName: string;
+    readonly optionName: string;
+  };
+
+  /** Triggered when a argument is provided to a command or subcommand that does not allow positional arguments. */
+  readonly PositionalArgumentNotAllowed: {
+    readonly commandKind: "command" | "subcommand";
+    readonly commandName: string;
+    readonly argumentName: string;
+  };
+
+  /** Triggered when a required option is not provided to a command or subcommand. */
+  readonly MissingRequiredOption: {
+    readonly commandKind: "command" | "subcommand";
+    readonly commandName: string;
+    readonly optionName: string;
+  };
+
+  /** Triggered when a required argument is not provided to a command or subcommand. */
+  readonly MissingRequiredArgument: {
+    readonly commandKind: "command" | "subcommand";
+    readonly commandName: string;
+    readonly argumentName: string;
+  };
+
+  /** Triggered when an option that requires a value is provided without one in a command or subcommand. */
+  readonly OptionMissingValue: {
+    readonly commandKind: "command" | "subcommand";
+    readonly commandName: string;
+    readonly optionName: string;
+  };
+
+  /** Triggered when a flag (single letter options: -v) argument is incorrectly assigned a value using "=". */
+  readonly FlagAssignedValue: {
+    readonly commandKind: "command" | "subcommand";
+    readonly commandName: string;
+    readonly flag: string;
+    readonly value: string;
+  };
+}
+
+export interface ValidationErrorI {
+  /** Triggered when validating an option on a command or subcommand that has no options defined. */
+  readonly NoOptionsToValidate: {
+    readonly commandKind: "command" | "subcommand";
+    readonly commandName: string;
+  };
+
+  /** Triggered when validating an argument on a command or subcommand that has no arguments defined. */
+  readonly NoArgumentsToValidate: {
+    readonly commandKind: "command" | "subcommand";
+    readonly commandName: string;
+  };
+
+  /** Triggered when attempting to validate an option that does not exist for a command or subcommand. */
+  readonly UnknownOptionValidation: {
+    readonly commandKind: "command" | "subcommand";
+    readonly commandName: string;
+    readonly optionName: string;
+  };
+
+  /** Triggered when attempting to validate an argument that does not exist for a command or subcommand. */
+  readonly UnknownArgumentValidation: {
+    readonly commandKind: "command" | "subcommand";
+    readonly commandName: string;
+    readonly argumentName: string;
+  };
+
+  /** Triggered when schema validation of an option or argument fails */
+  readonly SchemaValidationFailed: {
+    readonly commandKind: "command" | "subcommand";
+    readonly commandName: string;
+    readonly kind: "option" | "argument";
+    readonly name: string;
+    readonly inputValue: unknown;
+    readonly issues: ReadonlyArray<StandardSchemaV1.Issue>;
+  };
+
+  /**
+   * Triggered when an option or argument cannot be used together with certain other options or arguments due to mutual
+   * exclusivity.
+   */
+  readonly MutuallyExclusiveConflict: {
+    readonly kind: "option" | "argument";
+    readonly name: string;
+    readonly conflictedOptions: readonly string[];
+    readonly conflictedArguments: readonly string[];
+  };
+
+  /** Triggered when an option or argument is missing a required dependent option or argument in a command or subcommand. */
+  readonly RequiredDependencyMissing: {
+    readonly kind: "option" | "argument";
+    readonly name: string;
+    readonly missingOptions: readonly string[];
+    readonly missingArguments: readonly string[];
+  };
+
+  /** Triggered when attempting to perform synchronous validation on an asynchronous schema. */
+  readonly AsyncSchemaNotSupported: {
+    value: unknown;
+    schema: SchemaType;
+  };
+
+  /** Triggered when coercion of a value to the expected type fails during validation. */
+  readonly CoercionFailed: {
+    readonly providedValue: unknown;
+    readonly coerceToType: string;
+  };
+}
+
+export interface CliErrorI extends DefinitionErrorI, ParseErrorI, ValidationErrorI, InternalErrorI {}
+
+export interface CliErrorImpl<O extends CliErrorOptionUnion = CliErrorOptionUnion> extends Error {
+  readonly cause: O["cause"];
+  readonly code: O["code"];
+  readonly context: O["context"];
+}
+
+/**
+ * Represents a subset of CliErrorOptions filtered by the provided cause. Removes the 'message' property and narrows the
+ * union to only relevant cause.
+ */
+export type CliErrorOptionByCause<K extends keyof ErrorCauseI, T = CliErrorOptionUnion> = T extends CliErrorOptionUnion
+  ? T["cause"] extends K
+    ? T
+    : never
+  : never;
+
+interface CliErrorOption<Code extends keyof CliErrorI> {
+  cause: { [K in keyof ErrorCauseI]: Code extends ErrorCauseI[K] ? K : never }[keyof ErrorCauseI];
+  code: Code;
+  context: CliErrorI[Code];
+  message?: string;
+}
+
+/** A union of all possible CLI error options, one per error code. Each member includes: */
+export type CliErrorOptionUnion = { [Code in keyof CliErrorI]: CliErrorOption<Code> }[keyof CliErrorI];
+
+/** A union of all possible CLI error instances */
+export type CliErrorInstanceUnion = CliErrorOptionUnion extends infer T
+  ? T extends CliErrorOptionUnion
+    ? CliErrorImpl<T>
+    : never
+  : never;
+
+export type AllCliErrorInstances = CliErrorInstanceUnion & {};

package/src/types/types.ts

@@ -1,9 +1,94 @@
 import type { Cli, Subcommand } from "./definitions-types.ts";
+import type { AllCliErrorInstances } from "./error-types.ts";
 import type { PrintHelpOptions } from "./help-message-types.ts";
 import type { InferInputType, InputTypeWide, OutputType, OutputTypeWide } from "./io-types.ts";
 
-type PrimitiveTypeNames = "string" | "number" | "boolean" | "object" | "unknown";
-export type CoerceTypes = PrimitiveTypeNames | `${PrimitiveTypeNames}[]` | `set<${PrimitiveTypeNames}>` | (string & {});
+export type CoerceTypes = "boolean" | (string & {});
+
+export interface ObjectCoerceMethodOptions {
+  /**
+   * Converts `'true'` or `'false'` (case-sensitive) strings to boolean values.
+   *
+   * The coercion is applied after parsing the string as JSON.
+   *
+   * ```bash
+   * # coerced to boolean
+   * --obj.key=true       # true
+   * --obj.key false      # false
+   *
+   * # remains a string (case-sensitive)
+   * --obj.key=FALSE      # "FALSE"
+   * ```
+   *
+   * @example
+   *   coerce: coerce.object({ coerceBoolean: true }); // coerce all boolean-like keys
+   *   coerce: coerce.object({ coerceBoolean: ["key.nested"] }); // coerce only specific keys
+   */
+  coerceBoolean?: boolean | string[];
+
+  /**
+   * Converts strings matching a number regex to numbers.
+   *
+   * The coercion is applied after parsing the string as JSON.
+   *
+   * ```bash
+   * # parsed as number
+   * --obj.key=123
+   * --obj.key 123.45
+   * --obj.key -123.45
+   * --obj.key +123.45
+   *
+   * # remains a string (invalid number)
+   * --obj.key 1.23.45
+   * --obj.key string
+   * ```
+   *
+   * @example
+   *   coerce: coerce.object({ coerceNumber: true }); // coerce all numeric keys
+   *   coerce: coerce.object({ coerceNumber: ["key.nested"] }); // coerce only specific keys
+   */
+  coerceNumber?: boolean | string[];
+
+  /**
+   * Converts strings matching a number regex to bigints.
+   *
+   * The coercion is applied after parsing the string as JSON.
+   *
+   * ```bash
+   * # parsed as bigint
+   * --obj.key=12345678901234567890
+   *
+   * # remains a string (invalid bigint)
+   * --obj.key 123.45
+   * --obj.key string
+   * ```
+   *
+   * @example
+   *   coerce: coerce.object({ coerceBigint: true }); // coerce all bigint-like keys
+   *   coerce: coerce.object({ coerceBigint: ["key.id"] }); // coerce only specific keys
+   */
+  coerceBigint?: boolean | string[];
+
+  /**
+   * Converts tries to convert any string to `Date` objects.
+   *
+   * The coercion is applied after parsing the string as JSON.
+   *
+   * ```bash
+   * # parsed as Date
+   * --obj.key="2024-03-12T10:30:00Z"
+   * --obj.key "2025-11-13"
+   *
+   * # remains a string (invalid date)
+   * --obj.key "invalid-date"
+   * ```
+   *
+   * @example
+   *   coerce: coerce.object({ coerceDate: true }); // coerce all date-like keys
+   *   coerce: coerce.object({ coerceDate: ["user.createdAt"] }); // coerce only specific keys
+   */
+  coerceDate?: boolean | string[];
+}
 
 export interface CoerceMethod<Value> {
   (terminalInput: string): Value;
@@ -27,20 +112,27 @@ export interface AttachedMethods<T extends Cli | Subcommand> {
    */
   onExecute: (handler: (data: OutputType<[T]>) => void) => Unsubscribe;
 
-  // Make the argument optional if it has undefined type
+  /** Execute the main command/subcommand programmatically */
   execute: InferInputType<T> extends infer InputType
     ? undefined extends InputType
       ? (input?: InputType) => void
       : (input: InputType) => void
     : never;
 
+  /** Execute the main command/subcommand programmatically */
+  executeAsync: InferInputType<T> extends infer InputType
+    ? undefined extends InputType
+      ? (input?: InputType) => Promise<void>
+      : (input: InputType) => Promise<void>
+    : never;
+
   /** **WARNING**: This will only be available after the CLI schema has been created */
   generateCliHelpMessage?: (options?: PrintHelpOptions) => string;
 
   /**
    * **WARNING**: This will only be available after the CLI schema has been created
    *
-   * @throws {Error} - When the subcommand is not found
+   * @throws {CliError} - When the subcommand is not found
    */
   generateSubcommandHelpMessage?: (
     subcommandName: GetSubcommandsNames<T> | (string & {}),
@@ -49,10 +141,11 @@ export interface AttachedMethods<T extends Cli | Subcommand> {
 }
 
 export interface AttachedMethodsWide {
-  onExecute: (handler: (data: OutputTypeWide) => void) => Unsubscribe;
+  onExecute: (handler: (data: OutputTypeWide) => void | Promise<void>) => Unsubscribe;
   execute: (input?: InputTypeWide) => void;
+  executeAsync: (input?: InputTypeWide) => Promise<void>;
   generateCliHelpMessage?: (options?: PrintHelpOptions) => void;
-  /** @throws {Error} - When the subcommand is not found */
+  /** @throws {CliError} - When the subcommand is not found */
   generateSubcommandHelpMessage?: (subcommandName: string, options?: PrintHelpOptions) => void;
 }
 
@@ -62,7 +155,7 @@ export type CliOutputType<S extends Cli> =
 
 export type CliParseResult<S extends Cli> =
   | { value: CliOutputType<S>; error?: undefined }
-  | { value?: never; error: Error };
+  | { value?: never; error: AllCliErrorInstances };
 
 export type CliParseResultWide = { value: OutputTypeWide; error?: undefined } | { value?: never; error: Error };
 

package/src/types/utilities-types.ts

@@ -14,13 +14,3 @@ export type AllowUndefinedIfOptional<T> = {
 }[keyof T] extends never
   ? T | undefined
   : T;
-
-/** Widen literal and tuples */
-// prettier-ignore
-export type Widen<T> =
-  T extends string ? string :
-  T extends number ? number :
-  T extends boolean ? boolean :
-  T extends readonly (infer U)[] ? Widen<U>[] :
-  T extends Set<infer U> ? Set<Widen<U>> :
-  T;

package/src/utilities/parse-argv.ts

@@ -0,0 +1,79 @@
+/** Parse a string into an argv (array of arguments) */
+export function parseArgv(input: string): string[] {
+  const argv = [];
+
+  let currentQuote: string | undefined = undefined;
+  let currentArgument: string | undefined = undefined;
+
+  for (let index = 0; index < input.length; index++) {
+    const char = input[index];
+    const previousChar = input[index - 1];
+    const nextChar = input[index + 1];
+    const end = index === input.length - 1;
+
+    // entering/leaving quote
+    if ((char === '"' || char === "'") && previousChar !== "\\") {
+      // leaving quote
+      if (currentQuote === char) {
+        currentQuote = undefined;
+        continue;
+      }
+
+      // entering quote
+      if (currentQuote === undefined) {
+        currentQuote = char;
+        continue;
+      }
+
+      // quote inside quote
+      if (currentQuote !== undefined && char !== currentQuote) {
+        currentArgument ??= "";
+        currentArgument += char;
+        continue;
+      }
+      continue;
+    }
+
+    // new line
+    if (char === "\\" && nextChar === "\n") {
+      index++;
+      continue;
+    }
+
+    // Add to argv
+    if (currentArgument !== undefined && currentQuote === undefined) {
+      if (char === " ") {
+        argv.push(currentArgument);
+        currentArgument = undefined;
+        continue;
+      }
+
+      if (end) {
+        currentArgument += char;
+        argv.push(currentArgument);
+        currentArgument = undefined;
+        continue;
+      }
+    }
+
+    // Ignore spaces outside of quotes
+    if (char === " " && currentQuote === undefined) {
+      continue;
+    }
+
+    // Ignore escaped characters
+    if (char === "\\" && (nextChar === "'" || nextChar === '"')) {
+      continue;
+    }
+
+    currentArgument ??= "";
+    currentArgument += char;
+  }
+
+  // Add last argument
+  if (currentArgument !== undefined) {
+    argv.push(currentArgument);
+  }
+
+  return argv;
+}

package/src/utilities/schema-utilities.ts

@@ -0,0 +1,72 @@
+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 type { Argument, Option, PreparedType } from "../types/definitions-types.ts";
+import type { SchemaResult, SchemaType } from "../types/schema-types.ts";
+import type { CoerceMethod } from "../types/types.ts";
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+
+/** @throws {CliError} When schema is async */
+export function validateSync(schema: SchemaType, value?: unknown): SchemaResult {
+  const results = schema["~standard"].validate(value);
+  if (results instanceof Promise) {
+    throw new CliError({
+      cause: ErrorCause.Validation,
+      code: ValidationErrorCode.AsyncSchemaNotSupported,
+      context: { schema, value },
+    });
+  }
+
+  return results;
+}
+
+/** @throws {CliError} When schema is async */
+export function defaultValueAndIsOptional(schema: SchemaType): { defaultValue: unknown; optional: boolean } {
+  const results = validateSync(schema);
+
+  if (results.issues) {
+    return { defaultValue: undefined, optional: false };
+  }
+
+  return { defaultValue: results.value, optional: true };
+}
+
+/** @throws {CliError} When schema is async */
+function PrepareType(schema: SchemaType, coerceHandler: CoerceMethod<unknown>): PreparedType {
+  const { optional, defaultValue } = defaultValueAndIsOptional(schema);
+
+  return {
+    schema,
+    optional,
+    defaultValue,
+    coerceTo: coerceHandler.type,
+    validate: (value?: string) => validateSync(schema, value && coerceHandler(value)),
+  };
+}
+
+/** @throws {CliError} When schema is async */
+export function prepareDefinitionTypes(definition: Record<string, Argument> | Record<string, Option> | undefined) {
+  if (!definition) return;
+
+  for (const object of Object.values<Argument | Option>(definition)) {
+    if (!object.coerce) {
+      (object.coerce as CoerceMethod<string> | undefined) = (value: string) => value;
+    }
+
+    if (!object._preparedType) {
+      object._preparedType = PrepareType(object.schema, object.coerce!);
+    }
+  }
+}
+
+/** Prettify Standard Schema V1 issues */
+export function prettifyError(issues: ReadonlyArray<StandardSchemaV1.Issue>): string {
+  return issues
+    .map(issue => {
+      const path = issue.path?.map(seg => (typeof seg === "object" && "key" in seg ? seg.key : seg));
+      const pathString = path && path.length > 0 ? ` at "${path.join(".")}"` : "";
+      return `${issue.message}${pathString}`;
+    })
+    .join(" : ");
+}