deno_error

Trait and macros to represent Rust errors in JS.

Usage

The JsErrorClass trait is available to be manually implemented, which includes 3 functions: get_class, get_message and get_additional_properties.

It is however advised to not implement this trait manually, but rather go through the JsError derive macro that is exposed, which provides the following functionality:

• Define the class via the #[class()] attribute, that can be defined on either variants of an enum, or the top-level of an enum to define for all variants, where on individual variants overwrite can still be applied. Structs are also supported.

  This attribute accepts 3 possible kinds of value:

  1. GENERIC, TYPE, and a few more that are defined in the builtin_classes module, without the _ERROR suffix.
  2. A text value ie "NotFound". If a text value is passed that is a valid builtin (see the previous point), it will error out as the special identifiers are preferred to avoid mistakes.
  3. inherit: this will inherit the class from whatever field is marked with the #[inherit] attribute. Alternatively, the #[inherit] attribute can be omitted if only one field is present in the enum variant or struct. This value is inferred if the class attribute is missing and only a single field is present on a struct, however for enums this inferring is not done.

• Define additional properties via the #[property] attribute that can be defined on individual fields. The type of the field needs to implement a .to_string() function for it being able to be inherited.

• Inherit class and properties via the #[inherit] attribute which can be specified on fields that contain a value that implements JsErrorClass. This is inferred if only one field is present in the enum variant or struct.

The macro does not provide functionality to related to the get_message function, as one can combine the thiserror well with this macro.

There also is the js_error_wrapper macro which lets you wrap an existing error in a new error that implements the JsErrorClass trait. This macro however does currently not support the special identifiers that the JsError macro supports. Here are two examples on how to use it:

js_error_wrapper!(std::net::AddrParseError, JsAddrParseError, "TypeError");

js_error_wrapper!(std::net::AddrParseError, JsAddrParseError, |err| {
  // match or do some logic to get the error class
});

Additionally, this crate provides some features which related to some commonly used crates in Deno, which implements the JsErrorClass trait on some of their errors.

Versioning Strategy

This crate does not follow semver so make sure to pin it to a patch version. Instead a versioning strategy that optimizes for more efficient maintenance is used:

• Does deno_graph still compile in the Deno repo?
  • If yes, is this a change that would break something at runtime?
    • If yes, it's a minor release.
    • If no, it's a patch release.
  • If no, it's a minor release.

Contributing

We appreciate your help!

To contribute, please read our contributing instructions.