feat: error handler (#29)

Author: so1ve

packages/core/src/cli.ts

@@ -45,7 +45,7 @@ import {
 import { mapParametersToArguments, parseParameters } from "./parameters";
 import { locales } from "./locales";
 
-export const Root = Symbol("Root");
+export const Root = Symbol.for("Clerc.Root");
 export type RootType = typeof Root;
 
 export class Clerc<C extends CommandRecord = {}> {
@@ -57,6 +57,7 @@ export class Clerc<C extends CommandRecord = {}> {
   #commandEmitter = new LiteEmit<MakeEventMap<C>>();
   #usedNames = new Set<string | RootType>();
   #argv: string[] | undefined;
+  #errorHandlers = [] as ((err: any) => void)[];
 
   #isOtherMethodCalled = false;
   #defaultLocale = "en";
@@ -162,7 +163,7 @@ export class Clerc<C extends CommandRecord = {}> {
 
   /**
    * Set the Locale
-   * It's recommended to call this method once after you created the Clerc instance.
+   * You must call this method once after you created the Clerc instance.
    * @param locale
    * @returns
    * @example
@@ -180,7 +181,7 @@ export class Clerc<C extends CommandRecord = {}> {
 
   /**
    * Set the fallback Locale
-   * It's recommended to call this method once after you created the Clerc instance.
+   * You must call this method once after you created the Clerc instance.
    * @param fallbackLocale
    * @returns
    * @example
@@ -196,6 +197,21 @@ export class Clerc<C extends CommandRecord = {}> {
     return this;
   }
 
+  /**
+   * Register a error handler
+   * @param handler
+   * @returns
+   * @example
+   * ```ts
+   * Clerc.create()
+   *   .errorHandler((err) => { console.log(err); })
+   * ```
+   */
+  errorHandler(handler: (err: any) => void) {
+    this.#errorHandlers.push(handler);
+    return this;
+  }
+
   /**
    * Register a command
    * @param name
@@ -356,87 +372,74 @@ export class Clerc<C extends CommandRecord = {}> {
     }
   }
 
-  /**
-   * Run matched command
-   * @returns
-   * @example
-   * ```ts
-   * Clerc.create()
-   *   .parse({ run: false })
-   *   .runMatchedCommand()
-   * ```
-   */
-  runMatchedCommand() {
+  #getContext(getCommand: () => ReturnType<typeof resolveCommand>) {
+    const argv = this.#argv!;
+    const [command, called] = getCommand();
+    const isCommandResolved = !!command;
+    // [...argv] is a workaround since TypeFlag modifies argv
+    const parsed = typeFlag(command?.flags || {}, [...argv]);
+    const { _: args, flags, unknownFlags } = parsed;
+    let parameters = !isCommandResolved || command.name === Root ? args : args.slice(command.name.split(" ").length);
+    let commandParameters = command?.parameters || [];
+    // eof handle
+    const hasEof = commandParameters.indexOf("--");
+    const eofParameters = commandParameters.slice(hasEof + 1) || [];
+    const mapping: Record<string, string | string[]> = Object.create(null);
+    // Support `--` eof parameters
+    if (hasEof > -1 && eofParameters.length > 0) {
+      commandParameters = commandParameters.slice(0, hasEof);
+      const eofArguments = args["--"];
+      parameters = parameters.slice(0, -eofArguments.length || undefined);
+
+      mapParametersToArguments(
+        mapping,
+        parseParameters(commandParameters),
+        parameters,
+      );
+      mapParametersToArguments(
+        mapping,
+        parseParameters(eofParameters),
+        eofArguments,
+      );
+    } else {
+      mapParametersToArguments(
+        mapping,
+        parseParameters(commandParameters),
+        parameters,
+      );
+    }
+    const mergedFlags = { ...flags, ...unknownFlags };
+    const context: InspectorContext | HandlerContext = {
+      name: command?.name as any,
+      called: Array.isArray(called) ? called.join(" ") : called,
+      resolved: isCommandResolved as any,
+      hasRootOrAlias: this.#hasRootOrAlias,
+      hasRoot: this.#hasRoot,
+      raw: { ...parsed, parameters, mergedFlags },
+      parameters: mapping,
+      flags,
+      unknownFlags,
+      cli: this as any,
+    };
+    return context;
+  }
+
+  #runMatchedCommand() {
     this.#otherMethodCaled();
     const { t } = this.i18n;
     const argv = this.#argv;
     if (!argv) {
-      throw new Error("cli.parse() must be called.");
+      throw new Error(t("core.cliParseMustBeCalled"));
     }
     const name = resolveParametersBeforeFlag(argv);
     const stringName = name.join(" ");
     const getCommand = () => resolveCommand(this.#commands, name, t);
-    const mapErrors = [] as (Error | undefined)[];
-    const getContext = () => {
-      mapErrors.length = 0;
-      const [command, called] = getCommand();
-      const isCommandResolved = !!command;
-      // [...argv] is a workaround since TypeFlag modifies argv
-      const parsed = typeFlag(command?.flags || {}, [...argv]);
-      const { _: args, flags, unknownFlags } = parsed;
-      let parameters = !isCommandResolved || command.name === Root ? args : args.slice(command.name.split(" ").length);
-      let commandParameters = command?.parameters || [];
-      // eof handle
-      const hasEof = commandParameters.indexOf("--");
-      const eofParameters = commandParameters.slice(hasEof + 1) || [];
-      const mapping: Record<string, string | string[]> = Object.create(null);
-      // Support `--` eof parameters
-      if (hasEof > -1 && eofParameters.length > 0) {
-        commandParameters = commandParameters.slice(0, hasEof);
-        const eofArguments = args["--"];
-        parameters = parameters.slice(0, -eofArguments.length || undefined);
-
-        mapErrors.push(mapParametersToArguments(
-          mapping,
-          parseParameters(commandParameters),
-          parameters,
-        ));
-        mapErrors.push(mapParametersToArguments(
-          mapping,
-          parseParameters(eofParameters),
-          eofArguments,
-        ));
-      } else {
-        mapErrors.push(mapParametersToArguments(
-          mapping,
-          parseParameters(commandParameters),
-          parameters,
-        ));
-      }
-      const mergedFlags = { ...flags, ...unknownFlags };
-      const context: InspectorContext | HandlerContext = {
-        name: command?.name as any,
-        called: Array.isArray(called) ? called.join(" ") : called,
-        resolved: isCommandResolved as any,
-        hasRootOrAlias: this.#hasRootOrAlias,
-        hasRoot: this.#hasRoot,
-        raw: { ...parsed, parameters, mergedFlags },
-        parameters: mapping,
-        flags,
-        unknownFlags,
-        cli: this as any,
-      };
-      return context;
-    };
+    const getContext = () => this.#getContext(getCommand);
     const emitHandler: Inspector = {
       enforce: "post",
       fn: () => {
         const [command] = getCommand();
         const handlerContext = getContext();
-        const errors = mapErrors.filter(Boolean) as Error[];
-        if (errors.length > 0) {
-          throw errors[0];
-        }
         if (!command) {
           if (stringName) {
             throw new NoSuchCommandError(stringName, t);
@@ -450,6 +453,28 @@ export class Clerc<C extends CommandRecord = {}> {
     const inspectors = [...this.#inspectors, emitHandler];
     const callInspector = compose(inspectors);
     callInspector(getContext);
+  }
+
+  /**
+   * Run matched command
+   * @returns
+   * @example
+   * ```ts
+   * Clerc.create()
+   *   .parse({ run: false })
+   *   .runMatchedCommand()
+   * ```
+   */
+  runMatchedCommand() {
+    try {
+      this.#runMatchedCommand();
+    } catch (e) {
+      if (this.#errorHandlers.length > 0) {
+        this.#errorHandlers.forEach(cb => cb(e));
+      } else {
+        throw e;
+      }
+    }
     return this;
   }
 }

packages/core/src/locales.ts

@@ -11,6 +11,7 @@ export const locales: Locales = {
     "core.versionNotSet": "Version not set.",
     "core.badNameFormat": "Bad name format: %s.",
     "core.localeMustBeCalledFirst": "locale() or fallbackLocale() must be called at first.",
+    "core.cliParseMustBeCalled": "cli.parse() must be called.",
   },
   "zh-CN": {
     "core.commandExists": "命令 \"%s\" 已存在。",
@@ -22,5 +23,6 @@ export const locales: Locales = {
     "core.versionNotSet": "未设置CLI版本。",
     "core.badNameFormat": "错误的命令名字格式: %s。",
     "core.localeMustBeCalledFirst": "locale() 或 fallbackLocale() 必须在最开始调用。",
+    "core.cliParseMustBeCalled": "cli.parse() 必须被调用。",
   },
 };

packages/core/src/parameters.ts

@@ -70,7 +70,7 @@ export function mapParametersToArguments(
     const { name, required, spread } = parameters[i];
     const camelCaseName = camelCase(name);
     if (camelCaseName in mapping) {
-      return new Error(`Invalid parameter: ${stringify(name)} is used more than once.`);
+      throw new Error(`Invalid parameter: ${stringify(name)} is used more than once.`);
     }
 
     const value = spread ? cliArguments.slice(i) : cliArguments[i];
@@ -83,7 +83,7 @@ export function mapParametersToArguments(
       required
       && (!value || (spread && value.length === 0))
     ) {
-      return new Error(`Error: Missing required parameter ${stringify(name)}`);
+      throw new Error(`Missing required parameter ${stringify(name)}`);
     }
 
     mapping[camelCaseName] = value;

packages/plugin-friendly-error/src/index.ts

@@ -5,16 +5,9 @@ import * as kons from "kons";
 
 export const friendlyErrorPlugin = () => definePlugin({
   setup: (cli) => {
-    return cli.inspector({
-      enforce: "pre",
-      fn: (_ctx, next) => {
-        try {
-          next();
-        } catch (e: any) {
-          kons.error(e.message);
-          process.exit(1);
-        }
-      },
+    return cli.errorHandler((err) => {
+      kons.error(err.message);
+      process.exit(1);
     });
   },
 });