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 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.5.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
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
@@ -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;
@@ -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 []>(fn: (...args: CallbackArgs<TArgs>) => CallbackResult<TRet>, returnType: TRet, argTypes?: TArgs): ThreadSafeCallbackWrapper;
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.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "node-ctypes",
3
- "version": "2.5.0",
3
+ "version": "2.6.0",
4
4
  "description": "Python ctypes-like FFI for Node.js using libffi",
5
5
  "author": "Damiano Mazzella",
6
6
  "license": "MIT",