/**
 * @packageDocumentation Read/write IOStream backed by Deno's native file system API
 * (`Deno.FsFile`).
 *
 * Because Deno types are not available in a standard TypeScript / Node.js
 * environment, minimal inline declarations are provided below so that the
 * module compiles under any `tsc` target without needing `@types/deno` or a
 * custom lib.
 */
import { ByteVector } from "../byteVector.js";
import { IOStream } from "./ioStream.js";
import { type offset_t, Position } from "./types.js";
/**
 * A read/write {@link IOStream} backed by a `Deno.FsFile` from Deno's native
 * file system API.
 *
 * **Read-write mode** (default): opens the file with `{ read: true, write: true }`.
 * All mutating operations (`writeBlock`, `insert`, `removeBlock`, `truncate`)
 * are available.
 *
 * **Read-only mode**: opens the file with `{ read: true }` only.  Any attempt
 * to call a mutating method throws an `Error`.
 *
 * The constructor is private. Always use one of the async factories:
 * ```ts
 * const stream = await DenoFileStream.open("/path/to/audio.mp3");
 * const ro     = await DenoFileStream.openReadOnly("/path/to/audio.mp3");
 * ```
 *
 * @example
 * // Read-write
 * const stream = await DenoFileStream.open("song.mp3");
 * const tag    = await FileRef.open(stream);
 * await stream.close();
 *
 * @example
 * // Read-only
 * const stream = await DenoFileStream.openReadOnly("song.flac");
 * const tag    = await FileRef.open(stream);
 * await stream.close();
 */
export declare class DenoFileStream extends IOStream {
    private readonly _path;
    private readonly _readOnly;
    private readonly _file;
    private _open;
    private constructor();
    /**
     * Opens a file at `path` for reading and optionally writing.
     *
     * Internally calls:
     * ```ts
     * await Deno.open(path, { read: true, write: true, create: create ?? false })
     * ```
     *
     * @param path   - Absolute or relative path to the file.
     * @param create - When `true` the file is created if it does not exist.
     *   Defaults to `false`.
     * @returns A fully initialised `DenoFileStream` in read-write mode.
     */
    static open(path: string, create?: boolean): Promise<DenoFileStream>;
    /**
     * Opens a file at `path` for reading only.
     *
     * Internally calls:
     * ```ts
     * await Deno.open(path, { read: true })
     * ```
     *
     * @param path - Absolute or relative path to the file.
     * @returns A fully initialised `DenoFileStream` in read-only mode.
     */
    static openReadOnly(path: string): Promise<DenoFileStream>;
    /** Returns the file path this stream was opened with. */
    name(): string;
    /** Returns `true` if this stream was opened in read-only mode. */
    readOnly(): boolean;
    /** Returns `true` if the stream has not yet been closed. */
    isOpen(): boolean;
    /**
     * Reads up to `length` bytes from the current file position and advances
     * the position by the number of bytes actually read.
     *
     * @param length - Maximum number of bytes to read.
     * @returns Resolves with a {@link ByteVector} containing the bytes read.
     *   May be shorter than `length` when the end of the file is reached.
     */
    readBlock(length: number): Promise<ByteVector>;
    /**
     * Writes `data` at the current file position, extending the file if
     * necessary, and advances the position by `data.length`.
     *
     * @param data - The bytes to write.
     * @throws {Error} If the stream is read-only.
     */
    writeBlock(data: ByteVector): Promise<void>;
    /**
     * Inserts `data` at byte offset `start`, optionally replacing `replace`
     * bytes of existing content. The position is set to `start + data.length`
     * after the operation.
     *
     * Because `Deno.FsFile` does not support in-place insertion, this method
     * reads the tail of the file, writes the new data at `start`, then writes
     * the tail back, and truncates if necessary.
     *
     * @param data    - The bytes to insert.
     * @param start   - Byte offset at which to begin the insertion.
     * @param replace - Number of existing bytes to overwrite. Defaults to 0.
     * @throws {Error} If the stream is read-only.
     */
    insert(data: ByteVector, start: offset_t, replace?: number): Promise<void>;
    /**
     * Removes `length` bytes beginning at byte offset `start`, shifting all
     * subsequent bytes towards the beginning of the file.
     *
     * @param start  - Byte offset of the first byte to remove.
     * @param length - Number of bytes to remove.
     * @throws {Error} If the stream is read-only.
     */
    removeBlock(start: offset_t, length: number): Promise<void>;
    /**
     * Moves the read/write position within the file.
     *
     * @param offset   - Number of bytes to move relative to `position`.
     * @param position - Reference point for the seek. Defaults to
     *   {@link Position.Beginning}.
     */
    seek(offset: offset_t, position?: Position): Promise<void>;
    /** Resets the stream position to the beginning of the file. */
    clear(): Promise<void>;
    /** Returns the current read/write position in bytes from the start of the file. */
    tell(): Promise<offset_t>;
    /** Returns the total size of the file in bytes. */
    length(): Promise<offset_t>;
    /**
     * Truncates or zero-extends the file to exactly `length` bytes.
     *
     * @param length - The desired file length in bytes.
     * @throws {Error} If the stream is read-only.
     */
    truncate(length: offset_t): Promise<void>;
    /**
     * Closes the underlying `Deno.FsFile`. After calling `close()`,
     * {@link isOpen} returns `false`.
     */
    close(): Promise<void>;
}
//# sourceMappingURL=denoFileStream.d.ts.map