Oodle.js

Simple wrapper for Oodle data compression/decompression using native bindings via koffi.

Supports automatic downloading from workingrobot/oodleue or passing a path to the lib manually.

AI was used to generate the README and jsdoc, code is human.

Installation

npm i oodle.js@latest

Compatibility

• Windows: Tested

• Linux: Tested

• macOS: Untested (should work)

• NodeJS: Tested

• Bun: Tested

• Deno: Untested

Please open a PR or an issue if you encounter any errors.

Quick Start

import { Oodle } from "oodle.js";

const oodle = await Oodle.Create();

const input = Buffer.from("Hello, World!".repeat(50));

const compressed = oodle.compress({
	buffer: input,
});

const decompressed = oodle.decompress(
	{
		buffer: compressed,
	},
	input.length
);

console.log(decompressed.toString());

Creating an Instance

const oodle = await Oodle.Create();

Custom library path

const oodle = await Oodle.Create("./native/oodle.dll");

Clear download cache

const oodle = await Oodle.Create(true);

Compression

const compressed = oodle.compress(
	{
		buffer: input,
		size: input.length,   // optional
		offset: 0,            // optional
	},
	OodleCompressor.Kraken,
	OodleCompressionLevel.Optimal
);

Notes

• Returns a trimmed Buffer
• Automatically allocates output buffer using Oodle’s size estimator
• Throws OodleError on invalid ranges or failure

Decompression

const output = oodle.decompress(
	{
		buffer: compressed,
		size: compressed.length,
		offset: 0,
	},
	originalSize
);

Options

{
	fuzzSafe?: OodleFuzzSafe;
	checkCRC?: OodleCheckCRC;
	verbosity?: OodleVerbosity;
	decodeThreadPhase?: OodleDecodeThreadPhase;
}

Use size and offset to select the data you want inside of the Buffer.

Utility Methods

Get compressor type from buffer

const compressor = oodle.getCompressor(buffer);

Maximum compressed size

const max = oodle.maxCompressedSize(1024, OodleCompressor.Kraken);

Minimum decode buffer size

const size = oodle.minDecodeSize(
	buffer.length,
	OodleCompressor.Kraken,
	false
);

Error Handling

try {
	oodle.compress({ buffer: input });
} catch (err) {
	if (err instanceof OodleError) {
		console.log(err.code);
	}
}

OodleError

{
	name: "OodleError",
	message: string,
	code: string,
	isOodleError(): true
}

Internal / Private API Notice

The following properties are NOT part of the public API and should not be used directly unless you know what you're doing:

• _lib
• _Compress
• _Decompress
• _GetAllChunksCompressor
• _GetDecodeBufferSize
• _GetCompressedBufferSizeNeeded

Why?

These are direct native bindings created via koffi and may change without notice. They also lack the abstraction provided by the wrapper.

Always use:

• compress()
• decompress()
• maxCompressedSize()
• minDecodeSize()
• getCompressor()

Advanced Notes

• Compression level affects speed vs ratio
• Kraken is the default compressor (good balance)
• Buffer slicing is handled internally (offset, size supported)
• Native memory allocation is unsafe (Buffer.allocUnsafe) for performance

Type Support

Check typings for:

• OodleCompressor
• OodleCompressionLevel
• OodleFuzzSafe
• OodleCheckCRC
• OodleVerbosity
• OodleDecodeThreadPhase

Example: Full Pipeline

const oodle = await Oodle.Create();

const data = Buffer.from("example data".repeat(100));

const compressed = oodle.compress({ buffer: data });

const decompressed = oodle.decompress(
	{ buffer: compressed },
	data.length
);

console.log(decompressed.equals(data)); // true