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
@@ -33,9 +33,11 @@
33
33
  * ```
34
34
  */
35
35
 
36
- import { _readBitField, _writeBitField } from "./bitfield.js";
36
+ import { bitFieldAccessors } from "./bitfield.js";
37
+ import { computeLayout, isGccLayout } from "./layout.js";
37
38
  import { buildWrapper } from "./wrap.js";
38
- import { copyInstance, funcPtrFieldType, writePointerField } from "./common.js";
39
+ import { isMirror, syncDefinition } from "../../memory/mirror.js";
40
+ import { copyInstance, fieldEntries, fieldsOf, funcPtrFieldType, simpleFieldWriter, writePointerField } from "./common.js";
39
41
 
40
42
  /**
41
43
  * Creates a struct type definition with proper alignment and padding.
@@ -49,7 +51,8 @@ import { copyInstance, funcPtrFieldType, writePointerField } from "./common.js";
49
51
  *
50
52
  * @param {Object} fields - Field definitions { name: type, ... }
51
53
  * @param {Object} [options] - Options { packed: false }
52
- * @param {boolean} [options.packed=false] - If true, disable padding/alignment
54
+ * @param {boolean} [options.packed=false] - If true, disable padding/alignment (pack 1)
55
+ * @param {number} [options.pack] - Maximum field alignment (Python `_pack_`)
53
56
  * @param {Function} sizeof - sizeof function reference
54
57
  * @param {Function} alloc - alloc function reference
55
58
  * @param {Function} readValue - readValue function reference
@@ -89,33 +92,28 @@ const pointerOrNull = (ptrType, address) => (address === 0n ? null : ptrType.fro
89
92
 
90
93
  export function struct(fields, options = {}, sizeof, alloc, readValue, writeValue, _isStruct, _isArrayType, _isBitField, Structure, Union, native) {
91
94
  // Validate inputs
92
- if (!fields || typeof fields !== "object" || Array.isArray(fields)) {
95
+ // Un oggetto { name: type }, o le coppie [name, type] in ordine (Structure).
96
+ if (!fields || typeof fields !== "object") {
93
97
  throw new TypeError("fields must be a non-null object");
94
98
  }
95
99
 
96
- const packed = options.packed || false;
97
- // Python-ctypes `_pack_` semantics: numeric max alignment. Boolean `packed`
98
- // (no numeric pack value) means fully packed => pack = 1.
99
- const packValue = packed ? (typeof options.pack === "number" ? options.pack : 1) : 0;
100
- const packAlign = (natural) => (packValue ? Math.min(natural, packValue) : natural);
101
- // `swapped` selects _readerBE/_writerBE on primitive SimpleCData fields.
102
- // Used by BigEndianStructure / LittleEndianStructure (on LE host, swapped=true
103
- // means "use BE"; on theoretical BE host, same flag would mean LE — but we
104
- // only officially support LE hosts, so "swapped" == "big-endian").
100
+ // Python _pack_: `pack` (massimo allineamento), o `packed: true` (= pack 1).
101
+ const packValue = typeof options.pack === "number" ? options.pack : options.packed ? 1 : 0;
102
+ // `swapped` selects _readerBE/_writerBE on primitive SimpleCData fields and
103
+ // lays out bitfields from the big end. Used by BigEndianStructure /
104
+ // LittleEndianStructure (on LE host, swapped=true means "use BE").
105
105
  const swapped = options.swapped === true;
106
- let totalSize = 0;
107
- const fieldDefs = [];
108
- let maxAlignment = 1;
109
-
110
- // Track field names to detect duplicates
111
- const fieldNames = new Set();
112
-
113
- // Stato per bit fields consecutivi
114
- let currentBitFieldBase = null;
115
- let currentBitFieldOffset = 0;
116
- let currentBitOffset = 0;
117
-
118
- for (const [name, type] of Object.entries(fields)) {
106
+ const gccLayout = isGccLayout(options.layout, packValue);
107
+ // Python: una sottoclasse con _fields_ estende il layout della base, i cui
108
+ // campi restano agli stessi offset.
109
+ const base = options.base ?? null;
110
+ const fieldDefs = base ? base.fields.map((f) => ({ ...f })) : [];
111
+ const fieldNames = new Set(fieldDefs.map((f) => f.name));
112
+
113
+ // Tipo, dimensione e allineamento naturale di ogni campo; gli offset sono
114
+ // calcolati dopo, tutti insieme, da computeLayout (come Python).
115
+ const ownDefs = [];
116
+ for (const [name, type] of fieldEntries(fields)) {
119
117
  // Validate field name
120
118
  if (!name || typeof name !== "string" || name.trim().length === 0) {
121
119
  throw new TypeError("Field name must be a non-empty string");
@@ -124,279 +122,78 @@ export function struct(fields, options = {}, sizeof, alloc, readValue, writeValu
124
122
  throw new TypeError(`Duplicate field name: ${name}`);
125
123
  }
126
124
  fieldNames.add(name);
127
- let fieldDef;
128
-
129
- // Caso 0: Anonymous field - { type: SomeStruct, anonymous: true }
130
- if (typeof type === "object" && type !== null && type.anonymous === true && type.type) {
131
- // Reset bit field state
132
- currentBitFieldBase = null;
133
- currentBitOffset = 0;
134
-
135
- const actualType = type.type;
136
- const size = actualType.size;
137
- const alignment = packAlign(actualType.alignment);
138
-
139
- // Applica padding per allineamento
140
- if (totalSize % alignment !== 0) {
141
- totalSize += alignment - (totalSize % alignment);
142
- }
143
-
144
- fieldDef = {
145
- name,
146
- type: actualType,
147
- offset: totalSize,
148
- size,
149
- alignment,
150
- isNested: true,
151
- isAnonymous: true,
152
- };
153
-
154
- totalSize += size;
125
+ ownDefs.push(describeField(name, type));
126
+ }
155
127
 
156
- if (alignment > maxAlignment) {
157
- maxAlignment = alignment;
158
- }
128
+ // Campo di _anonymous_: una struct/union (classe o definizione), i cui
129
+ // campi sono raggiungibili dalla struct esterna.
130
+ function anonymousField(name, { type, cls }) {
131
+ let def = type;
132
+ if (typeof type === "function" && typeof type._buildStruct === "function") {
133
+ cls = type;
134
+ def = type._structDef || type._buildStruct();
159
135
  }
160
- // Caso 1: Bit field
161
- else if (_isBitField(type)) {
162
- const { baseType, bits, baseSize } = type;
163
- const alignment = packAlign(Math.min(baseSize, native.POINTER_SIZE));
164
-
165
- // Verifica se possiamo continuare nel bit field corrente
166
- const canContinue = currentBitFieldBase === baseType && currentBitOffset + bits <= baseSize * 8;
167
-
168
- if (!canContinue) {
169
- // Inizia un nuovo bit field
170
- // Applica padding per allineamento
171
- if (totalSize % alignment !== 0) {
172
- totalSize += alignment - (totalSize % alignment);
173
- }
174
-
175
- currentBitFieldBase = baseType;
176
- currentBitFieldOffset = totalSize;
177
- currentBitOffset = 0;
178
- totalSize += baseSize;
179
- }
180
-
181
- fieldDef = {
182
- name,
183
- type: baseType,
184
- offset: currentBitFieldOffset,
185
- size: 0, // Bit fields non aggiungono size extra
186
- alignment,
187
- isBitField: true,
188
- bitOffset: currentBitOffset,
189
- bitSize: bits,
190
- baseSize,
191
- };
192
-
193
- currentBitOffset += bits;
194
-
195
- if (alignment > maxAlignment) {
196
- maxAlignment = alignment;
197
- }
136
+ if (def === null || typeof def !== "object" || !Array.isArray(def.fields)) {
137
+ throw new TypeError(`anonymous field "${name}" must be a structure or union`);
198
138
  }
199
- // Caso 2a: Struct class (declarata come `class X extends Structure`)
200
- else if (typeof type === "function" && type.prototype instanceof Structure) {
201
- // Reset bit field state
202
- currentBitFieldBase = null;
203
- currentBitOffset = 0;
204
-
205
- const nestedStruct = type._structDef || type._buildStruct();
206
- const size = nestedStruct.size;
207
- const alignment = packAlign(nestedStruct.alignment);
208
-
209
- // Applica padding per allineamento
210
- if (totalSize % alignment !== 0) {
211
- totalSize += alignment - (totalSize % alignment);
212
- }
213
-
214
- fieldDef = {
215
- name,
216
- type: nestedStruct,
217
- offset: totalSize,
218
- size,
219
- alignment,
220
- isNested: true,
221
- };
222
-
223
- totalSize += size;
139
+ return { name, type: def, cls, size: def.size, alignment: def.alignment, isNested: true, isAnonymous: true };
140
+ }
224
141
 
225
- if (alignment > maxAlignment) {
226
- maxAlignment = alignment;
227
- }
142
+ function describeField(name, type) {
143
+ // Anonymous field - { type: SomeStruct, anonymous: true }
144
+ if (typeof type === "object" && type !== null && type.anonymous === true && type.type) {
145
+ return anonymousField(name, type);
228
146
  }
229
- // Caso 2b: Union class (declarata come `class X extends Union`)
230
- else if (typeof type === "function" && type.prototype instanceof Union) {
231
- // Reset bit field state
232
- currentBitFieldBase = null;
233
- currentBitOffset = 0;
234
-
235
- const nestedUnion = type._unionDef || type._buildUnion();
236
- const size = nestedUnion.size;
237
- const alignment = packAlign(nestedUnion.alignment);
238
-
239
- // Applica padding per allineamento
240
- if (totalSize % alignment !== 0) {
241
- totalSize += alignment - (totalSize % alignment);
242
- }
243
-
244
- fieldDef = {
245
- name,
246
- type: nestedUnion,
247
- offset: totalSize,
248
- size,
249
- alignment,
250
- isNested: true,
251
- };
252
-
253
- totalSize += size;
254
-
255
- if (alignment > maxAlignment) {
256
- maxAlignment = alignment;
257
- }
147
+ // Bit field
148
+ if (_isBitField(type)) {
149
+ const { baseType, bits, baseSize } = type;
150
+ return { name, type: baseType, size: 0, alignment: Math.min(baseSize, native.POINTER_SIZE), isBitField: true, bitSize: bits, baseSize };
258
151
  }
259
- // Caso 2: Nested struct
260
- else if (_isStruct(type)) {
261
- // Reset bit field state
262
- currentBitFieldBase = null;
263
- currentBitOffset = 0;
264
-
265
- // Normalize type: if it's a Structure/Union class, get its _structDef
266
- let nestedStruct = type;
267
- if (typeof type === "function" && typeof type._buildStruct === "function") {
268
- nestedStruct = type._structDef || type._buildStruct();
269
- }
270
-
271
- const size = nestedStruct.size;
272
- const alignment = packAlign(nestedStruct.alignment);
273
-
274
- // Applica padding per allineamento
275
- if (totalSize % alignment !== 0) {
276
- totalSize += alignment - (totalSize % alignment);
277
- }
278
-
279
- fieldDef = {
280
- name,
281
- type: nestedStruct,
282
- offset: totalSize,
283
- size,
284
- alignment,
285
- isNested: true,
286
- };
287
-
288
- totalSize += size;
289
-
290
- if (alignment > maxAlignment) {
291
- maxAlignment = alignment;
292
- }
152
+ // Structure / Union class (Union estende Structure)
153
+ if (typeof type === "function" && type.prototype instanceof Structure) {
154
+ const nested = type._structDef || type._buildStruct();
155
+ // `cls`: Python restituisce un'istanza della classe annidata, sulla
156
+ // stessa memoria.
157
+ return { name, type: nested, cls: type, size: nested.size, alignment: nested.alignment, isNested: true };
293
158
  }
294
- // Caso 3: Array type
295
- else if (_isArrayType(type)) {
296
- // Reset bit field state
297
- currentBitFieldBase = null;
298
- currentBitOffset = 0;
299
-
300
- const size = type.getSize();
301
- // Array alignment == element alignment (C standard). For primitives we
302
- // clamp to POINTER_SIZE (same as natural alignment for all types ≤ 8
303
- // bytes on x64). For Structure/Union elements we must use their
304
- // declared alignment (smaller than size when the struct has padding).
159
+ // struct() / union() definition
160
+ if (_isStruct(type)) {
161
+ return { name, type, size: type.size, alignment: type.alignment, isNested: true };
162
+ }
163
+ // Array type: alignment == element alignment (C standard).
164
+ if (_isArrayType(type)) {
305
165
  const elemSize = sizeof(type.elementType);
306
- const elemAlignment = typeof type.getAlignment === "function" ? type.getAlignment() : Math.min(elemSize, native.POINTER_SIZE);
307
- const alignment = packAlign(elemAlignment);
308
-
309
- // Applica padding per allineamento
310
- if (totalSize % alignment !== 0) {
311
- totalSize += alignment - (totalSize % alignment);
312
- }
313
-
314
- fieldDef = {
315
- name,
316
- type,
317
- offset: totalSize,
318
- size,
319
- alignment,
320
- isArray: true,
321
- };
322
-
323
- totalSize += size;
324
-
325
- if (alignment > maxAlignment) {
326
- maxAlignment = alignment;
327
- }
166
+ const alignment = typeof type.getAlignment === "function" ? type.getAlignment() : Math.min(elemSize, native.POINTER_SIZE);
167
+ return { name, type, size: type.getSize(), alignment, isArray: true };
328
168
  }
329
- // Caso 4b: POINTER() type — stored as pointer-sized field with typed access
330
- else if ((typeof type === "object" && type !== null && type._pointerTo !== undefined) || (typeof type === "function" && type._isFuncPtr === true)) {
331
- // Reset bit field state
332
- currentBitFieldBase = null;
333
- currentBitOffset = 0;
334
-
335
- const size = native.POINTER_SIZE;
336
- const alignment = packAlign(Math.min(size, native.POINTER_SIZE));
337
-
338
- if (totalSize % alignment !== 0) {
339
- totalSize += alignment - (totalSize % alignment);
340
- }
341
-
342
- fieldDef = {
343
- name,
344
- // CFUNCTYPE: campo puntatore letto come funzione chiamabile (Python parity)
345
- type: typeof type === "function" ? funcPtrFieldType(type) : type,
346
- offset: totalSize,
347
- size,
348
- alignment,
349
- isPointer: true,
350
- };
351
-
352
- totalSize += size;
353
-
354
- if (alignment > maxAlignment) {
355
- maxAlignment = alignment;
356
- }
169
+ // POINTER() / CFUNCTYPE — pointer-sized field with typed access
170
+ if ((typeof type === "object" && type !== null && type._pointerTo !== undefined) || (typeof type === "function" && type._isFuncPtr === true)) {
171
+ // CFUNCTYPE: campo puntatore letto come funzione chiamabile (Python parity)
172
+ return { name, type: typeof type === "function" ? funcPtrFieldType(type) : type, size: native.POINTER_SIZE, alignment: native.POINTER_SIZE, isPointer: true };
357
173
  }
358
- // Caso 4: Tipo base (SimpleCData)
359
- else {
360
- // Reset bit field state
361
- currentBitFieldBase = null;
362
- currentBitOffset = 0;
363
-
364
- // Validate type is a SimpleCData class
365
- if (!(typeof type === "function" && type._isSimpleCData)) {
366
- throw new TypeError(`struct field "${name}": type must be a SimpleCData class, struct, union, or array`);
367
- }
368
-
369
- const size = type._size;
370
- const naturalAlign = Math.min(size, native.POINTER_SIZE);
371
- const alignment = packAlign(naturalAlign);
372
-
373
- // Applica padding per allineamento
374
- if (totalSize % alignment !== 0) {
375
- totalSize += alignment - (totalSize % alignment);
376
- }
377
-
378
- fieldDef = {
379
- name,
380
- type,
381
- offset: totalSize,
382
- size,
383
- alignment,
384
- };
385
-
386
- totalSize += size;
387
-
388
- if (alignment > maxAlignment) {
389
- maxAlignment = alignment;
390
- }
174
+ // Tipo base (SimpleCData)
175
+ if (!(typeof type === "function" && type._isSimpleCData)) {
176
+ throw new TypeError(`struct field "${name}": type must be a SimpleCData class, struct, union, or array`);
391
177
  }
392
-
393
- fieldDefs.push(fieldDef);
178
+ return { name, type, size: type._size, alignment: Math.min(type._size, native.POINTER_SIZE) };
394
179
  }
395
180
 
396
- // Padding finale per allineamento della struct
397
- if (totalSize % maxAlignment !== 0) {
398
- totalSize += maxAlignment - (totalSize % maxAlignment);
399
- }
181
+ const layout = computeLayout(
182
+ ownDefs.map((f) => (f.isBitField ? { name: f.name, size: f.baseSize, align: f.alignment, bitSize: f.bitSize } : { name: f.name, size: f.size, align: f.alignment })),
183
+ { isStruct: true, gccLayout, pack: packValue, align: options.align ?? 1, base, bigEndian: swapped },
184
+ );
185
+ ownDefs.forEach((f, i) => {
186
+ f.offset = layout.offsets[i].offset;
187
+ if (f.isBitField) f.bitOffset = layout.offsets[i].bitOffset;
188
+ // Allineamento del tipo in C, prima di _pack_ (usato per le struct native
189
+ // passate per valore, lib/core/types.js).
190
+ f.naturalAlignment = f.alignment;
191
+ if (packValue) f.alignment = Math.min(f.alignment, packValue);
192
+ f.swapped = swapped;
193
+ fieldDefs.push(f);
194
+ });
195
+ const totalSize = layout.size;
196
+ const maxAlignment = layout.alignment;
400
197
 
401
198
  // Crea Map per lookup O(1) invece di find() O(n)
402
199
  const fieldMap = new Map();
@@ -408,14 +205,20 @@ export function struct(fields, options = {}, sizeof, alloc, readValue, writeValu
408
205
  // inclusi i sotto-campi dei campi _anonymous_. Il Proxy get/set/has
409
206
  // altrimenti scansionerebbe linearmente tutti i campi anonymous e i loro
410
207
  // subfields su ogni accesso. Usa un null-proto object per IC monomorfo.
411
- const anonymousFieldNames = Object.create(null); // subField.name -> true
208
+ // Come Python, la promozione è ricorsiva: un campo anonimo dentro un campo
209
+ // anonimo è raggiungibile dalla struct esterna.
210
+ const anonymousFieldNames = Object.create(null); // subField.name -> true
412
211
  for (const field of fieldDefs) {
413
212
  if (field.isAnonymous && field.type && field.type.fields) {
414
213
  for (const subField of field.type.fields) {
415
214
  anonymousFieldNames[subField.name] = true;
416
215
  }
216
+ for (const name of Object.keys(field.type.anonymousFieldNames ?? {})) {
217
+ anonymousFieldNames[name] = true;
218
+ }
417
219
  }
418
220
  }
221
+ const promotes = (f, name) => f.type.fields.some((subField) => subField.name === name) || f.type.anonymousFieldNames?.[name] === true;
419
222
 
420
223
  // Pre-compile reader/writer functions for each field.
421
224
  // We use null-prototype plain objects rather than `Map` because V8 builds
@@ -433,92 +236,21 @@ export function struct(fields, options = {}, sizeof, alloc, readValue, writeValu
433
236
  const offset = field.offset;
434
237
  const name = field.name;
435
238
 
436
- // Bitfield: pre-calcola mask/shift così read/write salta il dispatch
437
- // generico. Sign-extension applicata quando il base type è signed
438
- // (parity Python ctypes — `c_int8, 3` con valore -1 deve rileggere -1,
439
- // non 7).
239
+ // Bitfield: accessor precompilati (sign-extension per base type signed,
240
+ // come Python: `c_int8, 3` con valore -1 rilegge -1, non 7).
440
241
  if (field.isBitField) {
441
- const fieldOffset = offset;
442
- const baseSize = field.baseSize;
443
- const bitOffset = field.bitOffset;
444
- const bitSize = field.bitSize;
445
- const isSigned = field.type?._signed === true;
446
-
447
- if (baseSize === 1) {
448
- const mask = (1 << bitSize) - 1;
449
- const clearMask = ~(mask << bitOffset);
450
- if (isSigned) {
451
- const signBit = 1 << (bitSize - 1);
452
- const extendMask = ~mask;
453
- fieldReaders[name] = (buf) => {
454
- const raw = (buf.readUInt8(fieldOffset) >> bitOffset) & mask;
455
- return (raw & signBit) ? (raw | extendMask) : raw;
456
- };
457
- } else {
458
- fieldReaders[name] = (buf) => (buf.readUInt8(fieldOffset) >> bitOffset) & mask;
459
- }
460
- fieldWriters[name] = (buf, val) => {
461
- const v = buf.readUInt8(fieldOffset);
462
- buf.writeUInt8(((v & clearMask) | ((val & mask) << bitOffset)) & 0xff, fieldOffset);
463
- };
464
- } else if (baseSize === 2) {
465
- const mask = (1 << bitSize) - 1;
466
- const clearMask = ~(mask << bitOffset);
467
- if (isSigned) {
468
- const signBit = 1 << (bitSize - 1);
469
- const extendMask = ~mask;
470
- fieldReaders[name] = (buf) => {
471
- const raw = (buf.readUInt16LE(fieldOffset) >> bitOffset) & mask;
472
- return (raw & signBit) ? (raw | extendMask) : raw;
473
- };
474
- } else {
475
- fieldReaders[name] = (buf) => (buf.readUInt16LE(fieldOffset) >> bitOffset) & mask;
476
- }
477
- fieldWriters[name] = (buf, val) => {
478
- const v = buf.readUInt16LE(fieldOffset);
479
- buf.writeUInt16LE(((v & clearMask) | ((val & mask) << bitOffset)) & 0xffff, fieldOffset);
480
- };
481
- } else if (baseSize === 4) {
482
- const mask = (1 << bitSize) - 1;
483
- const clearMask = ~(mask << bitOffset);
484
- if (isSigned) {
485
- const signBit = 1 << (bitSize - 1);
486
- const extendMask = ~mask;
487
- fieldReaders[name] = (buf) => {
488
- const raw = (buf.readUInt32LE(fieldOffset) >>> bitOffset) & mask;
489
- return (raw & signBit) ? (raw | extendMask) : raw;
490
- };
491
- } else {
492
- fieldReaders[name] = (buf) => (buf.readUInt32LE(fieldOffset) >>> bitOffset) & mask;
493
- }
494
- fieldWriters[name] = (buf, val) => {
495
- const v = buf.readUInt32LE(fieldOffset);
496
- buf.writeUInt32LE(((v & clearMask) | ((val & mask) << bitOffset)) >>> 0, fieldOffset);
497
- };
498
- } else if (baseSize === 8) {
499
- const bMask = (1n << BigInt(bitSize)) - 1n;
500
- const bBitOffset = BigInt(bitOffset);
501
- const bClearMask = ~(bMask << bBitOffset);
502
- if (isSigned) {
503
- const bSignBit = 1n << BigInt(bitSize - 1);
504
- const bExtend = ~bMask;
505
- fieldReaders[name] = (buf) => {
506
- const raw = (buf.readBigUInt64LE(fieldOffset) >> bBitOffset) & bMask;
507
- const signed = (raw & bSignBit) ? (raw | bExtend) : raw;
508
- // Ritorna Number se sta nel safe range, altrimenti BigInt
509
- const asNum = Number(signed);
510
- return (asNum >= Number.MIN_SAFE_INTEGER && asNum <= Number.MAX_SAFE_INTEGER)
511
- ? asNum
512
- : signed;
513
- };
514
- } else {
515
- fieldReaders[name] = (buf) => Number((buf.readBigUInt64LE(fieldOffset) >> bBitOffset) & bMask);
516
- }
517
- fieldWriters[name] = (buf, val) => {
518
- const v = buf.readBigUInt64LE(fieldOffset);
519
- buf.writeBigUInt64LE((v & bClearMask) | ((BigInt(val) & bMask) << bBitOffset), fieldOffset);
520
- };
521
- }
242
+ const { read, write } = bitFieldAccessors({
243
+ offset,
244
+ baseSize: field.baseSize,
245
+ bitOffset: field.bitOffset,
246
+ bitSize: field.bitSize,
247
+ signed: field.type?._signed === true,
248
+ bigEndian: field.swapped === true,
249
+ });
250
+ field.readBits = read;
251
+ field.writeBits = write;
252
+ fieldReaders[name] = read;
253
+ fieldWriters[name] = write;
522
254
  continue;
523
255
  }
524
256
 
@@ -550,10 +282,10 @@ export function struct(fields, options = {}, sizeof, alloc, readValue, writeValu
550
282
  const fieldType = field.type;
551
283
  if (fieldType && fieldType._isSimpleCData) {
552
284
  const fieldOffset = offset; // Capture offset for closure
553
- const reader = swapped && fieldType._readerBE ? fieldType._readerBE : fieldType._reader;
554
- const writer = swapped && fieldType._writerBE ? fieldType._writerBE : fieldType._writer;
285
+ const reader = field.swapped && fieldType._readerBE ? fieldType._readerBE : fieldType._reader;
286
+ const writer = field.swapped && fieldType._writerBE ? fieldType._writerBE : fieldType._writer;
555
287
  fieldReaders[name] = (buf) => reader(buf, fieldOffset);
556
- fieldWriters[name] = (buf, val) => writer(buf, fieldOffset, val);
288
+ fieldWriters[name] = simpleFieldWriter(fieldType, writer, fieldOffset);
557
289
  }
558
290
  }
559
291
 
@@ -564,8 +296,10 @@ export function struct(fields, options = {}, sizeof, alloc, readValue, writeValu
564
296
  fieldMap,
565
297
  fieldReaders,
566
298
  fieldWriters,
567
- anonymousFieldNames, // usato dai nested proxy per evitare ricostruzioni
568
- packed: packed,
299
+ anonymousFieldNames, // usato dai nested proxy per evitare ricostruzioni
300
+ packed: packValue !== 0,
301
+ swapped,
302
+ base, // definizione della classe base (i suoi campi sono i primi di `fields`)
569
303
  _isStructType: true,
570
304
 
571
305
  /**
@@ -595,10 +329,13 @@ export function struct(fields, options = {}, sizeof, alloc, readValue, writeValu
595
329
  }
596
330
  }
597
331
 
598
- return new Proxy(buf, buildWrapper(structDef, {
599
- instanceTag: "StructInstance",
600
- exposeAnonymous: true,
601
- }));
332
+ return new Proxy(
333
+ buf,
334
+ buildWrapper(structDef, {
335
+ instanceTag: "StructInstance",
336
+ exposeAnonymous: true,
337
+ }),
338
+ );
602
339
  },
603
340
 
604
341
  /**
@@ -649,17 +386,23 @@ export function struct(fields, options = {}, sizeof, alloc, readValue, writeValu
649
386
  if (field) {
650
387
  // Bit field
651
388
  if (field.isBitField) {
652
- return _readBitField(buf, field.offset, field.type, field.bitOffset, field.bitSize, sizeof);
389
+ return field.readBits(buf);
653
390
  }
654
391
 
655
392
  // Nested struct (senza dot = ritorna intero oggetto)
656
393
  if (field.isNested) {
657
394
  const nestedBuf = buf.subarray(field.offset, field.offset + field.size);
395
+ // Classe Structure/Union: un'istanza sulla stessa memoria (Python).
396
+ if (field.cls !== undefined) return new field.cls(nestedBuf);
658
397
  return field.type.create
659
- ? new Proxy(nestedBuf, buildWrapper(field.type, {
660
- instanceTag: "NestedStructInstance",
661
- exposeAnonymous: true,
662
- }))
398
+ ? new Proxy(
399
+ nestedBuf,
400
+ buildWrapper(field.type, {
401
+ instanceTag: "NestedStructInstance",
402
+ exposeAnonymous: true,
403
+ mirrored: isMirror(nestedBuf),
404
+ }),
405
+ )
663
406
  : field.type.toObject(nestedBuf);
664
407
  }
665
408
 
@@ -676,8 +419,8 @@ export function struct(fields, options = {}, sizeof, alloc, readValue, writeValu
676
419
  return field.type.wrap(arrayBuf);
677
420
  }
678
421
 
679
- // Tipo base - fast path!
680
- return readValue(buf, field.type, field.offset);
422
+ // Tipo base: stesso accessor del fast path (rispetta l'endianness)
423
+ return fieldReaders[field.name](buf);
681
424
  }
682
425
 
683
426
  // supporto per accesso nested 'outer.inner' o anonymous fields
@@ -690,7 +433,7 @@ export function struct(fields, options = {}, sizeof, alloc, readValue, writeValu
690
433
  if (!field) {
691
434
  for (const f of fieldDefs) {
692
435
  if (f.isAnonymous && f.type && f.type.fields) {
693
- const hasField = f.type.fields.some((subField) => subField.name === firstPart);
436
+ const hasField = promotes(f, firstPart);
694
437
  if (hasField) {
695
438
  const nestedBuf = buf.subarray(f.offset, f.offset + f.size);
696
439
  return f.type.get(nestedBuf, fieldName);
@@ -739,7 +482,7 @@ export function struct(fields, options = {}, sizeof, alloc, readValue, writeValu
739
482
  if (field) {
740
483
  // Bit field
741
484
  if (field.isBitField) {
742
- _writeBitField(buf, field.offset, field.type, field.bitOffset, field.bitSize, value, sizeof);
485
+ field.writeBits(buf, value);
743
486
  return;
744
487
  }
745
488
 
@@ -767,7 +510,8 @@ export function struct(fields, options = {}, sizeof, alloc, readValue, writeValu
767
510
 
768
511
  // Array field
769
512
  if (field.isArray) {
770
- if (field.type._charKind !== undefined && typeof value === "string") {
513
+ // Python: bytes / str con il controllo di lunghezza ("bytes too long").
514
+ if (field.type._charKind !== undefined && (typeof value === "string" || (field.type._charKind === "char" && Buffer.isBuffer(value) && value._buffer === undefined))) {
771
515
  field.type.setValue(buf.subarray(field.offset, field.offset + field.size), value, (len, max) => `${field.type._charKind === "char" ? "bytes" : "string"} too long (${len}, maximum length ${max})`);
772
516
  } else if (Buffer.isBuffer(value)) {
773
517
  value.copy(buf, field.offset, 0, field.size);
@@ -781,8 +525,8 @@ export function struct(fields, options = {}, sizeof, alloc, readValue, writeValu
781
525
  return;
782
526
  }
783
527
 
784
- // Tipo base - fast path!
785
- writeValue(buf, field.type, value, field.offset);
528
+ // Tipo base: stesso accessor del fast path (rispetta l'endianness)
529
+ fieldWriters[field.name](buf, value);
786
530
  return;
787
531
  }
788
532
 
@@ -797,7 +541,7 @@ export function struct(fields, options = {}, sizeof, alloc, readValue, writeValu
797
541
  for (const f of fieldDefs) {
798
542
  if (f.isAnonymous && f.type && f.type.fields) {
799
543
  // Verifica se il campo esiste nel tipo anonimo
800
- const hasField = f.type.fields.some((subField) => subField.name === firstPart);
544
+ const hasField = promotes(f, firstPart);
801
545
  if (hasField) {
802
546
  // Scrive nel campo dell'anonymous field
803
547
  const nestedBuf = buf.subarray(f.offset, f.offset + f.size);
@@ -811,7 +555,7 @@ export function struct(fields, options = {}, sizeof, alloc, readValue, writeValu
811
555
 
812
556
  // Bit field
813
557
  if (field.isBitField) {
814
- _writeBitField(buf, field.offset, field.type, field.bitOffset, field.bitSize, value, sizeof);
558
+ field.writeBits(buf, value);
815
559
  return;
816
560
  }
817
561
 
@@ -856,7 +600,7 @@ export function struct(fields, options = {}, sizeof, alloc, readValue, writeValu
856
600
  }
857
601
 
858
602
  // Tipo base
859
- writeValue(buf, field.type, value, field.offset);
603
+ fieldWriters[field.name](buf, value);
860
604
  },
861
605
 
862
606
  /**
@@ -889,7 +633,7 @@ export function struct(fields, options = {}, sizeof, alloc, readValue, writeValu
889
633
  // Leggi tutti i campi in una volta (eager approach)
890
634
  for (const field of fieldDefs) {
891
635
  if (field.isBitField) {
892
- result[field.name] = _readBitField(buf, field.offset, field.type, field.bitOffset, field.bitSize, sizeof);
636
+ result[field.name] = field.readBits(buf);
893
637
  } else if (field.isNested) {
894
638
  const nestedBuf = buf.subarray(field.offset, field.offset + field.size);
895
639
  const nestedObj = field.type.toObject(nestedBuf);
@@ -907,7 +651,7 @@ export function struct(fields, options = {}, sizeof, alloc, readValue, writeValu
907
651
  result[field.name] = field.type._charKind !== undefined ? field.type.getValue(arrayBuf) : field.type.wrap(arrayBuf);
908
652
  } else {
909
653
  // Tipo base - lettura diretta
910
- result[field.name] = readValue(buf, field.type, field.offset);
654
+ result[field.name] = fieldReaders[field.name](buf);
911
655
  }
912
656
  }
913
657
 
@@ -931,7 +675,7 @@ export function struct(fields, options = {}, sizeof, alloc, readValue, writeValu
931
675
 
932
676
  // fromObject: write plain object values into buffer
933
677
  structDef.fromObject = function (buf, obj) {
934
- for (const [key, value] of Object.entries(obj)) {
678
+ for (const [key, value] of Object.entries(fieldsOf(obj))) {
935
679
  if (this.fields.some((f) => f.name === key)) {
936
680
  this.set(buf, key, value);
937
681
  }
@@ -943,5 +687,5 @@ export function struct(fields, options = {}, sizeof, alloc, readValue, writeValu
943
687
  return this.toObject(this.create(values)._buffer);
944
688
  };
945
689
 
946
- return structDef;
690
+ return syncDefinition(structDef);
947
691
  }