@alessiofrittoli/web-utils

Web Utils 🛠️

Common TypeScript web utilities

Table of Contents

• Getting started
• What's Changed
• API Reference
  • Blob utilities
  • Array utilities
  • Dom utilities
    • Scroll utilities
    • Stylesheet utilities
  • Generators utilities
  • Map utilities
  • Promises utilities
  • Strings utilities
  • Types utilities
  • Validation utilities
  • Objects utilities
  • Browser API utilities
    • Document Picture-in-Picture
    • Network Information
  • Device utilities
  • Storage utilities
    • Cookie Class
    • LocalStorage Class
    • SessionStorage Class
  • Utils
• Development
  • Install depenendencies
  • Build the source code
  • ESLint
  • Jest
• Contributing
• Security
• Credits

Getting started

Run the following command to start using web-utils in your projects:

npm i @alessiofrittoli/web-utils

or using pnpm

pnpm i @alessiofrittoli/web-utils

What's Changed

Updates in the latest release 🎉

• Add normalizeIndex utility function. See API Reference for more info.
• Add getPreviousIndex utility function. See API Reference for more info.
• Add getNextIndex utility function. See API Reference for more info.
• Add insertAfter utility function. See API Reference for more info.

Old updates:

• Add deferTask. See API Reference for more info.
• Add deferCallback. See API Reference for more info.
• Add parameterized function. See API Reference for more info.
• Add Document Picture-in-Picture utilities. See 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

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

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

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

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.

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<T>	The array to shuffle.

Returns

Type: Array<T>

The modified shuffled array.

Example

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.

Same API of 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

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

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

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

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<T, U>	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

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

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

import { blockScroll } from "@alessiofrittoli/web-utils";

const openPopUpHandler = () => {
  blockScroll();
  // ... handle popup
};

.modal-wrapper {
  position: fixed;
  inset: 0;
  padding-right: var(--scrollbar-size, 0);
}

Block scroll of a specific HTMLElement

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

import { restoreScroll } from "@alessiofrittoli/web-utils";

const closePopUpHandler = () => {
  // ... handle close
  restoreScroll();
};

Restore scroll of a specific HTMLElement

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.

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.

type Style = UrlStylesheet | HTMLStyleElement | CSSStyleSheet | StyleSheetList;

Styles

Represents a single style object or an array of style objects.

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 <style> elements containing the serialized CSS text. If an error occurs while processing a stylesheet, the error is logged and that stylesheet is skipped.

Parameters

Parameter	Type	Description
styles	StyleSheetList|CSSStyleSheet[]	The source StyleSheetList or array of CSSStyleSheet objects to clone.

Returns

Type: HTMLStyleElement[]

• An array of HTMLStyleElement objects, each containing the CSS rules from the source stylesheets.
• Failed stylesheets are filtered out and not included in the result.

Examples

import { cloneStyleSheetList } from "@alessiofrittoli/web-utils";

const styles = cloneStyleSheetList(document.styleSheets);
// do something with cloned stylesheets
// styles.forEach( style => shadowRoot.appendChild( style ) )

cloneStyleSheets

Clones style sheets from various sources into new HTMLStyleElement nodes.

• When a URL stylesheet has fetch: true, the stylesheet content is fetched and embedded as inline CSS.
• When fetch: false (default), a link element is created instead.
• URL parsing is handled through the Url utility with support for both string and UrlInput object formats.

Parameters

Parameter	Type	Description
styles	Styles	A style source or array of style sources.
		- See Styles type for a list of possible values.

Returns

Type: Promise<CloneStyleSheetsReturn>

• A promise that resolves to an array of cloned HTMLStyleElement and HTMLLinkElement nodes.
• For inline styles and StyleSheetLists, returns HTMLStyleElement nodes.
• For URL-based stylesheets, returns HTMLLinkElement nodes (or HTMLStyleElement if fetch is true).
• Failed operations are silently ignored.

Examples

Cloning StyleSheetList

import { cloneStyleSheets } from "@alessiofrittoli/web-utils";

const styles = await cloneStyleSheets(document.styleSheets);
// do something with cloned dcoument stylesheets
// styles.forEach( style => shadowRoot.appendChild( style ) )

Cloning stylesheets from URL

import { cloneStyleSheets } from "@alessiofrittoli/web-utils";

const styles = await cloneStyleSheets("/path-to-stylesheet-file.css");

const styles = await cloneStyleSheets({
  url: "/path-to-stylesheet-file-2.css",
  fetch: true,
});

const styles = await cloneStyleSheets([
  "/path-to-stylesheet-file-3.css",
  { url: "/path-to-stylesheet-file-4.css", fetch: true },
]);

Generators utilities

isGeneratorFunction

Check if a function is a GeneratorFunction or AsyncGeneratorFunction.

Parameters

Parameter	Type	Description
reference	unknown	The function to check.

Returns

Type: reference is GeneratorFunction | AsyncGeneratorFunction

• true if the given reference is a GeneratorFunction or AsyncGeneratorFunction.
• false otherwise.

isDefaultGeneratorFunction

Check if a function is a GeneratorFunction.

Parameters

Parameter	Type	Description
reference	unknown	The function to check.

Returns

Type: reference is GeneratorFunction

• true if the given reference is a GeneratorFunction.
• false otherwise.

isAsyncGeneratorFunction

Check if a function is an AsyncGeneratorFunction.

Parameters

Parameter	Type	Description
reference	unknown	The function to check.

Returns

Type: reference is AsyncGeneratorFunction

• true if the given reference is an AsyncGeneratorFunction.
• false otherwise.

isGeneratorObject<T>

Check if reference is a Generator or AsyncGenerator.

Parameters

Parameter	Type	Description
reference	unknown	The reference to check.

Returns

Type: reference is Generator<T> | AsyncGenerator<T>

• true if the given reference is a Generator or AsyncGenerator.
• false otherwise.

isDefaultGeneratorObject<T>

Check if reference is a Generator.

Parameters

Parameter	Type	Description
reference	unknown	The reference to check.

Returns

Type: reference is Generator<T>

• true if the given reference is a Generator.
• false otherwise.

isAsyncGeneratorObject<T>

Check if reference is an AsyncGenerator.

Parameters

Parameter	Type	Description
reference	unknown	The reference to check.

Returns

Type: reference is AsyncGenerator<T>

• true if the given reference is an AsyncGenerator.
• false otherwise.

Map utilities

Interface TypedMap<T, P, K>

A type-safe extension of the Map class that enforces key-value relationships based on a provided type.

Type parameters

Parameter	Type	Default	Description
T	Record<string, unknown>	unknown	The object type defining the key-value relationships.
P	boolean	true	Defines whether the Map.get() method should return a possibily undefined value.
K	keyof T	keyof T	Internal - The subset of keys in T that are allowed in the Map.

getTypedMap<T, P, K>

Creates a new instance of a type-safe Map with the given type.

Type parameters

• See Interface TypedMap<T, P, K> - Type parameters

Parameters

Parameter	Type	Description
iterable	Iterable<readonly [ K, T[ K ] ]> | null	Initial Map constructor iterable object.

Returns

Type: TypedMap<T, P, K>

A new instance of a type-safe Map.

Usage

Basic usage

import { getTypedMap } from "@alessiofrittoli/web-utils";

interface User {
  name: string;
  age: number;
  isActive: boolean;
}

const user = getTypedMap<User>([
  ["name", "Foo"],
  ["age", 27],
  ["isActive", true],
]);

console.log(user.get("name")); // type: `string | undefined`
console.log(user.get("age")); // type: `number | undefined`
console.log(user.get("isActive")); // type: `boolean | undefined`

Respect the given type

import { getTypedMap } from "@alessiofrittoli/web-utils";

interface User {
  name: string;
  age: number;
  isActive: boolean;
  banned?: boolean;
}

const user = getTypedMap<User, false>([
  ["name", "Foo"],
  ["age", 27],
  ["isActive", true],
]);

console.log(user.get("name")); // type: `string`
console.log(user.get("age")); // type: `number`
console.log(user.get("isActive")); // type: `boolean`
console.log(user.get("banned")); // type: `boolean | undefined`

Promises utilities

sleep

Await a void Promise that resolves after the given time.

Parameters

Parameter	Type	Description
time	number	The sleep time in milliseconds after the Promise get resolved.

Returns

Type: Promise<void>

A new Promise which get resolved after the specified time.

Usage

import { sleep } from "@alessiofrittoli/web-utils";

const fn = async () => {
  // ...
  await sleep(2000);
  // ...
};

deferTask

Defer task so main-thread is not blocked in order to quickly paint and respond to user interaction.

Type Parameters

Parameter	Description
T	The task function definition. unknown types will be inherited by your function type definition.
U	The task function arguments. unknown types will be inherited by your function type.

Parameters

Parameter	Type	Description
task	T	The task callable function.
...args	U	Arguments required by the given task function.

Returns

Type: Promise<Awaited<ReturnType<T>>>

A new Promise which returns the task result once fulfilled.

Usage

Basic usage

import { deferTask } from '@alessiofrittoli/web-utils'

const myLongTask = () => {
  ...
}

button.addEventListener( 'click', () => {
  deferTask( myLongTask )
} )

With custom arguments

import { deferTask } from '@alessiofrittoli/web-utils'

const myLongTask = ( target: HTMLButtonElement ) => {
  ...
}

button.addEventListener( 'click', event => {
  const target = event.target as HTMLButtonElement
  deferTask( myLongTask, target )
} )

deferCallback

Defer task handler so main-thread is not blocked in order to quickly paint and respond to user interaction.

Type Parameters

Parameter	Description
T	The task function definition. unknown types will be inherited by your function type definition.
U	The task function arguments. unknown types will be inherited by your function type.

Parameters

Parameter	Type	Description
task	T	The task callable function.

Returns

Type: ( ...args: U ) => Promise<Awaited<ReturnType<T>>>

A new handler which returns a new Promise that returns the task result once fulfilled.

Usage

import { deferCallback } from '@alessiofrittoli/web-utils'

const myLongTask = ( event: Event ) => {
  ...
}

button.addEventListener( 'click', deferCallback( myLongTask ) )

Strings utilities

ucFirst

Make first letter uppercase.

Parameters

Parameter	Type	Description
input	string	The input string to convert.

Returns

Type: string

The processed string.

Usage

import { ucFirst } from "@alessiofrittoli/web-utils";

console.log(ucFirst("String value")); // Outputs: 'String value'
console.log(ucFirst("string value")); // Outputs: 'String value'

lcFirst

Make first letter lowercase.

Parameters

Parameter	Type	Description
input	string	The input string to convert.

Returns

Type: string

The processed string.

Usage

import { lcFirst } from "@alessiofrittoli/web-utils";

console.log(lcFirst("String value")); // Outputs: 'string value'
console.log(lcFirst("string value")); // Outputs: 'string value'

toCamelCase

Convert string to camelCase.

Parameters

Parameter	Type	Description
input	string	The input string to convert.

Returns

Type: string

The converted string to camelCase.

Usage

import { toCamelCase } from "@alessiofrittoli/web-utils";

console.log(toCamelCase("font-family")); // Outputs: 'fontFamily'
console.log(toCamelCase("background-color")); // Outputs: 'backgroundColor'
console.log(toCamelCase("-webkit-align-content")); // Outputs: 'WebkitAlignContent'
console.log(toCamelCase("some value")); // Outputs: 'someValue'
console.log(toCamelCase("some_value")); // Outputs: 'someValue'
console.log(toCamelCase("some value_with mixed_Cases")); // Outputs: 'someValueWithMixedCases'
console.log(toCamelCase("-string@with#special$characters")); // Outputs: 'StringWithSpecialCharacters'

toKebabCase

Convert string to kebab-case string.

Parameters

Parameter	Type	Description
input	string	The input string to convert.

Returns

Type: string

The converted string to kebab-case.

Usage

import { toKebabCase } from "@alessiofrittoli/web-utils";

console.log(toKebabCase("fontFamily")); // Outputs: 'font-family'
console.log(toKebabCase("backgroundColor")); // Outputs: 'background-color'
console.log(toKebabCase("string with spaces")); // Outputs: 'string-with-spaces'
console.log(toKebabCase("string_with_underscores")); // Outputs: 'string-with-underscores'
console.log(toKebabCase("WebkitAlignContent")); // Outputs: '-webkit-align-content'
console.log(toKebabCase("some value_with mixed_Cases")); // Outputs: 'some-value-with-mixed-cases'
console.log(toKebabCase("-string@with#special$characters")); // Outputs: '-string-with-special-characters

stringifyValue

Stringify value.

Parameters

Parameter	Type	Description
input	any	The value to stringify.

Returns

Type: string

The stringified input.

Usage

import { stringifyValue } from "@alessiofrittoli/web-utils";

console.log(stringifyValue(new Date("Sat, 20 Apr 2025 16:20:00 GMT")));
// Outputs: '2025-04-20T16:20:00.000Z'

console.log(stringifyValue(null));
// Outputs: 'null'

console.log(stringifyValue({ prop: "value", prop2: true }));
// Outputs: '{"prop":"value","prop2":true}'

console.log(stringifyValue([1, 2, true, null, () => {}]));
// Outputs: '[1,2,true,null,null]'

console.log(
  stringifyValue(
    new Map([
      ["key", "value"],
      ["key2", "value"],
    ]),
  ),
);
// Outputs: '[["key","value"],["key2","value"]]'

console.log(
  stringifyValue(
    new Headers({
      key: "value",
      key2: "value",
    }),
  ),
);
// Outputs: '[["key","value"],["key2","value"]]'

console.log(stringifyValue(true)); // Outputs: 'true'
console.log(stringifyValue(false)); // Outputs: 'false'
console.log(stringifyValue(0)); // Outputs: '0'
console.log(stringifyValue(420)); // Outputs: '420'

console.log(stringifyValue(undefined)); // Outputs: ''
console.log(stringifyValue(() => {})); // Outputs: ''
console.log(stringifyValue(new Promise<void>((resolve) => resolve()))); // Outputs: ''

parseValue

Parse stringified value.

Type parameters

Parameter	Description
T	The expected returned value type.

Parameters

Parameter	Type	Description
input	string	The value to parse.

Returns

Type: T | undefined

• The parsed input.
• undefined if no input or empty string is given.

Usage

import { parseValue } from "@alessiofrittoli/web-utils";

console.log(parseValue<Date>(stringifyValue(new Date())));
// Outputs: current Date object.

console.log(parseValue<number>("12345")); // Outputs: 12345
console.log(parseValue()); // Outputs: undefined
console.log(parseValue(" ")); // Outputs: undefined

console.log(parseValue<true>(stringifyValue(true)));
// Outputs: true

console.log(parseValue(stringifyValue({ key: "value" })));
// Outputs: { key: 'value' }

console.log(parseValue(stringifyValue([1, 2, 3, 4, 5])));
// Outputs: [ 1, 2, 3, 4, 5 ]

console.log(parseValue("String value")); // Outputs: 'String value'

parameterized

Creates a parameterized string with placeholder values.

Types

ParameterizedValue

Represents a value that can be used as a parameter in string operations.

type ParameterizedValue = string | boolean | number | bigint;

Parameterized

Represents a parameterized string with its corresponding values.

type Parameterized = [string, ParameterizedValue[]];

Examples

import { parameterized } from "@alessiofrittoli/web-utils";

const data = {
  value: "parameterized",
};

console.log(parameterized`My string with ${data.value} values.`); // [ 'My string with ? values.', [ 'parameterized' ] ]

Types utilities

⚠️ Docs coming soon

Validation utilities

⚠️ Docs coming soon

Objects utilities

⚠️ Docs coming soon

Browser API utilities

getMediaMatches

Safely executes window.matchMedia() in server and browser environments.

Parameters

Parameter	Type	Description
query	string	The Media Query string to check.

Returns

Type: boolean

• false if window is not defined or if the document currently doesn't matches the given query.
• true otherwise.

Usage

Check if current device is landscape oriented

import { getMediaMatches } from "@alessiofrittoli/web-utils";

console.log(!getMediaMatches("(orientation:portrait)"));

openBrowserPopUp

Opens a webpage in a browser PopUp.

The openBrowserPopUp uses Window.open() under the hood, but provides default options to make your work easier.

Parameters

Parameter	Type	Default	Description
options	OpenBrowserPopUpOptions	-	An object defining custom PopUp options.
options.url	UrlInput	-	The URL or path of the resource to be loaded. See UrlInput for more info about accepted formats.
options.width	number	600	The PopUp width.
options.height	number	800	The PopUp height.
options.context	string	-	A string, without whitespace, specifying the name of the browsing context the resource is being loaded into.
options.features	OptionsFeatures	-	Additional custom PopUp features.

Returns

Type: WindowProxy | null

• a WindowProxy object is returned if the browser successfully opens the new browsing context.
• null is returned if the browser fails to open the new browsing context, for example because it was blocked by a browser popup blocker.

Usage

Re-focus a previously opened popup

import { openBrowserPopUp } from "@alessiofrittoli/web-utils";

let windowProxy: WindowProxy | null = null;

const clickHandler = () => {
  if (windowProxy && !windowProxy.closed) {
    return windowProxy.focus();
  }

  windowProxy = openBrowserPopUp({
    url: {
      pathname: "/",
      query: { key: "value" },
    },
  });
};

Re-use a popup

import { openBrowserPopUp } from "@alessiofrittoli/web-utils";

const clickHandler = () => {
  openBrowserPopUp({
    context: "some-context-name",
    url: {
      pathname: "/",
      query: { key: "value" },
    },
  });
};

const clickHandler2 = () => {
  openBrowserPopUp({
    context: "some-context-name",
    url: "/other-path",
  });
};

Document Picture-in-Picture

Types

OpenDocumentPictureInPictureOptions

Defines configuration options for opening a Document Picture-in-Picture window.

Properties

Property	Type	Default	Description
sizes	InputDimensions	[ 250, 250 ]	A tuple defining non-negative numbers representing the width and the height to set
			for the Picture-in-Picture window's viewport, in pixels.
			- See InputDimensions type for a list of possible values.
disallowReturnToOpener	boolean	false	Hints to the browser that it should not display a UI control that enables the
			user to return to the originating tab and close the Picture-in-Picture window.
preferInitialWindowPlacement	boolean	false	Defines whether the Picture-in-Picture window will always appear back at the
			position and size it initially opened at, when it is closed and then reopened.
			By contrast, if preferInitialWindowPlacement is false the
			Picture-in-Picture window's size and position will be remembered when closed
			and reopened — it will reopen at its previous position and size,
			for example as set by the user.
styles	Styles	-	Custom styles to load inside the Picture-in-Picture window.
			- See Styles type for a list of possible values.
			⚠️ To keep consistent styling with your web-app, document styles are automatically cloned.
onQuit	() => void	-	A callback to execute when Picture-in-Picture window is closed.

OpenDocumentPictureInPicture

Defines the returned result of opening a Document Picture-in-Picture window.

Properties

Property	Type	Description
window	Window	The browsing context inside the Document Picture-in-Picture window.

isDocumentPictureInPictureSupported

Checks if the Document Picture-in-Picture API is supported by the current browser.

Returns

Type: boolean

• true if Document Picture-in-Picture is supported.
• false otherwise.

Examples

import { isDocumentPictureInPictureSupported } from "@alessiofrittoli/web-utils";

if ( isDocumentPictureInPictureSupported() ) {
  ...
}

requiresDocumentPictureInPictureAPI

Validates that the Document Picture-in-Picture API is supported by the current browser.

• Throws a new Exception with code ErrorCode.DOCUMENT_PIP_NOT_SUPPORTED if the Document Picture-in-Picture API is not supported.

Examples

import { Exception } from "@alessiofrittoli/exception";
import { requiresDocumentPictureInPictureAPI, ErrorCode } from "@alessiofrittoli/web-utils";

const myFunction = () => {
  requiresDocumentPictureInPictureAPI()
  ...
}

try {
  myFunction()
} catch ( _err ) {
  const err = _err as Error

  const error = (
    Exception.isException<string, ErrorCode>(err)
      ? err
      : (
        new Exception(
          err.message,
          {
            code  : ErrorCode.UNKNOWN,
            name  : err.name,
            cause : err,
          }
        )
      )
  )

  switch ( error.code ) {
    case ErrorCode.DOCUMENT_PIP_NOT_SUPPORTED:
      console.warn( 'Document Picture-in-Picture is not supported.' )
      break
    default:
      console.error( 'Unknown error', error )
  }
}

openDocumentPictureInPicture

Opens a Document Picture-in-Picture window.

• Throws a new Exception with code ErrorCode.DOCUMENT_PIP_NOT_SUPPORTED if the Document Picture-in-Picture API is not supported.

Parameters

Parameter	Type	Description
options	OpenDocumentPictureInPictureOptions	Configuration options for opening a new Document Picture-in-Picture window.

Returns

Type: Promise<OpenDocumentPictureInPicture>

• A new Promise that resolves to the Document Picture-in-Picture result containing the window of the new browsing context.

Examples

Simple usage

import { Exception } from "@alessiofrittoli/exception";
import {
  openDocumentPictureInPicture,
  ErrorCode,
} from "@alessiofrittoli/web-utils";

const openPictureInPicture = async () => {
  try {
    const content = document.createElement("div");

    const { window } = await openDocumentPictureInPicture();

    window.document.body.appendChild(content);
  } catch (_err) {
    const err = _err as Error;

    const error = Exception.isException<string, ErrorCode>(err)
      ? err
      : new Exception(err.message, {
          code: ErrorCode.UNKNOWN,
          name: err.name,
          cause: err,
        });

    switch (error.code) {
      case ErrorCode.DOCUMENT_PIP_NOT_SUPPORTED:
        console.warn("Document Picture-in-Picture is not supported.");
        break;
      default:
        console.error("Unknown error", error);
    }
  }
};

Load render blocking styles

import { Exception } from "@alessiofrittoli/exception";
import {
  openDocumentPictureInPicture,
  ErrorCode,
} from "@alessiofrittoli/web-utils";

const openPictureInPicture = async () => {
  try {
    const content = document.createElement("div");

    const { window } = await openDocumentPictureInPicture({
      styles: {
        url: "/important-stylesheet-fetched-before-opening.css",
        fetch: true,
      },
    });

    window.document.body.appendChild(content);
  } catch (error) {
    // ...
  }
};

Device utilities

isPortrait

Check if device is in portrait orientation.

Returns

Type: boolean

• true if the device is in portrait orientation when this function is executed.
• false otherwise.

Usage

Check if current device is landscape oriented

import { isPortrait } from "@alessiofrittoli/web-utils";

console.log(!isPortrait());

Network Information

Types

Connection interface

Defiens network status and NetworkInformation.

Properties

Property	Type	Description
network	NetworkInformation	The NetworkInformation interface of the Network Information API
		provides information about the connection a device is using to communicate
		with the network and provides a means for scripts to be notified if the connection type changes.
		⚠️ Limited availability - See full compatibility
onLine	boolean	Indicates whether the device is connected to the network.
		- See Listening for changes in network status.

getConnection

Get current Network status and information.

Returns

Type: Connection

An object defining network status and NetworkInformation. See Connection interface for more info.

Examples

import { getConnection } from "@alessiofrittoli/web-utils";

const { network } = getConnection();

console.log(network?.effectiveType);

Storage utilities

Cookie Class

Importing enum and types

import { Priority, SameSite } from "@alessiofrittoli/web-utils";

import type {
  RawCookie,
  ParsedCookie,
  ParsedCookieMap,
} from "@alessiofrittoli/web-utils";

Enumerators

Priority Enum

The Cookie Priority.

Constant	Value	Description
Low	Low	Low priority.
Medium	Medium	Medium priority (default).
High	High	High priority.

SameSite Enum

Controls whether or not a cookie is sent with cross-site requests, providing some protection against cross-site request forgery attacks (CSRF).

Constant	Value	Description
Strict	Strict	The browser sends the cookie only for same-site requests.
Lax	Lax	The cookie is not sent on cross-site requests, such as on requests to load images or frames, but is sent when a user is navigating to the origin site from an external site.
None	None	The browser sends the cookie with both cross-site and same-site requests.

Types

RawCookie<K, V>

Interface representing Cookie properties before it get parsed.

Properties

Property	Type	Description
name	K	The Cookie name.
value	V	The Cookie value.
domain	string	Defines the host to which the cookie will be sent.
expires	string | number | Date	Indicates the maximum lifetime of the cookie.
httpOnly	boolean	Forbids JavaScript from accessing the cookie, for example, through the Document.cookie property.
maxAge	number	Indicates the number of seconds until the cookie expires. If set, expires is ignored.
partitioned	boolean	Indicates that the cookie should be stored using partitioned storage.
path	string	Indicates the path that must exist in the requested URL for the browser to send the Cookie header.
sameSite	SameSite	Controls whether or not a cookie is sent with cross-site requests, providing some protection against cross-site request forgery attacks (CSRF).
secure	boolean	Indicates that the cookie is sent to the server only when a request is made with the https: scheme.
priority	Priority	Defines the Cookie priority.

ParsedCookie<K, V>

Interface representing Cookie properties after it get parsed.

Properties

• Extends and overrides - RawCookie<K, V>

Property	Type	Description
expires	Date	Indicates the maximum lifetime of the cookie.

ParsedCookieMap<K, V>

Map representation of a parsed Cookie.

Static methods

Cookie.parse<K, V>()

Parse the given cookie parameters to a Cookie Map.

Type parameters

Parameter	Description
K	The typed cookie name.
V	The type of the cookie value.

Parameters

Parameter	Type	Description
options	RawCookie<K, V> | ParsedCookieMap<K, V>	The cookie options or a parsed Cookie Map.

Returns

Type: ParsedCookieMap<K, V>

The parsed Cookie Map.

Usage

import { Cookie } from "@alessiofrittoli/web-utils";

const cookie = Cookie.parse({
  name: "cookiename",
  value: { test: "value" },
  path: "/specific-path",
  priority: Priority.High,
  expires: Date.now() + 20 * 60 * 1000,
  domain: "example.com",
  secure: true,
  httpOnly: true,
  sameSite: SameSite.Lax,
  maxAge: Date.now() + 30 * 60 * 1000,
  partitioned: true,
});

Cookie.toString<K, V>()

Stringify a Cookie ready to be stored.

Type parameters

Parameter	Description
K	The typed cookie name.
V	The type of the cookie value.

Parameters

Parameter	Type	Description
options	RawCookie<K, V> | ParsedCookieMap<K, V>	The cookie options or a parsed Cookie Map.

Returns

Type: string

The stringified Cookie ready to be stored.

Usage

import { Cookie } from "@alessiofrittoli/web-utils";

document.cookie = Cookie.toString({
  name: "cookiename",
  value: { test: "value" },
  path: "/specific-path",
  priority: Priority.High,
  expires: Date.now() + 20 * 60 * 1000,
  domain: "example.com",
  secure: true,
  httpOnly: false,
  sameSite: SameSite.Lax,
  maxAge: Date.now() + 30 * 60 * 1000,
  partitioned: true,
});

Cookie.fromString<K, V>()

Parse a cookie string to a Cookie Map.

Type parameters

Parameter	Description
K	The typed cookie name.
V	The expected cookie value type.

Parameters

Parameter	Type	Description
cookie	string	The cookie string.

Returns

Type: ParsedCookieMap<K, V> | null

The parsed Cookie Map or null if parsing fails.

Usage

import { Cookie } from "@alessiofrittoli/web-utils";

const cookies = document.cookie
  .split("; ")
  .map(Cookie.fromString)
  .filter(Boolean);

Cookie.fromListString<T, K>()

Parse a cookie list string to a Map of cookies.

Type parameters

Parameter	Description
T	A Record o key-value pairs (key: cookie name, value: expected cookie value type).
K	Internal.

Parameters

Parameter	Type	Description
list	string	The cookie list string.

Returns

Type: TypedMap<{ [P in K]: ParsedCookieMap<P, T[P]>; }>

The Map of parsed cookies indexed by the Cookie name.

Usage

Defining custom types

import { Cookie } from "@alessiofrittoli/web-utils";

/** On-site stubbed cookie names. */
enum CookieName {
  COOKIE_1 = "cookie-1",
  COOKIE_2 = "cookie-2",
}

interface Cookie1 {
  test: "value";
}

interface Cookie2 {
  test: boolean;
}

type CookiesMap = {
  [CookieName.COOKIE_1]: Cookie1;
  [CookieName.COOKIE_2]: Cookie2;
};

Get parsed cookies from Document.cookie

import { Cookie } from "@alessiofrittoli/web-utils";

const cookies = Cookie.fromListString<CookiesMap>(document.cookie);
const cookie = cookies.get(CookieName.COOKIE_1); // `ParsedCookieMap<CookieName.COOKIE_1, Cookie1> | undefined`
const cookieValue = cookie?.get("value"); // `Cookie1 | undefined`

Get parsed cookies from a request Cookie header

import { Cookie } from "@alessiofrittoli/web-utils";

const { headers } = request;
const cookielist = headers.get("Cookie");

if (cookielist) {
  const cookies = Cookie.fromListString<CookiesMap>(cookielist);
  const cookie = cookies.get(CookieName.COOKIE_2); // `ParsedCookieMap<CookieName.COOKIE_2, Cookie2> | undefined`
  const cookieValue = cookie?.get("value"); // `Cookie2 | undefined`
}

Cookie.get<T>()

Get a cookie by cookie name from Document.cookie.

Type parameters

Parameter	Description
T	The expected type for the Cookie value.

Parameters

Parameter	Type	Description
name	string	The name of the cookie.

Returns

Type: ParsedCookieMap<typeof name, T> | undefined

• The found parsed cookie.
• undefined if no cookie has been found in Document.cookie.

Usage

import { Cookie } from "@alessiofrittoli/web-utils";

const cookie = Cookie.get<string>("access_token");
const value = cookie?.get("value"); // `string | undefined`

Cookie.getAll<T>()

Get a Map of all cookies found in Document.cookie.

Type parameters

Parameter	Description
T	A Record o key-value pairs (key: cookie name, value: expected cookie value type).

Returns

Type: TypedMap<{ [P in K]: ParsedCookieMap<P, T[P]>; }>

The Map of parsed cookies indexed by the Cookie name.

Usage

import { Cookie } from "@alessiofrittoli/web-utils";

const cookies = Cookie.getAll();
const cookie = cookies.get("somecookie");

Cookie.set<K, V>()

Set a cookie to Document.cookie.

Type parameters

Parameter	Description
K	The typed cookie name.
V	The cookie value type.

Parameters

Parameter	Type	Description
options	RawCookie<K, V> | ParsedCookieMap<K, V>	The cookie options or a parsed Cookie Map.

Returns

Type: ParsedCookieMap<K, V> | false

• The set Cookie Map if successful.
• false on failure.

Usage

import { Cookie, type RawCookie } from "@alessiofrittoli/web-utils";

const cookieOptions: RawCookie = {
  name: "cookiename",
  value: { test: "value" },
  path: "/specific-path",
  priority: Priority.High,
  expires: Date.now() + 20 * 60 * 1000,
  domain: "example.com",
  secure: true,
  httpOnly: false,
  sameSite: SameSite.Lax,
  maxAge: Date.now() + 30 * 60 * 1000,
  partitioned: true,
};

Cookie.set(cookieOptions);
// or
Cookie.set(Coookie.parse(cookieOptions));

Cookie.delete()

Delete a cookie by cookie name from Document.cookie.

Parameters

Parameter	Type	Description
name	string	The cookie name to delete.

Returns

Type: boolean

• true on successfull.
• false on failure.

Usage

import { Cookie } from "@alessiofrittoli/web-utils";

Cookie.delete("some_cookie");

LocalStorage Class

A browser-compatible implementation of localStorage.

Static methods

LocalStorage.key()

Get storage item name by item numeric index.

Parameters

Parameter	Type	Description
index	number	The item index in the storage.

Returns

Type: string | null

• The name of the nth key.
• null if n is greater than or equal to the number of key/value pairs.

Usage

import { LocalStorage } from "@alessiofrittoli/web-utils";

console.log(LocalStorage.key(0)); // Outputs: first item name if any.

LocalStorage.getLength()

Get the number of key/value pairs.

Returns

Type: number

The number of key/value pairs.

Usage

import { LocalStorage } from "@alessiofrittoli/web-utils";

console.log(LocalStorage.getLength());

LocalStorage.get<T>()

Get the current value associated with the given key, or undefined if the given key does not exist.

Type parameters

Parameter	Description
T	The expected item value type.

Parameters

Parameter	Type	Description
key	string	The item name.

Returns

Type: T | undefined

• The current value associated with the given key.
• undefined if the given key does not exist.

Usage

import { LocalStorage } from "@alessiofrittoli/web-utils";

LocalStorage.get<Date>("expiration");

LocalStorage.set<T>()

Sets the value of the pair identified by key to value, creating a new key/value pair if none existed for key previously.

Dispatches a storage event on Window objects holding an equivalent Storage object.

If a nullish or empty string value is provided, the LocalStorage.delete() method is invoked.

Type parameters

Parameter	Description
T	The item value type.

Parameters

Parameter	Type	Description
key	string	The item name.
value	T	The item value.

Throws

Type: DOMException

A "QuotaExceededError" DOMException exception if the new value couldn't be set. (Setting could fail if, e.g., the user has disabled storage for the site, or if the quota has been exceeded.)

Usage

import { LocalStorage } from "@alessiofrittoli/web-utils";

LocalStorage.set<Date>("expiration", new Date());

LocalStorage.delete()

Removes the key/value pair with the given key, if a key/value pair with the given key exists.

Dispatches a storage event on Window objects holding an equivalent Storage object.

Parameters

Parameter	Type	Description
key	string	The item name.

Usage

import { LocalStorage } from "@alessiofrittoli/web-utils";

LocalStorage.delete("expiration");

LocalStorage.clear()

Removes all key/value pairs, if there are any.

Dispatches a storage event on Window objects holding an equivalent Storage object.

Usage

import { LocalStorage } from "@alessiofrittoli/web-utils";

LocalStorage.clear();

SessionStorage Class

A browser-compatible implementation of sessionStorage.

Same API References of LocalStorage Class is applied to the SessionStorage Class.

Please, refer to LocalStorage Class static methods API Reference for more informations.

Utils

getDimensions

Extracts and normalizes dimensions from various input formats.

Types

InputDimensions

Represents valid input types for specifying dimensions.

type InputDimensions = string | number | [xy: Dimensions[number]] | Dimensions;

Dimensions

Represents a tuple of two optional numeric values.

type Dimensions = [x: number | undefined, y: number | undefined];

Parameters

Parameter	Type	Description
dimensions	InputDimensions	The input dimensions.

Returns

Type: Dimensions

A tuple containing [ number, number ] where either value can be undefined.

Examples

import { getDimensions } from "@alessiofrittoli/web-utils";

const [width, height] = getDimensions(); // [ undefined, undefined ]
const [width, height] = getDimensions(100); // [ 100, 100 ]
const [width, height] = getDimensions([200, 300]); // [ 200, 300 ]
const [width, height] = getDimensions([200]); // [ 200, 200 ]
const [width, height] = getDimensions("200x300"); // [ 200, 300 ]

Development

Install depenendencies

npm install

or using pnpm

pnpm i

Build the source code

Run the following command to test and build code for distribution.

pnpm build

ESLint

warnings / errors check.

pnpm lint

Jest

Run all the defined test suites by running the following:

# Run tests and watch file changes.
pnpm test:watch

# Run tests in a CI environment.
pnpm test:ci

• See package.json file scripts for more info.

Run tests with coverage.

An HTTP server is then started to serve coverage files from ./coverage folder.

⚠️ You may see a blank page the first time you run this command. Simply refresh the browser to see the updates.

test:coverage:serve

Contributing

Contributions are truly welcome!

Please refer to the Contributing Doc for more information on how to start contributing to this project.

Help keep this project up to date with GitHub Sponsor.

Security

If you believe you have found a security vulnerability, we encourage you to responsibly disclose this and NOT open a public issue. We will investigate all legitimate reports. Email [e-mail] to disclose any security vulnerabilities.

Made with ☕

Alessio Frittoli https://alessiofrittoli.it | [e-mail]