Type: T[]

The filtered array.

Removes duplicates from array

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

const pointer = {}
console.log(arrayUnique([pointer, 'b', pointer, 'c', 'b']))
// Outputs: [ {}, 'b', 'c' ]

Type: T[]

The filtered array.

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' },
// ]

Type: string[]

The converted stringified Array to Array object.

Basic usage

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

console.log(listToArray('1,2, 3, 4').map(Number))
// Outputs: [ 1, 2, 3, 4 ]

Type: T[]

An Array of chunks.

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 ] ]

Type: Array<T>

The modified shuffled array.

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

console.log(shuffle([1, 2, 3, 4, 5]))

Type: number

The normalized index.

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

Type: number

The previous index.

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

Type: number

The next index.

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

• T The type of elements in the array.

Type: T[]

A new array with the item(s) inserted at the specified position.

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' ]

• T The object type stored in the array.
• U The key of T used for the comparison.

Type: number

The index of the matching item, or -1 when no match is found.

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

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 )
  } )

Block Document HTML scroll when a popup is opened

import { blockScroll } from '@alessiofrittoli/web-utils/dom'

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/dom'

const element = document.querySelector('.css-selector')

if (element) {
  blockScroll(element)
}

Restore Document HTML scroll when a popup is closed

import { restoreScroll } from '@alessiofrittoli/web-utils/dom'

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

Restore scroll of a specific HTMLElement

import { restoreScroll } from '@alessiofrittoli/web-utils/dom'

const element = document.querySelector('.css-selector')

if (element) {
  restoreScroll(element)
}

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.

import { cloneStyleSheetList } from '@alessiofrittoli/web-utils/stylesheet'

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

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.

Cloning StyleSheetList

import { cloneStyleSheets } from '@alessiofrittoli/web-utils/stylesheet'

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/stylesheet'

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 },
])

Type: reference is GeneratorFunction | AsyncGeneratorFunction

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

Type: reference is GeneratorFunction

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

Type: reference is AsyncGeneratorFunction

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

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

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

Type: reference is Generator<T>

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

Type: reference is AsyncGenerator<T>

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

Type: Promise<void>

A new Promise which get resolved after the specified time.

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

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

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

A new Promise which returns the task result once fulfilled.

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 )
} )

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

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

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

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

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

Type: string

The processed string.

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

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

Type: string

The processed string.

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

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

Type: string

The converted string to camelCase.

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'

Type: string

The converted string to kebab-case.

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

Type: string

The stringified input.

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: ''

Type: T | undefined

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

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'

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

const data = {
  value: 'parameterized',
}

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

Type: boolean

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

Check if current device is landscape oriented

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

console.log(!getMediaMatches('(orientation:portrait)'))

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.

Re-focus a previously opened popup

import { openBrowserPopUp } from '@alessiofrittoli/web-utils/browser-popup'

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/browser-popup'

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

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

Type: boolean

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

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

if ( isDocumentPictureInPictureSupported() ) {
  ...
}

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

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 )
  }
}

Type: Promise<OpenDocumentPictureInPicture>

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

Simple usage

import { openDocumentPictureInPicture, ErrorCode } from '@alessiofrittoli/web-utils/picture-in-picture'
import { Exception } from '@alessiofrittoli/exception'

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 { openDocumentPictureInPicture, ErrorCode } from '@alessiofrittoli/web-utils/picture-in-picture'
import { Exception } from '@alessiofrittoli/exception'

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) {
    // ...
  }
}

Type: boolean

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

Check if current device is landscape oriented

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

console.log(!isPortrait())

Type: Connection

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

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

const { network } = getConnection()

console.log(network?.effectiveType)

import type { RawCookie, ParsedCookie, ParsedCookieMap } from '@alessiofrittoli/web-utils/cookie'
import { Priority, SameSite } from '@alessiofrittoli/web-utils/cookie'

Priority Enum

The Cookie 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).

RawCookie<K, V>

Interface representing Cookie properties before it get parsed.

ParsedCookie<K, V>

Interface representing Cookie properties after it get parsed.

ParsedCookieMap<K, V>

Map representation of a parsed Cookie.

Cookie.parse<K, V>()

Parse the given cookie parameters to a Cookie Map.

import { Cookie } from '@alessiofrittoli/web-utils/cookie'

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.

import { Cookie } from '@alessiofrittoli/web-utils/cookie'

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.