@gesslar/toolkit 1.6.0 → 1.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gesslar/toolkit",
-  "version": "1.6.0",
+  "version": "1.8.0",
   "description": "Get in, bitches, we're going toolkitting.",
   "main": "./src/index.js",
   "type": "module",
@@ -66,14 +66,14 @@
     "ajv": "^8.17.1",
     "globby": "^16.0.0",
     "json5": "^2.2.3",
-    "yaml": "^2.8.1"
+    "yaml": "^2.8.2"
   },
   "devDependencies": {
     "@gesslar/uglier": "^0.0.5",
     "@stylistic/eslint-plugin": "^5.6.1",
     "@types/node": "^24.10.1",
-    "@typescript-eslint/eslint-plugin": "^8.48.0",
-    "@typescript-eslint/parser": "^8.48.0",
+    "@typescript-eslint/eslint-plugin": "^8.48.1",
+    "@typescript-eslint/parser": "^8.48.1",
     "eslint": "^9.39.1",
     "eslint-plugin-jsdoc": "^61.4.1",
     "globals": "^16.5.0"

package/src/index.js

@@ -18,6 +18,7 @@ export {default as DirectoryObject} from "./lib/DirectoryObject.js"
 export {default as FileObject} from "./lib/FileObject.js"
 export {default as FS} from "./lib/FS.js"
 export {default as Glog} from "./lib/Glog.js"
+export {default as Notify} from "./lib/Notify.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"

package/src/lib/DirectoryObject.js

@@ -355,4 +355,29 @@ export default class DirectoryObject extends FS {
 
     return await fs.rmdir(this.path)
   }
+
+  /**
+   * Checks if a file exists within this directory.
+   *
+   * @param {string} filename - The filename to check for
+   * @returns {Promise<boolean>} True if the file exists, false otherwise
+   */
+  async hasFile(filename) {
+    const file = new FileObject(filename, this)
+
+    return await file.exists
+  }
+
+  /**
+   * Checks if a subdirectory exists within this directory.
+   *
+   * @param {string} dirname - The directory name to check for
+   * @returns {Promise<boolean>} True if the directory exists, false otherwise
+   */
+  async hasDirectory(dirname) {
+    const resolved = FS.resolvePath(this.path, dirname)
+    const directory = new DirectoryObject(resolved)
+
+    return await directory.exists
+  }
 }

package/src/lib/Notify.js

@@ -0,0 +1,87 @@
+/**
+ * @file Notify.js
+ * @description Node.js event notification system using EventEmitter.
+ * Provides a centralized API for event emission and handling.
+ */
+
+import {EventEmitter} from "node:events"
+
+/**
+ * @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 default new class Notify {
+  /** @type {string} Display name for debugging. */
+  name = "Notify"
+
+  /** @type {EventEmitter} Internal event emitter */
+  #emitter = new EventEmitter()
+
+  /**
+   * Emits an event without expecting a return value.
+   *
+   * @param {string} type - Event name to dispatch.
+   * @param {unknown} [payload] - Data to send with the event.
+   * @returns {void}
+   */
+  emit(type, payload=undefined) {
+    this.#emitter.emit(type, payload)
+  }
+
+  /**
+   * Emits an event and returns the payload for simple request/response flows.
+   * Listeners can mutate the payload object to provide responses.
+   *
+   * @param {string} type - Event name to dispatch.
+   * @param {unknown} [payload] - Data to send with the event (will be returned).
+   * @returns {unknown} The payload after listeners have processed it.
+   */
+  request(type, payload={}) {
+    this.#emitter.emit(type, payload)
+
+    return payload
+  }
+
+  /**
+   * Registers a listener for the given event type.
+   *
+   * @param {string} type - Event name to listen for.
+   * @param {(payload: unknown) => void} handler - Listener callback.
+   * @param {EventEmitter} [emitter] - The EventEmitter to attach to. Default is internal emitter.
+   * @param {NotifyEventOptions} [options] - Options for the listener.
+   * @returns {() => void} Dispose function to unregister the handler.
+   */
+  on(type, handler, emitter=this.#emitter, 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.")
+
+    if(options?.once) {
+      emitter.once(type, handler, options)
+    } else {
+      emitter.on(type, handler, options)
+    }
+
+    return () => this.off(type, handler, emitter)
+  }
+
+  /**
+   * Removes a previously registered listener for the given event type.
+   *
+   * @param {string} type - Event name to remove.
+   * @param {(payload: unknown) => void} handler - Listener callback to detach.
+   * @param {EventEmitter} [emitter] - The EventEmitter from which to remove. Default is internal emitter.
+   * @returns {void}
+   */
+  off(type, handler, emitter=this.#emitter) {
+    emitter.off(type, handler)
+  }
+}

package/src/types/index.d.ts

@@ -11,6 +11,7 @@ export { default as DirectoryObject } from "./lib/DirectoryObject.js";
 export { default as FileObject } from "./lib/FileObject.js";
 export { default as FS } from "./lib/FS.js";
 export { default as Glog } from "./lib/Glog.js";
+export { default as Notify } from "./lib/Notify.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";

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

@@ -150,6 +150,20 @@ export default class DirectoryObject extends FS {
      * await dir.delete() // Only works if directory is empty
      */
     delete(): Promise<void>;
+    /**
+     * Checks if a file exists within this directory.
+     *
+     * @param {string} filename - The filename to check for
+     * @returns {Promise<boolean>} True if the file exists, false otherwise
+     */
+    hasFile(filename: string): Promise<boolean>;
+    /**
+     * Checks if a subdirectory exists within this directory.
+     *
+     * @param {string} dirname - The directory name to check for
+     * @returns {Promise<boolean>} True if the directory exists, false otherwise
+     */
+    hasDirectory(dirname: string): Promise<boolean>;
     /**
      * Custom inspect method for Node.js console.
      *

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

@@ -1 +1 @@
-{"version":3,"file":"DirectoryObject.d.ts","sourceRoot":"","sources":["../../lib/DirectoryObject.js"],"names":[],"mappings":"AAeA;;;;;;;;;;;;;GAaG;AACH;IA0BE;;;;OAIG;IACH,uBAFW,MAAM,EAsBhB;IAWD;;;;OAIG;IACH,UAFa,MAAM,CAalB;IAWD;;;;OAIG;IACH,cAFa,OAAO,CAAC,OAAO,CAAC,CAI5B;IAED;;;;OAIG;IACH,gBAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,YAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,WAFa,GAAG,CAIf;IAED;;;;OAIG;IACH,YAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,cAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,iBAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,WAFa,MAAM,CAIlB;IAED;;;;;;;OAOG;IACH,aALa,KAAK,CAAC,MAAM,CAAC,CAOzB;IAED;;;;OAIG;IACH,cAFa,OAAO,CAInB;IAED;;;;OAIG;IACH,mBAFa,OAAO,CAInB;IAiBD;;;;OAIG;IACH,QAFa,OAAO,CAAC;QAAC,KAAK,EAAE,KAAK,CAAC,UAAU,CAAC,CAAC;QAAC,WAAW,EAAE,KAAK,CAAC,eAAe,CAAC,CAAA;KAAC,CAAC,CAcpF;IAED;;;;;;;;;;;;OAYG;IACH,uBARW,MAAM,GACJ,OAAO,CAAC,IAAI,CAAC,CAqBzB;IA8BD;;;;;;;;;;;;;;;OAeG;IACH,cAZa,MAAM,CAclB;IAED;;;;;;;;;;;;;;OAcG;IACH,UARa,OAAO,CAAC,IAAI,CAAC,CAkBzB;IAvPD;;;;OAIG;IACH,yBAFa,MAAM,CAIlB;;CAiPF;eA1Vc,SAAS;oBAFN,UAAU;uBAGL,iBAAiB;iBAJvB,WAAW"}
+{"version":3,"file":"DirectoryObject.d.ts","sourceRoot":"","sources":["../../lib/DirectoryObject.js"],"names":[],"mappings":"AAeA;;;;;;;;;;;;;GAaG;AACH;IA0BE;;;;OAIG;IACH,uBAFW,MAAM,EAsBhB;IAWD;;;;OAIG;IACH,UAFa,MAAM,CAalB;IAWD;;;;OAIG;IACH,cAFa,OAAO,CAAC,OAAO,CAAC,CAI5B;IAED;;;;OAIG;IACH,gBAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,YAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,WAFa,GAAG,CAIf;IAED;;;;OAIG;IACH,YAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,cAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,iBAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,WAFa,MAAM,CAIlB;IAED;;;;;;;OAOG;IACH,aALa,KAAK,CAAC,MAAM,CAAC,CAOzB;IAED;;;;OAIG;IACH,cAFa,OAAO,CAInB;IAED;;;;OAIG;IACH,mBAFa,OAAO,CAInB;IAiBD;;;;OAIG;IACH,QAFa,OAAO,CAAC;QAAC,KAAK,EAAE,KAAK,CAAC,UAAU,CAAC,CAAC;QAAC,WAAW,EAAE,KAAK,CAAC,eAAe,CAAC,CAAA;KAAC,CAAC,CAcpF;IAED;;;;;;;;;;;;OAYG;IACH,uBARW,MAAM,GACJ,OAAO,CAAC,IAAI,CAAC,CAqBzB;IA8BD;;;;;;;;;;;;;;;OAeG;IACH,cAZa,MAAM,CAclB;IAED;;;;;;;;;;;;;;OAcG;IACH,UARa,OAAO,CAAC,IAAI,CAAC,CAkBzB;IAED;;;;;OAKG;IACH,kBAHW,MAAM,GACJ,OAAO,CAAC,OAAO,CAAC,CAM5B;IAED;;;;;OAKG;IACH,sBAHW,MAAM,GACJ,OAAO,CAAC,OAAO,CAAC,CAO5B;IAhRD;;;;OAIG;IACH,yBAFa,MAAM,CAIlB;;CA0QF;eAnXc,SAAS;oBAFN,UAAU;uBAGL,iBAAiB;iBAJvB,WAAW"}

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

@@ -0,0 +1,55 @@
+declare const _default: {
+    /** @type {string} Display name for debugging. */
+    name: string;
+    /** @type {EventEmitter} Internal event emitter */
+    "__#private@#emitter": EventEmitter;
+    /**
+     * Emits an event without expecting a return value.
+     *
+     * @param {string} type - Event name to dispatch.
+     * @param {unknown} [payload] - Data to send with the event.
+     * @returns {void}
+     */
+    emit(type: string, payload?: unknown): void;
+    /**
+     * Emits an event and returns the payload for simple request/response flows.
+     * Listeners can mutate the payload object to provide responses.
+     *
+     * @param {string} type - Event name to dispatch.
+     * @param {unknown} [payload] - Data to send with the event (will be returned).
+     * @returns {unknown} The payload after listeners have processed it.
+     */
+    request(type: string, payload?: unknown): unknown;
+    /**
+     * Registers a listener for the given event type.
+     *
+     * @param {string} type - Event name to listen for.
+     * @param {(payload: unknown) => void} handler - Listener callback.
+     * @param {EventEmitter} [emitter] - The EventEmitter to attach to. Default is internal emitter.
+     * @param {NotifyEventOptions} [options] - Options for the listener.
+     * @returns {() => void} Dispose function to unregister the handler.
+     */
+    on(type: string, handler: (payload: unknown) => void, emitter?: EventEmitter, options?: NotifyEventOptions): () => void;
+    /**
+     * Removes a previously registered listener for the given event type.
+     *
+     * @param {string} type - Event name to remove.
+     * @param {(payload: unknown) => void} handler - Listener callback to detach.
+     * @param {EventEmitter} [emitter] - The EventEmitter from which to remove. Default is internal emitter.
+     * @returns {void}
+     */
+    off(type: string, handler: (payload: unknown) => void, emitter?: EventEmitter): void;
+};
+export default _default;
+export type NotifyEventOptions = {
+    /**
+     * - Whether the listener should be invoked only once.
+     */
+    once?: boolean;
+    /**
+     * - An AbortSignal to remove the listener.
+     */
+    signal?: AbortSignal;
+};
+import { EventEmitter } from "node:events";
+//# sourceMappingURL=Notify.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Notify.d.ts","sourceRoot":"","sources":["../../lib/Notify.js"],"names":[],"mappings":";IAmBE,iDAAiD;UAAtC,MAAM;IAGjB,kDAAkD;2BAAvC,YAAY;IAGvB;;;;;;OAMG;eAHQ,MAAM,YACN,OAAO,GACL,IAAI;IAMjB;;;;;;;OAOG;kBAHQ,MAAM,YACN,OAAO,GACL,OAAO;IAQpB;;;;;;;;OAQG;aALQ,MAAM,WACN,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,YAC1B,YAAY,YACZ,kBAAkB,GAChB,MAAM,IAAI;IAkBvB;;;;;;;OAOG;cAJQ,MAAM,WACN,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,YAC1B,YAAY,GACV,IAAI;;;;;;;WAvEL,OAAO;;;;aACP,WAAW;;6BALE,aAAa"}