@sv443-network/coreutils 3.3.0 → 3.4.0

package/dist/lib/DataStore.d.ts

@@ -106,7 +106,8 @@ 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. */
@@ -142,7 +143,6 @@ export type DataStoreEventMap<TData> = {
  * - ⚠️ 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> extends NanoEmitter<DataStoreEventMap<TData>> {
     readonly id: string;

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.3.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",