node-ctypes 2.2.0 → 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.
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.
@@ -935,9 +969,43 @@ export interface ArrayTypeDef<E = any> {
935
969
  * Proxy interface for array index access and iteration.
936
970
  * @category Structures
937
971
  */
938
- 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
+ > {
939
1003
  [index: number]: T;
940
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[];
941
1009
  /**
942
1010
  * The Buffer of the array: for an array on native memory
943
1011
  * ({@link ArrayTypeDef.from_address}) a Buffer over that memory, as
@@ -951,8 +1019,14 @@ export interface ArrayProxy<T = any> {
951
1019
  * @category Structures
952
1020
  */
953
1021
  export interface StructOptions {
954
- /** If `true`, disables padding between fields. */
1022
+ /** If `true`, disables padding between fields (as `pack: 1`). */
955
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;
956
1030
  }
957
1031
 
958
1032
  /**
@@ -1241,6 +1315,15 @@ export class Structure<F extends Record<string, FieldSpec> = Record<string, any>
1241
1315
  */
1242
1316
  static _pack_?: number | boolean;
1243
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
+
1244
1327
  /**
1245
1328
  * List of field names whose members are promoted to the parent struct.
1246
1329
  *
@@ -1248,6 +1331,15 @@ export class Structure<F extends Record<string, FieldSpec> = Record<string, any>
1248
1331
  */
1249
1332
  static _anonymous_?: ReadonlyArray<string>;
1250
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
+
1251
1343
  /** Create instance with optional initial values. */
1252
1344
  static create<ThisT extends Structure<F>>(this: new (...args: any[]) => ThisT, values?: Partial<FieldsToInstance<F>> | Buffer): ThisT;
1253
1345
 
@@ -1260,14 +1352,14 @@ export class Structure<F extends Record<string, FieldSpec> = Record<string, any>
1260
1352
  *
1261
1353
  * Python ctypes parity: `Structure.from_buffer(source, offset=0)`.
1262
1354
  */
1263
- 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;
1264
1356
 
1265
1357
  /**
1266
1358
  * Create an instance whose buffer is an independent copy of the source bytes.
1267
1359
  *
1268
1360
  * Python ctypes parity: `Structure.from_buffer_copy(source, offset=0)`.
1269
1361
  */
1270
- 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;
1271
1363
 
1272
1364
  /**
1273
1365
  * Create an instance that views raw memory at `address`. Caller is
@@ -1301,7 +1393,10 @@ export class Structure<F extends Record<string, FieldSpec> = Record<string, any>
1301
1393
  /** Convert all fields to a plain JavaScript object (snapshot). */
1302
1394
  toObject(): FieldsToInstance<F>;
1303
1395
 
1304
- /** 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). */
1305
1400
  [field: string]: any;
1306
1401
  }
1307
1402
 
@@ -1624,6 +1719,13 @@ export function wstring_at(address: Buffer | bigint | number, size?: number): st
1624
1719
  */
1625
1720
  export function addressof(ptr: Buffer | bigint | number): bigint;
1626
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
+
1627
1729
  /**
1628
1730
  * Copy memory from source to destination.
1629
1731
  *
@@ -1631,9 +1733,6 @@ export function addressof(ptr: Buffer | bigint | number): bigint;
1631
1733
  *
1632
1734
  * @category Memory
1633
1735
  */
1634
- /** Memory argument of {@link memmove} / {@link memset}: a buffer, a ctypes instance, a pointer or an address. */
1635
- export type MemoryTarget = Uint8Array | { readonly _buffer: Buffer } | PointerInstance | bigint | number;
1636
-
1637
1736
  export function memmove(dst: MemoryTarget, src: MemoryTarget, count: number): void;
1638
1737
 
1639
1738
  /**
@@ -1661,8 +1760,8 @@ export function memset(dst: MemoryTarget, value: number, count: number): void;
1661
1760
  *
1662
1761
  * @category Memory
1663
1762
  */
1664
- export function readValue<T extends AnyType>(ptr: Buffer | bigint | number | PointerInstance, type: T, offset?: number): JsFromCType<T>;
1665
- 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;
1666
1765
 
1667
1766
  /**
1668
1767
  * Write a typed value to a buffer at a given offset.
@@ -1674,8 +1773,8 @@ export function readValue(ptr: Buffer | bigint | number | PointerInstance, type:
1674
1773
  *
1675
1774
  * @category Memory
1676
1775
  */
1677
- export function writeValue<T extends AnyType>(ptr: Buffer | bigint | number | PointerInstance, type: T, value: JsArgFromCType<T>, offset?: number): number | void;
1678
- 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;
1679
1778
 
1680
1779
  /**
1681
1780
  * Get the size of a type in bytes.
@@ -1691,7 +1790,10 @@ export function writeValue(ptr: Buffer | bigint | number | PointerInstance, type
1691
1790
  *
1692
1791
  * @category Memory
1693
1792
  */
1694
- 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;
1695
1797
 
1696
1798
  /**
1697
1799
  * Get the alignment requirement of a type in bytes.
@@ -1734,10 +1836,11 @@ export function struct<F extends Record<string, FieldSpec>>(fields: F, options?:
1734
1836
  * For Python-like class syntax, use {@link Union} instead.
1735
1837
  *
1736
1838
  * @param fields - Object mapping field names to types
1839
+ * @param options - Union options (e.g. `{ pack: 1 }`)
1737
1840
  *
1738
1841
  * @category Structures
1739
1842
  */
1740
- 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>;
1741
1844
 
1742
1845
  /**
1743
1846
  * Factory that returns a Structure subclass with typed fields.
@@ -1747,7 +1850,7 @@ export function union<F extends Record<string, FieldSpec>>(fields: F): UnionDef<
1747
1850
  *
1748
1851
  * @category Structures
1749
1852
  */
1750
- 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>>;
1751
1854
 
1752
1855
  /**
1753
1856
  * Factory that returns a Union subclass with typed fields.
@@ -1756,7 +1859,27 @@ export function defineStruct<F extends Record<string, FieldSpec>>(fields: F, opt
1756
1859
  *
1757
1860
  * @category Structures
1758
1861
  */
1759
- 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
+ }
1760
1883
 
1761
1884
  /**
1762
1885
  * Define a fixed-size array type.
@@ -1775,18 +1898,21 @@ export function defineUnion<F extends Record<string, FieldSpec>>(fields: F): new
1775
1898
  *
1776
1899
  * @category Structures
1777
1900
  */
1778
- 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;
1779
1905
 
1780
1906
  /**
1781
1907
  * Alias of {@link array}. Python equivalent: `ctypes.ARRAY(type, length)`.
1782
1908
  * @category Structures
1783
1909
  */
1784
- 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>;
1785
1911
 
1786
1912
  /**
1787
1913
  * Define a bit field for use in struct `_fields_`.
1788
1914
  *
1789
- * @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
1790
1916
  * @param bits - Number of bits
1791
1917
  *
1792
1918
  * @example
@@ -1801,7 +1927,7 @@ export function ARRAY<E extends AnyType | StructureClass | ArrayTypeDef | Pointe
1801
1927
  *
1802
1928
  * @category Structures
1803
1929
  */
1804
- export function bitfield(baseType: AnyType, bits: number): BitFieldDef;
1930
+ export function bitfield(baseType: SimpleCDataConstructor, bits: number): BitFieldDef;
1805
1931
 
1806
1932
  /**
1807
1933
  * Pass an object by reference (returns its underlying buffer).
@@ -1965,7 +2091,7 @@ export function set_last_error(code: number): number;
1965
2091
  * @category Error Handling
1966
2092
  */
1967
2093
  export class ArgumentError extends TypeError {
1968
- constructor(message?: string);
2094
+ constructor(message?: string, options?: ErrorOptions);
1969
2095
  }
1970
2096
 
1971
2097
  /**
@@ -1985,11 +2111,12 @@ export function FormatError(code?: number): string;
1985
2111
  * Python equivalent: `ctypes.WinError()`
1986
2112
  *
1987
2113
  * @param code - Error code (defaults to `GetLastError()`)
1988
- * @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`
1989
2116
  *
1990
2117
  * @category Error Handling
1991
2118
  */
1992
- export function WinError(code?: number): Error & { winerror: number };
2119
+ export function WinError(code?: number | null, descr?: string): Error & { winerror: number; errno: number; strerror: string };
1993
2120
 
1994
2121
  // =============================================================================
1995
2122
  // SimpleCData - Base class for simple C data types
@@ -2458,8 +2585,9 @@ export const DEFAULT_MODE: number;
2458
2585
  * are provided (e.g. `"c"` → `"msvcrt.dll"`).
2459
2586
  * - On Linux, the `ldconfig` cache and common library directories are
2460
2587
  * searched for the best-matching `libNAME.so.VERSION`.
2461
- * - On macOS, `/usr/lib`, `/usr/local/lib`, Homebrew prefixes and framework
2462
- * 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).
2463
2591
  *
2464
2592
  * Returns `null` if the input is invalid. Returns a best-effort fallback
2465
2593
  * (bare soname) if nothing is found, so the loader can still try its own
package/lib/index.js CHANGED
@@ -44,7 +44,6 @@ import { addressOf as _addressOf, byref as _byref, cast as _cast, ptrToBuffer as
44
44
  import { FormatError as _FormatError, WinError as _WinError, ArgumentError } from "./platform/errors.js";
45
45
  import { bitfield as _bitfield, _isStruct, _isArrayType, _isBitField } from "./structures/helpers/common.js";
46
46
  import { array as _array } from "./structures/helpers/array.js";
47
- import { _readBitField as _readBitFieldHelper, _writeBitField as _writeBitFieldHelper, _readUintFromBuffer, _writeUintToBuffer } from "./structures/helpers/bitfield.js";
48
47
  import { union as _union } from "./structures/helpers/union.js";
49
48
  import { struct as _struct } from "./structures/helpers/struct.js";
50
49
  import { createStructureClass } from "./structures/Structure.js";
@@ -270,8 +269,18 @@ function ptrToBuffer(address, size) {
270
269
  return _ptrToBuffer(address, size, native);
271
270
  }
272
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
+
273
276
  function POINTER(baseType) {
274
- 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;
275
284
  }
276
285
 
277
286
  /**
@@ -291,7 +300,7 @@ function POINTER(baseType) {
291
300
  * ```
292
301
  */
293
302
  function pointer(obj) {
294
- 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);
295
304
  }
296
305
 
297
306
  /**
@@ -320,8 +329,8 @@ function defineStruct(fields, options) {
320
329
  /**
321
330
  * Helper to define a JS class backed by a union definition.
322
331
  */
323
- function defineUnion(fields) {
324
- const def = union(fields);
332
+ function defineUnion(fields, options) {
333
+ const def = union(fields, options);
325
334
  class AutoUnion extends Union {}
326
335
  AutoUnion._structDef = def;
327
336
  AutoUnion._fields_ = fields;
@@ -362,7 +371,17 @@ memoryDeps.Union = Union;
362
371
  * console.log(arr[2]); // 42
363
372
  */
364
373
  function array(elementType, count) {
365
- return _array(elementType, count, sizeof, alloc, readValue, writeValue, Structure, Union, ArrayType, c_void_p, ptrToBuffer);
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;
366
385
  }
367
386
 
368
387
  // ============================================================================
@@ -413,9 +432,9 @@ function FormatError(code) {
413
432
  return _FormatError(code, WinDLL, alloc, c_uint32, c_void, c_void_p);
414
433
  }
415
434
 
416
- function WinError(code) {
417
- if (code === undefined) code = native.getCapturedLastError();
418
- 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);
419
438
  }
420
439
 
421
440
  /**
@@ -424,26 +443,16 @@ function WinError(code) {
424
443
  * @param {number} bits - Numero di bit
425
444
  * @returns {Object} Definizione del bit field
426
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
+
427
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
+ }
428
453
  return _bitfield(baseType, bits, sizeof);
429
454
  }
430
455
 
431
- /**
432
- * Helper per leggere un valore bit field da un buffer
433
- * @private
434
- */
435
- function _readBitField(buf, offset, baseType, bitOffset, bitSize) {
436
- return _readBitFieldHelper(buf, offset, baseType, bitOffset, bitSize, sizeof);
437
- }
438
-
439
- /**
440
- * Helper per scrivere un valore bit field in un buffer
441
- * @private
442
- */
443
- function _writeBitField(buf, offset, baseType, bitOffset, bitSize, newValue) {
444
- return _writeBitFieldHelper(buf, offset, baseType, bitOffset, bitSize, newValue, sizeof);
445
- }
446
-
447
456
  /**
448
457
  * Helper per definire struct con supporto per:
449
458
  * - Alignment corretto
@@ -698,7 +707,8 @@ export { POINTER_SIZE, WCHAR_SIZE, NULL } from "./platform/constants.js";
698
707
  export const EXTERNAL_BUFFERS = externalBuffers;
699
708
 
700
709
  // Python ctypes.util.find_library equivalent
701
- 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);
702
712
 
703
713
  // Lazy loader namespaces (Python's `ctypes.cdll.libname` / `ctypes.windll.libname`).
704
714
  export const cdll = createLazyLoader(CDLL);
@@ -101,7 +101,7 @@ export function decodeWide(buf, wcharSize) {
101
101
  for (let off = 0; off + 3 < buf.length; off += 4) {
102
102
  const cp = buf.readUInt32LE(off);
103
103
  if (cp === 0) break;
104
- out += String.fromCodePoint(cp);
104
+ out += String.fromCodePoint(cp > 0x10ffff ? 0xfffd : cp);
105
105
  }
106
106
  return out;
107
107
  }
@@ -392,7 +392,7 @@ export function create_unicode_buffer(init, size, native) {
392
392
  * ```
393
393
  */
394
394
  export function string_at(address, size, native) {
395
- return native.readCString(address, size);
395
+ return native.readCString(stringSource(address, native), size);
396
396
  }
397
397
 
398
398
  /**
@@ -420,10 +420,20 @@ export function string_at(address, size, native) {
420
420
  * ```
421
421
  */
422
422
  export function wstring_at(address, size, native) {
423
- if (address === null || address === undefined) {
424
- return null;
425
- }
426
- return native.readWString(address, size);
423
+ return native.readWString(stringSource(address, native), size);
424
+ }
425
+
426
+ /**
427
+ * Source of string_at / wstring_at, as Python's c_void_p.from_param: the
428
+ * memory of instances and arrays, the value of pointers, c_void_p, c_char_p
429
+ * and c_wchar_p, `_as_parameter_`. Buffer or address; NULL gives null.
430
+ */
431
+ function stringSource(value, native) {
432
+ if (value === null || value === undefined || typeof value === "bigint" || typeof value === "number") return value;
433
+ // Array proxies pass Buffer.isBuffer but are resolved through _buffer.
434
+ if (Buffer.isBuffer(value) && value._buffer === undefined) return mirrorAddress(value) ?? value;
435
+ const memory = memoryOf(value, native, "address", true);
436
+ return memory instanceof Uint8Array && !Buffer.isBuffer(memory) ? Buffer.from(memory.buffer, memory.byteOffset, memory.byteLength) : memory;
427
437
  }
428
438
 
429
439
  /**
@@ -456,26 +466,44 @@ export function memmove(dst, src, count, native) {
456
466
  if (typeof to !== "bigint") n = Math.min(n, to.length);
457
467
  if (typeof from !== "bigint") n = Math.min(n, from.length);
458
468
  if (n <= 0) return;
459
- if (typeof to !== "bigint" && typeof from !== "bigint") from.copy(to, 0, 0, n);
469
+ // TypedArray.set gestisce anche la sovrapposizione (stesso ArrayBuffer).
470
+ if (typeof to !== "bigint" && typeof from !== "bigint") to.set(n === from.length ? from : from.subarray(0, n));
460
471
  else native.memmove(to, from, n);
461
472
  }
462
473
 
463
- // Memoria di un argomento di memmove/memset, come Python: Buffer, istanze
464
- // ctypes (struct, array, c_*), puntatori o un indirizzo (BigInt/number).
474
+ // Memoria di un argomento di memmove/memset, come Python: Buffer, ogni
475
+ // TypedArray/DataView/ArrayBuffer (come vista a byte), istanze ctypes (struct,
476
+ // array, c_*), puntatori o un indirizzo (BigInt/number).
465
477
  // Gli indirizzi (anche quello originale di una copia, memory/mirror.js) sono
466
478
  // letti e scritti dal nativo, senza creare un Buffer esterno.
467
- function memoryOf(value, native, name) {
479
+ function memoryOf(value, native, name, allowNull = false) {
468
480
  if (value !== null && typeof value === "object") {
481
+ // c_void_p / c_char_p / c_wchar_p: the memory they point to, as in Python.
482
+ const T = value.constructor;
483
+ if (T?._isSimpleCData === true && (T._type === native.CType.POINTER || T._type === native.CType.STRING || T._type === native.CType.WSTRING)) {
484
+ const slot = value._buffer;
485
+ return addressOrNull(native.POINTER_SIZE === 8 ? slot.readBigUInt64LE(0) : BigInt(slot.readUInt32LE(0)), name, allowNull);
486
+ }
469
487
  if (Buffer.isBuffer(value._buffer)) return mirrorAddress(value._buffer) ?? value._buffer;
470
- if (value._pointerType !== undefined) return addressOrNull(value.address, name);
471
- if (value instanceof Uint8Array) return mirrorAddress(value) ?? value;
488
+ if (value._pointerType !== undefined) return addressOrNull(value.address, name, allowNull);
489
+ if (ArrayBuffer.isView(value)) {
490
+ return mirrorAddress(value) ?? (value instanceof Uint8Array ? value : new Uint8Array(value.buffer, value.byteOffset, value.byteLength));
491
+ }
492
+ if (value instanceof ArrayBuffer || (typeof SharedArrayBuffer === "function" && value instanceof SharedArrayBuffer)) {
493
+ return new Uint8Array(value);
494
+ }
495
+ if (value._as_parameter_ !== undefined) return memoryOf(value._as_parameter_, native, name, allowNull);
472
496
  }
473
- if (typeof value === "bigint" || typeof value === "number") return addressOrNull(value, name);
497
+ if (typeof value === "bigint" || typeof value === "number") return addressOrNull(value, name, allowNull);
498
+ if (allowNull && value === null) return null;
474
499
  throw new TypeError(`${name} must be a Buffer, a ctypes instance, a pointer or an address`);
475
500
  }
476
501
 
477
- function addressOrNull(value, name) {
478
- if (!value) throw new TypeError(`${name} is a NULL pointer`);
502
+ function addressOrNull(value, name, allowNull = false) {
503
+ if (!value) {
504
+ if (allowNull) return null;
505
+ throw new TypeError(`${name} is a NULL pointer`);
506
+ }
479
507
  return BigInt(value);
480
508
  }
481
509
 
@@ -502,7 +530,8 @@ function addressOrNull(value, name) {
502
530
  export function memset(dst, value, count, native) {
503
531
  const to = memoryOf(dst, native, "dst");
504
532
  if (typeof to !== "bigint") {
505
- to.fill(value, 0, count);
533
+ // Come memmove, si ferma alla fine della memoria JS.
534
+ to.fill(value, 0, Math.max(0, Math.min(count, to.length)));
506
535
  } else if (count > 0) {
507
536
  native.memmove(to, Buffer.alloc(count, value), count);
508
537
  }