mentie 0.3.5 → 0.3.7

package/README.md

@@ -4,6 +4,15 @@ Mentor's favorite helpers.
 
 ## Logging
 
-Cross environment logging depends on the `LOGLEVEL` variable. In web it is set with `?loglevel=`, in others with an environment variable `LOGLEVEL`.
+Logging options:
 
-Valid values: `info`, `warn`, `error`.
+- `LOGLEVEL`/`?loglevel=`: Set the log level. Options:
+    - `info`: Keeps `log.info()`, `log.warn()`, `log.error()` visible
+    - `warn`: Keeps `log.warn()`, `log.error()` visible
+    - `error`: Keeps only `log.error()` visible
+    - Note that `log.warn()` adds a ⚠️ emoji and `log.error()` adds a 🚨 emoji.
+    - Note that `log()` only logs in development mode (detected in environment or through `NODE_ENV`/`?debug=true`).
+- `LOG_ANNOTATIONS`/`?log_annotations`: Comma separates list of annotations. Options:
+    - `timestamp`: Add `Date.now()` to the log message.
+    - `isotime`: Add `new Date().toISOString()` to the log message.
+    - `stringify`: Stringifies log messages (useful in environments where variables references might we deleted before you inspect them)

package/modules/environment.js

@@ -77,6 +77,24 @@ env.node_loglevel = () => env.is_node() && process.env?.LOG_LEVEL
  */
 env.loglevel = () => env.web_loglevel() || env.node_loglevel() || env.dev() ? 'info' : 'error'
 
+/**
+ * Retrieves the log annotations set via URL parameters in a web environment.
+ * @returns {Array<string>|boolean} An array of log annotations from URL parameters, or false if not set.
+ */
+env.web_log_annotations = () => env.is_web() && new URLSearchParams( location?.search ).get( 'log_annotations' ).split( ',' ).filter( Boolean ).map( annotation => annotation.trim() )
+
+/**
+ * Retrieves the log annotations set via environment variables in a Node.js environment.
+ * @returns {Array<string>|boolean} An array of log annotations from environment variables, or false if not set.
+ */
+env.node_log_annotations = () => env.is_node() && process.env?.LOG_ANNOTATIONS?.split( ',' ).filter( Boolean ).map( annotation => annotation.trim() )
+
+/**
+ * Retrieves the effective log annotations based on the environment. Defaults to an empty array if not set.
+ * @returns {Array<string>|boolean} An array of log annotations, or false if not set.
+ */
+env.log_annotations = () => env.web_log_annotations() || env.node_log_annotations() || []
+
 /**
  * Checks if the code is running in a web browser and the platform is Mac.
  * @returns {boolean} True if the code is running in a web browser and the platform is Mac, otherwise false.

package/modules/logging.js

@@ -32,9 +32,8 @@ const add_trace = messages => {
         // Do nothing if we are not in a browser
         if( typeof window === 'undefined' ) return messages
 
-        // If there is no trace=true in the url, do nothing
-        if( !window.location?.search?.includes?.( 'trace=true' ) ) return messages
-
+        // If there is no trace=true in the url, return
+        if( !new URLSearchParams( location?.search ).get( 'trace' ) ) return messages
 
         // Get the stack trace
         let { stack } = new Error()
@@ -65,9 +64,14 @@ const add_trace = messages => {
  */
 const annotate_messages = messages => {
 
+    // Add annotations if requested
+    const annotations = env.log_annotations()
+    if( annotations.includes( 'timestamp' ) ) messages = [ Date.now(), ...messages ]
+    if( annotations.includes( 'isotime' ) ) messages = [ new Date().toISOString(), ...messages ]
+
 
     // If we are running in cypress, stringify the messages because they become unavailable in the console
-    if( env.is_cypress() ) {
+    if( env.is_cypress() || annotations.includes( 'stringify' ) ) {
 
         try {
             messages = messages.map( message => stringify( message, null, 2 ) )
@@ -76,6 +80,7 @@ const annotate_messages = messages => {
         }
     }
 
+
     // Annotate the provided messages
     messages = add_trace( messages )
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mentie",
-  "version": "0.3.5",
+  "version": "0.3.7",
   "description": "Mentor's toolbelt",
   "type": "module",
   "main": "index.js",
@@ -28,9 +28,9 @@
     "husky": "^9.1.3"
   },
   "peerDependencies": {
+    "hash.js": "^1.1.7",
     "promise-parallel-throttle": "^3.5.0",
-    "promise-retry": "^2.0.1",
-    "hash.js": "^1.1.7"
+    "promise-retry": "^2.0.1"
   },
   "dependencies": {
     "safe-stable-stringify": "^2.4.3"