node-ctypes 1.2.0 → 1.3.0

package/README.md

@@ -221,15 +221,15 @@ console.log(u.f);  // 42 reinterpreted as float
 ### Bit Fields - Compact Data Structures
 
 ```javascript
-import { Structure, bitfield, c_uint32 } from 'node-ctypes';
+import { Structure, c_uint32 } from 'node-ctypes';
 
-// Bit fields for flags and compact data
+// Bit fields using Python-style syntax: [name, type, bits]
 class Flags extends Structure {
     static _fields_ = [
-        ["enabled", bitfield(c_uint32, 1)],   // 1 bit
-        ["mode", bitfield(c_uint32, 3)],      // 3 bits
-        ["priority", bitfield(c_uint32, 4)],  // 4 bits
-        ["reserved", bitfield(c_uint32, 24)]  // 24 bits
+        ["enabled", c_uint32, 1],   // 1 bit
+        ["mode", c_uint32, 3],      // 3 bits
+        ["priority", c_uint32, 4],  // 4 bits
+        ["reserved", c_uint32, 24]  // 24 bits
     ];
 }
 
@@ -244,6 +244,19 @@ console.log(flags.mode);      // 5
 console.log(flags.priority);  // 12
 ```
 
+**Alternative syntax with `bitfield()` helper:**
+
+```javascript
+import { Structure, bitfield, c_uint32 } from 'node-ctypes';
+
+class Flags extends Structure {
+    static _fields_ = [
+        ["enabled", bitfield(c_uint32, 1)],
+        ["mode", bitfield(c_uint32, 3)],
+    ];
+}
+```
+
 ### Arrays - Fixed-size and Dynamic
 
 ```javascript
@@ -508,9 +521,33 @@ Benchmarked on Windows with Node.js v24.11.0:
 **Key Insights:**
 - koffi excels at simple operations and struct access
 - node-ctypes competitive on complex argument handling
-- **Struct performance gap**: koffi 15x faster due to direct object manipulation
+- **Struct performance gap**: koffi ~13x faster due to plain object vs Proxy+N-API
+- **Workaround**: Use `toObject()` for repeated struct reads (see below)
 - **Callback overhead**: koffi 1.5x faster at callback creation
 
+### Struct Performance Tip
+
+When reading struct fields repeatedly (e.g., in a tight loop), use `toObject()` to convert to a plain JavaScript object:
+
+```javascript
+const point = Point.create({ x: 10, y: 20 });
+
+// ❌ Slow: Each access goes through Proxy → N-API → buffer read
+for (let i = 0; i < 1000000; i++) {
+  const x = point.x;  // ~80ns per access
+}
+
+// ✅ Fast: Convert once, then use plain object access
+const obj = point.toObject();  // { x: 10, y: 20 }
+for (let i = 0; i < 1000000; i++) {
+  const x = obj.x;  // ~6ns per access (same as koffi!)
+}
+```
+
+**When to use direct access vs toObject():**
+- **Direct access (`point.x`)**: Always synchronized with underlying buffer; required when C code modifies the buffer
+- **`toObject()`**: Snapshot copy; use for read-only loops or when passing data to JS-only code
+
 **Transparent API overhead**: Only **3.5%** for auto `._buffer` extraction!
 
 *See `tests/benchmarks/` for full benchmark suite.*
@@ -623,7 +660,8 @@ puts(s);
 
 **Types and helpers**
 - `sizeof(type)` → `number` : size in bytes of a type.
-- `POINTER(baseType)` : creates a pointer type with helpers `create()`, `fromBuffer()`, `deref()`, `set()`.
+- `POINTER(baseType)` : creates a pointer type factory (see [POINTER and pointer() API](#pointer-and-pointer-api) below).
+- `pointer(obj)` : creates a pointer to an existing ctypes instance (Python-compatible).
 - `byref(buffer)` : passes a buffer by reference (Python ctypes compatibility).
 - `cast(ptr, targetType)` : interprets a pointer as another type (returns wrapper for struct).
 
@@ -700,6 +738,82 @@ Write a value to memory.
 #### `sizeof(type)` → `number`
 Get the size of a type in bytes.
 
+#### POINTER and pointer() API
+
+`node-ctypes` provides a Python ctypes-compatible pointer API:
+
+```javascript
+import { POINTER, pointer, c_int32, Structure } from 'node-ctypes';
+
+// Create a pointer type
+const IntPtr = POINTER(c_int32);
+
+// Create NULL pointer
+const p1 = IntPtr.create();
+console.log(p1.isNull); // true
+
+// Create pointer from buffer
+const buf = Buffer.alloc(12);
+buf.writeInt32LE(10, 0);
+buf.writeInt32LE(20, 4);
+buf.writeInt32LE(30, 8);
+
+const p2 = IntPtr.fromBuffer(buf);
+
+// .contents property (Python-compatible)
+console.log(p2.contents); // 10
+p2.contents = 100;
+console.log(buf.readInt32LE(0)); // 100
+
+// Pointer indexing (Python-compatible)
+console.log(p2[0]); // 100
+console.log(p2[1]); // 20
+console.log(p2[2]); // 30
+
+p2[1] = 200;
+console.log(buf.readInt32LE(4)); // 200
+
+// pointer() function - create pointer to existing object
+const x = new c_int32(42);
+const px = pointer(x);
+console.log(px.contents); // 42
+px.contents = 100;
+console.log(x.value); // 100
+
+// Works with structures too
+class Point extends Structure {
+  static _fields_ = [["x", c_int32], ["y", c_int32]];
+}
+const pt = new Point({ x: 10, y: 20 });
+const ppt = pointer(pt);
+```
+
+**POINTER type methods:**
+- `POINTER(baseType)` - creates a pointer type factory
+- `PointerType.create()` - creates a NULL pointer instance
+- `PointerType.fromBuffer(buf)` - creates pointer to buffer
+- `PointerType.fromAddress(addr)` - creates pointer from address
+
+**Pointer instance properties:**
+- `.contents` - get/set dereferenced value (Python-compatible)
+- `.address` - get raw address as BigInt
+- `.isNull` - check if pointer is NULL
+- `[n]` - array-style indexing with pointer arithmetic
+- `.deref()` - alias for `.contents` getter
+- `.set(value)` - update pointer target
+
+**Using POINTER in function definitions:**
+```javascript
+// POINTER types can be used as argtypes and restype
+const IntPtr = POINTER(c_int32);
+
+// As argument type
+const memset = msvcrt.func("memset", c_void_p, [IntPtr, c_int32, c_size_t]);
+
+// As return type
+const memchr = msvcrt.func("memchr", IntPtr, [c_void_p, c_int32, c_size_t]);
+```
+
 #### `struct(fields)` → `StructDefinition`
 Create a simple struct definition.
 
@@ -720,10 +834,11 @@ Base class for Python-like union definitions. Subclasses should define `static _
 | **Structs** | `class Point(Structure):`<br>&nbsp;&nbsp;`_fields_ = [("x", c_int)]` | `class Point extends Structure`<br>&nbsp;&nbsp;`{ static _fields_ = [["x", c_int]] }` |
 | **Unions** | `class U(Union):`<br>&nbsp;&nbsp;`_fields_ = [("i", c_int)]` | `class U extends Union`<br>&nbsp;&nbsp;`{ static _fields_ = [["i", c_int]] }` |
 | **Arrays** | `c_int * 5` | `array(c_int, 5)` |
-| **Bit fields** | `("flags", c_uint, 3)` | `bitfield(c_uint32, 3)` |
+| **Bit fields** | `("flags", c_uint, 3)` | `["flags", c_uint32, 3]`<br>**or** `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>`new c_char_p(b"hello")` |
-| **Pointers** | `POINTER(c_int)` | `c_void_p` |
+| **Pointers** | `POINTER(c_int)`<br>`p.contents`<br>`p[0]` | `POINTER(c_int)`<br>`p.contents`<br>`p[0]` |
+| **pointer()** | `pointer(obj)` | `pointer(obj)` |
 | **Variadic** | `sprintf(buf, b"%d", 42)` | `sprintf(buf, fmt, 42)` (auto) |
 | **Sizeof** | `sizeof(c_int)` | `sizeof(c_int)` |
 

package/lib/core/Library.js

@@ -51,255 +51,263 @@
  * @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) {
-            if (restype === undefined) {
-              throw new Error(`Function ${name}: restype not set`);
+        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 = cdll.func(name, restype, argtypes);
+            cachedFunc.errcheck = value;
+            return true;
           }
-          cachedFunc.errcheck = value;
+          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
-              processedArgs.push(arg);
+      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 {
-              // Other object, pass as-is
+              // Primitive value (number, string, bigint, null, undefined)
               processedArgs.push(arg);
             }
-          } else {
-            // Primitive value (number, string, bigint, null, undefined)
-            processedArgs.push(arg);
           }
-        }
 
-        return ffiFunc.call(...processedArgs);
-      };
-    }
+          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);
+      // 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,
         },
-        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 };
 }