@gesslar/toolkit 3.5.0 → 3.6.1

package/README.md

@@ -21,6 +21,7 @@ a Tauri app.
 | Promised | Promise utilities for settling, filtering, and extracting values from promise results |
 | Sass | Custom Error class with enhanced features |
 | Tantrum | AggregateError implementation |
+| Time | Timing operations and promise-based delays with cancellation support |
 | Type | String-based type management (exported as TypeSpec in browser) |
 | Util | General utility functions |
 | Valid | Validation and assertion methods |

package/package.json

@@ -6,7 +6,7 @@
     "email": "bmw@gesslar.dev",
     "url": "https://gesslar.dev"
   },
-  "version": "3.5.0",
+  "version": "3.6.1",
   "license": "Unlicense",
   "homepage": "https://github.com/gesslar/toolkit#readme",
   "repository": {
@@ -52,25 +52,28 @@
   "engines": {
     "node": ">=22"
   },
-  "scripts": {
-    "types:build": "node -e \"require('fs').rmSync('src/types',{recursive:true,force:true});\" && tsc -p tsconfig.types.json",
-    "prepublishOnly": "npm run types:build",
-    "lint": "eslint src/",
-    "lint:fix": "eslint src/ --fix",
-    "submit": "npm publish --access public --//registry.npmjs.org/:_authToken=\"${NPM_ACCESS_TOKEN}\"",
-    "update": "npx npm-check-updates -u && npm install",
-    "test": "node --test tests/**/*.test.js",
-    "pr": "gt submit -p --ai"
-  },
   "dependencies": {
-    "@gesslar/colours": "^0.4.0",
+    "@gesslar/colours": "^0.5.0",
     "ajv": "^8.17.1",
     "globby": "^16.1.0",
     "json5": "^2.2.3",
     "yaml": "^2.8.2"
   },
   "devDependencies": {
-    "@gesslar/uglier": "^0.2.0",
+    "@gesslar/uglier": "^0.4.0",
+    "eslint": "^9.39.2",
     "typescript": "^5.9.3"
+  },
+  "scripts": {
+    "types:build": "node -e \"require('fs').rmSync('src/types',{recursive:true,force:true});\" && tsc -p tsconfig.types.json",
+    "lint": "eslint src/",
+    "lint:fix": "eslint src/ --fix",
+    "submit": "pnpm publish --access public --//registry.npmjs.org/:_authToken=\"${NPM_ACCESS_TOKEN}\"",
+    "update": "pnpm up --latest --recursive",
+    "test": "node --test tests/**/*.test.js",
+    "pr": "gt submit -p --ai",
+    "patch": "pnpm version patch",
+    "minor": "pnpm version minor",
+    "major": "pnpm version major"
   }
-}
+}

package/src/browser/index.js

@@ -11,6 +11,7 @@ export {default as Notify} from "./lib/Notify.js"
 export {default as Promised} from "./lib/Promised.js"
 export {default as Sass} from "./lib/Sass.js"
 export {default as Tantrum} from "./lib/Tantrum.js"
+export {default as Time} from "./lib/Time.js"
 export {default as Type} from "./lib/TypeSpec.js"
 export {default as Util} from "./lib/Util.js"
 export {default as Valid} from "./lib/Valid.js"

package/src/browser/lib/Time.js

@@ -0,0 +1,54 @@
+import Valid from "./Valid.js"
+
+/**
+ * Utility class for timing operations and promise-based delays.
+ * Provides methods for creating cancellable timeout promises.
+ */
+export default class Time {
+  /**
+   * Creates a promise that resolves after a specified delay.
+   * 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
+   * @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')
+   *
+   * // Create a cancellable delay
+   * const promise = Time.after(5000, 'data')
+   * Time.cancel(promise) // Cancel before it resolves
+   */
+  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 => {
+      timerId = setTimeout(() => resolve(value), delay)
+    })
+    promise.timerId = timerId
+
+    return promise
+  }
+
+  /**
+   * Cancels a promise created by Time.after() by clearing its timeout.
+   * If the promise has already resolved or is not a Time.after() promise, this is a no-op.
+   *
+   * @param {Promise<unknown> & {timerId?: number}} promise - Promise returned from Time.after() to cancel
+   * @returns {void}
+   * @example
+   * const promise = Time.after(5000, 'data')
+   * Time.cancel(promise) // Prevents the promise from resolving
+   */
+  static cancel(promise) {
+    if(promise && typeof promise === "object" && "timerId" in promise)
+      clearTimeout(promise.timerId)
+  }
+}

package/src/index.js

@@ -4,6 +4,7 @@ export {default as Data} from "./browser/lib/Data.js"
 export {default as Disposer} from "./browser/lib/Disposer.js"
 export {Disposer as DisposerClass} from "./browser/lib/Disposer.js"
 export {default as Promised} from "./browser/lib/Promised.js"
+export {default as Time} from "./browser/lib/Time.js"
 export {default as Type} from "./browser/lib/TypeSpec.js"
 export {default as Valid} from "./lib/Valid.js"
 

package/src/types/browser/index.d.ts

@@ -4,6 +4,7 @@ export { default as Notify } from "./lib/Notify.js";
 export { default as Promised } from "./lib/Promised.js";
 export { default as Sass } from "./lib/Sass.js";
 export { default as Tantrum } from "./lib/Tantrum.js";
+export { default as Time } from "./lib/Time.js";
 export { default as Type } from "./lib/TypeSpec.js";
 export { default as Util } from "./lib/Util.js";
 export { default as Valid } from "./lib/Valid.js";

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

@@ -0,0 +1,42 @@
+/**
+ * Utility class for timing operations and promise-based delays.
+ * Provides methods for creating cancellable timeout promises.
+ */
+export default class Time {
+    /**
+     * Creates a promise that resolves after a specified delay.
+     * 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
+     * @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')
+     *
+     * // Create a cancellable delay
+     * const promise = Time.after(5000, 'data')
+     * Time.cancel(promise) // Cancel before it resolves
+     */
+    static after(delay: number, value?: unknown): Promise<unknown> & {
+        timerId: number;
+    };
+    /**
+     * Cancels a promise created by Time.after() by clearing its timeout.
+     * If the promise has already resolved or is not a Time.after() promise, this is a no-op.
+     *
+     * @param {Promise<unknown> & {timerId?: number}} promise - Promise returned from Time.after() to cancel
+     * @returns {void}
+     * @example
+     * const promise = Time.after(5000, 'data')
+     * Time.cancel(promise) // Prevents the promise from resolving
+     */
+    static cancel(promise: Promise<unknown> & {
+        timerId?: number;
+    }): void;
+}
+//# sourceMappingURL=Time.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Time.d.ts","sourceRoot":"","sources":["../../../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,CAwBhD;IAED;;;;;;;;;OASG;IACH,uBANW,OAAO,CAAC,OAAO,CAAC,GAAG;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAC,GACnC,IAAI,CAQhB;CACF"}

package/src/types/index.d.ts

@@ -1,6 +1,7 @@
 export { default as Collection } from "./browser/lib/Collection.js";
 export { default as Data } from "./browser/lib/Data.js";
 export { default as Promised } from "./browser/lib/Promised.js";
+export { default as Time } from "./browser/lib/Time.js";
 export { default as Type } from "./browser/lib/TypeSpec.js";
 export { default as Valid } from "./lib/Valid.js";
 export { default as Sass } from "./lib/Sass.js";