List

Minimalist, mutable, double linked, iterable list.

List supports iteration over values and nodes. If you wish to have functions like map, filter, forEach, and such, please use an iterable or Observable library. One such possibility is Iterablefu.

Table of Contents

• Installation
• Getting Started
• API
  • Node
  • constructor
  • first
  • last
  • insertAfter
  • insertBefore
  • remove
  • push
  • pop
  • find
  • shift
  • nodes
  • nodesReversed
  • from
  • of
  • Symbol.iterator
• Contributing
• Issues
• License

Installation

npm install --save @toolbuilder/list

Access the latest UMD package from unpkg like this:

<script src="https://unpkg.com/@toolbuilder%2flist/umd/list.umd.min.js"></script>

Or for the full version:

<script src="https://unpkg.com/@toolbuilder%2flist/umd/list.umd.js"></script>

Both packages create a global variable representing the list as DoubleLinkedList.

Getting Started

To access as the Node version, use this import:

let { List } = require('@toolbuilder/list')

const list = new List()
list.push('A')
const node = list.first()
list.insertAfter(node, 'B')
console.log(list.last().value) // prints 'B'

To access the pure list with no esm dependency, use this import:

import { List } from '@toolbuilder/list/src/list.js'

API

API documentation follows.

Node

The Node object is used by insertBefore and insertAfter to specify where to insert a new value. Other methods return Nodes to support using those two methods. Nodes are only valid for the List that created them.

const list = List.of('A', 'C')
list.insertAfter(list.first(), 'B')
console.log([...list]) // prints ['A', 'B', 'C']

The Node object has a value property, which provides the value associated with that node. Other properties and methods of the Node object are subject to change, and are not considered part of the public API.

const list = List.of('A')
const node = list.first()
console.log(node.value) // prints 'A'

constructor

Constructor.

Parameters

• iterable Iterable builds list using iterable (optional, default null)

Examples

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

first

Provide the first node in the list. Returns undefined if list is empty.

Examples

const list = List.from(['a', 'b', 'c'])
const node = list.first()
console.log(node.value) // prints 'a'

Returns Node first node in list

last

Provide the last node in the list. Returns undefined if list is empty.

Examples

const list = List.from(['A', 'B', 'C'])
const node = list.last()
console.log(node.value) // prints 'C'

Returns Node last node in list

insertAfter

Insert value after a node.

Parameters

• prevNode Node node from this list to insert value behind
• value any value to insert

Examples

const list = new List(['A', 'B', 'D'])
const prevNode = list.find(value => value === 'B')
list.insertAfter(prevNode, 'C')
console.log([...list]) // prints ['A', 'B', 'C', 'D']

Returns Node the newly created node

insertBefore

Insert value before a node.

Parameters

• nextNode Node node from this list to insert value in front of
• value any value to insert

Examples

const list = new List(['A', 'C', 'D'])
const nextNode = list.find(value => value === 'C')
list.insertBefore(nextNode, 'B')
console.log([...list]) // prints ['A', 'B', 'C', 'D']

Returns Node the newly created node

remove

Remove a node from the list.

Parameters

• node Node the node to remove from the list. The node is no longer useable after this call, and no longer references the associated value.

Examples

const list = new List(['A', 'B', 'C', 'D'])
const node = list.find(value => value === 'C')
list.remove(node)
// at this point the variable 'node' is no longer useable, node.value will return null.
console.log([...list]) // prints ['A', 'B', 'D']

push

Add a value to the end of the list.

Parameters

• value any to be added to end of list

Examples

const list = new List(['A', 'B', 'C'])
const node = list.push('D')
console.log([...list]) // prints ['A', 'B', 'C', 'D']
console.log(node.value) // prints 'D'

Returns Node the newly created Node

pop

Remove the last value in the list.

Examples

const list = new List(['A', 'B', 'C'])
const value = list.pop()
console.log([...list]) // prints ['A', 'B']
console.log(value) // prints 'C'

Returns any the value of the removed node, or undefined if the list was empty

find

Find the first value in the list where callback(value) returns truthy.

Parameters

• callback Function called for each value in the list until returns truthy
• thisArg Object value to use as this when executing callback, defaults to null (optional, default null)

Examples

const list = new List(['A', 'B', 'C', 'D'])
const node = list.find(value => value === 'C')
console.log(node.value) // prints 'C'

Returns Node the node that contains the value. The value property will provide the value.

shift

Remove first node from list, and return the value. When combined with push, this enables List to work like a FIFO queue.

Examples

const list = List.from(['A', 'B', 'C'])
const value = list.shift()
console.log(value) // prints 'A'
console.log([...list]) // prints ['B', 'C']

Returns any the value of the first node before the call to shift, or undefined if the list is empty.

nodes

Generator that produces each node list in order from first to last. The value property of each node provides the associated value.

Examples

const list = List.from([1, 2, 3, 4])
const array = []
for (const node of list.nodes()) {
  array.push(node.value)
}
console.log(array) // prints [1, 2, 3, 4]

Returns Generator

nodesReversed

Generator that produces each node in order from last to first.

Returns Generator

from

Static constructor.

Parameters

• iterable Iterable build list from iterable, may be null (optional, default null)

Examples

const list = List.from(['A', 'B'])
console.log([...list]) // prints ['A', 'B']

Returns List

of

Static constructor from parameter values.

Parameters

• values ...any each value becomes an element of the list in the order provided

Examples

const list = List.of(1, 2, 'B')
console.log([...list]) // prints [1, 2, 'B']

Returns List

Symbol.iterator

Iterable protocol over the values in the list.

Examples

const list = List.from([1, 2, 3, 4])
const array = []
for (const value of list) {
  array.push(value)
}
console.log(array) // prints [1, 2, 3, 4]

Returns Generator

Contributing

Contributions are welcome. Please create a pull request. Linting with standard, version 13.1.0.

Issues

This project uses Github issues.

License

The MIT License (MIT)

Copyright 2019 Kevin Hudson

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.