@gesslar/toolkit 4.2.0 → 4.4.0

package/README.md

@@ -101,6 +101,37 @@ The browser version includes: Collection, Data, Disposer, HTML, Notify, Sass,
 Tantrum, Type (TypeSpec), Util, and Valid. Node-only modules (Cache,
 DirectoryObject, FileObject, FileSystem, Glog, Term) are not available in the browser version.
 
+### Vendor Bundle
+
+Pre-built bundles are included for environments without a build pipeline, such
+as webviews (VS Code, Tauri, Electron) or plain HTML pages. No bundler required.
+
+#### ES module
+
+```html
+<script type="module">
+  import {Data, Collection} from "./node_modules/@gesslar/toolkit/vendor/toolkit.esm.js"
+</script>
+```
+
+Or import via the package export:
+
+```javascript
+import {Data, Collection} from "@gesslar/toolkit/vendor"
+```
+
+#### UMD (global script)
+
+```html
+<script src="./node_modules/@gesslar/toolkit/vendor/toolkit.umd.js"></script>
+<script>
+  const {Data, Collection} = Toolkit
+</script>
+```
+
+The vendor bundles contain the same browser-compatible utilities listed above,
+fully self-contained with zero external dependencies.
+
 ## Post Partum
 
 If you made it this far, please understand that I have absolutely zero scruples
@@ -117,3 +148,20 @@ off klaxons about my fetish for breaking changes, so you should be all right
 if you're paying attention. 🤷🏻
 
 Sincerely, Senator Yabba of the Dabba (Doo)
+
+## License
+
+toolkit is released into the public domain under the
+[Unlicense](UNLICENSE.txt).
+
+This package includes or depends on third-party components under their own
+licenses:
+
+| Dependency | License |
+| --- | --- |
+| [@gesslar/colours](https://github.com/gesslar/colours) | Unlicense |
+| [ajv](https://github.com/ajv-validator/ajv) | MIT |
+| [DOMPurify](https://github.com/cure53/DOMPurify) | Apache-2.0 / MPL-2.0 |
+| [json5](https://github.com/json5/json5) | MIT |
+| [supports-color](https://github.com/chalk/supports-color) | MIT |
+| [yaml](https://github.com/eemeli/yaml) | ISC |

package/package.json

@@ -5,7 +5,7 @@
     "name": "gesslar",
     "url": "https://gesslar.dev"
   },
-  "version": "4.2.0",
+  "version": "4.4.0",
   "license": "Unlicense",
   "homepage": "https://github.com/gesslar/toolkit#readme",
   "repository": {
@@ -41,11 +41,16 @@
     "./node": {
       "types": "./types/node/index.d.ts",
       "default": "./src/node/index.js"
+    },
+    "./vendor": {
+      "types": "./types/browser/index.d.ts",
+      "default": "./vendor/toolkit.esm.js"
     }
   },
   "files": [
     "src/",
     "types/",
+    "vendor/",
     "scripts/",
     "UNLICENSE.txt"
   ],
@@ -55,7 +60,8 @@
   "scripts": {
     "preinstall": "node ./scripts/check-node-version.mjs",
     "types": "node -e \"require('fs').rmSync('types',{recursive:true,force:true});\" && tsc -p tsconfig.types.json",
-    "prepublishOnly": "npm run types",
+    "vendor:build": "node scripts/vendor-build.js",
+    "prepack": "npm run types && npm run vendor:build",
     "lint": "eslint src/",
     "lint:fix": "eslint src/ --fix",
     "submit": "npm publish --access public --//registry.npmjs.org/:_authToken=\"${NPM_ACCESS_TOKEN}\"",
@@ -78,8 +84,10 @@
   },
   "devDependencies": {
     "@gesslar/uglier": "^2.2.0",
+    "@rollup/plugin-node-resolve": "^16.0.3",
     "eslint": "^10.0.3",
     "happy-dom": "^20.8.4",
+    "rollup": "^4.59.0",
     "typescript": "^5.9.3"
   }
 }

package/scripts/vendor-build.js

@@ -0,0 +1,32 @@
+import {readFileSync, mkdirSync} from "node:fs"
+import {rollup} from "rollup"
+import {nodeResolve} from "@rollup/plugin-node-resolve"
+
+const vendorDir = "vendor"
+const {version} = JSON.parse(readFileSync("package.json", "utf8"))
+
+mkdirSync(vendorDir, {recursive: true})
+
+const bundle = await rollup({
+  input: "src/browser/index.js",
+  plugins: [nodeResolve()],
+})
+
+try {
+  await bundle.write({
+    file: `${vendorDir}/toolkit.esm.js`,
+    format: "es",
+    banner: `// @gesslar/toolkit v${version} - ES module bundle`,
+  })
+
+  await bundle.write({
+    file: `${vendorDir}/toolkit.umd.js`,
+    format: "umd",
+    name: "Toolkit",
+    banner: `// @gesslar/toolkit v${version} - UMD bundle`,
+  })
+} finally {
+  await bundle.close()
+}
+
+console.log(`Built vendor bundles for @gesslar/toolkit@${version}`)

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"}