Improve typing

Author: schaable

v-next/core/src/config.ts

@@ -1,6 +1,8 @@
-import type { ArgumentTypeToValueType } from "./types/arguments.js";
+import type {
+  ArgumentTypeToValueType,
+  OptionDefinition,
+} from "./types/arguments.js";
 import type { ConfigurationVariable } from "./types/config.js";
-import type { GlobalOptionDefinition } from "./types/global-options.js";
 import type {
   EmptyTaskDefinitionBuilder,
   NewTaskDefinitionBuilder,
@@ -63,7 +65,7 @@ export function globalOption<T extends ArgumentType>(options: {
   description: string;
   type?: T;
   defaultValue: ArgumentTypeToValueType<T>;
-}): GlobalOptionDefinition {
+}): OptionDefinition {
   return buildGlobalOptionDefinition(options);
 }
 
@@ -73,7 +75,7 @@ export function globalOption<T extends ArgumentType>(options: {
 export function globalFlag(options: {
   name: string;
   description: string;
-}): GlobalOptionDefinition {
+}): OptionDefinition {
   return buildGlobalOptionDefinition({
     ...options,
     type: ArgumentType.BOOLEAN,

v-next/core/src/internal/global-options.ts

@@ -1,10 +1,10 @@
 import type {
   ArgumentTypeToValueType,
   ArgumentValue,
+  OptionDefinition,
 } from "../types/arguments.js";
 import type {
   GlobalOptions,
-  GlobalOptionDefinition,
   GlobalOptionDefinitions,
 } from "../types/global-options.js";
 import type { HardhatPlugin } from "../types/plugins.js";
@@ -80,7 +80,7 @@ export function buildGlobalOptionDefinition<T extends ArgumentType>({
   description: string;
   type?: T;
   defaultValue: ArgumentTypeToValueType<T>;
-}): GlobalOptionDefinition {
+}): OptionDefinition {
   const argumentType = type ?? ArgumentType.STRING;
 
   if (!isArgumentNameValid(name)) {

v-next/core/src/internal/tasks/builders.ts

@@ -1,10 +1,12 @@
-import type { ArgumentTypeToValueType } from "../../types/arguments.js";
 import type {
-  TaskOptionDefinition,
+  ArgumentTypeToValueType,
+  OptionDefinition,
+  PositionalArgumentDefinition,
+} from "../../types/arguments.js";
+import type {
   NewTaskActionFunction,
   NewTaskDefinitionBuilder,
   NewTaskDefinition,
-  TaskPositionalArgumentDefinition,
   TaskOverrideActionFunction,
   TaskOverrideDefinitionBuilder,
   TaskOverrideDefinition,
@@ -62,8 +64,8 @@ export class NewTaskDefinitionBuilderImplementation
   readonly #id: string[];
   readonly #usedNames: Set<string> = new Set();
 
-  readonly #options: Record<string, TaskOptionDefinition> = {};
-  readonly #positionalArgs: TaskPositionalArgumentDefinition[] = [];
+  readonly #options: Record<string, OptionDefinition> = {};
+  readonly #positionalArgs: PositionalArgumentDefinition[] = [];
 
   #description: string;
 
@@ -294,7 +296,7 @@ export class TaskOverrideDefinitionBuilderImplementation
 {
   readonly #id: string[];
 
-  readonly #options: Record<string, TaskOptionDefinition> = {};
+  readonly #options: Record<string, OptionDefinition> = {};
 
   #description?: string;
 

v-next/core/src/internal/tasks/resolved-task.ts

@@ -1,14 +1,15 @@
-import type { ArgumentValue } from "../../types/arguments.js";
+import type {
+  ArgumentValue,
+  OptionDefinition,
+  PositionalArgumentDefinition,
+} from "../../types/arguments.js";
 import type { HardhatRuntimeEnvironment } from "../../types/hre.js";
 import type {
-  TaskOptionDefinition,
   NewTaskActionFunction,
-  TaskPositionalArgumentDefinition,
   Task,
   TaskActions,
   TaskArguments,
   TaskOverrideActionFunction,
-  TaskArgumentDefinition,
 } from "../../types/tasks.js";
 
 import {
@@ -48,8 +49,8 @@ export class ResolvedTask implements Task {
     id: string[],
     description: string,
     action: NewTaskActionFunction | string,
-    options: Record<string, TaskOptionDefinition>,
-    positionalArguments: TaskPositionalArgumentDefinition[],
+    options: Record<string, OptionDefinition>,
+    positionalArguments: PositionalArgumentDefinition[],
     pluginId?: string,
   ): ResolvedTask {
     return new ResolvedTask(
@@ -68,8 +69,8 @@ export class ResolvedTask implements Task {
     public readonly id: string[],
     public readonly description: string,
     public readonly actions: TaskActions,
-    public readonly options: Map<string, TaskOptionDefinition>,
-    public readonly positionalArguments: TaskPositionalArgumentDefinition[],
+    public readonly options: Map<string, OptionDefinition>,
+    public readonly positionalArguments: PositionalArgumentDefinition[],
     public readonly pluginId: string | undefined,
     public readonly subtasks: Map<string, Task>,
     hre: HardhatRuntimeEnvironment,
@@ -98,25 +99,34 @@ export class ResolvedTask implements Task {
       });
     }
 
-    // Normalize arguments into a single iterable
-    const allArguments: TaskArgumentDefinition[] = [
-      ...this.options.values(),
-      ...this.positionalArguments,
-    ];
-
     const providedArgumentNames = new Set(Object.keys(taskArguments));
-    for (const argument of allArguments) {
+
+    // Validate and resolve the task options
+    for (const option of this.options.values()) {
+      const value = taskArguments[option.name];
+
+      this.#validateArgumentType(option, value);
+
+      // resolve defaults for optional arguments
+      if (value === undefined) {
+        taskArguments[option.name] = option.defaultValue;
+      }
+
+      providedArgumentNames.delete(option.name);
+    }
+
+    // Validate and resolve the task positional arguments
+    for (const argument of this.positionalArguments) {
       const value = taskArguments[argument.name];
 
       this.#validateRequiredArgument(argument, value);
-      this.#validateArgumentType(argument, value);
+      this.#validateArgumentType(argument, value, argument.isVariadic);
 
       // resolve defaults for optional arguments
       if (value === undefined && argument.defaultValue !== undefined) {
         taskArguments[argument.name] = argument.defaultValue;
       }
 
-      // Remove processed argument from the set
       providedArgumentNames.delete(argument.name);
     }
 
@@ -166,7 +176,7 @@ export class ResolvedTask implements Task {
    * @throws HardhatError if the argument is required and doesn't have a value.
    */
   #validateRequiredArgument(
-    argument: TaskArgumentDefinition,
+    argument: PositionalArgumentDefinition,
     value: ArgumentValue | ArgumentValue[],
   ) {
     if (argument.defaultValue === undefined && value === undefined) {
@@ -188,20 +198,15 @@ export class ResolvedTask implements Task {
    * @throws HardhatError if the argument has an invalid type.
    */
   #validateArgumentType(
-    argument: TaskArgumentDefinition,
+    argument: OptionDefinition | PositionalArgumentDefinition,
     value: ArgumentValue | ArgumentValue[],
+    isVariadic: boolean = false,
   ) {
     // skip type validation for optional arguments with undefined value
     if (value === undefined && argument.defaultValue !== undefined) {
       return;
     }
 
-    // check if the argument is variadic
-    const isPositionalArgument = (
-      arg: TaskArgumentDefinition,
-    ): arg is TaskPositionalArgumentDefinition => "isVariadic" in arg;
-    const isVariadic = isPositionalArgument(argument) && argument.isVariadic;
-
     // check if the value is valid for the argument type
     if (!isArgumentValueValid(argument.type, value, isVariadic)) {
       throw new HardhatError(

v-next/core/src/types/arguments.ts

@@ -43,3 +43,37 @@ export type ArgumentValue = ArgumentValueTypes[keyof ArgumentValueTypes];
  */
 export type ArgumentTypeToValueType<T extends ArgumentType> =
   ArgumentValueTypes[T];
+
+/**
+ * Options in CLI are specified as `--<name> value`, where `--<name>` is the
+ * option's name and `value` is the argument it takes. For example,
+ * `--network mainnet` sets the network option to `mainnet`.
+ *
+ * Options can also be flags, which are boolean options that don't take an
+ * argument. For example, `--help` is a flag that shows the help message.
+ *
+ * Options are always optional and can be provided in any order.
+ */
+export interface OptionDefinition<T extends ArgumentType = ArgumentType> {
+  name: string;
+  description: string;
+  type: ArgumentType;
+  defaultValue: ArgumentTypeToValueType<T>;
+}
+
+/**
+ * A positional argument is used as `<value>` in the CLI, where its position
+ * matters. For example, `mv <from> <to>` has two positional arguments.
+ *
+ * If the argument is variadic, it accepts multiple values. A variadic argument
+ * must be the last positional argument and consumes all remaining values.
+ */
+export interface PositionalArgumentDefinition<
+  T extends ArgumentType = ArgumentType,
+> {
+  name: string;
+  description: string;
+  type: T;
+  defaultValue?: ArgumentTypeToValueType<T> | Array<ArgumentTypeToValueType<T>>;
+  isVariadic: boolean;
+}

v-next/core/src/types/global-options.ts

@@ -1,28 +1,18 @@
-import type { ArgumentType, ArgumentTypeToValueType } from "./arguments.js";
+import type { OptionDefinition } from "./arguments.js";
 
 /**
- * A global option with an associated value and a default if not provided by
- * the user. They are available in the Hardhat Runtime Environment.
+ * The values of each global option for a certain instance of the Hardhat
+ * Runtime Environment are defined here. This interface can be extended through
+ * module augmentation to include additional global options as needed.
  *
- * They can be provided in these different ways:
- *  1. Through environment variables, with the format
- *     `HARDHAT_<OPTION_NAME_WITH_THIS_CASING>`.
- *  2. Through the CLI with the format `--<option-name-with-this-casing> <value>`.
- *    2.1. Through the CLI with the format `--<option-name-with-this-casing>` if
- *      the option is boolean and its default value is `false`.
+ * Global options can be provided in several ways and are accessible through
+ * the Hardhat Runtime Environment:
+ *  1. Environment variables: `HARDHAT_<OPTION_NAME_WITH_THIS_CASING>`
+ *  2. CLI arguments:
+ *     - `--<option-name-with-this-casing> <value>` for options with values
+ *     - `--<option-name-with-this-casing>` for boolean options with a false default
  *
- * If both are present, the second one takes precedence.
- */
-export interface GlobalOptionDefinition<T extends ArgumentType = ArgumentType> {
-  name: string;
-  description: string;
-  type: ArgumentType;
-  defaultValue: ArgumentTypeToValueType<T>;
-}
-
-/**
- * The values of each global option for a certain instance of the Hardhat
- * Runtime Environment.
+ * CLI arguments take precedence over environment variables.
  */
 // eslint-disable-next-line @typescript-eslint/no-empty-interface -- To be used through module augmentation
 export interface GlobalOptions {}
@@ -33,7 +23,7 @@ export interface GlobalOptions {}
  */
 export interface GlobalOptionDefinitionsEntry {
   pluginId: string;
-  option: GlobalOptionDefinition;
+  option: OptionDefinition;
 }
 
 /**

v-next/core/src/types/plugins.ts

@@ -1,4 +1,4 @@
-import type { GlobalOptionDefinition } from "./global-options.js";
+import type { OptionDefinition } from "./arguments.js";
 import type { HardhatHooks } from "./hooks.js";
 import type { TaskDefinition } from "./tasks.js";
 
@@ -67,7 +67,7 @@ export interface HardhatPlugin {
   /**
    * An array of the global options that this plugin defines.
    */
-  globalOptions?: GlobalOptionDefinition[];
+  globalOptions?: OptionDefinition[];
 
   /**
    * An array of type definitions, which should be created using their builders.

v-next/core/src/types/tasks.ts

@@ -1,7 +1,9 @@
 import type {
+  OptionDefinition,
   ArgumentType,
   ArgumentTypeToValueType,
   ArgumentValue,
+  PositionalArgumentDefinition,
 } from "./arguments.js";
 import type { HardhatRuntimeEnvironment } from "./hre.js";
 
@@ -27,40 +29,6 @@ declare module "./config.js" {
   }
 }
 
-export interface TaskArgumentDefinition<T extends ArgumentType = ArgumentType> {
-  name: string;
-  description: string;
-  type: T;
-  defaultValue?: ArgumentTypeToValueType<T> | Array<ArgumentTypeToValueType<T>>;
-}
-
-/**
- * A task option is one that is used as `--<name> value` in the CLI.
- *
- * They have a name, description, type, and an optional default value.
- *
- * If the type is ArgumentType.BOOLEAN, the default value is `false`, the
- * argument is considered a flag, and can be used as `--<name>` to set it to
- * `true`.
- */
-export interface TaskOptionDefinition<T extends ArgumentType = ArgumentType>
-  extends TaskArgumentDefinition<T> {
-  defaultValue: ArgumentTypeToValueType<T>;
-}
-
-/**
- * A positional task argument is one that is used as `<value>` in the CLI, and whose
- * position matters. For example, `mv <from> <to>` has two positional arguments.
- *
- * If the argument is variadic, it can have multiple values. A variadic argument
- * can only be the last positional argument, and it consumes all the remaining values.
- */
-export interface TaskPositionalArgumentDefinition<
-  T extends ArgumentType = ArgumentType,
-> extends TaskArgumentDefinition<T> {
-  isVariadic: boolean;
-}
-
 /**
  * A type representing the concrete arguments of a task. That is,
  * the actual values passed to it.
@@ -125,9 +93,9 @@ export interface NewTaskDefinition {
 
   action: NewTaskActionFunction | string;
 
-  options: Record<string, TaskOptionDefinition>;
+  options: Record<string, OptionDefinition>;
 
-  positionalArguments: TaskPositionalArgumentDefinition[];
+  positionalArguments: PositionalArgumentDefinition[];
 }
 
 /**
@@ -142,7 +110,7 @@ export interface TaskOverrideDefinition {
 
   action: TaskOverrideActionFunction | string;
 
-  options: Record<string, TaskOptionDefinition>;
+  options: Record<string, OptionDefinition>;
 }
 
 /**
@@ -343,12 +311,12 @@ export interface Task {
   /**
    * The task options.
    */
-  options: Map<string, TaskOptionDefinition>;
+  options: Map<string, OptionDefinition>;
 
   /**
    * The task positional arguments.
    */
-  positionalArguments: TaskPositionalArgumentDefinition[];
+  positionalArguments: PositionalArgumentDefinition[];
 
   /**
    * Whether the task is an empty task.