node-ctypes 2.2.0 → 2.4.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.
Files changed (38) hide show
  1. package/CHANGELOG.md +932 -0
  2. package/README.md +504 -99
  3. package/build/Release/ctypes-darwin-arm64.node +0 -0
  4. package/build/Release/ctypes-darwin-x64.node +0 -0
  5. package/build/Release/ctypes-linux-arm64-musl.node +0 -0
  6. package/build/Release/ctypes-linux-arm64.node +0 -0
  7. package/build/Release/ctypes-linux-x64-musl.node +0 -0
  8. package/build/Release/ctypes-linux-x64.node +0 -0
  9. package/build/Release/ctypes-win32-arm64.node +0 -0
  10. package/build/Release/ctypes-win32-x64.node +0 -0
  11. package/lib/core/Library.js +136 -109
  12. package/lib/core/callback.js +17 -20
  13. package/lib/core/conversions.js +376 -16
  14. package/lib/core/funcptr.js +148 -73
  15. package/lib/core/lazy-loader.js +10 -4
  16. package/lib/core/types.js +201 -98
  17. package/lib/index.d.ts +276 -83
  18. package/lib/index.js +44 -32
  19. package/lib/memory/buffer.js +82 -22
  20. package/lib/memory/operations.js +55 -45
  21. package/lib/memory/pointer.js +233 -57
  22. package/lib/platform/constants.js +0 -1
  23. package/lib/platform/errors.js +48 -4
  24. package/lib/platform/find_library.js +78 -19
  25. package/lib/platform/win_types.js +8 -3
  26. package/lib/structures/Structure.js +252 -203
  27. package/lib/structures/Union.js +10 -21
  28. package/lib/structures/helpers/array.js +102 -16
  29. package/lib/structures/helpers/bitfield.js +75 -150
  30. package/lib/structures/helpers/common.js +310 -21
  31. package/lib/structures/helpers/layout.js +145 -0
  32. package/lib/structures/helpers/struct.js +160 -419
  33. package/lib/structures/helpers/union.js +154 -155
  34. package/lib/structures/helpers/wrap.js +3 -15
  35. package/lib/types/SimpleCData.js +11 -32
  36. package/lib/types/primitives.js +160 -113
  37. package/lib/utils/cache.js +34 -2
  38. package/package.json +4 -1
@@ -37,8 +37,12 @@
37
37
  */
38
38
 
39
39
  import { _toNativeReturnType, _toNativeTypes } from "./types.js";
40
- import { argumentConverters, convertArguments, resultConverter } from "./conversions.js";
40
+ import { argumentConverters, argumentsNeedOwners, callWithArgumentOwners, callWithResultHandler, convertArguments, resultCheck, resultConverter, scalarResult, structResult } from "./conversions.js";
41
41
  import { callback as createCallback } from "./callback.js";
42
+ import { isScalarSubclass, scalarOutparam } from "../structures/helpers/common.js";
43
+ import { cacheWeakValue, createTypeKey } from "../utils/cache.js";
44
+
45
+ const prototypeOwners = new WeakMap();
42
46
 
43
47
  /**
44
48
  * Internal helper: builds a function wrapper that interprets paramflags
@@ -46,7 +50,7 @@ import { callback as createCallback } from "./callback.js";
46
50
  * native function. Used by both CFUNCTYPE and WINFUNCTYPE factories.
47
51
  *
48
52
  * `paramflags` is an array the same length as argtypes, where each entry is:
49
- * { dir: "in" | "out", name: string, default?: any }
53
+ * { dir: "in" | "out" | "inout", name: string, default?: any }
50
54
  *
51
55
  * Calling conventions:
52
56
  * - Positional: fn(arg1, arg2, ...) — only "in" params supplied in order
@@ -58,7 +62,9 @@ import { callback as createCallback } from "./callback.js";
58
62
  * - N out params → array di N elementi [out1, out2, ...].
59
63
  *
60
64
  * Quando ci sono out params, `result` (restype) NON appare nel return.
61
- * Se serve ispezionarlo usa `.errcheck = fn` che riceve (result, func, args).
65
+ * Se serve ispezionarlo usa `.errcheck = fn` che riceve (result, func, args),
66
+ * con le istanze "out" in args; il valore restituito da errcheck diventa il
67
+ * risultato, salvo `args` stesso (allora il risultato sono le out).
62
68
  *
63
69
  * @private
64
70
  */
@@ -69,7 +75,8 @@ function applyParamflags(rawFn, restype, argtypes, paramflags) {
69
75
 
70
76
  // Classify slots and cache pointed-to types for out-params
71
77
  const slots = paramflags.map((pf, idx) => {
72
- const isOut = pf.dir === "out";
78
+ if (!["in", "out", "inout"].includes(pf.dir)) throw new TypeError(`paramflags[${idx}] has an invalid direction`);
79
+ const isOut = pf.dir !== "in";
73
80
  const argtype = argtypes[idx];
74
81
  let outType = null;
75
82
  if (isOut) {
@@ -79,24 +86,28 @@ function applyParamflags(rawFn, restype, argtypes, paramflags) {
79
86
  throw new TypeError(`paramflags[${idx}] is "out" but argtype ${idx} is not a POINTER(T)`);
80
87
  }
81
88
  }
82
- return { idx, name: pf.name, dir: pf.dir, default: pf.default, argtype, outType };
89
+ return { idx, name: pf.name, dir: pf.dir, default: pf.default, argtype, outType, simple: outType?._isSimpleCData === true && !isScalarSubclass(outType) };
83
90
  });
84
91
 
85
92
  const inputs = slots.filter((s) => s.dir !== "out");
86
- const outputs = slots.filter((s) => s.dir === "out");
93
+ const outputs = slots.filter((s) => s.dir !== "in");
94
+
95
+ let errcheck = null;
87
96
 
88
- return function paramflagsWrapper(...callArgs) {
97
+ const invokeWithFlags = (method, callArgs) => {
98
+ const checked = errcheck;
89
99
  const namedForm =
90
100
  callArgs.length === 1 &&
91
101
  callArgs[0] !== null &&
92
102
  typeof callArgs[0] === "object" &&
93
103
  !Buffer.isBuffer(callArgs[0]) &&
104
+ !ArrayBuffer.isView(callArgs[0]) &&
105
+ !(callArgs[0] instanceof ArrayBuffer) &&
94
106
  !Array.isArray(callArgs[0]) &&
95
107
  // Exclude struct/union proxies (they have _buffer)
96
108
  callArgs[0]._buffer === undefined;
97
109
 
98
110
  const rawArgs = new Array(slots.length);
99
- const outBuffers = [];
100
111
 
101
112
  // Populate in-slots
102
113
  let posIdx = 0;
@@ -114,65 +125,88 @@ function applyParamflags(rawFn, restype, argtypes, paramflags) {
114
125
  rawArgs[input.idx] = value;
115
126
  }
116
127
 
117
- // Allocate out-slots. `outType` può essere:
118
- // - SimpleCData class: usa _size + _reader
119
- // - Structure/Union class: usa .size (dalla structDef) + new T(buf)
120
- // - structDef/unionDef object: usa .size + def.toObject(buf)
121
- for (const output of outputs) {
122
- const t = output.outType;
123
- let baseSize;
124
- if (t._isSimpleCData) {
125
- baseSize = t._size;
126
- } else if (typeof t === "function" && (typeof t._buildStruct === "function" || typeof t._buildUnion === "function")) {
127
- const def = t._structDef || t._unionDef || t._buildStruct?.() || t._buildUnion?.();
128
- baseSize = def?.size;
129
- } else if (t && typeof t === "object" && typeof t.size === "number") {
130
- baseSize = t.size;
131
- }
132
- if (!baseSize || baseSize <= 0) {
133
- throw new TypeError(`paramflags "out" param "${output.name}": cannot determine size of target type`);
128
+ // Python: un parametro "out" è un'istanza del tipo puntato, passata per
129
+ // riferimento (il suo Buffer).
130
+ const outs = outputs.map((output) => {
131
+ const instance = output.dir === "inout" ? rawArgs[output.idx] : newOutInstance(output.outType, output.name);
132
+ rawArgs[output.idx] = instance;
133
+ return { instance, type: output.outType, dir: output.dir, simple: output.simple };
134
+ });
135
+
136
+ const finish = (result) => {
137
+ // Returning the original args continues normal output unpacking.
138
+ if (checked !== null) {
139
+ const value = checked(result, paramflagsWrapper, rawArgs);
140
+ if (value !== rawArgs) return value;
134
141
  }
135
- const buf = Buffer.alloc(baseSize);
136
- outBuffers.push({ buf, type: t, name: output.name });
137
- rawArgs[output.idx] = buf;
142
+ if (outs.length === 0) return result;
143
+ const values = outs.map(({ instance, type, dir, simple }) => {
144
+ if (dir === "inout") return instance;
145
+ const convert = instance.__ctypes_from_outparam__;
146
+ if (convert === scalarOutparam) return simple ? instance.value : instance;
147
+ if (convert !== undefined) {
148
+ if (typeof convert !== "function") throw new TypeError("__ctypes_from_outparam__ must be callable");
149
+ return convert.call(instance);
150
+ }
151
+ if (typeof type === "function") return instance;
152
+ return type.toObject(instance._buffer);
153
+ });
154
+ return values.length === 1 ? values[0] : values;
155
+ };
156
+ // The private binding snapshots this handler and keeps adapter temporaries
157
+ // alive until output processing finishes, including on an async rejection.
158
+ const previous = rawFn.errcheck;
159
+ rawFn.errcheck = finish;
160
+ try {
161
+ return method === "callAsync" ? rawFn.callAsync(...rawArgs) : rawFn(...rawArgs);
162
+ } finally {
163
+ rawFn.errcheck = previous;
138
164
  }
165
+ };
139
166
 
140
- const result = rawFn(...rawArgs);
141
-
142
- if (outputs.length === 0) return result;
167
+ const paramflagsWrapper = (...args) => invokeWithFlags("call", args);
168
+ Object.defineProperties(paramflagsWrapper, {
169
+ funcName: { value: rawFn.funcName },
170
+ address: { value: rawFn.address },
171
+ _as_parameter_: { value: rawFn.address },
172
+ _ffi: { value: rawFn._ffi },
173
+ callAsync: { value: (...args) => invokeWithFlags("callAsync", args) },
174
+ errcheck: {
175
+ get: () => errcheck,
176
+ set: (callback) => {
177
+ if (callback !== null && callback !== undefined && typeof callback !== "function") {
178
+ throw new TypeError("errcheck must be a function or null");
179
+ }
180
+ errcheck = callback ?? null;
181
+ },
182
+ enumerable: false,
183
+ configurable: true,
184
+ },
185
+ });
186
+ return paramflagsWrapper;
187
+ }
143
188
 
144
- // Read-back per type: SimpleCData → _reader, Structure/Union → instance
145
- // wrapper, plain def → toObject.
146
- const outs = outBuffers.map(({ buf, type }) => {
147
- if (type._isSimpleCData) return type._reader(buf, 0);
148
- if (typeof type === "function" && (typeof type._buildStruct === "function" || typeof type._buildUnion === "function")) {
149
- // Istanzia la classe wrappando il buffer (zero-copy se Structure).
150
- return new type(buf);
151
- }
152
- if (type && typeof type === "object" && typeof type.toObject === "function") {
153
- return type.toObject(buf);
154
- }
155
- // Fallback: ritorna il buffer raw.
156
- return buf;
157
- });
158
- // Python ctypes parity: quando ci sono out-params il return value è
159
- // SOLO le outs (singolo valore se 1, array se >1) — indipendentemente
160
- // da restype. Il `result` (già post-errcheck se configurato) viene
161
- // scartato qui; se l'utente deve ispezionarlo, deve usare un errcheck
162
- // callback che lo riceve come primo argomento.
163
- return outs.length === 1 ? outs[0] : outs;
164
- };
189
+ // Istanza per un parametro "out": SimpleCData, Structure/Union class o
190
+ // definizione struct()/union().
191
+ function newOutInstance(type, name) {
192
+ if (typeof type === "function" && (type._isSimpleCData || type._isArrayType || typeof type._buildStruct === "function")) {
193
+ return new type();
194
+ }
195
+ if (type && typeof type === "object" && typeof type.create === "function") {
196
+ return type.create();
197
+ }
198
+ throw new TypeError(`paramflags "out" param "${name}": cannot determine the target type`);
165
199
  }
166
200
 
167
201
  /**
168
202
  * Normalize a paramflags entry: Python tuple `[flag, name, default]`
169
- * (flag 1 = in, 2 = out, 4 = in defaulting to 0) or `{ dir, name, default }`.
203
+ * (flag 1 = in, 2 = out, 3 = inout, 4 = in defaulting to 0) or `{ dir, name, default }`.
170
204
  * @private
171
205
  */
172
206
  function toParamFlag(pf) {
173
207
  if (!Array.isArray(pf)) return pf;
174
208
  const [flag = 1, name, ...rest] = pf;
175
- const dir = flag & 2 ? "out" : "in";
209
+ const dir = (flag & 3) === 3 ? "inout" : flag & 2 ? "out" : "in";
176
210
  const result = { dir, name };
177
211
  if (rest.length > 0) result.default = rest[0];
178
212
  else if (flag & 4) result.default = 0;
@@ -197,12 +231,14 @@ function attachBind(factory, restype, argtypes, abi) {
197
231
  }
198
232
  for (let i = 0; i < paramflags.length; i++) {
199
233
  const pf = paramflags[i];
200
- if (pf.dir === "out" && !(argtypes[i] && argtypes[i]._pointerTo)) {
234
+ if (pf.dir !== "in" && !(argtypes[i] && argtypes[i]._pointerTo)) {
201
235
  throw new TypeError(`paramflags[${i}] is "out" but argtype ${i} is not a POINTER(T)`);
202
236
  }
203
237
  }
204
- const rawFn = library.func(symbolName, restype, argtypes, abi ? { abi } : {});
205
- return applyParamflags(rawFn, restype, argtypes, paramflags);
238
+ const rawFn = library._createFunction(symbolName, restype, argtypes, abi ? { abi } : {});
239
+ const bound = applyParamflags(rawFn, restype, argtypes, paramflags);
240
+ prototypeOwners.set(bound, factory);
241
+ return bound;
206
242
  };
207
243
  return factory;
208
244
  }
@@ -210,19 +246,42 @@ function attachBind(factory, restype, argtypes, abi) {
210
246
  // Tipo funzione CFUNCTYPE / WINFUNCTYPE: chiamato con un indirizzo restituisce
211
247
  // una funzione chiamabile, con una funzione JS crea un callback C.
212
248
  function createFuncPtrType(native, typeName, abi) {
249
+ const cache = new Map();
250
+ const signatures = new WeakMap();
251
+ const typeKey = createTypeKey();
252
+ let recent;
213
253
  return function (restype, ...argtypes) {
254
+ const previous = recent?.deref();
255
+ if (previous !== undefined) {
256
+ const signature = signatures.get(previous);
257
+ let same = signature.restype === restype && signature.argtypes.length === argtypes.length;
258
+ for (let i = 0; same && i < argtypes.length; i++) same = signature.argtypes[i] === argtypes[i];
259
+ if (same) return previous;
260
+ }
261
+ const key = `${typeKey(restype)};${argtypes.map(typeKey).join(";")}`;
262
+ const cached = cache.get(key)?.deref();
263
+ if (cached !== undefined) {
264
+ recent = cache.get(key);
265
+ return cached;
266
+ }
214
267
  const nativeRestype = _toNativeReturnType(restype, native);
215
268
  const nativeArgtypes = _toNativeTypes(argtypes, native);
216
- const converters = argumentConverters(argtypes, native);
217
- const convertResult = resultConverter(restype);
218
269
 
219
270
  function factory(addressOrFn, paramflags) {
220
271
  // Python ctypes parity: CFUNCTYPE(...)(jsFunc) wraps a JS function as a C callback.
221
272
  if (typeof addressOrFn === "function") {
222
- return createCallback(addressOrFn, restype, argtypes, native, abi);
273
+ const callback = createCallback(addressOrFn, restype, argtypes, native, abi);
274
+ prototypeOwners.set(callback, factory);
275
+ return callback;
223
276
  }
277
+ const converters = argumentConverters(argtypes, native);
278
+ const hasAdapters = converters.some((convert) => convert.requiresOwners);
279
+ const represent = resultConverter(restype);
280
+ const check = resultCheck(restype, typeName);
281
+ const convertResult = check === undefined ? represent : represent === undefined ? check : (value) => check(represent(value));
224
282
  // Python: prototype((name, dll)) / prototype((name, dll), paramflags)
225
283
  // binds an exported function of a library to this prototype.
284
+ let ownerLibrary;
226
285
  if (Array.isArray(addressOrFn)) {
227
286
  const [name, library] = addressOrFn;
228
287
  if (typeof name !== "string" || library === null || typeof library !== "object" || typeof library.symbol !== "function") {
@@ -231,6 +290,9 @@ function createFuncPtrType(native, typeName, abi) {
231
290
  if (paramflags !== undefined) {
232
291
  return factory.bind(library, name, paramflags);
233
292
  }
293
+ // La funzione tiene caricata la libreria del simbolo (come CDLL.func).
294
+ const nativeLibrary = library._lib ?? library;
295
+ if (nativeLibrary instanceof native.Library) ownerLibrary = nativeLibrary;
234
296
  addressOrFn = library.symbol(name);
235
297
  }
236
298
  // Python accetta l'indirizzo come int: anche qui number o BigInt.
@@ -239,27 +301,39 @@ function createFuncPtrType(native, typeName, abi) {
239
301
  throw new TypeError(`${typeName}: argument must be an address (BigInt or number), a JS function or [name, library]`);
240
302
  }
241
303
 
242
- const ffiFunc = abi ? new native.FFIFunction(address, null, nativeRestype, nativeArgtypes, { abi }) : new native.FFIFunction(address, null, nativeRestype, nativeArgtypes);
304
+ const options = {};
305
+ if (abi) options.abi = abi;
306
+ if (ownerLibrary) options.library = ownerLibrary;
307
+ if (structResult(restype)) options.struct_buffer = true;
308
+ if (scalarResult(restype)) options.scalar_buffer = true;
309
+ const ffiFunc = new native.FFIFunction(address, null, nativeRestype, nativeArgtypes, options);
243
310
 
244
311
  // Come le funzioni di CDLL: restype POINTER/CFUNCTYPE convertito, ed
245
312
  // errcheck applicato sul valore convertito.
246
313
  let jsErrcheck = null;
247
- const finish = (result, args) => {
248
- if (convertResult === undefined) return result;
249
- const converted = convertResult(result);
250
- return jsErrcheck === null ? converted : jsErrcheck(converted, callMethod, args);
314
+ let checkedSync;
315
+ const finish = (result) => (convertResult === undefined ? result : convertResult(result));
316
+ const checkedCall = (method, args, checked) => {
317
+ const resultHandler = (result) => checked(finish(result), callMethod, args);
318
+ const call = method === "call" ? (checkedSync ??= ffiFunc._makeCheckedCall()) : undefined;
319
+ return callWithResultHandler(ffiFunc, method, args, converters, resultHandler, hasAdapters || argumentsNeedOwners(args), call);
251
320
  };
252
321
 
253
322
  const callMethod = function (...args) {
323
+ if (jsErrcheck !== null) return checkedCall("call", args, jsErrcheck);
324
+ if (hasAdapters || argumentsNeedOwners(args)) return callWithArgumentOwners(ffiFunc, "call", args, converters, finish);
254
325
  return finish(ffiFunc.call(...convertArguments(args, converters)), args);
255
326
  };
256
327
 
257
328
  Object.defineProperties(callMethod, {
258
329
  funcName: { value: `0x${address.toString(16)}` },
259
330
  address: { value: ffiFunc.address },
331
+ _as_parameter_: { value: ffiFunc.address },
260
332
  _ffi: { value: ffiFunc },
261
333
  callAsync: {
262
334
  value: function (...args) {
335
+ if (jsErrcheck !== null) return checkedCall("callAsync", args, jsErrcheck);
336
+ if (hasAdapters || argumentsNeedOwners(args)) return callWithArgumentOwners(ffiFunc, "callAsync", args, converters, finish);
263
337
  return ffiFunc.callAsync(...convertArguments(args, converters)).then((result) => finish(result, args));
264
338
  },
265
339
  writable: false,
@@ -268,30 +342,31 @@ function createFuncPtrType(native, typeName, abi) {
268
342
  },
269
343
  errcheck: {
270
344
  get() {
271
- return ffiFunc._errcheck ?? null;
345
+ return jsErrcheck;
272
346
  },
273
347
  set(callback) {
274
- ffiFunc._errcheck = callback;
275
- if (convertResult !== undefined) {
276
- jsErrcheck = callback ?? null;
277
- } else {
278
- ffiFunc.setErrcheck(callback);
279
- }
348
+ callback = callback ?? null;
349
+ if (callback !== null && typeof callback !== "function") throw new TypeError("errcheck must be a function or null");
350
+ jsErrcheck = callback;
280
351
  },
281
352
  enumerable: false,
282
353
  configurable: true,
283
354
  },
284
355
  });
285
356
 
357
+ prototypeOwners.set(callMethod, factory);
286
358
  return callMethod;
287
359
  }
288
360
 
289
361
  // Attach metadata + paramflags binding to the factory
290
362
  factory.restype = restype;
291
- factory.argtypes = argtypes;
363
+ factory.argtypes = argtypes.slice();
292
364
  factory._isFuncPtr = true;
293
365
  attachBind(factory, restype, argtypes, abi);
294
366
 
367
+ signatures.set(factory, { restype, argtypes });
368
+ cacheWeakValue(cache, key, factory);
369
+ recent = cache.get(key);
295
370
  return factory;
296
371
  };
297
372
  }
@@ -37,23 +37,29 @@
37
37
  * @param {Function} DllClass - CDLL, WinDLL, or OleDLL constructor.
38
38
  * @returns {Proxy} Namespace object with `.<libname>` auto-loading.
39
39
  */
40
+ // Proprietà interrogate da String(), JSON.stringify, util.inspect, test
41
+ // runner e framework: non sono nomi di librerie.
42
+ const probes = new Set(["then", "toJSON", "valueOf", "constructor", "inspect", "nodeType", "asymmetricMatch", "$$typeof"]);
43
+
40
44
  export function createLazyLoader(DllClass) {
41
45
  const cache = new Map();
42
46
  // Python: cdll.LoadLibrary(name, ...) crea sempre una nuova istanza.
43
47
  const LoadLibrary = (name, ...args) => new DllClass(name, ...args);
48
+ const toString = () => `[object LibraryLoader ${DllClass.name}]`;
49
+ // Python LibraryLoader.__getattr__: i nomi che iniziano con "_" non sono librerie.
50
+ const isLibraryName = (name) => typeof name === "string" && name !== "" && name[0] !== "_" && !probes.has(name) && name !== "toString" && name !== "LoadLibrary";
44
51
  return new Proxy(Object.create(null), {
45
52
  get(_, libName) {
46
- if (typeof libName !== "string") return undefined;
47
- // Skip symbol/private probes used by Node's inspect / util.inspect.
48
- if (libName === "then") return undefined;
49
53
  if (libName === "LoadLibrary") return LoadLibrary;
54
+ if (libName === "toString") return toString;
55
+ if (!isLibraryName(libName)) return undefined;
50
56
  if (!cache.has(libName)) {
51
57
  cache.set(libName, new DllClass(libName));
52
58
  }
53
59
  return cache.get(libName);
54
60
  },
55
61
  has(_, libName) {
56
- return typeof libName === "string";
62
+ return libName === "LoadLibrary" || libName === "toString" || isLibraryName(libName);
57
63
  },
58
64
  });
59
65
  }