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
@@ -60,6 +60,8 @@
60
60
  * ```
61
61
  */
62
62
 
63
+ import { booleanValue, keepAlive, notIntegral, registerSimpleType } from "../structures/helpers/common.js";
64
+
63
65
  /**
64
66
  * Creates all primitive type classes with required dependencies injected.
65
67
  *
@@ -98,6 +100,52 @@ export function createPrimitiveTypes(SimpleCData, native, addressOf, cstring, ws
98
100
  // Integer types - signed
99
101
  // ============================================================================
100
102
 
103
+ // Python: un intero è troncato ai bit del tipo (c_uint8(256) → 0,
104
+ // c_int64(2**64 + 7) → 7). Signed e unsigned hanno gli stessi bit, quindi i
105
+ // writer (tranne c_int32, più veloce con writeInt32) scrivono la
106
+ // rappresentazione senza segno. Number via ToInt32/ToUint32 (esatti per ogni
107
+ // double), BigInt via asIntN/asUintN.
108
+ // Il caso number è testato per primo: è il percorso caldo dei campi.
109
+ // Un number non intero è un float, che Python rifiuta per i tipi interi.
110
+ const integerBoolean = (val) => {
111
+ if (typeof val === "boolean") return +val;
112
+ throw new TypeError(`'${typeName(val)}' object cannot be interpreted as an integer`);
113
+ };
114
+ const u32 = (val) => (typeof val === "number" ? (Number.isInteger(val) ? val >>> 0 : notIntegral()) : typeof val === "bigint" ? Number(BigInt.asUintN(32, val)) : integerBoolean(val));
115
+ const i32 = (val) => (typeof val === "number" ? (Number.isInteger(val) ? val | 0 : notIntegral()) : typeof val === "bigint" ? Number(BigInt.asIntN(32, val)) : integerBoolean(val));
116
+ const u64 = (val) => BigInt.asUintN(64, typeof val === "bigint" ? val : typeof val === "number" ? (Number.isInteger(val) ? BigInt(val) : notIntegral()) : BigInt(integerBoolean(val)));
117
+ const real = (val) => {
118
+ if (typeof val === "number") return val;
119
+ if (typeof val === "boolean") return +val;
120
+ if (typeof val === "bigint") {
121
+ if (val < -(2n ** 63n) || val >= 2n ** 64n) throw new RangeError("BigInt out of range for a floating point argument");
122
+ return Number(val);
123
+ }
124
+ throw new TypeError(`must be real number, not ${typeName(val)}`);
125
+ };
126
+ const writeU8 = (buf, off, val) => {
127
+ buf[off] = u32(val);
128
+ };
129
+ // Interi a 64 bit: un number intero sicuro (il caso comune) è scritto come
130
+ // due metà a 32 bit, senza passare da BigInt (~10x più lento).
131
+ const TWO_32 = 4294967296;
132
+ const writeU64LE = (buf, off, val) => {
133
+ if (typeof val === "number" && Number.isSafeInteger(val) && off + 8 <= buf.length) {
134
+ buf.writeUInt32LE(val >>> 0, off);
135
+ buf.writeUInt32LE(Math.floor(val / TWO_32) >>> 0, off + 4);
136
+ } else {
137
+ buf.writeBigUInt64LE(u64(val), off);
138
+ }
139
+ };
140
+ const writeU64BE = (buf, off, val) => {
141
+ if (typeof val === "number" && Number.isSafeInteger(val) && off + 8 <= buf.length) {
142
+ buf.writeUInt32BE(Math.floor(val / TWO_32) >>> 0, off);
143
+ buf.writeUInt32BE(val >>> 0, off + 4);
144
+ } else {
145
+ buf.writeBigUInt64BE(u64(val), off);
146
+ }
147
+ };
148
+
101
149
  // Each numeric primitive carries both a default LE _reader/_writer AND BE
102
150
  // variants (_readerBE/_writerBE). BigEndianStructure / LittleEndianStructure
103
151
  // opt-in via the struct's _swapped_ flag; native-order code is unaffected.
@@ -108,7 +156,7 @@ export function createPrimitiveTypes(SimpleCData, native, addressOf, cstring, ws
108
156
  static _type = CType.INT8;
109
157
  static _signed = true;
110
158
  static _reader = (buf, off) => buf.readInt8(off);
111
- static _writer = (buf, off, val) => buf.writeInt8(val, off);
159
+ static _writer = writeU8;
112
160
  static _readerBE = c_int8._reader;
113
161
  static _writerBE = c_int8._writer;
114
162
  }
@@ -118,9 +166,9 @@ export function createPrimitiveTypes(SimpleCData, native, addressOf, cstring, ws
118
166
  static _type = CType.INT16;
119
167
  static _signed = true;
120
168
  static _reader = (buf, off) => buf.readInt16LE(off);
121
- static _writer = (buf, off, val) => buf.writeInt16LE(val, off);
169
+ static _writer = (buf, off, val) => buf.writeUInt16LE(u32(val) & 0xffff, off);
122
170
  static _readerBE = (buf, off) => buf.readInt16BE(off);
123
- static _writerBE = (buf, off, val) => buf.writeInt16BE(val, off);
171
+ static _writerBE = (buf, off, val) => buf.writeUInt16BE(u32(val) & 0xffff, off);
124
172
  }
125
173
 
126
174
  class c_int32 extends SimpleCData {
@@ -128,12 +176,9 @@ export function createPrimitiveTypes(SimpleCData, native, addressOf, cstring, ws
128
176
  static _type = CType.INT32;
129
177
  static _signed = true;
130
178
  static _reader = (buf, off) => buf.readInt32LE(off);
131
- static _writer = (buf, off, val) => {
132
- const v = Number(val) | 0; // coerce to signed 32-bit
133
- return buf.writeInt32LE(v, off);
134
- };
179
+ static _writer = (buf, off, val) => buf.writeInt32LE(i32(val), off);
135
180
  static _readerBE = (buf, off) => buf.readInt32BE(off);
136
- static _writerBE = (buf, off, val) => buf.writeInt32BE(Number(val) | 0, off);
181
+ static _writerBE = (buf, off, val) => buf.writeInt32BE(i32(val), off);
137
182
  }
138
183
 
139
184
  class c_int64 extends SimpleCData {
@@ -141,9 +186,9 @@ export function createPrimitiveTypes(SimpleCData, native, addressOf, cstring, ws
141
186
  static _type = CType.INT64;
142
187
  static _signed = true;
143
188
  static _reader = (buf, off) => buf.readBigInt64LE(off);
144
- static _writer = (buf, off, val) => buf.writeBigInt64LE(BigInt(val), off);
189
+ static _writer = writeU64LE;
145
190
  static _readerBE = (buf, off) => buf.readBigInt64BE(off);
146
- static _writerBE = (buf, off, val) => buf.writeBigInt64BE(BigInt(val), off);
191
+ static _writerBE = writeU64BE;
147
192
  }
148
193
 
149
194
  // ============================================================================
@@ -154,7 +199,7 @@ export function createPrimitiveTypes(SimpleCData, native, addressOf, cstring, ws
154
199
  static _size = 1;
155
200
  static _type = CType.UINT8;
156
201
  static _reader = (buf, off) => buf.readUInt8(off);
157
- static _writer = (buf, off, val) => buf.writeUInt8(val, off);
202
+ static _writer = writeU8;
158
203
  static _readerBE = c_uint8._reader;
159
204
  static _writerBE = c_uint8._writer;
160
205
  }
@@ -163,30 +208,27 @@ export function createPrimitiveTypes(SimpleCData, native, addressOf, cstring, ws
163
208
  static _size = 2;
164
209
  static _type = CType.UINT16;
165
210
  static _reader = (buf, off) => buf.readUInt16LE(off);
166
- static _writer = (buf, off, val) => buf.writeUInt16LE(val, off);
211
+ static _writer = (buf, off, val) => buf.writeUInt16LE(u32(val) & 0xffff, off);
167
212
  static _readerBE = (buf, off) => buf.readUInt16BE(off);
168
- static _writerBE = (buf, off, val) => buf.writeUInt16BE(val, off);
213
+ static _writerBE = (buf, off, val) => buf.writeUInt16BE(u32(val) & 0xffff, off);
169
214
  }
170
215
 
171
216
  class c_uint32 extends SimpleCData {
172
217
  static _size = 4;
173
218
  static _type = CType.UINT32;
174
219
  static _reader = (buf, off) => buf.readUInt32LE(off);
175
- static _writer = (buf, off, val) => {
176
- const v = Number(val) >>> 0; // coerce to unsigned 32-bit
177
- return buf.writeUInt32LE(v, off);
178
- };
220
+ static _writer = (buf, off, val) => buf.writeUInt32LE(u32(val), off);
179
221
  static _readerBE = (buf, off) => buf.readUInt32BE(off);
180
- static _writerBE = (buf, off, val) => buf.writeUInt32BE(Number(val) >>> 0, off);
222
+ static _writerBE = (buf, off, val) => buf.writeUInt32BE(u32(val), off);
181
223
  }
182
224
 
183
225
  class c_uint64 extends SimpleCData {
184
226
  static _size = 8;
185
227
  static _type = CType.UINT64;
186
228
  static _reader = (buf, off) => buf.readBigUInt64LE(off);
187
- static _writer = (buf, off, val) => buf.writeBigUInt64LE(BigInt(val), off);
229
+ static _writer = writeU64LE;
188
230
  static _readerBE = (buf, off) => buf.readBigUInt64BE(off);
189
- static _writerBE = (buf, off, val) => buf.writeBigUInt64BE(BigInt(val), off);
231
+ static _writerBE = writeU64BE;
190
232
  }
191
233
 
192
234
  // ============================================================================
@@ -197,18 +239,18 @@ export function createPrimitiveTypes(SimpleCData, native, addressOf, cstring, ws
197
239
  static _size = 4;
198
240
  static _type = CType.FLOAT;
199
241
  static _reader = (buf, off) => buf.readFloatLE(off);
200
- static _writer = (buf, off, val) => buf.writeFloatLE(val, off);
242
+ static _writer = (buf, off, val) => buf.writeFloatLE(real(val), off);
201
243
  static _readerBE = (buf, off) => buf.readFloatBE(off);
202
- static _writerBE = (buf, off, val) => buf.writeFloatBE(val, off);
244
+ static _writerBE = (buf, off, val) => buf.writeFloatBE(real(val), off);
203
245
  }
204
246
 
205
247
  class c_double extends SimpleCData {
206
248
  static _size = 8;
207
249
  static _type = CType.DOUBLE;
208
250
  static _reader = (buf, off) => buf.readDoubleLE(off);
209
- static _writer = (buf, off, val) => buf.writeDoubleLE(val, off);
251
+ static _writer = (buf, off, val) => buf.writeDoubleLE(real(val), off);
210
252
  static _readerBE = (buf, off) => buf.readDoubleBE(off);
211
- static _writerBE = (buf, off, val) => buf.writeDoubleBE(val, off);
253
+ static _writerBE = (buf, off, val) => buf.writeDoubleBE(real(val), off);
212
254
  }
213
255
 
214
256
  // ============================================================================
@@ -218,8 +260,9 @@ export function createPrimitiveTypes(SimpleCData, native, addressOf, cstring, ws
218
260
  class c_bool extends SimpleCData {
219
261
  static _size = 1;
220
262
  static _type = CType.BOOL;
263
+ static _isBoolean = true;
221
264
  static _reader = (buf, off) => buf.readUInt8(off) !== 0;
222
- static _writer = (buf, off, val) => buf.writeUInt8(val ? 1 : 0, off);
265
+ static _writer = (buf, off, val) => buf.writeUInt8(booleanValue(val) ? 1 : 0, off);
223
266
  static _readerBE = c_bool._reader;
224
267
  static _writerBE = c_bool._writer;
225
268
  }
@@ -231,27 +274,53 @@ export function createPrimitiveTypes(SimpleCData, native, addressOf, cstring, ws
231
274
  // Python c_char: il valore è un bytes di 1 byte; in JS una stringa di 1
232
275
  // carattere con codice 0-255. In scrittura accetta anche un numero o un Buffer.
233
276
  // Python ctypes accetta solo un singolo carattere (o un intero 0..255 per c_char).
277
+ const typeName = (val) => {
278
+ if (val === null) return "null";
279
+ if (Buffer.isBuffer(val)) return "Buffer";
280
+ if (typeof val === "object") return val.constructor?.name || "object";
281
+ return typeof val;
282
+ };
283
+
284
+ const CHAR_EXPECTED = "one character bytes, bytearray, or an integer in range(256) expected";
234
285
  const charCode = (val) => {
235
286
  if (typeof val === "string") {
236
- if (val.length === 1 && val.charCodeAt(0) <= 0xff) return val.charCodeAt(0);
237
- } else if (Buffer.isBuffer(val) || val instanceof Uint8Array) {
238
- if (val.length === 1) return val[0];
239
- } else if (typeof val === "number" && Number.isInteger(val) && val >= 0 && val <= 0xff) {
287
+ if (val.length !== 1) throw new TypeError(`${CHAR_EXPECTED}, not a string of length ${val.length}`);
288
+ const code = val.charCodeAt(0);
289
+ if (code > 0xff) throw new TypeError("character not in range(256)");
290
+ return code;
291
+ }
292
+ if (val instanceof Uint8Array) {
293
+ if (val.length !== 1) throw new TypeError(`${CHAR_EXPECTED}, not ${typeName(val)} of length ${val.length}`);
294
+ return val[0];
295
+ }
296
+ if (typeof val === "number" && Number.isInteger(val)) {
297
+ if (val < 0 || val > 0xff) throw new TypeError("integer not in range(256)");
240
298
  return val;
241
299
  }
242
- throw new TypeError("one character bytes, bytearray or integer expected");
300
+ if (typeof val === "boolean") return val ? 1 : 0;
301
+ throw new TypeError(`${CHAR_EXPECTED}, not ${typeName(val)}`);
243
302
  };
244
303
 
304
+ // Python c_wchar: un solo carattere. Dove wchar_t è a 16 bit un carattere
305
+ // fuori dal BMP occupa due wchar_t e non è accettato.
306
+ const WCHAR_LIMIT = native.WCHAR_SIZE === 2 ? 0x10000 : 0x110000;
245
307
  const wcharCode = (val) => {
246
308
  if (typeof val === "string") {
247
309
  const code = val.codePointAt(0);
248
- if (code !== undefined && val.length === (code > 0xffff ? 2 : 1)) return code;
249
- throw new TypeError("one character unicode string expected");
310
+ let length = val.length;
311
+ if (length === 2 && code > 0xffff && code < WCHAR_LIMIT) length = 1;
312
+ if (length !== 1) throw new TypeError(`a unicode character expected, not a string of length ${length}`);
313
+ return code;
314
+ }
315
+ if (typeof val === "number") {
316
+ if (Number.isInteger(val) && val >= 0 && val < WCHAR_LIMIT) return val;
317
+ throw new TypeError(`wchar_t code point not in range(0x${WCHAR_LIMIT.toString(16)})`);
250
318
  }
251
- if (typeof val === "number" && Number.isInteger(val) && val >= 0) return val;
252
- throw new TypeError(`unicode string expected instead of ${val === null ? "null" : typeof val}`);
319
+ throw new TypeError(`a unicode character expected, not instance of ${typeName(val)}`);
253
320
  };
254
321
 
322
+ const wcharString = (code) => String.fromCodePoint(code > 0x10ffff ? 0xfffd : code);
323
+
255
324
  class c_char extends SimpleCData {
256
325
  static _size = 1;
257
326
  static _type = CType.CHAR;
@@ -272,7 +341,7 @@ export function createPrimitiveTypes(SimpleCData, native, addressOf, cstring, ws
272
341
  if (native.WCHAR_SIZE === 2) {
273
342
  return String.fromCharCode(buf.readUInt16LE(off));
274
343
  }
275
- return String.fromCodePoint(buf.readUInt32LE(off));
344
+ return wcharString(buf.readUInt32LE(off));
276
345
  };
277
346
  static _writer = (buf, off, val) => {
278
347
  const code = wcharCode(val);
@@ -286,7 +355,7 @@ export function createPrimitiveTypes(SimpleCData, native, addressOf, cstring, ws
286
355
  if (native.WCHAR_SIZE === 2) {
287
356
  return String.fromCharCode(buf.readUInt16BE(off));
288
357
  }
289
- return String.fromCodePoint(buf.readUInt32BE(off));
358
+ return wcharString(buf.readUInt32BE(off));
290
359
  };
291
360
  static _writerBE = (buf, off, val) => {
292
361
  const code = wcharCode(val);
@@ -305,80 +374,70 @@ export function createPrimitiveTypes(SimpleCData, native, addressOf, cstring, ws
305
374
  class c_void_p extends SimpleCData {
306
375
  static _size = native.POINTER_SIZE;
307
376
  static _type = CType.POINTER;
377
+ static _isPointerValued = true;
378
+ // Campi c_void_p: anche istanze c_char_p / c_wchar_p (il loro indirizzo).
379
+ static _acceptsPointerValues = true;
308
380
  static _reader = (buf, off) => {
309
381
  const ptr = native.POINTER_SIZE === 8 ? buf.readBigUInt64LE(off) : BigInt(buf.readUInt32LE(off));
310
382
  if (!ptr) return null;
311
383
  return ptr;
312
384
  };
313
385
  static _writer = (buf, off, val) => {
314
- // Accept Buffers (pointer to memory) and struct proxies with _buffer
315
- if (Buffer.isBuffer(val)) {
316
- const addr = addressOf(val);
317
- const v = typeof addr === "bigint" ? addr : BigInt(addr || 0);
318
- if (native.POINTER_SIZE === 8) buf.writeBigUInt64LE(v, off);
319
- else buf.writeUInt32LE(Number(v), off);
320
- return;
321
- }
322
- if (val && typeof val === "object" && val._buffer && Buffer.isBuffer(val._buffer)) {
323
- const addr = addressOf(val._buffer);
324
- const v = typeof addr === "bigint" ? addr : BigInt(addr || 0);
325
- if (native.POINTER_SIZE === 8) buf.writeBigUInt64LE(v, off);
326
- else buf.writeUInt32LE(Number(v), off);
327
- return;
328
- }
386
+ const address = voidPointerAddress(val);
387
+ if (native.POINTER_SIZE === 8) buf.writeBigUInt64LE(address, off);
388
+ else buf.writeUInt32LE(Number(address), off);
389
+ // La memoria assegnata resta viva con il buffer (Python `_objects`).
390
+ keepAlive(buf, off, val !== null && typeof val === "object" ? val : null);
391
+ };
392
+ }
329
393
 
330
- // Fallback: accept BigInt or number
331
- const v = typeof val === "bigint" ? val : BigInt(val || 0);
332
- if (native.POINTER_SIZE === 8) {
333
- buf.writeBigUInt64LE(v, off);
334
- } else {
335
- buf.writeUInt32LE(Number(v), off);
394
+ // Indirizzo assegnato a un c_void_p: memoria di Buffer e istanze, valore di
395
+ // puntatori, c_void_p / c_char_p / c_wchar_p e `_as_parameter_`.
396
+ function voidPointerAddress(val) {
397
+ if (typeof val === "bigint") return val;
398
+ if (val === null || val === undefined) return 0n;
399
+ if (typeof val === "object") {
400
+ if (val._pointerType !== undefined) return val.address;
401
+ const T = val.constructor;
402
+ if (T?._isSimpleCData === true && (T._type === CType.POINTER || T._type === CType.STRING || T._type === CType.WSTRING)) {
403
+ return native.POINTER_SIZE === 8 ? val._buffer.readBigUInt64LE(0) : BigInt(val._buffer.readUInt32LE(0));
336
404
  }
337
- };
405
+ if (Buffer.isBuffer(val) || Buffer.isBuffer(val._buffer)) return BigInt(addressOf(val));
406
+ if (val._as_parameter_ !== undefined) return voidPointerAddress(val._as_parameter_);
407
+ throw new TypeError("c_void_p: cannot be converted to pointer");
408
+ }
409
+ return BigInt(val);
338
410
  }
339
411
 
340
412
  // ============================================================================
341
413
  // Platform-specific types
342
414
  // ============================================================================
343
415
 
416
+ // Interi pointer-sized e long: stessi writer troncanti degli interi a 32/64 bit.
417
+ const writeWord = (size) => (size === 8 ? writeU64LE : (buf, off, val) => buf.writeUInt32LE(u32(val), off));
418
+ const writeWordBE = (size) => (size === 8 ? writeU64BE : (buf, off, val) => buf.writeUInt32BE(u32(val), off));
419
+
344
420
  class c_size_t extends SimpleCData {
345
421
  static _size = native.POINTER_SIZE;
346
422
  static _type = CType.SIZE_T;
347
423
  static _reader = (buf, off) => {
348
424
  return native.POINTER_SIZE === 8 ? buf.readBigUInt64LE(off) : buf.readUInt32LE(off);
349
425
  };
350
- static _writer = (buf, off, val) => {
351
- if (native.POINTER_SIZE === 8) {
352
- buf.writeBigUInt64LE(BigInt(val), off);
353
- } else {
354
- buf.writeUInt32LE(Number(val), off);
355
- }
356
- };
426
+ static _writer = writeWord(native.POINTER_SIZE);
357
427
  static _readerBE = (buf, off) => (native.POINTER_SIZE === 8 ? buf.readBigUInt64BE(off) : buf.readUInt32BE(off));
358
- static _writerBE = (buf, off, val) => {
359
- if (native.POINTER_SIZE === 8) buf.writeBigUInt64BE(BigInt(val), off);
360
- else buf.writeUInt32BE(Number(val), off);
361
- };
428
+ static _writerBE = writeWordBE(native.POINTER_SIZE);
362
429
  }
363
430
 
364
431
  class c_ssize_t extends SimpleCData {
365
432
  static _size = native.POINTER_SIZE;
366
433
  static _type = CType.SSIZE_T;
434
+ static _signed = true;
367
435
  static _reader = (buf, off) => {
368
436
  return native.POINTER_SIZE === 8 ? buf.readBigInt64LE(off) : buf.readInt32LE(off);
369
437
  };
370
- static _writer = (buf, off, val) => {
371
- if (native.POINTER_SIZE === 8) {
372
- buf.writeBigInt64LE(BigInt(val), off);
373
- } else {
374
- buf.writeInt32LE(Number(val), off);
375
- }
376
- };
438
+ static _writer = writeWord(native.POINTER_SIZE);
377
439
  static _readerBE = (buf, off) => (native.POINTER_SIZE === 8 ? buf.readBigInt64BE(off) : buf.readInt32BE(off));
378
- static _writerBE = (buf, off, val) => {
379
- if (native.POINTER_SIZE === 8) buf.writeBigInt64BE(BigInt(val), off);
380
- else buf.writeInt32BE(Number(val), off);
381
- };
440
+ static _writerBE = writeWordBE(native.POINTER_SIZE);
382
441
  }
383
442
 
384
443
  // Get actual long size from native module (4 on Windows, 4 or 8 on Unix depending on arch)
@@ -387,50 +446,34 @@ export function createPrimitiveTypes(SimpleCData, native, addressOf, cstring, ws
387
446
  // c_long / c_ulong valgono BigInt su ogni piattaforma, anche dove `long` è a
388
447
  // 32 bit (Windows): stesso tipo JS per ritorni, campi e `.value` ovunque.
389
448
  // In scrittura accettano number e BigInt (troncato ai bit del tipo, come Python).
390
- const asInt32 = (val) => (typeof val === "bigint" ? Number(BigInt.asIntN(32, val)) : val);
391
- const asUint32 = (val) => (typeof val === "bigint" ? Number(BigInt.asUintN(32, val)) : val);
392
-
393
449
  class c_long extends SimpleCData {
394
450
  static _size = _longSize;
395
451
  static _type = CType.LONG;
452
+ static _signed = true;
396
453
  static _reader = _longSize === 8 ? (buf, off) => buf.readBigInt64LE(off) : (buf, off) => BigInt(buf.readInt32LE(off));
397
- static _writer = _longSize === 8 ? (buf, off, val) => buf.writeBigInt64LE(BigInt(val), off) : (buf, off, val) => buf.writeInt32LE(asInt32(val), off);
454
+ static _writer = writeWord(_longSize);
398
455
  static _readerBE = _longSize === 8 ? (buf, off) => buf.readBigInt64BE(off) : (buf, off) => BigInt(buf.readInt32BE(off));
399
- static _writerBE = _longSize === 8 ? (buf, off, val) => buf.writeBigInt64BE(BigInt(val), off) : (buf, off, val) => buf.writeInt32BE(asInt32(val), off);
456
+ static _writerBE = writeWordBE(_longSize);
400
457
  }
401
458
 
402
459
  class c_ulong extends SimpleCData {
403
460
  static _size = _longSize;
404
461
  static _type = CType.ULONG;
405
462
  static _reader = _longSize === 8 ? (buf, off) => buf.readBigUInt64LE(off) : (buf, off) => BigInt(buf.readUInt32LE(off));
406
- static _writer = _longSize === 8 ? (buf, off, val) => buf.writeBigUInt64LE(BigInt(val), off) : (buf, off, val) => buf.writeUInt32LE(asUint32(val), off);
463
+ static _writer = writeWord(_longSize);
407
464
  static _readerBE = _longSize === 8 ? (buf, off) => buf.readBigUInt64BE(off) : (buf, off) => BigInt(buf.readUInt32BE(off));
408
- static _writerBE = _longSize === 8 ? (buf, off, val) => buf.writeBigUInt64BE(BigInt(val), off) : (buf, off, val) => buf.writeUInt32BE(asUint32(val), off);
465
+ static _writerBE = writeWordBE(_longSize);
409
466
  }
410
467
 
411
468
  // ============================================================================
412
469
  // String pointer types (special handling)
413
470
  // ============================================================================
414
471
 
415
- // Keepalive helper: when assigning a JS string (or an arbitrary Buffer) to a
416
- // c_char_p / c_wchar_p field of a Structure, we convert/reference the backing
417
- // Buffer and attach it to the struct's underlying Buffer so it outlives the
418
- // write. Without this the converted Buffer would be GC-eligible immediately
419
- // after _writer returns, leaving a dangling pointer in the field.
420
- // This mirrors Python ctypes' `_objects` keepalive mechanism.
421
- const _stringKeepalive = (targetBuf, off, val) => {
422
- let keep = targetBuf.__ctypesKeepalive;
423
- if (!keep) {
424
- keep = Object.create(null);
425
- Object.defineProperty(targetBuf, "__ctypesKeepalive", {
426
- value: keep,
427
- enumerable: false,
428
- configurable: false,
429
- writable: false,
430
- });
431
- }
432
- keep[off] = val;
433
- };
472
+ // Keepalive: when assigning a JS string (or an arbitrary Buffer) to a
473
+ // c_char_p / c_wchar_p field, the converted Buffer is kept alive with the
474
+ // memory of the structure (see keepAlive), otherwise the field would point
475
+ // to collected memory. This mirrors Python ctypes' `_objects`.
476
+ const _stringKeepalive = keepAlive;
434
477
 
435
478
  const _writePointerField = (buf, off, val) => {
436
479
  const addr = typeof val === "bigint" ? val : BigInt(val || 0);
@@ -444,6 +487,7 @@ export function createPrimitiveTypes(SimpleCData, native, addressOf, cstring, ws
444
487
  class c_char_p extends SimpleCData {
445
488
  static _size = native.POINTER_SIZE;
446
489
  static _type = CType.STRING;
490
+ static _isPointerValued = true;
447
491
  static _reader = (buf, off) => {
448
492
  const ptr = native.POINTER_SIZE === 8 ? buf.readBigUInt64LE(off) : BigInt(buf.readUInt32LE(off));
449
493
  if (!ptr) return null;
@@ -454,14 +498,14 @@ export function createPrimitiveTypes(SimpleCData, native, addressOf, cstring, ws
454
498
  val = cstring(val);
455
499
  }
456
500
  if (Buffer.isBuffer(val)) {
457
- _stringKeepalive(buf, off, val);
458
501
  _writePointerField(buf, off, addressOf(val));
502
+ _stringKeepalive(buf, off, val);
459
503
  } else if (val == null) {
460
- _stringKeepalive(buf, off, null);
461
504
  _writePointerField(buf, off, 0n);
462
- } else {
463
505
  _stringKeepalive(buf, off, null);
506
+ } else {
464
507
  _writePointerField(buf, off, val);
508
+ _stringKeepalive(buf, off, null);
465
509
  }
466
510
  };
467
511
  }
@@ -469,6 +513,7 @@ export function createPrimitiveTypes(SimpleCData, native, addressOf, cstring, ws
469
513
  class c_wchar_p extends SimpleCData {
470
514
  static _size = native.POINTER_SIZE;
471
515
  static _type = CType.WSTRING;
516
+ static _isPointerValued = true;
472
517
  static _reader = (buf, off) => {
473
518
  const ptr = native.POINTER_SIZE === 8 ? buf.readBigUInt64LE(off) : BigInt(buf.readUInt32LE(off));
474
519
  if (!ptr) return null;
@@ -479,14 +524,14 @@ export function createPrimitiveTypes(SimpleCData, native, addressOf, cstring, ws
479
524
  val = wstring(val);
480
525
  }
481
526
  if (Buffer.isBuffer(val)) {
482
- _stringKeepalive(buf, off, val);
483
527
  _writePointerField(buf, off, addressOf(val));
528
+ _stringKeepalive(buf, off, val);
484
529
  } else if (val == null) {
485
- _stringKeepalive(buf, off, null);
486
530
  _writePointerField(buf, off, 0n);
487
- } else {
488
531
  _stringKeepalive(buf, off, null);
532
+ } else {
489
533
  _writePointerField(buf, off, val);
534
+ _stringKeepalive(buf, off, null);
490
535
  }
491
536
  };
492
537
  }
@@ -505,7 +550,7 @@ export function createPrimitiveTypes(SimpleCData, native, addressOf, cstring, ws
505
550
  const c_ulonglong = c_uint64;
506
551
 
507
552
  // Return all types
508
- return {
553
+ const types = {
509
554
  // Void
510
555
  c_void,
511
556
  // Signed integers
@@ -545,4 +590,6 @@ export function createPrimitiveTypes(SimpleCData, native, addressOf, cstring, ws
545
590
  c_longlong,
546
591
  c_ulonglong,
547
592
  };
593
+ for (const type of Object.values(types)) registerSimpleType(type);
594
+ return types;
548
595
  }
@@ -1,8 +1,8 @@
1
1
  /**
2
2
  * @file cache.js
3
3
  * @module utils/cache
4
- * @description Simple LRU (Least Recently Used) cache implementation for function caching.
5
- * Prevents unbounded memory growth in long-running applications.
4
+ * @description LRU function caching and weak-value type interning.
5
+ * Prevents unbounded cache retention in long-running applications.
6
6
  *
7
7
  * @example
8
8
  * import { LRUCache } from './utils/cache.js';
@@ -140,3 +140,35 @@ export class LRUCache {
140
140
  return this.cache.size;
141
141
  }
142
142
  }
143
+
144
+ const weakValues = new FinalizationRegistry(({ cache, key, ref }) => {
145
+ // A delayed finalizer must not remove a replacement for the same key.
146
+ if (cache.get(key) === ref) cache.delete(key);
147
+ });
148
+
149
+ /** Identity keys without retaining object/function types. */
150
+ export function createTypeKey() {
151
+ const identities = new WeakMap();
152
+ let next = 0;
153
+ return (type) => {
154
+ if (type === null || (typeof type !== "object" && typeof type !== "function")) {
155
+ const value = String(type);
156
+ return `${typeof type}:${value.length}:${value}`;
157
+ }
158
+ let id = identities.get(type);
159
+ if (id === undefined) {
160
+ id = `#${++next}`;
161
+ identities.set(type, id);
162
+ }
163
+ return id;
164
+ };
165
+ }
166
+
167
+ /** Store a weak value in a Map and remove its key when the value is collected. */
168
+ export function cacheWeakValue(cache, key, value) {
169
+ const previous = cache.get(key);
170
+ const ref = new WeakRef(value);
171
+ if (previous !== undefined) weakValues.unregister(previous);
172
+ cache.set(key, ref);
173
+ weakValues.register(value, { cache, key, ref }, ref);
174
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "node-ctypes",
3
- "version": "2.2.0",
3
+ "version": "2.4.0",
4
4
  "description": "Python ctypes-like FFI for Node.js using libffi",
5
5
  "author": "Damiano Mazzella",
6
6
  "license": "MIT",
@@ -27,10 +27,13 @@
27
27
  "scripts": {
28
28
  "build": "cmake-js compile --target ctypes",
29
29
  "build:debug": "cmake-js compile --target ctypes --debug",
30
+ "build:test-fixture": "cmake-js compile --target ctypes_test_fixture",
30
31
  "rebuild": "cmake-js rebuild --target ctypes",
31
32
  "clean": "cmake-js clean",
32
33
  "generate-ffi-headers": "node third-party/libffi_cmake/generate-headers.js",
33
34
  "test:types": "tsc -p tests/types/tsconfig.json",
35
+ "bench:koffi": "node tests/benchmarks/benchmark_koffi.js",
36
+ "bench:ffi": "node --experimental-ffi tests/benchmarks/benchmark_node_ffi.js",
34
37
  "docs": "typedoc",
35
38
  "docs:serve": "typedoc && npx serve docs"
36
39
  },