env.rs source code [crates/napi-2.16.0/src/env.rs]

1	use std::any::{type_name, TypeId};
2	use std::convert::TryInto;
3	use std::ffi::CString;
4	#[cfg(all(feature = "tokio_rt", feature = "napi4"))]
5	use std::future::Future;
6	use std::mem;
7	use std::os::raw::{c_char, c_void};
8	use std::ptr;
9
10	use crate::bindgen_runtime::FromNapiValue;
11	#[cfg(feature = "napi4")]
12	use crate::bindgen_runtime::ToNapiValue;
13	use crate::{
14	async_work::{self, AsyncWorkPromise},
15	check_status,
16	js_values::*,
17	sys,
18	task::Task,
19	Error, ExtendedErrorInfo, NodeVersion, Result, Status, ValueType,
20	};
21
22	#[cfg(feature = "napi8")]
23	use crate::async_cleanup_hook::AsyncCleanupHook;
24	#[cfg(feature = "napi3")]
25	use crate::cleanup_env::{CleanupEnvHook, CleanupEnvHookData};
26	#[cfg(feature = "serde-json")]
27	use crate::js_values::{De, Ser};
28	#[cfg(feature = "napi4")]
29	use crate::threadsafe_function::{ThreadSafeCallContext, ThreadsafeFunction};
30	#[cfg(feature = "napi3")]
31	use crate::JsError;
32	#[cfg(feature = "serde-json")]
33	use serde::de::DeserializeOwned;
34	#[cfg(feature = "serde-json")]
35	use serde::Serialize;
36
37	pub type Callback = unsafe extern "C" fn(sys::napi_env, sys::napi_callback_info) -> sys::napi_value;
38
39	pub(crate) static EMPTY_VEC: Vec<u8> = vec![];
40
41	#[derive(Clone, Copy)]
42	/// `Env` is used to represent a context that the underlying N-API implementation can use to persist VM-specific state.
43	///
44	/// Specifically, the same `Env` that was passed in when the initial native function was called must be passed to any subsequent nested N-API calls.
45	///
46	/// Caching the `Env` for the purpose of general reuse, and passing the `Env` between instances of the same addon running on different Worker threads is not allowed.
47	///
48	/// The `Env` becomes invalid when an instance of a native addon is unloaded.
49	///
50	/// Notification of this event is delivered through the callbacks given to `Env::add_env_cleanup_hook` and `Env::set_instance_data`.
51	pub struct Env(pub(crate) sys::napi_env);
52
53	impl From<sys::napi_env> for Env {
54	fn from(env: sys::napi_env) -> Self {
55	Env(env)
56	}
57	}
58
59	impl Env {
60	#[allow(clippy::missing_safety_doc)]
61	pub unsafe fn from_raw(env: sys::napi_env) -> Self {
62	Env(env)
63	}
64
65	pub fn get_boolean(&self, value: bool) -> Result<JsBoolean> {
66	let mut raw_value = ptr::null_mut();
67	check_status!(unsafe { sys::napi_get_boolean(self.0, value, &mut raw_value) })?;
68	Ok(unsafe { JsBoolean::from_raw_unchecked(self.0, raw_value) })
69	}
70
71	pub fn create_int32(&self, int: i32) -> Result<JsNumber> {
72	let mut raw_value = ptr::null_mut();
73	check_status!(unsafe {
74	sys::napi_create_int32(self.0, int, (&mut raw_value) as *mut sys::napi_value)
75	})?;
76	Ok(unsafe { JsNumber::from_raw_unchecked(self.0, raw_value) })
77	}
78
79	pub fn create_int64(&self, int: i64) -> Result<JsNumber> {
80	let mut raw_value = ptr::null_mut();
81	check_status!(unsafe {
82	sys::napi_create_int64(self.0, int, (&mut raw_value) as *mut sys::napi_value)
83	})?;
84	Ok(unsafe { JsNumber::from_raw_unchecked(self.0, raw_value) })
85	}
86
87	pub fn create_uint32(&self, number: u32) -> Result<JsNumber> {
88	let mut raw_value = ptr::null_mut();
89	check_status!(unsafe { sys::napi_create_uint32(self.0, number, &mut raw_value) })?;
90	Ok(unsafe { JsNumber::from_raw_unchecked(self.0, raw_value) })
91	}
92
93	pub fn create_double(&self, double: f64) -> Result<JsNumber> {
94	let mut raw_value = ptr::null_mut();
95	check_status!(unsafe {
96	sys::napi_create_double(self.0, double, (&mut raw_value) as *mut sys::napi_value)
97	})?;
98	Ok(unsafe { JsNumber::from_raw_unchecked(self.0, raw_value) })
99	}
100
101	/// [n_api_napi_create_bigint_int64](https://nodejs.org/api/n-api.html#n_api_napi_create_bigint_int64)
102	#[cfg(feature = "napi6")]
103	pub fn create_bigint_from_i64(&self, value: i64) -> Result<JsBigInt> {
104	let mut raw_value = ptr::null_mut();
105	check_status!(unsafe { sys::napi_create_bigint_int64(self.0, value, &mut raw_value) })?;
106	Ok(JsBigInt::from_raw_unchecked(self.0, raw_value, `1`))
107	}
108
109	#[cfg(feature = "napi6")]
110	pub fn create_bigint_from_u64(&self, value: u64) -> Result<JsBigInt> {
111	let mut raw_value = ptr::null_mut();
112	check_status!(unsafe { sys::napi_create_bigint_uint64(self.0, value, &mut raw_value) })?;
113	Ok(JsBigInt::from_raw_unchecked(self.0, raw_value, `1`))
114	}
115
116	#[cfg(feature = "napi6")]
117	pub fn create_bigint_from_i128(&self, value: i128) -> Result<JsBigInt> {
118	let mut raw_value = ptr::null_mut();
119	let sign_bit = i32::from(value <= `0`);
120	let words = &value as *const i128 as *const u64;
121	check_status!(unsafe {
122	sys::napi_create_bigint_words(self.0, sign_bit, `2`, words, &mut raw_value)
123	})?;
124	Ok(JsBigInt::from_raw_unchecked(self.0, raw_value, `1`))
125	}
126
127	#[cfg(feature = "napi6")]
128	pub fn create_bigint_from_u128(&self, value: u128) -> Result<JsBigInt> {
129	let mut raw_value = ptr::null_mut();
130	let words = &value as *const u128 as *const u64;
131	check_status!(unsafe { sys::napi_create_bigint_words(self.0, `0`, `2`, words, &mut raw_value) })?;
132	Ok(JsBigInt::from_raw_unchecked(self.0, raw_value, `1`))
133	}
134
135	/// [n_api_napi_create_bigint_words](https://nodejs.org/api/n-api.html#n_api_napi_create_bigint_words)
136	///
137	/// The resulting BigInt will be negative when sign_bit is true.
138	#[cfg(feature = "napi6")]
139	pub fn create_bigint_from_words(&self, sign_bit: bool, words: Vec<u64>) -> Result<JsBigInt> {
140	let mut raw_value = ptr::null_mut();
141	let len = words.len();
142	check_status!(unsafe {
143	sys::napi_create_bigint_words(
144	self.0,
145	match sign_bit {
146	`true` => `1`,
147	`false` => `0`,
148	},
149	len,
150	words.as_ptr(),
151	&mut raw_value,
152	)
153	})?;
154	Ok(JsBigInt::from_raw_unchecked(self.0, raw_value, len))
155	}
156
157	pub fn create_string(&self, s: &str) -> Result<JsString> {
158	unsafe { self.create_string_from_c_char(s.as_ptr().cast(), s.len()) }
159	}
160
161	pub fn create_string_from_std(&self, s: String) -> Result<JsString> {
162	unsafe { self.create_string_from_c_char(s.as_ptr().cast(), s.len()) }
163	}
164
165	/// This API is used for C ffi scenario.
166	/// Convert raw const c_char into JsString*
167	///
168	/// # Safety
169	///
170	/// Create JsString from known valid utf-8 string
171	pub unsafe fn create_string_from_c_char(
172	&self,
173	data_ptr: *const c_char,
174	len: usize,
175	) -> Result<JsString> {
176	let mut raw_value = ptr::null_mut();
177	check_status!(unsafe { sys::napi_create_string_utf8(self.0, data_ptr, len, &mut raw_value) })?;
178	Ok(unsafe { JsString::from_raw_unchecked(self.0, raw_value) })
179	}
180
181	pub fn create_string_utf16(&self, chars: &[u16]) -> Result<JsString> {
182	let mut raw_value = ptr::null_mut();
183	check_status!(unsafe {
184	sys::napi_create_string_utf16(self.0, chars.as_ptr(), chars.len(), &mut raw_value)
185	})?;
186	Ok(unsafe { JsString::from_raw_unchecked(self.0, raw_value) })
187	}
188
189	pub fn create_string_latin1(&self, chars: &[u8]) -> Result<JsString> {
190	let mut raw_value = ptr::null_mut();
191	check_status!(unsafe {
192	sys::napi_create_string_latin1(
193	self.0,
194	chars.as_ptr() as *const _,
195	chars.len(),
196	&mut raw_value,
197	)
198	})?;
199	Ok(unsafe { JsString::from_raw_unchecked(self.0, raw_value) })
200	}
201
202	pub fn create_symbol_from_js_string(&self, description: JsString) -> Result<JsSymbol> {
203	let mut result = ptr::null_mut();
204	check_status!(unsafe { sys::napi_create_symbol(self.0, description.0.value, &mut result) })?;
205	Ok(unsafe { JsSymbol::from_raw_unchecked(self.0, result) })
206	}
207
208	pub fn create_symbol(&self, description: Option<&str>) -> Result<JsSymbol> {
209	let mut result = ptr::null_mut();
210	check_status!(unsafe {
211	sys::napi_create_symbol(
212	self.0,
213	description
214	.and_then(\|desc\| self.create_string(desc).ok())
215	.map(\|string\| string.0.value)
216	.unwrap_or(ptr::null_mut()),
217	&mut result,
218	)
219	})?;
220	Ok(unsafe { JsSymbol::from_raw_unchecked(self.0, result) })
221	}
222
223	pub fn create_object(&self) -> Result<JsObject> {
224	let mut raw_value = ptr::null_mut();
225	check_status!(unsafe { sys::napi_create_object(self.0, &mut raw_value) })?;
226	Ok(unsafe { JsObject::from_raw_unchecked(self.0, raw_value) })
227	}
228
229	pub fn create_empty_array(&self) -> Result<JsObject> {
230	let mut raw_value = ptr::null_mut();
231	check_status!(unsafe { sys::napi_create_array(self.0, &mut raw_value) })?;
232	Ok(unsafe { JsObject::from_raw_unchecked(self.0, raw_value) })
233	}
234
235	pub fn create_array_with_length(&self, length: usize) -> Result<JsObject> {
236	let mut raw_value = ptr::null_mut();
237	check_status!(unsafe { sys::napi_create_array_with_length(self.0, length, &mut raw_value) })?;
238	Ok(unsafe { JsObject::from_raw_unchecked(self.0, raw_value) })
239	}
240
241	/// This API allocates a node::Buffer object. While this is still a fully-supported data structure, in most cases using a TypedArray will suffice.
242	pub fn create_buffer(&self, length: usize) -> Result<JsBufferValue> {
243	let mut raw_value = ptr::null_mut();
244	let mut data_ptr = ptr::null_mut();
245	check_status!(unsafe {
246	sys::napi_create_buffer(self.0, length, &mut data_ptr, &mut raw_value)
247	})?;
248
249	Ok(JsBufferValue::new(
250	JsBuffer(Value {
251	env: self.0,
252	value: raw_value,
253	value_type: ValueType::Object,
254	}),
255	mem::ManuallyDrop::new(unsafe { Vec::from_raw_parts(data_ptr as *mut _, length, length) }),
256	))
257	}
258
259	/// This API allocates a node::Buffer object and initializes it with data backed by the passed in buffer.
260	///
261	/// While this is still a fully-supported data structure, in most cases using a TypedArray will suffice.
262	pub fn create_buffer_with_data(&self, mut data: Vec<u8>) -> Result<JsBufferValue> {
263	let length = data.len();
264	let mut raw_value = ptr::null_mut();
265	let data_ptr = data.as_mut_ptr();
266	let hint_ptr = Box::into_raw(Box::new((length, data.capacity())));
267	check_status!(unsafe {
268	if length == `0` {
269	// Rust uses 0x1 as the data pointer for empty buffers,
270	// but NAPI/V8 only allows multiple buffers to have
271	// the same data pointer if it's 0x0.
272	sys::napi_create_buffer(self.0, length, ptr::null_mut(), &mut raw_value)
273	} else {
274	let status = sys::napi_create_external_buffer(
275	self.0,
276	length,
277	data_ptr.cast(),
278	Some(drop_buffer),
279	hint_ptr.cast(),
280	&mut raw_value,
281	);
282	// electron doesn't support external buffers
283	if status == sys::Status::napi_no_external_buffers_allowed {
284	drop(Box::from_raw(hint_ptr));
285	let mut dest_data_ptr = ptr::null_mut();
286	let status = sys::napi_create_buffer_copy(
287	self.0,
288	length,
289	data.as_ptr().cast(),
290	&mut dest_data_ptr,
291	&mut raw_value,
292	);
293	data = Vec::from_raw_parts(dest_data_ptr.cast(), length, length);
294	status
295	} else {
296	status
297	}
298	}
299	})?;
300	Ok(JsBufferValue::new(
301	JsBuffer(Value {
302	env: self.0,
303	value: raw_value,
304	value_type: ValueType::Object,
305	}),
306	mem::ManuallyDrop::new(data),
307	))
308	}
309
310	/// # Safety
311	/// Mostly the same with `create_buffer_with_data`
312	///
313	/// Provided `finalize_callback` will be called when `Buffer` got dropped.
314	///
315	/// You can pass in `noop_finalize` if you have nothing to do in finalize phase.
316	///
317	/// # Notes
318	///
319	/// JavaScript may mutate the data passed in to this buffer when writing the buffer.
320	/// However, some JavaScript runtimes do not support external buffers (notably electron!)
321	/// in which case modifications may be lost.
322	///
323	/// If you need to support these runtimes, you should create a buffer by other means and then
324	/// later copy the data back out.
325	pub unsafe fn create_buffer_with_borrowed_data<Hint, Finalize>(
326	&self,
327	mut data: *mut u8,
328	length: usize,
329	hint: Hint,
330	finalize_callback: Finalize,
331	) -> Result<JsBufferValue>
332	where
333	Finalize: FnOnce(Hint, Env),
334	{
335	let mut raw_value = ptr::null_mut();
336	if data.is_null() \|\| data as *const u8 == EMPTY_VEC.as_ptr() {
337	return Err(Error::new(
338	Status::InvalidArg,
339	"Borrowed data should not be null".to_owned(),
340	));
341	}
342	let hint_ptr = Box::into_raw(Box::new((hint, finalize_callback)));
343	unsafe {
344	let status = sys::napi_create_external_buffer(
345	self.0,
346	length,
347	data as *mut c_void,
348	Some(
349	raw_finalize_with_custom_callback::<Hint, Finalize>
350	as unsafe extern "C" fn(
351	env: sys::napi_env,
352	finalize_data: *mut c_void,
353	finalize_hint: *mut c_void,
354	),
355	),
356	hint_ptr.cast(),
357	&mut raw_value,
358	);
359	if status == sys::Status::napi_no_external_buffers_allowed {
360	let (hint, finalize) = *Box::from_raw(hint_ptr);
361	let mut result_data = ptr::null_mut();
362	let status = sys::napi_create_buffer_copy(
363	self.0,
364	length,
365	data.cast(),
366	&mut result_data,
367	&mut raw_value,
368	);
369	data = result_data.cast();
370	finalize(hint, *self);
371	check_status!(status)?;
372	} else {
373	check_status!(status)?;
374	}
375	};
376	Ok(JsBufferValue::new(
377	JsBuffer(Value {
378	env: self.0,
379	value: raw_value,
380	value_type: ValueType::Object,
381	}),
382	mem::ManuallyDrop::new(unsafe { Vec::from_raw_parts(data, length, length) }),
383	))
384	}
385
386	#[cfg(not(target_family = "wasm"))]
387	/// This function gives V8 an indication of the amount of externally allocated memory that is kept alive by JavaScript objects (i.e. a JavaScript object that points to its own memory allocated by a native module).
388	///
389	/// Registering externally allocated memory will trigger global garbage collections more often than it would otherwise.
390	///
391	/// ATTENTION ⚠️, do not use this with `create_buffer_with_data/create_arraybuffer_with_data`, since these two functions already called the `adjust_external_memory` internal.
392	pub fn adjust_external_memory(&mut self, size: i64) -> Result<i64> {
393	let mut changed = `0i64`;
394	check_status!(unsafe { sys::napi_adjust_external_memory(self.0, size, &mut changed) })?;
395	Ok(changed)
396	}
397
398	#[cfg(target_family = "wasm")]
399	#[allow(unused_variables)]
400	pub fn adjust_external_memory(&mut self, size: i64) -> Result<i64> {
401	Ok(`0`)
402	}
403
404	/// This API allocates a node::Buffer object and initializes it with data copied from the passed-in buffer.
405	///
406	/// While this is still a fully-supported data structure, in most cases using a TypedArray will suffice.
407	pub fn create_buffer_copy<D>(&self, data_to_copy: D) -> Result<JsBufferValue>
408	where
409	D: AsRef<[u8]>,
410	{
411	let length = data_to_copy.as_ref().len();
412	let data_ptr = data_to_copy.as_ref().as_ptr();
413	let mut copy_data = ptr::null_mut();
414	let mut raw_value = ptr::null_mut();
415	check_status!(unsafe {
416	sys::napi_create_buffer_copy(
417	self.0,
418	length,
419	data_ptr as *mut c_void,
420	&mut copy_data,
421	&mut raw_value,
422	)
423	})?;
424	Ok(JsBufferValue::new(
425	JsBuffer(Value {
426	env: self.0,
427	value: raw_value,
428	value_type: ValueType::Object,
429	}),
430	mem::ManuallyDrop::new(unsafe { Vec::from_raw_parts(copy_data as *mut u8, length, length) }),
431	))
432	}
433
434	pub fn create_arraybuffer(&self, length: usize) -> Result<JsArrayBufferValue> {
435	let mut raw_value = ptr::null_mut();
436	let mut data_ptr = ptr::null_mut();
437	check_status!(unsafe {
438	sys::napi_create_arraybuffer(self.0, length, &mut data_ptr, &mut raw_value)
439	})?;
440
441	Ok(JsArrayBufferValue::new(
442	unsafe { JsArrayBuffer::from_raw_unchecked(self.0, raw_value) },
443	data_ptr as *mut c_void,
444	length,
445	))
446	}
447
448	pub fn create_arraybuffer_with_data(&self, mut data: Vec<u8>) -> Result<JsArrayBufferValue> {
449	let length = data.len();
450	let mut raw_value = ptr::null_mut();
451	let data_ptr = data.as_mut_ptr();
452	check_status!(unsafe {
453	if length == `0` {
454	// Rust uses 0x1 as the data pointer for empty buffers,
455	// but NAPI/V8 only allows multiple buffers to have
456	// the same data pointer if it's 0x0.
457	sys::napi_create_arraybuffer(self.0, length, ptr::null_mut(), &mut raw_value)
458	} else {
459	let hint_ptr = Box::into_raw(Box::new((length, data.capacity())));
460	let status = sys::napi_create_external_arraybuffer(
461	self.0,
462	data_ptr.cast(),
463	length,
464	Some(drop_buffer),
465	hint_ptr.cast(),
466	&mut raw_value,
467	);
468	if status == sys::Status::napi_no_external_buffers_allowed {
469	drop(Box::from_raw(hint_ptr));
470	let mut underlying_data = ptr::null_mut();
471	let status =
472	sys::napi_create_arraybuffer(self.0, length, &mut underlying_data, &mut raw_value);
473	ptr::copy_nonoverlapping(data_ptr, underlying_data.cast(), length);
474	status
475	} else {
476	status
477	}
478	}
479	})?;
480
481	mem::forget(data);
482	Ok(JsArrayBufferValue::new(
483	JsArrayBuffer(Value {
484	env: self.0,
485	value: raw_value,
486	value_type: ValueType::Object,
487	}),
488	data_ptr.cast(),
489	length,
490	))
491	}
492
493	/// # Safety
494	/// Mostly the same with `create_arraybuffer_with_data`
495	///
496	/// Provided `finalize_callback` will be called when `Buffer` got dropped.
497	///
498	/// You can pass in `noop_finalize` if you have nothing to do in finalize phase.
499	///
500	/// # Notes
501	///
502	/// JavaScript may mutate the data passed in to this buffer when writing the buffer.
503	/// However, some JavaScript runtimes do not support external buffers (notably electron!)
504	/// in which case modifications may be lost.
505	///
506	/// If you need to support these runtimes, you should create a buffer by other means and then
507	/// later copy the data back out.
508	pub unsafe fn create_arraybuffer_with_borrowed_data<Hint, Finalize>(
509	&self,
510	data: *mut u8,
511	length: usize,
512	hint: Hint,
513	finalize_callback: Finalize,
514	) -> Result<JsArrayBufferValue>
515	where
516	Finalize: FnOnce(Hint, Env),
517	{
518	let mut raw_value = ptr::null_mut();
519	let hint_ptr = Box::into_raw(Box::new((hint, finalize_callback)));
520	unsafe {
521	let status = sys::napi_create_external_arraybuffer(
522	self.0,
523	if length == `0` {
524	// Rust uses 0x1 as the data pointer for empty buffers,
525	// but NAPI/V8 only allows multiple buffers to have
526	// the same data pointer if it's 0x0.
527	ptr::null_mut()
528	} else {
529	data as *mut c_void
530	},
531	length,
532	Some(
533	raw_finalize_with_custom_callback::<Hint, Finalize>
534	as unsafe extern "C" fn(
535	env: sys::napi_env,
536	finalize_data: *mut c_void,
537	finalize_hint: *mut c_void,
538	),
539	),
540	hint_ptr.cast(),
541	&mut raw_value,
542	);
543	if status == sys::Status::napi_no_external_buffers_allowed {
544	let (hint, finalize) = *Box::from_raw(hint_ptr);
545	let mut underlying_data = ptr::null_mut();
546	let status =
547	sys::napi_create_arraybuffer(self.0, length, &mut underlying_data, &mut raw_value);
548	ptr::copy_nonoverlapping(data, underlying_data.cast(), length);
549	finalize(hint, *self);
550	check_status!(status)?;
551	} else {
552	check_status!(status)?;
553	}
554	};
555	Ok(JsArrayBufferValue::new(
556	JsArrayBuffer(Value {
557	env: self.0,
558	value: raw_value,
559	value_type: ValueType::Object,
560	}),
561	data as *mut c_void,
562	length,
563	))
564	}
565
566	/// This API allows an add-on author to create a function object in native code.
567	///
568	/// This is the primary mechanism to allow calling into the add-on's native code from JavaScript.
569	///
570	/// The newly created function is not automatically visible from script after this call.
571	///
572	/// Instead, a property must be explicitly set on any object that is visible to JavaScript, in order for the function to be accessible from script.
573	pub fn create_function(&self, name: &str, callback: Callback) -> Result<JsFunction> {
574	let mut raw_result = ptr::null_mut();
575	let len = name.len();
576	let name = CString::new(name)?;
577	check_status!(unsafe {
578	sys::napi_create_function(
579	self.0,
580	name.as_ptr(),
581	len,
582	Some(callback),
583	ptr::null_mut(),
584	&mut raw_result,
585	)
586	})?;
587
588	Ok(unsafe { JsFunction::from_raw_unchecked(self.0, raw_result) })
589	}
590
591	#[cfg(feature = "napi5")]
592	pub fn create_function_from_closure<R, F>(&self, name: &str, callback: F) -> Result<JsFunction>
593	where
594	F: 'static + Fn(crate::CallContext<'_>) -> Result<R>,
595	R: ToNapiValue,
596	{
597	let closure_data_ptr = Box::into_raw(Box::new(callback));
598
599	let mut raw_result = ptr::null_mut();
600	let len = name.len();
601	let name = CString::new(name)?;
602	check_status!(unsafe {
603	sys::napi_create_function(
604	self.0,
605	name.as_ptr(),
606	len,
607	Some(trampoline::<R, F>),
608	closure_data_ptr.cast(), // We let it borrow the data here
609	&mut raw_result,
610	)
611	})?;
612
613	// Note: based on N-API docs, at this point, we have created an effective
614	// `&'static dyn Fn…` in Rust parlance, in that thanks to `Box::into_raw()`
615	// we are sure the context won't be freed, and thus the callback may use
616	// it to call the actual method thanks to the trampoline…
617	// But we thus have a data leak: there is nothing yet responsible for
618	// running the `drop(Box::from_raw(…))` cleanup code.
619	//
620	// To solve that, according to the docs, we need to attach a finalizer:
621	check_status!(unsafe {
622	sys::napi_add_finalizer(
623	self.0,
624	raw_result,
625	closure_data_ptr.cast(),
626	Some(finalize_box_trampoline::<F>),
627	ptr::null_mut(),
628	ptr::null_mut(),
629	)
630	})?;
631
632	Ok(unsafe { JsFunction::from_raw_unchecked(self.0, raw_result) })
633	}
634
635	/// This API retrieves a napi_extended_error_info structure with information about the last error that occurred.
636	///
637	/// The content of the napi_extended_error_info returned is only valid up until an n-api function is called on the same env.
638	///
639	/// Do not rely on the content or format of any of the extended information as it is not subject to SemVer and may change at any time. It is intended only for logging purposes.
640	///
641	/// This API can be called even if there is a pending JavaScript exception.
642	pub fn get_last_error_info(&self) -> Result<ExtendedErrorInfo> {
643	let mut raw_extended_error = ptr::null();
644	check_status!(unsafe { sys::napi_get_last_error_info(self.0, &mut raw_extended_error) })?;
645	unsafe { ptr::read(raw_extended_error) }.try_into()
646	}
647
648	/// Throw any JavaScript value
649	pub fn throw<T: NapiRaw>(&self, value: T) -> Result<()> {
650	check_status!(unsafe { sys::napi_throw(self.0, value.raw()) })
651	}
652
653	/// This API throws a JavaScript Error with the text provided.
654	pub fn throw_error(&self, msg: &str, code: Option<&str>) -> Result<()> {
655	let code = code.and_then(\|s\| CString::new(s).ok());
656	let msg = CString::new(msg)?;
657	check_status!(unsafe {
658	sys::napi_throw_error(
659	self.0,
660	code.map(\|s\| s.as_ptr()).unwrap_or(ptr::null_mut()),
661	msg.as_ptr(),
662	)
663	})
664	}
665
666	/// This API throws a JavaScript RangeError with the text provided.
667	pub fn throw_range_error(&self, msg: &str, code: Option<&str>) -> Result<()> {
668	let code = code.and_then(\|s\| CString::new(s).ok());
669	let msg = CString::new(msg)?;
670	check_status!(unsafe {
671	sys::napi_throw_range_error(
672	self.0,
673	code.map(\|s\| s.as_ptr()).unwrap_or(ptr::null_mut()),
674	msg.as_ptr(),
675	)
676	})
677	}
678
679	/// This API throws a JavaScript TypeError with the text provided.
680	pub fn throw_type_error(&self, msg: &str, code: Option<&str>) -> Result<()> {
681	let code = code.and_then(\|s\| CString::new(s).ok());
682	let msg = CString::new(msg)?;
683	check_status!(unsafe {
684	sys::napi_throw_type_error(
685	self.0,
686	code.map(\|s\| s.as_ptr()).unwrap_or(ptr::null_mut()),
687	msg.as_ptr(),
688	)
689	})
690	}
691
692	/// This API throws a JavaScript SyntaxError with the text provided.
693	#[cfg(feature = "napi9")]
694	pub fn throw_syntax_error<S: AsRef<str>, C: AsRef<str>>(&self, msg: S, code: Option<C>) {
695	use crate::check_status_or_throw;
696
697	let code = code.as_ref().map(\|c\| c.as_ref()).unwrap_or("");
698	let c_code = CString::new(code).expect("code must be a valid utf-8 string");
699	let code_ptr = c_code.as_ptr();
700	let msg: CString = CString::new(msg.as_ref()).expect("msg must be a valid utf-8 string");
701	let msg_ptr = msg.as_ptr();
702	check_status_or_throw!(
703	self.`0`,
704	unsafe { sys::node_api_throw_syntax_error(self.`0`, code_ptr, msg_ptr,) },
705	"Throw syntax error failed"
706	);
707	}
708
709	#[allow(clippy::expect_fun_call)]
710	/// In the event of an unrecoverable error in a native module
711	///
712	/// A fatal error can be thrown to immediately terminate the process.
713	pub fn fatal_error(self, location: &str, message: &str) {
714	let location_len = location.len();
715	let message_len = message.len();
716	let location =
717	CString::new(location).expect(format!("Convert [{}] to CString failed", location).as_str());
718	let message =
719	CString::new(message).expect(format!("Convert [{}] to CString failed", message).as_str());
720
721	unsafe {
722	sys::napi_fatal_error(
723	location.as_ptr(),
724	location_len,
725	message.as_ptr(),
726	message_len,
727	)
728	}
729	}
730
731	#[cfg(feature = "napi3")]
732	/// Trigger an 'uncaughtException' in JavaScript.
733	///
734	/// Useful if an async callback throws an exception with no way to recover.
735	pub fn fatal_exception(&self, err: Error) {
736	unsafe {
737	let js_error = JsError::from(err).into_value(self.0);
738	debug_assert!(sys::napi_fatal_exception(self.0, js_error) == sys::Status::napi_ok);
739	};
740	}
741
742	/// Create JavaScript class
743	pub fn define_class(
744	&self,
745	name: &str,
746	constructor_cb: Callback,
747	properties: &[Property],
748	) -> Result<JsFunction> {
749	let mut raw_result = ptr::null_mut();
750	let raw_properties = properties
751	.iter()
752	.map(\|prop\| prop.raw())
753	.collect::<Vec<sys::napi_property_descriptor>>();
754	let c_name = CString::new(name)?;
755	check_status!(unsafe {
756	sys::napi_define_class(
757	self.0,
758	c_name.as_ptr() as *const c_char,
759	name.len(),
760	Some(constructor_cb),
761	ptr::null_mut(),
762	raw_properties.len(),
763	raw_properties.as_ptr(),
764	&mut raw_result,
765	)
766	})?;
767
768	Ok(unsafe { JsFunction::from_raw_unchecked(self.0, raw_result) })
769	}
770
771	#[allow(clippy::needless_pass_by_ref_mut)]
772	pub fn wrap<T: 'static>(&self, js_object: &mut JsObject, native_object: T) -> Result<()> {
773	check_status!(unsafe {
774	sys::napi_wrap(
775	self.0,
776	js_object.0.value,
777	Box::into_raw(Box::new(TaggedObject::new(native_object))).cast(),
778	Some(raw_finalize::<T>),
779	ptr::null_mut(),
780	ptr::null_mut(),
781	)
782	})
783	}
784
785	pub fn unwrap<T: 'static>(&self, js_object: &JsObject) -> Result<&mut T> {
786	unsafe {
787	let mut unknown_tagged_object: *mut c_void = ptr::null_mut();
788	check_status!(sys::napi_unwrap(
789	self.0,
790	js_object.0.value,
791	&mut unknown_tagged_object,
792	))?;
793
794	let type_id = unknown_tagged_object as *const TypeId;
795	if *type_id == TypeId::of::<T>() {
796	let tagged_object = unknown_tagged_object as *mut TaggedObject<T>;
797	(*tagged_object).object.as_mut().ok_or_else(\|\| {
798	Error::new(
799	Status::InvalidArg,
800	"Invalid argument, nothing attach to js_object".to_owned(),
801	)
802	})
803	} else {
804	Err(Error::new(
805	Status::InvalidArg,
806	format!(
807	"Invalid argument, {} on unwrap is not the type of wrapped object",
808	type_name::<T>()
809	),
810	))
811	}
812	}
813	}
814
815	pub fn drop_wrapped<T: 'static>(&self, js_object: &JsObject) -> Result<()> {
816	unsafe {
817	let mut unknown_tagged_object = ptr::null_mut();
818	check_status!(sys::napi_remove_wrap(
819	self.0,
820	js_object.0.value,
821	&mut unknown_tagged_object,
822	))?;
823	let type_id = unknown_tagged_object as *const TypeId;
824	if *type_id == TypeId::of::<T>() {
825	drop(Box::from_raw(unknown_tagged_object as *mut TaggedObject<T>));
826	Ok(())
827	} else {
828	Err(Error::new(
829	Status::InvalidArg,
830	format!(
831	"Invalid argument, {} on unwrap is not the type of wrapped object",
832	type_name::<T>()
833	),
834	))
835	}
836	}
837	}
838
839	/// This API create a new reference with the initial 1 ref count to the Object passed in.
840	pub fn create_reference<T>(&self, value: T) -> Result<Ref<()>>
841	where
842	T: NapiRaw,
843	{
844	let mut raw_ref = ptr::null_mut();
845	let initial_ref_count = `1`;
846	let raw_value = unsafe { value.raw() };
847	check_status!(unsafe {
848	sys::napi_create_reference(self.0, raw_value, initial_ref_count, &mut raw_ref)
849	})?;
850	Ok(Ref {
851	raw_ref,
852	count: `1`,
853	inner: (),
854	})
855	}
856
857	/// This API create a new reference with the specified reference count to the Object passed in.
858	pub fn create_reference_with_refcount<T>(&self, value: T, ref_count: u32) -> Result<Ref<()>>
859	where
860	T: NapiRaw,
861	{
862	let mut raw_ref = ptr::null_mut();
863	let raw_value = unsafe { value.raw() };
864	check_status!(unsafe {
865	sys::napi_create_reference(self.0, raw_value, ref_count, &mut raw_ref)
866	})?;
867	Ok(Ref {
868	raw_ref,
869	count: ref_count,
870	inner: (),
871	})
872	}
873
874	/// Get reference value from `Ref` with type check
875	///
876	/// Return error if the type of `reference` provided is mismatched with `T`
877	pub fn get_reference_value<T>(&self, reference: &Ref<()>) -> Result<T>
878	where
879	T: NapiValue,
880	{
881	let mut js_value = ptr::null_mut();
882	check_status!(unsafe {
883	sys::napi_get_reference_value(self.0, reference.raw_ref, &mut js_value)
884	})?;
885	unsafe { T::from_raw(self.0, js_value) }
886	}
887
888	/// Get reference value from `Ref` without type check
889	///
890	/// Using this API if you are sure the type of `T` is matched with provided `Ref<()>`.
891	///
892	/// If type mismatched, calling `T::method` would return `Err`.
893	pub fn get_reference_value_unchecked<T>(&self, reference: &Ref<()>) -> Result<T>
894	where
895	T: NapiValue,
896	{
897	let mut js_value = ptr::null_mut();
898	check_status!(unsafe {
899	sys::napi_get_reference_value(self.0, reference.raw_ref, &mut js_value)
900	})?;
901	Ok(unsafe { T::from_raw_unchecked(self.0, js_value) })
902	}
903
904	/// If `size_hint` provided, `Env::adjust_external_memory` will be called under the hood.
905	///
906	/// If no `size_hint` provided, global garbage collections will be triggered less times than expected.
907	///
908	/// If getting the exact `native_object` size is difficult, you can provide an approximate value, it's only effect to the GC.
909	pub fn create_external<T: 'static>(
910	&self,
911	native_object: T,
912	size_hint: Option<i64>,
913	) -> Result<JsExternal> {
914	let mut object_value = ptr::null_mut();
915	check_status!(unsafe {
916	sys::napi_create_external(
917	self.0,
918	Box::into_raw(Box::new(TaggedObject::new(native_object))).cast(),
919	Some(raw_finalize::<T>),
920	Box::into_raw(Box::new(size_hint)).cast(),
921	&mut object_value,
922	)
923	})?;
924	if let Some(changed) = size_hint {
925	if changed != `0` {
926	let mut adjusted_value = `0i64`;
927	check_status!(unsafe {
928	sys::napi_adjust_external_memory(self.0, changed, &mut adjusted_value)
929	})?;
930	}
931	};
932	Ok(unsafe { JsExternal::from_raw_unchecked(self.0, object_value) })
933	}
934
935	pub fn get_value_external<T: 'static>(&self, js_external: &JsExternal) -> Result<&mut T> {
936	unsafe {
937	let mut unknown_tagged_object = ptr::null_mut();
938	check_status!(sys::napi_get_value_external(
939	self.0,
940	js_external.0.value,
941	&mut unknown_tagged_object,
942	))?;
943
944	let type_id = unknown_tagged_object as *const TypeId;
945	if *type_id == TypeId::of::<T>() {
946	let tagged_object = unknown_tagged_object as *mut TaggedObject<T>;
947	(*tagged_object).object.as_mut().ok_or_else(\|\| {
948	Error::new(
949	Status::InvalidArg,
950	"nothing attach to js_external".to_owned(),
951	)
952	})
953	} else {
954	Err(Error::new(
955	Status::InvalidArg,
956	"T on get_value_external is not the type of wrapped object".to_owned(),
957	))
958	}
959	}
960	}
961
962	pub fn create_error(&self, e: Error) -> Result<JsObject> {
963	let reason = &e.reason;
964	let reason_string = self.create_string(reason.as_str())?;
965	let mut result = ptr::null_mut();
966	check_status!(unsafe {
967	sys::napi_create_error(self.0, ptr::null_mut(), reason_string.0.value, &mut result)
968	})?;
969	Ok(unsafe { JsObject::from_raw_unchecked(self.0, result) })
970	}
971
972	/// Run [Task](./trait.Task.html) in libuv thread pool, return [AsyncWorkPromise](./struct.AsyncWorkPromise.html)
973	pub fn spawn<T: 'static + Task>(&self, task: T) -> Result<AsyncWorkPromise> {
974	async_work::run(self.0, task, None)
975	}
976
977	pub fn run_in_scope<T, F>(&self, executor: F) -> Result<T>
978	where
979	F: FnOnce() -> Result<T>,
980	{
981	let mut handle_scope = ptr::null_mut();
982	check_status!(unsafe { sys::napi_open_handle_scope(self.0, &mut handle_scope) })?;
983
984	let result = executor();
985
986	check_status!(unsafe { sys::napi_close_handle_scope(self.0, handle_scope) })?;
987	result
988	}
989
990	/// Node-API provides an API for executing a string containing JavaScript using the underlying JavaScript engine.
991	/// This function executes a string of JavaScript code and returns its result with the following caveats:
992	/// - Unlike `eval`, this function does not allow the script to access the current lexical scope, and therefore also does not allow to access the [module scope](https://nodejs.org/api/modules.html#the-module-scope), meaning that pseudo-globals such as require will not be available.
993	/// - The script can access the [global scope](https://nodejs.org/api/globals.html). Function and `var` declarations in the script will be added to the [global](https://nodejs.org/api/globals.html#global) object. Variable declarations made using `let` and `const` will be visible globally, but will not be added to the global object.
994	/// - The value of this is [global](https://nodejs.org/api/globals.html) within the script.
995	pub fn run_script<S: AsRef<str>, V: FromNapiValue>(&self, script: S) -> Result<V> {
996	let s = self.create_string(script.as_ref())?;
997	let mut raw_value = ptr::null_mut();
998	check_status!(unsafe { sys::napi_run_script(self.0, s.raw(), &mut raw_value) })?;
999	unsafe { V::from_napi_value(self.0, raw_value) }
1000	}
1001
1002	/// `process.versions.napi`
1003	pub fn get_napi_version(&self) -> Result<u32> {
1004	let global = self.get_global()?;
1005	let process: JsObject = global.get_named_property("process")?;
1006	let versions: JsObject = process.get_named_property("versions")?;
1007	let napi_version: JsString = versions.get_named_property("napi")?;
1008	napi_version
1009	.into_utf8()?
1010	.as_str()?
1011	.parse()
1012	.map_err(\|e\| Error::new(Status::InvalidArg, format!("{}", e)))
1013	}
1014
1015	#[cfg(feature = "napi2")]
1016	pub fn get_uv_event_loop(&self) -> Result<*mut sys::uv_loop_s> {
1017	let mut uv_loop: *mut sys::uv_loop_s = ptr::null_mut();
1018	check_status!(unsafe { sys::napi_get_uv_event_loop(self.0, &mut uv_loop) })?;
1019	Ok(uv_loop)
1020	}
1021
1022	#[cfg(feature = "napi3")]
1023	pub fn add_env_cleanup_hook<T, F>(
1024	&mut self,
1025	cleanup_data: T,
1026	cleanup_fn: F,
1027	) -> Result<CleanupEnvHook<T>>
1028	where
1029	T: 'static,
1030	F: 'static + FnOnce(T),
1031	{
1032	let hook = CleanupEnvHookData {
1033	data: cleanup_data,
1034	hook: Box::new(cleanup_fn),
1035	};
1036	let hook_ref = Box::leak(Box::new(hook));
1037	check_status!(unsafe {
1038	sys::napi_add_env_cleanup_hook(
1039	self.0,
1040	Some(cleanup_env::<T>),
1041	hook_ref as *mut CleanupEnvHookData<T> as *mut _,
1042	)
1043	})?;
1044	Ok(CleanupEnvHook(hook_ref))
1045	}
1046
1047	#[cfg(feature = "napi3")]
1048	pub fn remove_env_cleanup_hook<T>(&mut self, hook: CleanupEnvHook<T>) -> Result<()>
1049	where
1050	T: 'static,
1051	{
1052	check_status!(unsafe {
1053	sys::napi_remove_env_cleanup_hook(self.0, Some(cleanup_env::<T>), hook.0 as *mut _)
1054	})
1055	}
1056
1057	#[cfg(feature = "napi4")]
1058	pub fn create_threadsafe_function<
1059	T: Send,
1060	V: ToNapiValue,
1061	R: 'static + Send + FnMut(ThreadSafeCallContext<T>) -> Result<Vec<V>>,
1062	>(
1063	&self,
1064	func: &JsFunction,
1065	max_queue_size: usize,
1066	callback: R,
1067	) -> Result<ThreadsafeFunction<T>> {
1068	ThreadsafeFunction::create(self.0, func.0.value, max_queue_size, callback)
1069	}
1070
1071	#[cfg(all(feature = "tokio_rt", feature = "napi4"))]
1072	pub fn execute_tokio_future<
1073	T: 'static + Send,
1074	V: 'static + ToNapiValue,
1075	F: 'static + Send + Future<Output = Result<T>>,
1076	R: 'static + FnOnce(&mut Env, T) -> Result<V>,
1077	>(
1078	&self,
1079	fut: F,
1080	resolver: R,
1081	) -> Result<JsObject> {
1082	use crate::tokio_runtime;
1083
1084	let promise = tokio_runtime::execute_tokio_future(self.0, fut, \|env, val\| unsafe {
1085	resolver(&mut Env::from_raw(env), val).and_then(\|v\| ToNapiValue::to_napi_value(env, v))
1086	})?;
1087
1088	Ok(unsafe { JsObject::from_raw_unchecked(self.0, promise) })
1089	}
1090
1091	#[cfg(all(feature = "tokio_rt", feature = "napi4"))]
1092	pub fn spawn_future<
1093	T: 'static + Send + ToNapiValue,
1094	F: 'static + Send + Future<Output = Result<T>>,
1095	>(
1096	&self,
1097	fut: F,
1098	) -> Result<JsObject> {
1099	use crate::tokio_runtime;
1100
1101	let promise = tokio_runtime::execute_tokio_future(self.0, fut, \|env, val\| unsafe {
1102	ToNapiValue::to_napi_value(env, val)
1103	})?;
1104
1105	Ok(unsafe { JsObject::from_raw_unchecked(self.0, promise) })
1106	}
1107
1108	/// Creates a deferred promise, which can be resolved or rejected from a background thread.
1109	#[cfg(feature = "napi4")]
1110	pub fn create_deferred<Data: ToNapiValue, Resolver: FnOnce(Env) -> Result<Data>>(
1111	&self,
1112	) -> Result<(JsDeferred<Data, Resolver>, JsObject)> {
1113	JsDeferred::new(self.raw())
1114	}
1115
1116	/// This API does not observe leap seconds; they are ignored, as ECMAScript aligns with POSIX time specification.
1117	///
1118	/// This API allocates a JavaScript Date object.
1119	///
1120	/// JavaScript Date objects are described in [Section 20.3](https://tc39.github.io/ecma262/#sec-date-objects) of the ECMAScript Language Specification.
1121	#[cfg(feature = "napi5")]
1122	pub fn create_date(&self, time: f64) -> Result<JsDate> {
1123	let mut js_value = ptr::null_mut();
1124	check_status!(unsafe { sys::napi_create_date(self.0, time, &mut js_value) })?;
1125	Ok(unsafe { JsDate::from_raw_unchecked(self.0, js_value) })
1126	}
1127
1128	#[cfg(feature = "napi6")]
1129
1130	/// This API associates data with the currently running Agent. data can later be retrieved using `Env::get_instance_data()`.
1131	///
1132	/// Any existing data associated with the currently running Agent which was set by means of a previous call to `Env::set_instance_data()` will be overwritten.
1133	///
1134	/// If a `finalize_cb` was provided by the previous call, it will not be called.
1135	pub fn set_instance_data<T, Hint, F>(&self, native: T, hint: Hint, finalize_cb: F) -> Result<()>
1136	where
1137	T: 'static,
1138	Hint: 'static,
1139	F: FnOnce(FinalizeContext<T, Hint>),
1140	{
1141	check_status!(unsafe {
1142	sys::napi_set_instance_data(
1143	self.0,
1144	Box::leak(Box::new((TaggedObject::new(native), finalize_cb))) as *mut (TaggedObject<T>, F)
1145	as *mut c_void,
1146	Some(
1147	set_instance_finalize_callback::<T, Hint, F>
1148	as unsafe extern "C" fn(
1149	env: sys::napi_env,
1150	finalize_data: *mut c_void,
1151	finalize_hint: *mut c_void,
1152	),
1153	),
1154	Box::leak(Box::new(hint)) as *mut Hint as *mut c_void,
1155	)
1156	})
1157	}
1158
1159	/// This API retrieves data that was previously associated with the currently running Agent via `Env::set_instance_data()`.
1160	///
1161	/// If no data is set, the call will succeed and data will be set to NULL.
1162	#[cfg(feature = "napi6")]
1163	pub fn get_instance_data<T>(&self) -> Result<Option<&'static mut T>>
1164	where
1165	T: 'static,
1166	{
1167	let mut unknown_tagged_object: *mut c_void = ptr::null_mut();
1168	unsafe {
1169	check_status!(sys::napi_get_instance_data(
1170	self.0,
1171	&mut unknown_tagged_object
1172	))?;
1173	let type_id = unknown_tagged_object as *const TypeId;
1174	if unknown_tagged_object.is_null() {
1175	return Ok(None);
1176	}
1177	if *type_id == TypeId::of::<T>() {
1178	let tagged_object = unknown_tagged_object as *mut TaggedObject<T>;
1179	(*tagged_object).object.as_mut().map(Some).ok_or_else(\|\| {
1180	Error::new(
1181	Status::InvalidArg,
1182	"Invalid argument, nothing attach to js_object".to_owned(),
1183	)
1184	})
1185	} else {
1186	Err(Error::new(
1187	Status::InvalidArg,
1188	format!(
1189	"Invalid argument, {} on unwrap is not the type of wrapped object",
1190	type_name::<T>()
1191	),
1192	))
1193	}
1194	}
1195	}
1196
1197	/// Registers hook, which is a function of type `FnOnce(Arg)`, as a function to be run with the `arg` parameter once the current Node.js environment exits.
1198	///
1199	/// Unlike [`add_env_cleanup_hook`](https://docs.rs/napi/latest/napi/struct.Env.html#method.add_env_cleanup_hook), the hook is allowed to be asynchronous.
1200	///
1201	/// Otherwise, behavior generally matches that of [`add_env_cleanup_hook`](https://docs.rs/napi/latest/napi/struct.Env.html#method.add_env_cleanup_hook).
1202	#[cfg(feature = "napi8")]
1203	pub fn add_removable_async_cleanup_hook<Arg, F>(
1204	&self,
1205	arg: Arg,
1206	cleanup_fn: F,
1207	) -> Result<AsyncCleanupHook>
1208	where
1209	F: FnOnce(Arg),
1210	Arg: 'static,
1211	{
1212	let mut handle = ptr::null_mut();
1213	check_status!(unsafe {
1214	sys::napi_add_async_cleanup_hook(
1215	self.0,
1216	Some(
1217	async_finalize::<Arg, F>
1218	as unsafe extern "C" fn(handle: sys::napi_async_cleanup_hook_handle, data: *mut c_void),
1219	),
1220	Box::leak(Box::new((arg, cleanup_fn))) as *mut (Arg, F) as *mut c_void,
1221	&mut handle,
1222	)
1223	})?;
1224	Ok(AsyncCleanupHook(handle))
1225	}
1226
1227	/// This API is very similar to [`add_removable_async_cleanup_hook`](https://docs.rs/napi/latest/napi/struct.Env.html#method.add_removable_async_cleanup_hook)
1228	///
1229	/// Use this one if you don't want remove the cleanup hook anymore.
1230	#[cfg(feature = "napi8")]
1231	pub fn add_async_cleanup_hook<Arg, F>(&self, arg: Arg, cleanup_fn: F) -> Result<()>
1232	where
1233	F: FnOnce(Arg),
1234	Arg: 'static,
1235	{
1236	check_status!(unsafe {
1237	sys::napi_add_async_cleanup_hook(
1238	self.0,
1239	Some(
1240	async_finalize::<Arg, F>
1241	as unsafe extern "C" fn(handle: sys::napi_async_cleanup_hook_handle, data: *mut c_void),
1242	),
1243	Box::leak(Box::new((arg, cleanup_fn))) as *mut (Arg, F) as *mut c_void,
1244	ptr::null_mut(),
1245	)
1246	})
1247	}
1248
1249	#[cfg(feature = "napi9")]
1250	pub fn symbol_for(&self, description: &str) -> Result<JsSymbol> {
1251	let mut result = ptr::null_mut();
1252	let len = description.len();
1253	let description = CString::new(description)?;
1254	check_status!(unsafe {
1255	sys::node_api_symbol_for(self.0, description.as_ptr(), len, &mut result)
1256	})?;
1257
1258	Ok(unsafe { JsSymbol::from_raw_unchecked(self.0, result) })
1259	}
1260
1261	#[cfg(feature = "napi9")]
1262	/// This API retrieves the file path of the currently running JS module as a URL. For a file on
1263	/// the local file system it will start with `file://`.
1264	///
1265	/// # Errors
1266	///
1267	/// The retrieved string may be empty if the add-on loading process fails to establish the
1268	/// add-on's file name.
1269	pub fn get_module_file_name(&self) -> Result<String> {
1270	let mut char_ptr = ptr::null();
1271	check_status!(
1272	unsafe { sys::node_api_get_module_file_name(self.0, &mut char_ptr) },
1273	"call node_api_get_module_file_name failed"
1274	)?;
1275	// SAFETY: This is safe because `char_ptr` is guaranteed to not be `null`, and point to
1276	// null-terminated string data.
1277	let module_filename = unsafe { std::ffi::CStr::from_ptr(char_ptr) };
1278
1279	Ok(module_filename.to_string_lossy().into_owned())
1280	}
1281
1282	/// ### Serialize `Rust Struct` into `JavaScript Value`
1283	///
1284	/// ```
1285	/// #[derive(Serialize, Debug, Deserialize)]
1286	/// struct AnObject {
1287	/// a: u32,
1288	/// b: Vec<f64>,
1289	/// c: String,
1290	/// }
1291	///
1292	/// #[js_function]
1293	/// fn serialize(ctx: CallContext) -> Result<JsUnknown> {
1294	/// let value = AnyObject { a: 1, b: vec![0.1, 2.22], c: "hello" };
1295	/// ctx.env.to_js_value(&value)
1296	/// }
1297	/// ```
1298	#[cfg(feature = "serde-json")]
1299	#[allow(clippy::wrong_self_convention)]
1300	pub fn to_js_value<T>(&self, node: &T) -> Result<JsUnknown>
1301	where
1302	T: Serialize,
1303	{
1304	let s = Ser(self);
1305	node.serialize(s).map(JsUnknown)
1306	}
1307
1308	/// ### Deserialize data from `JsValue`
1309	/// ```
1310	/// #[derive(Serialize, Debug, Deserialize)]
1311	/// struct AnObject {
1312	/// a: u32,
1313	/// b: Vec<f64>,
1314	/// c: String,
1315	/// }
1316	///
1317	/// #[js_function(1)]
1318	/// fn deserialize_from_js(ctx: CallContext) -> Result<JsUndefined> {
1319	/// let arg0 = ctx.get::<JsUnknown>(0)?;
1320	/// let de_serialized: AnObject = ctx.env.from_js_value(arg0)?;
1321	/// ...
1322	/// }
1323	///
1324	#[cfg(feature = "serde-json")]
1325	pub fn from_js_value<T, V>(&self, value: V) -> Result<T>
1326	where
1327	T: DeserializeOwned + ?Sized,
1328	V: NapiRaw,
1329	{
1330	let value = Value {
1331	env: self.0,
1332	value: unsafe { value.raw() },
1333	value_type: ValueType::Unknown,
1334	};
1335	let mut de = De(&value);
1336	T::deserialize(&mut de)
1337	}
1338
1339	/// This API represents the invocation of the Strict Equality algorithm as defined in [Section 7.2.14](https://tc39.es/ecma262/#sec-strict-equality-comparison) of the ECMAScript Language Specification.
1340	pub fn strict_equals<A: NapiRaw, B: NapiRaw>(&self, a: A, b: B) -> Result<bool> {
1341	let mut result = `false`;
1342	check_status!(unsafe { sys::napi_strict_equals(self.0, a.raw(), b.raw(), &mut result) })?;
1343	Ok(result)
1344	}
1345
1346	pub fn get_node_version(&self) -> Result<NodeVersion> {
1347	let mut result = ptr::null();
1348	check_status!(unsafe { sys::napi_get_node_version(self.0, &mut result) })?;
1349	let version = unsafe { *result };
1350	version.try_into()
1351	}
1352
1353	/// get raw env ptr
1354	pub fn raw(&self) -> sys::napi_env {
1355	self.0
1356	}
1357	}
1358
1359	/// This function could be used for `create_buffer_with_borrowed_data` and want do noting when Buffer finalized.
1360	pub fn noop_finalize<Hint>(_hint: Hint, _env: Env) {}
1361
1362	unsafe extern "C" fn drop_buffer(
1363	_env: sys::napi_env,
1364	finalize_data: *mut c_void,
1365	hint: *mut c_void,
1366	) {
1367	let length_ptr: mut (usize, usize) = hint as mut (usize, usize);
1368	let (length: usize, cap: usize) = unsafe { *Box::from_raw(length_ptr) };
1369	mem::drop(unsafe { Vec::from_raw_parts(ptr:finalize_data as *mut u8, length, capacity:cap) });
1370	}
1371
1372	pub(crate) unsafe extern "C" fn raw_finalize<T>(
1373	env: sys::napi_env,
1374	finalize_data: *mut c_void,
1375	finalize_hint: *mut c_void,
1376	) {
1377	let tagged_object: mut TaggedObject = finalize_data as mut TaggedObject<T>;
1378	drop(unsafe { Box::from_raw(tagged_object) });
1379	if !finalize_hint.is_null() {
1380	let size_hint: Option = unsafe { Box::from_raw(finalize_hint as mut Option<i64>) };
1381	if let Some(changed: i64) = size_hint {
1382	if changed != `0` {
1383	let mut adjusted: i64 = `0i64`;
1384	let status: i32 = unsafe { sys::napi_adjust_external_memory(env, -changed, &mut adjusted) };
1385	debug_assert!(
1386	status == sys::Status::napi_ok,
1387	"Calling napi_adjust_external_memory failed"
1388	);
1389	}
1390	};
1391	}
1392	}
1393
1394	#[cfg(feature = "napi6")]
1395	unsafe extern "C" fn set_instance_finalize_callback<T, Hint, F>(
1396	raw_env: sys::napi_env,
1397	finalize_data: *mut c_void,
1398	finalize_hint: *mut c_void,
1399	) where
1400	T: 'static,
1401	Hint: 'static,
1402	F: FnOnce(FinalizeContext<T, Hint>),
1403	{
1404	let (value: TaggedObject, callback: F) = unsafe { Box::from_raw(finalize_data as mut (TaggedObject<T>, F)) };
1405	let hint: Hint = unsafe { Box::from_raw(finalize_hint as mut Hint) };
1406	let env: Env = unsafe { Env::from_raw(raw_env) };
1407	callback(FinalizeContext {
1408	value: value.object.unwrap(),
1409	hint,
1410	env,
1411	});
1412	}
1413
1414	#[cfg(feature = "napi3")]
1415	unsafe extern "C" fn cleanup_env<T: 'static>(hook_data: *mut c_void) {
1416	let cleanup_env_hook: Box> = unsafe { Box::from_raw(hook_data as *mut CleanupEnvHookData<T>) };
1417	(cleanup_env_hook.hook)(cleanup_env_hook.data);
1418	}
1419
1420	unsafe extern "C" fn raw_finalize_with_custom_callback<Hint, Finalize>(
1421	env: sys::napi_env,
1422	_finalize_data: *mut c_void,
1423	finalize_hint: *mut c_void,
1424	) where
1425	Finalize: FnOnce(Hint, Env),
1426	{
1427	let (hint: Hint, callback: Finalize) = unsafe { Box::from_raw(finalize_hint as mut (Hint, Finalize)) };
1428	callback(hint, unsafe { Env::from_raw(env) });
1429	}
1430
1431	#[cfg(feature = "napi8")]
1432	unsafe extern "C" fn async_finalize<Arg, F>(
1433	handle: sys::napi_async_cleanup_hook_handle,
1434	data: *mut c_void,
1435	) where
1436	Arg: 'static,
1437	F: FnOnce(Arg),
1438	{
1439	let (arg: Arg, callback: F) = unsafe { Box::from_raw(data as mut (Arg, F)) };
1440	callback(arg);
1441	if !handle.is_null() {
1442	let status: i32 = unsafe { sys::napi_remove_async_cleanup_hook(remove_handle:handle) };
1443	assert!(
1444	status == sys::Status::napi_ok,
1445	"Remove async cleanup hook failed after async cleanup callback"
1446	);
1447	}
1448	}
1449
1450	#[cfg(feature = "napi5")]
1451	pub(crate) unsafe extern "C" fn trampoline<
1452	R: ToNapiValue,
1453	F: Fn(crate::CallContext) -> Result<R>,
1454	>(
1455	raw_env: sys::napi_env,
1456	cb_info: sys::napi_callback_info,
1457	) -> sys::napi_value {
1458	use crate::CallContext;
1459
1460	let (raw_this, raw_args, closure_data_ptr, argc) = {
1461	// Fast path for 4 arguments or less.
1462	let mut argc = `4`;
1463	let mut raw_args = Vec::with_capacity(`4`);
1464	let mut raw_this = ptr::null_mut();
1465	let mut closure_data_ptr = ptr::null_mut();
1466
1467	let status = unsafe {
1468	sys::napi_get_cb_info(
1469	raw_env,
1470	cb_info,
1471	&mut argc,
1472	raw_args.as_mut_ptr(),
1473	&mut raw_this,
1474	&mut closure_data_ptr,
1475	)
1476	};
1477	debug_assert!(
1478	Status::from(status) == Status::Ok,
1479	"napi_get_cb_info failed"
1480	);
1481
1482	// Arguments length greater than 4, resize the vector.
1483	if argc > `4` {
1484	raw_args = vec![ptr::null_mut(); argc];
1485	let status = unsafe {
1486	sys::napi_get_cb_info(
1487	raw_env,
1488	cb_info,
1489	&mut argc,
1490	raw_args.as_mut_ptr(),
1491	&mut raw_this,
1492	&mut closure_data_ptr,
1493	)
1494	};
1495	debug_assert!(
1496	Status::from(status) == Status::Ok,
1497	"napi_get_cb_info failed"
1498	);
1499	} else {
1500	unsafe { raw_args.set_len(argc) };
1501	}
1502
1503	(raw_this, raw_args, closure_data_ptr, argc)
1504	};
1505
1506	let closure: &F = Box::leak(unsafe { Box::from_raw(closure_data_ptr.cast()) });
1507	let mut env = unsafe { Env::from_raw(raw_env) };
1508	let call_context = CallContext::new(&mut env, cb_info, raw_this, raw_args.as_slice(), argc);
1509	closure(call_context)
1510	.and_then(\|ret: R\| unsafe { <R as ToNapiValue>::to_napi_value(env.0, ret) })
1511	.unwrap_or_else(\|e\| {
1512	unsafe { JsError::from(e).throw_into(raw_env) };
1513	ptr::null_mut()
1514	})
1515	}
1516
1517	#[cfg(feature = "napi5")]
1518	pub(crate) unsafe extern "C" fn trampoline_setter<
1519	V: FromNapiValue,
1520	F: Fn(Env, crate::bindgen_runtime::Object, V) -> Result<()>,
1521	>(
1522	raw_env: sys::napi_env,
1523	cb_info: sys::napi_callback_info,
1524	) -> sys::napi_value {
1525	use crate::bindgen_runtime::Object;
1526
1527	let (raw_args, raw_this, closure_data_ptr) = {
1528	let mut argc = `1`;
1529	let mut raw_args = vec![ptr::null_mut(); `1`];
1530	let mut raw_this = ptr::null_mut();
1531	let mut data_ptr = ptr::null_mut();
1532
1533	let status = unsafe {
1534	sys::napi_get_cb_info(
1535	raw_env,
1536	cb_info,
1537	&mut argc,
1538	raw_args.as_mut_ptr(),
1539	&mut raw_this,
1540	&mut data_ptr,
1541	)
1542	};
1543	unsafe { raw_args.set_len(argc) };
1544	debug_assert!(
1545	Status::from(status) == Status::Ok,
1546	"napi_get_cb_info failed"
1547	);
1548
1549	let closure_data_ptr = unsafe { (data_ptr as mut PropertyClosures) }.setter_closure;
1550	(raw_args, raw_this, closure_data_ptr)
1551	};
1552
1553	let closure: &F = Box::leak(unsafe { Box::from_raw(closure_data_ptr.cast()) });
1554	let env = unsafe { Env::from_raw(raw_env) };
1555	raw_args
1556	.first()
1557	.ok_or_else(\|\| Error::new(Status::InvalidArg, "Missing argument in property setter"))
1558	.and_then(\|value\| unsafe { V::from_napi_value(raw_env, *value) })
1559	.and_then(\|value\| {
1560	closure(
1561	env,
1562	unsafe { Object::from_raw_unchecked(raw_env, raw_this) },
1563	value,
1564	)
1565	})
1566	.map(\|_\| std::ptr::null_mut())
1567	.unwrap_or_else(\|e\| {
1568	unsafe { JsError::from(e).throw_into(raw_env) };
1569	ptr::null_mut()
1570	})
1571	}
1572
1573	#[cfg(feature = "napi5")]
1574	pub(crate) unsafe extern "C" fn trampoline_getter<
1575	R: ToNapiValue,
1576	F: Fn(Env, crate::bindgen_runtime::This) -> Result<R>,
1577	>(
1578	raw_env: sys::napi_env,
1579	cb_info: sys::napi_callback_info,
1580	) -> sys::napi_value {
1581	let (raw_this, closure_data_ptr) = {
1582	let mut raw_this = ptr::null_mut();
1583	let mut data_ptr = ptr::null_mut();
1584
1585	let status = unsafe {
1586	sys::napi_get_cb_info(
1587	raw_env,
1588	cb_info,
1589	&mut `0`,
1590	ptr::null_mut(),
1591	&mut raw_this,
1592	&mut data_ptr,
1593	)
1594	};
1595	debug_assert!(
1596	Status::from(status) == Status::Ok,
1597	"napi_get_cb_info failed"
1598	);
1599
1600	let closure_data_ptr = unsafe { (data_ptr as mut PropertyClosures) }.getter_closure;
1601	(raw_this, closure_data_ptr)
1602	};
1603
1604	let closure: &F = Box::leak(unsafe { Box::from_raw(closure_data_ptr.cast()) });
1605	let env = unsafe { Env::from_raw(raw_env) };
1606	closure(env, unsafe {
1607	crate::bindgen_runtime::Object::from_raw_unchecked(raw_env, raw_this)
1608	})
1609	.and_then(\|ret: R\| unsafe { <R as ToNapiValue>::to_napi_value(env.0, ret) })
1610	.unwrap_or_else(\|e\| {
1611	unsafe { JsError::from(e).throw_into(raw_env) };
1612	ptr::null_mut()
1613	})
1614	}
1615
1616	#[cfg(feature = "napi5")]
1617	pub(crate) unsafe extern "C" fn finalize_box_trampoline<F>(
1618	_raw_env: sys::napi_env,
1619	closure_data_ptr: *mut c_void,
1620	_finalize_hint: *mut c_void,
1621	) {
1622	drop(unsafe { Box::<F>::from_raw(closure_data_ptr.cast()) })
1623	}
1624