koffi 2.5.0-beta.1 → 2.5.0-beta.2

package/doc/index.rst

@@ -26,6 +26,7 @@ Table of contents
    functions
    types
    pointers
+   unions
    parameters
    callbacks
    misc

package/doc/parameters.md

@@ -9,6 +9,7 @@ By default, Koffi will only forward arguments from Javascript to C. However, man
 For simplicity, and because Javascript only has value semantics for primitive types, Koffi can marshal out (or in/out) two types of parameters:
 
 - [Structs](types.md#struct-types) (to/from JS objects)
+- [Unions](unions.md)
 - [Opaque types](types.md#opaque-types)
 - String buffers
 

package/doc/unions.md

@@ -0,0 +1,187 @@
+# Union values
+
+*New in Koffi 2.5*
+
+## Union definition
+
+You can declare unions with a syntax similar to structs, but with the `koffi.union()` function. This function takes two arguments: the first one is the name of the type, and the second one is an object containing the union member names and types. You can omit the first argument to declare an anonymous union.
+
+The following example illustrates how to declare the same union in C and in JS with Koffi:
+
+```c
+typedef union IntOrDouble {
+    int64_t i;
+    double d;
+} IntOrDouble;
+```
+
+```js
+const IntOrDouble = koffi.union('IntOrDouble', {
+    i: 'int64_t',
+    d: 'double'
+});
+```
+
+## Input unions
+
+### Passing union values to C
+
+You can instantiate an union object with `koffi.Union(type)`. This will create a special object that contains at most one active member.
+
+Once you have created an instance of your union, you can simply set the member with the dot operator as you would with a basic object. Then, simply pass your union value to the C function you wish.
+
+```js
+const U = koffi.union('U', { i: 'int', str: 'char *' });
+
+const DoSomething = lib.func('void DoSomething(const char *type, U u)');
+
+const u1 = new koffi.Union('U'); u1.i = 42;
+const u2 = new koffi.Union('U'); u2.str = 'Hello!';
+
+DoSomething('int', u1);
+DoSomething('string', u2);
+```
+
+For simplicity, Koffi also accepts object literals with one property (no more, no less) setting the corresponding union member. The example belows uses this to simplify the code shown above:
+
+```js
+const U = koffi.union('U', { i: 'int', str: 'char *' });
+
+const DoSomething = lib.func('void DoSomething(const char *type, U u)');
+
+DoSomething('int', { .i = 42 });
+DoSomething('string', { .str = 'Hello!' });
+```
+
+### Win32 example
+
+The following example uses the [SendInput](https://learn.microsoft.com/en-us/windows/win32/api/winuser/nf-winuser-sendinput) Win32 API to emit the Win+D shortcut and hide windows (show the desktop).
+
+```js
+const koffi = require('koffi');
+
+// Win32 type and functions
+
+const user32 = koffi.load('user32.dll');
+
+const INPUT_MOUSE = 0;
+const INPUT_KEYBOARD = 1;
+const INPUT_HARDWARE = 2;
+
+const KEYEVENTF_KEYUP = 0x2;
+const KEYEVENTF_SCANCODE = 0x8;
+
+const VK_LWIN = 0x5B;
+const VK_D = 0x44;
+
+const MOUSEINPUT = koffi.struct('MOUSEINPUT', {
+    dx: 'long',
+    dy: 'long',
+    mouseData: 'uint32_t',
+    dwFlags: 'uint32_t',
+    time: 'uint32_t',
+    dwExtraInfo: 'uintptr_t'
+});
+const KEYBDINPUT = koffi.struct('KEYBDINPUT', {
+    wVk: 'uint16_t',
+    wScan: 'uint16_t',
+    dwFlags: 'uint32_t',
+    time: 'uint32_t',
+    dwExtraInfo: 'uintptr_t'
+});
+const HARDWAREINPUT = koffi.struct('HARDWAREINPUT', {
+    uMsg: 'uint32_t',
+    wParamL: 'uint16_t',
+    wParamH: 'uint16_t'
+});
+
+const INPUT = koffi.struct('INPUT', {
+    type: 'uint32_t',
+    u: koffi.union({
+        mi: MOUSEINPUT,
+        ki: KEYBDINPUT,
+        hi: HARDWAREINPUT
+    })
+});
+
+const SendInput = user32.func('unsigned int __stdcall SendInput(unsigned int cInputs, INPUT *pInputs, int cbSize');
+
+// Show/hide desktop with Win+D shortcut
+
+let events = [
+    make_keyboard_event(VK_WIN, true),
+    make_keyboard_event(VK_D, true),
+    make_keyboard_event(VK_D, false),
+    make_keyboard_event(VK_WIN, false)
+];
+
+SendInput(events.length, events, koffi.sizeof(INPUT));
+
+// Utility
+
+function make_keyboard_event(vk, down) {
+    let event = {
+        type: INPUT_KEYBOARD,
+        u: {
+            ki: {
+                wVk: vk,
+                wScan: 0,
+                dwFlags: down ? 0 : KEYEVENTF_KEYUP,
+                time: 0,
+                dwExtraInfo: 0
+            }
+        }
+    };
+
+    return event;
+}
+```
+
+## Output unions
+
+Unlike structs, Koffi does not know which union member is valid, and it cannot decode it automatically. You can however use special `koffi.Union` objects for output parameters, and decode the memory after the call.
+
+To decode an output union pointer parameter, create a placeholder object with `new koffi.Union(type)` and pass the resulting object to the function.
+
+After the call, you can dereference the member value you want on this object and Koffi will decode it at this moment.
+
+The following example illustrates the use of `koffi.Union()` to decode output unions after the call.
+
+```c
+#include <stdint.h>
+
+typedef union IntOrDouble {
+    int64_t i;
+    double d;
+} IntOrDouble;
+
+void SetUnionInt(int64_t i, IntOrDouble *out)
+{
+    out->i = i;
+}
+
+void SetUnionDouble(double d, IntOrDouble *out)
+{
+    out->d = d;
+}
+```
+
+```js
+const IntOrDouble = koffi.union('IntOrDouble', {
+    i: 'int64_t',
+    d: 'double',
+    raw: koffi.array('uint8_t', 8)
+});
+
+const SetUnionInt = lib.func('void SetUnionInt(int64_t i, _Out_ IntOrDouble *out)');
+const SetUnionDouble = lib.func('void SetUnionDouble(double d, _Out_ IntOrDouble *out)');
+
+let u1 = new koffi.Union('IntOrDouble');
+let u2 = new koffi.Union('IntOrDouble');
+
+SetUnionInt(123, u1);
+SetUnionDouble(123, u2);
+
+console.log(u1.i, '---', u1.raw); // Prints 123 --- Uint8Array(8) [123, 0, 0, 0, 0, 0, 0, 0]
+console.log(u2.d, '---', u2.raw); // Prints 123 --- Uint8Array(8) [0, 0, 0, 0, 0, 0, 69, 64]
+```

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "koffi",
-    "version": "2.5.0-beta.1",
+    "version": "2.5.0-beta.2",
     "stable": "2.4.2",
     "description": "Fast and simple C FFI (foreign function interface) for Node.js",
     "keywords": [

package/src/koffi/src/call.cc

@@ -364,6 +364,11 @@ bool CallData::PushObject(Napi::Object obj, const TypeInfo *type, uint8_t *origi
             MagicUnion *u = MagicUnion::Unwrap(obj);
             const uint8_t *raw = u->GetRaw();
 
+            if (RG_UNLIKELY(u->GetType() != type)) {
+                ThrowError<Napi::TypeError>(env, "Expected union type %1, got %2", type->name, u->GetType()->name);
+                return false;
+            }
+
             // Fast path: encoded value already exists, just copy!
             if (raw) {
                 memcpy(origin, raw, type->size);
@@ -380,12 +385,12 @@ bool CallData::PushObject(Napi::Object obj, const TypeInfo *type, uint8_t *origi
         } else {
             Napi::Array properties = obj.GetPropertyNames();
 
-            if (RG_UNLIKELY(properties.Length() != 1 || !((Napi::Value)properties[0u]).IsString())) {
+            if (RG_UNLIKELY(properties.Length() != 1 || !properties.Get(0u).IsString())) {
                 ThrowError<Napi::Error>(env, "Expected object with single property name for union");
                 return false;
             }
 
-            std::string property = ((Napi::Value)properties[0u]).As<Napi::String>().Utf8Value();
+            std::string property = properties.Get(0u).As<Napi::String>();
 
             members.ptr = std::find_if(type->members.begin(), type->members.end(),
                                        [&](const RecordMember &member) { return TestStr(property.c_str(), member.name); });

package/src/koffi/src/ffi.cc

@@ -134,7 +134,7 @@ static Napi::Value GetSetConfig(const Napi::CallbackInfo &info)
         Napi::Array keys = obj.GetPropertyNames();
 
         for (uint32_t i = 0; i < keys.Length(); i++) {
-            std::string key = ((Napi::Value)keys[i]).As<Napi::String>();
+            std::string key = keys.Get(i).As<Napi::String>();
             Napi::Value value = obj[key];
 
             if (key == "sync_stack_size") {
@@ -243,7 +243,7 @@ static Napi::Value CreateStructType(const Napi::CallbackInfo &info, bool pad)
     for (uint32_t i = 0; i < keys.Length(); i++) {
         RecordMember member = {};
 
-        std::string key = ((Napi::Value)keys[i]).As<Napi::String>();
+        std::string key = keys.Get(i).As<Napi::String>();
         Napi::Value value = obj[key];
         int16_t align = 0;
 
@@ -252,12 +252,12 @@ static Napi::Value CreateStructType(const Napi::CallbackInfo &info, bool pad)
         if (value.IsArray()) {
             Napi::Array array = value.As<Napi::Array>();
 
-            if (array.Length() != 2 || !((Napi::Value)array[0u]).IsNumber()) {
+            if (array.Length() != 2 || !array.Get(0u).IsNumber()) {
                 ThrowError<Napi::Error>(env, "Member specifier array must contain alignement value and type");
                 return env.Null();
             }
 
-            int64_t align64 = ((Napi::Value)array[0u]).As<Napi::Number>().Int64Value();
+            int64_t align64 = array.Get(0u).As<Napi::Number>().Int64Value();
 
             if (!CheckAlignment(align64)) {
                 ThrowError<Napi::Error>(env, "Alignment of member '%1' must be 1, 2, 4 or 8", member.name);
@@ -371,7 +371,7 @@ static Napi::Value CreateUnionType(const Napi::CallbackInfo &info)
     for (uint32_t i = 0; i < keys.Length(); i++) {
         RecordMember member = {};
 
-        std::string key = ((Napi::Value)keys[i]).As<Napi::String>();
+        std::string key = keys.Get(i).As<Napi::String>();
         Napi::Value value = obj[key];
         int16_t align = 0;
 
@@ -380,12 +380,12 @@ static Napi::Value CreateUnionType(const Napi::CallbackInfo &info)
         if (value.IsArray()) {
             Napi::Array array = value.As<Napi::Array>();
 
-            if (array.Length() != 2 || !((Napi::Value)array[0u]).IsNumber()) {
+            if (array.Length() != 2 || !array.Get(0u).IsNumber()) {
                 ThrowError<Napi::Error>(env, "Member specifier array must contain alignement value and type");
                 return env.Null();
             }
 
-            int64_t align64 = ((Napi::Value)array[0u]).As<Napi::Number>().Int64Value();
+            int64_t align64 = array.Get(0u).As<Napi::Number>().Int64Value();
 
             if (!CheckAlignment(align64)) {
                 ThrowError<Napi::Error>(env, "Alignment of member '%1' must be 1, 2, 4 or 8", member.name);
@@ -879,7 +879,7 @@ static bool ParseClassicFunction(Napi::Env env, Napi::String name, Napi::Value r
     uint32_t parameters_len = parameters.Length();
 
     if (parameters_len) {
-        Napi::String str = ((Napi::Value)parameters[parameters_len - 1]).As<Napi::String>();
+        Napi::String str = parameters.Get(parameters_len - 1).As<Napi::String>();
 
         if (str.IsString() && str.Utf8Value() == "...") {
             func->variadic = true;

package/src/koffi/src/util.hh

@@ -48,6 +48,7 @@ public:
 
     MagicUnion(const Napi::CallbackInfo &info);
 
+    const TypeInfo *GetType() { return type; }
     const RecordMember *GetMember() const { return (active_idx >= 0) ? &type->members[active_idx] : nullptr; }
 
     void SetRaw(const uint8_t *ptr);

package/vendor/node-addon-api/CHANGELOG.md

@@ -1,5 +1,36 @@
 # node-addon-api Changelog
 
+## 2023-06-13 Version 7.0.0, @KevinEady
+
+### Notable changes
+
+#### API
+
+- Drop support for Node.js v14.x and v19.x.
+- Ensure native receiver exists when calling instance methods and properties.
+- Fix issue when creating `Napi::Error` instances that wrap primitives values.
+
+#### TEST
+
+- Added tests for `Napi::AsyncProgressQueueWorker<T>` class.
+- Added tests for `Napi::AsyncProgressWorker<T>` class.
+
+### Documentation
+
+- Added documentation for `Napi::Value::IsBigInt()`.
+
+### Commits
+
+* \[[`de5c899400`](https://github.com/nodejs/node-addon-api/commit/de5c899400)] - **doc,chore**: drop support for Node.js v14, v19 (Kevin Eady) [#1324](https://github.com/nodejs/node-addon-api/pull/1324)
+* \[[`3083b7f148`](https://github.com/nodejs/node-addon-api/commit/3083b7f148)] - \[StepSecurity] Apply security best practices (StepSecurity Bot) [#1308](https://github.com/nodejs/node-addon-api/pull/1308)
+* \[[`a198e24a15`](https://github.com/nodejs/node-addon-api/commit/a198e24a15)] - \[Test] Add tests for async progress queue worker (Jack) [#1316](https://github.com/nodejs/node-addon-api/pull/1316)
+* \[[`665f4aa845`](https://github.com/nodejs/node-addon-api/commit/665f4aa845)] - **doc**: add missing Value::IsBigInt (Kevin Eady) [#1319](https://github.com/nodejs/node-addon-api/pull/1319)
+* \[[`358b2d3b4f`](https://github.com/nodejs/node-addon-api/commit/358b2d3b4f)] - **doc**: complete code curly braces  in async\_worker.md (wanlu) [#1317](https://github.com/nodejs/node-addon-api/pull/1317)
+* \[[`858942ce31`](https://github.com/nodejs/node-addon-api/commit/858942ce31)] - **src**: avoid calling into C++ with a null this (Caleb Hearon) [#1313](https://github.com/nodejs/node-addon-api/pull/1313)
+* \[[`64f6515331`](https://github.com/nodejs/node-addon-api/commit/64f6515331)] - **src**: handle failure during error wrap of primitive (Gabriel Schulhof) [#1310](https://github.com/nodejs/node-addon-api/pull/1310)
+* \[[`dfad6b45fe`](https://github.com/nodejs/node-addon-api/commit/dfad6b45fe)] - \[test] Add test coverage for AsyncProgressWorker (Jack) [#1307](https://github.com/nodejs/node-addon-api/pull/1307)
+* \[[`0e34f22839`](https://github.com/nodejs/node-addon-api/commit/0e34f22839)] - **release**: v6.1.0. (Nicola Del Gobbo)
+
 ## 2023-04-20 Version 6.1.0, @NickNaso
 
 ### Notable changes

package/vendor/node-addon-api/README.md

@@ -70,7 +70,7 @@ and node-addon-api.
 - **[Contributors](#contributors)**
 - **[License](#license)**
 
-## **Current version: 6.1.0**
+## **Current version: 7.0.0**
 
 (See [CHANGELOG.md](CHANGELOG.md) for complete Changelog)
 
@@ -83,7 +83,7 @@ This allows addons built with it to run with Node.js versions which support the
 **However** the node-addon-api support model is to support only the active LTS Node.js versions. This means that
 every year there will be a new major which drops support for the Node.js LTS version which has gone out of service.
 
-The oldest Node.js version supported by the current version of node-addon-api is Node.js 14.x.
+The oldest Node.js version supported by the current version of node-addon-api is Node.js 16.x.
 
 ## Setup
   - [Installation and usage](doc/setup.md)
@@ -275,6 +275,7 @@ available:
 ![Node-API v6 Badge](https://github.com/nodejs/abi-stable-node/blob/doc/assets/Node-API%20v6%20Badge.svg)
 ![Node-API v7 Badge](https://github.com/nodejs/abi-stable-node/blob/doc/assets/Node-API%20v7%20Badge.svg)
 ![Node-API v8 Badge](https://github.com/nodejs/abi-stable-node/blob/doc/assets/Node-API%20v8%20Badge.svg)
+![Node-API v9 Badge](https://github.com/nodejs/abi-stable-node/blob/doc/assets/Node-API%20v9%20Badge.svg)
 ![Node-API Experimental Version Badge](https://github.com/nodejs/abi-stable-node/blob/doc/assets/Node-API%20Experimental%20Version%20Badge.svg)
 
 ## **Contributing**

package/vendor/node-addon-api/doc/async_worker.md

@@ -418,6 +418,7 @@ Value Echo(const CallbackInfo& info) {
     EchoWorker* wk = new EchoWorker(cb, in);
     wk->Queue();
     return info.Env().Undefined();
+}
 ```
 
 Using the implementation of a `Napi::AsyncWorker` is straight forward. You only

package/vendor/node-addon-api/doc/creating_a_release.md

@@ -60,3 +60,24 @@ and that the correct version is installed.
 and close the issue.
 
 * Tweet that the release has been created.
+
+## Optional Steps
+
+Depending on circumstances for the release, additional steps may be required to
+support the release process.
+
+### Major Releases to Drop Support Node.js Versions
+
+`node-addon-api` provides support for Node.js versions following the same
+[release schedule](https://nodejs.dev/en/about/releases/): once a Node.js
+version leaves maintenance mode, the next major version of `node-addon-api`
+published will drop support for that version. These are the steps to follow to
+drop support for a Node.js version:
+
+* Update minimum version supported in documentation ([README.md](../README.md))
+
+* Remove from GitHub actions ([ci.yml](../.github/workflows/ci.yml) and
+  [ci-win.yml](../.github/workflows/ci-win.yml))
+
+* Remove from Jenkins CI ([node-test-node-addon-api-LTS versions
+  [Jenkins]](https://ci.nodejs.org/view/x%20-%20Abi%20stable%20module%20API/job/node-test-node-addon-api-LTS%20versions/))

package/vendor/node-addon-api/doc/value.md

@@ -141,6 +141,13 @@ bool Napi::Value::IsArrayBuffer() const;
 Returns `true` if the underlying value is a JavaScript `Napi::ArrayBuffer` or
 `false` otherwise.
 
+```cpp
+bool Napi::Value::IsBigInt() const;
+```
+
+Returns `true` if the underlying value is a JavaScript `Napi::BigInt` or `false`
+otherwise.
+
 ### IsBoolean
 
 ```cpp

package/vendor/node-addon-api/napi-inl.h

@@ -165,7 +165,7 @@ napi_value TemplatedInstanceCallback(napi_env env,
   return details::WrapCallback([&] {
     CallbackInfo cbInfo(env, info);
     T* instance = T::Unwrap(cbInfo.This().As<Object>());
-    return (instance->*UnwrapCallback)(cbInfo);
+    return instance ? (instance->*UnwrapCallback)(cbInfo) : Napi::Value();
   });
 }
 
@@ -175,7 +175,7 @@ napi_value TemplatedInstanceVoidCallback(napi_env env, napi_callback_info info)
   return details::WrapCallback([&] {
     CallbackInfo cbInfo(env, info);
     T* instance = T::Unwrap(cbInfo.This().As<Object>());
-    (instance->*UnwrapCallback)(cbInfo);
+    if (instance) (instance->*UnwrapCallback)(cbInfo);
     return nullptr;
   });
 }
@@ -2937,6 +2937,22 @@ inline Error::Error(napi_env env, napi_value value)
           nullptr};
 
       status = napi_define_properties(env, wrappedErrorObj, 1, &wrapObjFlag);
+#ifdef NODE_API_SWALLOW_UNTHROWABLE_EXCEPTIONS
+      if (status == napi_pending_exception) {
+        // Test if the pending exception was reported because the environment is
+        // shutting down. We assume that a status of napi_pending_exception
+        // coupled with the absence of an actual pending exception means that
+        // the environment is shutting down. If so, we replace the
+        // napi_pending_exception status with napi_ok.
+        bool is_exception_pending = false;
+        status = napi_is_exception_pending(env, &is_exception_pending);
+        if (status == napi_ok && !is_exception_pending) {
+          status = napi_ok;
+        } else {
+          status = napi_pending_exception;
+        }
+      }
+#endif  // NODE_API_SWALLOW_UNTHROWABLE_EXCEPTIONS
       NAPI_FATAL_IF_FAILED(status, "Error::Error", "napi_define_properties");
 
       // Create a reference on the newly wrapped object
@@ -4340,7 +4356,7 @@ inline napi_value InstanceWrap<T>::InstanceVoidMethodCallbackWrapper(
     callbackInfo.SetData(callbackData->data);
     T* instance = T::Unwrap(callbackInfo.This().As<Object>());
     auto cb = callbackData->callback;
-    (instance->*cb)(callbackInfo);
+    if (instance) (instance->*cb)(callbackInfo);
     return nullptr;
   });
 }
@@ -4355,7 +4371,7 @@ inline napi_value InstanceWrap<T>::InstanceMethodCallbackWrapper(
     callbackInfo.SetData(callbackData->data);
     T* instance = T::Unwrap(callbackInfo.This().As<Object>());
     auto cb = callbackData->callback;
-    return (instance->*cb)(callbackInfo);
+    return instance ? (instance->*cb)(callbackInfo) : Napi::Value();
   });
 }
 
@@ -4369,7 +4385,7 @@ inline napi_value InstanceWrap<T>::InstanceGetterCallbackWrapper(
     callbackInfo.SetData(callbackData->data);
     T* instance = T::Unwrap(callbackInfo.This().As<Object>());
     auto cb = callbackData->getterCallback;
-    return (instance->*cb)(callbackInfo);
+    return instance ? (instance->*cb)(callbackInfo) : Napi::Value();
   });
 }
 
@@ -4383,7 +4399,7 @@ inline napi_value InstanceWrap<T>::InstanceSetterCallbackWrapper(
     callbackInfo.SetData(callbackData->data);
     T* instance = T::Unwrap(callbackInfo.This().As<Object>());
     auto cb = callbackData->setterCallback;
-    (instance->*cb)(callbackInfo, callbackInfo[0]);
+    if (instance) (instance->*cb)(callbackInfo, callbackInfo[0]);
     return nullptr;
   });
 }
@@ -4395,7 +4411,7 @@ inline napi_value InstanceWrap<T>::WrappedMethod(
   return details::WrapCallback([&] {
     const CallbackInfo cbInfo(env, info);
     T* instance = T::Unwrap(cbInfo.This().As<Object>());
-    (instance->*method)(cbInfo, cbInfo[0]);
+    if (instance) (instance->*method)(cbInfo, cbInfo[0]);
     return nullptr;
   });
 }

package/vendor/node-addon-api/package.json

@@ -399,6 +399,14 @@
     {
       "name": "Feng Yu",
       "url": "https://github.com/F3n67u"
+    },
+    {
+      "name": "wanlu wang",
+      "url": "https://github.com/wanlu"
+    },
+    {
+      "name": "Caleb Hearon",
+      "url": "https://github.com/chearon"
     }
   ],
   "description": "Node.js API (Node-API)",
@@ -459,6 +467,6 @@
     "lint:fix": "node tools/clang-format --fix && node tools/eslint-format --fix"
   },
   "pre-commit": "lint",
-  "version": "6.1.0",
+  "version": "7.0.0",
   "support": true
 }