Struct boa_engine::error::JsError

pub struct JsError { /* private fields */ }

The error type returned by all operations related to the execution of Javascript code.

This is essentially an enum that can store either JsNativeErrors (for ideal native errors) or opaque JsValues, since Javascript allows throwing any valid JsValue.

The implementation doesn’t provide a From conversion for JsValue. This is with the intent of encouraging the usage of proper JsNativeErrors instead of plain JsValues. However, if you do need a proper opaque error, you can construct one using the JsError::from_opaque method.

Examples

let cause = JsError::from_opaque(js_string!("error!").into());

assert!(cause.as_opaque().is_some());
assert_eq!(cause.as_opaque().unwrap(), &JsValue::from(js_string!("error!")));

let native_error: JsError = JsNativeError::typ()
    .with_message("invalid type!")
    .with_cause(cause)
    .into();

assert!(native_error.as_native().is_some());

let kind = &native_error.as_native().unwrap().kind;
assert!(matches!(kind, JsNativeErrorKind::Type));

Implementations

impl JsError

pub const fn from_native(err: JsNativeError) -> Self

Creates a new JsError from a native error err.

Examples

let error = JsError::from_native(JsNativeError::syntax());

assert!(error.as_native().is_some());

pub const fn from_opaque(value: JsValue) -> Self

Creates a new JsError from an opaque error value.

Examples

let error = JsError::from_opaque(5.0f64.into());

assert!(error.as_opaque().is_some());

pub fn to_opaque(&self, context: &mut Context) -> JsValue

Converts the error to an opaque JsValue error

Unwraps the inner JsValue if the error is already an opaque error.

Examples

let context = &mut Context::default();
let error: JsError =
    JsNativeError::eval().with_message("invalid script").into();
let error_val = error.to_opaque(context);

assert!(error_val.as_object().unwrap().is::<ErrorObject>());

pub fn try_native( &self, context: &mut Context ) -> Result<JsNativeError, TryNativeError>

Unwraps the inner error if this contains a native error. Otherwise, inspects the opaque error and tries to extract the necessary information to construct a native error similar to the provided opaque error. If the conversion fails, returns a TryNativeError with the cause of the failure.

Note 1

This method won’t try to make any conversions between JS types. In other words, for this conversion to succeed:

• message MUST be a JsString value.
• errors (in the case of AggregateErrors) MUST be an Array object.

Note 2

This operation should be considered a lossy conversion, since it won’t store any additional properties of the opaque error, other than message, cause and errors (in the case of AggregateErrors). If you cannot affort a lossy conversion, clone the object before calling from_opaque to preserve its original properties.

Examples

let context = &mut Context::default();

// create a new, opaque Error object
let error: JsError = JsNativeError::typ().with_message("type error!").into();
let error_val = error.to_opaque(context);

// then, try to recover the original
let error = JsError::from_opaque(error_val).try_native(context).unwrap();

assert!(matches!(error.kind, JsNativeErrorKind::Type));
assert_eq!(error.message(), "type error!");

pub const fn as_opaque(&self) -> Option<&JsValue>

Gets the inner JsValue if the error is an opaque error, or None otherwise.

Examples

let error: JsError = JsNativeError::reference()
    .with_message("variable not found!")
    .into();

assert!(error.as_opaque().is_none());

let error = JsError::from_opaque(256u32.into());

assert!(error.as_opaque().is_some());

pub const fn as_native(&self) -> Option<&JsNativeError>

Gets the inner JsNativeError if the error is a native error, or None otherwise.

Examples

let error: JsError =
    JsNativeError::error().with_message("Unknown error").into();

assert!(error.as_native().is_some());

let error = JsError::from_opaque(JsValue::undefined().into());

assert!(error.as_native().is_none());

pub fn into_erased(self, context: &mut Context) -> JsErasedError

Converts this error into its thread-safe, erased version.

Even though this operation is lossy, converting into a JsErasedError is useful since it implements Send and Sync, making it compatible with error reporting frameworks such as anyhow, eyre or miette.

Examples

let context = &mut Context::default();
let cause = JsError::from_opaque(JsSymbol::new(Some(js_string!("error!"))).unwrap().into());

let native_error: JsError = JsNativeError::typ()
    .with_message("invalid type!")
    .with_cause(cause)
    .into();

let erased_error = native_error.into_erased(context);

assert_eq!(erased_error.to_string(), "TypeError: invalid type!");

let send_sync_error: Box<dyn Error + Send + Sync> = Box::new(erased_error);

assert_eq!(
    send_sync_error.source().unwrap().to_string(),
    "Symbol(error!)"
);

Trait Implementations

impl Clone for JsError

fn clone(&self) -> JsError

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for JsError

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for JsError

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Error for JsError

fn source(&self) -> Option<&(dyn Error + 'static)>

The lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0: use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0: replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type based access to context intended for error reports.

impl Finalize for JsError

fn finalize(&self)

Cleanup logic for a type.

impl From<Error> for JsError

fn from(err: Error) -> Self

Converts to this type from the input type.

impl From<JsNativeError> for JsError

fn from(error: JsNativeError) -> Self

Converts to this type from the input type.

impl PartialEq for JsError

fn eq(&self, other: &JsError) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Trace for JsError

unsafe fn trace(&self, tracer: &mut Tracer)

Marks all contained Gcs.

unsafe fn trace_non_roots(&self)

Trace handles located in GC heap, and mark them as non root.

fn run_finalizer(&self)

Runs Finalize::finalize on this object and all contained subobjects.

impl Eq for JsError

impl StructuralPartialEq for JsError