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
@@ -5,7 +5,7 @@
5
5
  *
6
6
  * This module provides the `Structure` base class that users extend to create
7
7
  * custom struct types with automatic field management, memory layout, and
8
- * proxy-based field access.
8
+ * field accessors on the class prototype (as Python field descriptors).
9
9
  *
10
10
  * **Python ctypes Compatibility**:
11
11
  * Direct equivalent to Python's `ctypes.Structure` class with `_fields_` attribute.
@@ -65,6 +65,8 @@
65
65
  */
66
66
 
67
67
  import { kMirrorBase, mirrorBase, mirroredAccessors, mirrorsActive } from "../memory/mirror.js";
68
+ import { copyInstance, fieldsOf, inDllBuffer, sourceBytes } from "./helpers/common.js";
69
+ import { normalizePack } from "./helpers/layout.js";
68
70
 
69
71
  /**
70
72
  * Creates the Structure base class with required dependencies injected.
@@ -75,128 +77,123 @@ import { kMirrorBase, mirrorBase, mirroredAccessors, mirrorsActive } from "../me
75
77
  * @returns {Class} Structure base class
76
78
  * @private
77
79
  */
80
+ function isPlainObject(value) {
81
+ const proto = Object.getPrototypeOf(value);
82
+ return proto === Object.prototype || proto === null;
83
+ }
84
+
78
85
  export function createStructureClass(alloc, struct, bitfield, ptrToBuffer) {
79
86
  // Buffer dell'istanza, letto dall'handler condiviso. Chiave privata e non
80
87
  // `__buffer`, così riassegnare `__buffer` non cambia i campi (come prima).
81
88
  const kBuffer = Symbol("buffer");
89
+ // Definizione (layout) propria di ogni classe, vedi `static get _structDef`.
90
+ const kStructDef = Symbol("structDef");
91
+
92
+ // Definizione con cui è stata creata l'istanza (layout dei suoi byte).
93
+ const kDef = Symbol("def");
94
+ // Istanze dei campi struct/union annidati, create al primo accesso: sono
95
+ // viste sulla memoria dell'istanza, quindi restano valide.
96
+ const kViews = Symbol("views");
97
+ // Nomi dei campi con un accessor installato da noi, per prototipo.
98
+ const installedNames = new WeakMap();
99
+ // Nomi che restano proprietà della libreria anche se usati come campi.
100
+ const reservedNames = new Set(["constructor", "_buffer", "__buffer", "_structDef", "__structDef"]);
101
+
102
+ // Percorso generale di un campo: istanza con un'altra definizione (creata
103
+ // prima di un'invalidazione del layout), copia di memoria nativa (Electron,
104
+ // memory/mirror.js), campi senza lettore precompilato (struct annidate,
105
+ // array, sotto-campi di _anonymous_).
106
+ function readField(inst, name) {
107
+ const def = inst[kDef];
108
+ const base = inst[kMirrorBase];
109
+ const read = (base !== undefined ? mirroredAccessors(def) : def).fieldReaders?.[name];
110
+ return read !== undefined ? read(inst[kBuffer], base) : def.get(inst[kBuffer], name);
111
+ }
112
+
113
+ function writeField(inst, name, value) {
114
+ const def = inst[kDef];
115
+ const base = inst[kMirrorBase];
116
+ const write = (base !== undefined ? mirroredAccessors(def) : def).fieldWriters?.[name];
117
+ if (write !== undefined) write(inst[kBuffer], value, base);
118
+ else def.set(inst[kBuffer], name, value);
119
+ }
82
120
 
83
- // Un handler Proxy per definizione, condiviso da tutte le istanze: prima
84
- // ogni `new` ricreava l'handler (5 closure) e la mappa dei nomi dei campi.
85
- const handlerCache = new WeakMap();
86
- // Istanze su una copia di memoria nativa (Electron, memory/mirror.js):
87
- // stesso handler con lettori e scrittori che sincronizzano il campo.
88
- const mirroredHandlerCache = new WeakMap();
89
-
90
- function getProxyHandler(def, mirrored = false) {
91
- const cache = mirrored ? mirroredHandlerCache : handlerCache;
92
- let handler = cache.get(def);
93
- if (handler !== undefined) return handler;
94
-
95
- // Lookup plana dei nomi (normali + sotto-campi anonymous) su oggetto
96
- // null-proto: bracket access è inline-cached da V8 (più veloce di
97
- // Map.has / Set.has che sono builtin megamorfici).
98
- const allFieldNames = Object.create(null);
121
+ // Python: i campi sono descrittori della classe (CField), non attributi
122
+ // dell'istanza. Qui accessor sul prototipo della classe, condivisi da tutte
123
+ // le istanze: un Proxy per istanza costava ~20 ns per accesso. Il percorso
124
+ // veloce usa il lettore/scrittore precompilato della definizione della classe.
125
+ function installFieldAccessors(Ctor, def) {
126
+ const proto = Ctor.prototype;
127
+ for (const name of installedNames.get(proto) ?? []) {
128
+ delete proto[name];
129
+ }
130
+ const names = [];
99
131
  for (const field of def.fields) {
100
- allFieldNames[field.name] = true;
132
+ names.push(field.name);
101
133
  if (field.isAnonymous && field.type && Array.isArray(field.type.fields)) {
102
- for (const subField of field.type.fields) {
103
- allFieldNames[subField.name] = true;
104
- }
134
+ // Campi promossi (anche da campi anonimi annidati), come Python.
135
+ for (const subField of field.type.fields) names.push(subField.name);
136
+ for (const name of Object.keys(field.type.anonymousFieldNames ?? {})) names.push(name);
105
137
  }
106
138
  }
107
-
108
- // Pre-compiled reader/writer maps from structDef for FAST PATH
109
- // (avoids going through def.get/def.set branching on every access)
110
- const { fieldReaders: readers, fieldWriters: writers } = mirrored ? mirroredAccessors(def) : def;
111
-
112
- handler = {
113
- get(target, prop, receiver) {
114
- // FAST PATH: pre-compiled reader (simple scalar / pointer fields).
115
- // `readers` può essere undefined quando questa Structure è in realtà
116
- // una Union (unionDef non espone fieldReaders al livello esterno).
117
- if (typeof prop === "string") {
118
- const reader = readers !== undefined ? readers[prop] : undefined;
119
- if (reader !== undefined) return reader(target[kBuffer], target[kMirrorBase]);
120
- if (allFieldNames[prop] === true) return def.get(target[kBuffer], prop);
121
- }
122
-
123
- // SLOW PATH: special properties and methods
124
- if (typeof prop === "symbol") {
125
- if (prop === Symbol.toStringTag) return target.constructor.name || "Structure";
126
- return undefined;
127
- }
128
-
129
- if (prop === "_buffer" || prop === "__buffer") return target[kBuffer];
130
- if (prop === "_structDef" || prop === "__structDef") return def;
131
- // La classe, non una sua copia legata (x.constructor === Point).
132
- if (prop === "constructor") return target.constructor;
133
-
134
- const method = target[prop];
135
- if (typeof method === "function") {
136
- // Bind al Proxy (receiver), NON al target raw. Un metodo custom
137
- // come `mag2() { return this.x * this.x + ... }` dentro fa
138
- // `this.x` che deve passare attraverso il Proxy get trap per
139
- // leggere il field. Binding su `target` (istanza raw) salta
140
- // il trap e ritorna undefined → NaN nei calcoli.
141
- return method.bind(receiver);
142
- }
143
-
144
- return Reflect.get(target, prop, receiver);
145
- },
146
- set(target, prop, value, receiver) {
147
- // FAST PATH: pre-compiled writer (null-proto obj, bracket access)
148
- if (typeof prop === "string") {
149
- const writer = writers !== undefined ? writers[prop] : undefined;
150
- if (writer !== undefined) {
151
- writer(target[kBuffer], value, target[kMirrorBase]);
152
- return true;
153
- }
154
- if (allFieldNames[prop] === true) {
155
- def.set(target[kBuffer], prop, value);
156
- return true;
157
- }
158
- }
159
-
160
- return Reflect.set(target, prop, value, receiver);
161
- },
162
- has(target, prop) {
163
- if (typeof prop === "string" && allFieldNames[prop] === true) return true;
164
- if (prop === "_buffer" || prop === "_structDef" || prop === "toObject") return true;
165
- return Reflect.has(target, prop);
166
- },
167
- ownKeys(target) {
168
- const keys = [];
169
- for (const f of def.fields) {
170
- if (f.isAnonymous && f.type && Array.isArray(f.type.fields)) {
171
- for (const sf of f.type.fields) {
172
- keys.push(sf.name);
139
+ const installed = [];
140
+ const nestedClasses = new Map();
141
+ for (const field of def.fields) {
142
+ if (field.isNested && !field.isAnonymous && field.cls !== undefined) nestedClasses.set(field.name, field);
143
+ }
144
+ for (const name of names) {
145
+ if (reservedNames.has(name)) continue;
146
+ const nested = nestedClasses.get(name);
147
+ if (nested !== undefined) {
148
+ const { cls, offset, size } = nested;
149
+ Object.defineProperty(proto, name, {
150
+ get() {
151
+ if (this[kDef] !== def) return readField(this, name);
152
+ let views = this[kViews];
153
+ if (views === undefined) views = this[kViews] = new Map();
154
+ let view = views.get(name);
155
+ if (view === undefined) {
156
+ view = new cls(this[kBuffer].subarray(offset, offset + size));
157
+ views.set(name, view);
173
158
  }
174
- } else {
175
- keys.push(f.name);
176
- }
177
- }
178
- return keys;
179
- },
180
- getOwnPropertyDescriptor(target, prop) {
181
- if (typeof prop === "string" && allFieldNames[prop] === true) {
182
- return {
183
- enumerable: true,
184
- configurable: true,
185
- writable: true,
186
- };
187
- }
188
- if (prop === "_buffer" || prop === "_structDef") {
189
- return {
190
- enumerable: false,
191
- configurable: true,
192
- writable: true,
193
- };
194
- }
195
- return Reflect.getOwnPropertyDescriptor(target, prop);
196
- },
197
- };
198
- cache.set(def, handler);
199
- return handler;
159
+ return view;
160
+ },
161
+ set(value) {
162
+ writeField(this, name, value);
163
+ },
164
+ enumerable: false,
165
+ configurable: true,
166
+ });
167
+ installed.push(name);
168
+ continue;
169
+ }
170
+ const read = def.fieldReaders?.[name];
171
+ const write = def.fieldWriters?.[name];
172
+ Object.defineProperty(proto, name, {
173
+ get:
174
+ read !== undefined
175
+ ? function () {
176
+ if (this[kDef] === def && this[kMirrorBase] === undefined) return read(this[kBuffer]);
177
+ return readField(this, name);
178
+ }
179
+ : function () {
180
+ return readField(this, name);
181
+ },
182
+ set:
183
+ write !== undefined
184
+ ? function (value) {
185
+ if (this[kDef] === def && this[kMirrorBase] === undefined) write(this[kBuffer], value);
186
+ else writeField(this, name, value);
187
+ }
188
+ : function (value) {
189
+ writeField(this, name, value);
190
+ },
191
+ enumerable: false,
192
+ configurable: true,
193
+ });
194
+ installed.push(name);
195
+ }
196
+ installedNames.set(proto, installed);
200
197
  }
201
198
 
202
199
  // Scrittore precompilato del campo quando esiste, altrimenti def.set generico.
@@ -224,12 +221,12 @@ export function createStructureClass(alloc, struct, bitfield, ptrToBuffer) {
224
221
  * Structure base class for creating C-style structures.
225
222
  *
226
223
  * Users extend this class and define static `_fields_` to specify the struct layout.
227
- * The constructor handles memory allocation, field initialization, and returns a
228
- * Proxy for transparent field access.
224
+ * The constructor handles memory allocation and field initialization; the
225
+ * fields are accessors of the class prototype (Python: field descriptors).
229
226
  *
230
227
  * **Key Features**:
231
228
  * - Automatic memory layout based on `_fields_`
232
- * - Proxy-based transparent field access
229
+ * - Field accessors shared by all instances of the class
233
230
  * - Support for positional arguments in constructor
234
231
  * - Buffer wrapping for zero-copy operations
235
232
  * - Anonymous field support via `_anonymous_`
@@ -285,14 +282,19 @@ export function createStructureClass(alloc, struct, bitfield, ptrToBuffer) {
285
282
  class Structure {
286
283
  constructor(...args) {
287
284
  const Ctor = this.constructor;
288
- const def = Ctor._structDef || Ctor._buildStruct();
285
+ // Definizione propria della classe (percorso caldo di `new`: una lettura
286
+ // di proprietà invece di Object.hasOwn).
287
+ const own = Ctor[kStructDef];
288
+ const def = own !== undefined && own.owner === Ctor ? own.def : Ctor._buildStruct();
289
289
  let buf;
290
290
 
291
291
  // Support positional args: new Point(10,20)
292
292
  // Un'istanza di struct/union come unico argomento è posizionale
293
293
  // (Python: RECT(point)), non un oggetto di inizializzazione per nome.
294
294
  const single = args.length === 1 ? args[0] : undefined;
295
- const isNamedInit = typeof single === "object" && single !== null && !Array.isArray(single) && !Buffer.isBuffer(single) && single._structDef === undefined;
295
+ // Solo un oggetto semplice è un'inizializzazione per nome: istanze
296
+ // ctypes (anche SimpleCData, Python: P(c_int(5))) sono posizionali.
297
+ const isNamedInit = typeof single === "object" && single !== null && isPlainObject(single);
296
298
  if (isNamedInit) {
297
299
  // alloc() restituisce un buffer già azzerato (Buffer.alloc)
298
300
  buf = alloc(def.size);
@@ -312,21 +314,54 @@ export function createStructureClass(alloc, struct, bitfield, ptrToBuffer) {
312
314
  if (args.length > 0) {
313
315
  // Positional mapping to non-anonymous declared fields order
314
316
  const ordered = getPositionalFields(def);
315
- for (let i = 0; i < Math.min(args.length, ordered.length); i++) {
317
+ if (args.length > ordered.length) throw new TypeError("too many initializers");
318
+ for (let i = 0; i < args.length; i++) {
316
319
  setField(def, buf, ordered[i].name, args[i]);
317
320
  }
318
321
  }
319
322
  }
320
323
 
321
- // Store internal references on this (needed for methods like toObject)
322
- this.__buffer = buf;
323
- this.__structDef = def;
324
324
  this[kBuffer] = buf;
325
+ this[kDef] = def;
326
+ this[kViews] = undefined;
325
327
  // Indirizzo di una copia di memoria nativa (Electron), undefined altrimenti.
326
- const base = mirrorsActive ? mirrorBase(buf) : undefined;
327
- this[kMirrorBase] = base;
328
+ this[kMirrorBase] = mirrorsActive ? mirrorBase(buf) : undefined;
329
+ }
330
+
331
+ // Memoria e definizione dell'istanza. Riassegnare `__buffer` crea una
332
+ // proprietà propria e non cambia la memoria dei campi.
333
+ get _buffer() {
334
+ return this[kBuffer];
335
+ }
336
+
337
+ get __buffer() {
338
+ return this[kBuffer];
339
+ }
340
+
341
+ set __buffer(value) {
342
+ Object.defineProperty(this, "__buffer", { value, writable: true, configurable: true });
343
+ }
344
+
345
+ get _structDef() {
346
+ return this[kDef];
347
+ }
328
348
 
329
- return new Proxy(this, getProxyHandler(def, base !== undefined));
349
+ get __structDef() {
350
+ return this[kDef];
351
+ }
352
+
353
+ get [Symbol.toStringTag]() {
354
+ return this.constructor.name || "Structure";
355
+ }
356
+
357
+ // I campi non sono proprietà proprie (come in Python): JSON.stringify e
358
+ // util.inspect li mostrano tramite toObject().
359
+ toJSON() {
360
+ return this.toObject();
361
+ }
362
+
363
+ [Symbol.for("nodejs.util.inspect.custom")](depth, options, inspect) {
364
+ return `${this.constructor.name || "Structure"} ${inspect(this.toObject(), options)}`;
330
365
  }
331
366
 
332
367
  // Static getters for size, alignment, and fields (enables use as nested type)
@@ -361,14 +396,10 @@ export function createStructureClass(alloc, struct, bitfield, ptrToBuffer) {
361
396
  * @returns {Structure} A new instance sharing memory with source.
362
397
  */
363
398
  static from_buffer(source, offset = 0) {
364
- if (!Buffer.isBuffer(source)) {
365
- throw new TypeError("from_buffer: source must be a Buffer");
366
- }
367
399
  const def = this._structDef || this._buildStruct();
368
- if (source.length - offset < def.size) {
369
- throw new RangeError(`from_buffer: source too small (${source.length - offset} < ${def.size})`);
370
- }
371
- return new this(source.subarray(offset, offset + def.size));
400
+ const bytes = sourceBytes(source, offset, def.size, "from_buffer");
401
+ // Buffer: subarray (conserva la sincronizzazione delle copie native).
402
+ return new this(Buffer.isBuffer(bytes) ? bytes.subarray(offset, offset + def.size) : Buffer.from(bytes.buffer, bytes.byteOffset + offset, def.size));
372
403
  }
373
404
 
374
405
  /**
@@ -379,22 +410,13 @@ export function createStructureClass(alloc, struct, bitfield, ptrToBuffer) {
379
410
  *
380
411
  * @param {Buffer|Uint8Array} source - Bytes to copy from.
381
412
  * @param {number} [offset=0] - Byte offset into source.
382
- * @returns {Structure} A new instance with an independent buffer.
413
+ * @returns {Structure} A new instance with its own buffer.
383
414
  */
384
415
  static from_buffer_copy(source, offset = 0) {
385
- if (!Buffer.isBuffer(source) && !(source instanceof Uint8Array)) {
386
- throw new TypeError("from_buffer_copy: source must be a Buffer or Uint8Array");
387
- }
388
416
  const def = this._structDef || this._buildStruct();
389
- if (source.length - offset < def.size) {
390
- throw new RangeError(`from_buffer_copy: source too small (${source.length - offset} < ${def.size})`);
391
- }
417
+ const bytes = sourceBytes(source, offset, def.size, "from_buffer_copy");
392
418
  const copy = Buffer.alloc(def.size);
393
- if (Buffer.isBuffer(source)) {
394
- source.copy(copy, 0, offset, offset + def.size);
395
- } else {
396
- copy.set(source.subarray(offset, offset + def.size));
397
- }
419
+ copyInstance(copy, 0, def.size, bytes, offset, def);
398
420
  return new this(copy);
399
421
  }
400
422
 
@@ -410,7 +432,7 @@ export function createStructureClass(alloc, struct, bitfield, ptrToBuffer) {
410
432
  */
411
433
  static from_address(address) {
412
434
  if (!ptrToBuffer) {
413
- throw new Error("from_address requires the native module (ptrToBuffer unavailable)");
435
+ throw new Error("from_address requires the native module (not loaded)");
414
436
  }
415
437
  const addr = typeof address === "bigint" ? address : BigInt(address);
416
438
  const def = this._structDef || this._buildStruct();
@@ -423,83 +445,110 @@ export function createStructureClass(alloc, struct, bitfield, ptrToBuffer) {
423
445
  * Python ctypes parity: `S.in_dll(library, name)`.
424
446
  */
425
447
  static in_dll(library, name) {
426
- const nativeLib = library && library._lib ? library._lib : library;
427
- if (!nativeLib || typeof nativeLib.symbol !== "function") {
428
- throw new TypeError("in_dll: first arg must be a Library (CDLL/WinDLL)");
429
- }
430
- const addr = nativeLib.symbol(name);
431
- if (!addr) {
432
- throw new Error(`in_dll: symbol '${name}' not found`);
433
- }
434
- return this.from_address(addr);
448
+ const def = this._structDef || this._buildStruct();
449
+ return new this(inDllBuffer(library, name, def.size, ptrToBuffer));
435
450
  }
436
451
 
437
452
  // Build the underlying struct definition and cache it on the constructor
438
- static _buildStruct() {
439
- // Accept either array _fields_ (Python style) or object map
440
- const fields = this._fields_ || {};
441
- let mapFields = {};
453
+ // Definizione della classe stessa: una sottoclasse non eredita quella
454
+ // della base (ha un layout proprio, vedi _buildStruct).
455
+ static get _structDef() {
456
+ const own = this[kStructDef];
457
+ return own !== undefined && own.owner === this ? own.def : undefined;
458
+ }
442
459
 
460
+ static set _structDef(def) {
461
+ // null/undefined invalida la cache (il layout viene ricostruito).
462
+ if (def === null || def === undefined) {
463
+ delete this[kStructDef];
464
+ return;
465
+ }
466
+ // { owner, def }: una sottoclasse eredita la proprietà ma non è `owner`.
467
+ Object.defineProperty(this, kStructDef, { value: { owner: this, def }, configurable: true, writable: true });
468
+ installFieldAccessors(this, def);
469
+ }
470
+
471
+ // Classe base con un layout (Python: la sottoclasse ne estende i campi),
472
+ // null per le basi della libreria (Structure, Union, BigEndianStructure...).
473
+ static _baseLayoutClass() {
474
+ const parent = Object.getPrototypeOf(this);
475
+ for (let c = parent; typeof c === "function" && c.prototype instanceof Structure; c = Object.getPrototypeOf(c)) {
476
+ if (Object.hasOwn(c, "_fields_") || c._structDef !== undefined) return parent;
477
+ }
478
+ return null;
479
+ }
480
+
481
+ // `_fields_` della classe come coppie [name, type] nell'ordine dichiarato
482
+ // (un oggetto metterebbe prima i nomi come "1"), con i bitfield
483
+ // `[name, type, bits]` e (se `withAnonymous`) i campi di `_anonymous_`
484
+ // come { anonymous: true, type, cls }.
485
+ static _fieldMap(withAnonymous = true) {
486
+ const fields = Object.hasOwn(this, "_fields_") ? this._fields_ : {};
487
+ let entries;
443
488
  if (Array.isArray(fields)) {
444
- for (const entry of fields) {
445
- if (Array.isArray(entry) && entry.length >= 2) {
446
- const name = entry[0];
447
- const type = entry[1];
448
- // Python-style bitfield: [name, type, bits]
449
- if (entry.length >= 3 && typeof entry[2] === "number") {
450
- mapFields[name] = bitfield(type, entry[2]);
451
- } else {
452
- mapFields[name] = type;
453
- }
489
+ entries = fields.map((entry) => {
490
+ const valid = Array.isArray(entry) && typeof entry[0] === "string" && entry[1] != null && (entry.length === 2 || (entry.length === 3 && typeof entry[2] === "number"));
491
+ if (!valid) {
492
+ throw new TypeError("_fields_ must be a sequence of (name, C type) pairs or (name, C type, bit size) triples");
454
493
  }
455
- }
494
+ return entry.length === 3 ? [entry[0], bitfield(entry[1], entry[2])] : [entry[0], entry[1]];
495
+ });
456
496
  } else if (typeof fields === "object" && fields !== null) {
457
- mapFields = { ...fields };
497
+ entries = Object.entries(fields);
498
+ } else {
499
+ entries = [];
458
500
  }
459
501
 
460
- // Handle anonymous fields list: convert to { anonymous: true, type: T }
461
- if (Array.isArray(this._anonymous_)) {
462
- for (const anonName of this._anonymous_) {
463
- if (mapFields[anonName] !== undefined) {
464
- let anonType = mapFields[anonName];
465
- // Normalize type: if it's a Structure/Union class, get its _structDef
466
- if (typeof anonType === "function" && typeof anonType._buildStruct === "function") {
467
- anonType = anonType._structDef || anonType._buildStruct();
468
- }
469
- mapFields[anonName] = {
470
- anonymous: true,
471
- type: anonType,
472
- };
502
+ if (withAnonymous && Array.isArray(this._anonymous_)) {
503
+ const anonymous = new Set(this._anonymous_);
504
+ entries = entries.map(([name, type]) => {
505
+ if (!anonymous.has(name)) return [name, type];
506
+ // Classe Structure/Union: la sua definizione, e la classe per le istanze.
507
+ if (typeof type === "function" && typeof type._buildStruct === "function") {
508
+ return [name, { anonymous: true, type: type._structDef || type._buildStruct(), cls: type }];
473
509
  }
474
- }
510
+ return [name, { anonymous: true, type }];
511
+ });
475
512
  }
513
+ return entries;
514
+ }
476
515
 
516
+ // Opzioni di layout della classe (ereditate, come getattr in Python):
517
+ // `_pack_`, `_layout_`, `_align_` e byte order.
518
+ static _layoutOptions() {
477
519
  const options = {};
478
- if (this._pack_ !== undefined) {
479
- // Python ctypes: `_pack_` is a positive integer specifying the maximum
480
- // alignment used when laying out fields (1 = fully packed). A boolean
481
- // `true` is tolerated as an alias for `_pack_ = 1`. Anything else is
482
- // rejected so we don't silently produce a mislaid struct.
483
- const p = this._pack_;
484
- if (p === true) {
485
- options.pack = 1;
486
- } else if (p === false) {
487
- // explicit false = no packing, same as absent
488
- } else if (typeof p === "number" && Number.isInteger(p) && p >= 1 && (p & (p - 1)) === 0) {
489
- options.pack = p;
490
- } else {
491
- throw new TypeError(`_pack_ must be a positive power-of-two integer, got ${p}`);
492
- }
493
- if (options.pack !== undefined) options.packed = true;
520
+ if (this._pack_ !== undefined && this._pack_ !== null) {
521
+ options.pack = normalizePack(this._pack_);
522
+ options.packed = options.pack !== 0;
494
523
  }
524
+ // Python ctypes: "ms" (Windows, or with _pack_) or "gcc-sysv" bitfield layout.
525
+ if (this._layout_ !== undefined) options.layout = this._layout_;
526
+ // Python ctypes: `_align_` raises the minimum alignment of the type.
527
+ if (this._align_ !== undefined) options.align = this._align_;
495
528
  // Python ctypes: `_swappedbytes_` (or the BigEndianStructure /
496
529
  // LittleEndianStructure base class) requests byte-swapped fields.
497
530
  // We only officially support LE hosts, so `swapped: true` ⇒ BE layout.
498
531
  if (this._swappedbytes_ === true || this._swapped_ === true) {
499
532
  options.swapped = true;
500
533
  }
534
+ return options;
535
+ }
501
536
 
502
- const def = struct(mapFields, options);
537
+ // Build the underlying struct definition and cache it on the constructor
538
+ static _buildStruct() {
539
+ const own = this._structDef;
540
+ if (own !== undefined) return own;
541
+ const Base = this._baseLayoutClass();
542
+ const base = Base === null ? null : Base._structDef || Base._buildStruct();
543
+ // Python: una sottoclasse senza _fields_ propri ha il layout della base.
544
+ if (base !== null && !Object.hasOwn(this, "_fields_")) {
545
+ this._structDef = base;
546
+ return base;
547
+ }
548
+ if (base !== null && base.isUnion) {
549
+ throw new TypeError("a Structure cannot extend a Union");
550
+ }
551
+ const def = struct(this._fieldMap(), { ...this._layoutOptions(), base });
503
552
  this._structDef = def;
504
553
  return def;
505
554
  }
@@ -559,7 +608,7 @@ export function createStructureClass(alloc, struct, bitfield, ptrToBuffer) {
559
608
 
560
609
  // Bulk operations for better performance
561
610
  setFields(fields) {
562
- for (const [name, value] of Object.entries(fields)) {
611
+ for (const [name, value] of Object.entries(fieldsOf(fields))) {
563
612
  this.__structDef.set(this.__buffer, name, value);
564
613
  }
565
614
  }
@@ -572,7 +621,7 @@ export function createStructureClass(alloc, struct, bitfield, ptrToBuffer) {
572
621
  return result;
573
622
  }
574
623
 
575
- // bulk operations (Proxy reads directly from buffer - no cache needed)
624
+ // bulk operations (fields read directly from the buffer - no cache needed)
576
625
  withBulkUpdate(callback) {
577
626
  return callback(this);
578
627
  }
@@ -82,29 +82,18 @@ export function createUnionClass(Structure, union, bitfield) {
82
82
  */
83
83
  class Union extends Structure {
84
84
  static _buildStruct() {
85
- const fields = this._fields_ || {};
86
- let mapFields = {};
87
- if (Array.isArray(fields)) {
88
- for (const entry of fields) {
89
- if (Array.isArray(entry) && entry.length >= 2) {
90
- const name = entry[0];
91
- const type = entry[1];
92
- // Python-style bitfield: [name, type, bits]
93
- if (entry.length >= 3 && typeof entry[2] === "number") {
94
- mapFields[name] = bitfield(type, entry[2]);
95
- } else {
96
- mapFields[name] = type;
97
- }
98
- }
99
- }
100
- } else if (typeof fields === "object" && fields !== null) {
101
- mapFields = fields;
85
+ if (this._structDef !== undefined) return this._structDef;
86
+ const Base = this._baseLayoutClass();
87
+ const base = Base === null ? null : Base._structDef || Base._buildStruct();
88
+ // Python: una sottoclasse senza _fields_ propri ha il layout della base.
89
+ if (base !== null && !Object.hasOwn(this, "_fields_")) {
90
+ this._structDef = base;
91
+ return base;
102
92
  }
103
- const options = {};
104
- if (this._swappedbytes_ === true || this._swapped_ === true) {
105
- options.swapped = true;
93
+ if (base !== null && !base.isUnion) {
94
+ throw new TypeError("a Union cannot extend a Structure");
106
95
  }
107
- const def = union(mapFields, options);
96
+ const def = union(this._fieldMap(), { ...this._layoutOptions(), base });
108
97
  this._structDef = def;
109
98
  return def;
110
99
  }