koffi 2.14.0-beta.3 → 2.14.1

package/CHANGELOG.md

@@ -5,6 +5,24 @@
 
 ## Koffi 2
 
+### Koffi 2.14
+
+#### Koffi 2.14.1
+
+*Released on 2025-09-13*
+
+- Recompile Linux (musl) ARM64 prebuild with Alpine 3.20 (instead of Alpine edge)
+- Clean up redundant code paths for handling string arguments
+
+#### 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
@@ -969,7 +987,6 @@ This entry documents changes since version 1.1.0.
 
 The following features and improvements are planned, not necessarily in that order:
 
-- Port Koffi to Loong64 ISA and ABI
 - Port Koffi to PowerPC (POWER9+) ISA and ABI
 - Optimize passing of structs and arrays (with auto-generated JS)
 - Automate Windows/AArch64 (qemu) and macOS/AArch64 (how? ... thanks Apple) tests

package/README.md

@@ -4,7 +4,7 @@ Koffi is a fast and easy-to-use C FFI module for Node.js, featuring:
 
 * Low-overhead and fast performance (see [benchmarks](https://koffi.dev/benchmarks))
 * Support for primitive and aggregate data types (structs and fixed-size arrays), both by reference (pointer) and by value
-* Javascript functions can be used as C callbacks (since 1.2.0)
+* Javascript functions can be used as C callbacks
 * Well-tested code base for popular OS/architecture combinations
 
 The following combinations of OS and architectures __are officially supported and tested__ at the moment:

package/doc/pages/index.md

@@ -1,16 +1,51 @@
-# Koffi
+# Overview
 
 Koffi is a **fast and easy-to-use C FFI module for Node.js**, featuring:
 
 * Low-overhead and fast performance (see [benchmarks](benchmarks))
 * Support for primitive and aggregate data types (structs and fixed-size arrays), both by reference (pointer) and by value
-* Javascript functions can be used as C callbacks (since 1.2.0)
-* Well-tested code base for [popular OS/architecture combinations](platforms)
+* Javascript functions can be used as C callbacks
+* Well-tested code base for popular OS/architecture combinations
 
-Koffi requires a recent [Node.js](https://nodejs.org/) version with N-API version 8 support, see [this page](platforms) for more information.
+I work on this project on my spare time, if you like this project, consider supporting me:
+
+<p style="display: flex; gap: 2em; justify-content: center;">
+     <a href="https://buymeacoffee.com/koromix" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/default-orange.png" alt="Buy Me A Coffee" height="41" width="174" style="border-radius: 12px;"></a>
+</p>
+
+Koffi requires [Node.js](https://nodejs.org/) version 16 or later. Use [NVM](https://github.com/nvm-sh/nvm) to install more recent Node versions on older Linux distributions.
+
+The following combinations of OS and architectures __are officially supported and tested__ at the moment:
+
+ISA / OS           | Windows | Linux (glibc) | Linux (musl) | macOS | FreeBSD | OpenBSD
+------------------ | ------- | ------------- | ------------ | ----- | ------- | -------
+x86 (IA32) [^2]    | ✅       | ✅             | 🟨            | ⬜️    | ✅       | ✅
+x86_64 (AMD64)     | ✅       | ✅             | ✅            | ✅    | ✅       | ✅
+ARM32 LE [^3]      | ⬜️       | ✅             | 🟨            | ⬜️    | 🟨       | 🟨
+ARM64 (AArch64) LE | ✅       | ✅             | ✅            | ✅    | ✅       | 🟨
+RISC-V 64 [^4]     | ⬜️       | ✅             | 🟨            | ⬜️    | 🟨       | 🟨
+LoongArch64        | ⬜️       | ✅             | 🟨            | ⬜️    | 🟨       | 🟨
+
+<div class="legend">✅ Yes | 🟨 Probably | ⬜️ Not applicable</div>
+
+[^2]: The following call conventions are supported for forward calls: cdecl, stdcall, MS fastcall, thiscall. Only cdecl and stdcall can be used for C to JS callbacks.
+[^3]: The prebuilt binary uses the hard float ABI and expects a VFP coprocessor. Build from source to use Koffi with a different ABI (softfp, soft).
+[^4]: The prebuilt binary uses the LP64D (double-precision float) ABI. The LP64 ABI is supported in theory if you build Koffi from source (untested), the LP64F ABI is not supported.
+
+For all fully supported platforms (green check marks), a prebuilt binary is included in the NPM package which means you can install Koffi without a C++ compiler.
+
+# Source code
 
 The source code is available here: https://github.com/Koromix/rygel/ (in the *src/koffi* subdirectory).
 
+> [!NOTE]
+> Most of my projects live in a single repository (or monorepo), which have two killer features for me:
+>
+> - Cross-project refactoring
+> - Simplified dependency management
+>
+> You can find a more detailed rationale here: https://danluu.com/monorepo/
+
 New releases are frequent, look at the [changelog](changelog) for more information.
 
 # License
@@ -18,3 +53,7 @@ New releases are frequent, look at the [changelog](changelog) for more informati
 This program is free software: you can redistribute it and/or modify it under the terms of the **MIT License**.
 
 Find more information here: https://choosealicense.com/licenses/mit/
+
+<style>
+     table td:not(:first-child) { text-align: center; }
+</style>

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/doc/pages/platforms.md

@@ -14,25 +14,14 @@ Use [NVM](https://github.com/nvm-sh/nvm) to install more recent Node versions on
 
 The following combinations of OS and architectures __are officially supported and tested__ at the moment:
 
-ISA / OS           | Windows | Linux (glibc) | Linux (musl)
------------------- | ------- | ------------- | ------------
-x86 (IA32) [^1]    | ✅      | ✅            | 🟨
-x86_64 (AMD64)     | ✅      | ✅            | ✅
-ARM32 LE [^2]      | ⬜️      | ✅            | 🟨
-ARM64 (AArch64) LE | ✅      | ✅            | ✅
-RISC-V 64 [^3]     | ⬜️      | ✅            | 🟨
-LoongArch64        | ⬜️      | ✅            | 🟨
-
-<div class="legend">✅ Yes | 🟨 Probably | ⬜️ Not applicable</div>
-
-ISA / OS           | macOS | FreeBSD     | OpenBSD
------------------- | ----- | ----------- | --------
-x86 (IA32) [^1]    | ⬜️    | ✅          | ✅
-x86_64 (AMD64)     | ✅    | ✅          | ✅
-ARM32 LE [^2]      | ⬜️    | 🟨          | 🟨
-ARM64 (AArch64) LE | ✅    | ✅          | 🟨
-RISC-V 64 [^3]     | ⬜️    | 🟨          | 🟨
-LoongArch64        | ⬜️    | 🟨          | 🟨
+ISA / OS           | Windows     | Linux (glibc) | Linux (musl) | macOS       | FreeBSD     | OpenBSD
+------------------ | ----------- | ------------- | ------------ | ----------- | ----------- | --------
+x86 (IA32) [^1]    | ✅ Yes      | ✅ Yes        | 🟨 Probably  | ⬜️ *N/A*    | ✅ Yes      | ✅ Yes
+x86_64 (AMD64)     | ✅ Yes      | ✅ Yes        | ✅ Yes       | ✅ Yes      | ✅ Yes      | ✅ Yes
+ARM32 LE [^2]      | ⬜️ *N/A*    | ✅ Yes        | 🟨 Probably  | ⬜️ *N/A*    | 🟨 Probably | 🟨 Probably
+ARM64 (AArch64) LE | ✅ Yes      | ✅ Yes        | ✅ Yes       | ✅ Yes      | ✅ Yes      | 🟨 Probably
+RISC-V 64 [^3]     | ⬜️ *N/A*    | ✅ Yes        | 🟨 Probably  | ⬜️ *N/A*    | 🟨 Probably | 🟨 Probably
+LoongArch64        | ⬜️ *N/A*    | ✅ Yes        | 🟨 Probably  | ⬜️ *N/A*    | 🟨 Probably | 🟨 Probably
 
 <div class="legend">✅ Yes | 🟨 Probably | ⬜️ Not applicable</div>
 

package/doc/pages.ini

@@ -2,13 +2,6 @@
 Title = Koffi
 Menu = Overview
 Description = Koffi presentation and features
-ToC = Off
-Template = templates/page.html
-
-[pages/platforms.md]
-Title = Requirements | Koffi
-Menu = Documentation / Requirements
-Description = Supported systemd and architectures
 Template = templates/page.html
 
 [pages/start.md]

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.1",
       description: "Fast and simple C FFI (foreign function interface) for Node.js",
       keywords: [
         "foreign",
@@ -438,14 +438,15 @@ var require_package = __commonJS({
         node: 16,
         napi: 8,
         require: "./index.js"
-      }
+      },
+      funding: "https://buymeacoffee.com/koromix"
     };
   }
 });
 
-// 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 +529,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.1",
       description: "Fast and simple C FFI (foreign function interface) for Node.js",
       keywords: [
         "foreign",
@@ -438,14 +438,15 @@ var require_package = __commonJS({
         node: 16,
         napi: 8,
         require: "./index.js"
-      }
+      },
+      funding: "https://buymeacoffee.com/koromix"
     };
   }
 });
 
-// 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 +529,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.1",
     "description": "Fast and simple C FFI (foreign function interface) for Node.js",
     "keywords": [
         "foreign",
@@ -33,5 +33,6 @@
         "node": 16,
         "napi": 8,
         "require": "./index.js"
-    }
+    },
+    "funding": "https://buymeacoffee.com/koromix"
 }

package/src/cnoke/src/builder.js

@@ -309,8 +309,7 @@ function Builder(config = {}) {
         tools.unlink_recursive(build_dir);
     };
 
-    function find_parent_directory(dirname, basename)
-    {
+    function find_parent_directory(dirname, basename) {
         if (process.platform == 'win32')
             dirname = dirname.replace(/\\/g, '/');