HyperFrontend
@hyperfrontend/list-utilsView on npm →API Reference →

@hyperfrontend/list-utils

Purpose-built collection utilities for queue management, filtering, and iteration patterns.

What is @hyperfrontend/list-utils?

@hyperfrontend/list-utils provides specialized collection utilities focused on common programming patterns that native JavaScript arrays don't handle elegantly. Rather than replicating lodash, this library targets specific use cases: FIFO/LIFO queue management with object reference tracking, cyclical value iteration, and string array sanitization.

The library enforces immutability through frozen interfaces while maintaining high performance. All queue operations (FIFO/LIFO) use native Set for O(1) lookups and guaranteed uniqueness, solving the common problem of accidentally adding duplicate items to task queues or event handlers.

Key Features

  • FIFO and LIFO queues with type-safe object tracking
  • Value picker for cyclical iteration (ideal for round-robin patterns)
  • String sanitization utilities (dedupe, trim, filter empty)
  • Range generation for loop-free number sequences
  • Map utilities for common Map operations
  • Zero dependencies - Self-contained implementation with no third-party runtime dependencies

Architecture Highlights

Queue implementations return frozen objects to prevent external mutation while using native Set internally for optimal performance. Object-only restriction on queues prevents reference comparison issues with primitives.

Why Use @hyperfrontend/list-utils?

Prevents Queue Bugs in Event-Driven Systems

Native arrays don't enforce uniqueness, making it easy to accidentally register the same event handler, task, or subscription multiple times. FIFO/LIFO lists automatically reject duplicates based on reference equality, eliminating a common source of memory leaks and duplicate processing in event loops, job queues, and observer patterns.

Simplifies Round-Robin and Cyclical Patterns

The value picker solves the boilerplate problem of cycling through options (load balancer endpoints, color schemes, retry strategies). No manual index tracking or modulo math—just call next(). Particularly useful for testing scenarios where you need predictable value rotation.

Type-Safe String Sanitization

nonEmptyStrings() and uniqueStrings() handle the tedious work of cleaning user input, configuration arrays, or CSV parsing results. Filters null/undefined/empty/whitespace-only values in one call, with full TypeScript type narrowing.

Functional Composition Without Dependencies

All utilities return new arrays or frozen objects, never mutate inputs. This makes them safe for use in React hooks dependencies, Redux reducers, or any pure function context. No lodash required for these specific operations.

Installation

npm install @hyperfrontend/list-utils

Quick Start

import { createFifoList, createValuePicker, nonEmptyStrings, uniqueStrings } from '@hyperfrontend/list-utils'

// FIFO queue for task management
const taskQueue = createFifoList<{ id: string; execute: () => void }>()
taskQueue.push({ id: 'task1', execute: () => console.log('Task 1') })
taskQueue.push({ id: 'task2', execute: () => console.log('Task 2') })
const nextTask = taskQueue.pull() // Gets task1 (first in)

// Round-robin value picker
const colorPicker = createValuePicker(['red', 'blue', 'green'])
colorPicker.next() // 'red'
colorPicker.next() // 'blue'
colorPicker.next() // 'green'
colorPicker.next() // 'red' (cycles back)

// String sanitization
const userInputs = ['  hello  ', '', 'world', null, 'hello', '   ', 'world']
const cleaned = uniqueStrings(nonEmptyStrings(userInputs)) // ['hello', 'world']

API Overview

Queue Management

  • createFifoList<T>() - First-in-first-out queue with reference uniqueness
  • createLifoList<T>() - Last-in-first-out stack with reference uniqueness

Iteration Utilities

  • createValuePicker(values) - Cyclical iterator for round-robin patterns
  • createRange(start, end) - Generate number arrays without loops

String Utilities

  • nonEmptyStrings(values) - Filter null/undefined/empty/whitespace strings
  • uniqueStrings(values) - Remove duplicates while preserving order

Map Helpers

  • getLastKeyInMap(map) - Retrieve the last inserted key from a Map

Compatibility

Platform Support
Browser ✅
Node.js ✅
Web Workers ✅
Deno, Bun, Cloudflare Workers ✅

Output Formats

Format File Tree-Shakeable
ESM index.esm.js ✅
CJS index.cjs.js ❌
IIFE bundle/index.iife.min.js ❌
UMD bundle/index.umd.min.js ❌

CDN Usage

<!-- unpkg -->
<script src="https://unpkg.com/@hyperfrontend/list-utils"></script>

<!-- jsDelivr -->
<script src="https://cdn.jsdelivr.net/npm/@hyperfrontend/list-utils"></script>

<script>
  const { createQueue, forEach } = HyperfrontendListUtils
</script>

Global variable: HyperfrontendListUtils

Part of hyperfrontend

This library is part of the hyperfrontend monorepo.

📖 Full documentation

License

MIT

API Reference§

Filter:

ƒFunctions

§function

createFifoList<T>(): FifoList<T>

Creates a FIFO (First-In-First-Out) list.

Returns

FifoList<T>
A FIFO list with methods to manipulate and query the list.

Example

Creating and using FIFO queue

interface Task { id: number; name: string }
const queue = createFifoList<Task>()

queue.push({ id: 1, name: 'first' })
queue.push({ id: 2, name: 'second' })

queue.pull() // => { id: 1, name: 'first' }
queue.pull() // => { id: 2, name: 'second' }
§function

createLifoList<T>(): LifoList<T>

Creates a LIFO (Last-In-First-Out) list.

Returns

LifoList<T>
A LIFO list with methods to manipulate and query the list.

Example

Creating and using LIFO stack

interface HistoryEntry { url: string; timestamp: number }
const history = createLifoList<HistoryEntry>()

history.push({ url: '/home', timestamp: 1 })
history.push({ url: '/about', timestamp: 2 })

history.pull() // => { url: '/about', timestamp: 2 }
history.pull() // => { url: '/home', timestamp: 1 }
§function

createRange(start: number, end: number): number[]

Creates an array of numbers within a specified range (inclusive).

Parameters

NameTypeDescription
§start
number
The starting number of the range
§end
number
The ending number of the range (inclusive)

Returns

number[]
An array containing all numbers from start to end

Example

Generating number ranges

createRange(1, 5)
// => [1, 2, 3, 4, 5]

createRange(3, 3)
// => [3]
§function

createValuePicker(values: string[]): ValuePicker

Creates a value picker that cycles through a list of string values.

Parameters

NameTypeDescription
§values
string[]
The array of string values to cycle through

Returns

ValuePicker
A ValuePicker instance with current and next methods

Example

Cycling through values

const colorPicker = createValuePicker(['red', 'green', 'blue'])

colorPicker.current() // => 'red'
colorPicker.next()    // => 'red' (first call initializes)
colorPicker.next()    // => 'green'
colorPicker.next()    // => 'blue'
colorPicker.next()    // => 'red' (cycles back)
§function

getLastKeyInMap<K>(map: Map<K, any>): K

Retrieves the final key from a Map by converting keys to an array.

Parameters

NameTypeDescription
§map
Map<K, any>
The Map to extract the last key from

Returns

K
The key that was inserted last, or undefined if map is empty

Example

Getting last key from Map

const userRoles = new Map<string, string>()
userRoles.set('alice', 'admin')
userRoles.set('bob', 'editor')
userRoles.set('charlie', 'viewer')

getLastKeyInMap(userRoles) // => 'charlie'
§function

nonEmptyStrings(values: string[]): string[]

Filters out empty, null, undefined, and whitespace-only strings from an array.

Parameters

NameTypeDescription
§values
string[]
The array of strings to filter

Returns

string[]
A new array containing only non-empty strings with content

Example

Filtering empty strings

nonEmptyStrings(['hello', '', '  ', 'world', null as unknown as string])
// => ['hello', 'world']
§function

uniqueStrings(values: string[]): string[]

Removes duplicate strings from an array, preserving insertion order.

Parameters

NameTypeDescription
§values
string[]
The array of strings to deduplicate

Returns

string[]
A new array containing only unique strings

Example

Deduplicating strings

uniqueStrings(['apple', 'banana', 'apple', 'cherry', 'banana'])
// => ['apple', 'banana', 'cherry']

◈Interfaces

§interface

FifoList

A FIFO (First-In-First-Out) list interface.

Properties

§interface

LifoList

A LIFO (Last-In-First-Out) list interface.

Properties

§interface

ValuePicker

Interface for cycling through a list of values.

Properties

§current:() => string—
Returns the current value without advancing.
§next:() => string—
Advances and returns the next value, cycling at end.

Related

Getting Started

Learn how to set up hyperfrontend.

Architecture Guide

Understand how the libraries work together.