@gesslar/toolkit 1.0.4 → 1.2.0

package/package.json

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

package/src/browser/index.js

@@ -3,7 +3,9 @@
 
 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 {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"

package/src/browser/lib/Disposable.js

@@ -0,0 +1,73 @@
+/**
+ * Simple lifecycle helper that tracks disposer callbacks.
+ * Register any teardown functions and call dispose() to run them in reverse.
+ */
+export default 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)
+  }
+}

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,7 @@
 // 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 {default as Type} from "./browser/lib/TypeSpec.js"
 export {default as Valid} from "./lib/Valid.js"
 

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

@@ -1,6 +1,8 @@
 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 { 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";

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

@@ -0,0 +1,45 @@
+/**
+ * Base helper for UI classes that want centralized event lifecycles.
+ * Tracks listener disposer functions and registered DOM elements so subclasses
+ * can easily tear down on removal.
+ */
+export default class Base extends Disposable {
+    /**
+     * Assigns an HTMLElement to this object.
+     *
+     * @throws {Error} If there is already one assigned.
+     */
+    set element(element: HTMLElement);
+    /**
+     * Returns the HTMLElement associated with this object.
+     *
+     * @returns {HTMLElement} The HTMLElement associated with this object.
+     */
+    get element(): HTMLElement;
+    /**
+     * Cleans up registered disposers and emits a removal event for subscribers.
+     *
+     * @returns {void}
+     */
+    remove(): void;
+    /**
+     * Registers a Notify listener and tracks its disposer for later cleanup.
+     *
+     * @param {string} eventName - Event to subscribe to.
+     * @param {(evt: Event) => void} func - Handler to invoke.
+     * @param {HTMLElement | Window} [element] - Target element; defaults to window.
+     * @param {boolean | object} [options] - addEventListener options.
+     */
+    registerOn(eventName: string, func: (evt: Event) => void, element?: HTMLElement | Window, options?: boolean | object): void;
+    /**
+     * Resolves a DOM element and optionally registers listener functions on it.
+     * Each listener's return value is treated as a disposer and tracked.
+     *
+     * @param {string} elementId - Selector passed to querySelector.
+     * @param {((element: Element) => (void | (() => void))) | Array<(element: Element) => (void | (() => void))>} [listenerFunctions] - One or more listener initializers.
+     */
+    initialiseElement(elementId: string, listenerFunctions?: ((element: Element) => (void | (() => void))) | Array<(element: Element) => (void | (() => void))>): void;
+    #private;
+}
+import Disposable from "./Disposable.js";
+//# sourceMappingURL=Base.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Base.d.ts","sourceRoot":"","sources":["../../../browser/lib/Base.js"],"names":[],"mappings":"AAIA;;;;GAIG;AACH;IAcE;;;;OAIG;IACH,qBAWa,WAAW,EALvB;IAED;;;;OAIG;IACH,eAFa,WAAW,CAIvB;IAED;;;;OAIG;IACH,UAFa,IAAI,CAQhB;IAED;;;;;;;OAOG;IACH,sBALW,MAAM,QACN,CAAC,GAAG,EAAE,KAAK,KAAK,IAAI,YACpB,WAAW,GAAG,MAAM,YACpB,OAAO,GAAG,MAAM,QAM1B;IAED;;;;;;OAMG;IACH,6BAHW,MAAM,sBACN,CAAC,CAAC,OAAO,EAAE,OAAO,KAAK,CAAC,IAAI,GAAG,CAAC,MAAM,IAAI,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,OAAO,EAAE,OAAO,KAAK,CAAC,IAAI,GAAG,CAAC,MAAM,IAAI,CAAC,CAAC,CAAC,QA8B5G;;CACF;uBA5GsB,iBAAiB"}

package/src/types/browser/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/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/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

@@ -1,5 +1,6 @@
 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 { default as Type } from "./browser/lib/TypeSpec.js";
 export { default as Valid } from "./lib/Valid.js";
 export { default as Sass } from "./lib/Sass.js";

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