node-ctypes 2.3.0 → 2.5.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.
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,12 +132,31 @@ 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
+
118
140
  An array type in `argtypes` is passed by address, as in C and Python
119
141
  (`fill.argtypes = [c_int32 * 4]`). As in Python, the argument must be an
120
142
  instance of an array with the same element type and length; a Buffer or a
121
143
  typed array is also accepted as its memory. Other values raise
122
144
  `ArgumentError`.
123
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
+
124
160
  Nested structs, anonymous fields (`static _anonymous_ = ["data"]`),
125
161
  explicit packing (`static _pack_ = 1`), minimum alignment
126
162
  (`static _align_ = 16`), self-referential pointers (`POINTER(() => Node)`)
@@ -129,11 +165,40 @@ Python. The layout of bit fields follows Python's `_layout_`: `"gcc-sysv"`
129
165
  by default, `"ms"` on Windows or with `_pack_`. Bit fields wider than 53
130
166
  bits read as BigInt.
131
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
+
132
174
  Structures and unions passed or returned by value keep this layout, also
133
175
  with `_pack_`: as with GCC and clang, a structure with misaligned fields is
134
176
  passed in memory on x86-64 System V (Linux, macOS Intel), where Python
135
177
  ctypes passes it in registers and the called function reads wrong values.
136
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.
201
+
137
202
  ### Pointers, buffers, and cast
138
203
 
139
204
  ```javascript
@@ -143,14 +208,16 @@ import { POINTER, pointer, cast, c_int32, c_void_p } from "node-ctypes";
143
208
  const x = new c_int32(42);
144
209
  const px = pointer(x);
145
210
  px.contents.value; // 42 (Python: px.contents.value — a live c_int32)
146
- px[0]; // 42 (Python: px[0])
211
+ px[0]; // 42 (Python: px[0])
147
212
  px[0] = 100;
148
- x.value; // 100 (same memory)
213
+ x.value; // 100 (same memory)
149
214
 
150
215
  // View existing memory as a typed pointer
151
216
  const IntPtr = POINTER(c_int32);
152
217
  const p = IntPtr.fromBuffer(someBuffer);
153
- p[0]; p[1]; p[2]; // pointer arithmetic
218
+ p[0];
219
+ p[1];
220
+ p[2]; // pointer arithmetic
154
221
 
155
222
  // cast() — Python: cast(ptr, POINTER(T))
156
223
  const q = cast(someBuffer, POINTER(c_int32));
@@ -166,6 +233,24 @@ that cannot be converted (a plain JS function, an object) raise
166
233
  `ArgumentError` instead of passing NULL; `c_void_p` also accepts strings
167
234
  (as `char *`, Python `bytes`) and any TypedArray/ArrayBuffer.
168
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
+ These implicit scalar/array/NULL conversions apply to direct arguments only.
240
+ To adapt one of these values through `_as_parameter_`, return an explicit
241
+ compatible pointer or `byref` value instead, as in CPython.
242
+ An explicit `cast()` changes the pointer type. Raw addresses and raw
243
+ Buffer/TypedArray/ArrayBuffer memory remain node-ctypes extensions; use
244
+ `c_void_p` for portable raw-address code.
245
+
246
+ `byref(value, byteOffset = 0)` preserves the original owner and supports
247
+ signed byte offsets. In-range references remain Buffer views; references
248
+ outside the object's byte range carry an address and owner. As with raw
249
+ addresses, the caller must ensure such memory is valid before dereferencing.
250
+ Function pointers read from fields or obtained from FFI bindings can be
251
+ assigned back to fields/arrays and passed as pointer arguments. Bare JS
252
+ functions still require `callback()` / a prototype-created callback.
253
+
169
254
  ### Callbacks
170
255
 
171
256
  ```javascript
@@ -176,11 +261,7 @@ const CompareFn = CFUNCTYPE(c_int32, c_void_p, c_void_p);
176
261
  const cmp = new CompareFn((a, b) => readValue(a, c_int32) - readValue(b, c_int32));
177
262
 
178
263
  // Or the one-shot form:
179
- const cmp2 = callback(
180
- (a, b) => readValue(a, c_int32) - readValue(b, c_int32),
181
- c_int32,
182
- [c_void_p, c_void_p]
183
- );
264
+ const cmp2 = callback((a, b) => readValue(a, c_int32) - readValue(b, c_int32), c_int32, [c_void_p, c_void_p]);
184
265
 
185
266
  // Pass the callback itself (as in Python) or its address `cmp.pointer`.
186
267
  qsort(arr, 5, 4, cmp);
@@ -191,8 +272,23 @@ qsort(arr, 5, 4, cmp);
191
272
  // rely on GC — the callback holds a libffi closure that native code may
192
273
  // still reference.
193
274
  cmp.release();
275
+ cmp2.release();
194
276
  ```
195
277
 
278
+ `CFUNCTYPE` and `WINFUNCTYPE` weakly intern live prototypes by the complete
279
+ identity and order of their argument/return types, separately for each calling
280
+ convention. Repeated requests reuse the same live prototype, as in Python,
281
+ without keeping abandoned types alive. Callers, callbacks and output bindings
282
+ retain their prototype while they are live.
283
+
284
+ Prototype metadata is shared. Changing its public `restype` / `argtypes`
285
+ metadata does not recompile the captured native signature or alter cache keys;
286
+ request a different signature to change the ABI. Each new caller prepares its
287
+ argument-conversion pipeline and captures its result-check hook independently.
288
+ Existing callers retain their result-check snapshot and their own `errcheck`.
289
+ An installed `from_param` converter still resolves the method at call time,
290
+ as before.
291
+
196
292
  Both callbacks and libraries implement `Symbol.dispose`, so they work
197
293
  with the `using` declaration for scope-bound cleanup (also on `throw`):
198
294
 
@@ -204,10 +300,18 @@ with the `using` declaration for scope-bound cleanup (also on `throw`):
204
300
  } // close() + release() run automatically
205
301
  ```
206
302
 
207
- A function keeps its library loaded as long as it is referenced, also when
208
- the `CDLL` object itself is no longer used. After `close()`, its functions
209
- throw instead of calling unloaded code; `close()` itself throws while a call
210
- to one of them is in progress (from a callback, or a pending `callAsync()`).
303
+ A bound function keeps its library loaded as long as it is referenced, also
304
+ when the `CDLL` object itself is no longer used. After `close()`, `loaded` is
305
+ false and its bound functions and symbol lookups throw; `close()` itself
306
+ throws while a call to one of them is in progress (from a callback, or a
307
+ pending `callAsync()`). Repeated `close()` calls are harmless.
308
+
309
+ Existing `in_dll()` views keep the underlying module loaded even after
310
+ `close()`. Release of the native library handle is deferred until the last
311
+ dependent view, Buffer, typed array or typed pointer copy is collected; those
312
+ existing views remain usable. Actual physical unloading depends on the OS loader: for example,
313
+ musl keeps shared libraries resident until process exit even after `dlclose()`.
314
+ Raw addresses obtained with `symbol()` do not carry this ownership information.
211
315
 
212
316
  Set `NODE_CTYPES_DEBUG_CALLBACKS=1` to log a stack trace for every
213
317
  callback garbage-collected without `.release()`.
@@ -225,12 +329,18 @@ const onEvent = threadSafeCallback((code) => console.log("event", code), null, [
225
329
  startWorker(onEvent); // a native library calling onEvent from its own thread
226
330
  ```
227
331
 
332
+ Both callback implementations store narrow integer results in a complete
333
+ libffi `ffi_arg`, with the declared signedness; failures zero that complete
334
+ slot. Floating-point results retain their own storage width. The native
335
+ `Callback` / `ThreadSafeCallback` classes also expose `getPointer()`, which
336
+ throws after release.
337
+
228
338
  ### Errors: `errno` and `GetLastError`
229
339
 
230
340
  `GetLastError()` / `get_errno()` read a **private thread-local slot** —
231
341
  exactly like Python's `ctypes.get_last_error()` / `ctypes.get_errno()`.
232
- The slot is used **only** by FFI calls through libraries opened with
233
- `use_last_error` or `use_errno`; otherwise it stays at 0. As in Python
342
+ The slot is updated **only** by FFI calls through libraries opened with
343
+ `use_last_error` or `use_errno`; unflagged calls leave it unchanged. As in Python
234
344
  those calls swap it with the system value: the function sees the value set
235
345
  with `set_errno()` / `set_last_error()`, the value it leaves becomes the
236
346
  private one, and the system value is restored after the call.
@@ -240,12 +350,12 @@ const user32 = new WinDLL("user32.dll", { use_last_error: true });
240
350
  const FindWindow = user32.func("FindWindowW", c_void_p, [c_wchar_p, c_wchar_p]);
241
351
  FindWindow("NoSuchClass", null);
242
352
 
243
- GetLastError(); // top-level (Python: ctypes.get_last_error)
244
- user32.get_last_error(); // per-library alias
353
+ GetLastError(); // top-level (Python: ctypes.get_last_error)
354
+ user32.get_last_error(); // per-library alias
245
355
  ```
246
356
 
247
- The snapshot is captured atomically in native code immediately after
248
- `ffi_call`, before any other JS can clobber it. To read the raw system
357
+ The snapshot is captured in native code immediately after the native call,
358
+ whether direct or through libffi, before any other JS can clobber it. To read the raw system
249
359
  error instead, call `GetLastError` via FFI like any other function.
250
360
 
251
361
  ### Windows API
@@ -264,8 +374,14 @@ const kernel32 = new WinDLL("kernel32.dll");
264
374
 
265
375
  class SYSTEMTIME extends Structure {
266
376
  static _fields_ = [
267
- ["wYear", WORD], ["wMonth", WORD], ["wDayOfWeek", WORD], ["wDay", WORD],
268
- ["wHour", WORD], ["wMinute", WORD], ["wSecond", WORD], ["wMilliseconds", WORD],
377
+ ["wYear", WORD],
378
+ ["wMonth", WORD],
379
+ ["wDayOfWeek", WORD],
380
+ ["wDay", WORD],
381
+ ["wHour", WORD],
382
+ ["wMinute", WORD],
383
+ ["wSecond", WORD],
384
+ ["wMilliseconds", WORD],
269
385
  ];
270
386
  }
271
387
 
@@ -282,32 +398,105 @@ user32.GetClientRect(hwnd, byref(rect));
282
398
  rect.right - rect.left; // LONG (c_long) values are BigInt
283
399
  ```
284
400
 
401
+ ### Error checking (`errcheck`)
402
+
403
+ Set `fn.errcheck = (result, func, args) => ...` to check or replace a result,
404
+ or set it to `null` to clear it. For `lib.func()`, library attributes and
405
+ `CFUNCTYPE` / `WINFUNCTYPE` callers, `func` is the public callable and `args`
406
+ contains the original, unconverted arguments. Result conversion and any
407
+ `OleDLL` HRESULT check run before the hook.
408
+
409
+ Each invocation captures its hook before argument adapters or getters run.
410
+ Replacing or clearing it affects later invocations, including reentrant calls,
411
+ not the call already in progress or a pending `callAsync()` job.
412
+
413
+ Hooks do not prevent otherwise unreachable functions and libraries from being
414
+ garbage-collected, even when they reference the function itself. Active calls
415
+ and workers retain their captured hook through result checking; `close()` is
416
+ still rejected while that checking runs.
417
+
418
+ The low-level native handle's `setErrcheck()` API instead passes the native
419
+ handle as `func`, invoked with `.call()`, not a directly callable function.
420
+
421
+ ### Scalar subclasses and result hooks
422
+
423
+ Builtin scalar types return ordinary JS values. A subclass instead produces
424
+ an instance containing the original C bytes, without invoking its constructor,
425
+ public buffer factory or writer. Derived scalar fields, array elements,
426
+ pointer indexing and callback arguments likewise expose typed instances;
427
+ memory views remain live, including in mirror mode.
428
+
429
+ The result pipeline is:
430
+ `C bytes -> restype representation -> _check_retval_ -> errcheck -> OUT/INOUT`.
431
+ A static `_check_retval_` receives the represented result and can replace it
432
+ or throw. It is captured when the function is bound; reassigning an attribute's
433
+ `restype` rebuilds that binding.
434
+
435
+ ```javascript
436
+ class CheckedInt extends c_int32 {
437
+ static _check_retval_(value) {
438
+ return value.value + 100;
439
+ }
440
+ }
441
+ const checkedAbs = libc.func("abs", CheckedInt, [c_int32]);
442
+ checkedAbs(-7); // 107
443
+ ```
444
+
445
+ Explicit `HRESULT` validation runs before `errcheck` with all loaders and
446
+ prototype callers, not only `OleDLL`. An error in result checking prevents
447
+ both `errcheck` and output conversion.
448
+ `OleDLL` attributes and `func(name)` default to `HRESULT`; other loaders
449
+ default to `c_int`. An explicit restype always overrides the default.
450
+
285
451
  ### Output parameters (`paramflags`)
286
452
 
287
453
  When at least one `out` param is declared, the call returns **only the
288
454
  out-params** (single value, or array if >1) — the `restype` is
289
- discarded. To also inspect it (e.g. a `BOOL` success flag), attach an
455
+ discarded. To also inspect it (e.g. a thread ID or success flag), attach an
290
456
  `errcheck`:
291
457
 
292
458
  ```javascript
293
- const proto = WINFUNCTYPE(BOOL, HWND, POINTER(DWORD), POINTER(DWORD));
459
+ const { DWORD, HWND, LPDWORD } = wintypes;
460
+ const proto = WINFUNCTYPE(DWORD, HWND, LPDWORD);
294
461
  const fn = proto.bind(user32, "GetWindowThreadProcessId", [
295
462
  { dir: "in", name: "hWnd" },
296
463
  { dir: "out", name: "pid" },
297
- { dir: "out", name: "tid" },
298
464
  ]);
299
465
 
300
- const [pid, tid] = fn(hwnd); // positional
301
- const [p2, t2] = fn({ hWnd }); // or named-args
466
+ const pid = fn(hwnd); // positional; thread ID is discarded
467
+ const p2 = fn({ hWnd: hwnd }); // or named-args
468
+
469
+ fn.errcheck = (threadId, func, args) => {
470
+ if (!threadId) throw new Error("call failed");
471
+ return args; // continue returning the PID from the output instance
472
+ };
473
+ const p3 = await fn.callAsync(hwnd);
302
474
 
303
- fn.errcheck = (result, func, args) => {
304
- if (!result) throw new Error("call failed");
305
- return args; // args: the arguments, out params as instances (args[1].value)
475
+ fn.errcheck = (threadId, func, args) => {
476
+ if (!threadId) throw new Error("call failed");
477
+ return { threadId, processId: args[1].value };
306
478
  };
479
+ const ids = fn(hwnd); // inspect both the return value and the output parameter
307
480
  ```
308
481
 
309
482
  As in Python, the value returned by `errcheck` is the result of the call,
310
- unless it is `args` itself: then the out-params are returned.
483
+ unless it is `args` itself: then the out-params are returned. Here `args`
484
+ is the expanded argument list, with out-params as instances.
485
+
486
+ These bindings have their own hook, independent of any cached `lib.func()`
487
+ binding, and support `callAsync()` with the same output processing and
488
+ per-call hook snapshot. Adapter temporaries stay alive through that processing,
489
+ also when the hook throws.
490
+
491
+ OUT conversion invokes the output instance's `__ctypes_from_outparam__()`.
492
+ By default a builtin scalar yields its value, while a scalar subclass yields
493
+ the instance. Override the method for custom output conversion.
494
+
495
+ Use `{ dir: "inout", name: "value" }`, or tuple flag `3`, to pass an existing
496
+ instance and return that exact instance after C modifies it. INOUT does not
497
+ call `__ctypes_from_outparam__`; positional, named and default arguments use
498
+ the same rule. Mixed outputs preserve parameter order. If `errcheck` returns
499
+ anything other than the original `args`, neither OUT nor INOUT unpacking runs.
311
500
 
312
501
  ### Sharing memory with existing buffers
313
502
 
@@ -327,10 +516,28 @@ const bytes = array(c_uint8, 64).from_address(malloc_result);
327
516
  const view = new Float32Array(bytes._buffer.buffer, bytes._buffer.byteOffset, 16);
328
517
  ```
329
518
 
519
+ Typed pointers read from fields or array elements, and views derived from
520
+ them, retain their known memory owners. Typed assignments and
521
+ `from_buffer_copy()` preserve known pointer references, including overlapping
522
+ and self-copies; replacing a pointer releases its previous reference.
523
+
524
+ Raw copies (`memmove()`, Buffer methods) do not transfer ownership metadata.
525
+ Likewise, `from_address()` given a raw address cannot discover its allocation
526
+ or library: the caller must keep that memory valid. Keeping a known owner
527
+ alive does not take over responsibility for freeing externally allocated
528
+ memory or explicitly releasing callbacks.
529
+
530
+ `memmove()` and `memset()` return the destination address as BigInt, including
531
+ zero-length operations (`0n` for a NULL destination with count zero).
532
+ Counts must be non-negative safe integers. Copies/fills involving JS memory
533
+ still stop at its end; raw native addresses remain the caller's responsibility.
534
+ Scalar `from_buffer()` / `from_buffer_copy()` validate byte size and offset
535
+ before producing an instance and accept Buffer, typed views and ctypes memory.
536
+
330
537
  ### Electron
331
538
 
332
539
  Electron does not allow Buffers over memory that V8 did not allocate, so a
333
- Buffer *view* of native memory cannot exist there. node-ctypes detects this
540
+ Buffer _view_ of native memory cannot exist there. node-ctypes detects this
334
541
  when it loads (`EXTERNAL_BUFFERS` is `false`) and keeps the same API:
335
542
 
336
543
  - instances on native memory (`from_address`, `in_dll`, `pointer.contents`,
@@ -344,8 +551,8 @@ when it loads (`EXTERNAL_BUFFERS` is `false`) and keeps the same API:
344
551
  (`arr[i]`, `s.field`) or `memmove()`.
345
552
 
346
553
  Only the bytes of the accessed field are copied, one native call per read
347
- or write (about 50 ns); instances on ordinary Buffers (`new Point()`,
348
- `c_int(5)`) have no extra cost. Set `NODE_CTYPES_NO_EXTERNAL_BUFFERS=1`
554
+ or write; instances on ordinary Buffers (`new Point()`, `c_int(5)`) do not
555
+ need this native-memory synchronization. Set `NODE_CTYPES_NO_EXTERNAL_BUFFERS=1`
349
556
  to run in this mode on Node.js.
350
557
 
351
558
  ### Adapter protocols: `_as_parameter_` and `from_param`
@@ -353,13 +560,17 @@ to run in this mode on Node.js.
353
560
  ```javascript
354
561
  // Instance protocol: auto-unwrap on call
355
562
  class Handle {
356
- constructor(h) { this._as_parameter_ = h; }
563
+ constructor(h) {
564
+ this._as_parameter_ = h;
565
+ }
357
566
  }
358
567
  user32.CloseHandle(new Handle(hwnd));
359
568
 
360
569
  // Class protocol: custom conversion in argtypes
361
570
  class StrLen extends c_int32 {
362
- static from_param(s) { return typeof s === "string" ? s.length : s; }
571
+ static from_param(s) {
572
+ return typeof s === "string" ? s.length : s;
573
+ }
363
574
  }
364
575
  const abs = libc.func("abs", c_int32, [StrLen]);
365
576
  abs("hello"); // 5
@@ -369,6 +580,25 @@ As in Python, `from_param` receives the argument as passed (also with
369
580
  `CFUNCTYPE` prototypes), its result is converted as the declared type, and
370
581
  an error it throws becomes `ArgumentError` (`"argument 1: RangeError: ..."`).
371
582
 
583
+ Objects passed through argument adapters and the objects produced by their
584
+ conversions stay alive while later arguments are converted and until the
585
+ result and `errcheck` have been processed. With `callAsync()`, those temporary
586
+ owners stay alive until its Promise settles. The native worker also retains
587
+ memory passed by value or as an integer address, including values materialized
588
+ by getters.
589
+
590
+ `_as_parameter_` chains are resolved recursively, including results of
591
+ `from_param`, with intermediate owners retained. As in CPython, an adapter may
592
+ be visited again when a stateful getter eventually returns a usable value;
593
+ object identity alone is not rejected as a cycle, and there is no fixed
594
+ 128-step limit. Non-terminating recursion raises an argument conversion error.
595
+ The available recursion depth and stack-error wording follow the JavaScript
596
+ runtime, rather than CPython's runtime-specific recursion guard.
597
+
598
+ This only covers the call: if C stores a pointer for later use, or returns a
599
+ pointer into an argument's memory, keep the source object referenced for as
600
+ long as that pointer is used. Callbacks still require explicit `.release()`.
601
+
372
602
  ### Big-endian structures
373
603
 
374
604
  ```javascript
@@ -385,14 +615,21 @@ h.magic = 0x12345678; // stored as 12 34 56 78 on the wire
385
615
  `LittleEndianStructure`, `BigEndianUnion`, `LittleEndianUnion` work the
386
616
  same way. Byte order is per-class — nested structs keep their own.
387
617
 
618
+ Primitive arrays also follow their containing class's byte order, recursively
619
+ for multidimensional arrays, including floats and wide-character arrays.
620
+ Arrays of structures keep the element structure's own byte order. The same
621
+ array type can be shared with native/little-endian containers without being
622
+ modified. Raw Buffer and typed-memory copies still copy bytes, not values
623
+ converted between byte orders.
624
+
388
625
  ### TypeScript
389
626
 
390
- Argument and return types are narrowed when `argTypes` is a literal
391
- tuple (`as const`) and `returnType` is a CType constant:
627
+ Argument and return types are inferred from declared type classes such as
628
+ `c_int32` and `c_size_t`. A literal tuple (`as const`) preserves argument types:
392
629
 
393
630
  ```ts
394
631
  const libc = new CDLL(null);
395
- const strlen = libc.func("strlen", c_int64, [c_char_p] as const);
632
+ const strlen = libc.func("strlen", c_size_t, [c_char_p] as const);
396
633
  const n: bigint = strlen("hello"); // typed as bigint, not any
397
634
  ```
398
635
 
@@ -402,7 +639,9 @@ const n: bigint = strlen("hello"); // typed as bigint, not any
402
639
 
403
640
  ```ts
404
641
  class Point extends defineStruct({ x: c_int32, y: c_int32 }) {
405
- distance() { return Math.sqrt(this.x ** 2 + this.y ** 2); }
642
+ distance() {
643
+ return Math.sqrt(this.x ** 2 + this.y ** 2);
644
+ }
406
645
  }
407
646
  const p = new Point({ x: 3, y: 4 }); // p.x, p.y typed as number
408
647
  ```
@@ -412,10 +651,10 @@ types are typed too; a `null` return type is `void`:
412
651
 
413
652
  ```ts
414
653
  const PointDef = struct({ x: c_int32, y: c_double });
415
- PointDef.get(buf, "y"); // number
416
- POINTER(c_int32).fromAddress(addr)[0]; // number (.contents: c_int32 instance)
417
- array(c_int32, 4).create([1, 2, 3, 4])[0]; // number
418
- libc.func("srand", null, [c_uint32]); // returns undefined
654
+ PointDef.get(buf, "y"); // number
655
+ POINTER(c_int32).fromAddress(addr)[0]; // number (.contents: c_int32 instance)
656
+ array(c_int32, 4).create([1, 2, 3, 4])[0]; // number
657
+ libc.func("srand", null, [c_uint32]); // returns undefined
419
658
  ```
420
659
 
421
660
  ---
@@ -424,30 +663,30 @@ libc.func("srand", null, [c_uint32]); // returns undefined
424
663
 
425
664
  ### Primitive types
426
665
 
427
- | Type | Aliases | Size | Notes |
428
- | ----------- | -------------- | -------- | --------------------------------------------- |
429
- | `c_int8` | `c_byte` | 1 | |
430
- | `c_uint8` | `c_ubyte` | 1 | |
431
- | `c_int16` | `c_short` | 2 | |
432
- | `c_uint16` | `c_ushort` | 2 | |
433
- | `c_int32` | `c_int` | 4 | |
434
- | `c_uint32` | `c_uint` | 4 | |
435
- | `c_int64` | `c_longlong` | 8 | |
436
- | `c_uint64` | `c_ulonglong` | 8 | |
437
- | `c_long` | | platform | 4 on Windows, 8 on Unix 64-bit; BigInt values |
438
- | `c_ulong` | | platform | mirrors `c_long`; BigInt values |
439
- | `c_float` | | 4 | |
440
- | `c_double` | | 8 | |
441
- | `c_bool` | | 1 | |
442
- | `c_char` | | 1 | 1-char string (Python `bytes`); also 0..255 |
443
- | `c_wchar` | | 2 or 4 | 1-char string; 2 on Windows, 4 on Unix |
444
- | `c_char_p` | | pointer | `char *` (NUL-terminated) |
445
- | `c_wchar_p` | | pointer | `wchar_t *` (NUL-terminated wide) |
446
- | `c_void_p` | `c_voidp` | pointer | opaque pointer / `HANDLE` |
447
- | `c_time_t` | | 8 | `time_t` (`SIZEOF_TIME_T`) |
448
- | `c_size_t` | | pointer | pointer-sized unsigned integer |
449
- | `c_ssize_t` | | pointer | pointer-sized signed integer |
450
- | `HRESULT` | | 4 | `c_int32` subclass — auto-raise on `OleDLL` |
666
+ | Type | Aliases | Size | Notes |
667
+ | ----------- | ------------- | -------- | --------------------------------------------- |
668
+ | `c_int8` | `c_byte` | 1 | |
669
+ | `c_uint8` | `c_ubyte` | 1 | |
670
+ | `c_int16` | `c_short` | 2 | |
671
+ | `c_uint16` | `c_ushort` | 2 | |
672
+ | `c_int32` | `c_int` | 4 | |
673
+ | `c_uint32` | `c_uint` | 4 | |
674
+ | `c_int64` | `c_longlong` | 8 | |
675
+ | `c_uint64` | `c_ulonglong` | 8 | |
676
+ | `c_long` | | platform | 4 on Windows, 8 on Unix 64-bit; BigInt values |
677
+ | `c_ulong` | | platform | mirrors `c_long`; BigInt values |
678
+ | `c_float` | | 4 | |
679
+ | `c_double` | | 8 | |
680
+ | `c_bool` | | 1 | |
681
+ | `c_char` | | 1 | 1-char string (Python `bytes`); also 0..255 |
682
+ | `c_wchar` | | 2 or 4 | 1-char string; 2 on Windows, 4 on Unix |
683
+ | `c_char_p` | | pointer | `char *` (NUL-terminated) |
684
+ | `c_wchar_p` | | pointer | `wchar_t *` (NUL-terminated wide) |
685
+ | `c_void_p` | `c_voidp` | pointer | opaque pointer / `HANDLE` |
686
+ | `c_time_t` | | 8 | `time_t` (`SIZEOF_TIME_T`) |
687
+ | `c_size_t` | | pointer | pointer-sized unsigned integer |
688
+ | `c_ssize_t` | | pointer | pointer-sized signed integer |
689
+ | `HRESULT` | | 4 | `c_int32` subclass — auto-raise on `OleDLL` |
451
690
 
452
691
  Plus the Win32 types, structures and pointer types of `ctypes.wintypes` under `wintypes`.
453
692
 
@@ -475,13 +714,18 @@ Plus the Win32 types, structures and pointer types of `ctypes.wintypes` under `w
475
714
 
476
715
  - `sizeof(type)` / `alignment(type)` — in bytes
477
716
  - `addressof(obj)` → BigInt
478
- - `byref(obj)` — lightweight pass-by-reference marker
717
+ - `byref(obj, byteOffset = 0)` — lightweight reference with a signed byte offset
479
718
  - `cast(ptr, type)` — reinterpret a pointer as another type
480
- - `memmove(dst, src, n)` / `memset(dst, val, n)` — buffers, ctypes instances, pointers or addresses
719
+ - `memmove(dst, src, n)` / `memset(dst, val, n)` — buffers, ctypes instances, pointers or addresses; return the destination address as BigInt
481
720
  - `readValue(ptr, type, offset?)` / `writeValue(ptr, type, val, offset?)`
482
721
  - `create_string_buffer(init, size?)` / `c_buffer` / `create_unicode_buffer(init, size?)` — with `.value` (and `.raw`)
483
722
  - `string_at(addr, size?)` / `wstring_at(addr, size?)` — exactly `size` units, or up to the NUL
484
723
 
724
+ With an explicit byte count, `string_at` returns a lossless Latin1 string:
725
+ `Buffer.from(string_at(addr, n), "latin1")` recovers all `n` original bytes,
726
+ including embedded NUL and invalid UTF-8. Without a count it retains the
727
+ UTF-8 text representation. `wstring_at` counts native wide-character units.
728
+
485
729
  ### Error slots
486
730
 
487
731
  - `get_errno()` / `set_errno(v)`
@@ -501,7 +745,7 @@ Plus the Win32 types, structures and pointer types of `ctypes.wintypes` under `w
501
745
 
502
746
  ## Python ctypes parity & differences
503
747
 
504
- ### What works identically
748
+ ### Supported Python ctypes behavior
505
749
 
506
750
  Structs, unions, bit fields (`_layout_` `"gcc-sysv"` / `"ms"`), anonymous
507
751
  fields, `_pack_`, `_align_`, subclasses of structures and unions, nested layouts,
@@ -522,8 +766,8 @@ pointer arithmetic (also `POINTER(POINTER(T))`), callbacks (`CFUNCTYPE` /
522
766
  - **No automatic memory management** for returned pointers.
523
767
  - **Both class and functional syntax**: `class extends Structure`
524
768
  (Python-like) and `struct({...})` (functional) are both supported.
525
- - **Only type classes**, not string literals: `c_int32`, never `"int32"`
526
- — same as Python.
769
+ - **Use type classes** such as `c_int32`, rather than string names such as
770
+ `"int32"`, for the Python-compatible, typed API.
527
771
  - **`bytes` are JS strings**: `c_char` values, `c_char * n` arrays and
528
772
  fields, `c_char_p` and `create_string_buffer().value` use strings (UTF-8)
529
773
  where Python uses `bytes`; `.raw` is a `Buffer`.
@@ -535,7 +779,7 @@ pointer arithmetic (also `POINTER(POINTER(T))`), callbacks (`CFUNCTYPE` /
535
779
  (Python: Windows only), so the same code runs everywhere.
536
780
  - **64-bit and pointer-sized integers** (`c_int64`, `c_uint64`,
537
781
  `c_size_t`, `c_ssize_t`) also accept `null` (as 0) and a `Buffer`
538
- (as its address) as arguments.
782
+ or `ArrayBuffer` (as its address) as arguments.
539
783
  - **Variadic arguments follow the C promotions**: a `c_float`, `c_int8`,
540
784
  `c_char`, … instance passed beyond `argtypes` is passed as `double` /
541
785
  `int`, where Python fails (`ffi_prep_cif_var failed`).
@@ -547,9 +791,14 @@ pointer arithmetic (also `POINTER(POINTER(T))`), callbacks (`CFUNCTYPE` /
547
791
  array, `ArrayBuffer`) instead of writing past it.
548
792
  - **Integer types reject non-integral numbers** (`3.7`, `NaN`) as Python
549
793
  rejects floats; JS has no int/float distinction, so `3.0` is accepted.
794
+ - **Floating-point scalars accept BigInt in the range `-2**63` to `2**64-1`**,
795
+ converted to a JS number; larger BigInts raise a range error. This applies
796
+ consistently to constructors, fields and function arguments.
550
797
  - **Array instances are Buffers whose Array methods work on the elements**
551
798
  (`slice`, `map`, `includes`, …, as Python sequences); the Buffer methods
552
799
  (`readInt32LE`, `subarray`, …) work on the bytes.
800
+ - **Array index reads follow JavaScript bounds behavior**: out-of-range
801
+ indices return `undefined`; negative indices do not wrap around as in Python.
553
802
  - **Unions by value on x86-64 System V** are passed with the ABI rules;
554
803
  Python passes them in the wrong registers (libffi#33).
555
804
  - **Structure/Union fields are accessors of the class**, as Python fields
@@ -563,27 +812,29 @@ pointer arithmetic (also `POINTER(POINTER(T))`), callbacks (`CFUNCTYPE` /
563
812
  Node `Buffer`, and Buffers aren't resizable in place.
564
813
  Work-around: `new MyStruct(myBuffer)` with a pre-sized buffer.
565
814
  - **`c_longdouble`** (80/128-bit float, `ffi_type_longdouble`) — rarely
566
- used; fall back to `c_double` or raw bytes.
815
+ used; use a native wrapper that converts to supported types, or access
816
+ storage through pointers/bytes. Declaring a `long double` ABI value as
817
+ `c_double` is not a portable substitute.
567
818
 
568
819
  ### Migrating from 1.x
569
820
 
570
821
  2.0 follows Python ctypes more closely. Code relying on the 1.x behavior
571
822
  needs these changes:
572
823
 
573
- | 1.x | 2.0 (as Python) |
574
- | --- | --- |
575
- | `ptr.contents` returned the value | returns a live instance: `ptr.contents.value` (simple types), `ptr.contents.x` (structs); `ptr[0]` still returns the value |
576
- | `POINTER(T)` restype returned a `bigint` address | returns a pointer object (`null` for NULL); use `.address` for the number |
577
- | NULL `POINTER` struct fields were pointer objects | they are `null` |
578
- | `c_char` values were numbers | 1-character strings; `c_char * n` fields read/write as strings |
579
- | invalid `c_char` values were truncated | `TypeError` (`"one character bytes, bytearray, or an integer in range(256) expected, not ..."`) |
580
- | wrong argument types raised `TypeError` | raise `ArgumentError` (a `TypeError` subclass), message `"argument N: TypeError: ..."` |
581
- | unsupported pointer arguments (functions, plain objects) passed NULL | raise `ArgumentError` (`"'function' object cannot be interpreted as ctypes.c_void_p"`) |
582
- | functions without `restype` / `argtypes` | default `restype` is `c_int`; without `argtypes` the call uses the fixed-argument ABI |
583
- | `create_string_buffer(init)` | also takes `size` and returns a Buffer with `.value` / `.raw` |
584
- | `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 |
585
- | `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) |
586
- | `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) |
824
+ | 1.x | 2.0 (as Python) |
825
+ | ------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
826
+ | `ptr.contents` returned the value | returns a live instance: `ptr.contents.value` (simple types), `ptr.contents.x` (structs); `ptr[0]` still returns the value |
827
+ | `POINTER(T)` restype returned a `bigint` address | returns a pointer object (`null` for NULL); use `.address` for the number |
828
+ | NULL `POINTER` struct fields were pointer objects | they are `null` |
829
+ | `c_char` values were numbers | 1-character strings; `c_char * n` fields read/write as strings |
830
+ | invalid `c_char` values were truncated | `TypeError` (`"one character bytes, bytearray, or an integer in range(256) expected, not ..."`) |
831
+ | wrong argument types raised `TypeError` | raise `ArgumentError` (a `TypeError` subclass), message `"argument N: TypeError: ..."` |
832
+ | unsupported pointer arguments (functions, plain objects) passed NULL | raise `ArgumentError` (`"'function' object cannot be interpreted as ctypes.c_void_p"`) |
833
+ | functions without `restype` / `argtypes` | default `restype` is `c_int`; without `argtypes` the call uses the fixed-argument ABI |
834
+ | `create_string_buffer(init)` | also takes `size` and returns a Buffer with `.value` / `.raw` |
835
+ | `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 |
836
+ | `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) |
837
+ | `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) |
587
838
 
588
839
  ---
589
840
 
@@ -604,21 +855,150 @@ Each example in `examples/` has its own README; see the [index](examples/README.
604
855
 
605
856
  ## Tests & docs
606
857
 
607
- `npm test` first builds a small C library (`tests/fixtures/`, into
858
+ From the repository root, `npm --prefix tests test` first builds a small C library (`tests/fixtures/`, into
608
859
  `build/fixture/`) used by the tests of structures by value, array parameters
609
- and reentrant calls; `npm run build:test-fixture` builds it alone. Python
610
- twins of the tests (`tests/common/*.py`) load the same library.
860
+ and reentrant calls; `npm run build:test-fixture` builds it alone. Matched
861
+ Python/JavaScript contracts live under `tests/cpython_parity/`, divided by domain,
862
+ and load the same library. Node-specific async, representation and GC checks
863
+ live under `tests/node_specific/`; genuine Python-only scheduling checks live
864
+ under `tests/python_specific/`. The former `common/` and `windows/` suites have
865
+ been migrated into these domains.
866
+
867
+ Paired JavaScript uses the Python-shaped API: `Structure`/`Union` classes,
868
+ `ARRAY`, library attributes with `argtypes`/`restype`, and `CFUNCTYPE` bindings.
869
+ The structural guard checks neighboring files and matching class/method IDs
870
+ using the existing TypeScript parser and Python AST; runtime assertions remain
871
+ independent checks against CPython, not a claim based on file names alone.
872
+
873
+ ```bash
874
+ npm install
875
+ npm run build
876
+ npm --prefix tests install
877
+ npm --prefix tests test # functional/parity tests
878
+ NODE_CTYPES_NO_EXTERNAL_BUFFERS=1 npm --prefix tests test # mirrored native memory
879
+ npm --prefix tests run test:parity # matched CPython and JS contracts
880
+ npm --prefix tests run test:parity:check # paired file/case/discovery/style guard
881
+ npm --prefix tests run test:python # all Python references
882
+ npm run test:types # TypeScript declarations
883
+ npm run docs # TypeDoc API site in docs/
884
+ npm run docs:serve # preview
885
+ ```
886
+
887
+ See the [test suite guide](tests/README.md) for paired-case conventions,
888
+ runtime differences and focused commands.
889
+
890
+ ### Performance comparisons
891
+
892
+ There are two JavaScript comparisons, both against another FFI library.
893
+ From the repository root, after building node-ctypes:
894
+
895
+ ```bash
896
+ npm --prefix tests install # includes Koffi
897
+ npm run build:test-fixture # shared C functions for both libraries
898
+ npm run bench:koffi # node-ctypes vs Koffi; Node 24+
899
+ npm run bench:ffi # node-ctypes vs node:ffi; Node 26+
900
+ ```
901
+
902
+ The private test package explicitly approves the install script for Koffi 3.3.3.
903
+ When upgrading Koffi, review the new version before updating that approval with
904
+ `npm --prefix tests install-scripts approve koffi`; future versions are not
905
+ automatically authorized.
906
+
907
+ `bench:ffi` adds `--experimental-ffi` automatically. Both comparisons
908
+ print a table grouped by workload and automatically generate HTML reports:
909
+
910
+ - `tests/benchmarks/results/koffi.html`
911
+ - `tests/benchmarks/results/node-ffi.html`
912
+
913
+ These paths are relative to the repository root, regardless of the working
914
+ directory. Each successful run replaces its previous report; generated results
915
+ are ignored by Git. Open the HTML file directly in a browser: it is responsive
916
+ and self-contained, with native HTML/CSS bar charts and no browser JavaScript,
917
+ external resources or server requirements.
918
+
919
+ | Column | Meaning |
920
+ | ------------------------ | ----------------------------------------------------- |
921
+ | Case | The same operation and inputs for both libraries |
922
+ | node-ctypes / competitor | Median time +/- MAD (dispersion), in ns per operation |
923
+ | Ratio | node-ctypes time divided by competitor time |
924
+
925
+ A ratio of `0.50x` means node-ctypes took half the time; `2.00x` means it
926
+ took twice the time. Lower times are better. There is no overall score
927
+ combining unrelated calls, memory access and asynchronous scheduling.
928
+ In the charts, **shorter bars are better**. Each workload group shares a linear
929
+ scale starting at zero; different groups use different scales. Bars show
930
+ medians, with +/- MAD whiskers (not confidence intervals). Each library also
931
+ shows its total measured operation count and elapsed time across the samples.
932
+
933
+ Reports record library/runtime versions, CPU, OS/kernel, buffer mode, start/
934
+ finish timestamps and Git revision/working-tree status. Missing CPU or Git
935
+ metadata produces an explicit warning rather than invented values.
936
+
937
+ The comparisons cover scalars, mixed arguments, short/long strings, buffer
938
+ arguments, field reads and callbacks. Koffi also covers structures by value,
939
+ variadic calls and async calls with 1/8 calls in flight. Cases without an
940
+ equivalent documented node:ffi API are listed as **not compared**, not
941
+ emulated with a different native signature.
942
+
943
+ The `CFUNCTYPE` rows measure calls through an already-bound node-ctypes
944
+ prototype, against an independently bound competitor function with the same
945
+ C signature. Bindings are separate to avoid sharing optimization feedback
946
+ with the direct-call rows. These cases do not include prototype construction
947
+ or callback registration.
948
+
949
+ Both sides call the same C fixture and verify results before/after timing.
950
+ String contents are encoded on every call; node-ctypes reuses scratch storage,
951
+ not previously encoded strings. Measurements describe warmed repeated calls,
952
+ not cold-start allocation costs.
953
+ String lengths are compared as Numbers, including conversion where the API
954
+ returns BigInt; wide integers are BigInt in both APIs. Structures are plain
955
+ objects. Async times include scheduling and are reported per completed call,
956
+ with the concurrency shown in the case name.
957
+
958
+ Defaults are nine samples of at least 250 ms per library after warmup,
959
+ alternating library order. Each native signature has a separate call-site to
960
+ avoid mixing V8 optimization feedback between cases.
961
+ Each row is printed when its measurements finish.
962
+ Run comparisons serially, not concurrently. Optional arguments:
611
963
 
612
964
  ```bash
613
- cd tests && npm install && npm run test # unit tests (JS + Python parity)
614
- NODE_CTYPES_NO_EXTERNAL_BUFFERS=1 npm test # again as in Electron (from tests/)
615
- npm run test:types # type-check lib/index.d.ts (tests/types)
616
- npm run docs # TypeDoc API site in docs/
617
- npm run docs:serve # preview
965
+ npm run bench:koffi -- --filter string,callback
966
+ npm run bench:ffi -- --samples 11 --duration 500
967
+ npm run bench:koffi -- --output comparison.json
618
968
  ```
619
969
 
620
- See [tests/common/](tests/common/) for runnable examples alongside
621
- parallel Python ctypes implementations.
970
+ `--output comparison.json` additionally saves medians, dispersion and all sample
971
+ durations/operation counts as JSON, and writes `comparison.html` next to it
972
+ instead of the default HTML report. Parent directories are created automatically.
973
+ HTML generation runs only after all measurements finish.
974
+ `benchmark_koffi.js` and `benchmark_node_ffi.js` define the actual side-by-side
975
+ comparisons; `runner.js` shares timing, table output and HTML generation without
976
+ extra dependencies or a separate renderer script. There is no separate
977
+ self-benchmark command, and benchmarks are not run by the functional/parity
978
+ test suite.
979
+
980
+ ### Release validation
981
+
982
+ The workflow retains the eight Node 24 native build targets (Windows/macOS,
983
+ x64/ARM64, and Linux glibc/musl). C++20 conformance is checked with
984
+ `-pedantic-errors` on GCC/Clang and `/permissive-` on MSVC; vendor optimization
985
+ and the node-addon-api integration remain unchanged.
986
+
987
+ Three runtime-control jobs reuse the built artifacts on Node 26 without
988
+ rebuilding the addon, running the functional parity suite normally and with
989
+ mirrored buffers. A Linux job runs the focused Python 3.15
990
+ reference tests in addition to the Python 3.14 reference coverage.
991
+
992
+ The package assembler requires all eight nonempty binaries and includes
993
+ declarations, README, changelog and license. It fails on missing/unknown
994
+ artifacts or a stale output directory. Publish depends on the runtime gates,
995
+ requires a pushed tag matching the manifest version exactly, and uses `next`
996
+ for prereleases instead of `latest`. Manual workflow runs never publish.
997
+ These are configured gates, not a substitute for a successful native CI run.
998
+
999
+ `npm --prefix tests test` builds the fixture and runs the suite;
1000
+ `npm --prefix tests run test:js` reuses an already-built fixture/addon.
1001
+ Both use the documented `--test-timeout` runner option.
622
1002
 
623
1003
  ---
624
1004