@psenger/multivalue-map v1.1.2

Multi Value Map

ES6 Multi Value Map for NodeJS

A Multi Value Map is a decorated map, allowing it to have more than one value for a key. Additionally, it has slightly different semantics. Putting a value into the map will add the value to a Array. Getting a value will return an Array, holding all the values put into that key.

API

Collection

Abstract class Collection must be implemented to be passed as the option.valueType in the MultiValueMap class constructor. This abstract class defines the behavior of the values stored in the MultiValueMap. When constructed, the creator parameter, a JavaScript Class, will be called with the new operator and stored in a private variable, a reference variable, called this._proxyObject

Parameters

• creator Class the class to construct internally

setValue

Setting the value hides the implementation and off loads the behavior to the Proxy Object.Each backing proxy has different behaviors.

Parameters

• value any Passing the value as Null or Undefined are ignored.

getValue

Get the values from the Proxy Object, as a shallow copy array.

Returns Array\ All sub classes return a shallow copy array of the values

iterator

Iterator

ArrayCollection

Extends Collection

An Array Collection, is just that, an array. This means there can be duplicated values.

setValue

Extends Collection

Push a new value into the proxy array object.

Parameters

• value any if you push null or undefined, it is ignored.

getValue

Extends Collection

Gets a shallow copied array of the array of objects.

Returns Array\ an array of objects.

SetCollection

Extends Collection

A Set collection enforces uniqueness IFF the values are primitives ( sorry this is JavaScript not Java ).

setValue

Extends Collection

Add a new Value to the Set.

Parameters

• value any if you push null or undefined, it is ignored.

getValue

Extends Collection

Get an Array ( a shallow copy ) of the values of the Set.

Returns Array\ All sub classes return an array of the values

MultiValuedMapOption

A MultiValuedMap constructor option

Type: Object

Properties

• valueType Collection Indicates the value class and implements the Collection

MultiValuedMap

• See: wikipedia for further information on Advanced Data Types
• See: wikipedia for further information on MultiMap

MultiValuedMap is an ADT ( Advanced Data Type ) and based on Apache Commons Collections. While a Map or Dictionary's keys are associated with a single values, each MultiValueMap's key has multiple values. The cardinality of the values stored can be composed with the property option.valueType or building a class that extends the abstract class Collection. The default option.valueType is an ArrayCollection.

Type: MultiValuedMap

Parameters

• iterable Iterable? An Array or other iterable object whose elements are key-value pairs (arrays with two elements, e.g. [[ 1, ['one','two'] ],[ 2, ['three'] ]]). Each key-value pair is added to the new Map; null values are treated as undefined.

• options MultiValuedMapOption An option object literal. (optional, default {})

  • options.valueType Collection A decorator, that can be called to supply a value for the collection of values. Optional and defaults to Array (optional, default {ArrayCollection})

Examples

const ar = [['a',[1,2,2]],['b',[1,1]]];
const a = new MultiValueMap();
const a = new MultiValueMap( ar );
const a = new MultiValueMap( ar, { valueType: ArrayCollection });
const b = new MultiValueMap( ar, { valueType: SetCollection });
const b = new MultiValueMap( null, { valueType: SetCollection });

Meta

• version: 1.1.1

set

Sets the value for the key in the Map object. Returns the Map object reference for chaining.

Parameters

• key any the key
• value any the value

Examples

const mvm = new MultiValueMap(preData,{ valueType: SetCollection })
mvm.set('D', 'E')

Returns MultiValuedMap

setAll

Set All values.

Parameters

• key any the key
• values Iterable values to feed. (optional, default [])

Examples

const mvm = new MultiValueMap(preData,{ valueType: SetCollection })
mvm.setAll('F',['G','H','H','H'])

Returns MultiValuedMap

size

Returns the number of key/value pairs in the MultiValueMap object.

Examples

const mvm = new MultiValueMap(preData,{ valueType: SetCollection })
mvm.set('D', 'E')
mvm.set('D', 'E')
mvm.set('D', 'E')
mvm.setAll('F',['G','H','H','H'])
console.log('mvm.size=', mvm.size); // mvm.size= 3

Returns number

has

Returns a boolean asserting whether a value has been associated to the key in the MultiValueMap object or not.

Parameters

• key any the key

Examples

if ( ! mvm.has('non existing') ) {
  console.log('not here');
}
if ( mvm.has('D') ) {
  console.log('here');
}

Returns boolean indicates a value exists in the MultiValueMap

delete

Returns true if an element in the MultiValueMap object existed and has been removed, or false if the element does not exist. It will return false afterwards.

Parameters

• key any the key

Examples

if ( ! mvm.delete('A') ) {
  console.log('A was not deleted');
}

Returns boolean true indicates the value was found and deleted

clear

Removes all key/value pairs from the Multi Value Map object.

Examples

mvm.clear()

keys

Returns a new Iterator object that contains an array of [key, [value]] for each element in the Map object in insertion order.

Returns IterableIterator\

values

Return all the values in the Map.

Returns IterableIterator\ An iterable value, composed of what ever values or value was inserted into the map.

entries

The entries in the map, key value pair.

Examples

const data = [
   [ 'a', ['1','2','3'] ],
   [ 'b', ['4'] ],
   [ 'c', ['5','6'] ]
]
const mvn = new MultiValueMap(data);
for (let [key, values] of mvn.entries()) {
  console.log(key, values.getValue());
}
// a [ '1', '2', '3' ]
// b [ '4' ]
// c [ '5', '6' ]

Returns IterableIterator<[any, IterableIterator\]>

get

get the values associated with the key.

Parameters

• key any The key

Examples

const mvm = new MultiValueMap([iterable])
mvm.set('Captain Marvel', 'Carol Danvers')
const value = mvm.get('Captain Marvel')
console.log( value ) // ['Carol Danvers']

Returns (any | null)

Example Usage

const preData = [['A',['B','B','C']]]
const mvm = new MultiValueMap(preData,{ valueType: SetCollection })
mvm.set('D', 'E')
mvm.set('D', 'E')
const value = mvm.get('A')
console.log( value ) // [ 'B', 'C' ]
for (let [key, values] of mvm.entries()) {
  console.log(key, values.getValue());
}
// A [ 'B', 'C' ]
// D [ 'E' ]

Installation Instructions

npm install @psenger/multivalue-map --save

or

yarn add @psenger/multivalue-map

License

MIT License

Copyright (c) 2021 Philip A Senger

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.

Deployment Steps

• create a pull request from dev to main
• check out main
• npm version patch -m "message here" or minor
• npm publish --access public
• Then switch to dev branch
• Then merge main into dev and push dev to origin