node-ctypes 2.3.0 → 2.5.0

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