node-ctypes 2.13.1 → 2.13.2

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/CHANGELOG.md CHANGED
@@ -7,6 +7,42 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
7
7
 
8
8
  ## [Unreleased]
9
9
 
10
+ ## [2.13.2] - 2026-11-15
11
+
12
+ ### Fixed
13
+
14
+ - **libffi 3.8.1**: the submodule moves from upstream commit `d02afc25` to the
15
+ v3.8.1 tag, with two fixes that node-ctypes could reach on ARM64:
16
+ - a struct larger than 16 bytes (other than an HFA) passed by value after the
17
+ integer registers, after a narrow stack argument on macOS (stack arguments
18
+ are packed there) or with `_align_ = 16` elsewhere, had the pointer to its
19
+ copy in a misaligned stack slot: the C function read another address and
20
+ could crash ([GHSA-h52h-3759-xqm4](https://github.com/libffi/libffi/security/advisories/GHSA-h52h-3759-xqm4)).
21
+ The tests skipped on Darwin ARM64 for this limitation run again;
22
+ - on macOS ARM64, with more than 1024 live callbacks, some orders of
23
+ `release()` wrote into a freed trampoline table
24
+ ([GHSA-23hx-9rxv-9qfp](https://github.com/libffi/libffi/security/advisories/GHSA-23hx-9rxv-9qfp)).
25
+
26
+ The other fixes of the release concern types node-ctypes does not expose
27
+ (`long double`, vectors) or platforms and APIs it does not use. The generated
28
+ headers report 3.8.1.
29
+
30
+ ### Documentation
31
+
32
+ - **Guides**: the reference sections of the README moved, unchanged, to
33
+ `guides/` (libraries and functions, types, structures, memory, callbacks,
34
+ asynchronous calls, errors, Windows API, TypeScript, Python ctypes parity,
35
+ building and testing), also published on the documentation site. The README
36
+ keeps the quick start, the supported platforms and the list of guides. New
37
+ pages: Getting started (installation, supported platforms, building from
38
+ source), Coming from Koffi (the Koffi API mapped to node-ctypes) and
39
+ Performance (results of the Koffi comparison, with charts, and how to run
40
+ it). The paragraph on direct calls now describes the register-frame calls.
41
+ - **Benchmark charts**: `npm run bench:charts -- report.json` writes static
42
+ SVG charts (ratio summary and one chart per workload group, light and dark)
43
+ from the JSON report of `bench:koffi` or `bench:ffi` (`--output`), into
44
+ `guides/images/` or the `--out` directory.
45
+
10
46
  ## [2.13.1] - 2026-11-14
11
47
 
12
48
  ### Fixed
@@ -1117,7 +1153,7 @@ number, not string`).
1117
1153
 
1118
1154
  2.0 aligns node-ctypes with Python ctypes as closely as the language allows,
1119
1155
  so that Python code can be ported with only the changes JavaScript requires.
1120
- It contains breaking changes: see [Migrating from 1.x](README.md#migrating-from-1x).
1156
+ It contains breaking changes: see [Migrating from 1.x](guides/python.md#migrating-from-1x).
1121
1157
 
1122
1158
  ### Breaking changes
1123
1159
 
@@ -1431,7 +1467,8 @@ It contains breaking changes: see [Migrating from 1.x](README.md#migrating-from-
1431
1467
 
1432
1468
  Initial releases.
1433
1469
 
1434
- [Unreleased]: https://github.com/dmazzella/node-ctypes/compare/v2.13.1...HEAD
1470
+ [Unreleased]: https://github.com/dmazzella/node-ctypes/compare/v2.13.2...HEAD
1471
+ [2.13.2]: https://github.com/dmazzella/node-ctypes/compare/v2.13.1...v2.13.2
1435
1472
  [2.13.1]: https://github.com/dmazzella/node-ctypes/compare/v2.13.0...v2.13.1
1436
1473
  [2.13.0]: https://github.com/dmazzella/node-ctypes/compare/v2.12.2...v2.13.0
1437
1474
  [2.12.2]: https://github.com/dmazzella/node-ctypes/compare/v2.12.1...v2.12.2
package/README.md CHANGED
@@ -52,946 +52,38 @@ const p = new Point(3, 4);
52
52
  console.log(p.x, p.y); // 3 4
53
53
  ```
54
54
 
55
- <details>
56
- <summary>Build from source</summary>
55
+ To build from source, see [Getting started](guides/getting-started.md#building-from-source).
57
56
 
58
- Requires Node.js >= 24, CMake >= 3.15, and a C++20 compiler and standard library.
59
- Run these commands from a source checkout:
57
+ ## Supported platforms
60
58
 
61
- ```bash
62
- npm install
63
- npm run build
64
- ```
59
+ | Operating system | x64 | ARM64 | Minimum version |
60
+ | -------------------- | --- | ----- | --------------- |
61
+ | Windows | ✅ | ✅ | |
62
+ | macOS | ✅ | ✅ | macOS 13.5 |
63
+ | Linux, glibc | ✅ | ✅ | glibc 2.28 |
64
+ | Linux, musl (Alpine) | ✅ | ✅ | |
65
65
 
66
- </details>
66
+ Node.js 24 or later. Details, testing and building from source are in
67
+ [Getting started](guides/getting-started.md).
67
68
 
68
69
  ---
69
70
 
70
71
  ## Guides
71
72
 
72
- ### Calling a C function
73
-
74
- Two equivalent styles — use whichever reads better:
75
-
76
- ```javascript
77
- // Python-style: set argtypes/restype on the bound symbol
78
- const abs = libc.abs;
79
- abs.argtypes = [c_int32];
80
- abs.restype = c_int32;
81
- abs(-42); // 42
82
-
83
- // One-shot: declare signature at lookup
84
- const abs2 = libc.func("abs", c_int32, [c_int32]);
85
- abs2(-42); // 42
86
- ```
87
-
88
- For Windows `__stdcall` APIs use `WinDLL` instead of `CDLL`. For COM-style
89
- auto-`HRESULT`-checking use `OleDLL`.
90
-
91
- Direct native calls are limited to a bounded set of exact scalar C++
92
- signatures with up to four arguments, on 64-bit little-endian targets using
93
- the default ABI. By default, other signatures use the existing cached libffi plans/CIFs,
94
- including pointers and strings whose pointee types and qualifiers are not
95
- encoded in the native type metadata. Float/double arguments continue to use
96
- libffi on x86-64. This changes the optimization route, not the JavaScript API.
97
- Eligible fixed invokers are selected before constructing libffi types, CIFs or
98
- call plans. Fixed async workers reuse the same selected invoker, with their own
99
- argument/result storage. Other signatures retain eager fallback setup;
100
- additional arguments bypass fixed invokers and prepare their libffi metadata
101
- on the JavaScript thread. Inferred calls use the ordinary ABI; true variadic
102
- calls preserve the declared named-prefix boundary.
103
-
104
- ### Asynchronous calls: `callAsync` and `Executor`
105
-
106
- `fn.callAsync(...args)` runs the call on a libuv worker and returns a promise;
107
- the event loop stays free meanwhile. Arguments are converted on the
108
- JavaScript thread before the call, results (and `errcheck`) after it, and the
109
- memory passed by address stays referenced until the promise settles.
110
-
111
- libuv workers are shared with `fs`, `dns` and `crypto` (4 by default), and
112
- concurrent calls run in parallel in any order. For long or blocking calls, or
113
- calls that must run in sequence on one thread (thread-local state,
114
- thread-affine handles, libraries that are not thread-safe), use an
115
- `Executor`: a native thread owned by node-ctypes with a FIFO queue.
116
- `fn.callOn(executor, ...args)` is the same call as `callAsync`, run there:
117
-
118
- ```javascript
119
- import { Executor } from "node-ctypes";
120
-
121
- const executor = new Executor({ name: "device" }); // thread name for debuggers
122
- const read = await lib.device_read.callOn(executor, handle, buffer, buffer.length);
123
-
124
- // Cancel a call that has not started yet: the promise rejects with signal.reason.
125
- const controller = new AbortController();
126
- const next = lib.device_read.callOn({ executor, signal: controller.signal }, handle, buffer, buffer.length);
127
- controller.abort();
128
-
129
- await executor.close(); // waits for the accepted calls, then stops the thread
130
- ```
131
-
132
- - Calls run one at a time, in arrival order; each promise settles once.
133
- - The thread starts with the first call. Pending calls keep the process
134
- alive; an idle executor does not, and is collected with its thread when no
135
- longer referenced. `close()` rejects new calls, waits for the accepted ones
136
- and stops the thread (an executor cannot be reopened).
137
- - `executor.pending`, `completed`, `running` and `closed` report its state.
138
- - `spin` (microseconds, default 50, `0` to disable): after a call the thread
139
- polls for the next one this long (at most 50 µs) before sleeping, and the JavaScript thread
140
- waits this long for a call submitted to an idle executor, completing it
141
- without a round trip through the event loop. Awaited calls in sequence then
142
- cost a few microseconds instead of tens; its errcheck may run before
143
- `callOn` returns. The wait is per function: `spin` for a function not
144
- called yet, then about one and a half times its measured typical duration,
145
- up to `spinLimit` (microseconds, default 500); a function that usually takes
146
- longer completes through the event loop without delaying the others. Inline
147
- completions are limited to 1 ms per turn of the event loop, so timers, I/O
148
- and UI events keep running.
149
- - A call that has started cannot be interrupted: the signal only removes
150
- queued calls.
151
- - On process exit (or worker termination) queued calls are discarded and a
152
- running call is left to finish on its own.
153
- - Callbacks invoked during the call run on the executor thread: use
154
- `threadSafeCallback`, as with `callAsync`.
155
-
156
- An `Executor` also suits many short calls kept in flight. Each `callAsync()`
157
- queues its own libuv work item, which wakes a worker, and completes
158
- separately; the executor thread takes the next queued call without being
159
- woken and delivers the completed calls to JavaScript together. With several
160
- calls in flight this usually costs less than `callAsync()`: about a third on
161
- Windows, where waking a thread is expensive, less of a difference elsewhere.
162
- The calls then run one at a time: for short calls that is usually faster than
163
- spreading them over the libuv workers, but blocking calls that must overlap
164
- still need `callAsync()` or one executor each.
165
-
166
- ### Structs, unions, bit fields, arrays
167
-
168
- ```javascript
169
- import { Structure, Union, array, c_int32, c_uint32, c_float, c_char } from "node-ctypes";
170
-
171
- class Rect extends Structure {
172
- static _fields_ = [
173
- ["x", c_int32],
174
- ["y", c_int32],
175
- ["w", c_int32],
176
- ["h", c_int32],
177
- ];
178
- }
179
-
180
- class Value extends Union {
181
- static _fields_ = [
182
- ["i", c_int32],
183
- ["f", c_float],
184
- ];
185
- }
186
-
187
- // Bit fields: [name, type, bitCount]
188
- class Flags extends Structure {
189
- static _fields_ = [
190
- ["enabled", c_uint32, 1],
191
- ["mode", c_uint32, 3],
192
- ["priority", c_uint32, 4],
193
- ];
194
- }
195
-
196
- // Arrays: elementType * count (Python: `c_int32 * 5`)
197
- const IntArr5 = array(c_int32, 5);
198
- const arr = IntArr5(1, 2, 3, 4, 5); // Python: (c_int32 * 5)(1, 2, 3, 4, 5)
199
-
200
- // char arrays read and write as strings (Python: bytes)
201
- const name = array(c_char, 16)();
202
- name.value = "node"; // .value / .raw as in Python
203
- ```
204
-
205
- `array(type, n)` reuses the same type while it is alive. Instances, function
206
- signatures and containing types keep their array types alive; the cache itself
207
- does not. Unused array types and their length entries can be garbage-collected,
208
- including arrays of builtin element types.
209
-
210
- An array type in `argtypes` is passed by address, as in C and Python
211
- (`fill.argtypes = [c_int32 * 4]`). As in Python, the argument must be an
212
- instance of an array with the same element type and length; a Buffer or a
213
- typed array is also accepted as its memory. Other values raise
214
- `ArgumentError`.
215
-
216
- Builtin numeric scalars accept numbers, booleans and BigInt; integers wrap to
217
- their C width, but reject non-integral or non-finite numbers. Use BigInt when
218
- the original integer needs more precision than a JS number can represent.
219
- No argument, or `undefined` in a constructor, initializes zero. Explicit
220
- `null`, strings and arbitrary objects are not implicit numeric conversions.
221
- Assigning a scalar instance to a field or passing it to a declared numeric
222
- argument requires a compatible type. The documented numeric-pointer argument
223
- extensions below are unchanged.
224
-
225
- `c_bool` and `wintypes.VARIANT_BOOL` use JavaScript truthiness, using `.value`
226
- for scalar instances rather than treating every instance as true.
227
- `VARIANT_BOOL` stores true as `-1`, and its results and callback arguments
228
- are booleans. Boolean bitfields normalize before masking and read as booleans.
229
-
230
- Nested structs, anonymous fields (`static _anonymous_ = ["data"]`),
231
- explicit packing (`static _pack_ = 1`), minimum alignment
232
- (`static _align_ = 16`), self-referential pointers (`POINTER(() => Node)`)
233
- and subclasses that add fields to their base class all work identically to
234
- Python. The layout of bit fields follows Python's `_layout_`: `"gcc-sysv"`
235
- by default, `"ms"` on Windows or with `_pack_`. Bit fields wider than 53
236
- bits read as BigInt.
237
-
238
- `_pack_` follows Python's integer conversion and permits zero and non-powers
239
- of two (for example `3`) with the MS layout. An explicit `_pack_`, including
240
- zero, is incompatible with `"gcc-sysv"`. Layouts with non-power-of-two
241
- alignment can be used for memory serialization but are rejected as native
242
- by-value signatures: they do not describe a valid C ABI alignment.
243
-
244
- Structures and unions passed or returned by value keep this layout, also
245
- with `_pack_`: as with GCC and clang, a structure with misaligned fields is
246
- passed in memory on x86-64 System V (Linux, macOS Intel), where Python
247
- ctypes passes it in registers and the called function reads wrong values.
248
-
249
- Each returned structure or union owns a snapshot of its value, including
250
- results declared with functional `struct()` / `union()` definitions. Array
251
- views, nested composites and union getters remain valid after later calls,
252
- reentrant conversion or `errcheck`, and concurrent `callAsync()` jobs.
253
- Mutating one result does not modify another result's value storage.
254
-
255
- This is not a deep copy through pointers: pointer fields can still refer to
256
- the same external memory. Explicit `definition.toObject(buffer)` keeps its
257
- existing buffer-view behavior. Synchronous low-level native `struct_buffer`
258
- results are borrowed, reusable storage; public callables snapshot their
259
- results before any JavaScript result conversion.
260
-
261
- Low-level native `StructType` descriptors are builders only until consumed.
262
- Adding a descriptor as a field, constructing an `ArrayType` from it (even at
263
- length zero), preparing a function/callback signature, or creating/reading a
264
- native value finalizes the captured layout and its dependencies.
265
- `addField()` then throws instead of changing sizes, offsets or FFI metadata
266
- already in use. Build a new descriptor for a different layout.
267
- `getSize()` and `getAlignment()` alone leave an unused builder open; an
268
- outer builder can still receive fields after it captures a finalized child.
269
- Direct by-value self-reference is rejected. Pointers do not capture or
270
- finalize the pointed-to layout.
271
-
272
- ### Pointers, buffers, and cast
273
-
274
- ```javascript
275
- import { POINTER, pointer, cast, c_int32, c_void_p } from "node-ctypes";
276
-
277
- // Pointer to an existing c-data instance (Python: pointer(x))
278
- const x = new c_int32(42);
279
- const px = pointer(x);
280
- px.contents.value; // 42 (Python: px.contents.value — a live c_int32)
281
- px[0]; // 42 (Python: px[0])
282
- px[0] = 100;
283
- x.value; // 100 (same memory)
284
-
285
- // View existing memory as a typed pointer
286
- const IntPtr = POINTER(c_int32);
287
- const p = IntPtr.fromBuffer(someBuffer);
288
- p[0];
289
- p[1];
290
- p[2]; // pointer arithmetic
291
-
292
- // cast() — Python: cast(ptr, POINTER(T))
293
- const q = cast(someBuffer, POINTER(c_int32));
294
- const r = cast(addressAsBigInt, POINTER(MyStruct));
295
- ```
296
-
297
- A `POINTER(T)` restype returns a pointer object, and a NULL pointer (return
298
- value or struct field) is `null` — where Python returns a falsy pointer.
299
-
300
- To hand a raw address to a function, use `c_void_p` as the argtype for
301
- portable code (Python accepts raw `int` only there). As in Python, values
302
- that cannot be converted (a plain JS function, an object) raise
303
- `ArgumentError` instead of passing NULL; `c_void_p` also accepts strings
304
- (as `char *`, Python `bytes`) and any TypedArray/ArrayBuffer.
305
-
306
- Declared `POINTER(T)` parameters reject incompatible ctypes instances,
307
- arrays and pointer types before entering C. Compatible subclasses and arrays
308
- are accepted, and a matching scalar/structure is passed by reference.
309
- These implicit scalar/array/NULL conversions apply to direct arguments only.
310
- To adapt one of these values through `_as_parameter_`, return an explicit
311
- compatible pointer or `byref` value instead, as in CPython.
312
- An explicit `cast()` changes the pointer type. Raw addresses and raw
313
- Buffer/TypedArray/ArrayBuffer memory remain node-ctypes extensions; use
314
- `c_void_p` for portable raw-address code.
315
-
316
- `byref(value, byteOffset = 0)` preserves the original owner and supports
317
- signed byte offsets. In-range references remain Buffer views; references
318
- outside the object's byte range carry an address and owner. As with raw
319
- addresses, the caller must ensure such memory is valid before dereferencing.
320
- Function pointers read from fields or obtained from FFI bindings can be
321
- assigned back to fields/arrays and passed as pointer arguments. Bare JS
322
- functions still require `callback()` / a prototype-created callback.
323
-
324
- ### Callbacks
325
-
326
- ```javascript
327
- import { callback, CFUNCTYPE, c_int32, c_void_p, readValue } from "node-ctypes";
328
-
329
- // Python-style type: CFUNCTYPE(restype, ...argtypes)
330
- const CompareFn = CFUNCTYPE(c_int32, c_void_p, c_void_p);
331
- const cmp = new CompareFn((a, b) => readValue(a, c_int32) - readValue(b, c_int32));
332
-
333
- // Or the one-shot form:
334
- const cmp2 = callback((a, b) => readValue(a, c_int32) - readValue(b, c_int32), c_int32, [c_void_p, c_void_p]);
335
-
336
- // Pass the callback itself (as in Python) or its address `cmp.pointer`.
337
- qsort(arr, 5, 4, cmp);
338
-
339
- // CFUNCTYPE types also work as struct fields (read back as a callable).
340
-
341
- // IMPORTANT: release the trampoline when done. Unlike Python, we cannot
342
- // rely on GC — the callback holds a native trampoline that C code may
343
- // still reference.
344
- cmp.release();
345
- cmp2.release();
346
- ```
347
-
348
- `CFUNCTYPE` and `WINFUNCTYPE` weakly intern live prototypes by the complete
349
- identity and order of their argument/return types, separately for each calling
350
- convention. Repeated requests reuse the same live prototype, as in Python,
351
- without keeping abandoned types alive. Callers, callbacks and output bindings
352
- retain their prototype while they are live.
353
-
354
- Prototype metadata is shared. Changing its public `restype` / `argtypes`
355
- metadata does not recompile the captured native signature or alter cache keys;
356
- request a different signature to change the ABI. Each new caller prepares its
357
- argument-conversion pipeline and captures its result-check hook independently.
358
- Existing callers retain their result-check snapshot and their own `errcheck`.
359
- An installed `from_param` converter still resolves the method at call time,
360
- as before.
361
-
362
- Structure, union and scalar-instance arguments received by `callback()`,
363
- `CFUNCTYPE` and `threadSafeCallback()` are owned snapshots: each one is a
364
- distinct slice of an 8 KB off-heap pool reserved for callback snapshots.
365
- Native-call temporaries use a separate pool that is never exposed, so a
366
- snapshot cannot reveal or alter memory that native code is still using.
367
- Slices are never reused, so a retained argument keeps its own bytes and
368
- identity. Detaching a snapshot's `ArrayBuffer` (`transfer()`, a transfer list)
369
- only affects the snapshots in that pool; later callbacks use a fresh one.
370
-
371
- - Retaining any slice keeps its whole 8 KB backing `ArrayBuffer` alive. When
372
- storing many small arguments for a long time, copy them, for example
373
- `Buffer.from(value._buffer)` or a new instance built from its fields.
374
- - `value._buffer.buffer` is the whole pool and can contain other callback
375
- snapshots. Use `_buffer` itself (or `byteOffset` and `length`), and copy
376
- before handing the underlying `ArrayBuffer` to untrusted code.
377
-
378
- Values larger than 2 KB, layouts aligned to more than 8 bytes and raw native
379
- callbacks keep a dedicated allocation.
380
-
381
- Both callbacks and libraries implement `Symbol.dispose`, so they work
382
- with the `using` declaration for scope-bound cleanup (also on `throw`):
383
-
384
- ```javascript
385
- {
386
- using libc = new CDLL(null);
387
- using cmp = callback(fn, c_int32, [c_void_p, c_void_p]);
388
- qsort(arr, 5, 4, cmp);
389
- } // close() + release() run automatically
390
- ```
391
-
392
- A bound function keeps its library loaded as long as it is referenced, also
393
- when the `CDLL` object itself is no longer used. After `close()`, `loaded` is
394
- false and its bound functions and symbol lookups throw; `close()` itself
395
- throws while a call to one of them is in progress (from a callback, or a
396
- pending `callAsync()`). Repeated `close()` calls are harmless.
397
-
398
- Existing `in_dll()` views keep the underlying module loaded even after
399
- `close()`. Release of the native library handle is deferred until the last
400
- dependent view, Buffer, typed array or typed pointer copy is collected; those
401
- existing views remain usable. Actual physical unloading depends on the OS loader: for example,
402
- musl keeps shared libraries resident until process exit even after `dlclose()`.
403
- Raw addresses obtained with `symbol()` do not carry this ownership information.
404
-
405
- Set `NODE_CTYPES_DEBUG_CALLBACKS=1` to log a stack trace for every
406
- callback garbage-collected without `.release()`.
407
-
408
- Callbacks invoked by native threads need `threadSafeCallback()`: the
409
- JavaScript function runs on the main thread, and the calling thread waits
410
- for its result (several threads can call it at the same time; each gets the
411
- result of its own call, `0` if the function throws). Like a timer, a
412
- thread-safe callback keeps the event loop
413
- alive until released; `.unref()` lets the process exit when nothing else
414
- is pending (calls are still delivered while it runs), `.ref()` restores it:
415
-
416
- ```javascript
417
- const onEvent = threadSafeCallback((code) => console.log("event", code), null, [c_int]).unref();
418
- startWorker(onEvent); // a native library calling onEvent from its own thread
419
- ```
420
-
421
- For an embedding runtime that must detach its native thread state before waiting,
422
- the optional fourth argument can be `{ abi, nativeContext: { suspend, resume, onError, notify? } }`
423
- instead of the existing ABI string. Each hook accepts a ctypes native function,
424
- a low-level function handle, or a nonzero BigInt function address:
425
-
426
- ```javascript
427
- const onRequest = threadSafeCallback(handleRequest, c_int, [c_int], {
428
- nativeContext: {
429
- suspend: runtime.func("save_context", c_void_p, []),
430
- resume: runtime.func("restore_context", null, [c_void_p]),
431
- onError: runtime.func("install_error", null, [c_void_p]),
432
- notify: runtime.func("wake_host", null, []),
433
- },
434
- });
435
- ```
436
-
437
- Function objects resolve through `_as_parameter_` or `address` once, when the
438
- callback is constructed. The hooks are called directly using the default C ABI;
439
- the function wrapper's JS converters and `errcheck` are not invoked:
440
-
441
- - `void *suspend(void)` runs on a foreign caller before queueing.
442
- - `void resume(void *)` restores that caller's saved state after dispatch, including
443
- queue failure or environment shutdown. Neither hook runs on the Node host fast path.
444
- - `void onError(void *)` consumes an opaque error pointer on the original caller
445
- thread, after restoration. During the JS callback, use
446
- `callback.setNativeError(pointer)` once and return the native API's required error
447
- sentinel (`NULL`, `-1`, etc.). Error payloads belong to each invocation, including
448
- concurrent and nested calls; JS exceptions are still reported as documented above.
449
- - Optional `void notify(void)` runs on the foreign caller after successful queueing,
450
- while its native state is detached. It may wake the host through the consumer's
451
- runtime, but must not execute JavaScript itself.
452
-
453
- `callback.drain()` executes a snapshot of pending calls **on the owning Node
454
- thread**, returning the number it claimed. Each call executes at most once,
455
- whether the TSFN or a drain gets there first. Delayed TSFN deliveries retain
456
- only the shared request state and do not touch completed calls' native arguments.
457
- The consumer must provide a safe way to reenter the host and call `drain()`;
458
- calling it before entering a blocking native wait is not sufficient.
459
-
460
- Hooks must not throw or execute JavaScript. Plain JS functions and known
461
- JS-backed callback wrappers are rejected; an address cannot prove a function's
462
- signature, validity or implementation. Supplied function objects are retained by
463
- the native dispatcher through release and queued delivery cleanup. This does not
464
- prevent explicitly closing their libraries or releasing their underlying resources;
465
- raw addresses carry no owner. Keep the callback and the hook libraries
466
- alive until all native calls have returned; explicit release is rejected while a
467
- native-context call is active. These hooks do not acquire the host runtime context,
468
- pump a blocked host event loop automatically, or implement interpreter ownership/subinterpreters.
469
- The host JS handler must acquire/release its own runtime context around native API
470
- operations. The ordinary callback path is unchanged when no hooks are supplied.
471
-
472
- Both callback implementations store narrow integer results in a complete
473
- libffi `ffi_arg`, with the declared signedness; failures zero that complete
474
- slot. Floating-point results retain their own storage width. The native
475
- `Callback` / `ThreadSafeCallback` classes also expose `getPointer()`, which
476
- throws after release.
477
-
478
- ### Errors: `errno` and `GetLastError`
479
-
480
- `GetLastError()` / `get_errno()` read a **private thread-local slot** —
481
- exactly like Python's `ctypes.get_last_error()` / `ctypes.get_errno()`.
482
- The slot is updated **only** by FFI calls through libraries opened with
483
- `use_last_error` or `use_errno`; unflagged calls leave it unchanged. As in Python
484
- those calls swap it with the system value: the function sees the value set
485
- with `set_errno()` / `set_last_error()`, the value it leaves becomes the
486
- private one, and the system value is restored after the call.
487
-
488
- ```javascript
489
- const user32 = new WinDLL("user32.dll", { use_last_error: true });
490
- const FindWindow = user32.func("FindWindowW", c_void_p, [c_wchar_p, c_wchar_p]);
491
- FindWindow("NoSuchClass", null);
492
-
493
- GetLastError(); // top-level (Python: ctypes.get_last_error)
494
- user32.get_last_error(); // per-library alias
495
- ```
496
-
497
- The snapshot is captured in native code immediately after the native call,
498
- whether direct or through libffi, before any other JS can clobber it. To read the raw system
499
- error instead, call `GetLastError` via FFI like any other function.
500
-
501
- ### Windows API
502
-
503
- `wintypes` is Python's `ctypes.wintypes`: the same types (BOOL, BYTE,
504
- WORD, DWORD, HANDLE, HWND, LPARAM, WPARAM, LPCWSTR, …), structures (`RECT`,
505
- `POINT`, `SIZE`, `MSG`, `FILETIME`, `WIN32_FIND_DATAW`, …) and pointer types
506
- (`LPDWORD = POINTER(DWORD)`, `LPRECT`, `PHANDLE`, …), plus common extras
507
- (`LRESULT`, `UINT_PTR`, `LSTATUS`, …).
508
-
509
- ```javascript
510
- import { WinDLL, Structure, POINTER, byref, wintypes } from "node-ctypes";
511
- const { WORD, HWND, BOOL, RECT, LPRECT } = wintypes;
512
-
513
- const kernel32 = new WinDLL("kernel32.dll");
514
-
515
- class SYSTEMTIME extends Structure {
516
- static _fields_ = [
517
- ["wYear", WORD],
518
- ["wMonth", WORD],
519
- ["wDayOfWeek", WORD],
520
- ["wDay", WORD],
521
- ["wHour", WORD],
522
- ["wMinute", WORD],
523
- ["wSecond", WORD],
524
- ["wMilliseconds", WORD],
525
- ];
526
- }
527
-
528
- kernel32.GetLocalTime.argtypes = [POINTER(SYSTEMTIME)];
529
- kernel32.GetLocalTime.restype = null;
530
- const st = new SYSTEMTIME();
531
- kernel32.GetLocalTime(byref(st));
532
-
533
- const user32 = new WinDLL("user32.dll");
534
- user32.GetClientRect.argtypes = [HWND, LPRECT];
535
- user32.GetClientRect.restype = BOOL;
536
- const rect = new RECT();
537
- user32.GetClientRect(hwnd, byref(rect));
538
- rect.right - rect.left; // LONG (c_long) values are BigInt
539
- ```
540
-
541
- ### Error checking (`errcheck`)
542
-
543
- Set `fn.errcheck = (result, func, args) => ...` to check or replace a result,
544
- or set it to `null` to clear it. For `lib.func()`, library attributes and
545
- `CFUNCTYPE` / `WINFUNCTYPE` callers, `func` is the public callable and `args`
546
- contains the original, unconverted arguments. Result conversion and any
547
- `OleDLL` HRESULT check run before the hook.
548
-
549
- Each invocation captures its hook before argument adapters or getters run.
550
- Replacing or clearing it affects later invocations, including reentrant calls,
551
- not the call already in progress or a pending `callAsync()` job.
552
-
553
- Hooks do not prevent otherwise unreachable functions and libraries from being
554
- garbage-collected, even when they reference the function itself. Active calls
555
- and workers retain their captured hook through result checking; `close()` is
556
- still rejected while that checking runs.
557
-
558
- The low-level native handle's `setErrcheck()` API instead passes the native
559
- handle as `func`, invoked with `.call()`, not a directly callable function.
560
-
561
- ### Scalar subclasses and result hooks
562
-
563
- Builtin scalar types return ordinary JS values. A subclass instead produces
564
- an instance containing the original C bytes, without invoking its constructor,
565
- public buffer factory or writer. Derived scalar fields, array elements,
566
- pointer indexing and callback arguments likewise expose typed instances;
567
- memory views remain live, including in mirror mode.
568
-
569
- The result pipeline is:
570
- `C bytes -> restype representation -> _check_retval_ -> errcheck -> OUT/INOUT`.
571
- A static `_check_retval_` receives the represented result and can replace it
572
- or throw. It is captured when the function is bound; reassigning an attribute's
573
- `restype` rebuilds that binding.
574
-
575
- ```javascript
576
- class CheckedInt extends c_int32 {
577
- static _check_retval_(value) {
578
- return value.value + 100;
579
- }
580
- }
581
- const checkedAbs = libc.func("abs", CheckedInt, [c_int32]);
582
- checkedAbs(-7); // 107
583
- ```
584
-
585
- Explicit `HRESULT` validation runs before `errcheck` with all loaders and
586
- prototype callers, not only `OleDLL`. An error in result checking prevents
587
- both `errcheck` and output conversion.
588
- `OleDLL` attributes and `func(name)` default to `HRESULT`; other loaders
589
- default to `c_int`. An explicit restype always overrides the default.
590
-
591
- ### Output parameters (`paramflags`)
592
-
593
- When at least one `out` param is declared, the call returns **only the
594
- out-params** (single value, or array if >1) — the `restype` is
595
- discarded. To also inspect it (e.g. a thread ID or success flag), attach an
596
- `errcheck`:
597
-
598
- ```javascript
599
- const { DWORD, HWND, LPDWORD } = wintypes;
600
- const proto = WINFUNCTYPE(DWORD, HWND, LPDWORD);
601
- const fn = proto.bind(user32, "GetWindowThreadProcessId", [
602
- { dir: "in", name: "hWnd" },
603
- { dir: "out", name: "pid" },
604
- ]);
605
-
606
- const pid = fn(hwnd); // positional; thread ID is discarded
607
- const p2 = fn({ hWnd: hwnd }); // or named-args
608
-
609
- fn.errcheck = (threadId, func, args) => {
610
- if (!threadId) throw new Error("call failed");
611
- return args; // continue returning the PID from the output instance
612
- };
613
- const p3 = await fn.callAsync(hwnd);
614
-
615
- fn.errcheck = (threadId, func, args) => {
616
- if (!threadId) throw new Error("call failed");
617
- return { threadId, processId: args[1].value };
618
- };
619
- const ids = fn(hwnd); // inspect both the return value and the output parameter
620
- ```
621
-
622
- As in Python, the value returned by `errcheck` is the result of the call,
623
- unless it is `args` itself: then the out-params are returned. Here `args`
624
- is the expanded argument list, with out-params as instances.
625
-
626
- These bindings have their own hook, independent of any cached `lib.func()`
627
- binding, and support `callAsync()` with the same output processing and
628
- per-call hook snapshot. Adapter temporaries stay alive through that processing,
629
- also when the hook throws.
630
-
631
- OUT conversion invokes the output instance's `__ctypes_from_outparam__()`.
632
- By default a builtin scalar yields its value, while a scalar subclass yields
633
- the instance. Override the method for custom output conversion.
634
-
635
- Use `{ dir: "inout", name: "value" }`, or tuple flag `3`, to pass an existing
636
- instance and return that exact instance after C modifies it. INOUT does not
637
- call `__ctypes_from_outparam__`; positional, named and default arguments use
638
- the same rule. Mixed outputs preserve parameter order. If `errcheck` returns
639
- anything other than the original `args`, neither OUT nor INOUT unpacking runs.
640
-
641
- ### Sharing memory with existing buffers
642
-
643
- ```javascript
644
- // Zero-copy view over a Node Buffer (Python: Structure.from_buffer)
645
- const r = RECT.from_buffer(packet, 16);
646
-
647
- // Wrap an externally-allocated pointer (Python: Structure.from_address)
648
- const r2 = RECT.from_address(malloc_result);
649
-
650
- // Bind a C-exported global (Python: c_int.in_dll)
651
- const tz = c_int32.in_dll(libc, "_timezone");
652
-
653
- // Raw bytes at an address (Python: (c_ubyte * n).from_address(addr));
654
- // `bytes._buffer` is a Buffer over that memory, as Python's memoryview()
655
- const bytes = array(c_uint8, 64).from_address(malloc_result);
656
- const view = new Float32Array(bytes._buffer.buffer, bytes._buffer.byteOffset, 16);
657
- ```
658
-
659
- Typed pointers read from fields or array elements, and views derived from
660
- them, retain their known memory owners. Typed assignments and
661
- `from_buffer_copy()` preserve known pointer references, including overlapping
662
- and self-copies; replacing a pointer releases its previous reference.
663
-
664
- Raw copies (`memmove()`, Buffer methods) do not transfer ownership metadata.
665
- Likewise, `from_address()` given a raw address cannot discover its allocation
666
- or library: the caller must keep that memory valid. Keeping a known owner
667
- alive does not take over responsibility for freeing externally allocated
668
- memory or explicitly releasing callbacks.
669
-
670
- `memmove()` and `memset()` return the destination address as BigInt, including
671
- zero-length operations (`0n` for a NULL destination with count zero).
672
- Counts must be non-negative safe integers. Copies/fills involving JS memory
673
- still stop at its end; raw native addresses remain the caller's responsibility.
674
- Scalar `from_buffer()` / `from_buffer_copy()` validate byte size and offset
675
- before producing an instance and accept Buffer, typed views and ctypes memory.
676
-
677
- Do not detach (`ArrayBuffer.prototype.transfer()`, a `postMessage` /
678
- `structuredClone` transfer list) memory passed to a call that is still running:
679
- a pending `callAsync()`, or the outer call while a callback runs. Native code
680
- keeps its address and may access memory that now belongs to another
681
- `ArrayBuffer` or has been released. Node-API cannot prevent the detach, so
682
- node-ctypes reports it instead. A synchronous call during which a JavaScript
683
- callback ran throws `argument N: memory was detached ...` after native code
684
- returns, and a `callAsync()` whose Buffer, typed array, DataView or ArrayBuffer
685
- argument was detached rejects. The check covers those arguments as passed,
686
- not addresses stored inside structures or obtained with `addressof()`.
687
-
688
- ### Electron
689
-
690
- Electron does not allow Buffers over memory that V8 did not allocate, so a
691
- Buffer _view_ of native memory cannot exist there. node-ctypes detects this
692
- when it loads (`EXTERNAL_BUFFERS` is `false`) and keeps the same API:
693
-
694
- - instances on native memory (`from_address`, `in_dll`, `pointer.contents`,
695
- `p[i]`, pointer fields) work on a copy that is re-read before every access
696
- and written back after every assignment, so they still see what C writes
697
- and C sees what JavaScript writes;
698
- - passed to a C function, `addressof()`, `pointer()`, `memmove()` and
699
- `memset()`, such an instance uses the original address;
700
- - the `_buffer` of such an instance is the copy: a typed array or Buffer
701
- method over it does not read or write native memory. Use the instance
702
- (`arr[i]`, `s.field`) or `memmove()`.
703
-
704
- Only the bytes of the accessed field are copied, one native call per read
705
- or write; instances on ordinary Buffers (`new Point()`, `c_int(5)`) do not
706
- need this native-memory synchronization. Set `NODE_CTYPES_NO_EXTERNAL_BUFFERS=1`
707
- to run in this mode on Node.js.
708
-
709
- ### Adapter protocols: `_as_parameter_` and `from_param`
710
-
711
- ```javascript
712
- // Instance protocol: auto-unwrap on call
713
- class Handle {
714
- constructor(h) {
715
- this._as_parameter_ = h;
716
- }
717
- }
718
- user32.CloseHandle(new Handle(hwnd));
719
-
720
- // Class protocol: custom conversion in argtypes
721
- class StrLen extends c_int32 {
722
- static from_param(s) {
723
- return typeof s === "string" ? s.length : s;
724
- }
725
- }
726
- const abs = libc.func("abs", c_int32, [StrLen]);
727
- abs("hello"); // 5
728
- ```
729
-
730
- As in Python, `from_param` receives the argument as passed (also with
731
- `CFUNCTYPE` prototypes), its result is converted as the declared type, and
732
- an error it throws becomes `ArgumentError` (`"argument 1: RangeError: ..."`).
733
-
734
- Non-pointer scalar CData arguments are read from their backing bytes, not an
735
- overridden public `.value` getter. Each value is snapshotted before converting
736
- the next argument, even without `argtypes`. A scalar `from_param` converter may
737
- return a CData instance of another class when its native scalar kind matches
738
- the declared type.
739
-
740
- Objects passed through argument adapters and the objects produced by their
741
- conversions stay alive while later arguments are converted and until the
742
- result and `errcheck` have been processed. With `callAsync()`, those temporary
743
- owners stay alive until its Promise settles. The native worker also retains
744
- memory passed by value or as an integer address, including values materialized
745
- by getters.
746
-
747
- `_as_parameter_` chains are resolved recursively, including results of
748
- `from_param`, with intermediate owners retained. As in CPython, an adapter may
749
- be visited again when a stateful getter eventually returns a usable value;
750
- object identity alone is not rejected as a cycle, and there is no fixed
751
- 128-step limit. Non-terminating recursion raises an argument conversion error.
752
- The available recursion depth and stack-error wording follow the JavaScript
753
- runtime, rather than CPython's runtime-specific recursion guard.
754
-
755
- This only covers the call: if C stores a pointer for later use, or returns a
756
- pointer into an argument's memory, keep the source object referenced for as
757
- long as that pointer is used. Callbacks still require explicit `.release()`.
758
-
759
- ### Big-endian structures
760
-
761
- ```javascript
762
- class NetHeader extends BigEndianStructure {
763
- static _fields_ = [
764
- ["magic", c_uint32],
765
- ["length", c_uint32],
766
- ];
767
- }
768
- const h = new NetHeader();
769
- h.magic = 0x12345678; // stored as 12 34 56 78 on the wire
770
- ```
771
-
772
- `LittleEndianStructure`, `BigEndianUnion`, `LittleEndianUnion` work the
773
- same way. Byte order is per-class — nested structs keep their own.
774
-
775
- Primitive arrays also follow their containing class's byte order, recursively
776
- for multidimensional arrays, including floats and wide-character arrays.
777
- Arrays of structures keep the element structure's own byte order. The same
778
- array type can be shared with native/little-endian containers without being
779
- modified. Raw Buffer and typed-memory copies still copy bytes, not values
780
- converted between byte orders.
781
-
782
- ### TypeScript
783
-
784
- Argument and return types are inferred from declared type classes such as
785
- `c_int32` and `c_size_t`. A literal tuple (`as const`) preserves argument types:
786
-
787
- ```ts
788
- const libc = new CDLL(null);
789
- const strlen = libc.func("strlen", c_size_t, [c_char_p] as const);
790
- const n: bigint = strlen("hello"); // typed as bigint, not any
791
- ```
792
-
793
- `static _fields_ = [["x", c_int32]]` compiles as written in Python (no
794
- `as const`). For typed struct fields use `defineStruct` instead of
795
- `extends Structure`:
796
-
797
- ```ts
798
- class Point extends defineStruct({ x: c_int32, y: c_int32 }) {
799
- distance() {
800
- return Math.sqrt(this.x ** 2 + this.y ** 2);
801
- }
802
- }
803
- const p = new Point({ x: 3, y: 4 }); // p.x, p.y typed as number
804
- ```
805
-
806
- `struct()` / `union()` fields, `POINTER()` targets and arrays of numeric
807
- types are typed too; a `null` return type is `void`:
808
-
809
- ```ts
810
- const PointDef = struct({ x: c_int32, y: c_double });
811
- PointDef.get(buf, "y"); // number
812
- POINTER(c_int32).fromAddress(addr)[0]; // number (.contents: c_int32 instance)
813
- array(c_int32, 4).create([1, 2, 3, 4])[0]; // number
814
- libc.func("srand", null, [c_uint32]); // returns undefined
815
- ```
816
-
817
- ---
818
-
819
- ## API reference
820
-
821
- ### Primitive types
822
-
823
- | Type | Aliases | Size | Notes |
824
- | ----------- | ------------- | -------- | --------------------------------------------- |
825
- | `c_int8` | `c_byte` | 1 | |
826
- | `c_uint8` | `c_ubyte` | 1 | |
827
- | `c_int16` | `c_short` | 2 | |
828
- | `c_uint16` | `c_ushort` | 2 | |
829
- | `c_int32` | `c_int` | 4 | |
830
- | `c_uint32` | `c_uint` | 4 | |
831
- | `c_int64` | `c_longlong` | 8 | |
832
- | `c_uint64` | `c_ulonglong` | 8 | |
833
- | `c_long` | | platform | 4 on Windows, 8 on Unix 64-bit; BigInt values |
834
- | `c_ulong` | | platform | mirrors `c_long`; BigInt values |
835
- | `c_float` | | 4 | |
836
- | `c_double` | | 8 | |
837
- | `c_bool` | | 1 | |
838
- | `c_char` | | 1 | 1-char string (Python `bytes`); also 0..255 |
839
- | `c_wchar` | | 2 or 4 | 1-char string; 2 on Windows, 4 on Unix |
840
- | `c_char_p` | | pointer | `char *` (NUL-terminated) |
841
- | `c_wchar_p` | | pointer | `wchar_t *` (NUL-terminated wide) |
842
- | `c_void_p` | `c_voidp` | pointer | opaque pointer / `HANDLE` |
843
- | `c_time_t` | | 8 | `time_t` (`SIZEOF_TIME_T`) |
844
- | `c_size_t` | | pointer | pointer-sized unsigned integer |
845
- | `c_ssize_t` | | pointer | pointer-sized signed integer |
846
- | `HRESULT` | | 4 | `c_int32` subclass — auto-raise on `OleDLL` |
847
-
848
- Plus the Win32 types, structures and pointer types of `ctypes.wintypes` under `wintypes`.
849
-
850
- ### Library loaders
851
-
852
- - `CDLL(name, mode?)` or `CDLL(name, { mode?, use_errno?, use_last_error? })` — C calling convention; `mode` is the `dlopen` flag (`RTLD_GLOBAL`, `RTLD_LOCAL`, `DEFAULT_MODE`)
853
- - `WinDLL(name, ...)` — Windows `__stdcall`
854
- - `OleDLL(name, ...)` — like `WinDLL`, auto-raises on negative `HRESULT`
855
- - `find_library(name)` — cross-platform name resolution
856
- - `cdll.<libname>`, `windll.<libname>` — lazy namespaces; `cdll.LoadLibrary(name)`, `new LibraryLoader(CDLL)`
857
- - Functions without `restype` return `c_int`; without `argtypes` the arguments are converted from their JS values (as Python)
858
-
859
- ### Type constructors
860
-
861
- - `struct({...})` / `class extends Structure` — composite struct types
862
- - `class extends Union` — union types
863
- - `array(type, n)` / `ARRAY(type, n)` — Python's `type * n`; callable: `array(c_int, 3)(1, 2, 3)`; elements can be simple types, structures, arrays, `POINTER(T)` and `CFUNCTYPE` types
864
- - `POINTER(type)` — pointer-to-type; accepts a thunk `POINTER(() => T)`
865
- - `pointer(instance)` — pointer to an existing c-data instance
866
- - `CFUNCTYPE(restype, ...argtypes)` — function pointer type: `proto(jsFn)` (callback), `proto(address)`, `proto([name, lib], paramflags?)` (Python: `proto((name, dll), paramflags)`)
867
- - `WINFUNCTYPE(restype, ...argtypes)` — `__stdcall` callback type
868
- - `defineStruct({...})` — typed-TS variant of `struct`
869
-
870
- ### Memory & introspection
871
-
872
- - `sizeof(type)` / `alignment(type)` — in bytes
873
- - `addressof(obj)` → BigInt
874
- - `byref(obj, byteOffset = 0)` — lightweight reference with a signed byte offset
875
- - `cast(ptr, type)` — reinterpret a pointer as another type
876
- - `memmove(dst, src, n)` / `memset(dst, val, n)` — buffers, ctypes instances, pointers or addresses; return the destination address as BigInt
877
- - `readValue(ptr, type, offset?)` / `writeValue(ptr, type, val, offset?)`
878
- - `create_string_buffer(init, size?)` / `c_buffer` / `create_unicode_buffer(init, size?)` — with `.value` (and `.raw`)
879
- - `string_at(addr, size?)` / `wstring_at(addr, size?)` — exactly `size` units, or up to the NUL
880
-
881
- With an explicit byte count, `string_at` returns a lossless Latin1 string:
882
- `Buffer.from(string_at(addr, n), "latin1")` recovers all `n` original bytes,
883
- including embedded NUL and invalid UTF-8. Without a count it retains the
884
- UTF-8 text representation. `wstring_at` counts native wide-character units.
885
-
886
- ### Error slots
887
-
888
- - `get_errno()` / `set_errno(v)`
889
- - `GetLastError()` / `SetLastError(v)` / `FormatError(code)`, Python names `get_last_error()` / `set_last_error(v)` (all platforms)
890
- - `ArgumentError` — raised for arguments that do not match `argtypes` (`"argument N: TypeError: ..."`)
891
- - Per-library: `lib.get_last_error()` / `lib.get_errno()`
892
-
893
- ### Structure helpers
894
-
895
- - `T.from_buffer(buf, offset?)` — zero-copy view
896
- - `T.from_buffer_copy(buf, offset?)` — independent copy
897
- - `T.from_address(addr)` — wrap raw pointer
898
- - `T.in_dll(lib, name)` — bind to exported global
899
- - `T._as_parameter_` / `T.from_param(v)` — adapter protocols
900
-
901
- ---
902
-
903
- ## Python ctypes parity & differences
904
-
905
- ### Supported Python ctypes behavior
906
-
907
- Structs, unions, bit fields (`_layout_` `"gcc-sysv"` / `"ms"`), anonymous
908
- fields, `_pack_`, `_align_`, subclasses of structures and unions, nested layouts,
909
- structures and unions by value (a struct `restype` returns an instance),
910
- arrays (also of arrays, pointers and function pointers), pointers and
911
- pointer arithmetic (also `POINTER(POINTER(T))`), callbacks (`CFUNCTYPE` /
912
- `WINFUNCTYPE`, also as struct fields), `prototype((name, dll), paramflags)`,
913
- `from_buffer` / `from_buffer_copy` / `from_address` / `in_dll`,
914
- `_as_parameter_` / `from_param`, `paramflags` out-params, `errcheck`,
915
- `use_errno` / `use_last_error`, `OleDLL` + `HRESULT` auto-raise,
916
- `BigEndianStructure` / `LittleEndianStructure` and union variants,
917
- `ctypes.wintypes`, keepalive of objects assigned to fields (`_objects`).
918
-
919
- ### Differences
920
-
921
- - **Callbacks must be released** with `.release()`. GC cannot detect when
922
- C code still holds the pointer; relying on it causes use-after-free.
923
- - **No automatic memory management** for returned pointers.
924
- - **Both class and functional syntax**: `class extends Structure`
925
- (Python-like) and `struct({...})` (functional) are both supported.
926
- - **Use type classes** such as `c_int32`, rather than string names such as
927
- `"int32"`, for the Python-compatible, typed API.
928
- - **`bytes` are JS strings**: `c_char` values, `c_char * n` arrays and
929
- fields, `c_char_p` and `create_string_buffer().value` use strings (UTF-8)
930
- where Python uses `bytes`; `.raw` is a `Buffer`.
931
- - **NULL pointers are `null`**, where Python returns a falsy pointer object.
932
- - **`c_char_p` / `c_wchar_p` accept raw addresses** (BigInt/number) as
933
- argtypes. Python is stricter (raises `TypeError` on `int`). For
934
- portable code use `c_void_p` there; both libraries accept it.
935
- - **`get_last_error()` / `set_last_error()`** exist on every platform
936
- (Python: Windows only), so the same code runs everywhere.
937
- - **64-bit and pointer-sized integers** (`c_int64`, `c_uint64`,
938
- `c_size_t`, `c_ssize_t`) also accept `null` (as 0) and a `Buffer`
939
- or `ArrayBuffer` (as its address) as arguments.
940
- - **Variadic arguments follow the C promotions**: a `c_float`, `c_int8`,
941
- `c_char`, … instance passed beyond `argtypes` is passed as `double` /
942
- `int`, where Python fails (`ffi_prep_cif_var failed`).
943
- - **A plain object is accepted for a structure argument** passed by value
944
- (fields by name).
945
- - **`c_wchar` also accepts a code point** (`new c_wchar(0x4E2D)`), where
946
- Python requires a 1-character string.
947
- - **`memmove()` / `memset()` stop at the end of JS memory** (Buffer, typed
948
- array, `ArrayBuffer`) instead of writing past it.
949
- - **Integer types reject non-integral numbers** (`3.7`, `NaN`) as Python
950
- rejects floats; JS has no int/float distinction, so `3.0` is accepted.
951
- - **Floating-point scalars accept BigInt in the range `-2**63` to `2**64-1`**,
952
- converted to a JS number; larger BigInts raise a range error. This applies
953
- consistently to constructors, fields and function arguments.
954
- - **Array instances are Buffers whose Array methods work on the elements**
955
- (`slice`, `map`, `includes`, …, as Python sequences); the Buffer methods
956
- (`readInt32LE`, `subarray`, …) work on the bytes.
957
- - **Array index reads follow JavaScript bounds behavior**: out-of-range
958
- indices return `undefined`; negative indices do not wrap around as in Python.
959
- - **Unions by value on x86-64 System V** are passed with the ABI rules;
960
- Python passes them in the wrong registers (libffi#33).
961
- - **Structure/Union fields are accessors of the class**, as Python fields
962
- are descriptors (`vars(s)` is empty): `Object.keys(s)` and `{ ...s }` do
963
- not list them; use `s.toObject()`. `JSON.stringify(s)` and
964
- `console.log(s)` show the fields.
965
-
966
- ### Not supported
967
-
968
- - **`ctypes.resize(instance, size)`** — Structure/Union instances use a
969
- Node `Buffer`, and Buffers aren't resizable in place.
970
- Work-around: `new MyStruct(myBuffer)` with a pre-sized buffer.
971
- - **`c_longdouble`** (80/128-bit float, `ffi_type_longdouble`) — rarely
972
- used; use a native wrapper that converts to supported types, or access
973
- storage through pointers/bytes. Declaring a `long double` ABI value as
974
- `c_double` is not a portable substitute.
975
-
976
- ### Migrating from 1.x
977
-
978
- 2.0 follows Python ctypes more closely. Code relying on the 1.x behavior
979
- needs these changes:
980
-
981
- | 1.x | 2.0 (as Python) |
982
- | ------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
983
- | `ptr.contents` returned the value | returns a live instance: `ptr.contents.value` (simple types), `ptr.contents.x` (structs); `ptr[0]` still returns the value |
984
- | `POINTER(T)` restype returned a `bigint` address | returns a pointer object (`null` for NULL); use `.address` for the number |
985
- | NULL `POINTER` struct fields were pointer objects | they are `null` |
986
- | `c_char` values were numbers | 1-character strings; `c_char * n` fields read/write as strings |
987
- | invalid `c_char` values were truncated | `TypeError` (`"one character bytes, bytearray, or an integer in range(256) expected, not ..."`) |
988
- | wrong argument types raised `TypeError` | raise `ArgumentError` (a `TypeError` subclass), message `"argument N: TypeError: ..."` |
989
- | unsupported pointer arguments (functions, plain objects) passed NULL | raise `ArgumentError` (`"'function' object cannot be interpreted as ctypes.c_void_p"`) |
990
- | functions without `restype` / `argtypes` | default `restype` is `c_int`; without `argtypes` the call uses the fixed-argument ABI |
991
- | `create_string_buffer(init)` | also takes `size` and returns a Buffer with `.value` / `.raw` |
992
- | `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 |
993
- | `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) |
994
- | `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) |
73
+ - [Getting started](guides/getting-started.md) — installation, supported platforms, building from source
74
+ - [Libraries and functions](guides/functions.md) — loading libraries, declaring and calling functions, adapters
75
+ - [Types](guides/types.md) — the C types, their sizes and JavaScript values, scalar subclasses
76
+ - [Structures, unions and arrays](guides/structures.md) — layouts, bit fields, packing, byte order
77
+ - [Pointers and memory](guides/memory.md) — pointers, `cast`, shared buffers, native memory, Electron
78
+ - [Callbacks](guides/callbacks.md) — C calling JavaScript, also from other threads
79
+ - [Asynchronous calls](guides/async.md) — `callAsync` and the `Executor`
80
+ - [Errors and results](guides/errors.md) — `errno`, `GetLastError`, `errcheck`, output parameters
81
+ - [Windows API](guides/windows.md) — `wintypes`
82
+ - [TypeScript](guides/typescript.md) — typed signatures and structures
83
+ - [Python ctypes parity](guides/python.md) — supported behavior, differences, migrating from 1.x
84
+ - [Coming from Koffi](guides/from-koffi.md) — the Koffi API mapped to node-ctypes
85
+ - [Performance](guides/performance.md) — comparisons with Koffi and how to run them
86
+ - [Building, testing and internals](guides/contributing.md) — tests, native backends, release validation
995
87
 
996
88
  ---
997
89
 
@@ -1012,245 +104,6 @@ Each example in `examples/` has its own README; see the [index](examples/README.
1012
104
 
1013
105
  ---
1014
106
 
1015
- ## Tests & docs
1016
-
1017
- From the repository root, `npm --prefix tests test` first builds a small C library (`tests/fixtures/`, into
1018
- `build/fixture/`) used by the tests of structures by value, array parameters
1019
- and reentrant calls; `npm run build:test-fixture` builds it alone. Matched
1020
- Python/JavaScript contracts live under `tests/cpython_parity/`, divided by domain,
1021
- and load the same library. Node-specific async, representation and GC checks
1022
- live under `tests/node_specific/`; genuine Python-only scheduling checks live
1023
- under `tests/python_specific/`. The former `common/` and `windows/` suites have
1024
- been migrated into these domains.
1025
-
1026
- Paired JavaScript uses the Python-shaped API: `Structure`/`Union` classes,
1027
- `ARRAY`, library attributes with `argtypes`/`restype`, and `CFUNCTYPE` bindings.
1028
- The structural guard checks neighboring files and matching class/method IDs
1029
- using the existing TypeScript parser and Python AST; runtime assertions remain
1030
- independent checks against CPython, not a claim based on file names alone.
1031
-
1032
- ```bash
1033
- npm install
1034
- npm run build
1035
- npm --prefix tests install
1036
- npm --prefix tests test # functional/parity tests
1037
- NODE_CTYPES_NO_EXTERNAL_BUFFERS=1 npm --prefix tests test # mirrored native memory
1038
- npm --prefix tests run test:parity # matched CPython and JS contracts
1039
- npm --prefix tests run test:parity:check # paired file/case/discovery/style guard
1040
- npm --prefix tests run test:python # all Python references
1041
- npm run test:types # TypeScript declarations
1042
- npm run docs # TypeDoc API site in docs/
1043
- npm run docs:serve # preview
1044
- ```
1045
-
1046
- See the [test suite guide](tests/README.md) for paired-case conventions,
1047
- runtime differences and focused commands.
1048
-
1049
- ### Performance comparisons
1050
-
1051
- There are two JavaScript comparisons, both against another FFI library.
1052
- From the repository root, after building node-ctypes:
1053
-
1054
- ```bash
1055
- npm --prefix tests install # includes Koffi
1056
- npm run build:test-fixture # shared C functions for both libraries
1057
- npm run bench:koffi # node-ctypes vs Koffi; Node 24+
1058
- npm run bench:ffi # node-ctypes vs node:ffi; Node 26+
1059
- ```
1060
-
1061
- The private test package explicitly approves the install script for Koffi 3.3.8.
1062
- When upgrading Koffi, review the new version before updating that approval with
1063
- `npm --prefix tests install-scripts approve koffi`; future versions are not
1064
- automatically authorized.
1065
-
1066
- `bench:ffi` adds `--experimental-ffi` automatically. Both comparisons
1067
- print a table grouped by workload and automatically generate HTML reports:
1068
-
1069
- - `tests/benchmarks/results/koffi.html`
1070
- - `tests/benchmarks/results/node-ffi.html`
1071
-
1072
- These paths are relative to the repository root, regardless of the working
1073
- directory. Each successful run replaces its previous report; generated results
1074
- are ignored by Git. Open the HTML file directly in a browser: it is responsive
1075
- and self-contained, with native HTML/CSS bar charts and no browser JavaScript,
1076
- external resources or server requirements.
1077
-
1078
- | Column | Meaning |
1079
- | ------------------------ | ----------------------------------------------------- |
1080
- | Case | The same operation and inputs for both libraries |
1081
- | node-ctypes / competitor | Median time +/- MAD (dispersion), in ns per operation |
1082
- | Ratio | node-ctypes time divided by competitor time |
1083
-
1084
- A ratio of `0.50x` means node-ctypes took half the time; `2.00x` means it
1085
- took twice the time. Lower times are better. There is no overall score
1086
- combining unrelated calls, memory access and asynchronous scheduling.
1087
- In the charts, **shorter bars are better**. Each workload group shares a linear
1088
- scale starting at zero; different groups use different scales. Bars show
1089
- medians, with +/- MAD whiskers (not confidence intervals). Each library also
1090
- shows its total measured operation count and elapsed time across the samples.
1091
-
1092
- Reports record library/runtime versions, CPU, OS/kernel, buffer mode, start/
1093
- finish timestamps and Git revision/working-tree status. Missing CPU or Git
1094
- metadata produces an explicit warning rather than invented values.
1095
-
1096
- Both comparisons cover narrow scalars, mixed GP/FP stack arguments, short/long
1097
- strings, buffer arguments, field reads, scalar callbacks and 64-callback C loops.
1098
- The node:ffi comparison includes 25 workloads. Koffi also covers structures by value,
1099
- variadic calls and async calls with 1/8 calls in flight. Cases without an
1100
- equivalent documented node:ffi API are listed as **not compared**, not
1101
- emulated with a different native signature.
1102
-
1103
- Inferred rows omit node-ctypes `argtypes`, while both competitors use explicit
1104
- fixed signatures for the same C functions: these rows include node-ctypes
1105
- inference overhead, not equivalent automatic-inference APIs.
1106
- The node:ffi bool row passes numeric `1` and compares normalized Number results:
1107
- node:ffi represents bool arguments/results as uint8 values, whereas node-ctypes
1108
- returns a JavaScript Boolean. Koffi's bool row uses Boolean input/output.
1109
- The thread-safe scalar callback rows measure node-ctypes dispatch on its host
1110
- thread against a competitor callback on the same thread, not cross-thread handoff.
1111
- The C-loop times are per batch of 64 completed callbacks, not per callback.
1112
-
1113
- The `CFUNCTYPE` rows measure calls through an already-bound node-ctypes
1114
- prototype, against an independently bound competitor function with the same
1115
- C signature. Bindings are separate to avoid sharing optimization feedback
1116
- with the direct-call rows. These cases do not include prototype construction
1117
- or callback registration.
1118
-
1119
- Both sides call the same C fixture and verify results before/after timing.
1120
- String contents are encoded on every call; node-ctypes reuses scratch storage,
1121
- not previously encoded strings. Measurements describe warmed repeated calls,
1122
- not cold-start allocation costs.
1123
- String lengths, narrow/inferred-stack i64 results and C-loop sums are compared
1124
- as Numbers, including conversion where the API returns BigInt; wide integers
1125
- are BigInt in both APIs. Structures are plain
1126
- objects. Async times include scheduling and are reported per completed call,
1127
- with the concurrency shown in the case name.
1128
-
1129
- Defaults are nine samples of at least 250 ms per library after warmup,
1130
- alternating library order. Each native signature has a separate call-site to
1131
- avoid mixing V8 optimization feedback between cases.
1132
- Each row is printed when its measurements finish.
1133
- Run comparisons serially, not concurrently. Optional arguments:
1134
-
1135
- ```bash
1136
- npm run bench:koffi -- --filter string,callback
1137
- npm run bench:ffi -- --samples 11 --duration 500
1138
- npm run bench:koffi -- --output comparison.json
1139
- ```
1140
-
1141
- `--output comparison.json` additionally saves medians, dispersion and all sample
1142
- durations/operation counts as JSON, and writes `comparison.html` next to it
1143
- instead of the default HTML report. Parent directories are created automatically.
1144
- HTML generation runs only after all measurements finish.
1145
- `benchmark_koffi.js` and `benchmark_node_ffi.js` define the actual side-by-side
1146
- comparisons; `runner.js` shares timing, table output and HTML generation without
1147
- extra dependencies or a separate renderer script. Benchmarks are not run by the
1148
- functional/parity test suite.
1149
-
1150
- ### Native backends and upstream libffi
1151
-
1152
- The maintained outgoing paths are the bounded C++ direct invokers, register-frame
1153
- calls and libffi. Register-frame calls cover any signature of scalars, pointers
1154
- and strings up to 32 arguments on AArch64, x86-64 System V and Win64: each
1155
- argument is converted straight into its register or stack word, and one C++
1156
- signature per ABI passes the whole frame (on Apple ARM64 the stack arguments
1157
- are packed by size and natural alignment, as the platform ABI requires).
1158
- libffi remains for aggregates, other calling conventions
1159
- and the remaining cases. `CDLL.func()` and prototype calls return the native
1160
- function itself when the arguments need no JavaScript conversion (scalars,
1161
- `c_char_p` strings), as Koffi does; objects, `errcheck` and the other
1162
- signatures are forwarded to the JavaScript converters.
1163
- Callbacks use libffi closures and the shared Node-API bridge; up to 64 callbacks
1164
- running inside one synchronous call reuse its handle scope instead of opening
1165
- their own. The source tree stays flat, with backend-specific files prefixed
1166
- where needed:
1167
-
1168
- | Files | Responsibility |
1169
- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
1170
- | [call_abi.h](./src/call_abi.h), [types.h](./src/types.h) | Shared calling conventions, ABI return words and scalar conversions, without libffi headers |
1171
- | [direct_call.h](./src/direct_call.h) | Exact fixed-signature C++ invokers |
1172
- | [frame_call.h](./src/frame_call.h) | Register-frame calls: argument placement per ABI and one C++ signature per return type |
1173
- | [libffi_types.cc](./src/libffi_types.cc), [libffi_types.h](./src/libffi_types.h) | Primitive mapping and aggregate descriptor factories |
1174
- | [libffi_type_cache.h](./src/libffi_type_cache.h) | Concrete owned aggregate cache used by layout metadata |
1175
- | [libffi_call.cc](./src/libffi_call.cc), [libffi_call.h](./src/libffi_call.h) | Calling conventions, CIFs, reusable plans and worker-owned extra-call interfaces |
1176
- | [libffi_callback.cc](./src/libffi_callback.cc), [libffi_callback.h](./src/libffi_callback.h) | Closure preparation, allocation and release |
1177
- | [function.cc](./src/function.cc), [function.h](./src/function.h) | Node-API call orchestration, marshalling, hooks and sync/async ownership |
1178
- | [callback.cc](./src/callback.cc), [callback.h](./src/callback.h) | Shared callback conversions, TSFN delivery, native-context hooks and lifetime |
1179
-
1180
- CMake discovers native files with `file(GLOB_RECURSE ... CONFIGURE_DEPENDS ...)`.
1181
- The public layouts retain their physical size/alignment; the libffi descriptor
1182
- cache in `layout.h` is intentionally concrete rather than ABI-agnostic.
1183
- High-level callback snapshot pooling and cached struct/array readers remain:
1184
- slices are never recycled, retained views have independent bytes and identity,
1185
- and custom getters, mirrored synchronization and Node-API ownership are preserved.
1186
-
1187
- **Temporary dependency pin.** The unmodified
1188
- [libffi submodule](https://github.com/libffi/libffi/tree/d02afc25e8ea3aac9e78e227748e1fd7c9f14c82) is pinned to upstream commit
1189
- [`d02afc25e8ea3aac9e78e227748e1fd7c9f14c82`](https://github.com/libffi/libffi/commit/d02afc25e8ea3aac9e78e227748e1fd7c9f14c82),
1190
- after the v3.8.0 release. Generated version fields still report 3.8.0; the
1191
- gitlink, not that version string, identifies the exact dependency source.
1192
- This includes the Darwin GP-composite stack-slot
1193
- [fix](https://github.com/libffi/libffi/commit/2472245a3430b9d24f085b7654e896e074bceb82)
1194
- and its [compiler/ABI guard adjustment](https://github.com/libffi/libffi/commit/3365ad8b968a9b742922b6f1188462fe6ce142ec):
1195
- small GP composites use aligned, whole-word stack slots in outgoing calls and
1196
- closures, without widening ctypes buffers or changing scalar/HFA packing.
1197
- This follows the compiler's C ABI rather than reproducing broken padding in
1198
- older libffi builds, including those used by some Python installations.
1199
-
1200
- Return to an official tag containing these fixes when released. After changing
1201
- the submodule revision, run `npm run generate-ffi-headers`, rebuild and repeat
1202
- the ABI/parity tests. Do not patch the vendored libffi internals.
1203
-
1204
- **Darwin ARM64 upstream limitation.** When all GP registers are
1205
- occupied, a byte-aligned non-HFA struct larger than 16 bytes after a narrow
1206
- stack scalar can still misalign its indirect pointer and subsequent arguments.
1207
- A callee dereferencing that pointer can crash. The upstream update does not
1208
- resolve this case and this project does not disguise it by altering layouts.
1209
- [test_function_abi.js](./tests/node_specific/test_function_abi.js) retains a
1210
- safe C stack-tag probe for sync/async calls, temporarily skipped only on Darwin
1211
- ARM64 until an upstream fix is available. The test remains active on other
1212
- targets. Other supported GP/HFA/large-aggregate cases and ordinary/thread-safe
1213
- callback ABI tests run normally.
1214
-
1215
- **Windows ARM64 variadic HFA limitation.** A named HFA argument containing four
1216
- doubles (32 bytes) in a variadic call triggers an access violation in upstream
1217
- libffi, independently of the Node wrapper. Avoid this signature until an upstream
1218
- fix is available. Its regression is temporarily skipped only on Windows ARM64
1219
- and still runs on other targets. Native calling behavior is unchanged.
1220
-
1221
- `CTYPES_ENABLE_DIRECT_CALLS` remains a build-time control, default ON, for both
1222
- the direct invokers and the register-frame calls. Fixed direct calls and workers
1223
- need no CIF; unsupported fixed signatures use libffi,
1224
- and async inferred/variadic calls own CIFs prepared on the JavaScript thread.
1225
- Workers retain the parent function, metadata and library through completion.
1226
- To compare the direct-enabled and libffi-only builds, follow the
1227
- [native validation commands](./tests/README.md#native-backends-and-abi-regressions).
1228
-
1229
- ### Release validation
1230
-
1231
- The workflow retains the eight Node 24 native build targets (Windows/macOS,
1232
- x64/ARM64, and Linux glibc/musl). C++20 conformance is checked with
1233
- `-pedantic-errors` on GCC/Clang and `/permissive-` on MSVC; vendor optimization
1234
- and the node-addon-api integration remain unchanged.
1235
-
1236
- Three runtime-control jobs reuse the built artifacts on Node 26 without
1237
- rebuilding the addon, running the functional parity suite normally and with
1238
- mirrored buffers. A Linux job runs the focused Python 3.15
1239
- reference tests in addition to the Python 3.14 reference coverage.
1240
-
1241
- The package assembler requires all eight nonempty binaries and includes
1242
- declarations, README, changelog and license. It fails on missing/unknown
1243
- artifacts or a stale output directory. Publish depends on the runtime gates,
1244
- requires a pushed tag matching the manifest version exactly, and uses `next`
1245
- for prereleases instead of `latest`. Manual workflow runs never publish.
1246
- These are configured gates, not a substitute for a successful native CI run.
1247
-
1248
- `npm --prefix tests test` builds the fixture and runs the suite;
1249
- `npm --prefix tests run test:js` reuses an already-built fixture/addon.
1250
- Both use the documented `--test-timeout` runner option.
1251
-
1252
- ---
1253
-
1254
107
  ## License
1255
108
 
1256
109
  MIT. Built with [libffi](https://github.com/libffi/libffi),
Binary file
Binary file
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "node-ctypes",
3
- "version": "2.13.1",
3
+ "version": "2.13.2",
4
4
  "description": "Python ctypes-like FFI for Node.js using libffi",
5
5
  "author": "Damiano Mazzella",
6
6
  "license": "MIT",
@@ -34,6 +34,7 @@
34
34
  "test:types": "tsc -p tests/types/tsconfig.json",
35
35
  "bench:koffi": "node tests/benchmarks/benchmark_koffi.js",
36
36
  "bench:ffi": "node --experimental-ffi tests/benchmarks/benchmark_node_ffi.js",
37
+ "bench:charts": "node tests/benchmarks/charts.js",
37
38
  "docs": "typedoc",
38
39
  "docs:serve": "typedoc && npx serve docs"
39
40
  },