mentie 0.3.15 → 0.3.17

package/modules/cache.js

@@ -29,6 +29,11 @@ export function cache( key, value, expires_in_ms=Infinity ) {
         log.warn( `The cache key is ${ key }, this may indicate a bug in your cache logic` )
     }
 
+    if( typeof expires_in_ms !== 'number' ) {
+        log.warn( `cache() expires_in_ms must be a number, got ${ typeof expires_in_ms }` )
+        expires_in_ms = Infinity
+    }
+
     // If value is provided, save value and expiration
     if( value !== undefined ) _cache[key] = { value, expires: Date.now() + expires_in_ms }
 

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

@@ -117,10 +117,14 @@ env.is_android = () => env.is_web() && navigator.userAgent?.toUpperCase().includ
  * Checks if the code is running in a web browser and the platform is iOS.
  * @returns {boolean} True if the code is running in a web browser and the platform is made by Apple
  */
-env.is_apple = () => env.is_web() && navigator.userAgent?.toUpperCase().includes( 'MAC OS X' )
+env.is_apple = () => {
+    if( !env.is_web() ) return false
+    const userAgent = navigator.userAgent?.toUpperCase()
+    return userAgent?.includes( 'MAC OS X' ) || userAgent?.includes( 'IPHONE' ) || userAgent?.includes( 'IPAD' )
+}
 
 /**
- * Checks if the code is running in a web browser and the platform is Windows.
+ * Checks if the code is running in a web browser and the platform is Linux.
  * @returns {boolean} True if the code is running in a web browser and the platform is Linux, otherwise false.
  */
 env.is_linux = () => env.is_web() && navigator.userAgent?.toUpperCase().includes( 'LINUX' )
@@ -165,7 +169,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/network.js

@@ -6,32 +6,37 @@
  * @returns {Object} signal_data - Object containing fetch options and abort signal
  * @returns {Object} signal_data.fetch_options - Options for usage with fetch requests
  * @returns {AbortController} signal_data.controller - Raw abort controller
- * @returns {Function} signal_data.abort_signal - Function to abort the request
- * @returns {Function} signal_data.abort - Alias for abort_signal
- * @returns {number} signal_data.timeout_id - Timeout ID
+ * @returns {number|null} signal_data.timeout_id - Timeout ID, or null if no timeout was set
+ * @example
+ * const { fetch_options, controller } = abort_controller( { timeout_ms: 5000 } )
+ * fetch( 'https://api.example.com/data', fetch_options )
+ * controller.abort() // Abort the request
  */
 export const abort_controller = ( { timeout_ms }={} ) => {
 
+    // Input validation
+    if( timeout_ms !== undefined && ( typeof timeout_ms !== 'number' || timeout_ms < 0 ) ) {
+        throw new Error( 'timeout_ms must be a non-negative number' )
+    }
+
     // Request with timeout
     const controller = new AbortController()
-    const timeout_id = timeout_ms && setTimeout( () => {
+    const timeout_id = timeout_ms !== undefined ? setTimeout( () => {
         controller.abort()
-    }, timeout_ms )
+    }, timeout_ms ) : null
+
+    // Clear timeout when controller is aborted
+    controller.signal.addEventListener( 'abort', () => {
+        if( timeout_id !== null ) clearTimeout( timeout_id )
+    } )
 
     const fetch_options = {
         signal: controller.signal
     }
 
-    const abort = () => {
-        if( timeout_ms ) clearTimeout( timeout_id )
-        controller.abort()
-    }
-
     return {
         fetch_options,
         controller,
-        abort_signal: abort,
-        abort,
         timeout_id
     }
 

package/modules/promises.js

@@ -60,7 +60,7 @@ export async function make_retryable( async_function, { retry_times = 5, cooldow
  *
  * @param {Array<Function>} async_function_array - Array of async functions to be throttled and retried.
  * @param {Object} options - Options for throttling and retrying.
- * @param {number} [options.max_parallell=2] - Maximum number of functions to run in parallel.
+ * @param {number} [options.max_parallel=2] - Maximum number of functions to run in parallel.
  * @param {number} [options.retry_times] - Number of times to retry each function.
  * @param {number} [options.cooldown_in_s] - Cooldown time in seconds between retries.
  * @param {number} [options.cooldown_entropy] - Random factor to add to the cooldown time.
@@ -112,17 +112,26 @@ export async function throttle_and_retry( async_function_array = [], { max_paral
  */
 export async function promise_timeout( promise, timeout_in_ms=60_000, throw_on_timeout=true ) {
 
-    // Timeout finction
-    const timeout = () => new Promise( ( res, rej ) => setTimeout( throw_on_timeout ? rej : () => res( 'timed out' ), timeout_in_ms ) )
+    // Timeout id placeholder
+    let timeout_id
+
+    // Timeout function that stores the timeout ID so we can clear it
+    const timeout = () => new Promise( ( res, rej ) => {
+        timeout_id = setTimeout( throw_on_timeout ? rej : () => res( 'timed out' ), timeout_in_ms )
+    } )
 
     // Race the promise against the timeout
-    return Promise.race( [
+    try {
+        const result = await Promise.race( [
+            promise,
+            timeout()
+        ] )
 
-        // If the promise resolves first, return the result (including throwsing on error)
-        promise,
+        return result
 
-        // If this resolves first, this function throws or returns a timeout message
-        timeout()
-    ] )
+    } finally {
+        // Clear the timeout
+        clearTimeout( timeout_id )
+    }
 
 }

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.15",
+  "version": "0.3.17",
   "description": "Mentor's toolbelt",
   "type": "module",
   "main": "index.js",