node-ctypes 2.4.0 → 2.6.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 CHANGED
@@ -7,6 +7,120 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
7
7
 
8
8
  ## [Unreleased]
9
9
 
10
+ ## [2.6.0] - 2026-10-30
11
+
12
+ ### Added
13
+
14
+ - **Native callback contexts**: opt into `suspend`, `resume` and `onError`
15
+ hooks through the fourth `threadSafeCallback()` argument. Foreign callers
16
+ detach their native state before waiting and restore it on the original
17
+ thread before consuming an opaque error supplied with `setNativeError()`.
18
+ Error payloads are isolated per invocation, including concurrent and nested
19
+ calls.
20
+ - **Cooperative callback dispatch**: optional native `notify` hooks can wake
21
+ the consumer's host runtime; `drain()` processes a snapshot of pending calls
22
+ on the owning Node thread. Atomic claiming prevents duplicate execution
23
+ between drains and TSFN delivery, and late deliveries do not access completed
24
+ calls' native arguments. These primitives do not pump a blocked event loop
25
+ automatically.
26
+ - **Electron + React example**: a real native system clock and process-ID check
27
+ in `examples/cross-platform/electron-app`, with node-ctypes confined to the main process,
28
+ typed sandboxed IPC and no renderer Node polyfill. Native `malloc`/clock/view/
29
+ `free` reads exercise automatic synchronized mirrors when Electron disables
30
+ external buffers. Local dependency packaging keeps the addon outside ASAR;
31
+ real macOS ARM64 development and standalone packaged-app checks passed without
32
+ an Electron-specific addon rebuild.
33
+
34
+ ### Changed
35
+
36
+ - **Explicit native hook functions**: accept ctypes native function objects,
37
+ low-level function handles and raw BigInt addresses. Resolve hook addresses
38
+ once and retain supplied function objects through release and queued delivery
39
+ cleanup. Plain JavaScript functions and known JavaScript-backed callback
40
+ wrappers are rejected; native hooks bypass JavaScript converters and
41
+ `errcheck`. Explicit library closure remains the consumer's responsibility.
42
+ - **Callback lifecycle**: represent validated native contexts with C++20
43
+ `std::optional` and restore caller state through a noncopyable, nonmovable
44
+ RAII scope, including a saved state equal to `nullptr`. Reject explicit
45
+ release while a native-context invocation is active.
46
+ - **Public types and documentation**: expose the native-context options,
47
+ error-transfer and drain methods, and native address metadata on library
48
+ attribute functions. Document ownership, thread constraints and dispatch
49
+ flows, with regressions for concurrency, reentry, GC and null-state
50
+ restoration. Existing ABI-string options and callbacks without native
51
+ contexts retain their behavior; the new hooks require a matching rebuilt
52
+ addon, not only updated JavaScript wrappers.
53
+
54
+ ## [2.5.0] - 2026-10-26
55
+
56
+ ### Fixed
57
+
58
+ - **Portable CI validation**: large BigInt-to-float conversion no longer requires
59
+ the floating-point `from_chars` overload introduced in macOS 26, preserving
60
+ the macOS 13.5 deployment target and integer rounding/overflow checks. Paired
61
+ Linux lookup tests accept musl's `libm` alias to `libc` and verify the resolved
62
+ libraries by calling their correctly declared functions. Windows references
63
+ resolve the explicit `msvcrt` library and accept absolute DLL paths instead of
64
+ assuming CPython implements Node's `"c"` alias or returns bare file names.
65
+
66
+ ### Changed
67
+
68
+ - **Parity tests**: migrate the complete former `common/` and `windows/`
69
+ suites into domain-based `cpython_parity/` pairs, `node_specific/` regressions
70
+ and genuine `python_specific/` scheduling checks. Paired JS uses Python-shaped
71
+ classes, `ARRAY`, attribute bindings and `CFUNCTYPE`, with corresponding
72
+ class/method IDs, input matrices and actual C signatures. A structural AST
73
+ guard rejects one-sided files/cases, missing discovery markers and convenience
74
+ APIs in the canonical pairs without adding dependencies or replacing either
75
+ test runner. Python 3.15 CI now runs all references.
76
+ - **Pointer definitions**: expose Python's `_type_` metadata and defer incomplete
77
+ aggregate pointee layout until an actual memory access, so forward-bound
78
+ `_fields_` and self-referential types do not need manual cache invalidation.
79
+ - **Scalar and field conversion**: accept legitimate empty/whitespace field
80
+ names without corrupting constructor/prototype metadata, and convert full-width
81
+ BigInts to floating-point values with CPython rounding and overflow behavior
82
+ rather than an artificial 64-bit integer limit.
83
+ - **Function protocols**: `CFUNCTYPE` callbacks are callable, native functions
84
+ can be cast through the public API, and cached prototype conversion/retval
85
+ hooks are captured at type creation. Pointer-to-pointer values use the pointer
86
+ slot rather than the pointee bytes. Declared integer arguments reject nullish
87
+ values, and string-pointer arguments require strings, compatible C-data or an
88
+ explicit cast instead of an untyped integer address.
89
+ - **Raw memory and finalization**: explicitly sized `string_at` preserves all
90
+ bytes, including invalid UTF-8 and embedded NUL, as a Latin1 string; unsized
91
+ textual reads retain their UTF-8 representation. Address conversion errors
92
+ retain their causes through `ArgumentError`. Materialized aggregate layouts
93
+ reject `_fields_` reassignment, including previously incomplete types.
94
+ - **Typed pointer adapters**: match CPython's distinction between direct and
95
+ adapted arguments. Automatic by-reference conversion, array decay and NULL
96
+ acceptance no longer apply to scalar/array/null `_as_parameter_` results for
97
+ `POINTER(T)`; explicit compatible pointers and `byref` results remain accepted.
98
+ - **Parameter resolution**: terminal primitive `_as_parameter_` results avoid
99
+ allocating a cycle-detection Set. Recursive conversion follows CPython:
100
+ stateful getters may revisit an object before terminating, and the fixed
101
+ 128-step rejection is removed. Non-terminating recursion uses the host runtime
102
+ stack guard; intermediate owners stay alive and getter errors propagate unchanged.
103
+ - **Prototype callers**: eligible synchronous prototype bindings reuse the
104
+ fixed-arity JavaScript wrappers used by library functions. Calls needing
105
+ owners, custom adapters, result conversion or argument-count fallback keep
106
+ the general pipeline. Hook snapshots, original argument arrays, callable
107
+ metadata and prototype asynchronous behavior are preserved. External
108
+ comparisons include explicit already-bound `CFUNCTYPE` caller rows.
109
+ - **Callback conversion**: builtin-only signatures skip the generic argument
110
+ conversion dispatcher while preserving invocation and result conversion. Native
111
+ handlers construct fallback error messages only on failure, with unchanged
112
+ diagnostics and thread-safety checks.
113
+ - **Long UTF-8 arguments**: synchronous calls encode directly into reusable
114
+ scratch storage when it fits, keeping the ordinary encoder for growth.
115
+ String contents are still encoded on every call; the existing retention
116
+ bound, wide-string alignment and independent reentrant buffers are preserved.
117
+ - **Structure argument conversion**: plain-object arguments for functional
118
+ `struct()` definitions containing only builtin non-pointer scalar fields
119
+ skip the transient Proxy and use the same byte initializer as `create()`.
120
+ Field validation, zero defaults, dynamic `create()` / `set()` hooks and
121
+ argument lifetimes are preserved. Classes and complex definitions keep
122
+ their existing conversion paths.
123
+
10
124
  ## [2.4.0] - 2026-10-24
11
125
 
12
126
  ### Added
@@ -904,7 +1018,9 @@ It contains breaking changes: see [Migrating from 1.x](README.md#migrating-from-
904
1018
 
905
1019
  Initial releases.
906
1020
 
907
- [Unreleased]: https://github.com/dmazzella/node-ctypes/compare/v2.4.0...HEAD
1021
+ [Unreleased]: https://github.com/dmazzella/node-ctypes/compare/v2.6.0...HEAD
1022
+ [2.6.0]: https://github.com/dmazzella/node-ctypes/compare/v2.5.0...v2.6.0
1023
+ [2.5.0]: https://github.com/dmazzella/node-ctypes/compare/v2.4.0...v2.5.0
908
1024
  [2.4.0]: https://github.com/dmazzella/node-ctypes/compare/v2.3.0...v2.4.0
909
1025
  [2.3.0]: https://github.com/dmazzella/node-ctypes/compare/v2.2.0...v2.3.0
910
1026
  [2.2.0]: https://github.com/dmazzella/node-ctypes/compare/v2.1.1...v2.2.0
package/README.md CHANGED
@@ -236,6 +236,9 @@ that cannot be converted (a plain JS function, an object) raise
236
236
  Declared `POINTER(T)` parameters reject incompatible ctypes instances,
237
237
  arrays and pointer types before entering C. Compatible subclasses and arrays
238
238
  are accepted, and a matching scalar/structure is passed by reference.
239
+ These implicit scalar/array/NULL conversions apply to direct arguments only.
240
+ To adapt one of these values through `_as_parameter_`, return an explicit
241
+ compatible pointer or `byref` value instead, as in CPython.
239
242
  An explicit `cast()` changes the pointer type. Raw addresses and raw
240
243
  Buffer/TypedArray/ArrayBuffer memory remain node-ctypes extensions; use
241
244
  `c_void_p` for portable raw-address code.
@@ -326,6 +329,57 @@ const onEvent = threadSafeCallback((code) => console.log("event", code), null, [
326
329
  startWorker(onEvent); // a native library calling onEvent from its own thread
327
330
  ```
328
331
 
332
+ For an embedding runtime that must detach its native thread state before waiting,
333
+ the optional fourth argument can be `{ abi, nativeContext: { suspend, resume, onError, notify? } }`
334
+ instead of the existing ABI string. Each hook accepts a ctypes native function,
335
+ a low-level function handle, or a nonzero BigInt function address:
336
+
337
+ ```javascript
338
+ const onRequest = threadSafeCallback(handleRequest, c_int, [c_int], {
339
+ nativeContext: {
340
+ suspend: runtime.func("save_context", c_void_p, []),
341
+ resume: runtime.func("restore_context", null, [c_void_p]),
342
+ onError: runtime.func("install_error", null, [c_void_p]),
343
+ notify: runtime.func("wake_host", null, []),
344
+ },
345
+ });
346
+ ```
347
+
348
+ Function objects resolve through `_as_parameter_` or `address` once, when the
349
+ callback is constructed. The hooks are called directly using the default C ABI;
350
+ the function wrapper's JS converters and `errcheck` are not invoked:
351
+
352
+ - `void *suspend(void)` runs on a foreign caller before queueing.
353
+ - `void resume(void *)` restores that caller's saved state after dispatch, including
354
+ queue failure or environment shutdown. Neither hook runs on the Node host fast path.
355
+ - `void onError(void *)` consumes an opaque error pointer on the original caller
356
+ thread, after restoration. During the JS callback, use
357
+ `callback.setNativeError(pointer)` once and return the native API's required error
358
+ sentinel (`NULL`, `-1`, etc.). Error payloads belong to each invocation, including
359
+ concurrent and nested calls; JS exceptions are still reported as documented above.
360
+ - Optional `void notify(void)` runs on the foreign caller after successful queueing,
361
+ while its native state is detached. It may wake the host through the consumer's
362
+ runtime, but must not execute JavaScript itself.
363
+
364
+ `callback.drain()` executes a snapshot of pending calls **on the owning Node
365
+ thread**, returning the number it claimed. Each call executes at most once,
366
+ whether the TSFN or a drain gets there first. Delayed TSFN deliveries retain
367
+ only the shared request state and do not touch completed calls' native arguments.
368
+ The consumer must provide a safe way to reenter the host and call `drain()`;
369
+ calling it before entering a blocking native wait is not sufficient.
370
+
371
+ Hooks must not throw or execute JavaScript. Plain JS functions and known
372
+ JS-backed callback wrappers are rejected; an address cannot prove a function's
373
+ signature, validity or implementation. Supplied function objects are retained by
374
+ the native dispatcher through release and queued delivery cleanup. This does not
375
+ prevent explicitly closing their libraries or releasing their underlying resources;
376
+ raw addresses carry no owner. Keep the callback and the hook libraries
377
+ alive until all native calls have returned; explicit release is rejected while a
378
+ native-context call is active. These hooks do not acquire the host runtime context,
379
+ pump a blocked host event loop automatically, or implement interpreter ownership/subinterpreters.
380
+ The host JS handler must acquire/release its own runtime context around native API
381
+ operations. The ordinary callback path is unchanged when no hooks are supplied.
382
+
329
383
  Both callback implementations store narrow integer results in a complete
330
384
  libffi `ffi_arg`, with the declared signedness; failures zero that complete
331
385
  slot. Floating-point results retain their own storage width. The native
@@ -585,9 +639,12 @@ memory passed by value or as an integer address, including values materialized
585
639
  by getters.
586
640
 
587
641
  `_as_parameter_` chains are resolved recursively, including results of
588
- `from_param`, with intermediate owners retained. Cycles and chains exceeding
589
- 128 adapter steps raise explicit argument errors, rather than overflowing
590
- the stack or silently passing an incorrect pointer.
642
+ `from_param`, with intermediate owners retained. As in CPython, an adapter may
643
+ be visited again when a stateful getter eventually returns a usable value;
644
+ object identity alone is not rejected as a cycle, and there is no fixed
645
+ 128-step limit. Non-terminating recursion raises an argument conversion error.
646
+ The available recursion depth and stack-error wording follow the JavaScript
647
+ runtime, rather than CPython's runtime-specific recursion guard.
591
648
 
592
649
  This only covers the call: if C stores a pointer for later use, or returns a
593
650
  pointer into an argument's memory, keep the source object referenced for as
@@ -715,6 +772,11 @@ Plus the Win32 types, structures and pointer types of `ctypes.wintypes` under `w
715
772
  - `create_string_buffer(init, size?)` / `c_buffer` / `create_unicode_buffer(init, size?)` — with `.value` (and `.raw`)
716
773
  - `string_at(addr, size?)` / `wstring_at(addr, size?)` — exactly `size` units, or up to the NUL
717
774
 
775
+ With an explicit byte count, `string_at` returns a lossless Latin1 string:
776
+ `Buffer.from(string_at(addr, n), "latin1")` recovers all `n` original bytes,
777
+ including embedded NUL and invalid UTF-8. Without a count it retains the
778
+ UTF-8 text representation. `wstring_at` counts native wide-character units.
779
+
718
780
  ### Error slots
719
781
 
720
782
  - `get_errno()` / `set_errno(v)`
@@ -734,7 +796,7 @@ Plus the Win32 types, structures and pointer types of `ctypes.wintypes` under `w
734
796
 
735
797
  ## Python ctypes parity & differences
736
798
 
737
- ### What works identically
799
+ ### Supported Python ctypes behavior
738
800
 
739
801
  Structs, unions, bit fields (`_layout_` `"gcc-sysv"` / `"ms"`), anonymous
740
802
  fields, `_pack_`, `_align_`, subclasses of structures and unions, nested layouts,
@@ -831,8 +893,10 @@ needs these changes:
831
893
 
832
894
  Each example in `examples/` has its own README; see the [index](examples/README.md).
833
895
 
896
+ - [Electron + React](examples/cross-platform/electron-app/README.md) — a native system clock through a sandboxed preload bridge, synchronized C-memory views and a packaged ASAR application
834
897
  - [Embedded Python](examples/cross-platform/python/README.md) — CPython through its C API: code, modules, callbacks, JavaScript objects by reference, shared memory, threads, asyncio and cancellation (Windows, macOS, Linux)
835
898
  - [Smart card (PC/SC)](examples/cross-platform/smartcard/README.md) — `winscard` on Windows, `PCSC.framework` on macOS, `libpcsclite` on Linux
899
+ - [Cryptoki (PKCS #11)](examples/cross-platform/cryptoki/README.md) — complete 3.2 declarations with 2.20–3.2 dispatch and a standalone SoftHSM demo: temporary token, login, RSA, ECDSA, AES and SHA-256
836
900
  - [Accessibility](examples/macos/accessibility/README.md) — macOS UI automation with the Accessibility API
837
901
  - [COM automation](examples/windows/com/README.md) — shell shortcuts (`IShellLinkW`) and Active Directory (`IDirectorySearch`)
838
902
  - [Controls](examples/windows/controls/README.md) — Win32 common controls
@@ -846,8 +910,18 @@ Each example in `examples/` has its own README; see the [index](examples/README.
846
910
 
847
911
  From the repository root, `npm --prefix tests test` first builds a small C library (`tests/fixtures/`, into
848
912
  `build/fixture/`) used by the tests of structures by value, array parameters
849
- and reentrant calls; `npm run build:test-fixture` builds it alone. Python
850
- twins of the tests (`tests/common/*.py`) load the same library.
913
+ and reentrant calls; `npm run build:test-fixture` builds it alone. Matched
914
+ Python/JavaScript contracts live under `tests/cpython_parity/`, divided by domain,
915
+ and load the same library. Node-specific async, representation and GC checks
916
+ live under `tests/node_specific/`; genuine Python-only scheduling checks live
917
+ under `tests/python_specific/`. The former `common/` and `windows/` suites have
918
+ been migrated into these domains.
919
+
920
+ Paired JavaScript uses the Python-shaped API: `Structure`/`Union` classes,
921
+ `ARRAY`, library attributes with `argtypes`/`restype`, and `CFUNCTYPE` bindings.
922
+ The structural guard checks neighboring files and matching class/method IDs
923
+ using the existing TypeScript parser and Python AST; runtime assertions remain
924
+ independent checks against CPython, not a claim based on file names alone.
851
925
 
852
926
  ```bash
853
927
  npm install
@@ -855,13 +929,16 @@ npm run build
855
929
  npm --prefix tests install
856
930
  npm --prefix tests test # functional/parity tests
857
931
  NODE_CTYPES_NO_EXTERNAL_BUFFERS=1 npm --prefix tests test # mirrored native memory
932
+ npm --prefix tests run test:parity # matched CPython and JS contracts
933
+ npm --prefix tests run test:parity:check # paired file/case/discovery/style guard
934
+ npm --prefix tests run test:python # all Python references
858
935
  npm run test:types # TypeScript declarations
859
936
  npm run docs # TypeDoc API site in docs/
860
937
  npm run docs:serve # preview
861
938
  ```
862
939
 
863
- See [tests/common/](https://github.com/dmazzella/node-ctypes/tree/main/tests/common) for runnable examples alongside
864
- parallel Python ctypes implementations.
940
+ See the [test suite guide](tests/README.md) for paired-case conventions,
941
+ runtime differences and focused commands.
865
942
 
866
943
  ### Performance comparisons
867
944
 
@@ -916,7 +993,16 @@ variadic calls and async calls with 1/8 calls in flight. Cases without an
916
993
  equivalent documented node:ffi API are listed as **not compared**, not
917
994
  emulated with a different native signature.
918
995
 
996
+ The `CFUNCTYPE` rows measure calls through an already-bound node-ctypes
997
+ prototype, against an independently bound competitor function with the same
998
+ C signature. Bindings are separate to avoid sharing optimization feedback
999
+ with the direct-call rows. These cases do not include prototype construction
1000
+ or callback registration.
1001
+
919
1002
  Both sides call the same C fixture and verify results before/after timing.
1003
+ String contents are encoded on every call; node-ctypes reuses scratch storage,
1004
+ not previously encoded strings. Measurements describe warmed repeated calls,
1005
+ not cold-start allocation costs.
920
1006
  String lengths are compared as Numbers, including conversion where the API
921
1007
  returns BigInt; wide integers are BigInt in both APIs. Structures are plain
922
1008
  objects. Async times include scheduling and are reported per completed call,
Binary file
Binary file
@@ -40,7 +40,7 @@
40
40
  */
41
41
 
42
42
  import { _toNativeReturnType } from "./types.js";
43
- import { adaptCallbackFunction, argumentConverters, argumentsNeedOwners, callWithArgumentOwners, callWithResultHandler, convertArguments, needsArgumentOwners, resultCheck, resultConverter, scalarResult, structResult } from "./conversions.js";
43
+ import { adaptCallbackFunction, argumentConverters, argumentsNeedOwners, callWithArgumentOwners, callWithResultHandler, convertArguments, resultCheck, resultConverter, scalarResult, specializeCall, structResult } from "./conversions.js";
44
44
  import { createTypeKey } from "../utils/cache.js";
45
45
 
46
46
  /**
@@ -72,7 +72,10 @@ export function createLibraryClasses(Library, LRUCache, _toNativeType, _toNative
72
72
  class FunctionWrapper {
73
73
  constructor(cdll, name) {
74
74
  const argtypes = [];
75
+ let declaredArgtypes = [];
76
+ let converters = [];
75
77
  let restype = undefined;
78
+ let resultSignature;
76
79
  let errcheck = null;
77
80
  let cachedFunc = null;
78
81
 
@@ -82,7 +85,9 @@ export function createLibraryClasses(Library, LRUCache, _toNativeType, _toNative
82
85
  // argtypes / restype, come in Python.
83
86
  const resolve = () => {
84
87
  if (!cachedFunc) {
85
- cachedFunc = cdll._createFunction(name, restype === undefined ? cdll._defaultRestype() : restype, argtypes);
88
+ const returnType = restype === undefined ? cdll._defaultRestype() : restype;
89
+ const signature = resultSignature ?? { represent: resultConverter(returnType), check: cdll._resultCheck(returnType, name) };
90
+ cachedFunc = cdll._createFunction(name, returnType, declaredArgtypes, {}, { ...signature, converters });
86
91
  Object.defineProperty(cachedFunc, kErrcheckFunc, { value: func });
87
92
  if (errcheck !== null) {
88
93
  cachedFunc.errcheck = errcheck;
@@ -102,7 +107,11 @@ export function createLibraryClasses(Library, LRUCache, _toNativeType, _toNative
102
107
  get: () => argtypes,
103
108
  set: (value) => {
104
109
  // Python: argtypes = None toglie i tipi degli argomenti.
105
- argtypes.splice(0, argtypes.length, ...(value ?? []));
110
+ const types = [...(value ?? [])];
111
+ const next = argumentConverters(types, native);
112
+ argtypes.splice(0, argtypes.length, ...types);
113
+ declaredArgtypes = types;
114
+ converters = next;
106
115
  cachedFunc = null; // Invalidate cache
107
116
  },
108
117
  configurable: true,
@@ -110,6 +119,8 @@ export function createLibraryClasses(Library, LRUCache, _toNativeType, _toNative
110
119
  restype: {
111
120
  get: () => (restype === undefined ? cdll._defaultRestype() : restype),
112
121
  set: (value) => {
122
+ const returnType = value === undefined ? cdll._defaultRestype() : value;
123
+ resultSignature = { represent: resultConverter(returnType), check: cdll._resultCheck(returnType, name) };
113
124
  restype = value;
114
125
  cachedFunc = null; // Invalidate cache
115
126
  },
@@ -214,7 +225,7 @@ export function createLibraryClasses(Library, LRUCache, _toNativeType, _toNative
214
225
  * Crea una nuova funzione, senza cache (vedi func()).
215
226
  * @protected
216
227
  */
217
- _createFunction(name, returnType, argTypes = [], options = {}) {
228
+ _createFunction(name, returnType, argTypes = [], options = {}, signature) {
218
229
  // Propagate library-level use_last_error / use_errno to the FFIFunction
219
230
  const mergedOptions = {
220
231
  ...options,
@@ -223,26 +234,23 @@ export function createLibraryClasses(Library, LRUCache, _toNativeType, _toNative
223
234
  ...(structResult(returnType) ? { struct_buffer: true } : {}),
224
235
  ...(scalarResult(returnType) ? { scalar_buffer: true } : {}),
225
236
  };
226
- const ffiFunc = this._lib.func(name, _toNativeReturnType(returnType, native), _toNativeTypes(argTypes, native), mergedOptions);
237
+ const ffiFunc = this._lib.func(name, signature?.nativeRestype ?? _toNativeReturnType(returnType, native), signature?.nativeArgtypes ?? _toNativeTypes(argTypes, native), mergedOptions);
227
238
 
228
239
  // =========================================================================
229
240
  // OPTIMIZATION: Create specialized wrapper based on argument types
230
241
  // For primitive-only args, bypass the processing loop entirely
231
242
  // =========================================================================
232
243
 
233
- const argCount = argTypes.length;
234
-
235
244
  // Conversione degli argomenti come il from_param di base di Python
236
245
  // (vedi conversions.js): un convertitore per posizione dichiarata.
237
- const C = argumentConverters(argTypes, native);
238
- const [C0, C1, C2, C3, C4, C5] = C;
246
+ const C = signature?.converters ?? argumentConverters(argTypes, native);
239
247
  const convertAll = (args) => convertArguments(args, C);
240
248
  const hasAdapters = C.some((convert) => convert.requiresOwners);
241
- const baseConvert = resultConverter(returnType);
242
- const check = this._resultCheck(returnType, name);
249
+ const baseConvert = signature === undefined ? resultConverter(returnType) : signature.represent;
250
+ const check = signature === undefined ? this._resultCheck(returnType, name) : signature.check;
243
251
  const convertResult = check === undefined ? baseConvert : baseConvert === undefined ? check : (result) => check(baseConvert(result));
244
252
  const captureHere = convertResult === undefined;
245
- let jsErrcheck = null;
253
+ const callState = { errcheck: null };
246
254
  let checkedSync;
247
255
  const checkedCall = (method, args, checked) => {
248
256
  const originalArgs = Array.isArray(args) ? args : Array.prototype.slice.call(args);
@@ -252,71 +260,13 @@ export function createLibraryClasses(Library, LRUCache, _toNativeType, _toNative
252
260
  return callWithResultHandler(ffiFunc, method, originalArgs, C, finish, hasAdapters || argumentsNeedOwners(originalArgs), call);
253
261
  };
254
262
  const ownedCall = (method, args) => callWithArgumentOwners(ffiFunc, method, args, C);
255
- const invoke = (method, args) => {
256
- if (captureHere && jsErrcheck !== null) return checkedCall(method, args, jsErrcheck);
263
+ const invoke = (method, args, checked) => {
264
+ if (captureHere && checked !== null) return checkedCall(method, args, checked);
257
265
  return captureHere && (hasAdapters || argumentsNeedOwners(args)) ? ownedCall(method, args) : ffiFunc[method](...convertAll(args));
258
266
  };
259
267
 
260
- // Funzioni specializzate per numero di argomenti (niente array per la
261
- // chiamata comune); `method` è "call" o "callAsync".
262
- const specialize = (method) => {
263
- switch (argCount) {
264
- case 0:
265
- return function () {
266
- if (captureHere && jsErrcheck !== null) return checkedCall(method, arguments, jsErrcheck);
267
- return arguments.length === 0 ? ffiFunc[method]() : invoke(method, arguments);
268
- };
269
- case 1:
270
- return function (a0) {
271
- if (captureHere && jsErrcheck !== null) return checkedCall(method, arguments, jsErrcheck);
272
- if (arguments.length !== 1) return invoke(method, arguments);
273
- if (captureHere && (hasAdapters || needsArgumentOwners(a0))) return ownedCall(method, arguments);
274
- return ffiFunc[method](C0(a0));
275
- };
276
- case 2:
277
- return function (a0, a1) {
278
- if (captureHere && jsErrcheck !== null) return checkedCall(method, arguments, jsErrcheck);
279
- if (arguments.length !== 2) return invoke(method, arguments);
280
- if (captureHere && (hasAdapters || needsArgumentOwners(a0) || needsArgumentOwners(a1))) return ownedCall(method, arguments);
281
- return ffiFunc[method](C0(a0), C1(a1));
282
- };
283
- case 3:
284
- return function (a0, a1, a2) {
285
- if (captureHere && jsErrcheck !== null) return checkedCall(method, arguments, jsErrcheck);
286
- if (arguments.length !== 3) return invoke(method, arguments);
287
- if (captureHere && (hasAdapters || needsArgumentOwners(a0) || needsArgumentOwners(a1) || needsArgumentOwners(a2))) return ownedCall(method, arguments);
288
- return ffiFunc[method](C0(a0), C1(a1), C2(a2));
289
- };
290
- case 4:
291
- return function (a0, a1, a2, a3) {
292
- if (captureHere && jsErrcheck !== null) return checkedCall(method, arguments, jsErrcheck);
293
- if (arguments.length !== 4) return invoke(method, arguments);
294
- if (captureHere && (hasAdapters || needsArgumentOwners(a0) || needsArgumentOwners(a1) || needsArgumentOwners(a2) || needsArgumentOwners(a3))) return ownedCall(method, arguments);
295
- return ffiFunc[method](C0(a0), C1(a1), C2(a2), C3(a3));
296
- };
297
- case 5:
298
- return function (a0, a1, a2, a3, a4) {
299
- if (captureHere && jsErrcheck !== null) return checkedCall(method, arguments, jsErrcheck);
300
- if (arguments.length !== 5) return invoke(method, arguments);
301
- if (captureHere && (hasAdapters || needsArgumentOwners(a0) || needsArgumentOwners(a1) || needsArgumentOwners(a2) || needsArgumentOwners(a3) || needsArgumentOwners(a4))) return ownedCall(method, arguments);
302
- return ffiFunc[method](C0(a0), C1(a1), C2(a2), C3(a3), C4(a4));
303
- };
304
- case 6:
305
- return function (a0, a1, a2, a3, a4, a5) {
306
- if (captureHere && jsErrcheck !== null) return checkedCall(method, arguments, jsErrcheck);
307
- if (arguments.length !== 6) return invoke(method, arguments);
308
- if (captureHere && (hasAdapters || needsArgumentOwners(a0) || needsArgumentOwners(a1) || needsArgumentOwners(a2) || needsArgumentOwners(a3) || needsArgumentOwners(a4) || needsArgumentOwners(a5))) return ownedCall(method, arguments);
309
- return ffiFunc[method](C0(a0), C1(a1), C2(a2), C3(a3), C4(a4), C5(a5));
310
- };
311
- default:
312
- return function (...args) {
313
- return invoke(method, args);
314
- };
315
- }
316
- };
317
-
318
- let callMethod = specialize("call");
319
- let asyncCallMethod = specialize("callAsync");
268
+ let callMethod = specializeCall(ffiFunc, "call", C, callState, (args, checked) => invoke("call", args, checked), captureHere);
269
+ let asyncCallMethod = specializeCall(ffiFunc, "callAsync", C, callState, (args, checked) => invoke("callAsync", args, checked), captureHere);
320
270
 
321
271
  // Result handlers run inside the native call scope, after conversion and
322
272
  // with the hook/arguments captured before any argument adapter executes.
@@ -325,12 +275,12 @@ export function createLibraryClasses(Library, LRUCache, _toNativeType, _toNative
325
275
  const rawAsync = asyncCallMethod;
326
276
  const finish = (result) => convertResult(result);
327
277
  callMethod = function (...args) {
328
- if (jsErrcheck !== null) return checkedCall("call", args, jsErrcheck);
278
+ if (callState.errcheck !== null) return checkedCall("call", args, callState.errcheck);
329
279
  if (hasAdapters || argumentsNeedOwners(args)) return callWithArgumentOwners(ffiFunc, "call", args, C, finish);
330
280
  return finish(rawCall.apply(this, args), args);
331
281
  };
332
282
  asyncCallMethod = function (...args) {
333
- if (jsErrcheck !== null) return checkedCall("callAsync", args, jsErrcheck);
283
+ if (callState.errcheck !== null) return checkedCall("callAsync", args, callState.errcheck);
334
284
  if (hasAdapters || argumentsNeedOwners(args)) return callWithArgumentOwners(ffiFunc, "callAsync", args, C, finish);
335
285
  return rawAsync.apply(this, args).then((result) => finish(result, args));
336
286
  };
@@ -366,12 +316,12 @@ export function createLibraryClasses(Library, LRUCache, _toNativeType, _toNative
366
316
  // Esponi errcheck come setter/getter
367
317
  errcheck: {
368
318
  get() {
369
- return jsErrcheck;
319
+ return callState.errcheck;
370
320
  },
371
321
  set(callback) {
372
322
  callback = callback ?? null;
373
323
  if (callback !== null && typeof callback !== "function") throw new TypeError("errcheck must be a function or null");
374
- jsErrcheck = callback;
324
+ callState.errcheck = callback;
375
325
  },
376
326
  enumerable: false,
377
327
  configurable: true,
@@ -448,11 +398,17 @@ export function createLibraryClasses(Library, LRUCache, _toNativeType, _toNative
448
398
  * WinDLL - come CDLL ma con stdcall di default (per Windows)
449
399
  */
450
400
  class WinDLL extends CDLL {
451
- _createFunction(name, returnType, argTypes = [], options = {}) {
452
- return super._createFunction(name, returnType, argTypes, {
453
- abi: "stdcall",
454
- ...options,
455
- });
401
+ _createFunction(name, returnType, argTypes = [], options = {}, signature) {
402
+ return super._createFunction(
403
+ name,
404
+ returnType,
405
+ argTypes,
406
+ {
407
+ abi: "stdcall",
408
+ ...options,
409
+ },
410
+ signature,
411
+ );
456
412
  }
457
413
  }
458
414
 
@@ -57,6 +57,31 @@ import { _toNativeReturnType, _toNativeTypes } from "./types.js";
57
57
  import { adaptCallbackFunction, scalarResult } from "./conversions.js";
58
58
  import { trackCallback } from "./callback-tracker.js";
59
59
 
60
+ function nativeContextHook(value, name, owners) {
61
+ if (value !== null && (typeof value === "object" || typeof value === "function")) {
62
+ if ("_callback" in value) throw new TypeError(`nativeContext.${name} must not execute JavaScript`);
63
+ const parameter = value._as_parameter_;
64
+ const address = parameter === undefined ? value.address : parameter;
65
+ if (typeof address !== "bigint") throw new TypeError(`nativeContext.${name} must be a native function or BigInt address`);
66
+ owners.push(value);
67
+ return address;
68
+ }
69
+ if (typeof value !== "bigint") throw new TypeError(`nativeContext.${name} must be a native function or BigInt address`);
70
+ return value;
71
+ }
72
+
73
+ function nativeContextAddresses(context, owners) {
74
+ if (context === null || typeof context !== "object") throw new TypeError("nativeContext must contain suspend, resume and onError hooks");
75
+ const addresses = {
76
+ suspend: nativeContextHook(context.suspend, "suspend", owners),
77
+ resume: nativeContextHook(context.resume, "resume", owners),
78
+ onError: nativeContextHook(context.onError, "onError", owners),
79
+ };
80
+ const notify = context.notify;
81
+ if (notify !== undefined) addresses.notify = nativeContextHook(notify, "notify", owners);
82
+ return addresses;
83
+ }
84
+
60
85
  /**
61
86
  * Creates a C-callable callback from a JavaScript function (main-thread only).
62
87
  *
@@ -164,8 +189,8 @@ export function callback(fn, returnType, argTypes = [], native, abi = undefined)
164
189
  },
165
190
  _callback: cb,
166
191
  };
167
- // Python ctypes parity: il callback si passa direttamente come argomento,
168
- // es. qsort(arr, n, size, cmp). Non enumerabile per non cambiare Object.keys.
192
+ // Python ctypes parity: pass the callback directly as an argument,
193
+ // e.g. qsort(arr, n, size, cmp). Non-enumerable to preserve Object.keys.
169
194
  Object.defineProperty(wrapper, "_as_parameter_", {
170
195
  get() {
171
196
  return cb.pointer;
@@ -276,10 +301,26 @@ export function callback(fn, returnType, argTypes = [], native, abi = undefined)
276
301
  * @throws {Error} If callback creation fails or type conversion fails
277
302
  * @see {@link callback} for main-thread-only callbacks
278
303
  */
279
- export function threadSafeCallback(fn, returnType, argTypes = [], native, abi = undefined) {
280
- const args = [adaptCallbackFunction(fn, argTypes, returnType, native), _toNativeReturnType(returnType, native), _toNativeTypes(argTypes, native)];
304
+ export function threadSafeCallback(fn, returnType, argTypes = [], native, options = undefined) {
305
+ const { abi, nativeContext } = typeof options === "object" && options !== null ? options : { abi: options };
306
+ const owners = [];
307
+ const context = nativeContext === undefined ? undefined : nativeContextAddresses(nativeContext, owners);
308
+ const adapted = adaptCallbackFunction(fn, argTypes, returnType, native);
309
+ // Both the native callback and TSFN pin this function through queued delivery.
310
+ const dispatch =
311
+ owners.length === 0
312
+ ? adapted
313
+ : Object.defineProperty(
314
+ function (...args) {
315
+ return Reflect.apply(adapted, this, args);
316
+ },
317
+ "_objects",
318
+ { value: owners },
319
+ );
320
+ const args = [dispatch, _toNativeReturnType(returnType, native), _toNativeTypes(argTypes, native)];
281
321
  const scalarArgs = argTypes.map(scalarResult);
282
- if (scalarArgs.some(Boolean)) args.push(abi ?? "default", scalarArgs);
322
+ if (context !== undefined) args.push(abi ?? "default", scalarArgs, context);
323
+ else if (scalarArgs.some(Boolean)) args.push(abi ?? "default", scalarArgs);
283
324
  else if (abi) args.push(abi);
284
325
  const cb = new native.ThreadSafeCallback(...args);
285
326
 
@@ -298,13 +339,19 @@ export function threadSafeCallback(fn, returnType, argTypes = [], native, abi =
298
339
  cb.unref();
299
340
  return wrapper;
300
341
  },
342
+ setNativeError(error) {
343
+ cb.setNativeError(error);
344
+ },
345
+ drain() {
346
+ return cb.drain();
347
+ },
301
348
  [Symbol.dispose]() {
302
349
  cb.release();
303
350
  },
304
351
  _callback: cb,
305
352
  };
306
- // Python ctypes parity: il callback si passa direttamente come argomento,
307
- // es. qsort(arr, n, size, cmp). Non enumerabile per non cambiare Object.keys.
353
+ // Python ctypes parity: pass the callback directly as an argument,
354
+ // e.g. qsort(arr, n, size, cmp). Non-enumerable to preserve Object.keys.
308
355
  Object.defineProperty(wrapper, "_as_parameter_", {
309
356
  get() {
310
357
  return cb.pointer;