node-ctypes 2.1.1 → 2.3.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 (36) hide show
  1. package/README.md +98 -13
  2. package/build/Release/ctypes-darwin-arm64.node +0 -0
  3. package/build/Release/ctypes-darwin-x64.node +0 -0
  4. package/build/Release/ctypes-linux-arm64-musl.node +0 -0
  5. package/build/Release/ctypes-linux-arm64.node +0 -0
  6. package/build/Release/ctypes-linux-x64-musl.node +0 -0
  7. package/build/Release/ctypes-linux-x64.node +0 -0
  8. package/build/Release/ctypes-win32-arm64.node +0 -0
  9. package/build/Release/ctypes-win32-x64.node +0 -0
  10. package/lib/core/Library.js +86 -76
  11. package/lib/core/callback.js +10 -17
  12. package/lib/core/conversions.js +193 -3
  13. package/lib/core/funcptr.js +67 -52
  14. package/lib/core/lazy-loader.js +10 -4
  15. package/lib/core/types.js +196 -98
  16. package/lib/index.d.ts +193 -47
  17. package/lib/index.js +51 -28
  18. package/lib/memory/buffer.js +66 -19
  19. package/lib/memory/mirror.js +283 -0
  20. package/lib/memory/operations.js +59 -42
  21. package/lib/memory/pointer.js +180 -61
  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/structures/Structure.js +260 -172
  26. package/lib/structures/Union.js +10 -21
  27. package/lib/structures/helpers/array.js +235 -92
  28. package/lib/structures/helpers/bitfield.js +66 -150
  29. package/lib/structures/helpers/common.js +115 -15
  30. package/lib/structures/helpers/layout.js +131 -0
  31. package/lib/structures/helpers/struct.js +144 -400
  32. package/lib/structures/helpers/union.js +132 -142
  33. package/lib/structures/helpers/wrap.js +29 -17
  34. package/lib/types/SimpleCData.js +14 -7
  35. package/lib/types/primitives.js +130 -101
  36. package/package.json +2 -1
@@ -27,6 +27,8 @@
27
27
  * ```
28
28
  */
29
29
 
30
+ import { mirrorAddress } from "./mirror.js";
31
+
30
32
  /**
31
33
  * Allocates a zero-initialized buffer of the specified size.
32
34
  *
@@ -99,7 +101,7 @@ export function decodeWide(buf, wcharSize) {
99
101
  for (let off = 0; off + 3 < buf.length; off += 4) {
100
102
  const cp = buf.readUInt32LE(off);
101
103
  if (cp === 0) break;
102
- out += String.fromCodePoint(cp);
104
+ out += String.fromCodePoint(cp > 0x10ffff ? 0xfffd : cp);
103
105
  }
104
106
  return out;
105
107
  }
@@ -390,7 +392,7 @@ export function create_unicode_buffer(init, size, native) {
390
392
  * ```
391
393
  */
392
394
  export function string_at(address, size, native) {
393
- return native.readCString(address, size);
395
+ return native.readCString(stringSource(address, native), size);
394
396
  }
395
397
 
396
398
  /**
@@ -418,10 +420,20 @@ export function string_at(address, size, native) {
418
420
  * ```
419
421
  */
420
422
  export function wstring_at(address, size, native) {
421
- if (address === null || address === undefined) {
422
- return null;
423
- }
424
- return native.readWString(address, size);
423
+ return native.readWString(stringSource(address, native), size);
424
+ }
425
+
426
+ /**
427
+ * Source of string_at / wstring_at, as Python's c_void_p.from_param: the
428
+ * memory of instances and arrays, the value of pointers, c_void_p, c_char_p
429
+ * and c_wchar_p, `_as_parameter_`. Buffer or address; NULL gives null.
430
+ */
431
+ function stringSource(value, native) {
432
+ if (value === null || value === undefined || typeof value === "bigint" || typeof value === "number") return value;
433
+ // Array proxies pass Buffer.isBuffer but are resolved through _buffer.
434
+ if (Buffer.isBuffer(value) && value._buffer === undefined) return mirrorAddress(value) ?? value;
435
+ const memory = memoryOf(value, native, "address", true);
436
+ return memory instanceof Uint8Array && !Buffer.isBuffer(memory) ? Buffer.from(memory.buffer, memory.byteOffset, memory.byteLength) : memory;
425
437
  }
426
438
 
427
439
  /**
@@ -447,25 +459,54 @@ export function wstring_at(address, size, native) {
447
459
  * ```
448
460
  */
449
461
  export function memmove(dst, src, count, native) {
450
- const srcBuf = memoryOf(src, count, native, "src");
451
- srcBuf.copy(memoryOf(dst, count, native, "dst"), 0, 0, count);
462
+ const to = memoryOf(dst, native, "dst");
463
+ const from = memoryOf(src, native, "src");
464
+ // Come Buffer.copy, la copia si ferma alla fine dei Buffer coinvolti.
465
+ let n = count;
466
+ if (typeof to !== "bigint") n = Math.min(n, to.length);
467
+ if (typeof from !== "bigint") n = Math.min(n, from.length);
468
+ if (n <= 0) return;
469
+ // TypedArray.set gestisce anche la sovrapposizione (stesso ArrayBuffer).
470
+ if (typeof to !== "bigint" && typeof from !== "bigint") to.set(n === from.length ? from : from.subarray(0, n));
471
+ else native.memmove(to, from, n);
452
472
  }
453
473
 
454
- // Memoria di un argomento di memmove/memset, come Python: Buffer, istanze
455
- // ctypes (struct, array, c_*), puntatori o un indirizzo (BigInt/number).
456
- function memoryOf(value, count, native, name) {
474
+ // Memoria di un argomento di memmove/memset, come Python: Buffer, ogni
475
+ // TypedArray/DataView/ArrayBuffer (come vista a byte), istanze ctypes (struct,
476
+ // array, c_*), puntatori o un indirizzo (BigInt/number).
477
+ // Gli indirizzi (anche quello originale di una copia, memory/mirror.js) sono
478
+ // letti e scritti dal nativo, senza creare un Buffer esterno.
479
+ function memoryOf(value, native, name, allowNull = false) {
457
480
  if (value !== null && typeof value === "object") {
458
- if (Buffer.isBuffer(value._buffer)) return value._buffer;
459
- if (value._pointerType !== undefined) return native.ptrToBuffer(value.address, count);
460
- if (value instanceof Uint8Array) return value;
461
- }
462
- if (typeof value === "bigint" || typeof value === "number") {
463
- if (!value) throw new TypeError(`${name} is a NULL pointer`);
464
- return native.ptrToBuffer(value, count);
481
+ // c_void_p / c_char_p / c_wchar_p: the memory they point to, as in Python.
482
+ const T = value.constructor;
483
+ if (T?._isSimpleCData === true && (T._type === native.CType.POINTER || T._type === native.CType.STRING || T._type === native.CType.WSTRING)) {
484
+ const slot = value._buffer;
485
+ return addressOrNull(native.POINTER_SIZE === 8 ? slot.readBigUInt64LE(0) : BigInt(slot.readUInt32LE(0)), name, allowNull);
486
+ }
487
+ if (Buffer.isBuffer(value._buffer)) return mirrorAddress(value._buffer) ?? value._buffer;
488
+ if (value._pointerType !== undefined) return addressOrNull(value.address, name, allowNull);
489
+ if (ArrayBuffer.isView(value)) {
490
+ return mirrorAddress(value) ?? (value instanceof Uint8Array ? value : new Uint8Array(value.buffer, value.byteOffset, value.byteLength));
491
+ }
492
+ if (value instanceof ArrayBuffer || (typeof SharedArrayBuffer === "function" && value instanceof SharedArrayBuffer)) {
493
+ return new Uint8Array(value);
494
+ }
495
+ if (value._as_parameter_ !== undefined) return memoryOf(value._as_parameter_, native, name, allowNull);
465
496
  }
497
+ if (typeof value === "bigint" || typeof value === "number") return addressOrNull(value, name, allowNull);
498
+ if (allowNull && value === null) return null;
466
499
  throw new TypeError(`${name} must be a Buffer, a ctypes instance, a pointer or an address`);
467
500
  }
468
501
 
502
+ function addressOrNull(value, name, allowNull = false) {
503
+ if (!value) {
504
+ if (allowNull) return null;
505
+ throw new TypeError(`${name} is a NULL pointer`);
506
+ }
507
+ return BigInt(value);
508
+ }
509
+
469
510
  /**
470
511
  * Fills memory with a byte value (like C's memset).
471
512
  *
@@ -487,5 +528,11 @@ function memoryOf(value, count, native, name) {
487
528
  * ```
488
529
  */
489
530
  export function memset(dst, value, count, native) {
490
- memoryOf(dst, count, native, "dst").fill(value, 0, count);
531
+ const to = memoryOf(dst, native, "dst");
532
+ if (typeof to !== "bigint") {
533
+ // Come memmove, si ferma alla fine della memoria JS.
534
+ to.fill(value, 0, Math.max(0, Math.min(count, to.length)));
535
+ } else if (count > 0) {
536
+ native.memmove(to, Buffer.alloc(count, value), count);
537
+ }
491
538
  }
@@ -0,0 +1,283 @@
1
+ /**
2
+ * @file mirror.js
3
+ * @module memory/mirror
4
+ * @description Memory access where external buffers are not allowed.
5
+ *
6
+ * Electron (V8 memory cage) forbids Buffers over memory not allocated by V8,
7
+ * so the library cannot create a view of native memory. There, the view
8
+ * is replaced by a "mirror": a V8 Buffer with a copy of the bytes, registered
9
+ * with the address it mirrors. ctypes instances on a mirror (`from_address`,
10
+ * `in_dll`, `pointer.contents`, ...) stay live: every read refreshes the
11
+ * bytes from native memory, every write is copied back, and FFI arguments,
12
+ * `addressof()` and pointers use the original address.
13
+ *
14
+ * On Node.js the mirrors are never created and every function here returns
15
+ * immediately.
16
+ */
17
+
18
+ // Indirizzo nativo di ogni ArrayBuffer specchio. Buffer.alloc non usa il pool,
19
+ // quindi l'ArrayBuffer è solo della copia e le sotto-view (subarray) la
20
+ // ritrovano con l'indirizzo base + byteOffset. L'indirizzo è un Number quando
21
+ // è esatto (sotto 2^53, cioè sempre in user space), altrimenti un BigInt: la
22
+ // somma di Number non alloca.
23
+ const bases = new WeakMap();
24
+
25
+ let raw = null;
26
+
27
+ /**
28
+ * True when external buffers are not allowed and mirrors are used.
29
+ * @type {boolean}
30
+ */
31
+ export let mirrorsActive = false;
32
+
33
+ /**
34
+ * Enable mirrors for the given native module.
35
+ *
36
+ * @param {Object} native - Native module (unwrapped)
37
+ */
38
+ export function enableMirrors(native) {
39
+ raw = native;
40
+ mirrorsActive = true;
41
+ }
42
+
43
+ const toBase = (address) => {
44
+ const n = Number(address);
45
+ return Number.isSafeInteger(n) ? n : BigInt(address);
46
+ };
47
+ const at = (base, offset) => (typeof base === "number" ? base + offset : base + BigInt(offset));
48
+
49
+ /**
50
+ * Wrap the native module: `ptrToBuffer` returns a mirror, the address of a
51
+ * mirror is the native one. Reads and writes on a mirror stay on the copy,
52
+ * like the JS readers/writers, and are synchronized by refresh()/flush().
53
+ *
54
+ * @param {Object} native - Native module
55
+ * @returns {Object} Native module with mirror-aware memory functions
56
+ */
57
+ export function wrapNative(native) {
58
+ return Object.create(native, {
59
+ ptrToBuffer: { value: (address, size) => mirrorBuffer(address, size) },
60
+ addressOf: { value: (buf) => mirrorAddress(buf) ?? native.addressOf(buf) },
61
+ // Un Buffer specchio scritto come valore puntatore vale il suo indirizzo.
62
+ writeValue: { value: (ptr, type, value, offset) => native.writeValue(ptr, type, mirrorAddress(value) ?? value, offset) },
63
+ });
64
+ }
65
+
66
+ /**
67
+ * Copy `size` bytes at `address` into a new mirror Buffer.
68
+ *
69
+ * @param {bigint|number} address - Native address
70
+ * @param {number} size - Size in bytes
71
+ * @returns {Buffer|null} Mirror, `null` for a NULL address
72
+ */
73
+ export function mirrorBuffer(address, size) {
74
+ const base = toBase(address);
75
+ if (base === 0 || base === 0n) return null;
76
+ if (typeof size !== "number" || !(size > 0)) throw new RangeError("Invalid buffer size");
77
+ const buf = Buffer.alloc(size);
78
+ raw.readMemory(buf, 0, size, base);
79
+ bases.set(buf.buffer, base);
80
+ return buf;
81
+ }
82
+
83
+ /**
84
+ * True if `buf` is a mirror (or a subarray of one).
85
+ *
86
+ * @param {*} buf - Any value
87
+ * @returns {boolean}
88
+ */
89
+ export function isMirror(buf) {
90
+ return mirrorsActive && buf instanceof Uint8Array && bases.has(buf.buffer);
91
+ }
92
+
93
+ /**
94
+ * Native address mirrored by a Buffer (or a subarray of a mirror).
95
+ *
96
+ * @param {*} buf - Any value
97
+ * @returns {bigint|undefined} Address, `undefined` if not a mirror
98
+ */
99
+ export function mirrorAddress(buf) {
100
+ if (!mirrorsActive || !(buf instanceof Uint8Array)) return undefined;
101
+ const base = bases.get(buf.buffer);
102
+ return base === undefined ? undefined : BigInt(at(base, buf.byteOffset));
103
+ }
104
+
105
+ /**
106
+ * Symbol of the native address of an instance on a mirror, saved when the
107
+ * instance is created so that each access skips the lookup.
108
+ */
109
+ export const kMirrorBase = Symbol("mirrorBase");
110
+
111
+ /**
112
+ * Native address of the first byte of a mirror, as stored (Number when
113
+ * exact, otherwise BigInt).
114
+ *
115
+ * @param {*} buf - Any value
116
+ * @returns {number|bigint|undefined} Address, `undefined` if not a mirror
117
+ */
118
+ export function mirrorBase(buf) {
119
+ if (!(buf instanceof Uint8Array)) return undefined;
120
+ const base = bases.get(buf.buffer);
121
+ return base === undefined ? undefined : at(base, buf.byteOffset);
122
+ }
123
+
124
+ /**
125
+ * Refresh a mirror (or a range of it) with the current native bytes.
126
+ *
127
+ * @param {Buffer} buf - Buffer, ignored if not a mirror
128
+ * @param {number} [offset=0] - Start of the range in `buf`
129
+ * @param {number} [length] - Length of the range (default: to the end)
130
+ */
131
+ export function refresh(buf, offset = 0, length = buf.length - offset) {
132
+ if (!mirrorsActive || length <= 0) return;
133
+ const base = bases.get(buf.buffer);
134
+ if (base !== undefined) raw.readMemory(buf, offset, length, at(base, buf.byteOffset + offset));
135
+ }
136
+
137
+ /**
138
+ * Copy a mirror (or a range of it) back to native memory.
139
+ *
140
+ * @param {Buffer} buf - Buffer, ignored if not a mirror
141
+ * @param {number} [offset=0] - Start of the range in `buf`
142
+ * @param {number} [length] - Length of the range (default: to the end)
143
+ */
144
+ export function flush(buf, offset = 0, length = buf.length - offset) {
145
+ if (!mirrorsActive || length <= 0) return;
146
+ const base = bases.get(buf.buffer);
147
+ if (base !== undefined) raw.writeMemory(buf, offset, length, at(base, buf.byteOffset + offset));
148
+ }
149
+
150
+ // Byte di un campo da sincronizzare: l'unità di memoria per i bitfield.
151
+ const fieldSize = (field) => (field.isBitField ? field.baseSize : field.size);
152
+
153
+ const mirroredCache = new WeakMap();
154
+
155
+ /**
156
+ * Field readers and writers of a struct/union definition for instances on a
157
+ * mirror: a read refreshes the bytes of the field, a write copies them back
158
+ * (a bitfield refreshes its storage unit first). Instances on ordinary
159
+ * Buffers keep using `def.fieldReaders` / `def.fieldWriters` unchanged.
160
+ *
161
+ * @param {Object} def - structDef / unionDef
162
+ * @returns {{fieldReaders: Object, fieldWriters: Object}}
163
+ */
164
+ export function mirroredAccessors(def) {
165
+ let accessors = mirroredCache.get(def);
166
+ if (accessors !== undefined) return accessors;
167
+ const fieldReaders = Object.create(null);
168
+ const fieldWriters = Object.create(null);
169
+ for (const field of def.fields) {
170
+ const read = def.fieldReaders?.[field.name];
171
+ const write = def.fieldWriters?.[field.name];
172
+ const offset = field.offset;
173
+ const size = fieldSize(field);
174
+ // `base` è l'indirizzo del Buffer, salvato nell'istanza (Structure) o
175
+ // cercato (struct annidate).
176
+ if (read !== undefined) {
177
+ fieldReaders[field.name] = (buf, base = mirrorBase(buf)) => {
178
+ raw.readMemory(buf, offset, size, at(base, offset));
179
+ return read(buf);
180
+ };
181
+ }
182
+ if (write !== undefined) {
183
+ // Un campo intero viene sovrascritto, quindi basta ricopiarlo; un
184
+ // bitfield cambia solo alcuni bit dell'unità, che va prima riletta.
185
+ fieldWriters[field.name] = field.isBitField
186
+ ? (buf, value, base = mirrorBase(buf)) => {
187
+ raw.readMemory(buf, offset, size, at(base, offset));
188
+ write(buf, value);
189
+ raw.writeMemory(buf, offset, size, at(base, offset));
190
+ }
191
+ : (buf, value, base = mirrorBase(buf)) => {
192
+ write(buf, value);
193
+ raw.writeMemory(buf, offset, size, at(base, offset));
194
+ };
195
+ }
196
+ }
197
+ accessors = { fieldReaders, fieldWriters };
198
+ mirroredCache.set(def, accessors);
199
+ return accessors;
200
+ }
201
+
202
+ /**
203
+ * Make `get` / `set` / `toObject` of a struct/union definition mirror-aware
204
+ * (the generic paths: nested fields, arrays, instance methods, readValue).
205
+ * A named field syncs only its bytes; nested structures and arrays sync
206
+ * themselves on access. Applied only when mirrors are active; Buffers that
207
+ * are not mirrors cost one lookup.
208
+ *
209
+ * @param {Object} def - structDef / unionDef
210
+ * @returns {Object} The same definition
211
+ */
212
+ export function syncDefinition(def) {
213
+ if (!mirrorsActive) return def;
214
+ const size = def.size;
215
+ const fieldMap = def.fieldMap;
216
+ const { get, set, toObject } = def;
217
+ def.get = function (bufOrObj, fieldName) {
218
+ if (isMirror(bufOrObj)) {
219
+ const field = fieldMap?.get(fieldName);
220
+ if (field === undefined) refresh(bufOrObj, 0, size);
221
+ else if (!field.isNested && !field.isArray) refresh(bufOrObj, field.offset, fieldSize(field));
222
+ }
223
+ return get.call(this, bufOrObj, fieldName);
224
+ };
225
+ def.set = function (bufOrObj, fieldName, value) {
226
+ if (!isMirror(bufOrObj)) return set.call(this, bufOrObj, fieldName, value);
227
+ const field = fieldMap?.get(fieldName);
228
+ const whole = field === undefined || field.isNested || field.isArray || field.isBitField;
229
+ const offset = whole ? 0 : field.offset;
230
+ const length = whole ? size : fieldSize(field);
231
+ if (whole) refresh(bufOrObj, offset, length);
232
+ const result = set.call(this, bufOrObj, fieldName, value);
233
+ flush(bufOrObj, offset, length);
234
+ return result;
235
+ };
236
+ def.toObject = function (bufOrObj) {
237
+ if (isMirror(bufOrObj)) refresh(bufOrObj, 0, size);
238
+ return toObject.call(this, bufOrObj);
239
+ };
240
+ return def;
241
+ }
242
+
243
+ const simpleCache = new WeakMap();
244
+
245
+ // Accessor `value` ereditato (le sottoclassi possono ridefinirlo).
246
+ function inheritedValue(proto) {
247
+ for (let p = proto; p !== null; p = Object.getPrototypeOf(p)) {
248
+ const descriptor = Object.getOwnPropertyDescriptor(p, "value");
249
+ if (descriptor !== undefined) return descriptor;
250
+ }
251
+ return undefined;
252
+ }
253
+
254
+ /**
255
+ * Prototype for SimpleCData instances on a mirror (with `kMirrorBase` set):
256
+ * `value` refreshes the bytes before reading and copies them back after
257
+ * writing. Instances on ordinary Buffers keep the class prototype, without
258
+ * any check.
259
+ *
260
+ * @param {Function} Ctor - SimpleCData class
261
+ * @returns {Object} Prototype inheriting from `Ctor.prototype`
262
+ */
263
+ export function mirroredPrototype(Ctor) {
264
+ let proto = simpleCache.get(Ctor);
265
+ if (proto !== undefined) return proto;
266
+ const { get, set } = inheritedValue(Ctor.prototype);
267
+ const size = Ctor._size;
268
+ proto = Object.create(Ctor.prototype, {
269
+ value: {
270
+ configurable: true,
271
+ get() {
272
+ raw.readMemory(this._buffer, 0, size, this[kMirrorBase]);
273
+ return get.call(this);
274
+ },
275
+ set(value) {
276
+ set.call(this, value);
277
+ raw.writeMemory(this._buffer, 0, size, this[kMirrorBase]);
278
+ },
279
+ },
280
+ });
281
+ simpleCache.set(Ctor, proto);
282
+ return proto;
283
+ }
@@ -27,6 +27,9 @@
27
27
  * ```
28
28
  */
29
29
 
30
+ import { flush, mirrorsActive, refresh } from "./mirror.js";
31
+ import { copyInstance } from "../structures/helpers/common.js";
32
+
30
33
  /**
31
34
  * Factory che cattura le dipendenze in closure e restituisce un bundle di
32
35
  * funzioni memory-op con signature logica pulita.
@@ -65,8 +68,9 @@ export function createMemoryOps(deps) {
65
68
  if (type && typeof type === "object" && type._structDef !== undefined && typeof type._structDef.size === "number") {
66
69
  return type._structDef.size;
67
70
  }
68
- // Buffer, create_string_buffer() o istanza di array: dimensione in byte
69
- if (Buffer.isBuffer(type)) {
71
+ // Buffer, create_string_buffer(), istanza di array, TypedArray/DataView:
72
+ // dimensione in byte
73
+ if (Buffer.isBuffer(type) || ArrayBuffer.isView(type)) {
70
74
  return type.byteLength;
71
75
  }
72
76
  // Structure class
@@ -102,6 +106,31 @@ export function createMemoryOps(deps) {
102
106
  // es. gli argomenti POINTER dei callback passati a readValue/writeValue.
103
107
  const pointerTarget = (ptr) => (ptr._buffer !== null ? ptr._buffer : ptr.address);
104
108
 
109
+ // Memoria di readValue/writeValue: Buffer, istanza ctypes, puntatore,
110
+ // TypedArray/DataView o indirizzo (Buffer su `offset + size()` byte).
111
+ const memoryAt = (ptr, offset, size, name) => {
112
+ if (ptr !== null && typeof ptr === "object") {
113
+ if (ptr._pointerType !== undefined) {
114
+ ptr = pointerTarget(ptr);
115
+ } else if (Buffer.isBuffer(ptr._buffer)) {
116
+ ptr = ptr._buffer;
117
+ } else if (ArrayBuffer.isView(ptr) && !Buffer.isBuffer(ptr)) {
118
+ return Buffer.from(ptr.buffer, ptr.byteOffset, ptr.byteLength);
119
+ }
120
+ }
121
+ if (typeof ptr === "bigint" || typeof ptr === "number") {
122
+ if (!ptr) throw new TypeError(`${name}: NULL pointer`);
123
+ return ptrToBuffer(ptr, offset + size());
124
+ }
125
+ if (!Buffer.isBuffer(ptr)) throw new TypeError(`${name} requires a Buffer, a ctypes instance or a pointer address`);
126
+ return ptr;
127
+ };
128
+ const checkBounds = (ptr, offset, size, verb) => {
129
+ if (offset + size > ptr.length) {
130
+ throw new RangeError(`${verb} would exceed buffer bounds (offset: ${offset}, size: ${size}, buffer length: ${ptr.length})`);
131
+ }
132
+ };
133
+
105
134
  function readValue(ptr, type, offset = 0) {
106
135
  if (typeof offset !== "number" || offset < 0) {
107
136
  throw new RangeError("offset must be a non-negative number");
@@ -112,41 +141,32 @@ export function createMemoryOps(deps) {
112
141
 
113
142
  // SimpleCData class: usa _reader diretto
114
143
  if (typeof type === "function" && type._isSimpleCData) {
115
- if (Buffer.isBuffer(ptr)) {
116
- const size = type._size || sizeof(type);
117
- if (offset + size > ptr.length) {
118
- throw new RangeError(`Read would exceed buffer bounds (offset: ${offset}, size: ${size}, buffer length: ${ptr.length})`);
119
- }
120
- return type._reader(ptr, offset);
121
- }
122
- if (typeof ptr === "bigint" || typeof ptr === "number") {
144
+ const size = type._size || sizeof(type);
145
+ if ((typeof ptr === "bigint" || typeof ptr === "number") && ptr !== 0n && ptr !== 0) {
123
146
  const nativeType = deps.nativeReadTypes !== undefined ? deps.nativeReadTypes.get(type) : undefined;
124
- if (nativeType !== undefined && ptr !== 0n && ptr !== 0) {
147
+ if (nativeType !== undefined) {
125
148
  return deps.native.readValue(ptr, nativeType, offset);
126
149
  }
127
- const size = type._size || sizeof(type);
128
- const buf = ptrToBuffer(ptr, size + offset);
129
- return type._reader(buf, offset);
130
150
  }
131
- throw new TypeError("readValue requires a Buffer or pointer address");
151
+ ptr = memoryAt(ptr, offset, () => size, "readValue");
152
+ checkBounds(ptr, offset, size, "Read");
153
+ if (mirrorsActive) refresh(ptr, offset, size);
154
+ return type._reader(ptr, offset);
132
155
  }
133
156
 
134
- // Structure class
157
+ let def;
135
158
  if (typeof type === "function" && type.prototype instanceof getStructure()) {
136
- const def = type._structDef || type._buildStruct();
137
- return def.toObject(ptr.subarray(offset, offset + def.size));
138
- }
139
- // Union class
140
- if (typeof type === "function" && type.prototype instanceof getUnion()) {
141
- const def = type._unionDef || type._buildUnion();
142
- return def.toObject(ptr.subarray(offset, offset + def.size));
143
- }
144
- // structDef / unionDef object
145
- if (typeof type === "object" && type !== null && type._isStructType && typeof type.toObject === "function") {
146
- return type.toObject(ptr.subarray(offset, offset + type.size));
147
- }
148
-
149
- throw new TypeError(`readValue: unsupported type ${type}`);
159
+ def = type._structDef || type._buildStruct();
160
+ } else if (typeof type === "function" && type.prototype instanceof getUnion()) {
161
+ def = type._unionDef || type._buildUnion();
162
+ } else if (typeof type === "object" && type !== null && type._isStructType && typeof type.toObject === "function") {
163
+ def = type;
164
+ } else {
165
+ throw new TypeError(`readValue: unsupported type ${type}`);
166
+ }
167
+ ptr = memoryAt(ptr, offset, () => def.size, "readValue");
168
+ checkBounds(ptr, offset, def.size, "Read");
169
+ return def.toObject(ptr.subarray(offset, offset + def.size));
150
170
  }
151
171
 
152
172
  /**
@@ -156,32 +176,29 @@ export function createMemoryOps(deps) {
156
176
  if (typeof offset !== "number" || offset < 0) {
157
177
  throw new RangeError("offset must be a non-negative number");
158
178
  }
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
- }
179
+ ptr = memoryAt(ptr, offset, () => sizeof(type), "writeValue");
165
180
 
166
181
  // SimpleCData class: usa _writer diretto
167
182
  if (typeof type === "function" && type._isSimpleCData) {
168
- if (!Buffer.isBuffer(ptr)) {
169
- throw new TypeError("writeValue requires a Buffer");
170
- }
171
183
  const size = type._size || sizeof(type);
172
- if (offset + size > ptr.length) {
173
- throw new RangeError(`Write would exceed buffer bounds (offset: ${offset}, size: ${size}, buffer length: ${ptr.length})`);
174
- }
184
+ checkBounds(ptr, offset, size, "Write");
175
185
  type._writer(ptr, offset, value);
186
+ if (mirrorsActive) flush(ptr, offset, size);
176
187
  return type._size;
177
188
  }
178
189
 
179
190
  // Structure/Union class o def — tutti gestiti con la stessa logica:
180
191
  // o value è un Buffer (copia raw) o è un object (set field-by-field).
181
192
  const writeComposite = (def) => {
193
+ checkBounds(ptr, offset, def.size, "Write");
182
194
  const tempBuf = ptr.subarray(offset, offset + def.size);
183
195
  if (Buffer.isBuffer(value)) {
184
196
  value.copy(tempBuf, 0, 0, def.size);
197
+ if (mirrorsActive) flush(tempBuf);
198
+ } else if (value !== null && typeof value === "object" && Buffer.isBuffer(value._buffer)) {
199
+ // Istanza struct/union: copia dei byte (Python), non campo per campo.
200
+ copyInstance(tempBuf, 0, def.size, value);
201
+ if (mirrorsActive) flush(tempBuf);
185
202
  } else if (typeof value === "object" && value !== null) {
186
203
  for (const [k, v] of Object.entries(value)) {
187
204
  def.set(tempBuf, k, v);