@sv443-network/coreutils 3.2.0 → 3.3.0

package/dist/lib/DataStore.d.ts

@@ -2,8 +2,10 @@
  * @module DataStore  
  * This module contains the DataStore class, which is a general purpose, sync and async persistent database for JSON-serializable data - [see the documentation for more info](https://github.com/Sv443-Network/CoreUtils/blob/main/docs.md#class-datastore)  
  */
+import { MigrationError } from "./Errors.ts";
 import type { DataStoreEngine } from "./DataStoreEngine.ts";
 import type { LooseUnion, Prettify } from "./types.ts";
+import { NanoEmitter, type NanoEmitterOptions } from "./NanoEmitter.ts";
 /** Function that takes the data in the old format and returns the data in the new format. Also supports an asynchronous migration. */
 type MigrationFunc = (oldData: any) => any | Promise<any>;
 /** Dictionary of format version numbers and the function that migrates to them from the previous whole integer */
@@ -45,7 +47,7 @@ export type DataStoreOptions<TData extends DataStoreData, TMemCache extends bool
      * A dictionary of functions that can be used to migrate data from older versions to newer ones.  
      * The keys of the dictionary should be the format version that the functions can migrate to, from the previous whole integer value.  
      * The values should be functions that take the data in the old format and return the data in the new format.  
-     * The functions will be run in order from the oldest to the newest version.  
+     * The functions will be run in order from the oldest (smallest number) to the newest (biggest number) version.  
      * If the current format version is not in the dictionary, no migrations will be run.  
      */
     migrations?: DataMigrationsDict;
@@ -68,6 +70,8 @@ export type DataStoreOptions<TData extends DataStoreData, TMemCache extends bool
      * Note: this will break backwards compatibility with any previously saved data, so only change this if you know what you're doing and ideally before any non-volatile data is saved by the end user.  
      */
     keyPrefix?: string;
+    /** Options for the internal NanoEmitter instance. */
+    nanoEmitterOptions?: NanoEmitterOptions;
 } & ({
     encodeData?: never;
     decodeData?: never;
@@ -105,6 +109,27 @@ export type DataStoreOptions<TData extends DataStoreData, TMemCache extends bool
  *   Make sure to only use JSON-serializable types here, otherwise unexpected behavior may occur!  
  */
 export type DataStoreData = object;
+/** Map of event names and their corresponding listener function signatures for the {@linkcode DataStore} class. */
+export type DataStoreEventMap<TData> = {
+    /** Emitted whenever the data is loaded from persistent storage with {@linkcode DataStore.loadData()}. */
+    loadData: (data: TData) => void;
+    /** Emitted when the data is updated with {@linkcode DataStore.setData()} or {@linkcode DataStore.runMigrations()} */
+    updateData: (newData: TData) => void;
+    /** Emitted when the memory cache was updated with {@linkcode DataStore.setData()}, before the data is saved to persistent storage. Not emitted if `memoryCache` is set to `false`. */
+    updateDataSync: (newData: TData) => void;
+    /** Emitted for every called migration function with the resulting data. */
+    migrateData: (migratedTo: number, migratedData: unknown, isFinalMigration: boolean) => void;
+    /** Emitted for every successfully migrated old ID. Gets passed the old and new ID. */
+    migrateId: (oldId: string, newId: string) => void;
+    /** Emitted whenever the data is reset to the default value with {@linkcode DataStore.saveDefaultData()} (will not be called on the initial population of persistent storage with the default data in {@linkcode DataStore.loadData()}). */
+    setDefaultData: (defaultData: TData) => void;
+    /** Emitted after the data was deleted from persistent storage with {@linkcode DataStore.deleteData()}. */
+    deleteData: () => void;
+    /** Emitted when an error occurs at any point. */
+    error: (error: Error) => void;
+    /** Emitted only when an error occurs during a migration function. */
+    migrationError: (migratingTo: number, error: MigrationError) => void;
+};
 /**
  * Manages a hybrid synchronous & asynchronous persistent JSON database that is cached in memory and persistently saved across sessions using one of the preset DataStoreEngines or your own one.  
  * Supports migrating data from older format versions to newer ones and populating the cache with default data if no persistent data is found.  
@@ -119,7 +144,7 @@ export type DataStoreData = object;
  * @template TData The type of the data that is saved in persistent storage for the currently set format version  
  * (TODO:FIXME: will be automatically inferred from `defaultData` if not provided)  
  */
-export declare class DataStore<TData extends DataStoreData, TMemCache extends boolean = true> {
+export declare class DataStore<TData extends DataStoreData, TMemCache extends boolean = true> extends NanoEmitter<DataStoreEventMap<TData>> {
     readonly id: string;
     readonly formatVersion: number;
     readonly defaultData: TData;
@@ -164,8 +189,11 @@ export declare class DataStore<TData extends DataStoreData, TMemCache extends bo
     getData(this: DataStore<TData, true>): TData;
     /** Saves the data synchronously to the in-memory cache and asynchronously to the persistent storage */
     setData(data: TData): Promise<void>;
-    /** Saves the default data passed in the constructor synchronously to the in-memory cache and asynchronously to persistent storage */
-    saveDefaultData(): Promise<void>;
+    /**
+     * Saves the default data passed in the constructor synchronously to the in-memory cache and asynchronously to persistent storage.  
+     * @param emitEvent Whether to emit the `setDefaultData` event - set to `false` to prevent event emission (used internally during initial population in {@linkcode loadData()})  
+     */
+    saveDefaultData(emitEvent?: boolean): Promise<void>;
     /**
      * Call this method to clear all persistently stored data associated with this DataStore instance, including the storage container (if supported by the DataStoreEngine).  
      * The in-memory cache will be left untouched, so you may still access the data with {@linkcode getData()}  

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sv443-network/coreutils",
   "libName": "@sv443-network/coreutils",
-  "version": "3.2.0",
+  "version": "3.3.0",
   "description": "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.",
   "main": "dist/CoreUtils.cjs",
   "module": "dist/CoreUtils.mjs",