API Reference

Complete reference for every function, class, and type exported by the Crous Node.js SDK.

Module Functions

`dumps(data, options?)`

Serialize a JavaScript value to a Crous binary Buffer.

Parameter	Type	Description
`data`	`any`	The value to serialize
`options.default`	`DefaultFunction?`	Fallback for unsupported types

Returns: Buffer

Throws: CrousEncodeError

const buf = crous.dumps({ key: 'value' });
const buf2 = crous.dumps(data, {
    default: (obj) => obj.toJSON()
});

`loads(buffer, options?)`

Deserialize a Crous binary Buffer to a JavaScript value.

Parameter	Type	Description
`buffer`	`Buffer \| Uint8Array`	Binary data to decode
`options.object_hook`	`ObjectHook?`	Transform decoded objects

Returns: any

Throws: CrousDecodeError

const data = crous.loads(buffer);
const data2 = crous.loads(buffer, {
    object_hook: (obj) => revive(obj)
});

`dump(data, target, options?)`

Serialize data and write to a file path or writable stream.

Parameter	Type	Description
`data`	`any`	The value to serialize
`target`	`string \| Writable`	File path or writable stream
`options.default`	`DefaultFunction?`	Fallback for unsupported types

Returns: void

Throws: CrousEncodeError, file system errors

crous.dump({ key: 'value' }, 'output.crous');
crous.dump(data, writableStream);

`load(source, options?)`

Read and deserialize data from a file path.

Parameter	Type	Description
`source`	`string`	File path to read from
`options.object_hook`	`ObjectHook?`	Transform decoded objects

Returns: any

Throws: CrousDecodeError, file system errors

const data = crous.load('data.crous');

Custom Type Registration

`registerSerializer(constructor, serializer)`

Parameter	Type	Description
`constructor`	`Function`	The class/constructor to match
`serializer`	`SerializerFunction`	Converts instance to serializable form

Returns: void

crous.registerSerializer(MyClass, (obj) => ({
    field1: obj.field1,
    field2: obj.field2
}));

`unregisterSerializer(constructor)`

Remove a previously registered serializer.

Parameter	Type	Description
`constructor`	`Function`	The class/constructor to unregister

Returns: void

`registerDecoder(tag, decoder)`

Parameter	Type	Description
`tag`	`number`	Tag number (≥ 100 for user types)
`decoder`	`DecoderFunction`	Reconstructs instance from decoded data

Returns: void

crous.registerDecoder(100, (data) => new MyClass(
    data.field1, data.field2
));

`unregisterDecoder(tag)`

Remove a previously registered decoder.

Parameter	Type	Description
`tag`	`number`	The tag number to unregister

Returns: void

Classes

`CrousEncoder`

Stateful encoder with pre-configured options.

class CrousEncoder {
    constructor(options?: {
        default?: DefaultFunction;
    });
    dumps(data: any): Buffer;
    dump(data: any, target: string | Writable): void;
}

`CrousDecoder`

Stateful decoder with pre-configured options.

class CrousDecoder {
    constructor(options?: {
        object_hook?: ObjectHook;
    });
    loads(buffer: Buffer | Uint8Array): any;
    load(source: string): any;
}

Error Classes

`CrousError`

Base error class. All Crous-specific errors extend this.

class CrousError extends Error {
    name: 'CrousError';
    message: string;
}

`CrousEncodeError`

Thrown when serialization fails.

class CrousEncodeError extends CrousError {
    name: 'CrousEncodeError';
}

Common causes:

Unsupported type (Map, Function, Symbol, etc.)
Circular reference / max depth exceeded
Non-string dictionary key
Memory allocation failure

`CrousDecodeError`

Thrown when deserialization fails.

class CrousDecodeError extends CrousError {
    name: 'CrousDecodeError';
}

Common causes:

Corrupted or malformed data
Truncated buffer
Unknown tagged type (no decoder registered)
Version mismatch

Version Information

`version`

The SDK version as a string.

console.log(crous.version); // '2.0.0'

`versionInfo`

Structured version information from the C core.

interface VersionInfo {
    major: number;
    minor: number;
    patch: number;
    full: string;       // e.g., '2.0.0'
    build_date: string; // compilation date
    compiler: string;   // compiler used
}

console.log(crous.versionInfo);
// {
//   major: 2, minor: 0, patch: 0,
//   full: '2.0.0',
//   build_date: '2025-01-15',
//   compiler: 'Apple clang 15.0.0'
// }

`versionTuple`

The version as a [major, minor, patch] array.

console.log(crous.versionTuple); // [2, 0, 0]

TypeScript Types

index.d.ts

// Callback that converts unsupported objects to serializable form
type DefaultFunction = (obj: any) => any;

// Callback that transforms every decoded object
type ObjectHook = (obj: Record<string, any>) => any;

// Converts a custom type instance to a serializable value
type SerializerFunction = (obj: any) => any;

// Reconstructs a custom type from decoded data
type DecoderFunction = (data: any) => any;

// Options for dumps / dump
interface EncodeOptions {
    default?: DefaultFunction;
}

// Options for loads / load
interface DecodeOptions {
    object_hook?: ObjectHook;
}

// Version info structure
interface VersionInfo {
    major: number;
    minor: number;
    patch: number;
    full: string;
    build_date: string;
    compiler: string;
}

// Module exports
export function dumps(data: any, options?: EncodeOptions): Buffer;
export function loads(buffer: Buffer | Uint8Array, options?: DecodeOptions): any;
export function dump(data: any, target: string | NodeJS.WritableStream, options?: EncodeOptions): void;
export function load(source: string, options?: DecodeOptions): any;

export function registerSerializer(constructor: Function, serializer: SerializerFunction): void;
export function unregisterSerializer(constructor: Function): void;
export function registerDecoder(tag: number, decoder: DecoderFunction): void;
export function unregisterDecoder(tag: number): void;

export class CrousEncoder {
    constructor(options?: EncodeOptions);
    dumps(data: any): Buffer;
    dump(data: any, target: string | NodeJS.WritableStream): void;
}

export class CrousDecoder {
    constructor(options?: DecodeOptions);
    loads(buffer: Buffer | Uint8Array): any;
    load(source: string): any;
}

export class CrousError extends Error {}
export class CrousEncodeError extends CrousError {}
export class CrousDecodeError extends CrousError {}

export const version: string;
export const versionInfo: VersionInfo;
export const versionTuple: [number, number, number];

Quick Reference

Task	Function
Serialize to Buffer	`dumps(data)`
Deserialize from Buffer	`loads(buffer)`
Write to file	`dump(data, path)`
Read from file	`load(path)`
Custom type → binary	`registerSerializer(ctor, fn)`
Binary → custom type	`registerDecoder(tag, fn)`
Handle unknown types	`dumps(data, { default: fn })`
Revive objects	`loads(buf, { object_hook: fn })`
Check version	`crous.version`

Error Handling