@sv443-network/coreutils 3.4.0 → 3.5.0

package/dist/CoreUtils.umd.js

@@ -74,10 +74,12 @@ __export(lib_exports, {
   consumeStringGen: () => consumeStringGen,
   createProgressBar: () => createProgressBar,
   createRecurringTask: () => createRecurringTask,
+  createTable: () => createTable,
   darkenColor: () => darkenColor,
   debounce: () => debounce,
   decompress: () => decompress,
   defaultPbChars: () => defaultPbChars,
+  defaultTableLineCharset: () => defaultTableLineCharset,
   digitCount: () => digitCount,
   fetchAdvanced: () => fetchAdvanced,
   formatNumber: () => formatNumber,
@@ -606,6 +608,173 @@ function truncStr(input, length, endStr = "...") {
   const finalStr = str.length > length ? str.substring(0, length - endStr.length) + endStr : str;
   return finalStr.length > length ? finalStr.substring(0, length) : finalStr;
 }
+var defaultTableLineCharset = {
+  single: {
+    horizontal: "\u2500",
+    vertical: "\u2502",
+    topLeft: "\u250C",
+    topRight: "\u2510",
+    bottomLeft: "\u2514",
+    bottomRight: "\u2518",
+    leftT: "\u251C",
+    rightT: "\u2524",
+    topT: "\u252C",
+    bottomT: "\u2534",
+    cross: "\u253C"
+  },
+  double: {
+    horizontal: "\u2550",
+    vertical: "\u2551",
+    topLeft: "\u2554",
+    topRight: "\u2557",
+    bottomLeft: "\u255A",
+    bottomRight: "\u255D",
+    leftT: "\u2560",
+    rightT: "\u2563",
+    topT: "\u2566",
+    bottomT: "\u2569",
+    cross: "\u256C"
+  },
+  none: {
+    horizontal: " ",
+    vertical: " ",
+    topLeft: " ",
+    topRight: " ",
+    bottomLeft: " ",
+    bottomRight: " ",
+    leftT: " ",
+    rightT: " ",
+    topT: " ",
+    bottomT: " ",
+    cross: " "
+  }
+};
+function createTable(rows, options) {
+  var _a;
+  const opts = {
+    columnAlign: "left",
+    truncateAbove: Infinity,
+    truncEndStr: "\u2026",
+    minPadding: 1,
+    lineStyle: "single",
+    applyCellStyle: () => void 0,
+    applyLineStyle: () => void 0,
+    lineCharset: defaultTableLineCharset,
+    ...options ?? {}
+  };
+  const defRange = (val, min, max) => clamp(typeof val !== "number" || isNaN(Number(val)) ? min : val, min, max);
+  opts.truncateAbove = defRange(opts.truncateAbove, 0, Infinity);
+  opts.minPadding = defRange(opts.minPadding, 0, Infinity);
+  const lnCh = opts.lineCharset[opts.lineStyle];
+  const stripAnsi = (str) => str.replace(/\u001b\[[0-9;]*m/g, "");
+  const stringRows = rows.map((row) => row.map((cell) => String(cell)));
+  const colCount = ((_a = rows[0]) == null ? void 0 : _a.length) ?? 0;
+  if (colCount === 0 || stringRows.length === 0)
+    return "";
+  if (isFinite(opts.truncateAbove)) {
+    const truncAnsi = (str, maxVisible, endStr) => {
+      const limit = maxVisible - endStr.length;
+      if (limit <= 0)
+        return endStr.slice(0, maxVisible);
+      let visible = 0;
+      let result = "";
+      let i = 0;
+      let hasAnsi = false;
+      while (i < str.length) {
+        if (str[i] === "\x1B" && str[i + 1] === "[") {
+          const seqEnd = str.indexOf("m", i + 2);
+          if (seqEnd !== -1) {
+            result += str.slice(i, seqEnd + 1);
+            hasAnsi = true;
+            i = seqEnd + 1;
+            continue;
+          }
+        }
+        if (visible === limit) {
+          result += endStr;
+          if (hasAnsi)
+            result += "\x1B[0m";
+          return result;
+        }
+        result += str[i];
+        visible++;
+        i++;
+      }
+      return result;
+    };
+    for (const row of stringRows)
+      for (let j = 0; j < row.length; j++)
+        if (stripAnsi(row[j] ?? "").length > opts.truncateAbove)
+          row[j] = truncAnsi(row[j] ?? "", opts.truncateAbove, opts.truncEndStr);
+  }
+  const colWidths = Array.from(
+    { length: colCount },
+    (_, j) => Math.max(0, ...stringRows.map((row) => stripAnsi(row[j] ?? "").length))
+  );
+  const applyLn = (i, j, ch) => {
+    const [before = "", after = ""] = opts.applyLineStyle(i, j) ?? [];
+    return `${before}${ch}${after}`;
+  };
+  const buildBorderRow = (lineIdx, leftCh, midCh, rightCh) => {
+    let result = "";
+    let j = 0;
+    result += applyLn(lineIdx, j++, leftCh);
+    for (let col = 0; col < colCount; col++) {
+      const cellWidth = (colWidths[col] ?? 0) + opts.minPadding * 2;
+      for (let ci = 0; ci < cellWidth; ci++)
+        result += applyLn(lineIdx, j++, lnCh.horizontal);
+      if (col < colCount - 1)
+        result += applyLn(lineIdx, j++, midCh);
+    }
+    result += applyLn(lineIdx, j++, rightCh);
+    return result;
+  };
+  const lines = [];
+  for (let rowIdx = 0; rowIdx < stringRows.length; rowIdx++) {
+    const row = stringRows[rowIdx] ?? [];
+    const lineIdxBase = rowIdx * 3;
+    if (opts.lineStyle !== "none") {
+      lines.push(
+        rowIdx === 0 ? buildBorderRow(lineIdxBase, lnCh.topLeft, lnCh.topT, lnCh.topRight) : buildBorderRow(lineIdxBase, lnCh.leftT, lnCh.cross, lnCh.rightT)
+      );
+    }
+    let contentLine = "";
+    let j = 0;
+    contentLine += applyLn(lineIdxBase + 1, j++, lnCh.vertical);
+    for (let colIdx = 0; colIdx < colCount; colIdx++) {
+      const cell = row[colIdx] ?? "";
+      const visLen = stripAnsi(cell).length;
+      const extra = (colWidths[colIdx] ?? 0) - visLen;
+      const align = (Array.isArray(opts.columnAlign) ? opts.columnAlign[colIdx] : opts.columnAlign) ?? "left";
+      let leftPad;
+      let rightPad;
+      switch (align) {
+        case "right":
+          leftPad = opts.minPadding + extra;
+          rightPad = opts.minPadding;
+          break;
+        case "centerLeft":
+          leftPad = opts.minPadding + Math.floor(extra / 2);
+          rightPad = opts.minPadding + Math.ceil(extra / 2);
+          break;
+        case "centerRight":
+          leftPad = opts.minPadding + Math.ceil(extra / 2);
+          rightPad = opts.minPadding + Math.floor(extra / 2);
+          break;
+        default:
+          leftPad = opts.minPadding;
+          rightPad = opts.minPadding + extra;
+      }
+      const [cellBefore = "", cellAfter = ""] = opts.applyCellStyle(rowIdx, colIdx) ?? [];
+      contentLine += " ".repeat(leftPad) + cellBefore + cell + cellAfter + " ".repeat(rightPad);
+      contentLine += applyLn(lineIdxBase + 1, j++, lnCh.vertical);
+    }
+    lines.push(contentLine);
+    if (opts.lineStyle !== "none" && rowIdx === stringRows.length - 1)
+      lines.push(buildBorderRow(lineIdxBase + 2, lnCh.bottomLeft, lnCh.bottomT, lnCh.bottomRight));
+  }
+  return lines.join("\n");
+}
 
 // node_modules/.pnpm/nanoevents@9.1.0/node_modules/nanoevents/index.js
 var createNanoEvents = () => ({
@@ -1316,6 +1485,7 @@ var FileStorageEngine = class extends DataStoreEngine {
 // lib/DataStoreSerializer.ts
 var DataStoreSerializer = class _DataStoreSerializer {
   stores;
+  // eslint-disable-line @typescript-eslint/no-explicit-any
   options;
   constructor(stores, options = {}) {
     if (!crypto || !crypto.subtle)
@@ -1558,7 +1728,166 @@ function debounce(fn, timeout = 200, type = "immediate", nanoEmitterOptions) {
   func.debouncer = debouncer;
   return func;
 }
+sistent 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) {
+    return __async(this, null, function* () {
+      return Promise.allSettled(
+        this.getStoresFiltered(stores).map((store) => __async(this, null, function* () {
+          return {
+            id: store.id,
+            data: yield store.loadData()
+          };
+        }))
+      );
+    });
+  }
+  /**
+   * 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) {
+    return __async(this, null, function* () {
+      return Promise.allSettled(
+        this.getStoresFiltered(stores).map((store) => store.saveDefaultData())
+      );
+    });
+  }
+  /**
+   * 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) {
+    return __async(this, null, function* () {
+      return Promise.allSettled(
+        this.getStoresFiltered(stores).map((store) => store.deleteData())
+      );
+    });
+  }
+  /** Checks if a given value is an array of SerializedDataStore objects */
+  static isSerializedDataStoreObjArray(obj) {
+    return Array.isArray(obj) && obj.every((o) => typeof o === "object" && o !== null && "id" in o && "data" in o && "formatVersion" in o && "encoded" in o);
+  }
+  /** Checks if a given value is a SerializedDataStore object */
+  static isSerializedDataStoreObj(obj) {
+    return typeof obj === "object" && obj !== null && "id" in obj && "data" in obj && "formatVersion" in obj && "encoded" in obj;
+  }
+  /** Returns the DataStore instances whose IDs match the provided array or function */
+  getStoresFiltered(stores) {
+    return this.stores.filter((s) => typeof stores === "undefined" ? true : Array.isArray(stores) ? stores.includes(s.id) : stores(s.id));
+  }
+};
 
+// lib/Debouncer.ts
+var Debouncer = class extends NanoEmitter {
+  /**
+   * Creates a new debouncer with the specified timeout and edge type.
+   * @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 = 200, type = "immediate", nanoEmitterOptions) {
+    super(nanoEmitterOptions);
+    this.timeout = timeout;
+    this.type = type;
+    /** All registered listener functions and the time they were attached */
+    __publicField(this, "listeners", []);
+    /** The currently active timeout */
+    __publicField(this, "activeTimeout");
+    /** The latest queued call */
+    __publicField(this, "queuedCall");
+  }
+  //#region listeners
+  /** Adds a listener function that will be called on timeout */
+  addListener(fn) {
+    this.listeners.push(fn);
+  }
+  /** Removes the listener with the specified function reference */
+  removeListener(fn) {
+    const idx = this.listeners.findIndex((l) => l === fn);
+    idx !== -1 && this.listeners.splice(idx, 1);
+  }
+  /** Removes all listeners */
+  removeAllListeners() {
+    this.listeners = [];
+  }
+  /** Returns all registered listeners */
+  getListeners() {
+    return this.listeners;
+  }
+  //#region timeout
+  /** Sets the timeout for the debouncer */
+  setTimeout(timeout) {
+    this.events.emit("change", this.timeout = timeout, this.type);
+  }
+  /** Returns the current timeout */
+  getTimeout() {
+    return this.timeout;
+  }
+  /** Whether the timeout is currently active, meaning any latest call to the {@linkcode call()} method will be queued */
+  isTimeoutActive() {
+    return typeof this.activeTimeout !== "undefined";
+  }
+  //#region type
+  /** Sets the edge type for the debouncer */
+  setType(type) {
+    this.events.emit("change", this.timeout, this.type = type);
+  }
+  /** Returns the current edge type */
+  getType() {
+    return this.type;
+  }
+  //#region call
+  /** Use this to call the debouncer with the specified arguments that will be passed to all listener functions registered with {@linkcode addListener()} */
+  call(...args) {
+    const cl = (...a) => {
+      this.queuedCall = void 0;
+      this.events.emit("call", ...a);
+      this.listeners.forEach((l) => l.call(this, ...a));
+    };
+    const setRepeatTimeout = () => {
+      this.activeTimeout = setTimeout(() => {
+        if (this.queuedCall) {
+          this.queuedCall();
+          setRepeatTimeout();
+        } else
+          this.activeTimeout = void 0;
+      }, this.timeout);
+    };
+    switch (this.type) {
+      case "immediate":
+        if (typeof this.activeTimeout === "undefined") {
+          cl(...args);
+          setRepeatTimeout();
+        } else
+          this.queuedCall = () => cl(...args);
+        break;
+      case "idle":
+        if (this.activeTimeout)
+          clearTimeout(this.activeTimeout);
+        this.activeTimeout = setTimeout(() => {
+          cl(...args);
+          this.activeTimeout = void 0;
+        }, this.timeout);
+        break;
+      default:
+        throw new TypeError(`Invalid debouncer type: ${this.type}`);
+    }
+  }
+};
+function debounce(fn, timeout = 200, type = "immediate", nanoEmitterOptions) {
+  const debouncer = new Debouncer(timeout, type, nanoEmitterOptions);
+  debouncer.addListener(fn);
+  const func = ((...args) => debouncer.call(...args));
+  func.debouncer = debouncer;
+  return func;
+}
+
+if(__exports != exports)module.exports = exports;return module.exports}));
+//# sourceMappingURL=CoreUtils.umd.js.map
 
 
 if (typeof module.exports == "object" && typeof exports == "object") {

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` */
@@ -44,9 +44,9 @@ 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);
+    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.  
@@ -118,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/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.4.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",