Bounce

When using async/await, application errors (expected failures) and system/developer errors (unexpected bugs) are both thrown as exceptions. This makes it easy to accidentally swallow critical developer errors when trying to ignore non-critical application errors.

@hapi/bounce allows you to selectively rethrow system errors while ignoring application errors. This ensures that while a non-critical task (like sending an email) might fail silently for a user, a developer error (like a TypeError due to a bug) will still surface and crash the process or trigger error reporting.

const Bounce = require('@hapi/bounce');

try {
    await email(user);
} catch (err) {
    // Rethrows system errors (bugs) and ignores application errors (expected failures)
    Bounce.rethrow(err, 'system');
}

When using rethrow, ignore, or background, the types parameter determines which errors are caught. You can match errors using several strategies:

1. Predefined Rule Strings:
   • 'system': Matches standard JavaScript and Node.js system errors (e.g., TypeError, RangeError, AssertionError).
   • 'boom': Matches @hapi/boom errors.
2. Constructors:
   • Pass a class/constructor (e.g., TypeError) to match via instanceof.
3. Objects:
   • Pass an object to perform a deep containment check (using @hapi/hoek).
4. Arrays:
   • Pass an array of any of the above to match if the error satisfies any one of the criteria.

The ignore(err, types, [options]) method is the opposite of rethrow(). It ignores any errors matching the specified types. Any error that does not match the criteria is thrown after applying the provided options.

// Example: Ignore only boom errors
Bounce.ignore(err, 'boom');

The background(operation, [action], [types], [options]) method allows you to await a value in the background and automatically apply either a rethrow or ignore strategy to any errors encountered.

Arguments:

• operation: A function, promise, or value to be awaited inside a try...catch.
• action: 'rethrow' or 'ignore'. Defaults to 'rethrow'.
• types: Same as rethrow() or ignore(). Defaults to 'system'.
• options: Same as rethrow() or ignore().

// Example: Run an operation in the background, ignoring application errors but rethrowing system errors
await Bounce.background(email(user), 'ignore', 'system');

Bounce provides utility methods to check the nature of an error:

• isBoom(err): Returns true if err is a boom error.
• isError(err): Returns true if err is an error.
• isSystem(err): Returns true if err is a language-native error or Node assertion. Specifically matches:
  • EvalError
  • RangeError
  • ReferenceError
  • SyntaxError
  • TypeError
  • URIError
  • Node's AssertionError

Use background(operation, action, types, options) to execute an asynchronous operation and handle any resulting errors using Bounce's logic.

Parameters:

• operation (Function | Promise): The async operation to perform.
• action (string): Which Bounce method to call if the operation fails. Defaults to 'rethrow'. Valid values are 'rethrow' or 'ignore'.
• types (string | Array | undefined): The error types to match against. Defaults to 'system'.
• options (Object): Options passed to the chosen action method.

const Bounce = require('@hapi/bounce');

// Run an operation that ignores system errors in the background
await Bounce.background(
    async () => {
        await someAsyncWork();
    },
    'ignore',
    'system'
);

Bounce provides utility methods to inspect error types:

• isBoom(err): Returns true if the error is a @hapi/boom error.
• isError(err): Returns true if the error is an instance of Error.
• isSystem(err): Returns true if the error is a standard JavaScript system error (e.g., TypeError, ReferenceError, SyntaxError) or a Node.js Assert.AssertionError. It returns false if the error is a Boom error or if no error is provided.