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
package/lib/index.d.ts CHANGED
@@ -172,7 +172,11 @@ export class Library {
172
172
  */
173
173
  symbol(name: string): bigint;
174
174
 
175
- /** Close the library and release resources. */
175
+ /**
176
+ * Close the library and release resources. Functions obtained from it
177
+ * throw when called afterwards. Throws while a call to one of its
178
+ * functions is in progress (from a callback, or a pending `callAsync()`).
179
+ */
176
180
  close(): void;
177
181
 
178
182
  /** Library file path. */
@@ -312,13 +316,22 @@ export interface TypedFFIFunction<TArgs extends readonly FFIType[], TRet extends
312
316
  */
313
317
  export interface LibraryOptions {
314
318
  /**
315
- * `dlopen` flags combined with `RTLD_LAZY` (e.g. {@link RTLD_GLOBAL}).
319
+ * `dlopen` flags combined with `RTLD_NOW` (e.g. {@link RTLD_GLOBAL}).
316
320
  * Ignored on Windows. Default: {@link DEFAULT_MODE}.
317
321
  *
318
322
  * Python ctypes parity: the `mode` argument of `CDLL(name, mode)`.
319
323
  */
320
324
  mode?: number;
321
325
 
326
+ /**
327
+ * `LoadLibraryExW` flags (Windows only). Default: `LOAD_LIBRARY_SEARCH_DEFAULT_DIRS`,
328
+ * plus `LOAD_LIBRARY_SEARCH_DLL_LOAD_DIR` (with the path made absolute) when the
329
+ * name contains a path separator.
330
+ *
331
+ * Python ctypes parity: the `winmode` argument of `CDLL(name, winmode=...)`.
332
+ */
333
+ winmode?: number;
334
+
322
335
  /**
323
336
  * Maximum size of the internal function cache. Default: 1000.
324
337
  */
@@ -370,7 +383,11 @@ export class CDLL {
370
383
  */
371
384
  symbol(name: string): bigint;
372
385
 
373
- /** Close the library and clear the function cache. */
386
+ /**
387
+ * Close the library and clear the function cache. Functions obtained from
388
+ * it throw when called afterwards. Throws while a call to one of its
389
+ * functions is in progress (from a callback, or a pending `callAsync()`).
390
+ */
374
391
  close(): void;
375
392
 
376
393
  /** Close the library at the end of a `using` block. */
@@ -790,11 +807,27 @@ type PointerContents<T> = IsAny<T> extends true ? any : T extends SimpleCDataCon
790
807
  type CharArrayValue<E, Else> = IsAny<E> extends true ? Else : [E] extends [SimpleCDataConstructor<"char">] ? string : [E] extends [SimpleCDataConstructor<"wchar">] ? string : Else;
791
808
 
792
809
  /**
793
- * Array instance: a Buffer with index access; `c_char` arrays also expose
794
- * `.value`/`.raw` and `c_wchar` arrays `.value`, as in Python.
810
+ * Array instance: a Buffer with index access; the Array methods (`slice`, `map`,
811
+ * `includes`, ...) work on the elements, as Python's sequence operations.
812
+ * `c_char` arrays also expose `.value`/`.raw` and `c_wchar` arrays `.value`.
795
813
  * @category Structures
796
814
  */
797
- export type ArrayInstance<E = any> = Buffer & ArrayProxy<ArrayElement<E>> & (IsAny<E> extends true ? {} : [E] extends [SimpleCDataConstructor<"char">] ? CharBufferValue : [E] extends [SimpleCDataConstructor<"wchar">] ? WideBufferValue : {});
815
+ export type ArrayInstance<E = any> = Omit<Buffer, ElementMethod | "length" | "toJSON"> &
816
+ (IsAny<E> extends true
817
+ ? ArrayProxy<any>
818
+ : [E] extends [SimpleCDataConstructor<"char">]
819
+ ? Omit<ArrayProxy<ArrayElement<E>>, "slice"> & CharBufferValue & CharSlice
820
+ : [E] extends [SimpleCDataConstructor<"wchar">]
821
+ ? Omit<ArrayProxy<ArrayElement<E>>, "slice"> & WideBufferValue & CharSlice
822
+ : ArrayProxy<ArrayElement<E>>);
823
+
824
+ /** Array methods that work on the elements of an array instance; the Buffer methods (`readInt32LE`, `subarray`, ...) work on the bytes. */
825
+ type ElementMethod = Exclude<keyof ArrayProxy, number | typeof Symbol.iterator | "length" | "toJSON">;
826
+
827
+ /** `c_char` / `c_wchar` arrays: a slice is a string (Python: bytes / str). */
828
+ interface CharSlice {
829
+ slice(start?: number, end?: number): string;
830
+ }
798
831
 
799
832
  /**
800
833
  * Text accessors of `c_char` buffers (arrays, {@link create_string_buffer}).
@@ -824,17 +857,18 @@ type ArgsFromCTypes<TArgs extends readonly any[]> = {
824
857
  };
825
858
 
826
859
  /** JS argument accepted for a function parameter of type `T`. */
827
- type JsArgFromFFIType<T> = T extends StructureClass ? Buffer | { _buffer: Buffer } | Record<string, any> : JsArgFromCType<T>;
860
+ type JsArgFromFFIType<T> = T extends StructureClass ? Buffer | { _buffer: Buffer } | Record<string, any> : T extends ArrayTypeDef<infer E> ? ArrayInstance<E> | ArrayBufferView | ArrayBuffer | { readonly _as_parameter_: unknown } : JsArgFromCType<T>;
828
861
 
829
862
  /** Function arguments for `argtypes` `TArgs` (`any[]` when not a literal tuple). */
830
863
  type FFIArgs<TArgs extends readonly any[]> = FFIType[] extends TArgs ? any[] : { [K in keyof TArgs]: JsArgFromFFIType<TArgs[K]> };
831
864
 
832
865
  /**
833
866
  * JS value returned by a function with `restype` `T`. As in Python, a
834
- * `POINTER(T)` restype returns a {@link PointerInstance} and a {@link CFUNCTYPE}
835
- * restype a callable function (`null` for NULL).
867
+ * `POINTER(T)` restype returns a {@link PointerInstance}, a {@link CFUNCTYPE}
868
+ * restype a callable function (`null` for NULL) and a Structure/Union class an
869
+ * instance of that class.
836
870
  */
837
- type FFIReturn<T> = FFIType extends T ? any : T extends null ? undefined : T extends StructureClass ? Record<string, any> : JsFromCType<T>;
871
+ type FFIReturn<T> = FFIType extends T ? any : T extends null ? undefined : T extends StructureClass ? InstanceType<T> : JsFromCType<T>;
838
872
 
839
873
  /**
840
874
  * A union type definition created by the {@link union} function.
@@ -914,15 +948,70 @@ export interface ArrayTypeDef<E = any> {
914
948
  create(values?: ReadonlyArray<ArrayElementArg<E>> | string): ArrayInstance<E>;
915
949
  /** Wrap an existing buffer as an array with index access. */
916
950
  wrap(buffer: Buffer): ArrayInstance<E>;
951
+ /**
952
+ * Array sharing the memory of `source` from `offset` (Python:
953
+ * `(c_int * 3).from_buffer(source, offset)`).
954
+ */
955
+ from_buffer(source: Buffer | Uint8Array | { _buffer: Buffer }, offset?: number): ArrayInstance<E>;
956
+ /** Array with a copy of the bytes of `source` from `offset` (Python: `from_buffer_copy`). */
957
+ from_buffer_copy(source: Buffer | Uint8Array | { _buffer: Buffer }, offset?: number): ArrayInstance<E>;
958
+ /**
959
+ * Array on the memory at `address` (Python: `(c_int * 3).from_address(address)`).
960
+ * Its `_buffer` is a Buffer over that memory, as Python's
961
+ * `memoryview((c_char * n).from_address(address))`; where
962
+ * {@link EXTERNAL_BUFFERS} is `false` it is a copy kept in sync by the
963
+ * array's element accesses.
964
+ */
965
+ from_address(address: bigint | number): ArrayInstance<E>;
917
966
  }
918
967
 
919
968
  /**
920
969
  * Proxy interface for array index access and iteration.
921
970
  * @category Structures
922
971
  */
923
- export interface ArrayProxy<T = any> {
972
+ export interface ArrayProxy<T = any> extends Pick<
973
+ T[],
974
+ | "at"
975
+ | "copyWithin"
976
+ | "entries"
977
+ | "every"
978
+ | "fill"
979
+ | "filter"
980
+ | "find"
981
+ | "findIndex"
982
+ | "findLast"
983
+ | "findLastIndex"
984
+ | "forEach"
985
+ | "includes"
986
+ | "indexOf"
987
+ | "join"
988
+ | "keys"
989
+ | "lastIndexOf"
990
+ | "map"
991
+ | "reduce"
992
+ | "reduceRight"
993
+ | "reverse"
994
+ | "slice"
995
+ | "some"
996
+ | "sort"
997
+ | "toLocaleString"
998
+ | "toReversed"
999
+ | "toSorted"
1000
+ | "values"
1001
+ | "with"
1002
+ > {
924
1003
  [index: number]: T;
925
1004
  [Symbol.iterator](): Iterator<T>;
1005
+ /** Number of elements (Python `len(arr)`); the size in bytes is `byteLength`. */
1006
+ readonly length: number;
1007
+ /** The elements, for `JSON.stringify`. */
1008
+ toJSON(): T[];
1009
+ /**
1010
+ * The Buffer of the array: for an array on native memory
1011
+ * ({@link ArrayTypeDef.from_address}) a Buffer over that memory, as
1012
+ * Python's `memoryview()` (a copy where {@link EXTERNAL_BUFFERS} is `false`).
1013
+ */
1014
+ readonly _buffer: Buffer;
926
1015
  }
927
1016
 
928
1017
  /**
@@ -930,8 +1019,14 @@ export interface ArrayProxy<T = any> {
930
1019
  * @category Structures
931
1020
  */
932
1021
  export interface StructOptions {
933
- /** If `true`, disables padding between fields. */
1022
+ /** If `true`, disables padding between fields (as `pack: 1`). */
934
1023
  packed?: boolean;
1024
+ /** Maximum field alignment in bytes, as Python's `_pack_`. */
1025
+ pack?: number;
1026
+ /** Bit field layout, as Python's `_layout_` (`"ms"` with `pack`, otherwise the platform's). */
1027
+ layout?: "gcc-sysv" | "ms";
1028
+ /** Minimum alignment in bytes, as Python's `_align_`. */
1029
+ align?: number;
935
1030
  }
936
1031
 
937
1032
  /**
@@ -1220,6 +1315,15 @@ export class Structure<F extends Record<string, FieldSpec> = Record<string, any>
1220
1315
  */
1221
1316
  static _pack_?: number | boolean;
1222
1317
 
1318
+ /**
1319
+ * Bit field layout, as Python's `_layout_`: `"gcc-sysv"` (default except on
1320
+ * Windows) or `"ms"` (default on Windows and with `_pack_`).
1321
+ */
1322
+ static _layout_?: "gcc-sysv" | "ms";
1323
+
1324
+ /** Minimum alignment in bytes, as Python's `_align_`. */
1325
+ static _align_?: number;
1326
+
1223
1327
  /**
1224
1328
  * List of field names whose members are promoted to the parent struct.
1225
1329
  *
@@ -1227,6 +1331,15 @@ export class Structure<F extends Record<string, FieldSpec> = Record<string, any>
1227
1331
  */
1228
1332
  static _anonymous_?: ReadonlyArray<string>;
1229
1333
 
1334
+ /** Size in bytes (Python: `sizeof(cls)`). */
1335
+ static readonly size: number;
1336
+
1337
+ /** Alignment in bytes (Python: `alignment(cls)`). */
1338
+ static readonly alignment: number;
1339
+
1340
+ /** Field descriptors, in layout order. */
1341
+ static readonly fields: FieldDef[];
1342
+
1230
1343
  /** Create instance with optional initial values. */
1231
1344
  static create<ThisT extends Structure<F>>(this: new (...args: any[]) => ThisT, values?: Partial<FieldsToInstance<F>> | Buffer): ThisT;
1232
1345
 
@@ -1239,14 +1352,14 @@ export class Structure<F extends Record<string, FieldSpec> = Record<string, any>
1239
1352
  *
1240
1353
  * Python ctypes parity: `Structure.from_buffer(source, offset=0)`.
1241
1354
  */
1242
- static from_buffer<ThisT extends Structure<F>>(this: new (...args: any[]) => ThisT, source: Buffer, offset?: number): ThisT;
1355
+ static from_buffer<ThisT extends Structure<F>>(this: new (...args: any[]) => ThisT, source: ArrayBufferView | { _buffer: Buffer }, offset?: number): ThisT;
1243
1356
 
1244
1357
  /**
1245
1358
  * Create an instance whose buffer is an independent copy of the source bytes.
1246
1359
  *
1247
1360
  * Python ctypes parity: `Structure.from_buffer_copy(source, offset=0)`.
1248
1361
  */
1249
- static from_buffer_copy<ThisT extends Structure<F>>(this: new (...args: any[]) => ThisT, source: Buffer | Uint8Array, offset?: number): ThisT;
1362
+ static from_buffer_copy<ThisT extends Structure<F>>(this: new (...args: any[]) => ThisT, source: ArrayBufferView | { _buffer: Buffer }, offset?: number): ThisT;
1250
1363
 
1251
1364
  /**
1252
1365
  * Create an instance that views raw memory at `address`. Caller is
@@ -1280,7 +1393,10 @@ export class Structure<F extends Record<string, FieldSpec> = Record<string, any>
1280
1393
  /** Convert all fields to a plain JavaScript object (snapshot). */
1281
1394
  toObject(): FieldsToInstance<F>;
1282
1395
 
1283
- /** Dynamic field access via Proxy. */
1396
+ /** The fields, for `JSON.stringify` (same as {@link toObject}). */
1397
+ toJSON(): FieldsToInstance<F>;
1398
+
1399
+ /** Fields: accessors of the class (not own properties, as in Python). */
1284
1400
  [field: string]: any;
1285
1401
  }
1286
1402
 
@@ -1603,6 +1719,13 @@ export function wstring_at(address: Buffer | bigint | number, size?: number): st
1603
1719
  */
1604
1720
  export function addressof(ptr: Buffer | bigint | number): bigint;
1605
1721
 
1722
+ /**
1723
+ * Memory argument of {@link memmove} / {@link memset}: a buffer (any typed
1724
+ * array, DataView or ArrayBuffer, as bytes), a ctypes instance, a pointer or an
1725
+ * address.
1726
+ */
1727
+ export type MemoryTarget = ArrayBufferView | ArrayBufferLike | { readonly _buffer: Buffer } | PointerInstance | bigint | number;
1728
+
1606
1729
  /**
1607
1730
  * Copy memory from source to destination.
1608
1731
  *
@@ -1610,9 +1733,6 @@ export function addressof(ptr: Buffer | bigint | number): bigint;
1610
1733
  *
1611
1734
  * @category Memory
1612
1735
  */
1613
- /** Memory argument of {@link memmove} / {@link memset}: a buffer, a ctypes instance, a pointer or an address. */
1614
- export type MemoryTarget = Uint8Array | { readonly _buffer: Buffer } | PointerInstance | bigint | number;
1615
-
1616
1736
  export function memmove(dst: MemoryTarget, src: MemoryTarget, count: number): void;
1617
1737
 
1618
1738
  /**
@@ -1640,8 +1760,8 @@ export function memset(dst: MemoryTarget, value: number, count: number): void;
1640
1760
  *
1641
1761
  * @category Memory
1642
1762
  */
1643
- export function readValue<T extends AnyType>(ptr: Buffer | bigint | number | PointerInstance, type: T, offset?: number): JsFromCType<T>;
1644
- export function readValue(ptr: Buffer | bigint | number | PointerInstance, type: AnyType | StructureClass, offset?: number): any;
1763
+ export function readValue<T extends AnyType>(ptr: MemorySource, type: T, offset?: number): JsFromCType<T>;
1764
+ export function readValue(ptr: MemorySource, type: AnyType | StructureClass, offset?: number): any;
1645
1765
 
1646
1766
  /**
1647
1767
  * Write a typed value to a buffer at a given offset.
@@ -1653,8 +1773,8 @@ export function readValue(ptr: Buffer | bigint | number | PointerInstance, type:
1653
1773
  *
1654
1774
  * @category Memory
1655
1775
  */
1656
- export function writeValue<T extends AnyType>(ptr: Buffer | bigint | number | PointerInstance, type: T, value: JsArgFromCType<T>, offset?: number): number | void;
1657
- export function writeValue(ptr: Buffer | bigint | number | PointerInstance, type: AnyType | StructureClass, value: any, offset?: number): number | void;
1776
+ export function writeValue<T extends AnyType>(ptr: MemorySource, type: T, value: JsArgFromCType<T>, offset?: number): number | void;
1777
+ export function writeValue(ptr: MemorySource, type: AnyType | StructureClass, value: any, offset?: number): number | void;
1658
1778
 
1659
1779
  /**
1660
1780
  * Get the size of a type in bytes.
@@ -1670,7 +1790,10 @@ export function writeValue(ptr: Buffer | bigint | number | PointerInstance, type
1670
1790
  *
1671
1791
  * @category Memory
1672
1792
  */
1673
- export function sizeof(type: AnyType | StructDef | ArrayTypeDef | StructureClass | PointerTypeDef | FuncPtrFactory | SimpleCDataInstance | Structure<any> | Uint8Array): number;
1793
+ export function sizeof(type: AnyType | StructDef | ArrayTypeDef | StructureClass | PointerTypeDef | FuncPtrFactory | SimpleCDataInstance | Structure<any> | ArrayBufferView): number;
1794
+
1795
+ /** Memory read/written by {@link readValue} / {@link writeValue}: a buffer, a ctypes instance, a pointer or an address. */
1796
+ type MemorySource = Buffer | ArrayBufferView | { _buffer: Buffer } | bigint | number | PointerInstance;
1674
1797
 
1675
1798
  /**
1676
1799
  * Get the alignment requirement of a type in bytes.
@@ -1688,18 +1811,6 @@ export function sizeof(type: AnyType | StructDef | ArrayTypeDef | StructureClass
1688
1811
  */
1689
1812
  export function alignment(type: AnyType | StructDef | ArrayTypeDef | StructureClass | PointerTypeDef | FuncPtrFactory | SimpleCDataInstance | Structure<any>): number;
1690
1813
 
1691
- /**
1692
- * Create a Buffer view of native memory at a given address.
1693
- *
1694
- * **Warning:** Use with caution — the buffer is not bounds-checked.
1695
- *
1696
- * @param address - Native memory address
1697
- * @param size - Number of bytes
1698
- *
1699
- * @category Memory
1700
- */
1701
- export function ptrToBuffer(address: bigint | number, size: number): Buffer;
1702
-
1703
1814
  /**
1704
1815
  * Define a struct using the functional API.
1705
1816
  *
@@ -1725,10 +1836,11 @@ export function struct<F extends Record<string, FieldSpec>>(fields: F, options?:
1725
1836
  * For Python-like class syntax, use {@link Union} instead.
1726
1837
  *
1727
1838
  * @param fields - Object mapping field names to types
1839
+ * @param options - Union options (e.g. `{ pack: 1 }`)
1728
1840
  *
1729
1841
  * @category Structures
1730
1842
  */
1731
- export function union<F extends Record<string, FieldSpec>>(fields: F): UnionDef<F>;
1843
+ export function union<F extends Record<string, FieldSpec>>(fields: F, options?: StructOptions): UnionDef<F>;
1732
1844
 
1733
1845
  /**
1734
1846
  * Factory that returns a Structure subclass with typed fields.
@@ -1738,7 +1850,7 @@ export function union<F extends Record<string, FieldSpec>>(fields: F): UnionDef<
1738
1850
  *
1739
1851
  * @category Structures
1740
1852
  */
1741
- export function defineStruct<F extends Record<string, FieldSpec>>(fields: F, options?: StructOptions): new (values?: Partial<FieldsToInstance<F>> | Buffer) => Structure<F> & FieldsToInstance<F>;
1853
+ export function defineStruct<F extends Record<string, FieldSpec>>(fields: F, options?: StructOptions): DefinedClass<F, Structure<F> & FieldsToInstance<F>>;
1742
1854
 
1743
1855
  /**
1744
1856
  * Factory that returns a Union subclass with typed fields.
@@ -1747,7 +1859,27 @@ export function defineStruct<F extends Record<string, FieldSpec>>(fields: F, opt
1747
1859
  *
1748
1860
  * @category Structures
1749
1861
  */
1750
- export function defineUnion<F extends Record<string, FieldSpec>>(fields: F): new (values?: Partial<FieldsToInstance<F>> | Buffer) => Union<F> & FieldsToInstance<F>;
1862
+ export function defineUnion<F extends Record<string, FieldSpec>>(fields: F, options?: StructOptions): DefinedClass<F, Union<F> & FieldsToInstance<F>>;
1863
+
1864
+ /**
1865
+ * Class returned by {@link defineStruct} / {@link defineUnion}: the statics of
1866
+ * {@link Structure} and a constructor with positional values (field order),
1867
+ * an object of field values or a Buffer.
1868
+ * @category Structures
1869
+ */
1870
+ export interface DefinedClass<F extends Record<string, FieldSpec>, I> {
1871
+ new (values?: Partial<FieldsToInstance<F>> | Buffer): I;
1872
+ new (...values: any[]): I;
1873
+ readonly size: number;
1874
+ readonly alignment: number;
1875
+ readonly fields: FieldDef[];
1876
+ create(values?: Partial<FieldsToInstance<F>> | Buffer): I;
1877
+ toObject(bufOrInstance: Buffer | I): FieldsToInstance<F>;
1878
+ from_buffer(source: ArrayBufferView | { _buffer: Buffer }, offset?: number): I;
1879
+ from_buffer_copy(source: ArrayBufferView | { _buffer: Buffer }, offset?: number): I;
1880
+ from_address(address: bigint | number): I;
1881
+ in_dll(library: CDLL | Library, name: string): I;
1882
+ }
1751
1883
 
1752
1884
  /**
1753
1885
  * Define a fixed-size array type.
@@ -1766,18 +1898,21 @@ export function defineUnion<F extends Record<string, FieldSpec>>(fields: F): new
1766
1898
  *
1767
1899
  * @category Structures
1768
1900
  */
1769
- export function array<E extends AnyType | StructureClass | ArrayTypeDef | PointerTypeDef | FuncPtrFactory>(elementType: E, count: number): ArrayTypeDef<E>;
1901
+ export function array<E extends ArrayElementType>(elementType: E, count: number): ArrayTypeDef<E>;
1902
+
1903
+ /** Element types of {@link array}: C types, structures and unions (classes or definitions), arrays, pointers, function pointers. */
1904
+ type ArrayElementType = SimpleCDataConstructor | StructDef | UnionDef | StructureClass | ArrayTypeDef | PointerTypeDef | FuncPtrFactory;
1770
1905
 
1771
1906
  /**
1772
1907
  * Alias of {@link array}. Python equivalent: `ctypes.ARRAY(type, length)`.
1773
1908
  * @category Structures
1774
1909
  */
1775
- export function ARRAY<E extends AnyType | StructureClass | ArrayTypeDef | PointerTypeDef | FuncPtrFactory>(elementType: E, count: number): ArrayTypeDef<E>;
1910
+ export function ARRAY<E extends ArrayElementType>(elementType: E, count: number): ArrayTypeDef<E>;
1776
1911
 
1777
1912
  /**
1778
1913
  * Define a bit field for use in struct `_fields_`.
1779
1914
  *
1780
- * @param baseType - The underlying integer type (e.g. `c_uint32`)
1915
+ * @param baseType - The underlying integer type (e.g. `c_uint32`) or `c_bool`; other types raise TypeError, as in Python
1781
1916
  * @param bits - Number of bits
1782
1917
  *
1783
1918
  * @example
@@ -1792,7 +1927,7 @@ export function ARRAY<E extends AnyType | StructureClass | ArrayTypeDef | Pointe
1792
1927
  *
1793
1928
  * @category Structures
1794
1929
  */
1795
- export function bitfield(baseType: AnyType, bits: number): BitFieldDef;
1930
+ export function bitfield(baseType: SimpleCDataConstructor, bits: number): BitFieldDef;
1796
1931
 
1797
1932
  /**
1798
1933
  * Pass an object by reference (returns its underlying buffer).
@@ -1956,7 +2091,7 @@ export function set_last_error(code: number): number;
1956
2091
  * @category Error Handling
1957
2092
  */
1958
2093
  export class ArgumentError extends TypeError {
1959
- constructor(message?: string);
2094
+ constructor(message?: string, options?: ErrorOptions);
1960
2095
  }
1961
2096
 
1962
2097
  /**
@@ -1976,11 +2111,12 @@ export function FormatError(code?: number): string;
1976
2111
  * Python equivalent: `ctypes.WinError()`
1977
2112
  *
1978
2113
  * @param code - Error code (defaults to `GetLastError()`)
1979
- * @returns Error with `.winerror` property
2114
+ * @param descr - Message (defaults to `FormatError(code)`)
2115
+ * @returns Error with `winerror`, `errno` (mapped as Python's OSError) and `strerror`
1980
2116
  *
1981
2117
  * @category Error Handling
1982
2118
  */
1983
- export function WinError(code?: number): Error & { winerror: number };
2119
+ export function WinError(code?: number | null, descr?: string): Error & { winerror: number; errno: number; strerror: string };
1984
2120
 
1985
2121
  // =============================================================================
1986
2122
  // SimpleCData - Base class for simple C data types
@@ -2393,6 +2529,15 @@ export const SimpleCData: SimpleCDataConstructor;
2393
2529
  */
2394
2530
  export const POINTER_SIZE: number;
2395
2531
 
2532
+ /**
2533
+ * `false` where the runtime does not allow Buffers over native memory
2534
+ * (Electron, or `NODE_CTYPES_NO_EXTERNAL_BUFFERS=1`). ctypes instances on
2535
+ * native memory (`from_address`, `in_dll`, pointers) then work on a
2536
+ * synchronized copy, and their `_buffer` is that copy.
2537
+ * @category Constants
2538
+ */
2539
+ export const EXTERNAL_BUFFERS: boolean;
2540
+
2396
2541
  /**
2397
2542
  * Size of `wchar_t` in bytes (2 on Windows, 4 on Unix).
2398
2543
  * @category Constants
@@ -2440,8 +2585,9 @@ export const DEFAULT_MODE: number;
2440
2585
  * are provided (e.g. `"c"` → `"msvcrt.dll"`).
2441
2586
  * - On Linux, the `ldconfig` cache and common library directories are
2442
2587
  * searched for the best-matching `libNAME.so.VERSION`.
2443
- * - On macOS, `/usr/lib`, `/usr/local/lib`, Homebrew prefixes and framework
2444
- * bundles are searched.
2588
+ * - On macOS, the `DYLD_*` paths, the dyld fallback directories, Homebrew and
2589
+ * the framework directories are searched, including the dyld shared cache
2590
+ * (system libraries and frameworks are not on disk since macOS 11).
2445
2591
  *
2446
2592
  * Returns `null` if the input is invalid. Returns a best-effort fallback
2447
2593
  * (bare soname) if nothing is found, so the loader can still try its own
package/lib/index.js CHANGED
@@ -39,11 +39,11 @@ import {
39
39
  memset as _memset,
40
40
  } from "./memory/buffer.js";
41
41
  import { createMemoryOps } from "./memory/operations.js";
42
+ import { enableMirrors, wrapNative } from "./memory/mirror.js";
42
43
  import { addressOf as _addressOf, byref as _byref, cast as _cast, ptrToBuffer as _ptrToBuffer, POINTER as _POINTER, pointer as _pointer } from "./memory/pointer.js";
43
44
  import { FormatError as _FormatError, WinError as _WinError, ArgumentError } from "./platform/errors.js";
44
45
  import { bitfield as _bitfield, _isStruct, _isArrayType, _isBitField } from "./structures/helpers/common.js";
45
46
  import { array as _array } from "./structures/helpers/array.js";
46
- import { _readBitField as _readBitFieldHelper, _writeBitField as _writeBitFieldHelper, _readUintFromBuffer, _writeUintToBuffer } from "./structures/helpers/bitfield.js";
47
47
  import { union as _union } from "./structures/helpers/union.js";
48
48
  import { struct as _struct } from "./structures/helpers/struct.js";
49
49
  import { createStructureClass } from "./structures/Structure.js";
@@ -98,7 +98,14 @@ const findNativeModule = () => {
98
98
  };
99
99
 
100
100
  const require = createRequire(import.meta.url);
101
- const native = require(findNativeModule());
101
+ const rawNative = require(findNativeModule());
102
+
103
+ // Senza Buffer esterni (Electron) le view sulla memoria nativa diventano copie
104
+ // sincronizzate (memory/mirror.js). NODE_CTYPES_NO_EXTERNAL_BUFFERS=1 forza la
105
+ // stessa modalità su Node.js, per provarla senza Electron.
106
+ const externalBuffers = rawNative.externalBuffersAllowed !== false && process.env.NODE_CTYPES_NO_EXTERNAL_BUFFERS !== "1";
107
+ if (!externalBuffers) enableMirrors(rawNative);
108
+ const native = externalBuffers ? rawNative : wrapNative(rawNative);
102
109
 
103
110
  // Initialize platform constants from native module
104
111
  _initConstants(native);
@@ -256,12 +263,24 @@ function cast(ptr, targetType) {
256
263
  return _cast(ptr, targetType, readValue, sizeof, ptrToBuffer, native);
257
264
  }
258
265
 
266
+ // Uso interno (from_address, cast, ...): una view della memoria nativa, o una
267
+ // copia sincronizzata dove i Buffer esterni non sono permessi.
259
268
  function ptrToBuffer(address, size) {
260
269
  return _ptrToBuffer(address, size, native);
261
270
  }
262
271
 
272
+ // Python: POINTER(T) is POINTER(T) e (T * n) is (T * n): un tipo per base.
273
+ const pointerTypes = new WeakMap();
274
+ const arrayTypes = new WeakMap();
275
+
263
276
  function POINTER(baseType) {
264
- return _POINTER(baseType, sizeof, alloc, readValue, writeValue, c_void_p, native);
277
+ const cacheable = baseType !== null && (typeof baseType === "object" || typeof baseType === "function");
278
+ let type = cacheable ? pointerTypes.get(baseType) : undefined;
279
+ if (type === undefined) {
280
+ type = _POINTER(baseType, sizeof, alloc, readValue, writeValue, c_void_p, native);
281
+ if (cacheable) pointerTypes.set(baseType, type);
282
+ }
283
+ return type;
265
284
  }
266
285
 
267
286
  /**
@@ -281,7 +300,7 @@ function POINTER(baseType) {
281
300
  * ```
282
301
  */
283
302
  function pointer(obj) {
284
- return _pointer(obj, _POINTER, sizeof, alloc, readValue, writeValue, c_void_p, native);
303
+ return _pointer(obj, POINTER, sizeof, alloc, readValue, writeValue, c_void_p, native);
285
304
  }
286
305
 
287
306
  /**
@@ -310,8 +329,8 @@ function defineStruct(fields, options) {
310
329
  /**
311
330
  * Helper to define a JS class backed by a union definition.
312
331
  */
313
- function defineUnion(fields) {
314
- const def = union(fields);
332
+ function defineUnion(fields, options) {
333
+ const def = union(fields, options);
315
334
  class AutoUnion extends Union {}
316
335
  AutoUnion._structDef = def;
317
336
  AutoUnion._fields_ = fields;
@@ -352,7 +371,17 @@ memoryDeps.Union = Union;
352
371
  * console.log(arr[2]); // 42
353
372
  */
354
373
  function array(elementType, count) {
355
- return _array(elementType, count, sizeof, alloc, readValue, writeValue, Structure, Union, ArrayType, c_void_p);
374
+ const cacheable = elementType !== null && (typeof elementType === "object" || typeof elementType === "function");
375
+ let byCount = cacheable ? arrayTypes.get(elementType) : undefined;
376
+ let type = byCount?.get(count);
377
+ if (type === undefined) {
378
+ type = _array(elementType, count, sizeof, alloc, readValue, writeValue, Structure, Union, ArrayType, c_void_p, ptrToBuffer);
379
+ if (cacheable) {
380
+ if (byCount === undefined) arrayTypes.set(elementType, (byCount = new Map()));
381
+ byCount.set(count, type);
382
+ }
383
+ }
384
+ return type;
356
385
  }
357
386
 
358
387
  // ============================================================================
@@ -403,9 +432,9 @@ function FormatError(code) {
403
432
  return _FormatError(code, WinDLL, alloc, c_uint32, c_void, c_void_p);
404
433
  }
405
434
 
406
- function WinError(code) {
407
- if (code === undefined) code = native.getCapturedLastError();
408
- return _WinError(code, WinDLL, alloc, c_uint32, c_void, c_void_p);
435
+ function WinError(code, descr) {
436
+ if (code === undefined || code === null) code = native.getCapturedLastError();
437
+ return _WinError(code, WinDLL, alloc, c_uint32, c_void, c_void_p, descr ?? undefined);
409
438
  }
410
439
 
411
440
  /**
@@ -414,26 +443,16 @@ function WinError(code) {
414
443
  * @param {number} bits - Numero di bit
415
444
  * @returns {Object} Definizione del bit field
416
445
  */
446
+ // Python: bitfield solo su interi e c_bool.
447
+ const bitFieldTypes = new Set([CType.INT8, CType.UINT8, CType.INT16, CType.UINT16, CType.INT32, CType.UINT32, CType.INT64, CType.UINT64, CType.LONG, CType.ULONG, CType.SIZE_T, CType.SSIZE_T, CType.BOOL]);
448
+
417
449
  function bitfield(baseType, bits) {
450
+ if (typeof baseType === "function" && baseType._isSimpleCData === true && !bitFieldTypes.has(baseType._type)) {
451
+ throw new TypeError(`bit fields not allowed for type ${baseType.name}`);
452
+ }
418
453
  return _bitfield(baseType, bits, sizeof);
419
454
  }
420
455
 
421
- /**
422
- * Helper per leggere un valore bit field da un buffer
423
- * @private
424
- */
425
- function _readBitField(buf, offset, baseType, bitOffset, bitSize) {
426
- return _readBitFieldHelper(buf, offset, baseType, bitOffset, bitSize, sizeof);
427
- }
428
-
429
- /**
430
- * Helper per scrivere un valore bit field in un buffer
431
- * @private
432
- */
433
- function _writeBitField(buf, offset, baseType, bitOffset, bitSize, newValue) {
434
- return _writeBitFieldHelper(buf, offset, baseType, bitOffset, bitSize, newValue, sizeof);
435
- }
436
-
437
456
  /**
438
457
  * Helper per definire struct con supporto per:
439
458
  * - Alignment corretto
@@ -595,7 +614,6 @@ export {
595
614
  writeValue,
596
615
  sizeof,
597
616
  alignment,
598
- ptrToBuffer,
599
617
 
600
618
  // Strutture
601
619
  struct,
@@ -684,8 +702,13 @@ export {
684
702
  // Re-export constants from platform module
685
703
  export { POINTER_SIZE, WCHAR_SIZE, NULL } from "./platform/constants.js";
686
704
 
705
+ // false dove i Buffer su memoria nativa non sono permessi (Electron): le
706
+ // istanze su memoria nativa usano una copia sincronizzata (memory/mirror.js).
707
+ export const EXTERNAL_BUFFERS = externalBuffers;
708
+
687
709
  // Python ctypes.util.find_library equivalent
688
- export { find_library } from "./platform/find_library.js";
710
+ import { find_library as findLibrary } from "./platform/find_library.js";
711
+ export const find_library = (name) => findLibrary(name, native);
689
712
 
690
713
  // Lazy loader namespaces (Python's `ctypes.cdll.libname` / `ctypes.windll.libname`).
691
714
  export const cdll = createLazyLoader(CDLL);