Module napi::threadsafe_function::ErrorStrategy

Expand description

Type-level enum to express how to feed ThreadsafeFunction errors to the inner [JsFunction].

Context

For callbacks that expect a Result-like kind of input, the convention is to have the callback take an error parameter as its first parameter.

This way receiving a Result<Args…> can be modelled as follows:

In case of Err(error), feed that error entity as the first parameter of the callback;
Otherwise (in case of Ok(_)), feed null instead.

In pseudo-code:

match result_args {
    Ok(args) => {
        let js_null = /* … */;
        callback.call(
            // this
            None,
            // args…
            &iter::once(js_null).chain(args).collect::<Vec<_>>(),
        )
    },
    Err(err) => callback.call(None, &[JsError::from(err)]),
}

Note that the Err case can stem from a failed conversion from native values to js values when calling the callback!

That’s why:

This is the default error strategy.

In order to opt-out of it, ThreadsafeFunction has an optional second generic parameter (of “kind” ErrorStrategy::T) that defines whether this behavior (ErrorStrategy::CalleeHandled) or a non-Result one (ErrorStrategy::Fatal) is desired.

Type-level `enum`

Until const_generics can handle custom enums, this pattern must be implemented at the type level.

We thus end up with:

#[type_level_enum]
enum ErrorStrategy {
    CalleeHandled,
    Fatal,
}

With ErrorStrategy::T being the type-level “enum type”:

<Param: ErrorStrategy::T>

Re-exports

pub use ErrorStrategy as T;

Enums

CalleeHandled

Input errors (including conversion errors) are left for the callee to handle:

Fatal

Input errors (including conversion errors) are deemed fatal:

Traits

ErrorStrategy