@openmeteo/file-reader/dist/index.d.ts

JavaScript reader for the om file format using WebAssembly

interface OmFileReaderBackend {
    /**
     * Get bytes from the backend at the specified offset and size
     * @param offset The offset in bytes from the start of the file
     * @param size The number of bytes to read
     */
    getBytes(offset: number, size: number): Promise<Uint8Array>;
    /**
     * Tell the backend to prefetch data at the specified offset and size
     * @param offset The offset in bytes from the start of the file
     * @param size The number of bytes to prefetch
     */
    prefetchData(offset: number, size: number): Promise<void>;
    /**
     * Get the total size of the file in bytes
     */
    count(): Promise<number>;
    /**
     * Close the backend and release any resources
     */
    close(): Promise<void>;
}

interface Range {
    start: number;
    end: number;
}
interface OffsetSize {
    offset: number;
    size: number;
}
declare enum CompressionType {
    PforDelta2dInt16 = 0,
    FpxXor2d = 1,
    PforDelta2d = 2,
    PforDelta2dInt16Logarithmic = 3,
    None = 4
}
declare enum OmDataType {
    None = 0,
    Int8 = 1,
    Uint8 = 2,
    Int16 = 3,
    Uint16 = 4,
    Int32 = 5,
    Uint32 = 6,
    Int64 = 7,
    Uint64 = 8,
    Float = 9,
    Double = 10,
    String = 11,
    Int8Array = 12,
    Uint8Array = 13,
    Int16Array = 14,
    Uint16Array = 15,
    Int32Array = 16,
    Uint32Array = 17,
    Int64Array = 18,
    Uint64Array = 19,
    FloatArray = 20,
    DoubleArray = 21,
    StringArray = 22
}
type TypedArray = Int8Array | Uint8Array | Int16Array | Uint16Array | Int32Array | Uint32Array | Float32Array | Float64Array | BigInt64Array | BigUint64Array;

interface WasmModule {
    _malloc(size: number): number;
    _free(ptr: number): void;
    setValue(ptr: number, value: any, type: string): void;
    getValue(ptr: number, type: string): any;
    HEAPU8: Uint8Array;
    om_header_size(): number;
    om_header_type(ptr: number): number;
    om_trailer_size(): number;
    om_trailer_read(trailerPtr: number, offsetPtr: number, sizePtr: number): boolean;
    om_variable_init(dataPtr: number): number;
    om_variable_get_type(variable: number): number;
    om_variable_get_compression(variable: number): number;
    om_variable_get_scale_factor(variable: number): number;
    om_variable_get_add_offset(variable: number): number;
    om_variable_get_dimension_count(variable: number): number;
    om_variable_get_dimension_value(variable: number, index: bigint): number;
    om_variable_get_chunk_count(variable: number): number;
    om_variable_get_chunk_value(variable: number, index: bigint): number;
    om_variable_get_name_count(variable: number): number;
    om_variable_get_name_ptr(variable: number): number;
    om_variable_get_children_count(variable: number): number;
    om_variable_get_children(variable: number, index: number, count: number, offsetPtr: number, sizePtr: number): boolean;
    om_variable_get_scalar(variable: number, ptrPtr: number, sizePtr: number): number;
    om_decoder_init(decoderPtr: number, variable: number, nDims: bigint, readOffsetPtr: number, readCountPtr: number, intoCubeOffsetPtr: number, intoCubeDimensionPtr: number, ioSizeMerge: bigint, ioSizeMax: bigint): number;
    om_decoder_init_index_read(decoder: number, indexReadPtr: number): void;
    om_decoder_init_data_read(dataReadPtr: number, indexReadPtr: number): void;
    om_decoder_read_buffer_size(decoderPtr: number): number;
    om_decoder_next_index_read(decoder: number, indexRead: number): boolean;
    om_decoder_next_data_read(decoder: number, dataRead: number, indexData: number, indexCount: bigint, error: number): boolean;
    om_decoder_decode_chunks(decoder: number, chunkIndex: number, data: number, count: bigint, output: number, chunkBuffer: number, error: number): boolean;
    OM_HEADER_INVALID: number;
    OM_HEADER_LEGACY: number;
    OM_HEADER_READ_TRAILER: number;
    ERROR_OK: number;
    DATA_TYPE_INT8_ARRAY: number;
    DATA_TYPE_UINT8_ARRAY: number;
    DATA_TYPE_INT16_ARRAY: number;
    DATA_TYPE_UINT16_ARRAY: number;
    DATA_TYPE_INT32_ARRAY: number;
    DATA_TYPE_UINT32_ARRAY: number;
    DATA_TYPE_INT64_ARRAY: number;
    DATA_TYPE_UINT64_ARRAY: number;
    DATA_TYPE_FLOAT_ARRAY: number;
    DATA_TYPE_DOUBLE_ARRAY: number;
    sizeof_decoder: number;
}
declare function initWasm(): Promise<WasmModule>;
declare function getWasmModule(): WasmModule;

declare class OmFileReader {
    private backend;
    private wasm;
    private variable;
    private variableDataPtr;
    private metadataCache;
    constructor(backend: OmFileReaderBackend, wasm?: WasmModule);
    /**
     * Static factory method to create and initialize an OmFileReader
     */
    static create(backend: OmFileReaderBackend): Promise<OmFileReader>;
    initialize(): Promise<OmFileReader>;
    private _getString;
    dataType(): number;
    compression(): number;
    scaleFactor(): number;
    addOffset(): number;
    getDimensions(): number[];
    getChunkDimensions(): number[];
    getName(): string | null;
    numberOfChildren(): number;
    getChild(index: number): Promise<OmFileReader | null>;
    /**
     * Searches direct children by name. Does not search recursively.
     */
    getChildByName(name: string): Promise<OmFileReader | null>;
    initChildFromOffsetSize(offsetSize: OffsetSize): Promise<OmFileReader>;
    /**
     * Get child metadata by index.
     */
    _getChildMetadata(index: number): OffsetSize | null;
    /**
     * Find a variable by its path (e.g., "parent/child/grandchild")
     */
    findByPath(path: string): Promise<OmFileReader | null>;
    /**
     * Navigate through a path recursively
     */
    navigatePath(parts: string[]): Promise<OmFileReader | null>;
    readScalar<T>(dataType: OmDataType): T | null;
    private newIndexRead;
    private newDataRead;
    read(dataType: OmDataType, dimRanges: Range[], ioSizeMax?: bigint, ioSizeMerge?: bigint, prefetch?: boolean): Promise<TypedArray>;
    /**
     * Read data into an existing TypedArray with specified dimension ranges
     * @param dataType The data type to read
     * @param output The TypedArray to read data into
     * @param dimRanges Ranges for each dimension to read
     * @param ioSizeMax Maximum I/O size (default: 65536)
     * @param ioSizeMerge Merge threshold for I/O operations (default: 512)
     */
    readInto(dataType: OmDataType, output: TypedArray, dimRanges: Range[], ioSizeMax?: bigint, ioSizeMerge?: bigint, prefetch?: boolean): Promise<void>;
    decodePrefetch(decoderPtr: number): Promise<void>;
    private decode;
    private readDataBlock;
    /**
     * Helper method to copy data from WASM memory to a TypedArray with the correct type
     */
    private copyToTypedArray;
    dispose(): void;
}

declare class FileBackendNode implements OmFileReaderBackend {
    private filePath;
    private memory;
    private fileSize;
    private fileHandle;
    constructor(source: string | Uint8Array | ArrayBuffer);
    count(): Promise<number>;
    getBytes(offset: number, size: number): Promise<Uint8Array>;
    prefetchData(_offset: number, _bytes: number): Promise<void>;
    close(): Promise<void>;
}

declare class MemoryHttpBackend implements OmFileReaderBackend {
    private url;
    private fileSize;
    private fileData;
    private loadPromise;
    private countPromise;
    private maxFileSize;
    private onProgress?;
    private debug;
    /**
     * Create a new MemoryHttpBackend
     * @param options Configuration options
     */
    constructor(options: {
        url: string;
        maxFileSize?: number;
        onProgress?: (loaded: number, total: number) => void;
        debug?: boolean;
    });
    /**
     * Get the total size of the file
     */
    count(): Promise<number>;
    /**
     * Load the entire file into memory
     */
    loadFile(): Promise<void>;
    /**
     * Get bytes from the file
     * @param offset The starting position in the file
     * @param size The number of bytes to read
     */
    getBytes(offset: number, size: number): Promise<Uint8Array>;
    /**
     * Check if the file is fully loaded
     */
    isLoaded(): boolean;
    /**
     * Get the current loaded data or null if not loaded
     */
    getFileData(): Uint8Array | null;
    /**
     * Force a reload of the file
     */
    reload(): Promise<void>;
    prefetchData(_offset: number, _bytes: number): Promise<void>;
    /**
     * Close the backend and release any resources
     */
    close(): Promise<void>;
}

declare function setupGlobalCache(blockSize?: number, maxBlocks?: number): void;
interface OmHttpBackendOptions {
    url: string;
    debug?: boolean;
    timeoutMs?: number;
    retries?: number;
}
/**
 * Backend for reading from HTTP servers with partial read support using Range requests.
 * Checks last modified header and ETag.
 */
declare class OmHttpBackend implements OmFileReaderBackend {
    private readonly url;
    private readonly debug;
    private readonly timeoutMs;
    private readonly retries;
    private fileSize;
    private lastModified;
    private eTag;
    private metadataPromise;
    constructor(options: OmHttpBackendOptions);
    /**
     * Get cache key based on URL, ETag, and Last-Modified
     */
    get cacheKey(): bigint;
    /**
     * Fetch metadata using HEAD request
     */
    private fetchMetadata;
    /**
     * Get the total size of the file
     */
    count(): Promise<number>;
    /**
     * Get bytes from the file using Range requests
     */
    getBytes(offset: number, size: number): Promise<Uint8Array>;
    prefetchData(_offset: number, _bytes: number): Promise<void>;
    asCachedReader(): Promise<OmFileReader>;
    /**
     * Close the backend and release resources
     */
    close(): Promise<void>;
}

type BlockKey = bigint;
declare class BlockCacheCoordinator {
    private cache;
    constructor(blockSize: number, maxBlocks: number);
    blockSize(): number;
    maxBlocks(): number;
    get(key: BlockKey, fetchFn: () => Promise<Uint8Array>): Promise<Uint8Array>;
    prefetch(key: BlockKey, fetchFn: () => Promise<Uint8Array>): void;
    clear(): void;
}

/**
 * Wraps a backend for caching blocks of data.
 */
declare class BlockCacheBackend implements OmFileReaderBackend {
    private backend;
    private cacheCoordinator;
    private cacheKey;
    constructor(backend: OmFileReaderBackend, cacheCoordinator: BlockCacheCoordinator, cacheKey: bigint);
    count(): Promise<number>;
    prefetchData(offset: number, count: number): Promise<void>;
    getBytes(offset: number, size: number): Promise<Uint8Array>;
    close(): Promise<void>;
}

export { BlockCacheBackend, CompressionType, FileBackendNode, MemoryHttpBackend, OmDataType, OmFileReader, OmHttpBackend, getWasmModule, initWasm, setupGlobalCache };
export type { OffsetSize, OmFileReaderBackend, Range, TypedArray };