node-ctypes 2.2.0 → 2.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (38) hide show
  1. package/CHANGELOG.md +932 -0
  2. package/README.md +504 -99
  3. package/build/Release/ctypes-darwin-arm64.node +0 -0
  4. package/build/Release/ctypes-darwin-x64.node +0 -0
  5. package/build/Release/ctypes-linux-arm64-musl.node +0 -0
  6. package/build/Release/ctypes-linux-arm64.node +0 -0
  7. package/build/Release/ctypes-linux-x64-musl.node +0 -0
  8. package/build/Release/ctypes-linux-x64.node +0 -0
  9. package/build/Release/ctypes-win32-arm64.node +0 -0
  10. package/build/Release/ctypes-win32-x64.node +0 -0
  11. package/lib/core/Library.js +136 -109
  12. package/lib/core/callback.js +17 -20
  13. package/lib/core/conversions.js +376 -16
  14. package/lib/core/funcptr.js +148 -73
  15. package/lib/core/lazy-loader.js +10 -4
  16. package/lib/core/types.js +201 -98
  17. package/lib/index.d.ts +276 -83
  18. package/lib/index.js +44 -32
  19. package/lib/memory/buffer.js +82 -22
  20. package/lib/memory/operations.js +55 -45
  21. package/lib/memory/pointer.js +233 -57
  22. package/lib/platform/constants.js +0 -1
  23. package/lib/platform/errors.js +48 -4
  24. package/lib/platform/find_library.js +78 -19
  25. package/lib/platform/win_types.js +8 -3
  26. package/lib/structures/Structure.js +252 -203
  27. package/lib/structures/Union.js +10 -21
  28. package/lib/structures/helpers/array.js +102 -16
  29. package/lib/structures/helpers/bitfield.js +75 -150
  30. package/lib/structures/helpers/common.js +310 -21
  31. package/lib/structures/helpers/layout.js +145 -0
  32. package/lib/structures/helpers/struct.js +160 -419
  33. package/lib/structures/helpers/union.js +154 -155
  34. package/lib/structures/helpers/wrap.js +3 -15
  35. package/lib/types/SimpleCData.js +11 -32
  36. package/lib/types/primitives.js +160 -113
  37. package/lib/utils/cache.js +34 -2
  38. package/package.json +4 -1
package/README.md CHANGED
@@ -5,10 +5,19 @@
5
5
  [![Build](https://github.com/dmazzella/node-ctypes/actions/workflows/build.yml/badge.svg)](https://github.com/dmazzella/node-ctypes/actions/workflows/build.yml)
6
6
  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
7
7
 
8
- **Python ctypes for Node.js.** A foreign function interface built on
9
- [libffi](https://github.com/libffi/libffi) and [N-API](https://nodejs.org/api/n-api.html).
8
+ **Python ctypes for Node.js.** A foreign function interface built with C++20,
9
+ [node-addon-api](https://github.com/nodejs/node-addon-api) and
10
+ [libffi](https://github.com/libffi/libffi).
10
11
  If you know Python ctypes, you already know node-ctypes.
11
12
 
13
+ ## Support
14
+
15
+ Development help is welcome: issues, pull requests and discussions are all appreciated.
16
+
17
+ > [!TIP]
18
+ > If you find **node-ctypes** useful, consider :star: this project
19
+ > and why not ... [Buy me a coffee](https://www.buymeacoffee.com/damianomazp) :smile:
20
+
12
21
  ---
13
22
 
14
23
  ## Quick start
@@ -21,14 +30,14 @@ Prebuilt binaries ship for Windows, macOS 13.5+ and Linux (glibc 2.28+ or musl /
21
30
  Alpine), on x64 and ARM64 — wherever Node 24 runs.
22
31
 
23
32
  ```javascript
24
- import { CDLL, Structure, c_int32, c_char_p } from "node-ctypes";
33
+ import { CDLL, Structure, c_int32, c_size_t, c_char_p } from "node-ctypes";
25
34
 
26
35
  // 1. Load a shared library
27
36
  const libc = new CDLL(process.platform === "win32" ? "msvcrt" : null);
28
37
 
29
38
  // 2. Declare a function signature
30
- const strlen = libc.func("strlen", c_int32, [c_char_p]);
31
- console.log(strlen("hello")); // 5
39
+ const strlen = libc.func("strlen", c_size_t, [c_char_p]);
40
+ console.log(strlen("hello")); // 5n
32
41
 
33
42
  // 3. Declare a struct
34
43
  class Point extends Structure {
@@ -44,7 +53,8 @@ console.log(p.x, p.y); // 3 4
44
53
  <details>
45
54
  <summary>Build from source</summary>
46
55
 
47
- Requires Node.js >= 24, CMake >= 3.15, and a C++ compiler.
56
+ Requires Node.js >= 24, CMake >= 3.15, and a C++20 compiler and standard library.
57
+ Run these commands from a source checkout:
48
58
 
49
59
  ```bash
50
60
  npm install
@@ -76,6 +86,13 @@ abs2(-42); // 42
76
86
  For Windows `__stdcall` APIs use `WinDLL` instead of `CDLL`. For COM-style
77
87
  auto-`HRESULT`-checking use `OleDLL`.
78
88
 
89
+ Direct native calls are limited to a bounded set of exact scalar C++
90
+ signatures with up to four arguments, on 64-bit little-endian targets using
91
+ the default ABI. Other signatures use the existing cached libffi plans/CIFs,
92
+ including pointers and strings whose pointee types and qualifiers are not
93
+ encoded in the native type metadata. Float/double arguments continue to use
94
+ libffi on x86-64. This changes the optimization route, not the JavaScript API.
95
+
79
96
  ### Structs, unions, bit fields, arrays
80
97
 
81
98
  ```javascript
@@ -115,9 +132,72 @@ const name = array(c_char, 16)();
115
132
  name.value = "node"; // .value / .raw as in Python
116
133
  ```
117
134
 
135
+ `array(type, n)` reuses the same type while it is alive. Instances, function
136
+ signatures and containing types keep their array types alive; the cache itself
137
+ does not. Unused array types and their length entries can be garbage-collected,
138
+ including arrays of builtin element types.
139
+
140
+ An array type in `argtypes` is passed by address, as in C and Python
141
+ (`fill.argtypes = [c_int32 * 4]`). As in Python, the argument must be an
142
+ instance of an array with the same element type and length; a Buffer or a
143
+ typed array is also accepted as its memory. Other values raise
144
+ `ArgumentError`.
145
+
146
+ Builtin numeric scalars accept numbers, booleans and BigInt; integers wrap to
147
+ their C width, but reject non-integral or non-finite numbers. Use BigInt when
148
+ the original integer needs more precision than a JS number can represent.
149
+ No argument, or `undefined` in a constructor, initializes zero. Explicit
150
+ `null`, strings and arbitrary objects are not implicit numeric conversions.
151
+ Assigning a scalar instance to a field or passing it to a declared numeric
152
+ argument requires a compatible type. The documented numeric-pointer argument
153
+ extensions below are unchanged.
154
+
155
+ `c_bool` and `wintypes.VARIANT_BOOL` use JavaScript truthiness, using `.value`
156
+ for scalar instances rather than treating every instance as true.
157
+ `VARIANT_BOOL` stores true as `-1`, and its results and callback arguments
158
+ are booleans. Boolean bitfields normalize before masking and read as booleans.
159
+
118
160
  Nested structs, anonymous fields (`static _anonymous_ = ["data"]`),
119
- explicit packing (`static _pack_ = 1`), and self-referential pointers
120
- (`POINTER(() => Node)`) all work identically to Python.
161
+ explicit packing (`static _pack_ = 1`), minimum alignment
162
+ (`static _align_ = 16`), self-referential pointers (`POINTER(() => Node)`)
163
+ and subclasses that add fields to their base class all work identically to
164
+ Python. The layout of bit fields follows Python's `_layout_`: `"gcc-sysv"`
165
+ by default, `"ms"` on Windows or with `_pack_`. Bit fields wider than 53
166
+ bits read as BigInt.
167
+
168
+ `_pack_` follows Python's integer conversion and permits zero and non-powers
169
+ of two (for example `3`) with the MS layout. An explicit `_pack_`, including
170
+ zero, is incompatible with `"gcc-sysv"`. Layouts with non-power-of-two
171
+ alignment can be used for memory serialization but are rejected as native
172
+ by-value signatures: they do not describe a valid C ABI alignment.
173
+
174
+ Structures and unions passed or returned by value keep this layout, also
175
+ with `_pack_`: as with GCC and clang, a structure with misaligned fields is
176
+ passed in memory on x86-64 System V (Linux, macOS Intel), where Python
177
+ ctypes passes it in registers and the called function reads wrong values.
178
+
179
+ Each returned structure or union owns a snapshot of its value, including
180
+ results declared with functional `struct()` / `union()` definitions. Array
181
+ views, nested composites and union getters remain valid after later calls,
182
+ reentrant conversion or `errcheck`, and concurrent `callAsync()` jobs.
183
+ Mutating one result does not modify another result's value storage.
184
+
185
+ This is not a deep copy through pointers: pointer fields can still refer to
186
+ the same external memory. Explicit `definition.toObject(buffer)` keeps its
187
+ existing buffer-view behavior. Synchronous low-level native `struct_buffer`
188
+ results are borrowed, reusable storage; public callables snapshot their
189
+ results before any JavaScript result conversion.
190
+
191
+ Low-level native `StructType` descriptors are builders only until consumed.
192
+ Adding a descriptor as a field, constructing an `ArrayType` from it (even at
193
+ length zero), preparing a function/callback signature, or creating/reading a
194
+ native value finalizes the captured layout and its dependencies.
195
+ `addField()` then throws instead of changing sizes, offsets or FFI metadata
196
+ already in use. Build a new descriptor for a different layout.
197
+ `getSize()` and `getAlignment()` alone leave an unused builder open; an
198
+ outer builder can still receive fields after it captures a finalized child.
199
+ Direct by-value self-reference is rejected. Pointers do not capture or
200
+ finalize the pointed-to layout.
121
201
 
122
202
  ### Pointers, buffers, and cast
123
203
 
@@ -128,14 +208,16 @@ import { POINTER, pointer, cast, c_int32, c_void_p } from "node-ctypes";
128
208
  const x = new c_int32(42);
129
209
  const px = pointer(x);
130
210
  px.contents.value; // 42 (Python: px.contents.value — a live c_int32)
131
- px[0]; // 42 (Python: px[0])
211
+ px[0]; // 42 (Python: px[0])
132
212
  px[0] = 100;
133
- x.value; // 100 (same memory)
213
+ x.value; // 100 (same memory)
134
214
 
135
215
  // View existing memory as a typed pointer
136
216
  const IntPtr = POINTER(c_int32);
137
217
  const p = IntPtr.fromBuffer(someBuffer);
138
- p[0]; p[1]; p[2]; // pointer arithmetic
218
+ p[0];
219
+ p[1];
220
+ p[2]; // pointer arithmetic
139
221
 
140
222
  // cast() — Python: cast(ptr, POINTER(T))
141
223
  const q = cast(someBuffer, POINTER(c_int32));
@@ -151,6 +233,21 @@ that cannot be converted (a plain JS function, an object) raise
151
233
  `ArgumentError` instead of passing NULL; `c_void_p` also accepts strings
152
234
  (as `char *`, Python `bytes`) and any TypedArray/ArrayBuffer.
153
235
 
236
+ Declared `POINTER(T)` parameters reject incompatible ctypes instances,
237
+ arrays and pointer types before entering C. Compatible subclasses and arrays
238
+ are accepted, and a matching scalar/structure is passed by reference.
239
+ An explicit `cast()` changes the pointer type. Raw addresses and raw
240
+ Buffer/TypedArray/ArrayBuffer memory remain node-ctypes extensions; use
241
+ `c_void_p` for portable raw-address code.
242
+
243
+ `byref(value, byteOffset = 0)` preserves the original owner and supports
244
+ signed byte offsets. In-range references remain Buffer views; references
245
+ outside the object's byte range carry an address and owner. As with raw
246
+ addresses, the caller must ensure such memory is valid before dereferencing.
247
+ Function pointers read from fields or obtained from FFI bindings can be
248
+ assigned back to fields/arrays and passed as pointer arguments. Bare JS
249
+ functions still require `callback()` / a prototype-created callback.
250
+
154
251
  ### Callbacks
155
252
 
156
253
  ```javascript
@@ -161,11 +258,7 @@ const CompareFn = CFUNCTYPE(c_int32, c_void_p, c_void_p);
161
258
  const cmp = new CompareFn((a, b) => readValue(a, c_int32) - readValue(b, c_int32));
162
259
 
163
260
  // Or the one-shot form:
164
- const cmp2 = callback(
165
- (a, b) => readValue(a, c_int32) - readValue(b, c_int32),
166
- c_int32,
167
- [c_void_p, c_void_p]
168
- );
261
+ const cmp2 = callback((a, b) => readValue(a, c_int32) - readValue(b, c_int32), c_int32, [c_void_p, c_void_p]);
169
262
 
170
263
  // Pass the callback itself (as in Python) or its address `cmp.pointer`.
171
264
  qsort(arr, 5, 4, cmp);
@@ -176,8 +269,23 @@ qsort(arr, 5, 4, cmp);
176
269
  // rely on GC — the callback holds a libffi closure that native code may
177
270
  // still reference.
178
271
  cmp.release();
272
+ cmp2.release();
179
273
  ```
180
274
 
275
+ `CFUNCTYPE` and `WINFUNCTYPE` weakly intern live prototypes by the complete
276
+ identity and order of their argument/return types, separately for each calling
277
+ convention. Repeated requests reuse the same live prototype, as in Python,
278
+ without keeping abandoned types alive. Callers, callbacks and output bindings
279
+ retain their prototype while they are live.
280
+
281
+ Prototype metadata is shared. Changing its public `restype` / `argtypes`
282
+ metadata does not recompile the captured native signature or alter cache keys;
283
+ request a different signature to change the ABI. Each new caller prepares its
284
+ argument-conversion pipeline and captures its result-check hook independently.
285
+ Existing callers retain their result-check snapshot and their own `errcheck`.
286
+ An installed `from_param` converter still resolves the method at call time,
287
+ as before.
288
+
181
289
  Both callbacks and libraries implement `Symbol.dispose`, so they work
182
290
  with the `using` declaration for scope-bound cleanup (also on `throw`):
183
291
 
@@ -189,12 +297,27 @@ with the `using` declaration for scope-bound cleanup (also on `throw`):
189
297
  } // close() + release() run automatically
190
298
  ```
191
299
 
300
+ A bound function keeps its library loaded as long as it is referenced, also
301
+ when the `CDLL` object itself is no longer used. After `close()`, `loaded` is
302
+ false and its bound functions and symbol lookups throw; `close()` itself
303
+ throws while a call to one of them is in progress (from a callback, or a
304
+ pending `callAsync()`). Repeated `close()` calls are harmless.
305
+
306
+ Existing `in_dll()` views keep the underlying module loaded even after
307
+ `close()`. Release of the native library handle is deferred until the last
308
+ dependent view, Buffer, typed array or typed pointer copy is collected; those
309
+ existing views remain usable. Actual physical unloading depends on the OS loader: for example,
310
+ musl keeps shared libraries resident until process exit even after `dlclose()`.
311
+ Raw addresses obtained with `symbol()` do not carry this ownership information.
312
+
192
313
  Set `NODE_CTYPES_DEBUG_CALLBACKS=1` to log a stack trace for every
193
314
  callback garbage-collected without `.release()`.
194
315
 
195
316
  Callbacks invoked by native threads need `threadSafeCallback()`: the
196
317
  JavaScript function runs on the main thread, and the calling thread waits
197
- for its result. Like a timer, a thread-safe callback keeps the event loop
318
+ for its result (several threads can call it at the same time; each gets the
319
+ result of its own call, `0` if the function throws). Like a timer, a
320
+ thread-safe callback keeps the event loop
198
321
  alive until released; `.unref()` lets the process exit when nothing else
199
322
  is pending (calls are still delivered while it runs), `.ref()` restores it:
200
323
 
@@ -203,24 +326,33 @@ const onEvent = threadSafeCallback((code) => console.log("event", code), null, [
203
326
  startWorker(onEvent); // a native library calling onEvent from its own thread
204
327
  ```
205
328
 
329
+ Both callback implementations store narrow integer results in a complete
330
+ libffi `ffi_arg`, with the declared signedness; failures zero that complete
331
+ slot. Floating-point results retain their own storage width. The native
332
+ `Callback` / `ThreadSafeCallback` classes also expose `getPointer()`, which
333
+ throws after release.
334
+
206
335
  ### Errors: `errno` and `GetLastError`
207
336
 
208
337
  `GetLastError()` / `get_errno()` read a **private thread-local slot** —
209
338
  exactly like Python's `ctypes.get_last_error()` / `ctypes.get_errno()`.
210
339
  The slot is updated **only** by FFI calls through libraries opened with
211
- `use_last_error` or `use_errno`; otherwise it stays at 0.
340
+ `use_last_error` or `use_errno`; unflagged calls leave it unchanged. As in Python
341
+ those calls swap it with the system value: the function sees the value set
342
+ with `set_errno()` / `set_last_error()`, the value it leaves becomes the
343
+ private one, and the system value is restored after the call.
212
344
 
213
345
  ```javascript
214
346
  const user32 = new WinDLL("user32.dll", { use_last_error: true });
215
347
  const FindWindow = user32.func("FindWindowW", c_void_p, [c_wchar_p, c_wchar_p]);
216
348
  FindWindow("NoSuchClass", null);
217
349
 
218
- GetLastError(); // top-level (Python: ctypes.get_last_error)
219
- user32.get_last_error(); // per-library alias
350
+ GetLastError(); // top-level (Python: ctypes.get_last_error)
351
+ user32.get_last_error(); // per-library alias
220
352
  ```
221
353
 
222
- The snapshot is captured atomically in native code immediately after
223
- `ffi_call`, before any other JS can clobber it. To read the raw system
354
+ The snapshot is captured in native code immediately after the native call,
355
+ whether direct or through libffi, before any other JS can clobber it. To read the raw system
224
356
  error instead, call `GetLastError` via FFI like any other function.
225
357
 
226
358
  ### Windows API
@@ -239,8 +371,14 @@ const kernel32 = new WinDLL("kernel32.dll");
239
371
 
240
372
  class SYSTEMTIME extends Structure {
241
373
  static _fields_ = [
242
- ["wYear", WORD], ["wMonth", WORD], ["wDayOfWeek", WORD], ["wDay", WORD],
243
- ["wHour", WORD], ["wMinute", WORD], ["wSecond", WORD], ["wMilliseconds", WORD],
374
+ ["wYear", WORD],
375
+ ["wMonth", WORD],
376
+ ["wDayOfWeek", WORD],
377
+ ["wDay", WORD],
378
+ ["wHour", WORD],
379
+ ["wMinute", WORD],
380
+ ["wSecond", WORD],
381
+ ["wMilliseconds", WORD],
244
382
  ];
245
383
  }
246
384
 
@@ -257,30 +395,106 @@ user32.GetClientRect(hwnd, byref(rect));
257
395
  rect.right - rect.left; // LONG (c_long) values are BigInt
258
396
  ```
259
397
 
398
+ ### Error checking (`errcheck`)
399
+
400
+ Set `fn.errcheck = (result, func, args) => ...` to check or replace a result,
401
+ or set it to `null` to clear it. For `lib.func()`, library attributes and
402
+ `CFUNCTYPE` / `WINFUNCTYPE` callers, `func` is the public callable and `args`
403
+ contains the original, unconverted arguments. Result conversion and any
404
+ `OleDLL` HRESULT check run before the hook.
405
+
406
+ Each invocation captures its hook before argument adapters or getters run.
407
+ Replacing or clearing it affects later invocations, including reentrant calls,
408
+ not the call already in progress or a pending `callAsync()` job.
409
+
410
+ Hooks do not prevent otherwise unreachable functions and libraries from being
411
+ garbage-collected, even when they reference the function itself. Active calls
412
+ and workers retain their captured hook through result checking; `close()` is
413
+ still rejected while that checking runs.
414
+
415
+ The low-level native handle's `setErrcheck()` API instead passes the native
416
+ handle as `func`, invoked with `.call()`, not a directly callable function.
417
+
418
+ ### Scalar subclasses and result hooks
419
+
420
+ Builtin scalar types return ordinary JS values. A subclass instead produces
421
+ an instance containing the original C bytes, without invoking its constructor,
422
+ public buffer factory or writer. Derived scalar fields, array elements,
423
+ pointer indexing and callback arguments likewise expose typed instances;
424
+ memory views remain live, including in mirror mode.
425
+
426
+ The result pipeline is:
427
+ `C bytes -> restype representation -> _check_retval_ -> errcheck -> OUT/INOUT`.
428
+ A static `_check_retval_` receives the represented result and can replace it
429
+ or throw. It is captured when the function is bound; reassigning an attribute's
430
+ `restype` rebuilds that binding.
431
+
432
+ ```javascript
433
+ class CheckedInt extends c_int32 {
434
+ static _check_retval_(value) {
435
+ return value.value + 100;
436
+ }
437
+ }
438
+ const checkedAbs = libc.func("abs", CheckedInt, [c_int32]);
439
+ checkedAbs(-7); // 107
440
+ ```
441
+
442
+ Explicit `HRESULT` validation runs before `errcheck` with all loaders and
443
+ prototype callers, not only `OleDLL`. An error in result checking prevents
444
+ both `errcheck` and output conversion.
445
+ `OleDLL` attributes and `func(name)` default to `HRESULT`; other loaders
446
+ default to `c_int`. An explicit restype always overrides the default.
447
+
260
448
  ### Output parameters (`paramflags`)
261
449
 
262
450
  When at least one `out` param is declared, the call returns **only the
263
451
  out-params** (single value, or array if >1) — the `restype` is
264
- discarded. To also inspect it (e.g. a `BOOL` success flag), attach an
452
+ discarded. To also inspect it (e.g. a thread ID or success flag), attach an
265
453
  `errcheck`:
266
454
 
267
455
  ```javascript
268
- const proto = WINFUNCTYPE(BOOL, HWND, POINTER(DWORD), POINTER(DWORD));
456
+ const { DWORD, HWND, LPDWORD } = wintypes;
457
+ const proto = WINFUNCTYPE(DWORD, HWND, LPDWORD);
269
458
  const fn = proto.bind(user32, "GetWindowThreadProcessId", [
270
459
  { dir: "in", name: "hWnd" },
271
460
  { dir: "out", name: "pid" },
272
- { dir: "out", name: "tid" },
273
461
  ]);
274
462
 
275
- const [pid, tid] = fn(hwnd); // positional
276
- const [p2, t2] = fn({ hWnd }); // or named-args
463
+ const pid = fn(hwnd); // positional; thread ID is discarded
464
+ const p2 = fn({ hWnd: hwnd }); // or named-args
465
+
466
+ fn.errcheck = (threadId, func, args) => {
467
+ if (!threadId) throw new Error("call failed");
468
+ return args; // continue returning the PID from the output instance
469
+ };
470
+ const p3 = await fn.callAsync(hwnd);
277
471
 
278
- fn.errcheck = (result, func, args) => {
279
- if (!result) throw new Error("call failed");
280
- return result; // ignored when outs exist
472
+ fn.errcheck = (threadId, func, args) => {
473
+ if (!threadId) throw new Error("call failed");
474
+ return { threadId, processId: args[1].value };
281
475
  };
476
+ const ids = fn(hwnd); // inspect both the return value and the output parameter
282
477
  ```
283
478
 
479
+ As in Python, the value returned by `errcheck` is the result of the call,
480
+ unless it is `args` itself: then the out-params are returned. Here `args`
481
+ is the expanded argument list, with out-params as instances.
482
+
483
+ These bindings have their own hook, independent of any cached `lib.func()`
484
+ binding, and support `callAsync()` with the same output processing and
485
+ per-call hook snapshot. Adapter temporaries stay alive through that processing,
486
+ also when the hook throws.
487
+
488
+ OUT conversion invokes the output instance's `__ctypes_from_outparam__()`.
489
+ By default a builtin scalar yields its value, while a scalar subclass yields
490
+ the instance. Override the method for custom output conversion.
491
+
492
+ Use `{ dir: "inout", name: "value" }`, or tuple flag `3`, to pass an existing
493
+ instance and return that exact instance after C modifies it. INOUT does not
494
+ call `__ctypes_from_outparam__`; positional, named and default arguments use
495
+ the same rule. Mixed outputs preserve parameter order. If `errcheck` returns
496
+ anything other than the original `args`, neither OUT nor INOUT unpacking runs.
497
+
284
498
  ### Sharing memory with existing buffers
285
499
 
286
500
  ```javascript
@@ -299,10 +513,28 @@ const bytes = array(c_uint8, 64).from_address(malloc_result);
299
513
  const view = new Float32Array(bytes._buffer.buffer, bytes._buffer.byteOffset, 16);
300
514
  ```
301
515
 
516
+ Typed pointers read from fields or array elements, and views derived from
517
+ them, retain their known memory owners. Typed assignments and
518
+ `from_buffer_copy()` preserve known pointer references, including overlapping
519
+ and self-copies; replacing a pointer releases its previous reference.
520
+
521
+ Raw copies (`memmove()`, Buffer methods) do not transfer ownership metadata.
522
+ Likewise, `from_address()` given a raw address cannot discover its allocation
523
+ or library: the caller must keep that memory valid. Keeping a known owner
524
+ alive does not take over responsibility for freeing externally allocated
525
+ memory or explicitly releasing callbacks.
526
+
527
+ `memmove()` and `memset()` return the destination address as BigInt, including
528
+ zero-length operations (`0n` for a NULL destination with count zero).
529
+ Counts must be non-negative safe integers. Copies/fills involving JS memory
530
+ still stop at its end; raw native addresses remain the caller's responsibility.
531
+ Scalar `from_buffer()` / `from_buffer_copy()` validate byte size and offset
532
+ before producing an instance and accept Buffer, typed views and ctypes memory.
533
+
302
534
  ### Electron
303
535
 
304
536
  Electron does not allow Buffers over memory that V8 did not allocate, so a
305
- Buffer *view* of native memory cannot exist there. node-ctypes detects this
537
+ Buffer _view_ of native memory cannot exist there. node-ctypes detects this
306
538
  when it loads (`EXTERNAL_BUFFERS` is `false`) and keeps the same API:
307
539
 
308
540
  - instances on native memory (`from_address`, `in_dll`, `pointer.contents`,
@@ -316,8 +548,8 @@ when it loads (`EXTERNAL_BUFFERS` is `false`) and keeps the same API:
316
548
  (`arr[i]`, `s.field`) or `memmove()`.
317
549
 
318
550
  Only the bytes of the accessed field are copied, one native call per read
319
- or write (about 50 ns); instances on ordinary Buffers (`new Point()`,
320
- `c_int(5)`) have no extra cost. Set `NODE_CTYPES_NO_EXTERNAL_BUFFERS=1`
551
+ or write; instances on ordinary Buffers (`new Point()`, `c_int(5)`) do not
552
+ need this native-memory synchronization. Set `NODE_CTYPES_NO_EXTERNAL_BUFFERS=1`
321
553
  to run in this mode on Node.js.
322
554
 
323
555
  ### Adapter protocols: `_as_parameter_` and `from_param`
@@ -325,18 +557,42 @@ to run in this mode on Node.js.
325
557
  ```javascript
326
558
  // Instance protocol: auto-unwrap on call
327
559
  class Handle {
328
- constructor(h) { this._as_parameter_ = h; }
560
+ constructor(h) {
561
+ this._as_parameter_ = h;
562
+ }
329
563
  }
330
564
  user32.CloseHandle(new Handle(hwnd));
331
565
 
332
566
  // Class protocol: custom conversion in argtypes
333
567
  class StrLen extends c_int32 {
334
- static from_param(s) { return typeof s === "string" ? s.length : s; }
568
+ static from_param(s) {
569
+ return typeof s === "string" ? s.length : s;
570
+ }
335
571
  }
336
572
  const abs = libc.func("abs", c_int32, [StrLen]);
337
573
  abs("hello"); // 5
338
574
  ```
339
575
 
576
+ As in Python, `from_param` receives the argument as passed (also with
577
+ `CFUNCTYPE` prototypes), its result is converted as the declared type, and
578
+ an error it throws becomes `ArgumentError` (`"argument 1: RangeError: ..."`).
579
+
580
+ Objects passed through argument adapters and the objects produced by their
581
+ conversions stay alive while later arguments are converted and until the
582
+ result and `errcheck` have been processed. With `callAsync()`, those temporary
583
+ owners stay alive until its Promise settles. The native worker also retains
584
+ memory passed by value or as an integer address, including values materialized
585
+ by getters.
586
+
587
+ `_as_parameter_` chains are resolved recursively, including results of
588
+ `from_param`, with intermediate owners retained. Cycles and chains exceeding
589
+ 128 adapter steps raise explicit argument errors, rather than overflowing
590
+ the stack or silently passing an incorrect pointer.
591
+
592
+ This only covers the call: if C stores a pointer for later use, or returns a
593
+ pointer into an argument's memory, keep the source object referenced for as
594
+ long as that pointer is used. Callbacks still require explicit `.release()`.
595
+
340
596
  ### Big-endian structures
341
597
 
342
598
  ```javascript
@@ -353,14 +609,21 @@ h.magic = 0x12345678; // stored as 12 34 56 78 on the wire
353
609
  `LittleEndianStructure`, `BigEndianUnion`, `LittleEndianUnion` work the
354
610
  same way. Byte order is per-class — nested structs keep their own.
355
611
 
612
+ Primitive arrays also follow their containing class's byte order, recursively
613
+ for multidimensional arrays, including floats and wide-character arrays.
614
+ Arrays of structures keep the element structure's own byte order. The same
615
+ array type can be shared with native/little-endian containers without being
616
+ modified. Raw Buffer and typed-memory copies still copy bytes, not values
617
+ converted between byte orders.
618
+
356
619
  ### TypeScript
357
620
 
358
- Argument and return types are narrowed when `argTypes` is a literal
359
- tuple (`as const`) and `returnType` is a CType constant:
621
+ Argument and return types are inferred from declared type classes such as
622
+ `c_int32` and `c_size_t`. A literal tuple (`as const`) preserves argument types:
360
623
 
361
624
  ```ts
362
625
  const libc = new CDLL(null);
363
- const strlen = libc.func("strlen", c_int64, [c_char_p] as const);
626
+ const strlen = libc.func("strlen", c_size_t, [c_char_p] as const);
364
627
  const n: bigint = strlen("hello"); // typed as bigint, not any
365
628
  ```
366
629
 
@@ -370,7 +633,9 @@ const n: bigint = strlen("hello"); // typed as bigint, not any
370
633
 
371
634
  ```ts
372
635
  class Point extends defineStruct({ x: c_int32, y: c_int32 }) {
373
- distance() { return Math.sqrt(this.x ** 2 + this.y ** 2); }
636
+ distance() {
637
+ return Math.sqrt(this.x ** 2 + this.y ** 2);
638
+ }
374
639
  }
375
640
  const p = new Point({ x: 3, y: 4 }); // p.x, p.y typed as number
376
641
  ```
@@ -380,10 +645,10 @@ types are typed too; a `null` return type is `void`:
380
645
 
381
646
  ```ts
382
647
  const PointDef = struct({ x: c_int32, y: c_double });
383
- PointDef.get(buf, "y"); // number
384
- POINTER(c_int32).fromAddress(addr)[0]; // number (.contents: c_int32 instance)
385
- array(c_int32, 4).create([1, 2, 3, 4])[0]; // number
386
- libc.func("srand", null, [c_uint32]); // returns undefined
648
+ PointDef.get(buf, "y"); // number
649
+ POINTER(c_int32).fromAddress(addr)[0]; // number (.contents: c_int32 instance)
650
+ array(c_int32, 4).create([1, 2, 3, 4])[0]; // number
651
+ libc.func("srand", null, [c_uint32]); // returns undefined
387
652
  ```
388
653
 
389
654
  ---
@@ -392,30 +657,30 @@ libc.func("srand", null, [c_uint32]); // returns undefined
392
657
 
393
658
  ### Primitive types
394
659
 
395
- | Type | Aliases | Size | Notes |
396
- | ----------- | -------------- | -------- | --------------------------------------------- |
397
- | `c_int8` | `c_byte` | 1 | |
398
- | `c_uint8` | `c_ubyte` | 1 | |
399
- | `c_int16` | `c_short` | 2 | |
400
- | `c_uint16` | `c_ushort` | 2 | |
401
- | `c_int32` | `c_int` | 4 | |
402
- | `c_uint32` | `c_uint` | 4 | |
403
- | `c_int64` | `c_longlong` | 8 | |
404
- | `c_uint64` | `c_ulonglong` | 8 | |
405
- | `c_long` | | platform | 4 on Windows, 8 on Unix 64-bit; BigInt values |
406
- | `c_ulong` | | platform | mirrors `c_long`; BigInt values |
407
- | `c_float` | | 4 | |
408
- | `c_double` | | 8 | |
409
- | `c_bool` | | 1 | |
410
- | `c_char` | | 1 | 1-char string (Python `bytes`); also 0..255 |
411
- | `c_wchar` | | 2 or 4 | 1-char string; 2 on Windows, 4 on Unix |
412
- | `c_char_p` | | pointer | `char *` (NUL-terminated) |
413
- | `c_wchar_p` | | pointer | `wchar_t *` (NUL-terminated wide) |
414
- | `c_void_p` | `c_voidp` | pointer | opaque pointer / `HANDLE` |
415
- | `c_time_t` | | 8 | `time_t` (`SIZEOF_TIME_T`) |
416
- | `c_size_t` | | pointer | pointer-sized unsigned integer |
417
- | `c_ssize_t` | | pointer | pointer-sized signed integer |
418
- | `HRESULT` | | 4 | `c_int32` subclass — auto-raise on `OleDLL` |
660
+ | Type | Aliases | Size | Notes |
661
+ | ----------- | ------------- | -------- | --------------------------------------------- |
662
+ | `c_int8` | `c_byte` | 1 | |
663
+ | `c_uint8` | `c_ubyte` | 1 | |
664
+ | `c_int16` | `c_short` | 2 | |
665
+ | `c_uint16` | `c_ushort` | 2 | |
666
+ | `c_int32` | `c_int` | 4 | |
667
+ | `c_uint32` | `c_uint` | 4 | |
668
+ | `c_int64` | `c_longlong` | 8 | |
669
+ | `c_uint64` | `c_ulonglong` | 8 | |
670
+ | `c_long` | | platform | 4 on Windows, 8 on Unix 64-bit; BigInt values |
671
+ | `c_ulong` | | platform | mirrors `c_long`; BigInt values |
672
+ | `c_float` | | 4 | |
673
+ | `c_double` | | 8 | |
674
+ | `c_bool` | | 1 | |
675
+ | `c_char` | | 1 | 1-char string (Python `bytes`); also 0..255 |
676
+ | `c_wchar` | | 2 or 4 | 1-char string; 2 on Windows, 4 on Unix |
677
+ | `c_char_p` | | pointer | `char *` (NUL-terminated) |
678
+ | `c_wchar_p` | | pointer | `wchar_t *` (NUL-terminated wide) |
679
+ | `c_void_p` | `c_voidp` | pointer | opaque pointer / `HANDLE` |
680
+ | `c_time_t` | | 8 | `time_t` (`SIZEOF_TIME_T`) |
681
+ | `c_size_t` | | pointer | pointer-sized unsigned integer |
682
+ | `c_ssize_t` | | pointer | pointer-sized signed integer |
683
+ | `HRESULT` | | 4 | `c_int32` subclass — auto-raise on `OleDLL` |
419
684
 
420
685
  Plus the Win32 types, structures and pointer types of `ctypes.wintypes` under `wintypes`.
421
686
 
@@ -443,9 +708,9 @@ Plus the Win32 types, structures and pointer types of `ctypes.wintypes` under `w
443
708
 
444
709
  - `sizeof(type)` / `alignment(type)` — in bytes
445
710
  - `addressof(obj)` → BigInt
446
- - `byref(obj)` — lightweight pass-by-reference marker
711
+ - `byref(obj, byteOffset = 0)` — lightweight reference with a signed byte offset
447
712
  - `cast(ptr, type)` — reinterpret a pointer as another type
448
- - `memmove(dst, src, n)` / `memset(dst, val, n)` — buffers, ctypes instances, pointers or addresses
713
+ - `memmove(dst, src, n)` / `memset(dst, val, n)` — buffers, ctypes instances, pointers or addresses; return the destination address as BigInt
449
714
  - `readValue(ptr, type, offset?)` / `writeValue(ptr, type, val, offset?)`
450
715
  - `create_string_buffer(init, size?)` / `c_buffer` / `create_unicode_buffer(init, size?)` — with `.value` (and `.raw`)
451
716
  - `string_at(addr, size?)` / `wstring_at(addr, size?)` — exactly `size` units, or up to the NUL
@@ -471,7 +736,9 @@ Plus the Win32 types, structures and pointer types of `ctypes.wintypes` under `w
471
736
 
472
737
  ### What works identically
473
738
 
474
- Structs, unions, bit fields, anonymous fields, `_pack_`, nested layouts,
739
+ Structs, unions, bit fields (`_layout_` `"gcc-sysv"` / `"ms"`), anonymous
740
+ fields, `_pack_`, `_align_`, subclasses of structures and unions, nested layouts,
741
+ structures and unions by value (a struct `restype` returns an instance),
475
742
  arrays (also of arrays, pointers and function pointers), pointers and
476
743
  pointer arithmetic (also `POINTER(POINTER(T))`), callbacks (`CFUNCTYPE` /
477
744
  `WINFUNCTYPE`, also as struct fields), `prototype((name, dll), paramflags)`,
@@ -488,8 +755,8 @@ pointer arithmetic (also `POINTER(POINTER(T))`), callbacks (`CFUNCTYPE` /
488
755
  - **No automatic memory management** for returned pointers.
489
756
  - **Both class and functional syntax**: `class extends Structure`
490
757
  (Python-like) and `struct({...})` (functional) are both supported.
491
- - **Only type classes**, not string literals: `c_int32`, never `"int32"`
492
- — same as Python.
758
+ - **Use type classes** such as `c_int32`, rather than string names such as
759
+ `"int32"`, for the Python-compatible, typed API.
493
760
  - **`bytes` are JS strings**: `c_char` values, `c_char * n` arrays and
494
761
  fields, `c_char_p` and `create_string_buffer().value` use strings (UTF-8)
495
762
  where Python uses `bytes`; `.raw` is a `Buffer`.
@@ -501,36 +768,62 @@ pointer arithmetic (also `POINTER(POINTER(T))`), callbacks (`CFUNCTYPE` /
501
768
  (Python: Windows only), so the same code runs everywhere.
502
769
  - **64-bit and pointer-sized integers** (`c_int64`, `c_uint64`,
503
770
  `c_size_t`, `c_ssize_t`) also accept `null` (as 0) and a `Buffer`
504
- (as its address).
771
+ or `ArrayBuffer` (as its address) as arguments.
772
+ - **Variadic arguments follow the C promotions**: a `c_float`, `c_int8`,
773
+ `c_char`, … instance passed beyond `argtypes` is passed as `double` /
774
+ `int`, where Python fails (`ffi_prep_cif_var failed`).
775
+ - **A plain object is accepted for a structure argument** passed by value
776
+ (fields by name).
777
+ - **`c_wchar` also accepts a code point** (`new c_wchar(0x4E2D)`), where
778
+ Python requires a 1-character string.
779
+ - **`memmove()` / `memset()` stop at the end of JS memory** (Buffer, typed
780
+ array, `ArrayBuffer`) instead of writing past it.
781
+ - **Integer types reject non-integral numbers** (`3.7`, `NaN`) as Python
782
+ rejects floats; JS has no int/float distinction, so `3.0` is accepted.
783
+ - **Floating-point scalars accept BigInt in the range `-2**63` to `2**64-1`**,
784
+ converted to a JS number; larger BigInts raise a range error. This applies
785
+ consistently to constructors, fields and function arguments.
786
+ - **Array instances are Buffers whose Array methods work on the elements**
787
+ (`slice`, `map`, `includes`, …, as Python sequences); the Buffer methods
788
+ (`readInt32LE`, `subarray`, …) work on the bytes.
789
+ - **Array index reads follow JavaScript bounds behavior**: out-of-range
790
+ indices return `undefined`; negative indices do not wrap around as in Python.
791
+ - **Unions by value on x86-64 System V** are passed with the ABI rules;
792
+ Python passes them in the wrong registers (libffi#33).
793
+ - **Structure/Union fields are accessors of the class**, as Python fields
794
+ are descriptors (`vars(s)` is empty): `Object.keys(s)` and `{ ...s }` do
795
+ not list them; use `s.toObject()`. `JSON.stringify(s)` and
796
+ `console.log(s)` show the fields.
505
797
 
506
798
  ### Not supported
507
799
 
508
- - **`ctypes.resize(instance, size)`** — our Structure/Union instances are
509
- `Proxy` objects wrapping a Node `Buffer`; Buffers aren't resizable in
510
- place, and re-pointing the Proxy target would break identity.
800
+ - **`ctypes.resize(instance, size)`** — Structure/Union instances use a
801
+ Node `Buffer`, and Buffers aren't resizable in place.
511
802
  Work-around: `new MyStruct(myBuffer)` with a pre-sized buffer.
512
803
  - **`c_longdouble`** (80/128-bit float, `ffi_type_longdouble`) — rarely
513
- used; fall back to `c_double` or raw bytes.
804
+ used; use a native wrapper that converts to supported types, or access
805
+ storage through pointers/bytes. Declaring a `long double` ABI value as
806
+ `c_double` is not a portable substitute.
514
807
 
515
808
  ### Migrating from 1.x
516
809
 
517
810
  2.0 follows Python ctypes more closely. Code relying on the 1.x behavior
518
811
  needs these changes:
519
812
 
520
- | 1.x | 2.0 (as Python) |
521
- | --- | --- |
522
- | `ptr.contents` returned the value | returns a live instance: `ptr.contents.value` (simple types), `ptr.contents.x` (structs); `ptr[0]` still returns the value |
523
- | `POINTER(T)` restype returned a `bigint` address | returns a pointer object (`null` for NULL); use `.address` for the number |
524
- | NULL `POINTER` struct fields were pointer objects | they are `null` |
525
- | `c_char` values were numbers | 1-character strings; `c_char * n` fields read/write as strings |
526
- | invalid `c_char` values were truncated | `TypeError` (`"one character bytes, bytearray or integer expected"`) |
527
- | wrong argument types raised `TypeError` | raise `ArgumentError` (a `TypeError` subclass), message `"argument N: TypeError: ..."` |
528
- | unsupported pointer arguments (functions, plain objects) passed NULL | raise `ArgumentError` (`"wrong type"`) |
529
- | functions without `restype` / `argtypes` | default `restype` is `c_int`; without `argtypes` the call uses the fixed-argument ABI |
530
- | `create_string_buffer(init)` | also takes `size` and returns a Buffer with `.value` / `.raw` |
531
- | `c_long` / `c_ulong` (and `BOOL`, `LONG`, `DWORD`, `ULONG`) fields and `.value` were numbers on Windows | `BigInt` on every platform, like function results; writes accept numbers and BigInt |
532
- | `wintypes.CHAR` was `c_ubyte`; `LPDWORD`, `PDWORD`, `LPBYTE`, `PBYTE`, `PHKEY` were `c_void_p` | as Python: `CHAR = c_char` and pointer types are `POINTER(T)` (fields and results are pointer objects) |
533
- | `string_at(addr, n)` / `wstring_at(addr, n)` stopped at the first NUL | read exactly `n` units; without `n`, `wstring_at` reads up to the NUL (no 256-character limit) |
813
+ | 1.x | 2.0 (as Python) |
814
+ | ------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
815
+ | `ptr.contents` returned the value | returns a live instance: `ptr.contents.value` (simple types), `ptr.contents.x` (structs); `ptr[0]` still returns the value |
816
+ | `POINTER(T)` restype returned a `bigint` address | returns a pointer object (`null` for NULL); use `.address` for the number |
817
+ | NULL `POINTER` struct fields were pointer objects | they are `null` |
818
+ | `c_char` values were numbers | 1-character strings; `c_char * n` fields read/write as strings |
819
+ | invalid `c_char` values were truncated | `TypeError` (`"one character bytes, bytearray, or an integer in range(256) expected, not ..."`) |
820
+ | wrong argument types raised `TypeError` | raise `ArgumentError` (a `TypeError` subclass), message `"argument N: TypeError: ..."` |
821
+ | unsupported pointer arguments (functions, plain objects) passed NULL | raise `ArgumentError` (`"'function' object cannot be interpreted as ctypes.c_void_p"`) |
822
+ | functions without `restype` / `argtypes` | default `restype` is `c_int`; without `argtypes` the call uses the fixed-argument ABI |
823
+ | `create_string_buffer(init)` | also takes `size` and returns a Buffer with `.value` / `.raw` |
824
+ | `c_long` / `c_ulong` (and `BOOL`, `LONG`, `DWORD`, `ULONG`) fields and `.value` were numbers on Windows | `BigInt` on every platform, like function results; writes accept numbers and BigInt |
825
+ | `wintypes.CHAR` was `c_ubyte`; `LPDWORD`, `PDWORD`, `LPBYTE`, `PBYTE`, `PHKEY` were `c_void_p` | as Python: `CHAR = c_char` and pointer types are `POINTER(T)` (fields and results are pointer objects) |
826
+ | `string_at(addr, n)` / `wstring_at(addr, n)` stopped at the first NUL | read exactly `n` units; without `n`, `wstring_at` reads up to the NUL (no 256-character limit) |
534
827
 
535
828
  ---
536
829
 
@@ -551,17 +844,129 @@ Each example in `examples/` has its own README; see the [index](examples/README.
551
844
 
552
845
  ## Tests & docs
553
846
 
847
+ From the repository root, `npm --prefix tests test` first builds a small C library (`tests/fixtures/`, into
848
+ `build/fixture/`) used by the tests of structures by value, array parameters
849
+ and reentrant calls; `npm run build:test-fixture` builds it alone. Python
850
+ twins of the tests (`tests/common/*.py`) load the same library.
851
+
554
852
  ```bash
555
- cd tests && npm install && npm run test # unit tests (JS + Python parity)
556
- NODE_CTYPES_NO_EXTERNAL_BUFFERS=1 npm test # again as in Electron (from tests/)
557
- npm run test:types # type-check lib/index.d.ts (tests/types)
558
- npm run docs # TypeDoc API site in docs/
559
- npm run docs:serve # preview
853
+ npm install
854
+ npm run build
855
+ npm --prefix tests install
856
+ npm --prefix tests test # functional/parity tests
857
+ NODE_CTYPES_NO_EXTERNAL_BUFFERS=1 npm --prefix tests test # mirrored native memory
858
+ npm run test:types # TypeScript declarations
859
+ npm run docs # TypeDoc API site in docs/
860
+ npm run docs:serve # preview
560
861
  ```
561
862
 
562
- See [tests/common/](tests/common/) for runnable examples alongside
863
+ See [tests/common/](https://github.com/dmazzella/node-ctypes/tree/main/tests/common) for runnable examples alongside
563
864
  parallel Python ctypes implementations.
564
865
 
866
+ ### Performance comparisons
867
+
868
+ There are two JavaScript comparisons, both against another FFI library.
869
+ From the repository root, after building node-ctypes:
870
+
871
+ ```bash
872
+ npm --prefix tests install # includes Koffi
873
+ npm run build:test-fixture # shared C functions for both libraries
874
+ npm run bench:koffi # node-ctypes vs Koffi; Node 24+
875
+ npm run bench:ffi # node-ctypes vs node:ffi; Node 26+
876
+ ```
877
+
878
+ The private test package explicitly approves the install script for Koffi 3.3.3.
879
+ When upgrading Koffi, review the new version before updating that approval with
880
+ `npm --prefix tests install-scripts approve koffi`; future versions are not
881
+ automatically authorized.
882
+
883
+ `bench:ffi` adds `--experimental-ffi` automatically. Both comparisons
884
+ print a table grouped by workload and automatically generate HTML reports:
885
+
886
+ - `tests/benchmarks/results/koffi.html`
887
+ - `tests/benchmarks/results/node-ffi.html`
888
+
889
+ These paths are relative to the repository root, regardless of the working
890
+ directory. Each successful run replaces its previous report; generated results
891
+ are ignored by Git. Open the HTML file directly in a browser: it is responsive
892
+ and self-contained, with native HTML/CSS bar charts and no browser JavaScript,
893
+ external resources or server requirements.
894
+
895
+ | Column | Meaning |
896
+ | ------------------------ | ----------------------------------------------------- |
897
+ | Case | The same operation and inputs for both libraries |
898
+ | node-ctypes / competitor | Median time +/- MAD (dispersion), in ns per operation |
899
+ | Ratio | node-ctypes time divided by competitor time |
900
+
901
+ A ratio of `0.50x` means node-ctypes took half the time; `2.00x` means it
902
+ took twice the time. Lower times are better. There is no overall score
903
+ combining unrelated calls, memory access and asynchronous scheduling.
904
+ In the charts, **shorter bars are better**. Each workload group shares a linear
905
+ scale starting at zero; different groups use different scales. Bars show
906
+ medians, with +/- MAD whiskers (not confidence intervals). Each library also
907
+ shows its total measured operation count and elapsed time across the samples.
908
+
909
+ Reports record library/runtime versions, CPU, OS/kernel, buffer mode, start/
910
+ finish timestamps and Git revision/working-tree status. Missing CPU or Git
911
+ metadata produces an explicit warning rather than invented values.
912
+
913
+ The comparisons cover scalars, mixed arguments, short/long strings, buffer
914
+ arguments, field reads and callbacks. Koffi also covers structures by value,
915
+ variadic calls and async calls with 1/8 calls in flight. Cases without an
916
+ equivalent documented node:ffi API are listed as **not compared**, not
917
+ emulated with a different native signature.
918
+
919
+ Both sides call the same C fixture and verify results before/after timing.
920
+ String lengths are compared as Numbers, including conversion where the API
921
+ returns BigInt; wide integers are BigInt in both APIs. Structures are plain
922
+ objects. Async times include scheduling and are reported per completed call,
923
+ with the concurrency shown in the case name.
924
+
925
+ Defaults are nine samples of at least 250 ms per library after warmup,
926
+ alternating library order. Each native signature has a separate call-site to
927
+ avoid mixing V8 optimization feedback between cases.
928
+ Each row is printed when its measurements finish.
929
+ Run comparisons serially, not concurrently. Optional arguments:
930
+
931
+ ```bash
932
+ npm run bench:koffi -- --filter string,callback
933
+ npm run bench:ffi -- --samples 11 --duration 500
934
+ npm run bench:koffi -- --output comparison.json
935
+ ```
936
+
937
+ `--output comparison.json` additionally saves medians, dispersion and all sample
938
+ durations/operation counts as JSON, and writes `comparison.html` next to it
939
+ instead of the default HTML report. Parent directories are created automatically.
940
+ HTML generation runs only after all measurements finish.
941
+ `benchmark_koffi.js` and `benchmark_node_ffi.js` define the actual side-by-side
942
+ comparisons; `runner.js` shares timing, table output and HTML generation without
943
+ extra dependencies or a separate renderer script. There is no separate
944
+ self-benchmark command, and benchmarks are not run by the functional/parity
945
+ test suite.
946
+
947
+ ### Release validation
948
+
949
+ The workflow retains the eight Node 24 native build targets (Windows/macOS,
950
+ x64/ARM64, and Linux glibc/musl). C++20 conformance is checked with
951
+ `-pedantic-errors` on GCC/Clang and `/permissive-` on MSVC; vendor optimization
952
+ and the node-addon-api integration remain unchanged.
953
+
954
+ Three runtime-control jobs reuse the built artifacts on Node 26 without
955
+ rebuilding the addon, running the functional parity suite normally and with
956
+ mirrored buffers. A Linux job runs the focused Python 3.15
957
+ reference tests in addition to the Python 3.14 reference coverage.
958
+
959
+ The package assembler requires all eight nonempty binaries and includes
960
+ declarations, README, changelog and license. It fails on missing/unknown
961
+ artifacts or a stale output directory. Publish depends on the runtime gates,
962
+ requires a pushed tag matching the manifest version exactly, and uses `next`
963
+ for prereleases instead of `latest`. Manual workflow runs never publish.
964
+ These are configured gates, not a substitute for a successful native CI run.
965
+
966
+ `npm --prefix tests test` builds the fixture and runs the suite;
967
+ `npm --prefix tests run test:js` reuses an already-built fixture/addon.
968
+ Both use the documented `--test-timeout` runner option.
969
+
565
970
  ---
566
971
 
567
972
  ## License