Error Handling

func separates registration problems, runtime handler errors, and runtime errors that print a default message. Add @CommandError() when you want one place to format runtime failures.

@CommandError() only receives F_RUNTIME and F_RUNTIME_PRINT errors. F_SYSTEM errors are not delivered to user handlers; once a system error happens, the program stops.

import { CommandError, CommandErrorProvider } from 'func'

@CommandError()
export class ErrorHandler {
  constructor(private error: CommandErrorProvider) {
    console.error(error.message)
    error.preventDefaultPrint()
  }
}

Runtime Errors

F_RUNTIME is the main runtime error family. It represents failures that happen while a matched handler is running.

Runtime-print Errors

F_RUNTIME_PRINT is a runtime error family with an extra default behavior: func prints the message to stderr. A CommandErrorProvider can handle the error and call preventDefaultPrint() to block that default print.

import { CommandError, CommandErrorProvider } from 'func'

@CommandError()
export class ErrorHandler {
  constructor(private error: CommandErrorProvider) {
    if (error.level !== 'runtime-print') return

    console.error(`Invalid input: ${error.message}`)
    error.preventDefaultPrint()
  }
}

In this example, your handler prints a custom message and then prevents func from printing the original runtime-print message again.

System Errors

System errors indicate invalid command definitions, duplicate registrations, or injection configuration problems. They happen before user error handlers can safely run, so func throws them immediately and interrupts the program. Fix these during development before publishing your CLI.