koffi 3.0.1 → 3.1.0

package/CHANGELOG.md

@@ -5,8 +5,37 @@
 
 ## Koffi 3
 
+### Koffi 3.1
+
+#### Koffi 3.1.0
+
+*Released on 2026-06-29*
+
+- Add endian-sensitive integer decoding functions
+- Drop required but useless type specifier from `lib.symbol()`
+- Add `wstring` type alias for wide strings
+- Add platform-dependent `koffi.decode.wstring()` function
+- Improve performance of various functions and value conversions
+- Optimize Windows build flags
+- Fix static native loading from the koffi ESM entry point ([@yibe](https://codeberg.org/yibe))
+- Fix minor memory and reference leaks on exit
+- Fix length argument types in TypeScript definition
+- Reorganize documentation pages
+
 ### Koffi 3.0
 
+#### Koffi 3.0.2
+
+*Released on 2026-05-26*
+
+- Fix unexpected type error when passing array of pointers (see [Koromix/koffi#269](https://github.com/Koromix/koffi/issues/269))
+- Search more native addon directories under `process.resourcesPath`
+- Rearrange Koffi loading to use `require()` for static packages
+- Avoid declare module syntax in TypeScript definition file
+- Fix error when using *String* array hint with UTF-32 string types (`const char32_t *`)
+- Add *Buffer* array hint to convert arrays and pointers to Node Buffer objects
+- Reduce overhead of various Koffi functions
+
 #### Koffi 3.0.1
 
 *Released on 2026-05-20*
@@ -400,7 +429,7 @@ Consult the [migration guide](migration) for more information.
 *Released on 2023-12-05*
 
 - Speed up resolving simple and often used type names
-- Fix use of optional length argument with [koffi.encode()](variables#encode-to-c-memory)
+- Fix use of optional length argument with [koffi.encode()](values#encode-to-c-memory)
 
 #### Koffi 2.6.10
 
@@ -461,8 +490,8 @@ Consult the [migration guide](migration) for more information.
 
 **New features:**
 
-- Use [koffi.symbol()](variables#variable-definitions) to make pointers to exported variables (or other symbols)
-- Use [koffi.encode()](variables#encode-to-c-memory) to explictly encode data from JS to C memory
+- Use [koffi.symbol()](values#variable-definitions) to make pointers to exported variables (or other symbols)
+- Use [koffi.encode()](values#encode-to-c-memory) to explictly encode data from JS to C memory
 - Use shared library [lazy-loading](functions#loading-options) (RTLD_LAZY) on POSIX platforms
 
 **Other changes:**

package/cnoke.cjs

@@ -317,8 +317,8 @@ endif()
 if(CMAKE_CXX_COMPILER_ID STREQUAL "Clang" OR CMAKE_CXX_COMPILER_ID STREQUAL "GNU")
     if(CMAKE_SYSTEM_PROCESSOR MATCHES "(amd64|x86_64)")
         foreach(lang C CXX)
-            set(CMAKE_\${lang}_FLAGS_RELEASE "\${CMAKE_\${lang}_FLAGS_RELEASE} -mpopcnt -msse4.1 -msse4.2 -mssse3 -mcx16")
-            set(CMAKE_\${lang}_FLAGS_RELWITHDEBINFO "\${CMAKE_\${lang}_FLAGS_RELWITHDEBINFO} -mpopcnt -msse4.1 -msse4.2 -mssse3 -mcx16")
+            set(CMAKE_\${lang}_FLAGS_RELEASE "\${CMAKE_\${lang}_FLAGS_RELEASE} -march=x86-64-v2")
+            set(CMAKE_\${lang}_FLAGS_RELWITHDEBINFO "\${CMAKE_\${lang}_FLAGS_RELWITHDEBINFO} -march=x86-64-v2")
         endforeach()
     endif()
 endif()

package/doc/benchmarks.md

@@ -25,7 +25,7 @@ This test is based around repeated calls to the standard C function `memset`. Al
 
 # macOS ARM64
 
-The results presented below were measured on an Apple Mac mini M2 hosted by Scaleway.
+The results presented below were measured on an Apple Mac mini M1 hosted by Scaleway.
 
 <div class="benchmark chart" data-platform="darwin_arm64"></div>
 

package/doc/callbacks.md

@@ -1,7 +1,5 @@
 # Callback types
 
-*Changed in Koffi 2.7*
-
 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
@@ -14,10 +12,8 @@ const ExampleCallback = koffi.proto('ExampleCallback', 'void', ['int']);
 // With the prototype parser, this callback expects a double and float, and returns the sum as a double
 const AddDoubleFloat = koffi.proto('double AddDoubleFloat(double d, float f)');
 ```
-> [!NOTE]
-> The function `koffi.proto()` was introduced in Koffi 2.4, it was called `koffi.callback()` in earlier versions.
 
-For alternative [calling conventions](functions#calling-conventions) (such as `stdcall` on Windows x86 32-bit), you can specify as the first argument with the classic syntax, or after the return type in prototype strings, like this:
+For alternative [calling conventions](load#calling-conventions) (such as `stdcall` on Windows x86 32-bit), you can specify as the first argument with the classic syntax, or after the return type in prototype strings, like this:
 
 ```js
 const HANDLE = koffi.pointer('HANDLE', koffi.opaque());
@@ -31,30 +27,19 @@ const EnumWindowsProc = koffi.proto('__stdcall', 'EnumWindowsProc', 'bool', ['HW
 > [!WARNING]
 > You have to make sure you **get the calling convention right** (such as specifying __stdcall for a Windows API callback), or your code will crash on Windows 32-bit.
 >
-> Before Koffi 2.7, it was *impossible to use an alternative callback calling convention with the classic syntax*. Use a prototype string or *upgrade to Koffi 2.7* to solve this limitation.
+> Only *cdecl* and *stdcall* callbacks are supported.
 
 Once your callback type is declared, you can use a pointer to it in struct definitions, as function parameters and/or return types, or to call/decode function pointers.
 
-> [!NOTE]
-> Callbacks **have changed in version 2.0**.
->
-> In Koffi 1.x, callbacks were defined in a way that made them usable directly as parameter and return types, obscuring the underlying pointer.
->
-> Now, you must use them through a pointer: `void CallIt(CallbackType func)` in Koffi 1.x becomes `void CallIt(CallbackType *func)` in version 2.0 and newer.
->
-> Consult the [migration guide](migration) for more information.
-
 # Transient and registered callbacks
 
 Koffi only uses predefined static trampolines, and does not need to generate code at runtime, which makes it compatible with platforms with hardened W^X migitations (such as PaX mprotect). However, this imposes some restrictions on the maximum number of callbacks, and their duration.
 
 Thus, Koffi distinguishes two callback modes:
 
-- [Transient callbacks](#transient-callbacks) can only be called while the C function they are passed to is running, and are invalidated when it returns. If the C function calls the callback later, the behavior is undefined, though Koffi tries to detect such cases. If it does, an exception will be thrown, but this is no guaranteed. However, they are simple to use, and don't require any special handling.
+- [Transient callbacks](#transient-callbacks) can only be called while the C function they are passed to is running, and are invalidated when it returns. If the C function calls the callback later, the behavior is undefined, though Koffi tries to detect such cases. If it does, an exception will be thrown, but this is not guaranteed. However, they are simple to use, and don't require any special handling.
 - [Registered callbacks](#registered-callbacks) can be called at any time, but they must be manually registered and unregistered. A limited number of registered callbacks can exist at the same time.
 
-You need to specify the correct [calling convention](functions#calling-conventions) on x86 platforms, or the behavior is undefined (Node will probably crash). Only *cdecl* and *stdcall* callbacks are supported.
-
 ## Transient callbacks
 
 Use transient callbacks when the native C function only needs to call them while it runs (e.g. qsort, progress callback, `sqlite3_exec`). Here is a small example with the C part and the JS part.
@@ -95,7 +80,7 @@ console.log(ret);
 
 ## Registered callbacks
 
-*New in Koffi 2.0 (explicit this binding in Koffi 2.2)*
+*Changed in Koffi 3.0 (see note below)*
 
 Use registered callbacks when the function needs to be called at a later time (e.g. log handler, event handler, `fopencookie/funopen`). Call `koffi.register(func, type)` to register a callback function, with two arguments: the JS function, and the callback type.
 
@@ -143,7 +128,7 @@ koffi.unregister(cb2);
 ```
 
 > [!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()`.
+> In Koffi 2.2, you could bind a specific `this` value to the callback function, by giving an object as the first argument: `koffi.register(object, func)`.
 >
 > This feature has been deprecated in Koffi 3 and will eventually be removed. Replace with an explicit call to `function.bind()` instead.
 
@@ -151,11 +136,9 @@ koffi.unregister(cb2);
 
 ## Decoding pointer arguments
 
-*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 a *BigInt* value with the pointer address (or *null* is the pointer is null).
 
-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.
+You can pass this value through to another C function that expects a pointer of the same type, or you can use [koffi.decode()](values#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()`:
 
@@ -182,8 +165,6 @@ console.log(array); // Prints ['123', 'bar', 'foo', 'foobar']
 
 ## Asynchronous callbacks
 
-*New in Koffi 2.2.2*
-
 JS execution is inherently single-threaded, so JS callbacks must run on the main thread. There are two ways you may want to call a callback function from another thread:
 
 - Call the callback from an asynchronous FFI call (e.g. `waitpid.async`)

package/doc/{input.md → composites.md}

@@ -1,83 +1,3 @@
-# Primitive types
-
-## Standard types
-
-While the C standard allows for variation in the size of most integer types, Koffi enforces the same definition for most primitive types, listed below:
-
-C type                        | JS type          | Bytes | Signedness | Note
------------------------------ | ---------------- | ----- | ---------- | ---------------------------
-void                          | Undefined        | 0     |            | Only valid as a return type
-int8, int8_t                  | Number (integer) | 1     | Signed     |
-uint8, uint8_t                | Number (integer) | 1     | Unsigned   |
-char                          | Number (integer) | 1     | Signed     |
-uchar, unsigned char          | Number (integer) | 1     | Unsigned   |
-char16, char16_t              | Number (integer) | 2     | Signed     |
-int16, int16_t                | Number (integer) | 2     | Signed     |
-uint16, uint16_t              | Number (integer) | 2     | Unsigned   |
-short                         | Number (integer) | 2     | Signed     |
-ushort, unsigned short        | Number (integer) | 2     | Unsigned   |
-char32, char32_t              | Number (integer) | 4     | Signed     |
-int32, int32_t                | Number (integer) | 4     | Signed     |
-uint32, uint32_t              | Number (integer) | 4     | Unsigned   |
-int                           | Number (integer) | 4     | Signed     |
-uint, unsigned int            | Number (integer) | 4     | Unsigned   |
-int64, int64_t                | Number (integer) | 8     | Signed     |
-uint64, uint64_t              | Number (integer) | 8     | Unsigned   |
-longlong, long long           | Number (integer) | 8     | Signed     |
-ulonglong, unsigned long long | Number (integer) | 8     | Unsigned   |
-float32                       | Number (float)   | 4     |            |
-float64                       | Number (float)   | 8     |            |
-float                         | Number (float)   | 4     |            |
-double                        | Number (float)   | 8     |            |
-
-Koffi also accepts BigInt values when converting from JS to C integers. If the value exceeds the range of the C type, Koffi will convert the number to an undefined value. In the reverse direction, BigInt values are automatically used when needed for big 64-bit integers.
-
-Koffi defines a few more types that can change size depending on the OS and the architecture:
-
-C type           | JS type          | Signedness  | Note
----------------- | ---------------- | ----------- | ------------------------------------------------
-bool             | Boolean          |             | Usually one byte
-long             | Number (integer) | Signed      | 4 or 8 bytes depending on platform (LP64, LLP64)
-ulong            | Number (integer) | Unsigned    | 4 or 8 bytes depending on platform (LP64, LLP64)
-unsigned long    | Number (integer) | Unsigned    | 4 or 8 bytes depending on platform (LP64, LLP64)
-intptr           | Number (integer) | Signed      | 4 or 8 bytes depending on register width
-intptr_t         | Number (integer) | Signed      | 4 or 8 bytes depending on register width
-uintptr          | Number (integer) | Unsigned    | 4 or 8 bytes depending on register width
-uintptr_t        | Number (integer) | Unsigned    | 4 or 8 bytes depending on register width
-wchar_t          | Number (integer) | *Undefined* | 2 bytes on Windows, 4 bytes Linux, macOS and BSD
-str, string      | String           |             | JS strings are converted to and from UTF-8
-str16, string16  | String           |             | JS strings are converted to and from UTF-16 (LE)
-str32, string32  | String           |             | JS strings are converted to and from UTF-32 (LE)
-
-Primitive types can be specified by name (in a string) or through `koffi.types`:
-
-```js
-// These two lines do the same:
-let struct1 = koffi.struct({ dummy: 'long' });
-let struct2 = koffi.struct({ dummy: koffi.types.long });
-```
-
-## Endian-sensitive integers
-
-*New in Koffi 2.1*
-
-Koffi defines a bunch of endian-sensitive types, which can be used when dealing with binary data (network payloads, binary file formats, etc.).
-
-C type                 | Bytes | Signedness | Endianness
----------------------- | ----- | ---------- | -------------
-int16_le, int16_le_t   | 2     | Signed     | Little Endian
-int16_be, int16_be_t   | 2     | Signed     | Big Endian
-uint16_le, uint16_le_t | 2     | Unsigned   | Little Endian
-uint16_be, uint16_be_t | 2     | Unsigned   | Big Endian
-int32_le, int32_le_t   | 4     | Signed     | Little Endian
-int32_be, int32_be_t   | 4     | Signed     | Big Endian
-uint32_le, uint32_le_t | 4     | Unsigned   | Little Endian
-uint32_be, uint32_be_t | 4     | Unsigned   | Big Endian
-int64_le, int64_le_t   | 8     | Signed     | Little Endian
-int64_be, int64_be_t   | 8     | Signed     | Big Endian
-uint64_le, uint64_le_t | 8     | Unsigned   | Little Endian
-uint64_be, uint64_be_t | 8     | Unsigned   | Big Endian
-
 # Struct types
 
 ## Struct definition
@@ -145,17 +65,6 @@ Many C libraries use some kind of object-oriented API, with a pair of functions
 
 In Koffi, you can manage this with opaque types. Declare the opaque type with `koffi.opaque(name)`, and use a pointer to this type either as a return type or some kind of [output parameter](output) (with a double pointer).
 
-> [!NOTE]
-> Opaque types **have changed in version 2.0, and again in version 2.1**.
->
-> In Koffi 1.x, opaque handles were defined in a way that made them usable directly as parameter and return types, obscuring the underlying pointer.
->
-> Now, you must use them through a pointer, and use an array for output parameters. This is shown in the example below (look for the call to `ConcatNewOut` in the JS part), and is described in the section on [output parameters](output).
->
-> In addition to this, you should use `koffi.opaque()` (introduced in Koffi 2.1) instead of `koffi.handle()` which is deprecated, and will be removed eventually in Koffi 3.0.
->
-> Consult the [migration guide](migration) for more information.
-
 The full example below implements an iterative string builder (concatenator) in C, and uses it from Javascript to output a mix of Hello World and FizzBuzz. The builder is hidden behind an opaque type, and is created and destroyed using a pair of C functions: `ConcatNew` (or `ConcatNewOut`) and `ConcatFree`.
 
 ```c
@@ -336,8 +245,6 @@ try {
 
 ## Fixed-size C arrays
 
-*Changed in Koffi 2.7.1*
-
 Fixed-size arrays are declared with `koffi.array(type, length)`. Just like in C, they cannot be passed as functions parameters (they degenerate to pointers), or returned by value. You can however embed them in struct types.
 
 Koffi applies the following conversion rules when passing arrays to/from C:
@@ -378,28 +285,18 @@ const StructType = koffi.struct('StructType', {
 });
 ```
 
-> [!NOTE]
-> The short C-like syntax was introduced in Koffi 2.7.1, use `koffi.array()` for older versions.
-
 ## Fixed-size string buffers
 
-*Changed in Koffi 2.9.0*
-
 Koffi can also convert JS strings to fixed-sized arrays in the following cases:
 
 - **char arrays** are filled with the UTF-8 encoded string, truncated if needed. The buffer is always NUL-terminated.
 - **char16 (or char16_t) arrays** are filled with the UTF-16 encoded string, truncated if needed. The buffer is always NUL-terminated.
 - **char32 (or char32_t) arrays** are filled with the UTF-32 encoded string, truncated if needed. The buffer is always NUL-terminated.
 
-> [!NOTE]
-> Support for UTF-32 and wchar_t (wide) strings was introduced in Koffi 2.9.0.
-
 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:
@@ -466,70 +363,187 @@ 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
+# Unions
 
-*Added in Koffi 3.0*
+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.
 
-C enumeration values are stored as integers. The underlying integer type is implementation-defined but Koffi tries to match usual platform behavior.
+The following example illustrates how to declare the same union in C and in JS with Koffi:
 
-On POSIX platforms, Koffi follows the following rules:
+```c
+typedef union IntOrDouble {
+    int64_t i;
+    double d;
+} IntOrDouble;
+```
 
-- 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
+```js
+const IntOrDouble = koffi.union('IntOrDouble', {
+    i: 'int64_t',
+    d: 'double'
+});
+```
+
+## Input unions
+
+### Passing union values to C
 
-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.
+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
-// 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
-});
+const U = koffi.union('U', { i: 'int', str: 'char *' });
 
-// For RelativePosition, the underlying type will be int everywhere
-const RelativePosition = koffi.enumeration('RelativePosition', {
-    Left: -1,
-    Center: 0,
-    Right: 1
-});
+const DoSomething = lib.func('void DoSomething(const char *type, U u)');
 
-// For IntLimits, the underlying type will be int64_t on POSIX, and fail on Windows
-const Int64Limits = koffi.enumeration('Int64Limits', {
-    Min: -9223372036854775808n,
-    Max: 9223372036854775807n
-});
+const u1 = new koffi.Union('U'); u1.i = 42;
+const u2 = new koffi.Union('U'); u2.str = 'Hello!';
+
+DoSomething('int', u1);
+DoSomething('string', u2);
 ```
 
-```{warning}
-This behavior may not match your compiler:
+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 *' });
 
-- 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.
+const DoSomething = lib.func('void DoSomething(const char *type, U u)');
 
-Use an explicit type specifier to work around these problems, as shown below.
+DoSomething('int', { i: 42 });
+DoSomething('string', { str: 'Hello!' });
 ```
 
-You can access the constants in `values` member of the type object.
+### 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
-console.log(OpenResult.values.MissingFile); // Prints 1
-console.log(RelativePosition.values.Left); // Prints -1
+import koffi from 'koffi';
+// CJS: 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_LWIN, true),
+    make_keyboard_event(VK_D, true),
+    make_keyboard_event(VK_D, false),
+    make_keyboard_event(VK_LWIN, 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;
+}
 ```
 
-You can specify the storage type explicitly as the last argument to `koffi.enumeration(name, values, type)`.
+## Output unions
 
-```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');
+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;
+}
 ```
 
-# Union types
+```js
+const IntOrDouble = koffi.union('IntOrDouble', {
+    i: 'int64_t',
+    d: 'double',
+    raw: koffi.array('uint8_t', 8)
+});
 
-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.
+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/doc/contribute.md

@@ -131,11 +131,12 @@ node tools/brew.js info debian_x64
 
 # Making a release
 
-First, you must update the code in three steps:
+First, you must update the code in four steps:
 
 - Change the version number in `package.json`
 - Add an entry to `CHANGELOG` to summarize the changes since last release
 - Commit theses changes with the message *Bump Koffi to X.Y.Z*
+- Create a signed tag on this commit with `git tag -s koffi/X.Y.Z -m 'Koffi X.Y.Z'`
 
 Once this is done, you can publish a new release with the following commands:
 
@@ -145,7 +146,7 @@ cd src/koffi
 node tools/brew.js test # If not done before
 node tools/brew.js build
 
-cd ../../bin/koffi/packages
+cd ../../bin/Koffi/packages
 
 ./prepare.sh
 ./publish.sh

package/doc/index.md

@@ -35,20 +35,6 @@ LoongArch64        | ⬜️      | ✅          | 🟨         | ⬜️    |
 
 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
 
 This program is free software: you can redistribute it and/or modify it under the terms of the **MIT License**.