Web Utils 🛠️
Common TypeScript web utilities
[sponsor-badge]: https://img.shields.io/static/v1?label=Fund%20this%20package&message=%E2%9D%A4&logo=GitHub&color=%23DB61A2
[sponsor-url]: https://github.com/sponsors/alessiofrittoli
### Table of Contents
- [Getting started](#getting-started)
- [What's Changed](#whats-changed)
- [API Reference](#api-reference)
- [Blob utilities](#blob-utilities)
- [Array utilities](#array-utilities)
- [Dom utilities](#dom-utilities)
- [Scroll utilities](#scroll-utilities)
- [Stylesheet utilities](#stylesheet-utilities)
- [Generators utilities](#generators-utilities)
- [Map utilities](#map-utilities)
- [Promises utilities](#promises-utilities)
- [Strings utilities](#strings-utilities)
- [Types utilities](#types-utilities)
- [Validation utilities](#validation-utilities)
- [Objects utilities](#objects-utilities)
- [Browser API utilities](#browser-api-utilities)
- [Document Picture-in-Picture](#document-picture-in-picture)
- [Network Information](#network-information)
- [Device utilities](#device-utilities)
- [Storage utilities](#storage-utilities)
- [`Cookie` Class](#cookie-class)
- [`LocalStorage` Class](#localstorage-class)
- [`SessionStorage` Class](#sessionstorage-class)
- [Utils](#utils)
- [Development](#development)
- [Install depenendencies](#install-depenendencies)
- [Build the source code](#build-the-source-code)
- [ESLint](#eslint)
- [Jest](#jest)
- [Contributing](#contributing)
- [Security](#security)
- [Credits](#made-with-)
---
### Getting started
Run the following command to start using `web-utils` in your projects:
```bash
npm i @alessiofrittoli/web-utils
```
or using `pnpm`
```bash
pnpm i @alessiofrittoli/web-utils
```
---
### What's Changed
#### Updates in the latest release 🎉
- Add `normalizeIndex` utility function. See [API Reference](#normalizeindex) for more info.
- Add `getPreviousIndex` utility function. See [API Reference](#getpreviousindex) for more info.
- Add `getNextIndex` utility function. See [API Reference](#getnextindex) for more info.
- Add `insertAfter` utility function. See [API Reference](#insertafter) for more info.
Old updates:
- Add `deferTask`. See [API Reference](#defertask) for more info.
- Add `deferCallback`. See [API Reference](#defercallback) for more info.
- Add `parameterized` function. See [API Reference](#parameterized) for more info.
- Add Document Picture-in-Picture utilities. See [Document Picture-in-Picture](#document-picture-in-picture) for more info.
---
### API Reference
#### Array utilities
##### `arrayUnique`
Removes duplicate values from an array.
Parameters
| Parameter | Type | Description |
| --------- | ----- | ---------------- |
| `array` | `T[]` | The input array. |
---
Returns
Type: `T[]`
The filtered array.
---
Usage
###### Removes duplicates from array
```ts
import { arrayUnique } from "@alessiofrittoli/web-utils";
const pointer = {};
console.log(arrayUnique([pointer, "b", pointer, "c", "b"]));
// Outputs: [ {}, 'b', 'c' ]
```
---
##### `arrayObjectUnique`
Removes duplicate entries from an array referencing an object key.
Parameters
| Parameter | Type | Description |
| ---------- | --------- | -------------------------------- |
| `array` | `T[]` | An array of objects. |
| `property` | `keyof T` | The Object property to refer to. |
---
Returns
Type: `T[]`
The filtered array.
---
Usage
###### Removes duplicates from array with the same propery value
```ts
import { arrayObjectUnique } from "@alessiofrittoli/web-utils";
const arr = [
{ id: 1, name: "a" },
{ id: 2, name: "b" },
{ id: 1, name: "c" }, // duplicate `id`
{ id: 3, name: "d" },
{ id: 4, name: "a" }, // duplicate `name`
];
console.log(arrayObjectUnique(arr, "id"));
// Outputs: [
// { id: 1, name: 'a' },
// { id: 2, name: 'b' },
// { id: 3, name: 'd' },
// { id: 4, name: 'a' },
// ]
console.log(arrayObjectUnique(arr, "name"));
// Outputs: [
// { id: 1, name: 'a' },
// { id: 2, name: 'b' },
// { id: 1, name: 'c' },
// { id: 3, name: 'd' },
// ]
```
---
##### `listToArray`
Convert a stringified Array to Array object.
Parameters
| Parameter | Type | Description |
| --------- | -------- | -------------------- |
| `string` | `string` | An array of objects. |
---
Returns
Type: `string[]`
The converted stringified Array to Array object.
---
Usage
###### Basic usage
```ts
import { listToArray } from "@alessiofrittoli/web-utils";
console.log(listToArray("1,2, 3, 4").map(Number));
// Outputs: [ 1, 2, 3, 4 ]
```
---
##### `chunkInto`
Split Array into chunks.
Type Parameters
| Parameter | Default | Description |
| --------- | ----------- | ----------------------- |
| `T` | `unknown[]` | The input `array` type. |
---
Parameters
| Parameter | Type | Description |
| --------------- | ------------------ | ---------------------------------------------------------------------------------------------------------------- |
| `array` | `T[]` | The original Array. |
| `options` | `ChunkIntoOptions` | An object defining split criteria. |
| `options.size` | `number` | Will split the given Array in a way to ensure each chunk length is, whenever possible, equal to the given value. |
| `options.count` | `number` | Will split the given Array in a way to ensure n chunks as the given value. |
---
Returns
Type: `T[]`
An Array of chunks.
---
Usage
###### Basic usage
```ts
import { chunkInto } from "@alessiofrittoli/web-utils";
console.log(chunkInto([1, 2, 3, 4, 5], { count: 2 }));
// Output: [ [ 1, 2, 3 ], [ 4, 5 ] ]
console.log(chunkInto([1, 2, 3, 4, 5], { size: 2 }));
// Output: [ [ 1, 2 ], [ 3, 4 ], [ 5 ] ]
```
---
##### `shuffle`
Shuffle the elements of an array in place using the [Fisher-Yates algorithm](https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle).
Please note that this function modify the original given `array`.
Type parameters
| Parameter | Description |
| --------- | --------------------------------------------------------- |
| `T` | The automatically inferred type of elements in the array. |
---
Parameters
| Parameter | Type | Description |
| --------- | ---------- | --------------------- |
| `array` | `Array` | The array to shuffle. |
---
Returns
Type: `Array`
The modified shuffled array.
---
Example
```ts
import { shuffle } from "@alessiofrittoli/web-utils";
console.log(shuffle([1, 2, 3, 4, 5]));
```
---
##### `shuffleCopy`
Copy and shuffle the elements of an array in place using the [Fisher-Yates algorithm](https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle).
Same API of [`shuffle`](#shuffle) is applied, but this function **does not modify** the original given `array`.
---
##### `normalizeIndex`
Normalize negative indexes to a positive value.
Parameters
| Parameter | Type | Description |
| --------- | -------- | ----------------- |
| `index` | `number` | The index. |
| `length` | `number` | The array length. |
---
Returns
Type: `number`
The normalized index.
---
Examples
```ts
import { normalizeIndex } from "@alessiofrittoli/web-utils";
const array = [0, 1, 2, 3];
console.log(normalizeIndex(2, array.length)); // Outputs: 2
console.log(normalizeIndex(-1, array.length)); // Outputs: 3
console.log(normalizeIndex(-3, array.length)); // Outputs: 1
```
---
##### `getPreviousIndex`
Get the previous index.
Parameters
| Parameter | Type | Default | Description |
| --------- | -------- | ------- | ----------------- |
| `length` | `number` | - | The array length. |
| `index` | `number` | `0` | The index. |
---
Returns
Type: `number`
The previous index.
---
Examples
```ts
import { getPreviousIndex } from "@alessiofrittoli/web-utils";
const array = [0, 1, 2, 3];
console.log(getPreviousIndex(array.length, 2)); // Outputs: 1
console.log(getPreviousIndex(array.length, -1)); // Outputs: 2
console.log(getPreviousIndex(array.length, -3)); // Outputs: 0
```
---
##### `getNextIndex`
Get the next index.
Parameters
| Parameter | Type | Default | Description |
| --------- | -------- | ------- | ----------------- |
| `length` | `number` | - | The array length. |
| `index` | `number` | `0` | The index. |
---
Returns
Type: `number`
The next index.
---
Examples
```ts
import { getNextIndex } from "@alessiofrittoli/web-utils";
const array = [0, 1, 2, 3];
console.log(getNextIndex(array.length, 2)); // Outputs: 3
console.log(getNextIndex(array.length, -1)); // Outputs: 0
console.log(getNextIndex(array.length, -3)); // Outputs: 2
```
---
##### `insertAfter`
Inserts one or more items into an array at the specified index position.
Type Parameters
- `T` The type of elements in the array.
---
Parameters
| Parameter | Type | Default | Description |
| --------- | -------- | ------- | --------------------------------------------- |
| `array` | `T[]` | - | The original array to insert items into. |
| `item` | `T\|T[]` | 0 | A single item or an array of items to insert. |
| `index` | `number` | `-1` | The index after which to insert the item(s). |
---
Returns
Type: `T[]`
A new array with the item(s) inserted at the specified position.
---
Examples
```ts
import { insertAfter } from "@alessiofrittoli/web-utils";
console.log(insertAfter([1, 2, 3, 4], 5)); // Outputs: [ 1, 2, 3, 4, 5 ]
console.log(insertAfter(["a", "c"], "b", 0)); // Outputs: [ 'a', 'b', 'c' ]
console.log(insertAfter(["a", "b", "c", "e"], "d", -2)); // Outputs: [ 'a', 'b', 'c', 'd', 'e' ]
```
---
##### `findIndexBy`
Finds the index of the first object whose selected field strictly equals the provided value.
Type Parameters
- `T` The object type stored in the array.
- `U` The key of `T` used for the comparison.
---
Parameters
| Parameter | Type | Description |
| --------------- | --------------------------- | ------------------------------------------------- |
| `options` | `FindInxeByOptions` | The search options. |
| `options.items` | `T[]` | The collection to search. |
| `options.field` | `U` | The object field to compare against `value`. |
| `options.value` | `T[U]` | The value that must match the selected field. |
---
Returns
Type: `number`
The index of the matching item, or `-1` when no match is found.
---
Examples
```ts
import { findIndexBy } from "@alessiofrittoli/web-utils";
const users = [
{ id: 1, name: "Ada" },
{ id: 2, name: "Grace" },
{ id: 3, name: "Linus" },
];
console.log(findIndexBy({ items: users, field: "id", value: 2 })); // Outputs: 1
console.log(findIndexBy({ items: users, field: "name", value: "Linus" })); // Outputs: 2
console.log(findIndexBy({ items: users, field: "id", value: 9 })); // Outputs: -1
```
---
#### Blob utilities
##### `downloadBlob`
Create and download a blob object.
Parameters
| Parameter | Type | Description |
| ---------- | -------------- | ----------------------------------- |
| `filename` | `string` | The download file name. |
| `data` | `BodyInit` | The download file data. |
| `init` | `ResponseInit` | (Optional) The ResponseInit object. |
---
Usage
###### Download file from HTTP Response
```ts
import { downloadBlob } from '@alessiofrittoli/web-utils'
fetch( ... )
.then( response => response.formData() )
.then( async data => {
await Promise.all(
Array.from( data.entries() )
.map( async ( [, file ] ) => {
if ( ! ( file instanceof File ) ) return
await downloadBlob( file.name, file )
} )
)
} )
.catch( error => {
console.error( error )
} )
```
---
#### Dom utilities
##### Scroll utilities
###### `blockScroll`
Prevent Element Overflow.
It calculates the scrollbar width and the resulting value is applied to the target element right padding-right to prevent width grows.
It also applies the `--scrollbar-size` CSS variable that can be used to apply a padding-right to the position fixed elements inside the target.
Parameters
| Parameter | Type | Default | Description |
| --------- | ------------- | -------------------------- | ------------------------------ |
| `target` | `HTMLElement` | `Document.documentElement` | (Optional) The target Element. |
---
Usage
###### Block Document HTML scroll when a popup is opened
```ts
import { blockScroll } from "@alessiofrittoli/web-utils";
const openPopUpHandler = () => {
blockScroll();
// ... handle popup
};
```
```css
.modal-wrapper {
position: fixed;
inset: 0;
padding-right: var(--scrollbar-size, 0);
}
```
---
###### Block scroll of a specific HTMLElement
```ts
import { blockScroll } from "@alessiofrittoli/web-utils";
const element = document.querySelector(".css-selector");
if (element) {
blockScroll(element);
}
```
---
###### `restoreScroll`
Restore Element Overflow.
Parameters
| Parameter | Type | Default | Description |
| --------- | ------------- | -------------------------- | ------------------------------ |
| `target` | `HTMLElement` | `Document.documentElement` | (Optional) The target Element. |
---
Usage
###### Restore Document HTML scroll when a popup is closed
```ts
import { restoreScroll } from "@alessiofrittoli/web-utils";
const closePopUpHandler = () => {
// ... handle close
restoreScroll();
};
```
---
###### Restore scroll of a specific HTMLElement
```ts
import { restoreScroll } from "@alessiofrittoli/web-utils";
const element = document.querySelector(".css-selector");
if (element) {
restoreScroll(element);
}
```
---
##### Stylesheet utilities
###### Types
###### UrlStylesheet
Represents a URL stylesheet as a simple URL input, URL object or as an object with URL and fetch configuration options.
```ts
type UrlStylesheet =
| UrlInput
| {
/**
* The URL string or a URL object of the stylesheet to load.
*
*/
url: UrlInput;
/**
* Indicates whether to fetch the given URL.
*
* @default false
*/
fetch?: boolean;
};
```
---
###### Style
Represents a style input.
```ts
type Style = UrlStylesheet | HTMLStyleElement | CSSStyleSheet | StyleSheetList;
```
---
###### Styles
Represents a single style object or an array of style objects.
```ts
type Styles = Style | Style[];
```
---
###### `cloneStyleSheetList`
Clones a StyleSheetList or array of CSSStyleSheets into an array of `HTMLStyleElement` objects.
This function extracts CSS rules from each stylesheet and creates corresponding `