node-ctypes 1.2.0 → 1.4.0

package/lib/core/Library.js

@@ -51,255 +51,295 @@
  * @private
  */
 export function createLibraryClasses(Library, LRUCache, _toNativeType, _toNativeTypes, native) {
-class FunctionWrapper {
-  constructor(cdll, name) {
-    const argtypes = [];
-    let restype = undefined;
-    let cachedFunc = null;
+  class FunctionWrapper {
+    constructor(cdll, name) {
+      const argtypes = [];
+      let restype = undefined;
+      let cachedFunc = null;
 
-    // Create a function and proxy it to make it callable
-    const func = (...args) => {
-      if (restype === undefined) {
-        throw new Error(`Function ${name}: restype not set`);
-      }
-      if (!cachedFunc) {
-        cachedFunc = cdll.func(name, restype, argtypes);
-      }
-      return cachedFunc(...args);
-    };
-
-    // Proxy the function to intercept property access
-    return new Proxy(func, {
-      get(target, prop) {
-        if (prop === "argtypes") return argtypes;
-        if (prop === "restype") return restype;
-        if (prop === "errcheck") return cachedFunc ? cachedFunc.errcheck : undefined;
-        return target[prop];
-      },
-      set(target, prop, value) {
-        if (prop === "argtypes") {
-          argtypes.splice(0, argtypes.length, ...value);
-          cachedFunc = null; // Invalidate cache
-          return true;
+      // Create a function and proxy it to make it callable
+      const func = (...args) => {
+        if (restype === undefined) {
+          throw new Error(`Function ${name}: restype not set`);
         }
-        if (prop === "restype") {
-          restype = value;
-          cachedFunc = null; // Invalidate cache
-          return true;
+        if (!cachedFunc) {
+          cachedFunc = cdll.func(name, restype, argtypes);
         }
-        if (prop === "errcheck") {
-          if (!cachedFunc) {
+        return cachedFunc(...args);
+      };
+
+      // Proxy the function to intercept property access
+      return new Proxy(func, {
+        get(target, prop) {
+          if (prop === "argtypes") return argtypes;
+          if (prop === "restype") return restype;
+          if (prop === "errcheck") return cachedFunc ? cachedFunc.errcheck : undefined;
+          if (prop === "callAsync") {
             if (restype === undefined) {
               throw new Error(`Function ${name}: restype not set`);
             }
-            cachedFunc = cdll.func(name, restype, argtypes);
+            if (!cachedFunc) {
+              cachedFunc = cdll.func(name, restype, argtypes);
+            }
+            return cachedFunc.callAsync;
+          }
+          return target[prop];
+        },
+        set(target, prop, value) {
+          if (prop === "argtypes") {
+            argtypes.splice(0, argtypes.length, ...value);
+            cachedFunc = null; // Invalidate cache
+            return true;
           }
-          cachedFunc.errcheck = value;
+          if (prop === "restype") {
+            restype = value;
+            cachedFunc = null; // Invalidate cache
+            return true;
+          }
+          if (prop === "errcheck") {
+            if (!cachedFunc) {
+              if (restype === undefined) {
+                throw new Error(`Function ${name}: restype not set`);
+              }
+              cachedFunc = cdll.func(name, restype, argtypes);
+            }
+            cachedFunc.errcheck = value;
+            return true;
+          }
+          target[prop] = value;
           return true;
-        }
-        target[prop] = value;
-        return true;
-      },
-    });
-  }
-}
-
-/**
- * Wrapper conveniente per CDLL (come in Python ctypes)
- */
-class CDLL {
-  constructor(libPath, options = {}) {
-    this._lib = new Library(libPath);
-    // Use LRU cache to prevent unbounded memory growth
-    const cacheSize = options.cacheSize ?? 1000;
-    this._cache = new LRUCache(cacheSize);
-
-    // Return a proxy to enable Python-like syntax: libc.abs.argtypes = [...]; libc.abs.restype = ...; libc.abs(...)
-    return new Proxy(this, {
-      get(target, prop, receiver) {
-        // Allow access to existing properties/methods
-        if (prop in target || typeof prop !== "string") {
-          return Reflect.get(target, prop, receiver);
-        }
-        // Assume it's a function name from the library
-        return new FunctionWrapper(target, prop);
-      },
-    });
+        },
+      });
+    }
   }
 
   /**
-   * Ottiene una funzione dalla libreria
-   * @param {string} name - Nome della funzione
-   * @param {Function|number|CType} returnType - Tipo di ritorno (SimpleCData class, CType value, o CType)
-   * @param {Array<Function|number|CType>} argTypes - Tipi degli argomenti
-   * @param {Object} [options] - Opzioni aggiuntive (es. { abi: 'stdcall' })
-   * @returns {Function} Funzione callable
+   * Wrapper conveniente per CDLL (come in Python ctypes)
    */
-  func(name, returnType, argTypes = [], options = {}) {
-    const cacheKey = `${name}:${returnType}:${argTypes.join(",")}`;
+  class CDLL {
+    constructor(libPath, options = {}) {
+      this._lib = new Library(libPath);
+      // Use LRU cache to prevent unbounded memory growth
+      const cacheSize = options.cacheSize ?? 1000;
+      this._cache = new LRUCache(cacheSize);
+      // Cache for FunctionWrapper instances (Python-like syntax)
+      this._funcWrapperCache = new Map();
 
-    if (this._cache.has(cacheKey)) {
-      return this._cache.get(cacheKey);
+      // Return a proxy to enable Python-like syntax: libc.abs.argtypes = [...]; libc.abs.restype = ...; libc.abs(...)
+      return new Proxy(this, {
+        get(target, prop, receiver) {
+          // Allow access to existing properties/methods
+          if (prop in target || typeof prop !== "string") {
+            return Reflect.get(target, prop, receiver);
+          }
+          // Check if we already have a FunctionWrapper for this function name
+          if (target._funcWrapperCache.has(prop)) {
+            return target._funcWrapperCache.get(prop);
+          }
+          // Create and cache a new FunctionWrapper
+          const wrapper = new FunctionWrapper(target, prop);
+          target._funcWrapperCache.set(prop, wrapper);
+          return wrapper;
+        },
+      });
     }
 
-    const ffiFunc = this._lib.func(name, _toNativeType(returnType, native), _toNativeTypes(argTypes, native), options);
+    /**
+     * Ottiene una funzione dalla libreria
+     * @param {string} name - Nome della funzione
+     * @param {Function|number|CType} returnType - Tipo di ritorno (SimpleCData class, CType value, o CType)
+     * @param {Array<Function|number|CType>} argTypes - Tipi degli argomenti
+     * @param {Object} [options] - Opzioni aggiuntive (es. { abi: 'stdcall' })
+     * @returns {Function} Funzione callable
+     */
+    func(name, returnType, argTypes = [], options = {}) {
+      const cacheKey = `${name}:${returnType}:${argTypes.join(",")}`;
 
-    // =========================================================================
-    // OPTIMIZATION: Create specialized wrapper based on argument types
-    // For primitive-only args, bypass the processing loop entirely
-    // =========================================================================
+      if (this._cache.has(cacheKey)) {
+        return this._cache.get(cacheKey);
+      }
 
-    const argCount = argTypes.length;
+      const ffiFunc = this._lib.func(name, _toNativeType(returnType, native), _toNativeTypes(argTypes, native), options);
 
-    // Check if all args are primitive types (no structs/buffers that need _buffer extraction)
-    const allPrimitive = argTypes.every((t) => {
-      if (typeof t === "function" && t._isSimpleCData) {
-        // SimpleCData types that are NOT pointers are primitive
-        const typeName = t._type;
-        return typeName !== native.CType.POINTER && typeName !== native.CType.STRING && typeName !== native.CType.WSTRING;
-      }
-      return false;
-    });
+      // =========================================================================
+      // OPTIMIZATION: Create specialized wrapper based on argument types
+      // For primitive-only args, bypass the processing loop entirely
+      // =========================================================================
 
-    let callMethod;
+      const argCount = argTypes.length;
 
-    if (argCount === 0) {
-      // FAST PATH: No arguments - direct call
-      callMethod = function () {
-        return ffiFunc.call();
-      };
-    } else if (allPrimitive) {
-      // FAST PATH: All primitive args - direct call without processing
-      switch (argCount) {
-        case 1:
-          callMethod = function (a0) {
-            return ffiFunc.call(a0);
-          };
-          break;
-        case 2:
-          callMethod = function (a0, a1) {
-            return ffiFunc.call(a0, a1);
-          };
-          break;
-        case 3:
-          callMethod = function (a0, a1, a2) {
-            return ffiFunc.call(a0, a1, a2);
-          };
-          break;
-        case 4:
-          callMethod = function (a0, a1, a2, a3) {
-            return ffiFunc.call(a0, a1, a2, a3);
-          };
-          break;
-        default:
-          // Fallback for many args
-          callMethod = function (...args) {
-            return ffiFunc.call(...args);
-          };
-      }
-    } else {
-      // SLOW PATH: Has buffer/struct args - need to extract _buffer
-      callMethod = function (...args) {
-        const processedArgs = [];
+      // Check if all args are primitive types (no structs/buffers that need _buffer extraction)
+      const allPrimitive = argTypes.every((t) => {
+        if (typeof t === "function" && t._isSimpleCData) {
+          // SimpleCData types that are NOT pointers are primitive
+          const typeName = t._type;
+          return typeName !== native.CType.POINTER && typeName !== native.CType.STRING && typeName !== native.CType.WSTRING;
+        }
+        return false;
+      });
 
-        for (let i = 0; i < args.length; i++) {
-          const arg = args[i];
-          // Check for _buffer FIRST (handles Proxy-wrapped structs)
-          // This avoids calling Buffer.isBuffer() on Proxy which can cause issues
-          if (arg && typeof arg === "object") {
-            // Check for struct proxy FIRST - accessing _buffer on Proxy is safe
-            // but Buffer.isBuffer(proxy) can cause hangs
-            if (arg._buffer !== undefined && Buffer.isBuffer(arg._buffer)) {
-              // Struct proxy or object with _buffer
-              processedArgs.push(arg._buffer);
-            } else if (Buffer.isBuffer(arg)) {
-              // Already a buffer, use directly
+      let callMethod;
+
+      if (argCount === 0) {
+        // FAST PATH: No declared arguments - but still support variadic
+        callMethod = function (...args) {
+          if (args.length === 0) {
+            return ffiFunc.call();
+          }
+          // Variadic: pass all args directly
+          return ffiFunc.call(...args);
+        };
+      } else if (allPrimitive) {
+        // FAST PATH: All primitive args - use rest args to support variadic
+        callMethod = function (...args) {
+          return ffiFunc.call(...args);
+        };
+      } else {
+        // SLOW PATH: Has buffer/struct args - need to extract _buffer
+        callMethod = function (...args) {
+          const processedArgs = [];
+
+          for (let i = 0; i < args.length; i++) {
+            const arg = args[i];
+            // Check for _buffer FIRST (handles Proxy-wrapped structs)
+            // This avoids calling Buffer.isBuffer() on Proxy which can cause issues
+            if (arg && typeof arg === "object") {
+              // Check for struct proxy FIRST - accessing _buffer on Proxy is safe
+              // but Buffer.isBuffer(proxy) can cause hangs
+              if (arg._buffer !== undefined && Buffer.isBuffer(arg._buffer)) {
+                // Struct proxy or object with _buffer
+                processedArgs.push(arg._buffer);
+              } else if (Buffer.isBuffer(arg)) {
+                // Already a buffer, use directly
+                processedArgs.push(arg);
+              } else {
+                // Other object, pass as-is
+                processedArgs.push(arg);
+              }
+            } else {
+              // Primitive value (number, string, bigint, null, undefined)
               processedArgs.push(arg);
+            }
+          }
+
+          return ffiFunc.call(...processedArgs);
+        };
+      }
+
+      // =========================================================================
+      // ASYNC WRAPPER: same argument processing, but calls callAsync
+      // Returns a Promise instead of the result directly
+      // =========================================================================
+
+      let asyncCallMethod;
+
+      if (argCount === 0) {
+        asyncCallMethod = function (...args) {
+          if (args.length === 0) {
+            return ffiFunc.callAsync();
+          }
+          // Variadic: pass all args directly
+          return ffiFunc.callAsync(...args);
+        };
+      } else if (allPrimitive) {
+        asyncCallMethod = function (...args) {
+          return ffiFunc.callAsync(...args);
+        };
+      } else {
+        asyncCallMethod = function (...args) {
+          const processedArgs = [];
+
+          for (let i = 0; i < args.length; i++) {
+            const arg = args[i];
+            if (arg && typeof arg === "object") {
+              if (arg._buffer !== undefined && Buffer.isBuffer(arg._buffer)) {
+                processedArgs.push(arg._buffer);
+              } else if (Buffer.isBuffer(arg)) {
+                processedArgs.push(arg);
+              } else {
+                processedArgs.push(arg);
+              }
             } else {
-              // Other object, pass as-is
               processedArgs.push(arg);
             }
-          } else {
-            // Primitive value (number, string, bigint, null, undefined)
-            processedArgs.push(arg);
           }
-        }
 
-        return ffiFunc.call(...processedArgs);
-      };
-    }
+          return ffiFunc.callAsync(...processedArgs);
+        };
+      }
 
-    // Aggiungi metadata come proprietà non-enumerable per non interferire
-    Object.defineProperties(callMethod, {
-      funcName: { value: name },
-      address: { value: ffiFunc.address },
-      _ffi: { value: ffiFunc },
-      // Esponi errcheck come setter/getter
-      errcheck: {
-        get() {
-          return ffiFunc._errcheck;
-        },
-        set(callback) {
-          ffiFunc._errcheck = callback;
-          ffiFunc.setErrcheck(callback);
+      // Aggiungi metadata come proprietà non-enumerable per non interferire
+      Object.defineProperties(callMethod, {
+        funcName: { value: name },
+        address: { value: ffiFunc.address },
+        _ffi: { value: ffiFunc },
+        callAsync: { value: asyncCallMethod, writable: false, enumerable: false, configurable: false },
+        // Esponi errcheck come setter/getter
+        errcheck: {
+          get() {
+            return ffiFunc._errcheck;
+          },
+          set(callback) {
+            ffiFunc._errcheck = callback;
+            ffiFunc.setErrcheck(callback);
+          },
+          enumerable: false,
+          configurable: true,
         },
-        enumerable: false,
-        configurable: true,
-      },
-    });
+      });
 
-    this._cache.set(cacheKey, callMethod);
-    return callMethod;
-  }
+      this._cache.set(cacheKey, callMethod);
+      return callMethod;
+    }
 
-  /**
-   * Ottiene l'indirizzo di un simbolo
-   * @param {string} name - Nome del simbolo
-   * @returns {BigInt} Indirizzo del simbolo
-   */
-  symbol(name) {
-    return this._lib.symbol(name);
-  }
+    /**
+     * Ottiene l'indirizzo di un simbolo
+     * @param {string} name - Nome del simbolo
+     * @returns {BigInt} Indirizzo del simbolo
+     */
+    symbol(name) {
+      return this._lib.symbol(name);
+    }
 
-  /**
-   * Crea un callback JS chiamabile da C
-   * @param {Function} fn - Funzione JavaScript
-   * @param {Function|number|CType} returnType - Tipo di ritorno (SimpleCData class, CType value, o CType)
-   * @param {Array<Function|number|CType>} argTypes - Tipi degli argomenti
-   * @returns {Object} Oggetto callback con proprietà pointer e metodi
-   */
-  callback(fn, returnType, argTypes = []) {
-    return this._lib.callback(_toNativeType(returnType, native), _toNativeTypes(argTypes, native), fn);
-  }
+    /**
+     * Crea un callback JS chiamabile da C
+     * @param {Function} fn - Funzione JavaScript
+     * @param {Function|number|CType} returnType - Tipo di ritorno (SimpleCData class, CType value, o CType)
+     * @param {Array<Function|number|CType>} argTypes - Tipi degli argomenti
+     * @returns {Object} Oggetto callback con proprietà pointer e metodi
+     */
+    callback(fn, returnType, argTypes = []) {
+      return this._lib.callback(_toNativeType(returnType, native), _toNativeTypes(argTypes, native), fn);
+    }
 
-  /**
-   * Chiude la libreria
-   */
-  close() {
-    this._lib.close();
-    this._cache.clear();
-  }
+    /**
+     * Chiude la libreria
+     */
+    close() {
+      this._lib.close();
+      this._cache.clear();
+    }
 
-  get path() {
-    return this._lib.path;
-  }
+    get path() {
+      return this._lib.path;
+    }
 
-  get loaded() {
-    return this._lib.loaded;
+    get loaded() {
+      return this._lib.loaded;
+    }
   }
-}
 
-/**
- * WinDLL - come CDLL ma con stdcall di default (per Windows)
- */
-class WinDLL extends CDLL {
-  func(name, returnType, argTypes = [], options = {}) {
-    return super.func(name, returnType, argTypes, {
-      abi: "stdcall",
-      ...options,
-    });
+  /**
+   * WinDLL - come CDLL ma con stdcall di default (per Windows)
+   */
+  class WinDLL extends CDLL {
+    func(name, returnType, argTypes = [], options = {}) {
+      return super.func(name, returnType, argTypes, {
+        abi: "stdcall",
+        ...options,
+      });
+    }
   }
-}
 
   return { FunctionWrapper, CDLL, WinDLL };
 }

package/lib/core/types.js

@@ -88,6 +88,13 @@ export function _toNativeType(type, native) {
     return type._type;
   }
 
+  // POINTER types: return CType.POINTER (11)
+  // POINTER(baseType) returns an object with _pointerTo property
+  if (type && typeof type === "object" && type._pointerTo !== undefined) {
+    // All pointer types are passed as generic pointers to FFI
+    return native.CType.POINTER;
+  }
+
   // Structure/Union classes: pass through unchanged
   // These are handled specially by the FFI layer
   if (typeof type === "function" && type.prototype) {

package/lib/index.d.ts

@@ -79,6 +79,8 @@ export type ErrcheckCallback = (result: any, func: CallableFunction, args: any[]
 /** FFI function wrapper */
 export interface FFIFunction {
   (...args: any[]): any;
+  /** Async version: executes the native call on a worker thread, returns a Promise */
+  callAsync(...args: any[]): Promise<any>;
   readonly funcName: string;
   readonly address: bigint;
   errcheck: ErrcheckCallback | null;
@@ -87,11 +89,23 @@ export interface FFIFunction {
 /** CDLL - C calling convention library */
 export class CDLL {
   constructor(path: string | null);
-  func(name: string, returnType: AnyType, argTypes?: AnyType[], options?: FunctionOptions): CallableFunction & { errcheck: ErrcheckCallback | null };
+  func(name: string, returnType: AnyType, argTypes?: AnyType[], options?: FunctionOptions): CallableFunction & { callAsync(...args: any[]): Promise<any>; errcheck: ErrcheckCallback | null };
   symbol(name: string): bigint;
   close(): void;
   readonly path: string;
   readonly loaded: boolean;
+  /** Python-like function access: lib.FuncName returns a FunctionWrapper */
+  [funcName: string]: FunctionWrapper | any;
+}
+
+/** FunctionWrapper for Python-like argtypes/restype syntax */
+export interface FunctionWrapper {
+  (...args: any[]): any;
+  /** Async version: executes the native call on a worker thread, returns a Promise */
+  callAsync(...args: any[]): Promise<any>;
+  argtypes: AnyType[];
+  restype: AnyType;
+  errcheck: ErrcheckCallback | null;
 }
 
 /** WinDLL - stdcall calling convention library (Windows) */
@@ -326,6 +340,7 @@ export function bitfield(baseType: AnyType, bits: number): BitFieldDef;
 export function byref(obj: Buffer | SimpleCDataInstance | { _buffer: Buffer }): Buffer;
 export function cast(ptr: Buffer | bigint, targetType: AnyType | StructDef): Buffer | { [key: string]: any };
 export function POINTER(baseType: AnyType | StructDef): PointerTypeDef;
+export function pointer(obj: SimpleCDataInstance | { _buffer: Buffer }): SimpleCDataInstance & { contents: any; [index: number]: any };
 
 // Error handling
 export function get_errno(): number;
@@ -343,7 +358,7 @@ export function WinError(code?: number): Error & { winerror: number };
 export interface SimpleCDataConstructor {
   new (value?: any): SimpleCDataInstance;
   readonly _size: number;
-  readonly _type: number;  // CType numeric value from native module
+  readonly _type: number; // CType numeric value from native module
   readonly _isSimpleCData: true;
   _reader(buf: Buffer, offset: number): any;
   _writer(buf: Buffer, offset: number, value: any): void;
@@ -385,6 +400,17 @@ export const c_size_t: SimpleCDataConstructor;
 export const c_long: SimpleCDataConstructor;
 export const c_ulong: SimpleCDataConstructor;
 
+// Python-compatible aliases
+export const c_byte: SimpleCDataConstructor;
+export const c_ubyte: SimpleCDataConstructor;
+export const c_short: SimpleCDataConstructor;
+export const c_ushort: SimpleCDataConstructor;
+export const c_longlong: SimpleCDataConstructor;
+export const c_ulonglong: SimpleCDataConstructor;
+
+/** SimpleCData base class for creating custom simple types */
+export const SimpleCData: SimpleCDataConstructor;
+
 // =============================================================================
 // Constants
 // =============================================================================