node-ctypes 0.1.5 → 1.0.0

package/README.md

@@ -38,7 +38,7 @@ npm install node-ctypes
 Prebuilt binaries are available for:
 - Windows x64, ARM64
 - Linux x64, ARM64
-- macOS ARM64
+- macOS x64, ARM64
 
 ### From source
 
@@ -659,10 +659,12 @@ console.log(p.x, p.y);  // 1 2
 - `get_errno()` / `set_errno(value)` : access to errno (platform-specific implementation).
 - `_initWinError()` internals; public helpers: `GetLastError()`, `SetLastError(code)`, `FormatError(code)`, `WinError(code)`.
 
-**Type aliases**
-The following aliases are exposed (mapped from `native.types`):
+**Type aliases (Python-compatible)**
+The following type classes are exported (identical to Python ctypes):
 `c_int, c_uint, c_int8, c_uint8, c_int16, c_uint16, c_int32, c_uint32, c_int64, c_uint64, c_float, c_double, c_char, c_char_p, c_wchar, c_wchar_p, c_void_p, c_bool, c_size_t, c_long, c_ulong`.
 
+**Note**: Only type classes (e.g., `c_int32`) are supported, not string literals (e.g., `"int32"`). This matches Python ctypes behavior exactly.
+
 **Constants**
 - `POINTER_SIZE` - pointer size (from `native.POINTER_SIZE`).
 - `WCHAR_SIZE` - wchar size (from `native.WCHAR_SIZE`).
@@ -720,7 +722,7 @@ Base class for Python-like union definitions. Subclasses should define `static _
 | **Arrays** | `c_int * 5` | `array(c_int, 5)` |
 | **Bit fields** | `("flags", c_uint, 3)` | `bitfield(c_uint32, 3)` |
 | **Callbacks** | `CFUNCTYPE(c_int, c_int)` | `callback(fn, c_int, [c_int])` |
-| **Strings** | `c_char_p(b"hello")` | `create_string_buffer("hello")`<br>**or**<br>`c_char_p(b"hello")` |
+| **Strings** | `c_char_p(b"hello")` | `create_string_buffer("hello")`<br>**or**<br>`new c_char_p(b"hello")` |
 | **Pointers** | `POINTER(c_int)` | `c_void_p` |
 | **Variadic** | `sprintf(buf, b"%d", 42)` | `sprintf(buf, fmt, 42)` (auto) |
 | **Sizeof** | `sizeof(c_int)` | `sizeof(c_int)` |
@@ -742,19 +744,22 @@ Base class for Python-like union definitions. Subclasses should define `static _
 - Windows API (__stdcall via WinDLL)
 
 ⚠️ **Differences from Python ctypes**:
-- Structs use `.toObject()` for property access (eager loading for performance)
 - Callbacks must be manually released with `.release()`
 - **Function definition supports both syntaxes**: `func(name, returnType, argTypes)` **or** `func.argtypes = [...]; func.restype = ...`
-- No `POINTER()` type - use `c_void_p`
 
+✨ **100% Python-compatible**:
+- **Struct property access**: Direct access (`p.x`, `p.y`) works with `class X extends Structure` - identical to Python!
+- **Type system**: Only type classes (`c_int32`, `c_char_p`) are accepted, exactly like Python ctypes
+- **No string literals**: `"int32"`, `"string"` are NOT supported (Python doesn't use them either)
 
 ## Limitations & Known Issues
 
 - ⚠️ Callbacks must be released manually with `.release()` to prevent memory leaks
 - ⚠️ No automatic memory management for returned pointers (manual `free()` required)
-- ⚠️ Struct alignment follows platform defaults (not customizable per-field)
-- ℹ️ Nested union access uses getter caching (slight behavior difference from Python)
-- ℹ️ Struct property access via `.toObject()` instead of direct field access (performance optimization)
+- ℹ️ Struct property access:
+  - **Python-style classes** (`class X extends Structure`): Direct property access (`p.x`, `p.y`) - fully compatible!
+  - **Plain struct definitions** (`struct({...})`): Use `.get()` / `.set()` methods for property access
+- ℹ️ Struct alignment: Platform defaults are used, but `packed: true` option is available for packed structs
 
 ## Examples in Test Suite
 

package/lib/core/Library.js

@@ -0,0 +1,312 @@
+/**
+ * @file Library.js
+ * @module core/Library
+ * @description Library loading and FFI function wrapping for CDLL and WinDLL.
+ *
+ * This module provides the core library loading functionality including:
+ * - FunctionWrapper for Python-like function attribute syntax
+ * - CDLL class for loading C libraries (cdecl calling convention)
+ * - WinDLL class for loading Windows libraries (stdcall calling convention)
+ *
+ * **Python ctypes Compatibility**:
+ * - `CDLL` ≈ Python's `ctypes.CDLL`
+ * - `WinDLL` ≈ Python's `ctypes.WinDLL`
+ *
+ * @example Loading a library
+ * ```javascript
+ * import { CDLL } from 'node-ctypes';
+ *
+ * const libc = new CDLL(null); // Load C standard library
+ * const printf = libc.func('printf', c_int, [c_char_p]);
+ * printf('Hello from Node.js!\n');
+ * ```
+ *
+ * @example Python-like syntax
+ * ```javascript
+ * const libc = new CDLL(null);
+ * const abs = libc.abs;
+ * abs.argtypes = [c_int];
+ * abs.restype = c_int;
+ * console.log(abs(-42)); // 42
+ * ```
+ *
+ * @example Windows DLL
+ * ```javascript
+ * import { WinDLL } from 'node-ctypes';
+ *
+ * const user32 = new WinDLL('user32.dll');
+ * const MessageBoxW = user32.func('MessageBoxW', c_int, [c_void_p, c_wchar_p, c_wchar_p, c_uint]);
+ * ```
+ */
+
+/**
+ * Creates the Library-related classes with required dependencies injected.
+ *
+ * @param {Class} Library - Native Library class
+ * @param {Class} LRUCache - LRU cache class
+ * @param {Function} _toNativeType - Type conversion function
+ * @param {Function} _toNativeTypes - Type array conversion function
+ * @param {Object} native - Native module reference
+ * @returns {Object} Object containing FunctionWrapper, CDLL, WinDLL classes
+ * @private
+ */
+export function createLibraryClasses(Library, LRUCache, _toNativeType, _toNativeTypes, native) {
+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;
+        }
+        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;
+      },
+    });
+  }
+}
+
+/**
+ * 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 {string|CType} returnType - Tipo di ritorno
+   * @param {Array<string|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(",")}`;
+
+    if (this._cache.has(cacheKey)) {
+      return this._cache.get(cacheKey);
+    }
+
+    const ffiFunc = this._lib.func(name, _toNativeType(returnType, native), _toNativeTypes(argTypes, native), options);
+
+    // =========================================================================
+    // OPTIMIZATION: Create specialized wrapper based on argument types
+    // For primitive-only args, bypass the processing loop entirely
+    // =========================================================================
+
+    const argCount = argTypes.length;
+
+    // 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 !== "pointer" && typeName !== "char_p" && typeName !== "wchar_p";
+      }
+      if (typeof t === "string") {
+        return t !== "pointer" && t !== "char_p" && t !== "wchar_p" && t !== "void_p";
+      }
+      // CType objects from native - check if it's a pointer type
+      if (t && typeof t === "object" && t.name) {
+        return !t.name.includes("pointer") && !t.name.includes("char_p");
+      }
+      return false;
+    });
+
+    let callMethod;
+
+    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 = [];
+
+        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);
+      };
+    }
+
+    // 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);
+        },
+        enumerable: false,
+        configurable: true,
+      },
+    });
+
+    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);
+  }
+
+  /**
+   * Crea un callback JS chiamabile da C
+   * @param {Function} fn - Funzione JavaScript
+   * @param {string|CType} returnType - Tipo di ritorno
+   * @param {Array<string|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();
+  }
+
+  get path() {
+    return this._lib.path;
+  }
+
+  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,
+    });
+  }
+}
+
+  return { FunctionWrapper, CDLL, WinDLL };
+}

package/lib/core/callback.js

@@ -0,0 +1,275 @@
+/**
+ * @file callback.js
+ * @module core/callback
+ * @description Callback wrapper functions for creating C-callable JavaScript functions.
+ *
+ * This module provides two types of callbacks for different threading scenarios:
+ * 1. **callback()**: Fast, main-thread-only callbacks (e.g., qsort, EnumWindows)
+ * 2. **threadSafeCallback()**: Thread-safe callbacks for external threads (e.g., CreateThread)
+ *
+ * **Python ctypes Compatibility**:
+ * Equivalent to Python's `ctypes.CFUNCTYPE` and `ctypes.WINFUNCTYPE`.
+ *
+ * @example Main-thread callback (fast)
+ * ```javascript
+ * import { callback, c_int } from 'node-ctypes';
+ *
+ * // Comparison function for qsort
+ * const compareInts = callback(
+ *   (a, b) => {
+ *     const aVal = a.readInt32LE(0);
+ *     const bVal = b.readInt32LE(0);
+ *     return aVal - bVal;
+ *   },
+ *   c_int,      // return type
+ *   [c_void_p, c_void_p]  // arg types
+ * );
+ *
+ * // Use callback.pointer to pass to C
+ * libc.func('qsort', c_void, [c_void_p, c_size_t, c_size_t, c_void_p])
+ *     (arrayBuf, count, sizeof(c_int), compareInts.pointer);
+ *
+ * // CRITICAL: Release when done to prevent memory leak
+ * compareInts.release();
+ * ```
+ *
+ * @example Thread-safe callback (for external threads)
+ * ```javascript
+ * import { threadSafeCallback, c_int, c_void_p } from 'node-ctypes';
+ *
+ * // Callback that will be called from a C thread pool
+ * const threadWorker = threadSafeCallback(
+ *   (dataPtr) => {
+ *     console.log('Called from C thread!');
+ *     return 0;
+ *   },
+ *   c_int,
+ *   [c_void_p]
+ * );
+ *
+ * // Pass to CreateThread or similar
+ * kernel32.func('CreateThread', c_void_p, [...])
+ *           (null, 0, threadWorker.pointer, null, 0, null);
+ *
+ * // Release when done
+ * threadWorker.release();
+ * ```
+ */
+
+import { _toNativeType, _toNativeTypes } from "./types.js";
+
+/**
+ * Creates a C-callable callback from a JavaScript function (main-thread only).
+ *
+ * This callback is optimized for performance with minimal overhead, but it **MUST**
+ * only be called from Node.js's main thread. Use this for standard C APIs that
+ * invoke callbacks synchronously on the same thread (e.g., qsort, bsearch,
+ * EnumWindows, etc.).
+ *
+ * **When to Use**:
+ * - Callbacks invoked by C functions on the same thread (qsort, bsearch, etc.)
+ * - Synchronous callbacks in event loops (Windows message processing)
+ * - Callbacks that don't involve threading
+ *
+ * **When NOT to Use**:
+ * - Callbacks invoked from external threads (CreateThread, pthread_create)
+ * - Asynchronous callbacks from thread pools
+ * - Any callback that might be called from a non-Node.js thread
+ * → Use `threadSafeCallback()` instead
+ *
+ * **Python ctypes Compatibility**:
+ * Equivalent to Python's `ctypes.CFUNCTYPE(restype, *argtypes)`.
+ *
+ * **Memory Management**:
+ * - Callbacks must be manually released by calling `.release()` when done
+ * - Failing to release callbacks will leak native memory
+ * - Keep a reference to the callback object while it's in use to prevent GC
+ *
+ * @param {Function} fn - JavaScript function to wrap
+ *   The function will receive converted arguments based on argTypes
+ * @param {Function|Object} returnType - Return type (SimpleCData class or CType)
+ * @param {Array<Function|Object>} argTypes - Argument types array
+ * @param {Object} native - Native module reference (internal use)
+ * @returns {Object} Callback wrapper with properties:
+ *   - `pointer` (BigInt): Function pointer to pass to C
+ *   - `release()`: Release native resources (MUST be called)
+ *   - `_callback`: Internal callback object
+ *
+ * @example Basic callback usage
+ * ```javascript
+ * import { CDLL, callback, c_int, c_char_p } from 'node-ctypes';
+ *
+ * const libc = new CDLL(null);
+ *
+ * // Create callback for qsort comparison
+ * const compare = callback(
+ *   (aPtr, bPtr) => {
+ *     const a = aPtr.readInt32LE(0);
+ *     const b = bPtr.readInt32LE(0);
+ *     return a - b;
+ *   },
+ *   c_int,
+ *   [c_void_p, c_void_p]
+ * );
+ *
+ * // Sort array of integers
+ * const arr = Buffer.from([5, 2, 8, 1].flatMap(n => [n, 0, 0, 0]));
+ * const qsort = libc.func('qsort', c_void, [c_void_p, c_size_t, c_size_t, c_void_p]);
+ * qsort(arr, 4, 4, compare.pointer);
+ *
+ * console.log([...arr].filter((_, i) => i % 4 === 0)); // [1, 2, 5, 8]
+ *
+ * // CRITICAL: Release callback
+ * compare.release();
+ * ```
+ *
+ * @example Windows API callback
+ * ```javascript
+ * import { WinDLL, callback, c_bool, c_void_p } from 'node-ctypes';
+ *
+ * const user32 = new WinDLL('user32.dll');
+ *
+ * // EnumWindows callback
+ * const windowList = [];
+ * const enumProc = callback(
+ *   (hwnd, lParam) => {
+ *     windowList.push(hwnd);
+ *     return 1; // Continue enumeration
+ *   },
+ *   c_bool,
+ *   [c_void_p, c_void_p]
+ * );
+ *
+ * user32.func('EnumWindows', c_bool, [c_void_p, c_void_p])
+ *       (enumProc.pointer, 0n);
+ *
+ * console.log(`Found ${windowList.length} windows`);
+ * enumProc.release();
+ * ```
+ *
+ * @throws {Error} If callback creation fails or type conversion fails
+ * @see {@link threadSafeCallback} for thread-safe callbacks
+ */
+export function callback(fn, returnType, argTypes = [], native) {
+  const cb = new native.Callback(fn, _toNativeType(returnType, native), _toNativeTypes(argTypes, native));
+
+  return {
+    get pointer() {
+      return cb.pointer;
+    },
+    release() {
+      cb.release();
+    },
+    _callback: cb,
+  };
+}
+
+/**
+ * Creates a thread-safe C-callable callback from a JavaScript function.
+ *
+ * This callback can be invoked from **any thread**, including threads created
+ * by C code (e.g., CreateThread, pthread_create, thread pools). It uses Node.js's
+ * thread-safe function mechanism to safely execute JavaScript on the main thread.
+ *
+ * **Performance Trade-off**:
+ * - Thread-safe callbacks have higher overhead than regular callbacks
+ * - They involve cross-thread synchronization and event loop scheduling
+ * - Use regular `callback()` if you know the callback is main-thread-only
+ *
+ * **When to Use**:
+ * - Callbacks invoked from C threads (CreateThread, pthread_create)
+ * - Asynchronous callbacks from thread pools
+ * - Any callback where you're unsure about the calling thread
+ *
+ * **When NOT to Use**:
+ * - Main-thread-only callbacks (qsort, bsearch, etc.)
+ * → Use `callback()` instead for better performance
+ *
+ * **Python ctypes Compatibility**:
+ * Python's ctypes doesn't distinguish between thread-safe and regular callbacks.
+ * This is a Node.js-specific requirement due to V8's threading model.
+ *
+ * **Memory Management**:
+ * - Must be manually released by calling `.release()` when done
+ * - Failing to release will leak native memory
+ * - Keep a reference while in use to prevent GC
+ *
+ * @param {Function} fn - JavaScript function to wrap
+ *   The function will be executed on Node.js's main thread regardless of
+ *   which thread invokes the callback
+ * @param {Function|Object} returnType - Return type (SimpleCData class or CType)
+ * @param {Array<Function|Object>} argTypes - Argument types array
+ * @param {Object} native - Native module reference (internal use)
+ * @returns {Object} Callback wrapper with properties:
+ *   - `pointer` (BigInt): Function pointer to pass to C
+ *   - `release()`: Release native resources (MUST be called)
+ *   - `_callback`: Internal callback object
+ *
+ * @example Windows thread callback
+ * ```javascript
+ * import { WinDLL, threadSafeCallback, c_int, c_void_p } from 'node-ctypes';
+ *
+ * const kernel32 = new WinDLL('kernel32.dll');
+ *
+ * // Thread function that will run in a C thread
+ * const threadFunc = threadSafeCallback(
+ *   (param) => {
+ *     console.log('Running in C thread, but executed on Node.js main thread');
+ *     return 0;
+ *   },
+ *   c_int,
+ *   [c_void_p]
+ * );
+ *
+ * // Create Windows thread
+ * const CreateThread = kernel32.func('CreateThread', c_void_p,
+ *   [c_void_p, c_size_t, c_void_p, c_void_p, c_uint32, c_void_p]);
+ *
+ * const threadHandle = CreateThread(null, 0, threadFunc.pointer, null, 0, null);
+ *
+ * // Wait for thread to finish...
+ * // Then release callback
+ * threadFunc.release();
+ * ```
+ *
+ * @example POSIX thread callback
+ * ```javascript
+ * import { CDLL, threadSafeCallback, c_void_p } from 'node-ctypes';
+ *
+ * const pthread = new CDLL('libpthread.so.0');
+ *
+ * const threadFunc = threadSafeCallback(
+ *   (arg) => {
+ *     console.log('POSIX thread callback');
+ *     return null;
+ *   },
+ *   c_void_p,
+ *   [c_void_p]
+ * );
+ *
+ * const pthread_create = pthread.func('pthread_create', c_int,
+ *   [c_void_p, c_void_p, c_void_p, c_void_p]);
+ *
+ * const tidBuf = Buffer.alloc(8);
+ * pthread_create(tidBuf, null, threadFunc.pointer, null);
+ *
+ * // Wait for thread...
+ * threadFunc.release();
+ * ```
+ *
+ * @throws {Error} If callback creation fails or type conversion fails
+ * @see {@link callback} for main-thread-only callbacks
+ */
+export function threadSafeCallback(fn, returnType, argTypes = [], native) {
+  const cb = new native.ThreadSafeCallback(fn, _toNativeType(returnType, native), _toNativeTypes(argTypes, native));
+
+  return {
+    get pointer() {
+      return cb.pointer;
+    },
+    release() {
+      cb.release();
+    },
+    _callback: cb,
+  };
+}