@applicvision/js-toolbox/README.md

<div align="center">

### *Zero-dependency collection of tools aiming to speed up modern JavaScript development.*

<br>

![Version image](https://badgen.net/badge/npm/2.2.0/green?icon=npm)

[![install size](https://packagephobia.com/badge?p=@applicvision/js-toolbox@latest)](https://packagephobia.com/result?p=@applicvision/js-toolbox@latest)

```console
> npm install @applicvision/js-toolbox
```

</div>

<br>


## Toolbox contents

  - [Tests](#tests)
  - [Auto reload](#auto-reload)
  - [Ayay](#ayay)
  - [IzzaDate](#izzadate)
  - [Argument Parser](#argument-parser)
  - [Terminal Style](#terminal-style)

<br>
<br>

# Tests

Write tests with EcmaScript modules syntax, and run them both in browser and in Node, without any build step. Compose your tests in suites using `describe`, and declare test units with `test` or `it`:

```javascript
// test.js
import {describe, it} from '@applicvision/js-toolbox/test'
import assert from 'node:assert/strict'

describe('My suite', () => {
  it('test', () => {
    assert.equal(1 + 1, 2)
  })
})
```

A bin called `testa` (Swedish for 'test' in imperative form) is exported which runs the test. So either put `test: testa` in your package.json script section, and call:
```
npm test
```

Or even shorter, just call with npx:

```
npx testa
```

In your `package.json` you can configure which files will be picked up by the test runner.
```json
"config": {
  "testa": {
    "endsWith": ".test.js"
  }
}
```
By default, files ending with `.test.js` will be searched for from the project directory, but you can specify files and folders as argument to limit the search: `testa unit integration extra.test.js`.

Passing `--help` will print the usage information:

```
Options:
  -f, --filter     Specify a regex to only run matching tests and describes.
  -l, --logger     Specify a logger for the test. Available: animated, simple. Default: animated
  -m, --mode       Specify mode, node or browser. Default node.
  -w, --watch      In browser mode, reload on file changes in specified directory.
  -p, --port       In browser mode, select the port to run the server on. Default 3000.
  --timeout        Set general time limit for tests. Default 4s.
  --bail           Exit immediately on first test failure.
  --only           Run only tests marked with only.
  --notify         Show MacOS notification (osascript)
  -h, --help       Show this message and exit.
```

## Browser mode
Going back to the start of the test module example
```javascript
import { describe, test } from '@applicvision/js-toolbox/test'
import assert from 'node:assert/strict'
```
one might wonder how this code will run in the browser, without any compiling, transpiling, translation, build steps or anything.

The answer to that is two fairly new features for EcmaScript modules. The first is in the browser, and is called importmaps, which is available in recent versions of the major web browsers. See more at https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script/type/importmap.

The other is on the Node side, and is called `import.meta.resolve`. More info here: https://nodejs.org/dist/latest-v20.x/docs/api/esm.html#importmetaresolvespecifier.

So the first line in the example above is resolved to the correct file in node_modules, when the browser requests the module.

And the second line, `import node:assert/strict`, is intercepted and resolves a browser compatible implementation of `node:assert/strict`.

A separate bin called `browser-test` is exposed. It simply calls the testrunner with test mode set to browser.

The server for browser testing is run with http by default, but can also be run with https. To set this up, please create a `key.pem` (private key) and `cert.pem` (certificate), in any directory, and set the directory location to an environment variable called `JS_TOOLBOX_CERT`.

Once the server is started, default port is 3000, simply visit the page in the browser to run the tests.

Query parameters can be used to configure the tests. Available query parameters are:
* `only` – run only tests marked with only 
* `filter=<regex>` – Run tests matching filter.
* `expand` – Keep the test suites expanded when finished

Two examples:
```bash
'https://localhost:3000/?only'
#run only tests marked with .only

'https://localhost:3000/?filter=sum|random&filter=ayay'
#run only tests matching /sum|random/ and /ayay/
```
<br>

# Auto reload

Auto reload is a tool to make the browser reload when files are changed. Start it with the exported bin, `autoreload`.
In package json, add a script row:
```
autoreload: autoreload src
```
And then call
```
npm run autoreload
```
Or with npx:
```
npx autoreload src
```

This starts the file watcher and the server. The default port is 3333, but this can be configured with option `--port`. The server can also be run with https. To set up this, please create a `key.pem` (private key) and `cert.pem` (certificate), in any directory, and set the directory location to an environment variable called `JS_TOOLBOX_CERT`, or pass the directory location with the option `--certificate`.

Example:
```
npx autoreload --certificate ~/certificates/localhost
```

Then in your web application, during development, import the client script, and call start:
```html
<script type="module">
    import { start } from 'https://localhost:3333/autoreload.js'
    start()
</script>
```

A little indicator will appear in the bottom right corner. If the indicator is green, it means autoreload is active, and file changes will trigger page reload. If it turns red, it means it lost connection to the server. It will automatically try to reconnect if it loses connection, and if connection is reestablished, the indicator color will return to green.

The file watcher can also be used as a standalone bin:
```
npx filewatcher .
```

Then it will emit to standard out when files change, and another process could be piped to it to handle file changes. The auto reload functionality is built that way.

<br>

# Ayay

A subclass of the native Array. The aim is to extend Array with immutable methods. Create instances of Ayay using the constructor, or any of the static factory methods (which are just the same as those of Array):

```javascript
import Ayay from '@applicvision/js-toolbox/Ayay'

const anArray = new Ayay()
// or
const anArray = Ayay.of(1, 2, 3)
// or
const anotherArray = Ayay.from([1, 2, 3, 4])
```

There are also two other static methods for constructing instances:

`fromPrettyJoined`, `seedWith`

Available prototype methods:

`arrayByDroppingLastItem`, `arrayByInsertingItem`, `arrayByMoving`, `arrayByRemovingItemAtIndex`, `arrayByReplacingItemAtIndex`, `arrayBySwappingItems`, `arraySortedBy`, `asyncFilter`, `average`, `chunksOf`, `compactMap`, `findLast`, `findLastIndex`, `get first`, `groupBy`, `indices`, `isEmpty`, `isShallowIdenticalWith`, `iterateWhile`, `get last`, `get lastIndex`, `mapWhile`, `omitInObject`, `permutations`, `pickInObject`, `get pipe`, `prettyJoin`, `randomIndex`, `randomItem`, `reduceWhile`, `reversedArray`, `sampleOfSize`, `shuffledArray`, `sumItems`, `sumItemsWhile`, `toVanilla`, `transpose`, `uniqueItems`, `useAsKeyPathIn`, `get vanilla`

Methods have been named in order to hopefully make them self explanatory. But additional documentation and examples are available in the TypeScript definitions, and will show in your editor.

One example:
```javascript
const numberArray = Ayay.of(1, 2, 3, 4, 5, 6)

numberArray
  .arrayByDroppingLastItem()
  .average() // 3

// original array not modified
numberArray // [1, 2, 3, 4, 5, 6]

```

<br>

# IzzaDate

IzzaDate is a small subclass of the native Date class. It enables easier manipulation, and some immutable operations on Date objects, as well as a few methods for date comparison.

Available methods:

`add`, `components`, `copy`, `dateByAdding`, `dateBySetting`, `dateBySubtracting`, `daysSince`, `daysUntil`, `get`, `isEarlierInTheDay`, `isLaterInTheDay`, `isSameTimeOfDay`, `set`, `subtract`

Documentation is available in TypeScript definition.

One example:
```javascript
import IzzaDate, { DAY } from '@applicivions/js-toolbox/izza-date'
const now = new IzzaDate()
const tomorrow = now.dateByAdding(1, DAY)
now.daysUntil(tomorrow) // 1
```
<br>

# Terminal Style

Simple utility to get colored output in the terminal.

```javascript
import style from '@applicvision/js-toolbox/style'

console.log(
  style.cyan('This text is Cyan'),
  style.bold.red('This text is red and bold')
)
```

Available styles are those defined in `util.inspect.colors`, please see https://nodejs.org/api/util.html#foreground-colors for reference.

The default export is a function, with the following properties. Each property returns the style function with that text modifier activated.

`blue`, `bold`, `cyan`, `dim`, `gray`, `green`, `italic`, `red`, `underline`

The modifiers are chainable to combine styles:

```javascript
style.green.bold.italic.underline('Hello')
```

And can be nested
```javascript
style.blue(`blue ${style.bold('bold and blue')} blue`)
```

To pass custom style string, use `.custom`:

```javascript
console.log(style.custom('bgRed', 'bold')('Hello Red background'))
```
<br>

# Argument Parser
Argument parser is a simple utility to configure a command line tool. Specify which options and flags a program accepts. The parser will parse the arguments sent (by default `process.argv.slice(2)`).

Given this
```javascript
// program.js
import {parseArguments} from '@applicvision/js-toolbox/args'
const parsed = parseArguments
  .option('message', { description: 'Specify a message' })
  .flag('flag', { description: 'A boolean option'})
  .option('option', { description: 'Another good option' })
  .help('Welcome to the program')
  .parse()
```

When invoked like this
```
node program.js --option=value1 --option value2 --flag -mhello -- arg1 arg2
```

The argument parser will return this:
```
{
  options: { option: [ 'value1', 'value2' ], flag: true, message: 'hello' },
  args: [ 'arg1', 'arg2' ]
}
```

If `--help` or `-h` is passed, the parser will return an object with `help` as the only property. This help can be logged to display a generated message to the user:
```
Welcome to the program

Options:
  -m, --message     Specify a message
  -f, --flag        A boolean option
  -o, --option      Another good option
  -h, --help        Show this message and exit.
```

if an unknown option is passed, or if a value is not correctly passed to an option, the parser will throw an error, with a message that can be logged to the user:

```
node program.js --missing-option=value1
```

```
Error Unknown option 'missing-option'

Available options:
  -m, --message     Specify a message
  -f, --flag        A boolean option
  -o, --option      Another good option
  -h, --help        Show this message and exit.

```


<div align="center">
<br>

*Passionately developed by ApplicVision*

<br>

[![ApplicVision logo](https://applicvision.com/img/applicvision.png)](https://applicvision.com)

</div>