array-keyed-map

A map which keys are Array "paths" of arbitrary values. Uses the identity of the objects in the key (like Map does with a single key); not some fragile string-serialisation hack.

const ArrayKeyedMap = require('array-keyed-map')
const m = new ArrayKeyedMap()

const obj = { x: true }
const objIdentical = { x: true }
const fun = function() {}
const reg = /regexp/

// Set values
m.set([obj],            1)
m.set([obj, fun],       2)
m.set([reg, reg, true], 3)
m.set([],               4)

// Get values
console.log( m.get([obj]) )            // => 1
console.log( m.get([objIdentical]) )   // => undefined
console.log( m.get([obj, fun]) )       // => 2
console.log( m.get([reg, reg, true]) ) // => 3
console.log( m.get([]) )               // => 4

Implements the same methods as Map, with the difference of not remembering insertion order when iterating entries later. Stores paths compactly as a tree.

API

new ArrayKeyedMap([iterable])

Arguments:

• (optional) iterable: any iterable value of [key, value] entries from which to initialise contents

Returns ArrayKeyedMap akmap.

Array keyed maps are iterable, so you can use them in for-loops, pass them to Array.from, pass them into the constructor to create a copy (let copy = new ArrayKeyedMap(akmap)), etc. (See .entries.)

akmap.set(array, value)

Arguments:

• array: Array of values
• value: any value

Sets the value for the given array.

Objects in the array are treated by identity. The identity of the array object itself is irrelevant.

Returns undefined.

akmap.has(array)

Arguments:

• array: Array of values

Returns a Boolean: whether a previously set value exists for that key array.

akmap.get(array)

Arguments:

• array: Array of values

Returns the previously assigned value for this array, or undefined otherwise.

akmap.delete(array)

Arguments:

• array: Array of values

Deletes the value at this exact array. Does not affect other array, even if they are prefixes or extensions of this one. Remember to do this if you no longer need a array: the keys and values are not automatically garbage-collected, even if the objects used as keys go out of scope!

Returns undefined.

akmap.clear()

Deletes all entries from akmap.

Returns undefined.

akmap.hasPrefix(array)

Arguments:

• array: Array of values

Returns a Boolean: whether the map has some key starting with values matching the given array.

akmap.entries()

Returns an iterator that yields [key, value] for every entry in akmap.

⚠️ Note that these are in arbitrary order; not insertion order! This differs from the basic Map!

akmap.keys()

Returns an iterator that yields the key part (type Array) of each entry in akmap.

⚠️ Note that these are in arbitrary order; not insertion order! This differs from the basic Map!

akmap.values()

Returns an iterator that yields the value part of each entry in akmap.

⚠️ Note that these are in arbitrary order; not insertion order! This differs from the basic Map!

akmap.forEach(callback[, thisArg])

Arguments:

• callback: Function that will be called for each entry in akmap, passing the value, key, and map as arguments.
• (optional) thisArg: Object passed to the callback as the value for this.

Returns undefined.

⚠️ Note that these are in arbitrary order; not insertion order! This differs from the basic Map!

Performance characteristics

get, has, set, and delete are all O(n) with key array length n. I believe this is optimal; O(1) would require the JS runtime to expose the identity of all objects as hashable values, which is not currently possible.

Stores paths in a tree structure, to conserve memory when key arrays share a prefix. This means entries, keys, values, and forEach are O(n) with n total length of all keys of all entries, only counting shared key-array prefixes once.

clear is O(1).

FAQ

Why is this better than .join('/')ing the keys and using a regular object?

1. Because you might want your key array to contain objects (by identity) rather than strings. Objects are impossible to stringify in the general case (e.g. they may contain cyclic references), and even if you make some compromise, two distinct objects with identical contents would stringify to the same value and cause subtle bugs anyway.

2. Because even if you are only using Strings, your key array's elements might have /s in them. For example, with such a scheme, the arrays ['a/b'] and ['a', 'b'] would both resolve to the key a/b and overwrite each other.

   So use something other than a /? Sure, but then you have the same problem with elements possibly containing that.

   So use a sufficiently long probabilistically unguessable string like 03f2a8291a700b95904190583dba17c4ae1bf3bdfc2834391d60985ac6724940? That wastes RAM/disk when you have many long arrays. Also this is the code police speaking, you are under assert for crimes against humanity.

So please use this module instead of such hacks.

What version of JS does this rely on?

ES2015 I think—it uses Maps and Symbols (← caniuse links). At time of writing, it works in any recent Node.js or browser. Except IE, of course.

License

ISC.