/** * A utility class to help make it easier to access the data stores * @extends {Map} */ class Collection extends Map { constructor(iterable) { super(iterable); this._array = null; this._keyArray = null; } set(key, val) { super.set(key, val); this._array = null; this._keyArray = null; } delete(key) { super.delete(key); this._array = null; this._keyArray = null; } /** * Creates an ordered array of the values of this collection, and caches it internally. The array will only be * reconstructed if an item is added to or removed from the collection, or if you add/remove elements on the array. * @returns {Array} * @example * // identical to: * Array.from(collection.values()); */ array() { if (!this._array || this._array.length !== this.size) this._array = Array.from(this.values()); return this._array; } /** * Creates an ordered array of the keys of this collection, and caches it internally. The array will only be * reconstructed if an item is added to or removed from the collection, or if you add/remove elements on the array. * @returns {Array} * @example * // identical to: * Array.from(collection.keys()); */ keyArray() { if (!this._keyArray || this._keyArray.length !== this.size) this._keyArray = Array.from(this.keys()); return this._keyArray; } /** * Returns the first item in this collection. * @returns {*} */ first() { return this.values().next().value; } /** * Returns the first key in this collection. * @returns {*} */ firstKey() { return this.keys().next().value; } /** * Returns the last item in this collection. This is a relatively slow operation, * since an array copy of the values must be made to find the last element. * @returns {*} */ last() { const arr = this.array(); return arr[arr.length - 1]; } /** * Returns the last key in this collection. This is a relatively slow operation, * since an array copy of the keys must be made to find the last element. * @returns {*} */ lastKey() { const arr = this.keyArray(); return arr[arr.length - 1]; } /** * Returns a random item from this collection. This is a relatively slow operation, * since an array copy of the values must be made to find a random element. * @returns {*} */ random() { const arr = this.array(); return arr[Math.floor(Math.random() * arr.length)]; } /** * Returns a random key from this collection. This is a relatively slow operation, * since an array copy of the keys must be made to find a random element. * @returns {*} */ randomKey() { const arr = this.keyArray(); return arr[Math.floor(Math.random() * arr.length)]; } /** * Returns an array of items where `item[prop] === value` of the collection * @param {string} prop The property to test against * @param {*} value The expected value * @returns {array} * @example * collection.findAll('username', 'Bob'); */ findAll(prop, value) { if (typeof prop !== 'string') throw new TypeError('Key must be a string.'); if (typeof value === 'undefined') throw new Error('Value must be specified.'); const results = []; for (const item of this.values()) { if (item[prop] === value) results.push(item); } return results; } /** * Returns a single item where `item[prop] === value`, or the given function returns `true`. * In the latter case, this is identical to * [Array.find()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/find). * @param {string|function} propOrFn The property to test against, or the function to test with * @param {*} [value] The expected value - only applicable and required if using a property for the first argument * @returns {*} * @example * collection.find('username', 'Bob'); * @example * collection.find(val => val.username === 'Bob'); */ find(propOrFn, value) { if (typeof propOrFn === 'string') { if (typeof value === 'undefined') throw new Error('Value must be specified.'); for (const item of this.values()) { if (item[propOrFn] === value) return item; } return null; } else if (typeof propOrFn === 'function') { for (const [key, val] of this) { if (propOrFn(val, key, this)) return val; } return null; } else { throw new Error('First argument must be a property string or a function.'); } } /* eslint-disable max-len */ /** * Returns the key of the item where `item[prop] === value`, or the given function returns `true`. * In the latter case, this is identical to * [Array.findIndex()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/findIndex). * @param {string|function} propOrFn The property to test against, or the function to test with * @param {*} [value] The expected value - only applicable and required if using a property for the first argument * @returns {*} * @example * collection.findKey('username', 'Bob'); * @example * collection.findKey(val => val.username === 'Bob'); */ /* eslint-enable max-len */ findKey(propOrFn, value) { if (typeof propOrFn === 'string') { if (typeof value === 'undefined') throw new Error('Value must be specified.'); for (const [key, val] of this) { if (val[propOrFn] === value) return key; } return null; } else if (typeof propOrFn === 'function') { for (const [key, val] of this) { if (propOrFn(val, key, this)) return key; } return null; } else { throw new Error('First argument must be a property string or a function.'); } } /** * Returns true if the collection has an item where `item[prop] === value` * @param {string} prop The property to test against * @param {*} value The expected value * @returns {boolean} * @example * if (collection.exists('username', 'Bob')) { * console.log('user here!'); * } */ exists(prop, value) { return Boolean(this.find(prop, value)); } /** * Identical to * [Array.filter()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/filter), * but returns a Collection instead of an Array. * @param {function} fn Function used to test (should return a boolean) * @param {Object} [thisArg] Value to use as `this` when executing function * @returns {Collection} */ filter(fn, thisArg) { if (thisArg) fn = fn.bind(thisArg); const results = new Collection(); for (const [key, val] of this) { if (fn(val, key, this)) results.set(key, val); } return results; } /** * Identical to * [Array.filter()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/filter). * @param {function} fn Function used to test (should return a boolean) * @param {Object} [thisArg] Value to use as `this` when executing function * @returns {Collection} */ filterArray(fn, thisArg) { if (thisArg) fn = fn.bind(thisArg); const results = []; for (const [key, val] of this) { if (fn(val, key, this)) results.push(val); } return results; } /** * Identical to * [Array.map()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/map). * @param {function} fn Function that produces an element of the new array, taking three arguments * @param {*} [thisArg] Value to use as `this` when executing function * @returns {array} */ map(fn, thisArg) { if (thisArg) fn = fn.bind(thisArg); const arr = new Array(this.size); let i = 0; for (const [key, val] of this) arr[i++] = fn(val, key, this); return arr; } /** * Identical to * [Array.some()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/some). * @param {function} fn Function used to test (should return a boolean) * @param {Object} [thisArg] Value to use as `this` when executing function * @returns {boolean} */ some(fn, thisArg) { if (thisArg) fn = fn.bind(thisArg); for (const [key, val] of this) { if (fn(val, key, this)) return true; } return false; } /** * Identical to * [Array.every()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/every). * @param {function} fn Function used to test (should return a boolean) * @param {Object} [thisArg] Value to use as `this` when executing function * @returns {boolean} */ every(fn, thisArg) { if (thisArg) fn = fn.bind(thisArg); for (const [key, val] of this) { if (!fn(val, key, this)) return false; } return true; } /** * Identical to * [Array.reduce()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/reduce). * @param {function} fn Function used to reduce * @param {*} [startVal] The starting value * @returns {*} */ reduce(fn, startVal) { let currentVal = startVal; for (const [key, val] of this) currentVal = fn(currentVal, val, key, this); return currentVal; } /** * Combines this collection with others into a new collection. None of the source collections are modified. * @param {Collection} collections Collections to merge * @returns {Collection} * @example const newColl = someColl.concat(someOtherColl, anotherColl, ohBoyAColl); */ concat(...collections) { const newColl = new this.constructor(); for (const [key, val] of this) newColl.set(key, val); for (const coll of collections) { for (const [key, val] of coll) newColl.set(key, val); } return newColl; } /** * If the items in this collection have a delete method (e.g. messages), invoke * the delete method. Returns an array of promises * @returns {Promise[]} */ deleteAll() { const returns = []; for (const item of this.values()) { if (item.delete) returns.push(item.delete()); } return returns; } } module.exports = Collection;