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
package/lib/index.d.ts CHANGED
@@ -134,7 +134,7 @@ export type FFIType = AnyType | StructureClass | PointerTypeDef | ArrayTypeDef |
134
134
  * @example
135
135
  * ```javascript
136
136
  * import { Version } from 'node-ctypes';
137
- * console.log(Version.toString()); // "2.0.0"
137
+ * console.log(Version.toString()); // "2.4.0"
138
138
  * ```
139
139
  *
140
140
  * @category Library Loading
@@ -172,13 +172,20 @@ export class Library {
172
172
  */
173
173
  symbol(name: string): bigint;
174
174
 
175
- /** Close the library and release resources. */
175
+ /**
176
+ * Logically close the library. 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
+ * Existing `in_dll()` views and dependent memory remain valid and defer
180
+ * native handle release until their last owner is collected.
181
+ * Physical unloading depends on the OS loader; musl keeps modules resident.
182
+ */
176
183
  close(): void;
177
184
 
178
185
  /** Library file path. */
179
186
  readonly path: string;
180
187
 
181
- /** Whether the library is currently loaded. */
188
+ /** Whether the logical library handle is open (not a physical-unload probe). */
182
189
  readonly loaded: boolean;
183
190
  }
184
191
 
@@ -221,6 +228,7 @@ export interface FFIFunction {
221
228
 
222
229
  /** The function address as BigInt. */
223
230
  readonly address: bigint;
231
+ readonly _as_parameter_: bigint;
224
232
 
225
233
  /**
226
234
  * Error checking callback, called after every invocation (`null` when not set).
@@ -244,8 +252,8 @@ export interface NativeFFIFunction<TArgs extends readonly FFIType[] = FFIType[],
244
252
  /** Call the native function asynchronously on a worker thread. */
245
253
  callAsync(...args: FFIArgs<TArgs>): Promise<FFIReturn<TRet>>;
246
254
 
247
- /** Set (or clear with `null`) the error checking callback. */
248
- setErrcheck(callback: ErrcheckCallback | null): void;
255
+ /** Set (or clear with `null`) the hook captured at each call's entry, including async calls. */
256
+ setErrcheck(callback: NativeErrcheckCallback<TArgs, TRet> | null): void;
249
257
 
250
258
  /** `GetLastError()` (Windows) or `errno` captured after the last call, with `use_last_error`. */
251
259
  getCapturedLastError(): number;
@@ -260,6 +268,13 @@ export interface NativeFFIFunction<TArgs extends readonly FFIType[] = FFIType[],
260
268
  readonly address: bigint;
261
269
  }
262
270
 
271
+ /**
272
+ * Low-level errcheck: `func` is the native handle, invoked with `.call()`,
273
+ * not a directly callable JavaScript function.
274
+ * @category Library Loading
275
+ */
276
+ export type NativeErrcheckCallback<TArgs extends readonly FFIType[] = FFIType[], TRet extends FFIType | null = FFIType> = (result: any, func: NativeFFIFunction<TArgs, TRet>, args: any[]) => any;
277
+
263
278
  /**
264
279
  * Strongly-typed FFI function returned by `CDLL.func` when the
265
280
  * argument types and return type are given as a literal tuple and constant respectively.
@@ -274,6 +289,7 @@ export interface TypedFFIFunction<TArgs extends readonly FFIType[], TRet extends
274
289
  callAsync(...args: FFIArgs<TArgs>): Promise<FFIReturn<TRet>>;
275
290
  readonly funcName: string;
276
291
  readonly address: bigint;
292
+ readonly _as_parameter_: bigint;
277
293
  errcheck: ErrcheckCallback | null;
278
294
  }
279
295
 
@@ -312,13 +328,22 @@ export interface TypedFFIFunction<TArgs extends readonly FFIType[], TRet extends
312
328
  */
313
329
  export interface LibraryOptions {
314
330
  /**
315
- * `dlopen` flags combined with `RTLD_LAZY` (e.g. {@link RTLD_GLOBAL}).
331
+ * `dlopen` flags combined with `RTLD_NOW` (e.g. {@link RTLD_GLOBAL}).
316
332
  * Ignored on Windows. Default: {@link DEFAULT_MODE}.
317
333
  *
318
334
  * Python ctypes parity: the `mode` argument of `CDLL(name, mode)`.
319
335
  */
320
336
  mode?: number;
321
337
 
338
+ /**
339
+ * `LoadLibraryExW` flags (Windows only). Default: `LOAD_LIBRARY_SEARCH_DEFAULT_DIRS`,
340
+ * plus `LOAD_LIBRARY_SEARCH_DLL_LOAD_DIR` (with the path made absolute) when the
341
+ * name contains a path separator.
342
+ *
343
+ * Python ctypes parity: the `winmode` argument of `CDLL(name, winmode=...)`.
344
+ */
345
+ winmode?: number;
346
+
322
347
  /**
323
348
  * Maximum size of the internal function cache. Default: 1000.
324
349
  */
@@ -361,6 +386,7 @@ export class CDLL {
361
386
  */
362
387
  /** Typed overload: narrows args/return when argTypes is a literal tuple. */
363
388
  func<TRet extends FFIType | null, const TArgs extends readonly FFIType[]>(name: string, returnType: TRet, argTypes: TArgs, options?: FunctionOptions): TypedFFIFunction<TArgs, TRet>;
389
+ func(name: string): TypedFFIFunction<readonly FFIType[], typeof c_int32>;
364
390
  func(name: string, returnType: FFIType | null, argTypes?: FFIType[], options?: FunctionOptions): FFIFunction;
365
391
 
366
392
  /**
@@ -370,7 +396,14 @@ export class CDLL {
370
396
  */
371
397
  symbol(name: string): bigint;
372
398
 
373
- /** Close the library and clear the function cache. */
399
+ /**
400
+ * Close the library and clear the function cache. Functions obtained from
401
+ * it throw when called afterwards. Throws while a call to one of its
402
+ * functions is in progress (from a callback, or a pending `callAsync()`).
403
+ * Existing `in_dll()` views defer native handle release until their dependent
404
+ * memory is collected, but new calls and symbol lookups are rejected.
405
+ * Physical unloading depends on the OS loader; musl keeps modules resident.
406
+ */
374
407
  close(): void;
375
408
 
376
409
  /** Close the library at the end of a `using` block. */
@@ -380,7 +413,7 @@ export class CDLL {
380
413
  * Create a native callback bound to this library's context.
381
414
  * Call `release()` when it is no longer needed.
382
415
  */
383
- callback(fn: Function, returnType: AnyType | null, argTypes?: AnyType[]): Callback;
416
+ callback<TRet extends CallbackRestype, const TArgs extends readonly FFIType[] = readonly []>(fn: (...args: CallbackArgs<TArgs>) => CallbackResult<TRet>, returnType: TRet, argTypes?: TArgs): Callback;
384
417
 
385
418
  /**
386
419
  * Read the snapshotted `GetLastError()` (Windows) or `errno` from the most
@@ -402,7 +435,7 @@ export class CDLL {
402
435
  /** Library file path. */
403
436
  readonly path: string;
404
437
 
405
- /** Whether the library is loaded. */
438
+ /** Whether the logical handle is open, independently of physical module residency. */
406
439
  readonly loaded: boolean;
407
440
 
408
441
  /**
@@ -489,8 +522,8 @@ export class OleDLL extends WinDLL {
489
522
  }
490
523
 
491
524
  /**
492
- * `HRESULT` return type marker. Use as `restype` on an OleDLL function to
493
- * enable automatic throw-on-failure behavior.
525
+ * `HRESULT` return type marker. Explicit use as restype enables failure checks
526
+ * for all library loaders and prototype callers, before errcheck.
494
527
  *
495
528
  * Python equivalent: `ctypes.HRESULT`
496
529
  *
@@ -575,6 +608,7 @@ export const oledll: LibraryNamespace<OleDLL> | undefined;
575
608
  * @category Callbacks
576
609
  */
577
610
  export interface CallbackWrapper {
611
+ readonly _callback: Callback;
578
612
  /** The callback function pointer, passable to native functions. */
579
613
  readonly pointer: bigint;
580
614
 
@@ -593,6 +627,7 @@ export interface CallbackWrapper {
593
627
  * @category Callbacks
594
628
  */
595
629
  export interface ThreadSafeCallbackWrapper extends CallbackWrapper {
630
+ readonly _callback: ThreadSafeCallback;
596
631
  /** Keep the Node.js event loop alive until released (the default). */
597
632
  ref(): this;
598
633
 
@@ -611,10 +646,8 @@ export class Callback {
611
646
  constructor(fn: Function, returnType: AnyType, argTypes?: AnyType[]);
612
647
  /** The callback function pointer, passable to native functions. */
613
648
  readonly pointer: bigint;
614
- /** Same as {@link Callback.pointer}. */
649
+ /** Return the function pointer, throwing if the callback has been released. */
615
650
  getPointer(): bigint;
616
- /** Same as `pointer`: lets the callback be passed directly as an argument. */
617
- readonly _as_parameter_: bigint;
618
651
  /** Release the callback and free native resources. Must be called when done. */
619
652
  release(): void;
620
653
  /**
@@ -714,7 +747,11 @@ export type FieldSpec = AnyType | StructDef | ArrayTypeDef | BitFieldDef | Anony
714
747
  */
715
748
  export type JsFromCType<T> =
716
749
  T extends SimpleCDataConstructor<infer Tag>
717
- ? JsFromTag<Tag>
750
+ ? T extends { prototype: infer Instance }
751
+ ? IsAny<Instance> extends true
752
+ ? JsFromTag<Tag>
753
+ : Instance
754
+ : JsFromTag<Tag>
718
755
  : T extends BitFieldDef
719
756
  ? number
720
757
  : T extends PointerTypeDef<infer B>
@@ -772,10 +809,10 @@ type FieldValue<F extends Record<string, FieldSpec>, K extends keyof F> = string
772
809
  type FieldArg<F extends Record<string, FieldSpec>, K extends keyof F> = string extends keyof F ? any : JsArgFromCType<F[K]>;
773
810
 
774
811
  /**
775
- * Element read from an array of `E`. Narrowed only to `number`: arrays are
776
- * also Buffers, whose numeric index is `number`, so other element types stay `any`.
812
+ * Numeric elements and scalar subclass instances are typed; other element
813
+ * representations retain the existing permissive array API.
777
814
  */
778
- type ArrayElement<E> = IsAny<E> extends true ? any : JsFromCType<E> extends number ? number : any;
815
+ type ArrayElement<E> = IsAny<E> extends true ? any : JsFromCType<E> extends SimpleCDataInstance<unknown> ? JsFromCType<E> : JsFromCType<E> extends number ? number : any;
779
816
 
780
817
  /** Element accepted when writing an array of `E`. */
781
818
  type ArrayElementArg<E> = IsAny<E> extends true ? any : E extends StructureClass ? Buffer | Record<string, any> : JsArgFromCType<E>;
@@ -784,17 +821,44 @@ type ArrayElementArg<E> = IsAny<E> extends true ? any : E extends StructureClass
784
821
  type PointerValue<T> = IsAny<T> extends true ? any : T extends StructureClass ? InstanceType<T> : JsFromCType<T>;
785
822
 
786
823
  /** `p.contents`: a live instance on the pointed memory (Python parity). */
787
- type PointerContents<T> = IsAny<T> extends true ? any : T extends SimpleCDataConstructor<infer Tag> ? SimpleCDataInstance<JsFromTag<Tag>> : T extends StructureClass ? InstanceType<T> : JsFromCType<T>;
824
+ type PointerContents<T> =
825
+ IsAny<T> extends true
826
+ ? any
827
+ : T extends SimpleCDataConstructor<infer Tag>
828
+ ? T extends { prototype: infer Instance }
829
+ ? IsAny<Instance> extends true
830
+ ? SimpleCDataInstance<JsFromTag<Tag>>
831
+ : Instance
832
+ : SimpleCDataInstance<JsFromTag<Tag>>
833
+ : T extends StructureClass
834
+ ? InstanceType<T>
835
+ : JsFromCType<T>;
788
836
 
789
837
  /** `string` for `c_char`/`c_wchar` arrays (read as text, as Python), otherwise `Else`. */
790
838
  type CharArrayValue<E, Else> = IsAny<E> extends true ? Else : [E] extends [SimpleCDataConstructor<"char">] ? string : [E] extends [SimpleCDataConstructor<"wchar">] ? string : Else;
791
839
 
792
840
  /**
793
- * Array instance: a Buffer with index access; `c_char` arrays also expose
794
- * `.value`/`.raw` and `c_wchar` arrays `.value`, as in Python.
841
+ * Array instance: a Buffer with index access; the Array methods (`slice`, `map`,
842
+ * `includes`, ...) work on the elements, as Python's sequence operations.
843
+ * `c_char` arrays also expose `.value`/`.raw` and `c_wchar` arrays `.value`.
795
844
  * @category Structures
796
845
  */
797
- export type ArrayInstance<E = any> = Buffer & ArrayProxy<ArrayElement<E>> & (IsAny<E> extends true ? {} : [E] extends [SimpleCDataConstructor<"char">] ? CharBufferValue : [E] extends [SimpleCDataConstructor<"wchar">] ? WideBufferValue : {});
846
+ export type ArrayInstance<E = any> = Omit<Buffer, ElementMethod | "length" | "toJSON" | number> &
847
+ (IsAny<E> extends true
848
+ ? ArrayProxy<any>
849
+ : [E] extends [SimpleCDataConstructor<"char">]
850
+ ? Omit<ArrayProxy<ArrayElement<E>>, "slice"> & CharBufferValue & CharSlice
851
+ : [E] extends [SimpleCDataConstructor<"wchar">]
852
+ ? Omit<ArrayProxy<ArrayElement<E>>, "slice"> & WideBufferValue & CharSlice
853
+ : ArrayProxy<ArrayElement<E>>);
854
+
855
+ /** Array methods that work on the elements of an array instance; the Buffer methods (`readInt32LE`, `subarray`, ...) work on the bytes. */
856
+ type ElementMethod = Exclude<keyof ArrayProxy, number | typeof Symbol.iterator | "length" | "toJSON">;
857
+
858
+ /** `c_char` / `c_wchar` arrays: a slice is a string (Python: bytes / str). */
859
+ interface CharSlice {
860
+ slice(start?: number, end?: number): string;
861
+ }
798
862
 
799
863
  /**
800
864
  * Text accessors of `c_char` buffers (arrays, {@link create_string_buffer}).
@@ -824,17 +888,19 @@ type ArgsFromCTypes<TArgs extends readonly any[]> = {
824
888
  };
825
889
 
826
890
  /** 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>;
891
+ type JsArgFromFFIType<T> =
892
+ { readonly _as_parameter_: unknown } | (T extends StructureClass ? Buffer | { _buffer: Buffer } | Record<string, any> : T extends ArrayTypeDef<infer E> ? ArrayInstance<E> | ArrayBufferView | ArrayBuffer : JsArgFromCType<T>);
828
893
 
829
894
  /** Function arguments for `argtypes` `TArgs` (`any[]` when not a literal tuple). */
830
895
  type FFIArgs<TArgs extends readonly any[]> = FFIType[] extends TArgs ? any[] : { [K in keyof TArgs]: JsArgFromFFIType<TArgs[K]> };
831
896
 
832
897
  /**
833
898
  * 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).
899
+ * `POINTER(T)` restype returns a {@link PointerInstance}, a {@link CFUNCTYPE}
900
+ * restype a callable function (`null` for NULL) and a Structure/Union class an
901
+ * instance of that class.
836
902
  */
837
- type FFIReturn<T> = FFIType extends T ? any : T extends null ? undefined : T extends StructureClass ? Record<string, any> : JsFromCType<T>;
903
+ type FFIReturn<T> = FFIType extends T ? any : T extends null ? undefined : T extends { _check_retval_: (...args: never[]) => infer Result } ? Result : T extends StructureClass ? InstanceType<T> : JsFromCType<T>;
838
904
 
839
905
  /**
840
906
  * A union type definition created by the {@link union} function.
@@ -935,9 +1001,43 @@ export interface ArrayTypeDef<E = any> {
935
1001
  * Proxy interface for array index access and iteration.
936
1002
  * @category Structures
937
1003
  */
938
- export interface ArrayProxy<T = any> {
1004
+ export interface ArrayProxy<T = any> extends Pick<
1005
+ T[],
1006
+ | "at"
1007
+ | "copyWithin"
1008
+ | "entries"
1009
+ | "every"
1010
+ | "fill"
1011
+ | "filter"
1012
+ | "find"
1013
+ | "findIndex"
1014
+ | "findLast"
1015
+ | "findLastIndex"
1016
+ | "forEach"
1017
+ | "includes"
1018
+ | "indexOf"
1019
+ | "join"
1020
+ | "keys"
1021
+ | "lastIndexOf"
1022
+ | "map"
1023
+ | "reduce"
1024
+ | "reduceRight"
1025
+ | "reverse"
1026
+ | "slice"
1027
+ | "some"
1028
+ | "sort"
1029
+ | "toLocaleString"
1030
+ | "toReversed"
1031
+ | "toSorted"
1032
+ | "values"
1033
+ | "with"
1034
+ > {
939
1035
  [index: number]: T;
940
1036
  [Symbol.iterator](): Iterator<T>;
1037
+ /** Number of elements (Python `len(arr)`); the size in bytes is `byteLength`. */
1038
+ readonly length: number;
1039
+ /** The elements, for `JSON.stringify`. */
1040
+ toJSON(): T[];
941
1041
  /**
942
1042
  * The Buffer of the array: for an array on native memory
943
1043
  * ({@link ArrayTypeDef.from_address}) a Buffer over that memory, as
@@ -951,8 +1051,14 @@ export interface ArrayProxy<T = any> {
951
1051
  * @category Structures
952
1052
  */
953
1053
  export interface StructOptions {
954
- /** If `true`, disables padding between fields. */
1054
+ /** If `true`, disables padding between fields (as `pack: 1`). */
955
1055
  packed?: boolean;
1056
+ /** Maximum field alignment in bytes, as Python's `_pack_`. */
1057
+ pack?: number | boolean | bigint | string | null;
1058
+ /** Bit field layout, as Python's `_layout_` (`"ms"` with `pack`, otherwise the platform's). */
1059
+ layout?: "gcc-sysv" | "ms";
1060
+ /** Minimum alignment in bytes, as Python's `_align_`. */
1061
+ align?: number;
956
1062
  }
957
1063
 
958
1064
  /**
@@ -1164,23 +1270,32 @@ export interface PointerTypeDef<T = any> {
1164
1270
 
1165
1271
  /**
1166
1272
  * Low-level native struct type. Prefer {@link Structure} for most use cases.
1273
+ * Mutable only until captured by a field, array, prepared function/callback
1274
+ * signature or native value. Finalization includes nested descriptors.
1275
+ * Create a new descriptor rather than modifying a finalized layout.
1167
1276
  * @category Structures
1168
1277
  */
1169
1278
  export class StructType {
1170
- constructor(isUnion?: boolean);
1171
- addField(name: string, type: AnyType | StructType | ArrayType): this;
1279
+ constructor(options?: { union?: boolean; alignment?: number; memoryClass?: boolean });
1280
+ /** Append a field while the builder is open; throws after finalization. */
1281
+ addField(name: string, type: number | StructType | ArrayType | { readonly _native: ArrayType }, options?: { anonymous?: boolean }): this;
1282
+ /** Query without finalizing an unused builder. */
1172
1283
  getSize(): number;
1284
+ /** Query without finalizing an unused builder. */
1173
1285
  getAlignment(): number;
1174
- create(values?: Record<string, any>): Buffer;
1286
+ /** Materialize a value and finalize its layout. */
1287
+ create(values?: Record<string, unknown>): Record<string, unknown> & { readonly _buffer: Buffer };
1175
1288
  read(buffer: Buffer): Record<string, any>;
1289
+ toObject(source: Buffer | { readonly _buffer: Buffer }): Record<string, unknown>;
1176
1290
  }
1177
1291
 
1178
1292
  /**
1179
1293
  * Low-level native array type. Prefer {@link array} for most use cases.
1294
+ * Captures and finalizes an aggregate element's layout, including at length zero.
1180
1295
  * @category Structures
1181
1296
  */
1182
1297
  export class ArrayType {
1183
- constructor(elementType: AnyType, count: number);
1298
+ constructor(elementType: number | StructType, count: number);
1184
1299
  getSize(): number;
1185
1300
  getLength(): number;
1186
1301
  getAlignment(): number;
@@ -1239,7 +1354,16 @@ export class Structure<F extends Record<string, FieldSpec> = Record<string, any>
1239
1354
  * Maximum field alignment in bytes, as Python's `_pack_` (`1` = no padding).
1240
1355
  * `true` is accepted as `1`.
1241
1356
  */
1242
- static _pack_?: number | boolean;
1357
+ static _pack_?: number | boolean | bigint | string | null;
1358
+
1359
+ /**
1360
+ * Bit field layout, as Python's `_layout_`: `"gcc-sysv"` (default except on
1361
+ * Windows) or `"ms"` (default on Windows and with `_pack_`).
1362
+ */
1363
+ static _layout_?: "gcc-sysv" | "ms";
1364
+
1365
+ /** Minimum alignment in bytes, as Python's `_align_`. */
1366
+ static _align_?: number;
1243
1367
 
1244
1368
  /**
1245
1369
  * List of field names whose members are promoted to the parent struct.
@@ -1248,6 +1372,15 @@ export class Structure<F extends Record<string, FieldSpec> = Record<string, any>
1248
1372
  */
1249
1373
  static _anonymous_?: ReadonlyArray<string>;
1250
1374
 
1375
+ /** Size in bytes (Python: `sizeof(cls)`). */
1376
+ static readonly size: number;
1377
+
1378
+ /** Alignment in bytes (Python: `alignment(cls)`). */
1379
+ static readonly alignment: number;
1380
+
1381
+ /** Field descriptors, in layout order. */
1382
+ static readonly fields: FieldDef[];
1383
+
1251
1384
  /** Create instance with optional initial values. */
1252
1385
  static create<ThisT extends Structure<F>>(this: new (...args: any[]) => ThisT, values?: Partial<FieldsToInstance<F>> | Buffer): ThisT;
1253
1386
 
@@ -1260,14 +1393,14 @@ export class Structure<F extends Record<string, FieldSpec> = Record<string, any>
1260
1393
  *
1261
1394
  * Python ctypes parity: `Structure.from_buffer(source, offset=0)`.
1262
1395
  */
1263
- static from_buffer<ThisT extends Structure<F>>(this: new (...args: any[]) => ThisT, source: Buffer, offset?: number): ThisT;
1396
+ static from_buffer<ThisT extends Structure<F>>(this: new (...args: any[]) => ThisT, source: ArrayBufferView | { _buffer: Buffer }, offset?: number): ThisT;
1264
1397
 
1265
1398
  /**
1266
1399
  * Create an instance whose buffer is an independent copy of the source bytes.
1267
1400
  *
1268
1401
  * Python ctypes parity: `Structure.from_buffer_copy(source, offset=0)`.
1269
1402
  */
1270
- static from_buffer_copy<ThisT extends Structure<F>>(this: new (...args: any[]) => ThisT, source: Buffer | Uint8Array, offset?: number): ThisT;
1403
+ static from_buffer_copy<ThisT extends Structure<F>>(this: new (...args: any[]) => ThisT, source: ArrayBufferView | { _buffer: Buffer }, offset?: number): ThisT;
1271
1404
 
1272
1405
  /**
1273
1406
  * Create an instance that views raw memory at `address`. Caller is
@@ -1301,7 +1434,10 @@ export class Structure<F extends Record<string, FieldSpec> = Record<string, any>
1301
1434
  /** Convert all fields to a plain JavaScript object (snapshot). */
1302
1435
  toObject(): FieldsToInstance<F>;
1303
1436
 
1304
- /** Dynamic field access via Proxy. */
1437
+ /** The fields, for `JSON.stringify` (same as {@link toObject}). */
1438
+ toJSON(): FieldsToInstance<F>;
1439
+
1440
+ /** Fields: accessors of the class (not own properties, as in Python). */
1305
1441
  [field: string]: any;
1306
1442
  }
1307
1443
 
@@ -1430,7 +1566,11 @@ export function load(path: string | null): Library;
1430
1566
  *
1431
1567
  * @category Callbacks
1432
1568
  */
1433
- export function callback(fn: Function, returnType: AnyType | null, argTypes?: AnyType[]): CallbackWrapper;
1569
+ type CallbackRestype = SimpleCDataConstructor | PointerTypeDef | FuncPtrFactory | number | null;
1570
+ type CallbackArgs<T extends readonly FFIType[]> = { -readonly [K in keyof T]: JsFromCType<T[K]> };
1571
+ type CallbackResult<T> = T extends null | SimpleCDataConstructor<"void"> ? void : T extends StructureClass | StructDef | ArrayTypeDef ? never : JsArgFromCType<T> | (T extends SimpleCDataConstructor ? InstanceType<T> : never);
1572
+
1573
+ export function callback<TRet extends CallbackRestype, const TArgs extends readonly FFIType[] = readonly []>(fn: (...args: CallbackArgs<TArgs>) => CallbackResult<TRet>, returnType: TRet, argTypes?: TArgs): CallbackWrapper;
1434
1574
 
1435
1575
  /**
1436
1576
  * Create a thread-safe callback that can be invoked from any thread.
@@ -1445,7 +1585,7 @@ export function callback(fn: Function, returnType: AnyType | null, argTypes?: An
1445
1585
  *
1446
1586
  * @category Callbacks
1447
1587
  */
1448
- export function threadSafeCallback(fn: Function, returnType: AnyType | null, argTypes?: AnyType[]): ThreadSafeCallbackWrapper;
1588
+ export function threadSafeCallback<TRet extends CallbackRestype, const TArgs extends readonly FFIType[] = readonly []>(fn: (...args: CallbackArgs<TArgs>) => CallbackResult<TRet>, returnType: TRet, argTypes?: TArgs): ThreadSafeCallbackWrapper;
1449
1589
 
1450
1590
  /**
1451
1591
  * Create a function pointer type with cdecl calling convention.
@@ -1482,8 +1622,8 @@ export function threadSafeCallback(fn: Function, returnType: AnyType | null, arg
1482
1622
  * @category Function Pointers
1483
1623
  */
1484
1624
  export interface ParamFlag {
1485
- /** `"in"` for input params (default), `"out"` for output params (POINTER(T) argtype). */
1486
- dir: "in" | "out";
1625
+ /** OUT allocates a pointee; INOUT uses and returns the supplied instance. */
1626
+ dir: "in" | "out" | "inout";
1487
1627
  /** Parameter name, used for the named-call form `fn({ name: value, ... })`. */
1488
1628
  name: string;
1489
1629
  /** Optional default value; applied when the caller omits this `in` param. */
@@ -1495,47 +1635,54 @@ export interface ParamFlag {
1495
1635
  *
1496
1636
  * @category Function Pointers
1497
1637
  */
1498
- export interface FuncPtrFactory {
1638
+ export interface FuncPtrFactory<TRet extends FFIType | null = FFIType | null, TArgs extends readonly FFIType[] = readonly FFIType[]> {
1499
1639
  /** Call with a raw address to produce a caller. */
1500
- (address: bigint | number): (...args: any[]) => any;
1640
+ (address: bigint | number): TypedFFIFunction<TArgs, TRet>;
1641
+ new (address: bigint | number): TypedFFIFunction<TArgs, TRet>;
1501
1642
  /**
1502
1643
  * Call with a JS function to produce a C-callable callback closure, usable
1503
1644
  * as argument or struct field of this type. Keep it referenced while C may
1504
1645
  * call it; `release()` frees it.
1505
1646
  */
1506
- (fn: (...args: any[]) => any): { readonly pointer: bigint; readonly _as_parameter_: bigint; release(): void };
1647
+ (fn: (...args: CallbackArgs<TArgs>) => CallbackResult<TRet>): CallbackWrapper;
1648
+ new (fn: (...args: CallbackArgs<TArgs>) => CallbackResult<TRet>): CallbackWrapper;
1507
1649
  /**
1508
1650
  * Bind an exported function of a library, optionally with paramflags.
1509
1651
  * Python: `prototype((name, dll))` / `prototype((name, dll), paramflags)`.
1510
1652
  */
1511
- (spec: readonly [name: string, library: CDLL], paramflags?: ReadonlyArray<ParamFlag | readonly [flag: number, name?: string, defaultValue?: any]>): (...args: any[]) => any;
1653
+ (spec: readonly [name: string, library: CDLL]): TypedFFIFunction<TArgs, TRet>;
1654
+ (spec: readonly [name: string, library: CDLL], paramflags: ReadonlyArray<ParamFlag | readonly [flag: number, name?: string, defaultValue?: any]>): FFIFunction;
1512
1655
 
1656
+ /** Shared metadata; assigning it does not recompile the captured signature. */
1513
1657
  restype: FFIType | null;
1658
+ /** Shared metadata; mutating it does not recompile the captured signature. */
1514
1659
  argtypes: FFIType[];
1515
1660
  readonly _isFuncPtr: true;
1516
1661
 
1517
1662
  /**
1518
1663
  * Bind the factory to a library export with Python-style paramflags.
1519
- * Out params are allocated automatically and returned as part of the tuple.
1664
+ * Out params are allocated automatically and returned alone (one value or
1665
+ * an array). Returning the original `args` from errcheck keeps this behavior.
1666
+ * `callAsync()` uses the same output processing and per-call hook snapshot.
1520
1667
  *
1521
1668
  * Python ctypes parity: `prototype((name, lib), paramflags)`.
1522
1669
  *
1523
1670
  * @example
1524
1671
  * ```javascript
1525
- * const proto = WINFUNCTYPE(BOOL, HWND, POINTER(DWORD), POINTER(DWORD));
1672
+ * const proto = WINFUNCTYPE(DWORD, HWND, LPDWORD);
1526
1673
  * const fn = proto.bind(user32, "GetWindowThreadProcessId", [
1527
1674
  * { dir: "in", name: "hWnd" },
1528
1675
  * { dir: "out", name: "pid" },
1529
- * { dir: "out", name: "tid" },
1530
1676
  * ]);
1531
- * const [ok, pid, tid] = fn(hwnd); // positional
1532
- * const [ok2, pid2, tid2] = fn({ hWnd: hwnd }); // named
1677
+ * const pid = fn(hwnd); // positional; thread ID is discarded
1678
+ * const pid2 = fn({ hWnd: hwnd }); // named
1679
+ * const pid3 = await fn.callAsync(hwnd); // async, same output processing
1533
1680
  * ```
1534
1681
  */
1535
- bind(library: CDLL, symbolName: string, paramflags: ReadonlyArray<ParamFlag | readonly [flag: number, name?: string, defaultValue?: any]>): (...args: any[]) => any;
1682
+ bind(library: CDLL, symbolName: string, paramflags: ReadonlyArray<ParamFlag | readonly [flag: number, name?: string, defaultValue?: any]>): FFIFunction;
1536
1683
  }
1537
1684
 
1538
- export function CFUNCTYPE(restype: FFIType | null, ...argtypes: FFIType[]): FuncPtrFactory;
1685
+ export function CFUNCTYPE<TRet extends FFIType | null, const TArgs extends readonly FFIType[]>(restype: TRet, ...argtypes: TArgs): FuncPtrFactory<TRet, TArgs>;
1539
1686
 
1540
1687
  /**
1541
1688
  * Create a function pointer type with stdcall calling convention (Windows).
@@ -1550,7 +1697,7 @@ export function CFUNCTYPE(restype: FFIType | null, ...argtypes: FFIType[]): Func
1550
1697
  *
1551
1698
  * @category Callbacks
1552
1699
  */
1553
- export function WINFUNCTYPE(restype: FFIType | null, ...argtypes: FFIType[]): FuncPtrFactory;
1700
+ export function WINFUNCTYPE<TRet extends FFIType | null, const TArgs extends readonly FFIType[]>(restype: TRet, ...argtypes: TArgs): FuncPtrFactory<TRet, TArgs>;
1554
1701
 
1555
1702
  /**
1556
1703
  * Create a C string buffer (null-terminated).
@@ -1622,7 +1769,14 @@ export function wstring_at(address: Buffer | bigint | number, size?: number): st
1622
1769
  *
1623
1770
  * @category Memory
1624
1771
  */
1625
- export function addressof(ptr: Buffer | bigint | number): bigint;
1772
+ export function addressof(ptr: ArrayBufferView | ArrayBuffer | { readonly _buffer: Buffer } | PointerInstance | bigint | number): bigint;
1773
+
1774
+ /**
1775
+ * Memory argument of {@link memmove} / {@link memset}: a buffer (any typed
1776
+ * array, DataView or ArrayBuffer, as bytes), a ctypes instance, a pointer or an
1777
+ * address.
1778
+ */
1779
+ export type MemoryTarget = ArrayBufferView | ArrayBufferLike | { readonly _buffer: Buffer } | { readonly _as_parameter_: unknown } | PointerInstance | bigint | number | null;
1626
1780
 
1627
1781
  /**
1628
1782
  * Copy memory from source to destination.
@@ -1631,10 +1785,7 @@ export function addressof(ptr: Buffer | bigint | number): bigint;
1631
1785
  *
1632
1786
  * @category Memory
1633
1787
  */
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
- export function memmove(dst: MemoryTarget, src: MemoryTarget, count: number): void;
1788
+ export function memmove(dst: MemoryTarget, src: MemoryTarget, count: number): bigint;
1638
1789
 
1639
1790
  /**
1640
1791
  * Fill memory with a byte value.
@@ -1643,7 +1794,7 @@ export function memmove(dst: MemoryTarget, src: MemoryTarget, count: number): vo
1643
1794
  *
1644
1795
  * @category Memory
1645
1796
  */
1646
- export function memset(dst: MemoryTarget, value: number, count: number): void;
1797
+ export function memset(dst: MemoryTarget, value: number, count: number): bigint;
1647
1798
 
1648
1799
  /**
1649
1800
  * Read a typed value from a buffer at a given offset.
@@ -1661,8 +1812,8 @@ export function memset(dst: MemoryTarget, value: number, count: number): void;
1661
1812
  *
1662
1813
  * @category Memory
1663
1814
  */
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;
1815
+ export function readValue<T extends AnyType>(ptr: MemorySource, type: T, offset?: number): JsFromCType<T>;
1816
+ export function readValue(ptr: MemorySource, type: AnyType | StructureClass, offset?: number): any;
1666
1817
 
1667
1818
  /**
1668
1819
  * Write a typed value to a buffer at a given offset.
@@ -1674,8 +1825,8 @@ export function readValue(ptr: Buffer | bigint | number | PointerInstance, type:
1674
1825
  *
1675
1826
  * @category Memory
1676
1827
  */
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;
1828
+ export function writeValue<T extends AnyType>(ptr: MemorySource, type: T, value: JsArgFromCType<T>, offset?: number): number | void;
1829
+ export function writeValue(ptr: MemorySource, type: AnyType | StructureClass, value: any, offset?: number): number | void;
1679
1830
 
1680
1831
  /**
1681
1832
  * Get the size of a type in bytes.
@@ -1691,7 +1842,10 @@ export function writeValue(ptr: Buffer | bigint | number | PointerInstance, type
1691
1842
  *
1692
1843
  * @category Memory
1693
1844
  */
1694
- export function sizeof(type: AnyType | StructDef | ArrayTypeDef | StructureClass | PointerTypeDef | FuncPtrFactory | SimpleCDataInstance | Structure<any> | Uint8Array): number;
1845
+ export function sizeof(type: AnyType | StructDef | ArrayTypeDef | StructureClass | PointerTypeDef | FuncPtrFactory | SimpleCDataInstance | Structure<any> | ArrayBufferView): number;
1846
+
1847
+ /** Memory read/written by {@link readValue} / {@link writeValue}: a buffer, a ctypes instance, a pointer or an address. */
1848
+ type MemorySource = Buffer | ArrayBufferView | { _buffer: Buffer } | bigint | number | PointerInstance;
1695
1849
 
1696
1850
  /**
1697
1851
  * Get the alignment requirement of a type in bytes.
@@ -1734,10 +1888,11 @@ export function struct<F extends Record<string, FieldSpec>>(fields: F, options?:
1734
1888
  * For Python-like class syntax, use {@link Union} instead.
1735
1889
  *
1736
1890
  * @param fields - Object mapping field names to types
1891
+ * @param options - Union options (e.g. `{ pack: 1 }`)
1737
1892
  *
1738
1893
  * @category Structures
1739
1894
  */
1740
- export function union<F extends Record<string, FieldSpec>>(fields: F): UnionDef<F>;
1895
+ export function union<F extends Record<string, FieldSpec>>(fields: F, options?: StructOptions): UnionDef<F>;
1741
1896
 
1742
1897
  /**
1743
1898
  * Factory that returns a Structure subclass with typed fields.
@@ -1747,7 +1902,7 @@ export function union<F extends Record<string, FieldSpec>>(fields: F): UnionDef<
1747
1902
  *
1748
1903
  * @category Structures
1749
1904
  */
1750
- export function defineStruct<F extends Record<string, FieldSpec>>(fields: F, options?: StructOptions): new (values?: Partial<FieldsToInstance<F>> | Buffer) => Structure<F> & FieldsToInstance<F>;
1905
+ export function defineStruct<F extends Record<string, FieldSpec>>(fields: F, options?: StructOptions): DefinedClass<F, Structure<F> & FieldsToInstance<F>>;
1751
1906
 
1752
1907
  /**
1753
1908
  * Factory that returns a Union subclass with typed fields.
@@ -1756,11 +1911,35 @@ export function defineStruct<F extends Record<string, FieldSpec>>(fields: F, opt
1756
1911
  *
1757
1912
  * @category Structures
1758
1913
  */
1759
- export function defineUnion<F extends Record<string, FieldSpec>>(fields: F): new (values?: Partial<FieldsToInstance<F>> | Buffer) => Union<F> & FieldsToInstance<F>;
1914
+ export function defineUnion<F extends Record<string, FieldSpec>>(fields: F, options?: StructOptions): DefinedClass<F, Union<F> & FieldsToInstance<F>>;
1915
+
1916
+ /**
1917
+ * Class returned by {@link defineStruct} / {@link defineUnion}: the statics of
1918
+ * {@link Structure} and a constructor with positional values (field order),
1919
+ * an object of field values or a Buffer.
1920
+ * @category Structures
1921
+ */
1922
+ export interface DefinedClass<F extends Record<string, FieldSpec>, I> {
1923
+ new (values?: Partial<FieldsToInstance<F>> | Buffer): I;
1924
+ new (...values: any[]): I;
1925
+ readonly size: number;
1926
+ readonly alignment: number;
1927
+ readonly fields: FieldDef[];
1928
+ create(values?: Partial<FieldsToInstance<F>> | Buffer): I;
1929
+ toObject(bufOrInstance: Buffer | I): FieldsToInstance<F>;
1930
+ from_buffer(source: ArrayBufferView | { _buffer: Buffer }, offset?: number): I;
1931
+ from_buffer_copy(source: ArrayBufferView | { _buffer: Buffer }, offset?: number): I;
1932
+ from_address(address: bigint | number): I;
1933
+ in_dll(library: CDLL | Library, name: string): I;
1934
+ }
1760
1935
 
1761
1936
  /**
1762
1937
  * Define a fixed-size array type.
1763
1938
  *
1939
+ * Weakly interned by element type and count: live types keep their identity,
1940
+ * including when retained by instances, signatures or containing types.
1941
+ * The cache does not keep unused types alive.
1942
+ *
1764
1943
  * Python equivalent: `c_int * 5`
1765
1944
  *
1766
1945
  * @param elementType - Type of each element
@@ -1775,18 +1954,21 @@ export function defineUnion<F extends Record<string, FieldSpec>>(fields: F): new
1775
1954
  *
1776
1955
  * @category Structures
1777
1956
  */
1778
- export function array<E extends AnyType | StructureClass | ArrayTypeDef | PointerTypeDef | FuncPtrFactory>(elementType: E, count: number): ArrayTypeDef<E>;
1957
+ export function array<E extends ArrayElementType>(elementType: E, count: number): ArrayTypeDef<E>;
1958
+
1959
+ /** Element types of {@link array}: C types, structures and unions (classes or definitions), arrays, pointers, function pointers. */
1960
+ type ArrayElementType = SimpleCDataConstructor | StructDef | UnionDef | StructureClass | ArrayTypeDef | PointerTypeDef | FuncPtrFactory;
1779
1961
 
1780
1962
  /**
1781
1963
  * Alias of {@link array}. Python equivalent: `ctypes.ARRAY(type, length)`.
1782
1964
  * @category Structures
1783
1965
  */
1784
- export function ARRAY<E extends AnyType | StructureClass | ArrayTypeDef | PointerTypeDef | FuncPtrFactory>(elementType: E, count: number): ArrayTypeDef<E>;
1966
+ export function ARRAY<E extends ArrayElementType>(elementType: E, count: number): ArrayTypeDef<E>;
1785
1967
 
1786
1968
  /**
1787
1969
  * Define a bit field for use in struct `_fields_`.
1788
1970
  *
1789
- * @param baseType - The underlying integer type (e.g. `c_uint32`)
1971
+ * @param baseType - The underlying integer type (e.g. `c_uint32`) or `c_bool`; other types raise TypeError, as in Python
1790
1972
  * @param bits - Number of bits
1791
1973
  *
1792
1974
  * @example
@@ -1801,18 +1983,25 @@ export function ARRAY<E extends AnyType | StructureClass | ArrayTypeDef | Pointe
1801
1983
  *
1802
1984
  * @category Structures
1803
1985
  */
1804
- export function bitfield(baseType: AnyType, bits: number): BitFieldDef;
1986
+ export function bitfield(baseType: SimpleCDataConstructor, bits: number): BitFieldDef;
1805
1987
 
1806
1988
  /**
1807
- * Pass an object by reference (returns its underlying buffer).
1989
+ * Pass an object by reference, retaining its owner and applying a signed byte offset.
1990
+ * In-range references are Buffer views; out-of-range offsets are address carriers.
1808
1991
  *
1809
1992
  * Python equivalent: `ctypes.byref`
1810
1993
  *
1811
1994
  * @param obj - A Buffer, SimpleCData instance, or any object with a `_buffer` property
1995
+ * @param offset - Signed byte offset; the caller is responsible for valid external memory
1812
1996
  *
1813
1997
  * @category Pointers
1814
1998
  */
1815
- export function byref(obj: Buffer | SimpleCDataInstance | { _buffer: Buffer }): Buffer;
1999
+ export interface ByRefAddress {
2000
+ readonly address: bigint;
2001
+ readonly _as_parameter_: bigint;
2002
+ }
2003
+ export function byref(obj: Buffer | SimpleCDataInstance | { _buffer: Buffer }, offset?: 0): Buffer;
2004
+ export function byref(obj: Buffer | SimpleCDataInstance | { _buffer: Buffer }, offset: number): Buffer | ByRefAddress;
1816
2005
 
1817
2006
  /**
1818
2007
  * Interpret a pointer as a different type.
@@ -1842,8 +2031,8 @@ export function byref(obj: Buffer | SimpleCDataInstance | { _buffer: Buffer }):
1842
2031
  *
1843
2032
  * @category Pointers
1844
2033
  */
1845
- export function cast<T>(ptr: Buffer | bigint | number | SimpleCDataInstance, targetType: PointerTypeDef<T>): PointerInstance<T>;
1846
- export function cast(ptr: Buffer | bigint | number | SimpleCDataInstance, targetType: AnyType | StructDef | StructureClass): any;
2034
+ export function cast<T>(ptr: MemorySource | ArrayBuffer | ByRefAddress | null, targetType: PointerTypeDef<T>): PointerInstance<T>;
2035
+ export function cast(ptr: MemorySource | ArrayBuffer | ByRefAddress | null, targetType: AnyType | StructDef | StructureClass): any;
1847
2036
 
1848
2037
  /**
1849
2038
  * Create a pointer type for a given base type.
@@ -1965,7 +2154,7 @@ export function set_last_error(code: number): number;
1965
2154
  * @category Error Handling
1966
2155
  */
1967
2156
  export class ArgumentError extends TypeError {
1968
- constructor(message?: string);
2157
+ constructor(message?: string, options?: ErrorOptions);
1969
2158
  }
1970
2159
 
1971
2160
  /**
@@ -1985,11 +2174,12 @@ export function FormatError(code?: number): string;
1985
2174
  * Python equivalent: `ctypes.WinError()`
1986
2175
  *
1987
2176
  * @param code - Error code (defaults to `GetLastError()`)
1988
- * @returns Error with `.winerror` property
2177
+ * @param descr - Message (defaults to `FormatError(code)`)
2178
+ * @returns Error with `winerror`, `errno` (mapped as Python's OSError) and `strerror`
1989
2179
  *
1990
2180
  * @category Error Handling
1991
2181
  */
1992
- export function WinError(code?: number): Error & { winerror: number };
2182
+ export function WinError(code?: number | null, descr?: string): Error & { winerror: number; errno: number; strerror: string };
1993
2183
 
1994
2184
  // =============================================================================
1995
2185
  // SimpleCData - Base class for simple C data types
@@ -2019,13 +2209,13 @@ export interface SimpleCDataConstructor<Tag extends string = string> {
2019
2209
  _writer(buf: Buffer, offset: number, value: JsArgFromTag<Tag>): void;
2020
2210
 
2021
2211
  /** Create an instance that aliases an existing Buffer (zero-copy). */
2022
- from_buffer(buffer: Buffer, offset?: number): SimpleCDataInstance<JsFromTag<Tag>>;
2212
+ from_buffer<T extends SimpleCDataConstructor<Tag>>(this: T, buffer: ArrayBufferView | { readonly _buffer: Buffer }, offset?: number): InstanceType<T>;
2023
2213
  /** Create an instance whose buffer is a copy of the source bytes. */
2024
- from_buffer_copy(buffer: Buffer, offset?: number): SimpleCDataInstance<JsFromTag<Tag>>;
2214
+ from_buffer_copy<T extends SimpleCDataConstructor<Tag>>(this: T, buffer: ArrayBufferView | { readonly _buffer: Buffer }, offset?: number): InstanceType<T>;
2025
2215
  /** Create an instance viewing raw memory at the given address. */
2026
- from_address(address: bigint | number): SimpleCDataInstance<JsFromTag<Tag>>;
2216
+ from_address<T extends SimpleCDataConstructor<Tag>>(this: T, address: bigint | number): InstanceType<T>;
2027
2217
  /** Bind this type to an exported global variable in a shared library. */
2028
- in_dll(library: CDLL | Library, name: string): SimpleCDataInstance<JsFromTag<Tag>>;
2218
+ in_dll<T extends SimpleCDataConstructor<Tag>>(this: T, library: CDLL | Library, name: string): InstanceType<T>;
2029
2219
  }
2030
2220
 
2031
2221
  /**
@@ -2097,6 +2287,8 @@ export interface SimpleCDataInstance<T = any> {
2097
2287
  toString(): string;
2098
2288
  toJSON(): T;
2099
2289
  valueOf(): T;
2290
+ /** OUT conversion; defaults to the value for builtins and the instance for subclasses. */
2291
+ __ctypes_from_outparam__(): unknown;
2100
2292
  }
2101
2293
 
2102
2294
  // =============================================================================
@@ -2458,8 +2650,9 @@ export const DEFAULT_MODE: number;
2458
2650
  * are provided (e.g. `"c"` → `"msvcrt.dll"`).
2459
2651
  * - On Linux, the `ldconfig` cache and common library directories are
2460
2652
  * searched for the best-matching `libNAME.so.VERSION`.
2461
- * - On macOS, `/usr/lib`, `/usr/local/lib`, Homebrew prefixes and framework
2462
- * bundles are searched.
2653
+ * - On macOS, the `DYLD_*` paths, the dyld fallback directories, Homebrew and
2654
+ * the framework directories are searched, including the dyld shared cache
2655
+ * (system libraries and frameworks are not on disk since macOS 11).
2463
2656
  *
2464
2657
  * Returns `null` if the input is invalid. Returns a best-effort fallback
2465
2658
  * (bare soname) if nothing is found, so the loader can still try its own