@qtoggle/qui 0.0.0

package/js/utils/object.js

@@ -0,0 +1,324 @@
+/**
+ * @namespace qui.utils.object
+ */
+
+import * as ArrayUtils from './array.js'
+
+
+/**
+ * Use Object's `hasOwnProperty` and never rely on whatever `hasOwnProperty` incoming objects have.
+ * @private
+ * @param {Object} obj
+ * @param {String} prop
+ * @returns {Boolean}
+ */
+function hasOwnProperty(obj, prop) {
+    return Object.prototype.hasOwnProperty.call(obj, prop)
+}
+
+/**
+ * Tell if a value is a pure object.
+ * @param {*} value value to test
+ * @returns {Boolean}
+ */
+export function isObject(value) {
+    return (value != null) && (value.constructor === Object)
+}
+
+/**
+ * Create an object from a list of entries. Each entry is an array of two elements: the key and its associated value.
+ * @alias qui.utils.object.fromEntries
+ * @param {Array[]} entries
+ * @returns {Object}
+ */
+export function fromEntries(entries) {
+    let obj = {}
+    entries.forEach(function (entry) {
+        obj[entry[0]] = entry[1]
+    })
+
+    return obj
+}
+
+/**
+ * Search an object for an entry that matches a condition and return the corresponding key.
+ * @alias qui.utils.object.findKey
+ * @param {Object} obj
+ * @param {Function} func function that implements the search condition; it is called with value and key as arguments
+ * @param {*} [thisArg] optional `this` argument to be used when calling `func`
+ * @returns {String} the matched key, or `undefined` if no entry matched
+ */
+export function findKey(obj, func, thisArg = null) {
+    let entry = Object.entries(obj).find(function (entry) {
+        if (func.call(thisArg, entry[1], entry[0])) {
+            return true
+        }
+    })
+
+    if (entry) {
+        return entry[0]
+    }
+
+    return undefined
+}
+
+/**
+ * Search an object for an entry that matches a condition and return the corresponding value.
+ * @alias qui.utils.object.findValue
+ * @param {Object} obj
+ * @param {Function} func function that implements the search condition; it is called with key and value as arguments
+ * @param {*} [thisArg] optional `this` argument to be used when calling `func`
+ * @returns {String} the matched value, or `undefined` if no entry matched
+ */
+export function findValue(obj, func, thisArg = null) {
+    let entry = Object.entries(obj).find(function (entry) {
+        if (func.call(thisArg, entry[0], entry[1])) {
+            return true
+        }
+    })
+
+    if (entry) {
+        return entry[1]
+    }
+
+    return undefined
+}
+
+/**
+ * Parse an object, calling a function for each entry.
+ * @alias qui.utils.object.forEach
+ * @param {Object} obj
+ * @param {Function} func function to be called for each entry; it is called with the entry (array of key and value) as
+ * argument
+ * @param {*} [thisArg] optional `this` argument to be used when calling `func`
+ * @param {Function} [sortKeyFunc] optional function used to extract key from each entry when sorting entries; no
+ * sorting is performed unless this function is supplied
+ */
+export function forEach(obj, func, thisArg = null, sortKeyFunc = null) {
+    let entries = Object.entries(obj)
+    if (sortKeyFunc) {
+        ArrayUtils.sortKey(entries, sortKeyFunc)
+    }
+    entries.forEach(function (entry) {
+        func.call(thisArg, entry[0], entry[1])
+    })
+}
+
+/**
+ * Filter object entries. This function is similar to Array's `filter` method, but applied on objects.
+ * @alias qui.utils.object.filter
+ * @param {Object} obj
+ * @param {Function} func a function called with each key and value as arguments; only entries for which this function
+ * returns a true value will be kept
+ * @param {*} [thisArg] optional `this` argument to be used when calling `func`
+ * @returns {Object} the filtered object
+ */
+export function filter(obj, func, thisArg = null) {
+    return fromEntries(Object.entries(obj).filter(entry => func.call(thisArg, entry[0], entry[1])))
+}
+
+/**
+ * Map object entries. This function is similar to Array's `map` method, but applied on objects.
+ * @alias qui.utils.object.map
+ * @param {Object} obj
+ * @param {Function} func a function called with each key and value as arguments; it is expected to return an array with
+ * two elements, the mapped key and value
+ * @param {*} [thisArg] optional `this` argument to be used when calling `func`
+ * @returns {Object} the mapped object
+ */
+export function map(obj, func, thisArg = null) {
+    return fromEntries(Object.entries(obj).map(entry => func.call(thisArg, entry[0], entry[1])))
+}
+
+/**
+ * Map object keys.
+ * @alias qui.utils.object.mapKey
+ * @param {Object} obj
+ * @param {Function} func a function called with each key and value as arguments; it is expected to return the mapped
+ * key
+ * @param {*} [thisArg] optional `this` argument to be used when calling `func`
+ * @returns {Object} the mapped object
+ */
+export function mapKey(obj, func, thisArg = null) {
+    return fromEntries(Object.entries(obj).map(entry => [func.call(thisArg, entry[0], entry[1]), entry[1]]))
+}
+
+/**
+ * Map object values.
+ * @alias qui.utils.object.mapValue
+ * @param {Object} obj
+ * @param {Function} func a function called with each value and key as arguments; it is expected to return the mapped
+ * value
+ * @param {*} [thisArg] optional `this` argument to be used when calling `func`
+ * @returns {Object} the mapped object
+ */
+export function mapValue(obj, func, thisArg = null) {
+    return fromEntries(Object.entries(obj).map(entry => [entry[0], func.call(thisArg, entry[1], entry[0])]))
+}
+
+/**
+ * Assign values to an object, *in place*, but only if corresponding keys are missing.
+ * @alias qui.utils.object.assignDefault
+ * @param {Object} dest
+ * @param {Object} src
+ * @returns {Object} the given `dest` object
+ */
+export function assignDefault(dest, src) {
+    Object.keys(src).forEach(function (key) {
+        if (key in dest) {
+            return
+        }
+
+        dest[key] = src[key]
+    })
+
+    return dest
+}
+
+/**
+ * Combine two or more objects into a single object by merging their keys and values.
+ * @alias qui.utils.object.combine
+ * @param {...Object} objs objects to combine
+ * @returns {Object} the combined object
+ */
+export function combine(...objs) {
+    let combined = {}
+    objs.forEach(function (obj) {
+        Object.keys(obj).forEach(function (key) {
+            combined[key] = obj[key]
+        })
+    })
+
+    return combined
+}
+
+/**
+ * Clone an object by copying its entries into a new object. Optionally recurse into inner objects and arrays.
+ * @alias qui.utils.object.copy
+ * @param {Object} orig original object to copy
+ * @param {Boolean} [deep] set to `true` to perform a *deep* copy (defaults to `false`)
+ * @returns {Object}
+ */
+export function copy(orig, deep = false) {
+    if (deep) {
+        let type = typeof orig
+        if (orig === undefined || orig === null ||
+            type === 'number' || type === 'string' ||
+            type === 'boolean' || type === 'function') {
+
+            return orig
+        }
+        else if (Array.isArray(orig)) {
+            return orig.map(e => copy(e, /* deep = */ true))
+        }
+        else if (orig.constructor === Object) { /* Plain object */
+            return map(orig, (k, v) => [k, copy(v, /* deep = */ true)])
+        }
+        else {
+            return orig
+        }
+    }
+    else {
+        return fromEntries(Object.entries(orig))
+    }
+}
+
+/**
+ * Remove a key from an object, returning it.
+ * @alias qui.utils.object.pop
+ * @param {Object} obj
+ * @param {String} key
+ * @param {*} [def] an optional default value to return if key is missing
+ * @returns {*}
+ */
+export function pop(obj, key, def = null) {
+    if (!(key in obj)) {
+        return def
+    }
+
+    let value = obj[key]
+    delete obj[key]
+
+    return value
+}
+
+/**
+ * Insert a value into an object, but only if it's not already present, and return it.
+ * @alias qui.utils.object.setDefault
+ * @param {Object} obj
+ * @param {String} key
+ * @param {*} value
+ * @returns {*}
+ */
+export function setDefault(obj, key, value) {
+    if (key in obj) {
+        return obj[key]
+    }
+
+    return (obj[key] = value)
+}
+
+/**
+ * A deep equals() operator that will recursively compare any non-primitive objects to validate the equality.
+ * @alias qui.utils.object.deepEquals
+ * @param {Object} obj1 the first object of the comparison
+ * @param {Object} obj2 the second object of the comparison
+ * @returns {Boolean} `true` if the two objects are deeply equal, `false`otherwise
+ */
+export function deepEquals(obj1, obj2) {
+    if (obj1 === obj2) {
+        return true
+    }
+
+    if (typeof obj1 !== typeof obj2) {
+        return false
+    }
+
+    if (Array.isArray(obj1)) {
+        if (!Array.isArray(obj2)) {
+            return false
+        }
+
+        if (obj1.length !== obj2.length) {
+            return false
+        }
+
+        for (let i = 0; i < obj1.length; i++) {
+            if (!deepEquals(obj1[i], obj2[i])) {
+                return false
+            }
+        }
+
+        return true
+    }
+    else if (obj1 instanceof Object) {
+        if (!(obj2 instanceof Object)) {
+            return false
+        }
+
+        for (let key in obj1) {
+            if (hasOwnProperty(obj1, key)) {
+                if (!hasOwnProperty(obj2, key)) {
+                    return false
+                }
+
+                if (!deepEquals(obj1[key], obj2[key])) {
+                    return false
+                }
+            }
+        }
+
+        for (let key in obj2) {
+            if (hasOwnProperty(obj2, key)) {
+                if (!hasOwnProperty(obj1, key)) {
+                    return false
+                }
+            }
+        }
+
+        return true
+    }
+    else {
+        return false
+    }
+}

package/js/utils/promise.js

@@ -0,0 +1,49 @@
+/**
+ * @namespace qui.utils.promise
+ */
+
+import {TimeoutError}     from '$qui/base/errors.js'
+import {asap as asapFunc} from '$qui/utils/misc.js'
+
+
+/**
+ * Return a promise that resolves as soon as possible, in the next main loop iteration.
+ * @alias qui.utils.promise.asap
+ * @returns {Promise}
+ */
+export function asap() {
+    return new Promise(function (resolve) {
+        asapFunc(resolve)
+    })
+}
+
+/**
+ * Return a promise that resolves later, after a specified number of seconds.
+ * @alias qui.utils.promise.later
+ * @param {Number} timeout the timeout, in milliseconds
+ * @param {*} [arg] an optional argument to pass along the promise chain
+ * @returns {Promise}
+ */
+export function later(timeout, arg) {
+    return new Promise(function (resolve) {
+        setTimeout(function () {
+            resolve(arg)
+        }, timeout)
+    })
+}
+
+/**
+ * Run a promise with a timeout. If the promise is not fulfilled within the given timeout, the returned promise will be
+ * rejected with {@link qui.base.errors.TimeoutError}
+ * @alias qui.utils.promise.withTimeout
+ * @param {Promise} promise the promise to run
+ * @param {Number} timeout the timeout, in milliseconds
+ * @returns {Promise} the promise with timeout
+ */
+export function withTimeout(promise, timeout) {
+    let timeoutPromise = later(timeout).then(function () {
+        throw new TimeoutError(`Operation timed out after ${timeout} milliseconds`)
+    })
+
+    return Promise.race([promise, timeoutPromise])
+}

package/js/utils/string.js

@@ -0,0 +1,192 @@
+/**
+ * @namespace qui.utils.string
+ */
+
+import * as ObjectUtils from '$qui/utils/object.js'
+
+
+const REGEX_ESCAPE_CHARS = '.\\+*?[^]$(){}=!<>|:-'
+
+
+/**
+ * Replace all occurrences of `oldStr` in `s` with `newStr`.
+ * @alias qui.utils.string.replaceAll
+ * @param {String} s
+ * @param {String} oldStr
+ * @param {String} newStr
+ * @returns {String}
+ */
+export function replaceAll(s, oldStr, newStr) {
+    let p
+    while ((p = s.indexOf(oldStr)) >= 0) {
+        s = s.substring(0, p) + newStr + s.substring(p + oldStr.length, s.length)
+    }
+
+    return s.toString()
+}
+
+/**
+ * Replace percent-formatted placeholders in a string with given values.
+ *
+ * Placeholders can be given as `"%s"`, `"%d"` or `"%f"`, in which case `args` will be used, in order, to replace
+ * them.
+ *
+ * Placeholders can also be given as `"%(name)s"`, `"%(name)d"` or `"%(name)f"`, in which case the first argument in
+ * `args` will be used as an object that maps names to replacement values.
+ *
+ * @alias qui.utils.string.formatPercent
+ * @param {String} text
+ * @param {...*} args values used to replace the placeholders
+ * @returns {String}
+ */
+export function formatPercent(text, ...args) {
+    let rex = new RegExp('%[sdf]')
+    let match, i = 0
+    while ((match = text.match(rex))) {
+        text = text.substring(0, match.index) + args[i] + text.substring(match.index + 2)
+        i++
+    }
+
+    if (i) { /* %s format used */
+        text = text.replace(new RegExp('%%', 'g'), '%')
+
+        return text
+    }
+
+    let keywords = args[0] || {}
+
+    ObjectUtils.forEach(keywords, function (key, value) {
+        text = text.replace(new RegExp(`%\\(${key}\\)s`, 'g'), value.toString())
+        text = text.replace(new RegExp(`%\\(${key}\\)d`, 'g'), value.toString())
+        text = text.replace(new RegExp(`%\\(${key}\\)f`, 'g'), value.toString())
+    })
+
+    text = text.replace('%%', '%')
+
+    return text
+}
+
+/**
+ * Transform a regular text to its camel-case representation.
+ * @alias qui.utils.string.camelize
+ * @param {String} s
+ * @returns {String}
+ */
+export function camelize(s) {
+    s = s.replace(/(?:^|[-_])(\w)/g, function (_, c) {
+        return c ? c.toUpperCase() : ''
+    })
+
+    return s.substr(0, 1).toLowerCase() + s.substr(1)
+}
+
+/**
+ * Transform a camel-case string into its dash-separated representation.
+ * @alias qui.utils.string.uncamelize
+ * @param {String} s
+ * @param {String} [chr] separator character (defaults to dash `"-"`)
+ * @returns {String}
+ */
+export function uncamelize(s, chr = '-') {
+    return s.replace(/([A-Z])/g, function ($1) {
+        return chr + $1.toLowerCase()
+    }).replace(new RegExp(`^${chr}`), '')
+}
+
+/**
+ * Transform the starting letter of each word of a text to uppercase.
+ * @alias qui.utils.string.title
+ * @param {String} s
+ * @returns {String}
+ */
+export function title(s) {
+    s = s.replace(/\s(\w)/g, function (_, c) {
+        return c ? ` ${c.toUpperCase()}` : ' '
+    })
+
+    return s.substr(0, 1).toUpperCase() + s.substr(1)
+}
+
+/**
+ * Encode a string to UTF8.
+ * @alias qui.utils.string.toUTF8
+ * @param {String} s
+ * @returns {String}
+ */
+export function toUTF8(s) {
+    s = s.replace(new RegExp('\\r\\n'), '\n')
+    let utf = ''
+
+    for (let n = 0; n < s.length; n++) {
+        let c = s.charCodeAt(n)
+
+        if (c < 128) {
+            utf += String.fromCharCode(c)
+        }
+        else if ((c > 127) && (c < 2048)) {
+            utf += String.fromCharCode((c >> 6) | 192)
+            utf += String.fromCharCode((c & 63) | 128)
+        }
+        else {
+            utf += String.fromCharCode((c >> 12) | 224)
+            utf += String.fromCharCode(((c >> 6) & 63) | 128)
+            utf += String.fromCharCode((c & 63) | 128)
+        }
+    }
+
+    return utf
+}
+
+/**
+ * Decode a string from UTF8.
+ * @alias qui.utils.string.fromUTF8
+ * @param {String} s
+ * @returns {String}
+ */
+export function fromUTF8(s) {
+    let result = ''
+    let i = 0
+    let c1 = 0
+    let c2 = 0
+    let c3 = 0
+
+    while (i < s.length) {
+        c1 = s.charCodeAt(i)
+
+        if (c1 < 128) {
+            result += String.fromCharCode(c1)
+            i++
+        }
+        else if ((c1 > 191) && (c1 < 224)) {
+            c2 = s.charCodeAt(i + 1)
+            result += String.fromCharCode(((c1 & 31) << 6) | (c2 & 63))
+            i += 2
+        }
+        else {
+            c2 = s.charCodeAt(i + 1)
+            c3 = s.charCodeAt(i + 2)
+            result += String.fromCharCode(((c1 & 15) << 12) | ((c2 & 63) << 6) | (c3 & 63))
+            i += 3
+        }
+    }
+
+    return result
+}
+
+/**
+ * Intelligently search for an input sequence in a string. All characters in the input sequence must be present in the
+ * searched string, in the respective order.
+ * @alias qui.utils.string.intelliSearch
+ * @param {String} s string to search into
+ * @param {String} search string to search for
+ * @returns {?RegExpMatchArray}
+ */
+export function intelliSearch(s, search) {
+    let rexStr = Array.prototype.map.call(search, function (c) {
+        return `${REGEX_ESCAPE_CHARS.includes(c) ? '\\' : ''}${c}.*`
+    }).join('')
+
+    let rex = new RegExp(rexStr, 'i')
+
+    return s.match(rex)
+}