feat: add .catch to command declaration

package.json

@@ -24,6 +24,7 @@
  "dev": "vitest dev",
  "lint": "eslint --cache --ext .ts,.js,.mjs,.cjs . && prettier -c src test",
  "lint:fix": "eslint --cache --ext .ts,.js,.mjs,.cjs . --fix && prettier -c src test -w",
+ "format": "prettier -c src test -w",
  "prepack": "pnpm run build",
  "play": "jiti ./playground/cli.ts",
  "release": "pnpm test && changelogen --release --push && npm publish",

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",
@@ -15,8 +15,13 @@ const main = defineCommand({
  subCommands: {
  build: () => import("./commands/build").then((r) => r.default),
  deploy: () => import("./commands/deploy").then((r) => r.default),
+ error: () => import("./commands/error").then((r) => r.default),
+ "error-no-catch": () =>
+ import("./commands/error-no-catch").then((r) => r.default),
  debug: () => import("./commands/debug").then((r) => r.default),
  },
 });
 
-runMain(main);
+if (process.env.NODE_ENV !== "test") {
+ runMain(main);
+}

playground/commands/error-no-catch.ts

@@ -0,0 +1,36 @@
+import { defineCommand } from "../../src";
+
+export default defineCommand({
+ meta: {
+ name: "error-no-catch",
+ description:
+ "Throws an error to test .catch functionality, does not have error handling",
+ },
+
+ args: {
+ throwType: {
+ type: "string",
+ },
+ },
+
+ run({ args }) {
+ switch (args.throwType) {
+ case "string": {
+ console.log("Throw string");
+ // we intentionally are throwing something invalid for testing purposes
+ // eslint-disable-next-line no-throw-literal
+ throw "Not an error!";
+ }
+ case "empty": {
+ console.log("Throw undefined");
+ // we intentionally are throwing something invalid for testing purposes
+ // eslint-disable-next-line no-throw-literal
+ throw undefined;
+ }
+ default: {
+ console.log("Throw Error");
+ throw new Error("Error!");
+ }
+ }
+ },
+});

playground/commands/error.ts

@@ -0,0 +1,19 @@
+import consola from "consola";
+import { defineCommand } from "../../src";
+
+export default defineCommand({
+ meta: {
+ name: "error",
+ description: "Throws an error to test .catch functionality",
+ },
+
+ run() {
+ throw new Error("Hello World");
+ },
+ catch(_, e) {
+ consola.error(`Caught error: ${e}`);
+ if (!(e instanceof Error)) {
+ throw new TypeError("Recieved non-error value");
+ }
+ },
+});

src/command.ts

@@ -64,6 +64,17 @@ export async function runCommand<T extends ArgsDef = ArgsDef>(
  if (typeof cmd.run === "function") {
  result = await cmd.run(context);
  }
+ } catch (error_) {
+ const error =
+ error_ instanceof Error
+ ? error_
+ : new Error(error_?.toString() ?? "Unknown Error", { cause: error_ });
+ if (typeof cmd.catch === "function") {
+ // Attempt to coerce e into an error to ensure type safety
+ await cmd.catch(context, error);
+ } else {
+ throw error;
+ }
  } finally {
  if (typeof cmd.cleanup === "function") {
  await cmd.cleanup(context);

src/main.ts

@@ -38,7 +38,9 @@ export async function runMain<T extends ArgsDef = ArgsDef>(
  await showUsage(...(await resolveSubCommand(cmd, rawArgs)));
  }
  consola.error(error.message);
- process.exit(1);
+ if (process.env.NODE_ENV !== "test") {
+ process.exit(1);
+ }
  }
 }
 

src/types.ts

@@ -93,6 +93,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>;
+ catch?: (context: CommandContext<T>, e: Error) => any | Promise<any>;
  run?: (context: CommandContext<T>) => any | Promise<any>;
 };
 

test/error.test.ts

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