yallist

What is yallist?

The yallist package is a Node.js module that provides a linked list data structure. It allows for efficient insertion and removal of elements from the beginning and end of the list, as well as iteration and various list manipulations.

What are yallist's main functionalities?

Create a linked list

This feature allows you to create a new linked list. You can pass in any number of arguments to the constructor, and they will be added to the list in order.

const Yallist = require('yallist')
const list = new Yallist(1, 2, 3)

Push items to the list

Pushing items to the list adds them to the end. This is similar to the Array.prototype.push method.

list.push('a')
list.push('b')

Pop items from the list

Popping items from the list removes the last item and returns it. This is similar to the Array.prototype.pop method.

list.pop()

Unshift items to the list

Unshifting items to the list adds them to the beginning. This is similar to the Array.prototype.unshift method.

list.unshift('new item')

Shift items from the list

Shifting items from the list removes the first item and returns it. This is similar to the Array.prototype.shift method.

list.shift()

Iterate over the list

You can iterate over the list using a for-of loop, similar to how you would with an array.

for (let item of list) {
  console.log(item)
}

Map a function over the list

The map method creates a new list with the results of calling a provided function on every element in the calling list.

const mappedList = list.map(x => x * 2)

Reduce the list

The reduce method applies a function against an accumulator and each element in the list to reduce it to a single value.

const sum = list.reduce((acc, x) => acc + x, 0)

Other packages similar to yallist

linked-list

The 'linked-list' package provides a basic linked list implementation. It offers similar functionality for adding and removing elements, but yallist has additional methods like map and reduce, making it more versatile.

double-ended-queue

The 'double-ended-queue' package, also known as 'deque', is similar to yallist in that it allows elements to be added or removed from both ends of the queue. However, it is optimized for queue and stack operations and does not provide linked list-specific features like node traversal.

list

The 'list' package is a functional list data structure with a focus on functional programming techniques. It provides many of the same methods as yallist but emphasizes immutability and persistent data structures.

README

yallist

Yet Another Linked List

There are many doubly-linked list implementations like it, but this one is mine.

For when an array would be too big, and a Map can't be iterated in reverse order.

basic usage

import { Yallist } from 'yallist'
var myList = new Yallist([1, 2, 3])
myList.push('foo')
myList.unshift('bar')
// of course pop() and shift() are there, too
console.log(myList.toArray()) // ['bar', 1, 2, 3, 'foo']
myList.forEach(function (k) {
  // walk the list head to tail
})
myList.forEachReverse(function (k, index, list) {
  // walk the list tail to head
})
var myDoubledList = myList.map(function (k) {
  return k + k
})
// now myDoubledList contains ['barbar', 2, 4, 6, 'foofoo']
// mapReverse is also a thing
var myDoubledListReverse = myList.mapReverse(function (k) {
  return k + k
}) // ['foofoo', 6, 4, 2, 'barbar']

var reduced = myList.reduce(function (set, entry) {
  set += entry
  return set
}, 'start')
console.log(reduced) // 'startfoo123bar'

api

The whole API is considered "public".

Functions with the same name as an Array method work more or less the same way.

There's reverse versions of most things because that's the point.

Yallist

Default export, the class that holds and manages a list.

Call it with either a forEach-able (like an array) or a set of arguments, to initialize the list.

The Array-ish methods all act like you'd expect. No magic length, though, so if you change that it won't automatically prune or add empty spots.

Yallist.create(..)

Alias for Yallist function. Some people like factories.

yallist.head

The first node in the list

yallist.tail

The last node in the list

yallist.length

The number of nodes in the list. (Change this at your peril. It is not magic like Array length.)

yallist.toArray()

Convert the list to an array.

yallist.forEach(fn, [thisp])

Call a function on each item in the list.

yallist.forEachReverse(fn, [thisp])

Call a function on each item in the list, in reverse order.

yallist.get(n)

Get the data at position n in the list. If you use this a lot, probably better off just using an Array.

yallist.getReverse(n)

Get the data at position n, counting from the tail.

yallist.map(fn, thisp)

Create a new Yallist with the result of calling the function on each item.

yallist.mapReverse(fn, thisp)

Same as map, but in reverse.

yallist.pop()

Get the data from the list tail, and remove the tail from the list.

yallist.push(item, ...)

Insert one or more items to the tail of the list.

yallist.reduce(fn, initialValue)

Like Array.reduce.

yallist.reduceReverse

Like Array.reduce, but in reverse.

yallist.reverse

Reverse the list in place.

yallist.shift()

Get the data from the list head, and remove the head from the list.

yallist.slice([from], [to])

Just like Array.slice, but returns a new Yallist.

yallist.sliceReverse([from], [to])

Just like yallist.slice, but the result is returned in reverse.

yallist.splice(start, deleteCount, ...)

Like Array.splice.

yallist.toArray()

Create an array representation of the list.

yallist.toArrayReverse()

Create a reversed array representation of the list.

yallist.unshift(item, ...)

Insert one or more items to the head of the list.

yallist.unshiftNode(node)

Move a Node object to the front of the list. (That is, pull it out of wherever it lives, and make it the new head.)

If the node belongs to a different list, then that list will remove it first.

yallist.pushNode(node)

Move a Node object to the end of the list. (That is, pull it out of wherever it lives, and make it the new tail.)

If the node belongs to a list already, then that list will remove it first.

yallist.removeNode(node)

Remove a node from the list, preserving referential integrity of head and tail and other nodes.

Will throw an error if you try to have a list remove a node that doesn't belong to it.

Yallist.Node

The class that holds the data and is actually the list.

Call with const n = new Node(value, previousNode, nextNode)

Note that if you do direct operations on Nodes themselves, it's very easy to get into weird states where the list is broken. Be careful :)

node.next

The next node in the list.

node.prev

The previous node in the list.

node.value

The data the node contains.

node.list

The list to which this node belongs. (Null if it does not belong to any list.)