feature-u/lib/core/useFassets.js

Feature Based Project Organization for React

'use strict';

exports.__esModule = true;

var _slicedToArray = function () { function sliceIterator(arr, i) { var _arr = []; var _n = true; var _d = false; var _e = undefined; try { for (var _i = arr[Symbol.iterator](), _s; !(_n = (_s = _i.next()).done); _n = true) { _arr.push(_s.value); if (i && _arr.length === i) break; } } catch (err) { _d = true; _e = err; } finally { try { if (!_n && _i["return"]) _i["return"](); } finally { if (_d) throw _e; } } return _arr; } return function (arr, i) { if (Array.isArray(arr)) { return arr; } else if (Symbol.iterator in Object(arr)) { return sliceIterator(arr, i); } else { throw new TypeError("Invalid attempt to destructure non-iterable instance"); } }; }();

exports.useFassets = useFassets;

var _react = require('react');

var _react2 = _interopRequireDefault(_react);

var _withFassets = require('./withFassets');

var _verify = require('../util/verify');

var _verify2 = _interopRequireDefault(_verify);

var _lodash = require('lodash.isplainobject');

var _lodash2 = _interopRequireDefault(_lodash);

var _lodash3 = require('lodash.isstring');

var _lodash4 = _interopRequireDefault(_lodash3);

var _mySpace = require('../util/mySpace');

function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }

/**
 * A {{book.ext.reactHook}} that provides functional component access
 * to **feature-u** {{book.api.fassets}}.
 *
 * **Hooks** allow you to **"hook into"** React state and lifecycle
 * aspects _from functional components_.  They greatly simplify the UI
 * implementation _as opposed to the alternative of Higher Order
 * Components (see: {{book.api.withFassets}})_.
 * 
 * There are three ways to invoke `useFassets()` _(examples can be
 * found at {{book.guide.crossCom_uiComposition}})_:
 * 
 * 1. Passing NO parameters, returns the
 *    {{book.api.FassetsObject}}:
 * 
 *    ```js
 *    + useFassets(): fassets
 *    ```
 * 
 * 2. Passing a `fassetsKey` _(a string)_, returns the resolved
 *    fassets resource:
 * 
 *    ```js
 *    + useFassets('MainPage.*.link@withKeys'): [] ... an array of cataloged links
 *    ```
 * 
 *    The `fassetsKey` parameter is identical _(in usage)_ to the
 *    {{book.api.Fassets_get}} method.
 * 
 * 3. Passing a {{book.api.mapFassetsToPropsStruct}}, returns a set of
 *    resolved fassetsProps:
 * 
 *    ```js
 *    + useFassets({
 *        mainBodies: 'MainPage.*.body',
 *        mainLinks:  'MainPage.*.link@withKeys'
 *      }): {  // ... return structure:
 *        mainBodies: ... resolved cataloged resource
 *        mainLinks:  ... ditto
 *      }
 *    ```
 * 
 *    The {{book.api.mapFassetsToPropsStruct}} allows you to return
 *    more than one resolved fassets resources.
 * 
 * **SideBar**: For `useFassets()` to operate,
 * `<FassetsContext.Provider>` must be rendered at the root of your
 * application DOM.  This is really a moot point, because
 * **feature-u** automatically performs this initialization, so you
 * really don't have to worry about this detail _(automating
 * configuration is a Hallmark of **feature-u** - reducing boilerplate
 * code)_.
 * 
 * @param {string|mapFassetsToPropsStruct} p the parameter controlling
 * what `useFassets` does _(see explanation above)_.
 *    
 * @returns {Fassets|fassets-resource|fassetsProps} _see explanation above_.
 * 
 * @function useFassets
 */
function useFassets() {
  var p = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : '.';


  useFassetsCheck(p);

  var fassets = (0, _react.useContext)(_withFassets.FassetsContext);

  return (0, _lodash4.default)(p) ? fassets.get(p) : (0, _withFassets.fassetsProps)(p, fassets);
}

// check useFassets() usage in a way that is masked as a hook
// (useXyz()), so as to allow execution before real hooks
// ... i.e. fake out the lint rule!!
// ... this includes BOTH verifying:
//     - hooks is available in this version of react
//     - parameter validation
function useFassetsCheck(p) {
  // verify that hooks are available in this version of react
  if (!_react.useContext) {
    throw new Error('feature-u useFassets() is only available in React versions that have HOOKS (React >=16.8) ... your React Version is: ' + _react2.default.version);
  }

  // parameter validation
  var check = _verify2.default.prefix('useFassets() parameter violation: ');

  check(p, 'single parameter IS required');
  check((0, _lodash4.default)(p) || (0, _lodash2.default)(p), 'single parameter must either be a string or a structure ... ' + p);

  // when a mapFassetsToProps is supplied, it must be a set of key/value pairs cataloging strings
  if ((0, _lodash2.default)(p)) {
    _mySpace.MyObj.entries(p).forEach(function (_ref) {
      var _ref2 = _slicedToArray(_ref, 2),
          propKey = _ref2[0],
          fassetsKey = _ref2[1];

      check((0, _lodash4.default)(fassetsKey), 'invalid mapFassetsToProps - all properties MUST reference a fassetsKey string ... at minimum ' + propKey + ' does NOT');
    });
  }
}