@gesslar/toolkit 3.14.2 → 3.16.1

package/package.json

@@ -5,7 +5,7 @@
     "name": "gesslar",
     "url": "https://gesslar.dev"
   },
-  "version": "3.14.2",
+  "version": "3.16.1",
   "license": "Unlicense",
   "homepage": "https://github.com/gesslar/toolkit#readme",
   "repository": {
@@ -52,7 +52,7 @@
     "node": ">=22"
   },
   "dependencies": {
-    "@gesslar/colours": "^0.7.1",
+    "@gesslar/colours": "^0.8.0",
     "ajv": "^8.17.1",
     "json5": "^2.2.3",
     "yaml": "^2.8.2"
@@ -68,7 +68,7 @@
     "lint": "eslint src/",
     "lint:fix": "eslint src/ --fix",
     "submit": "pnpm publish --access public --//registry.npmjs.org/:_authToken=\"${NPM_ACCESS_TOKEN}\"",
-    "update": "pnpm up --latest --recursive",
+    "update": "pnpm self-update && pnpx npm-check-updates -u && pnpm install",
     "test": "node --test tests/**/*.test.js",
     "test:coverage": "node --experimental-config-file=node.config.json --experimental-test-coverage --test-timeout=3000 --test tests/**/*.test.js",
     "test:node": "node --test tests/node/*.test.js",

package/src/node/lib/Glog.js

@@ -30,6 +30,7 @@ export const loggerColours = {
   info: "{F036}",    // Medium Spring Green
   warn: "{F214}",    // Orange1
   error: "{F196}",   // Red1
+  success: "{F046}", // Green (Bright Green)
   reset: "{/}",      // Reset
 }
 
@@ -107,36 +108,77 @@ class Glog {
 
   // === STATIC CONFIGURATION (for global usage) ===
 
+  /**
+   * Set the log prefix for global usage
+   *
+   * @param {string} prefix - Prefix to prepend to all log messages
+   * @returns {typeof Glog} The Glog class for chaining
+   */
   static setLogPrefix(prefix) {
     this.logPrefix = prefix
 
     return this
   }
 
+  /**
+   * Set the log level for global usage (0-5)
+   *
+   * @param {number} level - Log level (0 = off, 1-5 = increasing verbosity)
+   * @returns {typeof Glog} The Glog class for chaining
+   */
   static setLogLevel(level) {
     this.logLevel = Data.clamp(level, 0, 5)
 
     return this
   }
 
+  /**
+   * Set the logger name for global usage
+   *
+   * @param {string} name - Logger name to display in output
+   * @returns {typeof Glog} The Glog class for chaining
+   */
   static withName(name) {
     this.name = name
 
     return this
   }
 
+  /**
+   * Enable colors for global usage
+   * Merges with existing color configuration (can pass partial config)
+   * Shape: {debug?: string[], info?: string, warn?: string, error?: string, reset?: string}
+   * - debug: Array of 5 color codes [level0, level1, level2, level3, level4]
+   * - info, warn, error, reset: Single color code strings
+   * Uses @gesslar/colours format like "{F196}"
+   *
+   * @param {object} [colors=loggerColours] - Color configuration object (partial or complete)
+   * @returns {typeof Glog} The Glog class for chaining
+   */
   static withColors(colors = loggerColours) {
-    this.colors = colors
+    this.colors = Object.assign({}, this.colors ?? loggerColours, colors)
 
     return this
   }
 
+  /**
+   * Enable stack trace extraction for global usage
+   *
+   * @param {boolean} [enabled=true] - Whether to enable stack traces
+   * @returns {typeof Glog} The Glog class for chaining
+   */
   static withStackTrace(enabled = true) {
     this.stackTrace = enabled
 
     return this
   }
 
+  /**
+   * Use tag names as strings instead of symbols for global usage
+   *
+   * @param {boolean} [enabled=false] - Whether to use string tags
+   * @returns {typeof Glog} The Glog class for chaining
+   */
   static withTagsAsStrings(enabled = false) {
     this.tagsAsStrings = enabled
 
@@ -145,6 +187,12 @@ class Glog {
 
   // === FLUENT INSTANCE CREATION ===
 
+  /**
+   * Create a new Glog instance with fluent configuration
+   *
+   * @param {object} [options={}] - Initial options
+   * @returns {Glog} New Glog instance
+   */
   static create(options = {}) {
     return new this(options)
   }
@@ -167,8 +215,19 @@ class Glog {
     return this
   }
 
+  /**
+   * Enable colors for this logger instance
+   * Merges with existing color configuration (can pass partial config)
+   * Shape: {debug?: string[], info?: string, warn?: string, error?: string, reset?: string}
+   * - debug: Array of 5 color codes [level0, level1, level2, level3, level4]
+   * - info, warn, error, reset: Single color code strings
+   * Uses @gesslar/colours format like "{F196}"
+   *
+   * @param {object} [colors=loggerColours] - Color configuration object (partial or complete)
+   * @returns {Glog} This Glog instance for chaining
+   */
   withColors(colors = loggerColours) {
-    this.#colors = colors
+    this.#colors = Object.assign({}, this.#colors ?? loggerColours, colors)
 
     return this
   }
@@ -319,7 +378,12 @@ class Glog {
     this.#vscodeError?.(JSON.stringify(message))
   }
 
-  // Core execute method for simple usage
+  /**
+   * Core execute method for simple static usage
+   * Can be called as: Glog(data) or Glog(level, data)
+   *
+   * @param {...unknown} args - Arguments (optional level number, then data)
+   */
   static execute(...args) {
     // Use static properties for global calls
     let level, rest
@@ -383,16 +447,7 @@ class Glog {
    * @param {...unknown} args - Additional arguments
    */
   success(message, ...args) {
-    const name = this.#name || Glog.name || "Log"
-    const useStrings = this.#tagsAsStrings || Glog.tagsAsStrings
-    const showName = this.#displayName
-    const tag = useStrings ? "Success" : logSymbols.success
-    const namePrefix = showName ? `[${name}] ` : ""
-    const formatted = useStrings
-      ? c`${namePrefix}{success}${tag}{/}: ${message}`
-      : c`${namePrefix}{success}${tag}{/} ${message}`
-
-    Term.log(formatted, ...args)
+    Term.log(this.#compose("success", message), ...args)
   }
 
   /**
@@ -402,12 +457,14 @@ class Glog {
    * @param {...unknown} args - Additional arguments to log
    */
   static success(message, ...args) {
+    const colors = this.colors || loggerColours
     const name = this.name || "Log"
     const useStrings = this.tagsAsStrings
     const tag = useStrings ? "Success" : logSymbols.success
+    const colorCode = colors.success || "{F046}"
     const formatted = useStrings
-      ? c`[${name}] {success}${tag}{/}: ${message}`
-      : c`[${name}] {success}${tag}{/} ${message}`
+      ? c`[${name}] ${colorCode}${tag}{/}: ${message}`
+      : c`[${name}] ${colorCode}${tag}{/} ${message}`
 
     Term.log(formatted, ...args)
   }
@@ -662,7 +719,7 @@ class Glog {
 
 // Wrap in proxy for dual usage
 export default new Proxy(Glog, {
-  apply(target, thisArg, argumentsList) {
+  apply(target, _thisArg, argumentsList) {
     return target.execute(...argumentsList)
   },
   construct(target, argumentsList) {

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

@@ -3,6 +3,7 @@ export namespace loggerColours {
     let info: string;
     let warn: string;
     let error: string;
+    let success: string;
     let reset: string;
 }
 export namespace logSymbols {
@@ -14,7 +15,8 @@ export namespace logSymbols {
     export { warn_1 as warn };
     let error_1: string;
     export { error_1 as error };
-    export let success: string;
+    let success_1: string;
+    export { success_1 as success };
 }
 declare const _default: typeof Glog;
 export default _default;
@@ -25,20 +27,67 @@ declare class Glog {
     static stackTrace: boolean;
     static name: string;
     static tagsAsStrings: boolean;
-    static setLogPrefix(prefix: any): typeof Glog;
-    static setLogLevel(level: any): typeof Glog;
-    static withName(name: any): typeof Glog;
-    static withColors(colors?: {
-        debug: string[];
-        info: string;
-        warn: string;
-        error: string;
-        reset: string;
-    }): typeof Glog;
+    /**
+     * Set the log prefix for global usage
+     *
+     * @param {string} prefix - Prefix to prepend to all log messages
+     * @returns {typeof Glog} The Glog class for chaining
+     */
+    static setLogPrefix(prefix: string): typeof Glog;
+    /**
+     * Set the log level for global usage (0-5)
+     *
+     * @param {number} level - Log level (0 = off, 1-5 = increasing verbosity)
+     * @returns {typeof Glog} The Glog class for chaining
+     */
+    static setLogLevel(level: number): typeof Glog;
+    /**
+     * Set the logger name for global usage
+     *
+     * @param {string} name - Logger name to display in output
+     * @returns {typeof Glog} The Glog class for chaining
+     */
+    static withName(name: string): typeof Glog;
+    /**
+     * Enable colors for global usage
+     * Merges with existing color configuration (can pass partial config)
+     * Shape: {debug?: string[], info?: string, warn?: string, error?: string, reset?: string}
+     * - debug: Array of 5 color codes [level0, level1, level2, level3, level4]
+     * - info, warn, error, reset: Single color code strings
+     * Uses @gesslar/colours format like "{F196}"
+     *
+     * @param {object} [colors=loggerColours] - Color configuration object (partial or complete)
+     * @returns {typeof Glog} The Glog class for chaining
+     */
+    static withColors(colors?: object): typeof Glog;
+    /**
+     * Enable stack trace extraction for global usage
+     *
+     * @param {boolean} [enabled=true] - Whether to enable stack traces
+     * @returns {typeof Glog} The Glog class for chaining
+     */
     static withStackTrace(enabled?: boolean): typeof Glog;
+    /**
+     * Use tag names as strings instead of symbols for global usage
+     *
+     * @param {boolean} [enabled=false] - Whether to use string tags
+     * @returns {typeof Glog} The Glog class for chaining
+     */
     static withTagsAsStrings(enabled?: boolean): typeof Glog;
-    static create(options?: {}): Glog;
-    static execute(...args: any[]): void;
+    /**
+     * Create a new Glog instance with fluent configuration
+     *
+     * @param {object} [options={}] - Initial options
+     * @returns {Glog} New Glog instance
+     */
+    static create(options?: object): Glog;
+    /**
+     * Core execute method for simple static usage
+     * Can be called as: Glog(data) or Glog(level, data)
+     *
+     * @param {...unknown} args - Arguments (optional level number, then data)
+     */
+    static execute(...args: unknown[]): void;
     /**
      * Static version of colorize for global usage
      *
@@ -116,13 +165,18 @@ declare class Glog {
     withName(name: any): this;
     withLogLevel(level: any): this;
     withPrefix(prefix: any): this;
-    withColors(colors?: {
-        debug: string[];
-        info: string;
-        warn: string;
-        error: string;
-        reset: string;
-    }): this;
+    /**
+     * Enable colors for this logger instance
+     * Merges with existing color configuration (can pass partial config)
+     * Shape: {debug?: string[], info?: string, warn?: string, error?: string, reset?: string}
+     * - debug: Array of 5 color codes [level0, level1, level2, level3, level4]
+     * - info, warn, error, reset: Single color code strings
+     * Uses @gesslar/colours format like "{F196}"
+     *
+     * @param {object} [colors=loggerColours] - Color configuration object (partial or complete)
+     * @returns {Glog} This Glog instance for chaining
+     */
+    withColors(colors?: object): Glog;
     withStackTrace(enabled?: boolean): this;
     withTagsAsStrings(enabled?: boolean): this;
     noDisplayName(): this;

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

@@ -1 +1 @@
-{"version":3,"file":"Glog.d.ts","sourceRoot":"","sources":["../../../src/node/lib/Glog.js"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;AAsDA;IAEE,wBAAmB;IACnB,yBAAqB;IACrB,mBAAoB;IACpB,2BAAyB;IACzB,oBAAgB;IAChB,8BAA4B;IAgD5B,8CAIC;IAED,4CAIC;IAED,wCAIC;IAED;;;;;;oBAIC;IAED,sDAIC;IAED,yDAIC;IAID,kCAEC;IA6KD,qCAoBC;IAuBD;;;;;OAKG;IACH,yBAHW,KAAK,CAAC,MAAM,CAAC,aACV,OAAO,EAAA,QAOpB;IAqBD;;;;;OAKG;IACH,wBAHW,MAAM,WACH,OAAO,EAAA,QAWpB;IAED;;;;OAIG;IACH,sBAFc,OAAO,EAAA,QAOpB;IAED;;OAEG;IACH,wBAEC;IAED;;;;;OAKG;IACH,2BAHW,MAAM,UACN,MAAM,QAahB;IAED;;;;OAIG;IACH,0BAFW,MAAM,QAYhB;IAED;;;;OAIG;IACH,6BAFW,MAAM,QAWhB;IAyFD;;;;;;;;;OASG;IACH,mBAPW,MAAM,QAAQ,mBACd,MAAM,GAAG,MAAM,YAEvB;QAAgC,UAAU,GAAlC,KAAK,CAAC,MAAM,CAAC;QACK,UAAU,GAA5B,OAAO;QACW,aAAa,GAA/B,OAAO;KACjB,QAkBA;IAED;;;;;;OAMG;IACH,uBAJW,MAAM,aACN,MAAM,GACJ,IAAI,CAMhB;IA8BD;;;;OAIG;IACH,kBAFa,MAAM,CAclB;IAxkBD,0BAgBC;IAID,+BAUC;IA8CD,0BAIC;IAED,+BAIC;IAED,8BAIC;IAED;;;;;;aAIC;IAED,wCAIC;IAED,2CAIC;IAED,sBAIC;IAID,mBAEC;IAED,yBAEC;IAED;;;;;;MAQC;IA8BD,8BAGC;IAED,wBAQC;IA8BD;;;;;;;;;OASG;IACH,eALW,MAAM,UACN,MAAM,UACH,OAAO,EAAA,QAapB;IAED,wCAGC;IAED,wCAGC;IAED,yCAGC;IA0BD,8BAEC;IAID;;;;;;OAMG;IACH,kBAJW,KAAK,CAAC,MAAM,CAAC,aACV,OAAO,EAAA,QAQpB;IAeD;;;;;OAKG;IACH,iBAHW,MAAM,WACH,OAAO,EAAA,QAapB;IA0FD;;;;OAIG;IACH,eAFc,OAAO,EAAA,QASpB;IAED;;OAEG;IACH,iBAEC;IAED;;;;;OAKG;IACH,oBAHW,MAAM,UACN,MAAM,QAIhB;IAED;;;;OAIG;IACH,mBAFW,MAAM,QAIhB;IAED;;;;OAIG;IACH,sBAFW,MAAM,QAahB;IAED;;;;;;;;;OASG;IACH,YAPW,MAAM,QAAQ,mBACd,MAAM,GAAG,MAAM,YAEvB;QAAgC,UAAU,GAAlC,KAAK,CAAC,MAAM,CAAC;QACK,UAAU,GAA5B,OAAO;QACW,aAAa,GAA/B,OAAO;KACjB,QAkBA;IA4CD;;;;OAIG;IACH,mBAEC;IAED;;;;OAIG;IACH,WAFa,MAAM,CAclB;;CAoBF"}
+{"version":3,"file":"Glog.d.ts","sourceRoot":"","sources":["../../../src/node/lib/Glog.js"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;AAuDA;IAEE,wBAAmB;IACnB,yBAAqB;IACrB,mBAAoB;IACpB,2BAAyB;IACzB,oBAAgB;IAChB,8BAA4B;IAgD5B;;;;;OAKG;IACH,4BAHW,MAAM,GACJ,OAAO,IAAI,CAMvB;IAED;;;;;OAKG;IACH,0BAHW,MAAM,GACJ,OAAO,IAAI,CAMvB;IAED;;;;;OAKG;IACH,sBAHW,MAAM,GACJ,OAAO,IAAI,CAMvB;IAED;;;;;;;;;;OAUG;IACH,2BAHW,MAAM,GACJ,OAAO,IAAI,CAMvB;IAED;;;;;OAKG;IACH,gCAHW,OAAO,GACL,OAAO,IAAI,CAMvB;IAED;;;;;OAKG;IACH,mCAHW,OAAO,GACL,OAAO,IAAI,CAMvB;IAID;;;;;OAKG;IACH,wBAHW,MAAM,GACJ,IAAI,CAIhB;IAuLD;;;;;OAKG;IACH,wBAFc,OAAO,EAAA,QAsBpB;IAuBD;;;;;OAKG;IACH,yBAHW,KAAK,CAAC,MAAM,CAAC,aACV,OAAO,EAAA,QAOpB;IAYD;;;;;OAKG;IACH,wBAHW,MAAM,WACH,OAAO,EAAA,QAapB;IAED;;;;OAIG;IACH,sBAFc,OAAO,EAAA,QAOpB;IAED;;OAEG;IACH,wBAEC;IAED;;;;;OAKG;IACH,2BAHW,MAAM,UACN,MAAM,QAahB;IAED;;;;OAIG;IACH,0BAFW,MAAM,QAYhB;IAED;;;;OAIG;IACH,6BAFW,MAAM,QAWhB;IAyFD;;;;;;;;;OASG;IACH,mBAPW,MAAM,QAAQ,mBACd,MAAM,GAAG,MAAM,YAEvB;QAAgC,UAAU,GAAlC,KAAK,CAAC,MAAM,CAAC;QACK,UAAU,GAA5B,OAAO;QACW,aAAa,GAA/B,OAAO;KACjB,QAkBA;IAED;;;;;;OAMG;IACH,uBAJW,MAAM,aACN,MAAM,GACJ,IAAI,CAMhB;IA8BD;;;;OAIG;IACH,kBAFa,MAAM,CAclB;IAhoBD,0BAgBC;IAID,+BAUC;IA6FD,0BAIC;IAED,+BAIC;IAED,8BAIC;IAED;;;;;;;;;;OAUG;IACH,oBAHW,MAAM,GACJ,IAAI,CAMhB;IAED,wCAIC;IAED,2CAIC;IAED,sBAIC;IAID,mBAEC;IAED,yBAEC;IAED;;;;;;MAQC;IA8BD,8BAGC;IAED,wBAQC;IA8BD;;;;;;;;;OASG;IACH,eALW,MAAM,UACN,MAAM,UACH,OAAO,EAAA,QAapB;IAED,wCAGC;IAED,wCAGC;IAED,yCAGC;IA+BD,8BAEC;IAID;;;;;;OAMG;IACH,kBAJW,KAAK,CAAC,MAAM,CAAC,aACV,OAAO,EAAA,QAQpB;IAeD;;;;;OAKG;IACH,iBAHW,MAAM,WACH,OAAO,EAAA,QAIpB;IA4FD;;;;OAIG;IACH,eAFc,OAAO,EAAA,QASpB;IAED;;OAEG;IACH,iBAEC;IAED;;;;;OAKG;IACH,oBAHW,MAAM,UACN,MAAM,QAIhB;IAED;;;;OAIG;IACH,mBAFW,MAAM,QAIhB;IAED;;;;OAIG;IACH,sBAFW,MAAM,QAahB;IAED;;;;;;;;;OASG;IACH,YAPW,MAAM,QAAQ,mBACd,MAAM,GAAG,MAAM,YAEvB;QAAgC,UAAU,GAAlC,KAAK,CAAC,MAAM,CAAC;QACK,UAAU,GAA5B,OAAO;QACW,aAAa,GAA/B,OAAO;KACjB,QAkBA;IA4CD;;;;OAIG;IACH,mBAEC;IAED;;;;OAIG;IACH,WAFa,MAAM,CAclB;;CAoBF"}