feat: add error handling

Author: chenasraf

README.md

@@ -34,6 +34,7 @@ And it should look good too, right?
 - Required options
 - Options with multiple values
 - Nameless options
+- Built-in error handling with customizable handlers
 - Automatically generated help text:
   - Customizable colors
   - Customizable header and footer text
@@ -143,6 +144,38 @@ const parser = massarg({
   })
 ```
 
+### Error Handling
+
+By default, massarg catches all errors and displays a friendly error message in red to stderr,
+then exits with code 1. You can customize this behavior with the `.onError()` method:
+
+```ts
+massarg({
+  name: 'my-cli',
+  description: 'My CLI application',
+})
+  .option({
+    name: 'config',
+    description: 'Config file path',
+    aliases: ['c'],
+    required: true,
+  })
+  // Custom error handler
+  .onError((error) => {
+    console.error(`Error: ${error.message}`)
+    // Log to external service, show custom UI, etc.
+  })
+  .parse()
+```
+
+**Error handling features:**
+
+- **Default handler**: Logs error message in red to stderr
+- **Custom handler**: Use `.onError(callback)` to override the default behavior
+- **Automatic exit**: Process exits with code 1 after any error (regardless of handler)
+- **Process-level handling**: Handlers also catch `uncaughtException` and `unhandledRejection`
+- **Handler inheritance**: Error handlers propagate from parent commands to subcommands
+
 ## Documentation
 
 The full documentation can be found here:

src/command.ts

@@ -48,6 +48,12 @@ export type Runner<Args extends ArgsObject> = (
   instance: MassargCommand<Args>,
 ) => Promise<void> | void
 
+/**
+ * Error handler callback type.
+ * Called when an error occurs during parsing or command execution.
+ */
+export type ErrorHandler = (error: Error) => void
+
 /**
  * A command is a named function that can be invoked with a set of options.
  *
@@ -79,6 +85,7 @@ export class MassargCommand<Args extends ArgsObject = ArgsObject>
   examples: MassargExample[] = []
   args: Partial<Args> = {}
   private _helpConfig: HelpConfig
+  private _errorHandler?: ErrorHandler
   parent?: MassargCommand<any>
   optionPrefix = DEFAULT_OPT_FULL_PREFIX
   aliasPrefix = DEFAULT_OPT_SHORT_PREFIX
@@ -321,6 +328,46 @@ export class MassargCommand<Args extends ArgsObject = ArgsObject>
     return this
   }
 
+  /**
+   * Configure a custom error handler for this command.
+   *
+   * By default, errors are caught and logged to stderr with a red color.
+   * Use this method to override the default error handling behavior.
+   *
+   * Note: The process will always exit with code 1 after an error, regardless of the handler.
+   *
+   * @example
+   * ```ts
+   * massarg(options)
+   *   .onError((error) => {
+   *     console.error('Custom error:', error.message)
+   *     // Log to external service, show custom UI, etc.
+   *   })
+   *   .parse()
+   * ```
+   */
+  onError(handler: ErrorHandler): MassargCommand<Args> {
+    this._errorHandler = handler
+    return this
+  }
+
+  /** Get the error handler, checking parent chain if not set locally */
+  private get errorHandler(): ErrorHandler {
+    if (this._errorHandler) {
+      return this._errorHandler
+    }
+    if (this.parent) {
+      return this.parent.errorHandler
+    }
+    return this.defaultErrorHandler
+  }
+
+  /** Default error handler that logs red error message to stderr */
+  private defaultErrorHandler = (e: Error): void => {
+    const message = getErrorMessage(e)
+    console.error(format(message, { color: 'red' }))
+  }
+
   /**
    * Parse the given arguments and run the command or sub-commands along with the given options
    * and flags.
@@ -333,13 +380,30 @@ export class MassargCommand<Args extends ArgsObject = ArgsObject>
     args?: Partial<Args>,
     parent?: MassargCommand<Args>,
   ): Promise<void> | void {
+    // Set up process-level error handlers
+    const handleProcessError = (error: Error) => {
+      this.handleError(error)
+    }
+    process.on('uncaughtException', handleProcessError)
+    process.on('unhandledRejection', (reason) => {
+      const error = reason instanceof Error ? reason : new Error(String(reason))
+      handleProcessError(error)
+    })
+
     try {
       this.getArgs(argv, args, parent, true)
     } catch (e) {
-      this.printError(e)
+      this.handleError(e)
     }
   }
 
+  /** Handle an error using the configured error handler, then exit */
+  private handleError(e: unknown): void {
+    const error = e instanceof Error ? e : new Error(getErrorMessage(e))
+    this.errorHandler(error)
+    process.exit(1)
+  }
+
   private printError(e: unknown) {
     const message = getErrorMessage(e)
     console.error(format(message, { color: 'red' }))

src/massarg.ts

@@ -1,4 +1,6 @@
-import { ArgsObject, CommandConfig, MassargCommand } from './command'
+import { ArgsObject, CommandConfig, ErrorHandler, MassargCommand } from './command'
+
+export type { ErrorHandler }
 
 /** A minimal command config that can be used to create a top-level command. */
 export type MinimalCommandConfig<Args extends ArgsObject = ArgsObject> = Omit<

test/command.test.ts

@@ -210,3 +210,102 @@ describe('main', () => {
     expect(command.main(fn)).toBeInstanceOf(MassargCommand)
   })
 })
+
+describe('onError', () => {
+  let mockExit: jest.SpyInstance
+  let mockConsoleError: jest.SpyInstance
+
+  beforeEach(() => {
+    mockExit = jest.spyOn(process, 'exit').mockImplementation(() => undefined as never)
+    mockConsoleError = jest.spyOn(console, 'error').mockImplementation(() => {})
+  })
+
+  afterEach(() => {
+    mockExit.mockRestore()
+    mockConsoleError.mockRestore()
+  })
+
+  test('add handler', () => {
+    const handler = jest.fn()
+    const command = massarg(opts)
+    expect(command.onError).toBeInstanceOf(Function)
+    expect(command.onError(handler)).toBeInstanceOf(MassargCommand)
+  })
+
+  test('default error handler logs to stderr', () => {
+    const command = massarg(opts).option({
+      name: 'required-opt',
+      description: 'required option',
+      aliases: [],
+      required: true,
+    })
+    command.parse([])
+
+    expect(mockConsoleError).toHaveBeenCalled()
+    expect(mockExit).toHaveBeenCalledWith(1)
+  })
+
+  test('custom error handler is called', () => {
+    const handler = jest.fn()
+    const command = massarg(opts)
+      .onError(handler)
+      .option({
+        name: 'required-opt',
+        description: 'required option',
+        aliases: [],
+        required: true,
+      })
+    command.parse([])
+
+    expect(handler).toHaveBeenCalled()
+    expect(handler.mock.calls[0][0]).toBeInstanceOf(Error)
+    expect(mockExit).toHaveBeenCalledWith(1)
+  })
+
+  test('custom error handler overrides default', () => {
+    const handler = jest.fn()
+    const command = massarg(opts)
+      .onError(handler)
+      .option({
+        name: 'required-opt',
+        description: 'required option',
+        aliases: [],
+        required: true,
+      })
+    command.parse([])
+
+    expect(handler).toHaveBeenCalled()
+    expect(mockConsoleError).not.toHaveBeenCalled()
+  })
+
+  test('error handler catches errors from run function', () => {
+    const handler = jest.fn()
+    const command = massarg(opts)
+      .onError(handler)
+      .main(() => {
+        throw new Error('main error')
+      })
+    command.parse([])
+
+    expect(handler).toHaveBeenCalled()
+    expect(handler.mock.calls[0][0].message).toBe('main error')
+    expect(mockExit).toHaveBeenCalledWith(1)
+  })
+
+  test('error handler propagates to subcommands', () => {
+    const handler = jest.fn()
+    const command = massarg(opts)
+      .onError(handler)
+      .command({
+        name: 'sub',
+        description: 'sub command',
+        run: () => {
+          throw new Error('sub error')
+        },
+      })
+    command.parse(['sub'])
+
+    expect(handler).toHaveBeenCalled()
+    expect(handler.mock.calls[0][0].message).toBe('sub error')
+  })
+})