@sv443-network/coreutils/dist/lib/DataStoreEngine.d.ts

Cross-platform, general-purpose, JavaScript core library for Node, Deno and the browser. Intended to be used in conjunction with `@sv443-network/userutils` and `@sv443-network/djsutils`, but can be used independently as well.

/**
 * @module DataStoreEngine  
 * This module contains the `DataStoreEngine` class and some of its subclasses like `FileStorageEngine` and `BrowserStorageEngine`.  
 * [See the documentation for more info.](https://github.com/Sv443-Network/CoreUtils/blob/main/docs.md#class-datastoreengine)  
 */
import type { DataStoreData, DataStoreOptions } from "./DataStore.js";
import type { Prettify, SerializableVal } from "./types.js";
/** Contains the only properties of {@linkcode DataStoreOptions} that are relevant to the {@linkcode DataStoreEngine} class. */
export type DataStoreEngineDSOptions<TData extends DataStoreData> = Prettify<Pick<DataStoreOptions<TData>, "decodeData" | "encodeData" | "id">>;
export interface DataStoreEngine<TData extends DataStoreData> {
    /** Deletes all data in persistent storage, including the data container itself (e.g. a file or a database) */
    deleteStorage?(): Promise<void>;
}
/**
 * Base class for creating {@linkcode DataStore} storage engines.  
 * This acts as an interchangeable API for writing and reading persistent data in various environments.  
 */
export declare abstract class DataStoreEngine<TData extends DataStoreData> {
    protected dataStoreOptions: DataStoreEngineDSOptions<TData>;
    constructor(options?: DataStoreEngineDSOptions<TData>);
    /** Called by DataStore on creation, to pass its options. Only call this if you are using this instance standalone! */
    setDataStoreOptions(dataStoreOptions: DataStoreEngineDSOptions<TData>): void;
    /** Fetches a value from persistent storage */
    abstract getValue<TValue extends SerializableVal = string>(name: string, defaultValue: TValue): Promise<string | TValue>;
    /** Sets a value in persistent storage */
    abstract setValue(name: string, value: SerializableVal): Promise<void>;
    /** Deletes a value from persistent storage */
    abstract deleteValue(name: string): Promise<void>;
    /** Serializes the given object to a string, optionally encoded with `options.encodeData` if {@linkcode useEncoding} is set to true */
    serializeData(data: TData, useEncoding?: boolean): Promise<string>;
    /** Deserializes the given string to a JSON object, optionally decoded with `options.decodeData` if {@linkcode useEncoding} is set to true */
    deserializeData(data: string, useEncoding?: boolean): Promise<TData>;
    /** Throws an error if the DataStoreOptions are not set or invalid */
    protected ensureDataStoreOptions(): void;
    /**
     * Copies a JSON-compatible object and loses all its internal references in the process.  
     * Uses [`structuredClone()`](https://developer.mozilla.org/en-US/docs/Web/API/structuredClone) if available, otherwise falls back to `JSON.parse(JSON.stringify(obj))`.  
     */
    deepCopy<T>(obj: T): T;
}
/** Options for the {@linkcode BrowserStorageEngine} class */
export type BrowserStorageEngineOptions = {
    /** Whether to store the data in LocalStorage (default) or SessionStorage */
    type?: "localStorage" | "sessionStorage";
    /**
     * Specifies the necessary options for storing data.  
     * - ⚠️ Only specify this if you are using this instance standalone! The parent DataStore will set this automatically.  
     */
    dataStoreOptions?: DataStoreEngineDSOptions<DataStoreData>;
};
/**
 * Storage engine for the {@linkcode DataStore} class that uses the browser's LocalStorage or SessionStorage to store data.  
 *  
 * - ⚠️ Requires a DOM environment  
 * - ⚠️ Don't reuse engines across multiple {@linkcode DataStore} instances  
 */
export declare class BrowserStorageEngine<TData extends DataStoreData> extends DataStoreEngine<TData> {
    protected options: BrowserStorageEngineOptions & Required<Pick<BrowserStorageEngineOptions, "type">>;
    /**
     * Creates an instance of `BrowserStorageEngine`.  
     *  
     * - ⚠️ Requires a DOM environment  
     * - ⚠️ Don't reuse engines across multiple {@linkcode DataStore} instances  
     */
    constructor(options?: BrowserStorageEngineOptions);
    /** Fetches a value from persistent storage */
    getValue<TValue extends SerializableVal = string>(name: string, defaultValue: TValue): Promise<string | TValue>;
    /** Sets a value in persistent storage */
    setValue(name: string, value: SerializableVal): Promise<void>;
    /** Deletes a value from persistent storage */
    deleteValue(name: string): Promise<void>;
}
/** Options for the {@linkcode FileStorageEngine} class */
export type FileStorageEngineOptions = {
    /** Function that returns a string or a plain string that is the data file path, including name and extension. Defaults to `.ds-${dataStoreID}` */
    filePath?: ((dataStoreID: string) => string) | string;
    /**
     * Specifies the necessary options for storing data.  
     * - ⚠️ Only specify this if you are using this instance standalone! The parent DataStore will set this automatically.  
     */
    dataStoreOptions?: DataStoreEngineDSOptions<DataStoreData>;
};
/**
 * Storage engine for the {@linkcode DataStore} class that uses a JSON file to store data.  
 *  
 * - ⚠️ Requires Node.js or Deno with Node compatibility (v1.31+)  
 * - ⚠️ Don't reuse engines across multiple {@linkcode DataStore} instances  
 */
export declare class FileStorageEngine<TData extends DataStoreData> extends DataStoreEngine<TData> {
    protected options: FileStorageEngineOptions & Required<Pick<FileStorageEngineOptions, "filePath">>;
    /**
     * Creates an instance of `FileStorageEngine`.  
     *  
     * - ⚠️ Requires Node.js or Deno with Node compatibility (v1.31+)  
     * - ⚠️ Don't reuse engines across multiple {@linkcode DataStore} instances  
     */
    constructor(options?: FileStorageEngineOptions);
    /** Reads the file contents */
    protected readFile(): Promise<TData | undefined>;
    /** Overwrites the file contents */
    protected writeFile(data: TData): Promise<void>;
    /** Fetches a value from persistent storage */
    getValue<TValue extends SerializableVal = string>(name: string, defaultValue: TValue): Promise<string | TValue>;
    /** Sets a value in persistent storage */
    setValue<TValue extends SerializableVal = string>(name: string, value: TValue): Promise<void>;
    /** Deletes a value from persistent storage */
    deleteValue(name: string): Promise<void>;
    /** Deletes the file that contains the data of this DataStore. */
    deleteStorage(): Promise<void>;
}