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

Static Dataflow Analyzer and Program Slicer for the R Programming Language

import type { Readable } from 'stream';
import { type SigDbIndex } from './index-format';
/** whether a bundle path is a compressed (`.br`/`.zst`/`.gz`) source that must be decompressed to be seekable */
export declare const isCompressed: (f: string) => boolean;
/** read and parse the header (line 1) from a buffer/string of NDJSON */
export declare function parseHeader(text: string): Record<string, unknown> | undefined;
/** a readable stream of the bundle's plain NDJSON, transparently decompressing `.gz`/`.br`/`.zst` inputs */
export declare function sigDbStream(file: string): Readable;
/**
 * Resolve a manifest-relative file to the best source this runtime can read: a plain (already seekable) file
 * if present, else the most-preferred compressed variant that exists AND is decompressible here -- `.zst` first
 * when this Node supports zstd, otherwise `.br` (then `.gz`). A `.zst` is never returned on a Node without zstd
 * (it could not be decompressed), so `.br`-only bundles read on any Node. Falls back to the plain path.
 */
export declare function resolveSource(baseDir: string, relPath: string): string;
/**
 * Directory for decompressed, hash-keyed caches. Honours `$FLOWR_SIGDB_CACHE` / `$FLOWR_CACHE_DIR`, then the
 * platform cache home (`$XDG_CACHE_HOME` on Linux, `%LOCALAPPDATA%` on Windows), then `~/.cache/flowr`, falling
 * back to the OS temp dir (so it works in a read-only Docker image where only `/tmp` is writable -- mount a
 * volume at the cache dir to persist it).
 */
export declare function sigDbCacheDir(override?: string, create?: boolean): string;
/** read the (small) header line of a possibly-compressed bundle without decompressing the whole thing */
export declare function readHeaderOf(source: string): Promise<Record<string, unknown> | undefined>;
/** where an index for a decompressed source comes from -- a caller-supplied one (e.g. a manifest) or the sibling `.idx` */
export interface EnsureOptions {
    cacheDir?: string;
    hash?: string;
    index?: SigDbIndex;
    /** the source is not a seekable bundle (e.g. a shared dictionary file) -- decompress only, write no `.idx` */
    indexless?: boolean;
}
/** whether a compressed source with the given content hash has already been unpacked into its decompressed cache */
export declare function isUnpacked(hash: string, cacheDir?: string): boolean;
/**
 * Ensure a seekable plain `.sigs.ndjson` (+ its `.idx`) exists for `source`, decompressing a `.br`/`.zst`/`.gz`
 * once into a hash-keyed cache the first time and reusing it on every later startup. The index may be
 * supplied by the caller (e.g. embedded in a manifest) so no separate `.idx` file needs to ship.
 */
export declare function ensurePlain(source: string, opts?: EnsureOptions): Promise<string>;
/** synchronous {@link ensurePlain} (blocking decompression) -- a `hash` must be supplied to key the cache */
export interface EnsurePlainSyncOptions extends EnsureOptions {
    hash: string;
}
/** synchronous {@link ensurePlain} (blocking decompression); the supplied `hash` keys the decompress cache */
export declare function ensurePlainSync(source: string, opts: EnsurePlainSyncOptions): string;