@eagleoutice/flowr-dev/project/sigdb/codec.d.ts

Static Dataflow Analyzer and Program Slicer for the R Programming Language

import type { Transform } from 'stream';
/** whether the running Node exposes the `node:zlib` zstd API (Node 22.15+ / 23.8+) */
export declare function zstdSupported(): boolean;
/** on-disk compression codec for a sigdb bundle */
export type SigDbCodec = 'brotli' | 'zstd';
/** the richer codec, preferred by readers when this Node supports it (writers always additionally emit `.br`) */
export declare const DefaultSigDbCodec: SigDbCodec;
/** compressed extensions a reader understands (outer compression only); `.gz` is read-only legacy */
export declare const CompressedExts: readonly [".br", ".zst", ".gz"];
/** whether a bundle path is a compressed source that must be decompressed to be seekable */
export declare function isCompressedExt(file: string): boolean;
/** the compressed extension of a path, or `undefined` if it is a plain (uncompressed) source */
export declare function compressedExtOf(file: string): string | undefined;
/** strip a trailing compressed extension (`.br`/`.zst`/`.gz`) from a filename, if present */
export declare function stripCompressedExt(name: string): string;
/** regex alternation matching an optional trailing compressed extension, e.g. `(?:\.br|\.zst|\.gz)?` */
export declare const CompressedExtPattern: string;
/** options shared by the (de)compression codecs; unused knobs are ignored by a codec that lacks them */
export interface CodecCompressOptions {
    /** compression level -- brotli quality (0..11), zstd level (1..22) */
    level?: number;
    /** brotli window bits (10..30); above 24 enables large-window mode. Ignored by zstd */
    lgwin?: number;
    /** uncompressed size hint for the compressor */
    sizeHint?: number;
}
/** a compression codec: its file extension plus sync + streaming (de)compression */
export interface SigDbCodecSpec {
    readonly codec: SigDbCodec;
    readonly ext: string;
    compressSync(buf: Buffer | string, opts?: CodecCompressOptions): Buffer;
    createCompress(opts?: CodecCompressOptions): Transform;
}
export declare const BrotliCodec: SigDbCodecSpec;
export declare const ZstdCodec: SigDbCodecSpec;
/** the codec spec for a codec name (used when writing) */
export declare function codecFor(codec: SigDbCodec): SigDbCodecSpec;
/**
 * The codec specs a writer emits: brotli `.br` always (the universal fallback -- every Node ships it), plus
 * zstd `.zst` when this Node can produce/read it. So a `.br` fallback is guaranteed next to every `.zst`.
 */
export declare function writeCodecs(): readonly SigDbCodecSpec[];
/**
 * Compressed extensions this runtime can actually decompress, most-preferred first (zstd before brotli when
 * supported). `.zst` is omitted entirely when this Node lacks zstd, so a reader never picks a variant it cannot read.
 */
export declare function readableExtsPreferred(): readonly string[];
/** a streaming decompressor for a compressed source, chosen by its extension (`.zst`/`.gz`/`.br`) */
export declare function createDecompressFor(file: string): Transform;
/** synchronously decompress a compressed buffer, choosing the codec by the source's extension */
export declare function decompressSyncFor(file: string, raw: Buffer): Buffer;