taglib-wasm/dist/src/runtime/wasi-memory.d.ts

TagLib-Wasm is the universal tagging library for TypeScript/JavaScript platforms: Browsers, Node.js, Deno, Bun, Cloudflare Workers, and Electron apps

/**
 * @fileoverview RAII Memory Management for WASI
 *
 * Implements proper RAII pattern using Symbol.dispose and `using` statements.
 * Each allocation has single responsibility with automatic cleanup.
 */
import { TagLibError } from "../errors/base.js";
/**
 * Minimal memory interface: only `.buffer` is used (never `.grow()`).
 * Accepts both real WebAssembly.Memory and plain buffer-only shims.
 */
export type WasmMemoryLike = {
    readonly buffer: ArrayBufferLike;
};
/**
 * WASM exports interface matching our C API
 */
export interface WasmExports {
    memory: WasmMemoryLike;
    malloc(size: number): number;
    free(ptr: number): void;
}
/**
 * Re-usable heap views (must be refreshed after any memory growth!)
 */
export declare const heapViews: (mem: WasmMemoryLike) => {
    u8: Uint8Array<ArrayBufferLike>;
    i8: Int8Array<ArrayBufferLike>;
    u16: Uint16Array<ArrayBufferLike>;
    i16: Int16Array<ArrayBufferLike>;
    u32: Uint32Array<ArrayBufferLike>;
    dv: DataView<ArrayBufferLike>;
};
/**
 * Single allocation = single responsibility, auto-free
 * Implements proper RAII with Symbol.dispose
 */
export declare class WasmAlloc {
    #private;
    constructor(wasm: WasmExports, size: number);
    get ptr(): number;
    get size(): number;
    /**
     * Write bytes to allocation
     */
    write(bytes: Uint8Array, offset?: number): void;
    /**
     * Read bytes from allocation (zero-copy view)
     */
    read(len?: number, offset?: number): Uint8Array;
    /**
     * Write C string with null terminator.
     * Accepts a string or pre-encoded UTF-8 bytes (avoids double-encoding).
     */
    writeCString(input: string | Uint8Array): void;
    /**
     * Read C string (null-terminated)
     */
    readCString(): string;
    /**
     * Write 32-bit integer (little-endian)
     */
    writeUint32(value: number, offset?: number): void;
    /**
     * Read 32-bit integer (little-endian)
     */
    readUint32(offset?: number): number;
    /**
     * Automatic cleanup via Symbol.dispose
     */
    [Symbol.dispose](): void;
}
/**
 * Optional arena to collect many allocations & free them together
 * Useful for operations that need multiple related allocations
 */
export declare class WasmArena {
    #private;
    constructor(wasm: WasmExports);
    /**
     * Allocate memory within this arena
     */
    alloc(size: number): WasmAlloc;
    /**
     * Allocate and write string (encodes once)
     */
    allocString(str: string): WasmAlloc;
    /**
     * Allocate and write buffer
     */
    allocBuffer(buffer: Uint8Array): WasmAlloc;
    /**
     * Allocate 32-bit integer
     */
    allocUint32(value?: number): WasmAlloc;
    /**
     * Automatic cleanup of all allocations
     */
    [Symbol.dispose](): void;
}
/**
 * Helper for common memory operations with proper error context
 */
export declare class WasmMemoryError extends TagLibError {
    readonly operation: string;
    readonly errorCode?: number | undefined;
    constructor(message: string, operation: string, errorCode?: number | undefined);
}
//# sourceMappingURL=wasi-memory.d.ts.map