node-ctypes 1.2.0 → 1.3.0

package/lib/structures/Structure.js

@@ -69,10 +69,11 @@
  *
  * @param {Function} alloc - Memory allocation function
  * @param {Function} struct - Struct definition function
+ * @param {Function} bitfield - Bitfield helper function for Python-style [name, type, bits] syntax
  * @returns {Class} Structure base class
  * @private
  */
-export function createStructureClass(alloc, struct) {
+export function createStructureClass(alloc, struct, bitfield) {
   /**
    * Structure base class for creating C-style structures.
    *
@@ -135,280 +136,310 @@ export function createStructureClass(alloc, struct) {
    * c.radius = 5;
    * ```
    */
-class Structure {
-  constructor(...args) {
-    const Ctor = this.constructor;
-    const def = Ctor._structDef || Ctor._buildStruct();
-    // Allocate buffer for instance
-    let buf = alloc(def.size);
-    buf.fill(0);
-
-    // Support positional args: new Point(10,20)
-    if (args.length === 1 && typeof args[0] === "object" && !Array.isArray(args[0]) && !Buffer.isBuffer(args[0])) {
-      const initial = args[0];
-      for (const [k, v] of Object.entries(initial)) {
-        def.set(buf, k, v);
-      }
-    } else if (args.length === 1 && Buffer.isBuffer(args[0])) {
-      // new Point(buffer) - wrap existing buffer
-      buf = args[0];
-      // Validate buffer size matches struct size
-      if (buf.length < def.size) {
-        throw new RangeError(`Buffer size (${buf.length}) is smaller than struct size (${def.size})`);
-      }
-    } else if (args.length > 0) {
-      // Positional mapping to non-anonymous declared fields order
-      const ordered = def.fields.filter((f) => !f.isAnonymous);
-      for (let i = 0; i < Math.min(args.length, ordered.length); i++) {
-        def.set(buf, ordered[i].name, args[i]);
+  class Structure {
+    constructor(...args) {
+      const Ctor = this.constructor;
+      const def = Ctor._structDef || Ctor._buildStruct();
+      // Allocate buffer for instance
+      let buf = alloc(def.size);
+      buf.fill(0);
+
+      // Support positional args: new Point(10,20)
+      if (args.length === 1 && typeof args[0] === "object" && !Array.isArray(args[0]) && !Buffer.isBuffer(args[0])) {
+        const initial = args[0];
+        for (const [k, v] of Object.entries(initial)) {
+          def.set(buf, k, v);
+        }
+      } else if (args.length === 1 && Buffer.isBuffer(args[0])) {
+        // new Point(buffer) - wrap existing buffer
+        buf = args[0];
+        // Validate buffer size matches struct size
+        if (buf.length < def.size) {
+          throw new RangeError(`Buffer size (${buf.length}) is smaller than struct size (${def.size})`);
+        }
+      } else if (args.length > 0) {
+        // Positional mapping to non-anonymous declared fields order
+        const ordered = def.fields.filter((f) => !f.isAnonymous);
+        for (let i = 0; i < Math.min(args.length, ordered.length); i++) {
+          def.set(buf, ordered[i].name, args[i]);
+        }
       }
-    }
 
-    // Store internal references on this (needed for methods like toObject)
-    this.__buffer = buf;
-    this.__structDef = def;
-
-    // Build field map for O(1) lookup
-    const fieldMap = new Map();
-    const anonFieldNames = new Set();
-    for (const field of def.fields) {
-      fieldMap.set(field.name, field);
-      if (field.isAnonymous && field.type && Array.isArray(field.type.fields)) {
-        for (const subField of field.type.fields) {
-          anonFieldNames.add(subField.name);
+      // Store internal references on this (needed for methods like toObject)
+      this.__buffer = buf;
+      this.__structDef = def;
+
+      // Build field map for O(1) lookup
+      const fieldMap = new Map();
+      const anonFieldNames = new Set();
+      for (const field of def.fields) {
+        fieldMap.set(field.name, field);
+        if (field.isAnonymous && field.type && Array.isArray(field.type.fields)) {
+          for (const subField of field.type.fields) {
+            anonFieldNames.add(subField.name);
+          }
         }
       }
-    }
 
-    // Return Proxy instead of using Object.defineProperty for each field
-    return new Proxy(this, {
-      get(target, prop, receiver) {
-        // Special properties that exist on the instance
-        if (prop === "_buffer") return buf;
-        if (prop === "_structDef") return def;
-        if (prop === "__buffer") return buf;
-        if (prop === "__structDef") return def;
-        if (prop === Symbol.toStringTag) return Ctor.name || "Structure";
-        if (prop === Symbol.iterator) return undefined;
-
-        // Methods defined on the prototype
-        if (typeof target[prop] === "function") {
-          return target[prop].bind(target);
-        }
+      // Return Proxy instead of using Object.defineProperty for each field
+      // Pre-compute fast lookup set for all field names (including anonymous)
+      const allFieldNames = new Set(fieldMap.keys());
+      for (const name of anonFieldNames) allFieldNames.add(name);
+
+      return new Proxy(this, {
+        get(target, prop, receiver) {
+          // FAST PATH: struct field access (most common case)
+          // Check string type first, then Set lookup - both are O(1)
+          if (typeof prop === "string" && allFieldNames.has(prop)) {
+            return def.get(buf, prop);
+          }
 
-        // Check if it's a known field (O(1) lookup)
-        if (typeof prop === "string" && fieldMap.has(prop)) {
-          return def.get(buf, prop);
-        }
+          // SLOW PATH: special properties and methods
+          // Symbol check (Symbol.toStringTag, Symbol.iterator)
+          if (typeof prop === "symbol") {
+            if (prop === Symbol.toStringTag) return Ctor.name || "Structure";
+            return undefined;
+          }
 
-        // Check anonymous fields
-        if (typeof prop === "string" && anonFieldNames.has(prop)) {
-          return def.get(buf, prop);
-        }
+          // Internal buffer access
+          if (prop === "_buffer" || prop === "__buffer") return buf;
+          if (prop === "_structDef" || prop === "__structDef") return def;
 
-        // Fallback to target properties
-        return Reflect.get(target, prop, receiver);
-      },
-      set(target, prop, value, receiver) {
-        // Check if it's a known field (O(1) lookup)
-        if (typeof prop === "string" && fieldMap.has(prop)) {
-          def.set(buf, prop, value);
-          return true;
-        }
+          // Methods defined on the prototype
+          const method = target[prop];
+          if (typeof method === "function") {
+            return method.bind(target);
+          }
 
-        // Check anonymous fields
-        if (typeof prop === "string" && anonFieldNames.has(prop)) {
-          def.set(buf, prop, value);
-          return true;
-        }
+          // Fallback to target properties
+          return Reflect.get(target, prop, receiver);
+        },
+        set(target, prop, value, receiver) {
+          // FAST PATH: struct field access (most common case)
+          if (typeof prop === "string" && allFieldNames.has(prop)) {
+            def.set(buf, prop, value);
+            return true;
+          }
 
-        // Fallback
-        return Reflect.set(target, prop, value, receiver);
-      },
-      has(target, prop) {
-        if (prop === "_buffer" || prop === "_structDef" || prop === "toObject") return true;
-        if (typeof prop === "string" && fieldMap.has(prop)) return true;
-        if (typeof prop === "string" && anonFieldNames.has(prop)) return true;
-        return Reflect.has(target, prop);
-      },
-      ownKeys(target) {
-        const keys = [];
-        for (const f of def.fields) {
-          if (f.isAnonymous && f.type && Array.isArray(f.type.fields)) {
-            for (const sf of f.type.fields) {
-              keys.push(sf.name);
+          // Fallback
+          return Reflect.set(target, prop, value, receiver);
+        },
+        has(target, prop) {
+          if (typeof prop === "string" && allFieldNames.has(prop)) return true;
+          if (prop === "_buffer" || prop === "_structDef" || prop === "toObject") return true;
+          return Reflect.has(target, prop);
+        },
+        ownKeys(target) {
+          const keys = [];
+          for (const f of def.fields) {
+            if (f.isAnonymous && f.type && Array.isArray(f.type.fields)) {
+              for (const sf of f.type.fields) {
+                keys.push(sf.name);
+              }
+            } else {
+              keys.push(f.name);
             }
-          } else {
-            keys.push(f.name);
           }
-        }
-        return keys;
-      },
-      getOwnPropertyDescriptor(target, prop) {
-        if (typeof prop === "string" && (fieldMap.has(prop) || anonFieldNames.has(prop))) {
-          return {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-          };
-        }
-        if (prop === "_buffer" || prop === "_structDef") {
-          return {
-            enumerable: false,
-            configurable: true,
-            writable: true,
-          };
-        }
-        return Reflect.getOwnPropertyDescriptor(target, prop);
-      },
-    });
-  }
+          return keys;
+        },
+        getOwnPropertyDescriptor(target, prop) {
+          if (typeof prop === "string" && allFieldNames.has(prop)) {
+            return {
+              enumerable: true,
+              configurable: true,
+              writable: true,
+            };
+          }
+          if (prop === "_buffer" || prop === "_structDef") {
+            return {
+              enumerable: false,
+              configurable: true,
+              writable: true,
+            };
+          }
+          return Reflect.getOwnPropertyDescriptor(target, prop);
+        },
+      });
+    }
 
-  // Build the underlying struct definition and cache it on the constructor
-  static _buildStruct() {
-    // Accept either array _fields_ (Python style) or object map
-    const fields = this._fields_ || {};
-    let mapFields = {};
+    // Static getters for size, alignment, and fields (enables use as nested type)
+    static get size() {
+      const def = this._structDef || this._buildStruct();
+      return def.size;
+    }
 
-    if (Array.isArray(fields)) {
-      for (const entry of fields) {
-        if (Array.isArray(entry) && entry.length >= 2) {
-          mapFields[entry[0]] = entry[1];
-        }
-      }
-    } else if (typeof fields === "object" && fields !== null) {
-      mapFields = { ...fields };
+    static get alignment() {
+      const def = this._structDef || this._buildStruct();
+      return def.alignment;
+    }
+
+    static get fields() {
+      const def = this._structDef || this._buildStruct();
+      return def.fields;
+    }
+
+    static get create() {
+      const def = this._structDef || this._buildStruct();
+      return def.create.bind(def);
     }
 
-    // Handle anonymous fields list: convert to { anonymous: true, type: T }
-    if (Array.isArray(this._anonymous_)) {
-      for (const anonName of this._anonymous_) {
-        if (mapFields[anonName] !== undefined) {
-          mapFields[anonName] = {
-            anonymous: true,
-            type: mapFields[anonName],
-          };
+    // Build the underlying struct definition and cache it on the constructor
+    static _buildStruct() {
+      // Accept either array _fields_ (Python style) or object map
+      const fields = this._fields_ || {};
+      let mapFields = {};
+
+      if (Array.isArray(fields)) {
+        for (const entry of fields) {
+          if (Array.isArray(entry) && entry.length >= 2) {
+            const name = entry[0];
+            const type = entry[1];
+            // Python-style bitfield: [name, type, bits]
+            if (entry.length >= 3 && typeof entry[2] === "number") {
+              mapFields[name] = bitfield(type, entry[2]);
+            } else {
+              mapFields[name] = type;
+            }
+          }
         }
+      } else if (typeof fields === "object" && fields !== null) {
+        mapFields = { ...fields };
       }
-    }
 
-    const options = {};
-    if (this._pack_ !== undefined) options.packed = !!this._pack_;
+      // Handle anonymous fields list: convert to { anonymous: true, type: T }
+      if (Array.isArray(this._anonymous_)) {
+        for (const anonName of this._anonymous_) {
+          if (mapFields[anonName] !== undefined) {
+            let anonType = mapFields[anonName];
+            // Normalize type: if it's a Structure/Union class, get its _structDef
+            if (typeof anonType === "function" && typeof anonType._buildStruct === "function") {
+              anonType = anonType._structDef || anonType._buildStruct();
+            }
+            mapFields[anonName] = {
+              anonymous: true,
+              type: anonType,
+            };
+          }
+        }
+      }
 
-    const def = struct(mapFields, options);
-    this._structDef = def;
-    return def;
-  }
+      const options = {};
+      if (this._pack_ !== undefined) options.packed = !!this._pack_;
 
-  // Create returns an instance of the JS class (not a plain object)
-  static create(values = {}) {
-    const def = this._structDef || this._buildStruct();
-    // If a Buffer provided, wrap it
-    if (Buffer.isBuffer(values)) {
-      const inst = new this(values);
-      return inst;
+      const def = struct(mapFields, options);
+      this._structDef = def;
+      return def;
     }
-    // If values is instance of this class, return it
-    if (values && values._buffer && values._structDef === def) {
-      return values;
+
+    // Create returns an instance of the JS class (not a plain object)
+    static create(values = {}) {
+      const def = this._structDef || this._buildStruct();
+      // If a Buffer provided, wrap it
+      if (Buffer.isBuffer(values)) {
+        const inst = new this(values);
+        return inst;
+      }
+      // If values is instance of this class, return it
+      if (values && values._buffer && values._structDef === def) {
+        return values;
+      }
+      return new this(values);
     }
-    return new this(values);
-  }
 
-  // Create raw plain object without synchronization (for performance)
-  static createRaw(values = {}) {
-    const def = this._structDef || this._buildStruct();
-    return def.toObject(def.create(values)._buffer);
-  }
+    // Create raw plain object without synchronization (for performance)
+    static createRaw(values = {}) {
+      const def = this._structDef || this._buildStruct();
+      return def.toObject(def.create(values)._buffer);
+    }
 
-  // Synchronize plain object into instance buffer
-  syncFromObject(obj) {
-    const plain = this.__structDef.toObject(this.__buffer);
-    Object.assign(plain, obj);
-    this.__structDef.fromObject(this.__buffer, plain);
-  }
+    // Synchronize plain object into instance buffer
+    syncFromObject(obj) {
+      const plain = this.__structDef.toObject(this.__buffer);
+      Object.assign(plain, obj);
+      this.__structDef.fromObject(this.__buffer, plain);
+    }
 
-  // toObject: accept Buffer, instance or plain buffer
-  static toObject(bufOrInst) {
-    const def = this._structDef || this._buildStruct();
-    if (bufOrInst && bufOrInst._buffer) {
-      return def.toObject(bufOrInst._buffer);
+    // toObject: accept Buffer, instance or plain buffer
+    static toObject(bufOrInst) {
+      const def = this._structDef || this._buildStruct();
+      if (bufOrInst && bufOrInst._buffer) {
+        return def.toObject(bufOrInst._buffer);
+      }
+      return def.toObject(bufOrInst);
     }
-    return def.toObject(bufOrInst);
-  }
 
-  // fromObject: write plain object into buffer
-  static fromObject(bufOrInst, obj) {
-    const def = this._structDef || this._buildStruct();
-    const buf = bufOrInst && bufOrInst._buffer ? bufOrInst._buffer : bufOrInst;
-    return def.fromObject(buf, obj);
-  }
+    // fromObject: write plain object into buffer
+    static fromObject(bufOrInst, obj) {
+      const def = this._structDef || this._buildStruct();
+      const buf = bufOrInst && bufOrInst._buffer ? bufOrInst._buffer : bufOrInst;
+      return def.fromObject(buf, obj);
+    }
 
-  // Instance convenience
-  get(fieldName) {
-    return this.__structDef.get(this.__buffer, fieldName);
-  }
+    // Instance convenience
+    get(fieldName) {
+      return this.__structDef.get(this.__buffer, fieldName);
+    }
 
-  set(fieldName, value) {
-    return this.__structDef.set(this.__buffer, fieldName, value);
-  }
+    set(fieldName, value) {
+      return this.__structDef.set(this.__buffer, fieldName, value);
+    }
 
-  // Bulk operations for better performance
-  setFields(fields) {
-    for (const [name, value] of Object.entries(fields)) {
-      this.__structDef.set(this.__buffer, name, value);
+    // Bulk operations for better performance
+    setFields(fields) {
+      for (const [name, value] of Object.entries(fields)) {
+        this.__structDef.set(this.__buffer, name, value);
+      }
     }
-  }
 
-  getFields(fieldNames) {
-    const result = {};
-    for (const name of fieldNames) {
-      result[name] = this.__structDef.get(this.__buffer, name);
+    getFields(fieldNames) {
+      const result = {};
+      for (const name of fieldNames) {
+        result[name] = this.__structDef.get(this.__buffer, name);
+      }
+      return result;
     }
-    return result;
-  }
 
-  // bulk operations (Proxy reads directly from buffer - no cache needed)
-  withBulkUpdate(callback) {
-    return callback(this);
-  }
+    // bulk operations (Proxy reads directly from buffer - no cache needed)
+    withBulkUpdate(callback) {
+      return callback(this);
+    }
 
-  // Direct typed array access for numeric fields (maximum performance)
-  getInt32Array(offset = 0, length) {
-    return new Int32Array(this.__buffer.buffer, this.__buffer.byteOffset + offset, length);
-  }
+    // Direct typed array access for numeric fields (maximum performance)
+    getInt32Array(offset = 0, length) {
+      return new Int32Array(this.__buffer.buffer, this.__buffer.byteOffset + offset, length);
+    }
 
-  getFloat64Array(offset = 0, length) {
-    return new Float64Array(this.__buffer.buffer, this.__buffer.byteOffset + offset, length);
-  }
+    getFloat64Array(offset = 0, length) {
+      return new Float64Array(this.__buffer.buffer, this.__buffer.byteOffset + offset, length);
+    }
 
-  // Get raw buffer slice for external operations
-  getBufferSlice(offset = 0, size = this.__buffer.length - offset) {
-    return this.__buffer.subarray(offset, offset + size);
-  }
+    // Get raw buffer slice for external operations
+    getBufferSlice(offset = 0, size = this.__buffer.length - offset) {
+      return this.__buffer.subarray(offset, offset + size);
+    }
 
-  // Vectorized operations for arrays of structs
-  static createArray(count, initialValues = []) {
-    const instances = [];
-    for (let i = 0; i < count; i++) {
-      instances.push(this.create(initialValues[i] || {}));
+    // Vectorized operations for arrays of structs
+    static createArray(count, initialValues = []) {
+      const instances = [];
+      for (let i = 0; i < count; i++) {
+        instances.push(this.create(initialValues[i] || {}));
+      }
+      return instances;
     }
-    return instances;
-  }
 
-  // Bulk update all instances in array
-  static updateArray(instances, updates) {
-    for (let i = 0; i < instances.length && i < updates.length; i++) {
-      if (updates[i] && typeof updates[i] === "object") {
-        instances[i].setFields(updates[i]);
+    // Bulk update all instances in array
+    static updateArray(instances, updates) {
+      for (let i = 0; i < instances.length && i < updates.length; i++) {
+        if (updates[i] && typeof updates[i] === "object") {
+          instances[i].setFields(updates[i]);
+        }
       }
     }
-  }
 
-  toObject() {
-    return this.__structDef.toObject(this.__buffer);
+    toObject() {
+      return this.__structDef.toObject(this.__buffer);
+    }
   }
-}
 
   return Structure;
 }

package/lib/structures/Union.js

@@ -45,10 +45,11 @@
  *
  * @param {Class} Structure - Structure base class to extend from
  * @param {Function} union - Union definition function
+ * @param {Function} bitfield - Bitfield helper function for Python-style [name, type, bits] syntax
  * @returns {Class} Union base class
  * @private
  */
-export function createUnionClass(Structure, union) {
+export function createUnionClass(Structure, union, bitfield) {
   /**
    * Union base class for creating C-style unions.
    *
@@ -86,7 +87,14 @@ export function createUnionClass(Structure, union) {
       if (Array.isArray(fields)) {
         for (const entry of fields) {
           if (Array.isArray(entry) && entry.length >= 2) {
-            mapFields[entry[0]] = entry[1];
+            const name = entry[0];
+            const type = entry[1];
+            // Python-style bitfield: [name, type, bits]
+            if (entry.length >= 3 && typeof entry[2] === "number") {
+              mapFields[name] = bitfield(type, entry[2]);
+            } else {
+              mapFields[name] = type;
+            }
           }
         }
       } else if (typeof fields === "object" && fields !== null) {

package/lib/structures/helpers/common.js

@@ -87,7 +87,15 @@ export function bitfield(baseType, bits, sizeof) {
  * @private
  */
 export function _isStruct(type) {
-  return typeof type === "object" && type !== null && typeof type.size === "number" && Array.isArray(type.fields) && typeof type.create === "function";
+  // Check for struct definition object (from struct() function)
+  if (typeof type === "object" && type !== null && typeof type.size === "number" && Array.isArray(type.fields) && typeof type.create === "function") {
+    return true;
+  }
+  // Check for Structure/Union class (has _fields_ or _structDef and _buildStruct)
+  if (typeof type === "function" && (type._fields_ || type._structDef) && typeof type._buildStruct === "function") {
+    return true;
+  }
+  return false;
 }
 
 /**

package/lib/structures/helpers/struct.js

@@ -248,7 +248,12 @@ export function struct(fields, options = {}, sizeof, alloc, readValue, writeValu
       currentBitFieldBase = null;
       currentBitOffset = 0;
 
-      const nestedStruct = type;
+      // Normalize type: if it's a Structure/Union class, get its _structDef
+      let nestedStruct = type;
+      if (typeof type === "function" && typeof type._buildStruct === "function") {
+        nestedStruct = type._structDef || type._buildStruct();
+      }
+
       const size = nestedStruct.size;
       const alignment = packed ? 1 : nestedStruct.alignment;
 

package/lib/structures/helpers/union.js

@@ -94,26 +94,16 @@ export function union(fields, sizeof, alloc, readValue, writeValue, _isStruct, _
     let size, alignment;
     let fieldDef = { name, type, offset: 0 };
 
-    // Nested struct (object form)
+    // Nested struct (object form or class form)
     if (_isStruct(type)) {
-      size = type.size;
-      alignment = type.alignment;
-      fieldDef.isNested = true;
-    }
-    // Struct class (declarata come `class X extends Structure`)
-    else if (typeof type === "function" && type.prototype instanceof Structure) {
-      const nested = type._structDef || type._buildStruct();
-      size = nested.size;
-      alignment = nested.alignment;
-      fieldDef.type = nested;
-      fieldDef.isNested = true;
-    }
-    // Union class (declarata come `class X extends Union`)
-    else if (typeof type === "function" && type.prototype instanceof Union) {
-      const nested = type._unionDef || type._buildUnion();
-      size = nested.size;
-      alignment = nested.alignment;
-      fieldDef.type = nested;
+      // Normalize type: if it's a Structure/Union class, get its _structDef
+      let nestedStruct = type;
+      if (typeof type === "function" && typeof type._buildStruct === "function") {
+        nestedStruct = type._structDef || type._buildStruct();
+        fieldDef.type = nestedStruct;
+      }
+      size = nestedStruct.size;
+      alignment = nestedStruct.alignment;
       fieldDef.isNested = true;
     }
     // Array type