npm package: @mentoc/utils
Description: A library of useful functions.
Author: William Merfalen
Latest version: 1.1.1

# js-utils
A collection of **composable** utility functions. Take what you need, and uninstall the library.
No more bloated utility libraries. Did I mention, I added a minify step?

# Motivation
I feel like there are bits of functionality that I need to use everyday in my javascript projects. 
All the functionality I'm looking for isn't there or is inside another npm package. I **solved** the
npm portion by allowing developers the option to extract only specific functions. This makes it so
that developers are no longer tied to an NPM repo. Take the functions you need and uninstall the library.

# Installation
```
npm install @mentoc/utils
```

# Before you copy and paste!
Did you know, this library can export only the functions you need?
Let's say we only want the `random_array` and `shuffle` functions.
Easy. All we have to do is run this:
```
npm run pluck rand.random_array rand.shuffle
```
Now if you do an ls, you will notice that there is now a `lib.js` file.
If you look at the contents of lib.js, you'll notice it only contains
two exports (for both of the functions we exported). 

This command uses *dot notation*. 

If you just run `npm run pluck`, you will be greeted with this
object structure:
```
{
  rand: {
    random_array: [Function],
    pluck_random: [Function],
    shuffle: [Function],
    shuffle_for: [Function],
    random_hex: [Function]
  },
  array: { seq: [Function], xtract: [Function] }
}
```

If you want to export the `xtract` function, you would run:
```
npm run pluck array.xtract
```

## Specifying the inverse
You can use `npm run pluck-except <name>...` to pluck everything except
for a few functions.
```
npm run pluck-except rand.shuffle
```
This will extract the entire library except for `shuffle`

# RNG API (for Arrays)

## Grabbing a random array element
```
const {pluck_random} = require('@mentoc/utils').rand

const data = [1,2,3,4,5,6,7,8,9,10]

console.log(pluck_random(data))
```

## Generate an array of fixed length with random numbers between a range
```
const {random_array} = require('@mentoc/utils').rand

/**
 * Generate a random array of 20 elements.
 * Each element is between the number 1 and 100
 */
let data_set = random_array(1,100,20)

console.log(data_set)
```


## Shuffle an array
```
const {shuffle} = require('@mentoc/utils').rand

const data_set = [1,2,3,4,5,6,7,8,9,10]

console.log(shuffle(data_set))
```

## Shuffle an array by passing in more/less rounds
Maybe you want the algorithm to shuffle more than just one time. For this, you can
use the `shuffle_for` function. It accepts a number of rounds as it's second parameter.

```
const {shuffle_for} = require('@mentoc/utils').rand

const data_set = [1,2,3,4,5,6,7,8,9,10]

/**
 * This is equivalent to calling shuffle(data_set) 250 times in a loop
 */
console.log(shuffle_for(data_set,250))
```


# Dot notation API
## Use dot notation to grab an element out of a deeply nested structure
```
const {xtract} = require('@mentoc/utils').array
/** Grab an element out of a deeply nested structure */
let obj = [
    {
        user: {
            id: 1,
            name: "Larry Kenobi",
        }
    },
    {
        user: {
            id: 2,
            name: "Jerry Kenobi",
        }
    },
    {
        user: {
            id: 3,
            name: "John Kenobi",
        }
    }
]

let larry_schema = '0.user.name'
let john_schema = '2.user.name'
console.log('Example dataset: ',obj)

console.log(xtract(obj,larry_schema))    // prints "Larry Kenobi"
console.log(xtract(obj,john_schema))     // prints "John Kenobi"

```

## Use dot notation to delete an element out of a deeply nested structure
```
const {prune} = require('@mentoc/utils').array
/** Delete an element out of a deeply nested structure */
let obj = [
    {
        user: {
            id: 1,
            name: "Larry Kenobi",
        }
    },
    {
        user: {
            id: 2,
            name: "Jerry Kenobi",
        }
    },
    {
        user: {
            id: 3,
            name: "John Kenobi",
        }
    }
]
console.log(prune(obj,'1.user.name'))   // removes name: "Jerry Kenobi" from object
```

# Alternate notation API
There are times when you simply cannot pass in a dot notation in order to crawl
a deeply nested structure. An object key can be *any* string value. This complicates
matters and breaks the dot notation API. That is why the following functions accept
either a `string` or an `array` as the second parameter.

## xtract using an array schema
```
const {xtract} = require('@mentoc/utils').array
const first = "-1-_ yes, @#!_this is a valid key\"\"'"
const second = '_9-1 j#'
const weird_object = {
    "-1-_ yes, @#!_this is a valid key\"\"'": [
        {
            'z -1 +4': {
                id: 1,
                name: 'john doe'
            },
            '_9-1 j#': {
                id: 2,
                name: 'jane doe',
            },
        }
    ]
}
/**
 * Notice how we are passing in an array as opposed to a string for the 
 * second parameter here.
 */
let jane_doe = xtract(weird_object,[first,0,second,'name'])
console.log(jane_doe) // will print "jane doe"
```

## prune using an array schema
```
const {prune} = require('@mentoc/utils').array
const first = "-1-_ yes, @#!_this is a valid key\"\"'"
const second = '_9-1 j#'
const weird_object = {
    "-1-_ yes, @#!_this is a valid key\"\"'": [
        {
            'z -1 +4': {
                id: 1,
                name: 'john doe'
            },
            '_9-1 j#': {
                id: 2,
                name: 'jane doe',
            },
        }
    ]
}
/**
 * Notice how we are passing in an array as opposed to a string for the 
 * second parameter here.
 */
let pruned = prune(weird_object,[first,0,second,'name'])
console.log('removed the name of the object with id 2: ',pruned[first][0])

// output of above console.log:
// removed the name of the object with id 2:  { 'z -1 +4': { id: 1, name: 'john doe' }, '_9-1 j#': { id: 2 } }

```

# Array generation API
## Generate an array of sequential numbers
```
const {seq} = require('@mentoc/utils').array

/**
 * The next line creates: [1,2,3,4,5,6,7]
 */
const data_set = seq(1,7)
```

# RNG API (for Strings)

## Grabbing a random string of hexadecimal characters
```
const {random_hex} = require('@mentoc/utils').rand

const length = 16

console.log(random_hex(16))	// Prints out 16 hex chars (without prepending zeroes)
```


# Using the pluck npm commands
As stated above, you can export only the functions you need. This is all done for you
through the pluck npm commands. Here are the available commands:

### pluck
- **Description**: Pass in several dot-notation functions that you would like to export to `lib.js`
- **Syntax**: `npm run pluck category.name... [category.name-N]`
- **Example**: `npm run pluck rand.shuffle rand.rand_between`
  
### pluck-except
- **Description**: Export every function *EXCEPT* for the functions you specify
- **Syntax**: `npm run pluck-except category.name... [category.name-N]`
- **Example**: `npm run pluck-except rand.shuffle # exports the whole library except for rand.shuffle`

### pluck-minified
- **Description**: Just like `pluck` only this time use the minified versions.

### pluck-minified-except
- **Description**: Just like `pluck-except` only this time use the minified versions.

### minify-export
- **Description**: If you've already got a `lib.js`, run this command to minify it into `lib.min.js`

### export
- **Description**: Exports the entire library without minify.

### export-minified
- **Description**: Just like `export`, only this time minify the results.



# How to run the unit tests
```
npm run test
```

# Contributors
- William Merfalen (concept and initial coder)
- A.J. O'neil (resident technologist and node enthusiast)