node-ctypes 2.7.0 → 2.8.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,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
7
7
 
8
8
  ## [Unreleased]
9
9
 
10
+ ## [2.8.0] - 2026-11-04
11
+
12
+ ### Fixed
13
+
14
+ - **Scalar argument marshalling**: read genuine non-pointer CData arguments from
15
+ their backing bytes instead of overridden `.value` getters. Snapshot each
16
+ scalar before converting later arguments, including calls without `argtypes`,
17
+ matching CPython's conversion order.
18
+ - **Scalar adapters**: accept `from_param` results whose native scalar kind
19
+ matches the declared type, even when the CData instance belongs to a different
20
+ JavaScript class.
21
+ - **Examples navigation**: use explicit Electron and Cryptoki page titles
22
+ instead of duplicate `README` labels in the generated documentation.
23
+
24
+ ### Performance
25
+
26
+ - **Cached library symbols**: reuse attribute-function wrappers with a single
27
+ cache lookup instead of separate `Map.has()` and `Map.get()` calls, preserving
28
+ wrapper identity, signature changes and lazy symbol resolution.
29
+
10
30
  ## [2.7.0] - 2026-11-03
11
31
 
12
32
  ### Changed
@@ -1051,7 +1071,8 @@ It contains breaking changes: see [Migrating from 1.x](README.md#migrating-from-
1051
1071
 
1052
1072
  Initial releases.
1053
1073
 
1054
- [Unreleased]: https://github.com/dmazzella/node-ctypes/compare/v2.7.0...HEAD
1074
+ [Unreleased]: https://github.com/dmazzella/node-ctypes/compare/v2.8.0...HEAD
1075
+ [2.8.0]: https://github.com/dmazzella/node-ctypes/compare/v2.7.0...v2.8.0
1055
1076
  [2.7.0]: https://github.com/dmazzella/node-ctypes/compare/v2.6.0...v2.7.0
1056
1077
  [2.6.0]: https://github.com/dmazzella/node-ctypes/compare/v2.5.0...v2.6.0
1057
1078
  [2.5.0]: https://github.com/dmazzella/node-ctypes/compare/v2.4.0...v2.5.0
package/README.md CHANGED
@@ -631,6 +631,12 @@ As in Python, `from_param` receives the argument as passed (also with
631
631
  `CFUNCTYPE` prototypes), its result is converted as the declared type, and
632
632
  an error it throws becomes `ArgumentError` (`"argument 1: RangeError: ..."`).
633
633
 
634
+ Non-pointer scalar CData arguments are read from their backing bytes, not an
635
+ overridden public `.value` getter. Each value is snapshotted before converting
636
+ the next argument, even without `argtypes`. A scalar `from_param` converter may
637
+ return a CData instance of another class when its native scalar kind matches
638
+ the declared type.
639
+
634
640
  Objects passed through argument adapters and the objects produced by their
635
641
  conversions stay alive while later arguments are converted and until the
636
642
  result and `errcheck` have been processed. With `callAsync()`, those temporary
Binary file
Binary file
@@ -179,8 +179,9 @@ export function createLibraryClasses(Library, LRUCache, _toNativeType, _toNative
179
179
  return Reflect.get(target, prop, receiver);
180
180
  }
181
181
  // Check if we already have a FunctionWrapper for this function name
182
- if (target._funcWrapperCache.has(prop)) {
183
- return target._funcWrapperCache.get(prop);
182
+ const cached = target._funcWrapperCache.get(prop);
183
+ if (cached !== undefined) {
184
+ return cached;
184
185
  }
185
186
  // Create and cache a new FunctionWrapper
186
187
  const wrapper = new FunctionWrapper(target, prop);
@@ -10,12 +10,24 @@ import { mirrorAddress, mirrorsActive, refresh } from "../memory/mirror.js";
10
10
  import { ArgumentError } from "../platform/errors.js";
11
11
  import { encodeWide } from "../memory/buffer.js";
12
12
  import { buildWrapper } from "../structures/helpers/wrap.js";
13
- import { activeArgumentOwners as argumentOwnerRegistry, activeOwnerStack, byrefOwners, isScalarSubclass, resolveParameter, scalarView, structArgumentFactories, structResultReaders } from "../structures/helpers/common.js";
13
+ import {
14
+ activeArgumentOwners as argumentOwnerRegistry,
15
+ activeOwnerStack,
16
+ byrefOwners,
17
+ isScalarSubclass,
18
+ resolveParameter,
19
+ scalarArgumentKind,
20
+ scalarArgumentSnapshot,
21
+ scalarArgumentValue,
22
+ scalarInstanceInfo,
23
+ scalarView,
24
+ structArgumentFactories,
25
+ structResultReaders,
26
+ } from "../structures/helpers/common.js";
14
27
 
15
28
  const activeArgumentOwners = argumentOwnerRegistry;
16
29
  // Captured at load so callback dispatch is not affected by later patches.
17
30
  const reflectApply = Reflect.apply;
18
-
19
31
  function retainArgument(owners, value) {
20
32
  if (owners !== undefined && value !== null && (typeof value === "object" || typeof value === "function")) owners.push(value);
21
33
  }
@@ -247,13 +259,18 @@ export function coerceValue(a, owners) {
247
259
 
248
260
  /**
249
261
  * Conversion of an argument beyond `argtypes` (variadic, or without
250
- * argtypes): a SimpleCData instance is passed as is, and the native call uses
251
- * its type, as Python does (`printf("%f", c_double(2.0))`).
262
+ * argtypes): a numeric SimpleCData instance keeps its type and snapshots its
263
+ * value before the next conversion (`printf("%f", c_double(2.0))`).
252
264
  */
253
265
  export function coerceVariadic(a, owners) {
266
+ const info = scalarInstanceInfo(a);
267
+ if (info !== undefined) {
268
+ retainArgument(owners, a);
269
+ return scalarArgumentSnapshot(a, info);
270
+ }
254
271
  a = resolveParameter(a, owners);
255
272
  retainArgument(owners, a);
256
- if (a !== null && typeof a === "object" && a._isSimpleCDataInstance === true) return a;
273
+ if (a !== null && typeof a === "object" && a._isSimpleCDataInstance === true) return scalarArgumentSnapshot(a);
257
274
  return coerceObject(a, owners);
258
275
  }
259
276
 
@@ -276,15 +293,16 @@ export function argumentConverters(argTypes, native) {
276
293
  if (kind === native.CType.STRING || kind === native.CType.WSTRING) return stringArgument(t, kind, index, native);
277
294
  if (kind === native.CType.POINTER) return voidPointerArgument(index, native);
278
295
  if (typeof t !== "function" || t._isSimpleCData !== true) return coerceObject;
279
- return scalarArgument(t, index);
296
+ return scalarArgument(t, kind, index);
280
297
  };
281
- return argTypes.map((t, index) => {
298
+ const converters = argTypes.map((t, index) => {
282
299
  const base = baseConverter(t, index);
283
300
  if (t === null || (typeof t !== "function" && typeof t !== "object")) return base;
284
301
  const fromParam = t.from_param;
285
302
  if (fromParam === undefined) return base;
286
303
  return fromParamArgument(t, base.fromParam ?? base, index, fromParam);
287
304
  });
305
+ return converters;
288
306
  }
289
307
 
290
308
  function pointerValue(value, native) {
@@ -346,20 +364,36 @@ function stringArgument(T, kind, index, native) {
346
364
  return convert;
347
365
  }
348
366
 
349
- function scalarArgument(T, index) {
367
+ function scalarArgument(T, kind, index) {
350
368
  const boolean = T._isBoolean === true;
351
- return (value, owners) => {
352
- if (value !== null && (typeof value === "object" || typeof value === "function")) value = resolveArgument(value, owners, index);
369
+ const stored = (value, info, owners, adapted) => {
370
+ retainArgument(owners, value);
371
+ if (!boolean && info.type !== T && !(value instanceof T) && !(adapted && info.kind === kind)) {
372
+ throw new ArgumentError(`argument ${index + 1}: TypeError: incompatible types, ${info.type.name} instance instead of ${T.name} instance`);
373
+ }
374
+ return scalarArgumentValue(value, info);
375
+ };
376
+ const make = (adapted) => (value, owners) => {
377
+ if (value !== null && (typeof value === "object" || typeof value === "function")) {
378
+ const info = scalarInstanceInfo(value);
379
+ if (info !== undefined) return stored(value, info, owners, adapted);
380
+ value = resolveArgument(value, owners, index);
381
+ }
353
382
  if (value === null || typeof value !== "object") return value;
383
+ const info = scalarInstanceInfo(value);
384
+ if (info !== undefined) return stored(value, info, owners, adapted);
354
385
  retainArgument(owners, value);
355
386
  if (value._isSimpleCDataInstance === true) {
356
- if (!boolean && !(value instanceof T)) {
387
+ if (!boolean && !(value instanceof T) && !(adapted && scalarArgumentKind(value) === kind)) {
357
388
  throw new ArgumentError(`argument ${index + 1}: TypeError: incompatible types, ${value.constructor.name} instance instead of ${T.name} instance`);
358
389
  }
359
- return value.value;
390
+ return scalarArgumentValue(value);
360
391
  }
361
392
  return objectMemory(value, owners);
362
393
  };
394
+ const convert = make(false);
395
+ Object.defineProperty(convert, "fromParam", { value: make(true) });
396
+ return convert;
363
397
  }
364
398
 
365
399
  function resolveArgument(value, owners, index) {
package/lib/index.d.ts CHANGED
@@ -134,7 +134,7 @@ export type FFIType = AnyType | StructureClass | PointerTypeDef | ArrayTypeDef |
134
134
  * @example
135
135
  * ```javascript
136
136
  * import { Version } from 'node-ctypes';
137
- * console.log(Version.toString()); // "2.5.0"
137
+ * console.log(Version.toString()); // "2.8.0"
138
138
  * ```
139
139
  *
140
140
  * @category Library Loading
@@ -2,6 +2,12 @@ import { flush, kMirrorBase, mirrorBase, mirroredPrototype, mirrorsActive, refre
2
2
  import { POINTER_SIZE } from "../../platform/constants.js";
3
3
 
4
4
  const simpleTypes = new WeakSet();
5
+ const scalarInstances = new WeakMap();
6
+ const scalarTypeInfos = new WeakMap();
7
+ const scalarAccessors = [];
8
+ const scalarArgumentKinds = new Set();
9
+ const scalarArgumentTypes = new Map();
10
+ const applyScalarReader = Reflect.apply;
5
11
  export const activeArgumentOwners = new Set();
6
12
  // GC roots of in-progress synchronous conversions, released in LIFO order.
7
13
  export const activeOwnerStack = [];
@@ -48,6 +54,63 @@ export function sourceBytes(source, offset, size, name) {
48
54
 
49
55
  export function registerSimpleType(type) {
50
56
  simpleTypes.add(type);
57
+ scalarArgumentKinds.add(type._type);
58
+ }
59
+
60
+ export function scalarTypeInfo(type, swapped = false) {
61
+ let variants = scalarTypeInfos.get(type);
62
+ if (variants === undefined) {
63
+ const kind = type._type;
64
+ variants = [{ type, kind, swapped: false, pointer: type._isPointerValued === true }];
65
+ scalarTypeInfos.set(type, variants);
66
+ }
67
+ const index = swapped ? 1 : 0;
68
+ if (variants[index] === undefined) variants[index] = { ...variants[0], swapped: true };
69
+ return variants[index];
70
+ }
71
+
72
+ export function registerScalarAccessor(accessor) {
73
+ scalarAccessors.push(accessor);
74
+ }
75
+
76
+ export function registerScalarInstance(value, type, swapped = false) {
77
+ scalarInstances.set(value, scalarTypeInfo(type, swapped));
78
+ }
79
+
80
+ export function scalarInstanceInfo(value) {
81
+ if (value === null || (typeof value !== "object" && typeof value !== "function")) return undefined;
82
+ for (const accessor of scalarAccessors) {
83
+ const info = accessor(value);
84
+ if (info !== undefined) return info;
85
+ }
86
+ return scalarInstances.get(value);
87
+ }
88
+
89
+ export function scalarArgumentKind(value) {
90
+ return scalarInstanceInfo(value)?.kind;
91
+ }
92
+
93
+ export function scalarArgumentValue(value, info = scalarInstanceInfo(value)) {
94
+ if (info === undefined) return value.value;
95
+ const buffer = value._buffer;
96
+ if (mirrorsActive) refresh(buffer);
97
+ const reader = info.swapped ? info.type._readerBE : info.type._reader;
98
+ return applyScalarReader(reader, info.type, [buffer, 0]);
99
+ }
100
+
101
+ export function scalarArgumentSnapshot(value, info = scalarInstanceInfo(value)) {
102
+ if (info === undefined || info.pointer || info.kind === 0 || !scalarArgumentKinds.has(info.kind)) return value;
103
+ let constructor = scalarArgumentTypes.get(info.kind);
104
+ if (constructor === undefined) {
105
+ constructor = function ScalarArgument() {};
106
+ Object.defineProperties(constructor, {
107
+ _isSimpleCData: { value: true },
108
+ _type: { value: info.kind },
109
+ });
110
+ scalarArgumentTypes.set(info.kind, constructor);
111
+ }
112
+ // Keep the inferred type, but snapshot the value before the next adapter.
113
+ return { constructor, value: scalarArgumentValue(value, info) };
51
114
  }
52
115
 
53
116
  export function isScalarSubclass(type) {
@@ -60,7 +123,9 @@ export function scalarView(type, buffer, swapped = false) {
60
123
  const value = Object.create(base === undefined ? type.prototype : mirroredPrototype(type));
61
124
  value._buffer = buffer;
62
125
  if (base !== undefined) value[kMirrorBase] = base;
63
- if (swapped && type._readerBE && type._writerBE) {
126
+ const useSwapped = !!(swapped && type._readerBE && type._writerBE);
127
+ registerScalarInstance(value, type, useSwapped);
128
+ if (useSwapped) {
64
129
  Object.defineProperty(value, "value", {
65
130
  get() {
66
131
  if (base !== undefined) refresh(buffer);
@@ -46,7 +46,7 @@
46
46
  * ```
47
47
  */
48
48
 
49
- import { copyInstance, inDllBuffer, scalarOutparam, scalarView, sourceBytes } from "../structures/helpers/common.js";
49
+ import { copyInstance, inDllBuffer, registerScalarAccessor, scalarOutparam, scalarTypeInfo, scalarView, sourceBytes } from "../structures/helpers/common.js";
50
50
 
51
51
  /**
52
52
  * Creates the SimpleCData base class with required dependencies injected.
@@ -103,12 +103,19 @@ export function createSimpleCDataClass(alloc, ptrToBuffer) {
103
103
  * ```
104
104
  */
105
105
  class SimpleCData {
106
+ #scalarInfo;
107
+
108
+ static {
109
+ registerScalarAccessor((value) => (#scalarInfo in value ? value.#scalarInfo : undefined));
110
+ }
111
+
106
112
  /**
107
113
  * @param {number|bigint} [value] - Initial value (default: 0)
108
114
  */
109
115
  constructor(value) {
110
116
  const Ctor = this.constructor;
111
117
  this._buffer = alloc(Ctor._size);
118
+ this.#scalarInfo = scalarTypeInfo(Ctor);
112
119
  if (value !== undefined) {
113
120
  this.value = value;
114
121
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "node-ctypes",
3
- "version": "2.7.0",
3
+ "version": "2.8.0",
4
4
  "description": "Python ctypes-like FFI for Node.js using libffi",
5
5
  "author": "Damiano Mazzella",
6
6
  "license": "MIT",