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