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 +22 -1
- package/README.md +6 -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/Library.js +3 -2
- package/lib/core/conversions.js +46 -12
- package/lib/index.d.ts +1 -1
- package/lib/structures/helpers/common.js +66 -1
- package/lib/types/SimpleCData.js +8 -1
- package/package.json +1 -1
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.
|
|
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
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
package/lib/core/Library.js
CHANGED
|
@@ -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
|
-
|
|
183
|
-
|
|
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);
|
package/lib/core/conversions.js
CHANGED
|
@@ -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 {
|
|
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
|
|
251
|
-
*
|
|
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
|
-
|
|
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
|
-
|
|
352
|
-
|
|
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
|
|
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.
|
|
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
|
-
|
|
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);
|
package/lib/types/SimpleCData.js
CHANGED
|
@@ -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
|
}
|