velocedb/dist/index.d.ts

High-performance, secure, and robust local database

import fs from "node:fs";
import stringify from "json-stringify-safe";
/**
 * Veloce is a lightweight JSON database that uses proxies to simplify data manipulation.
 * It provides automatic saving (both synchronous and asynchronous), custom configurations,
 * and flexible data handling.
 *
 * @template TData The type of data stored in the database
 */
export declare class Veloce<TData = unknown> {
    /** The file path where the database will be stored
     *
     * @private
     */
    private readonly _filePath;
    /** Configuration options for the database
     *
     * @public
     */
    readonly configuration: {
        /**
         * The number of spaces for indentation when saving the file.
         * @default 2
         */
        indentation?: Parameters<typeof stringify>[2];
        /**
         * Whether data should be automatically saved to the database.
         * This feature only works in proxy mode.
         * @default true
         */
        autoSave?: boolean;
        /**
         * Whether the database should use no-proxy mode.
         * The no-proxy mode disables many features for a more streamlined process.
         * This mode is more optimized, but requires manual data saving.
         * @default false
         */
        noProxy?: boolean;
        /**
         * When auto-saving is enabled, the database will wait for this duration (in milliseconds)
         * before saving the data. If modified again during this period, the timer resets.
         * @default 750
         */
        autoSaveDelayMs?: number;
        /**
         * The timeout in milliseconds before retrying to save the data if any issues occur.
         * @default 100
         */
        saveRetryTimeoutMs?: number;
        /**
         * Callback function triggered on data updates (only in proxy mode).
         * Receives the update method name and operation result.
         * @param method - The method that was called on the proxy (e.g., 'get', 'set')
         * @param result - The result of the operation
         * @default undefined
         */
        onUpdate?: (method: "get" | "set" | "deleteProperty" | "defineProperty" | "setPrototypeOf" | "apply" | "construct" | "has" | "ownKeys" | "getOwnPropertyDescriptor" | "preventExtensions" | "isExtensible" | "getPrototypeOf", result: unknown) => void;
        /**
         * Maximum number of consecutive auto-save timeouts before forcing a save operation.
         * @default 10
         */
        maxAutoSaveTimeouts?: number;
        /**
         * File system options used when saving data to the database file.
         * @default { encoding: "utf-8" }
         */
        fileOptions?: fs.WriteFileOptions;
        /**
         * Whether to use synchronous file operations by default.
         * If false, asynchronous operations will be used.
         * @default false
         */
        useSync?: boolean;
    };
    /** Cache for storing proxied objects
     *
     * @private
     */
    private _proxyCache;
    /** Proxy handler for reactive data operations
     *
     * @private
     */
    private _proxyHandler;
    /** The data stored in the database, accessible for read/write operations
     *
     * @public
     */
    data: TData;
    /** Flag to track if the initial directory check has been performed
     *
     * @private
     */
    private _isInitialCheckComplete;
    /** Flag to indicate if a save operation is in progress
     *
     * @private
     */
    private _isSaving;
    /** Reference to the auto-save timeout
     *
     * @private
     */
    private _saveTimeout?;
    /** Counter for tracking consecutive auto-save timeout operations
     *
     * @private
     */
    private _saveTimeoutCount;
    /** Queue for handling save operations
     *
     * @private
     */
    private _saveQueue;
    /** Flag to indicate if the database is closed
     *
     * @private
     */
    private _isClosed;
    /**
     * Creates nested proxies for objects within the database structure
     * to track changes at all levels of the object hierarchy.
     *
     * @private
     * @template T The type of the target object
     * @param target - The target object to proxy
     * @param handler - The proxy handler containing trap methods
     * @param proxyCache - The cache for storing proxied objects
     * @returns A proxied version of the target object
     */
    private static _createNestedProxies;
    /**
     * Triggers an automatic save operation based on configuration settings.
     * If auto-save is enabled, it will use either synchronous or asynchronous
     * save methods depending on the configuration.
     *
     * @private
     */
    private _triggerAutoSave;
    /**
     * Creates a new Veloce database instance.
     *
     * @public
     * @param filePath - The path to the database file
     * @param baseData - The base data to use as fallback when no data exists
     * @param configuration - Configuration options for the database
     */
    constructor(filePath: string, baseData: TData, configuration?: Veloce<TData>["configuration"]);
    /**
     * Initializes the database data, either from an existing file or with the provided base data.
     *
     * @private
     * @param baseData - The base data to use as fallback when no data exists
     * @returns The initialized data
     */
    private _initializeData;
    /**
     * Creates the proxy handler for reactive data operations.
     *
     * @private
     * @returns A proxy handler object with trap methods
     */
    private _createProxyHandler;
    /**
     * Saves the current state of the database to the file synchronously.
     * @param force - If true, bypasses all checks and immediately saves the data
     *
     * @public
     */
    save(force?: boolean): void;
    /**
     * Saves the current state of the database to the file asynchronously.
     * @param force - If true, bypasses all checks and immediately saves the data
     *
     * @public
     */
    saveAsync(force?: boolean): Promise<void>;
    /**
     * Handles the save operation with proper timing and retry logic.
     *
     * @private
     */
    private _handleSaveOperation;
    /**
     * Cleans up the save state after a save operation.
     *
     * @private
     */
    private _cleanupSaveState;
    /**
     * Deletes the database file from the filesystem synchronously.
     * This operation cannot be undone.
     *
     * @public
     */
    delete(): void;
    /**
     * Deletes the database file from the filesystem asynchronously.
     * This operation cannot be undone.
     *
     * @public
     */
    deleteAsync(): Promise<void>;
    /**
     * Reloads the data from the file synchronously.
     *
     * @public
     */
    reload(): void;
    /**
     * Reloads the data from the file asynchronously.
     *
     * @public
     */
    reloadAsync(): Promise<void>;
    /**
     * Closes the database instance, cancelling any pending saves and cleaning up resources.
     * After closing, no further operations will be performed.
     *
     * @public
     */
    close(): Promise<void>;
}