mentie 0.0.9 → 0.0.11

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/logging.js

@@ -7,6 +7,10 @@ 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 ) {
 
@@ -22,11 +26,11 @@ 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 )
+ * 🎯 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' ]
@@ -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,24 @@
+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 1 and the specified maximum number.
+ *
+ * @param {number} max_number - The maximum number for generating the random number.
+ * @returns {number} The generated random number.
+ */
+export const random_number_of_max = max_number => Math.floor( Math.random() * max_number ) + 1
+
+
+/**
+ * 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 => Number( [ ...Array( length ) ].map( () => random_number_of_max( 9 ) ).join( '' ) )

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}
+ */
+async function throttle_and_retry( async_function_array=[], { max_parallell=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_parallell,
+        failFast: fail_fast,
+        ...logger && { progressCallback: logger }
+    }
+
+    // Return throttler
+    return Throttle.all( retryable_async_functions, throttle_config )
+
+}

package/modules/text.js

@@ -0,0 +1,33 @@
+/**
+ * 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 ) }${ suffix }`
+}
+
+/**
+ * Copies the given text to the clipboard.
+ * @param {string} text - The text to be copied to the clipboard.
+ * @param {string} [success_message='Copied to clipboard'] - The success message to be displayed after copying.
+ * @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' ) => {
+    if( !navigator?.clipboard?.writeText ) return alert( 'Your browser does not support copying to clipboard' )
+    await navigator.clipboard.writeText( text )
+    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 => `${ string?.charAt( 0 ).toUpperCase() }${ string?.slice( 1, string?.length ) }`

package/modules/time.js

@@ -1,6 +1,69 @@
 /**
  * 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.
+ * @param {number} timestamp - The timestamp to convert.
+ * @returns {string} The RFC-822 formatted date string.
+ */
+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
+
+    // Get the timezone on the running machine
+    const { timeZone } = Intl.DateTimeFormat().resolvedOptions()
+
+    // Construct the RFC-822 date string
+    return `${ dayOfWeek }, ${ dayStr } ${ month } ${ year } ${ hoursStr }:${ minutesStr }:${ secondsStr } ${ timeZone }`
+}
+
+/**
+ * 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.9",
+  "version": "0.0.11",
   "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"
   }
 }

package/.eslintrc.cjs

@@ -1,7 +0,0 @@
-// const { eslint_config } = require( './index.cjs' )
-const { eslint_config } = require( 'airier' )
-
-// Export the default eslint config
-module.exports = {
-    ...eslint_config
-}

package/.husky/pre-commit

@@ -1,17 +0,0 @@
-echo "\n🤖 [ precommit hook ] linting before committing..."
-
-# If errors, make it clear they cannot commit
-if ! lint_outcome=$(npm run lint); then
-    echo "🚨 [ precommit hook ] lint encountered blocking issues, fix them before committing\n"
-    echo "$lint_outcome"
-    exit 1
-fi
-
-# If warnings, suggest they fix them
-if echo $lint_outcome | grep -q "warning"; then
-    echo "⚠️ [ precommit hook ] lint encountered warnings, consider fixing them before pushing\n"
-    echo "$lint_outcome"
-    exit 0
-fi
-
-echo "✅ [ precommit hook ] lint encountered no blocking issues\n"

package/.vscode/settings.json

@@ -1,27 +0,0 @@
-{
-	"i18n-ally.localesPaths": [
-		"public/locales"
-	],
-	"i18n-ally.keystyle": "nested",
-	"eslint.validate": [
-		"javascript",
-		"javascriptreact",
-		"typescript",
-		"typescriptreact"
-	],
-	"editor.codeActionsOnSave": {
-		"source.fixAll.eslint": "explicit"
-	},
-	"editor.renderWhitespace": "all",
-	"editor.formatOnSave": true,
-	"eslint.format.enable": true,
-	"eslint.run": "onType",
-	"explorer.fileNesting.enabled": true,
-	"explorer.fileNesting.patterns": {
-		"vite.config.js": "*.js,.babelrc,.nvmrc,index.html,.gitignore",
-		".env": ".env*,.*.json",
-		"firebase.json": "fire*,.fire*",
-		"package.json": "package-lock.json, yarn.lock, pnpm-lock.yaml,.eslint*,config.*,.npm*,.nvm*,.ncu*",
-		"README.md": "*.md,LICENSE",
-	}
-}