compress

const brotliAvailable

true when the Brotli encoder and decoder backend libraries are available.

Use this before selecting { format: 'brotli' } in portable code. When this value is false, Brotli operations throw from the underlying backend.

import { brotliAvailable, compress } from 'fino:compress';

const format = brotliAvailable ? 'brotli' : 'gzip';
const bytes = compress(new Uint8Array([1, 2, 3]), { format });
console.log(bytes.byteLength);

const zstdAvailable

true when the Zstandard backend library (libzstd) is available.

Use this before selecting { format: 'zstd' } in portable code. When this value is false, Zstandard operations throw from the underlying backend.

import { zstdAvailable, compress } from 'fino:compress';

const format = zstdAvailable ? 'zstd' : 'gzip';
const bytes = compress(new Uint8Array([1, 2, 3]), { format });
console.log(bytes.byteLength);

const lz4Available

true when the LZ4 backend library (liblz4) is available.

Use this before selecting { format: 'lz4' } in portable code. The lz4 format produces and consumes the interoperable LZ4 Frame format. When this value is false, LZ4 operations throw from the underlying backend.

import { lz4Available, compress } from 'fino:compress';

const format = lz4Available ? 'lz4' : 'gzip';
const bytes = compress(new Uint8Array([1, 2, 3]), { format });
console.log(bytes.byteLength);

const snappyAvailable

true when the Snappy backend library (libsnappy) is available.

Use this before selecting { format: 'snappy' } in portable code. The snappy format is the Snappy raw block format (as used by Apache Parquet); it is a block codec, so streaming buffers input and emits one block on finish(). When this value is false, Snappy operations throw from the underlying backend.

import { snappyAvailable, compress } from 'fino:compress';

const format = snappyAvailable ? 'snappy' : 'gzip';
const bytes = compress(new Uint8Array([1, 2, 3]), { format });
console.log(bytes.byteLength);

function compress(data: ByteInput, options: CompressOptions): Uint8Array

Compress one byte buffer and return a single compressed byte array.

This one-shot helper keeps both input and output in memory and returns the complete compressed stream as a single Uint8Array. options.format is required, and invalid options throw TypeError. Selecting a format whose backend library is unavailable, or a backend compression failure, throws.

import { compress } from 'fino:compress';

const input = new TextEncoder().encode('hello');
const gzipped = compress(input, { format: 'gzip', level: 6 });
console.log(gzipped.byteLength);

function decompress(data: ByteInput, options: DecompressOptions): Uint8Array

Decompress one byte buffer and return a single decompressed byte array.

The input format must match options.format. The helper keeps the full decompressed output in memory and throws when the stream is invalid, truncated, or uses a format that is unavailable. It does not cap the decompressed output size; callers should use streaming decompression when handling untrusted or potentially large compressed input.

import { compress, decompress } from 'fino:compress';

const packed = compress(new Uint8Array([1, 2, 3]), { format: 'deflate' });
const plain = decompress(packed, { format: 'deflate' });
console.log(plain.length);

function createCompressor(options: CompressOptions): Compressor

Create a stateful compressor for the requested format.

This is a factory wrapper around new Compressor(options). It returns an object that must be finished or closed to release backend state.

import { createCompressor } from 'fino:compress';

const compressor = createCompressor({ format: 'gzip' });
compressor.close();

function createDecompressor(options: DecompressOptions): Decompressor

Create a stateful decompressor for the requested format.

This is a factory wrapper around new Decompressor(options). The selected format must match the stream that will be written.

import { createDecompressor } from 'fino:compress';

const decompressor = createDecompressor({ format: 'gzip' });
decompressor.close();

class Compressor implements CompressionTransform {

Stateful compressor for chunked writes or async iterable transforms.

A compressor may buffer internally and return zero or more output chunks for each write(). Always call finish() to flush final bytes. Call close() when abandoning the stream early.

import { Compressor } from 'fino:compress';

const compressor = new Compressor({ format: 'gzip' });
const chunks = [
  ...compressor.write(new Uint8Array([1, 2])),
  ...compressor.finish(),
];
compressor.close();
console.log(chunks.length);

Constructors

import { Compressor } from 'fino:compress';

const compressor = new Compressor({ format: 'deflate-raw' });
compressor.close();

Methods

import { Compressor } from 'fino:compress';

const compressor = new Compressor({ format: 'gzip' });
const chunks = compressor.write(new Uint8Array([1, 2, 3]));
chunks.push(...compressor.finish());
compressor.close();

import { Compressor } from 'fino:compress';

const compressor = new Compressor({ format: 'deflate' });
const finalChunks = compressor.finish();
compressor.close();
console.log(finalChunks.length);

import { Compressor } from 'fino:compress';

async function* source() {
  yield new Uint8Array([1, 2, 3]);
}
const compressor = new Compressor({ format: 'gzip' });
for await (const chunk of compressor.transform(source())) {
  console.log(chunk.byteLength);
}
compressor.close();

import { Compressor } from 'fino:compress';

const compressor = new Compressor({ format: 'gzip' });
compressor.close();

class Decompressor implements CompressionTransform {

Stateful decompressor for chunked writes or async iterable transforms.

A decompressor may buffer partial frames internally. Always call finish() after the last compressed chunk so truncated streams are detected and final output is flushed. The decompressor does not enforce an output-size limit; count returned chunk sizes in the caller when processing untrusted input.

import { Decompressor, compress } from 'fino:compress';

const packed = compress(new Uint8Array([1, 2]), { format: 'gzip' });
const decompressor = new Decompressor({ format: 'gzip' });
const chunks = [...decompressor.write(packed), ...decompressor.finish()];
decompressor.close();
console.log(chunks.length);

Constructors

import { Decompressor } from 'fino:compress';

const decompressor = new Decompressor({ format: 'deflate' });
decompressor.close();

Methods

import { Decompressor, compress } from 'fino:compress';

const packed = compress(new Uint8Array([1]), { format: 'gzip' });
const decompressor = new Decompressor({ format: 'gzip' });
const chunks = decompressor.write(packed);
chunks.push(...decompressor.finish());
decompressor.close();

import { Decompressor } from 'fino:compress';

const decompressor = new Decompressor({ format: 'gzip' });
const finalChunks = decompressor.finish();
decompressor.close();
console.log(finalChunks.length);

import { Decompressor } from 'fino:compress';

async function* compressedChunks() {
  yield new Uint8Array();
}
const decompressor = new Decompressor({ format: 'gzip' });
for await (const chunk of decompressor.transform(compressedChunks())) {
  console.log(chunk.byteLength);
}
decompressor.close();

import { Decompressor } from 'fino:compress';

const decompressor = new Decompressor({ format: 'deflate-raw' });
decompressor.close();

type ByteInput = Uint8Array | ArrayBuffer

Binary input accepted by compression helpers.

Uint8Array values are used directly; ArrayBuffer values become views. Strings are intentionally not accepted here so callers choose their own text encoding before compression.

import type { ByteInput } from 'fino:compress';
const input: ByteInput = new Uint8Array([1, 2, 3]);

type CompressionFormat = 'gzip' | 'deflate' | 'deflate-raw' | 'brotli' | 'zstd' | 'lz4' | 'snappy'

Compression formats accepted by fino:compress.

gzip, deflate, and deflate-raw are handled by zlib. brotli, zstd, lz4, and snappy each have their own backend that loads the matching system library, and may be unavailable at runtime when that library cannot be loaded — check the per-format *Available flags on fino:compress before relying on them.

import type { CompressionFormat } from 'fino:compress';
const format: CompressionFormat = 'gzip';

interface CompressOptions {

Options for one-shot or streaming compression.

format is required. level is backend-specific and optional; see the level property for how each backend interprets it.

import type { CompressOptions } from 'fino:compress';
const opts: CompressOptions = { format: 'gzip', level: 6 };

Properties

import type { CompressOptions } from 'fino:compress';
const options: CompressOptions = { format: 'brotli' };
options.format;

import type { CompressOptions } from 'fino:compress';
const options: CompressOptions = { format: 'deflate', level: 1 };
options.level;

interface DecompressOptions {

Options for one-shot or streaming decompression.

Only format is accepted because decompression does not use a level.

import type { DecompressOptions } from 'fino:compress';
const opts: DecompressOptions = { format: 'deflate-raw' };

Properties

import type { DecompressOptions } from 'fino:compress';
const options: DecompressOptions = { format: 'gzip' };
options.format;

interface CompressionTransform {

Stateful compressor/decompressor interface shared by backends.

write may return zero or more chunks for each input. finish finalizes the stream and closes native state. Calling methods after close may throw.

import type { ByteInput, CompressionTransform } from 'fino:compress';
function drain(codec: CompressionTransform, chunk: ByteInput) {
  return [...codec.write(chunk), ...codec.finish()];
}

Methods

const parts = codec.write(new Uint8Array([1, 2, 3]));

const finalParts = codec.finish();

for await (const part of codec.transform(source)) {
  void part;
}

codec.close();