/**
 * Codec for encoding/decoding values to/from strings for WAL storage.
 * Used to serialize/deserialize records written to and read from WAL files.
 */
export type Codec<I, O = string> = {
    /** Encode a value to a string for storage */
    encode: (v: I) => O;
    /** Decode a string back to the original value type */
    decode: (data: O) => I;
};
export type InvalidEntry<O = string> = {
    __invalid: true;
    raw: O;
};
/**
 * Interface for sinks that can append items.
 * Allows for different types of appendable storage (WAL, in-memory, etc.)
 */
export type AppendableSink<T> = Recoverable & {
    append: (item: T) => void;
    isClosed: () => boolean;
    open?: () => void;
    close?: () => void;
};
/**
 * Interface for sinks that support recovery operations.
 * Represents the recoverable subset of AppendableSink functionality.
 */
export type Recoverable = {
    recover: () => RecoverResult<unknown>;
    repack: (out?: string) => void;
    finalize?: (opt?: Record<string, unknown>) => void;
};
/**
 * Result of recovering records from a WAL file.
 * Contains successfully recovered records and any errors encountered during parsing.
 */
export type RecoverResult<T> = {
    /** Successfully recovered records */
    records: T[];
    /** Errors encountered during recovery with line numbers and context */
    errors: {
        lineNo: number;
        line: string;
        error: Error;
    }[];
    /** Last incomplete line if file was truncated (null if clean) */
    partialTail: string | null;
};
/**
 * Statistics about the WAL file state and last recovery operation.
 */
export type WalStats<T> = {
    /** File path for this WAL */
    filePath: string;
    /** Whether the WAL file is currently closed */
    isClosed: boolean;
    /** Whether the WAL file exists on disk */
    fileExists: boolean;
    /** File size in bytes (0 if file doesn't exist) */
    fileSize: number;
    /** Last recovery state from the most recent {@link recover} or {@link repack} operation */
    lastRecovery: RecoverResult<T | InvalidEntry<string>> | null;
};
export declare const createTolerantCodec: <I, O = string>(codec: {
    encode: (v: I) => O;
    decode: (d: O) => I;
}) => Codec<I | InvalidEntry<O>, O>;
export declare function filterValidRecords<T>(records: (T | InvalidEntry<unknown>)[]): T[];
/**
 * Pure helper function to recover records from WAL file content.
 * @param content - Raw file content as string
 * @param decode - function for decoding records
 * @returns Recovery result with records, errors, and partial tail
 */
export declare function recoverFromContent<T>(content: string, decode: Codec<T>['decode']): RecoverResult<T>;
/**
 * Write-Ahead Log implementation for crash-safe append-only logging.
 * Provides atomic operations for writing, recovering, and repacking log entries.
 */
export declare class WriteAheadLogFile<T extends WalRecord = WalRecord> implements AppendableSink<T> {
    #private;
    /**
     * Create a new WAL file instance.
     * @param options - Configuration options
     */
    constructor(options: {
        file: string;
        codec: Codec<T>;
    });
    /** Get the file path for this WAL */
    getPath: () => string;
    /** Open the WAL file for writing (creates directories if needed) */
    open: () => void;
    /**
     * Append a record to the WAL.
     * @param v - Record to append
     * @throws Error if WAL cannot be opened
     */
    append: (v: T) => void;
    /** Close the WAL file */
    close: () => void;
    isClosed: () => boolean;
    /**
     * Recover all records from the WAL file.
     * Handles partial writes and decode errors gracefully.
     * Updates the recovery state (accessible via {@link getStats}).
     * @returns Recovery result with records, errors, and partial tail
     */
    recover(): RecoverResult<T | InvalidEntry<string>>;
    /**
     * Repack the WAL by recovering all valid records and rewriting cleanly.
     * Removes corrupted entries and ensures clean formatting.
     * Updates the recovery state (accessible via {@link getStats}).
     * @param out - Output path (defaults to current file)
     */
    repack(out?: string): void;
    /**
     * Get comprehensive statistics about the WAL file state.
     * Includes file information, open/close status, and last recovery state.
     * @returns Statistics object with file info and last recovery state
     */
    getStats(): WalStats<T>;
}
export type WalRecord = object | string;
/**
 * Format descriptor that binds codec and file extension together.
 * Prevents misconfiguration by keeping related concerns in one object.
 */
export type WalFormat<T extends WalRecord = WalRecord> = {
    /** Base name for the WAL (e.g., "trace") */
    baseName: string;
    /** Shard file extension (e.g., ".jsonl") */
    walExtension: string;
    /** Final file extension (e.g., ".json", ".trace.json") falls back to walExtension if not provided */
    finalExtension: string;
    /** Codec for encoding/decoding records */
    codec: Codec<T, string>;
    /** Finalizer for converting records to a string */
    finalizer: (records: (T | InvalidEntry<string>)[], opt?: Record<string, unknown>) => string;
};
export declare const stringCodec: <T extends string | object = string>() => Codec<T>;
/**
 * Parses a partial WalFormat configuration and returns a complete WalFormat object.
 * All fallback values are targeting string types.
 *  - baseName defaults to 'wal'
 *  - walExtension defaults to '.log'
 *  - finalExtension defaults to '.log'
 *  - codec defaults to stringCodec<T>()
 *  - finalizer defaults to encoding each record using codec.encode() and joining with newlines.
 *    For object types, this properly JSON-stringifies them (not [object Object]).
 *    InvalidEntry records use their raw string value directly.
 * @param format - Partial WalFormat configuration
 * @returns Parsed WalFormat with defaults filled in
 */
export declare function parseWalFormat<T extends WalRecord = WalRecord>(format: Partial<WalFormat<T>>): WalFormat<T>;
/**
 * NOTE: this helper is only used within the scope of wal and sharded wal logic. The rest of the repo avoids sync methods so it is not reusable.
 * Ensures a directory exists, creating it recursively if necessary using sync methods.
 * @param dirPath - The directory path to ensure exists
 */
export declare function ensureDirectoryExistsSync(dirPath: string): void;