mentie 0.1.15 → 0.1.18

package/modules/cache.js

@@ -1,3 +1,5 @@
+import { log } from "./logging"
+
 /**
  * Cache object for storing data.
  * @type {Object}
@@ -15,6 +17,17 @@ const _cache = {}
  * @returns {*} The cached value.
  */
 export function cache( key, value ) {
+
+    // If the key is undefined, log a warning
+    if( key === undefined ) {
+        log.warn( `The cache key is undefined, this may indicate a bug in your cache logic` )
+    }
+
+    // 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( value ) _cache[key] = value
     return _cache[key]
 }

package/modules/environment.js

@@ -2,61 +2,128 @@
 // Platform and environment detection
 // ///////////////////////////////
 
+
+
+/**
+ * Environment checks for various runtime contexts.
+ * Useful in compiled code where the runtime environment may not be known at compile time.
+ * @namespace
+ */
+export const env = {}
+
+/**
+ * Determines if the current runtime environment is a web browser.
+ * @returns {boolean} True if running in a web environment, otherwise false.
+ */
+env.is_web = () => typeof window !== 'undefined'
+
+/**
+ * Checks if the code is running in the Cypress testing environment within a web browser.
+ * @returns {boolean} True if running in Cypress, otherwise false.
+ */
+env.is_cypress = () => env.is_web() && typeof window.Cypress !== 'undefined'
+
+/**
+ * Determines if the current runtime environment is Node.js.
+ * @returns {boolean} True if running in Node.js, otherwise false.
+ */
+env.is_node = () => typeof process !== 'undefined' && process.versions && process.versions?.node
+
+/**
+ * Checks if the code is running in an emulator environment in Node.js.
+ * @returns {boolean} True if running in a Node.js emulator, otherwise false.
+ */
+env.is_emulator = () => env.is_node() && process.env?.FUNCTIONS_EMULATOR === 'true'
+
+/**
+ * Determines if the Node.js environment is in development mode.
+ * @returns {boolean} True if NODE_ENV is 'development', otherwise false.
+ */
+env.node_dev = () => typeof process !== 'undefined' && process.env?.NODE_ENV === 'development'
+
+/**
+ * Determines if the web environment is in development mode.
+ * @returns {boolean} True if the URL includes 'debug=true' or 'localhost', otherwise false.
+ */
+env.web_dev = () => typeof location !== 'undefined' && ( `${ location.href }`.includes( 'debug=true' ) || `${ location.href }`.includes( 'localhost' ) )
+
+/**
+ * Determines if the environment is in development mode (either web or Node.js).
+ * @returns {boolean} True if either web_dev or node_dev returns true, otherwise false.
+ */
+env.dev = () => env.node_dev() || env.web_dev()
+
+/**
+ * Retrieves the log level set via URL parameters in a web environment.
+ * @returns {string|null} The log level from URL parameters, or null if not set.
+ */
+env.web_loglevel = () => env.is_web() && new URLSearchParams( location?.search ).get( 'loglevel' )
+
+/**
+ * Retrieves the log level set via environment variables in a Node.js environment.
+ * @returns {string|undefined} The log level from environment variables, or undefined if not set.
+ */
+env.node_loglevel = () => env.is_node() && process.env?.LOG_LEVEL
+
+/**
+ * Retrieves the effective log level based on the environment. Defaults to 'info' in development environments, 'error' otherwise.
+ * @returns {string} The determined log level.
+ */
+env.loglevel = () => env.web_loglevel() || env.node_loglevel() || env.dev() ? 'info' : 'error'
+
+
 /**
  * Checks if the code is running in a web environment.
  * @returns {boolean} Returns true if the code is running in a web environment, otherwise returns false.
  */
-export const is_web = typeof window !== 'undefined'
+export const is_web = env.is_web()
 
 /**
  * Checks if the code is running within a Cypress environment.
  * @returns {boolean} Returns true if the code is running in a Cypress environment, otherwise returns false.
  */
-export const is_cypress = is_web && typeof window.Cypress !== 'undefined'
+export const is_cypress = env.is_cypress()
 
 /**
  * Checks if the code is running in a Node environment.
  * @returns {boolean} Returns true if the code is running in a Node environment, otherwise returns false.
  */
-export const is_node = typeof process !== 'undefined' && process.versions && process.versions?.node
+export const is_node = env.is_node()
 
 /**
  * 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 = typeof process !== 'undefined' && process.env?.FUNCTIONS_EMULATOR === 'true'
+export const is_emulator = env.is_emulator()
 
 // ///////////////////////////////
 // Mode and loglevel detection
 // ///////////////////////////////
 
-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' ) )
-
 /**
  * Represents the development environment.
  * @type {boolean}
  */
-export const dev = node_dev || web_dev
+export const dev = env.dev()
 
 /**
  * The log level for web applications.
  * @type {string} - Log level. Valid values are: 'info', 'warn', 'error'
  */
-export const web_loglevel = is_web && new URLSearchParams( location?.search ).get( 'loglevel' )
+export const web_loglevel = env.web_loglevel()
 
 /**
  * The log level for the Node environment.
  * @type {string} - Log level. Valid values are: 'info', 'warn', 'error'
  */
-export const node_loglevel = typeof process !== 'undefined' && process.env?.LOG_LEVEL
+export const node_loglevel = env.node_loglevel()
 
 
 /**
  * The log level used in the environment.
  * @type {string}
  */
-export const loglevel = web_loglevel || node_loglevel || dev ? 'info' : 'error'
+export const loglevel = env.loglevel()
 
 
 /**

package/modules/logging.js

@@ -1,8 +1,10 @@
 // Import environment data
-import { dev, is_cypress, is_emulator, loglevel } from "./environment.js"
+import { dev, env } from "./environment.js"
 
 const should_log = levels => {
 
+    const loglevel = env.loglevel()
+
     // Check if the loglevel matches this call
     const valid_levels = [ 'info', 'warn', 'error' ]
 
@@ -63,7 +65,7 @@ const annotate_messages = messages => {
 
 
     // If we are running in cypress, stringify the messages because they become unavailable in the console
-    if( is_cypress ) {
+    if( env.is_cypress() ) {
 
         try {
             messages = messages.map( message => JSON.stringify( message, null, 2 ) )
@@ -122,7 +124,7 @@ log.info = function( ...messages ) {
     const levels = [ 'info' ]
 
     // Log the messages if the loglevel matches
-    if( is_emulator || should_log( levels ) ) {
+    if( env.is_emulator() || should_log( levels ) ) {
 
         // Annotate the provided messages
         annotate_messages( messages )
@@ -170,7 +172,7 @@ log.error = function( ...messages ) {
 
     // Check if the loglevel matches this call
     const levels = [ 'error', 'warn', 'info' ]
-    const should_log = dev || levels.includes( loglevel )
+    const should_log = dev || levels.includes( env.loglevel() )
     if( !dev || !should_log ) return
 
     // Log the messages if the loglevel matches
@@ -180,4 +182,4 @@ log.error = function( ...messages ) {
 }
 
 // Set the loglevel on the log function
-log.loglevel = loglevel
+log.loglevel = env.loglevel()

package/modules/validations.js

@@ -11,4 +11,56 @@ export const email_regex = /(?:[a-z0-9!#$%&'*+/=?^_`{|}~-]+(?:\.[a-z0-9!#$%&'*+/
  * @param {string} string - The string to be sanitized.
  * @returns {string} - The sanitized string.
  */
-export const sanetise_string = string => `${ string }`.trim().toLowerCase()
+export const sanetise_string = string => `${ string }`.trim().toLowerCase()
+
+
+/**
+ * Checks if an object contains all the required properties.
+ * @param {Object} obj - The object to check.
+ * @param {Array} required_properties - The array of required properties.
+ * @param {boolean} [error_on_fail=true] - Determines whether to throw an error if properties are missing.
+ * @returns {boolean} - Returns true if all required properties are present, otherwise returns false.
+ * @throws {Error} - Throws an error if properties are missing and `error_on_fail` is true.
+ */
+export const require_props = ( obj={}, required_properties=[], error_on_fail=true ) => {
+
+    // Get the keys on the object
+    const keys = Object.keys( obj )
+
+    // Check that required props are present
+    const contains_all_required = required_properties.every( key => keys.includes( key ) )
+
+    // If properties are missing, throw errors or return false
+    if( error_on_fail && !contains_all_required ) throw new Error( `Missing required properties on object` )
+    if( !contains_all_required ) return false
+
+    // If all good, return true
+    return true
+
+}
+
+/**
+ * Validates the properties of an object against a list of allowed properties.
+ * 
+ * @param {Object} obj - The object to validate.
+ * @param {Array} allowed_properties - The list of allowed properties.
+ * @param {boolean} [error_on_fail=true] - Determines whether to throw an error if unknown properties are found.
+ * @returns {boolean} - Returns true if all properties are allowed, false otherwise.
+ * @throws {Error} - Throws an error if unknown properties are found and `error_on_fail` is true.
+ */
+export const allow_props = ( obj={}, allowed_properties=[], error_on_fail=true ) => {
+
+    // Get the keys on the object
+    const keys = Object.keys( obj )
+
+    // Check that required props are present
+    const unknownProperties = keys.filter( key => !allowed_properties.includes( key ) )
+
+    // If properties are missing, throw errors or return false
+    if( error_on_fail && unknownProperties.length ) throw new Error( `Unknown properties on object: ${ unknownProperties.join( ', ' ) }` )
+    if( unknownProperties.length ) return false
+
+    // If all good, return true
+    return true
+
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mentie",
-  "version": "0.1.15",
+  "version": "0.1.18",
   "description": "Mentor's toolbelt",
   "type": "module",
   "main": "index.js",
@@ -30,5 +30,8 @@
   "peerDependencies": {
     "promise-parallel-throttle": "^3.5.0",
     "promise-retry": "^2.0.1"
+  },
+  "dependencies": {
+    "safe-stable-stringify": "^2.4.3"
   }
 }