node-ctypes 0.1.5 → 1.0.0

package/lib/structures/helpers/array.js

@@ -0,0 +1,261 @@
+/**
+ * @file array.js
+ * @module structures/array
+ * @description Array type implementation for fixed-size arrays of C types.
+ *
+ * This module provides Python ctypes-compatible array types that support:
+ * - Fixed-size arrays of any C type (primitives, structs, unions)
+ * - Python-like indexing with bracket notation
+ * - Iteration support (for...of, spread operator)
+ * - String initialization for character arrays
+ *
+ * **Python ctypes Compatibility**:
+ * Similar to Python's `type * count` array syntax or explicit array types.
+ *
+ * @example Basic usage
+ * ```javascript
+ * import { array, c_int32 } from 'node-ctypes';
+ *
+ * const IntArray5 = array(c_int32, 5);
+ * const arr = IntArray5.create([1, 2, 3, 4, 5]);
+ * console.log(arr[0]);  // 1
+ * arr[2] = 42;
+ * console.log(arr[2]);  // 42
+ * ```
+ *
+ * @example Array of structs
+ * ```javascript
+ * class Point extends Structure {
+ *   static _fields_ = [['x', c_int32], ['y', c_int32]];
+ * }
+ *
+ * const PointArray = array(Point, 3);
+ * const points = PointArray.create();
+ * points[0].x = 10;
+ * points[0].y = 20;
+ * ```
+ *
+ * @example Iteration
+ * ```javascript
+ * const arr = IntArray5.create([1, 2, 3, 4, 5]);
+ * for (const val of arr) {
+ *   console.log(val);
+ * }
+ * const values = [...arr]; // Spread operator
+ * ```
+ */
+
+/**
+ * Creates a fixed-size array type for a given element type.
+ *
+ * Returns an array type definition that can create instances of fixed-size
+ * arrays. The created arrays support Python-like indexing, iteration, and
+ * automatic memory management.
+ *
+ * **Python ctypes Compatibility**:
+ * Similar to Python's `type * count` syntax (e.g., `c_int * 5`).
+ *
+ * @param {Function|Object} elementType - Element type (SimpleCData class, Structure/Union class, or type object)
+ * @param {number} count - Number of elements in the array
+ * @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} Structure - Structure class reference
+ * @param {Function} Union - Union class reference
+ * @param {Function} ArrayType - Native ArrayType class reference (if available)
+ * @returns {Object} Array type definition with create and wrap methods
+ * @throws {TypeError} If elementType is not a valid type
+ *
+ * @example Create integer array
+ * ```javascript
+ * import { array, c_int32 } from 'node-ctypes';
+ *
+ * const IntArray5 = array(c_int32, 5);
+ * const arr = IntArray5.create([1, 2, 3, 4, 5]);
+ * console.log(arr[0]);  // 1
+ * arr[2] = 42;
+ * console.log(arr[2]);  // 42
+ * ```
+ *
+ * @example Partial initialization
+ * ```javascript
+ * const arr = IntArray5.create([1, 2]); // Rest are zeros
+ * console.log(arr[0]); // 1
+ * console.log(arr[4]); // 0
+ * ```
+ *
+ * @example String initialization (character arrays)
+ * ```javascript
+ * const CharArray10 = array(c_char, 10);
+ * const arr = CharArray10.create("hello");
+ * // arr contains ASCII codes: [104, 101, 108, 108, 111, 0, 0, 0, 0, 0]
+ * ```
+ *
+ * @example Array of structs
+ * ```javascript
+ * class Point extends Structure {
+ *   static _fields_ = [['x', c_int32], ['y', c_int32]];
+ * }
+ *
+ * const PointArray = array(Point, 3);
+ * const points = PointArray.create();
+ * points[0].x = 10;
+ * points[0].y = 20;
+ * ```
+ */
+export function array(elementType, count, sizeof, alloc, readValue, writeValue, Structure, Union, ArrayType) {
+  // Validate elementType: accept SimpleCData classes, Structure/Union classes,
+  // or native CType-like objects.
+  const isSimple = typeof elementType === "function" && elementType._isSimpleCData;
+  const isStruct = typeof elementType === "function" && (elementType.prototype instanceof Structure || elementType.prototype instanceof Union);
+  const isNativeTypeObj = typeof elementType === "object" && elementType !== null && (typeof elementType.getSize === "function" || elementType.size !== undefined);
+  if (!isSimple && !isStruct && !isNativeTypeObj) {
+    throw new TypeError("array elementType must be a SimpleCData class or a Structure/Union class");
+  }
+
+  const elementSize = sizeof(elementType);
+  let nativeArray;
+  if (isNativeTypeObj && ArrayType) {
+    nativeArray = new ArrayType(elementType, count);
+  } else {
+    // Provide a small JS-side shim implementing the minimal ArrayType API
+    nativeArray = {
+      getSize: () => count * elementSize,
+      getLength: () => count,
+      getAlignment: () => elementSize,
+      create: (values) => {
+        // JS create is implemented below; this should not be invoked by JS code
+        const size = count * elementSize;
+        const buffer = alloc(size);
+        buffer.fill(0);
+        return buffer;
+      },
+    };
+  }
+
+  // Wrap function that returns a Proxy for array-like indexing
+  const wrap = function (buffer) {
+    return new Proxy(buffer, {
+      get(target, prop, receiver) {
+        // Special case for _buffer to return the underlying buffer
+        if (prop === "_buffer") {
+          return target;
+        }
+
+        // Special case for toString to show array contents
+        if (prop === "toString") {
+          return function () {
+            try {
+              const arr = Array.from(this);
+              return `[${arr.join(", ")}]`;
+            } catch (e) {
+              return "[error]";
+            }
+          }.bind(receiver);
+        }
+
+        // Intercept Symbol.iterator to iterate over elements, not bytes
+        if (prop === Symbol.iterator) {
+          return function* () {
+            for (let i = 0; i < count; i++) {
+              const off = i * elementSize;
+              // If elementType is a struct/union class, return an instance bound to the slice
+              if (typeof elementType === "function" && (elementType.prototype instanceof Structure || elementType.prototype instanceof Union)) {
+                yield new elementType(target.subarray(off, off + elementSize));
+              } else {
+                yield readValue(target, elementType, off);
+              }
+            }
+          };
+        }
+
+        // Ignore other Symbols
+        if (typeof prop === "symbol") {
+          const value = Reflect.get(target, prop, target);
+          if (typeof value === "function") {
+            return value.bind(target);
+          }
+          return value;
+        }
+
+        // If it's a number (index) - intercept BEFORE checking target
+        const index = Number(prop);
+        if (Number.isInteger(index) && !isNaN(index)) {
+          if (index >= 0 && index < count) {
+            const off = index * elementSize;
+            if (typeof elementType === "function" && (elementType.prototype instanceof Structure || elementType.prototype instanceof Union)) {
+              return new elementType(target.subarray(off, off + elementSize));
+            }
+            return readValue(target, elementType, off);
+          }
+          // Numeric index out of bounds -> undefined (JavaScript behavior)
+          return undefined;
+        }
+
+        // For everything else, use the normal buffer
+        const value = Reflect.get(target, prop, target);
+        // If it's a function, bind it to the target
+        if (typeof value === "function") {
+          return value.bind(target);
+        }
+        return value;
+      },
+      set(target, prop, value) {
+        // Ignore Symbols
+        if (typeof prop === "symbol") {
+          return Reflect.set(target, prop, value, target);
+        }
+
+        const index = Number(prop);
+        if (Number.isInteger(index) && !isNaN(index)) {
+          if (index >= 0 && index < count) {
+            writeValue(target, elementType, value, index * elementSize);
+            return true;
+          }
+          // Index out of bounds - don't write anything but return false
+          return false;
+        }
+        return Reflect.set(target, prop, value, target);
+      },
+    });
+  };
+
+  // Return a wrapper object that delegates to nativeArray but overrides create()
+  return {
+    // Type information
+    elementType,
+    length: count,
+
+    // Delegated methods
+    getSize: () => nativeArray.getSize(),
+    getLength: () => nativeArray.getLength(),
+    getAlignment: () => nativeArray.getAlignment(),
+
+    // create automatically returns the proxy
+    create: (values) => {
+      const size = count * sizeof(elementType);
+      const buffer = alloc(size);
+      buffer.fill(0);
+      if (Array.isArray(values)) {
+        for (let i = 0; i < Math.min(values.length, count); i++) {
+          writeValue(buffer, elementType, values[i], i * sizeof(elementType));
+        }
+      } else if (typeof values === "string") {
+        for (let i = 0; i < Math.min(values.length, count); i++) {
+          writeValue(buffer, elementType, values.charCodeAt(i), i * sizeof(elementType));
+        }
+      }
+      return wrap(buffer);
+    },
+
+    // Explicit wrap method
+    wrap: wrap,
+
+    // For compatibility, expose the native array (needed for StructType.addField)
+    _native: nativeArray,
+
+    // Helper to check if this is an ArrayType wrapper
+    _isArrayType: true,
+  };
+}

package/lib/structures/helpers/bitfield.js

@@ -0,0 +1,147 @@
+/**
+ * @file bitfield-helpers.js
+ * @module structures/bitfield-helpers
+ * @description Helper functions for reading and writing bitfield values in structs.
+ *
+ * This module provides low-level bitfield manipulation functions used by struct
+ * and union implementations to pack multiple small integer values into single bytes.
+ *
+ * @example
+ * ```javascript
+ * import { _readBitField, _writeBitField } from './structures/bitfield-helpers.js';
+ *
+ * const buf = Buffer.alloc(4);
+ * _writeBitField(buf, 0, c_uint32, 0, 3, 5); // Write 5 to bits 0-2
+ * const value = _readBitField(buf, 0, c_uint32, 0, 3); // Read bits 0-2
+ * ```
+ */
+
+/**
+ * Reads an unsigned integer value from a buffer.
+ *
+ * @param {Buffer} buf - Buffer to read from
+ * @param {number} offset - Byte offset in buffer
+ * @param {number} byteSize - Size in bytes (1, 2, 4, or 8)
+ * @param {Function} sizeof - sizeof function reference
+ * @returns {number|bigint} Value read from buffer
+ * @throws {Error} If byteSize is not supported
+ * @private
+ */
+export function _readUintFromBuffer(buf, offset, byteSize) {
+  switch (byteSize) {
+    case 1:
+      return buf.readUInt8(offset);
+    case 2:
+      return buf.readUInt16LE(offset);
+    case 4:
+      return buf.readUInt32LE(offset);
+    case 8:
+      return buf.readBigUInt64LE(offset);
+    default:
+      throw new Error(`Unsupported byte size: ${byteSize}`);
+  }
+}
+
+/**
+ * Writes an unsigned integer value to a buffer.
+ *
+ * @param {Buffer} buf - Buffer to write to
+ * @param {number} offset - Byte offset in buffer
+ * @param {number} byteSize - Size in bytes (1, 2, 4, or 8)
+ * @param {number|bigint} value - Value to write
+ * @throws {Error} If byteSize is not supported
+ * @private
+ */
+export function _writeUintToBuffer(buf, offset, byteSize, value) {
+  switch (byteSize) {
+    case 1:
+      buf.writeUInt8(value, offset);
+      break;
+    case 2:
+      buf.writeUInt16LE(value, offset);
+      break;
+    case 4:
+      buf.writeUInt32LE(value, offset);
+      break;
+    case 8:
+      buf.writeBigUInt64LE(value, offset);
+      break;
+    default:
+      throw new Error(`Unsupported byte size: ${byteSize}`);
+  }
+}
+
+/**
+ * Reads a bitfield value from a buffer.
+ *
+ * Extracts a specific range of bits from an integer value stored in memory.
+ * Used by struct/union implementations to support packed bitfields.
+ *
+ * @param {Buffer} buf - Buffer to read from
+ * @param {number} offset - Byte offset of the containing integer
+ * @param {Function|Object} baseType - Base integer type (c_uint8, c_uint16, c_uint32, c_uint64)
+ * @param {number} bitOffset - Starting bit position (0-based)
+ * @param {number} bitSize - Number of bits to read
+ * @param {Function} sizeof - sizeof function reference
+ * @returns {number} Extracted bitfield value
+ *
+ * @example
+ * ```javascript
+ * // Read 3-bit field starting at bit 5
+ * const value = _readBitField(buf, 0, c_uint32, 5, 3);
+ * ```
+ * @private
+ */
+export function _readBitField(buf, offset, baseType, bitOffset, bitSize, sizeof) {
+  const baseSize = sizeof(baseType);
+  const value = _readUintFromBuffer(buf, offset, baseSize);
+
+  // Extract the bits
+  if (baseSize === 8) {
+    const mask = (1n << BigInt(bitSize)) - 1n;
+    return Number((value >> BigInt(bitOffset)) & mask);
+  } else {
+    const mask = (1 << bitSize) - 1;
+    return (value >> bitOffset) & mask;
+  }
+}
+
+/**
+ * Writes a bitfield value to a buffer.
+ *
+ * Modifies a specific range of bits in an integer value stored in memory,
+ * preserving other bits. Used by struct/union implementations to support
+ * packed bitfields.
+ *
+ * @param {Buffer} buf - Buffer to write to
+ * @param {number} offset - Byte offset of the containing integer
+ * @param {Function|Object} baseType - Base integer type (c_uint8, c_uint16, c_uint32, c_uint64)
+ * @param {number} bitOffset - Starting bit position (0-based)
+ * @param {number} bitSize - Number of bits to write
+ * @param {number} newValue - Value to write (will be masked to bitSize)
+ * @param {Function} sizeof - sizeof function reference
+ *
+ * @example
+ * ```javascript
+ * // Write 5 to a 3-bit field starting at bit 2
+ * _writeBitField(buf, 0, c_uint32, 2, 3, 5);
+ * ```
+ * @private
+ */
+export function _writeBitField(buf, offset, baseType, bitOffset, bitSize, newValue, sizeof) {
+  const baseSize = sizeof(baseType);
+  let value = _readUintFromBuffer(buf, offset, baseSize);
+
+  // Modify the bits
+  if (baseSize === 8) {
+    const mask = (1n << BigInt(bitSize)) - 1n;
+    const clearMask = ~(mask << BigInt(bitOffset));
+    value = (value & clearMask) | ((BigInt(newValue) & mask) << BigInt(bitOffset));
+  } else {
+    const mask = (1 << bitSize) - 1;
+    const clearMask = ~(mask << bitOffset);
+    value = (value & clearMask) | ((newValue & mask) << bitOffset);
+  }
+
+  _writeUintToBuffer(buf, offset, baseSize, value);
+}

package/lib/structures/helpers/common.js

@@ -0,0 +1,129 @@
+/**
+ * @file helpers.js
+ * @module structures/helpers
+ * @description Helper functions and type checks for structure and type system.
+ *
+ * This module provides utility functions for working with structures, arrays,
+ * and bitfields in the node-ctypes type system.
+ *
+ * @example
+ * ```javascript
+ * import { bitfield, _isStruct, _isArrayType } from './structures/helpers.js';
+ *
+ * // Create a bitfield
+ * const flags = bitfield(c_uint32, 8); // 8-bit field
+ *
+ * // Check if type is a struct
+ * if (_isStruct(myType)) {
+ *   // Handle struct type
+ * }
+ * ```
+ */
+
+/**
+ * Creates a bitfield definition.
+ *
+ * Bitfields allow packing multiple boolean or small integer values into a single
+ * integer type, useful for flags and compact data structures.
+ *
+ * **Python ctypes Compatibility**:
+ * Similar to Python's ctypes bitfield syntax in Structure _fields_.
+ *
+ * @param {Function|Object} baseType - Base integer type (c_uint8, c_uint16, c_uint32, c_uint64)
+ * @param {number} bits - Number of bits to allocate (1 to baseSize*8)
+ * @param {Function} sizeof - sizeof function reference
+ * @returns {Object} Bitfield definition object
+ * @throws {Error} If bits is out of valid range for base type
+ *
+ * @example 8-bit flags in uint32
+ * ```javascript
+ * import { struct, bitfield, c_uint32 } from 'node-ctypes';
+ *
+ * const Flags = struct({
+ *   isActive: bitfield(c_uint32, 1),   // 1 bit
+ *   priority: bitfield(c_uint32, 3),   // 3 bits
+ *   category: bitfield(c_uint32, 4),   // 4 bits
+ * });
+ * ```
+ *
+ * @example Using different base types
+ * ```javascript
+ * // Small bitfield (up to 8 bits)
+ * const smallFlags = bitfield(c_uint8, 5);
+ *
+ * // Large bitfield (up to 64 bits)
+ * const largeFlags = bitfield(c_uint64, 48);
+ * ```
+ */
+export function bitfield(baseType, bits, sizeof) {
+  const baseSize = sizeof(baseType);
+  const maxBits = baseSize * 8;
+
+  if (bits < 1 || bits > maxBits) {
+    throw new Error(`Bit field size must be between 1 and ${maxBits} for ${baseType}`);
+  }
+
+  return {
+    _isBitField: true,
+    baseType: baseType,
+    bits: bits,
+    baseSize: baseSize,
+  };
+}
+
+/**
+ * Checks if a type is a struct definition.
+ *
+ * @param {*} type - Type to check
+ * @returns {boolean} True if type is a struct definition
+ *
+ * @example
+ * ```javascript
+ * const myStruct = struct({ x: c_int32, y: c_int32 });
+ * console.log(_isStruct(myStruct)); // true
+ * console.log(_isStruct(c_int32));  // false
+ * ```
+ *
+ * @private
+ */
+export function _isStruct(type) {
+  return typeof type === "object" && type !== null && typeof type.size === "number" && Array.isArray(type.fields) && typeof type.create === "function";
+}
+
+/**
+ * Checks if a type is an array type definition.
+ *
+ * @param {*} type - Type to check
+ * @returns {boolean} True if type is an array type
+ *
+ * @example
+ * ```javascript
+ * const intArray = array(c_int32, 10);
+ * console.log(_isArrayType(intArray)); // true
+ * console.log(_isArrayType(c_int32));  // false
+ * ```
+ *
+ * @private
+ */
+export function _isArrayType(type) {
+  return typeof type === "object" && type !== null && type._isArrayType === true;
+}
+
+/**
+ * Checks if a type is a bitfield definition.
+ *
+ * @param {*} type - Type to check
+ * @returns {boolean} True if type is a bitfield
+ *
+ * @example
+ * ```javascript
+ * const flags = bitfield(c_uint32, 8);
+ * console.log(_isBitField(flags)); // true
+ * console.log(_isBitField(c_int32)); // false
+ * ```
+ *
+ * @private
+ */
+export function _isBitField(type) {
+  return typeof type === "object" && type !== null && type._isBitField === true;
+}