@sv443-network/userutils 10.1.0 → 10.2.0

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # @sv443-network/userutils
 
+## 10.2.0
+
+### Minor Changes
+
+- 1f32c2e: Updated CoreUtils to v3.4.0, which includes the following changes:
+  - `Debouncer` and `debounce` now have an extra parameter of type `NanoEmitterOptions` to customize the underlying `NanoEmitter` instance.
+  - Added function `createRecurringTask()` as a "batteries included" alternative to `setImmediateTimeoutLoop()` and `setImmediateInterval()`, with more ways to control task execution and aborting.
+  - Fixed internal event emission problems in `Debouncer`
+
 ## 10.1.0
 
 ### Minor Changes

package/README.md

@@ -108,6 +108,8 @@ View the documentation of previous major versions:
     - 🟧 [`class DataStore`](https://github.com/Sv443-Network/CoreUtils/blob/main/docs.md#class-datastore) - The main class for the data store
       - 🔷 [`type DataStoreOptions`](https://github.com/Sv443-Network/CoreUtils/blob/main/docs.md#type-datastoreoptions) - Options for the data store
       - 🔷 [`type DataMigrationsDict`](https://github.com/Sv443-Network/CoreUtils/blob/main/docs.md#type-datamigrationsdict) - Dictionary of data migration functions
+      - 🔷 [`type DataStoreData`](https://github.com/Sv443-Network/CoreUtils/blob/main/docs.md#type-datastoredata) - The type of the serializable data
+      - 🔷 [`type DataStoreEventMap`](https://github.com/Sv443-Network/CoreUtils/blob/main/docs.md#type-datastoreeventmap) - Map of DataStore events
     - 🟧 [`class DataStoreSerializer`](https://github.com/Sv443-Network/CoreUtils/blob/main/docs.md#class-datastoreserializer) - Serializes and deserializes data for multiple DataStore instances
       - 🔷 [`type DataStoreSerializerOptions`](https://github.com/Sv443-Network/CoreUtils/blob/main/docs.md#type-datastoreserializeroptions) - Options for the DataStoreSerializer
       - 🔷 [`type LoadStoresDataResult`](https://github.com/Sv443-Network/CoreUtils/blob/main/docs.md#type-loadstoresdataresult) - Result of calling [`loadStoresData()`](https://github.com/Sv443-Network/CoreUtils/blob/main/docs.md#datastoreserializer-loadstoresdata)

package/dist/UserUtils.cjs

@@ -64,6 +64,7 @@ __export(lib_exports, {
   consumeGen: () => consumeGen,
   consumeStringGen: () => consumeStringGen,
   createProgressBar: () => createProgressBar,
+  createRecurringTask: () => createRecurringTask,
   currentDialogId: () => currentDialogId,
   darkenColor: () => darkenColor,
   debounce: () => debounce,
@@ -117,7 +118,7 @@ __export(lib_exports, {
 });
 module.exports = __toCommonJS(lib_exports);
 
-// node_modules/.pnpm/@sv443-network+coreutils@3.3.0/node_modules/@sv443-network/coreutils/dist/CoreUtils.mjs
+// node_modules/.pnpm/@sv443-network+coreutils@3.4.0/node_modules/@sv443-network/coreutils/dist/CoreUtils.mjs
 function bitSetHas(bitSet, checkVal) {
   return (bitSet & checkVal) === checkVal;
 }
@@ -480,12 +481,46 @@ function getCallStack(asArray, lines = Infinity) {
   if (typeof lines !== "number" || isNaN(lines) || lines < 0)
     throw new TypeError("lines parameter must be a non-negative number");
   try {
-    throw new Error("This is to capture a stack trace with CoreUtils.getCallStack(). (If you see this somewhere, you can safely ignore it.)");
+    throw new CustomError("GetCallStack", "Capturing a stack trace with CoreUtils.getCallStack(). If you see this anywhere, you can safely ignore it.");
   } catch (err) {
     const stack = ((_a = err.stack) != null ? _a : "").split("\n").map((line) => line.trim()).slice(2, lines + 2);
     return asArray !== false ? stack : stack.join("\n");
   }
 }
+function createRecurringTask(options) {
+  var _a;
+  let iterations = 0;
+  let aborted = false;
+  (_a = options.signal) == null ? void 0 : _a.addEventListener("abort", () => {
+    aborted = true;
+  }, { once: true });
+  const runRecurringTask = async (initial = false) => {
+    var _a3, _b;
+    var _a2;
+    if (aborted)
+      return;
+    try {
+      if (((_a3 = options.immediate) != null ? _a3 : true) || !initial) {
+        iterations++;
+        if ((_b = await ((_a2 = options.condition) == null ? void 0 : _a2.call(options, iterations - 1))) != null ? _b : true) {
+          const val = await options.task(iterations - 1);
+          if (options.onSuccess)
+            await options.onSuccess(val, iterations - 1);
+        }
+      }
+    } catch (err) {
+      if (options.onError)
+        await options.onError(err, iterations - 1);
+      if (options.abortOnError)
+        aborted = true;
+      if (!options.onError && !options.abortOnError)
+        throw err;
+    }
+    if (!aborted && (typeof options.maxIterations !== "number" || iterations < options.maxIterations))
+      setTimeout(runRecurringTask, options.timeout);
+  };
+  return runRecurringTask(true);
+}
 function autoPlural(term, num, pluralType = "auto") {
   if (typeof num !== "number") {
     if ("length" in num)
@@ -1291,7 +1326,10 @@ var DataStoreSerializer = class _DataStoreSerializer {
       ...options
     };
   }
-  /** 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.
+   */
   async calcChecksum(input) {
     return computeHash(input, "SHA-256");
   }
@@ -1421,8 +1459,8 @@ var Debouncer = class extends NanoEmitter {
    * @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") {
-    super();
+  constructor(timeout = 200, type = "immediate", nanoEmitterOptions) {
+    super(nanoEmitterOptions);
     /** All registered listener functions and the time they were attached */
     __publicField(this, "listeners", []);
     /** The currently active timeout */
@@ -1453,7 +1491,7 @@ var Debouncer = class extends NanoEmitter {
   //#region timeout
   /** Sets the timeout for the debouncer */
   setTimeout(timeout) {
-    this.emit("change", this.timeout = timeout, this.type);
+    this.events.emit("change", this.timeout = timeout, this.type);
   }
   /** Returns the current timeout */
   getTimeout() {
@@ -1466,7 +1504,7 @@ var Debouncer = class extends NanoEmitter {
   //#region type
   /** Sets the edge type for the debouncer */
   setType(type) {
-    this.emit("change", this.timeout, this.type = type);
+    this.events.emit("change", this.timeout, this.type = type);
   }
   /** Returns the current edge type */
   getType() {
@@ -1477,7 +1515,7 @@ var Debouncer = class extends NanoEmitter {
   call(...args) {
     const cl = (...a) => {
       this.queuedCall = void 0;
-      this.emit("call", ...a);
+      this.events.emit("call", ...a);
       this.listeners.forEach((l) => l.call(this, ...a));
     };
     const setRepeatTimeout = () => {
@@ -1510,8 +1548,8 @@ var Debouncer = class extends NanoEmitter {
     }
   }
 };
-function debounce(fn, timeout = 200, type = "immediate") {
-  const debouncer = new Debouncer(timeout, 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;
@@ -1520,8 +1558,8 @@ function debounce(fn, timeout = 200, type = "immediate") {
 
 // lib/consts.ts
 var rawConsts = {
-  coreUtilsVersion: "3.3.0",
-  userUtilsVersion: "10.1.0"
+  coreUtilsVersion: "3.4.0",
+  userUtilsVersion: "10.2.0"
 };
 function getConst(constKey, defaultVal) {
   const val = rawConsts[constKey];

package/dist/UserUtils.mjs

@@ -2,7 +2,7 @@ var __defProp = Object.defineProperty;
 var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
 var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
 
-// node_modules/.pnpm/@sv443-network+coreutils@3.3.0/node_modules/@sv443-network/coreutils/dist/CoreUtils.mjs
+// node_modules/.pnpm/@sv443-network+coreutils@3.4.0/node_modules/@sv443-network/coreutils/dist/CoreUtils.mjs
 function bitSetHas(bitSet, checkVal) {
   return (bitSet & checkVal) === checkVal;
 }
@@ -365,12 +365,46 @@ function getCallStack(asArray, lines = Infinity) {
   if (typeof lines !== "number" || isNaN(lines) || lines < 0)
     throw new TypeError("lines parameter must be a non-negative number");
   try {
-    throw new Error("This is to capture a stack trace with CoreUtils.getCallStack(). (If you see this somewhere, you can safely ignore it.)");
+    throw new CustomError("GetCallStack", "Capturing a stack trace with CoreUtils.getCallStack(). If you see this anywhere, you can safely ignore it.");
   } catch (err) {
     const stack = ((_a = err.stack) != null ? _a : "").split("\n").map((line) => line.trim()).slice(2, lines + 2);
     return asArray !== false ? stack : stack.join("\n");
   }
 }
+function createRecurringTask(options) {
+  var _a;
+  let iterations = 0;
+  let aborted = false;
+  (_a = options.signal) == null ? void 0 : _a.addEventListener("abort", () => {
+    aborted = true;
+  }, { once: true });
+  const runRecurringTask = async (initial = false) => {
+    var _a3, _b;
+    var _a2;
+    if (aborted)
+      return;
+    try {
+      if (((_a3 = options.immediate) != null ? _a3 : true) || !initial) {
+        iterations++;
+        if ((_b = await ((_a2 = options.condition) == null ? void 0 : _a2.call(options, iterations - 1))) != null ? _b : true) {
+          const val = await options.task(iterations - 1);
+          if (options.onSuccess)
+            await options.onSuccess(val, iterations - 1);
+        }
+      }
+    } catch (err) {
+      if (options.onError)
+        await options.onError(err, iterations - 1);
+      if (options.abortOnError)
+        aborted = true;
+      if (!options.onError && !options.abortOnError)
+        throw err;
+    }
+    if (!aborted && (typeof options.maxIterations !== "number" || iterations < options.maxIterations))
+      setTimeout(runRecurringTask, options.timeout);
+  };
+  return runRecurringTask(true);
+}
 function autoPlural(term, num, pluralType = "auto") {
   if (typeof num !== "number") {
     if ("length" in num)
@@ -1176,7 +1210,10 @@ var DataStoreSerializer = class _DataStoreSerializer {
       ...options
     };
   }
-  /** 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.
+   */
   async calcChecksum(input) {
     return computeHash(input, "SHA-256");
   }
@@ -1306,8 +1343,8 @@ var Debouncer = class extends NanoEmitter {
    * @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") {
-    super();
+  constructor(timeout = 200, type = "immediate", nanoEmitterOptions) {
+    super(nanoEmitterOptions);
     /** All registered listener functions and the time they were attached */
     __publicField(this, "listeners", []);
     /** The currently active timeout */
@@ -1338,7 +1375,7 @@ var Debouncer = class extends NanoEmitter {
   //#region timeout
   /** Sets the timeout for the debouncer */
   setTimeout(timeout) {
-    this.emit("change", this.timeout = timeout, this.type);
+    this.events.emit("change", this.timeout = timeout, this.type);
   }
   /** Returns the current timeout */
   getTimeout() {
@@ -1351,7 +1388,7 @@ var Debouncer = class extends NanoEmitter {
   //#region type
   /** Sets the edge type for the debouncer */
   setType(type) {
-    this.emit("change", this.timeout, this.type = type);
+    this.events.emit("change", this.timeout, this.type = type);
   }
   /** Returns the current edge type */
   getType() {
@@ -1362,7 +1399,7 @@ var Debouncer = class extends NanoEmitter {
   call(...args) {
     const cl = (...a) => {
       this.queuedCall = void 0;
-      this.emit("call", ...a);
+      this.events.emit("call", ...a);
       this.listeners.forEach((l) => l.call(this, ...a));
     };
     const setRepeatTimeout = () => {
@@ -1395,8 +1432,8 @@ var Debouncer = class extends NanoEmitter {
     }
   }
 };
-function debounce(fn, timeout = 200, type = "immediate") {
-  const debouncer = new Debouncer(timeout, 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;
@@ -1405,8 +1442,8 @@ function debounce(fn, timeout = 200, type = "immediate") {
 
 // lib/consts.ts
 var rawConsts = {
-  coreUtilsVersion: "3.3.0",
-  userUtilsVersion: "10.1.0"
+  coreUtilsVersion: "3.4.0",
+  userUtilsVersion: "10.2.0"
 };
 function getConst(constKey, defaultVal) {
   const val = rawConsts[constKey];
@@ -2640,6 +2677,7 @@ export {
   consumeGen,
   consumeStringGen,
   createProgressBar,
+  createRecurringTask,
   currentDialogId,
   darkenColor,
   debounce,

package/dist/UserUtils.umd.js

@@ -131,6 +131,7 @@ __export(lib_exports, {
   consumeGen: () => consumeGen,
   consumeStringGen: () => consumeStringGen,
   createProgressBar: () => createProgressBar,
+  createRecurringTask: () => createRecurringTask,
   currentDialogId: () => currentDialogId,
   darkenColor: () => darkenColor,
   debounce: () => debounce,
@@ -184,7 +185,7 @@ __export(lib_exports, {
 });
 module.exports = __toCommonJS(lib_exports);
 
-// node_modules/.pnpm/@sv443-network+coreutils@3.3.0/node_modules/@sv443-network/coreutils/dist/CoreUtils.mjs
+// node_modules/.pnpm/@sv443-network+coreutils@3.4.0/node_modules/@sv443-network/coreutils/dist/CoreUtils.mjs
 function bitSetHas(bitSet, checkVal) {
   return (bitSet & checkVal) === checkVal;
 }
@@ -556,12 +557,46 @@ function getCallStack(asArray, lines = Infinity) {
   if (typeof lines !== "number" || isNaN(lines) || lines < 0)
     throw new TypeError("lines parameter must be a non-negative number");
   try {
-    throw new Error("This is to capture a stack trace with CoreUtils.getCallStack(). (If you see this somewhere, you can safely ignore it.)");
+    throw new CustomError("GetCallStack", "Capturing a stack trace with CoreUtils.getCallStack(). If you see this anywhere, you can safely ignore it.");
   } catch (err) {
     const stack = ((_a = err.stack) != null ? _a : "").split("\n").map((line) => line.trim()).slice(2, lines + 2);
     return asArray !== false ? stack : stack.join("\n");
   }
 }
+function createRecurringTask(options) {
+  var _a;
+  let iterations = 0;
+  let aborted = false;
+  (_a = options.signal) == null ? void 0 : _a.addEventListener("abort", () => {
+    aborted = true;
+  }, { once: true });
+  const runRecurringTask = (initial = false) => __async(null, null, function* () {
+    var _a3, _b;
+    var _a2;
+    if (aborted)
+      return;
+    try {
+      if (((_a3 = options.immediate) != null ? _a3 : true) || !initial) {
+        iterations++;
+        if ((_b = yield (_a2 = options.condition) == null ? void 0 : _a2.call(options, iterations - 1)) != null ? _b : true) {
+          const val = yield options.task(iterations - 1);
+          if (options.onSuccess)
+            yield options.onSuccess(val, iterations - 1);
+        }
+      }
+    } catch (err) {
+      if (options.onError)
+        yield options.onError(err, iterations - 1);
+      if (options.abortOnError)
+        aborted = true;
+      if (!options.onError && !options.abortOnError)
+        throw err;
+    }
+    if (!aborted && (typeof options.maxIterations !== "number" || iterations < options.maxIterations))
+      setTimeout(runRecurringTask, options.timeout);
+  });
+  return runRecurringTask(true);
+}
 function autoPlural(term, num, pluralType = "auto") {
   if (typeof num !== "number") {
     if ("length" in num)
@@ -1398,7 +1433,10 @@ var DataStoreSerializer = class _DataStoreSerializer {
       remapIds: {}
     }, options);
   }
-  /** 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.
+   */
   calcChecksum(input) {
     return __async(this, null, function* () {
       return computeHash(input, "SHA-256");
@@ -1546,8 +1584,8 @@ var Debouncer = class extends NanoEmitter {
    * @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") {
-    super();
+  constructor(timeout = 200, type = "immediate", nanoEmitterOptions) {
+    super(nanoEmitterOptions);
     /** All registered listener functions and the time they were attached */
     __publicField(this, "listeners", []);
     /** The currently active timeout */
@@ -1578,7 +1616,7 @@ var Debouncer = class extends NanoEmitter {
   //#region timeout
   /** Sets the timeout for the debouncer */
   setTimeout(timeout) {
-    this.emit("change", this.timeout = timeout, this.type);
+    this.events.emit("change", this.timeout = timeout, this.type);
   }
   /** Returns the current timeout */
   getTimeout() {
@@ -1591,7 +1629,7 @@ var Debouncer = class extends NanoEmitter {
   //#region type
   /** Sets the edge type for the debouncer */
   setType(type) {
-    this.emit("change", this.timeout, this.type = type);
+    this.events.emit("change", this.timeout, this.type = type);
   }
   /** Returns the current edge type */
   getType() {
@@ -1602,7 +1640,7 @@ var Debouncer = class extends NanoEmitter {
   call(...args) {
     const cl = (...a) => {
       this.queuedCall = void 0;
-      this.emit("call", ...a);
+      this.events.emit("call", ...a);
       this.listeners.forEach((l) => l.call(this, ...a));
     };
     const setRepeatTimeout = () => {
@@ -1635,8 +1673,8 @@ var Debouncer = class extends NanoEmitter {
     }
   }
 };
-function debounce(fn, timeout = 200, type = "immediate") {
-  const debouncer = new Debouncer(timeout, 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;
@@ -1645,8 +1683,8 @@ function debounce(fn, timeout = 200, type = "immediate") {
 
 // lib/consts.ts
 var rawConsts = {
-  coreUtilsVersion: "3.3.0",
-  userUtilsVersion: "10.1.0"
+  coreUtilsVersion: "3.4.0",
+  userUtilsVersion: "10.2.0"
 };
 function getConst(constKey, defaultVal) {
   const val = rawConsts[constKey];

package/dist/lib/consts.d.ts

@@ -1,7 +1,2 @@
 /** Contains the semver version strings of UserUtils and the bundled library CoreUtils. */
-export declare const versions: {
-    /** Semver version string of the bundled library CoreUtils. */
-    CoreUtils: string;
-    /** Semver version string of UserUtils. */
-    UserUtils: string;
-};
+export declare const versions: Record<"CoreUtils" | "UserUtils", string>;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sv443-network/userutils",
   "libName": "UserUtils",
-  "version": "10.1.0",
+  "version": "10.2.0",
   "description": "General purpose DOM/GreaseMonkey library that allows you to register listeners for when CSS selectors exist, intercept events, create persistent & synchronous data stores, modify the DOM more easily and much more",
   "main": "dist/UserUtils.mjs",
   "module": "dist/UserUtils.mjs",
@@ -33,7 +33,7 @@
   },
   "homepage": "https://github.com/Sv443-Network/UserUtils",
   "dependencies": {
-    "@sv443-network/coreutils": "3.3.0",
+    "@sv443-network/coreutils": "3.4.0",
     "nanoevents": "9.1.0"
   },
   "devDependencies": {