@gesslar/toolkit 3.26.0 → 3.28.0

package/package.json

@@ -5,7 +5,7 @@
     "name": "gesslar",
     "url": "https://gesslar.dev"
   },
-  "version": "3.26.0",
+  "version": "3.28.0",
   "license": "Unlicense",
   "homepage": "https://github.com/gesslar/toolkit#readme",
   "repository": {

package/src/browser/index.js

@@ -8,6 +8,7 @@ export {Disposer as DisposerClass} from "./lib/Disposer.js"
 export {default as HTML} from "./lib/HTML.js"
 export {HTML as HTMLClass} from "./lib/HTML.js"
 export {default as Notify} from "./lib/Notify.js"
+export {Notify as NotifyClass} 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"

package/src/browser/lib/Notify.js

@@ -10,7 +10,7 @@
  * @property {boolean} [cancelable] - Whether the event can be canceled.
  * @property {boolean} [composed] - Whether the event can cross the shadow DOM boundary.
  */
-export default new class Notify {
+export class Notify {
   /** @type {string} Display name for debugging. */
   name = "Notify"
 
@@ -87,3 +87,5 @@ export default new class Notify {
     return {detail}
   }
 }
+
+export default new Notify()

package/src/node/index.js

@@ -21,4 +21,5 @@ export {default as FileSystem} from "./lib/FileSystem.js"
 export {default as Font} from "./lib/Font.js"
 export {default as Glog} from "./lib/Glog.js"
 export {default as Notify} from "./lib/Notify.js"
+export {Notify as NotifyClass} from "./lib/Notify.js"
 export {default as Term} from "./lib/Term.js"

package/src/node/lib/Font.js

@@ -10,6 +10,10 @@ import child_process from "node:child_process"
 import DirectoryObject from "./DirectoryObject.js"
 import FS from "./FileSystem.js"
 
+/**
+ * @import {FileObject} from "./FileObject.js"
+ */
+
 const execFile = promisify(child_process.execFile)
 
 /**
@@ -29,6 +33,8 @@ const execFile = promisify(child_process.execFile)
  * console.log(fonts) // ["FiraCode", "JetBrainsMono", ...]
  */
 export default class Font {
+  static #cache = new Map()
+
   /**
    * Finds all Nerd Fonts installed on the system.
    * Detects the current platform and uses platform-specific methods
@@ -40,17 +46,20 @@ export default class Font {
    * console.log(nerdFonts) // ["FiraCode Nerd Font", "JetBrains Mono NF", ...]
    */
   static async findNerdFonts() {
-    const platform = os.platform()
-
-    if(platform === "win32") {
-      return this.#findNerdFontsWindows()
-    } else if(platform === "darwin") {
-      return this.#findNerdFontsMac()
-    } else if(platform === "linux") {
-      return this.#findNerdFontsLinux()
-    } else {
-      return []
+    if(!this.#cache.has("nerdFonts")) {
+      const platform = os.platform()
+
+      if(platform === "win32")
+        this.#cache.set("nerdFonts", this.#findNerdFontsWindows())
+      else if(platform === "darwin")
+        this.#cache.set("nerdFonts", this.#findNerdFontsMac())
+      else if(platform === "linux")
+        this.#cache.set("nerdFonts", this.#findNerdFontsLinux())
+      else
+        this.#cache.set("nerdFonts", [])
     }
+
+    return this.#cache.get("nerdFonts")
   }
 
   /**
@@ -113,12 +122,17 @@ export default class Font {
    */
   static async #findNerdFontsWindows() {
     const fontDirs = [
-      new DirectoryObject(FS.resolvePath(process.env.WINDIR || "C:/Windows", "/Fonts"))
+      new DirectoryObject(FS.resolvePath(
+        process.env.WINDIR || "C:/Windows",
+        "/Fonts"
+      ))
     ]
 
-    if(process.env.LOCALAPPDATA) {
-      fontDirs.push(new DirectoryObject(FS.resolvePath(process.env.LOCALAPPDATA, "Microsoft/Windows/Fonts")))
-    }
+    if(process.env.LOCALAPPDATA)
+      fontDirs.push(new DirectoryObject(FS.resolvePath(
+        process.env.LOCALAPPDATA,
+        "Microsoft/Windows/Fonts"
+      )))
 
     const fontFiles = []
 
@@ -135,7 +149,9 @@ export default class Font {
       }
     }
 
-    return this.#identifyNerdFonts(fontFiles)
+    this.#cache.set("nerdFonts", this.#identifyNerdFonts(fontFiles))
+
+    return this.#cache.get("nerdFonts")
   }
 
   /**
@@ -208,7 +224,7 @@ export default class Font {
   /**
    * Identifies Nerd Fonts from a list of font file objects.
    *
-   * @param {Array<import("./FileObject.js").default>} fileObjects - Array of FileObject instances representing font files.
+   * @param {Array<FileObject>} fileObjects - Array of FileObject instances representing font files.
    * @returns {Array<string>} Sorted array of unique Nerd Font family names.
    * @private
    */
@@ -225,4 +241,23 @@ export default class Font {
 
     return Array.from(nerdFonts).sort()
   }
+
+  /**
+   * Gets spinner animation frames appropriate for the current font environment.
+   * Returns Unicode braille characters if Nerd Fonts are available,
+   * otherwise returns ASCII fallback characters.
+   *
+   * @returns {Promise<Array<string>>} Promise resolving to array of spinner frame characters.
+   * @example
+   * const frames = await Font.spinFrames
+   * // With Nerd Fonts: ["⠋", "⠙", "⠹", ...]
+   * // Without: ["|", "/", "-", "\\"]
+   */
+  static get spinFrames() {
+    return this.hasNerdFonts().then(has =>
+      has
+        ? ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"]
+        : ["|", "/", "-", "\\"]
+    )
+  }
 }

package/src/node/lib/Notify.js

@@ -19,7 +19,7 @@ import Util from "./Util.js"
  * Notify class provides a thin wrapper around EventEmitter for centralized
  * event handling in Node.js applications. Mirrors the browser Notify API.
  */
-export default new class Notify {
+export class Notify {
   /** @type {string} Display name for debugging. */
   name = "Notify"
 
@@ -106,3 +106,5 @@ export default new class Notify {
     emitter.off(type, handler)
   }
 }
+
+export default new Notify()

package/types/browser/index.d.ts

@@ -1,6 +1,5 @@
 export { default as Collection } from "./lib/Collection.js";
 export { default as Data } from "./lib/Data.js";
-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";
@@ -10,4 +9,5 @@ export { default as Util } from "./lib/Util.js";
 export { default as Valid } from "./lib/Valid.js";
 export { default as Disposer, Disposer as DisposerClass } from "./lib/Disposer.js";
 export { default as HTML, HTML as HTMLClass } from "./lib/HTML.js";
+export { default as Notify, Notify as NotifyClass } from "./lib/Notify.js";
 //# sourceMappingURL=index.d.ts.map

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

@@ -1,4 +1,15 @@
-declare const _default: {
+/**
+ * Thin wrapper around `window` event handling to centralize emit/on/off
+ * helpers. Used to dispatch simple CustomEvents and manage listeners in one
+ * place.
+ */
+/**
+ * @typedef {object} NotifyEventOptions
+ * @property {boolean} [bubbles] - Whether the event bubbles up the DOM tree.
+ * @property {boolean} [cancelable] - Whether the event can be canceled.
+ * @property {boolean} [composed] - Whether the event can cross the shadow DOM boundary.
+ */
+export class Notify {
     /** @type {string} Display name for debugging. */
     name: string;
     /**
@@ -29,7 +40,7 @@ declare const _default: {
      * @param {boolean | object} [options] - Options to pass to addEventListener.
      * @returns {() => void} Dispose function to unregister the handler.
      */
-    on(type: string, handler: (evt: /*elided*/ any) => void, element?: HTMLElement | Window, options?: boolean | object): () => void;
+    on(type: string, handler: (evt: Notify) => void, element?: HTMLElement | Window, options?: boolean | object): () => void;
     /**
      * Removes a previously registered listener for the given event type.
      *
@@ -39,9 +50,10 @@ declare const _default: {
      * @param {boolean | object} [options] - Options to pass to removeEventListener.
      * @returns {void}
      */
-    off(type: string, handler: (evt: /*elided*/ any) => void, element?: HTMLElement | Window, options?: boolean | object): void;
-    "__#private@#buildEventInit"(detail: any, options: any): any;
-};
+    off(type: string, handler: (evt: Notify) => void, element?: HTMLElement | Window, options?: boolean | object): void;
+    #private;
+}
+declare const _default: Notify;
 export default _default;
 export type NotifyEventOptions = {
     /**

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

@@ -1 +1 @@
-{"version":3,"file":"Notify.d.ts","sourceRoot":"","sources":["../../../src/browser/lib/Notify.js"],"names":[],"mappings":";IAaE,iDAAiD;UAAtC,MAAM;IAGjB;;;;;;;OAOG;eAJQ,MAAM,YACN,OAAO,YACP,OAAO,GAAG,kBAAkB,GAC1B,IAAI;IAOjB;;;;;;;OAOG;kBAJQ,MAAM,YACN,OAAO,YACP,OAAO,GAAG,kBAAkB,GAC1B,OAAO;IASpB;;;;;;;;;OASG;aALQ,MAAM,WACN,CAAC,GAAG,gBAAQ,KAAK,IAAI,YACrB,WAAW,GAAG,MAAM,YACpB,OAAO,GAAG,MAAM,GACd,MAAM,IAAI;IAcvB;;;;;;;;OAQG;cALQ,MAAM,WACN,CAAC,GAAG,gBAAQ,KAAK,IAAI,YACrB,WAAW,GAAG,MAAM,YACpB,OAAO,GAAG,MAAM,GACd,IAAI;;;;;;;;cAjEL,OAAO;;;;iBACP,OAAO;;;;eACP,OAAO"}
+{"version":3,"file":"Notify.d.ts","sourceRoot":"","sources":["../../../src/browser/lib/Notify.js"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;GAKG;AACH;IACE,iDAAiD;IACjD,MADW,MAAM,CACF;IAEf;;;;;;;OAOG;IACH,WALW,MAAM,YACN,OAAO,YACP,OAAO,GAAG,kBAAkB,GAC1B,IAAI,CAKhB;IAED;;;;;;;OAOG;IACH,cALW,MAAM,YACN,OAAO,YACP,OAAO,GAAG,kBAAkB,GAC1B,OAAO,CAOnB;IAED;;;;;;;;;OASG;IACH,SANW,MAAM,WACN,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,YACrB,WAAW,GAAG,MAAM,YACpB,OAAO,GAAG,MAAM,GACd,MAAM,IAAI,CAYtB;IAED;;;;;;;;OAQG;IACH,UANW,MAAM,WACN,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,YACrB,WAAW,GAAG,MAAM,YACpB,OAAO,GAAG,MAAM,GACd,IAAI,CAIhB;;CAWF;;;;;;;cAhFa,OAAO;;;;iBACP,OAAO;;;;eACP,OAAO"}

package/types/node/index.d.ts

@@ -13,7 +13,7 @@ export { default as FileObject } from "./lib/FileObject.js";
 export { default as FileSystem } from "./lib/FileSystem.js";
 export { default as Font } from "./lib/Font.js";
 export { default as Glog } from "./lib/Glog.js";
-export { default as Notify } from "./lib/Notify.js";
 export { default as Term } from "./lib/Term.js";
 export { default as Disposer, Disposer as DisposerClass } from "../browser/lib/Disposer.js";
+export { default as Notify, Notify as NotifyClass } from "./lib/Notify.js";
 //# sourceMappingURL=index.d.ts.map

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

@@ -15,6 +15,7 @@
  * console.log(fonts) // ["FiraCode", "JetBrainsMono", ...]
  */
 export default class Font {
+    static "__#private@#cache": Map<any, any>;
     /**
      * Finds all Nerd Fonts installed on the system.
      * Detects the current platform and uses platform-specific methods
@@ -91,10 +92,22 @@ export default class Font {
     /**
      * Identifies Nerd Fonts from a list of font file objects.
      *
-     * @param {Array<import("./FileObject.js").default>} fileObjects - Array of FileObject instances representing font files.
+     * @param {Array<FileObject>} fileObjects - Array of FileObject instances representing font files.
      * @returns {Array<string>} Sorted array of unique Nerd Font family names.
      * @private
      */
     private static "__#private@#identifyNerdFonts";
+    /**
+     * Gets spinner animation frames appropriate for the current font environment.
+     * Returns Unicode braille characters if Nerd Fonts are available,
+     * otherwise returns ASCII fallback characters.
+     *
+     * @returns {Promise<Array<string>>} Promise resolving to array of spinner frame characters.
+     * @example
+     * const frames = await Font.spinFrames
+     * // With Nerd Fonts: ["⠋", "⠙", "⠹", ...]
+     * // Without: ["|", "/", "-", "\\"]
+     */
+    static get spinFrames(): Promise<Array<string>>;
 }
 //# sourceMappingURL=Font.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"Font.d.ts","sourceRoot":"","sources":["../../../src/node/lib/Font.js"],"names":[],"mappings":"AAcA;;;;;;;;;;;;;;;GAeG;AACH;IACE;;;;;;;;;OASG;IACH,wBALa,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAiBlC;IAED;;;;;;;;OAQG;IACH,uBANa,OAAO,CAAC,OAAO,CAAC,CAQ5B;IAED;;;;;;;;OAQG;IACH,8BALa,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAUlC;IAED;;;;;;OAMG;IACH,yCAEC;IAED;;;;;;;OAOG;IACH,4CAEC;IAED;;;;;OAKG;IACH,kDAyBC;IAED;;;;;OAKG;IACH,8CAyBC;IAED;;;;;OAKG;IACH,gDAoBC;IAED,wEAAwE;IACxE,gCADW,KAAK,CAAC,MAAM,CAAC,CACoB;IAE5C,8EAA8E;IAC9E,qCADW,KAAK,CAAC,MAAM,CAAC,CAC0B;IAElD;;;;;;OAMG;IACH,+CAYC;CACF"}
+{"version":3,"file":"Font.d.ts","sourceRoot":"","sources":["../../../src/node/lib/Font.js"],"names":[],"mappings":"AAkBA;;;;;;;;;;;;;;;GAeG;AACH;IACE,0CAAyB;IAEzB;;;;;;;;;OASG;IACH,wBALa,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAoBlC;IAED;;;;;;;;OAQG;IACH,uBANa,OAAO,CAAC,OAAO,CAAC,CAQ5B;IAED;;;;;;;;OAQG;IACH,8BALa,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAUlC;IAED;;;;;;OAMG;IACH,yCAEC;IAED;;;;;;;OAOG;IACH,4CAEC;IAED;;;;;OAKG;IACH,kDAgCC;IAED;;;;;OAKG;IACH,8CAyBC;IAED;;;;;OAKG;IACH,gDAoBC;IAED,wEAAwE;IACxE,gCADW,KAAK,CAAC,MAAM,CAAC,CACoB;IAE5C,8EAA8E;IAC9E,qCADW,KAAK,CAAC,MAAM,CAAC,CAC0B;IAElD;;;;;;OAMG;IACH,+CAYC;IAED;;;;;;;;;;OAUG;IACH,yBANa,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAYlC;CACF"}

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

@@ -1,8 +1,15 @@
-declare const _default: {
+/**
+ * @typedef {object} NotifyEventOptions
+ * @property {boolean} [once] - Whether the listener should be invoked only once.
+ * @property {AbortSignal} [signal] - An AbortSignal to remove the listener.
+ */
+/**
+ * Notify class provides a thin wrapper around EventEmitter for centralized
+ * event handling in Node.js applications. Mirrors the browser Notify API.
+ */
+export class Notify {
     /** @type {string} Display name for debugging. */
     name: string;
-    /** @type {EventEmitter} Internal event emitter */
-    "__#private@#emitter": EventEmitter;
     /**
      * Emits an event without expecting a return value.
      *
@@ -49,7 +56,9 @@ declare const _default: {
      * @returns {void}
      */
     off(type: string, handler: (payload: unknown) => void, emitter?: EventEmitter): void;
-};
+    #private;
+}
+declare const _default: Notify;
 export default _default;
 export type NotifyEventOptions = {
     /**

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":";IAsBE,iDAAiD;UAAtC,MAAM;IAGjB,kDAAkD;2BAAvC,YAAY;IAGvB;;;;;;OAMG;eAHQ,MAAM,YACN,OAAO,GACL,IAAI;IAQjB;;;;;;;;OAQG;oBAHQ,MAAM,YACN,OAAO,GACL,OAAO,CAAC,IAAI,CAAC;IAQ1B;;;;;;;OAOG;kBAHQ,MAAM,YACN,OAAO,GACL,OAAO;IAUpB;;;;;;;;OAQG;aALQ,MAAM,WACN,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,YAC1B,YAAY,YACZ,kBAAkB,GAChB,MAAM,IAAI;IAevB;;;;;;;OAOG;cAJQ,MAAM,WACN,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,YAC1B,YAAY,GACV,IAAI;;;;;;;WAvFL,OAAO;;;;aACP,WAAW"}
+{"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,IAAI,CAMhB;IAED;;;;;;;;OAQG;IACH,gBAJW,MAAM,YACN,OAAO,GACL,OAAO,CAAC,IAAI,CAAC,CAMzB;IAED;;;;;;;OAOG;IACH,cAJW,MAAM,YACN,OAAO,GACL,OAAO,CAQnB;IAED;;;;;;;;OAQG;IACH,SANW,MAAM,WACN,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,YAC1B,YAAY,YACZ,kBAAkB,GAChB,MAAM,IAAI,CAatB;IAED;;;;;;;OAOG;IACH,UALW,MAAM,WACN,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,YAC1B,YAAY,GACV,IAAI,CAMhB;;CACF;;;;;;;WA9Fa,OAAO;;;;aACP,WAAW"}