List

A type-safe extended Array class with chainable utility methods for list manipulation and generation.

Installation

npm install @outloud/list

Usage

import { List } from '@outloud/list'

const list = List.from([1, 2, 1, 5, 3, 2])
console.log(list.toUnique()) // [1, 2, 5, 3]

API

Properties

first

Returns the first element of the list, or undefined if the list is empty.

const list = List.from([1, 2, 3])
console.log(list.first) // 1

const empty = List.from([])
console.log(empty.first) // undefined

last

Returns the last element of the list, or undefined if the list is empty.

const list = List.from([1, 2, 3])
console.log(list.last) // 3

const empty = List.from([])
console.log(empty.last) // undefined

isEmpty

Returns true if the list has no elements, false otherwise.

const list = List.from([1, 2, 3])
console.log(list.isEmpty) // false

const empty = List.from([])
console.log(empty.isEmpty) // true

Static Methods

List.generator(arrayLike, generator)

Creates a List with a generator function that can be used to generate new items with the create() method.

const list = List.generator([], () => ({
  id: Math.random(),
  name: 'Generated Item'
}))

list.create()
list.create()
console.log(list.length) // 2
console.log(list[0].name) // 'Generated Item'

Methods

pull(item)

Removes the first occurrence of an item from the list and returns its index, or -1 if not found.

const list = List.from([1, 2, 3, 4, 5])
const index = list.pull(3)
console.log(index) // 2
console.log(list) // [1, 2, 4, 5]

const notFound = list.pull(99)
console.log(notFound) // -1

pushIf(conditional, value, factory?)

Conditionally pushes an item to the list and returns its index, or -1 if not added.

const list = List.from([1])

// Simple conditional push
list.pushIf(true, 2) // Returns 1 (index)
list.pushIf(false, 3) // Returns -1 (not added)
console.log(list) // [1, 2]

// Using factory function
list.pushIf(true, () => 4, true)
list.pushIf(5, (value) => value * 2, true) // Uses the truthy value
console.log(list) // [1, 2, 4, 10]

add(...items)

Adds one or more items to the list and returns the list itself for chaining.

const list = List.from([1, 2])
list.add(3, 4, 5)
console.log(list) // [1, 2, 3, 4, 5]

// Chainable
list.add(6).add(7).add(8)
console.log(list) // [1, 2, 3, 4, 5, 6, 7, 8]

remove(...items)

Removes one or more items from the list and returns the list itself for chaining.

const list = List.from([1, 2, 3, 4, 5])
list.remove(2, 4)
console.log(list) // [1, 3, 5]

// Chainable
list.remove(1).remove(5)
console.log(list) // [3]

merge(items)

Merges an array of items into the list and returns the list itself for chaining.

const list = List.from([1, 2])
list.merge([3, 4, 5])
console.log(list) // [1, 2, 3, 4, 5]

// Chainable
list.merge([6, 7]).merge([8, 9])
console.log(list) // [1, 2, 3, 4, 5, 6, 7, 8, 9]

addIf(conditional, value, factory?)

Conditionally adds an item to the list and returns the list itself for chaining.

const list = List.from([1])

// Simple conditional add
list.addIf(true, 2).addIf(false, 3)
console.log(list) // [1, 2]

// Using factory function
list.addIf(true, () => 4, true)
list.addIf(5, (value) => value * 2, true)
console.log(list) // [1, 2, 4, 10]

generate()

Generates a new item using the generator function defined in List.generator(). Throws an error if no generator is defined.

const list = List.generator([], () => Math.random())
const item = list.generate()
console.log(typeof item) // 'number'
console.log(list.length) // 0 (item not added to list)

create()

Generates a new item using the generator function and adds it to the list.

const list = List.generator([], () => ({ id: Date.now() }))
list.create()
list.create()
console.log(list.length) // 2
console.log(list[0].id) // timestamp

unique()

Removes duplicate items from the list and returns the list itself (mutates).

const list = List.from([1, 2, 1, 3, 2, 4])
const result = list.unique()
console.log(result) // [1, 2, 3, 4]
console.log(result === list) // true (same reference)

toUnique()

Returns a new List with all unique items (does not mutate the original).

const list = List.from([1, 2, 1, 3, 2, 4])
const unique = list.toUnique()
console.log(unique) // [1, 2, 3, 4]
console.log(unique === list) // false (different reference)
console.log(list) // [1, 2, 1, 3, 2, 4] (unchanged)

toCompact()

Returns a new List with all non-nullable items (removes null and undefined).

const list = List.from([1, null, 2, undefined, 3])
const compact = list.toCompact()
console.log(compact) // [1, 2, 3]
console.log(compact === list) // false (different reference)
console.log(list) // [1, null, 2, undefined, 3] (unchanged)

toArray()

Returns a plain Array with all items.

const list = List.from([1, 2, 3])
const array = list.toArray()
console.log(array instanceof Array) // true
console.log(array instanceof List) // false
console.log(array) // [1, 2, 3]