@gesslar/toolkit 4.1.0 → 4.3.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.1.0",
+  "version": "4.3.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}\"",
@@ -77,9 +83,11 @@
     "yaml": "^2.8.2"
   },
   "devDependencies": {
-    "@gesslar/uglier": "^2.0.0",
-    "eslint": "^10.0.2",
-    "happy-dom": "^20.8.3",
+    "@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",
     "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/node/lib/Notify.js

@@ -54,6 +54,26 @@ export class Notify {
     await Util.asyncEmit(this.#emitter, type, payload)
   }
 
+  /**
+   * Fires an event asynchronously without blocking the caller.
+   * Listeners run in the background. If any listener throws and an error
+   * callback is provided, it receives the error. Otherwise errors are
+   * silently discarded.
+   *
+   * @param {string} type - Event name to dispatch.
+   * @param {unknown} [payload] - Data to send with the event.
+   * @param {((error: Error) => void)|null} [errorCb] - Optional callback for errors.
+   * @param {AbortSignal} [signal] - Optional AbortSignal to cancel the operation.
+   * @returns {undefined}
+   */
+  fire(type, payload, errorCb, signal) {
+    Valid.type(type, "String", {allowEmpty: false})
+    Valid.type(errorCb, "Undefined|Null|Function")
+    Valid.type(signal, "Undefined|Null|AbortSignal")
+
+    Util.fire(this.#emitter, type, payload, errorCb, signal)
+  }
+
   /**
    * Emits an event and returns the payload for simple request/response flows.
    * Listeners can mutate the payload object to provide responses.

package/src/node/lib/Util.js

@@ -68,7 +68,7 @@ export default class Util extends BrowserUtil {
    * @returns {Promise<undefined>} Resolves when all listeners have completed
    */
   static async #performAsyncEmit(emitter, event, ...args) {
-    const listeners = emitter.listeners(event)
+    const listeners = emitter.rawListeners(event)
 
     if(listeners.length === 0)
       return // No listeners, nothing to do
@@ -115,6 +115,48 @@ export default class Util extends BrowserUtil {
     }
   }
 
+  /**
+   * Fires an event asynchronously without blocking the caller.
+   * Listeners run in the background via asyncEmit. If any listener rejects
+   * and an error callback is provided, it receives the error. If no callback
+   * is provided, errors are silently discarded.
+   *
+   * @param {EventEmitter} emitter - The EventEmitter instance to emit on
+   * @param {string} event - The event name to emit
+   * @param {unknown} [payload] - Data to send with the event
+   * @param {((error: Error) => void)|null} [errorCb] - Optional callback for errors
+   * @param {AbortSignal} [signal] - Optional AbortSignal to cancel the operation
+   * @returns {undefined}
+   */
+  static fire(emitter, event, payload, errorCb, signal) {
+    Valid.type(errorCb, "Undefined|Null|Function")
+    Valid.type(signal, "Undefined|Null|AbortSignal")
+
+    if(signal?.aborted)
+      return
+
+    const promise = this.asyncEmit(emitter, event, payload)
+
+    if(signal) {
+      const onAbort = () => {}  // asyncEmit already in flight, nothing to cancel
+      signal.addEventListener("abort", onAbort, {once: true})
+      promise.then(
+        () => signal.removeEventListener("abort", onAbort),
+        error => {
+          signal.removeEventListener("abort", onAbort)
+
+          if(!signal.aborted && errorCb) {
+            errorCb(error)
+          }
+        }
+      )
+    } else if(errorCb) {
+      promise.catch(errorCb)
+    } else {
+      promise.catch(() => {})
+    }
+  }
+
   /**
    * Emits an event asynchronously and waits for all listeners to complete.
    * Like asyncEmit, but uses duck typing for more flexible emitter validation.
@@ -129,7 +171,7 @@ export default class Util extends BrowserUtil {
   static async asyncEmitQuack(emitter, event, ...args) {
     try {
       if(!emitter ||
-         typeof emitter.listeners !== "function" ||
+         typeof emitter.rawListeners !== "function" ||
          typeof emitter.on !== "function" ||
          typeof emitter.emit !== "function") {
         throw Sass.new("First argument must be an EventEmitter-like object")

package/types/node/lib/Notify.d.ts

@@ -28,6 +28,19 @@ export class Notify {
      * @returns {Promise<undefined>} Resolves when all listeners have completed.
      */
     asyncEmit(type: string, payload?: unknown): Promise<undefined>;
+    /**
+     * Fires an event asynchronously without blocking the caller.
+     * Listeners run in the background. If any listener throws and an error
+     * callback is provided, it receives the error. Otherwise errors are
+     * silently discarded.
+     *
+     * @param {string} type - Event name to dispatch.
+     * @param {unknown} [payload] - Data to send with the event.
+     * @param {((error: Error) => void)|null} [errorCb] - Optional callback for errors.
+     * @param {AbortSignal} [signal] - Optional AbortSignal to cancel the operation.
+     * @returns {undefined}
+     */
+    fire(type: string, payload?: unknown, errorCb?: ((error: Error) => void) | null, signal?: AbortSignal): undefined;
     /**
      * Emits an event and returns the payload for simple request/response flows.
      * Listeners can mutate the payload object to provide responses.

package/types/node/lib/Notify.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Notify.d.ts","sourceRoot":"","sources":["../../../src/node/lib/Notify.js"],"names":[],"mappings":"AAWA;;;;GAIG;AAEH;;;GAGG;AACH;IACE,iDAAiD;IACjD,MADW,MAAM,CACF;IAKf;;;;;;OAMG;IACH,WAJW,MAAM,YACN,OAAO,GACL,SAAS,CAMrB;IAED;;;;;;;;OAQG;IACH,gBAJW,MAAM,YACN,OAAO,GACL,OAAO,CAAC,SAAS,CAAC,CAM9B;IAED;;;;;;;OAOG;IACH,cAJW,MAAM,YACN,OAAO,GACL,OAAO,CAQnB;IAED;;;;;;;;OAQG;IACH,SANW,MAAM,WACN,CAAC,OAAO,EAAE,OAAO,KAAK,SAAS,YAC/B,YAAY,YACZ,kBAAkB,GAChB,MAAM,SAAS,CAa3B;IAED;;;;;;;OAOG;IACH,UALW,MAAM,WACN,CAAC,OAAO,EAAE,OAAO,KAAK,SAAS,YAC/B,YAAY,GACV,SAAS,CAMrB;;CACF;;;;;;;WA9Fa,OAAO;;;;aACP,WAAW;;6BARE,aAAa"}
+{"version":3,"file":"Notify.d.ts","sourceRoot":"","sources":["../../../src/node/lib/Notify.js"],"names":[],"mappings":"AAWA;;;;GAIG;AAEH;;;GAGG;AACH;IACE,iDAAiD;IACjD,MADW,MAAM,CACF;IAKf;;;;;;OAMG;IACH,WAJW,MAAM,YACN,OAAO,GACL,SAAS,CAMrB;IAED;;;;;;;;OAQG;IACH,gBAJW,MAAM,YACN,OAAO,GACL,OAAO,CAAC,SAAS,CAAC,CAM9B;IAED;;;;;;;;;;;OAWG;IACH,WANW,MAAM,YACN,OAAO,YACP,CAAC,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC,GAAC,IAAI,WAC7B,WAAW,GACT,SAAS,CAQrB;IAED;;;;;;;OAOG;IACH,cAJW,MAAM,YACN,OAAO,GACL,OAAO,CAQnB;IAED;;;;;;;;OAQG;IACH,SANW,MAAM,WACN,CAAC,OAAO,EAAE,OAAO,KAAK,SAAS,YAC/B,YAAY,YACZ,kBAAkB,GAChB,MAAM,SAAS,CAa3B;IAED;;;;;;;OAOG;IACH,UALW,MAAM,WACN,CAAC,OAAO,EAAE,OAAO,KAAK,SAAS,YAC/B,YAAY,GACV,SAAS,CAMrB;;CACF;;;;;;;WAlHa,OAAO;;;;aACP,WAAW;;6BARE,aAAa"}

package/types/node/lib/Util.d.ts

@@ -59,6 +59,20 @@ export default class Util extends BrowserUtil {
      * @returns {Promise<undefined>} Resolves when all listeners have completed
      */
     static asyncEmit(emitter: EventEmitter, event: string, ...args: unknown[]): Promise<undefined>;
+    /**
+     * Fires an event asynchronously without blocking the caller.
+     * Listeners run in the background via asyncEmit. If any listener rejects
+     * and an error callback is provided, it receives the error. If no callback
+     * is provided, errors are silently discarded.
+     *
+     * @param {EventEmitter} emitter - The EventEmitter instance to emit on
+     * @param {string} event - The event name to emit
+     * @param {unknown} [payload] - Data to send with the event
+     * @param {((error: Error) => void)|null} [errorCb] - Optional callback for errors
+     * @param {AbortSignal} [signal] - Optional AbortSignal to cancel the operation
+     * @returns {undefined}
+     */
+    static fire(emitter: EventEmitter, event: string, payload?: unknown, errorCb?: ((error: Error) => void) | null, signal?: AbortSignal): undefined;
     /**
      * Emits an event asynchronously and waits for all listeners to complete.
      * Like asyncEmit, but uses duck typing for more flexible emitter validation.

package/types/node/lib/Util.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Util.d.ts","sourceRoot":"","sources":["../../../src/node/lib/Util.js"],"names":[],"mappings":"AAQA;;;GAGG;AACH;IACE;;;;;OAKG;IACH,iBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,mCAHW,MAAM,GACJ,KAAK,CAAC,MAAM,CAAC,CAazB;IAED;;;;;;;;OAQG;IACH,+CALW,MAAM,SACN,MAAM,WACH,OAAO,EAAA,GACR,OAAO,CAAC,SAAS,CAAC,CAmB9B;IAED;;;;;;;;;;;;OAYG;IACH,0BALW,YAAY,SACZ,MAAM,WACH,OAAO,EAAA,GACR,OAAO,CAAC,SAAS,CAAC,CAgB9B;IAED;;;;;;;;;;OAUG;IACH,+BALW,MAAM,SACN,MAAM,WACH,OAAO,EAAA,GACR,OAAO,CAAC,SAAS,CAAC,CAoB9B;IAED;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,kBALW,MAAM,QACN,OAAO,GACL,OAAO,CAmBnB;CACF;wBA1LuB,2BAA2B;6BADxB,aAAa"}
+{"version":3,"file":"Util.d.ts","sourceRoot":"","sources":["../../../src/node/lib/Util.js"],"names":[],"mappings":"AAQA;;;GAGG;AACH;IACE;;;;;OAKG;IACH,iBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,mCAHW,MAAM,GACJ,KAAK,CAAC,MAAM,CAAC,CAazB;IAED;;;;;;;;OAQG;IACH,+CALW,MAAM,SACN,MAAM,WACH,OAAO,EAAA,GACR,OAAO,CAAC,SAAS,CAAC,CAmB9B;IAED;;;;;;;;;;;;OAYG;IACH,0BALW,YAAY,SACZ,MAAM,WACH,OAAO,EAAA,GACR,OAAO,CAAC,SAAS,CAAC,CAgB9B;IAED;;;;;;;;;;;;OAYG;IACH,qBAPW,YAAY,SACZ,MAAM,YACN,OAAO,YACP,CAAC,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC,GAAC,IAAI,WAC7B,WAAW,GACT,SAAS,CA6BrB;IAED;;;;;;;;;;OAUG;IACH,+BALW,MAAM,SACN,MAAM,WACH,OAAO,EAAA,GACR,OAAO,CAAC,SAAS,CAAC,CAoB9B;IAED;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,kBALW,MAAM,QACN,OAAO,GACL,OAAO,CAmBnB;CACF;wBApOuB,2BAA2B;6BADxB,aAAa"}