pair-table v1.2.1

pair-table

PairTable is a class with an API similar to the ES2015 Set, except that it deals with ordered pairs of values, so you can use it as a join table.

Usage

import PairTable from 'pair-table';

const table = new PairTable();

table.add('foo', 'bar');
table.add('foo', 'baz');
table.add('123', 456);

table.has('foo', 'no');  // false (doesn't exist)
table.has('baz', 'foo'); // false (wrong order)

table.has('foo', 'bar'); // true
table.has('foo', 'baz'); // true

table.has('123', '456'); // false (strings !== integers)

table.getRightsFor('foo'); // Set {'bar', 'baz'}
table.getLeftsFor('baz'); // Set {'foo'}

Notes:

• It's conceptually similar to an ES2015 Set, but with every item being a pairing of two values – ‘left’ and ‘right’.
  • It might look more like a Map at first glance, but it's not – in a Map, the left side in each pairing is a key, and keys must be unique. With a pair table, a single value may appear multiple times in either column.
• The order of a pair matters: 'a', 'b' is not the same as 'b', 'a'.

API

add(left, right)

Adds a pair and returns the table. Has no effect if this exact pair already exists.

remove(left, right)

Removes a pair and returns the table. Has no effect if this exact pair does not exist.

has(left, right)

Checks if a pair exists and returns true or false.

clear()

Empties the table.

getRightsFor(left)

Returns the Set of ‘right’ values that are paired with the given ‘left’ value.

getLeftsFor(right)

Returns the Set of ‘left’ values that are paired with the given ‘right’ value.

getAllLefts()

Returns a Set of all the left values.

getAllRights()

Returns a Set of all the right values.

size

The number of pairs currently in the table.

Iterating

Every pair table is iterable. Each iteration gets a two-item array in the form left, right:

const table = new PairTable();

table.add('cow', 'grass');
table.add('rabbit', 'carrots');
table.add('rabbit', 'lettuce');

for (const [animal, food] of table) {
  console.log(`${animal} eats ${food}`);
}
// cow eats grass
// rabbit eats carrots
// rabbit eats lettuce

Warning: Updating the table while you're iterating over it will probably confuse the iterator. If you really need to do it, spread the table into an array first:

for (const [x, y] of [...table]) {
  // safe to update table here
}

License

MIT