node-ctypes 0.1.5 → 1.0.0

package/lib/structures/Structure.js

@@ -0,0 +1,414 @@
+/**
+ * @file Structure.js
+ * @module structures/Structure
+ * @description Structure base class for Python ctypes-compatible structures.
+ *
+ * This module provides the `Structure` base class that users extend to create
+ * custom struct types with automatic field management, memory layout, and
+ * proxy-based field access.
+ *
+ * **Python ctypes Compatibility**:
+ * Direct equivalent to Python's `ctypes.Structure` class with `_fields_` attribute.
+ *
+ * @example Basic Structure subclass
+ * ```javascript
+ * import { Structure, c_int32, c_float } from 'node-ctypes';
+ *
+ * class Point extends Structure {
+ *   static _fields_ = [
+ *     ['x', c_int32],
+ *     ['y', c_int32]
+ *   ];
+ * }
+ *
+ * const pt = new Point({ x: 10, y: 20 });
+ * console.log(pt.x, pt.y); // 10 20
+ * pt.x = 42;
+ * console.log(pt.x); // 42
+ * ```
+ *
+ * @example Positional arguments
+ * ```javascript
+ * const pt = new Point(10, 20); // x=10, y=20
+ * ```
+ *
+ * @example Wrapping existing buffer
+ * ```javascript
+ * const buffer = Buffer.alloc(8);
+ * const pt = new Point(buffer);
+ * pt.x = 100;
+ * ```
+ *
+ * @example Array-style _fields_ (Python ctypes compatible)
+ * ```javascript
+ * class Rect extends Structure {
+ *   static _fields_ = [
+ *     ['x', c_int32],
+ *     ['y', c_int32],
+ *     ['width', c_int32],
+ *     ['height', c_int32]
+ *   ];
+ * }
+ * ```
+ *
+ * @example Object-style _fields_ (alternative syntax)
+ * ```javascript
+ * class Rect extends Structure {
+ *   static _fields_ = {
+ *     x: c_int32,
+ *     y: c_int32,
+ *     width: c_int32,
+ *     height: c_int32
+ *   };
+ * }
+ * ```
+ */
+
+/**
+ * Creates the Structure base class with required dependencies injected.
+ *
+ * @param {Function} alloc - Memory allocation function
+ * @param {Function} struct - Struct definition function
+ * @returns {Class} Structure base class
+ * @private
+ */
+export function createStructureClass(alloc, struct) {
+  /**
+   * Structure base class for creating C-style structures.
+   *
+   * Users extend this class and define static `_fields_` to specify the struct layout.
+   * The constructor handles memory allocation, field initialization, and returns a
+   * Proxy for transparent field access.
+   *
+   * **Key Features**:
+   * - Automatic memory layout based on `_fields_`
+   * - Proxy-based transparent field access
+   * - Support for positional arguments in constructor
+   * - Buffer wrapping for zero-copy operations
+   * - Anonymous field support via `_anonymous_`
+   * - Packed mode via `_pack_`
+   *
+   * **Python ctypes Compatibility**:
+   * Similar to Python's `ctypes.Structure` with:
+   * - `_fields_` attribute (array or object)
+   * - `_anonymous_` attribute for anonymous fields
+   * - `_pack_` attribute for packed structures
+   *
+   * @class Structure
+   *
+   * @example Extending Structure
+   * ```javascript
+   * class Vec3 extends Structure {
+   *   static _fields_ = [
+   *     ['x', c_float],
+   *     ['y', c_float],
+   *     ['z', c_float]
+   *   ];
+   *
+   *   // Add custom methods
+   *   length() {
+   *     return Math.sqrt(this.x**2 + this.y**2 + this.z**2);
+   *   }
+   * }
+   *
+   * const v = new Vec3(1.0, 2.0, 3.0);
+   * console.log(v.length()); // 3.7416573867739413
+   * ```
+   *
+   * @example Anonymous fields
+   * ```javascript
+   * class Point extends Structure {
+   *   static _fields_ = [['x', c_int32], ['y', c_int32]];
+   * }
+   *
+   * class Circle extends Structure {
+   *   static _fields_ = [
+   *     ['center', Point],
+   *     ['radius', c_int32]
+   *   ];
+   *   static _anonymous_ = ['center'];
+   * }
+   *
+   * const c = new Circle();
+   * c.x = 10; // Access Point.x directly
+   * c.y = 20; // Access Point.y directly
+   * 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]);
+      }
+    }
+
+    // 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);
+        }
+
+        // Check if it's a known field (O(1) lookup)
+        if (typeof prop === "string" && fieldMap.has(prop)) {
+          return def.get(buf, prop);
+        }
+
+        // Check anonymous fields
+        if (typeof prop === "string" && anonFieldNames.has(prop)) {
+          return def.get(buf, prop);
+        }
+
+        // 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;
+        }
+
+        // Check anonymous fields
+        if (typeof prop === "string" && anonFieldNames.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);
+            }
+          } 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);
+      },
+    });
+  }
+
+  // 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) {
+          mapFields[entry[0]] = entry[1];
+        }
+      }
+    } else if (typeof fields === "object" && fields !== null) {
+      mapFields = { ...fields };
+    }
+
+    // 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],
+          };
+        }
+      }
+    }
+
+    const options = {};
+    if (this._pack_ !== undefined) options.packed = !!this._pack_;
+
+    const def = struct(mapFields, options);
+    this._structDef = def;
+    return def;
+  }
+
+  // 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);
+  }
+
+  // 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);
+  }
+
+  // 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);
+  }
+
+  // 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);
+  }
+
+  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);
+    }
+  }
+
+  getFields(fieldNames) {
+    const result = {};
+    for (const name of fieldNames) {
+      result[name] = this.__structDef.get(this.__buffer, name);
+    }
+    return result;
+  }
+
+  // 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);
+  }
+
+  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);
+  }
+
+  // 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;
+  }
+
+  // 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);
+  }
+}
+
+  return Structure;
+}

package/lib/structures/Union.js

@@ -0,0 +1,102 @@
+/**
+ * @file UnionClass.js
+ * @module structures/UnionClass
+ * @description Union base class for Python ctypes-compatible unions.
+ *
+ * This module provides the `Union` base class that users extend to create
+ * custom union types where all fields share the same memory location.
+ *
+ * **Python ctypes Compatibility**:
+ * Direct equivalent to Python's `ctypes.Union` class with `_fields_` attribute.
+ *
+ * @example Basic Union subclass
+ * ```javascript
+ * import { Union, c_int32, c_float } from 'node-ctypes';
+ *
+ * class Value extends Union {
+ *   static _fields_ = [
+ *     ['as_int', c_int32],
+ *     ['as_float', c_float]
+ *   ];
+ * }
+ *
+ * const v = new Value();
+ * v.as_int = 0x40490FDB; // IEEE 754 for ~3.14159
+ * console.log(v.as_float); // ~3.14159
+ * ```
+ *
+ * @example Type reinterpretation
+ * ```javascript
+ * class ByteWord extends Union {
+ *   static _fields_ = [
+ *     ['bytes', array(c_uint8, 4)],
+ *     ['word', c_uint32]
+ *   ];
+ * }
+ *
+ * const bw = new ByteWord();
+ * bw.word = 0x12345678;
+ * console.log([...bw.bytes]); // [0x78, 0x56, 0x34, 0x12] (little-endian)
+ * ```
+ */
+
+/**
+ * Creates the Union base class with required dependencies injected.
+ *
+ * @param {Class} Structure - Structure base class to extend from
+ * @param {Function} union - Union definition function
+ * @returns {Class} Union base class
+ * @private
+ */
+export function createUnionClass(Structure, union) {
+  /**
+   * Union base class for creating C-style unions.
+   *
+   * Extends `Structure` but uses union layout where all fields share the
+   * same memory location (offset 0). The union size is the maximum of all
+   * field sizes.
+   *
+   * **Python ctypes Compatibility**:
+   * Similar to Python's `ctypes.Union` with:
+   * - `_fields_` attribute (array or object)
+   * - All fields at same memory location
+   * - Size equals largest field size
+   *
+   * @class Union
+   * @extends Structure
+   *
+   * @example RGB color union
+   * ```javascript
+   * class Color extends Union {
+   *   static _fields_ = [
+   *     ['rgba', c_uint32],
+   *     ['components', array(c_uint8, 4)]
+   *   ];
+   * }
+   *
+   * const color = new Color();
+   * color.rgba = 0xFF0080FF; // RGBA: 255, 0, 128, 255
+   * console.log([...color.components]); // [255, 128, 0, 255] (little-endian)
+   * ```
+   */
+  class Union extends Structure {
+    static _buildStruct() {
+      const fields = this._fields_ || {};
+      let mapFields = {};
+      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;
+      }
+      const def = union(mapFields);
+      this._structDef = def;
+      return def;
+    }
+  }
+
+  return Union;
+}