@gesslar/toolkit 4.3.0 → 4.4.0

package/package.json

@@ -5,7 +5,7 @@
     "name": "gesslar",
     "url": "https://gesslar.dev"
   },
-  "version": "4.3.0",
+  "version": "4.4.0",
   "license": "Unlicense",
   "homepage": "https://github.com/gesslar/toolkit#readme",
   "repository": {
@@ -85,9 +85,9 @@
   "devDependencies": {
     "@gesslar/uglier": "^2.2.0",
     "@rollup/plugin-node-resolve": "^16.0.3",
-    "rollup": "^4.59.0",
     "eslint": "^10.0.3",
     "happy-dom": "^20.8.4",
+    "rollup": "^4.59.0",
     "typescript": "^5.9.3"
   }
 }

package/src/browser/lib/Time.js

@@ -1,3 +1,4 @@
+import Data from "./Data.js"
 import Sass from "./Sass.js"
 import Valid from "./Valid.js"
 /**
@@ -10,29 +11,45 @@ export default class Time {
    * The returned promise includes a timerId property that can be used with cancel().
    *
    * @param {number} delay - Delay in milliseconds before resolving (must be >= 0)
-   * @param {unknown} [value] - Optional value to resolve with after the delay
-   * @returns {Promise<unknown> & {timerId: number}} Promise that resolves with the value after delay, extended with timerId property
+   * @param {unknown} [value] - Optional value to resolve with, or a function to invoke after the delay
+   * @returns {Promise<unknown> & {timerId: number}} Promise that resolves with the value (or function result) after delay, extended with timerId property
    * @throws {Sass} If delay is not a number or is negative
    * @example
    * // Wait 1 second then continue
    * await Time.after(1000)
    *
-   * // Wait 1 second then get a value
-   * const result = await Time.after(1000, 'done')
+   * // Debounce: only apply the latest input after the user stops typing
+   * let pending = null
+   * function onInput(text) {
+   *   Time.cancel(pending) // cancel() is a no-op if not a valid Time promise.
+   *   pending = Time.after(300, () => applySearch(text))
+   * }
    *
-   * // Create a cancellable delay
-   * const promise = Time.after(5000, 'data')
-   * Time.cancel(promise) // Cancel before it resolves
+   * // Timeout a fetch request
+   * const result = await Promise.race([
+   *   fetch("/api/data"),
+   *   Time.after(5000, () => { throw new Error("Request timed out") })
+   * ])
+   *
+   * // Cancellable delay
+   * const promise = Time.after(5000, "data")
+   * Time.cancel(promise) // Prevents resolution
    */
   static after(delay, value) {
     Valid.type(delay, "Number", "delay")
     Valid.assert(delay >= 0, "delay must be non-negative", delay)
 
     let timerId
-    const promise = new Promise(resolve => {
+    const promise = new Promise((resolve, reject) => {
       // Cap at max 32-bit signed integer to avoid Node.js timeout overflow warning
       const safeDelay = Math.min(delay, 2147483647)
-      timerId = setTimeout(() => resolve(value), safeDelay)
+      timerId = setTimeout(() => {
+        try {
+          resolve(Data.isType(value, "Function") ? value() : value)
+        } catch(e) {
+          reject(e)
+        }
+      }, safeDelay)
     })
     promise.timerId = timerId
 

package/types/browser/lib/Time.d.ts

@@ -8,19 +8,29 @@ export default class Time {
      * The returned promise includes a timerId property that can be used with cancel().
      *
      * @param {number} delay - Delay in milliseconds before resolving (must be >= 0)
-     * @param {unknown} [value] - Optional value to resolve with after the delay
-     * @returns {Promise<unknown> & {timerId: number}} Promise that resolves with the value after delay, extended with timerId property
+     * @param {unknown} [value] - Optional value to resolve with, or a function to invoke after the delay
+     * @returns {Promise<unknown> & {timerId: number}} Promise that resolves with the value (or function result) after delay, extended with timerId property
      * @throws {Sass} If delay is not a number or is negative
      * @example
      * // Wait 1 second then continue
      * await Time.after(1000)
      *
-     * // Wait 1 second then get a value
-     * const result = await Time.after(1000, 'done')
+     * // Debounce: only apply the latest input after the user stops typing
+     * let pending = null
+     * function onInput(text) {
+     *   Time.cancel(pending) // cancel() is a no-op if not a valid Time promise.
+     *   pending = Time.after(300, () => applySearch(text))
+     * }
      *
-     * // Create a cancellable delay
-     * const promise = Time.after(5000, 'data')
-     * Time.cancel(promise) // Cancel before it resolves
+     * // Timeout a fetch request
+     * const result = await Promise.race([
+     *   fetch("/api/data"),
+     *   Time.after(5000, () => { throw new Error("Request timed out") })
+     * ])
+     *
+     * // Cancellable delay
+     * const promise = Time.after(5000, "data")
+     * Time.cancel(promise) // Prevents resolution
      */
     static after(delay: number, value?: unknown): Promise<unknown> & {
         timerId: number;

package/types/browser/lib/Time.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Time.d.ts","sourceRoot":"","sources":["../../../src/browser/lib/Time.js"],"names":[],"mappings":"AAEA;;;GAGG;AACH;IACE;;;;;;;;;;;;;;;;;;OAkBG;IACH,oBAfW,MAAM,UACN,OAAO,GACL,OAAO,CAAC,OAAO,CAAC,GAAG;QAAC,OAAO,EAAE,MAAM,CAAA;KAAC,CA0BhD;IAED;;;;;;;;;OASG;IACH,uBANW,OAAO,CAAC,OAAO,CAAC,GAAG;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAC,GACnC,IAAI,CAQhB;CACF"}
+{"version":3,"file":"Time.d.ts","sourceRoot":"","sources":["../../../src/browser/lib/Time.js"],"names":[],"mappings":"AAGA;;;GAGG;AACH;IACE;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACH,oBAzBW,MAAM,UACN,OAAO,GACL,OAAO,CAAC,OAAO,CAAC,GAAG;QAAC,OAAO,EAAE,MAAM,CAAA;KAAC,CA0ChD;IAED;;;;;;;;;OASG;IACH,uBANW,OAAO,CAAC,OAAO,CAAC,GAAG;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAC,GACnC,IAAI,CAQhB;CACF"}

package/vendor/toolkit.esm.js

@@ -1,4 +1,4 @@
-// @gesslar/toolkit v4.3.0 - ES module bundle
+// @gesslar/toolkit v4.4.0 - ES module bundle
 /**
  * @file Tantrum.js
  *
@@ -4170,29 +4170,45 @@ class Time {
    * The returned promise includes a timerId property that can be used with cancel().
    *
    * @param {number} delay - Delay in milliseconds before resolving (must be >= 0)
-   * @param {unknown} [value] - Optional value to resolve with after the delay
-   * @returns {Promise<unknown> & {timerId: number}} Promise that resolves with the value after delay, extended with timerId property
+   * @param {unknown} [value] - Optional value to resolve with, or a function to invoke after the delay
+   * @returns {Promise<unknown> & {timerId: number}} Promise that resolves with the value (or function result) after delay, extended with timerId property
    * @throws {Sass} If delay is not a number or is negative
    * @example
    * // Wait 1 second then continue
    * await Time.after(1000)
    *
-   * // Wait 1 second then get a value
-   * const result = await Time.after(1000, 'done')
+   * // Debounce: only apply the latest input after the user stops typing
+   * let pending = null
+   * function onInput(text) {
+   *   Time.cancel(pending) // cancel() is a no-op if not a valid Time promise.
+   *   pending = Time.after(300, () => applySearch(text))
+   * }
    *
-   * // Create a cancellable delay
-   * const promise = Time.after(5000, 'data')
-   * Time.cancel(promise) // Cancel before it resolves
+   * // Timeout a fetch request
+   * const result = await Promise.race([
+   *   fetch("/api/data"),
+   *   Time.after(5000, () => { throw new Error("Request timed out") })
+   * ])
+   *
+   * // Cancellable delay
+   * const promise = Time.after(5000, "data")
+   * Time.cancel(promise) // Prevents resolution
    */
   static after(delay, value) {
     Valid.type(delay, "Number", "delay");
     Valid.assert(delay >= 0, "delay must be non-negative", delay);
 
     let timerId;
-    const promise = new Promise(resolve => {
+    const promise = new Promise((resolve, reject) => {
       // Cap at max 32-bit signed integer to avoid Node.js timeout overflow warning
       const safeDelay = Math.min(delay, 2147483647);
-      timerId = setTimeout(() => resolve(value), safeDelay);
+      timerId = setTimeout(() => {
+        try {
+          resolve(Data.isType(value, "Function") ? value() : value);
+        } catch(e) {
+          reject(e);
+        }
+      }, safeDelay);
     });
     promise.timerId = timerId;
 

package/vendor/toolkit.umd.js

@@ -1,4 +1,4 @@
-// @gesslar/toolkit v4.3.0 - UMD bundle
+// @gesslar/toolkit v4.4.0 - UMD bundle
 (function (global, factory) {
   typeof exports === 'object' && typeof module !== 'undefined' ? factory(exports) :
   typeof define === 'function' && define.amd ? define(['exports'], factory) :
@@ -4176,29 +4176,45 @@
      * The returned promise includes a timerId property that can be used with cancel().
      *
      * @param {number} delay - Delay in milliseconds before resolving (must be >= 0)
-     * @param {unknown} [value] - Optional value to resolve with after the delay
-     * @returns {Promise<unknown> & {timerId: number}} Promise that resolves with the value after delay, extended with timerId property
+     * @param {unknown} [value] - Optional value to resolve with, or a function to invoke after the delay
+     * @returns {Promise<unknown> & {timerId: number}} Promise that resolves with the value (or function result) after delay, extended with timerId property
      * @throws {Sass} If delay is not a number or is negative
      * @example
      * // Wait 1 second then continue
      * await Time.after(1000)
      *
-     * // Wait 1 second then get a value
-     * const result = await Time.after(1000, 'done')
+     * // Debounce: only apply the latest input after the user stops typing
+     * let pending = null
+     * function onInput(text) {
+     *   Time.cancel(pending) // cancel() is a no-op if not a valid Time promise.
+     *   pending = Time.after(300, () => applySearch(text))
+     * }
      *
-     * // Create a cancellable delay
-     * const promise = Time.after(5000, 'data')
-     * Time.cancel(promise) // Cancel before it resolves
+     * // Timeout a fetch request
+     * const result = await Promise.race([
+     *   fetch("/api/data"),
+     *   Time.after(5000, () => { throw new Error("Request timed out") })
+     * ])
+     *
+     * // Cancellable delay
+     * const promise = Time.after(5000, "data")
+     * Time.cancel(promise) // Prevents resolution
      */
     static after(delay, value) {
       Valid.type(delay, "Number", "delay");
       Valid.assert(delay >= 0, "delay must be non-negative", delay);
 
       let timerId;
-      const promise = new Promise(resolve => {
+      const promise = new Promise((resolve, reject) => {
         // Cap at max 32-bit signed integer to avoid Node.js timeout overflow warning
         const safeDelay = Math.min(delay, 2147483647);
-        timerId = setTimeout(() => resolve(value), safeDelay);
+        timerId = setTimeout(() => {
+          try {
+            resolve(Data.isType(value, "Function") ? value() : value);
+          } catch(e) {
+            reject(e);
+          }
+        }, safeDelay);
       });
       promise.timerId = timerId;