@gesslar/toolkit 1.0.4 → 1.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gesslar/toolkit",
-  "version": "1.0.4",
+  "version": "1.3.0",
   "description": "Get in, bitches, we're going toolkitting.",
   "main": "./src/index.js",
   "type": "module",

package/src/browser/index.js

@@ -3,7 +3,11 @@
 
 export {default as Collection} from "./lib/Collection.js"
 export {default as Data} from "./lib/Data.js"
+export {default as Disposable} from "./lib/Disposable.js"
+export {Disposable as DisposableClass} from "./lib/Disposable.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 {default as Sass} from "./lib/Sass.js"
 export {default as Tantrum} from "./lib/Tantrum.js"
 export {default as Type} from "./lib/TypeSpec.js"

package/src/browser/lib/Disposable.js

@@ -0,0 +1,75 @@
+/**
+ * Simple lifecycle helper that tracks disposer callbacks.
+ * Register any teardown functions and call dispose() to run them in reverse.
+ */
+export class Disposable {
+  #disposers = []
+  #disposed = false
+
+  /**
+   * Registers a disposer callback to be executed when disposed.
+   *
+   * @param {() => void} disposer - Cleanup callback.
+   * @returns {() => void} Function to unregister the disposer.
+   */
+  registerDisposer(disposer) {
+    if(this.#disposed || typeof disposer !== "function")
+      return () => {}
+
+    this.#disposers.push(disposer)
+
+    return () => this.#removeDisposer(disposer)
+  }
+
+  /**
+   * Runs all registered disposers in reverse order.
+   *
+   * @returns {void}
+   */
+  dispose() {
+    if(this.#disposed)
+      return
+
+    this.#disposed = true
+
+    const errors = []
+    this.#disposers.toReversed().forEach(disposer => {
+      try {
+        disposer()
+      } catch(error) {
+        errors.push(error)
+      }
+    })
+    this.#disposers.length = 0
+
+    if(errors.length > 0)
+      throw new AggregateError(errors, "Errors occurred during disposal.")
+  }
+
+  /**
+   * Whether disposal has run.
+   *
+   * @returns {boolean} True when dispose() has already been called.
+   */
+  get disposed() {
+    return this.#disposed
+  }
+
+  /**
+   * Read-only list of registered disposers.
+   *
+   * @returns {Array<() => void>} Snapshot of disposer callbacks.
+   */
+  get disposers() {
+    return Object.freeze([...this.#disposers])
+  }
+
+  #removeDisposer(disposer) {
+    const index = this.#disposers.indexOf(disposer)
+
+    if(index >= 0)
+      this.#disposers.splice(index, 1)
+  }
+}
+
+export default new Disposable()

package/src/browser/lib/HTML.js

@@ -1,7 +1,7 @@
 import DOMPurify from "./vendor/dompurify.esm.js"
 import Sass from "./Sass.js"
 
-export default class HTML {
+export class HTML {
   #domPurify
 
   /**
@@ -135,3 +135,5 @@ export default class HTML {
     throw Sass.new("DOMPurify sanitization is unavailable in this environment.")
   }
 }
+
+export default new HTML()

package/src/browser/lib/Notify.js

@@ -0,0 +1,89 @@
+/**
+ * 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 default new class Notify {
+  /** @type {string} Display name for debugging. */
+  name = "Notify"
+
+  /**
+   * Emits a CustomEvent without expecting a return value.
+   *
+   * @param {string} type - Event name to dispatch.
+   * @param {unknown} [payload] - Value assigned to `event.detail`.
+   * @param {boolean | NotifyEventOptions} [options] - CustomEvent options or boolean to set `bubbles`.
+   * @returns {void}
+   */
+  emit(type, payload=undefined, options=undefined) {
+    const evt = new CustomEvent(type, this.#buildEventInit(payload, options))
+    window.dispatchEvent(evt)
+  }
+
+  /**
+   * Emits a CustomEvent and returns the detail for simple request/response flows.
+   *
+   * @param {string} type - Event name to dispatch.
+   * @param {unknown} [payload] - Value assigned to `event.detail`.
+   * @param {boolean | NotifyEventOptions} [options] - CustomEvent options or boolean to set `bubbles`.
+   * @returns {unknown} The detail placed on the CustomEvent.
+   */
+  request(type, payload={}, options=undefined) {
+    const evt = new CustomEvent(type, this.#buildEventInit(payload, options))
+    window.dispatchEvent(evt)
+
+    return evt.detail
+  }
+
+  /**
+   * Registers a listener for the given event type on an HTMLElement (or
+   * window, if not specified).
+   *
+   * @param {string} type - Event name to listen for.
+   * @param {(evt: Notify) => void} handler - Listener callback.
+   * @param {HTMLElement | Window} [element] - The object to which to attach the handler. Default is window.
+   * @param {boolean | object} [options] - Options to pass to addEventListener.
+   * @returns {() => void} Dispose function to unregister the handler.
+   */
+  on(type, handler, element=window, options=undefined) {
+    if(!(typeof type === "string" && type))
+      throw new Error("No event 'type' specified to listen for.")
+
+    if(typeof handler !== "function")
+      throw new Error("No handler function specified.")
+
+    element.addEventListener(type, handler, options)
+
+    return () => this.off(type, handler, element, options)
+  }
+
+  /**
+   * Removes a previously registered listener for the given event type.
+   *
+   * @param {string} type - Event name to remove.
+   * @param {(evt: Notify) => void} handler - Listener callback to detach.
+   * @param {HTMLElement | Window} [element] - The object from which to remove the handler. Default is window.
+   * @param {boolean | object} [options] - Options to pass to removeEventListener.
+   * @returns {void}
+   */
+  off(type, handler, element=window, options=undefined) {
+    element.removeEventListener(type, handler, options)
+  }
+
+  #buildEventInit(detail, options) {
+    if(typeof options === "boolean")
+      return {detail, bubbles: options}
+
+    if(typeof options === "object" && options !== null)
+      return {detail, ...options}
+
+    return {detail}
+  }
+}

package/src/index.js

@@ -1,6 +1,8 @@
 // Browser-compatible utilities (pure JS)
 export {default as Collection} from "./browser/lib/Collection.js"
 export {default as Data} from "./browser/lib/Data.js"
+export {default as Disposable} from "./browser/lib/Disposable.js"
+export {Disposable as DisposableClass} from "./browser/lib/Disposable.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

@@ -1,9 +1,11 @@
 export { default as Collection } from "./lib/Collection.js";
 export { default as Data } from "./lib/Data.js";
-export { default as HTML } from "./lib/HTML.js";
+export { default as Notify } from "./lib/Notify.js";
 export { default as Sass } from "./lib/Sass.js";
 export { default as Tantrum } from "./lib/Tantrum.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";
+export { default as Disposable, Disposable as DisposableClass } from "./lib/Disposable.js";
+export { default as HTML, HTML as HTMLClass } from "./lib/HTML.js";
 //# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1,35 @@
+/**
+ * Simple lifecycle helper that tracks disposer callbacks.
+ * Register any teardown functions and call dispose() to run them in reverse.
+ */
+export class Disposable {
+    /**
+     * Registers a disposer callback to be executed when disposed.
+     *
+     * @param {() => void} disposer - Cleanup callback.
+     * @returns {() => void} Function to unregister the disposer.
+     */
+    registerDisposer(disposer: () => void): () => void;
+    /**
+     * Runs all registered disposers in reverse order.
+     *
+     * @returns {void}
+     */
+    dispose(): void;
+    /**
+     * Whether disposal has run.
+     *
+     * @returns {boolean} True when dispose() has already been called.
+     */
+    get disposed(): boolean;
+    /**
+     * Read-only list of registered disposers.
+     *
+     * @returns {Array<() => void>} Snapshot of disposer callbacks.
+     */
+    get disposers(): Array<() => void>;
+    #private;
+}
+declare const _default: Disposable;
+export default _default;
+//# sourceMappingURL=Disposable.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Disposable.d.ts","sourceRoot":"","sources":["../../../browser/lib/Disposable.js"],"names":[],"mappings":"AAAA;;;GAGG;AACH;IAIE;;;;;OAKG;IACH,2BAHW,MAAM,IAAI,GACR,MAAM,IAAI,CAStB;IAED;;;;OAIG;IACH,WAFa,IAAI,CAoBhB;IAED;;;;OAIG;IACH,gBAFa,OAAO,CAInB;IAED;;;;OAIG;IACH,iBAFa,KAAK,CAAC,MAAM,IAAI,CAAC,CAI7B;;CAQF"}

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

@@ -1,4 +1,4 @@
-export default class HTML {
+export class HTML {
     /**
      * Lightweight HTML helper utilities for browser contexts.
      *
@@ -35,4 +35,6 @@ export default class HTML {
     clearHTMLContent(element: Element): void;
     #private;
 }
+declare const _default: HTML;
+export default _default;
 //# sourceMappingURL=HTML.d.ts.map

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

@@ -0,0 +1,60 @@
+declare const _default: {
+    /** @type {string} Display name for debugging. */
+    name: string;
+    /**
+     * Emits a CustomEvent without expecting a return value.
+     *
+     * @param {string} type - Event name to dispatch.
+     * @param {unknown} [payload] - Value assigned to `event.detail`.
+     * @param {boolean | NotifyEventOptions} [options] - CustomEvent options or boolean to set `bubbles`.
+     * @returns {void}
+     */
+    emit(type: string, payload?: unknown, options?: boolean | NotifyEventOptions): void;
+    /**
+     * Emits a CustomEvent and returns the detail for simple request/response flows.
+     *
+     * @param {string} type - Event name to dispatch.
+     * @param {unknown} [payload] - Value assigned to `event.detail`.
+     * @param {boolean | NotifyEventOptions} [options] - CustomEvent options or boolean to set `bubbles`.
+     * @returns {unknown} The detail placed on the CustomEvent.
+     */
+    request(type: string, payload?: unknown, options?: boolean | NotifyEventOptions): unknown;
+    /**
+     * Registers a listener for the given event type on an HTMLElement (or
+     * window, if not specified).
+     *
+     * @param {string} type - Event name to listen for.
+     * @param {(evt: Notify) => void} handler - Listener callback.
+     * @param {HTMLElement | Window} [element] - The object to which to attach the handler. Default is window.
+     * @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;
+    /**
+     * Removes a previously registered listener for the given event type.
+     *
+     * @param {string} type - Event name to remove.
+     * @param {(evt: Notify) => void} handler - Listener callback to detach.
+     * @param {HTMLElement | Window} [element] - The object from which to remove the handler. Default is window.
+     * @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;
+};
+export default _default;
+export type NotifyEventOptions = {
+    /**
+     * - Whether the event bubbles up the DOM tree.
+     */
+    bubbles?: boolean;
+    /**
+     * - Whether the event can be canceled.
+     */
+    cancelable?: boolean;
+    /**
+     * - Whether the event can cross the shadow DOM boundary.
+     */
+    composed?: boolean;
+};
+//# sourceMappingURL=Notify.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Notify.d.ts","sourceRoot":"","sources":["../../../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"}

package/src/types/index.d.ts

@@ -14,4 +14,5 @@ export { default as Glog } from "./lib/Glog.js";
 export { default as Schemer } from "./lib/Schemer.js";
 export { default as Term } from "./lib/Term.js";
 export { default as Terms } from "./lib/Terms.js";
+export { default as Disposable, Disposable as DisposableClass } from "./browser/lib/Disposable.js";
 //# sourceMappingURL=index.d.ts.map

package/src/types/lib/Disposable.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Simple lifecycle helper that tracks disposer callbacks.
+ * Register any teardown functions and call dispose() to run them in reverse.
+ */
+export default class Disposable {
+    /**
+     * Registers a disposer callback to be executed when disposed.
+     *
+     * @param {() => void} disposer - Cleanup callback.
+     * @returns {() => void} Function to unregister the disposer.
+     */
+    registerDisposer(disposer: () => void): () => void;
+    /**
+     * Runs all registered disposers in reverse order.
+     *
+     * @returns {void}
+     */
+    dispose(): void;
+    /**
+     * Whether disposal has run.
+     *
+     * @returns {boolean} True when dispose() has already been called.
+     */
+    get disposed(): boolean;
+    /**
+     * Read-only list of registered disposers.
+     *
+     * @returns {Array<() => void>} Snapshot of disposer callbacks.
+     */
+    get disposers(): Array<() => void>;
+    #private;
+}
+//# sourceMappingURL=Disposable.d.ts.map

package/src/types/lib/Disposable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Disposable.d.ts","sourceRoot":"","sources":["../../lib/Disposable.js"],"names":[],"mappings":"AAAA;;;GAGG;AACH;IAIE;;;;;OAKG;IACH,2BAHW,MAAM,IAAI,GACR,MAAM,IAAI,CAStB;IAED;;;;OAIG;IACH,WAFa,IAAI,CAoBhB;IAED;;;;OAIG;IACH,gBAFa,OAAO,CAInB;IAED;;;;OAIG;IACH,iBAFa,KAAK,CAAC,MAAM,IAAI,CAAC,CAI7B;;CAQF"}