Documentation

Typedefs

Mapper()

function Mapper(value: *, nodePath: List, tree: Iterable): *

A function required as an argument for the deepMap functions.

Params
  • value: *

    The value to update.

  • nodePath: List

    The current node's NodePath, a List of keys used to uniquely identify the current node.

  • tree: Iterable

    The original tree passed into the map function.

Returns
  • *

    The replacement value.

ChildPath

An Array or List of keys indicating where to find each node's children from within each node. This works in the same way as the keyPath parameter in Immutable's getIn() method. It also accepts null in place of an empty Array or List.

Example
// this tree would have a ChildPath of ['children'], as each node's children can be found in the 'children' iterable
const tree = fromJS({
  name: "root",
  children: [
    {
      name: "child 1",
      children: [
        {name: "grandchild 1"},
        {name: "grandchild 2"}
      ]
    },
    {
      name: "child 2",
      children: []
    },
    {name: "child 3"}
  ]
});

// nested maps and lists like these don't require a ChildPath, as each Iterable contains its own children
const nestedMaps = fromJS({
  a: {
    b: "B",
    c: "C",
    d: {
      e: "E"
    }
  },
  f: "F"
});

const nestedLists = fromJS([
 ["A","B","C"],
 ["D",["E","F"]],
 "G"
);

InputFunction()

function InputFunction(tree: Iterable): Iterable

InputFunction is a partially applied function returned from all 'deep' functions in immutable-recursive. It accepts an iterable, the tree of data you wish to call your deep function on, and returns the result of the deep function you're calling.

For example, one way to use deepGet is to call it, passing in any parameters required, then call the returned function, passing in your data tree.

const nestedMaps = fromJS({
  a: {
    b: "B",
    c: "C",
    d: {
      e: "E"
    }
  },
  f: "F"
});

return deepGet(['a','b'])(nestedMaps); // returns "B"

This design of using a partially applied function allows immutable-recursive's functions to be chained easily with Immutable, by using them inside of an update() method. This is the preferred usage pattern as it retains chainability.

return fromJS(someData)
    .get('tree')
    .update(deepGet(['a','b'])) // using deepGet in a chain
    .set('done', true)
    .toJS();

You can also define a function to perform a specific operation, and use it multiple times by passing in different tree data.

// make every node's name uppercase
const uppercaseNames = deepMap((node) => {
    return node.update('name', (name) => name.toUpperCase());
}, ['children']);

const a = fromJS(aDataTree).update(uppercaseNames);
const b = fromJS(aDifferentDataTree).update(uppercaseNames);
Params
  • tree: Iterable

    The tree Iterable to be processed by one of the deep functions.

Returns
  • Iterable

    The modified iterable.

Filterer()

function Filterer(value: *, nodePath: List, tree: Iterable): *

A function required as an argument for the deepFilter functions.

Params
  • value: *

    The value to filter.

  • nodePath: List

    The current node's NodePath, a List of keys used to uniquely identify the current node.

  • tree: Iterable

    The original tree passed into the map function.

Returns
  • *

    The replacement value.

NodePath

When passed as a parameter, NodePath can be a List or an Array of keys used to uniquely identify a node. Almost always used in conjunction with a ChildPath. Also accepts null in place of an empty Array or List.

Whenever NodePath is returned from a function in the immutable-recursive library, it will always be a List.

Example
const tree = fromJS({
  name: "root",
  children: [
    {
      name: "child 1",
      children: [
        {name: "grandchild 1"},
        {name: "grandchild 2"}
      ]
    }
    {name: "child 2"}
  ]
});
// The NodePath for "root" is [] (or null)
// The NodePath for "child 1" is [0]
// The NodePath for "grandchild 2" is [0,1]

const nestedMaps = fromJS({
  a: {
    b: "B",
    c: "C",
    d: {
      e: "E"
    }
  },
  f: "F"
});
// The NodePath for "A" is ['a']
// The NodePath for "B" is ['a','b']
// The NodePath for "E" is ['a','d','e']

Updater()

function Updater(value: *): *

A function required as an argument for the deepUpdate functions.

Params
  • value: *

    The value to update.

Returns
  • *

    The replacement value.

Reducer()

function Reducer(reduction: *, value: *, nodePath: List, tree: Iterable): *

A function required as an argument for the deepReduce functions.

Params
  • reduction: *

    The current reduction.

  • value: *

    The current value.

  • nodePath: List

    The current node's NodePath, a List of keys used to uniquely identify the current node.

  • tree: Iterable

    The original tree passed into the map function.

Returns
  • *

    The new reduced value.

Modules

utils

asList()

function asList(input: Array|List|null): List

Accepts an Array, List or null and returns an equivalent List. Passing in null will return an empty List.

Example
asList(null); // returns List()
asList([0,1,2]); // returns List().of(0,1,2)
asList(List().of(0,1,2)); // returns List().of(0,1,2)
Params
  • input: Array|List|null

    The input to be convert to a List. List items will pass through unchanged, all others will be passed into a List constructor.

Returns
  • List

    The equivalent List.

blankNode()

function blankNode(node: *, childPath?: ChildPath): *

Accepts a node and returns a copy of it with all children and all non-childPath keys removed. Essentially the minimum data structure required for the node.

Params
  • node: *

    The node to make blank.

  • childPath: ?ChildPath

    An Array or List of keys indicating where to find the node's children.

    • ChildPath: ChildPath

      An Array or List of keys indicating where to find each node's children from within each node. This works in the same way as the keyPath parameter in Immutable's getIn() method. It also accepts null in place of an empty Array or List.

Returns
  • *

    The blank node.

nodePathToKeys()

function nodePathToKeys(nodePath: NodePath, childPath?: ChildPath): List

Turns a node's nodePath and its childPath into a full key path.

Example
nodePathToKeys(null, ['children']); // returns []
nodePathToKeys(['bob'], ['children']); // returns ['children', 'bob']
nodePathToKeys([0,1], ['children']); // returns ['children', 0, 'children', 1]
Params
  • nodePath: NodePath

    A NodePath used to uniquely identify a node.

    • NodePath: NodePath

      When passed as a parameter, NodePath can be a List or an Array of keys used to uniquely identify a node. Almost always used in conjunction with a ChildPath. Also accepts null in place of an empty Array or List.

      Whenever NodePath is returned from a function in the immutable-recursive library, it will always be a List.

  • childPath: ?ChildPath

    An Array or List of keys indicating where to find each node's children from within each node.

    • ChildPath: ChildPath

      An Array or List of keys indicating where to find each node's children from within each node. This works in the same way as the keyPath parameter in Immutable's getIn() method. It also accepts null in place of an empty Array or List.

Returns
  • List

nodePathToKeysChildren()

function nodePathToKeysChildren(nodePath: NodePath, childPath?: ChildPath): List

Turns a node's nodePath and its childPath into a full key path to the node's children.

Example
nodePathToKeysChildren(null, ['children']); // returns ['children']
nodePathToKeysChildren(['bob'], ['children']); // returns ['children', 'bob', children']
nodePathToKeysChildren([0,1], ['children']); // returns ['children', 0, 'children', 1, 'children']
Params
  • nodePath: NodePath

    A NodePath used to uniquely identify a node.

    • NodePath: NodePath

      When passed as a parameter, NodePath can be a List or an Array of keys used to uniquely identify a node. Almost always used in conjunction with a ChildPath. Also accepts null in place of an empty Array or List.

      Whenever NodePath is returned from a function in the immutable-recursive library, it will always be a List.

  • childPath: ?ChildPath

    An Array or List of keys indicating where to find each node's children from within each node.

    • ChildPath: ChildPath

      An Array or List of keys indicating where to find each node's children from within each node. This works in the same way as the keyPath parameter in Immutable's getIn() method. It also accepts null in place of an empty Array or List.

Returns
  • List

isLeaf()

function isLeaf(node: *, childPath?: ChildPath): boolean

Accepts a node and returns a boolean indicating if the node is a leaf node (i.e. it has no children).

Example
const tree = fromJS({
  name: "root",
  children: [
    {
      name: "child 1",
      children: [
        {name: "grandchild 1"},
        {name: "grandchild 2"}
      ]
    },
    {
      name: "child 2",
      children: []
    }
  ]
});

isLeaf(tree.getIn(['children', 0]), ['childPath']); // returns false because child 1 has children
isLeaf(tree.getIn(['children', 1]), ['childPath']); // returns true because child 2 has no children
// note that normally deepGet is recommended instead of getIn for getting nodes from a tree
Params
  • node: *

    The node to check.

  • childPath: ?ChildPath

    An Array or List of keys indicating where to find each node's children from within each node.

    • ChildPath: ChildPath

      An Array or List of keys indicating where to find each node's children from within each node. This works in the same way as the keyPath parameter in Immutable's getIn() method. It also accepts null in place of an empty Array or List.

Returns
  • boolean

    A boolean indicating if the node is a leaf node.

pick()

function pick(iterable: Iterable, keys: Array): Iterable

Filter an Immutable Iterable so it only retains any keys provided in the keys param. Similar to the pick function in Lodash.

Example
const map = Map({
  a: "A",
  b: "B",
  c: "C",
  d: "D"
});

pick(map, ['a', 'c']); // returns Map({a: "A", c: "C"});
Params
  • iterable: Iterable

    The Iterable to filter.

  • keys: Array

    The iterable's keys to keep.

Returns
  • Iterable

filter

deepFilter()

function deepFilter(filterer: (value: *, nodePath: List, tree: Iterable) => *, childPath?: ChildPath): (tree: Iterable) => Iterable

Once fully applied, this iterates through nodes in the provided tree, passing them through a filter function. Only nodes which return a truthy value from the filter function will be present in the modified tree. Nodes are processed branch by branch in the order that Immutable maps through the child iterables, outwards from the root node to leaf nodes. Sibling nodes are processed in the order that Immutable iterates through collections.

Params
  • filterer: Filterer

    The function to be called for each node in the tree, the results of which will be used to create the modified tree.

    • Filterer: (value: *, nodePath: List, tree: Iterable)

      A function required as an argument for the deepFilter functions.

      • value: *

        The value to filter.

      • nodePath: List

        The current node's NodePath, a List of keys used to uniquely identify the current node.

      • tree: Iterable

        The original tree passed into the map function.

  • childPath: ?ChildPath

    An Array or List of keys indicating where to find each node's children from within each node.

    • ChildPath: ChildPath

      An Array or List of keys indicating where to find each node's children from within each node. This works in the same way as the keyPath parameter in Immutable's getIn() method. It also accepts null in place of an empty Array or List.

Returns
  • InputFunction

    A partially applied function which accepts a single tree Iterable, and returns the modified tree Iterable.

    • InputFunction: (tree: Iterable)

      InputFunction is a partially applied function returned from all 'deep' functions in immutable-recursive. It accepts an iterable, the tree of data you wish to call your deep function on, and returns the result of the deep function you're calling.

      For example, one way to use deepGet is to call it, passing in any parameters required, then call the returned function, passing in your data tree.

      const nestedMaps = fromJS({
        a: {
          b: "B",
          c: "C",
          d: {
            e: "E"
          }
        },
        f: "F"
      });
      
      return deepGet(['a','b'])(nestedMaps); // returns "B"

      This design of using a partially applied function allows immutable-recursive's functions to be chained easily with Immutable, by using them inside of an update() method. This is the preferred usage pattern as it retains chainability.

      return fromJS(someData)
          .get('tree')
          .update(deepGet(['a','b'])) // using deepGet in a chain
          .set('done', true)
          .toJS();

      You can also define a function to perform a specific operation, and use it multiple times by passing in different tree data.

      // make every node's name uppercase
      const uppercaseNames = deepMap((node) => {
          return node.update('name', (name) => name.toUpperCase());
      }, ['children']);
      
      const a = fromJS(aDataTree).update(uppercaseNames);
      const b = fromJS(aDifferentDataTree).update(uppercaseNames);
      • tree: Iterable

        The tree Iterable to be processed by one of the deep functions.

get

deepGet()

function deepGet(nodePath: NodePath, childPath?: ChildPath, notSetValue?: *): (tree: Iterable) => Iterable

Once fully applied, this returns a specific node from the tree. When no childPath is provided then this is functionally equivalent to Immutable's getIn() function.

Params
  • nodePath: NodePath

    A NodePath used to identify the node to return.

    • NodePath: NodePath

      When passed as a parameter, NodePath can be a List or an Array of keys used to uniquely identify a node. Almost always used in conjunction with a ChildPath. Also accepts null in place of an empty Array or List.

      Whenever NodePath is returned from a function in the immutable-recursive library, it will always be a List.

  • childPath: ?ChildPath

    An Array or List of keys indicating where to find each node's children from within each node.

    • ChildPath: ChildPath

      An Array or List of keys indicating where to find each node's children from within each node. This works in the same way as the keyPath parameter in Immutable's getIn() method. It also accepts null in place of an empty Array or List.

  • notSetValue: ?*

    A value to return when there is no node corresponding to nodePath.

Returns
  • InputFunction

    A partially applied function which accepts a single tree Iterable. InputFunction will return the node at the specified nodePath, or if no node exists then notSetValue will be returned.

    • InputFunction: (tree: Iterable)

      InputFunction is a partially applied function returned from all 'deep' functions in immutable-recursive. It accepts an iterable, the tree of data you wish to call your deep function on, and returns the result of the deep function you're calling.

      For example, one way to use deepGet is to call it, passing in any parameters required, then call the returned function, passing in your data tree.

      const nestedMaps = fromJS({
        a: {
          b: "B",
          c: "C",
          d: {
            e: "E"
          }
        },
        f: "F"
      });
      
      return deepGet(['a','b'])(nestedMaps); // returns "B"

      This design of using a partially applied function allows immutable-recursive's functions to be chained easily with Immutable, by using them inside of an update() method. This is the preferred usage pattern as it retains chainability.

      return fromJS(someData)
          .get('tree')
          .update(deepGet(['a','b'])) // using deepGet in a chain
          .set('done', true)
          .toJS();

      You can also define a function to perform a specific operation, and use it multiple times by passing in different tree data.

      // make every node's name uppercase
      const uppercaseNames = deepMap((node) => {
          return node.update('name', (name) => name.toUpperCase());
      }, ['children']);
      
      const a = fromJS(aDataTree).update(uppercaseNames);
      const b = fromJS(aDifferentDataTree).update(uppercaseNames);
      • tree: Iterable

        The tree Iterable to be processed by one of the deep functions.

deepGetChildren()

function deepGetChildren(nodePath: NodePath, childPath?: ChildPath, notSetValue?: *): (tree: Iterable) => Iterable

Once fully applied, this returns the children of a specific node from the tree.

This is intended to be used with a childPath, but if no childPath is provided then this is functionally equivalent to Immutable's getIn() function or deepMap().

Params
  • nodePath: NodePath

    A NodePath used to identify the node to return.

    • NodePath: NodePath

      When passed as a parameter, NodePath can be a List or an Array of keys used to uniquely identify a node. Almost always used in conjunction with a ChildPath. Also accepts null in place of an empty Array or List.

      Whenever NodePath is returned from a function in the immutable-recursive library, it will always be a List.

  • childPath: ?ChildPath

    An Array or List of keys indicating where to find each node's children from within each node.

    • ChildPath: ChildPath

      An Array or List of keys indicating where to find each node's children from within each node. This works in the same way as the keyPath parameter in Immutable's getIn() method. It also accepts null in place of an empty Array or List.

  • notSetValue: ?*

    A value to return when there is no node corresponding to nodePath, or if the node doesn't have any children.

Returns
  • InputFunction

    A partially applied function which accepts a single tree Iterable. InputFunction will return the children of the node at the specified nodePath, or if no node or children exist then notSetValue will be returned

    • InputFunction: (tree: Iterable)

      InputFunction is a partially applied function returned from all 'deep' functions in immutable-recursive. It accepts an iterable, the tree of data you wish to call your deep function on, and returns the result of the deep function you're calling.

      For example, one way to use deepGet is to call it, passing in any parameters required, then call the returned function, passing in your data tree.

      const nestedMaps = fromJS({
        a: {
          b: "B",
          c: "C",
          d: {
            e: "E"
          }
        },
        f: "F"
      });
      
      return deepGet(['a','b'])(nestedMaps); // returns "B"

      This design of using a partially applied function allows immutable-recursive's functions to be chained easily with Immutable, by using them inside of an update() method. This is the preferred usage pattern as it retains chainability.

      return fromJS(someData)
          .get('tree')
          .update(deepGet(['a','b'])) // using deepGet in a chain
          .set('done', true)
          .toJS();

      You can also define a function to perform a specific operation, and use it multiple times by passing in different tree data.

      // make every node's name uppercase
      const uppercaseNames = deepMap((node) => {
          return node.update('name', (name) => name.toUpperCase());
      }, ['children']);
      
      const a = fromJS(aDataTree).update(uppercaseNames);
      const b = fromJS(aDifferentDataTree).update(uppercaseNames);
      • tree: Iterable

        The tree Iterable to be processed by one of the deep functions.

map

deepMap()

function deepMap(mapper: (value: *, nodePath: List, tree: Iterable) => *, childPath?: ChildPath): (tree: Iterable) => Iterable

Once fully applied, this iterates through all nodes in the provided tree, passing them all through a mapper function. Nodes are processed branch by branch in the order that Immutable maps through the child iterables, inward from leaves to the root node. Sibling nodes are processed in the order that Immutable iterates through collections.

TODO: note about care with child collections, note about using as reduce

Params
  • mapper: Mapper

    The function to be called for every node in the tree, the results of which will be used to create the modified tree.

    • Mapper: (value: *, nodePath: List, tree: Iterable)

      A function required as an argument for the deepMap functions.

      • value: *

        The value to update.

      • nodePath: List

        The current node's NodePath, a List of keys used to uniquely identify the current node.

      • tree: Iterable

        The original tree passed into the map function.

  • childPath: ?ChildPath

    An Array or List of keys indicating where to find each node's children from within each node.

    • ChildPath: ChildPath

      An Array or List of keys indicating where to find each node's children from within each node. This works in the same way as the keyPath parameter in Immutable's getIn() method. It also accepts null in place of an empty Array or List.

Returns
  • InputFunction

    A partially applied function which accepts a single tree Iterable, and returns the modified tree Iterable.

    • InputFunction: (tree: Iterable)

      InputFunction is a partially applied function returned from all 'deep' functions in immutable-recursive. It accepts an iterable, the tree of data you wish to call your deep function on, and returns the result of the deep function you're calling.

      For example, one way to use deepGet is to call it, passing in any parameters required, then call the returned function, passing in your data tree.

      const nestedMaps = fromJS({
        a: {
          b: "B",
          c: "C",
          d: {
            e: "E"
          }
        },
        f: "F"
      });
      
      return deepGet(['a','b'])(nestedMaps); // returns "B"

      This design of using a partially applied function allows immutable-recursive's functions to be chained easily with Immutable, by using them inside of an update() method. This is the preferred usage pattern as it retains chainability.

      return fromJS(someData)
          .get('tree')
          .update(deepGet(['a','b'])) // using deepGet in a chain
          .set('done', true)
          .toJS();

      You can also define a function to perform a specific operation, and use it multiple times by passing in different tree data.

      // make every node's name uppercase
      const uppercaseNames = deepMap((node) => {
          return node.update('name', (name) => name.toUpperCase());
      }, ['children']);
      
      const a = fromJS(aDataTree).update(uppercaseNames);
      const b = fromJS(aDifferentDataTree).update(uppercaseNames);
      • tree: Iterable

        The tree Iterable to be processed by one of the deep functions.

deepMapLeaves()

function deepMapLeaves(mapper: (value: *, nodePath: List, tree: Iterable) => *, childPath?: ChildPath): (tree: Iterable) => Iterable

Once fully applied, this iterates through the leaf nodes in the provided tree, passing them all through a mapper function. Leaf nodes are nodes that have no child nodes. Nodes are processed branch by branch, in the order that Immutable maps through the child iterables.

Params
  • mapper: Mapper

    The function to be called for every leaf node in the tree, the results of which will be used to create the modified tree.

    • Mapper: (value: *, nodePath: List, tree: Iterable)

      A function required as an argument for the deepMap functions.

      • value: *

        The value to update.

      • nodePath: List

        The current node's NodePath, a List of keys used to uniquely identify the current node.

      • tree: Iterable

        The original tree passed into the map function.

  • childPath: ?ChildPath

    An Array or List of keys indicating where to find each node's children from within each node.

    • ChildPath: ChildPath

      An Array or List of keys indicating where to find each node's children from within each node. This works in the same way as the keyPath parameter in Immutable's getIn() method. It also accepts null in place of an empty Array or List.

Returns
  • InputFunction

    A partially applied function which accepts a single tree Iterable, and returns the modified tree Iterable.

    • InputFunction: (tree: Iterable)

      InputFunction is a partially applied function returned from all 'deep' functions in immutable-recursive. It accepts an iterable, the tree of data you wish to call your deep function on, and returns the result of the deep function you're calling.

      For example, one way to use deepGet is to call it, passing in any parameters required, then call the returned function, passing in your data tree.

      const nestedMaps = fromJS({
        a: {
          b: "B",
          c: "C",
          d: {
            e: "E"
          }
        },
        f: "F"
      });
      
      return deepGet(['a','b'])(nestedMaps); // returns "B"

      This design of using a partially applied function allows immutable-recursive's functions to be chained easily with Immutable, by using them inside of an update() method. This is the preferred usage pattern as it retains chainability.

      return fromJS(someData)
          .get('tree')
          .update(deepGet(['a','b'])) // using deepGet in a chain
          .set('done', true)
          .toJS();

      You can also define a function to perform a specific operation, and use it multiple times by passing in different tree data.

      // make every node's name uppercase
      const uppercaseNames = deepMap((node) => {
          return node.update('name', (name) => name.toUpperCase());
      }, ['children']);
      
      const a = fromJS(aDataTree).update(uppercaseNames);
      const b = fromJS(aDifferentDataTree).update(uppercaseNames);
      • tree: Iterable

        The tree Iterable to be processed by one of the deep functions.

deepMapParents()

function deepMapParents(mapper: (value: *, nodePath: List, tree: Iterable) => *, childPath?: ChildPath): (tree: Iterable) => Iterable

Once fully applied, this iterates through the parent nodes in the provided tree, passing them all through a mapper function. Parent nodes are nodes that have child nodes. Nodes are processed branch by branch in the order that Immutable maps through the child iterables, inward from leaves to the root node.

Params
  • mapper: Mapper

    The function to be called for every parent node in the tree. the results of which will be used to create the modified iterable.

    • Mapper: (value: *, nodePath: List, tree: Iterable)

      A function required as an argument for the deepMap functions.

      • value: *

        The value to update.

      • nodePath: List

        The current node's NodePath, a List of keys used to uniquely identify the current node.

      • tree: Iterable

        The original tree passed into the map function.

  • childPath: ?ChildPath

    An Array or List of keys indicating where to find each node's children from within each node.

    • ChildPath: ChildPath

      An Array or List of keys indicating where to find each node's children from within each node. This works in the same way as the keyPath parameter in Immutable's getIn() method. It also accepts null in place of an empty Array or List.

Returns
  • InputFunction

    A partially applied function which accepts a single tree Iterable, and returns the modified tree Iterable.

    • InputFunction: (tree: Iterable)

      InputFunction is a partially applied function returned from all 'deep' functions in immutable-recursive. It accepts an iterable, the tree of data you wish to call your deep function on, and returns the result of the deep function you're calling.

      For example, one way to use deepGet is to call it, passing in any parameters required, then call the returned function, passing in your data tree.

      const nestedMaps = fromJS({
        a: {
          b: "B",
          c: "C",
          d: {
            e: "E"
          }
        },
        f: "F"
      });
      
      return deepGet(['a','b'])(nestedMaps); // returns "B"

      This design of using a partially applied function allows immutable-recursive's functions to be chained easily with Immutable, by using them inside of an update() method. This is the preferred usage pattern as it retains chainability.

      return fromJS(someData)
          .get('tree')
          .update(deepGet(['a','b'])) // using deepGet in a chain
          .set('done', true)
          .toJS();

      You can also define a function to perform a specific operation, and use it multiple times by passing in different tree data.

      // make every node's name uppercase
      const uppercaseNames = deepMap((node) => {
          return node.update('name', (name) => name.toUpperCase());
      }, ['children']);
      
      const a = fromJS(aDataTree).update(uppercaseNames);
      const b = fromJS(aDifferentDataTree).update(uppercaseNames);
      • tree: Iterable

        The tree Iterable to be processed by one of the deep functions.

deepMapOutwards()

function deepMapOutwards(mapper: (value: *, nodePath: List, tree: Iterable) => *, childPath?: ChildPath): (tree: Iterable) => Iterable

Once fully applied, this iterates through all nodes in the provided tree, passing them all through a mapper function. Nodes are processed branch by branch in the order that Immutable maps through the child iterables, outwards from the root node to the leaf nodes. Sibling nodes are processed in the order that Immutable iterates through collections.

Because this moves from the root node outwards this function behaves quite differently to the other deep map functions.

  • If you modify a node's children, then those children will already be modified by the time they are called by the mapper function.
  • Because of the above, if a node removes or renames its own children iterable then those children will not be passed through the mapper function.
Params
  • mapper: Mapper

    The function to be called for every node in the tree, the results of which will be used to create the modified tree.

    • Mapper: (value: *, nodePath: List, tree: Iterable)

      A function required as an argument for the deepMap functions.

      • value: *

        The value to update.

      • nodePath: List

        The current node's NodePath, a List of keys used to uniquely identify the current node.

      • tree: Iterable

        The original tree passed into the map function.

  • childPath: ?ChildPath

    An Array or List of keys indicating where to find each node's children from within each node.

    • ChildPath: ChildPath

      An Array or List of keys indicating where to find each node's children from within each node. This works in the same way as the keyPath parameter in Immutable's getIn() method. It also accepts null in place of an empty Array or List.

Returns
  • InputFunction

    A partially applied function which accepts a single tree Iterable, and returns the modified tree Iterable.

    • InputFunction: (tree: Iterable)

      InputFunction is a partially applied function returned from all 'deep' functions in immutable-recursive. It accepts an iterable, the tree of data you wish to call your deep function on, and returns the result of the deep function you're calling.

      For example, one way to use deepGet is to call it, passing in any parameters required, then call the returned function, passing in your data tree.

      const nestedMaps = fromJS({
        a: {
          b: "B",
          c: "C",
          d: {
            e: "E"
          }
        },
        f: "F"
      });
      
      return deepGet(['a','b'])(nestedMaps); // returns "B"

      This design of using a partially applied function allows immutable-recursive's functions to be chained easily with Immutable, by using them inside of an update() method. This is the preferred usage pattern as it retains chainability.

      return fromJS(someData)
          .get('tree')
          .update(deepGet(['a','b'])) // using deepGet in a chain
          .set('done', true)
          .toJS();

      You can also define a function to perform a specific operation, and use it multiple times by passing in different tree data.

      // make every node's name uppercase
      const uppercaseNames = deepMap((node) => {
          return node.update('name', (name) => name.toUpperCase());
      }, ['children']);
      
      const a = fromJS(aDataTree).update(uppercaseNames);
      const b = fromJS(aDifferentDataTree).update(uppercaseNames);
      • tree: Iterable

        The tree Iterable to be processed by one of the deep functions.

deepMapLeavesOutwards()

function deepMapLeavesOutwards(mapper: (value: *, nodePath: List, tree: Iterable) => *, childPath?: ChildPath): (tree: Iterable) => Iterable

Once fully applied, this iterates through the leaf nodes in the provided tree, passing them all through a mapper function. Nodes are processed branch by branch in the order that Immutable maps through the child iterables, outwards from the root node to the leaf nodes. Sibling nodes are processed in the order that Immutable iterates through collections.

Params
  • mapper: Mapper

    The function to be called for every leaf node in the tree, the results of which will be used to create the modified tree.

    • Mapper: (value: *, nodePath: List, tree: Iterable)

      A function required as an argument for the deepMap functions.

      • value: *

        The value to update.

      • nodePath: List

        The current node's NodePath, a List of keys used to uniquely identify the current node.

      • tree: Iterable

        The original tree passed into the map function.

  • childPath: ?ChildPath

    An Array or List of keys indicating where to find each node's children from within each node.

    • ChildPath: ChildPath

      An Array or List of keys indicating where to find each node's children from within each node. This works in the same way as the keyPath parameter in Immutable's getIn() method. It also accepts null in place of an empty Array or List.

Returns
  • InputFunction

    A partially applied function which accepts a single tree Iterable, and returns the modified tree Iterable.

    • InputFunction: (tree: Iterable)

      InputFunction is a partially applied function returned from all 'deep' functions in immutable-recursive. It accepts an iterable, the tree of data you wish to call your deep function on, and returns the result of the deep function you're calling.

      For example, one way to use deepGet is to call it, passing in any parameters required, then call the returned function, passing in your data tree.

      const nestedMaps = fromJS({
        a: {
          b: "B",
          c: "C",
          d: {
            e: "E"
          }
        },
        f: "F"
      });
      
      return deepGet(['a','b'])(nestedMaps); // returns "B"

      This design of using a partially applied function allows immutable-recursive's functions to be chained easily with Immutable, by using them inside of an update() method. This is the preferred usage pattern as it retains chainability.

      return fromJS(someData)
          .get('tree')
          .update(deepGet(['a','b'])) // using deepGet in a chain
          .set('done', true)
          .toJS();

      You can also define a function to perform a specific operation, and use it multiple times by passing in different tree data.

      // make every node's name uppercase
      const uppercaseNames = deepMap((node) => {
          return node.update('name', (name) => name.toUpperCase());
      }, ['children']);
      
      const a = fromJS(aDataTree).update(uppercaseNames);
      const b = fromJS(aDifferentDataTree).update(uppercaseNames);
      • tree: Iterable

        The tree Iterable to be processed by one of the deep functions.

deepMapParentsOutwards()

function deepMapParentsOutwards(mapper: (value: *, nodePath: List, tree: Iterable) => *, childPath?: ChildPath): (tree: Iterable) => Iterable

Once fully applied, this iterates through the parent nodes in the provided tree, passing them all through a mapper function. Nodes are processed branch by branch in the order that Immutable maps through the child iterables, outwards from the root node to the leaf nodes. Sibling nodes are processed in the order that Immutable iterates through collections.

Because this moves from the root node outwards this function behaves quite differently to the other deep map functions.

  • If you modify a node's children, then those children will already be modified by the time they are called by the mapper function.
  • Because of the above, if a node removes or renames its own children iterable then those children will not be passed through the mapper function.
Params
  • mapper: Mapper

    The function to be called for every parent node in the tree, the results of which will be used to create the modified tree.

    • Mapper: (value: *, nodePath: List, tree: Iterable)

      A function required as an argument for the deepMap functions.

      • value: *

        The value to update.

      • nodePath: List

        The current node's NodePath, a List of keys used to uniquely identify the current node.

      • tree: Iterable

        The original tree passed into the map function.

  • childPath: ?ChildPath

    An Array or List of keys indicating where to find each node's children from within each node.

    • ChildPath: ChildPath

      An Array or List of keys indicating where to find each node's children from within each node. This works in the same way as the keyPath parameter in Immutable's getIn() method. It also accepts null in place of an empty Array or List.

Returns
  • InputFunction

    A partially applied function which accepts a single tree Iterable, and returns the modified tree Iterable.

    • InputFunction: (tree: Iterable)

      InputFunction is a partially applied function returned from all 'deep' functions in immutable-recursive. It accepts an iterable, the tree of data you wish to call your deep function on, and returns the result of the deep function you're calling.

      For example, one way to use deepGet is to call it, passing in any parameters required, then call the returned function, passing in your data tree.

      const nestedMaps = fromJS({
        a: {
          b: "B",
          c: "C",
          d: {
            e: "E"
          }
        },
        f: "F"
      });
      
      return deepGet(['a','b'])(nestedMaps); // returns "B"

      This design of using a partially applied function allows immutable-recursive's functions to be chained easily with Immutable, by using them inside of an update() method. This is the preferred usage pattern as it retains chainability.

      return fromJS(someData)
          .get('tree')
          .update(deepGet(['a','b'])) // using deepGet in a chain
          .set('done', true)
          .toJS();

      You can also define a function to perform a specific operation, and use it multiple times by passing in different tree data.

      // make every node's name uppercase
      const uppercaseNames = deepMap((node) => {
          return node.update('name', (name) => name.toUpperCase());
      }, ['children']);
      
      const a = fromJS(aDataTree).update(uppercaseNames);
      const b = fromJS(aDifferentDataTree).update(uppercaseNames);
      • tree: Iterable

        The tree Iterable to be processed by one of the deep functions.

pick

deepPick()

function deepPick(nodePath: NodePath, childPath?: ChildPath): (tree: Iterable) => Iterable

Once fully applied, this returns a new tree containing only nodes lying on the supplied nodePath, with all nodes and children outside of the nodePath removed.

Params
  • nodePath: NodePath

    A NodePath whose nodes will be filtered and returned.

    • NodePath: NodePath

      When passed as a parameter, NodePath can be a List or an Array of keys used to uniquely identify a node. Almost always used in conjunction with a ChildPath. Also accepts null in place of an empty Array or List.

      Whenever NodePath is returned from a function in the immutable-recursive library, it will always be a List.

  • childPath: ?ChildPath

    An Array or List of keys indicating where to find each node's children from within each node.

    • ChildPath: ChildPath

      An Array or List of keys indicating where to find each node's children from within each node. This works in the same way as the keyPath parameter in Immutable's getIn() method. It also accepts null in place of an empty Array or List.

Returns
  • InputFunction

    A partially applied function which accepts a single tree Iterable, and returns the modified tree Iterable.

    • InputFunction: (tree: Iterable)

      InputFunction is a partially applied function returned from all 'deep' functions in immutable-recursive. It accepts an iterable, the tree of data you wish to call your deep function on, and returns the result of the deep function you're calling.

      For example, one way to use deepGet is to call it, passing in any parameters required, then call the returned function, passing in your data tree.

      const nestedMaps = fromJS({
        a: {
          b: "B",
          c: "C",
          d: {
            e: "E"
          }
        },
        f: "F"
      });
      
      return deepGet(['a','b'])(nestedMaps); // returns "B"

      This design of using a partially applied function allows immutable-recursive's functions to be chained easily with Immutable, by using them inside of an update() method. This is the preferred usage pattern as it retains chainability.

      return fromJS(someData)
          .get('tree')
          .update(deepGet(['a','b'])) // using deepGet in a chain
          .set('done', true)
          .toJS();

      You can also define a function to perform a specific operation, and use it multiple times by passing in different tree data.

      // make every node's name uppercase
      const uppercaseNames = deepMap((node) => {
          return node.update('name', (name) => name.toUpperCase());
      }, ['children']);
      
      const a = fromJS(aDataTree).update(uppercaseNames);
      const b = fromJS(aDifferentDataTree).update(uppercaseNames);
      • tree: Iterable

        The tree Iterable to be processed by one of the deep functions.

reduce

deepReduce()

function deepReduce(reducer: (reduction: *, value: *, nodePath: List, tree: Iterable) => *, childPath?: ChildPath): (tree: Iterable) => Iterable

Once fully applied, this iterates through all nodes in the provided tree, passing them all through a reducer function. Nodes are processed branch by branch in the order that Immutable maps through the child iterables, inward from leaves to the root node. Sibling nodes are processed in the order that Immutable iterates through collections.

Unlike Immutable.js, if the initialReduction is not provided or is null, then the initialReduction will be null.

Params
  • reducer: Reducer

    The function to be called for every node in the tree, the results of which will be used to create the modified tree.

    • Reducer: (reduction: *, value: *, nodePath: List, tree: Iterable)

      A function required as an argument for the deepReduce functions.

      • reduction: *

        The current reduction.

      • value: *

        The current value.

      • nodePath: List

        The current node's NodePath, a List of keys used to uniquely identify the current node.

      • tree: Iterable

        The original tree passed into the map function.

  • childPath: ?ChildPath

    An Array or List of keys indicating where to find each node's children from within each node.

    • ChildPath: ChildPath

      An Array or List of keys indicating where to find each node's children from within each node. This works in the same way as the keyPath parameter in Immutable's getIn() method. It also accepts null in place of an empty Array or List.

Returns
  • InputFunction

    A partially applied function which accepts a single tree Iterable, and returns the modified tree Iterable.

    • InputFunction: (tree: Iterable)

      InputFunction is a partially applied function returned from all 'deep' functions in immutable-recursive. It accepts an iterable, the tree of data you wish to call your deep function on, and returns the result of the deep function you're calling.

      For example, one way to use deepGet is to call it, passing in any parameters required, then call the returned function, passing in your data tree.

      const nestedMaps = fromJS({
        a: {
          b: "B",
          c: "C",
          d: {
            e: "E"
          }
        },
        f: "F"
      });
      
      return deepGet(['a','b'])(nestedMaps); // returns "B"

      This design of using a partially applied function allows immutable-recursive's functions to be chained easily with Immutable, by using them inside of an update() method. This is the preferred usage pattern as it retains chainability.

      return fromJS(someData)
          .get('tree')
          .update(deepGet(['a','b'])) // using deepGet in a chain
          .set('done', true)
          .toJS();

      You can also define a function to perform a specific operation, and use it multiple times by passing in different tree data.

      // make every node's name uppercase
      const uppercaseNames = deepMap((node) => {
          return node.update('name', (name) => name.toUpperCase());
      }, ['children']);
      
      const a = fromJS(aDataTree).update(uppercaseNames);
      const b = fromJS(aDifferentDataTree).update(uppercaseNames);
      • tree: Iterable

        The tree Iterable to be processed by one of the deep functions.

deepReduceLeaves()

function deepReduceLeaves(reducer: (reduction: *, value: *, nodePath: List, tree: Iterable) => *, childPath?: ChildPath): (tree: Iterable) => Iterable

Once fully applied, this iterates through the leaf nodes in the provided tree, passing them all through a reducer function. Leaf nodes are nodes that have no child nodes. Nodes are processed branch by branch, in the order that Immutable maps through the child iterables.

Unlike Immutable.js, if the initialReduction is not provided or is null, then the initialReduction will be null.

Params
  • reducer: Reducer

    The function to be called for every leaf node in the tree, the results of which will be used to create the modified tree.

    • Reducer: (reduction: *, value: *, nodePath: List, tree: Iterable)

      A function required as an argument for the deepReduce functions.

      • reduction: *

        The current reduction.

      • value: *

        The current value.

      • nodePath: List

        The current node's NodePath, a List of keys used to uniquely identify the current node.

      • tree: Iterable

        The original tree passed into the map function.

  • childPath: ?ChildPath

    An Array or List of keys indicating where to find each node's children from within each node.

    • ChildPath: ChildPath

      An Array or List of keys indicating where to find each node's children from within each node. This works in the same way as the keyPath parameter in Immutable's getIn() method. It also accepts null in place of an empty Array or List.

Returns
  • InputFunction

    A partially applied function which accepts a single tree Iterable, and returns the modified tree Iterable.

    • InputFunction: (tree: Iterable)

      InputFunction is a partially applied function returned from all 'deep' functions in immutable-recursive. It accepts an iterable, the tree of data you wish to call your deep function on, and returns the result of the deep function you're calling.

      For example, one way to use deepGet is to call it, passing in any parameters required, then call the returned function, passing in your data tree.

      const nestedMaps = fromJS({
        a: {
          b: "B",
          c: "C",
          d: {
            e: "E"
          }
        },
        f: "F"
      });
      
      return deepGet(['a','b'])(nestedMaps); // returns "B"

      This design of using a partially applied function allows immutable-recursive's functions to be chained easily with Immutable, by using them inside of an update() method. This is the preferred usage pattern as it retains chainability.

      return fromJS(someData)
          .get('tree')
          .update(deepGet(['a','b'])) // using deepGet in a chain
          .set('done', true)
          .toJS();

      You can also define a function to perform a specific operation, and use it multiple times by passing in different tree data.

      // make every node's name uppercase
      const uppercaseNames = deepMap((node) => {
          return node.update('name', (name) => name.toUpperCase());
      }, ['children']);
      
      const a = fromJS(aDataTree).update(uppercaseNames);
      const b = fromJS(aDifferentDataTree).update(uppercaseNames);
      • tree: Iterable

        The tree Iterable to be processed by one of the deep functions.

deepReduceParents()

function deepReduceParents(reducer: (reduction: *, value: *, nodePath: List, tree: Iterable) => *, childPath?: ChildPath): (tree: Iterable) => Iterable

Once fully applied, this iterates through the parent nodes in the provided tree, passing them all through a reducer function. Parent nodes are nodes that have child nodes. Nodes are processed branch by branch in the order that Immutable maps through the child iterables, inward from leaves to the root node.

Unlike Immutable.js, if the initialReduction is not provided or is null, then the initialReduction will be null.

Params
  • reducer: Reducer

    The function to be called for every parent node in the tree. the results of which will be used to create the modified iterable.

    • Reducer: (reduction: *, value: *, nodePath: List, tree: Iterable)

      A function required as an argument for the deepReduce functions.

      • reduction: *

        The current reduction.

      • value: *

        The current value.

      • nodePath: List

        The current node's NodePath, a List of keys used to uniquely identify the current node.

      • tree: Iterable

        The original tree passed into the map function.

  • childPath: ?ChildPath

    An Array or List of keys indicating where to find each node's children from within each node.

    • ChildPath: ChildPath

      An Array or List of keys indicating where to find each node's children from within each node. This works in the same way as the keyPath parameter in Immutable's getIn() method. It also accepts null in place of an empty Array or List.

Returns
  • InputFunction

    A partially applied function which accepts a single tree Iterable, and returns the modified tree Iterable.

    • InputFunction: (tree: Iterable)

      InputFunction is a partially applied function returned from all 'deep' functions in immutable-recursive. It accepts an iterable, the tree of data you wish to call your deep function on, and returns the result of the deep function you're calling.

      For example, one way to use deepGet is to call it, passing in any parameters required, then call the returned function, passing in your data tree.

      const nestedMaps = fromJS({
        a: {
          b: "B",
          c: "C",
          d: {
            e: "E"
          }
        },
        f: "F"
      });
      
      return deepGet(['a','b'])(nestedMaps); // returns "B"

      This design of using a partially applied function allows immutable-recursive's functions to be chained easily with Immutable, by using them inside of an update() method. This is the preferred usage pattern as it retains chainability.

      return fromJS(someData)
          .get('tree')
          .update(deepGet(['a','b'])) // using deepGet in a chain
          .set('done', true)
          .toJS();

      You can also define a function to perform a specific operation, and use it multiple times by passing in different tree data.

      // make every node's name uppercase
      const uppercaseNames = deepMap((node) => {
          return node.update('name', (name) => name.toUpperCase());
      }, ['children']);
      
      const a = fromJS(aDataTree).update(uppercaseNames);
      const b = fromJS(aDifferentDataTree).update(uppercaseNames);
      • tree: Iterable

        The tree Iterable to be processed by one of the deep functions.

deepReduceOutwards()

function deepReduceOutwards(reducer: (reduction: *, value: *, nodePath: List, tree: Iterable) => *, childPath?: ChildPath): (tree: Iterable) => Iterable

Once fully applied, this iterates through all nodes in the provided tree, passing them all through a reducer function. Nodes are processed branch by branch in the order that Immutable maps through the child iterables, outwards from the root node to the leaf nodes. Sibling nodes are processed in the order that Immutable iterates through collections.

Unlike Immutable.js, if the initialReduction is not provided or is null, then the initialReduction will be null.

Params
  • reducer: Reducer

    The function to be called for every node in the tree, the results of which will be used to create the modified tree.

    • Reducer: (reduction: *, value: *, nodePath: List, tree: Iterable)

      A function required as an argument for the deepReduce functions.

      • reduction: *

        The current reduction.

      • value: *

        The current value.

      • nodePath: List

        The current node's NodePath, a List of keys used to uniquely identify the current node.

      • tree: Iterable

        The original tree passed into the map function.

  • childPath: ?ChildPath

    An Array or List of keys indicating where to find each node's children from within each node.

    • ChildPath: ChildPath

      An Array or List of keys indicating where to find each node's children from within each node. This works in the same way as the keyPath parameter in Immutable's getIn() method. It also accepts null in place of an empty Array or List.

Returns
  • InputFunction

    A partially applied function which accepts a single tree Iterable, and returns the modified tree Iterable.

    • InputFunction: (tree: Iterable)

      InputFunction is a partially applied function returned from all 'deep' functions in immutable-recursive. It accepts an iterable, the tree of data you wish to call your deep function on, and returns the result of the deep function you're calling.

      For example, one way to use deepGet is to call it, passing in any parameters required, then call the returned function, passing in your data tree.

      const nestedMaps = fromJS({
        a: {
          b: "B",
          c: "C",
          d: {
            e: "E"
          }
        },
        f: "F"
      });
      
      return deepGet(['a','b'])(nestedMaps); // returns "B"

      This design of using a partially applied function allows immutable-recursive's functions to be chained easily with Immutable, by using them inside of an update() method. This is the preferred usage pattern as it retains chainability.

      return fromJS(someData)
          .get('tree')
          .update(deepGet(['a','b'])) // using deepGet in a chain
          .set('done', true)
          .toJS();

      You can also define a function to perform a specific operation, and use it multiple times by passing in different tree data.

      // make every node's name uppercase
      const uppercaseNames = deepMap((node) => {
          return node.update('name', (name) => name.toUpperCase());
      }, ['children']);
      
      const a = fromJS(aDataTree).update(uppercaseNames);
      const b = fromJS(aDifferentDataTree).update(uppercaseNames);
      • tree: Iterable

        The tree Iterable to be processed by one of the deep functions.

deepReduceLeavesOutwards()

function deepReduceLeavesOutwards(reducer: (reduction: *, value: *, nodePath: List, tree: Iterable) => *, childPath?: ChildPath): (tree: Iterable) => Iterable

Once fully applied, this iterates through the leaf nodes in the provided tree, passing them all through a reducer function. Nodes are processed branch by branch in the order that Immutable maps through the child iterables, outwards from the root node to the leaf nodes. Sibling nodes are processed in the order that Immutable iterates through collections.

Because this moves from the root node outwards this function behaves quite differently to the other deep map functions.

Unlike Immutable.js, if the initialReduction is not provided or is null, then the initialReduction will be null.

Params
  • reducer: Reducer

    The function to be called for every leaf node in the tree, the results of which will be used to create the modified tree.

    • Reducer: (reduction: *, value: *, nodePath: List, tree: Iterable)

      A function required as an argument for the deepReduce functions.

      • reduction: *

        The current reduction.

      • value: *

        The current value.

      • nodePath: List

        The current node's NodePath, a List of keys used to uniquely identify the current node.

      • tree: Iterable

        The original tree passed into the map function.

  • childPath: ?ChildPath

    An Array or List of keys indicating where to find each node's children from within each node.

    • ChildPath: ChildPath

      An Array or List of keys indicating where to find each node's children from within each node. This works in the same way as the keyPath parameter in Immutable's getIn() method. It also accepts null in place of an empty Array or List.

Returns
  • InputFunction

    A partially applied function which accepts a single tree Iterable, and returns the modified tree Iterable.

    • InputFunction: (tree: Iterable)

      InputFunction is a partially applied function returned from all 'deep' functions in immutable-recursive. It accepts an iterable, the tree of data you wish to call your deep function on, and returns the result of the deep function you're calling.

      For example, one way to use deepGet is to call it, passing in any parameters required, then call the returned function, passing in your data tree.

      const nestedMaps = fromJS({
        a: {
          b: "B",
          c: "C",
          d: {
            e: "E"
          }
        },
        f: "F"
      });
      
      return deepGet(['a','b'])(nestedMaps); // returns "B"

      This design of using a partially applied function allows immutable-recursive's functions to be chained easily with Immutable, by using them inside of an update() method. This is the preferred usage pattern as it retains chainability.

      return fromJS(someData)
          .get('tree')
          .update(deepGet(['a','b'])) // using deepGet in a chain
          .set('done', true)
          .toJS();

      You can also define a function to perform a specific operation, and use it multiple times by passing in different tree data.

      // make every node's name uppercase
      const uppercaseNames = deepMap((node) => {
          return node.update('name', (name) => name.toUpperCase());
      }, ['children']);
      
      const a = fromJS(aDataTree).update(uppercaseNames);
      const b = fromJS(aDifferentDataTree).update(uppercaseNames);
      • tree: Iterable

        The tree Iterable to be processed by one of the deep functions.

deepReduceParentsOutwards()

function deepReduceParentsOutwards(reducer: (reduction: *, value: *, nodePath: List, tree: Iterable) => *, childPath?: ChildPath): (tree: Iterable) => Iterable

Once fully applied, this iterates through the parent nodes in the provided tree, passing them all through a reducer function. Nodes are processed branch by branch in the order that Immutable maps through the child iterables, outwards from the root node to the leaf nodes. Sibling nodes are processed in the order that Immutable iterates through collections.

Because this moves from the root node outwards this function behaves quite differently to the other deep map functions.

Unlike Immutable.js, if the initialReduction is not provided or is null, then the initialReduction will be null.

Params
  • reducer: Reducer

    The function to be called for every parent node in the tree, the results of which will be used to create the modified tree.

    • Reducer: (reduction: *, value: *, nodePath: List, tree: Iterable)

      A function required as an argument for the deepReduce functions.

      • reduction: *

        The current reduction.

      • value: *

        The current value.

      • nodePath: List

        The current node's NodePath, a List of keys used to uniquely identify the current node.

      • tree: Iterable

        The original tree passed into the map function.

  • childPath: ?ChildPath

    An Array or List of keys indicating where to find each node's children from within each node.

    • ChildPath: ChildPath

      An Array or List of keys indicating where to find each node's children from within each node. This works in the same way as the keyPath parameter in Immutable's getIn() method. It also accepts null in place of an empty Array or List.

Returns
  • InputFunction

    A partially applied function which accepts a single tree Iterable, and returns the modified tree Iterable.

    • InputFunction: (tree: Iterable)

      InputFunction is a partially applied function returned from all 'deep' functions in immutable-recursive. It accepts an iterable, the tree of data you wish to call your deep function on, and returns the result of the deep function you're calling.

      For example, one way to use deepGet is to call it, passing in any parameters required, then call the returned function, passing in your data tree.

      const nestedMaps = fromJS({
        a: {
          b: "B",
          c: "C",
          d: {
            e: "E"
          }
        },
        f: "F"
      });
      
      return deepGet(['a','b'])(nestedMaps); // returns "B"

      This design of using a partially applied function allows immutable-recursive's functions to be chained easily with Immutable, by using them inside of an update() method. This is the preferred usage pattern as it retains chainability.

      return fromJS(someData)
          .get('tree')
          .update(deepGet(['a','b'])) // using deepGet in a chain
          .set('done', true)
          .toJS();

      You can also define a function to perform a specific operation, and use it multiple times by passing in different tree data.

      // make every node's name uppercase
      const uppercaseNames = deepMap((node) => {
          return node.update('name', (name) => name.toUpperCase());
      }, ['children']);
      
      const a = fromJS(aDataTree).update(uppercaseNames);
      const b = fromJS(aDifferentDataTree).update(uppercaseNames);
      • tree: Iterable

        The tree Iterable to be processed by one of the deep functions.

set

deepSet()

function deepSet(nodePath: NodePath, value: *, childPath?: ChildPath): (tree: Iterable) => Iterable

Once fully applied, this returns a new tree containing the new node value at the location determined by nodePath. If an equivalent node already exists in this tree it will be replaced. If any keys on nodePath do not exist, a new Immutable Map will be created at the missing key.

Be aware that by setting values on deep nodes that don't yet exist, this may cause Maps to be created for child Iterables where other types of Iterables may be used for children elsewhere in the tree. This will be addressed in a future release.

When no childPath is provided then this is functionally equivalent to Immutable's setIn() method.

Params
  • nodePath: NodePath

    A NodePath used to uniquely identify the node to set.

    • NodePath: NodePath

      When passed as a parameter, NodePath can be a List or an Array of keys used to uniquely identify a node. Almost always used in conjunction with a ChildPath. Also accepts null in place of an empty Array or List.

      Whenever NodePath is returned from a function in the immutable-recursive library, it will always be a List.

  • value: *

    The value to set the node to.

  • childPath: ?ChildPath

    An Array or List of keys indicating where to find each node's children from within each node.

    • ChildPath: ChildPath

      An Array or List of keys indicating where to find each node's children from within each node. This works in the same way as the keyPath parameter in Immutable's getIn() method. It also accepts null in place of an empty Array or List.

Returns
  • InputFunction

    A partially applied function which accepts a single tree Iterable, and returns the modified tree Iterable.

    • InputFunction: (tree: Iterable)

      InputFunction is a partially applied function returned from all 'deep' functions in immutable-recursive. It accepts an iterable, the tree of data you wish to call your deep function on, and returns the result of the deep function you're calling.

      For example, one way to use deepGet is to call it, passing in any parameters required, then call the returned function, passing in your data tree.

      const nestedMaps = fromJS({
        a: {
          b: "B",
          c: "C",
          d: {
            e: "E"
          }
        },
        f: "F"
      });
      
      return deepGet(['a','b'])(nestedMaps); // returns "B"

      This design of using a partially applied function allows immutable-recursive's functions to be chained easily with Immutable, by using them inside of an update() method. This is the preferred usage pattern as it retains chainability.

      return fromJS(someData)
          .get('tree')
          .update(deepGet(['a','b'])) // using deepGet in a chain
          .set('done', true)
          .toJS();

      You can also define a function to perform a specific operation, and use it multiple times by passing in different tree data.

      // make every node's name uppercase
      const uppercaseNames = deepMap((node) => {
          return node.update('name', (name) => name.toUpperCase());
      }, ['children']);
      
      const a = fromJS(aDataTree).update(uppercaseNames);
      const b = fromJS(aDifferentDataTree).update(uppercaseNames);
      • tree: Iterable

        The tree Iterable to be processed by one of the deep functions.

deepSetChildren()

function deepSetChildren(nodePath: NodePath, value: *, childPath?: ChildPath): (tree: Iterable) => Iterable

Once fully applied, this returns a new tree where the children Iterable of the node at nodePath are set to value. If no node exists at nodePath then an Immutable Map will be created at that location.

This is intended to be used with a childPath, but if no childPath is provided then this is functionally equivalent to both Immutable's setIn() method and deepSet().

Params
  • nodePath: NodePath

    A NodePath used to uniquely identify a node whose children will be set.

    • NodePath: NodePath

      When passed as a parameter, NodePath can be a List or an Array of keys used to uniquely identify a node. Almost always used in conjunction with a ChildPath. Also accepts null in place of an empty Array or List.

      Whenever NodePath is returned from a function in the immutable-recursive library, it will always be a List.

  • value: *

    The value to set the node to.

  • childPath: ?ChildPath

    An Array or List of keys indicating where to find each node's children from within each node.

    • ChildPath: ChildPath

      An Array or List of keys indicating where to find each node's children from within each node. This works in the same way as the keyPath parameter in Immutable's getIn() method. It also accepts null in place of an empty Array or List.

Returns
  • InputFunction

    A partially applied function which accepts a single tree Iterable, and returns the modified tree Iterable.

    • InputFunction: (tree: Iterable)

      InputFunction is a partially applied function returned from all 'deep' functions in immutable-recursive. It accepts an iterable, the tree of data you wish to call your deep function on, and returns the result of the deep function you're calling.

      For example, one way to use deepGet is to call it, passing in any parameters required, then call the returned function, passing in your data tree.

      const nestedMaps = fromJS({
        a: {
          b: "B",
          c: "C",
          d: {
            e: "E"
          }
        },
        f: "F"
      });
      
      return deepGet(['a','b'])(nestedMaps); // returns "B"

      This design of using a partially applied function allows immutable-recursive's functions to be chained easily with Immutable, by using them inside of an update() method. This is the preferred usage pattern as it retains chainability.

      return fromJS(someData)
          .get('tree')
          .update(deepGet(['a','b'])) // using deepGet in a chain
          .set('done', true)
          .toJS();

      You can also define a function to perform a specific operation, and use it multiple times by passing in different tree data.

      // make every node's name uppercase
      const uppercaseNames = deepMap((node) => {
          return node.update('name', (name) => name.toUpperCase());
      }, ['children']);
      
      const a = fromJS(aDataTree).update(uppercaseNames);
      const b = fromJS(aDifferentDataTree).update(uppercaseNames);
      • tree: Iterable

        The tree Iterable to be processed by one of the deep functions.

update

deepUpdate()

function deepUpdate(nodePath: NodePath, updater: (value: *) => *, childPath?: ChildPath, notSetValue?: *): (tree: Iterable) => Iterable

Once fully applied, this returns a new tree with the node at nodePath set to the return value of updater. If any keys on nodePath do not exist, a new Immutable Map will be created at the missing key. If the node at nodePath doesn't exist, updater will be called with the value of notSetValue.

Be aware that by updating values on deep nodes that don't yet exist, this may cause Maps to be created for child Iterables where other types of Iterables may be used for children elsewhere in the tree. This will be addressed in a future release.

This is intended to be used with a childPath, but if no childPath is provided then this is functionally equivalent to Immutable's updateIn() method.

Params
  • nodePath: NodePath

    A NodePath used to uniquely identify the node to update.

    • NodePath: NodePath

      When passed as a parameter, NodePath can be a List or an Array of keys used to uniquely identify a node. Almost always used in conjunction with a ChildPath. Also accepts null in place of an empty Array or List.

      Whenever NodePath is returned from a function in the immutable-recursive library, it will always be a List.

  • updater: Updater

    The function to update the node, which is passed the existing node and must return the updated value of the node.

    • Updater: (value: *)

      A function required as an argument for the deepUpdate functions.

      • value: *

        The value to update.

  • childPath: ?ChildPath

    An Array or List of keys indicating where to find each node's children from within each node.

    • ChildPath: ChildPath

      An Array or List of keys indicating where to find each node's children from within each node. This works in the same way as the keyPath parameter in Immutable's getIn() method. It also accepts null in place of an empty Array or List.

  • notSetValue: ?*

    When there is no node corresponding to nodePath, this value is passed into updater.

Returns
  • InputFunction

    A partially applied function which accepts a single tree Iterable, and returns the modified tree Iterable.

    • InputFunction: (tree: Iterable)

      InputFunction is a partially applied function returned from all 'deep' functions in immutable-recursive. It accepts an iterable, the tree of data you wish to call your deep function on, and returns the result of the deep function you're calling.

      For example, one way to use deepGet is to call it, passing in any parameters required, then call the returned function, passing in your data tree.

      const nestedMaps = fromJS({
        a: {
          b: "B",
          c: "C",
          d: {
            e: "E"
          }
        },
        f: "F"
      });
      
      return deepGet(['a','b'])(nestedMaps); // returns "B"

      This design of using a partially applied function allows immutable-recursive's functions to be chained easily with Immutable, by using them inside of an update() method. This is the preferred usage pattern as it retains chainability.

      return fromJS(someData)
          .get('tree')
          .update(deepGet(['a','b'])) // using deepGet in a chain
          .set('done', true)
          .toJS();

      You can also define a function to perform a specific operation, and use it multiple times by passing in different tree data.

      // make every node's name uppercase
      const uppercaseNames = deepMap((node) => {
          return node.update('name', (name) => name.toUpperCase());
      }, ['children']);
      
      const a = fromJS(aDataTree).update(uppercaseNames);
      const b = fromJS(aDifferentDataTree).update(uppercaseNames);
      • tree: Iterable

        The tree Iterable to be processed by one of the deep functions.

deepUpdateChildren()

function deepUpdateChildren(nodePath: NodePath, updater: (value: *) => *, childPath?: ChildPath, notSetValue?: *): (tree: Iterable) => Iterable

Once fully applied, this returns a new tree with the children of the node at nodePath set to the return value of updater.

If no childPath is used there will be no change if the node at nodePath is not Iterable.

If no node exists at nodePath then an Immutable Map will be created at that location. If the node at nodePath doesn't exist, updater will be called with the value of notSetValue.

This is intended to be used with a childPath, but if no childPath is provided then this is functionally equivalent to both Immutable's 'updateIn()method anddeepUpdate()`.

Params
  • nodePath: NodePath

    A NodePath used to uniquely identify a node whose children will be updated.

    • NodePath: NodePath

      When passed as a parameter, NodePath can be a List or an Array of keys used to uniquely identify a node. Almost always used in conjunction with a ChildPath. Also accepts null in place of an empty Array or List.

      Whenever NodePath is returned from a function in the immutable-recursive library, it will always be a List.

  • updater: Updater

    The function to update the node, which is passed the existing node's children and must return the updated value of the node's children.

    • Updater: (value: *)

      A function required as an argument for the deepUpdate functions.

      • value: *

        The value to update.

  • childPath: ?ChildPath

    An Array or List of keys indicating where to find each node's children from within each node.

    • ChildPath: ChildPath

      An Array or List of keys indicating where to find each node's children from within each node. This works in the same way as the keyPath parameter in Immutable's getIn() method. It also accepts null in place of an empty Array or List.

  • notSetValue: ?*

    When there is no node corresponding to nodePath, this value is passed into updater.

Returns
  • InputFunction

    A partially applied function which accepts a single tree Iterable, and returns the modified tree Iterable.

    • InputFunction: (tree: Iterable)

      InputFunction is a partially applied function returned from all 'deep' functions in immutable-recursive. It accepts an iterable, the tree of data you wish to call your deep function on, and returns the result of the deep function you're calling.

      For example, one way to use deepGet is to call it, passing in any parameters required, then call the returned function, passing in your data tree.

      const nestedMaps = fromJS({
        a: {
          b: "B",
          c: "C",
          d: {
            e: "E"
          }
        },
        f: "F"
      });
      
      return deepGet(['a','b'])(nestedMaps); // returns "B"

      This design of using a partially applied function allows immutable-recursive's functions to be chained easily with Immutable, by using them inside of an update() method. This is the preferred usage pattern as it retains chainability.

      return fromJS(someData)
          .get('tree')
          .update(deepGet(['a','b'])) // using deepGet in a chain
          .set('done', true)
          .toJS();

      You can also define a function to perform a specific operation, and use it multiple times by passing in different tree data.

      // make every node's name uppercase
      const uppercaseNames = deepMap((node) => {
          return node.update('name', (name) => name.toUpperCase());
      }, ['children']);
      
      const a = fromJS(aDataTree).update(uppercaseNames);
      const b = fromJS(aDifferentDataTree).update(uppercaseNames);
      • tree: Iterable

        The tree Iterable to be processed by one of the deep functions.

delete

deepDelete()

function deepDelete(nodePath: NodePath, childPath?: ChildPath): (tree: Iterable) => Iterable

Once fully applied, this returns a new tree that no longer contains the node at nodePath, or any of its child nodes. If there is no node at nodePath then no change will occur.

When no childPath is provided then this is functionally equivalent to Immutable's deleteIn() method.

Params
  • nodePath: NodePath

    A NodePath used to uniquely identify the node to delete.

    • NodePath: NodePath

      When passed as a parameter, NodePath can be a List or an Array of keys used to uniquely identify a node. Almost always used in conjunction with a ChildPath. Also accepts null in place of an empty Array or List.

      Whenever NodePath is returned from a function in the immutable-recursive library, it will always be a List.

  • childPath: ?ChildPath

    An Array or List of keys indicating where to find each node's children from within each node.

    • ChildPath: ChildPath

      An Array or List of keys indicating where to find each node's children from within each node. This works in the same way as the keyPath parameter in Immutable's getIn() method. It also accepts null in place of an empty Array or List.

Returns
  • InputFunction

    A partially applied function which accepts a single tree Iterable, and returns the modified tree Iterable.

    • InputFunction: (tree: Iterable)

      InputFunction is a partially applied function returned from all 'deep' functions in immutable-recursive. It accepts an iterable, the tree of data you wish to call your deep function on, and returns the result of the deep function you're calling.

      For example, one way to use deepGet is to call it, passing in any parameters required, then call the returned function, passing in your data tree.

      const nestedMaps = fromJS({
        a: {
          b: "B",
          c: "C",
          d: {
            e: "E"
          }
        },
        f: "F"
      });
      
      return deepGet(['a','b'])(nestedMaps); // returns "B"

      This design of using a partially applied function allows immutable-recursive's functions to be chained easily with Immutable, by using them inside of an update() method. This is the preferred usage pattern as it retains chainability.

      return fromJS(someData)
          .get('tree')
          .update(deepGet(['a','b'])) // using deepGet in a chain
          .set('done', true)
          .toJS();

      You can also define a function to perform a specific operation, and use it multiple times by passing in different tree data.

      // make every node's name uppercase
      const uppercaseNames = deepMap((node) => {
          return node.update('name', (name) => name.toUpperCase());
      }, ['children']);
      
      const a = fromJS(aDataTree).update(uppercaseNames);
      const b = fromJS(aDifferentDataTree).update(uppercaseNames);
      • tree: Iterable

        The tree Iterable to be processed by one of the deep functions.

deepDeleteChildren()

function deepDeleteChildren(nodePath: NodePath, childPath?: ChildPath): (tree: Iterable) => Iterable

Once fully applied, this returns a new tree where the children of the node at nodePath have been deleted. The child container will still remain. This is the equivalent of calling the following:

deepUpdateChildren(nodePath, kids => kids.clear(), childPath);

No change will occur if any of the following circumstances are true:

  • If there is no node at nodePath
  • If childPath is provided and the node has no child Iterable
  • If no childPath is provided and the node itself is not Iterable

If no childPath is provided and the node is Iterable, then this has the same effect as calling clear() on the node.

Params
  • nodePath: NodePath

    A NodePath used to uniquely identify a node whose children will be deleted.

    • NodePath: NodePath

      When passed as a parameter, NodePath can be a List or an Array of keys used to uniquely identify a node. Almost always used in conjunction with a ChildPath. Also accepts null in place of an empty Array or List.

      Whenever NodePath is returned from a function in the immutable-recursive library, it will always be a List.

  • childPath: ?ChildPath

    An Array or List of keys indicating where to find each node's children from within each node.

    • ChildPath: ChildPath

      An Array or List of keys indicating where to find each node's children from within each node. This works in the same way as the keyPath parameter in Immutable's getIn() method. It also accepts null in place of an empty Array or List.

Returns
  • InputFunction

    A partially applied function which accepts a single tree Iterable, and returns the modified tree Iterable.

    • InputFunction: (tree: Iterable)

      InputFunction is a partially applied function returned from all 'deep' functions in immutable-recursive. It accepts an iterable, the tree of data you wish to call your deep function on, and returns the result of the deep function you're calling.

      For example, one way to use deepGet is to call it, passing in any parameters required, then call the returned function, passing in your data tree.

      const nestedMaps = fromJS({
        a: {
          b: "B",
          c: "C",
          d: {
            e: "E"
          }
        },
        f: "F"
      });
      
      return deepGet(['a','b'])(nestedMaps); // returns "B"

      This design of using a partially applied function allows immutable-recursive's functions to be chained easily with Immutable, by using them inside of an update() method. This is the preferred usage pattern as it retains chainability.

      return fromJS(someData)
          .get('tree')
          .update(deepGet(['a','b'])) // using deepGet in a chain
          .set('done', true)
          .toJS();

      You can also define a function to perform a specific operation, and use it multiple times by passing in different tree data.

      // make every node's name uppercase
      const uppercaseNames = deepMap((node) => {
          return node.update('name', (name) => name.toUpperCase());
      }, ['children']);
      
      const a = fromJS(aDataTree).update(uppercaseNames);
      const b = fromJS(aDifferentDataTree).update(uppercaseNames);
      • tree: Iterable

        The tree Iterable to be processed by one of the deep functions.