feat(napi): allow &External to be created from napi value (#2037)

crates/napi/src/bindgen_runtime/js_values/external.rs

@@ -3,7 +3,7 @@ use std::{
   ops::{Deref, DerefMut},
 };
 
-use super::{FromNapiMutRef, FromNapiRef, ToNapiValue, TypeName, ValidateNapiValue};
+use super::{FromNapiMutRef, FromNapiRef, FromNapiValue, ToNapiValue, TypeName, ValidateNapiValue};
 use crate::{check_status, sys, Error, Status};
 
 #[repr(C)]
@@ -96,6 +96,18 @@ impl<T: 'static> FromNapiRef for External<T> {
   }
 }
 
+impl<T: 'static> FromNapiValue for &mut External<T> {
+  unsafe fn from_napi_value(env: sys::napi_env, napi_val: sys::napi_value) -> crate::Result<Self> {
+    External::from_napi_mut_ref(env, napi_val)
+  }
+}
+
+impl<T: 'static> FromNapiValue for &External<T> {
+  unsafe fn from_napi_value(env: sys::napi_env, napi_val: sys::napi_value) -> crate::Result<Self> {
+    External::from_napi_ref(env, napi_val)
+  }
+}
+
 impl<T: 'static> AsRef<T> for External<T> {
   fn as_ref(&self) -> &T {
     &self.obj

examples/napi/__tests__/__snapshots__/typegen.spec.ts.md

@@ -372,6 +372,8 @@ Generated by [AVA](https://avajs.dev).
     ␊
     export function createObjWithProperty(): { value: ArrayBuffer, get getter(): number }␊
     ␊
+    export function createOptionalExternal(size?: number | undefined | null): ExternalObject<number> | null␊
+    ␊
     export function createReferenceOnFunction(cb: () => void): Promise<void>␊
     ␊
     export function createSymbol(): symbol␊
@@ -466,6 +468,8 @@ Generated by [AVA](https://avajs.dev).
     /** Gets some numbers */␊
     export function getNums(): Array<number>␊
     ␊
+    export function getOptionalExternal(external?: ExternalObject<number> | undefined | null): number | null␊
+    ␊
     export function getPackageJsonName(packageJson: PackageJson): string␊
     ␊
     export function getStrFromObject(): void␊
@@ -502,6 +506,8 @@ Generated by [AVA](https://avajs.dev).
     ␊
     export function mutateExternal(external: ExternalObject<number>, newVal: number): void␊
     ␊
+    export function mutateOptionalExternal(external: ExternalObject<number> | undefined | null, newVal: number): void␊
+    ␊
     export function mutateTypedArray(input: Float32Array): void␊
     ␊
     export interface NotUseNullableStruct {␊

examples/napi/__tests__/values.spec.ts

@@ -172,6 +172,9 @@ import {
   type AliasedStruct,
   returnObjectOnlyToJs,
   buildThreadsafeFunctionFromFunction,
+  createOptionalExternal,
+  getOptionalExternal,
+  mutateOptionalExternal,
 } from '../index.cjs'
 
 import { test } from './test.framework.js'
@@ -908,6 +911,22 @@ test('external', (t) => {
   t.is(e?.message, '<u32> on `External` is not the type of wrapped object')
 })
 
+test('optional external', (t) => {
+  const FX = 42
+  const extEmpty = createOptionalExternal()
+  t.is(getOptionalExternal(extEmpty), null)
+  const ext = createOptionalExternal(FX)
+  t.is(getOptionalExternal(ext), FX)
+  mutateOptionalExternal(ext, FX + 1)
+  t.is(getOptionalExternal(ext), FX + 1)
+  // @ts-expect-error
+  t.throws(() => getOptionalExternal({}))
+  const ext2 = createExternalString('wtf')
+  // @ts-expect-error
+  const e = t.throws(() => getOptionalExternal(ext2))
+  t.is(e?.message, '<u32> on `External` is not the type of wrapped object')
+})
+
 test('should be able to run script', async (t) => {
   t.is(runScript(`1 + 1`), 2)
   t.is(await runScript(`Promise.resolve(1)`), 1)

examples/napi/index.cjs

@@ -453,6 +453,7 @@ module.exports.createExternalTypedArray = nativeBinding.createExternalTypedArray
 module.exports.createObj = nativeBinding.createObj
 module.exports.createObjectWithClassField = nativeBinding.createObjectWithClassField
 module.exports.createObjWithProperty = nativeBinding.createObjWithProperty
+module.exports.createOptionalExternal = nativeBinding.createOptionalExternal
 module.exports.createReferenceOnFunction = nativeBinding.createReferenceOnFunction
 module.exports.createSymbol = nativeBinding.createSymbol
 module.exports.createSymbolFor = nativeBinding.createSymbolFor
@@ -487,6 +488,7 @@ module.exports.getNestedNumArr = nativeBinding.getNestedNumArr
 module.exports.getNull = nativeBinding.getNull
 module.exports.getNumArr = nativeBinding.getNumArr
 module.exports.getNums = nativeBinding.getNums
+module.exports.getOptionalExternal = nativeBinding.getOptionalExternal
 module.exports.getPackageJsonName = nativeBinding.getPackageJsonName
 module.exports.getStrFromObject = nativeBinding.getStrFromObject
 module.exports.getterFromObj = nativeBinding.getterFromObj
@@ -501,6 +503,7 @@ module.exports.Kind = nativeBinding.Kind
 module.exports.listObjKeys = nativeBinding.listObjKeys
 module.exports.mapOption = nativeBinding.mapOption
 module.exports.mutateExternal = nativeBinding.mutateExternal
+module.exports.mutateOptionalExternal = nativeBinding.mutateOptionalExternal
 module.exports.mutateTypedArray = nativeBinding.mutateTypedArray
 module.exports.objectGetNamedPropertyShouldPerformTypecheck = nativeBinding.objectGetNamedPropertyShouldPerformTypecheck
 module.exports.optionEnd = nativeBinding.optionEnd

examples/napi/index.d.cts

@@ -362,6 +362,8 @@ export function createObjectWithClassField(): ObjectFieldClassInstance
 
 export function createObjWithProperty(): { value: ArrayBuffer, get getter(): number }
 
+export function createOptionalExternal(size?: number | undefined | null): ExternalObject<number> | null
+
 export function createReferenceOnFunction(cb: () => void): Promise<void>
 
 export function createSymbol(): symbol
@@ -456,6 +458,8 @@ export function getNumArr(): number[]
 /** Gets some numbers */
 export function getNums(): Array<number>
 
+export function getOptionalExternal(external?: ExternalObject<number> | undefined | null): number | null
+
 export function getPackageJsonName(packageJson: PackageJson): string
 
 export function getStrFromObject(): void
@@ -492,6 +496,8 @@ export function mapOption(val?: number | undefined | null): number | null
 
 export function mutateExternal(external: ExternalObject<number>, newVal: number): void
 
+export function mutateOptionalExternal(external: ExternalObject<number> | undefined | null, newVal: number): void
+
 export function mutateTypedArray(input: Float32Array): void
 
 export interface NotUseNullableStruct {

examples/napi/src/external.rs

@@ -19,3 +19,20 @@ pub fn get_external(external: &External<u32>) -> u32 {
 pub fn mutate_external(external: &mut External<u32>, new_val: u32) {
   **external = new_val;
 }
+
+#[napi]
+pub fn create_optional_external(size: Option<u32>) -> Option<External<u32>> {
+  size.map(External::new)
+}
+
+#[napi]
+pub fn get_optional_external(external: Option<&External<u32>>) -> Option<u32> {
+  external.map(|external| **external)
+}
+
+#[napi]
+pub fn mutate_optional_external(external: Option<&mut External<u32>>, new_val: u32) {
+  if let Some(external) = external {
+    **external = new_val;
+  }
+}