@epigraph/epigraph-std-lib 1.1.0 → 2.0.0

package/dist/EpigraphLogger/epigraph-logger.d.ts

@@ -1,46 +1,130 @@
-export type ILoggerDetails = string | boolean | object | Array<string> | Array<boolean> | HTMLElement;
-export interface LoggerLevel {
+interface LoggerMode {
     name: string;
     allows: Array<string>;
 }
-export interface LoggerLevels {
-    release: LoggerLevel;
-    staging: LoggerLevel;
-    dev: LoggerLevel;
+interface LoggerModes {
+    release: LoggerMode;
+    staging: LoggerMode;
+    dev: LoggerMode;
 }
-export declare enum LoggerLevelNames {
-    release = "release",
-    staging = "staging",
-    dev = "dev"
+export declare enum LoggerModeNames {
+    Release = "release",
+    Staging = "staging",
+    Dev = "dev"
 }
-export declare enum Severities {
-    log = "log",
-    warn = "warn",
-    error = "error"
+export declare enum LogTypes {
+    Info = "info",
+    Warn = "warn",
+    Error = "error"
 }
 /**
- * Temporary class to use instead of console.log so it's
- * easy to migrate int he future.
+ * Epigraph's Logger class that provides various modes and functionalities to easily
+ * manage logging within our solutions in a consistent manner.
+ *
+ * Some common terminologies are:
+ * Mode: A logger's mode defines what log types would be automatically executed and
+ *       what would be ignored.
  */
 declare class EpigraphLogger {
     context: string;
-    private _levels;
-    private _level;
+    private _allModes;
+    private _currentMode;
     /**
      * @param {string} [context="EPIGRAPH-LOGGER"] Used to categorise each message within
      *                the console.
      * @example,CORE, UI
      */
     constructor(context: string);
-    get levels(): LoggerLevels;
-    setLevel(newValue: LoggerLevelNames): void;
-    private _isSeverityAllowedInCurrentLevel;
-    log(title?: string, details?: ILoggerDetails): void;
-    warn(title?: string, details?: ILoggerDetails): void;
-    error(title?: string, details?: ILoggerDetails): void;
-    table(title?: string, details?: ILoggerDetails, severity?: Severities): void;
-    group(title: string, severity?: Severities): void;
-    groupCollapsed(title: string, severity?: Severities): void;
+    get modes(): LoggerModes;
+    /**
+     *
+     * @param {LoggerModeNames} newValue Sets the logger mode of the current instance.
+     */
+    setCurrentMode(newValue: LoggerModeNames): void;
+    private _isLogTypeAllowedInCurrentMode;
+    /**
+     * A log type that doesn't necessarily need to be looked at by the end user.
+     * This can be any generic log that would be ignored in most logger modes except verbose.
+     *
+     * @param {string} title A short title for this log.
+     * @param {any} details Any optional detail that would be shown if this log was expanded in the console.
+     * @param {string | undefined} contextOverride Allows the user to specify where this log
+     * was recorded from. For eg. Core and Ui can pass in different values for this
+     * paramater to make it easy to debug. If not provided, the default context would be used
+     * that was provided at the time of initialisation of this class.
+     */
+    info(title?: string, details?: any, contextOverride?: string | undefined): void;
+    /**
+     * A warning log type that let's the user know that some action that could be dangerous was just
+     * performed and might need attention.
+     *
+     * @param {string} title A short title for this log.
+     * @param {any} details Any optional detail that would be shown if this log was expanded in the console.
+     * @param {string | undefined} contextOverride Allows the user to specify where this log
+     * was recorded from. For eg. Core and Ui can pass in different values for this
+     * paramater to make it easy to debug. If not provided, the default context would be used
+     * that was provided at the time of initialisation of this class.
+     */
+    warn(title?: string, details?: any, contextOverride?: string | undefined): void;
+    /**
+     * A critical error log type that let's the user know that some action that was unexpected and required immediate attention.
+     *
+     * @param {string} title A short title for this log.
+     * @param {any} details Any optional detail that would be shown if this log was expanded in the console.
+     * @param {string | undefined} contextOverride Allows the user to specify where this log
+     * was recorded from. For eg. Core and Ui can pass in different values for this
+     * paramater to make it easy to debug. If not provided, the default context would be used
+     * that was provided at the time of initialisation of this class.
+     */
+    error(title?: string, details?: any, contextOverride?: string | undefined): void;
+    /**
+     * A table log type that can show an object in an organised manner within the console.
+     * This is primarily for the visual purposes and doesn't provide any additional functionality
+     * that other log types cannot provide.
+     *
+     * @param {string} title A short title for this log.
+     * @param {any} details Any optional detail that would be shown if this log was expanded in the console.
+     * @param {string | undefined} contextOverride Allows the user to specify where this log
+     * was recorded from. For eg. Core and Ui can pass in different values for this
+     * paramater to make it easy to debug. If not provided, the default context would be used
+     * that was provided at the time of initialisation of this class.
+     * @param {LogTypes} logType A
+     */
+    table(title?: string, details?: any, contextOverride?: string | undefined, logType?: LogTypes): void;
+    /**
+     * Begins an expanded group with the browser's console window.
+     * NOTE: Please remember to close this group once done using EpigraphLogger.groupEnd();
+     *
+     * @param {string} title A short title for this group.
+     * @param {string | undefined} contextOverride Allows the user to specify where this log
+     * was recorded from. For eg. Core and Ui can pass in different values for this
+     * paramater to make it easy to debug. If not provided, the default context would be used
+     * that was provided at the time of initialisation of this class.
+     * @param {LogTypes} logType A group can implictly of any log type, by default it is of type
+     * info but this parameter allows the user to override this.
+     * @returns {void}
+     */
+    group(title: string, contextOverride?: string | undefined, logType?: LogTypes): void;
+    /**
+     * Begins a collapsed group with the browser's console window.
+     * NOTE: Please remember to close this group once done using EpigraphLogger.groupEnd();
+     *
+     * @param {string} title A short title for this group.
+     * @param {string | undefined} contextOverride Allows the user to specify where this log
+     * was recorded from. For eg. Core and Ui can pass in different values for this
+     * paramater to make it easy to debug. If not provided, the default context would be used
+     * that was provided at the time of initialisation of this class.
+     * @param {LogTypes} logType A group can implictly of any log type, by default it is of type
+     * info but this parameter allows the user to override this.
+     * @returns {void}
+     */
+    groupCollapsed(title: string, contextOverride?: string | undefined, logType?: LogTypes): void;
+    /**
+     * Similar to the console.groupEnd(). Useful for ending either a group or
+     * groupCollapse that was initialised by this logger.
+     *
+     * @returns {void}
+     */
     groupEnd(): void;
 }
 export { EpigraphLogger };

package/dist/epigraph-std-lib.js

@@ -31615,7 +31615,7 @@ const KR = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Object.defineProperty({
   ModelViewerElement: dv,
   NearestFilter: pt
 }, Symbol.toStringTag, { value: "Module" }));
-var GB = /* @__PURE__ */ ((a) => (a.release = "release", a.staging = "staging", a.dev = "dev", a))(GB || {}), zB = /* @__PURE__ */ ((a) => (a.log = "log", a.warn = "warn", a.error = "error", a))(zB || {});
+var GB = /* @__PURE__ */ ((a) => (a.Release = "release", a.Staging = "staging", a.Dev = "dev", a))(GB || {}), zB = /* @__PURE__ */ ((a) => (a.Info = "info", a.Warn = "warn", a.Error = "error", a))(zB || {});
 class jR {
   /**
    * @param {string} [context="EPIGRAPH-LOGGER"] Used to categorise each message within
@@ -31624,61 +31624,157 @@ class jR {
    */
   constructor(e) {
     Ca(this, "context", "EPIGRAPH-LOGGER");
-    Ca(this, "_levels", {
+    Ca(this, "_allModes", {
       release: { name: "release", allows: ["error"] },
       staging: { name: "staging", allows: ["warn", "error"] },
       dev: { name: "dev", allows: ["log", "warn", "error"] }
     });
-    Ca(this, "_level", "release");
+    Ca(this, "_currentMode", "release");
     e && (this.context = e.toLocaleUpperCase());
   }
-  get levels() {
-    return this._levels;
+  get modes() {
+    return this._allModes;
   }
-  setLevel(e) {
-    if (!Object.keys(this._levels).includes(e)) {
-      console.warn(`"${e}": is not a valid logger level`);
+  /**
+   *
+   * @param {LoggerModeNames} newValue Sets the logger mode of the current instance.
+   */
+  setCurrentMode(e) {
+    if (!Object.keys(this._allModes).includes(e)) {
+      console.warn(`"${e}": is not a valid logger mode`);
       return;
     }
-    this._level = e;
+    this._currentMode = e;
   }
-  _isSeverityAllowedInCurrentLevel(e) {
-    return this._levels[this._level].allows.includes(e);
+  _isLogTypeAllowedInCurrentMode(e) {
+    return this._allModes[this._currentMode].allows.includes(e);
   }
-  log(e = "", t = "") {
-    this._isSeverityAllowedInCurrentLevel(
-      "log"
-      /* log */
-    ) && (console.groupCollapsed(`[${this.context}]: ${e}`), console.log(t), console.groupCollapsed("Traceback..."), console.trace(), console.groupEnd(), console.groupEnd());
+  /**
+   * A log type that doesn't necessarily need to be looked at by the end user.
+   * This can be any generic log that would be ignored in most logger modes except verbose.
+   *
+   * @param {string} title A short title for this log.
+   * @param {any} details Any optional detail that would be shown if this log was expanded in the console.
+   * @param {string | undefined} contextOverride Allows the user to specify where this log
+   * was recorded from. For eg. Core and Ui can pass in different values for this
+   * paramater to make it easy to debug. If not provided, the default context would be used
+   * that was provided at the time of initialisation of this class.
+   */
+  info(e = "", t = "", n = void 0) {
+    if (!this._isLogTypeAllowedInCurrentMode(
+      "info"
+      /* Info */
+    ))
+      return;
+    const i = n || this.context;
+    console.groupCollapsed(`[${i}]: ${e}`), console.log(t), console.groupCollapsed("Traceback..."), console.trace(), console.groupEnd(), console.groupEnd();
   }
-  warn(e = "", t = "") {
-    this._isSeverityAllowedInCurrentLevel(
+  /**
+   * A warning log type that let's the user know that some action that could be dangerous was just
+   * performed and might need attention.
+   *
+   * @param {string} title A short title for this log.
+   * @param {any} details Any optional detail that would be shown if this log was expanded in the console.
+   * @param {string | undefined} contextOverride Allows the user to specify where this log
+   * was recorded from. For eg. Core and Ui can pass in different values for this
+   * paramater to make it easy to debug. If not provided, the default context would be used
+   * that was provided at the time of initialisation of this class.
+   */
+  warn(e = "", t = "", n = void 0) {
+    if (!this._isLogTypeAllowedInCurrentMode(
       "warn"
-      /* warn */
-    ) && (console.groupCollapsed(
-      `%c[${this.context}]: ${e}`,
-      "color: orange;"
-    ), console.warn(t), console.groupCollapsed("Traceback..."), console.trace(), console.groupEnd(), console.groupEnd());
-  }
-  error(e = "", t = "") {
-    this._isSeverityAllowedInCurrentLevel(
+      /* Warn */
+    ))
+      return;
+    const i = n || this.context;
+    console.groupCollapsed(`%c[${i}]: ${e}`, "color: orange;"), console.warn(t), console.groupCollapsed("Traceback..."), console.trace(), console.groupEnd(), console.groupEnd();
+  }
+  /**
+   * A critical error log type that let's the user know that some action that was unexpected and required immediate attention.
+   *
+   * @param {string} title A short title for this log.
+   * @param {any} details Any optional detail that would be shown if this log was expanded in the console.
+   * @param {string | undefined} contextOverride Allows the user to specify where this log
+   * was recorded from. For eg. Core and Ui can pass in different values for this
+   * paramater to make it easy to debug. If not provided, the default context would be used
+   * that was provided at the time of initialisation of this class.
+   */
+  error(e = "", t = "", n = void 0) {
+    if (!this._isLogTypeAllowedInCurrentMode(
       "error"
-      /* error */
-    ) && (console.groupCollapsed(`%c[${this.context}]: ${e}`, "color: red;"), console.error(t), console.groupCollapsed("Traceback..."), console.trace(), console.groupEnd(), console.groupEnd());
+      /* Error */
+    ))
+      return;
+    const i = n || this.context;
+    console.groupCollapsed(`%c[${i}]: ${e}`, "color: red;"), console.error(t), console.groupCollapsed("Traceback..."), console.trace(), console.groupEnd(), console.groupEnd();
   }
-  table(e = "", t = {}, n) {
-    n || (n = "log"), this._isSeverityAllowedInCurrentLevel(n) && (console.groupCollapsed(`[${this.context}]: ${e}`), console.table(t), console.groupCollapsed("Traceback..."), console.trace(), console.groupEnd(), console.groupEnd());
+  /**
+   * A table log type that can show an object in an organised manner within the console.
+   * This is primarily for the visual purposes and doesn't provide any additional functionality
+   * that other log types cannot provide.
+   *
+   * @param {string} title A short title for this log.
+   * @param {any} details Any optional detail that would be shown if this log was expanded in the console.
+   * @param {string | undefined} contextOverride Allows the user to specify where this log
+   * was recorded from. For eg. Core and Ui can pass in different values for this
+   * paramater to make it easy to debug. If not provided, the default context would be used
+   * that was provided at the time of initialisation of this class.
+   * @param {LogTypes} logType A
+   */
+  table(e = "", t = {}, n = void 0, i = "info") {
+    if (!this._isLogTypeAllowedInCurrentMode(i))
+      return;
+    const s = n || this.context;
+    console.groupCollapsed(`[${s}]: ${e}`), console.table(t), console.groupCollapsed("Traceback..."), console.trace(), console.groupEnd(), console.groupEnd();
   }
-  group(e, t) {
-    t || (t = "log"), this._isSeverityAllowedInCurrentLevel(t) && console.group(`%c ${this.context} GROUP`, e);
+  /**
+   * Begins an expanded group with the browser's console window.
+   * NOTE: Please remember to close this group once done using EpigraphLogger.groupEnd();
+   *
+   * @param {string} title A short title for this group.
+   * @param {string | undefined} contextOverride Allows the user to specify where this log
+   * was recorded from. For eg. Core and Ui can pass in different values for this
+   * paramater to make it easy to debug. If not provided, the default context would be used
+   * that was provided at the time of initialisation of this class.
+   * @param {LogTypes} logType A group can implictly of any log type, by default it is of type
+   * info but this parameter allows the user to override this.
+   * @returns {void}
+   */
+  group(e, t = void 0, n = "info") {
+    if (!this._isLogTypeAllowedInCurrentMode(n))
+      return;
+    const i = t || this.context;
+    console.group(`%c ${i} GROUP`, e);
   }
-  groupCollapsed(e, t) {
-    t || (t = "log"), this._isSeverityAllowedInCurrentLevel(t) && console.groupCollapsed(`%c ${this.context} GROUP`, e);
+  /**
+   * Begins a collapsed group with the browser's console window.
+   * NOTE: Please remember to close this group once done using EpigraphLogger.groupEnd();
+   *
+   * @param {string} title A short title for this group.
+   * @param {string | undefined} contextOverride Allows the user to specify where this log
+   * was recorded from. For eg. Core and Ui can pass in different values for this
+   * paramater to make it easy to debug. If not provided, the default context would be used
+   * that was provided at the time of initialisation of this class.
+   * @param {LogTypes} logType A group can implictly of any log type, by default it is of type
+   * info but this parameter allows the user to override this.
+   * @returns {void}
+   */
+  groupCollapsed(e, t = void 0, n = "info") {
+    if (!this._isLogTypeAllowedInCurrentMode(n))
+      return;
+    const i = t || this.context;
+    console.groupCollapsed(`%c ${i} GROUP`, e);
   }
+  /**
+   * Similar to the console.groupEnd(). Useful for ending either a group or
+   * groupCollapse that was initialised by this logger.
+   *
+   * @returns {void}
+   */
   groupEnd() {
-    this._isSeverityAllowedInCurrentLevel(
-      "log"
-      /* log */
+    this._isLogTypeAllowedInCurrentMode(
+      "info"
+      /* Info */
     ) && (console.log("----------------------------------"), console.groupEnd());
   }
 }
@@ -33085,7 +33181,8 @@ export {
   Yt as Loader,
   ha as LoaderUtils,
   j0 as LoadingManager,
-  GB as LoggerLevelNames,
+  zB as LogTypes,
+  GB as LoggerModeNames,
   g0 as LoopOnce,
   Qd as LoopPingPong,
   Fd as LoopRepeat,
@@ -33215,7 +33312,6 @@ export {
   Wf as SIGNED_RED_RGTC1_Format,
   Bn as SRGBColorSpace,
   wi as Scene,
-  zB as Severities,
   Ge as ShaderChunk,
   $n as ShaderLib,
   En as ShaderMaterial,

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@epigraph/epigraph-std-lib",
-    "version": "1.1.0",
+    "version": "2.0.0",
     "type": "module",
     "files": [
         "/dist"