@jaydeebee/lite3-native-addon

Node.js native addon bindings for lite3, a zero-copy binary serialization library.

Disclaimer

This project is:

• Unofficial - Built independently of the lite3 project, with no affiliation to the original authors
• A learning exercise - Created primarily to explore Node.js native addon development
• Not production-ready - Use at your own risk
• Potentially inefficient - The JavaScript/N-API bridge may negate some of the performance benefits that lite3 offers in native contexts

Installation

npm install @jaydeebee/lite3-native-addon

Prebuilt binaries are available for:

• Linux x64
• Linux arm64
• macOS arm64

Other platforms will fall back to source compilation (requires a C compiler and Python).

Usage

Basic Encode/Decode

import { encode, decode, version } from '@jaydeebee/lite3-native-addon';

// Encode an object to a binary buffer
const buffer = encode({ hello: 'world', count: 42 });

// Decode back to JavaScript
const obj = decode(buffer);

console.log(obj); // { hello: 'world', count: 42 }
console.log(version()); // Addon version

Lazy Proxy Access (Lite3Buffer)

For better performance with large objects where you only need a few fields, use Lite3Buffer.from() to create a lazy proxy that decodes values on-demand:

import { Lite3Buffer } from '@jaydeebee/lite3-native-addon';

// Create from an object (type is inferred)
const proxy = Lite3Buffer.from({
  users: [
    { name: 'Alice', age: 30 },
    { name: 'Bob', age: 25 }
  ],
  metadata: { count: 2 }
});

// Access properties naturally - decoded lazily
console.log(proxy.users[0].name);  // 'Alice' - only this field is decoded
console.log(proxy.metadata.count); // 2

// Array methods work as expected
const names = proxy.users.map(u => u.name);  // ['Alice', 'Bob']
const adults = proxy.users.filter(u => u.age >= 18);

// Works with JSON.stringify, spreading, for...of, etc.
console.log(JSON.stringify(proxy));
const copy = { ...proxy };
for (const user of proxy.users) {
  console.log(user.name);
}

Type Safety

When creating a proxy from a buffer, the return type defaults to unknown for safety (like JSON.parse). Provide a type parameter when you trust the data source:

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

// From buffer - returns unknown by default (safe)
const data = Lite3Buffer.from(buffer);
data.name;  // TS error: 'unknown' has no property 'name'

// With type parameter - returns User (trusted)
const user = Lite3Buffer.from<User>(buffer);
user.name;  // OK - full autocomplete and type checking

// For untrusted sources, consider runtime validation:
import { z } from 'zod';
const UserSchema = z.object({ name: z.string(), age: z.number() });
const validated = UserSchema.parse(Lite3Buffer.from(buffer));

Utility Functions

import { Lite3Buffer, $buffer, $decode } from '@jaydeebee/lite3-native-addon';

// Check if a value is a Lite3Buffer proxy
Lite3Buffer.isLite3Buffer(proxy);  // true
Lite3Buffer.isLite3Buffer({});     // false

// Get the underlying buffer
const buffer = Lite3Buffer.getBuffer(proxy);

// Force full decode (escape hatch)
const pojo = proxy[$decode]();

// Access raw buffer via symbol (alternative)
const rawBuffer = proxy[$buffer];

Why Use Lite3Buffer?

Scenario	decode()	Lite3Buffer.from()
Access all fields	Good	Similar
Access few fields from large object	Wasteful	Efficient
Repeated access to same field	Faster	Slightly slower (cached after first access)
Pass-through / routing	Decode + re-encode	Keep as buffer

Supported Types

• Strings
• Numbers (stored as f64)
• Booleans
• Null
• Arrays
• Objects

Unsupported types (functions, undefined, symbols) are silently skipped during encoding.

License

MIT

Contributing

Contributions are welcome.

• Open a pull request for bug fixes and minor improvements
• Use Angular commit message conventions (e.g., feat:, fix:, docs:)
• For significant or invasive changes, please open an issue first to discuss the approach