mentie 0.0.10 → 0.1.0

package/index.js

@@ -1,3 +1,7 @@
 export * from './modules/logging.js'
 export * from './modules/time.js'
-export * from './modules/environment.js'
+export * from './modules/environment.js'
+export * from './modules/validations.js'
+export * from './modules/text.js'
+export * from './modules/numbers.js'
+export * from './modules/promises.js'

package/modules/environment.js

@@ -17,13 +17,13 @@ export const is_node = typeof process !== 'undefined' && process.versions && pro
  * Checks if the code is running in a Firebase functions emulator environment.
  * @returns {boolean} Returns true if the code is running in a Firebase environment, otherwise returns false.
  */
-export const is_emulator = process.env.FUNCTIONS_EMULATOR === 'true'
+export const is_emulator = typeof process !== 'undefined' && process.env?.FUNCTIONS_EMULATOR === 'true'
 
 // ///////////////////////////////
 // Mode and loglevel detection
 // ///////////////////////////////
 
-const node_dev = process.env.NODE_ENV === 'development'
+const node_dev = typeof process !== 'undefined' && process.env?.NODE_ENV === 'development'
 const web_dev = typeof location !== 'undefined' && ( `${ location.href }`.includes( 'debug=true' ) || `${ location.href }`.includes( 'localhost' ) )
 
 /**
@@ -36,13 +36,13 @@ export const dev = node_dev || web_dev
  * The log level for web applications.
  * @type {string}
  */
-export const web_loglevel = is_web && new URLSearchParams( location.search ).get( 'loglevel' )
+export const web_loglevel = is_web && new URLSearchParams( location?.search ).get( 'loglevel' )
 
 /**
  * The log level for the Node environment.
  * @type {string}
  */
-export const node_loglevel = process.env.LOG_LEVEL
+export const node_loglevel = process.env?.LOG_LEVEL
 
 
 /**

package/modules/logging.js

@@ -7,11 +7,15 @@ import { dev, loglevel } from "./environment.js"
  *  🎯 Goal: log informational messages about the state of the application.
  * @example log( `User state was updated to: `, user )
  * @param {...any} messages - The messages to be logged.
+ * @property {function} info - Logs info trace messages used only for extremely granular debugging.
+ * @property {function} warn - Logs warnings of things that should not happen, but do not break functionality.
+ * @property {function} error - Logs errors that impact proper functioning of the application.
+ * @property {string} loglevel - The log level used in the environment
  */
 export function log( ...messages ) {
 
     // Check if the loglevel matches this call
-    const levels = [ 'error', 'warn', 'info' ]
+    const levels = [ 'info' ]
     const should_log = dev || levels.includes( loglevel )
 
     // Log the messages if the loglevel matches
@@ -21,16 +25,16 @@ export function log( ...messages ) {
 
 /**
  * Logs the provided info messages to the console.
- * Only logs in development mode OR if ?loglevel= or LOG_LEVEL= is set to one of the following: 'error', 'warn'
- * 🎯 Goal: log verbose trace messages used only for extremely granular debugging
- * @example log.verbose( `Retreived key '${ key }' of type '${ typeof key }' from localstorage: `, cache )
+ * Only logs if ?loglevel= or LOG_LEVEL= is set to: 'info'
+ * 🎯 Goal: log info trace messages used only for extremely granular debugging
+ * @example log.info( `Retreived key '${ key }' of type '${ typeof key }' from localstorage: `, cache )
  * @param {...any} messages - The messages to be logged.
  */
-log.verbose = function( ...messages ) {
+log.info = function( ...messages ) {
 
     // Check if the loglevel matches this call
-    const levels = [ 'error', 'warn', 'info' ]
-    const should_log = dev || levels.includes( loglevel )
+    const levels = [ 'info' ]
+    const should_log = levels.includes( loglevel )
 
     // Log the messages if the loglevel matches
     if( should_log ) console.info( ...messages )
@@ -39,7 +43,7 @@ log.verbose = function( ...messages ) {
 
 /**
  * Logs the provided info messages to the console.
- * Only logs in development mode OR if ?loglevel= or LOG_LEVEL= is set to one of the following: 'error', 'warn'
+ * Only logs in development mode OR if ?loglevel= or LOG_LEVEL= is set to one of the following: 'warn', 'info'
  * 🎯 Goal: log warnings of things that should not happen, but do not break functionality
  * @example log.warn( `Transaction history was empty, this should never happen: `, history )
  * @param {...any} messages - The messages to be logged.
@@ -47,7 +51,7 @@ log.verbose = function( ...messages ) {
 log.warn = function( ...messages ) {
 
     // Check if the loglevel matches this call
-    const levels = [ 'error', 'warn' ]
+    const levels = [ 'warn', 'info' ]
     const should_log = dev || levels.includes( loglevel )
 
     // Log the messages if the loglevel matches
@@ -57,7 +61,7 @@ log.warn = function( ...messages ) {
 
 /**
  * Logs the provided error messages to the console.
- * Only logs in development mode OR if ?loglevel= or LOG_LEVEL= is set to one of the following: 'error'
+ * Only logs in development mode OR if ?loglevel= or LOG_LEVEL= is set to one of the following: 'error', 'warn', 'info'
  * @scope log errors that impact proper functioning of the application
  * @example log.error( `Error connecting to database: `, error )
  * @param {...any} messages - The messages to be logged.
@@ -65,7 +69,7 @@ log.warn = function( ...messages ) {
 log.error = function( ...messages ) {
 
     // Check if the loglevel matches this call
-    const levels = [ 'error' ]
+    const levels = [ 'error', 'warn', 'info' ]
     const should_log = dev || levels.includes( loglevel )
     if( !should_log ) return
 
@@ -74,3 +78,6 @@ log.error = function( ...messages ) {
     console.trace()
 
 }
+
+// Set the loglevel on the log function
+log.loglevel = loglevel

package/modules/numbers.js

@@ -0,0 +1,32 @@
+/**
+ * Rounds a number to the specified number of decimals.
+ *
+ * @param {number} number - The number to round.
+ * @param {number} [decimals=4] - The number of decimals to round to. Default is 4.
+ * @returns {number} The rounded number.
+ */
+export const round_number_to_decimals = ( number, decimals=4 ) => {
+
+    if( number == undefined ) return ''
+
+    const factor = 10 ** decimals
+    return Math.round( number * factor ) / factor
+}
+
+/**
+ * Generates a random number between a minimum and maximum value.
+ *
+ * @param {number} max_num - The maximum value for the random number.
+ * @param {number} [min_num=1] - The minimum value for the random number
+ * @returns {number} The generated random number.
+ */
+export const random_number_between = ( max_num, min_num=1 ) => Math.floor( Math.random() * ( max_num - min_num + 1 ) ) + min_num
+
+
+/**
+ * Generates a random number of a specified length.
+ *
+ * @param {number} length - The length of the random number.
+ * @returns {number} - The generated random number.
+ */
+export const random_number_of_length = length =>  parseInt( Array.from( { length }, () => Math.floor( Math.random() * 10 ) ).join( '' ), 10 )

package/modules/promises.js

@@ -0,0 +1,93 @@
+/**
+ * Creates a retryable function that wraps an async function and adds retry logic.
+ * @param {Function} async_function - The async function to be made retryable. MUST be an UNCALLED function. See example.
+ * @param {Object} options - The options for retrying.
+ * @param {number} [options.retry_times=5] - The number of times to retry the async function.
+ * @param {number} [options.cooldown_in_s=10] - The cooldown time in seconds between retries.
+ * @param {boolean} [options.cooldown_entropy=true] - Whether to add randomness to the cooldown time.
+ * @param {Function} [options.logger=null] - The logger function to log retry attempts.
+ * @returns {Function} - The retryable function.
+ * @example
+ * make_retryable( do_thing )
+ * make_retryable( () => fetch( 'https://api.com/data' ) )
+ * @see {@link https://www.npmjs.com/package/promise-retry|promise-retry}
+ */
+export async function make_retryable( async_function, { retry_times=5, cooldown_in_s=10, cooldown_entropy=true, logger=null } ) {
+
+    // Function dependencies
+    const Retrier = await import( 'promise-retry' )
+    const { wait } = await import( './time.js' )
+
+    // Set a default logger that does nothing if none was provided
+    if( !logger ) logger = () => {}
+
+    // Formulate retry logic
+    const retryable_function = () => Retrier( ( do_retry, retry_counter ) => {
+
+        // Failure handling
+        return async_function().catch?.( async e => {
+
+            // If retry attempts exhausted, throw out
+            if( retry_counter >= retry_times ) {
+                logger( { message: 'Retry failed definitively', data: { retry_counter, retry_times } } )
+                throw e
+            }
+
+            // If retries left, retry with a progressive delay
+            const entropy = !cooldown_entropy ? 0 :  .1 + Math.random() // Add some randomness to cooldown
+            const cooldown_in_ms = ( cooldown_in_s + entropy ) * 1000 // Convert cooldown to milliseconds
+            const cooldown = cooldown_in_ms + cooldown_in_ms * ( retry_counter - 1 ) // Increase cooldown with each retry
+
+            // Log and wait
+            logger( { message: 'Retry failed, pausing...', data: { retry_counter, retry_times, cooldown_in_s, cooldown_in_ms, cooldown } } )
+            await wait( cooldown )
+            logger( { message: 'Cooldown complete, continuing...', data: { retry_counter, retry_times } } )
+
+            // Retry
+            return do_retry()
+
+        } )
+
+    } )
+
+    return retryable_function
+
+}
+
+
+/**
+ * Throttles and retries an array of async functions.
+ *
+ * @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.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.
+ * @param {Function} [options.logger] - Progress callback function.
+ * @param {boolean} [options.fail_fast=true] - Whether to fail fast or continue with other functions when an error occurs.
+ * @returns {Promise<Array>} - A promise that resolves to an array of results from the async functions.
+ * @see {@link https://www.npmjs.com/package/promise-parallel-throttle|promise-parallel-throttle}
+ */
+export async function throttle_and_retry( async_function_array=[], { max_parallel=2, retry_times, cooldown_in_s, cooldown_entropy, logger, fail_fast=true } ) {
+
+    // Function dependencies 
+    const Throttle = await import( 'promise-parallel-throttle' )
+
+    // Create array of retryable functions
+    const retryable_async_functions = async_function_array.map( async_function => {
+        const retryable_function = make_retryable( async_function, { retry_times, cooldown_in_s, logger, cooldown_entropy } )
+        return retryable_function
+    } )
+
+    // Throttle configuration
+    const throttle_config = {
+        maxInProgress: max_parallel,
+        failFast: fail_fast,
+        ...logger && { progressCallback: logger }
+    }
+
+    // Return throttler
+    return Throttle.all( retryable_async_functions, throttle_config )
+
+}

package/modules/text.js

@@ -0,0 +1,40 @@
+/**
+ * Truncates a given text to a specified length and appends a suffix if necessary.
+ *
+ * @param {string} text - The text to be truncated.
+ * @param {number} [length=100] - The maximum length of the truncated text.
+ * @param {string} [suffix='...'] - The suffix to be appended to the truncated text.
+ * @returns {string} The truncated text.
+ */
+export const truncate = ( text, length=100, suffix='...' ) => {
+    if( !text ) return ''
+    if( text.length <= length ) return text
+    return `${ text.slice( 0, length ).trim() }${ suffix }`
+}
+
+/**
+ * Copies the given text to the clipboard.
+ * @param {string} text - The text to be copied to the clipboard.
+ * @param {object} options - The options for copying to the clipboard.
+ * @param {string} [options.success_message='Copied to clipboard'] - The success message to be displayed after copying.
+ * @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' )
+    await navigator.clipboard.writeText( text )
+
+    if( alerter ) alerter( success_message )
+    else alert( success_message )
+}
+
+/**
+ * Capitalizes the first letter of a string.
+ *
+ * @param {string} string - The input string.
+ * @returns {string} The capitalized string.
+ */
+export const capitalise = string => { 
+    if( !string ) return ''
+    return `${ string?.charAt( 0 ).toUpperCase() }${ string?.slice( 1, string?.length ) }`
+}

package/modules/time.js

@@ -1,6 +1,68 @@
 /**
  * Waits for the specified amount of time.
  * @param {number} ms - The number of milliseconds to wait.
+ * @param {boolean} [error=false] - If true, the promise will reject after the specified time.
  * @returns {Promise<void>} - A promise that resolves after the specified time.
  */
-export const wait = ( ms=0 ) => new Promise( resolve => setTimeout( resolve, ms ) )
+export const wait = ( ms, error=false ) => new Promise( ( res, rej ) => setTimeout( error ? rej : res, ms ) )
+
+/**
+ * Converts a timestamp to RFC-822 date format, specifically in GMT.
+ * @param {number} timestamp - The timestamp to convert.
+ * @returns {string} The RFC-822 formatted date string in GMT.
+ */
+export function timestamp_to_RFC822( timestamp ) {
+
+    // Days and months
+    const days = [ "Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat" ]
+    const months = [ "Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec" ]
+
+    // Create a date object from the timestamp
+    const date = new Date( timestamp )    
+
+    // Get components of the date
+    const dayOfWeek = days[date.getUTCDay()]
+    const dayOfMonth = date.getUTCDate()
+    const month = months[date.getUTCMonth()]
+    const year = date.getUTCFullYear()
+    const hours = date.getUTCHours()
+    const minutes = date.getUTCMinutes()
+    const seconds = date.getUTCSeconds()
+
+    // Format components
+    const dayStr = dayOfMonth < 10 ? '0' + dayOfMonth : dayOfMonth
+    const hoursStr = hours < 10 ? '0' + hours : hours
+    const minutesStr = minutes < 10 ? '0' + minutes : minutes
+    const secondsStr = seconds < 10 ? '0' + seconds : seconds
+
+    
+
+    // Construct the RFC-822 date string
+    return `${ dayOfWeek }, ${ dayStr } ${ month } ${ year } ${ hoursStr }:${ minutesStr }:${ secondsStr } GMT`
+}
+
+/**
+ * Converts seconds to HH:MM:SS format.
+ *
+ * @param {number} seconds - The number of seconds to convert.
+ * @returns {string} The formatted time in HH:MM:SS format.
+ */
+export function seconds_to_hh_mm_ss( seconds ) {
+
+    // Round the input to the nearest second
+    const rounded_seconds = Math.round( seconds )
+
+    // Calculate hours, minutes, and seconds
+    const hours = Math.floor( rounded_seconds / 3600 )
+    const minutes = Math.floor( rounded_seconds % 3600  / 60 )
+    const remaining_seconds = rounded_seconds % 60
+    
+    // Pad each unit with zeros and concatenate them
+    const padded_hours = String( hours ).padStart( 2, '0' )
+    const padded_minutes = String( minutes ).padStart( 2, '0' )
+    const padded_seconds = String( remaining_seconds ).padStart( 2, '0' )
+    
+    // Return the formatted time
+    return `${ padded_hours }:${ padded_minutes }:${ padded_seconds }`
+
+}

package/modules/validations.js

@@ -0,0 +1,14 @@
+/**
+ * Regular expression for validating email addresses.
+ * @see {@link https://emailregex.com/}
+ * @type {RegExp}
+ */
+export const email_regex = /(?:[a-z0-9!#$%&'*+/=?^_`{|}~-]+(?:\.[a-z0-9!#$%&'*+/=?^_`{|}~-]+)*|"(?:[\x01-\x08\x0b\x0c\x0e-\x1f\x21\x23-\x5b\x5d-\x7f]|\\[\x01-\x09\x0b\x0c\x0e-\x7f])*")@(?:(?:[a-z0-9](?:[a-z0-9-]*[a-z0-9])?\.)+[a-z0-9](?:[a-z0-9-]*[a-z0-9])?|\[(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?|[a-z0-9-]*[a-z0-9]:(?:[\x01-\x08\x0b\x0c\x0e-\x1f\x21-\x5a\x53-\x7f]|\\[\x01-\x09\x0b\x0c\x0e-\x7f])+)\])/i
+
+/**
+ * Sanitizes a string by removing leading and trailing whitespace and converting it to lowercase.
+ *
+ * @param {string} string - The string to be sanitized.
+ * @returns {string} - The sanitized string.
+ */
+export const sanetise_string = string => `${ string }`.trim().toLowerCase()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mentie",
-  "version": "0.0.10",
+  "version": "0.1.0",
   "description": "Mentor's toolbelt",
   "type": "module",
   "main": "index.js",
@@ -26,5 +26,9 @@
     "eslint-plugin-react": "^7.35.0",
     "eslint-plugin-unused-imports": "^3.2.0",
     "husky": "^9.1.3"
+  },
+  "dependencies": {
+    "promise-parallel-throttle": "^3.5.0",
+    "promise-retry": "^2.0.1"
   }
 }