import { ChunkCollection } from './chunk-utils.js';

/**
 * High-level parameters for configuring the Clay encoder wasm instance.
 *
 * See [src/clay.clay.h](/src/clay/clay.h)
 */
interface EncoderOptions {
    /**
     * Total number of output chunks (systematic + parity)
     */
    n: number;
    /**
     * Number of systematic data chunks
     */
    k: number;
    /**
     * Number of helper nodes for repair
     */
    d: number;
    /**
     * Size in bytes of every chunk exchanged with the encoder.
     * @example 1024 // Each chunk is 1KB
     * TODO: Chunks are 2MB? so... 2_097_152 bytes?
     */
    chunkSizeBytes: number;
}
type EncoderAPI = {
    /**
     * Copy a caller-provided data chunk into the wasm encoder's staging buffer.
     *
     * The chunk index must be within the systematic range (0 ≤ idx < k) and the
     * provided `Uint8Array` should already be sized to `chunkSizeBytes`. The
     * buffer is duplicated into wasm memory immediately, so the caller can reuse
     * or mutate `data` right away.
     */
    setChunk(idx: number, data: Uint8Array): void;
    /**
     * Execute the Clay erasure-coding routine using the staged systematic data.
     *
     * Once this returns the wasm instance holds all `n` chunks (original data
     * plus parity) ready to be fetched with `getChunk`. Callers should stage
     * every systematic chunk before invoking `run` to avoid undefined behaviour.
     */
    run(): void;
    /**
     * Retrieve a systematic or parity chunk as a detached copy of wasm memory.
     *
     * The `idx` may target any chunk in the encoded range (0 ≤ idx < n). The
     * returned `Uint8Array` is a copy, so it can be mutated or retained without
     * impacting the underlying wasm buffers.
     */
    getChunk(idx: number): Uint8Array;
    /**
     * Convenience helper that stages `k` input chunks, runs the encoder, and
     * returns every chunk (systematic + parity) in a single call.
     */
    erasureCode(input: Uint8Array[] | Uint8Array): ChunkCollection;
    /**
     * Get an array of the chunk merkle tree roots, calculated by processing the samples as leaves of a binary merkle tree.
     */
    getChunkMerkleRoots(): Uint8Array[];
    /**
     * Optional hook for explicitly releasing wasm-side resources if the runtime
     * ever exposes a manual teardown routine. The encoder currently relies on GC
     * to dispose wasm memory, so this is reserved for future use.
     */
    free?(): void;
};
/**
 * ### Builds the JS facade for the Clay encoder.
 *
 * The wasm side only needs a handful of monotonic, long-lived allocations
 * (params, encoder instance, staging buffer), so we lean on a simple bump allocator rooted at
 * `__heap_base` rather than shipping a heavier malloc/free pair.
 *
 * **Important:** Coding parameters (n, k, d, chunkSizeBytes) are fixed for the lifetime of
 * the encoder instance. These parameters determine WASM memory layout and buffer sizes.
 * To use different coding parameters, create a new encoder instance.
 *
 * Clay currently targets memory32 builds, so the linear memory tops out just under 4 GiB.
 * Workloads that require erasure coding > 4 GiB will need to separate the original blob into chunks.
 *
 * This should NOT be an issue since we first create 10MiB chunksets of blobs before erasure coding,
 * but just calling it out here for posterity.
 *
 * Though [memory64](https://webassembly.org/features/) exists, we target memory32 builds because
 * memory64 is not supported on all browsers, namely Safari. If `n * chunkSizeBytes` approaches the
 * memory32 ceiling, consider shrinking chunks or adopting memory64 once it's viable across your
 * deployment targets.
 *
 * Alternatively, non-browser platforms can use the more performant C implementation of clay-codes.
 */
declare function makeEncoderAPI(instance: WebAssembly.Instance, opts: EncoderOptions): EncoderAPI;

export { type EncoderAPI, type EncoderOptions, makeEncoderAPI };