node-ctypes 2.13.2 → 2.15.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 (42) hide show
  1. package/CHANGELOG.md +71 -1
  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 +69 -51
  11. package/lib/core/callback-conversions.js +123 -0
  12. package/lib/core/callback.js +68 -4
  13. package/lib/core/conversions.js +74 -412
  14. package/lib/core/funcptr.js +31 -287
  15. package/lib/core/invocation.js +170 -0
  16. package/lib/core/native-aggregate.js +193 -0
  17. package/lib/core/parameters.js +45 -0
  18. package/lib/core/paramflags.js +183 -0
  19. package/lib/core/results.js +86 -0
  20. package/lib/core/types.js +14 -277
  21. package/lib/index.d.ts +3 -0
  22. package/lib/index.js +2 -1
  23. package/lib/memory/buffer.js +1 -1
  24. package/lib/memory/mirror.js +2 -2
  25. package/lib/memory/operations.js +2 -1
  26. package/lib/memory/ownership.js +218 -0
  27. package/lib/memory/pointer.js +6 -1
  28. package/lib/platform/win_types.js +1 -1
  29. package/lib/structures/Structure.js +50 -37
  30. package/lib/structures/helpers/array.js +27 -13
  31. package/lib/structures/helpers/bitfield.js +1 -1
  32. package/lib/structures/helpers/common.js +3 -368
  33. package/lib/structures/helpers/fields.js +111 -0
  34. package/lib/structures/helpers/layout.js +44 -57
  35. package/lib/structures/helpers/struct.js +19 -108
  36. package/lib/structures/helpers/union.js +13 -114
  37. package/lib/structures/helpers/wrap.js +1 -1
  38. package/lib/structures/protocol.js +8 -0
  39. package/lib/types/SimpleCData.js +2 -1
  40. package/lib/types/primitives.js +2 -1
  41. package/lib/types/scalar-protocol.js +120 -0
  42. package/package.json +1 -1
@@ -64,10 +64,16 @@
64
64
  * ```
65
65
  */
66
66
 
67
- import { kMirrorBase, mirrorBase, mirroredAccessors, mirrorsActive } from "../memory/mirror.js";
68
- import { copyInstance, fieldsOf, inDllBuffer, sourceBytes } from "./helpers/common.js";
67
+ import { flush, kMirrorBase, mirrorBase, mirroredAccessors, mirrorsActive } from "../memory/mirror.js";
68
+ import { copyInstance, inDllBuffer, sourceBytes } from "../memory/ownership.js";
69
+ import { fieldsOf } from "./helpers/common.js";
70
+ import { structClass as kCtor } from "./protocol.js";
69
71
  import { normalizePack } from "./helpers/layout.js";
70
72
 
73
+ export const kFromBytes = Symbol("fromBytes");
74
+ export const kFromCallbackBytes = Symbol("fromCallbackBytes");
75
+ const setBytes = Uint8Array.prototype.set;
76
+
71
77
  /**
72
78
  * Creates the Structure base class with required dependencies injected.
73
79
  *
@@ -91,11 +97,8 @@ export function createStructureClass(alloc, struct, bitfield, ptrToBuffer) {
91
97
 
92
98
  // Definizione con cui è stata creata l'istanza (layout dei suoi byte).
93
99
  const kDef = Symbol("def");
94
- // A field may shadow the public constructor property.
95
- const kCtor = Symbol("constructor");
96
- // Istanze dei campi struct/union annidati, create al primo accesso: sono
97
- // viste sulla memoria dell'istanza, quindi restano valide.
98
- const kViews = Symbol("views");
100
+ // A field view keeps its containing instance alive, never the other way round.
101
+ const kBase = Symbol("base");
99
102
  // Nomi dei campi con un accessor installato da noi, per prototipo.
100
103
  const installedNames = new WeakMap();
101
104
  // Nomi che restano proprietà della libreria anche se usati come campi.
@@ -128,6 +131,23 @@ export function createStructureClass(alloc, struct, bitfield, ptrToBuffer) {
128
131
  if (own?.owner === Ctor) own.finalized = true;
129
132
  }
130
133
 
134
+ function instanceLayout(Ctor) {
135
+ const own = Ctor[kStructDef];
136
+ if (own?.owner === Ctor && own.finalized) return own.def;
137
+ const def = own?.owner === Ctor ? own.def : Ctor._buildStruct();
138
+ finalizeFields(Ctor);
139
+ return def;
140
+ }
141
+
142
+ function bindStorage(instance, def, buf, owner) {
143
+ if (buf.length < def.size) throw new RangeError(`Buffer size (${buf.length}) is smaller than struct size (${def.size})`);
144
+ instance[kBuffer] = buf;
145
+ instance[kDef] = def;
146
+ instance[kBase] = owner;
147
+ instance[kMirrorBase] = mirrorsActive ? mirrorBase(buf) : undefined;
148
+ return instance;
149
+ }
150
+
131
151
  // Percorso generale di un campo: istanza con un'altra definizione (creata
132
152
  // prima di un'invalidazione del layout), copia di memoria nativa (Electron,
133
153
  // memory/mirror.js), campi senza lettore precompilato (struct annidate,
@@ -136,7 +156,7 @@ export function createStructureClass(alloc, struct, bitfield, ptrToBuffer) {
136
156
  const def = inst[kDef];
137
157
  const base = inst[kMirrorBase];
138
158
  const read = (base !== undefined ? mirroredAccessors(def) : def).fieldReaders?.[name];
139
- return read !== undefined ? read(inst[kBuffer], base) : def.get(inst[kBuffer], name);
159
+ return read !== undefined ? read(inst[kBuffer], base) : def.get(inst[kBuffer], name, inst);
140
160
  }
141
161
 
142
162
  function writeField(inst, name, value) {
@@ -179,14 +199,7 @@ export function createStructureClass(alloc, struct, bitfield, ptrToBuffer) {
179
199
  Object.defineProperty(proto, name, {
180
200
  get() {
181
201
  if (this[kDef] !== def) return readField(this, name);
182
- let views = this[kViews];
183
- if (views === undefined) views = this[kViews] = new Map();
184
- let view = views.get(name);
185
- if (view === undefined) {
186
- view = new cls(this[kBuffer].subarray(offset, offset + size));
187
- views.set(name, view);
188
- }
189
- return view;
202
+ return cls[kFromBytes](this[kBuffer].subarray(offset, offset + size), this);
190
203
  },
191
204
  set(value) {
192
205
  writeField(this, name, value);
@@ -311,12 +324,7 @@ export function createStructureClass(alloc, struct, bitfield, ptrToBuffer) {
311
324
  */
312
325
  class Structure {
313
326
  constructor(...args) {
314
- const Ctor = new.target;
315
- // Definizione propria della classe (percorso caldo di `new`: una lettura
316
- // di proprietà invece di Object.hasOwn).
317
- const own = Ctor[kStructDef];
318
- const def = own !== undefined && own.owner === Ctor ? own.def : Ctor._buildStruct();
319
- if (own?.owner !== Ctor || !own.finalized) finalizeFields(Ctor);
327
+ const def = instanceLayout(new.target);
320
328
  let buf;
321
329
 
322
330
  // Support positional args: new Point(10,20)
@@ -336,10 +344,6 @@ export function createStructureClass(alloc, struct, bitfield, ptrToBuffer) {
336
344
  } else if (args.length === 1 && Buffer.isBuffer(args[0])) {
337
345
  // new Point(buffer) - wrap existing buffer
338
346
  buf = args[0];
339
- // Validate buffer size matches struct size
340
- if (buf.length < def.size) {
341
- throw new RangeError(`Buffer size (${buf.length}) is smaller than struct size (${def.size})`);
342
- }
343
347
  } else {
344
348
  buf = alloc(def.size);
345
349
  if (args.length > 0) {
@@ -352,11 +356,20 @@ export function createStructureClass(alloc, struct, bitfield, ptrToBuffer) {
352
356
  }
353
357
  }
354
358
 
355
- this[kBuffer] = buf;
356
- this[kDef] = def;
357
- this[kViews] = undefined;
358
- // Indirizzo di una copia di memoria nativa (Electron), undefined altrimenti.
359
- this[kMirrorBase] = mirrorsActive ? mirrorBase(buf) : undefined;
359
+ bindStorage(this, def, buf);
360
+ }
361
+
362
+ static [kFromBytes](buf, owner) {
363
+ return bindStorage(Object.create(this.prototype), instanceLayout(this), buf, owner);
364
+ }
365
+
366
+ static [kFromCallbackBytes](bytes) {
367
+ const value = new this();
368
+ const target = value[kBuffer];
369
+ // Copy into the constructor's storage: it may already have published a field view.
370
+ setBytes.call(target, bytes);
371
+ if (mirrorsActive) flush(target, 0, bytes.length);
372
+ return value;
360
373
  }
361
374
 
362
375
  // Memoria e definizione dell'istanza. Riassegnare `__buffer` crea una
@@ -444,7 +457,7 @@ export function createStructureClass(alloc, struct, bitfield, ptrToBuffer) {
444
457
  const def = this._structDef || this._buildStruct();
445
458
  const bytes = sourceBytes(source, offset, def.size, "from_buffer");
446
459
  // Buffer: subarray (conserva la sincronizzazione delle copie native).
447
- return new this(Buffer.isBuffer(bytes) ? bytes.subarray(offset, offset + def.size) : Buffer.from(bytes.buffer, bytes.byteOffset + offset, def.size));
460
+ return this[kFromBytes](Buffer.isBuffer(bytes) ? bytes.subarray(offset, offset + def.size) : Buffer.from(bytes.buffer, bytes.byteOffset + offset, def.size));
448
461
  }
449
462
 
450
463
  /**
@@ -462,7 +475,7 @@ export function createStructureClass(alloc, struct, bitfield, ptrToBuffer) {
462
475
  const bytes = sourceBytes(source, offset, def.size, "from_buffer_copy");
463
476
  const copy = Buffer.alloc(def.size);
464
477
  copyInstance(copy, 0, def.size, bytes, offset, def);
465
- return new this(copy);
478
+ return this[kFromBytes](copy);
466
479
  }
467
480
 
468
481
  /**
@@ -482,7 +495,7 @@ export function createStructureClass(alloc, struct, bitfield, ptrToBuffer) {
482
495
  const addr = typeof address === "bigint" ? address : BigInt(address);
483
496
  const def = this._structDef || this._buildStruct();
484
497
  const buf = ptrToBuffer(addr, def.size);
485
- return new this(buf);
498
+ return this[kFromBytes](buf);
486
499
  }
487
500
 
488
501
  /**
@@ -491,7 +504,7 @@ export function createStructureClass(alloc, struct, bitfield, ptrToBuffer) {
491
504
  */
492
505
  static in_dll(library, name) {
493
506
  const def = this._structDef || this._buildStruct();
494
- return new this(inDllBuffer(library, name, def.size, ptrToBuffer));
507
+ return this[kFromBytes](inDllBuffer(library, name, def.size, ptrToBuffer));
495
508
  }
496
509
 
497
510
  // Build the underlying struct definition and cache it on the constructor
@@ -645,7 +658,7 @@ export function createStructureClass(alloc, struct, bitfield, ptrToBuffer) {
645
658
 
646
659
  // Instance convenience
647
660
  get(fieldName) {
648
- return this.__structDef.get(this.__buffer, fieldName);
661
+ return this.__structDef.get(this.__buffer, fieldName, this);
649
662
  }
650
663
 
651
664
  set(fieldName, value) {
@@ -662,7 +675,7 @@ export function createStructureClass(alloc, struct, bitfield, ptrToBuffer) {
662
675
  getFields(fieldNames) {
663
676
  const result = {};
664
677
  for (const name of fieldNames) {
665
- result[name] = this.__structDef.get(this.__buffer, name);
678
+ result[name] = this.__structDef.get(this.__buffer, name, this);
666
679
  }
667
680
  return result;
668
681
  }
@@ -105,10 +105,20 @@
105
105
  * ```
106
106
  */
107
107
  import { encodeWide, decodeWide } from "../../memory/buffer.js";
108
- import { copyInstance, funcPtrFieldType, pointerOwner, scalarReader, simpleFieldWriter, writePointerField } from "./common.js";
108
+ import { kFromBytes } from "../Structure.js";
109
+ import { copyInstance, pointerOwner } from "../../memory/ownership.js";
110
+ import { funcPtrFieldType, simpleFieldWriter, writePointerField } from "./common.js";
111
+ import { scalarReader } from "../../types/scalar-protocol.js";
109
112
  import { buildWrapper } from "./wrap.js";
110
113
  import { flush, isMirror, mirrorsActive, refresh } from "../../memory/mirror.js";
111
114
 
115
+ const fieldWrappers = new WeakMap();
116
+ export function readArrayField(type, buffer, owner) {
117
+ if (type._charKind !== undefined) return type.getValue(buffer);
118
+ const wrapField = owner === undefined ? undefined : fieldWrappers.get(type);
119
+ return wrapField === undefined ? type.wrap(buffer) : wrapField(buffer, owner);
120
+ }
121
+
112
122
  // Python: gli array di c_char / c_wchar (anche come campi struct) hanno un
113
123
  // `.value` stringa fino al primo NUL; quelli di c_char anche `.raw` (bytes).
114
124
  function charArrayValue(buf, charKind, wcharSize, swapped) {
@@ -219,10 +229,8 @@ export function array(elementType, count, sizeof, alloc, readValue, writeValue,
219
229
  // serve un'istanza reale).
220
230
  nativeArray = new ArrayType(elementType._type, count);
221
231
  } else {
222
- // Fallback shim (caso Structure/Union come element, o ArrayType
223
- // non disponibile): il native StructType.addField non può unwrappare
224
- // questo shim; l'utilizzo come field di struct-by-value fallirà con
225
- // errore chiaro da `_buildNativeStructType`.
232
+ // Memory views need only the layout. Aggregate and nested arrays acquire
233
+ // their ABI descriptor lazily when used in a by-value field.
226
234
  nativeArray = {
227
235
  getSize: () => count * elementSize,
228
236
  getLength: () => count,
@@ -263,14 +271,14 @@ export function array(elementType, count, sizeof, alloc, readValue, writeValue,
263
271
  };
264
272
  const writePointer = (target, off, value) => writePointerField(target, off, value, elementSize);
265
273
 
266
- const readAt = (target, index) => {
274
+ const readAt = (target, index, owner) => {
267
275
  if (index >= 0 && index < count) {
268
276
  const off = index * elementSize;
269
277
  if (pointerElemType !== null) {
270
278
  return readPointer(target, off);
271
279
  }
272
280
  if (isStructElem) {
273
- return new elementType(target.subarray(off, off + elementSize));
281
+ return elementType[kFromBytes](target.subarray(off, off + elementSize), owner);
274
282
  }
275
283
  if (isStructDef) {
276
284
  const view = target.subarray(off, off + elementSize);
@@ -318,9 +326,9 @@ export function array(elementType, count, sizeof, alloc, readValue, writeValue,
318
326
  // scritto (viene sovrascritto per intero). Gli elementi struct e array sono
319
327
  // istanze che si sincronizzano da sole.
320
328
  const scalarElem = !isStructElem && !isStructDef && !isArrayElem;
321
- const mirroredReadAt = (target, index) => {
329
+ const mirroredReadAt = (target, index, owner) => {
322
330
  if (scalarElem && index >= 0 && index < count) refresh(target, index * elementSize, elementSize);
323
- return readAt(target, index);
331
+ return readAt(target, index, owner);
324
332
  };
325
333
  const mirroredWriteAt = (target, index, value) => {
326
334
  const result = writeAt(target, index, value);
@@ -369,7 +377,7 @@ export function array(elementType, count, sizeof, alloc, readValue, writeValue,
369
377
  get(target, prop, receiver) {
370
378
  const fast = fastIndex(prop);
371
379
  if (fast === fast) {
372
- return readAt(target, fast);
380
+ return readAt(target, fast, receiver);
373
381
  }
374
382
 
375
383
  if (charKind !== undefined) {
@@ -410,7 +418,7 @@ export function array(elementType, count, sizeof, alloc, readValue, writeValue,
410
418
  if (prop === Symbol.iterator) {
411
419
  return function* () {
412
420
  for (let i = 0; i < count; i++) {
413
- yield readAt(target, i);
421
+ yield readAt(target, i, receiver);
414
422
  }
415
423
  };
416
424
  }
@@ -427,7 +435,7 @@ export function array(elementType, count, sizeof, alloc, readValue, writeValue,
427
435
  // If it's a number (index) - intercept BEFORE checking target
428
436
  const index = Number(prop);
429
437
  if (Number.isInteger(index) && !isNaN(index)) {
430
- return readAt(target, index);
438
+ return readAt(target, index, receiver);
431
439
  }
432
440
 
433
441
  const method = elementMethods.get(prop);
@@ -476,7 +484,8 @@ export function array(elementType, count, sizeof, alloc, readValue, writeValue,
476
484
  });
477
485
  const handler = makeHandler(readAt, writeAt, getValue, setValue, setRaw, getRaw);
478
486
  const mirroredHandler = mirrorsActive ? makeHandler(mirroredReadAt, mirroredWriteAt, mirroredGetValue, mirroredSetValue, mirroredSetRaw, mirroredGetRaw) : null;
479
- const wrap = (buffer) => new Proxy(buffer, mirroredHandler !== null && isMirror(buffer) ? mirroredHandler : handler);
487
+ const handlerFor = (buffer) => (mirroredHandler !== null && isMirror(buffer) ? mirroredHandler : handler);
488
+ const wrap = (buffer) => new Proxy(buffer, handlerFor(buffer));
480
489
 
481
490
  // create automatically returns the proxy
482
491
  const create = (values) => {
@@ -578,5 +587,10 @@ export function array(elementType, count, sizeof, alloc, readValue, writeValue,
578
587
  },
579
588
  });
580
589
 
590
+ fieldWrappers.set(ArrayCType, (buffer, owner) => {
591
+ // Keep the owner on this proxy's handler, not on the shared bytes or array type.
592
+ const { get, set } = handlerFor(buffer);
593
+ return new Proxy(buffer, { get, set, owner });
594
+ });
581
595
  return ArrayCType;
582
596
  }
@@ -24,7 +24,7 @@ const writers = {
24
24
  8: { le: (buf, off, v) => buf.writeBigUInt64LE(v, off), be: (buf, off, v) => buf.writeBigUInt64BE(v, off) },
25
25
  };
26
26
 
27
- import { booleanValue, notIntegral } from "./common.js";
27
+ import { booleanValue, notIntegral } from "../../types/scalar-protocol.js";
28
28
 
29
29
  /**
30
30
  * Reader and writer of one bitfield.