node-ctypes 1.5.0 → 1.7.0

package/lib/index.js

@@ -207,6 +207,27 @@ function sizeof(type) {
   return _sizeof(type, Structure, Union);
 }
 
+function alignment(type) {
+  // Structure/Union class
+  if (typeof type === "function" && (type.prototype instanceof Structure || type.prototype instanceof Union)) {
+    const def = type._structDef || type._unionDef || type._buildStruct?.() || type._buildUnion?.();
+    return def ? def.alignment : 1;
+  }
+  // StructDef / UnionDef object
+  if (typeof type === "object" && type !== null && type._isStructType && type.alignment !== undefined) {
+    return type.alignment;
+  }
+  // ArrayTypeDef
+  if (typeof type === "object" && type !== null && type._isArrayType) {
+    return type.getAlignment();
+  }
+  // SimpleCData class — natural alignment = min(size, POINTER_SIZE)
+  if (typeof type === "function" && type._isSimpleCData) {
+    return Math.min(type._size, native.POINTER_SIZE);
+  }
+  throw new TypeError("alignment() argument must be a ctypes type");
+}
+
 // ============================================================================
 // Pointer Operations
 // Now imported from ./memory/pointer.js - see that file for implementation details
@@ -425,6 +446,7 @@ const {
   c_char_p,
   c_wchar_p,
   c_size_t,
+  c_ssize_t,
   c_long,
   c_ulong,
   c_byte,
@@ -505,6 +527,7 @@ export {
   readValue,
   writeValue,
   sizeof,
+  alignment,
   ptrToBuffer,
 
   // Strutture
@@ -560,6 +583,7 @@ export {
   c_void_p,
   c_bool,
   c_size_t,
+  c_ssize_t,
   c_long,
   c_ulong,
   // Python-compatible aliases

package/lib/memory/pointer.js

@@ -173,6 +173,39 @@ export function cast(ptr, targetType, readValue, sizeof, ptrToBuffer) {
     throw new TypeError("cast() requires a target type");
   }
 
+  // PointerTypeDef — return a PointerInstance via fromAddress()
+  // Python equivalent: cast(c_void_p(addr), POINTER(MyStruct))
+  if (typeof targetType === "object" && targetType._pointerTo !== undefined) {
+    let addr;
+    if (typeof ptr === "bigint") {
+      addr = ptr;
+    } else if (typeof ptr === "number") {
+      addr = BigInt(ptr);
+    } else if (Buffer.isBuffer(ptr)) {
+      // Read the pointer value from the buffer
+      if (ptr.length >= 8) {
+        addr = ptr.readBigUInt64LE(0);
+      } else if (ptr.length >= 4) {
+        addr = BigInt(ptr.readUInt32LE(0));
+      } else {
+        throw new TypeError("cast(): buffer too small to contain a pointer");
+      }
+    } else if (ptr && ptr._buffer) {
+      // SimpleCData instance (e.g., c_void_p)
+      const buf = ptr._buffer;
+      if (buf.length >= 8) {
+        addr = buf.readBigUInt64LE(0);
+      } else if (buf.length >= 4) {
+        addr = BigInt(buf.readUInt32LE(0));
+      } else {
+        throw new TypeError("cast(): buffer too small to contain a pointer");
+      }
+    } else {
+      throw new TypeError("cast(): ptr must be a BigInt, number, Buffer, or ctypes instance");
+    }
+    return targetType.fromAddress(addr);
+  }
+
   // Struct type - return wrapper object
   if (typeof targetType === "object" && targetType.size !== undefined) {
     const buf = Buffer.isBuffer(ptr) ? ptr : ptrToBuffer(ptr, targetType.size);

package/lib/structures/helpers/struct.js

@@ -307,6 +307,34 @@ export function struct(fields, options = {}, sizeof, alloc, readValue, writeValu
         maxAlignment = alignment;
       }
     }
+    // Caso 4b: POINTER() type — stored as pointer-sized field with typed access
+    else if (typeof type === "object" && type !== null && type._pointerTo !== undefined) {
+      // Reset bit field state
+      currentBitFieldBase = null;
+      currentBitOffset = 0;
+
+      const size = native.POINTER_SIZE;
+      const alignment = packed ? 1 : Math.min(size, native.POINTER_SIZE);
+
+      if (!packed && totalSize % alignment !== 0) {
+        totalSize += alignment - (totalSize % alignment);
+      }
+
+      fieldDef = {
+        name,
+        type,
+        offset: totalSize,
+        size,
+        alignment,
+        isPointer: true,
+      };
+
+      totalSize += size;
+
+      if (alignment > maxAlignment) {
+        maxAlignment = alignment;
+      }
+    }
     // Caso 4: Tipo base (SimpleCData)
     else {
       // Reset bit field state
@@ -369,6 +397,37 @@ export function struct(fields, options = {}, sizeof, alloc, readValue, writeValu
       continue;
     }
 
+    // POINTER() type field — read returns PointerInstance, write accepts BigInt/PointerInstance
+    if (field.isPointer) {
+      const fieldOffset = offset;
+      const ptrType = field.type;
+      fieldReaders.set(name, (buf) => {
+        const addr = native.POINTER_SIZE === 8 ? buf.readBigUInt64LE(fieldOffset) : BigInt(buf.readUInt32LE(fieldOffset));
+        return ptrType.fromAddress(addr);
+      });
+      fieldWriters.set(name, (buf, val) => {
+        let addr;
+        if (typeof val === "bigint") {
+          addr = val;
+        } else if (typeof val === "number") {
+          addr = BigInt(val);
+        } else if (val && typeof val.address === "bigint") {
+          // PointerInstance
+          addr = val.address;
+        } else if (Buffer.isBuffer(val)) {
+          addr = native.POINTER_SIZE === 8 ? val.readBigUInt64LE(0) : BigInt(val.readUInt32LE(0));
+        } else {
+          addr = 0n;
+        }
+        if (native.POINTER_SIZE === 8) {
+          buf.writeBigUInt64LE(addr, fieldOffset);
+        } else {
+          buf.writeUInt32LE(Number(addr), fieldOffset);
+        }
+      });
+      continue;
+    }
+
     // Pre-compile based on SimpleCData type
     // Use the type's _reader and _writer directly for optimization
     const fieldType = field.type;
@@ -662,6 +721,12 @@ export function struct(fields, options = {}, sizeof, alloc, readValue, writeValu
             : field.type.toObject(nestedBuf);
         }
 
+        // POINTER() field — return PointerInstance
+        if (field.isPointer) {
+          const addr = native.POINTER_SIZE === 8 ? buf.readBigUInt64LE(field.offset) : BigInt(buf.readUInt32LE(field.offset));
+          return field.type.fromAddress(addr);
+        }
+
         // Array field
         if (field.isArray) {
           const arrayBuf = buf.subarray(field.offset, field.offset + field.size);
@@ -748,6 +813,26 @@ export function struct(fields, options = {}, sizeof, alloc, readValue, writeValu
           return;
         }
 
+        // POINTER() field — write address
+        if (field.isPointer) {
+          let addr;
+          if (typeof value === "bigint") {
+            addr = value;
+          } else if (typeof value === "number") {
+            addr = BigInt(value);
+          } else if (value && typeof value.address === "bigint") {
+            addr = value.address;
+          } else {
+            addr = 0n;
+          }
+          if (native.POINTER_SIZE === 8) {
+            buf.writeBigUInt64LE(addr, field.offset);
+          } else {
+            buf.writeUInt32LE(Number(addr), field.offset);
+          }
+          return;
+        }
+
         // Array field
         if (field.isArray) {
           if (Buffer.isBuffer(value)) {
@@ -875,6 +960,9 @@ export function struct(fields, options = {}, sizeof, alloc, readValue, writeValu
           } else {
             result[field.name] = nestedObj;
           }
+        } else if (field.isPointer) {
+          const addr = native.POINTER_SIZE === 8 ? buf.readBigUInt64LE(field.offset) : BigInt(buf.readUInt32LE(field.offset));
+          result[field.name] = field.type.fromAddress(addr);
         } else if (field.isArray) {
           const arrayBuf = buf.subarray(field.offset, field.offset + field.size);
           result[field.name] = field.type.wrap(arrayBuf);

package/lib/structures/helpers/union.js

@@ -123,6 +123,13 @@ export function union(fields, sizeof, alloc, readValue, writeValue, _isStruct, _
       fieldDef.baseSize = type.baseSize;
       fieldDef.type = type.baseType; // Usa il tipo base per lettura/scrittura
     }
+    // POINTER() type
+    else if (typeof type === "object" && type !== null && type._pointerTo !== undefined) {
+      size = native.POINTER_SIZE;
+      alignment = Math.min(size, native.POINTER_SIZE);
+      fieldDef.type = type;
+      fieldDef.isPointer = true;
+    }
     // Tipo base (SimpleCData)
     else {
       // Validate type is a SimpleCData class

package/lib/types/primitives.js

@@ -284,6 +284,21 @@ export function createPrimitiveTypes(SimpleCData, native, addressOf, cstring, ws
     };
   }
 
+  class c_ssize_t extends SimpleCData {
+    static _size = native.POINTER_SIZE;
+    static _type = CType.SSIZE_T;
+    static _reader = (buf, off) => {
+      return native.POINTER_SIZE === 8 ? buf.readBigInt64LE(off) : buf.readInt32LE(off);
+    };
+    static _writer = (buf, off, val) => {
+      if (native.POINTER_SIZE === 8) {
+        buf.writeBigInt64LE(BigInt(val), off);
+      } else {
+        buf.writeInt32LE(Number(val), off);
+      }
+    };
+  }
+
   // Get actual long size from native module (4 on Windows, 4 or 8 on Unix depending on arch)
   const _longSize = native.sizeof ? native.sizeof(CType.LONG) : 4;
 
@@ -408,6 +423,7 @@ export function createPrimitiveTypes(SimpleCData, native, addressOf, cstring, ws
     c_wchar_p,
     // Platform-specific
     c_size_t,
+    c_ssize_t,
     c_long,
     c_ulong,
     // Python-compatible aliases

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "node-ctypes",
-  "version": "1.5.0",
+  "version": "1.7.0",
   "description": "Python ctypes-like FFI for Node.js using libffi",
   "author": "Damiano Mazzella",
   "license": "MIT",
@@ -29,11 +29,15 @@
     "build:debug": "cmake-js compile --target ctypes --debug",
     "rebuild": "cmake-js rebuild --target ctypes",
     "clean": "cmake-js clean",
-    "generate-ffi-headers": "node third-party/libffi_cmake/generate-headers.js"
+    "generate-ffi-headers": "node third-party/libffi_cmake/generate-headers.js",
+    "docs": "typedoc",
+    "docs:serve": "typedoc && npx serve docs"
   },
   "devDependencies": {
+    "@types/node": "^25.3.3",
     "cmake-js": "^8.0.0",
-    "node-addon-api": "^8.5.0"
+    "node-addon-api": "^8.6.0",
+    "typedoc": "^0.28.17"
   },
   "engines": {
     "node": ">=16.0.0"