@sv443-network/coreutils 3.2.0 → 3.4.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;
@@ -102,9 +106,31 @@ export type DataStoreOptions<TData extends DataStoreData, TMemCache extends bool
 /**
  * Generic type that represents the serializable data structure saved in a {@linkcode DataStore} instance.  
  * - ⚠️ Uses `object` instead of an index signature so that interfaces without an explicit index signature can be used as `TData`.  
- *   Make sure to only use JSON-serializable types here, otherwise unexpected behavior may occur!  
+ *   However, this also means that the type system won't prevent you from using non-serializable data structures like functions or symbols in the data, which will cause errors at runtime.  
+ *   Make sure to only use types that are compatible with `JSON.stringify()`, and use `null` instead of `undefined` when you need to preserve the key of an empty value.  
  */
 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.  
@@ -117,9 +143,8 @@ export type DataStoreData = object;
  * - ⚠️ Make sure to call {@linkcode loadData()} at least once after creating an instance, or the returned data will be the same as `options.defaultData`  
  *  
  * @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/dist/lib/DataStoreSerializer.d.ts

@@ -35,7 +35,8 @@ export type LoadStoresDataResult = {
 /** Filter for selecting data stores */
 export type StoreFilter = string[] | ((id: string) => boolean);
 /**
- * Allows for easy serialization and deserialization of multiple DataStore instances.  
+ * Allows for easy serialization and deserialization of multiple {@linkcode DataStore} instances.  
+ * Offers methods to only serialize or deserialize a subset of the stores, and to ensure the integrity of the data by adding checksums.  
  *  
  * 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.  
@@ -46,7 +47,10 @@ export declare class DataStoreSerializer {
     protected stores: DataStore<DataStoreData, boolean>[];
     protected options: Required<DataStoreSerializerOptions>;
     constructor(stores: DataStore<DataStoreData, boolean>[], options?: DataStoreSerializerOptions);
-    /** Calculates the checksum of a string */
+    /**
+     * Calculates the checksum of a string. Uses {@linkcode computeHash()} with SHA-256 and digests as a hex string by default.  
+     * Override this in a subclass if a custom checksum method is needed.  
+     */
     protected calcChecksum(input: string): Promise<string>;
     /**
      * Serializes only a subset of the data stores into a string.  

package/dist/lib/Debouncer.d.ts

@@ -2,7 +2,7 @@
  * @module Debouncer  
  * This module contains the Debouncer class and debounce function that allow you to reduce the amount of calls in rapidly firing event listeners and such - [see the documentation for more info](https://github.com/Sv443-Network/UserUtils/blob/main/docs.md#debouncer)  
  */
-import { NanoEmitter } from "./NanoEmitter.ts";
+import { NanoEmitter, type NanoEmitterOptions } from "./NanoEmitter.ts";
 /**
  * The type of edge to use for the debouncer - [see the docs for a diagram and explanation.](https://github.com/Sv443-Network/UserUtils/blob/main/docs.md#debouncer)  
  * - `immediate` - (default & recommended) - calls the listeners at the very first call ("rising" edge) and queues the latest call until the timeout expires  
@@ -53,7 +53,7 @@ export declare class Debouncer<TFunc extends AnyFn> extends NanoEmitter<Debounce
      * @param timeout Timeout in milliseconds between letting through calls - defaults to 200  
      * @param type The edge type to use for the debouncer - see {@linkcode DebouncerType} for details or [the documentation for an explanation and diagram](https://github.com/Sv443-Network/UserUtils/blob/main/docs.md#debouncer) - defaults to "immediate"  
      */
-    constructor(timeout?: number, type?: DebouncerType);
+    constructor(timeout?: number, type?: DebouncerType, nanoEmitterOptions?: NanoEmitterOptions);
     /** Adds a listener function that will be called on timeout */
     addListener(fn: TFunc): void;
     /** Removes the listener with the specified function reference */
@@ -82,5 +82,5 @@ export declare class Debouncer<TFunc extends AnyFn> extends NanoEmitter<Debounce
  *  
  * Refer to the {@linkcode Debouncer} class definition or the [Debouncer documentation](https://github.com/Sv443-Network/UserUtils/blob/main/docs.md#debouncer) for more information.  
  */
-export declare function debounce<TFunc extends (...args: any[]) => any>(fn: TFunc, timeout?: number, type?: DebouncerType): DebouncedFunction<TFunc>;
+export declare function debounce<TFunc extends (...args: any[]) => any>(fn: TFunc, timeout?: number, type?: DebouncerType, nanoEmitterOptions?: NanoEmitterOptions): DebouncedFunction<TFunc>;
 export {};

package/dist/lib/misc.d.ts

@@ -77,3 +77,39 @@ export declare function scheduleExit(code?: number, timeout?: number): void;
  * @param lines The number of lines to return from the stack. Defaults to Infinity (all of them).  
  */
 export declare function getCallStack<TAsArray extends boolean = true>(asArray?: TAsArray, lines?: number): TAsArray extends true ? string[] : string;
+/** Options object for {@linkcode createRecurringTask()} */
+export type RecurringTaskOptions<TVal extends void | unknown> = {
+    /** Timeout between running the task, in milliseconds. For async tasks and conditions, the timeout will be added onto the execution time of the Promises. */
+    timeout: number;
+    /**
+     * The task to run. Can return a value or a Promise that resolves to a value of any type, which will be passed to the optional callback once the task is finished.  
+     * Gets passed the current iteration (starting at 0) as an argument. If no `condition` is given, the task will run indefinitely, or until aborted via the `signal`, `abortOnError` or `maxIterations` options.  
+     */
+    task: (iteration: number) => TVal | Promise<TVal>;
+    /**
+     * Condition that needs to return true in order to run the task. If not given, the task will run indefinitely with the given timeout.  
+     * Gets passed the current iteration (starting at 0) as an argument. A failing condition will still increment the iterations.  
+     */
+    condition?: (iteration: number) => boolean | Promise<boolean>;
+    /** Gets called with the task's return value and iteration number every time it's finished. Can be an async function if asynchronous operations are needed in the callback. */
+    onSuccess?: (value: TVal, iteration: number) => void | Promise<void>;
+    /** Gets called with the error if the `task`, `condition` or `onSuccess` functions throw an error or return a rejected Promise. Can be an async function if asynchronous operations are needed in the callback. */
+    onError?: (error: unknown, iteration: number) => void | Promise<void>;
+    /**
+     * If true, the recurring task will stop if the condition or task functions throw an error or return a rejected Promise. Defaults to false.  
+     * - ⚠️ If neither `onError` nor `abortOnError` are set, errors will be re-thrown, which could potentially crash the process if not handled by the caller.  
+     */
+    abortOnError?: boolean;
+    /** Max number of times to run the task. If not given, will run indefinitely as long as the condition is true. */
+    maxIterations?: number;
+    /** Optional AbortSignal to cancel the task. */
+    signal?: AbortSignal;
+    /** Whether to run the task immediately on the first call or wait for the first timeout to pass. Defaults to true. */
+    immediate?: boolean;
+};
+/**
+ * Schedules a task to run immediately and repeatedly at the given timeout as long as the given condition returns true.  
+ * Ensures no overlapping task executions and multiple ways to cleanly stop the repeated execution.  
+ * @returns A promise that resolves once the task is stopped, either by the condition returning false, reaching the max iterations, or the signal being aborted.  
+ */
+export declare function createRecurringTask<TVal extends void | unknown>(options: RecurringTaskOptions<TVal>): Promise<void>;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sv443-network/coreutils",
   "libName": "@sv443-network/coreutils",
-  "version": "3.2.0",
+  "version": "3.4.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",
@@ -38,30 +38,30 @@
   },
   "homepage": "https://github.com/Sv443-Network/CoreUtils",
   "dependencies": {
-    "nanoevents": "^9.1.0"
+    "nanoevents": "9.1.0"
   },
   "devDependencies": {
-    "@changesets/cli": "^2.29.8",
-    "@eslint/eslintrc": "^3.3.3",
-    "@eslint/js": "^9.39.2",
-    "@swc/core": "^1.15.11",
-    "@testing-library/dom": "^10.4.1",
-    "@types/deno": "^2.5.0",
-    "@types/node": "^22.19.11",
-    "@types/tx2": "^1.0.3",
-    "@typescript-eslint/eslint-plugin": "^8.56.0",
-    "@typescript-eslint/parser": "^8.56.0",
-    "@typescript-eslint/utils": "^8.56.0",
-    "@vitest/coverage-v8": "^3.2.4",
-    "esbuild-plugin-umd-wrapper": "^3.0.0",
-    "eslint": "^9.39.2",
-    "globals": "^16.5.0",
-    "jsdom": "^26.1.0",
-    "tslib": "^2.8.1",
-    "tsup": "^8.5.1",
-    "tsx": "^4.21.0",
-    "typescript": "^5.9.3",
-    "vitest": "^3.2.4"
+    "@changesets/cli": "2.30.0",
+    "@eslint/eslintrc": "3.3.5",
+    "@eslint/js": "9.39.4",
+    "@swc/core": "1.15.18",
+    "@testing-library/dom": "10.4.1",
+    "@types/deno": "2.5.0",
+    "@types/node": "22.19.15",
+    "@types/tx2": "1.0.3",
+    "@typescript-eslint/eslint-plugin": "8.56.1",
+    "@typescript-eslint/parser": "8.56.1",
+    "@typescript-eslint/utils": "8.56.1",
+    "@vitest/coverage-v8": "3.2.4",
+    "esbuild-plugin-umd-wrapper": "3.0.0",
+    "eslint": "9.39.4",
+    "globals": "16.5.0",
+    "jsdom": "26.1.0",
+    "tslib": "2.8.1",
+    "tsup": "8.5.1",
+    "tsx": "4.21.0",
+    "typescript": "5.9.3",
+    "vitest": "3.2.4"
   },
   "files": [
     "/dist/CoreUtils.cjs",