node-ctypes 1.6.0 → 1.8.0

package/README.md

@@ -119,13 +119,22 @@ const buf = Buffer.alloc(4);
 buf.writeInt32LE(42, 0);
 
 const p = IntPtr.fromBuffer(buf);
-console.log(p.contents);  // 42
-console.log(p[0]);         // 42
+console.log(p.contents);  // 42 (like *p in C)
+console.log(p[0]);        // 42 (like p[0] in C)
 
 // pointer() function
 const x = new c_int32(42);
 const px = pointer(x);
 console.log(px.contents);  // 42
+
+// fromAddress() — typed access to native memory
+const pValues = POINTER(MyStruct).fromAddress(nativeAddr);
+console.log(pValues[0].field);  // pointer arithmetic (like pValues[0] in C)
+console.log(pValues[5].field);  // pValues + 5 * sizeof(MyStruct)
+
+// cast() to POINTER — Python: cast(c_void_p(addr), POINTER(MyStruct))
+const pData = cast(rawAddr, POINTER(MyStruct));
+console.log(pData[0].field);  // same result as fromAddress()
 ```
 
 ### Callbacks
@@ -194,11 +203,12 @@ console.log(`${st.wYear}-${st.wMonth}-${st.wDay}`);
 | Callbacks | `CFUNCTYPE(c_int, c_int)` | `CFUNCTYPE(c_int, c_int)` |
 | Pointers | `POINTER(c_int)` / `pointer(obj)` | `POINTER(c_int)` / `pointer(obj)` |
 | Sizeof | `sizeof(c_int)` | `sizeof(c_int)` |
+| Alignment | `alignment(c_int)` | `alignment(c_int)` |
 | Strings | `c_char_p(b"hello")` | `create_string_buffer("hello")` |
 | Variadic | `sprintf(buf, b"%d", 42)` | `sprintf(buf, "%d", 42)` |
 | Errno | `get_errno()` | `get_errno()` |
 | byref | `byref(obj)` | `byref(obj)` |
-| cast | `cast(ptr, type)` | `cast(ptr, type)` |
+| cast | `cast(ptr, type)` | `cast(ptr, type)` (supports `POINTER()` target) |
 
 ## Supported Types
 
@@ -219,6 +229,7 @@ console.log(`${st.wYear}-${st.wMonth}-${st.wDay}`);
 | `c_wchar_p` | wide string | pointer |
 | `c_bool` | | 1 |
 | `c_size_t` | | platform |
+| `c_ssize_t` | | platform |
 
 ## Key Differences from Python ctypes
 
@@ -233,6 +244,7 @@ console.log(`${st.wYear}-${st.wMonth}-${st.wDay}`);
 - `string_at(address, size)` / `wstring_at(address, size)` — read strings from memory
 - `readValue(ptr, type, offset)` / `writeValue(ptr, type, value, offset)` — direct memory access
 - `sizeof(type)` — type size in bytes
+- `alignment(type)` — type alignment in bytes
 - `addressof(ptr)` — get address as BigInt
 - `memmove(dst, src, count)` / `memset(dst, value, count)` — memory operations
 - `GetLastError()` / `FormatError(code)` — Windows error helpers

package/lib/index.d.ts

@@ -373,7 +373,7 @@ export class ThreadSafeCallback extends Callback {}
  */
 export interface FieldDef {
   name: string;
-  type: AnyType | StructDef | ArrayTypeDef | BitFieldDef;
+  type: AnyType | StructDef | ArrayTypeDef | BitFieldDef | PointerTypeDef;
   offset: number;
   size: number;
   alignment: number;
@@ -419,7 +419,7 @@ export interface StructDef {
 }
 
 /** @category Structures */
-export type FieldSpec = AnyType | StructDef | ArrayTypeDef | BitFieldDef | AnonymousField;
+export type FieldSpec = AnyType | StructDef | ArrayTypeDef | BitFieldDef | AnonymousField | PointerTypeDef;
 
 type JsFromCType<T> = T extends "int64" | "uint64" | "size_t"
   ? bigint
@@ -544,14 +544,109 @@ export interface AnonymousField {
 // Pointers
 // =============================================================================
 
+/**
+ * A pointer instance created by {@link PointerTypeDef.create}, {@link PointerTypeDef.fromBuffer},
+ * or {@link PointerTypeDef.fromAddress}.
+ *
+ * Supports Python ctypes-compatible `.contents` property and C-like `[index]` pointer arithmetic.
+ *
+ * @example
+ * ```javascript
+ * const IntPtr = POINTER(c_int32);
+ * const p = IntPtr.fromBuffer(buf);
+ * console.log(p.contents);  // dereferenced value (like *p in C)
+ * console.log(p[0]);        // same as p.contents
+ * console.log(p[5]);        // pointer arithmetic (like p[5] in C)
+ * ```
+ *
+ * @example Access a native array via pointer from a struct field
+ * ```javascript
+ * // When a struct has a c_void_p field pointing to an array of structs:
+ * const pValues = POINTER(ADSVALUE).fromAddress(col.pADsValues);
+ * for (let i = 0; i < col.dwNumValues; i++) {
+ *   console.log(pValues[i].dwType);  // struct view at pValues + i * sizeof(ADSVALUE)
+ * }
+ * ```
+ *
+ * @category Pointers
+ */
+export interface PointerInstance {
+  /** The pointer type definition this instance was created from. */
+  readonly _pointerType: PointerTypeDef;
+  /** The base type this pointer points to. */
+  readonly _baseType: AnyType | StructDef;
+  /** Size of the pointed-to type in bytes. */
+  readonly _baseSize: number;
+
+  /** Raw memory address as BigInt. */
+  readonly address: bigint;
+
+  /**
+   * Dereference the pointer — read/write the value at the pointed location.
+   *
+   * Python equivalent: `p.contents`
+   *
+   * @example
+   * ```javascript
+   * const p = POINTER(c_int32).fromBuffer(buf);
+   * console.log(p.contents);  // read value
+   * p.contents = 42;          // write value
+   * ```
+   */
+  contents: any;
+
+  /** The underlying buffer (if created from a buffer), or null. */
+  readonly _buffer: Buffer | null;
+
+  /** Alias for contents getter. */
+  deref(): any;
+
+  /**
+   * Set pointer to a new target (buffer or address).
+   * @param value - Buffer to point to, or BigInt/number address
+   */
+  set(value: Buffer | bigint | number): void;
+
+  /** Check if this is a NULL pointer. */
+  readonly isNull: boolean;
+
+  /** Get pointer as an 8-byte buffer containing the address. */
+  toBuffer(): Buffer;
+
+  toString(): string;
+
+  /**
+   * Pointer arithmetic — access elements at offset from the pointer.
+   *
+   * `p[i]` reads `sizeof(baseType)` bytes at `address + i * sizeof(baseType)`,
+   * exactly like C pointer indexing.
+   *
+   * @example
+   * ```javascript
+   * const arr = POINTER(c_int32).fromAddress(arrayAddr);
+   * arr[0]       // first element
+   * arr[5]       // sixth element
+   * arr[2] = 99; // write to third element
+   * ```
+   */
+  [index: number]: any;
+}
+
 /**
  * A pointer type created by {@link POINTER}.
  *
  * @example
  * ```javascript
  * const IntPtr = POINTER(c_int32);
+ *
+ * // From existing buffer
  * const p = IntPtr.fromBuffer(buf);
- * console.log(p.contents);  // dereferenced value
+ * console.log(p.contents);  // 42
+ * console.log(p[0]);        // 42
+ *
+ * // From raw address (e.g., from a struct's c_void_p field)
+ * const pValues = POINTER(MyStruct).fromAddress(someStruct.pData);
+ * console.log(pValues[0].field1);
  * ```
  *
  * @category Pointers
@@ -564,14 +659,63 @@ export interface PointerTypeDef {
   /** Pointer size (always 8 on 64-bit). */
   readonly size: number;
 
-  /** Create a NULL pointer. */
-  create(): Buffer;
-  /** Create a pointer to an existing buffer. */
-  fromBuffer(targetBuf: Buffer): Buffer;
-  /** Dereference the pointer, returning the target address or null. */
+  /**
+   * Create a NULL pointer instance.
+   *
+   * @example
+   * ```javascript
+   * const p = POINTER(c_int32).create();
+   * console.log(p.isNull);  // true
+   * ```
+   */
+  create(value?: Buffer | bigint | number): PointerInstance;
+
+  /**
+   * Create a pointer from an existing buffer (points to that buffer's memory).
+   *
+   * @param targetBuf - Buffer to point to
+   *
+   * @example
+   * ```javascript
+   * const buf = Buffer.alloc(4);
+   * buf.writeInt32LE(42, 0);
+   * const p = POINTER(c_int32).fromBuffer(buf);
+   * console.log(p.contents);  // 42
+   * ```
+   */
+  fromBuffer(targetBuf: Buffer): PointerInstance;
+
+  /**
+   * Create a pointer from a raw memory address.
+   *
+   * Use this to create typed access to native memory, especially useful with
+   * `c_void_p` struct fields that point to arrays of structs.
+   *
+   * @param address - Memory address as BigInt or number
+   *
+   * @example
+   * ```javascript
+   * // Access array of structs from a c_void_p field
+   * const pValues = POINTER(ADSVALUE).fromAddress(col.pADsValues);
+   * for (let i = 0; i < col.dwNumValues; i++) {
+   *   console.log(pValues[i].dwType);
+   * }
+   * ```
+   */
+  fromAddress(address: bigint | number): PointerInstance;
+
+  /**
+   * @deprecated Use pointer instance `.contents` instead.
+   * Legacy API: Dereferences a pointer buffer.
+   */
   deref(ptrBuf: Buffer): bigint | null;
-  /** Update the pointer target. */
+
+  /**
+   * @deprecated Use pointer instance `.set()` instead.
+   * Legacy API: Sets pointer buffer value.
+   */
   set(ptrBuf: Buffer, value: Buffer | bigint): void;
+
   toString(): string;
 }
 
@@ -943,6 +1087,22 @@ export function writeValue(ptr: Buffer | bigint | number, type: AnyType, value:
  */
 export function sizeof(type: AnyType | StructDef | ArrayTypeDef): number;
 
+/**
+ * Get the alignment requirement of a type in bytes.
+ *
+ * Python equivalent: `ctypes.alignment`
+ *
+ * @example
+ * ```javascript
+ * alignment(c_int32)    // 4
+ * alignment(c_double)   // 8
+ * alignment(MyStruct)   // max field alignment
+ * ```
+ *
+ * @category Memory
+ */
+export function alignment(type: AnyType | StructDef | ArrayTypeDef | typeof Structure | typeof Union): number;
+
 /**
  * Create a Buffer view of native memory at a given address.
  *
@@ -1059,12 +1219,31 @@ export function byref(obj: Buffer | SimpleCDataInstance | { _buffer: Buffer }):
  *
  * Python equivalent: `ctypes.cast`
  *
- * @param ptr - Buffer or BigInt address to cast
- * @param targetType - The target type
+ * When the target is a {@link PointerTypeDef}, returns a {@link PointerInstance} with
+ * `.contents` and `[index]` access — equivalent to Python's
+ * `cast(c_void_p(addr), POINTER(MyStruct))`.
+ *
+ * @param ptr - Buffer, BigInt address, number, or SimpleCData instance (e.g., `c_void_p`)
+ * @param targetType - The target type (primitive, struct, or POINTER type)
+ *
+ * @example Cast to POINTER for typed array access
+ * ```javascript
+ * // Python: cast(c_void_p(addr), POINTER(MyStruct))
+ * const pValues = cast(col.pADsValues, POINTER(ADSVALUE));
+ * for (let i = 0; i < col.dwNumValues; i++) {
+ *   console.log(pValues[i].dwType);
+ * }
+ * ```
+ *
+ * @example Cast to primitive type
+ * ```javascript
+ * const floatVal = cast(intBuf, c_float);
+ * ```
  *
  * @category Pointers
  */
-export function cast(ptr: Buffer | bigint, targetType: AnyType | StructDef): Buffer | { [key: string]: any };
+export function cast(ptr: Buffer | bigint | number | SimpleCDataInstance, targetType: PointerTypeDef): PointerInstance;
+export function cast(ptr: Buffer | bigint | number | SimpleCDataInstance, targetType: AnyType | StructDef): any;
 
 /**
  * Create a pointer type for a given base type.
@@ -1074,7 +1253,7 @@ export function cast(ptr: Buffer | bigint, targetType: AnyType | StructDef): Buf
  * @param baseType - The type to point to
  * @returns A pointer type with `create()`, `fromBuffer()`, etc.
  *
- * @example
+ * @example Basic pointer
  * ```javascript
  * const IntPtr = POINTER(c_int32);
  * const buf = Buffer.alloc(4);
@@ -1082,7 +1261,20 @@ export function cast(ptr: Buffer | bigint, targetType: AnyType | StructDef): Buf
  *
  * const p = IntPtr.fromBuffer(buf);
  * console.log(p.contents);  // 42
- * console.log(p[0]);         // 42
+ * console.log(p[0]);        // 42
+ * ```
+ *
+ * @example Typed access to native array via c_void_p struct field
+ * ```javascript
+ * // Structure fields don't accept POINTER() types directly — use c_void_p,
+ * // then wrap with POINTER().fromAddress() for typed indexed access:
+ * class Column extends Structure {
+ *   static _fields_ = [["pValues", c_void_p], ["count", c_uint32]];
+ * }
+ * const pValues = POINTER(ValueStruct).fromAddress(col.pValues);
+ * for (let i = 0; i < col.count; i++) {
+ *   console.log(pValues[i].field);  // struct view at offset i
+ * }
  * ```
  *
  * @category Pointers
@@ -1108,7 +1300,7 @@ export function POINTER(baseType: AnyType | StructDef): PointerTypeDef;
  *
  * @category Pointers
  */
-export function pointer(obj: SimpleCDataInstance | { _buffer: Buffer }): SimpleCDataInstance & { contents: any; [index: number]: any };
+export function pointer(obj: SimpleCDataInstance | { _buffer: Buffer }): PointerInstance;
 
 /**
  * Get the C library errno value.
@@ -1264,8 +1456,10 @@ export const c_wchar_p: SimpleCDataConstructor;
 export const c_void_p: SimpleCDataConstructor;
 /** Boolean (1 byte). Python: `ctypes.c_bool` @category Types */
 export const c_bool: SimpleCDataConstructor;
-/** Platform-dependent size type (BigInt). Python: `ctypes.c_size_t` @category Types */
+/** Platform-dependent unsigned size type (BigInt). Python: `ctypes.c_size_t` @category Types */
 export const c_size_t: SimpleCDataConstructor;
+/** Platform-dependent signed size type (BigInt). Python: `ctypes.c_ssize_t` @category Types */
+export const c_ssize_t: SimpleCDataConstructor;
 /** Platform-dependent signed long. Python: `ctypes.c_long` @category Types */
 export const c_long: SimpleCDataConstructor;
 /** Platform-dependent unsigned long. Python: `ctypes.c_ulong` @category Types */

package/lib/index.js

@@ -207,6 +207,36 @@ function sizeof(type) {
   return _sizeof(type, Structure, Union);
 }
 
+function alignment(type) {
+  // Instance of Structure/Union — use _structDef/_unionDef (Python: alignment(instance) works)
+  if (type instanceof Structure || type instanceof Union) {
+    const def = type._structDef || type._unionDef;
+    return def ? def.alignment : 1;
+  }
+  // SimpleCData instance — delegate to class (Python: alignment(c_int32(42)) works)
+  if (typeof type === "object" && type !== null && type.constructor && type.constructor._isSimpleCData) {
+    return alignment(type.constructor);
+  }
+  // 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
@@ -221,7 +251,7 @@ function byref(obj) {
 }
 
 function cast(ptr, targetType) {
-  return _cast(ptr, targetType, readValue, sizeof, ptrToBuffer);
+  return _cast(ptr, targetType, readValue, sizeof, ptrToBuffer, native);
 }
 
 function ptrToBuffer(address, size) {
@@ -425,6 +455,7 @@ const {
   c_char_p,
   c_wchar_p,
   c_size_t,
+  c_ssize_t,
   c_long,
   c_ulong,
   c_byte,
@@ -505,6 +536,7 @@ export {
   readValue,
   writeValue,
   sizeof,
+  alignment,
   ptrToBuffer,
 
   // Strutture
@@ -560,6 +592,7 @@ export {
   c_void_p,
   c_bool,
   c_size_t,
+  c_ssize_t,
   c_long,
   c_ulong,
   // Python-compatible aliases

package/lib/memory/operations.js

@@ -119,6 +119,12 @@ export function readValue(ptr, type, offset = 0, sizeof, ptrToBuffer, Structure,
     return def.toObject(tempBuf);
   }
 
+  // Struct/Union def object (has _isStructType and toObject)
+  if (typeof type === "object" && type !== null && type._isStructType && typeof type.toObject === "function") {
+    const tempBuf = ptr.subarray(offset, offset + type.size);
+    return type.toObject(tempBuf);
+  }
+
   throw new TypeError(`readValue: unsupported type ${type}`);
 }
 
@@ -211,6 +217,19 @@ export function writeValue(ptr, type, value, offset = 0, sizeof, Structure, Unio
     return def.size;
   }
 
+  // Struct/Union def object (has _isStructType and set/fromObject)
+  if (typeof type === "object" && type !== null && type._isStructType && typeof type.set === "function") {
+    const tempBuf = ptr.subarray(offset, offset + type.size);
+    if (Buffer.isBuffer(value)) {
+      value.copy(tempBuf, 0, 0, type.size);
+    } else if (typeof value === "object" && value !== null) {
+      for (const [k, v] of Object.entries(value)) {
+        type.set(tempBuf, k, v);
+      }
+    }
+    return type.size;
+  }
+
   throw new TypeError(`writeValue: unsupported type ${type}`);
 }
 

package/lib/memory/pointer.js

@@ -53,6 +53,10 @@
  * ```
  */
 export function addressOf(ptr, alloc, native) {
+  // If it's an object with _buffer (SimpleCData, Structure, Union, array proxy), use its buffer
+  if (!Buffer.isBuffer(ptr) && ptr && ptr._buffer && Buffer.isBuffer(ptr._buffer)) {
+    ptr = ptr._buffer;
+  }
   if (Buffer.isBuffer(ptr)) {
     // Get the buffer's memory address
     const tempBuf = alloc(native.POINTER_SIZE);
@@ -164,7 +168,7 @@ export function byref(obj) {
  * console.log(header.contents); // { magic: 23117, version: 1 }
  * ```
  */
-export function cast(ptr, targetType, readValue, sizeof, ptrToBuffer) {
+export function cast(ptr, targetType, readValue, sizeof, ptrToBuffer, native) {
   // Validate inputs
   if (!ptr) {
     throw new TypeError("cast() requires a non-null pointer");
@@ -173,6 +177,62 @@ export function cast(ptr, targetType, readValue, sizeof, ptrToBuffer) {
     throw new TypeError("cast() requires a target type");
   }
 
+  // PointerTypeDef — return a PointerInstance via fromAddress() or fromBuffer()
+  // Python equivalent: cast(c_void_p(addr), POINTER(c_int32)) — read stored address
+  // Python equivalent: cast(arr, POINTER(c_int32))  — pointer to arr's memory
+  // Python equivalent: cast(p, POINTER(c_double))   — pointer to same memory as p
+  if (typeof targetType === "object" && targetType._pointerTo !== undefined) {
+    // PointerInstance — use its address/buffer (Python: cast(p, POINTER(OtherType)))
+    if (ptr && typeof ptr === "object" && typeof ptr.address === "bigint") {
+      if (ptr._buffer) {
+        return targetType.fromBuffer(ptr._buffer);
+      }
+      return targetType.fromAddress(ptr.address);
+    }
+
+    // ctypes object with _buffer — distinguish data objects from pointer-value objects
+    // Note: array proxies are Buffer.isBuffer()==true but also have ._buffer, so don't exclude Buffers
+    if (ptr && typeof ptr === "object" && ptr._buffer && Buffer.isBuffer(ptr._buffer)) {
+      // SimpleCData storing a pointer/address value (c_void_p, c_char_p, etc.)
+      // → read the stored address value from the buffer
+      if (ptr.constructor && ptr.constructor._isSimpleCData && ptr.constructor._type === native.CType.POINTER) {
+        // This is a pointer-valued SimpleCData — read address from buffer
+        const buf = ptr._buffer;
+        let addr;
+        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");
+        }
+        return targetType.fromAddress(addr);
+      }
+      // Array, Structure, Union — pointer to their data buffer
+      // Python: cast(arr, POINTER(c_int32)) points to arr's memory
+      return targetType.fromBuffer(ptr._buffer);
+    }
+
+    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 {
+      throw new TypeError("cast(): ptr must be a BigInt, number, Buffer, ctypes instance, or PointerInstance");
+    }
+    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);
@@ -287,7 +347,7 @@ export function ptrToBuffer(address, size, native) {
  */
 export function POINTER(baseType, sizeof, alloc, readValue, writeValue, c_void_p, native) {
   const baseSize = typeof baseType === "object" ? baseType.size : sizeof(baseType);
-  const typeName = typeof baseType === "object" ? "struct" : baseType._type || "unknown";
+  const typeName = typeof baseType === "object" ? "struct" : baseType._type || baseType.name || "unknown";
 
   /**
    * Helper to get buffer's memory address using native writeValue
@@ -558,13 +618,16 @@ export function pointer(obj, POINTER_fn, sizeof, alloc, readValue, writeValue, c
   } 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
+    // Get the base type for POINTER creation
     if (obj.constructor && obj.constructor._type) {
-      // SimpleCData instance - use the class itself
+      // SimpleCData instance - use the class itself (c_int32, c_double, etc.)
       baseType = obj.constructor;
+    } else if (obj._structDef) {
+      // Structure/Union instance - use the struct def object
+      // (obj.constructor is a bound function from Proxy, so we use _structDef directly)
+      baseType = obj._structDef;
     } else {
-      // Structure/Union instance
-      baseType = obj._structDef || obj.__structDef || c_void_p;
+      baseType = c_void_p;
     }
   } else {
     throw new TypeError("pointer() argument must be a ctypes instance or Buffer");

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
@@ -313,6 +320,12 @@ export function union(fields, sizeof, alloc, readValue, writeValue, _isStruct, _
         return field.type.wrap(buf.subarray(field.offset, field.offset + field.size));
       }
 
+      // 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);
+      }
+
       // Tipo base
       return readValue(buf, field.type, field.offset);
     },
@@ -369,6 +382,28 @@ export function union(fields, sizeof, alloc, readValue, writeValue, _isStruct, _
         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 if (Buffer.isBuffer(value)) {
+          addr = native.POINTER_SIZE === 8 ? value.readBigUInt64LE(0) : BigInt(value.readUInt32LE(0));
+        } else {
+          addr = 0n;
+        }
+        if (native.POINTER_SIZE === 8) {
+          buf.writeBigUInt64LE(addr, field.offset);
+        } else {
+          buf.writeUInt32LE(Number(addr), field.offset);
+        }
+        return;
+      }
+
       // Tipo base
       writeValue(buf, field.type, value, field.offset);
     },
@@ -422,6 +457,9 @@ export function union(fields, sizeof, alloc, readValue, writeValue, _isStruct, _
             } else if (field.isArray) {
               const wrapped = field.type.wrap(buf.subarray(0, field.size));
               return [...wrapped];
+            } else if (field.isPointer) {
+              const addr = native.POINTER_SIZE === 8 ? buf.readBigUInt64LE(0) : BigInt(buf.readUInt32LE(0));
+              return field.type.fromAddress(addr);
             } else {
               return readValue(buf, field.type, 0);
             }
@@ -429,6 +467,24 @@ export function union(fields, sizeof, alloc, readValue, writeValue, _isStruct, _
           set(value) {
             if (field.isBitField) {
               _writeBitField(buf, 0, field.type, field.bitOffset, field.bitSize, value, sizeof);
+            } else 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 if (Buffer.isBuffer(value)) {
+                addr = native.POINTER_SIZE === 8 ? value.readBigUInt64LE(0) : BigInt(value.readUInt32LE(0));
+              } else {
+                addr = 0n;
+              }
+              if (native.POINTER_SIZE === 8) {
+                buf.writeBigUInt64LE(addr, 0);
+              } else {
+                buf.writeUInt32LE(Number(addr), 0);
+              }
             } else {
               writeValue(buf, field.type, value, 0);
             }

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.6.0",
+  "version": "1.8.0",
   "description": "Python ctypes-like FFI for Node.js using libffi",
   "author": "Damiano Mazzella",
   "license": "MIT",