node-ctypes

Python ctypes for Node.js. A foreign function interface built on libffi and N-API. If you know Python ctypes, you already know node-ctypes.

Quick start

npm install node-ctypes

Prebuilt binaries ship for Windows, Linux, and macOS (x64/ARM64).

import { CDLL, Structure, c_int32, c_char_p } from "node-ctypes";

// 1. Load a shared library
const libc = new CDLL(process.platform === "win32" ? "msvcrt" : null);

// 2. Declare a function signature
const strlen = libc.func("strlen", c_int32, [c_char_p]);
console.log(strlen("hello")); // 5

// 3. Declare a struct
class Point extends Structure {
  static _fields_ = [
    ["x", c_int32],
    ["y", c_int32],
  ];
}
const p = new Point(3, 4);
console.log(p.x, p.y); // 3 4

Build from source

Requires Node.js >= 24, CMake >= 3.15, and a C++ compiler.

npm install
npm run build

Guides

Calling a C function

Two equivalent styles — use whichever reads better:

// Python-style: set argtypes/restype on the bound symbol
const abs = libc.abs;
abs.argtypes = [c_int32];
abs.restype = c_int32;
abs(-42); // 42

// One-shot: declare signature at lookup
const abs2 = libc.func("abs", c_int32, [c_int32]);
abs2(-42); // 42

For Windows __stdcall APIs use WinDLL instead of CDLL. For COM-style auto-HRESULT-checking use OleDLL.

Structs, unions, bit fields, arrays

import { Structure, Union, array, c_int32, c_uint32, c_float } from "node-ctypes";

class Rect extends Structure {
  static _fields_ = [
    ["x", c_int32],
    ["y", c_int32],
    ["w", c_int32],
    ["h", c_int32],
  ];
}

class Value extends Union {
  static _fields_ = [
    ["i", c_int32],
    ["f", c_float],
  ];
}

// Bit fields: [name, type, bitCount]
class Flags extends Structure {
  static _fields_ = [
    ["enabled", c_uint32, 1],
    ["mode", c_uint32, 3],
    ["priority", c_uint32, 4],
  ];
}

// Arrays: elementType * count (Python: `c_int32 * 5`)
const IntArr5 = array(c_int32, 5);
const buf = IntArr5.create([1, 2, 3, 4, 5]);

Nested structs, anonymous fields (static _anonymous_ = ["data"]), explicit packing (static _pack_ = 1), and self-referential pointers (POINTER(() => Node)) all work identically to Python.

Pointers, buffers, and cast

import { POINTER, pointer, cast, c_int32, c_void_p } from "node-ctypes";

// Pointer to an existing c-data instance (Python: pointer(x))
const x = new c_int32(42);
const px = pointer(x);
px.contents;   // 42   (Python: *px or px.contents)
px[0];         // 42   (Python: px[0])
px[0] = 100;
x.value;       // 100  (same memory)

// View existing memory as a typed pointer
const IntPtr = POINTER(c_int32);
const p = IntPtr.fromBuffer(someBuffer);
p[0]; p[1]; p[2];   // pointer arithmetic

// cast() — Python: cast(ptr, POINTER(T))
const q = cast(someBuffer, POINTER(c_int32));
const r = cast(addressAsBigInt, POINTER(MyStruct));

To hand a raw address to a function, use c_void_p as the argtype for portable code (Python accepts raw int only there).

Callbacks

import { callback, CFUNCTYPE, c_int32, c_void_p, readValue } from "node-ctypes";

// Python-style type: CFUNCTYPE(restype, ...argtypes)
const CompareFn = CFUNCTYPE(c_int32, c_void_p, c_void_p);
const cmp = new CompareFn((a, b) => readValue(a, c_int32) - readValue(b, c_int32));

// Or the one-shot form:
const cmp2 = callback(
  (a, b) => readValue(a, c_int32) - readValue(b, c_int32),
  c_int32,
  [c_void_p, c_void_p]
);

// IMPORTANT: release the trampoline when done. Unlike Python, we cannot
// rely on GC — the callback holds a libffi closure that native code may
// still reference.
cmp.release();

Both callbacks and libraries implement Symbol.dispose, so they work with the using declaration for scope-bound cleanup (also on throw):

{
  using libc = new CDLL(null);
  using cmp = callback(fn, c_int32, [c_void_p, c_void_p]);
  qsort(arr, 5, 4, cmp);
} // close() + release() run automatically

Set NODE_CTYPES_DEBUG_CALLBACKS=1 to log a stack trace for every callback garbage-collected without .release().

Errors: `errno` and `GetLastError`

GetLastError() / get_errno() read a private thread-local slot — exactly like Python's ctypes.get_last_error() / ctypes.get_errno(). The slot is updated only by FFI calls through libraries opened with use_last_error or use_errno; otherwise it stays at 0.

const user32 = new WinDLL("user32.dll", { use_last_error: true });
const FindWindow = user32.func("FindWindowW", c_void_p, [c_wchar_p, c_wchar_p]);
FindWindow("NoSuchClass", null);

GetLastError();              // top-level (Python: ctypes.get_last_error)
user32.get_last_error();     // per-library alias

The snapshot is captured atomically in native code immediately after ffi_call, before any other JS can clobber it. To read the raw system error instead, call GetLastError via FFI like any other function.

Windows API

wintypes mirrors ctypes.wintypes (BOOL, BYTE, WORD, DWORD, HANDLE, HWND, LPARAM, WPARAM, LRESULT, LPCWSTR, LPSTR, HGDIOBJ, …) — pure aliases of the primitive CTypes, so signatures read identical to MSDN.

import { WinDLL, Structure, wintypes } from "node-ctypes";
const { WORD, HWND, BOOL, LPVOID } = wintypes;

const kernel32 = new WinDLL("kernel32.dll");

class SYSTEMTIME extends Structure {
  static _fields_ = [
    ["wYear", WORD], ["wMonth", WORD], ["wDayOfWeek", WORD], ["wDay", WORD],
    ["wHour", WORD], ["wMinute", WORD], ["wSecond", WORD], ["wMilliseconds", WORD],
  ];
}

const GetLocalTime = kernel32.func("GetLocalTime", null, [LPVOID]);
const st = new SYSTEMTIME();
GetLocalTime(st);

const user32 = new WinDLL("user32.dll");
const IsWindow = user32.func("IsWindow", BOOL, [HWND]);

Output parameters (`paramflags`)

When at least one out param is declared, the call returns only the out-params (single value, or array if >1) — the restype is discarded. To also inspect it (e.g. a BOOL success flag), attach an errcheck:

const proto = WINFUNCTYPE(BOOL, HWND, POINTER(DWORD), POINTER(DWORD));
const fn = proto.bind(user32, "GetWindowThreadProcessId", [
  { dir: "in", name: "hWnd" },
  { dir: "out", name: "pid" },
  { dir: "out", name: "tid" },
]);

const [pid, tid] = fn(hwnd);     // positional
const [p2, t2] = fn({ hWnd });   // or named-args

fn.errcheck = (result, func, args) => {
  if (!result) throw new Error("call failed");
  return result; // ignored when outs exist
};

Sharing memory with existing buffers

// Zero-copy view over a Node Buffer (Python: Structure.from_buffer)
const r = RECT.from_buffer(packet, 16);

// Wrap an externally-allocated pointer (Python: Structure.from_address)
const r2 = RECT.from_address(malloc_result);

// Bind a C-exported global (Python: c_int.in_dll)
const tz = c_int32.in_dll(libc, "_timezone");

Adapter protocols: `_as_parameter_` and `from_param`

// Instance protocol: auto-unwrap on call
class Handle {
  constructor(h) { this._as_parameter_ = h; }
}
user32.CloseHandle(new Handle(hwnd));

// Class protocol: custom conversion in argtypes
class StrLen extends c_int32 {
  static from_param(s) { return typeof s === "string" ? s.length : s; }
}
const abs = libc.func("abs", c_int32, [StrLen]);
abs("hello"); // 5

Big-endian structures

class NetHeader extends BigEndianStructure {
  static _fields_ = [
    ["magic", c_uint32],
    ["length", c_uint32],
  ];
}
const h = new NetHeader();
h.magic = 0x12345678; // stored as 12 34 56 78 on the wire

LittleEndianStructure, BigEndianUnion, LittleEndianUnion work the same way. Byte order is per-class — nested structs keep their own.

TypeScript

Argument and return types are narrowed when argTypes is a literal tuple (as const) and returnType is a CType constant:

const libc = new CDLL(null);
const strlen = libc.func("strlen", c_int64, [c_char_p] as const);
const n: bigint = strlen("hello"); // typed as bigint, not any

For typed struct fields use defineStruct instead of extends Structure:

class Point extends defineStruct({ x: c_int32, y: c_int32 }) {
  distance() { return Math.sqrt(this.x ** 2 + this.y ** 2); }
}
const p = new Point({ x: 3, y: 4 }); // p.x, p.y typed as number

API reference

Primitive types

Type	Aliases	Size	Notes
`c_int8`	`c_byte`	1
`c_uint8`	`c_ubyte`	1
`c_int16`	`c_short`	2
`c_uint16`	`c_ushort`	2
`c_int32`	`c_int`	4
`c_uint32`	`c_uint`	4
`c_int64`	`c_longlong`	8
`c_uint64`	`c_ulonglong`	8
`c_long`		platform	4 on Windows (LLP64), 8 on Unix 64-bit (LP64)
`c_ulong`		platform	platform-dependent, mirrors `c_long`
`c_float`		4
`c_double`		8
`c_bool`		1
`c_char`		1	accepts a 1-char string or int
`c_wchar`		2 or 4	2 on Windows (UTF-16), 4 on Unix
`c_char_p`		pointer	`char *` (NUL-terminated)
`c_wchar_p`		pointer	`wchar_t *` (NUL-terminated wide)
`c_void_p`		pointer	opaque pointer / `HANDLE`
`c_size_t`		pointer	pointer-sized unsigned integer
`c_ssize_t`		pointer	pointer-sized signed integer
`HRESULT`		4	`c_int32` subclass — auto-raise on `OleDLL`

Plus Win32 aliases under wintypes (full ctypes.wintypes parity).

Library loaders

CDLL(name, { use_errno?, use_last_error? }) — C calling convention
WinDLL(name, ...) — Windows __stdcall
OleDLL(name, ...) — like WinDLL, auto-raises on negative HRESULT
find_library(name) — cross-platform name resolution
cdll.<libname>, windll.<libname> — lazy namespaces

Type constructors

struct({...}) / class extends Structure — composite struct types
class extends Union — union types
array(type, n) — Python's type * n
POINTER(type) — pointer-to-type; accepts a thunk POINTER(() => T)
pointer(instance) — pointer to an existing c-data instance
CFUNCTYPE(restype, ...argtypes) — callback type
WINFUNCTYPE(restype, ...argtypes) — __stdcall callback type
defineStruct({...}) — typed-TS variant of struct

Memory & introspection

sizeof(type) / alignment(type) — in bytes
addressof(obj) → BigInt
byref(obj) — lightweight pass-by-reference marker
cast(ptr, type) — reinterpret a pointer as another type
memmove(dst, src, n) / memset(dst, val, n)
readValue(ptr, type, offset?) / writeValue(ptr, type, val, offset?)
create_string_buffer(init) / create_unicode_buffer(init)
string_at(addr, size?) / wstring_at(addr, size?)

Error slots

get_errno() / set_errno(v)
GetLastError() / SetLastError(v) / FormatError(code)
Per-library: lib.get_last_error() / lib.get_errno()

Structure helpers

T.from_buffer(buf, offset?) — zero-copy view
T.from_buffer_copy(buf, offset?) — independent copy
T.from_address(addr) — wrap raw pointer
T.in_dll(lib, name) — bind to exported global
T._as_parameter_ / T.from_param(v) — adapter protocols

Python ctypes parity & differences

What works identically

Structs, unions, bit fields, anonymous fields, _pack_, nested layouts, arrays, pointers and pointer arithmetic, callbacks (CFUNCTYPE / WINFUNCTYPE), from_buffer / from_buffer_copy / from_address / in_dll, _as_parameter_ / from_param, paramflags out-params, errcheck, use_errno / use_last_error, OleDLL + HRESULT auto-raise, BigEndianStructure / LittleEndianStructure and union variants, all Win32 aliases under wintypes.

Differences

Callbacks must be released with .release(). GC cannot detect when C code still holds the pointer; relying on it causes use-after-free.
No automatic memory management for returned pointers.
Both class and functional syntax: class extends Structure (Python-like) and struct({...}) (functional) are both supported.
Only type classes, not string literals: c_int32, never "int32" — same as Python.
c_char_p / c_wchar_p accept raw addresses (BigInt/number) as argtypes. Python is stricter (raises TypeError on int). For portable code use c_void_p there; both libraries accept it.

Not supported

ctypes.resize(instance, size) — our Structure/Union instances are Proxy objects wrapping a Node Buffer; Buffers aren't resizable in place, and re-pointing the Proxy target would break identity. Work-around: new MyStruct(myBuffer) with a pre-sized buffer.
c_longdouble (80/128-bit float, ffi_type_longdouble) — rarely used; fall back to c_double or raw bytes.

Examples

Windows Controls Demo — Win32 common controls
Windows Registry Demo — setValue / getValue / openKey / deleteKey
Windows Tray Demo — system tray icon + popup menu
Windows COM (Shortcut) — IShellLinkW + IPersistFile
Windows COM (Active Directory) — IDirectorySearch / ADsOpenObject
Windows LDAP Demo — LDAPv3 paged search (wldap32)
Smart Card (PC/SC) Demo — WinSCard on Windows, pcsclite on macOS/Linux

Tests & docs

cd tests && npm install && npm run test    # unit tests (JS + Python parity)
npm run docs                                # TypeDoc API site in docs/
npm run docs:serve                          # preview

See tests/common/ for runnable examples alongside parallel Python ctypes implementations.

License

MIT. Built with libffi, node-addon-api, and cmake-js.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

node-ctypes

Quick start

Guides

Calling a C function

Structs, unions, bit fields, arrays

Pointers, buffers, and cast

Callbacks

Errors: `errno` and `GetLastError`

Windows API

Output parameters (`paramflags`)

Sharing memory with existing buffers

Adapter protocols: `_as_parameter_` and `from_param`

Big-endian structures

TypeScript

API reference

Primitive types

Library loaders

Type constructors

Memory & introspection

Error slots

Structure helpers

Python ctypes parity & differences

What works identically

Differences

Not supported

Examples

Tests & docs

License

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

node-ctypes

Quick start

Guides

Calling a C function

Structs, unions, bit fields, arrays

Pointers, buffers, and cast

Callbacks

Errors: errno and GetLastError

Windows API

Output parameters (paramflags)

Sharing memory with existing buffers

Adapter protocols: _as_parameter_ and from_param

Big-endian structures

TypeScript

API reference

Primitive types

Library loaders

Type constructors

Memory & introspection

Error slots

Structure helpers

Python ctypes parity & differences

What works identically

Differences

Not supported

Examples

Tests & docs

License

Errors: `errno` and `GetLastError`

Output parameters (`paramflags`)

Adapter protocols: `_as_parameter_` and `from_param`