Getting Started

This guide walks you through installing the Crous Node.js SDK and running your first serialization.

Requirements

Node.js 14.0.0 or later
A C compiler (GCC, Clang, or MSVC)
Python 3.x (required by node-gyp for building)
node-gyp build tools

Installation

npm install crous

Native Compilation

The package includes C source code that is compiled during npm install via node-gyp. Make sure you have a C compiler available. On macOS, install Xcode Command Line Tools. On Ubuntu, install build-essential.

Build from Source

git clone https://github.com/axiomchronicles/crous.git
cd crous/nodejs
npm install
npm run build

Verify Installation

verify.js

const crous = require('crous');

// Check version
console.log(`Crous version: ${crous.version}`);
// Output: Crous version: 2.0.0

// Quick round-trip test
const data = { hello: 'world', numbers: [1, 2, 3] };
const encoded = crous.dumps(data);
const decoded = crous.loads(encoded);
console.log(decoded);
console.log('✓ Crous is working correctly!');

Your First Serialization

first_example.js

const crous = require('crous');

// Create some data
const user = {
    name: 'Alice',
    age: 30,
    email: 'alice@example.com',
    scores: [98.5, 95.0, 100.0],
    verified: true,
    avatar: Buffer.from([0x89, 0x50, 0x4E, 0x47]),  // binary data!
    tags: new Set(['admin', 'developer']),             // sets too!
};

// Serialize to binary
const binaryData = crous.dumps(user);
console.log(`Serialized to ${binaryData.length} bytes`);

// Save to file
crous.dump(user, 'user.crous');

// Load from file
const loaded = crous.load('user.crous');
console.log('✓ File round-trip successful!');
console.log(loaded);

TypeScript Support

Full TypeScript definitions are included. No additional @types package needed.

example.ts

import * as crous from 'crous';

interface User {
    name: string;
    age: number;
}

const user: User = { name: 'Alice', age: 30 };
const binary: Buffer = crous.dumps(user);
const result = crous.loads(binary) as User;

Platform Support

Platform	Architecture	Status
Linux	x64, ARM64	✅
macOS	x64, ARM64 (Apple Silicon)	✅
Windows	x64	✅

ABI Stability

Crous uses N-API (not V8 directly), which is ABI-stable across Node.js versions. You won't need to recompile when upgrading Node.js.

Introduction Serialization