mentie 0.3.14 → 0.3.16

package/modules/cache.js

@@ -25,8 +25,8 @@ export function cache( key, value, expires_in_ms=Infinity ) {
     }
 
     // Warn if the key contains 'undefined'
-    if( `${ key }`.includes( 'undefined' ) ) {
-        log.warn( `The cache key ${ key } contains 'undefined', this may indicate a bug in your cache logic` )
+    if( `${ key }`.includes( 'undefined' ) || `${ key }`.includes( 'null' ) ) {
+        log.warn( `The cache key is ${ key }, this may indicate a bug in your cache logic` )
     }
 
     // If value is provided, save value and expiration
@@ -42,6 +42,49 @@ export function cache( key, value, expires_in_ms=Infinity ) {
     return _cache[key]?.value
 }
 
+/**
+ * Restores the cache from a given cache object.
+ * If the cache object is empty, it will overwrite the current cache.
+ * If the cache object has keys that already exist in the current cache, those keys will be skipped.
+ * @param {Object} cache_object - The cache object to restore.
+ * @returns {Object} The updated cache object.
+ * @throws {Error} If the cache_object is not an object or is null.
+ */
+cache.restore = ( cache_object ) => {
+
+    // Impute type of cache_object
+    let input_type = typeof cache_object
+    if( cache_object === null ) input_type = 'null'
+    if( Array.isArray( cache_object ) ) input_type = 'array'
+
+    // Check if the cache_object is an object, specifically check it is not an array
+    if( input_type != 'object' ) {
+        throw new Error( `cache.restore() expects an object, got ${ input_type }` )
+    }
+
+    // If current cache has no keys, restore the cache object
+    if( !Object.keys( _cache ).length ) {
+        // Assign the cache_object content to the cache obect
+        Object.assign( _cache, cache_object )
+        log.info( `Cache restored with ${ Object.keys( cache_object ).length } keys` )
+        return _cache
+    }
+
+    // If current cache has keys, only overwrite keys that are not already in cache, warn for keys that are skipped
+    const keys = Object.keys( cache_object )
+    for( const key of keys ) {
+        if( _cache[key] ) {
+            log.warn( `Cache key ${ key } already exists, skipping restore` )
+        } else {
+            _cache[key] = cache_object[ key ]
+        }
+    }
+
+    log.info( `Cache restored with ${ keys.length } keys, ${ Object.keys( _cache ).length } total keys in cache` )
+    return _cache
+
+}
+
 /**
  * 
  * @returns {Object} - A copy of the cache object.
@@ -84,11 +127,17 @@ cache.stats = () => {
 }
 
 /**
- * Function to inspect concurrency.
+ * Function to inspect concurrency calls of a function. Add this as a logger in a function to log out the concurrency value.
  * 
  * @param {Function} logger - The logger function.
  * @param {string} key_prefix - The key for the concurrency value, used to tag the logging
  * @returns {number} - The concurrency value.
+ * @example
+ * import { cache, concurrency } from 'mentie';
+ * function often_called_function() {
+ *    concurrency( console.log, 'important_function' );
+ *   // ... function logic ...
+ * }
  */
 export function concurrency( logger, key_prefix ) {
 

package/modules/crypto.js

@@ -3,7 +3,7 @@
  * 
  * @param {string} data - The data to be hashed.
  * @param {string} [algo='sha256'] - The algorithm to be used for hashing. Defaults to 'sha256'.
- * @param {string} [_digest='hex'] - The encoding of the output hash. Defaults to '
+ * @param {string} [_digest='hex'] - The encoding of the output hash. Defaults to 'hex'.
  * @returns {Promise<string>} The hashed value of the data.
  */
 export async function hash( data, algo='sha256', _digest='hex' ) {

package/modules/environment.js

@@ -165,7 +165,7 @@ export const is_emulator = env.is_emulator()
  * Checks if the code is running in a development environment.
  * @returns {boolean} Returns true if the code is running in a development environment, otherwise returns false.
  */
-export const is_github_actions = typeof process !== 'undefined' && process.env?.GITHUB_ACTIONS == true
+export const is_github_actions = typeof process !== 'undefined' && process.env?.GITHUB_ACTIONS === 'true'
 
 /**
  * @returns {boolean} Returns true if the code is running on an Apple device, otherwise returns false.

package/modules/logging.js

@@ -109,7 +109,7 @@ export function log( ...messages ) {
     if( dev || should_log( levels ) ) {
 
         // Annotate the provided messages
-        annotate_messages( messages )
+        messages = annotate_messages( messages )
 
         // Log the messages
         console.log( ...messages )
@@ -134,7 +134,7 @@ log.info = function( ...messages ) {
     if( env.is_emulator() || should_log( levels ) ) {
 
         // Annotate the provided messages
-        annotate_messages( messages )
+        messages = annotate_messages( messages )
 
         // Log the messages
         console.info( ...messages )
@@ -159,7 +159,7 @@ log.warn = function( ...messages ) {
     if( dev || should_log( levels ) ) {
 
         // Annotate the provided messages
-        annotate_messages( messages )
+        messages = annotate_messages( messages )
 
         // Log the messages
         console.warn( '⚠️ ', ...messages )
@@ -181,6 +181,9 @@ log.error = function( ...messages ) {
     const levels = [ 'error', 'warn', 'info' ]
     if( !should_log( levels ) ) return
 
+    // Annotate the provided messages
+    messages = annotate_messages( messages )
+
     // Log the messages if the loglevel matches
     console.error( '🚨 ', ...messages )
     console.trace()

package/modules/text.js

@@ -22,12 +22,11 @@ export const truncate = ( text, length=100, suffix='...' ) => {
  * @param {function} [options.alerter] - The custom function to display the success message.
  * @returns {Promise<void>} - A promise that resolves when the text is successfully copied to the clipboard.
  */
-export const copy_to_clipboard = async ( text, { success_message='Copied to clipboard', alerter } ) => {
-    if( !navigator?.clipboard?.writeText ) return alert( 'Your browser does not support copying to clipboard' )
+export const copy_to_clipboard = async ( text, { success_message='Copied to clipboard', alerter=alert } ) => {
+    if( !navigator?.clipboard?.writeText ) return alerter( 'Your browser does not support copying to clipboard' )
     await navigator.clipboard.writeText( text )
 
-    if( alerter ) alerter( success_message )
-    else alert( success_message )
+    alerter( success_message )
 }
 
 /**
@@ -58,12 +57,12 @@ export const random_letter = ( allowed_chars, capitals=true ) => {
 
 }
 
-export const random_string_of_length = ( length, allowed_chars, numbers=true ) => {
+export const random_string_of_length = ( length, allowed_chars, numbers=true, capitals=true ) => {
 
     return Array.from( { length }, () => {
         // If numbers are allowed, add a 50% chance of generating a number
         if( numbers && Math.random() > 0.5 ) return `${ random_number_between( 9, 0 ) }`
-        return random_letter( allowed_chars )
+        return random_letter( allowed_chars, capitals )
     } ).join( '' )
 
 }

package/modules/validations.js

@@ -15,6 +15,51 @@ export const email_regex = /(?:[a-z0-9!#$%&'*+/=?^_`{|}~-]+(?:\.[a-z0-9!#$%&'*+/
  */
 export const sanetise_string = string => `${ string }`.trim().toLowerCase()
 
+/**
+ * Validates whether a given string is a valid IPv4 address.
+ * @param {string} ip - The IP address string to validate.
+ * @returns {boolean} True if the IP address is valid, otherwise false.
+ */
+export const is_ipv4 = ip => {
+
+    // Split the IP address into its components and make then numbers
+    const octets = ip.split( '.' ).map( octet => parseInt( octet, 10 ) )
+
+    // Check if the IP address has 4 octets and each octet is between 0 and 255
+    return octets.length === 4 && octets.every( octet => !isNaN( octet ) && octet >= 0 && octet <= 255 )
+
+}
+
+/**
+ * Sanitizes and optionally validates an IPv4 address.
+ * @param {Object} options - The options object.
+ * @param {string} options.ip - The IP address to sanitize.
+ * @param {boolean} [options.validate=false] - Whether to validate the IP address.
+ * @param {boolean} [options.error_on_invalid=false] - Whether to throw an error on an invalid IP.
+ * @returns {string|null} The sanitized IPv4 address, or null if validation fails and error_on_invalid is false.
+ * @throws {Error} If the IP address is not provided or invalid when error_on_invalid is true.
+ */
+export const sanetise_ipv4 = ( { ip, validate=false, error_on_invalid=false } ) => {
+
+    // Ensure ip was provided
+    if( !ip ) throw new Error( 'IP address is required' )
+
+    // Sanetise ip address as string
+    ip = sanetise_string( ip )
+
+    // Remove ipv6 prefix if present
+    ip = ip.replace( '::ffff:', '' )
+
+    // Check if the IP address is valid
+    if( validate && !is_ipv4( ip ) ) {
+        if( error_on_invalid ) throw new Error( `Invalid IPv4 address: ${ ip }` )
+        return null
+    }
+
+    // Return the sanitized IP address
+    return ip
+
+}
 
 /**
  * Checks if an object contains all the required properties.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mentie",
-  "version": "0.3.14",
+  "version": "0.3.16",
   "description": "Mentor's toolbelt",
   "type": "module",
   "main": "index.js",