@sv443-network/coreutils/dist/lib/DataStoreSerializer.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 DataStoreSerializer  
 * This module contains the DataStoreSerializer class, which allows you to import and export serialized DataStore data - [see the documentation for more info](https://github.com/Sv443-Network/UserUtils/blob/main/docs.md#datastoreserializer)  
 */
import type { DataStore, DataStoreData } from "./DataStore.js";
/** Options for the DataStoreSerializer class */
export type DataStoreSerializerOptions = {
    /** Whether to add a checksum to the exported data. Defaults to `true` */
    addChecksum?: boolean;
    /** Whether to ensure the integrity of the data when importing it by throwing an error (doesn't throw when the checksum property doesn't exist). Defaults to `true` */
    ensureIntegrity?: boolean;
};
/** Meta object and serialized data of a DataStore instance */
export type SerializedDataStore = {
    /** The ID of the DataStore instance */
    id: string;
    /** The serialized data */
    data: string;
    /** The format version of the data */
    formatVersion: number;
    /** Whether the data is encoded */
    encoded: boolean;
    /** The checksum of the data - key is not present when `addChecksum` is `false` */
    checksum?: string;
};
/** Result of {@linkcode DataStoreSerializer.loadStoresData()} */
export type LoadStoresDataResult = {
    /** The ID of the DataStore instance */
    id: string;
    /** The in-memory data object */
    data: object;
};
/** Filter for selecting data stores */
export type StoreFilter = string[] | ((id: string) => boolean);
/**
 * Allows for easy serialization and deserialization of multiple DataStore instances.  
 *  
 * All methods are at least `protected`, so you can easily extend this class and overwrite them to use a different storage method or to add additional functionality.  
 * Remember that you can call `super.methodName()` in the subclass to access the original method.  
 *  
 * - ⚠️ Needs to run in a secure context (HTTPS) due to the use of the SubtleCrypto API if checksumming is enabled.  
 */
export declare class DataStoreSerializer<TData extends DataStoreData> {
    protected stores: DataStore<TData>[];
    protected options: Required<DataStoreSerializerOptions>;
    constructor(stores: DataStore<TData>[], options?: DataStoreSerializerOptions);
    /** Calculates the checksum of a string */
    protected calcChecksum(input: string): Promise<string>;
    /**
     * Serializes only a subset of the data stores into a string.  
     * @param stores An array of store IDs or functions that take a store ID and return a boolean  
     * @param useEncoding Whether to encode the data using each DataStore's `encodeData()` method  
     * @param stringified Whether to return the result as a string or as an array of `SerializedDataStore` objects  
     */
    serializePartial(stores: StoreFilter, useEncoding?: boolean, stringified?: true): Promise<string>;
    /**
     * Serializes only a subset of the data stores into a string.  
     * @param stores An array of store IDs or functions that take a store ID and return a boolean  
     * @param useEncoding Whether to encode the data using each DataStore's `encodeData()` method  
     * @param stringified Whether to return the result as a string or as an array of `SerializedDataStore` objects  
     */
    serializePartial(stores: StoreFilter, useEncoding?: boolean, stringified?: false): Promise<SerializedDataStore[]>;
    /**
     * Serializes only a subset of the data stores into a string.  
     * @param stores An array of store IDs or functions that take a store ID and return a boolean  
     * @param useEncoding Whether to encode the data using each DataStore's `encodeData()` method  
     * @param stringified Whether to return the result as a string or as an array of `SerializedDataStore` objects  
     */
    serializePartial(stores: StoreFilter, useEncoding?: boolean, stringified?: boolean): Promise<string | SerializedDataStore[]>;
    /**
     * Serializes the data stores into a string.  
     * @param useEncoding Whether to encode the data using each DataStore's `encodeData()` method  
     * @param stringified Whether to return the result as a string or as an array of `SerializedDataStore` objects  
     */
    serialize(useEncoding?: boolean, stringified?: true): Promise<string>;
    /**
     * Serializes the data stores into a string.  
     * @param useEncoding Whether to encode the data using each DataStore's `encodeData()` method  
     * @param stringified Whether to return the result as a string or as an array of `SerializedDataStore` objects  
     */
    serialize(useEncoding?: boolean, stringified?: false): Promise<SerializedDataStore[]>;
    /**
     * Deserializes the data exported via {@linkcode serialize()} and imports only a subset into the DataStore instances.  
     * Also triggers the migration process if the data format has changed.  
     */
    deserializePartial(stores: StoreFilter, data: string | SerializedDataStore[]): Promise<void>;
    /**
     * Deserializes the data exported via {@linkcode serialize()} and imports the data into all matching DataStore instances.  
     * Also triggers the migration process if the data format has changed.  
     */
    deserialize(data: string | SerializedDataStore[]): Promise<void>;
    /**
     * Loads the persistent data of the DataStore instances into the in-memory cache.  
     * Also triggers the migration process if the data format has changed.  
     * @param stores An array of store IDs or a function that takes the store IDs and returns a boolean - if omitted, all stores will be loaded  
     * @returns Returns a PromiseSettledResult array with the results of each DataStore instance in the format `{ id: string, data: object }`  
     */
    loadStoresData(stores?: StoreFilter): Promise<PromiseSettledResult<LoadStoresDataResult>[]>;
    /**
     * Resets the persistent and in-memory data of the DataStore instances to their default values.  
     * @param stores An array of store IDs or a function that takes the store IDs and returns a boolean - if omitted, all stores will be affected  
     */
    resetStoresData(stores?: StoreFilter): Promise<PromiseSettledResult<void>[]>;
    /**
     * Deletes the persistent data of the DataStore instances.  
     * Leaves the in-memory data untouched.  
     * @param stores An array of store IDs or a function that takes the store IDs and returns a boolean - if omitted, all stores will be affected  
     */
    deleteStoresData(stores?: StoreFilter): Promise<PromiseSettledResult<void>[]>;
    /** Checks if a given value is an array of SerializedDataStore objects */
    static isSerializedDataStoreObjArray(obj: unknown): obj is SerializedDataStore[];
    /** Checks if a given value is a SerializedDataStore object */
    static isSerializedDataStoreObj(obj: unknown): obj is SerializedDataStore;
    /** Returns the DataStore instances whose IDs match the provided array or function */
    protected getStoresFiltered(stores?: StoreFilter): DataStore<TData>[];
}