koffi 3.0.0-alpha.7 → 3.0.0-alpha.9

package/CHANGELOG.md

@@ -3,6 +3,36 @@
 > [!NOTE]
 > Consult the [migration guide](migration) to migrate between major Koffi versions.
 
+## Koffi 3
+
+### Koffi 3.0
+
+#### Koffi 3.0.0 (WIP)
+
+**Main changes:**
+
+- Replace use of externals with type objects:
+  * Use `koffi.type()` to resolve type specifiers (strings or objects) to type objects
+  * Access type information directly on type variables without `koffi.introspect()`
+- Replace use of externals with BigInt pointers
+- Rewrite call preparation and execution for vastly improved performance
+
+**Other changes:**
+
+- Add `koffi.enumeration()` to create [enum types](input#enum-types)
+
+**Newly deprecated functions:**
+
+- Deprecate `koffi.resolve()` function, replace with `koffi.type()`
+- Deprecate `koffi.introspect()` function, replace with `koffi.type()`
+
+**Removed deprecated functions:**
+
+- Remove `koffi.callback()` long replaced with `koffi.proto()`
+- Remove `koffi.handle()` long replaced with `koffi.opaque()`
+
+Consult the [migration guide](migration) for more information.
+
 ## Koffi 2
 
 ### Koffi 2.16

package/LICENSE.txt

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (C) 2025  Niels Martignène <niels.martignene@protonmail.com>
+Copyright (C) 2026  Niels Martignène <niels.martignene@protonmail.com>
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of
 this software and associated documentation files (the “Software”), to deal in

package/{build.cjs → cnoke.cjs}

@@ -196,7 +196,7 @@ function compareVersions(ver1, ver2) {
 
 // ../cnoke/src/assets.js
 var FIND_CNOKE_CMAKE = `# SPDX-License-Identifier: MIT
-# SPDX-FileCopyrightText: 2025 Niels Martign\xE8ne <niels.martignene@protonmail.com>
+# SPDX-FileCopyrightText: 2026 Niels Martign\xE8ne <niels.martignene@protonmail.com>
 
 if(CMAKE_BUILD_TYPE STREQUAL "Release" OR CMAKE_BUILD_TYPE STREQUAL "RelWithDebInfo" OR
    CMAKE_BUILD_TYPE STREQUAL "MinSizeRel")
@@ -324,7 +324,7 @@ if(CMAKE_CXX_COMPILER_ID STREQUAL "Clang" OR CMAKE_CXX_COMPILER_ID STREQUAL "GNU
 endif()
 `;
 var WIN_DELAY_HOOK_C = `// SPDX-License-Identifier: MIT
-// SPDX-FileCopyrightText: 2025 Niels Martign\xE8ne <niels.martignene@protonmail.com>
+// SPDX-FileCopyrightText: 2026 Niels Martign\xE8ne <niels.martignene@protonmail.com>
 
 #include <stdlib.h>
 #if !defined(NOMINMAX)

package/doc/callbacks.md

@@ -5,8 +5,8 @@
 In order to pass a JS function to a C function expecting a callback, you must first create a callback type with the expected return type and parameters. The syntax is similar to the one used to load functions from a shared library.
 
 ```js
-// ES6 syntax: import koffi from 'koffi';
-const koffi = require('koffi');
+import koffi from 'koffi';
+// CJS: const koffi = require('koffi');
 
 // With the classic syntax, this callback expects an integer and returns nothing
 const ExampleCallback = koffi.proto('ExampleCallback', 'void', ['int']);
@@ -71,8 +71,8 @@ int TransferToJS(const char *name, int age, int (*cb)(const char *str, int age))
 ```
 
 ```js
-// ES6 syntax: import koffi from 'koffi';
-const koffi = require('koffi');
+import koffi from 'koffi';
+// CJS: const koffi = require('koffi');
 
 const lib = koffi.load('./callbacks.so'); // Fake path
 
@@ -121,8 +121,8 @@ void SayIt(const char *name)
 ```
 
 ```js
-// ES6 syntax: import koffi from 'koffi';
-const koffi = require('koffi');
+import koffi from 'koffi';
+// CJS: const koffi = require('koffi');
 
 const lib = koffi.load('./callbacks.so'); // Fake path
 
@@ -162,15 +162,15 @@ let cb2 = koffi.register(store, store.get, 'IntCallback *'); // However in this
 
 *New in Koffi 2.2, changed in Koffi 2.3*
 
-Koffi does not have enough information to convert callback pointer arguments to an appropriate JS value. In this case, your JS function will receive an opaque *External* object.
+Koffi does not have enough information to convert callback pointer arguments to an appropriate JS value. In this case, your JS function will receive a *BigInt* value with the pointer address.
 
 You can pass this value through to another C function that expects a pointer of the same type, or you can use [koffi.decode()](variables#decode-to-js-values) function to decode pointer arguments.
 
 The following examples uses it to sort an array of strings in-place with the standard C function `qsort()`:
 
 ```js
-// ES6 syntax: import koffi from 'koffi';
-const koffi = require('koffi');
+import koffi from 'koffi';
+// CJS: const koffi = require('koffi');
 
 const lib = koffi.load('libc.so.6');
 

package/doc/contribute.md

@@ -151,7 +151,7 @@ cd ../../bin/koffi/packages
 ./publish.sh
 ```
 
-Some platforms are emulated so this can take a few minutes until the pre-built binaries are ready. Go grab a cup of coffee, come back and execute the `npm publish` command!
+Some platforms are emulated so this can take a few minutes until the pre-built binaries are ready. You might want to go grab a cup of coffee :)
 
 # Code style
 

package/doc/functions.md

@@ -3,8 +3,8 @@
 To declare functions, start by loading the shared library with `koffi.load(filename)`.
 
 ```js
-// ES6 syntax: import koffi from 'koffi';
-const koffi = require('koffi');
+import koffi from 'koffi';
+// CJS: const koffi = require('koffi');
 
 const lib = koffi.load('/path/to/shared/library'); // File extension depends on platforms: .so, .dll, .dylib, etc.
 ```
@@ -105,8 +105,8 @@ You can safely use these on non-x86 platforms, they are simply ignored.
 Below you can find a small example showing how to use a non-default calling convention, with the two syntaxes:
 
 ```js
-// ES6 syntax: import koffi from 'koffi';
-const koffi = require('koffi');
+import koffi from 'koffi';
+// CJS: const koffi = require('koffi');
 
 const lib = koffi.load('user32.dll');
 
@@ -142,8 +142,8 @@ printf('Integer %d, double %g, str %s', 'int', 6, 'double', 8.5, 'str', 'THE END
 You can issue asynchronous calls by calling the function through its async member. In this case, you need to provide a callback function as the last argument, with `(err, res)` parameters.
 
 ```js
-// ES6 syntax: import koffi from 'koffi';
-const koffi = require('koffi');
+import koffi from 'koffi';
+// CJS: const koffi = require('koffi');
 
 const lib = koffi.load('libc.so.6');
 

package/doc/input.md

@@ -278,8 +278,8 @@ const char *ConcatBuild(Concat *c)
 ```
 
 ```js
-// ES6 syntax: import koffi from 'koffi';
-const koffi = require('koffi');
+import koffi from 'koffi';
+// CJS: const koffi = require('koffi');
 
 const lib = koffi.load('./handles.so');
 
@@ -348,8 +348,8 @@ Koffi applies the following conversion rules when passing arrays to/from C:
 See the example below:
 
 ```js
-// ES6 syntax: import koffi from 'koffi';
-const koffi = require('koffi');
+import koffi from 'koffi';
+// CJS: const koffi = require('koffi');
 
 // Those two structs are exactly the same, only the array conversion hint is different
 const Foo1 = koffi.struct('Foo1', {
@@ -438,8 +438,8 @@ void AppendValues(struct FlexibleArray *arr, size_t count, int start, int step)
 ```
 
 ```js
-// ES6 syntax: import koffi from 'koffi';
-const koffi = require('koffi');
+import koffi from 'koffi';
+// CJS: const koffi = require('koffi');
 
 const lib = koffi.load('./flexible.so');
 
@@ -466,6 +466,70 @@ console.log(array); // Prints { count: 8, numbers: [1, 2, 3, 4, 5, 10, 12, 14] }
 
 In C, dynamically-sized arrays are usually passed around as pointers. Read more about [array pointers](pointers#dynamic-arrays) in the relevant section.
 
+# Enum types
+
+*Added in Koffi 3.0*
+
+C enumeration values are stored as integers. The underlying integer type is implementation-defined but Koffi tries to match usual platform behavior.
+
+On POSIX platforms, Koffi follows the following rules:
+
+- If no negative value exists: `unsigned int` by default, `uint64_t` if needed
+- If any negative value exists: `int` by default, `int64_t` if needed
+
+On Windows, things are simpler, and `int` is used all the time. Koffi will throw an error if any enumeration value does not fit in a 32-bit integer.
+
+```js
+// For OpenResult, the underlying type will be unsigned int on POSIX, int on Windows
+const OpenResult = koffi.enumeration('OpenResult', {
+    Success: 0,
+    MissingFile: 1,
+    AccessDenied: 2,
+    OtherError: 3
+});
+
+// For RelativePosition, the underlying type will be int everywhere
+const RelativePosition = koffi.enumeration('RelativePosition', {
+    Left: -1,
+    Center: 0,
+    Right: 1
+});
+
+// For IntLimits, the underlying type will be int64_t on POSIX, and fail on Windows
+const Int64Limits = koffi.enumeration('Int64Limits', {
+    Min: -9223372036854775808n,
+    Max: 9223372036854775807n
+});
+```
+
+```{warning}
+This behavior may not match your compiler:
+
+- POSIX platforms: GCC and Clang support will use a short integer type if `-fshort-enums` is specified and the enumeration values fit in `short` or `unsigned short`
+- Windows: MSVC (and Clang) always use `int` even if some values do not fit, which matches what Koffi does... unless the compiler flag `/Zc:enumTypes` is set, maybe.
+
+Use an explicit type specifier to work around these problems, as shown below.
+```
+
+You can access the constants in `values` member of the type object.
+
+```js
+console.log(OpenResult.values.MissingFile); // Prints 1
+console.log(RelativePosition.values.Left); // Prints -1
+```
+
+You can specify the storage type explicitly as the last argument to `koffi.enumeration(name, values, type)`.
+
+```js
+// This one explictly uses int64_t as the underlying type,
+// despite the fact that the values fit inside an int.
+const ExplicitEnum = koffi.enumeration('ExplicitEnum', {
+    Zero: 0,
+    One: 1,
+    Two: 2
+}, 'int64_t');
+```
+
 # Union types
 
 The declaration and use of [union types](unions) will be explained in a later section, they are only briefly mentioned here if you need them.

package/doc/misc.md

@@ -1,19 +1,17 @@
 # Types
 
-## Introspection
+## Type specifiers
 
-*New in Koffi 2.0: `koffi.resolve()`, new in Koffi 2.2: `koffi.offsetof()`*
+*Changed in Koffi 3.0*
 
 > [!NOTE]
-> The value returned by `introspect()` has **changed in version 2.0 and in version 2.2**.
->
-> In Koffi 1.x, it could only be used with struct types and returned the object passed to koffi.struct() with the member names and types.
->
-> Starting in Koffi 2.2, each record member is exposed as an object containing the name, the type and the offset within the record.
+> In Koffi 2.0, types were External values, you had to use `koffi.introspect()` to get type information. In Koffi 3.0, this information is directly available in type objects, and this function is deprecated.
 >
 > Consult the [migration guide](migration) for more information.
 
-Use `koffi.introspect(type)` to get detailed information about a type: name, primitive, size, alignment, members (record types), reference type (array, pointer) and length (array).
+You can use strings or type objects to give type information to Koffi (when declaring functions, structs, and so on). Use `koffi.type(spec)` to resolve all accepted type values (strings and type objects) to type objects.
+
+You can inspect the type object for information: name, primitive, size, alignment, members (record types), reference type (array, pointer), length (array), arguments and return type (prototypes).
 
 ```js
 const FoobarType = koffi.struct('FoobarType', {
@@ -22,7 +20,7 @@ const FoobarType = koffi.struct('FoobarType', {
     c: 'double'
 });
 
-console.log(koffi.introspect(FoobarType));
+console.log(FoobarType);
 
 // Expected result on 64-bit machines:
 // {
@@ -30,10 +28,11 @@ console.log(koffi.introspect(FoobarType));
 //     primitive: 'Record',
 //     size: 24,
 //     alignment: 8,
+//     disposable: false,
 //     members: {
-//         a: { name: 'a', type: [External: 4b28a60], offset: 0 },
-//         b: { name: 'b', type: [External: 4b292e0], offset: 8 },
-//         c: { name: 'c', type: [External: 4b29260], offset: 16 }
+//         a: { name: 'a', type: [Type], offset: 0 },
+//         b: { name: 'b', type: [Type], offset: 8 },
+//         c: { name: 'c', type: [Type], offset: 16 }
 //     }
 // }
 ```
@@ -43,7 +42,7 @@ Koffi also exposes a few more utility functions to get a subset of this informat
 - `koffi.sizeof(type)` to get the size of a type
 - `koffi.alignof(type)` to get the alignment of a type
 - `koffi.offsetof(type, member_name)` to get the offset of a record member
-- `koffi.resolve(type)` to get the resolved type object from a type string
+- `koffi.type(type)` to get the resolved type object from a type string
 
 Just like before, you can refer to primitive types by their name or through `koffi.types`:
 
@@ -152,8 +151,8 @@ The standard POSIX error codes are available in `koffi.os.errno`, as shown below
 ```js
 const assert = require('assert');
 
-// ES6 syntax: import koffi from 'koffi';
-const koffi = require('koffi');
+import koffi from 'koffi';
+// CJS: const koffi = require('koffi');
 
 const lib = koffi.load('libc.so.6');
 

package/doc/output.md

@@ -29,8 +29,8 @@ The same can be done when declaring a function with a C-like prototype string, w
 This Windows example enumerate all Chrome windows along with their PID and their title. The `GetWindowThreadProcessId()` function illustrates how to get a primitive value from an output argument.
 
 ```js
-// ES6 syntax: import koffi from 'koffi';
-const koffi = require('koffi');
+import koffi from 'koffi';
+// CJS: const koffi = require('koffi');
 
 const user32 = koffi.load('user32.dll');
 
@@ -87,8 +87,8 @@ for (let hwnd = null;;) {
 This example calls the POSIX function `gettimeofday()`, and uses the prototype-like syntax.
 
 ```js
-// ES6 syntax: import koffi from 'koffi';
-const koffi = require('koffi');
+import koffi from 'koffi';
+// CJS: const koffi = require('koffi');
 
 const lib = koffi.load('libc.so.6');
 
@@ -115,8 +115,8 @@ console.log(tv);
 Many Win32 functions that use struct outputs require you to set a size member (often named `cbSize`). These functions won't work with `_Out_` because the size value must be copied from JS to C, use `_Inout_` in this case.
 
 ```js
-// ES6 syntax: import koffi from 'koffi';
-const koffi = require('koffi');
+import koffi from 'koffi';
+// CJS: const koffi = require('koffi');
 
 const user32 = koffi.load('user32.dll');
 
@@ -137,8 +137,8 @@ console.log(success, info);
 This example opens an in-memory SQLite database, and uses the node-ffi-style function declaration syntax.
 
 ```js
-// ES6 syntax: import koffi from 'koffi';
-const koffi = require('koffi');
+import koffi from 'koffi';
+// CJS: const koffi = require('koffi');
 
 const lib = koffi.load('sqlite3.so');
 
@@ -215,8 +215,8 @@ You can use buffers and typed arrays for output (and input/output) pointer param
 Once the native function returns, you can decode the content with `koffi.decode(value, type)` as in the following example:
 
 ```js
-// ES6 syntax: import koffi from 'koffi';
-const koffi = require('koffi');
+import koffi from 'koffi';
+// CJS: const koffi = require('koffi');
 
 const lib = koffi.load('libc.so.6');
 

package/doc/packaging.md

@@ -45,7 +45,7 @@ MyApp.exe
 
 Some bundlers (such as vite) don't like when require is used with native modules.
 
-In this case, you can use `require('koffi/indirect')` but you will need to make sure that the native Koffi modules are packaged properly.
+In this case, you can use `import koffi from 'koffi/indirect'` but you will need to make sure that the native Koffi modules are packaged properly.
 
 # Packaging examples
 
@@ -53,7 +53,7 @@ In this case, you can use `require('koffi/indirect')` but you will need to make
 
 Packaging with electron-builder should work as-is.
 
-Take a look at the full [working example in the repository](https://codeberg.org/Koromix/rygel/src/branch/master/src/koffi/examples/electron-builder).
+Take a look at the full [working example in the repository](https://codeberg.org/Koromix/rygel/src/branch/master/src/koffi/examples/packaging/electron-builder).
 
 ## Electron Forge
 
@@ -63,13 +63,13 @@ Packaging with Electron Force should work as-is, even when using webpack as conf
 npm init electron-app@latest my-app -- --template=webpack
 ```
 
-Take a look at the full [working example in the repository](https://codeberg.org/Koromix/rygel/src/branch/master/src/koffi/examples/electron-forge).
+Take a look at the full [working example in the repository](https://codeberg.org/Koromix/rygel/src/branch/master/src/koffi/examples/packaging/electron-forge).
 
 ## NW.js
 
 Packagers such as nw-builder should work as-is.
 
-You can find a full [working example in the repository](https://codeberg.org/Koromix/rygel/src/branch/master/src/koffi/examples/nwjs).
+You can find a full [working example in the repository](https://codeberg.org/Koromix/rygel/src/branch/master/src/koffi/examples/packaging/nwjs).
 
 ## Node.js and esbuild
 
@@ -79,10 +79,10 @@ You can easily tell esbuild to copy the native files with the copy loader and th
 esbuild index.js --platform=node --bundle --loader:.node=copy --outdir=dist/
 ```
 
-You can find a full [working example in the repository](https://codeberg.org/Koromix/rygel/src/branch/master/src/koffi/examples/node-esbuild).
+You can find a full [working example in the repository](https://codeberg.org/Koromix/rygel/src/branch/master/src/koffi/examples/packaging/node-esbuild).
 
 ## Node.js and yao-pkg
 
 Use [yao-pkg](https://github.com/yao-pkg/pkg) to make binary packages of your Node.js-based project.
 
-You can find a full [working example in the repository](https://codeberg.org/Koromix/rygel/src/branch/master/src/koffi/examples/yao-pkg).
+You can find a full [working example in the repository](https://codeberg.org/Koromix/rygel/src/branch/master/src/koffi/examples/packaging/yao-pkg).

package/doc/pointers.md

@@ -14,8 +14,8 @@ In C, pointer arguments are used for differenty purposes. It is important to dis
 The following Win32 example uses `GetCursorPos()` (with an output parameter) to retrieve and show the current cursor position.
 
 ```js
-// ES6 syntax: import koffi from 'koffi';
-const koffi = require('koffi');
+import koffi from 'koffi';
+// CJS: const koffi = require('koffi');
 
 const lib = koffi.load('user32.dll');
 
@@ -49,6 +49,8 @@ const GetHandleInformation = lib.func('bool __stdcall GetHandleInformation(HANDL
 const CloseHandle = lib.func('bool __stdcall CloseHandle(HANDLE h)');
 ```
 
+Koffi uses BigInt numbers to represent opaque pointers.
+
 ## Pointer to primitive types
 
 In javascript, it is not possible to pass a primitive value by reference to another function. This means that you cannot call a function and expect it to modify the value of one of its number or string parameter.
@@ -115,8 +117,8 @@ int64_t ComputeTotalLength(const char **strings)
 ```
 
 ```js
-// ES6 syntax: import koffi from 'koffi';
-const koffi = require('koffi');
+import koffi from 'koffi';
+// CJS: const koffi = require('koffi');
 
 const lib = koffi.load('./length.so');
 
@@ -144,8 +146,8 @@ Koffi provides two features to deal with this:
 The example below shows the use of `koffi.as()` to read the header of a PNG file with `fread()` directly to a JS object.
 
 ```js
-// ES6 syntax: import koffi from 'koffi';
-const koffi = require('koffi');
+import koffi from 'koffi';
+// CJS: const koffi = require('koffi');
 
 const lib = koffi.load('libc.so.6');
 
@@ -216,8 +218,8 @@ const ExplicitFree = koffi.disposable('HeapStr16', 'str16', koffi.free); // You
 The following example illustrates the use of a disposable type derived from *str*.
 
 ```js
-// ES6 syntax: import koffi from 'koffi';
-const koffi = require('koffi');
+import koffi from 'koffi';
+// CJS: const koffi = require('koffi');
 
 const lib = koffi.load('libc.so.6');
 
@@ -231,8 +233,8 @@ console.log(copy); // Prints Hello!
 When you declare functions with the [prototype-like syntax](functions#definition-syntax), you can either use named disposable types or use the '!' shortcut qualifier with compatibles types, as shown in the example below. This qualifier creates an anonymous disposable type that calls `koffi.free(ptr)`.
 
 ```js
-// ES6 syntax: import koffi from 'koffi';
-const koffi = require('koffi');
+import koffi from 'koffi';
+// CJS: const koffi = require('koffi');
 
 const lib = koffi.load('libc.so.6');
 
@@ -260,8 +262,8 @@ You can access unmanaged memory with `koffi.view(ptr, len)`. This function takes
 The following Linux example writes the string "Hello World!" to a file named "hello.txt" through mmaped memory, to demontrate the use of `koffi.view()`:
 
 ```js
-// ES6 syntax: import koffi from 'koffi';
-const koffi = require('koffi');
+import koffi from 'koffi';
+// CJS: const koffi = require('koffi');
 
 const libc = koffi.load('libc.so.6');
 
@@ -322,7 +324,3 @@ function write(filename, str) {
     }
 }
 ```
-
-# Unwrap pointers
-
-You can use `koffi.address(ptr)` on a pointer to get the numeric value as a [BigInt object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt).

package/doc/start.md

@@ -30,8 +30,8 @@ This is a small example for Linux systems, which uses `gettimeofday()`, `localti
 It illustrates the use of output parameters.
 
 ```js
-// ES6 syntax: import koffi from 'koffi';
-const koffi = require('koffi');
+import koffi from 'koffi';
+// CJS: const koffi = require('koffi');
 
 // Load the shared library
 const lib = koffi.load('libc.so.6');
@@ -81,8 +81,8 @@ This is a small example targeting the Win32 API, using `MessageBox()` to show a
 It illustrates the use of the x86 stdcall calling convention, and the use of UTF-8 and UTF-16 string arguments.
 
 ```js
-// ES6 syntax: import koffi from 'koffi';
-const koffi = require('koffi');
+import koffi from 'koffi';
+// CJS: const koffi = require('koffi');
 
 // Load the shared library
 const lib = koffi.load('user32.dll');

package/doc/unions.md

@@ -56,8 +56,8 @@ DoSomething('string', { str: 'Hello!' });
 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
-// ES6 syntax: import koffi from 'koffi';
-const koffi = require('koffi');
+import koffi from 'koffi';
+// CJS: const koffi = require('koffi');
 
 // Win32 type and functions
 

package/doc/variables.md

@@ -23,7 +23,7 @@ You cannot directly manipulate these variables, use:
 
 *New in Koffi 2.2, changed in Koffi 2.3*
 
-Use `koffi.decode()` to decode C pointers, wrapped as external objects or as simple numbers.
+Use `koffi.decode()` to decode C pointers, represented by BigInt numbers.
 
 Some arguments are optional and this function can be called in several ways:
 
@@ -66,12 +66,12 @@ console.log(koffi.decode(my_string, 'const char *', 3)) // Prints "foo"
 
 *New in Koffi 2.6*
 
-Use `koffi.encode()` to encode JS values into C symbols or pointers, wrapped as external objects or as simple numbers.
+Use `koffi.encode()` to encode JS values into C symbols or pointers, which are represented by BigInt numbers.
 
 Some arguments are optional and this function can be called in several ways:
 
-- `koffi.encode(ref, type, value)`: no offset
-- `koffi.encode(ref, offset, type, value)`: explicit offset to add to the pointer before encoding
+- `koffi.encode(ptr, type, value)`: no offset
+- `koffi.encode(ptr, offset, type, value)`: explicit offset to add to the pointer before encoding
 
 We'll reuse the examples shown above and change the variable values with `koffi.encode()`.