node-ctypes 1.1.0 → 1.3.0

package/lib/core/callback.js

@@ -87,8 +87,8 @@ import { _toNativeType, _toNativeTypes } from "./types.js";
  *
  * @param {Function} fn - JavaScript function to wrap
  *   The function will receive converted arguments based on argTypes
- * @param {Function|Object} returnType - Return type (SimpleCData class or CType)
- * @param {Array<Function|Object>} argTypes - Argument types array
+ * @param {Function|Object|number} returnType - Return type (SimpleCData class, CType, or CType value)
+ * @param {Array<Function|Object|number>} argTypes - Argument types array
  * @param {Object} native - Native module reference (internal use)
  * @returns {Object} Callback wrapper with properties:
  *   - `pointer` (BigInt): Function pointer to pass to C
@@ -197,8 +197,8 @@ export function callback(fn, returnType, argTypes = [], native) {
  * @param {Function} fn - JavaScript function to wrap
  *   The function will be executed on Node.js's main thread regardless of
  *   which thread invokes the callback
- * @param {Function|Object} returnType - Return type (SimpleCData class or CType)
- * @param {Array<Function|Object>} argTypes - Argument types array
+ * @param {Function|Object|number} returnType - Return type (SimpleCData class, CType, or CType value)
+ * @param {Array<Function|Object|number>} argTypes - Argument types array
  * @param {Object} native - Native module reference (internal use)
  * @returns {Object} Callback wrapper with properties:
  *   - `pointer` (BigInt): Function pointer to pass to C

package/lib/core/types.js

@@ -11,14 +11,14 @@
  * @example
  * ```javascript
  * import { _toNativeType, _toNativeTypes } from './core/types.js';
- * import { c_int32, c_char_p } from './types/integers.js';
+ * import { c_int32, c_char_p, CType } from 'node-ctypes';
  *
- * // Convert single type
- * const nativeType = _toNativeType(c_int32); // Returns "int32"
+ * // Convert single type - returns numeric CType value
+ * const nativeType = _toNativeType(c_int32); // Returns CType.INT32 (5)
  *
  * // Convert array of types
  * const nativeTypes = _toNativeTypes([c_int32, c_char_p]);
- * // Returns ["int32", <native CType for c_char_p>]
+ * // Returns [CType.INT32, CType.STRING]
  * ```
  */
 
@@ -28,34 +28,36 @@
  *
  * **Type Conversion Rules**:
  * 1. **SimpleCData classes** (e.g., `c_int32`, `c_uint64`):
- *    - Most types → Convert to string type name (e.g., `"int32"`, `"uint64"`)
- *    - `c_char_p` and `c_wchar_p` → Convert to native CType for automatic string marshalling
+ *    - Returns the numeric CType value (e.g., `CType.INT32`, `CType.STRING`)
  *
  * 2. **Structure/Union classes**: Pass through unchanged for struct/union handling
  *
- * 3. **Native CType objects**: Pass through unchanged (already in native format)
+ * 3. **Numbers (CType values)**: Pass through unchanged (already in native format)
+ *
+ * 4. **Native CType objects**: Pass through unchanged (already in native format)
  *
  * **Python ctypes Compatibility**:
  * This function mimics Python's ctypes internal type normalization, ensuring that
  * type specifications work consistently whether passed as class constructors or
  * type objects.
  *
- * @param {Function|Object} type - Type specification to normalize
+ * @param {Function|Object|number} type - Type specification to normalize
  *   - SimpleCData class (e.g., `c_int32`)
  *   - Structure or Union class
+ *   - CType numeric value
  *   - Native CType object
- * @returns {string|Object} Normalized type for native FFI:
- *   - String type name for most SimpleCData types
- *   - Native CType object for string pointer types (c_char_p, c_wchar_p)
+ * @param {Object} native - Native module reference (unused but kept for API compatibility)
+ * @returns {number|Object} Normalized type for native FFI:
+ *   - Numeric CType value for SimpleCData types
  *   - Original value for Structure/Union/CType objects
  *
  * @example Basic type conversion
  * ```javascript
- * import { c_int32, c_float, c_char_p } from 'node-ctypes';
+ * import { c_int32, c_float, c_char_p, CType } from 'node-ctypes';
  *
- * _toNativeType(c_int32);  // Returns "int32"
- * _toNativeType(c_float);  // Returns "float"
- * _toNativeType(c_char_p); // Returns native.types.c_char_p (CType object)
+ * _toNativeType(c_int32);  // Returns CType.INT32 (5)
+ * _toNativeType(c_float);  // Returns CType.FLOAT (9)
+ * _toNativeType(c_char_p); // Returns CType.STRING (12)
  * ```
  *
  * @example Structure type pass-through
@@ -69,21 +71,30 @@
  * _toNativeType(Point); // Returns Point class unchanged
  * ```
  *
+ * @example Direct CType usage
+ * ```javascript
+ * import { CType } from 'node-ctypes';
+ *
+ * _toNativeType(CType.INT32); // Returns 5 (pass-through)
+ * ```
+ *
  * @private
  * @internal
  */
 export function _toNativeType(type, native) {
-  // SimpleCData classes: convert to string type names or native CTypes
+  // SimpleCData classes: return the numeric CType value directly
   if (typeof type === "function" && type._isSimpleCData) {
-    // String pointer types need native CType for automatic conversion
-    // This enables automatic marshalling between C strings and JS strings
-    if (type._type === "char_p") return native.types.c_char_p;
-    if (type._type === "wchar_p") return native.types.c_wchar_p;
-
-    // All other SimpleCData types: use string type name
+    // _type is now a numeric CType value from native.CType
     return type._type;
   }
 
+  // POINTER types: return CType.POINTER (11)
+  // POINTER(baseType) returns an object with _pointerTo property
+  if (type && typeof type === "object" && type._pointerTo !== undefined) {
+    // All pointer types are passed as generic pointers to FFI
+    return native.CType.POINTER;
+  }
+
   // Structure/Union classes: pass through unchanged
   // These are handled specially by the FFI layer
   if (typeof type === "function" && type.prototype) {
@@ -92,6 +103,11 @@ export function _toNativeType(type, native) {
     return type;
   }
 
+  // Numbers (direct CType values): pass through unchanged
+  if (typeof type === "number") {
+    return type;
+  }
+
   // Native CType objects: pass through unchanged (already in correct format)
   return type;
 }
@@ -108,16 +124,16 @@ export function _toNativeType(type, native) {
  *
  * @param {Array|*} types - Array of type specifications, or non-array value
  * @param {Object} native - Native module reference for CType lookups
- * @returns {Array|*} Array of normalized types, or original value if not an array
+ * @returns {Array|*} Array of normalized types (CType values), or original value if not an array
  *
  * @example Function signature normalization
  * ```javascript
- * import { c_int32, c_char_p, c_void_p } from 'node-ctypes';
+ * import { c_int32, c_char_p, c_void_p, CType } from 'node-ctypes';
  *
  * // Normalize function argument types
  * const argTypes = [c_int32, c_char_p, c_void_p];
  * const normalized = _toNativeTypes(argTypes);
- * // Returns ["int32", <native c_char_p CType>, "void_p"]
+ * // Returns [CType.INT32, CType.STRING, CType.POINTER]
  * ```
  *
  * @example Non-array pass-through

package/lib/index.d.ts

@@ -9,14 +9,42 @@
 // Basic Types
 // =============================================================================
 
-/** Native CType object (internal C++ type representation) */
-export interface CType {
-  readonly size: number;
-  readonly name: string;
+/**
+ * CType - Object containing numeric type identifiers
+ * Single source of truth for type values
+ */
+export interface CTypeValues {
+  readonly VOID: number;
+  readonly INT8: number;
+  readonly UINT8: number;
+  readonly INT16: number;
+  readonly UINT16: number;
+  readonly INT32: number;
+  readonly UINT32: number;
+  readonly INT64: number;
+  readonly UINT64: number;
+  readonly FLOAT: number;
+  readonly DOUBLE: number;
+  readonly POINTER: number;
+  readonly STRING: number;
+  readonly WSTRING: number;
+  readonly WCHAR: number;
+  readonly BOOL: number;
+  readonly SIZE_T: number;
+  readonly SSIZE_T: number;
+  readonly LONG: number;
+  readonly ULONG: number;
+  readonly STRUCT: number;
+  readonly UNION: number;
+  readonly ARRAY: number;
+  readonly COUNT: number;
 }
 
-/** Any accepted type specification (CType object or SimpleCData class) */
-export type AnyType = CType | SimpleCDataConstructor;
+/** CType object with numeric type identifiers */
+export const CType: CTypeValues;
+
+/** Any accepted type specification (SimpleCData class, CType value, or struct/union) */
+export type AnyType = SimpleCDataConstructor | number | StructDef | UnionDef;
 
 // =============================================================================
 // Library & Function
@@ -64,6 +92,16 @@ export class CDLL {
   close(): void;
   readonly path: string;
   readonly loaded: boolean;
+  /** Python-like function access: lib.FuncName returns a FunctionWrapper */
+  [funcName: string]: FunctionWrapper | any;
+}
+
+/** FunctionWrapper for Python-like argtypes/restype syntax */
+export interface FunctionWrapper {
+  (...args: any[]): any;
+  argtypes: AnyType[];
+  restype: AnyType;
+  errcheck: ErrcheckCallback | null;
 }
 
 /** WinDLL - stdcall calling convention library (Windows) */
@@ -298,6 +336,7 @@ export function bitfield(baseType: AnyType, bits: number): BitFieldDef;
 export function byref(obj: Buffer | SimpleCDataInstance | { _buffer: Buffer }): Buffer;
 export function cast(ptr: Buffer | bigint, targetType: AnyType | StructDef): Buffer | { [key: string]: any };
 export function POINTER(baseType: AnyType | StructDef): PointerTypeDef;
+export function pointer(obj: SimpleCDataInstance | { _buffer: Buffer }): SimpleCDataInstance & { contents: any; [index: number]: any };
 
 // Error handling
 export function get_errno(): number;
@@ -315,7 +354,7 @@ export function WinError(code?: number): Error & { winerror: number };
 export interface SimpleCDataConstructor {
   new (value?: any): SimpleCDataInstance;
   readonly _size: number;
-  readonly _type: string;
+  readonly _type: number; // CType numeric value from native module
   readonly _isSimpleCData: true;
   _reader(buf: Buffer, offset: number): any;
   _writer(buf: Buffer, offset: number, value: any): void;
@@ -357,6 +396,17 @@ export const c_size_t: SimpleCDataConstructor;
 export const c_long: SimpleCDataConstructor;
 export const c_ulong: SimpleCDataConstructor;
 
+// Python-compatible aliases
+export const c_byte: SimpleCDataConstructor;
+export const c_ubyte: SimpleCDataConstructor;
+export const c_short: SimpleCDataConstructor;
+export const c_ushort: SimpleCDataConstructor;
+export const c_longlong: SimpleCDataConstructor;
+export const c_ulonglong: SimpleCDataConstructor;
+
+/** SimpleCData base class for creating custom simple types */
+export const SimpleCData: SimpleCDataConstructor;
+
 // =============================================================================
 // Constants
 // =============================================================================

package/lib/index.js

@@ -35,39 +35,12 @@ import {
   memmove as _memmove,
   memset as _memset,
 } from "./memory/buffer.js";
-import {
-  readValue as _readValue,
-  writeValue as _writeValue,
-  sizeof as _sizeof,
-} from "./memory/operations.js";
-import {
-  addressOf as _addressOf,
-  byref as _byref,
-  cast as _cast,
-  ptrToBuffer as _ptrToBuffer,
-  POINTER as _POINTER,
-} from "./memory/pointer.js";
-import {
-  get_errno as _get_errno,
-  set_errno as _set_errno,
-  GetLastError as _GetLastError,
-  SetLastError as _SetLastError,
-  FormatError as _FormatError,
-  WinError as _WinError,
-} from "./platform/errors.js";
-import {
-  bitfield as _bitfield,
-  _isStruct,
-  _isArrayType,
-  _isBitField,
-} from "./structures/helpers/common.js";
+import { readValue as _readValue, writeValue as _writeValue, sizeof as _sizeof } from "./memory/operations.js";
+import { addressOf as _addressOf, byref as _byref, cast as _cast, ptrToBuffer as _ptrToBuffer, POINTER as _POINTER, pointer as _pointer } from "./memory/pointer.js";
+import { get_errno as _get_errno, set_errno as _set_errno, GetLastError as _GetLastError, SetLastError as _SetLastError, FormatError as _FormatError, WinError as _WinError } from "./platform/errors.js";
+import { bitfield as _bitfield, _isStruct, _isArrayType, _isBitField } from "./structures/helpers/common.js";
 import { array as _array } from "./structures/helpers/array.js";
-import {
-  _readBitField as _readBitFieldHelper,
-  _writeBitField as _writeBitFieldHelper,
-  _readUintFromBuffer,
-  _writeUintToBuffer,
-} from "./structures/helpers/bitfield.js";
+import { _readBitField as _readBitFieldHelper, _writeBitField as _writeBitFieldHelper, _readUintFromBuffer, _writeUintToBuffer } from "./structures/helpers/bitfield.js";
 import { union as _union } from "./structures/helpers/union.js";
 import { struct as _struct } from "./structures/helpers/struct.js";
 import { createStructureClass } from "./structures/Structure.js";
@@ -140,7 +113,7 @@ const native = require(nativeModulePath);
 _initConstants(native);
 
 // Re-esporta le classi native
-const { Version, Library, FFIFunction, Callback, ThreadSafeCallback, CType, StructType, ArrayType } = native;
+const { Version, Library, FFIFunction, Callback, ThreadSafeCallback, StructType, ArrayType, CType } = native;
 
 // ============================================================================
 // Type Normalization Helpers
@@ -163,13 +136,7 @@ function load(libPath) {
  * Wrapper per funzioni con sintassi Python-like ctypes (argtypes/restype)
  */
 // Create Library classes (FunctionWrapper, CDLL, WinDLL)
-const { FunctionWrapper, CDLL, WinDLL } = createLibraryClasses(
-  Library,
-  LRUCache,
-  _toNativeType,
-  _toNativeTypes,
-  native
-);
+const { FunctionWrapper, CDLL, WinDLL } = createLibraryClasses(Library, LRUCache, _toNativeType, _toNativeTypes, native);
 
 // ============================================================================
 // Callback Functions
@@ -260,6 +227,26 @@ function POINTER(baseType) {
   return _POINTER(baseType, sizeof, alloc, readValue, writeValue, c_void_p, native);
 }
 
+/**
+ * Creates a pointer to an existing ctypes object.
+ * Python ctypes compatible: pointer(obj) returns a pointer to obj.
+ *
+ * @param {Object} obj - Object to create pointer to (must have ._buffer or be a Buffer)
+ * @returns {Object} Pointer instance pointing to obj
+ *
+ * @example
+ * ```javascript
+ * const x = new c_int32(42);
+ * const p = pointer(x);
+ * console.log(p.contents); // 42
+ * p.contents = 100;
+ * console.log(x.value); // 100
+ * ```
+ */
+function pointer(obj) {
+  return _pointer(obj, _POINTER, sizeof, alloc, readValue, writeValue, c_void_p, native);
+}
+
 /**
  * Helper per definire union (tutti i campi condividono offset 0)
  * Supporta nested structs e bitfields come struct()
@@ -304,9 +291,8 @@ function defineUnion(fields) {
 // --------------------------------------------------------------------------
 
 // Create Structure and Union classes with injected dependencies
-const Structure = createStructureClass(alloc, struct);
-const Union = createUnionClass(Structure, union);
-
+const Structure = createStructureClass(alloc, struct, bitfield);
+const Union = createUnionClass(Structure, union, bitfield);
 
 /**
  * Helper per creare array a dimensione fissa (come c_int * 5 in Python)
@@ -412,28 +398,38 @@ function struct(fields, options = {}) {
 const SimpleCData = createSimpleCDataClass(alloc);
 
 // Create all primitive type classes
-const primitiveTypes = createPrimitiveTypes(
-  SimpleCData,
-  native,
-  addressOf,
-  cstring,
-  wstring,
-  readCString,
-  readWString
-);
+const primitiveTypes = createPrimitiveTypes(SimpleCData, native, addressOf, cstring, wstring, readCString, readWString);
 
 // Destructure all types for easy access
 const {
   c_void,
-  c_int8, c_int16, c_int32, c_int64,
-  c_uint8, c_uint16, c_uint32, c_uint64,
-  c_float, c_double,
+  c_int8,
+  c_int16,
+  c_int32,
+  c_int64,
+  c_uint8,
+  c_uint16,
+  c_uint32,
+  c_uint64,
+  c_float,
+  c_double,
   c_bool,
-  c_char, c_wchar,
-  c_void_p, c_char_p, c_wchar_p,
-  c_size_t, c_long, c_ulong,
-  c_byte, c_ubyte, c_short, c_ushort,
-  c_int, c_uint, c_longlong, c_ulonglong,
+  c_char,
+  c_wchar,
+  c_void_p,
+  c_char_p,
+  c_wchar_p,
+  c_size_t,
+  c_long,
+  c_ulong,
+  c_byte,
+  c_ubyte,
+  c_short,
+  c_ushort,
+  c_int,
+  c_uint,
+  c_longlong,
+  c_ulonglong,
 } = primitiveTypes;
 
 // ============================================================================
@@ -523,6 +519,7 @@ export {
   byref,
   cast,
   POINTER,
+  pointer,
 
   // Error handling
   get_errno,