node-ctypes 1.14.0 → 2.0.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.
@@ -61,6 +61,14 @@ export function createMemoryOps(deps) {
61
61
  if (type && type._buffer && type.constructor && type.constructor._isSimpleCData) {
62
62
  return type.constructor._size;
63
63
  }
64
+ // Structure/Union instance (Python: sizeof(instance))
65
+ if (type && typeof type === "object" && type._structDef !== undefined && typeof type._structDef.size === "number") {
66
+ return type._structDef.size;
67
+ }
68
+ // Buffer, create_string_buffer() o istanza di array: dimensione in byte
69
+ if (Buffer.isBuffer(type)) {
70
+ return type.byteLength;
71
+ }
64
72
  // Structure class
65
73
  if (typeof type === "function" && type.prototype instanceof getStructure()) {
66
74
  const def = type._structDef || type._buildStruct();
@@ -76,9 +84,13 @@ export function createMemoryOps(deps) {
76
84
  return type.size;
77
85
  }
78
86
  // Array type wrapper
79
- if (typeof type === "object" && type !== null && typeof type.getSize === "function") {
87
+ if ((typeof type === "object" || (typeof type === "function" && type._isArrayType === true)) && type !== null && typeof type.getSize === "function") {
80
88
  return type.getSize();
81
89
  }
90
+ // CFUNCTYPE type: function pointer
91
+ if (typeof type === "function" && type._isFuncPtr === true) {
92
+ return deps.native.POINTER_SIZE;
93
+ }
82
94
  throw new TypeError("sizeof: unsupported type. Use SimpleCData classes like c_int32, c_uint64, etc.");
83
95
  }
84
96
 
@@ -86,23 +98,32 @@ export function createMemoryOps(deps) {
86
98
  * Legge un valore tipato da buffer o da address raw.
87
99
  * Python: analogo a dereferenziare `pointer.contents`.
88
100
  */
101
+ // Un oggetto puntatore (POINTER(T)) vale il suo Buffer o il suo indirizzo:
102
+ // es. gli argomenti POINTER dei callback passati a readValue/writeValue.
103
+ const pointerTarget = (ptr) => (ptr._buffer !== null ? ptr._buffer : ptr.address);
104
+
89
105
  function readValue(ptr, type, offset = 0) {
90
106
  if (typeof offset !== "number" || offset < 0) {
91
107
  throw new RangeError("offset must be a non-negative number");
92
108
  }
109
+ if (ptr !== null && typeof ptr === "object" && ptr._pointerType !== undefined) {
110
+ ptr = pointerTarget(ptr);
111
+ }
93
112
 
94
113
  // SimpleCData class: usa _reader diretto
95
114
  if (typeof type === "function" && type._isSimpleCData) {
96
115
  if (Buffer.isBuffer(ptr)) {
97
116
  const size = type._size || sizeof(type);
98
117
  if (offset + size > ptr.length) {
99
- throw new RangeError(
100
- `Read would exceed buffer bounds (offset: ${offset}, size: ${size}, buffer length: ${ptr.length})`,
101
- );
118
+ throw new RangeError(`Read would exceed buffer bounds (offset: ${offset}, size: ${size}, buffer length: ${ptr.length})`);
102
119
  }
103
120
  return type._reader(ptr, offset);
104
121
  }
105
122
  if (typeof ptr === "bigint" || typeof ptr === "number") {
123
+ const nativeType = deps.nativeReadTypes !== undefined ? deps.nativeReadTypes.get(type) : undefined;
124
+ if (nativeType !== undefined && ptr !== 0n && ptr !== 0) {
125
+ return deps.native.readValue(ptr, nativeType, offset);
126
+ }
106
127
  const size = type._size || sizeof(type);
107
128
  const buf = ptrToBuffer(ptr, size + offset);
108
129
  return type._reader(buf, offset);
@@ -135,6 +156,12 @@ export function createMemoryOps(deps) {
135
156
  if (typeof offset !== "number" || offset < 0) {
136
157
  throw new RangeError("offset must be a non-negative number");
137
158
  }
159
+ if (ptr !== null && typeof ptr === "object" && ptr._pointerType !== undefined) {
160
+ ptr = pointerTarget(ptr);
161
+ if (typeof ptr === "bigint") {
162
+ ptr = ptrToBuffer(ptr, offset + sizeof(type));
163
+ }
164
+ }
138
165
 
139
166
  // SimpleCData class: usa _writer diretto
140
167
  if (typeof type === "function" && type._isSimpleCData) {
@@ -143,9 +170,7 @@ export function createMemoryOps(deps) {
143
170
  }
144
171
  const size = type._size || sizeof(type);
145
172
  if (offset + size > ptr.length) {
146
- throw new RangeError(
147
- `Write would exceed buffer bounds (offset: ${offset}, size: ${size}, buffer length: ${ptr.length})`,
148
- );
173
+ throw new RangeError(`Write would exceed buffer bounds (offset: ${offset}, size: ${size}, buffer length: ${ptr.length})`);
149
174
  }
150
175
  type._writer(ptr, offset, value);
151
176
  return type._size;
@@ -26,6 +26,8 @@
26
26
  * ```
27
27
  */
28
28
 
29
+ import { writePointerField } from "../structures/helpers/common.js";
30
+
29
31
  /**
30
32
  * Gets the memory address of a buffer or pointer.
31
33
  *
@@ -53,8 +55,10 @@
53
55
  * ```
54
56
  */
55
57
  export function addressOf(ptr, alloc, native) {
56
- // Object wrapper (SimpleCData, Structure, Union, array proxy) → unwrap al Buffer
57
- if (!Buffer.isBuffer(ptr) && ptr && ptr._buffer && Buffer.isBuffer(ptr._buffer)) {
58
+ // Object wrapper (SimpleCData, Structure, Union, array proxy) → unwrap al Buffer.
59
+ // Le istanze di array sono Proxy su un Buffer: Buffer.isBuffer() è vero in JS
60
+ // ma il nativo non vede un Buffer, quindi si usa sempre `_buffer` se presente.
61
+ if (ptr && typeof ptr === "object" && Buffer.isBuffer(ptr._buffer)) {
58
62
  ptr = ptr._buffer;
59
63
  }
60
64
  if (Buffer.isBuffer(ptr)) {
@@ -298,6 +302,17 @@ export function ptrToBuffer(address, size, native) {
298
302
  return native.ptrToBuffer(address, size);
299
303
  }
300
304
 
305
+ // Indice per chiavi composte solo da cifre ("0", "12"); -1 altrimenti.
306
+ // Equivale a /^\d+$/ + parseInt senza eseguire una regex ad ogni accesso.
307
+ function digitIndex(prop) {
308
+ if (typeof prop !== "string" || prop.length === 0) return -1;
309
+ for (let i = 0; i < prop.length; i++) {
310
+ const c = prop.charCodeAt(i);
311
+ if (c < 48 || c > 57) return -1;
312
+ }
313
+ return parseInt(prop, 10);
314
+ }
315
+
301
316
  /**
302
317
  * Creates a POINTER type for a base type.
303
318
  *
@@ -365,7 +380,9 @@ export function POINTER(baseType, sizeof, alloc, readValue, writeValue, c_void_p
365
380
  typeof baseType._buildStruct !== "function" &&
366
381
  typeof baseType._buildUnion !== "function" &&
367
382
  !baseType._pointerTo &&
368
- !baseType._isStructType;
383
+ !baseType._isStructType &&
384
+ !baseType._isArrayType &&
385
+ !baseType._isFuncPtr;
369
386
 
370
387
  // Se non è thunk, `baseType` rimane il valore passato e `baseSize` è
371
388
  // calcolabile subito. Se è thunk, entrambi vengono rimpiazzati al primo
@@ -390,9 +407,7 @@ export function POINTER(baseType, sizeof, alloc, readValue, writeValue, c_void_p
390
407
  baseSize = typeof baseType === "object" ? baseType.size : sizeof(baseType);
391
408
  }
392
409
 
393
- const typeName = isLazyThunk
394
- ? "lazy"
395
- : typeof baseType === "object" ? "struct" : baseType._type || baseType.name || "unknown";
410
+ const typeName = isLazyThunk ? "lazy" : typeof baseType === "object" ? "struct" : baseType._type || baseType.name || "unknown";
396
411
 
397
412
  /**
398
413
  * Helper to get buffer's memory address using native writeValue
@@ -406,6 +421,46 @@ export function POINTER(baseType, sizeof, alloc, readValue, writeValue, c_void_p
406
421
  return BigInt(tempBuf.readUInt32LE(0));
407
422
  }
408
423
 
424
+ // Python: per tipi semplici e Structure/Union `contents` (e p[i] per le struct)
425
+ // è un'istanza viva sulla memoria puntata, non una copia del valore.
426
+ const hasInstances = () => typeof baseType === "function" && (baseType._isSimpleCData === true || typeof baseType._buildStruct === "function" || typeof baseType._buildUnion === "function");
427
+ const isStructBase = () => typeof baseType === "function" && (typeof baseType._buildStruct === "function" || typeof baseType._buildUnion === "function");
428
+
429
+ // POINTER(POINTER(T)) / POINTER(CFUNCTYPE): elementi puntatore, letti come
430
+ // oggetto puntatore / funzione (NULL → null) e scritti come indirizzo.
431
+ const isPointerBase = () => (typeof baseType === "object" && baseType !== null && baseType._pointerTo !== undefined) || (typeof baseType === "function" && baseType._isFuncPtr === true);
432
+
433
+ function readPointerAt(buffer, address, offset) {
434
+ const inBuffer = buffer && offset + baseSize <= buffer.length;
435
+ const src = inBuffer ? buffer : native.ptrToBuffer(address + BigInt(offset), baseSize);
436
+ const off = inBuffer ? offset : 0;
437
+ const target = baseSize === 8 ? src.readBigUInt64LE(off) : BigInt(src.readUInt32LE(off));
438
+ if (target === 0n) return null;
439
+ return typeof baseType === "function" ? baseType(target) : baseType.fromAddress(target);
440
+ }
441
+
442
+ function writePointerAt(buffer, address, offset, value) {
443
+ const inBuffer = buffer && offset + baseSize <= buffer.length;
444
+ writePointerField(inBuffer ? buffer : native.ptrToBuffer(address + BigInt(offset), baseSize), inBuffer ? offset : 0, value, baseSize);
445
+ }
446
+
447
+ function instanceAt(buffer, address, offset) {
448
+ if (buffer && offset + baseSize <= buffer.length) {
449
+ return baseType.from_buffer(buffer, offset);
450
+ }
451
+ return baseType.from_address(address + BigInt(offset));
452
+ }
453
+
454
+ // Lettura a un indirizzo senza Buffer associato: per le primitive
455
+ // readValue(indirizzo) evita il Buffer esterno di ptrToBuffer.
456
+ function readAtAddress(addr) {
457
+ if (typeof baseType === "function" && baseType._isSimpleCData) {
458
+ return readValue(addr, baseType, 0);
459
+ }
460
+ const buf = native.ptrToBuffer(addr, baseSize);
461
+ return readValue(buf, baseType, 0);
462
+ }
463
+
409
464
  /**
410
465
  * Creates a pointer instance with Python ctypes-compatible API.
411
466
  * Supports .contents property and [index] access for pointer arithmetic.
@@ -443,27 +498,41 @@ export function POINTER(baseType, sizeof, alloc, readValue, writeValue, c_void_p
443
498
  },
444
499
 
445
500
  /**
446
- * Python ctypes compatible: get/set the value at the pointed location.
447
- * In Python: p.contents returns the dereferenced value.
501
+ * Python ctypes compatible: the pointed object. For simple types and
502
+ * Structure/Union classes it is a live instance on the pointed memory
503
+ * (`p.contents.value`, `p.contents.x`); assigning an instance re-points
504
+ * the pointer to it, assigning a plain value writes it.
448
505
  */
449
506
  get contents() {
450
507
  if (_address === 0n && !_buffer) {
451
508
  throw new Error("NULL pointer access");
452
509
  }
510
+ if (isPointerBase()) {
511
+ return readPointerAt(_buffer, _address, 0);
512
+ }
513
+ if (hasInstances()) {
514
+ return instanceAt(_buffer, _address, 0);
515
+ }
453
516
  if (_buffer) {
454
517
  // We have the actual buffer, read from it
455
518
  return readValue(_buffer, baseType, 0);
456
519
  }
457
- // We only have address - need native support to read
458
- const buf = native.ptrToBuffer(_address, baseSize);
459
- return readValue(buf, baseType, 0);
520
+ return readAtAddress(_address);
460
521
  },
461
522
 
462
523
  set contents(value) {
524
+ // Python: assegnare un'istanza ri-punta il puntatore a quell'istanza.
525
+ if (value !== null && typeof value === "object" && (value._isSimpleCDataInstance === true || value._structDef !== undefined) && Buffer.isBuffer(value._buffer)) {
526
+ _buffer = value._buffer;
527
+ _address = getBufferAddress(value._buffer);
528
+ return;
529
+ }
463
530
  if (_address === 0n && !_buffer) {
464
531
  throw new Error("NULL pointer access");
465
532
  }
466
- if (_buffer) {
533
+ if (isPointerBase()) {
534
+ writePointerAt(_buffer, _address, 0, value);
535
+ } else if (_buffer) {
467
536
  writeValue(_buffer, baseType, value, 0);
468
537
  } else {
469
538
  const buf = native.ptrToBuffer(_address, baseSize);
@@ -548,31 +617,41 @@ export function POINTER(baseType, sizeof, alloc, readValue, writeValue, c_void_p
548
617
  return new Proxy(instance, {
549
618
  get(target, prop, receiver) {
550
619
  // Numeric index access: p[0], p[1], etc.
551
- if (typeof prop === "string" && /^\d+$/.test(prop)) {
552
- const index = parseInt(prop, 10);
620
+ const index = digitIndex(prop);
621
+ if (index >= 0) {
553
622
  if (target.isNull) {
554
623
  throw new Error("NULL pointer access");
555
624
  }
556
625
  const offset = index * baseSize;
626
+ if (isPointerBase()) {
627
+ return readPointerAt(_buffer, _address, offset);
628
+ }
629
+ if (isStructBase()) {
630
+ return instanceAt(_buffer, _address, offset);
631
+ }
557
632
  if (_buffer && offset + baseSize <= _buffer.length) {
633
+ if (typeof baseType === "function" && baseType._isSimpleCData) {
634
+ return baseType._reader(_buffer, offset);
635
+ }
558
636
  return readValue(_buffer, baseType, offset);
559
637
  }
560
- // Use native to read at address + offset
561
- const addr = _address + BigInt(offset);
562
- const buf = native.ptrToBuffer(addr, baseSize);
563
- return readValue(buf, baseType, 0);
638
+ return readAtAddress(_address + BigInt(offset));
564
639
  }
565
640
  return Reflect.get(target, prop, receiver);
566
641
  },
567
642
 
568
643
  set(target, prop, value, receiver) {
569
644
  // Numeric index access: p[0] = value, p[1] = value, etc.
570
- if (typeof prop === "string" && /^\d+$/.test(prop)) {
571
- const index = parseInt(prop, 10);
645
+ const index = digitIndex(prop);
646
+ if (index >= 0) {
572
647
  if (target.isNull) {
573
648
  throw new Error("NULL pointer access");
574
649
  }
575
650
  const offset = index * baseSize;
651
+ if (isPointerBase()) {
652
+ writePointerAt(_buffer, _address, offset, value);
653
+ return true;
654
+ }
576
655
  if (_buffer && offset + baseSize <= _buffer.length) {
577
656
  writeValue(_buffer, baseType, value, offset);
578
657
  return true;
@@ -595,8 +674,14 @@ export function POINTER(baseType, sizeof, alloc, readValue, writeValue, c_void_p
595
674
  // Getter dinamici: se `baseType` è un thunk, viene risolto al primo
596
675
  // accesso — così l'uso come `POINTER(() => Node)` in field type resta
597
676
  // Python-compatibile senza forzare l'utente a invalidare manualmente.
598
- get _pointerTo() { resolveIfLazy(); return baseType; },
599
- get _baseSize() { resolveIfLazy(); return baseSize; },
677
+ get _pointerTo() {
678
+ resolveIfLazy();
679
+ return baseType;
680
+ },
681
+ get _baseSize() {
682
+ resolveIfLazy();
683
+ return baseSize;
684
+ },
600
685
  size: native.POINTER_SIZE,
601
686
 
602
687
  /**
@@ -679,7 +764,7 @@ export function POINTER(baseType, sizeof, alloc, readValue, writeValue, c_void_p
679
764
  * ```javascript
680
765
  * const x = new c_int32(42);
681
766
  * const p = pointer(x);
682
- * console.log(p.contents); // 42
767
+ * console.log(p.contents.value); // 42
683
768
  * p.contents = 100;
684
769
  * console.log(x.value); // 100
685
770
  * ```
@@ -699,9 +784,8 @@ export function pointer(obj, POINTER_fn, sizeof, alloc, readValue, writeValue, c
699
784
  // SimpleCData instance - use the class itself (c_int32, c_double, etc.)
700
785
  baseType = obj.constructor;
701
786
  } else if (obj._structDef) {
702
- // Structure/Union instance - use the struct def object
703
- // (obj.constructor is a bound function from Proxy, so we use _structDef directly)
704
- baseType = obj._structDef;
787
+ // Structure/Union instance: the class, so `.contents` is an instance of it (Python parity)
788
+ baseType = typeof obj.constructor === "function" && obj.constructor._fields_ !== undefined ? obj.constructor : obj._structDef;
705
789
  } else {
706
790
  baseType = c_void_p;
707
791
  }
@@ -120,3 +120,23 @@ export function WinError(code, WinDLL, alloc, c_uint32, c_void, c_void_p) {
120
120
  err.winerror = code;
121
121
  return err;
122
122
  }
123
+
124
+ /**
125
+ * Raised when a foreign function call cannot convert one of the passed
126
+ * arguments (Python ctypes `ctypes.ArgumentError`). Subclass of `TypeError`.
127
+ *
128
+ * @example
129
+ * ```javascript
130
+ * try {
131
+ * abs("12");
132
+ * } catch (e) {
133
+ * if (e instanceof ArgumentError) console.log(e.message); // "argument 1: TypeError: ..."
134
+ * }
135
+ * ```
136
+ */
137
+ export class ArgumentError extends TypeError {
138
+ constructor(message) {
139
+ super(message);
140
+ this.name = "ArgumentError";
141
+ }
142
+ }