koffi 2.14.0-beta.3 → 2.14.0

package/CHANGELOG.md

@@ -5,6 +5,17 @@
 
 ## Koffi 2
 
+### Koffi 2.14
+
+#### Koffi 2.14.0
+
+*Released on 2025-08-17*
+
+- Improve support for structs with [flexible array member](input#flexible-arrays)
+- Automatically encode/decode dynamic arrays pointers when length is known though struct member
+- Fix parser crash when direction qualifier is followed by unknown type
+- Add missing TypeScript types and arguments
+
 ### Koffi 2.13
 
 #### Koffi 2.13.0

package/doc/pages/input.md

@@ -396,6 +396,72 @@ Koffi can also convert JS strings to fixed-sized arrays in the following cases:
 
 The reverse case is also true, Koffi can convert a C fixed-size buffer to a JS string. This happens by default for char, char16_t and char32_t arrays, but you can also explicitly ask for this with the `String` array hint (e.g. `koffi.array('char', 8, 'String')`).
 
+## Flexible arrays
+
+*Added in Koffi 2.14.0*
+
+C structs ending with a flexible array member are often used for variable-sized structs, and are generally paired with dynamic memory allocation. In many cases, the number of elements is described by another struct member.
+
+Use `koffi.array(type, countedBy, maxLen)` to make a flexible array type, for which the array length is determined by the struct member indicated by the `countedBy` parameter. Flexible array types can only be used as the last member of a struct, as shown below:
+
+```js
+const FlexibleArray = koffi.struct('FlexibleArray', {
+    count: 'size_t',
+    numbers: koffi.array('int', 'count', 128)
+});
+````
+
+For various reasons, Koffi requires you to specify an upper bound (`maxLen`) for the number of elements in the flexible array member.
+
+> [!WARNING]
+> Also, unlike C flexible arrays, the struct size will expand to accomodate the maximum size of the flexible array.
+
+The following example illustrates how to use a flexible array API in C from Koffi.
+
+```c
+// Build with: clang -fPIC -o flexible.so -shared flexible.c -Wall -O2
+
+#include <stddef.h>
+
+struct FlexibleArray {
+    size_t count;
+    int numbers[];
+};
+
+void AppendValues(struct FlexibleArray *arr, size_t count, int start, int step)
+{
+    for (size_t i = 0; i < count; i++) {
+        arr->numbers[arr->count + i] = start + i * step;
+    }
+    arr->count += count;
+}
+```
+
+```js
+// ES6 syntax: import koffi from 'koffi';
+const koffi = require('koffi');
+
+const lib = koffi.load('./flexible.so');
+
+const FlexibleArray = koffi.struct('FlexibleArray', {
+    count: 'size_t',
+    numbers: koffi.array('int', 'count', 256, 'Array')
+});
+
+const AppendValues = lib.func('void AppendValues(_Inout_ FlexibleArray *arr, int count, int start, int step)');
+
+let array = { count: 0, numbers: [] };
+
+AppendValues(array, 5, 1, 1);
+console.log(array); // Prints { count: 5, numbers: [1, 2, 3, 4, 5] }
+
+AppendValues(array, 3, 10, 2);
+console.log(array); // Prints { count: 8, numbers: [1, 2, 3, 4, 5, 10, 12, 14] }
+```
+
+> [!NOTE]
+> This is frequently used in the Win32 API, an exemple of this is [AllocateAndInitializeSid()](https://learn.microsoft.com/windows/win32/api/securitybaseapi/nf-securitybaseapi-allocateandinitializesid).
+
 ## Dynamic arrays (pointers)
 
 In C, dynamically-sized arrays are usually passed around as pointers. Read more about [array pointers](pointers#dynamic-arrays) in the relevant section.

package/index.d.ts

@@ -105,7 +105,6 @@ export class Union {
 }
 
 export function array(ref: TypeSpec, len: number, hint?: ArrayHint | null): IKoffiCType;
-export function array(ref: TypeSpec, countedBy: string, hint?: ArrayHint | null): IKoffiCType;
 export function array(ref: TypeSpec, countedBy: string, maxLen: number, hint?: ArrayHint | null): IKoffiCType;
 
 export function opaque(name: string | null | undefined): IKoffiCType;

package/index.js

@@ -4,9 +4,9 @@ var __commonJS = (cb, mod3) => function __require() {
   return mod3 || (0, cb[__getOwnPropNames(cb)[0]])((mod3 = { exports: {} }).exports, mod3), mod3.exports;
 };
 
-// bin/Koffi/package/src/cnoke/src/tools.js
+// ../../../bin/Koffi/package/src/cnoke/src/tools.js
 var require_tools = __commonJS({
-  "bin/Koffi/package/src/cnoke/src/tools.js"(exports2, module2) {
+  "../../../bin/Koffi/package/src/cnoke/src/tools.js"(exports2, module2) {
     "use strict";
     var crypto = require("crypto");
     var fs2 = require("fs");
@@ -397,12 +397,12 @@ var require_tools = __commonJS({
   }
 });
 
-// bin/Koffi/package/src/koffi/package.json
+// ../../../bin/Koffi/package/src/koffi/package.json
 var require_package = __commonJS({
-  "bin/Koffi/package/src/koffi/package.json"(exports2, module2) {
+  "../../../bin/Koffi/package/src/koffi/package.json"(exports2, module2) {
     module2.exports = {
       name: "koffi",
-      version: "2.14.0-beta.3",
+      version: "2.14.0",
       description: "Fast and simple C FFI (foreign function interface) for Node.js",
       keywords: [
         "foreign",
@@ -443,9 +443,9 @@ var require_package = __commonJS({
   }
 });
 
-// bin/Koffi/package/src/koffi/src/init.js
+// ../../../bin/Koffi/package/src/koffi/src/init.js
 var require_init = __commonJS({
-  "bin/Koffi/package/src/koffi/src/init.js"(exports, module) {
+  "../../../bin/Koffi/package/src/koffi/src/init.js"(exports, module) {
     var fs = require("fs");
     var path = require("path");
     var util = require("util");
@@ -528,7 +528,7 @@ var require_init = __commonJS({
   }
 });
 
-// bin/Koffi/package/src/koffi/index.js
+// ../../../bin/Koffi/package/src/koffi/index.js
 var { detect: detect2, init: init2 } = require_init();
 var triplet2 = detect2();
 var native2 = null;

package/indirect.js

@@ -4,9 +4,9 @@ var __commonJS = (cb, mod3) => function __require() {
   return mod3 || (0, cb[__getOwnPropNames(cb)[0]])((mod3 = { exports: {} }).exports, mod3), mod3.exports;
 };
 
-// bin/Koffi/package/src/cnoke/src/tools.js
+// ../../../bin/Koffi/package/src/cnoke/src/tools.js
 var require_tools = __commonJS({
-  "bin/Koffi/package/src/cnoke/src/tools.js"(exports2, module2) {
+  "../../../bin/Koffi/package/src/cnoke/src/tools.js"(exports2, module2) {
     "use strict";
     var crypto = require("crypto");
     var fs2 = require("fs");
@@ -397,12 +397,12 @@ var require_tools = __commonJS({
   }
 });
 
-// bin/Koffi/package/src/koffi/package.json
+// ../../../bin/Koffi/package/src/koffi/package.json
 var require_package = __commonJS({
-  "bin/Koffi/package/src/koffi/package.json"(exports2, module2) {
+  "../../../bin/Koffi/package/src/koffi/package.json"(exports2, module2) {
     module2.exports = {
       name: "koffi",
-      version: "2.14.0-beta.3",
+      version: "2.14.0",
       description: "Fast and simple C FFI (foreign function interface) for Node.js",
       keywords: [
         "foreign",
@@ -443,9 +443,9 @@ var require_package = __commonJS({
   }
 });
 
-// bin/Koffi/package/src/koffi/src/init.js
+// ../../../bin/Koffi/package/src/koffi/src/init.js
 var require_init = __commonJS({
-  "bin/Koffi/package/src/koffi/src/init.js"(exports, module) {
+  "../../../bin/Koffi/package/src/koffi/src/init.js"(exports, module) {
     var fs = require("fs");
     var path = require("path");
     var util = require("util");
@@ -528,7 +528,7 @@ var require_init = __commonJS({
   }
 });
 
-// bin/Koffi/package/src/koffi/indirect.js
+// ../../../bin/Koffi/package/src/koffi/indirect.js
 var { detect: detect2, init: init2 } = require_init();
 var triplet2 = detect2();
 var mod2 = init2(triplet2, null);

package/package.json

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

package/src/core/base/base.cc

@@ -854,6 +854,31 @@ TimeSpec DecomposeTimeLocal(int64_t time)
     return spec;
 }
 
+int64_t ComposeTimeUTC(const TimeSpec &spec)
+{
+    RG_ASSERT(!spec.offset);
+
+    struct tm ti = {};
+
+    ti.tm_year = spec.year - 1900;
+    ti.tm_mon = spec.month - 1;
+    ti.tm_mday = spec.day;
+    ti.tm_hour = spec.hour;
+    ti.tm_min = spec.min;
+    ti.tm_sec = spec.sec;
+
+#if defined(_WIN32)
+    int64_t time = (int64_t)_mkgmtime64(&ti);
+#else
+    int64_t time = (int64_t)timegm(&ti);
+#endif
+
+    time *= 1000;
+    time += spec.msec;
+
+    return time;
+}
+
 // ------------------------------------------------------------------------
 // Strings
 // ------------------------------------------------------------------------

package/src/core/base/base.hh

@@ -3669,6 +3669,7 @@ struct TimeSpec {
 
 TimeSpec DecomposeTimeUTC(int64_t time);
 TimeSpec DecomposeTimeLocal(int64_t time);
+int64_t ComposeTimeUTC(const TimeSpec &spec);
 
 // ------------------------------------------------------------------------
 // Format

package/src/koffi/src/call.cc

@@ -517,7 +517,7 @@ bool CallData::PushObject(Napi::Object obj, const TypeInfo *type, uint8_t *origi
         RG_UNREACHABLE();
     }
 
-    memset(origin, 0, type->size);
+    MemSet(origin, 0, type->size);
 
     for (Size i = 0; i < members.len; i++) {
         const RecordMember &member = members[i];

package/src/koffi/src/call.hh

@@ -156,7 +156,7 @@ inline bool CallData::AllocStack(Size size, Size align, T **out_ptr)
     }
 
 #if defined(RG_DEBUG)
-    memset(ptr, 0, delta);
+    MemSet(ptr, 0, delta);
 #endif
 
     mem->stack.len -= delta;
@@ -173,7 +173,7 @@ inline T *CallData::AllocHeap(Size size, Size align)
 
     if (size < 4096 && delta <= mem->heap.len) [[likely]] {
 #if defined(RG_DEBUG)
-        memset(mem->heap.ptr, 0, (size_t)delta);
+        MemSet(mem->heap.ptr, 0, delta);
 #endif
 
         mem->heap.ptr += delta;

package/src/koffi/src/ffi.cc

@@ -986,7 +986,11 @@ static Napi::Value CreateArrayType(const Napi::CallbackInfo &info)
         return env.Null();
     }
     if (!info[1 + dynamic].IsNumber()) {
-        ThrowError<Napi::TypeError>(env, "Unexpected %1 value for %2, expected integer", GetValueType(instance, info[1]), dynamic ? "maxLen" : "len");
+        if (info.Length() == 2 && info[1].IsString()) {
+            ThrowError<Napi::TypeError>(env, "Missing maxLen argument");
+        } else {
+            ThrowError<Napi::TypeError>(env, "Unexpected %1 value for %2, expected integer", GetValueType(instance, info[1]), dynamic ? "maxLen" : "len");
+        }
         return env.Null();
     }
 
@@ -1003,7 +1007,7 @@ static Napi::Value CreateArrayType(const Napi::CallbackInfo &info)
 
     TypeInfo *type = nullptr;
 
-    if (info.Length() >= 3 + dynamic && !IsNullOrUndefined(info[2 + dynamic])) {
+    if (info.Length() >= 3u + dynamic && !IsNullOrUndefined(info[2 + dynamic])) {
         if (!info[2 + dynamic].IsString()) {
             ThrowError<Napi::TypeError>(env, "Unexpected %1 value for hint, expected string", GetValueType(instance, info[2]));
             return env.Null();
@@ -2087,7 +2091,7 @@ static Napi::Value DecodeValue(const Napi::CallbackInfo &info)
     Napi::Env env = info.Env();
 
     bool has_offset = (info.Length() >= 2 && info[1].IsNumber());
-    bool has_len = (info.Length() >= 3u + has_offset && info[2u + has_offset].IsNumber());
+    bool has_len = (info.Length() >= 3u + has_offset && info[2 + has_offset].IsNumber());
 
     if (info.Length() < 2u + has_offset) [[unlikely]] {
         ThrowError<Napi::TypeError>(env, "Expected %1 to 4 arguments, got %2", 2 + has_offset, info.Length());
@@ -2102,7 +2106,7 @@ static Napi::Value DecodeValue(const Napi::CallbackInfo &info)
     int64_t offset = has_offset ? info[1].As<Napi::Number>().Int64Value() : 0;
 
     if (has_len) {
-        Size len = info[2u + has_offset].As<Napi::Number>();
+        Size len = info[2 + has_offset].As<Napi::Number>();
 
         Napi::Value ret = Decode(value, offset, type, &len);
         return ret;
@@ -2164,7 +2168,7 @@ static Napi::Value EncodeValue(const Napi::CallbackInfo &info)
     Napi::Env env = info.Env();
 
     bool has_offset = (info.Length() >= 2 && info[1].IsNumber());
-    bool has_len = (info.Length() >= 4u + has_offset && info[3u + has_offset].IsNumber());
+    bool has_len = (info.Length() >= 4u + has_offset && info[3 + has_offset].IsNumber());
 
     if (info.Length() < 3u + has_offset) [[unlikely]] {
         ThrowError<Napi::TypeError>(env, "Expected %1 to 5 arguments, got %2", 3 + has_offset, info.Length());
@@ -2177,10 +2181,10 @@ static Napi::Value EncodeValue(const Napi::CallbackInfo &info)
 
     Napi::Value ref = info[0];
     int64_t offset = has_offset ? info[1].As<Napi::Number>().Int64Value() : 0;
-    Napi::Value value = info[2u + has_offset];
+    Napi::Value value = info[2 + has_offset];
 
     if (has_len) {
-        Size len = info[3u + has_offset].As<Napi::Number>();
+        Size len = info[3 + has_offset].As<Napi::Number>();
 
         if (!Encode(ref, offset, value, type, &len))
             return env.Null();