napi 3.8.5

N-API bindings
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157

use std::ptr;

use super::Value;
#[cfg(feature = "napi4")]
use crate::{
  bindgen_runtime::JsValuesTupleIntoVec,
  threadsafe_function::{ThreadsafeCallContext, ThreadsafeFunction},
};
use crate::{
  bindgen_runtime::{FromNapiValue, ToNapiValue, TypeName, ValidateNapiValue},
  check_pending_exception, sys, Error, JsObject, JsString, NapiRaw, NapiValue, Result, Status,
  Unknown, ValueType,
};

#[deprecated(since = "2.17.0", note = "Please use `Function` instead")]
pub struct JsFunction(pub(crate) Value);

impl ValidateNapiValue for JsFunction {}

impl TypeName for JsFunction {
  fn type_name() -> &'static str {
    "Function"
  }

  fn value_type() -> crate::ValueType {
    ValueType::Function
  }
}

/// See [Working with JavaScript Functions](https://nodejs.org/api/n-api.html#n_api_working_with_javascript_functions).
///
/// Example:
/// ```
/// use napi::{JsFunction, CallContext, JsNull, Result};
///
/// #[js_function(1)]
/// pub fn call_function(ctx: CallContext) -> Result<JsNull> {
///     let js_func = ctx.get::<JsFunction>(0)?;
///     let js_string = ctx.env.create_string("hello".as_ref())?.into_unknown()?;
///     js_func.call(None, &[js_string])?;
///     Ok(ctx.env.get_null()?)
/// }
/// ```
impl JsFunction {
  /// [napi_call_function](https://nodejs.org/api/n-api.html#n_api_napi_call_function)
  pub fn call<V>(&self, this: Option<&JsObject>, args: &[V]) -> Result<Unknown<'_>>
  where
    V: NapiRaw,
  {
    let raw_this = this
      .map(|v| unsafe { v.raw() })
      .or_else(|| unsafe { ToNapiValue::to_napi_value(self.0.env, ()) }.ok())
      .ok_or_else(|| Error::new(Status::GenericFailure, "Get raw this failed".to_owned()))?;
    let raw_args = args
      .iter()
      .map(|arg| unsafe { arg.raw() })
      .collect::<Vec<sys::napi_value>>();
    let mut return_value = ptr::null_mut();
    check_pending_exception!(self.0.env, unsafe {
      sys::napi_call_function(
        self.0.env,
        raw_this,
        self.0.value,
        args.len(),
        raw_args.as_ptr(),
        &mut return_value,
      )
    })?;

    Ok(unsafe { Unknown::from_raw_unchecked(self.0.env, return_value) })
  }

  /// [napi_call_function](https://nodejs.org/api/n-api.html#n_api_napi_call_function)
  /// The same with `call`, but without arguments
  pub fn call_without_args(&self, this: Option<&JsObject>) -> Result<Unknown<'_>> {
    let raw_this = this
      .map(|v| unsafe { v.raw() })
      .or_else(|| unsafe { ToNapiValue::to_napi_value(self.0.env, ()) }.ok())
      .ok_or_else(|| Error::new(Status::GenericFailure, "Get raw this failed".to_owned()))?;
    let mut return_value = ptr::null_mut();
    check_pending_exception!(self.0.env, unsafe {
      sys::napi_call_function(
        self.0.env,
        raw_this,
        self.0.value,
        0,
        ptr::null_mut(),
        &mut return_value,
      )
    })?;

    Ok(unsafe { Unknown::from_raw_unchecked(self.0.env, return_value) })
  }

  /// <https://nodejs.org/api/n-api.html#n_api_napi_new_instance>
  ///
  /// This method is used to instantiate a new `JavaScript` value using a given `JsFunction` that represents the constructor for the object.
  pub fn new_instance<V>(&self, args: &[V]) -> Result<JsObject>
  where
    V: NapiRaw,
  {
    let mut js_instance = ptr::null_mut();
    let length = args.len();
    let raw_args = args
      .iter()
      .map(|arg| unsafe { arg.raw() })
      .collect::<Vec<sys::napi_value>>();
    check_pending_exception!(self.0.env, unsafe {
      sys::napi_new_instance(
        self.0.env,
        self.0.value,
        length,
        raw_args.as_ptr(),
        &mut js_instance,
      )
    })?;
    Ok(unsafe { JsObject::from_raw_unchecked(self.0.env, js_instance) })
  }

  /// function name
  pub fn name(&self) -> Result<String> {
    let mut name = ptr::null_mut();
    check_pending_exception!(self.0.env, unsafe {
      sys::napi_get_named_property(self.0.env, self.0.value, c"name".as_ptr().cast(), &mut name)
    })?;
    let name_value = unsafe { JsString::from_napi_value(self.0.env, name) }?;
    Ok(name_value.into_utf8()?.as_str()?.to_owned())
  }

  #[cfg(feature = "napi4")]
  pub fn create_threadsafe_function<
    T,
    NewArgs,
    Return,
    ErrorStatus,
    F,
    const ES: bool,
    const Weak: bool,
    const MaxQueueSize: usize,
  >(
    &self,
    callback: F,
  ) -> Result<ThreadsafeFunction<T, Return, NewArgs, ErrorStatus, ES, Weak, MaxQueueSize>>
  where
    T: 'static,
    NewArgs: 'static + JsValuesTupleIntoVec,
    Return: crate::bindgen_runtime::FromNapiValue,
    F: 'static + Send + FnMut(ThreadsafeCallContext<T>) -> Result<NewArgs>,
    ErrorStatus: AsRef<str> + From<Status>,
  {
    ThreadsafeFunction::<T, Return, NewArgs, ErrorStatus, ES, Weak, MaxQueueSize>::create(
      self.0.env,
      self.0.value,
      callback,
    )
  }
}