suspended-list v1.0.0

A data-structure that arranges items according to a sparse set of position-rules (e.g. "a before b" and "z after y"), as a Node.js module.

Index

• Installation
• Basic Usage
• Motivation
• The SuspendedList Class
  • constructor
  • length
  • item
  • toArray
  • addRuleXBeforeY
  • addRuleXAfterY
  • removeRuleXBeforeY
  • removeRuleXAfterY
  • removeRulesForItem
  • copy
  • push
  • unshift
  • pushRight
  • insert
  • pop
  • shift
  • popLeft
  • popRight
  • remove
  • removeAtIndex
  • find
  • findIndex
  • includes
  • indexOf
  • lastIndexOf
  • forEach
  • map
  • filter
  • reduce
  • reduceRight

Installation

Using npm:

npm i -g npm
npm i --save suspended-list

Using yarn:

yarn add suspended-list

Basic Usage

After installing the package you can use it in Node.js as follows:

// Load the package
var SuspendedList = require('suspended-list');

// create an instance of the list
var list = new SuspendedList();

// use the list
list.addRuleXBeforeY('a', 'b');
list.push('b');
list.push('a');

// prints 'list.toArray(): "[ 'a', 'b' ]"'
console.log('list.toArray(): "' + list.toArray() + '"');

Motivation

A suspended-list is supposed to solve the scenario where there is no straight-forward, global order for a list of items, but there is an order that binds certain pairs of items in the list.

For example, if you have a list if tasks that you want to complete by the end of the day you may list them as follows:

[
  'shower',
  'do the dishes',
  'workout',
  'yoga',
  'creative writing',
  'meal prep',
  'water flowers',
  'grocery run'
]

The exact order in which you carry out the tasks may not be obvious at once, but you may have personal rules for some tasks that have to be carried out before others:

[
  'yoga after workout',
  'shower after yoga', // shower after the sweatiest part of the day
  'creative writing after meal prep',
  'do the dishes before creative writing', // the dishwasher will be done by the time you're done creative writing
  'grocery run before meal prep',
  'grocery run before workout',
  'meal prep before creative writing'
]

The suspended list would be able to arrange the items in an order that respects all of the above rules, if none of the rules conflict each other. Some tasks may have no associated rules and may be placed wherever we want.

The SuspendedList Class

constructor(serializer = identity)

• serializer {Function} - A method that take a list itemas an input and outputs a unique string for each item. This defaults to an identity function (a function that returns the input as an output).

length

The length property returns the number of items in the list.

item(index)

returns {Any} the item at the provided index.

• index {Integer} - The index of the list item to retrieve.

toArray()

returns {Array} a copy of the inner list (not a SuspendedList). Since the returned value is a copy modifying it won't affect the SuspendedList.

addRuleXBeforeY(x, y)

Adds a rule that item x should appear in the list before item y.

• x {Any} - The item that should appear to the left of y.
• y {Any} - The item that should appear to the right of x.

addRuleXAfterY(x, y)

Adds a rule that item x should appear in the list after item y.

• x {Any} - The item that should appear to the right of y.
• y {Any} - The item that should appear to the left of x.

removeRuleXBeforeY(x, y)

Removes the rule that item x should appear in the list before item y, if that rule exists.

• x {Any} - The item that should have appeared to the left of y.
• y {Any} - The item that should have appeared to the right of x.

removeRuleXAfterY(x, y)

Removes the rule that item x should appear in the list after item y, if that rule exists.

• x {Any} - The item that should have appeared to the right of y.
• y {Any} - The item that should have appeared to the left of x.

removeRulesForItem(item)

Removes all rules associated with the provided item, if any exists. This means that all rules added by calling list.addRuleXBeforeY(item, *) or list.addRuleXAfterY(item, *) will be removed.

• item {Any} - The item whose associated rules are to be removed.

copy()

Returns {SuspendedList} a deep copy of the SuspendedList. Adding/Removing items or rules from this copy will not affect the original whatsoever.

push|pushRight(item)

Pushes the provided item at the end of the list.

• item {Any} - The item to add to the list.

unshift|pushLeft(item)

Pushes the provided item at the start of the list.

• item {Any} - The item to add to the list.

insert(item, index)

Inserts the provided item at the indicated list index.

• item {Any} - The item to add to the list.
• index {Integer} - The index in the list at which to add the item.

pop|popRight()

Returns {Any} and removes the item at the end of the list.

shift|popLeft()

Returns {Any} and removes the item at the start of the list.

remove(item)

Removes the first instance of the provided item that appears in the list.

• item {Any} - The item to remove from the list.

removeAtIndex(index)

Removes the item at the indicated list index.

• index {Integer} - The index of the item to be removed.

find(callback, thisArg = this._list)

Returns {Any} iterates over the list and returns the first item that satisfies the provided callback.

• callback {Function} - A function that takes a list item as an input and returns true if the item matches the item being sought after.

findIndex(callback, thisArg = this._list)

Returns {Integer} iterates over the list and returns the index of the first item that satisfies the provided callback.

• callback {Function} - A function that takes a list item as an input and returns true if the item matches the item being sought after.

includes(valueToFind, fromIndex = undefined)

Returns {Boolean} true if the item being sought after exists in the list.

• valueToFind {Any} - The item being sought after in the list.
• fromIndex {Integer} - The list index at which to start looking for the provided value.

indexOf(searchElement, fromIndex = undefined)

Returns {Integer} the index in the list of the first item that matches the provided search item.

• searchElement {Any} - The item whose index we're seeking.
• fromIndex {Integer} - The list index at which to start looking for the provided item.

lastIndexOf(searchElement, fromIndex = undefined)

Returns {Integer} the index in the list of the last item that matches the provided search item.

• searchElement {Any} - The item whose index we're seeking.
• fromIndex {Integer} - The list index at which to start to start looking for the provided item (moving backwards from the indicated index).

forEach(callback, thisArg = this._list)

iterates over each item in the list and calls the callback with each item as an input.

• callback {Function} - A function that takes a list item as an input.

map(callback, thisArg = this._list)

Returns {Array} iterates over each item in the list and calls the callback with each item as an input, and appends the output of the callback to a list that will eventually be returned to the caller.

• callback {Function} - A function that takes a list item as an input, and outputs any value.

filter(callback, thisArg = this._list)

Returns {Array} iterates over each item in the list and calls the callback with each item as an input, if the callback returns a truthy value then the list item is appended to a list that will eventually be returned to the caller.

• callback {Function} - A function that takes a list item as an input, and outputs a boolean value. true indicates that the list item is to be included in the output list. false indicates that the list item is not to be included in the output list.

reduce(callback, initialValue = undefined)

Returns {Any} Reduces the list items into a single value by calling the provided "reducer" callback function.

• callback {Function} - A method that takes two inputs (accumulator, currentValue) and returns a combined (reduced) value.
• initialValue {Any} - The initial accumulator value. If not provided then the first list item is passed as the first accumulator.

reduceRight(callback, initialValue = undefined)

Returns {Any} Reduces the list items into a single value by calling the provided "reducer" callback function. The reduction happens from the right hand side and moves leftwards.

• callback {Function} - A method that takes two inputs (accumulator, currentValue) and returns a combined (reduced) value.
• initialValue {Any} - The initial accumulator value. If not provided then the last list item is passed as the initial accumulator.