node-ctypes 0.1.3 → 0.1.5

package/README.md

@@ -93,10 +93,20 @@ print(p.x, p.y)  # 10 20
 ```javascript
 import { CDLL, c_int, Structure } from 'node-ctypes';
 
-const libc = new CDLL("libc.so.6");
+// Traditional syntax (always available)
+const libc = new CDLL("libc.so.6"); // Linux
+// const libc = new CDLL('msvcrt.dll');  // Windows
+// const libc = new CDLL('libc.dylib');  // macOS
+
 const abs = libc.func("abs", c_int, [c_int]);
 console.log(abs(-42));  // 42
 
+// Python ctypes-like syntax
+const abs_func = libc.abs;
+abs_func.argtypes = [c_int];
+abs_func.restype = c_int;
+console.log(abs_func(-42));  // 42
+
 class Point extends Structure {
     static _fields_ = [
         ["x", c_int],
@@ -113,23 +123,32 @@ console.log(p.x, p.y);  // 10 20
 ### Basic FFI - Calling C Functions
 
 ```javascript
-import { CDLL, c_int, c_double, c_char_p } from 'node-ctypes';
+import { CDLL, c_int, c_double, c_char_p, c_size_t } from 'node-ctypes';
 
 // Load libc
 const libc = new CDLL('libc.so.6');  // Linux
 // const libc = new CDLL('msvcrt.dll');  // Windows
 // const libc = new CDLL('libc.dylib');  // macOS
 
-// Call abs() - integer absolute value
+// Traditional syntax
 const abs = libc.func('abs', c_int, [c_int]);
 console.log(abs(-42));  // 42
 
+// Python ctypes-like syntax (equivalent!)
+const abs_func = libc.abs;
+abs_func.argtypes = [c_int];
+abs_func.restype = c_int;
+console.log(abs_func(-42));  // 42
+
 // Call strlen() - string length
-const strlen = libc.func('strlen', 'size_t', [c_char_p]);
+const strlen = libc.func('strlen', c_size_t, [c_char_p]);
 console.log(strlen('Hello'));  // 5n (BigInt)
 
 // Load libm for math functions
-const libm = new CDLL('libm.so.6');
+const libm = new CDLL('libm.so.6'); // Linux
+// const libb = new CDLL('ucrtbase.dll'); // Windows
+// const libm = new CDLL('libm.dylib'); // macOS
+
 const sqrt = libm.func('sqrt', c_double, [c_double]);
 console.log(sqrt(16.0));  // 4.0
 ```
@@ -228,10 +247,10 @@ console.log(flags.priority);  // 12
 ### Arrays - Fixed-size and Dynamic
 
 ```javascript
-import { c_int, c_uint8, array } from 'node-ctypes';
+import { c_int32, c_uint8, array } from 'node-ctypes';
 
 // Fixed-size array
-const IntArray = array('int32', 5);
+const IntArray = array(c_int32, 5);
 const arr = IntArray.create([1, 2, 3, 4, 5]);
 
 // Array access
@@ -244,12 +263,12 @@ for (const val of arr) {
 }
 
 // Arrays in structs
-import { Structure, array } from 'node-ctypes';
+import { Structure, array, c_uint8 } from 'node-ctypes';
 
 class Packet extends Structure {
     static _fields_ = [
-        ["header", array("c_uint8", 8)],
-        ["data", array("c_uint8", 256)]
+        ["header", array(c_uint8, 8)],
+        ["data", array(c_uint8, 256)]
     ];
 }
 
@@ -258,7 +277,7 @@ const pkt = new Packet({
     data: new Array(256).fill(0)
 });
 
-console.log(pkt.header);  // [1, 2, 3, 4, 5, 6, 7, 8]
+console.log(pkt.header.toString());  // [1, 2, 3, 4, 5, 6, 7, 8]
 ```
 
 ### Complex Nested Structures
@@ -319,12 +338,13 @@ console.log(img.pixels[1].color.value);  // -16711936 (0xFF00FF00 as signed)
 
 // Union nested in struct - direct property access!
 img.pixels[0].color.rgb.g = 128;  // Works correctly!
+console.log(img.pixels[0].color.rgb.g);  // 128
 ```
 
 ### Callbacks - JavaScript Functions in C
 
 ```javascript
-import { CDLL, callback, c_int, c_void_p, readValue, writeValue, create_string_buffer } from 'node-ctypes';
+import { CDLL, callback, c_int32, c_void, c_void_p, c_size_t, readValue, writeValue, create_string_buffer } from 'node-ctypes';
 
 const libc = new CDLL('msvcrt.dll');  // or libc.so.6 on Linux
 
@@ -332,30 +352,30 @@ const libc = new CDLL('msvcrt.dll');  // or libc.so.6 on Linux
 const compare = callback(
     (a, b) => {
         // a and b are pointers to int32 values
-        const aVal = readValue(a, 'int32');
-        const bVal = readValue(b, 'int32');
+        const aVal = readValue(a, c_int32);
+        const bVal = readValue(b, c_int32);
         return aVal - bVal;
     },
-    c_int,              // return type
+    c_int32,              // return type
     [c_void_p, c_void_p]  // argument types: two pointers
 );
 
 // Sort an array using qsort
-const qsort = libc.func('qsort', 'void', [
+const qsort = libc.func('qsort', c_void, [
     c_void_p,  // array pointer
-    'size_t',  // number of elements
-    'size_t',  // element size
+    c_size_t,  // number of elements
+    c_size_t,  // element size
     c_void_p   // comparison function
 ]);
 
 const arr = create_string_buffer(5 * 4);
 const values = [5, 2, 8, 1, 9];
-values.forEach((v, i) => writeValue(arr, 'int32', v, i * 4));
+values.forEach((v, i) => writeValue(arr, c_int32, v, i * 4));
 qsort(arr, 5, 4, compare.pointer);
 
 // Array is now sorted: [1, 2, 5, 8, 9]
-console.log(readValue(arr, 'int32', 0));  // 1
-console.log(readValue(arr, 'int32', 4));  // 2
+console.log(readValue(arr, c_int32, 0));  // 1
+console.log(readValue(arr, c_int32, 4));  // 2
 
 // IMPORTANT: Release callback when done
 compare.release();
@@ -375,16 +395,16 @@ const sprintf = libc.func('sprintf', c_int, [c_void_p, c_char_p]);
 const buffer = Buffer.alloc(256);
 
 // Pass extra arguments - automatically handled as variadic
-sprintf(buffer, create_string_buffer('Hello %s!'), create_string_buffer('World'));
+sprintf(buffer, 'Hello %s!', 'World');
 console.log(string_at(buffer));  // "Hello World!"
 
-sprintf(buffer, create_string_buffer('Number: %d'), 42);
+sprintf(buffer, 'Number: %d', 42);
 console.log(string_at(buffer));  // "Number: 42"
 
-sprintf(buffer, create_string_buffer('%s: %d + %d = %d'), create_string_buffer('Sum'), 10, 20, 30);
+sprintf(buffer, '%s: %d + %d = %d', 'Sum', 10, 20, 30);
 console.log(string_at(buffer));  // "Sum: 10 + 20 = 30"
 
-sprintf(buffer, create_string_buffer('Pi ≈ %.2f'), 3.14159);
+sprintf(buffer, 'Pi ≈ %.2f', 3.14159);
 console.log(string_at(buffer));  // "Pi ≈ 3.14"
 ```
 
@@ -399,7 +419,7 @@ console.log(string_at(buffer));  // "Pi ≈ 3.14"
 ### Windows API - Full Support
 
 ```javascript
-import { WinDLL, Structure, c_uint16, c_void_p, c_wchar_p, c_int } from 'node-ctypes';
+import { WinDLL, Structure, c_uint16, c_uint32, c_void_p, c_wchar_p, c_int } from 'node-ctypes';
 
 // WinDLL uses __stdcall convention (default for Windows API)
 const kernel32 = new WinDLL('kernel32.dll');
@@ -419,7 +439,7 @@ class SYSTEMTIME extends Structure {
 }
 
 // Get local time
-const GetLocalTime = kernel32.func('GetLocalTime', 'void', [c_void_p]);
+const GetLocalTime = kernel32.func('GetLocalTime', c_void, [c_void_p]);
 
 const st = new SYSTEMTIME();
 GetLocalTime(st);  // Pass struct directly - automatic _buffer extraction!
@@ -433,7 +453,7 @@ const MessageBoxW = user32.func('MessageBoxW', c_int, [
     c_void_p,   // hWnd
     c_wchar_p,  // lpText
     c_wchar_p,  // lpCaption
-    'uint32'    // uType
+    c_uint32    // uType
 ]);
 
 // Create UTF-16 buffers for wide strings
@@ -549,10 +569,18 @@ This section provides a more complete description of the APIs exported from `lib
 
 Example:
 ```js
-import { CDLL } from './lib/index.js';
+import { CDLL, c_int32 } from './lib/index.js';
 const libc = new CDLL(null);
-const abs = libc.func('abs', 'int32', ['int32']);
+
+// Traditional syntax
+const abs = libc.func('abs', c_int32, [c_int32]);
 console.log(abs(-5));
+
+// Python ctypes-like syntax
+const abs_func = libc.abs;
+abs_func.argtypes = [c_int32];
+abs_func.restype = c_int32;
+console.log(abs_func(-5));
 ```
 
 **Detailed CDLL API**
@@ -560,6 +588,7 @@ console.log(abs(-5));
     - automatically extracts `._buffer` from struct objects passed as arguments;
     - exposes non-enumerable metadata: `funcName`, `address`, `_ffi`; 
     - provides the `errcheck` property as getter/setter to intercept return errors.
+- **Python ctypes-like access**: `libc.functionName` returns a wrapper with `argtypes`/`restype`/`errcheck` properties for Python-compatible syntax.
 - `symbol(name)` → `BigInt` : address of a symbol.
 - `close()` : closes the library and clears the cache.
 - `path` (getter) : library path.
@@ -581,9 +610,9 @@ Note: always call `release()` when a callback is no longer needed.
 
 Example string creation and passing to function:
 ```js
-import { create_string_buffer, CDLL } from './lib/index.js';
+import { create_string_buffer, CDLL, c_int32, c_void_p } from './lib/index.js';
 const libc = new CDLL(null);
-const puts = libc.func('puts', 'int32', ['pointer']);
+const puts = libc.func('puts', c_int32, [c_void_p]);
 const s = create_string_buffer('hello');
 puts(s);
 ```
@@ -685,14 +714,14 @@ Base class for Python-like union definitions. Subclasses should define `static _
 | Feature | Python ctypes | node-ctypes |
 |---------|---------------|-------------|
 | **Load library** | `CDLL("lib.so")` | `new CDLL("lib.so")` |
-| **Define function** | `lib.func.argtypes = [c_int]`<br>`lib.func.restype = c_int` | `lib.func("func", c_int, [c_int])` |
+| **Define function** | `lib.func.argtypes = [c_int]`<br>`lib.func.restype = c_int` | `lib.func("func", c_int, [c_int])`<br>**or**<br>`lib.func.argtypes = [c_int]`<br>`lib.func.restype = c_int` |
 | **Structs** | `class Point(Structure):`<br>&nbsp;&nbsp;`_fields_ = [("x", c_int)]` | `class Point extends Structure`<br>&nbsp;&nbsp;`{ static _fields_ = [["x", c_int]] }` |
 | **Unions** | `class U(Union):`<br>&nbsp;&nbsp;`_fields_ = [("i", c_int)]` | `class U extends Union`<br>&nbsp;&nbsp;`{ static _fields_ = [["i", c_int]] }` |
 | **Arrays** | `c_int * 5` | `array(c_int, 5)` |
 | **Bit fields** | `("flags", c_uint, 3)` | `bitfield(c_uint32, 3)` |
 | **Callbacks** | `CFUNCTYPE(c_int, c_int)` | `callback(fn, c_int, [c_int])` |
-| **Strings** | `c_char_p(b"hello")` | `create_string_buffer("hello")` |
-| **Pointers** | `POINTER(c_int)` | `c_void_p` or `"pointer"` |
+| **Strings** | `c_char_p(b"hello")` | `create_string_buffer("hello")`<br>**or**<br>`c_char_p(b"hello")` |
+| **Pointers** | `POINTER(c_int)` | `c_void_p` |
 | **Variadic** | `sprintf(buf, b"%d", 42)` | `sprintf(buf, fmt, 42)` (auto) |
 | **Sizeof** | `sizeof(c_int)` | `sizeof(c_int)` |
 
@@ -715,8 +744,8 @@ Base class for Python-like union definitions. Subclasses should define `static _
 ⚠️ **Differences from Python ctypes**:
 - Structs use `.toObject()` for property access (eager loading for performance)
 - Callbacks must be manually released with `.release()`
-- Function definition is combined: `func(name, returnType, argTypes)` vs separate argtypes/restype
-- No `POINTER()` type - use `c_void_p` or type name string
+- **Function definition supports both syntaxes**: `func(name, returnType, argTypes)` **or** `func.argtypes = [...]; func.restype = ...`
+- No `POINTER()` type - use `c_void_p`
 
 
 ## Limitations & Known Issues

package/lib/index.d.ts

@@ -108,12 +108,7 @@ export class Version {
 /** Native library handle */
 export class Library {
   constructor(path: string | null);
-  func(
-    name: string,
-    returnType: CTypeString | CType,
-    argTypes?: (CTypeString | CType)[],
-    options?: FunctionOptions,
-  ): FFIFunction;
+  func(name: string, returnType: CTypeString | CType, argTypes?: (CTypeString | CType)[], options?: FunctionOptions): FFIFunction;
   symbol(name: string): bigint;
   close(): void;
   readonly path: string;
@@ -126,11 +121,7 @@ export interface FunctionOptions {
 }
 
 /** Errcheck callback type */
-export type ErrcheckCallback = (
-  result: any,
-  func: CallableFunction,
-  args: any[],
-) => any;
+export type ErrcheckCallback = (result: any, func: CallableFunction, args: any[]) => any;
 
 /** FFI function wrapper */
 export interface FFIFunction {
@@ -143,12 +134,7 @@ export interface FFIFunction {
 /** CDLL - C calling convention library */
 export class CDLL {
   constructor(path: string | null);
-  func(
-    name: string,
-    returnType: CTypeString | CType,
-    argTypes?: (CTypeString | CType)[],
-    options?: FunctionOptions,
-  ): CallableFunction & { errcheck: ErrcheckCallback | null };
+  func(name: string, returnType: CTypeString | CType, argTypes?: (CTypeString | CType)[], options?: FunctionOptions): CallableFunction & { errcheck: ErrcheckCallback | null };
   symbol(name: string): bigint;
   close(): void;
   readonly path: string;
@@ -172,11 +158,7 @@ export interface CallbackWrapper {
 
 /** Native Callback class */
 export class Callback {
-  constructor(
-    fn: Function,
-    returnType: CTypeString | CType,
-    argTypes?: (CTypeString | CType)[],
-  );
+  constructor(fn: Function, returnType: CTypeString | CType, argTypes?: (CTypeString | CType)[]);
   readonly pointer: bigint;
   release(): void;
 }
@@ -220,31 +202,11 @@ export interface StructDef {
 }
 
 // Helper types for improved typed structs
-export type FieldSpec =
-  | CTypeString
-  | CType
-  | StructDef
-  | ArrayTypeDef
-  | BitFieldDef
-  | AnonymousField;
+export type FieldSpec = CTypeString | CType | StructDef | ArrayTypeDef | BitFieldDef | AnonymousField;
 
 type JsFromCType<T> = T extends "int64" | "uint64" | "size_t"
   ? bigint
-  : T extends
-        | "int8"
-        | "uint8"
-        | "int16"
-        | "uint16"
-        | "int32"
-        | "uint32"
-        | "int"
-        | "uint"
-        | "short"
-        | "ushort"
-        | "char"
-        | "uchar"
-        | "float"
-        | "double"
+  : T extends "int8" | "uint8" | "int16" | "uint16" | "int32" | "uint32" | "int" | "uint" | "short" | "ushort" | "char" | "uchar" | "float" | "double"
     ? number
     : T extends "bool"
       ? boolean
@@ -331,10 +293,7 @@ export interface PointerTypeDef {
 /** Native StructType class */
 export class StructType {
   constructor(isUnion?: boolean);
-  addField(
-    name: string,
-    type: CTypeString | CType | StructType | ArrayType,
-  ): this;
+  addField(name: string, type: CTypeString | CType | StructType | ArrayType): this;
   getSize(): number;
   getAlignment(): number;
   create(values?: Record<string, any>): Buffer;
@@ -355,28 +314,17 @@ export class ArrayType {
  * Subclasses should define `static _fields_` as array of [name, type]
  * or an object map { name: type }.
  */
-export class Structure<
-  F extends Record<string, FieldSpec> = Record<string, any>,
-> {
+export class Structure<F extends Record<string, FieldSpec> = Record<string, any>> {
   constructor(...args: any[]);
   static _fields_?: Array<[string, FieldSpec]> | Record<string, FieldSpec>;
   static _pack_?: boolean;
   static _anonymous_?: string[];
-  static create<ThisT extends Structure<F>>(
-    this: new (...args: any[]) => ThisT,
-    values?: Partial<FieldsToInstance<F>> | Buffer,
-  ): ThisT;
-  static toObject<ThisT extends Structure<F>>(
-    this: new (...args: any[]) => ThisT,
-    buf: Buffer | any,
-  ): FieldsToInstance<F>;
+  static create<ThisT extends Structure<F>>(this: new (...args: any[]) => ThisT, values?: Partial<FieldsToInstance<F>> | Buffer): ThisT;
+  static toObject<ThisT extends Structure<F>>(this: new (...args: any[]) => ThisT, buf: Buffer | any): FieldsToInstance<F>;
   _buffer: Buffer;
   _structDef: StructDef;
   get<K extends keyof F & string>(fieldName: K): FieldsToInstance<F>[K];
-  set<K extends keyof F & string>(
-    fieldName: K,
-    value: FieldsToInstance<F>[K],
-  ): void;
+  set<K extends keyof F & string>(fieldName: K, value: FieldsToInstance<F>[K]): void;
   toObject(): FieldsToInstance<F>;
   [field: string]: any; // instance has dynamic properties for fields
 }
@@ -384,9 +332,7 @@ export class Structure<
 /**
  * Python-like Union base class.
  */
-export class Union<
-  F extends Record<string, FieldSpec> = Record<string, any>,
-> extends Structure<F> {}
+export class Union<F extends Record<string, FieldSpec> = Record<string, any>> extends Structure<F> {}
 
 // =============================================================================
 // Functions
@@ -396,85 +342,36 @@ export class Union<
 export function load(path: string | null): Library;
 
 // Callbacks
-export function callback(
-  fn: Function,
-  returnType: CTypeString | CType,
-  argTypes?: (CTypeString | CType)[],
-): CallbackWrapper;
-export function threadSafeCallback(
-  fn: Function,
-  returnType: CTypeString | CType,
-  argTypes?: (CTypeString | CType)[],
-): CallbackWrapper;
+export function callback(fn: Function, returnType: CTypeString | CType, argTypes?: (CTypeString | CType)[]): CallbackWrapper;
+export function threadSafeCallback(fn: Function, returnType: CTypeString | CType, argTypes?: (CTypeString | CType)[]): CallbackWrapper;
 
 // Memory management - Python-compatible
 export function create_string_buffer(init: number | string | Buffer): Buffer;
 export function create_unicode_buffer(init: number | string): Buffer;
-export function string_at(
-  address: Buffer | bigint | number,
-  size?: number,
-): string | null;
-export function wstring_at(
-  address: Buffer | bigint | number,
-  size?: number,
-): string | null;
+export function string_at(address: Buffer | bigint | number, size?: number): string | null;
+export function wstring_at(address: Buffer | bigint | number, size?: number): string | null;
 export function addressof(ptr: Buffer | bigint | number): bigint;
 export function memmove(dst: Buffer, src: Buffer | bigint, count: number): void;
 export function memset(dst: Buffer, value: number, count: number): void;
 
 // Memory - utility (no direct Python equivalent)
-export function readValue(
-  ptr: Buffer | bigint | number,
-  type: CTypeString | CType,
-  offset?: number,
-): any;
-export function writeValue(
-  ptr: Buffer | bigint | number,
-  type: CTypeString | CType,
-  value: any,
-  offset?: number,
-): number;
-export function sizeof(
-  type: CTypeString | CType | StructDef | ArrayTypeDef,
-): number;
+export function readValue(ptr: Buffer | bigint | number, type: CTypeString | CType, offset?: number): any;
+export function writeValue(ptr: Buffer | bigint | number, type: CTypeString | CType, value: any, offset?: number): number;
+export function sizeof(type: CTypeString | CType | StructDef | ArrayTypeDef): number;
 export function ptrToBuffer(address: bigint | number, size: number): Buffer;
 
 // Structures
-export function struct(
-  fields: Record<
-    string,
-    | CTypeString
-    | CType
-    | StructDef
-    | ArrayTypeDef
-    | BitFieldDef
-    | AnonymousField
-  >,
-  options?: StructOptions,
-): StructDef;
-export function union(
-  fields: Record<
-    string,
-    CTypeString | CType | StructDef | ArrayTypeDef | BitFieldDef
-  >,
-): UnionDef;
+export function struct(fields: Record<string, CTypeString | CType | StructDef | ArrayTypeDef | BitFieldDef | AnonymousField>, options?: StructOptions): StructDef;
+export function union(fields: Record<string, CTypeString | CType | StructDef | ArrayTypeDef | BitFieldDef>): UnionDef;
 // Factory helpers that return a typed class extending Structure/Union
-export function defineStruct<F extends Record<string, FieldSpec>>(
-  fields: F,
-  options?: StructOptions,
-): new (...args: any[]) => Structure<F>;
-export function defineUnion<F extends Record<string, FieldSpec>>(
-  fields: F,
-): new (...args: any[]) => Union<F>;
+export function defineStruct<F extends Record<string, FieldSpec>>(fields: F, options?: StructOptions): new (...args: any[]) => Structure<F>;
+export function defineUnion<F extends Record<string, FieldSpec>>(fields: F): new (...args: any[]) => Union<F>;
 export function array(elementType: CTypeString, count: number): ArrayTypeDef;
 export function bitfield(baseType: CTypeString, bits: number): BitFieldDef;
 
 // Pointers
 export function byref(obj: Buffer): Buffer;
-export function cast(
-  ptr: Buffer | bigint,
-  targetType: CTypeString | StructDef,
-): any;
+export function cast(ptr: Buffer | bigint, targetType: CTypeString | StructDef): any;
 export function POINTER(baseType: CTypeString | StructDef): PointerTypeDef;
 
 // Error handling