node-ctypes 1.5.0 → 1.7.0

package/README.md

@@ -5,907 +5,282 @@
 [![Build](https://github.com/dmazzella/node-ctypes/actions/workflows/build.yml/badge.svg)](https://github.com/dmazzella/node-ctypes/actions/workflows/build.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-**Python ctypes for Node.js** - A high-performance FFI (Foreign Function Interface) library with full Python ctypes compatibility, built on [libffi](https://github.com/libffi/libffi) and [N-API](https://nodejs.org/api/n-api.html).
+**Python ctypes for Node.js** — A foreign function interface library that mirrors the Python ctypes API, built on [libffi](https://github.com/libffi/libffi) and [N-API](https://nodejs.org/api/n-api.html).
 
-## Why node-ctypes?
-
-- ✨ **Python ctypes API Compatibility** - If you know Python ctypes, you already know node-ctypes! Same syntax, same patterns.
-- 🚀 **High Performance** - Up to **50x faster** than ffi-napi, with struct operations matching or exceeding koffi performance.
-- 🔧 **Complete FFI Support** - Structs, unions, bit fields, nested structures, arrays, callbacks, variadic functions, and more.
-- 🌍 **Cross-platform** - Works seamlessly on Linux, macOS, and Windows with identical API.
-
-## Features
-
-- 🐍 **Full Python ctypes compatibility** - Struct definitions, unions, bit fields, anonymous fields
-- 📚 **Load shared libraries** (.so, .dll, .dylib) with CDLL and WinDLL
-- 🔄 **Variadic functions** (printf, sprintf) with automatic detection
-- 📞 **Callbacks** - JavaScript functions callable from C code
-- 🏗️ **Complex data structures** - Nested structs, unions in structs, arrays in structs
-- ⚡ **High performance** - Eager loading for struct properties, optimized FFI wrapper
-- 🔍 **Transparent API** - Pass struct objects directly to FFI functions
-- 🔧 **Extended type support** - All ctypes types (int8, uint8, int16, uint16, etc.)
-- 📊 **Memory utilities** - readValue/writeValue for direct memory access, enhanced sizeof
-- 🏗️ **Advanced array support** - String initialization, improved proxy behavior
+If you know Python ctypes, you already know node-ctypes.
 
 ## Installation
 
-### From npm (recommended)
-
 ```bash
 npm install node-ctypes
 ```
 
-Prebuilt binaries are available for:
-- Windows x64, ARM64
-- Linux x64, ARM64
-- macOS x64, ARM64
+Prebuilt binaries for Windows, Linux, and macOS (x64/ARM64).
 
-### From source
+<details>
+<summary>Build from source</summary>
 
-#### Prerequisites
+Requires Node.js >= 16, CMake >= 3.15, and a C++ compiler.
 
-- Node.js >= 16
-- CMake >= 3.15
-- C++ compiler (GCC, Clang, or MSVC)
-
-#### Ubuntu/Debian
-```bash
-sudo apt install build-essential cmake
-```
-
-#### macOS
-```bash
-brew install cmake
-```
-
-#### Windows
-- Install Visual Studio Build Tools
-- Install CMake
-
-#### Build
 ```bash
 npm install
 npm run build
 ```
+</details>
 
-## Quick Start - Python ctypes Users
+## Python ctypes vs node-ctypes
 
-If you're familiar with Python ctypes, you'll feel right at home:
+### Loading libraries and calling functions
 
-**Python ctypes:**
+**Python:**
 ```python
-from ctypes import CDLL, c_int, Structure
+from ctypes import CDLL, c_int
 
 libc = CDLL("libc.so.6")
 abs_func = libc.abs
 abs_func.argtypes = [c_int]
 abs_func.restype = c_int
 print(abs_func(-42))  # 42
-
-class Point(Structure):
-    _fields_ = [("x", c_int), ("y", c_int)]
-
-p = Point(10, 20)
-print(p.x, p.y)  # 10 20
 ```
 
-**node-ctypes (identical patterns!):**
+**Node.js:**
 ```javascript
-import { CDLL, c_int, Structure } from 'node-ctypes';
+import { CDLL, c_int } from 'node-ctypes';
 
-// Traditional syntax (always available)
-const libc = new CDLL("libc.so.6"); // Linux
+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],
-        ["y", c_int]
-    ];
-}
-
-const p = new Point(10, 20);
-console.log(p.x, p.y);  // 10 20
 ```
 
-## Usage
+A traditional syntax is also available: `libc.func("abs", c_int, [c_int])`.
 
-### Basic FFI - Calling C Functions
-
-```javascript
-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
-
-// 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
+### Structures
 
-// Call strlen() - string length
-const strlen = libc.func('strlen', c_size_t, [c_char_p]);
-console.log(strlen('Hello'));  // 5n (BigInt)
+**Python:**
+```python
+from ctypes import Structure, c_int, c_uint32
 
-// Load libm for math functions
-const libm = new CDLL('libm.so.6'); // Linux
-// const libb = new CDLL('ucrtbase.dll'); // Windows
-// const libm = new CDLL('libm.dylib'); // macOS
+class Point(Structure):
+    _fields_ = [("x", c_int), ("y", c_int)]
 
-const sqrt = libm.func('sqrt', c_double, [c_double]);
-console.log(sqrt(16.0));  // 4.0
+p = Point(10, 20)
+print(p.x, p.y)  # 10 20
 ```
 
-### Structs - Full Python ctypes Compatibility
-
+**Node.js:**
 ```javascript
 import { Structure, c_int, c_uint32 } from 'node-ctypes';
 
-// Simple struct - Python-like class syntax
 class Point extends Structure {
-    static _fields_ = [
-        ["x", c_int],
-        ["y", c_int]
-    ];
+    static _fields_ = [["x", c_int], ["y", c_int]];
 }
 
-// Create and initialize - direct property access!
 const p = new Point(10, 20);
 console.log(p.x, p.y);  // 10 20
-
-// Modify properties directly
-p.x = 100;
-console.log(p.x);  // 100
-
-// Get struct size
-console.log(Point.size);  // 8
-
-// Nested structs
-class Rectangle extends Structure {
-    static _fields_ = [
-        ["topLeft", Point],
-        ["bottomRight", Point],
-        ["color", c_uint32]
-    ];
-}
-
-const rect = new Rectangle({
-    topLeft: { x: 0, y: 0 },
-    bottomRight: { x: 100, y: 200 },
-    color: 0xff0000
-});
-
-console.log(rect.topLeft.x);      // 0
-console.log(rect.bottomRight.x);  // 100
-console.log(rect.color);          // 16711680
 ```
 
-### Unions - Shared Memory Regions
+Nested structs, unions, bit fields, and anonymous fields all work the same way.
+
+### Unions
 
 ```javascript
 import { Union, c_int, c_float } from 'node-ctypes';
 
-// Union - all fields share the same memory
 class IntOrFloat extends Union {
-    static _fields_ = [
-        ["i", c_int],
-        ["f", c_float]
-    ];
+    static _fields_ = [["i", c_int], ["f", c_float]];
 }
 
 const u = new IntOrFloat();
 u.f = 3.14159;
 console.log(u.i);  // Bit pattern of float as integer
-
-u.i = 42;
-console.log(u.f);  // 42 reinterpreted as float
-```
-
-### Bit Fields - Compact Data Structures
-
-```javascript
-import { Structure, c_uint32 } from 'node-ctypes';
-
-// Bit fields using Python-style syntax: [name, type, bits]
-class Flags extends Structure {
-    static _fields_ = [
-        ["enabled", c_uint32, 1],   // 1 bit
-        ["mode", c_uint32, 3],      // 3 bits
-        ["priority", c_uint32, 4],  // 4 bits
-        ["reserved", c_uint32, 24]  // 24 bits
-    ];
-}
-
-const flags = new Flags();
-
-flags.enabled = 1;
-flags.mode = 5;
-flags.priority = 12;
-
-console.log(flags.enabled);   // 1
-console.log(flags.mode);      // 5
-console.log(flags.priority);  // 12
 ```
 
-**Alternative syntax with `bitfield()` helper:**
+### Arrays
 
 ```javascript
-import { Structure, bitfield, c_uint32 } from 'node-ctypes';
+import { array, c_int32 } from 'node-ctypes';
 
-class Flags extends Structure {
-    static _fields_ = [
-        ["enabled", bitfield(c_uint32, 1)],
-        ["mode", bitfield(c_uint32, 3)],
-    ];
-}
-```
-
-### Arrays - Fixed-size and Dynamic
-
-```javascript
-import { c_int32, c_uint8, array } from 'node-ctypes';
-
-// Fixed-size array
 const IntArray = array(c_int32, 5);
 const arr = IntArray.create([1, 2, 3, 4, 5]);
-
-// Array access
 console.log(arr[0]);  // 1
-console.log(arr[4]);  // 5
-
-// Iterate
-for (const val of arr) {
-    console.log(val);
-}
-
-// Arrays in structs
-import { Structure, array, c_uint8 } from 'node-ctypes';
-
-class Packet extends Structure {
-    static _fields_ = [
-        ["header", array(c_uint8, 8)],
-        ["data", array(c_uint8, 256)]
-    ];
-}
-
-const pkt = new Packet({
-    header: [0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08],
-    data: new Array(256).fill(0)
-});
-
-console.log(pkt.header.toString());  // [1, 2, 3, 4, 5, 6, 7, 8]
 ```
 
-### Complex Nested Structures
-
-Real-world example from our test suite:
+### Pointers
 
 ```javascript
-import { Structure, Union, c_uint8, c_uint16, c_int32, array } from 'node-ctypes';
+import { POINTER, pointer, c_int32 } from 'node-ctypes';
 
-// RGB color components
-class RGB extends Structure {
-    static _fields_ = [
-        ["r", c_uint8],
-        ["g", c_uint8],
-        ["b", c_uint8],
-        ["a", c_uint8]
-    ];
-}
+const IntPtr = POINTER(c_int32);
+const buf = Buffer.alloc(4);
+buf.writeInt32LE(42, 0);
 
-// Union for color access (as RGB or as 32-bit value)
-class Color extends Union {
-    static _fields_ = [
-        ["rgb", RGB],
-        ["value", c_int32]
-    ];
-}
+const p = IntPtr.fromBuffer(buf);
+console.log(p.contents);  // 42 (like *p in C)
+console.log(p[0]);        // 42 (like p[0] in C)
 
-// Pixel with position and color
-class Pixel extends Structure {
-    static _fields_ = [
-        ["x", c_uint16],
-        ["y", c_uint16],
-        ["color", Color]
-    ];
-}
+// pointer() function
+const x = new c_int32(42);
+const px = pointer(x);
+console.log(px.contents);  // 42
 
-// Image with array of pixels
-class Image extends Structure {
-    static _fields_ = [
-        ["width", c_uint16],
-        ["height", c_uint16],
-        ["pixels", array(Pixel, 2)]
-    ];
-}
+// fromAddress() — typed access to native memory
+const pValues = POINTER(MyStruct).fromAddress(nativeAddr);
+console.log(pValues[0].field);  // pointer arithmetic (like pValues[0] in C)
+console.log(pValues[5].field);  // pValues + 5 * sizeof(MyStruct)
 
-// Create and manipulate
-const img = new Image({
-    width: 640,
-    height: 480,
-    pixels: [
-        { x: 10, y: 20, color: { rgb: { r: 255, g: 0, b: 0, a: 255 } } },
-        { x: 30, y: 40, color: { value: 0xFF00FF00 } }
-    ]
-});
-
-console.log(img.pixels[0].color.rgb.r);  // 255
-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
+// cast() to POINTER — Python: cast(c_void_p(addr), POINTER(MyStruct))
+const pData = cast(rawAddr, POINTER(MyStruct));
+console.log(pData[0].field);  // same result as fromAddress()
 ```
 
-### Callbacks - JavaScript Functions in C
+### Callbacks
 
 ```javascript
-import { CDLL, callback, c_int32, c_void, c_void_p, c_size_t, readValue, writeValue, create_string_buffer } from 'node-ctypes';
+import { callback, c_int32, c_void_p, readValue } from 'node-ctypes';
 
-const libc = new CDLL('msvcrt.dll');  // or libc.so.6 on Linux
-
-// Create a comparison callback for qsort
 const compare = callback(
-    (a, b) => {
-        // a and b are pointers to int32 values
-        const aVal = readValue(a, c_int32);
-        const bVal = readValue(b, c_int32);
-        return aVal - bVal;
-    },
-    c_int32,              // return type
-    [c_void_p, c_void_p]  // argument types: two pointers
+    (a, b) => readValue(a, c_int32) - readValue(b, c_int32),
+    c_int32, [c_void_p, c_void_p]
 );
 
-// Sort an array using qsort
-const qsort = libc.func('qsort', c_void, [
-    c_void_p,  // array pointer
-    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, c_int32, v, i * 4));
-qsort(arr, 5, 4, compare.pointer);
-
-// Array is now sorted: [1, 2, 5, 8, 9]
-console.log(readValue(arr, c_int32, 0));  // 1
-console.log(readValue(arr, c_int32, 4));  // 2
-
-// IMPORTANT: Release callback when done
-compare.release();
+// Use with qsort, etc.
+compare.release();  // Release when done
 ```
 
-### Variadic Functions - printf, sprintf
+`CFUNCTYPE(restype, ...argtypes)` is also supported for Python-compatible function pointer types.
 
-```javascript
-import { CDLL, create_string_buffer, string_at, c_int, c_void_p, c_char_p } from 'node-ctypes';
+### Variadic functions
 
-const libc = new CDLL('msvcrt.dll');  // Windows
-// const libc = new CDLL('libc.so.6');  // Linux
+```javascript
+import { CDLL, c_int, c_void_p, c_char_p, string_at } from 'node-ctypes';
 
-// Define only the fixed parameters - variadic args detected automatically!
+const libc = new CDLL('libc.so.6');  // Linux
+// const libc = new CDLL('msvcrt.dll');  // Windows
+// const libc = new CDLL('libc.dylib');  // macOS
 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, 'Hello %s!', 'World');
-console.log(string_at(buffer));  // "Hello World!"
-
-sprintf(buffer, 'Number: %d', 42);
-console.log(string_at(buffer));  // "Number: 42"
-
-sprintf(buffer, '%s: %d + %d = %d', 'Sum', 10, 20, 30);
-console.log(string_at(buffer));  // "Sum: 10 + 20 = 30"
-
-sprintf(buffer, 'Pi ≈ %.2f', 3.14159);
-console.log(string_at(buffer));  // "Pi ≈ 3.14"
+const buf = Buffer.alloc(256);
+sprintf(buf, 'Hello %s! %d', 'World', 42);  // Extra args auto-detected
+console.log(string_at(buf));  // "Hello World! 42"
 ```
 
-**Automatic variadic detection** - When you pass more arguments than specified, node-ctypes:
-- ✅ Detects the extra arguments
-- ✅ Infers their types (string → char*, number → int32/double, Buffer → pointer)
-- ✅ Uses `ffi_prep_cif_var` for variadic call preparation
-- ✅ Calls the function with correct argument marshalling
-
-**This matches Python ctypes behavior exactly!**
-
-### Windows API - Full Support
+### Windows API
 
 ```javascript
-import { WinDLL, Structure, c_uint16, c_uint32, c_void_p, c_wchar_p, c_int } from 'node-ctypes';
+import { WinDLL, Structure, c_uint16, c_void, c_void_p } from 'node-ctypes';
 
-// WinDLL uses __stdcall convention (default for Windows API)
-const kernel32 = new WinDLL('kernel32.dll');
+const kernel32 = new WinDLL('kernel32.dll');  // Uses __stdcall
 
-// SYSTEMTIME structure (from tests/windows/test_winapi.js)
 class SYSTEMTIME extends Structure {
     static _fields_ = [
-        ["wYear", c_uint16],
-        ["wMonth", c_uint16],
-        ["wDayOfWeek", c_uint16],
-        ["wDay", c_uint16],
-        ["wHour", c_uint16],
-        ["wMinute", c_uint16],
-        ["wSecond", c_uint16],
-        ["wMilliseconds", c_uint16]
+        ["wYear", c_uint16], ["wMonth", c_uint16],
+        ["wDayOfWeek", c_uint16], ["wDay", c_uint16],
+        ["wHour", c_uint16], ["wMinute", c_uint16],
+        ["wSecond", c_uint16], ["wMilliseconds", c_uint16]
     ];
 }
 
-// Get local time
 const GetLocalTime = kernel32.func('GetLocalTime', c_void, [c_void_p]);
-
 const st = new SYSTEMTIME();
-GetLocalTime(st);  // Pass struct directly - automatic _buffer extraction!
-
+GetLocalTime(st);
 console.log(`${st.wYear}-${st.wMonth}-${st.wDay}`);
-console.log(`${st.wHour}:${st.wMinute}:${st.wSecond}`);
-
-// MessageBox (wide string version)
-const user32 = new WinDLL('user32.dll');
-const MessageBoxW = user32.func('MessageBoxW', c_int, [
-    c_void_p,   // hWnd
-    c_wchar_p,  // lpText
-    c_wchar_p,  // lpCaption
-    c_uint32    // uType
-]);
-
-// Create UTF-16 buffers for wide strings
-const text = Buffer.from('Hello from node-ctypes!\0', 'utf16le');
-const caption = Buffer.from('node-ctypes\0', 'utf16le');
-
-MessageBoxW(null, text, caption, 0);
 ```
 
-### Memory Operations - Low-level Control
-
-```javascript
-import { readValue, writeValue, sizeof, create_string_buffer, string_at, c_int, c_double, c_void_p } from 'node-ctypes';
-
-// Allocate memory
-const buf = Buffer.alloc(16);
-
-// Write values at specific offsets
-writeValue(buf, c_int, 12345, 0);
-writeValue(buf, c_double, 3.14159, 8);
-
-// Read values back
-console.log(readValue(buf, c_int, 0));     // 12345
-console.log(readValue(buf, c_double, 8));  // 3.14159
-
-// Get type sizes
-console.log(sizeof(c_int));      // 4
-console.log(sizeof(c_double));   // 8
-console.log(sizeof(c_void_p));   // 8 (on 64-bit)
-
-// String handling
-const str = create_string_buffer('Hello, World!');
-console.log(string_at(str));  // "Hello, World!"
-```
-
-## Performance Benchmarks
-
-Benchmarked on Windows with Node.js v24.11.0:
+## API Compatibility Reference
 
-**vs koffi** (comprehensive 10-benchmark comparison, geometric mean: **3.27x slower**):
-- Simple int32 function: 1.74x slower
-- String parameter: 1.95x slower  
-- Floating point: 1.83x slower
-- No arguments: 2.11x slower
-- Multiple arguments: **1.40x faster**
-- Variadic function: 1.28x slower
-- **Struct read/write: 14.91x slower**
-- Buffer allocation: 40.5% overhead
-- Raw vs CDLL wrapper: 7.3% overhead
-- **Callback creation: 1.51x slower**
-
-**Key Insights:**
-- koffi excels at simple operations and struct access
-- node-ctypes competitive on complex argument handling
-- **Struct performance gap**: koffi ~13x faster due to plain object vs Proxy+N-API
-- **Workaround**: Use `toObject()` for repeated struct reads (see below)
-- **Callback overhead**: koffi 1.5x faster at callback creation
-
-### Struct Performance Tip
-
-When reading struct fields repeatedly (e.g., in a tight loop), use `toObject()` to convert to a plain JavaScript object:
-
-```javascript
-const point = Point.create({ x: 10, y: 20 });
-
-// ❌ Slow: Each access goes through Proxy → N-API → buffer read
-for (let i = 0; i < 1000000; i++) {
-  const x = point.x;  // ~80ns per access
-}
-
-// ✅ Fast: Convert once, then use plain object access
-const obj = point.toObject();  // { x: 10, y: 20 }
-for (let i = 0; i < 1000000; i++) {
-  const x = obj.x;  // ~6ns per access (same as koffi!)
-}
-```
-
-**When to use direct access vs toObject():**
-- **Direct access (`point.x`)**: Always synchronized with underlying buffer; required when C code modifies the buffer
-- **`toObject()`**: Snapshot copy; use for read-only loops or when passing data to JS-only code
-
-**Transparent API overhead**: Only **3.5%** for auto `._buffer` extraction!
-
-*See `tests/benchmarks/` for full benchmark suite.*
+| Feature | Python ctypes | node-ctypes |
+|---------|---------------|-------------|
+| Load library | `CDLL("lib.so")` | `new CDLL("lib.so")` |
+| Function setup | `f.argtypes = [c_int]` | `f.argtypes = [c_int]` |
+| Structs | `class P(Structure):` | `class P extends Structure` |
+| Unions | `class U(Union):` | `class U extends Union` |
+| Arrays | `c_int * 5` | `array(c_int, 5)` |
+| Bit fields | `("f", c_uint, 3)` | `["f", c_uint32, 3]` |
+| Callbacks | `CFUNCTYPE(c_int, c_int)` | `CFUNCTYPE(c_int, c_int)` |
+| Pointers | `POINTER(c_int)` / `pointer(obj)` | `POINTER(c_int)` / `pointer(obj)` |
+| Sizeof | `sizeof(c_int)` | `sizeof(c_int)` |
+| Alignment | `alignment(c_int)` | `alignment(c_int)` |
+| Strings | `c_char_p(b"hello")` | `create_string_buffer("hello")` |
+| Variadic | `sprintf(buf, b"%d", 42)` | `sprintf(buf, "%d", 42)` |
+| Errno | `get_errno()` | `get_errno()` |
+| byref | `byref(obj)` | `byref(obj)` |
+| cast | `cast(ptr, type)` | `cast(ptr, type)` (supports `POINTER()` target) |
 
 ## Supported Types
 
-| Type Name | Aliases | Size |
-|-----------|---------|------|
-| `void` | - | 0 |
-| `int8` | `c_int8`, `char` | 1 |
-| `uint8` | `c_uint8`, `uchar` | 1 |
-| `int16` | `c_int16`, `short` | 2 |
-| `uint16` | `c_uint16`, `ushort` | 2 |
-| `int32` | `c_int32`, `int`, `c_int` | 4 |
-| `uint32` | `c_uint32`, `uint`, `c_uint` | 4 |
-| `int64` | `c_int64`, `long long` | 8 |
-| `uint64` | `c_uint64` | 8 |
-| `float` | `c_float` | 4 |
-| `double` | `c_double` | 8 |
-| `pointer` | `c_void_p`, `void*`, `ptr` | 8 (64-bit) |
-| `string` | `c_char_p`, `char*` | pointer |
-| `bool` | `c_bool` | 1 |
-| `size_t` | `c_size_t` | pointer |
-
-## API Reference
-
-### Classes
-
-#### `CDLL(libPath)`
-Load a shared library using default (cdecl) calling convention.
-
-#### `WinDLL(libPath)`
-Load a shared library using stdcall calling convention (Windows).
-
-#### `Library(libPath)`
-Low-level library wrapper.
-
----
-
-## Detailed API Reference (from lib/index.js)
-
-This section provides a more complete description of the APIs exported from `lib/index.js`, with quick examples and usage notes.
-
-**Native classes and exports**
-- `Version` - Version information exposed by the native module.
-- `Library` - Represents a loaded native library and exposes low-level functions for symbols and library management.
-- `FFIFunction` - Low-level object representing an FFI function (has properties like `address` and internal methods).
-- `Callback` - Builds JS callbacks callable from C (main thread).
-- `ThreadSafeCallback` - Builds thread-safe JS callbacks (can be called from external threads).
-- `CType`, `StructType`, `ArrayType` - Types and helpers exposed by the native layer.
-
-**Library loading and wrappers**
-- `load(libPath)` → `Library` : loads a native library; `libPath` can be `null` for the current executable.
-- `CDLL(libPath)` : common-use wrapper for C calls with cdecl convention; maintains a function cache and provides more convenient `func()`.
-- `WinDLL(libPath)` : like `CDLL` but with `abi: 'stdcall'` by default (useful for WinAPI).
-
-Example:
-```js
-import { CDLL, c_int32 } from './lib/index.js';
-const libc = new CDLL(null);
-
-// 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**
-- `func(name, returnType, argTypes = [], options = {})` → `Function` : gets a callable function. The returned function is optimized and:
-    - 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.
-- `loaded` (getter) : loading status.
-
-**Callback**
-- `callback(fn, returnType, argTypes = [])` → `{ pointer, release(), _callback }` : fast callback, main thread only.
-- `threadSafeCallback(fn, returnType, argTypes = [])` → `{ pointer, release(), _callback }` : thread-safe callback for external threads.
-
-Note: always call `release()` when a callback is no longer needed.
-
-**Allocation and strings**
-
-- `Buffer.alloc(size)` → `Buffer` : allocates native memory.
-- `create_string_buffer(init)` → `Buffer` : creates null-terminated C string (init: size|string|Buffer).
-- `create_unicode_buffer(init)` → `Buffer` : creates null-terminated wide string (wchar_t).
-- `ptrToBuffer(address, size)` → `Buffer` : view on native address (use with caution).
-- `addressof(ptr)` → `BigInt` : get the address as BigInt.
-
-Example string creation and passing to function:
-```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', c_int32, [c_void_p]);
-const s = create_string_buffer('hello');
-puts(s);
-```
-
-**Reading and writing values**
-- `readValue(ptr, type, offset = 0)` : supports fast-path for Buffer + basic types (`int8`, `uint8`, `int16`, `int32`, `int64`, `float`, `double`, `bool`).
-- `writeValue(ptr, type, value, offset = 0)` : writes values with fast-path for Buffer.
-
-**Types and helpers**
-- `sizeof(type)` → `number` : size in bytes of a type.
-- `POINTER(baseType)` : creates a pointer type factory (see [POINTER and pointer() API](#pointer-and-pointer-api) below).
-- `pointer(obj)` : creates a pointer to an existing ctypes instance (Python-compatible).
-- `byref(buffer)` : passes a buffer by reference (Python ctypes compatibility).
-- `cast(ptr, targetType)` : interprets a pointer as another type (returns wrapper for struct).
-
-**Struct / Union / Array / Bitfield**
-- `struct(fields, options)` : defines struct with support for nested, bitfields, anonymous fields, packed option. Returns object with `create()`, `get()`, `set()`, `toObject()`, `getNestedBuffer()`.
-- `union(fields)` : defines union; provides `create()`, `get()`, `set()`, `toObject()` and returns plain objects with properties.
-- `array(elementType, count)` : defines ArrayType; `wrap(buffer)` returns Proxy with indexing.
-- `bitfield(baseType, bits)` : bitfield definition.
-
-Struct example:
-```js
-class Point extends Structure {
-    static _fields_ = [
-        ["x", c_int32],
-        ["y", c_int32]
-    ];
-}
-
-const p = new Point(1, 2);
-console.log(p.x, p.y);  // 1 2
-```
-
-**Python-compatible conveniences**
-- `create_string_buffer(init)` : create string buffer from number/string/Buffer.
-- `create_unicode_buffer(init)` : create wide string buffer.
-- `string_at(address, size)` / `wstring_at(address, size)` : read strings from address.
-
-**Memory: utilities**
-- `memmove(dst, src, count)` : copy memory.
-- `memset(dst, value, count)` : set memory.
-
-**Error handling and WinAPI helpers**
-- `get_errno()` / `set_errno(value)` : access to errno (platform-specific implementation).
-- `_initWinError()` internals; public helpers: `GetLastError()`, `SetLastError(code)`, `FormatError(code)`, `WinError(code)`.
-
-**Type aliases (Python-compatible)**
-The following type classes are exported (identical to Python ctypes):
-`c_int, c_uint, c_int8, c_uint8, c_int16, c_uint16, c_int32, c_uint32, c_int64, c_uint64, c_float, c_double, c_char, c_char_p, c_wchar, c_wchar_p, c_void_p, c_bool, c_size_t, c_long, c_ulong`.
-
-**Note**: Only type classes (e.g., `c_int32`) are supported, not string literals (e.g., `"int32"`). This matches Python ctypes behavior exactly.
-
-**Constants**
-- `POINTER_SIZE` - pointer size (from `native.POINTER_SIZE`).
-- `WCHAR_SIZE` - wchar size (from `native.WCHAR_SIZE`).
-- `NULL` - exported null value.
-
----
-
-If you want, I can generate additional Windows or Linux-specific snippets, or integrate examples in the `tests/` directory.
-
-### Functions
-
-#### `load(libPath)` → `Library`
-Load a shared library.
-
-#### `callback(fn, returnType, argTypes)` → `{pointer, release()}`
-Create a callback from a JavaScript function.
-
-#### `create_string_buffer(init)` → `Buffer`
-Create a null-terminated C string buffer (like Python ctypes). `init` can be a size, a string, or an existing `Buffer`.
-
-#### `create_unicode_buffer(init)` → `Buffer`
-Create a wide (wchar_t) null-terminated buffer (UTF-16LE on Windows).
-
-#### `string_at(address, [size])` → `string`
-Read a C string from an address or buffer.
-
-#### `readValue(ptr, type, [offset])` → `value`
-Read a value from memory.
-
-#### `writeValue(ptr, type, value, [offset])` → `bytesWritten`
-Write a value to memory.
-
-#### `sizeof(type)` → `number`
-Get the size of a type in bytes.
-
-#### POINTER and pointer() API
-
-`node-ctypes` provides a Python ctypes-compatible pointer API:
-
-```javascript
-import { POINTER, pointer, c_int32, Structure } from 'node-ctypes';
-
-// Create a pointer type
-const IntPtr = POINTER(c_int32);
-
-// Create NULL pointer
-const p1 = IntPtr.create();
-console.log(p1.isNull); // true
-
-// Create pointer from buffer
-const buf = Buffer.alloc(12);
-buf.writeInt32LE(10, 0);
-buf.writeInt32LE(20, 4);
-buf.writeInt32LE(30, 8);
+| Type | Aliases | Size |
+|------|---------|------|
+| `c_int8` | `c_char` | 1 |
+| `c_uint8` | `c_uchar` | 1 |
+| `c_int16` | `c_short` | 2 |
+| `c_uint16` | `c_ushort` | 2 |
+| `c_int32` | `c_int` | 4 |
+| `c_uint32` | `c_uint` | 4 |
+| `c_int64` | `c_long` (64-bit) | 8 |
+| `c_uint64` | `c_ulong` (64-bit) | 8 |
+| `c_float` | | 4 |
+| `c_double` | | 8 |
+| `c_void_p` | pointer | 8 (64-bit) |
+| `c_char_p` | string | pointer |
+| `c_wchar_p` | wide string | pointer |
+| `c_bool` | | 1 |
+| `c_size_t` | | platform |
+| `c_ssize_t` | | platform |
+
+## Key Differences from Python ctypes
+
+- Callbacks must be manually released with `.release()` to prevent memory leaks
+- No automatic memory management for returned pointers
+- Both `class extends Structure` (Python-like) and `struct({...})` (functional) syntaxes available
+- Only type classes (`c_int32`) are accepted, not string literals (`"int32"`) — same as Python
+
+## Utility Functions
+
+- `create_string_buffer(init)` / `create_unicode_buffer(init)` — create C string buffers
+- `string_at(address, size)` / `wstring_at(address, size)` — read strings from memory
+- `readValue(ptr, type, offset)` / `writeValue(ptr, type, value, offset)` — direct memory access
+- `sizeof(type)` — type size in bytes
+- `alignment(type)` — type alignment in bytes
+- `addressof(ptr)` — get address as BigInt
+- `memmove(dst, src, count)` / `memset(dst, value, count)` — memory operations
+- `GetLastError()` / `FormatError(code)` — Windows error helpers
 
-const p2 = IntPtr.fromBuffer(buf);
-
-// .contents property (Python-compatible)
-console.log(p2.contents); // 10
-p2.contents = 100;
-console.log(buf.readInt32LE(0)); // 100
-
-// Pointer indexing (Python-compatible)
-console.log(p2[0]); // 100
-console.log(p2[1]); // 20
-console.log(p2[2]); // 30
-
-p2[1] = 200;
-console.log(buf.readInt32LE(4)); // 200
-
-// pointer() function - create pointer to existing object
-const x = new c_int32(42);
-const px = pointer(x);
-console.log(px.contents); // 42
-px.contents = 100;
-console.log(x.value); // 100
-
-// Works with structures too
-class Point extends Structure {
-  static _fields_ = [["x", c_int32], ["y", c_int32]];
-}
-const pt = new Point({ x: 10, y: 20 });
-const ppt = pointer(pt);
-```
+## Examples
 
-**POINTER type methods:**
-- `POINTER(baseType)` - creates a pointer type factory
-- `PointerType.create()` - creates a NULL pointer instance
-- `PointerType.fromBuffer(buf)` - creates pointer to buffer
-- `PointerType.fromAddress(addr)` - creates pointer from address
-
-**Pointer instance properties:**
-- `.contents` - get/set dereferenced value (Python-compatible)
-- `.address` - get raw address as BigInt
-- `.isNull` - check if pointer is NULL
-- `[n]` - array-style indexing with pointer arithmetic
-- `.deref()` - alias for `.contents` getter
-- `.set(value)` - update pointer target
-
-**Using POINTER in function definitions:**
-```javascript
-// POINTER types can be used as argtypes and restype
-const IntPtr = POINTER(c_int32);
+- [Windows Controls Demo](examples/windows/demo_controls.js) — Win32 common controls showcase
+- [Windows Registry Demo](examples/windows/demo_registry.js) — setValue, getValue, openKey, deleteValue, deleteKey
+- [Windows Tray Demo](examples/windows/demo_tray.js) — System tray menu
+- [Windows COM Automation Demo](examples/windows/demo_comtypes.js) — IShellLinkW / IPersistFile COM interfaces
+- [Windows LDAP Demo](examples/windows/demo_ldap.js) — LDAP directory queries
+- [Smart Card (PC/SC) Demo](examples/demo_scard.js) — WinSCard on Windows, pcsclite on macOS/Linux
 
-// As argument type
-const memset = msvcrt.func("memset", c_void_p, [IntPtr, c_int32, c_size_t]);
+## Tests
 
-// As return type
-const memchr = msvcrt.func("memchr", IntPtr, [c_void_p, c_int32, c_size_t]);
+```bash
+cd tests
+npm install
+npm run test
 ```
 
-#### `struct(fields)` → `StructDefinition`
-Create a simple struct definition.
+See [tests/common/](tests/common/) for working examples including parallel Python implementations.
 
-#### `Structure` (base class)
-Base class for Python-like struct definitions. Subclasses should define `static _fields_`.
+## Documentation
 
-#### `Union` (base class)
-Base class for Python-like union definitions. Subclasses should define `static _fields_`.
+Generate the API docs locally:
 
-## Python ctypes Compatibility Reference
-
-### API Comparison
-
-| 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])`<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)` | `["flags", c_uint32, 3]`<br>**or** `bitfield(c_uint32, 3)` |
-| **Callbacks** | `CFUNCTYPE(c_int, c_int)` | `CFUNCTYPE(c_int, c_int)`<br>**or** ` callback(fn, c_int, [c_int])` |
-| **Strings** | `c_char_p(b"hello")` | `create_string_buffer("hello")`<br>**or**<br>`new c_char_p(b"hello")` |
-| **Pointers** | `POINTER(c_int)`<br>`p.contents`<br>`p[0]` | `POINTER(c_int)`<br>`p.contents`<br>`p[0]` |
-| **pointer()** | `pointer(obj)` | `pointer(obj)` |
-| **Variadic** | `sprintf(buf, b"%d", 42)` | `sprintf(buf, fmt, 42)` (auto) |
-| **Sizeof** | `sizeof(c_int)` | `sizeof(c_int)` |
-
-### What's Supported
-
-✅ **Fully Compatible**:
-- All basic types (int8-64, uint8-64, float, double, bool, pointer, string)
-- Structs with nested structures
-- Unions (including nested in structs)
-- Bit fields
-- Arrays (fixed-size)
-- Callbacks (with manual release)
-- Variadic functions (automatic detection)
-- Anonymous fields in structs/unions
-- **Class-based struct/union definitions** (`class MyStruct extends Structure`)
-- Platform-specific types (c_long, c_ulong, c_size_t)
-- Memory operations (alloc, read, write)
-- Windows API (__stdcall via WinDLL)
-
-⚠️ **Differences from Python ctypes**:
-- Callbacks must be manually released with `.release()`
-- **Function definition supports both syntaxes**: `func(name, returnType, argTypes)` **or** `func.argtypes = [...]; func.restype = ...`
-
-✨ **100% Python-compatible**:
-- **Struct property access**: Direct access (`p.x`, `p.y`) works with `class X extends Structure` - identical to Python!
-- **Type system**: Only type classes (`c_int32`, `c_char_p`) are accepted, exactly like Python ctypes
-- **No string literals**: `"int32"`, `"string"` are NOT supported (Python doesn't use them either)
-
-## Limitations & Known Issues
-
-- ⚠️ Callbacks must be released manually with `.release()` to prevent memory leaks
-- ⚠️ No automatic memory management for returned pointers (manual `free()` required)
-- ℹ️ Struct property access:
-  - **Python-style classes** (`class X extends Structure`): Direct property access (`p.x`, `p.y`) - fully compatible!
-  - **Plain struct definitions** (`struct({...})`): Use `.get()` / `.set()` methods for property access
-- ℹ️ Struct alignment: Platform defaults are used, but `packed: true` option is available for packed structs
-
-## Examples in Test Suite
-
-For complete, working examples, see the test suite:
-
-- **Basic types**: [tests/common/test_basic_types.js](tests/common/test_basic_types.js)
-- **Structs & unions**: [tests/common/test_structs.js](tests/common/test_structs.js)
-- **Nested structures**: [tests/common/test_nested_structs.js](tests/common/test_nested_structs.js)
-- **Arrays**: [tests/common/test_arrays.js](tests/common/test_arrays.js)
-- **Functions**: [tests/common/test_functions.js](tests/common/test_functions.js)
-- **Callbacks**: [tests/common/test_callbacks.js](tests/common/test_callbacks.js)
-- **Version info**: [tests/common/test_version.js](tests/common/test_version.js)
-- **Windows API**: [tests/windows/test_winapi.js](tests/windows/test_winapi.js)
-- **Python compatibility**: [tests/common/*.py](tests/common/) (parallel Python implementations)
-
-Run tests:
 ```bash
-cd tests
-npm install 
-npm run test               # All tests
-npm run bench:koffi        # Benchmark vs koffi
+npm run docs
 ```
 
-## Examples
-
-For practical GUI application examples using the Windows API:
+This produces a browsable site in `docs/` using [TypeDoc](https://typedoc.org/). To preview it:
 
-- **Windows Controls Showcase Demo**: [examples/windows/demo_controls.js](examples/windows/demo_controls.js) - Comprehensive demo with a wide set of common Win32 controls
-- **Windows Registry Demo**: [examples/windows/demo_registry](examples/windows/demo_registry) - Comprehensive demo with setValue, getValue, openKey, deleteValue, deleteKey
-- **Windows Tray Demo**: [examples/windows/demo_tray.js](examples/windows/demo_tray.js) - Comprehensive demo for tray menu inspired by [pit-ray/fluent-tray](https://github.com/pit-ray/fluent-tray)
-- **WinScard - PC/SC Smart Card**: [examples/demo_scard.js](examples/demo_scard.js) - Comprehensive demo for Windows Smart Card API on Windows and PC/SC Lite (pcsclite) on macOS and Linux
+```bash
+npm run docs:serve
+```
 
 ## License
 
@@ -913,7 +288,4 @@ MIT
 
 ## Credits
 
-Built with:
-- [libffi](https://github.com/libffi/libffi) - Foreign Function Interface library
-- [node-addon-api](https://github.com/nodejs/node-addon-api) - N-API C++ wrapper
-- [cmake-js](https://github.com/cmake-js/cmake-js) - CMake-based build system for Node.js addons
+Built with [libffi](https://github.com/libffi/libffi), [node-addon-api](https://github.com/nodejs/node-addon-api), and [cmake-js](https://github.com/cmake-js/cmake-js).