@sv443-network/coreutils 3.3.0 → 3.5.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

@@ -2,7 +2,7 @@
  * @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.ts";
+import type { DataStore } from "./DataStore.ts";
 /** Options for the DataStoreSerializer class */
 export type DataStoreSerializerOptions = {
     /** Whether to add a checksum to the exported data. Defaults to `true` */
@@ -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.  
@@ -43,10 +44,13 @@ export type StoreFilter = string[] | ((id: string) => boolean);
  * - ⚠️ Needs to run in a secure context (HTTPS) due to the use of the SubtleCrypto API if checksumming is enabled.  
  */
 export declare class DataStoreSerializer {
-    protected stores: DataStore<DataStoreData, boolean>[];
+    protected stores: DataStore<any, boolean>[];
     protected options: Required<DataStoreSerializerOptions>;
-    constructor(stores: DataStore<DataStoreData, boolean>[], options?: DataStoreSerializerOptions);
-    /** Calculates the checksum of a string */
+    constructor(stores: DataStore<any, boolean>[], options?: DataStoreSerializerOptions);
+    /**
+     * 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.  
@@ -114,5 +118,5 @@ export declare class DataStoreSerializer {
     /** 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<DataStoreData, boolean>[];
+    protected getStoresFiltered(stores?: StoreFilter): DataStore<any, boolean>[];
 }

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/dist/lib/text.d.ts

@@ -39,3 +39,68 @@ export declare function joinArrayReadable(array: unknown[], separators?: string,
 export declare function secsToTimeStr(seconds: number): string;
 /** Truncates a string if it exceeds `length` and inserts `endStr` at the end (empty string to disable), so that the final string doesn't exceed the given length */
 export declare function truncStr(input: Stringifiable, length: number, endStr?: string): string;
+/**
+ * Border styles for the `lineStyle` option of the {@linkcode createTable} function.  
+ *  
+ * | Style | Example |  
+ * | :-- | :-- |  
+ * | `single` | `┌──────┬──────┐` |  
+ * | `double` | `╔══════╦══════╗` |  
+ * | `none` |  |  
+ */
+export type TableLineStyle = "single" | "double" | "none";
+/**
+ * How to align cell content in a column for the `columnAlign` option of the {@linkcode createTable} function.  
+ *  
+ * | Alignment | Example | Description |  
+ * | :-- | :-- | :-- |  
+ * | `left` | `│.Text....│` | Hugs the left border, with padding determined by `minPadding`. |  
+ * | `centerLeft` | `│..Text...│` | In the center, but if the padding is uneven, favors the left side. |  
+ * | `centerRight` | `│...Text..│` | In the center, but if the padding is uneven, favors the right side. |  
+ * | `right` | `│....Text.│` | Hugs the right border, with padding determined by `minPadding`. |  
+ */
+export type TableColumnAlign = "left" | "centerLeft" | "centerRight" | "right";
+/** Options for the {@linkcode createTable} function. */
+export type TableOptions = {
+    /** Alignment for each column, either a single value to apply to all columns or an array of values for each column. Defaults to `left`. */
+    columnAlign?: TableColumnAlign | TableColumnAlign[];
+    /** If set, cell content that exceeds this width will be truncated with the value of `truncEndStr` (defaults to `…`) so that the final cell content doesn't exceed this width. */
+    truncateAbove?: number;
+    /** The string to append to truncated cell content if `truncateAbove` is set. Defaults to `…`. */
+    truncEndStr?: string;
+    /** Minimum padding to add to the left and right of cell content, regardless of alignment settings. Defaults to 1, set to 0 to disable. */
+    minPadding?: number;
+    /** Which kind of line characters to use for the border of the table. Defaults to `single` (`┌──────┬──────┐`). */
+    lineStyle?: TableLineStyle;
+    /** Can be used to change the characters used for the lines dividing cells in the table. If not set, {@linkcode defaultTableLineCharset} will be used. */
+    lineCharset?: TableLineCharset;
+    /**
+     * Can be used to add custom values like ANSI color codes to the lines dividing cells.  
+     * Function gets passed the row index (i) and column index (j) of the character being rendered.  
+     * Note that each row renders three rows of characters, so the row index (i) is not the same as the index of the row in the input array, but can be used to determine it with `Math.floor(i / 3)`.  
+     * The first value of the returned tuple will be added before the line character and the second value will be added after.  
+     * Return an empty array to not apply any custom styling.  
+     */
+    applyLineStyle?: (i: number, j: number) => [before?: string, after?: string] | void;
+    /**
+     * Can be used to add custom values like ANSI color codes to the cell content.  
+     * Function gets passed the row index (i) and column index (j) of the cell being rendered.  
+     * Note: cell width is calculated before applying this style, so characters with non-zero width will mess up the alignment and border placement.  
+     * The first value of the returned tuple will be added before the cell content and the second value will be added after.  
+     * Return an empty array to not apply any custom styling.  
+     */
+    applyCellStyle?: (i: number, j: number) => [before?: string, after?: string] | void;
+};
+/** Characters to use for the lines dividing cells in the table generated by {@linkcode createTable}, based on the `lineStyle` option. */
+export type TableLineStyleChars = Record<"horizontal" | "vertical" | `${"top" | "bottom"}${"Left" | "Right"}` | `${"left" | "right" | "top" | "bottom"}T` | "cross", string>;
+/** The characters to use for the lines dividing cells in the table generated by {@linkcode createTable}, based on the `lineStyle` option. */
+export type TableLineCharset = Record<TableLineStyle, TableLineStyleChars>;
+/** The default characters to use for the lines dividing cells in the table generated by {@linkcode createTable}, based on the `lineStyle` option. */
+export declare const defaultTableLineCharset: TableLineCharset;
+/**
+ * Creates an ASCII table string from the given rows and options.  
+ * Supports `\x1b` ANSI color codes in cell content: they are ignored for width calculation, included in the final output, and handled correctly during truncation (escape sequences are never split; any open color code is closed with a reset).  
+ * @param rows Array of tuples, where each tuple represents a row and its values. The first tuple is used to determine the column count.  
+ * @param options Object with options for customizing the table output, such as column alignment, truncation, padding and line styles.  
+ */
+export declare function createTable<TRow extends [...Stringifiable[]]>(rows: TRow[], options?: TableOptions): string;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sv443-network/coreutils",
   "libName": "@sv443-network/coreutils",
-  "version": "3.3.0",
+  "version": "3.5.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",