feat: onError support

playground/cli.ts

@@ -1,6 +1,6 @@
 import { defineCommand, runMain } from "../src";
 
-const main = defineCommand({
+export const main = defineCommand({
   meta: {
     name: "citty",
     version: "1.0.0",
@@ -16,7 +16,12 @@ const main = defineCommand({
     build: () => import("./commands/build").then((r) => r.default),
     deploy: () => import("./commands/deploy").then((r) => r.default),
     debug: () => import("./commands/debug").then((r) => r.default),
+    error: () => import("./commands/error").then((r) => r.error),
+    "error-handled": () =>
+      import("./commands/error").then((r) => r.errorHandled),
   },
 });
 
-runMain(main);
+if (process.env.NODE_ENV !== "test") {
+  runMain(main);
+}

playground/commands/error.ts

@@ -0,0 +1,39 @@
+import consola from "consola";
+import { defineCommand } from "../../src";
+
+export const error = defineCommand({
+  args: {
+    throwType: {
+      type: "string",
+    },
+  },
+  run({ args }) {
+    switch (args.throwType) {
+      case "string": {
+        console.log("Throw string");
+        // we intentionally are throwing something invalid for testing purposes
+
+        throw "Not an error!";
+      }
+      case "empty": {
+        console.log("Throw undefined");
+        // we intentionally are throwing something invalid for testing purposes
+
+        throw undefined;
+      }
+      default: {
+        console.log("Throw Error");
+        throw new Error("Error!");
+      }
+    }
+  },
+});
+
+export const errorHandled = defineCommand({
+  run() {
+    throw new Error("intentional error");
+  },
+  onError(error) {
+    consola.error(`Caught error: ${error}`);
+  },
+});

src/command.ts

@@ -64,6 +64,18 @@ export async function runCommand<T extends ArgsDef = ArgsDef>(
     if (typeof cmd.run === "function") {
       result = await cmd.run(context);
     }
+  } catch (originalError) {
+    const error =
+      originalError instanceof Error
+        ? originalError
+        : new Error((originalError as any) ?? "Unknown Error", {
+            cause: originalError,
+          });
+    if (typeof cmd.onError === "function") {
+      await cmd.onError(error, context);
+    } else {
+      throw error;
+    }
   } finally {
     if (typeof cmd.cleanup === "function") {
       await cmd.cleanup(context);

src/types.ts

@@ -95,7 +95,7 @@ type ParsedArg<T extends ArgDef> =
 
 // prettier-ignore
 export type ParsedArgs<T extends ArgsDef = ArgsDef> = RawArgs &
-  { [K in keyof T]: ParsedArg<T[K]>; } & 
+  { [K in keyof T]: ParsedArg<T[K]>; } &
   { [K in keyof T as T[K] extends { alias: string } ? T[K]["alias"] : never]: ParsedArg<T[K]> } &
   { [K in keyof T as T[K] extends { alias: string[] } ? T[K]["alias"][number] : never]: ParsedArg<T[K]> } &
   Record<string, string | number | boolean | string[]>;
@@ -121,6 +121,7 @@ export type CommandDef<T extends ArgsDef = ArgsDef> = {
   subCommands?: Resolvable<SubCommandsDef>;
   setup?: (context: CommandContext<T>) => any | Promise<any>;
   cleanup?: (context: CommandContext<T>) => any | Promise<any>;
+  onError?: (error: Error, context: CommandContext<T>) => any | Promise<any>;
   run?: (context: CommandContext<T>) => any | Promise<any>;
 };
 

test/error.test.ts

@@ -0,0 +1,30 @@
+import { expect, it, describe } from "vitest";
+import { main } from "../playground/cli";
+import { runCommand } from "../src/command";
+
+describe("error", () => {
+  it("should catch thrown errors with onError", () => {
+    expect(() =>
+      runCommand(main, { rawArgs: ["error-handled"] }),
+    ).not.toThrowError();
+  });
+
+  it("should still receive an error when a string is thrown from the command", () =>
+    expect(
+      runCommand(main, {
+        rawArgs: ["error", "--throwType", "string"],
+      }),
+    ).rejects.toThrowError());
+
+  it("should still receive an error when undefined is thrown from the command", () =>
+    expect(
+      runCommand(main, {
+        rawArgs: ["error", "--throwType", "empty"],
+      }),
+    ).rejects.toThrowError());
+
+  it("should not interfere with default error handling when not present", () =>
+    expect(() =>
+      runCommand(main, { rawArgs: ["error"] }),
+    ).rejects.toBeInstanceOf(Error));
+});