node-ctypes 2.2.0 → 2.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +932 -0
- package/README.md +504 -99
- package/build/Release/ctypes-darwin-arm64.node +0 -0
- package/build/Release/ctypes-darwin-x64.node +0 -0
- package/build/Release/ctypes-linux-arm64-musl.node +0 -0
- package/build/Release/ctypes-linux-arm64.node +0 -0
- package/build/Release/ctypes-linux-x64-musl.node +0 -0
- package/build/Release/ctypes-linux-x64.node +0 -0
- package/build/Release/ctypes-win32-arm64.node +0 -0
- package/build/Release/ctypes-win32-x64.node +0 -0
- package/lib/core/Library.js +136 -109
- package/lib/core/callback.js +17 -20
- package/lib/core/conversions.js +376 -16
- package/lib/core/funcptr.js +148 -73
- package/lib/core/lazy-loader.js +10 -4
- package/lib/core/types.js +201 -98
- package/lib/index.d.ts +276 -83
- package/lib/index.js +44 -32
- package/lib/memory/buffer.js +82 -22
- package/lib/memory/operations.js +55 -45
- package/lib/memory/pointer.js +233 -57
- package/lib/platform/constants.js +0 -1
- package/lib/platform/errors.js +48 -4
- package/lib/platform/find_library.js +78 -19
- package/lib/platform/win_types.js +8 -3
- package/lib/structures/Structure.js +252 -203
- package/lib/structures/Union.js +10 -21
- package/lib/structures/helpers/array.js +102 -16
- package/lib/structures/helpers/bitfield.js +75 -150
- package/lib/structures/helpers/common.js +310 -21
- package/lib/structures/helpers/layout.js +145 -0
- package/lib/structures/helpers/struct.js +160 -419
- package/lib/structures/helpers/union.js +154 -155
- package/lib/structures/helpers/wrap.js +3 -15
- package/lib/types/SimpleCData.js +11 -32
- package/lib/types/primitives.js +160 -113
- package/lib/utils/cache.js +34 -2
- package/package.json +4 -1
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,932 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes to this project are documented in this file.
|
|
4
|
+
|
|
5
|
+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
|
|
6
|
+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
7
|
+
|
|
8
|
+
## [Unreleased]
|
|
9
|
+
|
|
10
|
+
## [2.4.0] - 2026-10-24
|
|
11
|
+
|
|
12
|
+
### Added
|
|
13
|
+
|
|
14
|
+
- **Release validation gates**: strict project C++20 compiler checks, Node 26
|
|
15
|
+
functional-parity controls reusing the artifacts and focused Python 3.15
|
|
16
|
+
references are wired into CI.
|
|
17
|
+
The assembler requires every supported binary and includes release docs;
|
|
18
|
+
publish waits for runtime gates, checks the exact version tag and sends
|
|
19
|
+
prereleases to `next`.
|
|
20
|
+
- **External performance comparisons**: `npm run bench:koffi` and
|
|
21
|
+
`npm run bench:ffi` compare the same C operations against Koffi and node:ffi.
|
|
22
|
+
Tables show per-case medians, dispersion and time ratios from at least nine
|
|
23
|
+
250 ms samples per library, with matching result representations. Koffi
|
|
24
|
+
additionally covers aggregates, variadic calls and controlled async work.
|
|
25
|
+
Every run generates a standalone responsive HTML report with bar charts,
|
|
26
|
+
operation counts, measured times and environment/source metadata; optional
|
|
27
|
+
JSON output includes all samples.
|
|
28
|
+
The separate self-benchmark command has been removed.
|
|
29
|
+
- **Result protocols**: static `_check_retval_` runs on the restype representation
|
|
30
|
+
before `errcheck` for library functions and prototype callers. OUT conversion
|
|
31
|
+
uses `__ctypes_from_outparam__`; INOUT (`dir: "inout"` / flag 3) uses and
|
|
32
|
+
returns the supplied instance without invoking the OUT hook.
|
|
33
|
+
- **Asynchronous output bindings**: `CFUNCTYPE` / `WINFUNCTYPE` bindings with
|
|
34
|
+
`paramflags` expose `callAsync()`, `funcName`, `address` and `_ffi`, with
|
|
35
|
+
the same output instances and `errcheck` return-args behavior as sync calls.
|
|
36
|
+
|
|
37
|
+
### Fixed
|
|
38
|
+
|
|
39
|
+
- **npm publication path**: explicitly prefix the downloaded tarball path with
|
|
40
|
+
`./` so npm publishes the local package instead of interpreting the path as
|
|
41
|
+
a GitHub repository shorthand and attempting an SSH connection.
|
|
42
|
+
- **Windows build diagnostics**: use compile-time guards for disabled floating-point
|
|
43
|
+
direct invokers. Keep the required inline-buffer alignment and scope MSVC padding
|
|
44
|
+
diagnostics to the affected class; waive upstream libffi's intentional unsigned
|
|
45
|
+
alignment-mask negation only in its Windows ARM64 source file.
|
|
46
|
+
- **libffi header generation**: recognize `AC_PACKAGE_VERSION` as an Autoconf
|
|
47
|
+
reference instead of reporting a false version mismatch, while retaining checks
|
|
48
|
+
for conflicting literal version assignments.
|
|
49
|
+
- **Koffi installation policy**: explicitly approve only the reviewed Koffi 3.3.3
|
|
50
|
+
install script in the private test package, eliminating the unreviewed-script
|
|
51
|
+
warning without authorizing future dependency versions.
|
|
52
|
+
- **Narrow call-conversion tests across ABIs**: use matching C fixture
|
|
53
|
+
signatures for narrow arguments/results instead of declaring `abs(int)`
|
|
54
|
+
with incompatible 8/16-bit or boolean types. Preserve signedness, narrowing
|
|
55
|
+
and boolean coverage without relying on unspecified register bits.
|
|
56
|
+
- **Library-view lifetime tests on musl**: preserve view/owner GC and logical
|
|
57
|
+
close checks without assuming that `dlclose()` physically unloads a module.
|
|
58
|
+
Probe the OS loader independently of `Library.close()` and reset fixture
|
|
59
|
+
state between cases, since resident libraries keep their static data.
|
|
60
|
+
Clarify the loader-dependent unloading contract in the API documentation.
|
|
61
|
+
- **Canonical test timeout**: test scripts use `--test-timeout=5000` before
|
|
62
|
+
the file selector; the old trailing `--timeout` was not a valid runner
|
|
63
|
+
option. `test:js` allows runtime controls to reuse the native artifacts.
|
|
64
|
+
- **Direct-call types**: native fast calls use exact scalar C++ signatures rather
|
|
65
|
+
than treating register-class compatibility as function-type compatibility.
|
|
66
|
+
Unsupported combinations and opaque pointer/string types use the existing
|
|
67
|
+
cached libffi path. The signature set stays bounded and invokers retain
|
|
68
|
+
internal linkage.
|
|
69
|
+
- **Callback return ABI and resources**: both callback handlers sign/zero-extend
|
|
70
|
+
narrow integral results to a complete `ffi_arg`, including zero/error paths.
|
|
71
|
+
Closure allocation uses a dedicated RAII deleter; partial thread-safe callback
|
|
72
|
+
construction does not release an absent TSFN. `wchar_t`, `size_t` and `ssize_t`
|
|
73
|
+
FFI descriptors now reflect native signedness and integer width.
|
|
74
|
+
- **Native callback types**: declarations include the existing `getPointer()`
|
|
75
|
+
method, which validates that the callback has not been released.
|
|
76
|
+
- **Typed pointer arguments**: incompatible ctypes values are rejected before
|
|
77
|
+
C entry, while compatible scalar/structure subclasses, arrays, explicit casts
|
|
78
|
+
and documented raw-memory extensions remain supported. Recursive
|
|
79
|
+
`_as_parameter_` chains retain intermediate owners and report cycles/depth
|
|
80
|
+
limits, including after `from_param`.
|
|
81
|
+
- **Function pointer round-trips**: FFI callables can be stored back in pointer
|
|
82
|
+
fields/arrays, passed to native functions and returned by pointer callbacks;
|
|
83
|
+
bare JS functions still require explicit callback creation.
|
|
84
|
+
- **Scalar buffer factories and byref**: size/offset checks precede instance
|
|
85
|
+
creation, derived copies bypass application constructors, and typed views
|
|
86
|
+
are accepted. `byref(value, offset)` now applies signed byte offsets while
|
|
87
|
+
preserving the original owner and pointee type.
|
|
88
|
+
- **OleDLL defaults and packing**: implicit restypes use HRESULT; explicit
|
|
89
|
+
overrides remain effective. MS layouts accept `_pack_` zero and non-powers
|
|
90
|
+
of two, reject explicit pack with GCC layout, and reject non-ABI alignments
|
|
91
|
+
for by-value calls instead of preparing an invalid FFI description.
|
|
92
|
+
- **Scalar subclass representation**: C results and callback arguments preserve
|
|
93
|
+
their bytes in derived scalar instances without calling application constructors
|
|
94
|
+
or writers, including floating-point payload bits. Fields, arrays, pointer
|
|
95
|
+
indexing and typed memory reads expose live derived instances. Builtin scalar
|
|
96
|
+
fast paths retain ordinary JS values.
|
|
97
|
+
- **Result checking consistency**: explicit HRESULT validation applies to CDLL,
|
|
98
|
+
WinDLL and prototype callers as well as OleDLL, before `errcheck` and outputs.
|
|
99
|
+
Non-callable hooks and exceptions surface as errors/rejections.
|
|
100
|
+
- **Stable ABI descriptors**: captured native struct/union layouts and array
|
|
101
|
+
elements are finalized recursively. FFI types retained by CIFs and call plans
|
|
102
|
+
cannot be invalidated by later `addField()` calls. Open builders and size/
|
|
103
|
+
alignment queries remain supported; finalized children do not prematurely
|
|
104
|
+
finalize their outer builder. Native values use finalized layouts, reject
|
|
105
|
+
short read buffers, and direct by-value recursion is rejected.
|
|
106
|
+
- **Independent function results**: returned functional `struct()` / `union()`
|
|
107
|
+
values now own their bytes before JavaScript conversion. Array views, nested
|
|
108
|
+
unions and union getters no longer alias the native function's reused result
|
|
109
|
+
buffer, including during reentrant conversion or `errcheck`. Class results
|
|
110
|
+
retain their single JS snapshot. Sync and async callers, library attributes,
|
|
111
|
+
prototypes and output bindings keep their existing public result shapes.
|
|
112
|
+
Explicit `toObject(buffer)` views and borrowed native result buffers are
|
|
113
|
+
unchanged; pointer targets are not deep-copied.
|
|
114
|
+
- **Primitive conversions**: negative unsigned arguments and integers outside
|
|
115
|
+
the signed 64-bit range wrap without adding `2**64` in floating point or
|
|
116
|
+
casting an out-of-range floating value to an integer. Fast, generic, async
|
|
117
|
+
and native slot conversions agree, including boolean and BigInt inputs.
|
|
118
|
+
- **Wide-character calls**: `c_wchar` uses the validated wchar converter in
|
|
119
|
+
the simple path, not pointer/string marshalling. Simple argument types are
|
|
120
|
+
explicitly enumerated; unsupported variadic types fall back before use.
|
|
121
|
+
- **Endian arrays**: primitive arrays in big-endian structures and unions
|
|
122
|
+
use the correct byte order, including multidimensional, float and wchar
|
|
123
|
+
arrays, serialization and mirrored native memory. Shared native/LE array
|
|
124
|
+
types are unchanged; nested structure elements keep their own byte order.
|
|
125
|
+
- **Boolean values**: bool bitfields normalize before masking, return booleans
|
|
126
|
+
and preserve adjacent fields according to C. False scalar instances remain
|
|
127
|
+
false for `c_bool` and `VARIANT_BOOL`; VARIANT_BOOL arguments, fields,
|
|
128
|
+
results and callbacks use the same boolean / `-1` representation.
|
|
129
|
+
- **Scalar validation**: constructors, value setters, arrays and bitfields
|
|
130
|
+
no longer coerce numeric strings, arbitrary objects or null to numbers.
|
|
131
|
+
Constructors still default to zero for omitted/undefined values, and
|
|
132
|
+
documented 64-bit numeric pointer/null arguments remain supported.
|
|
133
|
+
Incompatible scalar instances are rejected in declared numeric arguments
|
|
134
|
+
and fields. Floating-point BigInt conversions have the same range checks
|
|
135
|
+
in JS and native code; long and ssize_t bitfields are signed.
|
|
136
|
+
- **Array type retention**: array types are weakly interned by element type
|
|
137
|
+
and length, with finalized entries removed from the cache. Builtin element
|
|
138
|
+
types no longer retain every array length ever requested. Live instances,
|
|
139
|
+
signatures and containing types preserve type identity and validity.
|
|
140
|
+
Internal byte-array wrappers used for native layouts follow the same
|
|
141
|
+
policy; live native layouts retain their underlying metadata.
|
|
142
|
+
- **Errcheck lifetime and snapshots**: self-referencing hooks no longer keep
|
|
143
|
+
abandoned functions, libraries and callbacks alive. Each invocation captures
|
|
144
|
+
its hook before adapters or getters run, including raw native handles and
|
|
145
|
+
asynchronous jobs; replacing, clearing or adding a hook affects later calls.
|
|
146
|
+
Public prototype hooks receive the public callable, not a native handle.
|
|
147
|
+
Invalid hook assignments preserve the previous valid hook.
|
|
148
|
+
- **Output binding isolation**: `paramflags` bindings no longer inherit hooks
|
|
149
|
+
from an unrelated cached function. Adapter temporaries and active-call
|
|
150
|
+
protection extend through `errcheck` and output processing, synchronously
|
|
151
|
+
and asynchronously, while explicit HRESULT validation still runs first.
|
|
152
|
+
- **Pointer views and typed copies**: pointers read from fields, arrays and
|
|
153
|
+
double indirections retain their known owners. Borrowed views, pointer-slot
|
|
154
|
+
buffers and address-backed aliases share the appropriate ownership, even
|
|
155
|
+
if the original pointer is repointed. Typed structure/union/array copies
|
|
156
|
+
preserve references across overlapping and self-copies; overwriting
|
|
157
|
+
pointer storage releases the replaced references. Raw memory copies do
|
|
158
|
+
not infer or transfer ownership.
|
|
159
|
+
- **Exported global lifetime**: `in_dll()` views and their dependent buffers,
|
|
160
|
+
pointers and typed copies keep the native module loaded independently of
|
|
161
|
+
the library wrapper. `close()` immediately closes the logical handle,
|
|
162
|
+
rejects subsequent bound calls and symbol lookups, and defers physical
|
|
163
|
+
unloading until the dependent memory is no longer needed. This also
|
|
164
|
+
makes closing a current-process handle logically effective.
|
|
165
|
+
- **Argument conversion lifetime**: objects and temporaries unwrapped by
|
|
166
|
+
`from_param` / `_as_parameter_` remain alive while later arguments are
|
|
167
|
+
converted and through result conversion and `errcheck`, including
|
|
168
|
+
`callAsync()`. The same behavior applies to library attributes and
|
|
169
|
+
`CFUNCTYPE` / `WINFUNCTYPE` callers, without allocating ownership frames
|
|
170
|
+
for ordinary numeric calls.
|
|
171
|
+
- **Native asynchronous arguments**: copied structures and arrays,
|
|
172
|
+
values produced by getters, inferred C-data arguments, and buffers passed
|
|
173
|
+
as integer addresses are retained until the worker finishes. Library
|
|
174
|
+
closure is also rejected while native getters materialize the arguments;
|
|
175
|
+
worker setup and queue failures release their resources.
|
|
176
|
+
|
|
177
|
+
### Changed
|
|
178
|
+
|
|
179
|
+
- **Prototype identity**: `CFUNCTYPE` / `WINFUNCTYPE` reuse live prototypes by
|
|
180
|
+
complete type identity and calling convention through weak-value interning.
|
|
181
|
+
Live callers/callbacks/output bindings retain their prototype. Public
|
|
182
|
+
metadata is shared but does not mutate the captured native signature or
|
|
183
|
+
cache key. New caller bindings capture fresh adapters/retval hooks and
|
|
184
|
+
retain independent `errcheck` state.
|
|
185
|
+
- **Comparison summaries**: Koffi / `node:ffi` scripts no longer
|
|
186
|
+
combine unrelated workloads into an average ratio or winner count.
|
|
187
|
+
- **Memory operation results**: `memmove()` / `memset()` return the destination
|
|
188
|
+
address as BigInt instead of undefined. JS-memory clipping is preserved;
|
|
189
|
+
address caching excludes resizable/growable stores and detects detachment.
|
|
190
|
+
- **API declarations**: callback arguments include typed pointers and scalar
|
|
191
|
+
instances; unsupported callback return types remain rejected. Prototypes
|
|
192
|
+
retain argument/return types and async metadata, and native descriptor/
|
|
193
|
+
callback declarations now match their runtime members.
|
|
194
|
+
- **Derived scalar return types** now produce instances, as Python ctypes does.
|
|
195
|
+
TypeScript infers those instances and `_check_retval_` return types without
|
|
196
|
+
widening builtin values; INOUT directions are included in `ParamFlag`.
|
|
197
|
+
- **Native descriptor mutation**: `StructType.addField()` now throws after
|
|
198
|
+
the layout is acquired by a field, array, prepared signature or native
|
|
199
|
+
value. Construct a new descriptor to change its layout. This includes
|
|
200
|
+
aggregate array elements of length zero and descriptors used by callbacks.
|
|
201
|
+
- **TypeScript function pointers**: prototype callers and output bindings
|
|
202
|
+
expose the full `FFIFunction` interface. Low-level hooks use
|
|
203
|
+
`NativeErrcheckCallback`, whose `func` argument is a native handle rather
|
|
204
|
+
than a directly callable function. Corrected the output-binding example
|
|
205
|
+
to use the actual `GetWindowThreadProcessId` signature.
|
|
206
|
+
|
|
207
|
+
## [2.3.0] - 2026-10-23
|
|
208
|
+
|
|
209
|
+
### Fixed
|
|
210
|
+
|
|
211
|
+
- **`threadSafeCallback()` called by several native threads at the same
|
|
212
|
+
time**: the calls shared one result slot, so a thread could receive the
|
|
213
|
+
result of another call or wait forever. Each call now waits for its own
|
|
214
|
+
result; a call whose JavaScript function throws returns `0` instead of a
|
|
215
|
+
previous result.
|
|
216
|
+
- **Functions keep their library loaded**: a function obtained from a
|
|
217
|
+
`CDLL` (or with `CFUNCTYPE(...)([name, lib])`) no longer crashes when the
|
|
218
|
+
library object is garbage-collected. After `close()` its calls throw
|
|
219
|
+
`Library is closed`, and `close()` throws while a call to one of its
|
|
220
|
+
functions is in progress (from a callback, or a pending `callAsync()`).
|
|
221
|
+
- **Reentrant calls**: a function called again from a callback during its
|
|
222
|
+
own call overwrote the string arguments of the outer call.
|
|
223
|
+
- **Memory growth**: strings passed to `c_void_p` parameters accumulated in
|
|
224
|
+
an internal buffer that was never cleared.
|
|
225
|
+
- **Structure and union layout follows Python ctypes** (`ctypes._layout`):
|
|
226
|
+
bit fields of different types share storage units as with GCC
|
|
227
|
+
(`"gcc-sysv"`, the default except on Windows) or MSVC (`"ms"`, on Windows
|
|
228
|
+
and with `_pack_`); before, a bit field of a different type always started
|
|
229
|
+
a new unit, so mixed bit fields had a different size and offsets than in
|
|
230
|
+
C. Checked byte by byte against Python ctypes.
|
|
231
|
+
- **Subclasses of structures and unions**: a subclass with `_fields_` reused
|
|
232
|
+
the layout of its base once the base had been used, so its own fields were
|
|
233
|
+
missing; it now extends the fields of the base, which keep their offsets,
|
|
234
|
+
as in Python. A subclass without `_fields_` has the layout of its base.
|
|
235
|
+
- **Bit fields**: 32-bit wide fields read back as 0, and 64-bit fields wider
|
|
236
|
+
than 53 bits lost precision. Fields wider than 53 bits now read as BigInt.
|
|
237
|
+
Bit fields of big-endian structures are laid out from the big end, as in
|
|
238
|
+
Python.
|
|
239
|
+
- **`BigEndianStructure` / `BigEndianUnion`**: `get()`, `set()` and
|
|
240
|
+
`toObject()` used little-endian (field access was already correct).
|
|
241
|
+
- **Objects assigned to fields of nested structures** (strings, pointers,
|
|
242
|
+
callbacks) were kept alive only by the temporary nested view and could be
|
|
243
|
+
collected while the outer structure still pointed to them; they now live
|
|
244
|
+
with the memory of the outer structure, as Python `_objects`.
|
|
245
|
+
- **Structures by value**: structures with bit fields, subclasses, `_align_`
|
|
246
|
+
and arrays of structures (`Cannot assign to read only property '_native'`)
|
|
247
|
+
are passed and returned with the layout of the JS definition.
|
|
248
|
+
- **Array parameters** (`argtypes = [c_int32 * 4]`) were passed by value,
|
|
249
|
+
as a structure of N elements, so the C function received the bytes of
|
|
250
|
+
the array as its pointer; they are now passed by address, as in C and
|
|
251
|
+
Python. As in Python, only an array of the same element type and length
|
|
252
|
+
(or a Buffer / typed array) is accepted, other values raise
|
|
253
|
+
`ArgumentError`.
|
|
254
|
+
- **`errcheck` of functions with `paramflags`** was never called. It now
|
|
255
|
+
receives `(result, func, args)` with the out-params as instances, and its
|
|
256
|
+
return value is the result unless it returns `args`, as in Python.
|
|
257
|
+
- **Invalid native types no longer terminate the process**:
|
|
258
|
+
`StructType.addField()` / `ArrayType` with an invalid type, a negative or
|
|
259
|
+
fractional array length and a zero-length `char` array initialized from a
|
|
260
|
+
string threw uncaught C++ exceptions or crashed; they now throw JS errors
|
|
261
|
+
(and any C++ exception becomes a JS error). Fields of
|
|
262
|
+
`StructType.create()` objects could not be assigned.
|
|
263
|
+
- **`use_errno` / `use_last_error`** only read `errno` / `GetLastError()`
|
|
264
|
+
after the call. As in Python, the value set with `set_errno()` /
|
|
265
|
+
`set_last_error()` is now the system value during the call, and the
|
|
266
|
+
system value is restored after it (also with `callAsync()`).
|
|
267
|
+
- **Wide strings with characters outside the BMP** (emoji, ...) were passed
|
|
268
|
+
as UTF-16 code units where `wchar_t` is 32-bit (Linux, macOS): `wcslen("a😀b")`
|
|
269
|
+
was 4 instead of 3. Surrogate pairs now become one `wchar_t`; lone
|
|
270
|
+
surrogates are kept, as in Python. `wstring_at()` keeps lone surrogates
|
|
271
|
+
instead of replacing them with U+FFFD.
|
|
272
|
+
- **`c_wchar` arguments** accepted any string (using its first code unit);
|
|
273
|
+
as in Python they must be exactly one character.
|
|
274
|
+
- **64-bit and pointer-sized integer arguments** (`c_int64`, `c_uint64`,
|
|
275
|
+
`c_size_t`, `c_ssize_t`) silently passed `0` for strings, symbols,
|
|
276
|
+
functions and plain objects; they now raise `ArgumentError`. `null` (0)
|
|
277
|
+
and Buffer / ArrayBuffer (their address) are still accepted.
|
|
278
|
+
- **`errcheck` of library attributes** (`libc.abs.errcheck = ...`) was set
|
|
279
|
+
on the function shared by `func()` calls with the same signature, and was
|
|
280
|
+
lost when `argtypes` / `restype` changed. Each attribute now keeps its
|
|
281
|
+
own function and its `errcheck`, as in Python.
|
|
282
|
+
- **`func()` cache**: functions with the same signature but different
|
|
283
|
+
options (`abi`, ...) shared one cache entry.
|
|
284
|
+
- **`OleDLL`**: each `func()` call returning a cached function added another
|
|
285
|
+
HRESULT check on top of its `errcheck`, and setting `errcheck` removed the
|
|
286
|
+
HRESULT check. As Python `HRESULT._check_retval_`, the check now runs
|
|
287
|
+
before `errcheck` and is not replaced by it.
|
|
288
|
+
- **`from_param`** was called after the default conversion of the argument
|
|
289
|
+
(so it received a Buffer instead of the object passed) and was ignored by
|
|
290
|
+
`CFUNCTYPE` prototypes. As in Python it now receives the argument as
|
|
291
|
+
passed, for `CDLL` functions and prototypes, and its errors raise
|
|
292
|
+
`ArgumentError` (`argument 1: RangeError: ...`).
|
|
293
|
+
- **`memmove()` / `memset()`** crashed with a `Uint8Array` that is not a
|
|
294
|
+
Buffer and rejected other typed arrays, `DataView` and `ArrayBuffer`;
|
|
295
|
+
these are now accepted as bytes. `memset()` stops at the end of JS memory
|
|
296
|
+
as `memmove()` does, instead of throwing.
|
|
297
|
+
- **`find_library()` on Linux** could return the 32-bit library of a
|
|
298
|
+
multiarch system, and never found versioned sonames outside the ldconfig
|
|
299
|
+
cache. As Python it returns the soname of the library with the ABI of the
|
|
300
|
+
process, then the highest version found in the library directories.
|
|
301
|
+
- **Integer values wrap to the bits of the type**, as in Python, instead of
|
|
302
|
+
throwing `RangeError`: `new c_uint8(256).value === 0`,
|
|
303
|
+
`new c_uint64(-1).value === 2n ** 64n - 1n`, also for structure fields
|
|
304
|
+
and array elements.
|
|
305
|
+
- **Structures with `_pack_` by value**: the native description placed the
|
|
306
|
+
fields at their natural offsets, so the C function received a different
|
|
307
|
+
layout. The fields now keep the offsets of the JS layout (misaligned ones
|
|
308
|
+
as bytes), and on x86-64 System V a structure with misaligned fields is
|
|
309
|
+
passed and returned in memory, as GCC and clang do (Python ctypes uses
|
|
310
|
+
registers there). Padding of structures with bit fields is no longer
|
|
311
|
+
passed as bytes, which moved a `float` that shares an eightbyte with
|
|
312
|
+
padding from an SSE register to an integer register on x86-64.
|
|
313
|
+
- **Native types are recognized by their instances**: `StructType`,
|
|
314
|
+
`ArrayType` and `Library` objects were recognized by the names of their
|
|
315
|
+
methods, so a JS object with the same methods reached the native code and
|
|
316
|
+
failed with an unclear error. Their instances are now marked with a
|
|
317
|
+
Node-API type tag; other values raise a `TypeError` (`Type must be a CType
|
|
318
|
+
enum value (number), StructType or ArrayType`). Invalid types of
|
|
319
|
+
functions, callbacks, fields and arrays raise `TypeError` everywhere.
|
|
320
|
+
- **Arguments of a type that cannot be converted** left their slot
|
|
321
|
+
uninitialized instead of raising `ArgumentError`.
|
|
322
|
+
- **Errors of a callback result conversion** no longer cross C frames: the
|
|
323
|
+
callback returns 0 and the error is reported as other callback errors.
|
|
324
|
+
|
|
325
|
+
- **Callback lifetime**: a `threadSafeCallback()` collected by the GC while
|
|
326
|
+
calls were still queued freed memory that the queued calls used; a
|
|
327
|
+
`callback()` called from another thread (for example by a function run with
|
|
328
|
+
`callAsync`) ran JavaScript off the main thread. The first now keeps its
|
|
329
|
+
state until the last queued call, the second records an error and returns 0
|
|
330
|
+
(use `threadSafeCallback()` for other threads).
|
|
331
|
+
- **Pointers** (Python parity): `byref(p)` / `addressof(p)` of a `POINTER`
|
|
332
|
+
instance give the address of the pointer itself (a `T**` output parameter
|
|
333
|
+
wrote past the target); `cast()` and `p.add()` keep the source alive;
|
|
334
|
+
`p.contents = x` rejects an instance smaller than the pointed type;
|
|
335
|
+
`cast(c_char_p(...), POINTER(c_char))` reads the stored address;
|
|
336
|
+
`pointer(array)` points to the array.
|
|
337
|
+
- **`cast(x, c_void_p | c_char_p | c_wchar_p)`** read the bytes of `x` as a
|
|
338
|
+
value: it now returns an instance pointing to `x` (kept alive), as Python.
|
|
339
|
+
- **Structure arguments**: a plain object is converted to an instance of the
|
|
340
|
+
structure; an array is rejected (Python rejects a tuple).
|
|
341
|
+
- **Variadic arguments**: typed instances (`c_int8(1)`, `c_float(1.5)`, ...)
|
|
342
|
+
are passed with the C default promotions; typed arrays as pointers.
|
|
343
|
+
- **`_fields_`**: entries keep their order also for integer-like names;
|
|
344
|
+
duplicate names and malformed entries raise `TypeError`. `struct()` accepts
|
|
345
|
+
a Structure/Union class as anonymous field; `Union` supports `_anonymous_`
|
|
346
|
+
(also nested).
|
|
347
|
+
- **Callbacks with `c_char_p` / `c_wchar_p` restype** can return a string
|
|
348
|
+
(it is kept alive with the callback, as Python does).
|
|
349
|
+
- **Library loading**: on Windows `LoadLibraryExW` (UTF-8 paths) with the
|
|
350
|
+
flags of Python (`LOAD_LIBRARY_SEARCH_DEFAULT_DIRS`, plus the directory of
|
|
351
|
+
the library when the name is a path), without changing the DLL search path
|
|
352
|
+
of the process; `GetProcAddress` errors no longer say `LoadLibraryExA`. On
|
|
353
|
+
POSIX symbols are resolved at load time (`RTLD_NOW`), as Python.
|
|
354
|
+
- **`find_library()` on macOS** finds libraries and frameworks in the dyld
|
|
355
|
+
shared cache (`/usr/lib/libc.dylib`, `CoreFoundation.framework`), searching
|
|
356
|
+
Homebrew first as Homebrew's Python.
|
|
357
|
+
- **`string_at()` / `wstring_at()`** returned `null` for instances, arrays,
|
|
358
|
+
pointers, `c_char_p`/`c_void_p` and `_as_parameter_`; they read their
|
|
359
|
+
memory as Python. Strings (also `c_char_p.value`) are no longer truncated
|
|
360
|
+
at 1 MiB.
|
|
361
|
+
- **`readValue()` / `writeValue()` / `sizeof()`** accept addresses, ctypes
|
|
362
|
+
instances and typed arrays for every type, with bounds checks.
|
|
363
|
+
- **`c_void_p` fields** accept pointers created from an address,
|
|
364
|
+
`_as_parameter_` and `c_char_p` instances, and keep assigned memory alive.
|
|
365
|
+
- **`array(struct({...}), n)`** (and `union()`) failed in the native layer.
|
|
366
|
+
- **`Structure.from_buffer()`** accepted negative offsets; it now validates
|
|
367
|
+
them as Python and accepts typed arrays and ctypes instances.
|
|
368
|
+
- **`String(cdll)`, `JSON.stringify` and other probes** of the lazy loaders
|
|
369
|
+
tried to load a library named `toString`, `toJSON`, ...; names starting
|
|
370
|
+
with `_` are not libraries, as in Python.
|
|
371
|
+
- **`f.argtypes = null`** and **`f.errcheck = undefined`** threw.
|
|
372
|
+
- **Unions by value on x86-64 System V** were passed in the wrong registers
|
|
373
|
+
(libffi has no union type, libffi#33; CPython has the same bug): each
|
|
374
|
+
eightbyte now gets the class of all the members that cover it.
|
|
375
|
+
- **Silent acceptances where Python raises**: too many positional
|
|
376
|
+
initializers (`TypeError: too many initializers`), an instance of another
|
|
377
|
+
type assigned to a field (`incompatible types`), a Buffer too long for a
|
|
378
|
+
`c_char * n` field (`bytes too long`), bit fields of non-integer types
|
|
379
|
+
(`bit fields not allowed for type c_float`). A `SimpleCData` instance is a
|
|
380
|
+
positional initializer (`P(c_int(5))`). `array(c_char, n).create("héllo")`
|
|
381
|
+
encodes UTF-8 as `.value`.
|
|
382
|
+
|
|
383
|
+
### Added
|
|
384
|
+
|
|
385
|
+
- **`_layout_` and `_align_`** on structures and unions, as in Python ctypes.
|
|
386
|
+
|
|
387
|
+
- **Structures and unions by value as callback arguments**, as in Python;
|
|
388
|
+
a structure restype of a callback raises `TypeError: invalid result type
|
|
389
|
+
for callback function` at creation, as in Python.
|
|
390
|
+
- **`winmode`** option of `CDLL` (Windows `LoadLibraryExW` flags), as Python.
|
|
391
|
+
- **`pack`, `layout`, `align` options** of `struct()` / `union()`;
|
|
392
|
+
`union()` and `defineUnion()` accept options.
|
|
393
|
+
- **`WinError(code, descr)`** has `errno` (mapped from the Windows code as
|
|
394
|
+
Python's `OSError`) and `strerror`.
|
|
395
|
+
|
|
396
|
+
### Changed
|
|
397
|
+
|
|
398
|
+
- **Non-integral numbers for integer types raise `TypeError`** (`'float'
|
|
399
|
+
object cannot be interpreted as an integer`), as Python does for floats:
|
|
400
|
+
arguments (`ArgumentError`), constructors, fields, bit fields and callback
|
|
401
|
+
results. Integral numbers outside the range of the type wrap as before
|
|
402
|
+
(64-bit values no longer saturate).
|
|
403
|
+
- **Array methods work on the elements**: `slice`, `at`, `indexOf`,
|
|
404
|
+
`includes`, `forEach`, `map`, `fill`, `join`, `entries`, ... on an array
|
|
405
|
+
instance use the elements (Python sequence operations), not the bytes of
|
|
406
|
+
the Buffer; slices of `c_char`/`c_wchar` arrays are strings and
|
|
407
|
+
`JSON.stringify` gives the elements. Buffer methods (`readInt32LE`,
|
|
408
|
+
`subarray`, ...) still work on the bytes.
|
|
409
|
+
- **`POINTER(T)` and `array(T, n)` are cached**: the same type object for
|
|
410
|
+
the same arguments, as in Python.
|
|
411
|
+
- **`errcheck` receives the function itself** (`func === lib.abs`) for every
|
|
412
|
+
restype, as in Python; it was the native wrapper for simple restypes.
|
|
413
|
+
- **Typings**: statics `size` / `alignment` / `fields` of Structure classes,
|
|
414
|
+
classes returned by `defineStruct()` / `defineUnion()` with their statics,
|
|
415
|
+
element-wise array methods, narrower element types of `array()` /
|
|
416
|
+
`bitfield()`, typed arrays and addresses in `readValue()` / `writeValue()`.
|
|
417
|
+
|
|
418
|
+
- **Structure/Union fields are accessors of the class** instead of a
|
|
419
|
+
`Proxy` around each instance (Python: fields are descriptors of the
|
|
420
|
+
class). Field reads and writes are about 5 times faster (about 4 ns
|
|
421
|
+
instead of 20-25 ns). `Object.keys(s)` and `{ ...s }` no longer list the
|
|
422
|
+
fields: use `s.toObject()`; `JSON.stringify(s)` (new `toJSON()`) and
|
|
423
|
+
`console.log(s)` show them.
|
|
424
|
+
- **A nested structure or union field is an instance of its class**
|
|
425
|
+
(Python parity) on the memory of the outer instance, instead of a
|
|
426
|
+
`Proxy` view: `rect.a instanceof POINT`, and its methods and `toObject()`
|
|
427
|
+
are available. The instance is created on the first access and reused
|
|
428
|
+
(`rect.a === rect.a`), so `rect.a.x` takes about 6 ns instead of 170 ns.
|
|
429
|
+
- **Faster calls** (measured on macOS arm64 against the previous version):
|
|
430
|
+
- functions with fixed numeric, pointer or string arguments and a result
|
|
431
|
+
that is not an array go through a dedicated path without the general
|
|
432
|
+
call state: `abs` / `sqrt` about 25% faster, `memset` with a Buffer
|
|
433
|
+
about 40%;
|
|
434
|
+
- numeric arguments take one Node-API call instead of two, and a Buffer
|
|
435
|
+
or typed array passed as a pointer one instead of three;
|
|
436
|
+
- variadic calls (`sprintf`) about 15% faster;
|
|
437
|
+
- structures returned by value about 2 times faster: the bytes are
|
|
438
|
+
returned in a Buffer reused by the function instead of a new one per
|
|
439
|
+
call;
|
|
440
|
+
- writes of 64-bit integer values given as numbers (`c_int64`,
|
|
441
|
+
`c_uint64`, `c_size_t`, `c_long` fields and `.value`) about 4 times
|
|
442
|
+
faster.
|
|
443
|
+
- **Benchmark 7** (`tests/benchmarks/benchmark_koffi.js`) measured reads of
|
|
444
|
+
two plain JS objects; it now measures structure fields in memory and a
|
|
445
|
+
structure returned by value.
|
|
446
|
+
- **Error messages follow Python 3.14+ ctypes**: `c_char` / `c_wchar`
|
|
447
|
+
values (`one character bytes, bytearray, or an integer in range(256)
|
|
448
|
+
expected, not a string of length 2`, `a unicode character expected, ...`),
|
|
449
|
+
pointer arguments (`'function' object cannot be interpreted as
|
|
450
|
+
ctypes.c_void_p` instead of `wrong type`) and numeric arguments
|
|
451
|
+
(`'string' object cannot be interpreted as an integer`, `must be real
|
|
452
|
+
number, not string`).
|
|
453
|
+
- **`ArgumentError`** accepts the `options` of `Error` (`{ cause }`).
|
|
454
|
+
- **Python reference tests run in CI** (Python 3.14, with `unittest`; no
|
|
455
|
+
longer `pytest`).
|
|
456
|
+
- **A Structure/Union `restype` returns an instance of the class** (Python
|
|
457
|
+
parity) instead of a plain object; `errcheck` receives the instance. A
|
|
458
|
+
`struct()` definition as `restype` still returns a plain object.
|
|
459
|
+
- **Tests**: `npm test` builds a C test library (`tests/fixtures/`) for
|
|
460
|
+
structures by value, array parameters and reentrant calls; its Python
|
|
461
|
+
twin tests check the same behavior with Python ctypes.
|
|
462
|
+
- **C++20 cleanup of the native module**: concepts for the wrapper classes
|
|
463
|
+
and the direct-call invokers, `constexpr` type helpers, `[[nodiscard]]`
|
|
464
|
+
results, one parser for native types and one for callback signatures.
|
|
465
|
+
Values in raw memory (libffi results, C memory) are read with one
|
|
466
|
+
`LoadAs<T>` helper instead of a union whose inactive members were read
|
|
467
|
+
(undefined behavior in C++); buffers are passed as `std::span` /
|
|
468
|
+
`std::wstring_view` with their size.
|
|
469
|
+
The descriptors of structures, unions and arrays (`StructInfo`,
|
|
470
|
+
`ArrayInfo`) are in `src/layout.h` / `layout.cc`, separate from their JS
|
|
471
|
+
wrappers (`StructType` in `struct.h`, `ArrayType` in `array.h`).
|
|
472
|
+
- **Build**: the native module is compiled as standard C++20 without
|
|
473
|
+
compiler extensions (`-std=c++20` instead of `-std=gnu++20`) and with
|
|
474
|
+
warnings enabled (`-Wall -Wextra`, `/W4`); it builds without warnings.
|
|
475
|
+
|
|
476
|
+
## [2.2.0] - 2026-10-22
|
|
477
|
+
|
|
478
|
+
### Added
|
|
479
|
+
|
|
480
|
+
- **Embedded Python example**: `demo_python_cryptography.js` uses
|
|
481
|
+
pyca/cryptography (hashes, HMAC, RSA, EC and DSA keys and signatures, an
|
|
482
|
+
X.509 CSR and a self-signed certificate) and checks every result with
|
|
483
|
+
`node:crypto`.
|
|
484
|
+
- **Embedded Python example**: `Python.initialize({ stdout, stderr })` writes
|
|
485
|
+
Python's output through `process.stdout` / `process.stderr` (`"node"`, in
|
|
486
|
+
order with `console.log`) or captures it with a function; in Electron,
|
|
487
|
+
`toTypedArray()` falls back to a copy.
|
|
488
|
+
- **`EXTERNAL_BUFFERS`**: `false` where the runtime does not allow Buffers
|
|
489
|
+
over native memory (Electron). Detected when the native module loads
|
|
490
|
+
(`napi_no_external_buffers_allowed`), not from the runtime name;
|
|
491
|
+
`NODE_CTYPES_NO_EXTERNAL_BUFFERS=1` forces the mode on Node.js.
|
|
492
|
+
- **`from_buffer()`, `from_buffer_copy()` and `from_address()` on array
|
|
493
|
+
types**, as in Python: `array(c_uint8, n).from_address(addr)` is an
|
|
494
|
+
array on the memory at `addr`, and its `_buffer` a Buffer over it (the
|
|
495
|
+
equivalent of `memoryview((c_ubyte * n).from_address(addr))`).
|
|
496
|
+
|
|
497
|
+
### Removed
|
|
498
|
+
|
|
499
|
+
- **`ptrToBuffer()`** is no longer exported. Python ctypes has no
|
|
500
|
+
such function, and the same view is
|
|
501
|
+
`array(c_uint8, size).from_address(address)._buffer`. To read or write a
|
|
502
|
+
value at an address use `T.from_address(address)` or a `POINTER(T)`; to
|
|
503
|
+
copy bytes, `memmove(Buffer.alloc(n), address, n)`.
|
|
504
|
+
|
|
505
|
+
### Fixed
|
|
506
|
+
|
|
507
|
+
- **Electron**: `from_address`, `in_dll`, `pointer.contents`, `p[i]`,
|
|
508
|
+
`cast` and `memmove` / `memset` with addresses failed with "External
|
|
509
|
+
buffers are not allowed". Without external buffers, instances on native
|
|
510
|
+
memory now work on a copy: each read refreshes the bytes of the field and
|
|
511
|
+
each write copies them back, with one native call (about 50 ns);
|
|
512
|
+
instances on ordinary Buffers have no extra cost. Passed to C functions,
|
|
513
|
+
`addressof()`, `pointer()` and `memmove()` / `memset()` they use the
|
|
514
|
+
original address. On Node.js nothing changes.
|
|
515
|
+
- **`memmove()` / `memset()` with addresses** copy through the native module
|
|
516
|
+
instead of creating a Buffer over the memory.
|
|
517
|
+
|
|
518
|
+
### Performance
|
|
519
|
+
|
|
520
|
+
- **Writes through a pointer to an address** (`p[i] = v`,
|
|
521
|
+
`p.contents = v` for simple types) copy the value with the native module
|
|
522
|
+
instead of creating an external Buffer at each write: `p[i]` read + write
|
|
523
|
+
goes from ~715 ns to ~350 ns.
|
|
524
|
+
- **Nested structures and arrays** reuse their Proxy handler instead of
|
|
525
|
+
creating one at each field access.
|
|
526
|
+
|
|
527
|
+
## [2.1.1] - 2026-10-22
|
|
528
|
+
|
|
529
|
+
### Fixed
|
|
530
|
+
|
|
531
|
+
- **`callAsync()` with `use_errno` / `use_last_error`**: the call runs on a
|
|
532
|
+
worker thread and its `errno` / `GetLastError()` were not captured, so
|
|
533
|
+
`get_errno()` / `get_last_error()` returned a previous value. They are now
|
|
534
|
+
read on the worker thread right after the call and published before
|
|
535
|
+
`errcheck` runs, as for synchronous calls.
|
|
536
|
+
- **`errcheck` with `callAsync()`** received an empty `args` array; it now
|
|
537
|
+
receives the arguments of the call, as for synchronous calls.
|
|
538
|
+
|
|
539
|
+
### Changed
|
|
540
|
+
|
|
541
|
+
- **Embedded Python example requires Python 3.12+** (was 3.8+): it uses only
|
|
542
|
+
the stable C API of Python (`Py_CompileString` / `PyEval_EvalCode` instead
|
|
543
|
+
of `PyRun_String`, `PyErr_GetRaisedException` / `PyErr_SetRaisedException`
|
|
544
|
+
instead of the deprecated `PyErr_Fetch` triple), and older interpreters get
|
|
545
|
+
a clear error.
|
|
546
|
+
|
|
547
|
+
## [2.1.0] - 2026-10-22
|
|
548
|
+
|
|
549
|
+
### Added
|
|
550
|
+
|
|
551
|
+
- **`threadSafeCallback().ref()` / `.unref()`**: like a timer, a thread-safe
|
|
552
|
+
callback keeps the event loop alive until released; `.unref()` lets the
|
|
553
|
+
process exit when nothing else is pending, while calls from other threads
|
|
554
|
+
are still delivered. Both return the wrapper.
|
|
555
|
+
- **Embedded Python example** (`examples/cross-platform/python`): CPython
|
|
556
|
+
driven through its C API with node-ctypes, on Windows, macOS and Linux
|
|
557
|
+
(glibc and musl), Python 3.8+ including free-threaded builds, hosted by
|
|
558
|
+
the main thread or by a worker thread. It runs code and imports modules
|
|
559
|
+
and packages (local `.py` files and numpy too), converts values both ways
|
|
560
|
+
(dict keys as properties, `Tuple`, `Date` ↔ `datetime`, `Temporal` types
|
|
561
|
+
on Node.js 26+), uses JavaScript objects from Python by reference
|
|
562
|
+
(`JsProxy`, `byReference()`), shares memory between typed arrays and
|
|
563
|
+
Python buffers without copies, and implements `with` / `async with` and
|
|
564
|
+
time limits. asyncio is connected to the Node.js event loop with an
|
|
565
|
+
unreferenced `threadSafeCallback`: coroutines are awaitable from
|
|
566
|
+
JavaScript, coroutines and Python threads call JavaScript functions (also
|
|
567
|
+
while synchronous Python code waits for them, without deadlocks), and
|
|
568
|
+
async iterators and cancellation work in both directions. `stats()`
|
|
569
|
+
counts the objects shared by the two languages.
|
|
570
|
+
- **A README for every example**, published as child pages of the Examples
|
|
571
|
+
document in the API documentation.
|
|
572
|
+
|
|
573
|
+
### Changed
|
|
574
|
+
|
|
575
|
+
- **Examples are organized by platform and example**
|
|
576
|
+
(`examples/cross-platform/`, `examples/macos/`, `examples/windows/`), one
|
|
577
|
+
folder per example with its library, demos and README;
|
|
578
|
+
`examples/README.md` is an index. The COM demos are renamed
|
|
579
|
+
`windows/com/demo_com_shortcut.js` and
|
|
580
|
+
`windows/com/demo_com_active_directory.js`.
|
|
581
|
+
|
|
582
|
+
### Fixed
|
|
583
|
+
|
|
584
|
+
- **Smart card example on Linux**: `libpcsclite.so.1` is loaded by soname
|
|
585
|
+
(the library is in the multiarch directory), `SCardError` codes are
|
|
586
|
+
unsigned 32-bit numbers (`c_long` results are BigInt), and listing readers
|
|
587
|
+
returns `[]` when none is connected (`SCARD_E_NO_READERS_AVAILABLE`).
|
|
588
|
+
|
|
589
|
+
## [2.0.0] - 2026-10-21
|
|
590
|
+
|
|
591
|
+
2.0 aligns node-ctypes with Python ctypes as closely as the language allows,
|
|
592
|
+
so that Python code can be ported with only the changes JavaScript requires.
|
|
593
|
+
It contains breaking changes: see [Migrating from 1.x](README.md#migrating-from-1x).
|
|
594
|
+
|
|
595
|
+
### Breaking changes
|
|
596
|
+
|
|
597
|
+
- **`pointer.contents` returns a live instance** on the pointed memory, as in
|
|
598
|
+
Python: `p.contents.value` for simple types, `p.contents.x` for structures.
|
|
599
|
+
Assigning an instance re-points the pointer; assigning a plain value writes
|
|
600
|
+
it. `p[i]` still returns the value (a live instance for structures).
|
|
601
|
+
- **`POINTER(T)` restype returns a pointer object** (`null` for NULL) instead
|
|
602
|
+
of a `bigint` address; use `.address` for the number. A `CFUNCTYPE` restype
|
|
603
|
+
returns a callable function.
|
|
604
|
+
- **NULL `POINTER` fields of structures and unions read as `null`.**
|
|
605
|
+
- **`c_char` values are 1-character strings** (Python `bytes` of length 1)
|
|
606
|
+
instead of numbers; `c_wchar` values are 1-character strings.
|
|
607
|
+
`c_char * n` / `c_wchar * n` fields read and write as strings.
|
|
608
|
+
- **Invalid `c_char` / `c_wchar` values raise `TypeError`**
|
|
609
|
+
(`"one character bytes, bytearray or integer expected"`,
|
|
610
|
+
`"one character unicode string expected"`) instead of being truncated.
|
|
611
|
+
- **Argument conversion errors raise `ArgumentError`** (a `TypeError`
|
|
612
|
+
subclass) with the Python message `"argument N: TypeError: ..."`. Numeric
|
|
613
|
+
arguments accept numbers, booleans and BigInt (truncated to the type, as
|
|
614
|
+
Python masks integers) and reject strings, `null` and objects.
|
|
615
|
+
- **Values that are not pointers raise `ArgumentError` (`"wrong type"`)** for
|
|
616
|
+
pointer parameters instead of passing NULL (JS functions, plain objects,
|
|
617
|
+
symbols). Invalid values assigned to pointer fields raise `TypeError`
|
|
618
|
+
instead of writing 0.
|
|
619
|
+
- **Functions without `restype` return `c_int`**, and calls without
|
|
620
|
+
`argtypes` use the fixed-argument ABI with Python's default conversions
|
|
621
|
+
(e.g. a `c_int(5)` instance is passed by value).
|
|
622
|
+
- **`c_long` / `c_ulong` are `BigInt` on every platform**: fields and
|
|
623
|
+
`.value` on Windows (where `long` is 32-bit) were numbers, while function
|
|
624
|
+
results were already `BigInt`. This includes `wintypes.BOOL`, `LONG`,
|
|
625
|
+
`DWORD`, `ULONG`, `LSTATUS`, `COLORREF`. Writes accept numbers and BigInt.
|
|
626
|
+
- **`wintypes` follows Python's `ctypes.wintypes`**: `CHAR` is `c_char`
|
|
627
|
+
(was `c_ubyte`); `LPDWORD`, `PDWORD`, `LPBYTE`, `PBYTE`, `PHKEY` are
|
|
628
|
+
`POINTER(T)` (were `c_void_p`), so fields and results of these types are
|
|
629
|
+
pointer objects.
|
|
630
|
+
- **`string_at(addr, n)` / `wstring_at(addr, n)` read exactly `n` units**,
|
|
631
|
+
embedded NULs included, instead of stopping at the first NUL.
|
|
632
|
+
- **`create_string_buffer(init, size)` / `create_unicode_buffer(init, size)`**
|
|
633
|
+
honor `size` (`RangeError` if `init` does not fit) and return Buffers with
|
|
634
|
+
`.value` (and `.raw` for char buffers).
|
|
635
|
+
- **`array(type, n)` returns a callable type** (a function, as Python's
|
|
636
|
+
`type * n`) instead of a plain object.
|
|
637
|
+
- **Structure/union instances assigned to nested fields are copied
|
|
638
|
+
bytewise**, as in Python, instead of field by field.
|
|
639
|
+
- **TypeScript declarations** follow the new runtime types (see below).
|
|
640
|
+
|
|
641
|
+
### Added
|
|
642
|
+
|
|
643
|
+
- Prebuilt binaries for Linux with musl (Alpine), x64 and ARM64
|
|
644
|
+
(`ctypes-linux-<arch>-musl.node`), selected automatically.
|
|
645
|
+
- Python names: `ArgumentError`, `ARRAY`, `c_buffer`, `c_voidp`, `c_time_t`,
|
|
646
|
+
`SIZEOF_TIME_T`, `RTLD_GLOBAL`, `RTLD_LOCAL`, `DEFAULT_MODE`,
|
|
647
|
+
`LibraryLoader`, `cdll.LoadLibrary()` (and `windll` / `oledll`),
|
|
648
|
+
`get_last_error()` / `set_last_error()` (on every platform), `CType.CHAR`.
|
|
649
|
+
- `CDLL(name, mode)` and `CDLL(name, { mode })` with the `dlopen` flags.
|
|
650
|
+
- Array types are callable like Python's: `array(c_int, 3)(1, 2, 3)` (also
|
|
651
|
+
with `new`); arrays of arrays, of `POINTER(T)` and of `CFUNCTYPE` types;
|
|
652
|
+
`.value` / `.raw` on `c_char` arrays and `.value` on `c_wchar` arrays.
|
|
653
|
+
- `CFUNCTYPE` types as `argtypes`, `restype` and structure/union fields (read
|
|
654
|
+
back as callables); `sizeof` / `alignment` of `CFUNCTYPE` and `alignment` of
|
|
655
|
+
`POINTER` types.
|
|
656
|
+
- `POINTER(POINTER(T))` and `POINTER(CFUNCTYPE)` element access
|
|
657
|
+
(`pp[i].contents`, `pp[i] = pointer(x)`).
|
|
658
|
+
- `prototype([name, library])` and `prototype([name, library], paramflags)`,
|
|
659
|
+
as Python's `prototype((name, dll), paramflags)`; `paramflags` also accept
|
|
660
|
+
Python tuples `[flag, name, default]`.
|
|
661
|
+
- A structure instance as the single positional initializer
|
|
662
|
+
(`new RECT(point)`).
|
|
663
|
+
- `memmove` / `memset` accept addresses, ctypes instances and pointers, not
|
|
664
|
+
only Buffers.
|
|
665
|
+
- `c_void_p` parameters accept strings (passed as `char *`) and any
|
|
666
|
+
TypedArray, DataView or ArrayBuffer.
|
|
667
|
+
- Objects assigned to pointer / `CFUNCTYPE` fields and array elements are
|
|
668
|
+
kept alive with the structure, as Python's `_objects`.
|
|
669
|
+
- `POINTER(T)` arguments of callbacks are pointer objects; objects returned by
|
|
670
|
+
callbacks are converted like arguments.
|
|
671
|
+
- `readValue` / `writeValue` accept pointer objects.
|
|
672
|
+
- `wintypes` matches Python's `ctypes.wintypes` on all its names: structures
|
|
673
|
+
(`RECT`, `POINT`, `SIZE`, `MSG`, `FILETIME`, `SMALL_RECT`, `_COORD`,
|
|
674
|
+
`WIN32_FIND_DATAA/W`), pointer types (`LPRECT`, `PHANDLE`, `LPMSG`, ...),
|
|
675
|
+
`RGB()`, `MAX_PATH`, `VARIANT_BOOL` and the missing handle types.
|
|
676
|
+
- TypeScript: `wintypes` declarations; `static _fields_ = [["x", c_int]]`
|
|
677
|
+
compiles without `as const`; `_pack_` as a number; typed `contents`,
|
|
678
|
+
callable array types, buffer `.value` / `.raw`, pointer and function-pointer
|
|
679
|
+
results; `StructureOf`, `ArrayInstance`, `CharBufferValue`,
|
|
680
|
+
`WideBufferValue`, `MemoryTarget`.
|
|
681
|
+
- Type tests in `tests/types` (`npm run test:types`) and Python parity tests
|
|
682
|
+
(`tests/common/test_python_parity.js` with its Python twin).
|
|
683
|
+
|
|
684
|
+
### Fixed
|
|
685
|
+
|
|
686
|
+
- Segmentation fault when passing a JS function or a plain object to a
|
|
687
|
+
pointer parameter (e.g. a function to `qsort` instead of a callback).
|
|
688
|
+
- Segmentation fault when assigning a union instance with a pointer member
|
|
689
|
+
(e.g. `c_wchar_p`) to a structure field.
|
|
690
|
+
- Segmentation fault when passing pointers created with `fromAddress()` and
|
|
691
|
+
callback wrappers as arguments.
|
|
692
|
+
- `addressof()` of an array instance threw a "requires a Buffer" error.
|
|
693
|
+
- `wstring_at(addr)` truncated strings at 256 characters (512 on Windows), and
|
|
694
|
+
so did long `c_wchar_p` fields; `wstring_at(addr, n)` behaved differently on
|
|
695
|
+
Windows and Unix; invalid code points threw `RangeError` (now U+FFFD).
|
|
696
|
+
- `string_at(buffer)` could read past the end of the Buffer.
|
|
697
|
+
- `c_long` / `c_ulong` fields threw when assigned a BigInt on Windows, and so
|
|
698
|
+
did 32-bit bit fields.
|
|
699
|
+
- `wchar_t` alignment in arrays and structures (`alignof(wchar_t)`).
|
|
700
|
+
- The function cache could return a function declared with other types of the
|
|
701
|
+
same name (now keyed by type identity).
|
|
702
|
+
- `pointer(structInstance).contents` was not an instance of the structure
|
|
703
|
+
class; `.constructor` of structure instances returned a bound function.
|
|
704
|
+
- `restype = null` (Python's `None`) threw `Invalid return type`; it now
|
|
705
|
+
means `void`.
|
|
706
|
+
- The native module was looked up from `process.cwd()`: applications started
|
|
707
|
+
from another directory, and nested installs, failed with "Native module not
|
|
708
|
+
found". It is now located from the package itself (the previous locations
|
|
709
|
+
remain as a fallback).
|
|
710
|
+
- macOS prebuilt binaries required the macOS version of the CI runner
|
|
711
|
+
(26.0 on arm64, 15.0 on x64); they now target macOS 13.5, like Node 24.
|
|
712
|
+
|
|
713
|
+
### Performance
|
|
714
|
+
|
|
715
|
+
- Faster calls: per-function `call` without wrapper unwrapping, direct-call
|
|
716
|
+
invokers for common signatures and lighter argument marshalling. In
|
|
717
|
+
`tests/benchmarks/benchmark_koffi.js` the average gap with koffi dropped
|
|
718
|
+
from 2.56x to about 1.45x (Apple Silicon).
|
|
719
|
+
- Faster JS paths: `readValue` at an address, array element access,
|
|
720
|
+
`create_string_buffer`, structure instances sharing one Proxy handler.
|
|
721
|
+
|
|
722
|
+
### Changed
|
|
723
|
+
|
|
724
|
+
- Native code uses node-addon-api only; raw N-API is confined to
|
|
725
|
+
`src/napi_fast.h` and all system headers are included from `src/shared.h`.
|
|
726
|
+
- `typescript` is a devDependency; CI type-checks `lib/index.d.ts` in a
|
|
727
|
+
dedicated job and packaging depends on it.
|
|
728
|
+
- Linux binaries are built in `manylinux_2_28` containers: they require glibc
|
|
729
|
+
2.28 (like Node 24) and the system libstdc++, instead of glibc 2.34 and the
|
|
730
|
+
libstdc++ of GCC 13 (Ubuntu 22.04 and Debian 11/12 could not load them).
|
|
731
|
+
CI fails if a build raises these requirements.
|
|
732
|
+
- Examples rewritten in Python ctypes style (`wintypes` structures,
|
|
733
|
+
`DWORD()` / `HKEY()` with `byref` and `.value`, `in_dll`, `buf.value`,
|
|
734
|
+
typed prototypes instead of raw Buffers and offsets).
|
|
735
|
+
|
|
736
|
+
## [1.14.0] - 2026-10-21
|
|
737
|
+
|
|
738
|
+
### Changed
|
|
739
|
+
|
|
740
|
+
- libffi updated to 3.8.0 (through 3.7.0 and 3.7.1), with `ffi_call_plan`
|
|
741
|
+
support.
|
|
742
|
+
- Dependencies updated to their latest versions.
|
|
743
|
+
|
|
744
|
+
### Added
|
|
745
|
+
|
|
746
|
+
- Benchmark of node-ctypes against `node:ffi`.
|
|
747
|
+
|
|
748
|
+
## [1.13.0] - 2026-06-22
|
|
749
|
+
|
|
750
|
+
### Added
|
|
751
|
+
|
|
752
|
+
- `Symbol.dispose` support for callbacks and libraries (`using`).
|
|
753
|
+
|
|
754
|
+
### Changed
|
|
755
|
+
|
|
756
|
+
- `node:` prefix for built-in imports; koffi updated to 3.x in benchmarks.
|
|
757
|
+
|
|
758
|
+
## [1.12.0] - 2026-04-24
|
|
759
|
+
|
|
760
|
+
### Changed
|
|
761
|
+
|
|
762
|
+
- Library restructured for Python ctypes parity and maintainability.
|
|
763
|
+
|
|
764
|
+
### Performance
|
|
765
|
+
|
|
766
|
+
- No array allocations in the slow path of `func()` call wrappers; branch
|
|
767
|
+
hints on the FFI hot path.
|
|
768
|
+
|
|
769
|
+
## [1.11.1] - 2026-04-22
|
|
770
|
+
|
|
771
|
+
### Fixed
|
|
772
|
+
|
|
773
|
+
- LDAP example: binary attributes preserved when `ensureSchema` inherits the
|
|
774
|
+
caller options.
|
|
775
|
+
|
|
776
|
+
## [1.11.0] - 2026-04-22
|
|
777
|
+
|
|
778
|
+
### Changed
|
|
779
|
+
|
|
780
|
+
- `GetLastError` / `errno` API unified with Python ctypes semantics.
|
|
781
|
+
|
|
782
|
+
## [1.10.1] - 2026-04-22
|
|
783
|
+
|
|
784
|
+
### Performance
|
|
785
|
+
|
|
786
|
+
- Lower per-call overhead in the hot path.
|
|
787
|
+
|
|
788
|
+
### Fixed
|
|
789
|
+
|
|
790
|
+
- Documentation of the lazy library loaders.
|
|
791
|
+
|
|
792
|
+
## [1.10.0] - 2026-04-20
|
|
793
|
+
|
|
794
|
+
### Added
|
|
795
|
+
|
|
796
|
+
- Broader Python ctypes parity.
|
|
797
|
+
|
|
798
|
+
### Changed
|
|
799
|
+
|
|
800
|
+
- LTO/IPO enabled for Release builds.
|
|
801
|
+
|
|
802
|
+
## [1.9.0] - 2026-04-18
|
|
803
|
+
|
|
804
|
+
### Added
|
|
805
|
+
|
|
806
|
+
- Typed API and callback leak guard.
|
|
807
|
+
|
|
808
|
+
### Performance
|
|
809
|
+
|
|
810
|
+
- Faster structures.
|
|
811
|
+
|
|
812
|
+
### Fixed
|
|
813
|
+
|
|
814
|
+
- ESM import in tests on Windows (`pathToFileURL`).
|
|
815
|
+
|
|
816
|
+
## [1.8.0] - 2026-03-14
|
|
817
|
+
|
|
818
|
+
### Added
|
|
819
|
+
|
|
820
|
+
- `POINTER()` fields in unions; more tests and Python compatibility.
|
|
821
|
+
|
|
822
|
+
### Fixed
|
|
823
|
+
|
|
824
|
+
- Pointer size.
|
|
825
|
+
|
|
826
|
+
## [1.7.0] - 2026-03-11
|
|
827
|
+
|
|
828
|
+
### Added
|
|
829
|
+
|
|
830
|
+
- `PointerTypeDef` and `alignment()`; better pointer handling in structures
|
|
831
|
+
and unions.
|
|
832
|
+
|
|
833
|
+
## [1.6.0] - 2026-03-09
|
|
834
|
+
|
|
835
|
+
### Added
|
|
836
|
+
|
|
837
|
+
- Documentation and examples.
|
|
838
|
+
|
|
839
|
+
### Fixed
|
|
840
|
+
|
|
841
|
+
- SID interpretation (`objectsid`) in the LDAP example.
|
|
842
|
+
|
|
843
|
+
## [1.5.0] - 2026-02-20
|
|
844
|
+
|
|
845
|
+
### Added
|
|
846
|
+
|
|
847
|
+
- Function pointer type factories (`CFUNCTYPE` / `WINFUNCTYPE`), callbacks
|
|
848
|
+
with optional ABI.
|
|
849
|
+
- COM automation example (`IShellLinkW`, `IPersistFile`) and LDAP wrapper
|
|
850
|
+
example (`wldap32.dll`).
|
|
851
|
+
|
|
852
|
+
## [1.4.0] - 2026-02-10
|
|
853
|
+
|
|
854
|
+
### Added
|
|
855
|
+
|
|
856
|
+
- Asynchronous function calls; simpler variadic calls.
|
|
857
|
+
|
|
858
|
+
### Changed
|
|
859
|
+
|
|
860
|
+
- Better error messages.
|
|
861
|
+
|
|
862
|
+
## [1.3.0] - 2026-02-05
|
|
863
|
+
|
|
864
|
+
### Added
|
|
865
|
+
|
|
866
|
+
- Inline string buffers and pointer support; cross-platform C library
|
|
867
|
+
loading in tests.
|
|
868
|
+
|
|
869
|
+
## [1.2.0] - 2026-02-01
|
|
870
|
+
|
|
871
|
+
### Changed
|
|
872
|
+
|
|
873
|
+
- CType internals reworked; spdlog and dotenv removed.
|
|
874
|
+
|
|
875
|
+
## [1.1.0] - 2026-01-28
|
|
876
|
+
|
|
877
|
+
### Added
|
|
878
|
+
|
|
879
|
+
- PC/SC smart card example.
|
|
880
|
+
|
|
881
|
+
### Changed
|
|
882
|
+
|
|
883
|
+
- `long` / `ulong` alignment handling; values returned as BigInt.
|
|
884
|
+
|
|
885
|
+
## [1.0.2] - 2026-01-24
|
|
886
|
+
|
|
887
|
+
### Fixed
|
|
888
|
+
|
|
889
|
+
- `wchar` and pointer handling in primitive types.
|
|
890
|
+
|
|
891
|
+
## [1.0.1] - 2026-01-24
|
|
892
|
+
|
|
893
|
+
### Fixed
|
|
894
|
+
|
|
895
|
+
- Buffer handling in primitive type writers.
|
|
896
|
+
|
|
897
|
+
## [1.0.0] - 2026-01-24
|
|
898
|
+
|
|
899
|
+
### Changed
|
|
900
|
+
|
|
901
|
+
- Security and cross-platform improvements; JS files restructured.
|
|
902
|
+
|
|
903
|
+
## 0.1.x - 2026-01-17 to 2026-01-23
|
|
904
|
+
|
|
905
|
+
Initial releases.
|
|
906
|
+
|
|
907
|
+
[Unreleased]: https://github.com/dmazzella/node-ctypes/compare/v2.4.0...HEAD
|
|
908
|
+
[2.4.0]: https://github.com/dmazzella/node-ctypes/compare/v2.3.0...v2.4.0
|
|
909
|
+
[2.3.0]: https://github.com/dmazzella/node-ctypes/compare/v2.2.0...v2.3.0
|
|
910
|
+
[2.2.0]: https://github.com/dmazzella/node-ctypes/compare/v2.1.1...v2.2.0
|
|
911
|
+
[2.1.1]: https://github.com/dmazzella/node-ctypes/compare/v2.1.0...v2.1.1
|
|
912
|
+
[2.1.0]: https://github.com/dmazzella/node-ctypes/compare/v2.0.0...v2.1.0
|
|
913
|
+
[2.0.0]: https://github.com/dmazzella/node-ctypes/compare/v1.14.0...v2.0.0
|
|
914
|
+
[1.14.0]: https://github.com/dmazzella/node-ctypes/compare/v1.13.0...v1.14.0
|
|
915
|
+
[1.13.0]: https://github.com/dmazzella/node-ctypes/compare/v1.12.1...v1.13.0
|
|
916
|
+
[1.12.0]: https://github.com/dmazzella/node-ctypes/compare/v1.11.1...v1.12.1
|
|
917
|
+
[1.11.1]: https://github.com/dmazzella/node-ctypes/compare/v1.11.0...v1.11.1
|
|
918
|
+
[1.11.0]: https://github.com/dmazzella/node-ctypes/compare/v1.10.1...v1.11.0
|
|
919
|
+
[1.10.1]: https://github.com/dmazzella/node-ctypes/compare/v1.10.0...v1.10.1
|
|
920
|
+
[1.10.0]: https://github.com/dmazzella/node-ctypes/compare/v1.9.0...v1.10.0
|
|
921
|
+
[1.9.0]: https://github.com/dmazzella/node-ctypes/compare/v1.8.0...v1.9.0
|
|
922
|
+
[1.8.0]: https://github.com/dmazzella/node-ctypes/compare/v1.7.0...v1.8.0
|
|
923
|
+
[1.7.0]: https://github.com/dmazzella/node-ctypes/compare/v1.6.0...v1.7.0
|
|
924
|
+
[1.6.0]: https://github.com/dmazzella/node-ctypes/compare/v1.5.0...v1.6.0
|
|
925
|
+
[1.5.0]: https://github.com/dmazzella/node-ctypes/compare/v1.4.0...v1.5.0
|
|
926
|
+
[1.4.0]: https://github.com/dmazzella/node-ctypes/compare/v1.3.0...v1.4.0
|
|
927
|
+
[1.3.0]: https://github.com/dmazzella/node-ctypes/compare/v1.2.0...v1.3.0
|
|
928
|
+
[1.2.0]: https://github.com/dmazzella/node-ctypes/compare/v1.1.0...v1.2.0
|
|
929
|
+
[1.1.0]: https://github.com/dmazzella/node-ctypes/compare/v1.0.2...v1.1.0
|
|
930
|
+
[1.0.2]: https://github.com/dmazzella/node-ctypes/compare/dbbb592...v1.0.2
|
|
931
|
+
[1.0.1]: https://github.com/dmazzella/node-ctypes/compare/78acf28...dbbb592
|
|
932
|
+
[1.0.0]: https://github.com/dmazzella/node-ctypes/compare/v0.1.7...78acf28
|