src/custom_step.js

  1. class CustomStep {
  2.   /**
  3.    * @constructs Step
  4.    * @classdesc A step within a {@link Lens} with fully customizable behavior
  5.    * @param {Step~Get_Maybe} get_maybe
  6.    *    Returns a {@link Maybe} value for the slot within the container it is
  7.    *    passed.
  8.    * @param {Step~UpdatedClone} updatedClone
  9.    *    Takes the current container and a {@link Maybe} of this step's slot
  10.    *    value, returning a minimally modified clone of the container such that
  11.    *    *get_maybe* will return the *value_maybe* passed to this function.
  12.    * @param {Step~Construct} construct
  13.    *    Instantiate an empty container of the type this step navigates.
  14.    *
  15.    * @description
  16.    * If standard logic for accessing data deeper in the conceptual structure
  17.    * is not adequate, an instance of this class may be passed as a step in a
  18.    * Lens, which will allow the Lens to have custom behavior.
  19.    *
  20.    * Passing `null` for any of these functions will limit the functionality of
  21.    * the lens: skipping either `construct` or `updatedClone` will prevent the lens
  22.    * from constructing a missing container, skipping `updatedClone` will
  23.    * additionally prevent the lens from modifying an existing container, and
  24.    * skipping `get_maybe` will prevent retrieving or transforming values in
  25.    * a subject.
  26.    */
  27.   constructor(get_maybe, updatedClone, construct) {
  28.     Object.assign(this, {construct, updatedClone, get_maybe});
  29.   }
  30. }
  31. export default CustomStep;
  33. /**
  34.  * @callback Step~Get_Maybe
  35.  * @param {*} container
  36.  * @returns {Maybe.<*>} A Maybe monad value for the represented slot within *container*
  37.  *
  38.  * @description
  39.  * Gets the value of this slot within the passed *container*, returning `{}` if
  40.  * the slot does not exist.
  41.  */
  42.  
  43.  /**
  44.   * @callback Step~UpdatedClone
  45.   * @param {*} container
  46.   * @param {Maybe.<*>} value_maybe
  47.   * @param {*} [value_maybe.just]  The value to assign into the target slot in the clone
  48.   * @returns The minimally modified clone of *container*
  49.   */
  51. /**
  52.  * @callback Step~Construct
  53.  * @returns The empty container type corresponding to this step
  54.  */