@synet/fs/dist/promises/json.d.ts

Robust, battle-tested filesystem abstraction for Node.js

import type { IAsyncFileSystem } from "./async-filesystem.interface";
/**
 * Type-safe async JSON filesystem that automatically handles JSON parsing/stringification
 * Wraps any IAsyncFileSystem implementation to provide typed JSON operations
 * @template T The type of data stored in JSON files
 */
export declare class JsonFileSystem<T = unknown> {
    private baseFileSystem;
    private options;
    constructor(baseFileSystem: IAsyncFileSystem, options?: JsonFileSystemOptions);
    /**
     * Read and parse JSON file as typed object
     * @param path File path
     * @returns Parsed object of type T
     */
    readJson(path: string): Promise<T>;
    /**
     * Stringify and write typed object as JSON
     * @param path File path
     * @param data Typed data to write
     */
    writeJson(path: string, data: T): Promise<void>;
    /**
     * Read and parse JSON file with default fallback
     * @param path File path
     * @param defaultValue Default value if file doesn't exist
     * @returns Parsed object or default value
     */
    readJsonWithDefault(path: string, defaultValue: T): Promise<T>;
    /**
     * Update JSON file with partial data (shallow merge)
     * @param path File path
     * @param updates Partial data to merge
     */
    updateJson(path: string, updates: Partial<T>): Promise<void>;
    /**
     * Validate JSON structure before writing (if validator provided)
     * @param path File path
     * @param data Data to validate and write
     */
    writeJsonWithValidation(path: string, data: T): Promise<void>;
    /**
     * Check if JSON file exists and is valid
     * @param path File path
     * @returns true if file exists and contains valid JSON
     */
    isValidJson(path: string): Promise<boolean>;
    /**
     * Atomically update JSON file (read-modify-write with custom updater function)
     * @param path File path
     * @param updater Function that receives current data and returns updated data
     */
    atomicUpdate(path: string, updater: (current: T) => T): Promise<void>;
    get fileSystem(): IAsyncFileSystem;
    exists(path: string): Promise<boolean>;
    deleteFile(path: string): Promise<void>;
    deleteDir(path: string): Promise<void>;
    ensureDir(path: string): Promise<void>;
    readDir(path: string): Promise<string[]>;
    chmod(path: string, mode: number): Promise<void>;
    clear?(dirPath: string): Promise<void>;
}
/**
 * Configuration options for JsonFileSystem
 */
export interface JsonFileSystemOptions {
    /**
     * JSON.stringify space parameter for formatting
     * @default 2
     */
    space?: string | number;
    /**
     * JSON.stringify replacer function
     */
    replacer?: (key: string, value: unknown) => unknown;
    /**
     * Optional validator function to validate data before writing
     */
    validator?: (data: unknown) => boolean;
}
/**
 * Error thrown when JSON parsing fails
 */
export declare class JsonParseError extends Error {
    readonly cause: Error;
    constructor(message: string, cause: Error);
}
/**
 * Error thrown when JSON stringification fails
 */
export declare class JsonStringifyError extends Error {
    readonly cause: Error;
    constructor(message: string, cause: Error);
}
/**
 * Error thrown when JSON validation fails
 */
export declare class JsonValidationError extends Error {
    constructor(message: string);
}