lemonutilities/README.md

Lightweight and simple JavaScript library for file management, randomization, and for CLIs.

# LemonUtilities
LemonUtilities is a lightweight and simple JavaScript library for file management, randomization, and for CLIs (Console User Interfaces).

# Setup


## Installation

Go to your console, and type the following commands in order

```bash
cd "C:/path/to/your/project"
```
```bash
npm install lemonutilities
```

## How to Use
In your main JavaScript file, write the following

```javascript
const {file, random, cli} = require('lemonutilities');
```

Down below, you will find a list of functions LemonUtilitites has to offer.

# Functions


## File Management

### getFiles(directoryPath, fileExtension)
-   Description: Gets files from a folder or directory
-   Parameters:
    - `directoryPath` (`string`): Path to check
    - `fileExtension` (`string`, optional): File extension to check for
- Returns (`array`): Array of all file names
- Example:
```javascript
const images = file.getFiles('goober', 'png');

// ['bird.png', 'cat.png', 'dog.png', 'sillygoober.png']
console.log(images);
```

### getSubFolders(directoryPath)
-   Description: Gets subfolders from a folder or directory
-   Parameters:
    - `directoryPath` (`string`): Path to check
- Returns (`array`): Array of all subfolder names
- Example:
```javascript
const subfolders = file.getSubFolders('goober');

// ['extra silly', 'very gooberish']
console.log(subfolders);
```

### moveDir(directoryPath, destinationFolderPath)
-   Description: Moves a file, or an entire folder
-   Parameters:
    - `directoryPath` (`string`): Path to file
    - `destinationFolderPath` (`string`): Folder to move the file to
- Example:
```javascript
file.moveDir('goober/cat.png', 'goober/extra silly');
```

### renameDir(directoryPath, newFileName)
-   Description: Renames a file, or a folder
-   Parameters:
    - `directoryPath` (`string`): File to rename
    - `newFileName` (`string`): New file name
- Example:
```javascript
file.renameDir('goober/extra silly/cat.png', 'silly car.png');

```

### cloneFile(filePath, destinationFolderPath)
-   Description: Clones a file to a specified destination
-   Parameters:
    - `filePath` (`string`): Path to file
    - `destinationFolderPath` (`string`): New file path
- Example:
```javascript
file.cloneFile('goober/very silly/silly car.png', 'goober of the day/silly car.png');
```

### cloneDir(directoryPath, destinationFolderPath)
-   Description: Clones a folder and all contents to a specified destination
-   Parameters:
    - `directoryPath` (`string`): Path to file
    - `destinationFolderPath` (`string`): New file path
- Example:
```javascript
file.cloneDir('goober/very silly/silly car.png', 'goober of the day/silly car.png');
```

### calculateSize(directoryPath)
-   Description: Calculates the size of a file or folder contents in bytes
-   Parameters:
    - `directoryPath` (`string`): Path to file
- Returns (`string`): Byte size
- Example:
```javascript
const size = file.calculateDirSize('goober/bird.png');


// bird.png is 295419 bytes. (295.419KB)
console.log(`bird.png is ${size} bytes. (${size/1000}KB)`);
```


## Randomness

### num(min, max)
-   Description: Returns a random number
-   Parameters:
    - `min` (`number`): Minimum value
    - `max` (`number`): Maximum value
- Returns (`num`): Random number
- Example:
```javascript
const num = random.num(0, 10);

console.log(num);
```

### int(min, max)
-   Description: Returns a random whole number
-   Parameters:
    - `min` (`number`): Minimum value
    - `max` (`number`): Maximum value
- Returns (`num`): Random number
- Example:
```javascript
const num = random.int(0, 10);

console.log(num);
```

### item(array)
-   Description: Returns a random item from an array
-   Parameters:
    - `array` (`array`): Array to get item from
- Returns (`any`): Random item
- Example:
```javascript
const items = ['goober', 'cat', 'dog', 'bird', true, false, 7, 8.5];
const item = random.item(items);

console.log(item);
```

### arrayShuffle(array)
-   Description: Shuffles an array
-   Parameters:
    - `array` (`array`):
- Returns (`array`): Shuffled array
- Example:
```javascript
const items = ['goober', 'cat', 'dog', 'bird', true, false, 7, 8.5];
const shuffledItems = random.arrayShuffle(items);

console.log(shuffledItems);
```

### chance(...chances)
-   Description: Generates a random chance based on the inputed values
-   Parameters:
    - `...chances` (`number`): Chances
- Example:
```javascript
const animals = ['cat', 'dog', 'bird'];
const chance = random.chance(10, 8, 3);

/*
10 in 21 chance it will return 0,
8 in 21 for 1,
and 3 in 21 for 2
*/
console.log(animals[chance]);
```

### generateToken(prefix)
-   Description: Generates a random token for use in applications requiring secure identifiers
-   Parameters:
    - `prefix` (`string`, optional): Prefix of the token
- Returns (`string`): Generated token
- Example:
```javascript
const token = random.generateToken('LEM-');

console.log(token);
```


## Inputs

### consoleInput() (async function)
-   Description: Asks user for input
- Returns (`string`): Response
- Example:
```javascript
console.log('is the cat a goober? [y/n]\n\n');

cli.consoleInput().then(response =>  {
    if (response.toLowerCase == 'y') {
        console.log('YAYAYAYAYAYY');
    } else {
        console.log('Aw man :(');
    }
});

console.log('Gets printed after, but before the user hits enter.');
```
OR
```javascript
console.log('is the cat a goober? [y/n]\n\n');

// This function needs to be async
async function askQuestion() {
    const response = await cli.consoleInput();

    if (response.toLowerCase == 'y') {
        console.log('YAYAYAYAYAYY');
    } else {
        console.log('Aw man :(');
    }

    console.log('Gets printed after the user hits enter.');
}

askQuestion();
```

### deleteLines(num)
-   Description: Delete a specified amount of lines already printed in the console
-   Parameters:
    - `num` (`number`): How many lines to delete
- Example:
```javascript
async function deleteLinesExample() {
    console.log('Cloning folder in 5 seconds...');

    // See below
    await cli.wait(5);

    cli.deleteLines(1);

    console.log('Silliest as can be :3');
}

deleteLinesExample();
```

### clear()
-   Description: Clears the entire console
- Example:
```javascript
console.log('clearing...');

cli.clear();
```


### wait(seconds, showCountdown) (async function)
-   Description: Waits a specified amount of time in seconds before allowing further code to run
-   Parameters:
    - `seconds` (`number`): Time to wait in seconds
    - `showCountdown` (`bool`, optional): Shows "Waiting... x" message
- Example:
```javascript
// This function needs to be async
async function waitExample() {
    console.log('Cloning folder in 5 seconds...');

    await cli.wait(5, true);

    file.cloneDir('goober/very silly', 'important');
}

waitExample();
```

### pause()
-   Description: Stops further code from running, and displays a "hit any key to continue" message
- Example:
```javascript
console.log('Done!');

cli.pause();

console.log('But there\'s more!');
```