node-ctypes 1.1.0 → 1.3.0

package/lib/memory/pointer.js

@@ -56,8 +56,7 @@ export function addressOf(ptr, alloc, native) {
   if (Buffer.isBuffer(ptr)) {
     // Get the buffer's memory address
     const tempBuf = alloc(native.POINTER_SIZE);
-    // Use native.writeValue with string 'pointer' to avoid JS-level recursion
-    native.writeValue(tempBuf, "pointer", ptr, 0);
+    native.writeValue(tempBuf, native.CType.POINTER, ptr, 0);
     if (native.POINTER_SIZE === 8) return tempBuf.readBigUInt64LE(0);
     return BigInt(tempBuf.readUInt32LE(0));
   }
@@ -290,54 +289,225 @@ export function POINTER(baseType, sizeof, alloc, readValue, writeValue, c_void_p
   const baseSize = typeof baseType === "object" ? baseType.size : sizeof(baseType);
   const typeName = typeof baseType === "object" ? "struct" : baseType._type || "unknown";
 
-  return {
+  /**
+   * Helper to get buffer's memory address using native writeValue
+   */
+  function getBufferAddress(buf) {
+    const tempBuf = alloc(native.POINTER_SIZE);
+    native.writeValue(tempBuf, native.CType.POINTER, buf, 0);
+    if (native.POINTER_SIZE === 8) return tempBuf.readBigUInt64LE(0);
+    return BigInt(tempBuf.readUInt32LE(0));
+  }
+
+  /**
+   * Creates a pointer instance with Python ctypes-compatible API.
+   * Supports .contents property and [index] access for pointer arithmetic.
+   */
+  function createPointerInstance(addressOrBuffer) {
+    let _address = 0n;
+    let _buffer = null;
+
+    if (addressOrBuffer === undefined || addressOrBuffer === null) {
+      _address = 0n;
+    } else if (typeof addressOrBuffer === "bigint") {
+      _address = addressOrBuffer;
+    } else if (typeof addressOrBuffer === "number") {
+      _address = BigInt(addressOrBuffer);
+    } else if (Buffer.isBuffer(addressOrBuffer)) {
+      // This is a buffer we're pointing TO
+      _buffer = addressOrBuffer;
+      _address = getBufferAddress(addressOrBuffer);
+    }
+
+    const instance = {
+      _pointerType: PointerType,
+      _baseType: baseType,
+      _baseSize: baseSize,
+
+      /**
+       * Get the raw address as BigInt
+       */
+      get address() {
+        return _address;
+      },
+
+      /**
+       * Python ctypes compatible: get/set the value at the pointed location.
+       * In Python: p.contents returns the dereferenced value.
+       */
+      get contents() {
+        if (_address === 0n && !_buffer) {
+          throw new Error("NULL pointer access");
+        }
+        if (_buffer) {
+          // We have the actual buffer, read from it
+          return readValue(_buffer, baseType, 0);
+        }
+        // We only have address - need native support to read
+        const buf = native.ptrToBuffer(_address, baseSize);
+        return readValue(buf, baseType, 0);
+      },
+
+      set contents(value) {
+        if (_address === 0n && !_buffer) {
+          throw new Error("NULL pointer access");
+        }
+        if (_buffer) {
+          writeValue(_buffer, baseType, value, 0);
+        } else {
+          const buf = native.ptrToBuffer(_address, baseSize);
+          writeValue(buf, baseType, value, 0);
+        }
+      },
+
+      /**
+       * Returns the buffer this pointer points to (if available)
+       */
+      get _buffer() {
+        return _buffer;
+      },
+
+      /**
+       * Dereference - alias for contents getter
+       */
+      deref() {
+        return this.contents;
+      },
+
+      /**
+       * Set pointer to point to a new address/buffer
+       */
+      set(value) {
+        if (Buffer.isBuffer(value)) {
+          _buffer = value;
+          _address = getBufferAddress(value);
+        } else if (typeof value === "bigint") {
+          _address = value;
+          _buffer = null;
+        } else if (typeof value === "number") {
+          _address = BigInt(value);
+          _buffer = null;
+        }
+      },
+
+      /**
+       * Check if pointer is NULL
+       */
+      get isNull() {
+        return _address === 0n && !_buffer;
+      },
+
+      /**
+       * For compatibility - get pointer as buffer (8 bytes containing address)
+       */
+      toBuffer() {
+        const buf = alloc(native.POINTER_SIZE);
+        writeValue(buf, c_void_p, _address);
+        return buf;
+      },
+
+      toString() {
+        return `<${typeName} pointer at 0x${_address.toString(16)}>`;
+      },
+    };
+
+    // Use Proxy for [index] access (pointer arithmetic)
+    return new Proxy(instance, {
+      get(target, prop, receiver) {
+        // Numeric index access: p[0], p[1], etc.
+        if (typeof prop === "string" && /^\d+$/.test(prop)) {
+          const index = parseInt(prop, 10);
+          if (target.isNull) {
+            throw new Error("NULL pointer access");
+          }
+          const offset = index * baseSize;
+          if (_buffer && offset + baseSize <= _buffer.length) {
+            return readValue(_buffer, baseType, offset);
+          }
+          // Use native to read at address + offset
+          const addr = _address + BigInt(offset);
+          const buf = native.ptrToBuffer(addr, baseSize);
+          return readValue(buf, baseType, 0);
+        }
+        return Reflect.get(target, prop, receiver);
+      },
+
+      set(target, prop, value, receiver) {
+        // Numeric index access: p[0] = value, p[1] = value, etc.
+        if (typeof prop === "string" && /^\d+$/.test(prop)) {
+          const index = parseInt(prop, 10);
+          if (target.isNull) {
+            throw new Error("NULL pointer access");
+          }
+          const offset = index * baseSize;
+          if (_buffer && offset + baseSize <= _buffer.length) {
+            writeValue(_buffer, baseType, value, offset);
+            return true;
+          }
+          // Use native to write at address + offset
+          const addr = _address + BigInt(offset);
+          const buf = native.ptrToBuffer(addr, baseSize);
+          writeValue(buf, baseType, value, 0);
+          return true;
+        }
+        return Reflect.set(target, prop, value, receiver);
+      },
+    });
+  }
+
+  /**
+   * Pointer type factory - creates pointer instances
+   */
+  const PointerType = {
     _pointerTo: baseType,
     _baseSize: baseSize,
     size: native.POINTER_SIZE,
 
     /**
-     * Creates a NULL pointer.
-     * @returns {Buffer} Buffer containing NULL pointer
+     * Creates a new pointer instance.
+     * @param {Buffer|bigint|number} [value] - Initial value (buffer to point to, or address)
+     * @returns {Object} Pointer instance with .contents and [index] access
      */
-    create() {
-      const buf = alloc(native.POINTER_SIZE);
-      writeValue(buf, c_void_p, 0n);
-      return buf;
+    create(value) {
+      return createPointerInstance(value);
     },
 
     /**
-     * Creates a pointer to an existing buffer.
-     * @param {Buffer} targetBuf - Target buffer to point to
-     * @returns {Buffer} Buffer containing pointer to targetBuf
+     * Creates a pointer from an existing buffer (points to that buffer).
+     * @param {Buffer} targetBuf - Buffer to point to
+     * @returns {Object} Pointer instance
      */
     fromBuffer(targetBuf) {
-      const buf = alloc(native.POINTER_SIZE);
-      writeValue(buf, c_void_p, targetBuf);
-      return buf;
+      return createPointerInstance(targetBuf);
+    },
+
+    /**
+     * Creates a pointer from a raw address.
+     * @param {bigint|number} address - Memory address
+     * @returns {Object} Pointer instance
+     */
+    fromAddress(address) {
+      return createPointerInstance(typeof address === "bigint" ? address : BigInt(address));
     },
 
     /**
-     * Dereferences the pointer (reads the address it points to).
-     * @param {Buffer} ptrBuf - Buffer containing the pointer
-     * @returns {bigint|null} Address value, or null if NULL pointer
+     * Legacy API: Dereferences a pointer buffer.
+     * @deprecated Use pointer instance .contents instead
      */
     deref(ptrBuf) {
       const addr = readValue(ptrBuf, c_void_p);
       if (addr === 0n || addr === null) {
         return null;
       }
-      // For struct types, return address (can't safely create buffer without native support)
       if (typeof baseType === "object" && baseType.toObject) {
         return addr;
       }
-      // For primitive types, return address
       return addr;
     },
 
     /**
-     * Sets the pointer to point to a value or buffer.
-     * @param {Buffer} ptrBuf - Buffer containing the pointer
-     * @param {Buffer|bigint|number} value - Value to set (buffer or address)
+     * Legacy API: Sets pointer buffer value.
+     * @deprecated Use pointer instance .set() instead
      */
     set(ptrBuf, value) {
       if (Buffer.isBuffer(value)) {
@@ -347,12 +517,59 @@ export function POINTER(baseType, sizeof, alloc, readValue, writeValue, c_void_p
       }
     },
 
-    /**
-     * Returns string representation of pointer type.
-     * @returns {string} Type name
-     */
     toString() {
       return `POINTER(${typeName})`;
     },
   };
+
+  return PointerType;
+}
+
+/**
+ * Creates a pointer to an existing ctypes object.
+ * Python ctypes compatible: pointer(obj) returns a pointer to obj.
+ *
+ * @param {Object} obj - Object to create pointer to (must have ._buffer or be a Buffer)
+ * @param {Function} POINTER_fn - POINTER function reference
+ * @param {Function} sizeof - sizeof function reference
+ * @param {Function} alloc - alloc function reference
+ * @param {Function} readValue - readValue function reference
+ * @param {Function} writeValue - writeValue function reference
+ * @param {Function} c_void_p - c_void_p type reference
+ * @param {Object} native - Native module reference
+ * @returns {Object} Pointer instance pointing to obj
+ *
+ * @example
+ * ```javascript
+ * const x = new c_int32(42);
+ * const p = pointer(x);
+ * console.log(p.contents); // 42
+ * p.contents = 100;
+ * console.log(x.value); // 100
+ * ```
+ */
+export function pointer(obj, POINTER_fn, sizeof, alloc, readValue, writeValue, c_void_p, native) {
+  let targetBuffer;
+  let baseType;
+
+  if (Buffer.isBuffer(obj)) {
+    targetBuffer = obj;
+    baseType = c_void_p; // Generic pointer
+  } else if (obj && obj._buffer) {
+    // Structure/Union instance or SimpleCData with _buffer
+    targetBuffer = obj._buffer;
+    // Get the base type - use constructor for SimpleCData, _structDef for structures
+    if (obj.constructor && obj.constructor._type) {
+      // SimpleCData instance - use the class itself
+      baseType = obj.constructor;
+    } else {
+      // Structure/Union instance
+      baseType = obj._structDef || obj.__structDef || c_void_p;
+    }
+  } else {
+    throw new TypeError("pointer() argument must be a ctypes instance or Buffer");
+  }
+
+  const PtrType = POINTER_fn(baseType, sizeof, alloc, readValue, writeValue, c_void_p, native);
+  return PtrType.fromBuffer(targetBuffer);
 }