/**
 * Centralized Atomic File I/O Utilities
 *
 * Provides safe, atomic file operations for all JSON persistence in Crewly.
 * Uses temp-file + fsync + rename to prevent corruption on crash,
 * and in-process locks to serialize concurrent writes to the same file.
 *
 * @module utils/file-io.utils
 */
/**
 * Minimal logger interface accepted by safeReadJson / modifyJsonFile.
 * Compatible with ComponentLogger from LoggerService.
 */
export interface FileIOLogger {
    warn(message: string, meta?: Record<string, unknown>): void;
    debug?(message: string, meta?: Record<string, unknown>): void;
}
/**
 * Ensures a directory exists, creating it recursively if necessary.
 *
 * @param dirPath - Absolute path to the directory
 */
export declare function ensureDir(dirPath: string): Promise<void>;
/**
 * Serialize concurrent writes to the same file.
 *
 * @param lockKey - Unique key for the lock (typically the file path)
 * @param operation - Async operation to run while holding the lock
 * @returns The result of the operation
 */
export declare function withFileLock<T>(lockKey: string, operation: () => Promise<T>): Promise<T>;
/**
 * Serialize read-modify-write cycles on a logical resource.
 *
 * Uses a separate lock map from {@link withFileLock} so that callers
 * can hold an operation lock across a read + write without deadlocking
 * on the inner file lock.
 *
 * @param lockKey - Unique key for the lock
 * @param operation - Async operation to run while holding the lock
 * @returns The result of the operation
 */
export declare function withOperationLock<T>(lockKey: string, operation: () => Promise<T>): Promise<T>;
/**
 * Write a string to a file atomically (temp file → fsync → rename).
 *
 * Acquires a per-path file lock so concurrent callers targeting the
 * same path are serialized.
 *
 * **Precondition:** The parent directory must already exist. This function
 * does not create intermediate directories — use {@link ensureDir} first
 * if the directory may not exist.
 *
 * @param filePath - Destination file path
 * @param content - String content to write
 */
export declare function atomicWriteFile(filePath: string, content: string): Promise<void>;
/**
 * Serialize a JavaScript value to JSON and write it atomically.
 *
 * @param filePath - Destination file path
 * @param data - Value to serialize (via `JSON.stringify`)
 */
export declare function atomicWriteJson<T>(filePath: string, data: T): Promise<void>;
/**
 * Read and parse a JSON file safely.
 *
 * - On `ENOENT` → returns `defaultValue` silently.
 * - On parse error → backs up the corrupt file as `<path>.corrupt.<ts>`
 *   and returns `defaultValue`.
 *
 * @param filePath - Path to the JSON file
 * @param defaultValue - Value to return when the file is missing or corrupt
 * @param logger - Optional logger for warnings on corruption
 * @returns Parsed value or `defaultValue`
 */
export declare function safeReadJson<T>(filePath: string, defaultValue: T, logger?: FileIOLogger): Promise<T>;
/**
 * Locked read → mutate → atomic write cycle.
 *
 * This is the most common persistence pattern: load a JSON file,
 * apply a mutation, and write it back atomically — all while holding
 * an operation lock to prevent concurrent read-modify-write races.
 *
 * **Important:** If the mutator returns `undefined` (void), the mutated
 * `data` object is written back. If it returns any other value — including
 * falsy values like `null`, `0`, or `false` — that value is written instead.
 * Beware of methods like `Array.push()` which return a number: an accidental
 * `return records.push(item)` will write the array length to the file.
 *
 * @param filePath - Path to the JSON file
 * @param defaultValue - Value to use if the file is missing or corrupt
 * @param mutator - Function that receives the current data and mutates it in place (or returns new data)
 * @param logger - Optional logger
 * @returns The value returned by `mutator` (or void)
 */
export declare function modifyJsonFile<T, R = void>(filePath: string, defaultValue: T, mutator: (data: T) => R | Promise<R>, logger?: FileIOLogger): Promise<R>;
/**
 * Reset all lock maps. **Test-only** — never call in production.
 */
export declare function _clearAllLocks(): void;
//# sourceMappingURL=file-io.utils.d.ts.map