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
@@ -26,8 +26,8 @@
26
26
  * ```
27
27
  */
28
28
 
29
- import { writePointerField } from "../structures/helpers/common.js";
30
- import { flush, mirrorAddress, mirrorsActive } from "./mirror.js";
29
+ import { byrefOwners, isScalarSubclass, keepAlive, keepFunctionOwner, keptObject, kPointerMemory, memoryDomain, pointerOwner, scalarView, shareMemory, writePointerField } from "../structures/helpers/common.js";
30
+ import { flush, mirrorAddress, mirrorsActive, refresh } from "./mirror.js";
31
31
 
32
32
  /**
33
33
  * Gets the memory address of a buffer or pointer.
@@ -56,13 +56,18 @@ import { flush, mirrorAddress, mirrorsActive } from "./mirror.js";
56
56
  * ```
57
57
  */
58
58
  export function addressOf(ptr, alloc, native) {
59
+ // Puntatore: l'indirizzo del puntatore stesso (Python addressof(p)), non
60
+ // quello della memoria puntata.
61
+ if (ptr && typeof ptr === "object" && ptr._pointerType !== undefined) {
62
+ ptr = ptr._pointerSlot;
63
+ }
59
64
  // Object wrapper (SimpleCData, Structure, Union, array proxy) → unwrap al Buffer.
60
65
  // Le istanze di array sono Proxy su un Buffer: Buffer.isBuffer() è vero in JS
61
66
  // ma il nativo non vede un Buffer, quindi si usa sempre `_buffer` se presente.
62
67
  if (ptr && typeof ptr === "object" && Buffer.isBuffer(ptr._buffer)) {
63
68
  ptr = ptr._buffer;
64
69
  }
65
- if (Buffer.isBuffer(ptr)) {
70
+ if (Buffer.isBuffer(ptr) || ArrayBuffer.isView(ptr) || ptr instanceof ArrayBuffer) {
66
71
  // Native API returns the buffer's memory address in one V8 boundary
67
72
  // crossing. The fallback path below (tempBuf + writeValue) is kept
68
73
  // for backward compatibility with older .node binaries that do not
@@ -80,7 +85,8 @@ export function addressOf(ptr, alloc, native) {
80
85
  /**
81
86
  * Passes an object by reference (Python byref equivalent).
82
87
  *
83
- * Returns the underlying buffer of a SimpleCData instance or the buffer itself.
88
+ * Returns an owner-retaining byte view, or an address carrier for offsets
89
+ * outside the known buffer range.
84
90
  * This is useful for passing arguments to C functions that expect pointers.
85
91
  *
86
92
  * **Python ctypes Compatibility**:
@@ -91,7 +97,8 @@ export function addressOf(ptr, alloc, native) {
91
97
  * - SimpleCData instance (has _buffer property)
92
98
  * - Buffer object
93
99
  * - Structure instance (has _buffer property)
94
- * @returns {Buffer} The underlying buffer
100
+ * @param {number} [offset=0] - Signed byte offset
101
+ * @returns {Buffer|Object} Buffer view or owner-retaining address carrier
95
102
  * @throws {TypeError} If obj is not a ctypes instance or Buffer
96
103
  *
97
104
  * @example Pass SimpleCData by reference
@@ -121,16 +128,24 @@ export function addressOf(ptr, alloc, native) {
121
128
  * move_point(byref(point), 5, 10);
122
129
  * ```
123
130
  */
124
- export function byref(obj) {
125
- // SimpleCData instance or Structure instance - return its buffer
126
- if (obj && obj._buffer && Buffer.isBuffer(obj._buffer)) {
127
- return obj._buffer;
131
+ export function byref(obj, offset = 0, native) {
132
+ if (!Number.isSafeInteger(offset)) throw new TypeError("byref() offset must be a safe integer");
133
+ let buffer;
134
+ // Puntatore: la memoria del puntatore (T**), così una funzione C può
135
+ // scriverci un indirizzo e ri-puntarlo (Python byref(p)).
136
+ if (obj && typeof obj === "object" && obj._pointerType !== undefined) {
137
+ buffer = obj._pointerSlot;
128
138
  }
139
+ // SimpleCData instance or Structure instance - return its buffer
140
+ else if (obj && obj._buffer && Buffer.isBuffer(obj._buffer)) buffer = obj._buffer;
129
141
  // Buffer - return as-is
130
- if (Buffer.isBuffer(obj)) {
131
- return obj;
132
- }
133
- throw new TypeError("byref() argument must be a ctypes instance or Buffer");
142
+ else if (Buffer.isBuffer(obj)) buffer = obj;
143
+ if (buffer === undefined) throw new TypeError("byref() argument must be a ctypes instance or Buffer");
144
+ const type = obj._pointerType ?? obj._arrayType ?? (obj.constructor?._isSimpleCData || typeof obj.constructor?._buildStruct === "function" ? obj.constructor : obj._structDef);
145
+ const view = offset >= 0 && offset <= buffer.length ? buffer.subarray(offset) : { address: (mirrorAddress(buffer) ?? native.addressOf(buffer)) + BigInt(offset) };
146
+ if (!Buffer.isBuffer(view)) Object.defineProperty(view, "_as_parameter_", { value: view.address });
147
+ byrefOwners.set(view, { owner: obj, type, offset });
148
+ return view;
134
149
  }
135
150
 
136
151
  /**
@@ -177,32 +192,36 @@ export function byref(obj) {
177
192
  */
178
193
  export function cast(ptr, targetType, readValue, sizeof, ptrToBuffer, native) {
179
194
  // Validate inputs
180
- if (!ptr) {
195
+ if (!ptr && !(targetType?._pointerTo !== undefined || targetType?._isPointerValued === true)) {
181
196
  throw new TypeError("cast() requires a non-null pointer");
182
197
  }
183
198
  if (!targetType) {
184
199
  throw new TypeError("cast() requires a target type");
185
200
  }
201
+ if (ArrayBuffer.isView(ptr) && !Buffer.isBuffer(ptr)) ptr = Buffer.from(ptr.buffer, ptr.byteOffset, ptr.byteLength);
202
+ else if (ptr instanceof ArrayBuffer) ptr = Buffer.from(ptr);
186
203
 
187
204
  // PointerTypeDef — return a PointerInstance via fromAddress() or fromBuffer()
188
205
  // Python equivalent: cast(c_void_p(addr), POINTER(c_int32)) — read stored address
189
206
  // Python equivalent: cast(arr, POINTER(c_int32)) — pointer to arr's memory
190
207
  // Python equivalent: cast(p, POINTER(c_double)) — pointer to same memory as p
191
208
  if (typeof targetType === "object" && targetType._pointerTo !== undefined) {
209
+ if (!ptr) return targetType.fromAddress(0n);
192
210
  // PointerInstance — use its address/buffer (Python: cast(p, POINTER(OtherType)))
193
211
  if (ptr && typeof ptr === "object" && typeof ptr.address === "bigint") {
194
212
  if (ptr._buffer) {
195
213
  return targetType.fromBuffer(ptr._buffer);
196
214
  }
197
- return targetType.fromAddress(ptr.address);
215
+ return targetType.fromAddress(ptr.address, ptr);
198
216
  }
199
217
 
200
218
  // ctypes object with _buffer — distinguish data objects from pointer-value objects
201
219
  // Note: array proxies are Buffer.isBuffer()==true but also have ._buffer, so don't exclude Buffers
202
220
  if (ptr && typeof ptr === "object" && ptr._buffer && Buffer.isBuffer(ptr._buffer)) {
203
- // SimpleCData storing a pointer/address value (c_void_p, c_char_p, etc.)
204
- // → read the stored address value from the buffer
205
- if (ptr.constructor && ptr.constructor._isSimpleCData && ptr.constructor._type === native.CType.POINTER) {
221
+ // SimpleCData storing a pointer/address value (c_void_p, c_char_p,
222
+ // c_wchar_p) → read the stored address value from the buffer
223
+ const pointerValued = new Set([native.CType.POINTER, native.CType.STRING, native.CType.WSTRING]);
224
+ if (ptr.constructor && ptr.constructor._isSimpleCData && pointerValued.has(ptr.constructor._type)) {
206
225
  // This is a pointer-valued SimpleCData — read address from buffer
207
226
  const buf = ptr._buffer;
208
227
  let addr;
@@ -213,7 +232,8 @@ export function cast(ptr, targetType, readValue, sizeof, ptrToBuffer, native) {
213
232
  } else {
214
233
  throw new TypeError("cast(): buffer too small to contain a pointer");
215
234
  }
216
- return targetType.fromAddress(addr);
235
+ // Python: il risultato tiene viva la sorgente (la stringa di un c_char_p).
236
+ return targetType.fromAddress(addr, ptr);
217
237
  }
218
238
  // Array, Structure, Union — pointer to their data buffer
219
239
  // Python: cast(arr, POINTER(c_int32)) points to arr's memory
@@ -242,6 +262,15 @@ export function cast(ptr, targetType, readValue, sizeof, ptrToBuffer, native) {
242
262
  return targetType.fromAddress(addr);
243
263
  }
244
264
 
265
+ // c_void_p / c_char_p / c_wchar_p: an instance pointing to the source,
266
+ // which it keeps alive (Python: cast(buf, c_void_p).value == addressof(buf)).
267
+ if (typeof targetType === "function" && targetType._isSimpleCData === true && isPointerValued(targetType, native)) {
268
+ const result = new targetType();
269
+ writePointerField(result._buffer, 0, ptr == null || ptr === 0 || ptr === 0n ? 0n : castSourceAddress(ptr, native), native.POINTER_SIZE);
270
+ if (typeof ptr === "object") keepAlive(result._buffer, 0, ptr);
271
+ return result;
272
+ }
273
+
245
274
  // Struct type - return wrapper object
246
275
  if (typeof targetType === "object" && targetType.size !== undefined) {
247
276
  const buf = Buffer.isBuffer(ptr) ? ptr : ptrToBuffer(ptr, targetType.size);
@@ -270,6 +299,28 @@ export function cast(ptr, targetType, readValue, sizeof, ptrToBuffer, native) {
270
299
  return readValue(tempBuf, targetType, 0);
271
300
  }
272
301
 
302
+ function isPointerValued(type, native) {
303
+ return type._type === native.CType.POINTER || type._type === native.CType.STRING || type._type === native.CType.WSTRING;
304
+ }
305
+
306
+ // Address given by a cast() source, as Python's c_void_p.from_param: the value
307
+ // of pointers, c_void_p, c_char_p and c_wchar_p, the memory of the others.
308
+ function castSourceAddress(ptr, native) {
309
+ if (typeof ptr === "bigint") return ptr;
310
+ if (typeof ptr === "number") return BigInt(ptr);
311
+ if (ptr !== null && typeof ptr === "object") {
312
+ if (ptr._pointerType !== undefined) return ptr.address;
313
+ const T = ptr.constructor;
314
+ if (T?._isSimpleCData === true && isPointerValued(T, native)) {
315
+ return native.POINTER_SIZE === 8 ? ptr._buffer.readBigUInt64LE(0) : BigInt(ptr._buffer.readUInt32LE(0));
316
+ }
317
+ if (Buffer.isBuffer(ptr._buffer)) return addressOf(ptr._buffer, null, native);
318
+ if (Buffer.isBuffer(ptr)) return addressOf(ptr, null, native);
319
+ if (ptr._as_parameter_ !== undefined) return castSourceAddress(ptr._as_parameter_, native);
320
+ }
321
+ throw new TypeError("cast(): ptr must be a BigInt, number, Buffer, ctypes instance, or PointerInstance");
322
+ }
323
+
273
324
  /**
274
325
  * Buffer over the memory at an address, used by `from_address`, `cast` and
275
326
  * pointers (not exported: the public, Python-compatible way is
@@ -372,6 +423,7 @@ export function POINTER(baseType, sizeof, alloc, readValue, writeValue, c_void_p
372
423
  // calcolabile subito. Se è thunk, entrambi vengono rimpiazzati al primo
373
424
  // uso, senza mutare le chiusure dei trap.
374
425
  let baseSize;
426
+ let scalarSubclass = isScalarSubclass(baseType);
375
427
  let _lazyResolved = false;
376
428
  function resolveIfLazy() {
377
429
  if (!isLazyThunk || _lazyResolved) return;
@@ -384,6 +436,7 @@ export function POINTER(baseType, sizeof, alloc, readValue, writeValue, c_void_p
384
436
  // `baseSize` serve solo per pointer arithmetic che avviene dopo la
385
437
  // costruzione della struct, quando `resolved` è completamente definito.
386
438
  baseType = resolved;
439
+ scalarSubclass = isScalarSubclass(baseType);
387
440
  _lazyResolved = true;
388
441
  baseSize = typeof resolved === "object" ? resolved.size : sizeof(resolved);
389
442
  }
@@ -407,37 +460,53 @@ export function POINTER(baseType, sizeof, alloc, readValue, writeValue, c_void_p
407
460
 
408
461
  // Python: per tipi semplici e Structure/Union `contents` (e p[i] per le struct)
409
462
  // è un'istanza viva sulla memoria puntata, non una copia del valore.
410
- const hasInstances = () => typeof baseType === "function" && (baseType._isSimpleCData === true || typeof baseType._buildStruct === "function" || typeof baseType._buildUnion === "function");
411
- const isStructBase = () => typeof baseType === "function" && (typeof baseType._buildStruct === "function" || typeof baseType._buildUnion === "function");
463
+ // Array (Python POINTER(c_int * 3)): contents e p[i] sono istanze dell'array.
464
+ const isArrayBase = () => baseType !== null && (typeof baseType === "function" || typeof baseType === "object") && baseType._isArrayType === true;
465
+ const hasInstances = () => isArrayBase() || (typeof baseType === "function" && (baseType._isSimpleCData === true || typeof baseType._buildStruct === "function" || typeof baseType._buildUnion === "function"));
466
+ const isStructBase = () => scalarSubclass || isArrayBase() || (typeof baseType === "function" && (typeof baseType._buildStruct === "function" || typeof baseType._buildUnion === "function"));
412
467
 
413
468
  // POINTER(POINTER(T)) / POINTER(CFUNCTYPE): elementi puntatore, letti come
414
469
  // oggetto puntatore / funzione (NULL → null) e scritti come indirizzo.
415
470
  const isPointerBase = () => (typeof baseType === "object" && baseType !== null && baseType._pointerTo !== undefined) || (typeof baseType === "function" && baseType._isFuncPtr === true);
416
471
 
417
- function readPointerAt(buffer, address, offset) {
472
+ function readPointerAt(buffer, address, offset, owner) {
418
473
  const inBuffer = buffer && offset + baseSize <= buffer.length;
419
474
  const src = inBuffer ? buffer : native.ptrToBuffer(address + BigInt(offset), baseSize);
420
475
  const off = inBuffer ? offset : 0;
476
+ if (!inBuffer) shareMemory(src, owner, address + BigInt(offset) - owner.origin);
477
+ if (mirrorsActive) refresh(src, off, baseSize);
421
478
  const target = baseSize === 8 ? src.readBigUInt64LE(off) : BigInt(src.readUInt32LE(off));
479
+ const keep = pointerOwner(src, off, target);
422
480
  if (target === 0n) return null;
423
- return typeof baseType === "function" ? baseType(target) : baseType.fromAddress(target);
481
+ if (typeof baseType !== "function") return baseType.fromAddress(target, keep);
482
+ return keepFunctionOwner(baseType(target), keep);
424
483
  }
425
484
 
426
- function writePointerAt(buffer, address, offset, value) {
485
+ function writePointerAt(buffer, address, offset, value, owner) {
427
486
  if (buffer && offset + baseSize <= buffer.length) {
428
487
  writePointerField(buffer, offset, value, baseSize);
488
+ if (mirrorsActive) flush(buffer, offset, baseSize);
429
489
  return;
430
490
  }
431
491
  const target = native.ptrToBuffer(address + BigInt(offset), baseSize);
492
+ shareMemory(target, owner, address + BigInt(offset) - owner.origin);
432
493
  writePointerField(target, 0, value, baseSize);
433
494
  if (mirrorsActive) flush(target);
434
495
  }
435
496
 
436
- function instanceAt(buffer, address, offset) {
497
+ function instanceAt(buffer, address, offset, owner) {
498
+ if (scalarSubclass) {
499
+ if (buffer && offset + baseSize <= buffer.length) return scalarView(baseType, buffer.subarray(offset, offset + baseSize));
500
+ const view = native.ptrToBuffer(address + BigInt(offset), baseSize);
501
+ shareMemory(view, owner, address + BigInt(offset) - owner.origin);
502
+ return scalarView(baseType, view);
503
+ }
437
504
  if (buffer && offset + baseSize <= buffer.length) {
438
505
  return baseType.from_buffer(buffer, offset);
439
506
  }
440
- return baseType.from_address(address + BigInt(offset));
507
+ const result = baseType.from_address(address + BigInt(offset));
508
+ shareMemory(result._buffer, owner, address + BigInt(offset) - owner.origin);
509
+ return result;
441
510
  }
442
511
 
443
512
  // Scrittura a un indirizzo senza Buffer associato: per le primitive il
@@ -445,24 +514,26 @@ export function POINTER(baseType, sizeof, alloc, readValue, writeValue, c_void_p
445
514
  // lo copia all'indirizzo, invece di creare un Buffer esterno (~400 ns,
446
515
  // vietato in Electron).
447
516
  let scratch = null;
448
- function writeAtAddress(addr, value) {
449
- if (typeof baseType === "function" && baseType._isSimpleCData) {
517
+ function writeAtAddress(addr, value, owner) {
518
+ if (typeof baseType === "function" && baseType._isSimpleCData && !baseType._isPointerValued) {
450
519
  scratch ??= alloc(baseSize);
451
520
  baseType._writer(scratch, 0, value);
452
521
  native.writeMemory(scratch, 0, baseSize, addr);
453
522
  return;
454
523
  }
455
524
  const buf = native.ptrToBuffer(addr, baseSize);
525
+ shareMemory(buf, owner, addr - owner.origin);
456
526
  writeValue(buf, baseType, value, 0);
457
527
  }
458
528
 
459
529
  // Lettura a un indirizzo senza Buffer associato: per le primitive
460
530
  // readValue(indirizzo) evita il Buffer esterno di ptrToBuffer.
461
- function readAtAddress(addr) {
531
+ function readAtAddress(addr, owner) {
462
532
  if (typeof baseType === "function" && baseType._isSimpleCData) {
463
533
  return readValue(addr, baseType, 0);
464
534
  }
465
535
  const buf = native.ptrToBuffer(addr, baseSize);
536
+ shareMemory(buf, owner, addr - owner.origin);
466
537
  return readValue(buf, baseType, 0);
467
538
  }
468
539
 
@@ -470,13 +541,43 @@ export function POINTER(baseType, sizeof, alloc, readValue, writeValue, c_void_p
470
541
  * Creates a pointer instance with Python ctypes-compatible API.
471
542
  * Supports .contents property and [index] access for pointer arithmetic.
472
543
  */
473
- function createPointerInstance(addressOrBuffer) {
544
+ function createPointerInstance(addressOrBuffer, keep, memory) {
474
545
  // Risolvi il thunk lazy alla prima creazione di istanza: a questo
475
546
  // punto la classe target è sicuramente inizializzata.
476
547
  resolveIfLazy();
477
548
 
478
549
  let _address = 0n;
479
550
  let _buffer = null;
551
+ // Python `_objects`: ciò che deve restare vivo finché il puntatore punta
552
+ // lì (la sorgente di cast(), il puntatore da cui deriva add()).
553
+ let _objects = keep;
554
+ let _memory = memory;
555
+ if (keep?._pointerType !== undefined) _objects = keep._buffer ?? keep._objects;
556
+ if (_memory === undefined && _objects?.[kPointerMemory]) _memory = _objects;
557
+ // Memoria del puntatore (Python: un puntatore è un oggetto ctypes di
558
+ // POINTER_SIZE byte), creata alla prima richiesta di byref(p) /
559
+ // addressof(p). Da allora è lei a dare l'indirizzo: una funzione C che ci
560
+ // scrive (f(byref(p))) ri-punta p.
561
+ let _slot = null;
562
+
563
+ function sync() {
564
+ if (_slot === null) return;
565
+ const addr = native.POINTER_SIZE === 8 ? _slot.readBigUInt64LE(0) : BigInt(_slot.readUInt32LE(0));
566
+ if (addr !== _address) {
567
+ _address = addr;
568
+ _buffer = null;
569
+ _objects = undefined;
570
+ _memory = undefined;
571
+ keepAlive(_slot, 0, null);
572
+ }
573
+ }
574
+
575
+ function store() {
576
+ if (_slot === null) return;
577
+ if (native.POINTER_SIZE === 8) _slot.writeBigUInt64LE(BigInt.asUintN(64, _address), 0);
578
+ else _slot.writeUInt32LE(Number(BigInt.asUintN(32, _address)), 0);
579
+ keepAlive(_slot, 0, _memory ?? _buffer ?? _objects);
580
+ }
480
581
 
481
582
  if (addressOrBuffer === undefined || addressOrBuffer === null) {
482
583
  _address = 0n;
@@ -484,6 +585,9 @@ export function POINTER(baseType, sizeof, alloc, readValue, writeValue, c_void_p
484
585
  _address = addressOrBuffer;
485
586
  } else if (typeof addressOrBuffer === "number") {
486
587
  _address = BigInt(addressOrBuffer);
588
+ } else if (typeof addressOrBuffer === "object" && Buffer.isBuffer(addressOrBuffer._buffer)) {
589
+ // Istanza ctypes (array, struct): la sua memoria.
590
+ pointTo(addressOrBuffer._buffer);
487
591
  } else if (Buffer.isBuffer(addressOrBuffer)) {
488
592
  pointTo(addressOrBuffer);
489
593
  }
@@ -491,14 +595,48 @@ export function POINTER(baseType, sizeof, alloc, readValue, writeValue, c_void_p
491
595
  // Puntare a un Buffer; una copia di memoria nativa (memory/mirror.js)
492
596
  // vale il suo indirizzo originale, come un puntatore creato da indirizzo.
493
597
  function pointTo(buf) {
598
+ _objects = undefined;
599
+ _memory = undefined;
494
600
  const mirrored = mirrorAddress(buf);
495
601
  if (mirrored !== undefined) {
496
602
  _buffer = null;
497
603
  _address = mirrored;
498
- return;
604
+ _objects = buf;
605
+ const domain = memoryDomain(buf);
606
+ _memory = { owner: buf, root: domain.root, origin: mirrored - domain.offset - BigInt(buf.byteOffset) };
607
+ _memory[kPointerMemory] = true;
608
+ } else {
609
+ _buffer = buf;
610
+ _address = getBufferAddress(buf);
611
+ }
612
+ store();
613
+ }
614
+
615
+ function getMemory() {
616
+ if (_memory === undefined) {
617
+ let buffer = _buffer;
618
+ let address = _address;
619
+ if (buffer === null && _objects !== null && typeof _objects === "object") {
620
+ const known = _objects.constructor?._isPointerValued ? keptObject(_objects._buffer, 0) : _objects;
621
+ const candidate = Buffer.isBuffer(known) ? known : known?._buffer;
622
+ if (Buffer.isBuffer(candidate)) {
623
+ const base = getBufferAddress(candidate);
624
+ if (_address >= base && _address < base + BigInt(candidate.length)) {
625
+ buffer = candidate;
626
+ address = base;
627
+ }
628
+ }
629
+ }
630
+ const domain = buffer === null ? { root: {}, offset: 0n } : memoryDomain(buffer);
631
+ _memory = {
632
+ owner: buffer ?? _objects,
633
+ root: domain.root,
634
+ origin: buffer === null ? 0n : address - domain.offset - BigInt(buffer.byteOffset),
635
+ };
636
+ _memory[kPointerMemory] = true;
637
+ if (_slot !== null) keepAlive(_slot, 0, _memory);
499
638
  }
500
- _buffer = buf;
501
- _address = getBufferAddress(buf);
639
+ return _memory;
502
640
  }
503
641
 
504
642
  const instance = {
@@ -510,9 +648,28 @@ export function POINTER(baseType, sizeof, alloc, readValue, writeValue, c_void_p
510
648
  * Get the raw address as BigInt
511
649
  */
512
650
  get address() {
651
+ sync();
513
652
  return _address;
514
653
  },
515
654
 
655
+ /**
656
+ * Memoria del puntatore (POINTER_SIZE byte con l'indirizzo): ciò che
657
+ * byref(p) / addressof(p) passano al C.
658
+ */
659
+ get _pointerSlot() {
660
+ if (_slot === null) {
661
+ _slot = alloc(native.POINTER_SIZE);
662
+ store();
663
+ }
664
+ return _slot;
665
+ },
666
+
667
+ /** Oggetti tenuti vivi dal puntatore (Python `_objects`). */
668
+ get _objects() {
669
+ sync();
670
+ return getMemory();
671
+ },
672
+
516
673
  /**
517
674
  * Python ctypes compatible: the pointed object. For simple types and
518
675
  * Structure/Union classes it is a live instance on the pointed memory
@@ -520,25 +677,32 @@ export function POINTER(baseType, sizeof, alloc, readValue, writeValue, c_void_p
520
677
  * the pointer to it, assigning a plain value writes it.
521
678
  */
522
679
  get contents() {
680
+ sync();
523
681
  if (_address === 0n && !_buffer) {
524
682
  throw new Error("NULL pointer access");
525
683
  }
526
684
  if (isPointerBase()) {
527
- return readPointerAt(_buffer, _address, 0);
685
+ return readPointerAt(_buffer, _address, 0, getMemory());
528
686
  }
529
687
  if (hasInstances()) {
530
- return instanceAt(_buffer, _address, 0);
688
+ return instanceAt(_buffer, _address, 0, getMemory());
531
689
  }
532
690
  if (_buffer) {
533
691
  // We have the actual buffer, read from it
534
692
  return readValue(_buffer, baseType, 0);
535
693
  }
536
- return readAtAddress(_address);
694
+ return readAtAddress(_address, getMemory());
537
695
  },
538
696
 
539
697
  set contents(value) {
698
+ sync();
540
699
  // Python: assegnare un'istanza ri-punta il puntatore a quell'istanza.
541
- if (value !== null && typeof value === "object" && (value._isSimpleCDataInstance === true || value._structDef !== undefined) && Buffer.isBuffer(value._buffer)) {
700
+ if (value !== null && typeof value === "object" && (value._isSimpleCDataInstance === true || value._structDef !== undefined || value._arrayType !== undefined) && Buffer.isBuffer(value._buffer)) {
701
+ // Python accetta anche un'istanza di un altro tipo; una più piccola
702
+ // del tipo puntato farebbe leggere e scrivere oltre la sua memoria.
703
+ if (value._buffer.length < baseSize) {
704
+ throw new TypeError(`contents: ${value.constructor?.name ?? "instance"} (${value._buffer.length} bytes) is smaller than the pointed type (${baseSize} bytes)`);
705
+ }
542
706
  pointTo(value._buffer);
543
707
  return;
544
708
  }
@@ -546,11 +710,11 @@ export function POINTER(baseType, sizeof, alloc, readValue, writeValue, c_void_p
546
710
  throw new Error("NULL pointer access");
547
711
  }
548
712
  if (isPointerBase()) {
549
- writePointerAt(_buffer, _address, 0, value);
713
+ writePointerAt(_buffer, _address, 0, value, getMemory());
550
714
  } else if (_buffer) {
551
715
  writeValue(_buffer, baseType, value, 0);
552
716
  } else {
553
- writeAtAddress(_address, value);
717
+ writeAtAddress(_address, value, getMemory());
554
718
  }
555
719
  },
556
720
 
@@ -558,6 +722,7 @@ export function POINTER(baseType, sizeof, alloc, readValue, writeValue, c_void_p
558
722
  * Returns the buffer this pointer points to (if available)
559
723
  */
560
724
  get _buffer() {
725
+ sync();
561
726
  return _buffer;
562
727
  },
563
728
 
@@ -574,12 +739,12 @@ export function POINTER(baseType, sizeof, alloc, readValue, writeValue, c_void_p
574
739
  set(value) {
575
740
  if (Buffer.isBuffer(value)) {
576
741
  pointTo(value);
577
- } else if (typeof value === "bigint") {
578
- _address = value;
579
- _buffer = null;
580
- } else if (typeof value === "number") {
742
+ } else if (typeof value === "bigint" || typeof value === "number") {
581
743
  _address = BigInt(value);
582
744
  _buffer = null;
745
+ _objects = undefined;
746
+ _memory = undefined;
747
+ store();
583
748
  }
584
749
  },
585
750
 
@@ -587,6 +752,7 @@ export function POINTER(baseType, sizeof, alloc, readValue, writeValue, c_void_p
587
752
  * Check if pointer is NULL
588
753
  */
589
754
  get isNull() {
755
+ sync();
590
756
  return _address === 0n && !_buffer;
591
757
  },
592
758
 
@@ -594,12 +760,15 @@ export function POINTER(baseType, sizeof, alloc, readValue, writeValue, c_void_p
594
760
  * For compatibility - get pointer as buffer (8 bytes containing address)
595
761
  */
596
762
  toBuffer() {
763
+ sync();
597
764
  const buf = alloc(native.POINTER_SIZE);
598
765
  writeValue(buf, c_void_p, _address);
766
+ keepAlive(buf, 0, _memory ?? _buffer ?? _objects);
599
767
  return buf;
600
768
  },
601
769
 
602
770
  toString() {
771
+ sync();
603
772
  return `<${typeName} pointer at 0x${_address.toString(16)}>`;
604
773
  },
605
774
 
@@ -608,8 +777,10 @@ export function POINTER(baseType, sizeof, alloc, readValue, writeValue, c_void_p
608
777
  * `ptr + n`. The pointer keeps the same element type.
609
778
  */
610
779
  add(n) {
780
+ sync();
611
781
  const offsetBytes = BigInt(n) * BigInt(baseSize);
612
- return PointerType.fromAddress(_address + offsetBytes);
782
+ // Il nuovo puntatore tiene viva la memoria di questo (Python _objects).
783
+ return createPointerInstance(_address + offsetBytes, _buffer ?? _objects, getMemory());
613
784
  },
614
785
 
615
786
  /**
@@ -637,10 +808,10 @@ export function POINTER(baseType, sizeof, alloc, readValue, writeValue, c_void_p
637
808
  }
638
809
  const offset = index * baseSize;
639
810
  if (isPointerBase()) {
640
- return readPointerAt(_buffer, _address, offset);
811
+ return readPointerAt(_buffer, _address, offset, getMemory());
641
812
  }
642
813
  if (isStructBase()) {
643
- return instanceAt(_buffer, _address, offset);
814
+ return instanceAt(_buffer, _address, offset, getMemory());
644
815
  }
645
816
  if (_buffer && offset + baseSize <= _buffer.length) {
646
817
  if (typeof baseType === "function" && baseType._isSimpleCData) {
@@ -648,7 +819,7 @@ export function POINTER(baseType, sizeof, alloc, readValue, writeValue, c_void_p
648
819
  }
649
820
  return readValue(_buffer, baseType, offset);
650
821
  }
651
- return readAtAddress(_address + BigInt(offset));
822
+ return readAtAddress(_address + BigInt(offset), getMemory());
652
823
  }
653
824
  return Reflect.get(target, prop, receiver);
654
825
  },
@@ -662,14 +833,14 @@ export function POINTER(baseType, sizeof, alloc, readValue, writeValue, c_void_p
662
833
  }
663
834
  const offset = index * baseSize;
664
835
  if (isPointerBase()) {
665
- writePointerAt(_buffer, _address, offset, value);
836
+ writePointerAt(_buffer, _address, offset, value, getMemory());
666
837
  return true;
667
838
  }
668
839
  if (_buffer && offset + baseSize <= _buffer.length) {
669
840
  writeValue(_buffer, baseType, value, offset);
670
841
  return true;
671
842
  }
672
- writeAtAddress(_address + BigInt(offset), value);
843
+ writeAtAddress(_address + BigInt(offset), value, getMemory());
673
844
  return true;
674
845
  }
675
846
  return Reflect.set(target, prop, value, receiver);
@@ -717,8 +888,8 @@ export function POINTER(baseType, sizeof, alloc, readValue, writeValue, c_void_p
717
888
  * @param {bigint|number} address - Memory address
718
889
  * @returns {Object} Pointer instance
719
890
  */
720
- fromAddress(address) {
721
- return createPointerInstance(typeof address === "bigint" ? address : BigInt(address));
891
+ fromAddress(address, keep) {
892
+ return createPointerInstance(typeof address === "bigint" ? address : BigInt(address), keep);
722
893
  },
723
894
 
724
895
  /**
@@ -783,14 +954,16 @@ export function pointer(obj, POINTER_fn, sizeof, alloc, readValue, writeValue, c
783
954
  let targetBuffer;
784
955
  let baseType;
785
956
 
786
- if (Buffer.isBuffer(obj)) {
787
- targetBuffer = obj;
788
- baseType = c_void_p; // Generic pointer
789
- } else if (obj && obj._buffer) {
790
- // Structure/Union instance or SimpleCData with _buffer
957
+ // Le istanze di array sono Proxy su un Buffer (Buffer.isBuffer è vero): la
958
+ // loro memoria è `_buffer`, controllato per primo.
959
+ if (obj !== null && typeof obj === "object" && Buffer.isBuffer(obj._buffer)) {
960
+ // Structure/Union instance, array or SimpleCData with _buffer
791
961
  targetBuffer = obj._buffer;
792
962
  // Get the base type for POINTER creation
793
- if (obj.constructor && obj.constructor._type) {
963
+ if (obj._arrayType !== undefined) {
964
+ // Python: pointer(c_int * 3 instance) è un POINTER(c_int * 3).
965
+ baseType = obj._arrayType;
966
+ } else if (obj.constructor && obj.constructor._type) {
794
967
  // SimpleCData instance - use the class itself (c_int32, c_double, etc.)
795
968
  baseType = obj.constructor;
796
969
  } else if (obj._structDef) {
@@ -799,6 +972,9 @@ export function pointer(obj, POINTER_fn, sizeof, alloc, readValue, writeValue, c
799
972
  } else {
800
973
  baseType = c_void_p;
801
974
  }
975
+ } else if (Buffer.isBuffer(obj)) {
976
+ targetBuffer = obj;
977
+ baseType = c_void_p; // Generic pointer
802
978
  } else {
803
979
  throw new TypeError("pointer() argument must be a ctypes instance or Buffer");
804
980
  }
@@ -11,7 +11,6 @@
11
11
  * console.log(`Wide char size: ${WCHAR_SIZE} bytes`);
12
12
  */
13
13
 
14
- import { createRequire } from "node:module";
15
14
  import path from "node:path";
16
15
 
17
16
  /**