Source: data/undercomplicate/joins.js

  1. /**
  2.  * Very simple client-side data joins. Useful for aligning records from two datasets based on a common key.
  3.  */
  4. import { clone } from './util';
  7. /**
  8.  * Simple grouping function, used to identify sets of records for joining.
  9.  *
  10.  * Used internally by join helpers, exported mainly for unit testing
  11.  * @memberOf module:undercomplicate
  12.  * @param {object[]} records
  13.  * @param {string} group_key
  14.  * @returns {Map<any, any>}
  15.  */
  16. function groupBy(records, group_key) {
  17.     const result = new Map();
  18.     for (let item of records) {
  19.         const item_group = item[group_key];
  21.         if (typeof item_group === 'undefined') {
  22.             throw new Error(`All records must specify a value for the field "${group_key}"`);
  23.         }
  24.         if (typeof item_group === 'object') {
  25.             // If we can't group this item, then don't (exclude object, array, map, null, etc from grouping keys)
  26.             throw new Error('Attempted to group on a field with non-primitive values');
  27.         }
  29.         let group = result.get(item_group);
  30.         if (!group) {
  31.             group = [];
  32.             result.set(item_group, group);
  33.         }
  34.         group.push(item);
  35.     }
  36.     return result;
  37. }
  40. function _any_match(type, left, right, left_key, right_key) {
  41.     // Helper that consolidates logic for all three join types
  42.     const right_index = groupBy(right, right_key);
  43.     const results = [];
  44.     for (let item of left) {
  45.         const left_match_value = item[left_key];
  46.         const right_matches = right_index.get(left_match_value) || [];
  47.         if (right_matches.length) {
  48.             // Record appears on both left and right; equiv to an inner join
  49.             results.push(...right_matches.map((right_item) => Object.assign({}, clone(right_item), clone(item))));
  50.         } else if (type !== 'inner') {
  51.             // Record appears on left but not right
  52.             results.push(clone(item));
  53.         }
  54.     }
  56.     if (type === 'outer') {
  57.         // Outer join part! We've already added all left-only and left-right matches; all that's left is the items that only appear on right side
  58.         const left_index = groupBy(left, left_key);
  59.         for (let item of right) {
  60.             const right_match_value = item[right_key];
  61.             const left_matches = left_index.get(right_match_value) || [];
  62.             if (!left_matches.length) {
  63.                 results.push(clone(item));
  64.             }
  65.         }
  66.     }
  67.     return results;
  68. }
  70. /**
  71.  * Equivalent to LEFT OUTER JOIN in SQL. Return all left records, joined to matching right data where appropriate.
  72.  * @memberOf module:undercomplicate
  73.  * @param {Object[]} left The left side recordset
  74.  * @param {Object[]} right The right side recordset
  75.  * @param {string} left_key The join field in left records
  76.  * @param {string} right_key The join field in right records
  77.  * @returns {Object[]}
  78.  */
  79. function left_match(left, right, left_key, right_key) {
  80.     return _any_match('left', ...arguments);
  81. }
  83. /**
  84.  * Equivalent to INNER JOIN in SQL. Only return record joins if the key field has a match on both left and right.
  85.  * @memberOf module:undercomplicate
  86.  * @param {object[]} left The left side recordset
  87.  * @param {object[]} right The right side recordset
  88.  * @param {string} left_key The join field in left records
  89.  * @param {string} right_key The join field in right records
  90.  * @returns {Object[]}
  91.  */
  92. function inner_match(left, right, left_key, right_key) {
  93.     return _any_match('inner', ...arguments);
  94. }
  96. /**
  97.  * Equivalent to FULL OUTER JOIN in SQL. Return records in either recordset, joined where appropriate.
  98.  * @memberOf module:undercomplicate
  99.  * @param {object[]} left The left side recordset
  100.  * @param  {object[]} right The right side recordset
  101.  * @param {string} left_key The join field in left records
  102.  * @param {string} right_key The join field in right records
  103.  * @returns {Object[]}
  104.  */
  105. function full_outer_match(left, right, left_key, right_key) {
  106.     return _any_match('outer', ...arguments);
  107. }
  109. export {left_match, inner_match, full_outer_match, groupBy};