Source: utils.js

  1. /**
  2.  * #### Import members from **@edx/frontend-platform**
  3.  *
  4.  * @module Utilities
  5.  */
  6. import camelCase from 'lodash.camelcase';
  7. import snakeCase from 'lodash.snakecase';
  9. /**
  10.  * This is the underlying function used by camelCaseObject, snakeCaseObject, and convertKeyNames
  11.  * above.
  12.  *
  13.  * Given an object (or array) and a modification function, will perform the function on each key it
  14.  * encounters on the object and its tree of children.
  15.  *
  16.  * The modification function must take a string as an argument and returns a string.
  17.  *
  18.  * Example:
  19.  *
  20.  * ```
  21.  * (key) => {
  22.  *   if (key === 'edX') {
  23.  *     return 'Open edX';
  24.  *   }
  25.  *   return key;
  26.  * }
  27.  * ```
  28.  *
  29.  * This function will turn any key that matches 'edX' into 'Open edX'.  All other keys will be
  30.  * passed through unmodified.
  31.  *
  32.  * Can accept arrays as well as objects, and will perform its conversion on any objects it finds in
  33.  * the array.
  34.  *
  35.  * @param {Object} object
  36.  * @param {function} modify
  37.  * @returns {Object}
  38.  */
  39. export function modifyObjectKeys(object, modify) {
  40.   // If the passed in object is not an Object, return it.
  41.   if (
  42.     object === undefined
  43.     || object === null
  44.     || (typeof object !== 'object' && !Array.isArray(object))
  45.   ) {
  46.     return object;
  47.   }
  49.   if (Array.isArray(object)) {
  50.     return object.map(value => modifyObjectKeys(value, modify));
  51.   }
  53.   // Otherwise, process all its keys.
  54.   const result = {};
  55.   Object.entries(object).forEach(([key, value]) => {
  56.     result[modify(key)] = modifyObjectKeys(value, modify);
  57.   });
  58.   return result;
  59. }
  61. /**
  62.  * Performs a deep conversion to camelCase on all keys in the provided object and its tree of
  63.  * children.  Uses [lodash.camelcase](https://lodash.com/docs/4.17.15#camelCase) on each key.  This
  64.  * is commonly used to convert snake_case keys in models from a backend server into camelCase keys
  65.  * for use in the JavaScript client.
  66.  *
  67.  * Can accept arrays as well as objects, and will perform its conversion on any objects it finds in
  68.  * the array.
  69.  *
  70.  * @param {Array|Object} object
  71.  * @returns {Array|Object}
  72.  */
  73. export function camelCaseObject(object) {
  74.   return modifyObjectKeys(object, camelCase);
  75. }
  77. /**
  78.  * Performs a deep conversion to snake_case on all keys in the provided object and its tree of
  79.  * children.  Uses [lodash.snakecase](https://lodash.com/docs/4.17.15#snakeCase) on each key.  This
  80.  * is commonly used to convert camelCase keys from the JavaScript app into snake_case keys expected
  81.  * by backend servers.
  82.  *
  83.  * Can accept arrays as well as objects, and will perform its conversion on any objects it finds in
  84.  * the array.
  85.  *
  86.  * @param {Array|Object} object
  87.  * @returns {Array|Object}
  88.  */
  89. export function snakeCaseObject(object) {
  90.   return modifyObjectKeys(object, snakeCase);
  91. }
  93. /**
  94.  * Given a map of key-value pairs, performs a deep conversion key names in the specified object
  95.  * _from_ the key _to_ the value.  This is useful for updating names in an API request to the names
  96.  * used throughout a client application if they happen to differ.  It can also be used in the
  97.  * reverse - formatting names from the client application to names expected by an API.
  98.  *
  99.  * ```
  100.  * import { convertKeyNames } from '@edx/frontend-base';
  101.  *
  102.  * // This object can be of any shape or depth with subobjects/arrays.
  103.  * const myObject = {
  104.  *   myKey: 'my value',
  105.  * }
  106.  *
  107.  * const result = convertKeyNames(myObject, { myKey: 'their_key' });
  108.  *
  109.  * console.log(result) // { their_key: 'my value' }
  110.  * ```
  111.  *
  112.  * Can accept arrays as well as objects, and will perform its conversion on any objects it finds in
  113.  * the array.
  114.  *
  115.  * @param {Array|Object} object
  116.  * @param {Object} nameMap
  117.  * @returns {Array|Object}
  118.  */
  119. export function convertKeyNames(object, nameMap) {
  120.   const transformer = key => (nameMap[key] === undefined ? key : nameMap[key]);
  122.   return modifyObjectKeys(object, transformer);
  123. }
  125. /**
  126.  * Given a string URL return an element that has been parsed via href.
  127.  * This element has the possibility to return different part of the URL.
  128.   parser.protocol; // => "http:"
  129.   parser.hostname; // => "example.com"
  130.   parser.port;     // => "3000"
  131.   parser.pathname; // => "/pathname/"
  132.   parser.search;   // => "?search=test"
  133.   parser.hash;     // => "#hash"
  134.   parser.host;     // => "example.com:3000"
  135.  * https://gist.github.com/jlong/2428561
  136.  *
  137.  * @param {string}
  138.  * @returns {Object}
  139.  */
  140. export function parseURL(url) {
  141.   if (typeof document !== 'undefined') {
  142.     const parser = document.createElement('a');
  143.     parser.href = url;
  144.     return parser;
  145.   }
  147.   return {};
  148. }
  150. /**
  151.  * Given a string URL return the path of the URL
  152.  *
  153.  *
  154.  * @param {string}
  155.  * @returns {string}
  156.  */
  157. export function getPath(url) {
  158.   return typeof document !== 'undefined' ? parseURL(url)?.pathname : '';
  159. }
  161. /**
  162.  * *Deprecated*: A method which converts the supplied query string into an object of
  163.  * key-value pairs and returns it.  Defaults to the current query string - should perform like
  164.  * [window.searchParams](https://developer.mozilla.org/en-US/docs/Web/API/URL/searchParams)
  165.  *
  166.  * @deprecated
  167.  * @param {string} [search=global.location.search]
  168.  * @returns {Object}
  169.  */
  170. export function getQueryParameters(search = global.location.search) {
  171.   const keyValueFragments = search
  172.     .slice(search.indexOf('?') + 1)
  173.     .split('&')
  174.     .filter(hash => hash !== '');
  176.   return keyValueFragments.reduce((params, keyValueFragment) => {
  177.     const split = keyValueFragment.indexOf('=');
  178.     const key = keyValueFragment.slice(0, split);
  179.     const value = keyValueFragment.slice(split + 1);
  180.     return Object.assign(params, { [key]: decodeURIComponent(value) });
  181.   }, {});
  182. }
  184. /**
  185.  * This function helps catch a certain class of misconfiguration in which configuration variables
  186.  * are not properly defined and/or supplied to a consumer that requires them.  Any key that exists
  187.  * is still set to "undefined" indicates a misconfiguration further up in the application, and
  188.  * should be flagged as an error, and is logged to 'warn'.
  189.  *
  190.  * Keys that are intended to be falsy should be defined using null, 0, false, etc.
  191.  *
  192.  * @param {Object} object
  193.  * @param {string} requester A human-readable identifier for the code which called this function.
  194.  * Used when throwing errors to aid in debugging.
  195.  */
  196. export function ensureDefinedConfig(object, requester) {
  197.   Object.keys(object).forEach((key) => {
  198.     if (object[key] === undefined) {
  199.       // eslint-disable-next-line no-console
  200.       console.warn(`Module configuration error: ${key} is required by ${requester}.`);
  201.     }
  202.   });
  203. }