neon/types_impl/
mod.rs

1// See types_docs.rs for top-level module API docs.
2
3#[cfg(feature = "napi-6")]
4#[cfg_attr(docsrs, doc(cfg(feature = "napi-6")))]
5pub mod bigint;
6pub(crate) mod boxed;
7pub mod buffer;
8#[cfg(feature = "napi-5")]
9pub(crate) mod date;
10pub(crate) mod error;
11pub mod extract;
12pub mod function;
13pub(crate) mod promise;
14
15pub(crate) mod private;
16pub(crate) mod utf8;
17
18use std::{
19    any,
20    fmt::{self, Debug},
21};
22
23use private::prepare_call;
24use smallvec::smallvec;
25
26use crate::{
27    context::{
28        internal::{ContextInternal, Env},
29        Context, Cx, FunctionContext,
30    },
31    handle::{
32        internal::{SuperType, TransparentNoCopyWrapper},
33        Handle,
34    },
35    object::Object,
36    result::{JsResult, NeonResult, ResultExt, Throw},
37    sys::{self, raw},
38    types::{
39        function::{BindOptions, CallOptions, ConstructOptions},
40        private::ValueInternal,
41        utf8::Utf8,
42    },
43};
44
45pub use self::{
46    boxed::{Finalize, JsBox},
47    buffer::types::{
48        JsArrayBuffer, JsBigInt64Array, JsBigUint64Array, JsBuffer, JsFloat32Array, JsFloat64Array,
49        JsInt16Array, JsInt32Array, JsInt8Array, JsTypedArray, JsUint16Array, JsUint32Array,
50        JsUint8Array,
51    },
52    error::JsError,
53    promise::{Deferred, JsPromise},
54};
55
56#[cfg(feature = "napi-5")]
57pub use self::date::{DateError, DateErrorKind, JsDate};
58
59#[cfg(all(feature = "napi-5", feature = "futures"))]
60#[cfg_attr(docsrs, doc(cfg(all(feature = "napi-5", feature = "futures"))))]
61pub use self::promise::JsFuture;
62
63// This should be considered deprecated and will be removed:
64// https://github.com/neon-bindings/neon/issues/983
65pub(crate) fn build<'a, T: Value, F: FnOnce(&mut raw::Local) -> bool>(
66    env: Env,
67    init: F,
68) -> JsResult<'a, T> {
69    unsafe {
70        let mut local: raw::Local = std::mem::zeroed();
71        if init(&mut local) {
72            Ok(Handle::new_internal(T::from_local(env, local)))
73        } else {
74            Err(Throw::new())
75        }
76    }
77}
78
79impl<T: Value> SuperType<T> for JsValue {
80    fn upcast_internal(v: &T) -> JsValue {
81        JsValue(v.to_local())
82    }
83}
84
85impl<T: Object> SuperType<T> for JsObject {
86    fn upcast_internal(v: &T) -> JsObject {
87        JsObject(v.to_local())
88    }
89}
90
91/// The trait shared by all JavaScript values.
92pub trait Value: ValueInternal {
93    fn to_string<'cx, C: Context<'cx>>(&self, cx: &mut C) -> JsResult<'cx, JsString> {
94        let env = cx.env();
95        build(env, |out| unsafe {
96            sys::convert::to_string(out, env.to_raw(), self.to_local())
97        })
98    }
99
100    fn as_value<'cx, C: Context<'cx>>(&self, _: &mut C) -> Handle<'cx, JsValue> {
101        JsValue::new_internal(self.to_local())
102    }
103
104    #[cfg(feature = "sys")]
105    #[cfg_attr(docsrs, doc(cfg(feature = "sys")))]
106    /// Get a raw reference to the wrapped Node-API value.
107    fn to_raw(&self) -> sys::Value {
108        self.to_local()
109    }
110
111    #[cfg(feature = "sys")]
112    #[cfg_attr(docsrs, doc(cfg(feature = "sys")))]
113    /// Creates a value from a raw Node-API value.
114    ///
115    /// # Safety
116    ///
117    /// * `value` must be of type `Self`
118    /// * `value` must be valid for `'cx`
119    unsafe fn from_raw<'cx, C: Context<'cx>>(cx: &C, value: sys::Value) -> Handle<'cx, Self> {
120        Handle::new_internal(Self::from_local(cx.env(), value))
121    }
122}
123
124/// The type of any JavaScript value, i.e., the root of all types.
125///
126/// The `JsValue` type is a catch-all type that sits at the top of the
127/// [JavaScript type hierarchy](./index.html#the-javascript-type-hierarchy).
128/// All JavaScript values can be safely and statically
129/// [upcast](crate::handle::Handle::upcast) to `JsValue`; by contrast, a
130/// [downcast](crate::handle::Handle::downcast) of a `JsValue` to another type
131/// requires a runtime check.
132/// (For TypeScript programmers, this can be thought of as similar to TypeScript's
133/// [`unknown`](https://www.typescriptlang.org/docs/handbook/2/functions.html#unknown)
134/// type.)
135///
136/// The `JsValue` type can be useful for generic, dynamic, or otherwise
137/// hard-to-express API signatures, such as overloaded types:
138///
139/// ```
140/// # use neon::prelude::*;
141/// // Takes a string and adds the specified padding to the left.
142/// // If the padding is a string, it's added as-is.
143/// // If the padding is a number, then that number of spaces is added.
144/// fn pad_left(mut cx: FunctionContext) -> JsResult<JsString> {
145///     let string: Handle<JsString> = cx.argument(0)?;
146///     let padding: Handle<JsValue> = cx.argument(1)?;
147///
148///     let padding: String = if let Ok(str) = padding.downcast::<JsString, _>(&mut cx) {
149///         str.value(&mut cx)
150///     } else if let Ok(num) = padding.downcast::<JsNumber, _>(&mut cx) {
151///         " ".repeat(num.value(&mut cx) as usize)
152///     } else {
153///         return cx.throw_type_error("expected string or number");
154///     };
155///
156///     let new_value = padding + &string.value(&mut cx);
157///     Ok(cx.string(&new_value))
158/// }
159/// ```
160#[derive(Debug)]
161#[repr(transparent)]
162pub struct JsValue(raw::Local);
163
164impl Value for JsValue {}
165
166unsafe impl TransparentNoCopyWrapper for JsValue {
167    type Inner = raw::Local;
168
169    fn into_inner(self) -> Self::Inner {
170        self.0
171    }
172}
173
174impl ValueInternal for JsValue {
175    fn name() -> &'static str {
176        "any"
177    }
178
179    fn is_typeof<Other: Value>(_cx: &mut Cx, _other: &Other) -> bool {
180        true
181    }
182
183    fn to_local(&self) -> raw::Local {
184        self.0
185    }
186
187    unsafe fn from_local(_env: Env, h: raw::Local) -> Self {
188        JsValue(h)
189    }
190}
191
192impl JsValue {
193    pub(crate) fn new_internal<'a>(value: raw::Local) -> Handle<'a, JsValue> {
194        Handle::new_internal(JsValue(value))
195    }
196}
197
198/// The type of JavaScript
199/// [`undefined`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#primitive_values)
200/// primitives.
201///
202/// # Example
203///
204/// ```
205/// # use neon::prelude::*;
206/// # fn test(mut cx: FunctionContext) -> JsResult<JsUndefined> {
207/// // Extract the console object:
208/// let console: Handle<JsObject> = cx.global("console")?;
209///
210/// // The undefined value:
211/// let undefined = cx.undefined();
212///
213/// // Call console.log(undefined):
214/// console.method(&mut cx, "log")?.arg(undefined)?.exec()?;
215/// # Ok(undefined)
216/// # }
217/// ```
218#[derive(Debug)]
219#[repr(transparent)]
220pub struct JsUndefined(raw::Local);
221
222impl JsUndefined {
223    /// Creates an `undefined` value.
224    ///
225    /// Although this method can be called many times, all `undefined`
226    /// values are indistinguishable.
227    ///
228    /// **See also:** [`Context::undefined`]
229    pub fn new<'a, C: Context<'a>>(cx: &mut C) -> Handle<'a, JsUndefined> {
230        JsUndefined::new_internal(cx.env())
231    }
232
233    pub(crate) fn new_internal<'a>(env: Env) -> Handle<'a, JsUndefined> {
234        unsafe {
235            let mut local: raw::Local = std::mem::zeroed();
236            sys::primitive::undefined(&mut local, env.to_raw());
237            Handle::new_internal(JsUndefined(local))
238        }
239    }
240}
241
242impl Value for JsUndefined {}
243
244unsafe impl TransparentNoCopyWrapper for JsUndefined {
245    type Inner = raw::Local;
246
247    fn into_inner(self) -> Self::Inner {
248        self.0
249    }
250}
251
252impl ValueInternal for JsUndefined {
253    fn name() -> &'static str {
254        "undefined"
255    }
256
257    fn is_typeof<Other: Value>(cx: &mut Cx, other: &Other) -> bool {
258        unsafe { sys::tag::is_undefined(cx.env().to_raw(), other.to_local()) }
259    }
260
261    fn to_local(&self) -> raw::Local {
262        self.0
263    }
264
265    unsafe fn from_local(_env: Env, h: raw::Local) -> Self {
266        JsUndefined(h)
267    }
268}
269
270/// The type of JavaScript
271/// [`null`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#primitive_values)
272/// primitives.
273///
274/// # Example
275///
276/// ```
277/// # use neon::prelude::*;
278/// # fn test(mut cx: FunctionContext) -> JsResult<JsNull> {
279/// let null = cx.null();
280/// cx.global::<JsObject>("console")?
281///     .method(&mut cx, "log")?
282///     .arg(null)?
283///     .exec()?;
284/// # Ok(null)
285/// # }
286/// ```
287#[derive(Debug)]
288#[repr(transparent)]
289pub struct JsNull(raw::Local);
290
291impl JsNull {
292    /// Creates a `null` value.
293    ///
294    /// Although this method can be called many times, all `null`
295    /// values are indistinguishable.
296    ///
297    /// **See also:** [`Context::null`]
298    pub fn new<'a, C: Context<'a>>(cx: &mut C) -> Handle<'a, JsNull> {
299        JsNull::new_internal(cx.env())
300    }
301
302    pub(crate) fn new_internal<'a>(env: Env) -> Handle<'a, JsNull> {
303        unsafe {
304            let mut local: raw::Local = std::mem::zeroed();
305            sys::primitive::null(&mut local, env.to_raw());
306            Handle::new_internal(JsNull(local))
307        }
308    }
309}
310
311impl Value for JsNull {}
312
313unsafe impl TransparentNoCopyWrapper for JsNull {
314    type Inner = raw::Local;
315
316    fn into_inner(self) -> Self::Inner {
317        self.0
318    }
319}
320
321impl ValueInternal for JsNull {
322    fn name() -> &'static str {
323        "null"
324    }
325
326    fn is_typeof<Other: Value>(cx: &mut Cx, other: &Other) -> bool {
327        unsafe { sys::tag::is_null(cx.env().to_raw(), other.to_local()) }
328    }
329
330    fn to_local(&self) -> raw::Local {
331        self.0
332    }
333
334    unsafe fn from_local(_env: Env, h: raw::Local) -> Self {
335        JsNull(h)
336    }
337}
338
339/// The type of JavaScript
340/// [Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#primitive_values)
341/// primitives.
342///
343/// # Example
344///
345/// ```
346/// # use neon::prelude::*;
347/// # fn test(mut cx: FunctionContext) -> JsResult<JsUndefined> {
348/// // The two Boolean values:
349/// let t = cx.boolean(true);
350/// let f = cx.boolean(false);
351///
352/// // Call console.log(true, false):
353/// cx.global::<JsObject>("console")?.method(&mut cx, "log")?.args((t, f))?.exec()?;
354/// # Ok(cx.undefined())
355/// # }
356/// ```
357#[derive(Debug)]
358#[repr(transparent)]
359pub struct JsBoolean(raw::Local);
360
361impl JsBoolean {
362    /// Creates a Boolean value with value `b`.
363    ///
364    /// **See also:** [`Context::boolean`]
365    pub fn new<'a, C: Context<'a>>(cx: &mut C, b: bool) -> Handle<'a, JsBoolean> {
366        JsBoolean::new_internal(cx.env(), b)
367    }
368
369    pub(crate) fn new_internal<'a>(env: Env, b: bool) -> Handle<'a, JsBoolean> {
370        unsafe {
371            let mut local: raw::Local = std::mem::zeroed();
372            sys::primitive::boolean(&mut local, env.to_raw(), b);
373            Handle::new_internal(JsBoolean(local))
374        }
375    }
376
377    /// Returns the value of this Boolean as a Rust `bool`.
378    pub fn value<'a, C: Context<'a>>(&self, cx: &mut C) -> bool {
379        let env = cx.env().to_raw();
380        unsafe { sys::primitive::boolean_value(env, self.to_local()) }
381    }
382}
383
384impl Value for JsBoolean {}
385
386unsafe impl TransparentNoCopyWrapper for JsBoolean {
387    type Inner = raw::Local;
388
389    fn into_inner(self) -> Self::Inner {
390        self.0
391    }
392}
393
394impl ValueInternal for JsBoolean {
395    fn name() -> &'static str {
396        "boolean"
397    }
398
399    fn is_typeof<Other: Value>(cx: &mut Cx, other: &Other) -> bool {
400        unsafe { sys::tag::is_boolean(cx.env().to_raw(), other.to_local()) }
401    }
402
403    fn to_local(&self) -> raw::Local {
404        self.0
405    }
406
407    unsafe fn from_local(_env: Env, h: raw::Local) -> Self {
408        JsBoolean(h)
409    }
410}
411
412/// The type of JavaScript
413/// [string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#primitive_values)
414/// primitives.
415///
416/// # Example
417///
418/// ```
419/// # use neon::prelude::*;
420/// # fn test(mut cx: FunctionContext) -> JsResult<JsUndefined> {
421/// // Create a string:
422/// let s = cx.string("hello 🥹");
423///
424/// // Call console.log(s):
425/// cx.global::<JsObject>("console")?.method(&mut cx, "log")?.arg(s)?.exec()?;
426/// # Ok(cx.undefined())
427/// # }
428/// ```
429#[derive(Debug)]
430#[repr(transparent)]
431pub struct JsString(raw::Local);
432
433/// An error produced when constructing a string that exceeds the limits of the runtime.
434#[derive(PartialEq, Eq, PartialOrd, Ord, Clone, Debug)]
435pub struct StringOverflow(usize);
436
437impl fmt::Display for StringOverflow {
438    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
439        write!(f, "string size out of range: {}", self.0)
440    }
441}
442
443/// The result of constructing a new `JsString`.
444pub type StringResult<'a> = Result<Handle<'a, JsString>, StringOverflow>;
445
446impl<'a> ResultExt<Handle<'a, JsString>> for StringResult<'a> {
447    fn or_throw<'b, C: Context<'b>>(self, cx: &mut C) -> JsResult<'a, JsString> {
448        match self {
449            Ok(v) => Ok(v),
450            Err(e) => cx.throw_range_error(e.to_string()),
451        }
452    }
453}
454
455impl Value for JsString {}
456
457unsafe impl TransparentNoCopyWrapper for JsString {
458    type Inner = raw::Local;
459
460    fn into_inner(self) -> Self::Inner {
461        self.0
462    }
463}
464
465impl ValueInternal for JsString {
466    fn name() -> &'static str {
467        "string"
468    }
469
470    fn is_typeof<Other: Value>(cx: &mut Cx, other: &Other) -> bool {
471        unsafe { sys::tag::is_string(cx.env().to_raw(), other.to_local()) }
472    }
473
474    fn to_local(&self) -> raw::Local {
475        self.0
476    }
477
478    unsafe fn from_local(_env: Env, h: raw::Local) -> Self {
479        JsString(h)
480    }
481}
482
483impl JsString {
484    /// Returns the size of the UTF-8 representation of this string,
485    /// measured in 8-bit code units.
486    ///
487    /// Equivalent to `self.value(cx).len()` (but more efficient).
488    ///
489    /// # Example
490    ///
491    /// The string `"hello 🥹"` encodes as 10 bytes in UTF-8:
492    ///
493    /// - 6 bytes for `"hello "` (including the space).
494    /// - 4 bytes for the emoji `"🥹"`.
495    ///
496    /// ```rust
497    /// # use neon::prelude::*;
498    /// # fn string_len(mut cx: FunctionContext) -> JsResult<JsUndefined> {
499    /// let str = cx.string("hello 🥹");
500    /// assert_eq!(10, str.size(&mut cx));
501    /// # Ok(cx.undefined())
502    /// # }
503    /// ```
504    pub fn size<'a, C: Context<'a>>(&self, cx: &mut C) -> usize {
505        let env = cx.env().to_raw();
506
507        unsafe { sys::string::utf8_len(env, self.to_local()) }
508    }
509
510    /// Returns the size of the UTF-16 representation of this string,
511    /// measured in 16-bit code units.
512    ///
513    /// Equivalent to `self.to_utf16(cx).len()` (but more efficient).
514    ///
515    /// # Example
516    ///
517    /// The string `"hello 🥹"` encodes as 8 code units in UTF-16:
518    ///
519    /// - 6 `u16`s for `"hello "` (including the space).
520    /// - 2 `u16`s for the emoji `"🥹"`.
521    ///
522    /// ```rust
523    /// # use neon::prelude::*;
524    /// # fn string_len_utf16(mut cx: FunctionContext) -> JsResult<JsUndefined> {
525    /// let str = cx.string("hello 🥹");
526    /// assert_eq!(8, str.size_utf16(&mut cx));
527    /// # Ok(cx.undefined())
528    /// # }
529    /// ```
530    pub fn size_utf16<'a, C: Context<'a>>(&self, cx: &mut C) -> usize {
531        let env = cx.env().to_raw();
532
533        unsafe { sys::string::utf16_len(env, self.to_local()) }
534    }
535
536    /// Convert this JavaScript string into a Rust [`String`].
537    ///
538    /// # Example
539    ///
540    /// This example function expects a single JavaScript string as argument
541    /// and prints it out.
542    ///
543    /// ```rust
544    /// # use neon::prelude::*;
545    /// fn print_string(mut cx: FunctionContext) -> JsResult<JsUndefined> {
546    ///     let s = cx.argument::<JsString>(0)?.value(&mut cx);
547    ///     println!("JavaScript string contents: {}", s);
548    ///
549    ///     Ok(cx.undefined())
550    /// }
551    /// ```
552    pub fn value<'a, C: Context<'a>>(&self, cx: &mut C) -> String {
553        let env = cx.env().to_raw();
554
555        unsafe {
556            let capacity = sys::string::utf8_len(env, self.to_local()) + 1;
557            let mut buffer: Vec<u8> = Vec::with_capacity(capacity);
558            let len = sys::string::data(env, buffer.as_mut_ptr(), capacity, self.to_local());
559            buffer.set_len(len);
560            String::from_utf8_unchecked(buffer)
561        }
562    }
563
564    /// Convert this JavaScript string into a [`Vec<u16>`] encoded as UTF-16.
565    ///
566    /// The returned vector is guaranteed to be valid UTF-16, so libraries that handle
567    /// UTF-16-encoded strings can assume the content to be valid.
568    ///
569    /// # Example
570    ///
571    /// This example function expects a single JavaScript string as argument and prints it out
572    /// as a raw vector of `u16`s.
573    ///
574    /// ```rust
575    /// # use neon::prelude::*;
576    /// fn print_string_as_utf16(mut cx: FunctionContext) -> JsResult<JsUndefined> {
577    ///     let s = cx.argument::<JsString>(0)?.to_utf16(&mut cx);
578    ///     println!("JavaScript string as raw UTF-16: {:?}", s);
579    ///
580    ///     Ok(cx.undefined())
581    /// }
582    /// ```
583    ///
584    /// This next example function also expects a single JavaScript string as argument and converts
585    /// to a [`Vec<u16>`], but utilizes the [`widestring`](https://crates.io/crates/widestring)
586    /// crate to handle the vector as a typical string.
587    ///
588    /// ```rust
589    /// # use neon::prelude::*;
590    /// use widestring::Utf16String;
591    ///
592    /// fn print_with_widestring(mut cx: FunctionContext) -> JsResult<JsUndefined> {
593    ///     let s = cx.argument::<JsString>(0)?.to_utf16(&mut cx);
594    ///
595    ///     // The returned vector is guaranteed to be valid UTF-16, so we can
596    ///     // safely skip the validation step.
597    ///     let s = unsafe { Utf16String::from_vec_unchecked(s) };
598    ///
599    ///     println!("JavaScript string as UTF-16: {}", s);
600    ///
601    ///     Ok(cx.undefined())
602    /// }
603    /// ```
604    pub fn to_utf16<'a, C: Context<'a>>(&self, cx: &mut C) -> Vec<u16> {
605        let env = cx.env().to_raw();
606
607        unsafe {
608            let capacity = sys::string::utf16_len(env, self.to_local()) + 1;
609            let mut buffer: Vec<u16> = Vec::with_capacity(capacity);
610            let len = sys::string::data_utf16(env, buffer.as_mut_ptr(), capacity, self.to_local());
611            buffer.set_len(len);
612            buffer
613        }
614    }
615
616    /// Creates a new `JsString` value from a Rust string by copying its contents.
617    ///
618    /// This method panics if the string is longer than the maximum string size allowed
619    /// by the JavaScript engine.
620    ///
621    /// # Example
622    ///
623    /// ```
624    /// # use neon::prelude::*;
625    /// # fn string_new(mut cx: FunctionContext) -> JsResult<JsUndefined> {
626    /// let str = JsString::new(&mut cx, "hello 🥹");
627    /// assert_eq!(10, str.size(&mut cx));
628    /// # Ok(cx.undefined())
629    /// # }
630    /// ```
631    ///
632    /// **See also:** [`Context::string`]
633    pub fn new<'a, C: Context<'a>, S: AsRef<str>>(cx: &mut C, val: S) -> Handle<'a, JsString> {
634        JsString::try_new(cx, val).unwrap()
635    }
636
637    /// Tries to create a new `JsString` value from a Rust string by copying its contents.
638    ///
639    /// Returns `Err(StringOverflow)` if the string is longer than the maximum string size
640    /// allowed by the JavaScript engine.
641    ///
642    /// # Example
643    ///
644    /// This example tries to construct a JavaScript string from a Rust string of
645    /// unknown length, and on overflow generates an alternate truncated string with
646    /// a suffix (`"[…]"`) to indicate the truncation.
647    ///
648    /// ```
649    /// # use neon::prelude::*;
650    /// # fn string_try_new(mut cx: FunctionContext) -> JsResult<JsString> {
651    /// # static str: &'static str = "hello 🥹";
652    /// let s = match JsString::try_new(&mut cx, str) {
653    ///     Ok(s) => s,
654    ///     Err(_) => cx.string(format!("{}[…]", &str[0..32])),
655    /// };
656    /// # Ok(s)
657    /// # }
658    /// ```
659    pub fn try_new<'a, C: Context<'a>, S: AsRef<str>>(cx: &mut C, val: S) -> StringResult<'a> {
660        let val = val.as_ref();
661        match JsString::new_internal(cx.env(), val) {
662            Some(s) => Ok(s),
663            None => Err(StringOverflow(val.len())),
664        }
665    }
666
667    pub(crate) fn new_internal<'a>(env: Env, val: &str) -> Option<Handle<'a, JsString>> {
668        let (ptr, len) = if let Some(small) = Utf8::from(val).into_small() {
669            small.lower()
670        } else {
671            return None;
672        };
673
674        unsafe {
675            let mut local: raw::Local = std::mem::zeroed();
676            if sys::string::new(&mut local, env.to_raw(), ptr, len) {
677                Some(Handle::new_internal(JsString(local)))
678            } else {
679                None
680            }
681        }
682    }
683}
684
685/// The type of JavaScript
686/// [number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#primitive_values)
687/// primitives.
688///
689/// # Example
690///
691/// ```
692/// # use neon::prelude::*;
693/// # fn test(mut cx: FunctionContext) -> JsResult<JsUndefined> {
694/// // Create a number:
695/// let n = cx.number(17.0);
696///
697/// // Call console.log(n):
698/// cx.global::<JsObject>("console")?.method(&mut cx, "log")?.arg(n)?.exec()?;
699/// # Ok(cx.undefined())
700/// # }
701/// ```
702#[derive(Debug)]
703#[repr(transparent)]
704pub struct JsNumber(raw::Local);
705
706impl JsNumber {
707    /// Creates a new number with value `x`.
708    ///
709    /// **See also:** [`Context::number`]
710    pub fn new<'a, C: Context<'a>, T: Into<f64>>(cx: &mut C, x: T) -> Handle<'a, JsNumber> {
711        JsNumber::new_internal(cx.env(), x.into())
712    }
713
714    pub(crate) fn new_internal<'a>(env: Env, v: f64) -> Handle<'a, JsNumber> {
715        unsafe {
716            let mut local: raw::Local = std::mem::zeroed();
717            sys::primitive::number(&mut local, env.to_raw(), v);
718            Handle::new_internal(JsNumber(local))
719        }
720    }
721
722    /// Returns the value of this number as a Rust `f64`.
723    pub fn value<'a, C: Context<'a>>(&self, cx: &mut C) -> f64 {
724        let env = cx.env().to_raw();
725        unsafe { sys::primitive::number_value(env, self.to_local()) }
726    }
727}
728
729impl Value for JsNumber {}
730
731unsafe impl TransparentNoCopyWrapper for JsNumber {
732    type Inner = raw::Local;
733
734    fn into_inner(self) -> Self::Inner {
735        self.0
736    }
737}
738
739impl ValueInternal for JsNumber {
740    fn name() -> &'static str {
741        "number"
742    }
743
744    fn is_typeof<Other: Value>(cx: &mut Cx, other: &Other) -> bool {
745        unsafe { sys::tag::is_number(cx.env().to_raw(), other.to_local()) }
746    }
747
748    fn to_local(&self) -> raw::Local {
749        self.0
750    }
751
752    unsafe fn from_local(_env: Env, h: raw::Local) -> Self {
753        JsNumber(h)
754    }
755}
756
757/// The type of JavaScript
758/// [objects](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#objects),
759/// i.e., the root of all object types.
760///
761/// # Example
762///
763/// ```
764/// # use neon::prelude::*;
765/// # fn test(mut cx: FunctionContext) -> JsResult<JsUndefined> {
766/// // Create an object:
767/// let obj = cx.empty_object()
768///     .prop(&mut cx, "name")
769///     .set("Neon")?
770///     .prop("url")
771///     .set("https://neon-bindings.com")?
772///     .this();
773///
774/// // Call console.log(obj):
775/// cx.global::<JsObject>("console")?.method(&mut cx, "log")?.arg(obj)?.exec()?;
776/// # Ok(cx.undefined())
777/// # }
778/// ```
779#[derive(Debug)]
780#[repr(transparent)]
781pub struct JsObject(raw::Local);
782
783impl Value for JsObject {}
784
785unsafe impl TransparentNoCopyWrapper for JsObject {
786    type Inner = raw::Local;
787
788    fn into_inner(self) -> Self::Inner {
789        self.0
790    }
791}
792
793impl ValueInternal for JsObject {
794    fn name() -> &'static str {
795        "object"
796    }
797
798    fn is_typeof<Other: Value>(cx: &mut Cx, other: &Other) -> bool {
799        unsafe { sys::tag::is_object(cx.env().to_raw(), other.to_local()) }
800    }
801
802    fn to_local(&self) -> raw::Local {
803        self.0
804    }
805
806    unsafe fn from_local(_env: Env, h: raw::Local) -> Self {
807        JsObject(h)
808    }
809}
810
811impl Object for JsObject {}
812
813impl JsObject {
814    /// Creates a new empty object.
815    ///
816    /// **See also:** [`Context::empty_object`]
817    pub fn new<'a, C: Context<'a>>(c: &mut C) -> Handle<'a, JsObject> {
818        JsObject::new_internal(c.env())
819    }
820
821    pub(crate) fn new_internal<'a>(env: Env) -> Handle<'a, JsObject> {
822        JsObject::build(|out| unsafe { sys::object::new(out, env.to_raw()) })
823    }
824
825    pub(crate) fn build<'a, F: FnOnce(&mut raw::Local)>(init: F) -> Handle<'a, JsObject> {
826        unsafe {
827            let mut local: raw::Local = std::mem::zeroed();
828            init(&mut local);
829            Handle::new_internal(JsObject(local))
830        }
831    }
832}
833
834/// The type of JavaScript
835/// [`Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)
836/// objects.
837///
838/// An array is any JavaScript value for which
839/// [`Array.isArray`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/isArray)
840/// would return `true`.
841///
842/// # Example
843///
844/// ```
845/// # use neon::prelude::*;
846/// # fn foo(mut cx: FunctionContext) -> JsResult<JsArray> {
847/// // Create a new empty array:
848/// let a: Handle<JsArray> = cx.empty_array();
849///
850/// // Push some values onto the array:
851/// a.prop(&mut cx, 0).set(17)?;
852/// a.prop(&mut cx, 1).set("hello")?;
853/// # Ok(a)
854/// # }
855/// ```
856#[derive(Debug)]
857#[repr(transparent)]
858pub struct JsArray(raw::Local);
859
860impl JsArray {
861    /// Constructs a new empty array of length `len`, equivalent to the JavaScript
862    /// expression `new Array(len)`.
863    ///
864    /// Note that for non-zero `len`, this creates a
865    /// [sparse array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Indexed_collections#sparse_arrays),
866    /// which can sometimes have surprising behavior. To ensure that a new array
867    /// is and remains dense (i.e., not sparse), consider creating an empty array
868    /// with `JsArray::new(cx, 0)` or `cx.empty_array()` and only appending
869    /// elements to the end of the array.
870    ///
871    /// **See also:** [`Context::empty_array`]
872    pub fn new<'a, C: Context<'a>>(cx: &mut C, len: usize) -> Handle<'a, JsArray> {
873        JsArray::new_internal(cx.env(), len)
874    }
875
876    pub(crate) fn new_internal<'a>(env: Env, len: usize) -> Handle<'a, JsArray> {
877        unsafe {
878            let mut local: raw::Local = std::mem::zeroed();
879            sys::array::new(&mut local, env.to_raw(), len);
880            Handle::new_internal(JsArray(local))
881        }
882    }
883
884    /// Copies the array contents into a new [`Vec`] by iterating through all indices
885    /// from 0 to `self.len()`.
886    ///
887    /// The length is dynamically checked on each iteration in case the array is modified
888    /// during the computation.
889    pub fn to_vec<'a, C: Context<'a>>(&self, cx: &mut C) -> NeonResult<Vec<Handle<'a, JsValue>>> {
890        let mut result = Vec::with_capacity(self.len_inner(cx.env()) as usize);
891        let mut i = 0;
892        loop {
893            // Since getting a property can trigger arbitrary code,
894            // we have to re-check the length on every iteration.
895            if i >= self.len_inner(cx.env()) {
896                return Ok(result);
897            }
898            result.push(self.get(cx, i)?);
899            i += 1;
900        }
901    }
902
903    fn len_inner(&self, env: Env) -> u32 {
904        unsafe { sys::array::len(env.to_raw(), self.to_local()) }
905    }
906
907    #[allow(clippy::len_without_is_empty)]
908    /// Returns the length of the array, equivalent to the JavaScript expression
909    /// [`this.length`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/length).
910    pub fn len<'a, C: Context<'a>>(&self, cx: &mut C) -> u32 {
911        self.len_inner(cx.env())
912    }
913
914    /// Indicates whether the array is empty, equivalent to
915    /// `self.len() == 0`.
916    pub fn is_empty<'a, C: Context<'a>>(&self, cx: &mut C) -> bool {
917        self.len(cx) == 0
918    }
919}
920
921impl Value for JsArray {}
922
923unsafe impl TransparentNoCopyWrapper for JsArray {
924    type Inner = raw::Local;
925
926    fn into_inner(self) -> Self::Inner {
927        self.0
928    }
929}
930
931impl ValueInternal for JsArray {
932    fn name() -> &'static str {
933        "Array"
934    }
935
936    fn is_typeof<Other: Value>(cx: &mut Cx, other: &Other) -> bool {
937        unsafe { sys::tag::is_array(cx.env().to_raw(), other.to_local()) }
938    }
939
940    fn to_local(&self) -> raw::Local {
941        self.0
942    }
943
944    unsafe fn from_local(_env: Env, h: raw::Local) -> Self {
945        JsArray(h)
946    }
947}
948
949impl Object for JsArray {}
950
951/// The type of JavaScript
952/// [`Function`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function)
953/// objects.
954#[derive(Debug)]
955#[repr(transparent)]
956///
957/// A `JsFunction` may come from an existing JavaScript function, for example
958/// by extracting it from the property of another object such as the
959/// [global object](crate::context::Context::global), or it may be defined in Rust
960/// with [`JsFunction::new()`](JsFunction::new).
961///
962/// ## Calling functions
963///
964/// Neon provides a convenient syntax for calling JavaScript functions with the
965/// [`bind()`](JsFunction::bind) method, which produces a [`BindOptions`](BindOptions)
966/// struct that can be used to provide the function arguments (and optionally, the binding for
967/// `this`) before calling the function:
968/// ```
969/// # use neon::prelude::*;
970/// # fn foo(mut cx: FunctionContext) -> JsResult<JsNumber> {
971/// // Extract the parseInt function from the global object
972/// let parse_int: Handle<JsFunction> = cx.global("parseInt")?;
973///
974/// // Call parseInt("42")
975/// let x: Handle<JsNumber> = parse_int
976///     .bind(&mut cx)
977///     .arg("42")?
978///     .call()?;
979/// # Ok(x)
980/// # }
981/// ```
982///
983/// ## Calling functions as constructors
984///
985/// A `JsFunction` can be called as a constructor (like `new Array(16)` or
986/// `new URL("https://neon-bindings.com")`) with the
987/// [`construct()`](BindOptions::construct) method:
988/// ```
989/// # use neon::prelude::*;
990/// # fn foo(mut cx: FunctionContext) -> JsResult<JsObject> {
991/// // Extract the URL constructor from the global object
992/// let url: Handle<JsFunction> = cx.global("URL")?;
993///
994/// // Call new URL("https://neon-bindings.com")
995/// let obj = url
996///     .bind(&mut cx)
997///     .arg("https://neon-bindings.com")?
998///     .construct()?;
999/// # Ok(obj)
1000/// # }
1001/// ```
1002///
1003/// ## Defining functions
1004///
1005/// JavaScript functions can be defined in Rust with the
1006/// [`JsFunction::new()`](JsFunction::new) constructor, which takes
1007/// a Rust implementation function and produces a JavaScript function.
1008///
1009/// ```
1010/// # use neon::prelude::*;
1011/// // A function implementation that adds 1 to its first argument
1012/// fn add1(mut cx: FunctionContext) -> JsResult<JsNumber> {
1013///     let x: Handle<JsNumber> = cx.argument(0)?;
1014///     let v = x.value(&mut cx);
1015///     Ok(cx.number(v + 1.0))
1016/// }
1017///
1018/// # fn foo(mut cx: FunctionContext) -> JsResult<JsFunction> {
1019/// // Define a new JsFunction implemented with the add1 function
1020/// let f = JsFunction::new(&mut cx, add1)?;
1021/// # Ok(f)
1022/// # }
1023/// ```
1024pub struct JsFunction {
1025    raw: raw::Local,
1026}
1027
1028impl Object for JsFunction {}
1029
1030impl JsFunction {
1031    #[cfg(not(feature = "napi-5"))]
1032    /// Returns a new `JsFunction` implemented by `f`.
1033    pub fn new<'a, C, U>(
1034        cx: &mut C,
1035        f: fn(FunctionContext) -> JsResult<U>,
1036    ) -> JsResult<'a, JsFunction>
1037    where
1038        C: Context<'a>,
1039        U: Value,
1040    {
1041        let name = any::type_name::<F>();
1042
1043        Self::new_internal(cx, f, name)
1044    }
1045
1046    #[cfg(feature = "napi-5")]
1047    /// Returns a new `JsFunction` implemented by `f`.
1048    pub fn new<'a, C, F, V>(cx: &mut C, f: F) -> JsResult<'a, JsFunction>
1049    where
1050        C: Context<'a>,
1051        F: Fn(FunctionContext) -> JsResult<V> + 'static,
1052        V: Value,
1053    {
1054        let name = any::type_name::<F>();
1055
1056        Self::new_internal(cx, f, name)
1057    }
1058
1059    #[cfg(not(feature = "napi-5"))]
1060    /// Returns a new `JsFunction` implemented by `f` with specified name
1061    pub fn with_name<'a, C, U>(
1062        cx: &mut C,
1063        name: &str,
1064        f: fn(FunctionContext) -> JsResult<U>,
1065    ) -> JsResult<'a, JsFunction>
1066    where
1067        C: Context<'a>,
1068        U: Value,
1069    {
1070        Self::new_internal(cx, f, name)
1071    }
1072
1073    #[cfg(feature = "napi-5")]
1074    /// Returns a new `JsFunction` implemented by `f` with specified name
1075    pub fn with_name<'a, C, F, V>(cx: &mut C, name: &str, f: F) -> JsResult<'a, JsFunction>
1076    where
1077        C: Context<'a>,
1078        F: Fn(FunctionContext) -> JsResult<V> + 'static,
1079        V: Value,
1080    {
1081        Self::new_internal(cx, f, name)
1082    }
1083
1084    fn new_internal<'a, C, F, V>(cx: &mut C, f: F, name: &str) -> JsResult<'a, JsFunction>
1085    where
1086        C: Context<'a>,
1087        F: Fn(FunctionContext) -> JsResult<V> + 'static,
1088        V: Value,
1089    {
1090        use std::panic::AssertUnwindSafe;
1091        use std::ptr;
1092
1093        use crate::context::CallbackInfo;
1094        use crate::types::error::convert_panics;
1095
1096        let f = move |env: raw::Env, info| {
1097            let env = env.into();
1098            let info = unsafe { CallbackInfo::new(info) };
1099
1100            FunctionContext::with(env, &info, |cx| {
1101                convert_panics(env, AssertUnwindSafe(|| f(cx)))
1102                    .map(|v| v.to_local())
1103                    // We do not have a Js Value to return, most likely due to an exception.
1104                    // If we are in a throwing state, constructing a Js Value would be invalid.
1105                    // While not explicitly written, the Node-API documentation includes many examples
1106                    // of returning `NULL` when a native function does not return a value.
1107                    // https://nodejs.org/api/n-api.html#n_api_napi_create_function
1108                    .unwrap_or_else(|_: Throw| ptr::null_mut())
1109            })
1110        };
1111
1112        unsafe {
1113            if let Ok(raw) = sys::fun::new(cx.env().to_raw(), name, f) {
1114                Ok(Handle::new_internal(JsFunction { raw }))
1115            } else {
1116                Err(Throw::new())
1117            }
1118        }
1119    }
1120}
1121
1122impl JsFunction {
1123    /// Calls this function.
1124    ///
1125    /// **See also:** [`JsFunction::bind`].
1126    pub fn call<'a, 'b, C: Context<'a>, T, AS>(
1127        &self,
1128        cx: &mut C,
1129        this: Handle<'b, T>,
1130        args: AS,
1131    ) -> JsResult<'a, JsValue>
1132    where
1133        T: Value,
1134        AS: AsRef<[Handle<'b, JsValue>]>,
1135    {
1136        unsafe { self.try_call(cx, this, args) }
1137    }
1138
1139    /// Calls this function for side effect, discarding its result.
1140    ///
1141    /// **See also:** [`JsFunction::bind`].
1142    pub fn exec<'a, 'b, C: Context<'a>, T, AS>(
1143        &self,
1144        cx: &mut C,
1145        this: Handle<'b, T>,
1146        args: AS,
1147    ) -> NeonResult<()>
1148    where
1149        T: Value,
1150        AS: AsRef<[Handle<'b, JsValue>]>,
1151    {
1152        self.call(cx, this, args)?;
1153        Ok(())
1154    }
1155
1156    /// Calls this function as a constructor.
1157    ///
1158    /// **See also:** [`JsFunction::bind`].
1159    pub fn construct<'a, 'b, C: Context<'a>, AS>(
1160        &self,
1161        cx: &mut C,
1162        args: AS,
1163    ) -> JsResult<'a, JsObject>
1164    where
1165        AS: AsRef<[Handle<'b, JsValue>]>,
1166    {
1167        let (argc, argv) = unsafe { prepare_call(cx, args.as_ref()) }?;
1168        let env = cx.env().to_raw();
1169        build(cx.env(), |out| unsafe {
1170            sys::fun::construct(out, env, self.to_local(), argc, argv)
1171        })
1172    }
1173}
1174
1175impl JsFunction {
1176    /// Create a [`BindOptions`] builder for calling this function.
1177    ///
1178    /// The builder methods make it convenient to assemble the call from parts:
1179    /// ```
1180    /// # use neon::prelude::*;
1181    /// # fn foo(mut cx: FunctionContext) -> JsResult<JsNumber> {
1182    /// # let parse_int: Handle<JsFunction> = cx.global("parseInt")?;
1183    /// let x: f64 = parse_int
1184    ///     .bind(&mut cx)
1185    ///     .arg("42")?
1186    ///     .call()?;
1187    /// # Ok(cx.number(x))
1188    /// # }
1189    /// ```
1190    pub fn bind<'a, 'cx: 'a>(&self, cx: &'a mut Cx<'cx>) -> BindOptions<'a, 'cx> {
1191        let callee = self.as_value(cx);
1192        BindOptions {
1193            cx,
1194            callee,
1195            this: None,
1196            args: smallvec![],
1197        }
1198    }
1199}
1200
1201impl JsFunction {
1202    /// Create a [`CallOptions`](function::CallOptions) for calling this function.
1203    #[deprecated(since = "TBD", note = "use `JsFunction::bind` instead")]
1204    pub fn call_with<'a, C: Context<'a>>(&self, _cx: &C) -> CallOptions<'a> {
1205        CallOptions {
1206            this: None,
1207            // # Safety
1208            // Only a single context may be used at a time because parent scopes
1209            // are locked with `&mut self`. Therefore, the lifetime of `CallOptions`
1210            // will always be the most narrow scope possible.
1211            callee: Handle::new_internal(unsafe { self.clone() }),
1212            args: smallvec![],
1213        }
1214    }
1215
1216    /// Create a [`ConstructOptions`](function::ConstructOptions) for calling this function
1217    /// as a constructor.
1218    #[deprecated(since = "TBD", note = "use `JsFunction::bind` instead")]
1219    pub fn construct_with<'a, C: Context<'a>>(&self, _cx: &C) -> ConstructOptions<'a> {
1220        ConstructOptions {
1221            // # Safety
1222            // Only a single context may be used at a time because parent scopes
1223            // are locked with `&mut self`. Therefore, the lifetime of `ConstructOptions`
1224            // will always be the most narrow scope possible.
1225            callee: Handle::new_internal(unsafe { self.clone() }),
1226            args: smallvec![],
1227        }
1228    }
1229
1230    /// # Safety
1231    /// The caller must wrap in a `Handle` with an appropriate lifetime.
1232    unsafe fn clone(&self) -> Self {
1233        Self { raw: self.raw }
1234    }
1235}
1236
1237impl Value for JsFunction {}
1238
1239unsafe impl TransparentNoCopyWrapper for JsFunction {
1240    type Inner = raw::Local;
1241
1242    fn into_inner(self) -> Self::Inner {
1243        self.raw
1244    }
1245}
1246
1247impl ValueInternal for JsFunction {
1248    fn name() -> &'static str {
1249        "function"
1250    }
1251
1252    fn is_typeof<Other: Value>(cx: &mut Cx, other: &Other) -> bool {
1253        unsafe { sys::tag::is_function(cx.env().to_raw(), other.to_local()) }
1254    }
1255
1256    fn to_local(&self) -> raw::Local {
1257        self.raw
1258    }
1259
1260    unsafe fn from_local(_env: Env, h: raw::Local) -> Self {
1261        JsFunction { raw: h }
1262    }
1263}
1264
1265#[cfg(feature = "napi-6")]
1266#[cfg_attr(docsrs, doc(cfg(feature = "napi-6")))]
1267#[derive(Debug)]
1268#[repr(transparent)]
1269/// The type of JavaScript
1270/// [`BigInt`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt)
1271/// values.
1272///
1273/// # Example
1274///
1275/// The following shows an example of adding two numbers that exceed
1276/// [`Number.MAX_SAFE_INTEGER`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/MAX_SAFE_INTEGER).
1277///
1278/// ```
1279/// # use neon::{prelude::*, types::JsBigInt};
1280///
1281/// fn add_bigint(mut cx: FunctionContext) -> JsResult<JsBigInt> {
1282///     // Get references to the `BigInt` arguments
1283///     let a = cx.argument::<JsBigInt>(0)?;
1284///     let b = cx.argument::<JsBigInt>(1)?;
1285///
1286///     // Convert the `BigInt` to `i64`
1287///     let a = a.to_i64(&mut cx)
1288///         // On failure, convert err to a `RangeError` exception
1289///         .or_throw(&mut cx)?;
1290///
1291///     let b = b.to_i64(&mut cx).or_throw(&mut cx)?;
1292///     let sum = a + b;
1293///
1294///     // Create a `BigInt` from the `i64` sum
1295///     Ok(JsBigInt::from_i64(&mut cx, sum))
1296/// }
1297/// ```
1298pub struct JsBigInt(raw::Local);
neon/types_impl/mod.rs

neon/types_impl/
mod.rs
