adaptorex/adaptor.js

Connect all your live interactive storytelling devices and software

/**
 * Contains useful unspecific classes and functions
 * may be required by all adaptor modules.
 * 
 * index.js will make all functions and the log available via global namespace
 *
 * @requires @apidevtools/json-schema-ref-parser
 * @requires npmlog
 * @requires events
 * @requires fs-extra
 * @requires nanoid
 * @requires os
 * 
 * @requires file
 *
 * @module adaptor
 * @copyright Lasse Marburg 2022
 * @license MIT
 */

const { EventEmitter } = require('events')
var npmlog = require('npmlog')
const ref_parser = require('@apidevtools/json-schema-ref-parser')
const {nanoid} = require('nanoid')
const os = require('os')

const fs = require('fs-extra')

const file = require('./file.js')

const { Variables } = require('./variables.js')

const npm_package = require('./package.json')
const { Plugin } = require ('./plugins/plugin.js')
const { PluginItem } = require ('./plugins/plugin_items.js')
const messenger = require ('./plugins/messenger.js')
const logic = require ('./plugins/logic/logic.js')
const socketio = require ('./plugins/socketio/socketio.js')

global.adaptor = {}

adaptor.info = npm_package
adaptor.locale = Intl.DateTimeFormat().resolvedOptions().locale

adaptor.parseJSON = Variables.parseJSON
adaptor.parseQuery = Variables.parseQuery

adaptor.messenger = messenger
adaptor.logic = logic
adaptor.socketio = socketio
adaptor.Plugin = Plugin
adaptor.PluginItem = PluginItem

/** webhook URL names for this adaptor instance and server */
adaptor.webhooks = []

/**
 * logging class based on [npmlog]{@link https://www.npmjs.com/package/npmlog}.
 * 
 * patches unexpected behavior of npmlog: log of Error object results in duplicated output.
 * see: https://github.com/npm/npmlog/issues/62 and https://github.com/npm/npmlog/blob/master/log.js#L182
 * 
 * Uses fs stream to write logs to logfile
 */
adaptor.Log = class {
	constructor() {
		npmlog.addLevel("debug",1000,{fg:"blue"})
		npmlog.addLevel("trace",500,{fg:"grey"})
        Object.assign(this, npmlog)

        this.error = function(prefix, message, ...args) {
            if(message instanceof Error && message.stack) {
                message = message.stack
            }
            npmlog.error(prefix, message, ...args)
        }
	}
	
	/**
	* initialize log write stream
	*/
	init(log_level, logfile_dir) {
		return new Promise((resolve, reject) => {
			npmlog.level = log_level
			file.mkdir(logfile_dir)
			let date = this.getPrettyDate()
			date = date.replace(/\:/gm, "-").slice(0, -4)
			let logfile = logfile_dir + '/' + date + '.log'
			
			var logstream = fs.createWriteStream(logfile, {flags:'a'})
            
			logstream.on('open', res => {
				npmlog.on('log', l => {
					logstream.write(this.getPrettyDate() + ' ' + l.level.toUpperCase() + ' ' + l.prefix + ' ' + l.message + '\n')
				})
				return resolve()
			})
		})
	}

    /**
     * Allow to connect socket for each of the dynamic namespaces /log/{level}
     * 
     * Publish each new log message if it is in the domain of the level
     * 
     * On connect publishes a list of latest 50 log records in the level domain
     * 
     * @param {Object} socket - socket.io connection object
     */
    createSocket(socketio) {
        socketio.on('connection', socket => {
            let level = socket.nsp.name.split('/').pop()
            
            let latest = []
            for(let r of npmlog.record) {
                if(npmlog.levels[r.level] >= npmlog.levels[level]) {
                    latest.push({id:r.id, level:r.level, topic:r.prefix, message: r.message})
                }
            }

            latest = latest.slice(-50)
            
            if(latest.length) {
                socket.emit('log', latest)
            }

            let log_event = l => {
                if(npmlog.levels[l.level] >= npmlog.levels[level]) {
                    socket.emit('log', [{id:l.id, level:l.level, topic:l.prefix, message: l.message}])
                }
            }
            
            npmlog.on('log', log_event)

            socket.on('disconnect', e => {
                npmlog.off('log', log_event)
            })
        })
    }
    
    /**
     * change current log level
     * - trace (show everything)
     * - debug
     * - info
     * - warn
     * - error
     * - silent (logging off)
     * @param {string} log_level 
     */
	setLevel(log_level) {
		npmlog.level = log_level
		console.log("log level changed to '" + log_level + "'")
    }
    
    /**
     * return current date time in following string format:
     * [year]-[month]-[day] [hour]-[minute]-[second]
     */
    getPrettyDate() {
        let tzoffset = (new Date()).getTimezoneOffset() * 60000 //offset in milliseconds
        return (new Date(Date.now() - tzoffset)).toISOString().slice(0, -1).replace('T', ' ')
    }

    /**
     * get log functions that prepends context info.
     * context log is itself a function that uses 'debug' log
     * 
     * @param {string} context - log context that is prepended to each log message
     * @returns {Object} - log functions that aut prepend context
     */
    getContextLog(context) {
        let context_log = msg => {
            this.debug(context, msg)
        }

        ['trace', 'debug', 'info', 'warn', 'error'].forEach(log_level => {
            context_log[log_level] = msg => {
                this[log_level](context, msg)
            }
        })

        return context_log
    }
}

adaptor.log = new adaptor.Log()
/**
 * Create an automated First in, first out queue. Runs a callback whenever something was added to the queue using the element as callback argument.
 * 
 * When callback is done queue will go on running the callback with the next items in stack until its.
 */
adaptor.Queue = class {
    /**
     * @param {function} callback - function to call on each element in queue
     */
    constructor(callback) {
        /** argument item list */
        this.items = []

        /** function to be called on each item */
        this.callback = callback

        /** emits empty event */
        this.event = new EventEmitter()

        /** queue will not accept any more items when joined */
        this.joined = false

        log.debug("queue", "create queue with function " + callback.name)
    }

    /**
     * add an item to queue. If queue is empty, run callback right away with item as argument.
     * 
     * goto next once callback resolves
     * 
     * use return_callback to feedback the result of queue callback
     *
     * @param {*} item - argument for callback put into queue
     * @param {function} return_callback - is called with result arg once queue callback resolves
     */
    put(item, return_callback) {
        let elem = {
            "arg":item,
            "call":return_callback
        }
        if(this.joined) {
            return_callback(undefined)
            return
        }
        if(this.items.length == 0) {
            this.execute(elem)
        }
        this.items.push(elem)
    }

    execute(elem) {
        Promise.resolve(this.callback(elem["arg"]))
        .then(result => {
            elem.call(result)
            this.next()
        })
        .catch(err => {
            this.items = []
            elem.call({error: err})
        })
    }

    /**
     * release latest element from queue. If there is another, run callback with next element.
     * 
     * When callback resolves, proceed with next element if any.
     * 
     * Emit empty event once there are no more elements enqueued
     */
    next() {
        if(this.items.length > 0) {
            this.items.shift()
        }
        
        if(this.items.length > 0) {
            this.execute(this.items[0])
        } else {
            this.event.emit('empty')
        }
    }

    /**
     * wait for queue to finish. Block adding of further elements until finished.
     *
     * @returns {Promise} - resolves once queue is done and empty
     */
    join() {
        return new Promise((resolve, reject) => {
            this.joined = true
            if(this.items.length > 0) {
                this.event.on('empty', e => {
                    this.joined = false
                    return resolve()
                })
            } else {
                this.joined = false
                return resolve()
            }
        })
    }

    /**
     * join queue but only wait for current item to finish.
     * Remove all leftover items.
     */
    cancel() {
        if(this.items.length > 1) {
            this.items = [this.items.shift()]
            log.debug("queue", "cancel and drop " + this.items.length + " items")
        }
        
        return this.join()
    }
}

/**
 * 
 * @returns object of local ip4 IP adresses (name:ip)
 */
adaptor.getIPs = function() {

    const interfaces = os.networkInterfaces()
    const results = Object.create(null)

    for (const name of Object.keys(interfaces)) {
        for (const net of interfaces[name]) {
        if (net.family === 'IPv4' && !net.internal) {
            if (!results[name]) {
                results[name] = []
            }
                results[name].push(net.address)
            }
        }
    }
    return results
}

/**
 * Generate short Unique Identifier String
 *
 * @returns {string} - uid string
 */
adaptor.createId = function() {
    return nanoid(8)
}

/**
 * Find out if a string or number is an integer value
 * 
 * @param {string|number} value 
 * @returns {boolean} - true if value is int or string that can be parsed to int
 */
adaptor.isInt = function(value) {
    return !isNaN(value) && 
        parseInt(Number(value)) == value && 
        !isNaN(parseInt(value, 10));
}
 
/**
* check if Object has any properties
* Checkout this post:
* https://coderwall.com/p/_g3x9q/how-to-check-if-javascript-object-is-empty
*
* @param {Object} obj - object to check on emptyness
*
* @returns {boolean} false if object is not empty
*/
adaptor.isEmpty = function(obj) {
    for(var key in obj) {
        if(obj.hasOwnProperty(key))
            return false
    }
    return true
}


/** 
 * see if a list of properties are all own properties of an object
 * 
 * @param {Object} obj - Object to review
 * @param {Array} properties - list of property names (each a string)
 *  
 * @returns {boolean} - true if all properties are own properties of object. Otherwise false
 */
adaptor.hasOwnProperties = function(obj, properties) {
    for (var i = 0; i < properties.length; i++) {
        if (!obj.hasOwnProperty(properties[i]))
            return false
    }
    return true
}

/**
* address object property with '.' seperated string   
* Comes in handy especially when working with Mongodb and nested document find queries.  
* Mongo uses [dot notation]{@link https://docs.mongodb.com/manual/core/document/#document-dot-notation}
* Inspired by:
* {@link https://stackoverflow.com/questions/6491463/accessing-nested-javascript-objects-with-string-key/6491621#6491621}
*
* @param {Object} o - some Object
* @param {string} s - some string that finds nested properties with '.' notation
* 
* @returns {*} - value or object that was found in '.' noted path. undefined if path doesn't exist in o
*/
adaptor.getPath = function(o, s) {
    s = s.replace(/\[(\w+)\]/g, '.$1') // convert indexes to properties
    s = s.replace(/^\./, '')          // strip a leading dot
    var a = s.split('.')
    for (var i = 0, n = a.length; i < n; ++i) {
        var k = a[i]
        if(typeof o !== "object" || Array.isArray(o)) {
            log.warn("getPath", o + " is not a valid object")
            return
        }
        if (k in o) {
            o = o[k]
        } else {
            return
        }
    }
    return o
}

/**
* assign object property with '.' seperated string path
*
* Inspired by:
* {@link https://stackoverflow.com/questions/13719593/how-to-set-object-property-of-object-property-of-given-its-string-name-in-ja/13719799#13719799}
*
* @param {Object} obj - object to assign value to
* @param {string} prop - path
* @param {*} value - value to assign to object at path
*/
adaptor.assignPath = function(obj, prop, value) {
    if (typeof prop === "string")
        prop = prop.split(".")

    if (prop.length > 1) {
        var e = prop.shift()
        adaptor.assignPath(obj[e] =
                 Object.prototype.toString.call(obj[e]) === "[object Object]"
                 ? obj[e]
                 : {},
               prop,
               value);
    } else {
			obj[prop[0]] = value
	}
}

/**
* check if Objects have the same key/value pairs (keys also have to be in the same Order)
* Simple string comparison
* @todo find a more efficient and safe way then JSON.stringify comparison
* @param {Object} objA - compare Object A
* @param {Object} objB - compare Object B
*/
adaptor.equalValues = function(objA, objB) {
	if(JSON.stringify(objA) == JSON.stringify(objB)) {
		return true
	} else {
		return false
	}
}

/**
* compare two objects and return what changes happened during the transition from
* one object to the other. Checks for equality in each property and recognizes if
* a property has changed (updated), is new (updated) or was removed.
*
* @param {Object} original - Original object
* @param {Object} changed - Object that derived from original Object
*
* @returns {Object} 'updated' contains all keys and their values that are not equal or have
* no equal key - value pair in the original object. 'removed' contains a list of all missing properties
* in the changed object
*/
adaptor.changes = function(original_object, changed_object) {
	let changes = {updated:{},removed:[]}
	for(let key in original_object) {
		if(changed_object.hasOwnProperty(key)) {
			if(!adaptor.equalValues(changed_object[key], original_object[key])) {
				changes.updated[key] = changed_object[key]
			}
		} else {
			changes.removed.push(key)
		}
	}
	for(let key in changed_object) {
		if(!original_object.hasOwnProperty(key)) {
			changes.updated[key] = changed_object[key]
		}
	}
	return changes
}

/**
* make an object clone using serialization. Leave no references even in nested properties.
* This does not work with complex object properties like functions, classes, dates etc.!
*
* @param {Object} source - Object to be deep cloned
*
* @returns {Object} - clone of object
*/
adaptor.deepClone = function(source) {
    return JSON.parse(JSON.stringify(source))
}

/**
* perform a function on all Object properties, including nested properties.
* 
* is not being used to date.
*
* similar to, though way more primitive than, lodash {@link https://lodash.com/docs/4.17.15#transform|_transform}
* @param {Object} obj - Object to be transformed
* @param {function} funct - function to perform on Object properties
*/
adaptor.transform = function(obj, funct) {
    var result = null

    if(obj instanceof Array) {
        for(var i = 0; i < theObject.length; i++) {
            result = transform(obj[i], funct)
            if (result) {
                break
            }   
        }
    } else {
        for(var prop in obj) {
						funct(prop, obj)
            if(obj[prop] instanceof Object || obj[prop] instanceof Array) {
                result = transform(obj[prop], funct)
                if (result) {
                    break
                }
            } 
        }
    }
    return result
}

/**
 * Use json-schema-ref-parser to resolve $ref references in json schema
 * 
 * @param {Object} obj - json schema with references to be resolved
 */
adaptor.dereference = async function(obj) {
    return ref_parser.dereference(obj)
}

/**
* check if Objects is of type object and not an array or null
* @param  {*}       obj   Object to check
* @return {Boolean} 
*/
adaptor.isObject = function(value) {
    return (typeof value === 'object' && !Array.isArray(value) && value !== null)
}