koffi 3.0.0-rc.2 → 3.0.1

package/CHANGELOG.md

@@ -7,6 +7,14 @@
 
 ### Koffi 3.0
 
+#### Koffi 3.0.1
+
+*Released on 2026-05-20*
+
+- Fix error when importing default koffi module from TypeScript
+- Optimize creation of new JS objects for return values
+- Adjust build flags for performance
+
 #### Koffi 3.0.0
 
 *Released on 2026-05-16*
@@ -22,10 +30,10 @@
   * Use `koffi.type()` to resolve type specifiers (strings or objects) to type objects
   * Access type information directly on type objects without `koffi.introspect()`
 - Replace use of externals with BigInt pointers
-- Support ESM and CJS module types
 
 **Other changes:**
 
+- Support ESM and CJS module types
 - Add `koffi.enumeration()` to create [enum types](input#enum-types)
 - Add fast decode functions for integers, floats and strings
 - Use proper types for various objects and handles:

package/README.md

@@ -1,9 +1,10 @@
 # Overview
 
-Koffi is a fast and easy-to-use C FFI module for Node.js, featuring:
+Koffi is a fast and easy-to-use dynamic C FFI module for Node.js, featuring:
 
-* Low-overhead and fast performance (see [benchmarks](https://koffi.dev/benchmarks))
+* Low-overhead compared to a static Node-API implementation (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
+* Support for synchronous and asynchronous calls
 * Javascript functions can be used as C callbacks
 * Well-tested code base for popular OS/architecture combinations
 
@@ -14,11 +15,11 @@ ISA / OS           | Windows     | Linux/glibc | Linux/musl  | macOS       | Fre
 x86 (IA32) [^1]    | ✅ Yes      | ✅ Yes      | 🟨 Probably | ⬜️ *N/A*    | ✅ Yes      | ✅ Yes
 x86_64 (AMD64)     | ✅ Yes      | ✅ Yes      | ✅ Yes      | ✅ Yes      | ✅ Yes      | ✅ Yes
 ARM64 (AArch64) LE | ✅ Yes      | ✅ Yes      | ✅ Yes      | ✅ Yes      | ✅ Yes      | 🟨 Probably
-RISC-V 64 [^3]     | ⬜️ *N/A*    | ✅ Yes      | 🟨 Probably | ⬜️ *N/A*    | 🟨 Probably | 🟨 Probably
+RISC-V 64 [^2]     | ⬜️ *N/A*    | ✅ Yes      | 🟨 Probably | ⬜️ *N/A*    | 🟨 Probably | 🟨 Probably
 LoongArch64        | ⬜️ *N/A*    | ✅ Yes      | 🟨 Probably | ⬜️ *N/A*    | 🟨 Probably | 🟨 Probably
 
 [^1]: The following call conventions are supported: cdecl, stdcall, MS fastcall, thiscall.
-[^3]: The prebuilt binary uses the LP64D (double-precision float) ABI. The LP64 ABI is supported in theory if you build Koffi from source but this is untested. The LP64F ABI is not supported.
+[^2]: The prebuilt binary uses the LP64D (double-precision float) ABI. The LP64 ABI is supported in theory if you build Koffi from source but this is untested. The LP64F ABI is not supported.
 
 Go to the web site for more information: https://koffi.dev/
 

package/cnoke.cjs

@@ -22,19 +22,19 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
   mod
 ));
 
-// src/cnoke/cnoke.js
+// ../cnoke/cnoke.js
 var import_node_fs4 = __toESM(require("node:fs"), 1);
 
-// src/cnoke/src/builder.js
+// ../cnoke/src/builder.js
 var import_node_fs3 = __toESM(require("node:fs"), 1);
 var import_node_os = __toESM(require("node:os"), 1);
 var import_node_path = __toESM(require("node:path"), 1);
 var import_node_child_process = require("node:child_process");
 
-// src/cnoke/src/abi.js
+// ../cnoke/src/abi.js
 var import_node_fs = __toESM(require("node:fs"), 1);
 function determineAbi() {
-  let abi = process.arch;
+  let abi = process.arch.toString();
   if (abi == "riscv32" || abi == "riscv64") {
     let buf = readFileHeader(process.execPath, 512);
     let header = decodeElfHeader(buf);
@@ -121,7 +121,7 @@ function decodeElfHeader(buf) {
   return header;
 }
 
-// src/cnoke/src/util.js
+// ../cnoke/src/util.js
 var import_node_fs2 = __toESM(require("node:fs"), 1);
 function pathIsAbsolute(path2) {
   if (process.platform == "win32" && path2.match(/^[a-zA-Z]:/))
@@ -194,7 +194,7 @@ function compareVersions(ver1, ver2) {
   return cmp;
 }
 
-// src/cnoke/src/assets.js
+// ../cnoke/src/assets.js
 var FIND_CNOKE_CMAKE = `# SPDX-License-Identifier: MIT
 # SPDX-FileCopyrightText: 2026 Niels Martign\xE8ne <niels.martignene@protonmail.com>
 
@@ -361,7 +361,7 @@ const PfnDliHook __pfnDliNotifyHook2 = self_exe_hook;
 #endif
 `;
 
-// src/cnoke/src/builder.js
+// ../cnoke/src/builder.js
 var DefaultOptions = {
   mode: "RelWithDebInfo"
 };
@@ -586,9 +586,9 @@ function Builder(config = {}) {
       let major = parseInt(runtime_version, 10);
       let required = getNapiVersion(options2.napi, major);
       if (required == null)
-        throw new Error(`Project ${options2.name} does not support the Node ${major}.x branch (old or missing N-API)`);
+        throw new Error(`Project ${options2.name} does not support the Node ${major}.x branch (old or missing Node-API)`);
       if (compareVersions(runtime_version, required) < 0)
-        throw new Error(`Project ${options2.name} requires Node >= ${required} in the Node ${major}.x branch (with N-API >= ${options2.napi})`);
+        throw new Error(`Project ${options2.name} requires Node >= ${required} in the Node ${major}.x branch (with Node-API >= ${options2.napi})`);
     }
   }
   function readCNokeOptions() {
@@ -650,7 +650,7 @@ function Builder(config = {}) {
   }
 }
 
-// src/cnoke/cnoke.js
+// ../cnoke/cnoke.js
 var VALID_COMMANDS = ["build", "configure", "clean"];
 main();
 async function main() {

package/doc/benchmarks.md

@@ -1,57 +1,59 @@
 # Overview
 
-Here is a quick overview of the execution time of Koffi calls on three benchmarks, where it is compared to a theoretical ideal FFI implementation (approximated with pre-compiled static N-API glue code):
+This pages presents the execution time of Koffi calls on three benchmarks, where it is compared to a theoretical ideal FFI implementation (approximated with pre-compiled static Node-API glue code), and other FFI implementations:
 
-- The first benchmark is based on `rand()` calls
-- The second benchmark is based on `atoi()` calls
-- The third benchmark is based on `memset()` calls
+- The first benchmark is based on `atoi()` calls
+- The second benchmark is based on `memset()` calls
+
+# Linux x86_64
+
+The results presented below were measured on my x86_64 Linux machine (Intel® Core™ Ultra 9 185H).
 
 <div class="benchmark chart" data-platform="linux_x64"></div>
-<div class="benchmark chart" data-platform="win32_x64"></div>
 
-These results are detailed and explained below, and compared to node-ffi/node-ffi-napi.
+## atoi results for Linux x86_64 ^ atoi results
 
-# Linux x86_64
+This test is based on `atoi`, which takes a string parameter. Javascript (V8) to C string conversion is relatively slow and heavy.
 
-The results presented below were measured on my x86_64 Linux machine (Intel® Core™ Ultra 9 185H).
+<div class="benchmark table" data-platform="linux_x64" data-benchmark="atoi"></div>
 
-## rand results
+## memset results for Linux x86_64 ^ memset results
 
-This test is based around repeated calls to a simple standard C function `rand`, which takes no parameter and returns a 32-bit integer.
+This test is based around repeated calls to the standard C function `memset`. All implementations pass a Node.js Buffer for the pointer argument.
 
-<div class="benchmark table" data-platform="linux_x64" data-benchmark="rand"></div>
+<div class="benchmark table" data-platform="linux_x64" data-benchmark="memset"></div>
 
-Because rand is a pretty small function, the FFI overhead is clearly visible.
+# macOS ARM64
 
-## atoi results
+The results presented below were measured on an Apple Mac mini M2 hosted by Scaleway.
 
-This test is similar to the rand one, but it is based on `atoi`, which takes a string parameter. Javascript (V8) to C string conversion is relatively slow and heavy.
+<div class="benchmark chart" data-platform="darwin_arm64"></div>
 
-<div class="benchmark table" data-platform="linux_x64" data-benchmark="atoi"></div>
+## atoi results for macOS ARM64 ^ atoi results
 
-## memset results
+This test is based on `atoi`, which takes a string parameter. Javascript (V8) to C string conversion is relatively slow and heavy.
 
-This test is based around repeated calls to the standard C function `memset`. All implementations pass a Node.js Buffer for the pointer argument.
+<div class="benchmark table" data-platform="darwin_arm64" data-benchmark="atoi"></div>
 
-<div class="benchmark table" data-platform="linux_x64" data-benchmark="memset"></div>
+## memset results for macOS ARM64 ^ memset results
 
-# Windows x86_64
+This test is based around repeated calls to the standard C function `memset`. All implementations pass a Node.js Buffer for the pointer argument.
 
-The results presented below were measured on my x86_64 Windows machine (Intel® Core™ i5-4460).
+<div class="benchmark table" data-platform="darwin_arm64" data-benchmark="memset"></div>
 
-## rand results
+# Windows x86_64
 
-This test is based around repeated calls to a simple standard C function `rand`, which takes no parameter and returns a 32-bit integer.
+The results presented below were measured on my x86_64 Windows machine (AMD Ryzen™ 5 2600).
 
-<div class="benchmark table" data-platform="win32_x64" data-benchmark="rand"></div>
+<div class="benchmark chart" data-platform="win32_x64"></div>
 
-## atoi results
+## atoi results for Windows x86_64 ^ atoi results
 
-This test is similar to the rand one, but it is based on `atoi`, which takes a string parameter. Javascript (V8) to C string conversion is relatively slow and heavy.
+This test is based on `atoi`, which takes a string parameter. Javascript (V8) to C string conversion is relatively slow and heavy.
 
 <div class="benchmark table" data-platform="win32_x64" data-benchmark="atoi"></div>
 
-## memset results
+## memset results for Windows x86_64 ^ memset results
 
 This test is based around repeated calls to the standard C function `memset`. All implementations pass a Node.js Buffer for the pointer argument.
 

package/doc/callbacks.md

@@ -142,19 +142,10 @@ koffi.unregister(cb1);
 koffi.unregister(cb2);
 ```
 
-Starting *with Koffi 2.2*, you can optionally specify the `this` value for the function as the first argument.
-
-```js
-class ValueStore {
-    constructor(value) { this.value = value; }
-    get() { return this.value; }
-}
-
-let store = new ValueStore(42);
-
-let cb1 = koffi.register(store.get, 'IntCallback *'); // If a C function calls cb1 it will fail because this will be undefined
-let cb2 = koffi.register(store, store.get, 'IntCallback *'); // However in this case, this will match the store object
-```
+> [!NOTE]
+> In Koffi 2.x (starting with Koffi 2.2), you could bind a specific `this` value to the callback function, by giving an object as the first argument to `koffi.register()`.
+>
+> This feature has been deprecated in Koffi 3 and will eventually be removed. Replace with an explicit call to `function.bind()` instead.
 
 # Special considerations
 

package/doc/contribute.md

@@ -6,7 +6,7 @@ Please note that the source code is not in this repository, instead it lives in
 
 # Build from source
 
-We provide prebuilt binaries, packaged in the NPM archive, so in most cases it should be as simple as `npm install koffi`. If you want to hack Koffi or use a specific platform, follow the instructions below.
+We provide prebuilt binaries, packaged in NPM packages, so in most cases it should be as simple as `npm install koffi`. If you want to hack Koffi or use a specific platform, follow the instructions below.
 
 Start by cloning the repository with [Git](https://git-scm.com/):
 
@@ -25,7 +25,7 @@ First, make sure the following dependencies are met:
 - [CMake meta build system](https://cmake.org/)
 - [Node.js](https://nodejs.org/) 16 or later
 
-Once this is done, run this command _from the test or the benchmark directory_ (depending on what you want to build):
+Once this is done, run this command from the _src/koffi_ directory:
 
 ```sh
 cd src/koffi
@@ -44,7 +44,7 @@ Make sure the following dependencies are met:
 - [CMake meta build system](https://cmake.org/)
 - [Node.js](https://nodejs.org/) 16 or later
 
-Once this is done, run this command _from the test or the benchmark directory_ (depending on what you want to build):
+Once this is done, run this command from the _src/koffi_ directory:
 
 ```sh
 cd src/koffi

package/doc/index.md

@@ -1,9 +1,10 @@
 # Overview
 
-Koffi is a **fast and easy-to-use C FFI module for Node.js**, featuring:
+Koffi is a **fast and easy-to-use dynamic C FFI module for Node.js**, featuring:
 
-* Low-overhead and fast performance (see [benchmarks](benchmarks))
+* Low-overhead compared to a static Node-API implementation (see [benchmarks](benchmarks))
 * Support for primitive and aggregate data types (structs and fixed-size arrays), both by reference (pointer) and by value
+* Support for synchronous and asynchronous calls
 * Javascript functions can be used as C callbacks
 * Well-tested code base for popular OS/architecture combinations
 

package/doc/migration.md

@@ -1,3 +1,103 @@
+# Koffi 2.x to 3.x
+
+Most programs should work as-is with Koffi 3.x.
+
+However, some changes could impact your code:
+
+- Koffi is now distributed in [split packages](#split-packages) to reduce install size/bloat.
+- Pointers are now [BigInt values](#bigint-pointers) instead of opaque V8 external values.
+- Types created by koffi are now [type objects](#type-objects) insted of opaque V8 external values.
+- Using `koffi.register()` with a [receiver value](#registered-callback-binding) is deprecated.
+- Several old [deprecated functions](#removed-functions) have been removed.
+
+## Split packages
+
+The main koffi package does not contain native code any longer. Instead, it depends on platform-specific packages (such as `@koromix/koffi-linux-x64`) for platform support, specified through `optionalDependencies`.
+
+Your package manager should automatically install the binary package relevant to your platform. Importing koffi should work transparently, just as before.
+
+However, if you redistribute software that uses Koffi, you will probably **need to change your packaging system** or configure your bundler differently.
+
+## BigInt pointers
+
+For performance reasons, Koffi now uses BigInt numbers for pointers instead of V8 external objects.
+
+Most code should work without any change, but there are two cases where this might impact you:
+
+- If you use a **type system**, for example in TypeScript code (e.g. for parameters), you may need to accept BigInt values now if you pass pointer values around.
+- BigInt pointers **do not carry the C type around**. In Koffi 2.x, trying to pass a pointer to an integer to a `void Myfunc(MyStruct *)` function would have triggerd an exception, but in Koffi 3.x this will "work" (and probably crash).
+
+## Type objects
+
+Type functions, such as `koffi.struct()`, now create *TypeObject* objects, and type information is directly available without `koffi.introspect()`.
+
+You can resolve type strings to type objects with `koffi.type()`. This function replaces `koffi.resolve()`, which is now a deprecated alias for `koffi.type()`.
+
+> [!NOTE]
+> For compatibility reasons, both `koffi.resolve()` and `koffi.introspect()` still exist, as aliases for `koffi.type()`. Using them will emit a deprecation warning.
+
+Read the documentation about [type specifiers](migration#type-specifiers) for more information.
+
+The two versions below illustrate the API difference between Koffi 2.x and Koffi 3.x:
+
+```js
+// Koffi 2.x
+
+const MyStruct = koffi.struct('MyStruct', {
+    a: 'int',
+    b: 'int'
+});
+
+console.log(koffi.introspect(MyStruct).members); // Prints MyStruct members
+console.log(koffi.introspect('MyStruct').members); // Prints MyStruct members
+
+console.log(koffi.introspect(koffi.types.int).alignment); // Prints MyStruct members
+console.log(koffi.introspect('int').alignment); // Prints alignment of int type
+
+// Koffi 3.x
+
+const MyStruct = koffi.struct('MyStruct', {
+    a: 'int',
+    b: 'int'
+});
+
+console.log(MyStruct.members); // Prints MyStruct members
+console.log(koffi.type('MyStruct').members); // Prints MyStruct members
+
+console.log(koffi.types.int.alignment); // Prints alignment of int type
+console.log(koffi.type('int').alignment); // Prints alignment of int type
+```
+
+## Registered callback binding
+
+In Koffi 2.x, it was possible to bind a specific `this` value to the callback function when using `koffi.register()`, by passing an object as the first argument. This feature has been deprecated, it still works but will emit a warning.
+
+You should replace these calls with an explicit call to the `bind()` method:
+
+```js
+class ValueStore {
+    constructor(value) { this.value = value; }
+    get() { return this.value; }
+}
+
+let store = new ValueStore(42);
+
+// Koffi 2.x
+
+let cb = koffi.register(store, store.get, 'IntCallback *');
+
+// Koffi 3.x
+
+let cb = koffi.register(store.get.bind(store), 'IntCallback *');
+```
+
+## Removed functions
+
+Two deprecated functions have been removed:
+
+- `koffi.callback()`: if you still use it, replace with `koffi.proto()`.
+- `koffi.handle()`: if you still use it, replace with `koffi.opaque()`.
+
 # Koffi 1.x to 2.x
 
 The API was changed in 2.x in a few ways, in order to reduce some excessively "magic" behavior and reduce the syntax differences between C and the C-like prototypes.

package/doc/start.md

@@ -9,11 +9,11 @@ npm install koffi
 Once you have installed Koffi, you can start by loading it:
 
 ```js
-// CommonJS syntax
-const koffi = require('koffi');
-
 // ES6 modules
 import koffi from 'koffi';
+
+// CommonJS syntax
+const koffi = require('koffi');
 ```
 
 # Simple examples
@@ -112,7 +112,9 @@ Please read the [dedicated page](packaging) for information about bundling and p
 
 # Build manually
 
-Follow the [build instrutions](contribute#build-from-source) if you want to build the native Koffi code yourself.
+Follow the [build instructions](contribute#build-from-source) if you want to build the native Koffi code yourself.
 
 > [!NOTE]
-> This is only needed if you want to hack on Koffi. The official NPM package provide prebuilt binaries and you don't need to compile anything if you only want to use Koffi in Node.js.
+> This is only needed if you want to hack on Koffi. The official NPM package provides prebuilt binaries and you don't need to compile anything if you only want to use Koffi in Node.js.
+>
+> Just run `npm install koffi`!