npm package: @oscbco/get-nested-array-element-by-position
Description: This small library allows for traversing a structure of nested arrays as a single one-dimensional array. Making it possible to use a single for loop to iterate through all the nested array nodes
Author: oscbco
Latest version: 0.0.3

# get-nested-array-element-by-position
Project website at [oscbco-libraries.gitlab.io/get-nested-array-element-by-position/](https://oscbco-libraries.gitlab.io/get-nested-array-element-by-position/)

This small library allows for traversing a structure of nested arrays as a single one-dimensional array. Making it possible to use a single `for loop` to iterate through all the nested array nodes

Nodes are returned by their position in the nested structure.

Nodes in the current array will be returned first, however if a node has a "child array" then nodes in the "child array" are returned before continuing with the current array. This is true for their children as well.

Required properties for these array structures:

  An object with these 2 properties:

  `value`: This is the payload of the node.

  `child`: Reference to the child array, or if it doesn't have one then it MUST be `null`

## Installation:
  ```bash
    npm install --save @oscbco/get-nested-array-element-by-position
  ```

You can import it like this:
  ```javascript
    let getNestedArrayElementByPosition = require('@oscbco/get-nested-array-element-by-position');
  ```

For example, the following code:

  ```javascript
    const getNestedArrayElementByPosition = require('@oscbco/get-nested-array-element-by-position');

    const collection = [
      {
        value: '/public',
        child: [
          {
            value: '/public/js',
            child: [
              {
                value: '/public/js/index.js',
                child: null
              }
            ]
          }
        ]
      },
      {
        value: '/public/images',
        child: [
          {
            value: '/public/images/logo.png',
            child: null
          },
          {
            value: '/public/images/header.png',
            child: null
          },
          {
            value: '/public/images/background.png',
            child: null
          }
        ]
      },
      {
        value: '/source',
        child: [
          {
            value: '/source/index.js',
            child: null
          }
        ]
      }
    ];

    let counter = 0;
    let node = null;
    let concatenatedNodes = '';
    do {
      node = getNestedArrayElementByPosition.findNode({collection, requestedIndex: counter});
      concatenatedNodes += node.value ? node.value + '\n' : '';
      counter++;
    } while (node.keypath !== undefined);
    console.log(concatenatedNodes);

    console.log("Example: Node at position 6\n", JSON.stringify(getNestedArrayElementByPosition.findNode({collection, requestedIndex: 6}), null, 2));

    console.log("Example: Node at a nonexistent position\n", JSON.stringify(getNestedArrayElementByPosition.findNode({collection, requestedIndex: 9}), null, 2));

  ```
  Results in:

    /public
    /public/js
    /public/js/index.js
    /public/images
    /public/images/logo.png
    /public/images/header.png
    /public/images/background.png
    /source
    /source/index.js

    Example: Node at position 6
    {
      "value": "/public/images/background.png",
      "count": 6,
      "keypath": [
        1,
        2
      ]
    }
    Example: Node at a nonexistent position
    {}


  `findNode` returns the `value` property of the node as well as the `count` and `keypath`.

  `count` and `keypath` are used by the library to speed up subsequent lookups because we don't have to start counting from zero, instead we use the last known count and keypath and start from there.

  If a node at a given position does not exist, then `findNode` returns:
  ```javascript
    {
      value: undefined,
      count: undefined,
      keypath: undefined
    }
  ```
## ToDo:
  - Wrap the array structure in a class and add CRUD methods
  - A method to count all elements

## Development
  If you want more info on how this project is structured and how this helps with development, testing, building the documentation and its own static website visit: <tt> [http://oscbco-boilerplate.gitlab.io/webpack-npm-library-boilerplate/](http://oscbco-boilerplate.gitlab.io/webpack-npm-library-boilerplate/)</tt>