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

Robust, battle-tested filesystem abstraction for Node.js

import type { IFileSystem } from "./filesystem.interface";
/**
 * Type-safe JSON filesystem that automatically handles JSON parsing/stringification
 * Wraps any IFileSystem 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: IFileSystem, options?: JsonFileSystemOptions);
    /**
     * Read and parse JSON file as typed object
     * @param path File path
     * @returns Parsed object of type T
     */
    readJsonSync(path: string): T;
    /**
     * Stringify and write typed object as JSON
     * @param path File path
     * @param data Typed data to write
     */
    writeJsonSync(path: string, data: T): 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
     */
    readJsonSyncWithDefault(path: string, defaultValue: T): T;
    /**
     * Update JSON file with partial data (shallow merge)
     * @param path File path
     * @param updates Partial data to merge
     */
    updateJsonSync(path: string, updates: Partial<T>): void;
    /**
     * Validate JSON structure before writing (if validator provided)
     * @param path File path
     * @param data Data to validate and write
     */
    writeJsonSyncWithValidation(path: string, data: T): void;
    /**
     * Check if JSON file exists and is valid
     * @param path File path
     * @returns true if file exists and contains valid JSON
     */
    isValidJsonSync(path: string): boolean;
    get fileSystem(): IFileSystem;
    existsSync(path: string): boolean;
    deleteFileSync(path: string): void;
    deleteDirSync(path: string): void;
    ensureDirSync(path: string): void;
    readDirSync(path: string): string[];
    chmodSync(path: string, mode: number): void;
    clear?(dirPath: string): 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);
}