Introduction

The Crous Node.js SDK provides high-performance binary serialization for Node.js applications via a native N-API addon. It produces wire-compatible output with the Python SDK, enabling seamless cross-language data exchange.

Key Features

• Native C addon — N-API bindings for maximum performance
• ABI stable — No recompilation needed across Node.js versions
• Cross-platform — Works on Linux, macOS, and Windows
• TypeScript ready — Full type definitions included
• Binary data — Native Buffer support (15x faster than JSON for binary)
• Custom serializers — Register handlers for any JavaScript class
• Set support — Native Set preservation
• Python compatible — Identical wire format for polyglot apps

Quick Example

const crous = require('crous');

// Serialize JavaScript data to compact binary
const data = {
    name: 'Alice',
    scores: [98, 95, 100],
    active: true,
    avatar: Buffer.from([0x89, 0x50, 0x4E, 0x47]),
    tags: new Set(['admin', 'developer']),
};

// Encode to binary Buffer
const binary = crous.dumps(data);
console.log(`Encoded: ${binary.length} bytes`);

// Decode back to JavaScript
const result = crous.loads(binary);
console.log(result);
// { name: 'Alice', scores: [98, 95, 100], ... }

Architecture

The Node.js SDK uses a three-layer architecture:

1. JavaScript Wrapper (index.js) — Error classes, file I/O, CrousEncoder/CrousDecoder
2. N-API C Bindings (crous_node.c) — Converts JS ↔ crous_value, custom serializer registry
3. Core C Library (crous_core/) — Shared with Python SDK: binary codec, value tree, arena allocator

Type Mapping

Performance