node-ctypes 2.5.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 +46 -1
- package/README.md +53 -0
- package/build/Release/ctypes-darwin-arm64.node +0 -0
- package/build/Release/ctypes-darwin-x64.node +0 -0
- package/build/Release/ctypes-linux-arm64-musl.node +0 -0
- package/build/Release/ctypes-linux-arm64.node +0 -0
- package/build/Release/ctypes-linux-x64-musl.node +0 -0
- package/build/Release/ctypes-linux-x64.node +0 -0
- package/build/Release/ctypes-win32-arm64.node +0 -0
- package/build/Release/ctypes-win32-x64.node +0 -0
- package/lib/core/callback.js +54 -7
- package/lib/core/conversions.js +0 -1
- package/lib/index.d.ts +57 -1
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -7,6 +7,50 @@ 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
|
+
|
|
10
54
|
## [2.5.0] - 2026-10-26
|
|
11
55
|
|
|
12
56
|
### Fixed
|
|
@@ -974,7 +1018,8 @@ It contains breaking changes: see [Migrating from 1.x](README.md#migrating-from-
|
|
|
974
1018
|
|
|
975
1019
|
Initial releases.
|
|
976
1020
|
|
|
977
|
-
[Unreleased]: https://github.com/dmazzella/node-ctypes/compare/v2.
|
|
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
|
|
978
1023
|
[2.5.0]: https://github.com/dmazzella/node-ctypes/compare/v2.4.0...v2.5.0
|
|
979
1024
|
[2.4.0]: https://github.com/dmazzella/node-ctypes/compare/v2.3.0...v2.4.0
|
|
980
1025
|
[2.3.0]: https://github.com/dmazzella/node-ctypes/compare/v2.2.0...v2.3.0
|
package/README.md
CHANGED
|
@@ -329,6 +329,57 @@ const onEvent = threadSafeCallback((code) => console.log("event", code), null, [
|
|
|
329
329
|
startWorker(onEvent); // a native library calling onEvent from its own thread
|
|
330
330
|
```
|
|
331
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
|
+
|
|
332
383
|
Both callback implementations store narrow integer results in a complete
|
|
333
384
|
libffi `ffi_arg`, with the declared signedness; failures zero that complete
|
|
334
385
|
slot. Floating-point results retain their own storage width. The native
|
|
@@ -842,8 +893,10 @@ needs these changes:
|
|
|
842
893
|
|
|
843
894
|
Each example in `examples/` has its own README; see the [index](examples/README.md).
|
|
844
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
|
|
845
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)
|
|
846
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
|
|
847
900
|
- [Accessibility](examples/macos/accessibility/README.md) — macOS UI automation with the Accessibility API
|
|
848
901
|
- [COM automation](examples/windows/com/README.md) — shell shortcuts (`IShellLinkW`) and Active Directory (`IDirectorySearch`)
|
|
849
902
|
- [Controls](examples/windows/controls/README.md) — Win32 common controls
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
package/lib/core/callback.js
CHANGED
|
@@ -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:
|
|
168
|
-
//
|
|
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,
|
|
280
|
-
const
|
|
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 (
|
|
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:
|
|
307
|
-
//
|
|
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;
|
package/lib/core/conversions.js
CHANGED
|
@@ -403,7 +403,6 @@ function fromParamArgument(T, base, index, fromParam) {
|
|
|
403
403
|
try {
|
|
404
404
|
converted = Reflect.apply(fromParam, T, [a]);
|
|
405
405
|
} catch (e) {
|
|
406
|
-
if (e instanceof ArgumentError) throw e;
|
|
407
406
|
throw new ArgumentError(`argument ${index + 1}: ${e?.name ?? "Error"}: ${e?.message ?? String(e)}`, { cause: e });
|
|
408
407
|
}
|
|
409
408
|
retainArgument(owners, converted);
|
package/lib/index.d.ts
CHANGED
|
@@ -464,6 +464,10 @@ export interface FunctionWrapper {
|
|
|
464
464
|
/** Call the function. */
|
|
465
465
|
(...args: any[]): any;
|
|
466
466
|
|
|
467
|
+
/** Resolve the native function address. */
|
|
468
|
+
readonly address: bigint;
|
|
469
|
+
readonly _as_parameter_: bigint;
|
|
470
|
+
|
|
467
471
|
/** Call the function asynchronously on a worker thread. */
|
|
468
472
|
callAsync(...args: any[]): Promise<any>;
|
|
469
473
|
|
|
@@ -636,6 +640,49 @@ export interface ThreadSafeCallbackWrapper extends CallbackWrapper {
|
|
|
636
640
|
* callback exists. Calls from other threads are delivered while it runs.
|
|
637
641
|
*/
|
|
638
642
|
unref(): this;
|
|
643
|
+
/**
|
|
644
|
+
* Transfer a nonzero opaque error pointer to nativeContext.onError on the
|
|
645
|
+
* original caller thread, after resume. Only during this callback; once per
|
|
646
|
+
* invocation. The callback must also return its ABI's error sentinel.
|
|
647
|
+
* Ownership transfers to onError, which must consume the pointer.
|
|
648
|
+
*/
|
|
649
|
+
setNativeError(error: bigint): void;
|
|
650
|
+
/** Execute a snapshot of queued calls on the owning Node thread; return the number claimed. */
|
|
651
|
+
drain(): number;
|
|
652
|
+
}
|
|
653
|
+
|
|
654
|
+
/**
|
|
655
|
+
* A raw function address, ctypes callable or low-level native function handle.
|
|
656
|
+
* JavaScript-backed callbacks are not valid hooks. Object targets are retained
|
|
657
|
+
* by the native dispatcher until release and queued delivery cleanup.
|
|
658
|
+
* @category Callbacks
|
|
659
|
+
*/
|
|
660
|
+
export type NativeCallbackHook = bigint | (({ readonly _as_parameter_: bigint } | { readonly address: bigint }) & { readonly _callback?: never });
|
|
661
|
+
|
|
662
|
+
/**
|
|
663
|
+
* Opt-in native runtime hooks. Addresses are resolved once at construction.
|
|
664
|
+
* Keep the callback and hook libraries alive until every invocation returns;
|
|
665
|
+
* retaining a function does not prevent explicit close()/release().
|
|
666
|
+
* Hooks use the default C ABI directly, bypassing JS argument conversion and
|
|
667
|
+
* errcheck. They must not throw or execute JavaScript and do not provide
|
|
668
|
+
* subinterpreter support.
|
|
669
|
+
* @category Callbacks
|
|
670
|
+
*/
|
|
671
|
+
export interface NativeCallbackContext {
|
|
672
|
+
/** `void *suspend(void)`: detach caller state before a foreign thread waits. */
|
|
673
|
+
suspend: NativeCallbackHook;
|
|
674
|
+
/** `void resume(void *)`: restore that state on the same thread, even on dispatch failure. */
|
|
675
|
+
resume: NativeCallbackHook;
|
|
676
|
+
/** `void onError(void *)`: consume setNativeError's pointer on the original thread. */
|
|
677
|
+
onError: NativeCallbackHook;
|
|
678
|
+
/** `void notify(void)`: after queueing on a foreign thread, while suspended; may wake the host, never run JS. */
|
|
679
|
+
notify?: NativeCallbackHook;
|
|
680
|
+
}
|
|
681
|
+
|
|
682
|
+
/** @category Callbacks */
|
|
683
|
+
export interface ThreadSafeCallbackOptions {
|
|
684
|
+
abi?: FunctionOptions["abi"];
|
|
685
|
+
nativeContext?: NativeCallbackContext;
|
|
639
686
|
}
|
|
640
687
|
|
|
641
688
|
/**
|
|
@@ -677,6 +724,10 @@ export class ThreadSafeCallback extends Callback {
|
|
|
677
724
|
ref(): this;
|
|
678
725
|
/** Do not keep the Node.js event loop alive. */
|
|
679
726
|
unref(): this;
|
|
727
|
+
/** See {@link ThreadSafeCallbackWrapper.setNativeError}. */
|
|
728
|
+
setNativeError(error: bigint): void;
|
|
729
|
+
/** See {@link ThreadSafeCallbackWrapper.drain}. */
|
|
730
|
+
drain(): number;
|
|
680
731
|
}
|
|
681
732
|
|
|
682
733
|
// =============================================================================
|
|
@@ -1593,7 +1644,12 @@ export function callback<TRet extends CallbackRestype, const TArgs extends reado
|
|
|
1593
1644
|
*
|
|
1594
1645
|
* @category Callbacks
|
|
1595
1646
|
*/
|
|
1596
|
-
export function threadSafeCallback<TRet extends CallbackRestype, const TArgs extends readonly FFIType[] = readonly []>(
|
|
1647
|
+
export function threadSafeCallback<TRet extends CallbackRestype, const TArgs extends readonly FFIType[] = readonly []>(
|
|
1648
|
+
fn: (...args: CallbackArgs<TArgs>) => CallbackResult<TRet>,
|
|
1649
|
+
returnType: TRet,
|
|
1650
|
+
argTypes?: TArgs,
|
|
1651
|
+
options?: FunctionOptions["abi"] | ThreadSafeCallbackOptions,
|
|
1652
|
+
): ThreadSafeCallbackWrapper;
|
|
1597
1653
|
|
|
1598
1654
|
/**
|
|
1599
1655
|
* Create a function pointer type with cdecl calling convention.
|