Bag

A simple collection class to contain unique, keyed items.

Properties

count: Numberreadonly

The number of items in this Bag.

values: Object[]

The set of values of this Bag.

Setting this property replaces the data set.

Functions

add

Adds the passed item(s) to this Bag. Existing items with the same ID will be replaced.

Parameter	Type	Description
`toAdd`	Object \| Object[]	Item(s) to add.

Returns nth item in this Bag.

Parameter	Type	Description
`nth`	Number	The index of the matching item. Negative numbers index for the last item. For example, -1 returns the last item, -2 the 2nd to last item etc.

Returns: Object -

The matched item, or undefined.

changeId

Change the id of an existing member by mutating its idProperty.

Parameter	Type	Description
`item`	String \| Number \| Object	The item or id of the item to change.
`newId`	String \| Number	The id to set in the existing member.

countOf

Returns the number of items in this Bag which elicits a truthy return value from the passed function.

Parameter	Type	Description
`fn`	function	A function, which, when passed an item, returns `true` to select it as the item to return.

Returns: Number -

The number of matched items.

filter

Extracts the matching items from this Bag into an array based upon the passed value filter function.

Parameter	Type	Description
`fn`	function	A function, which, when passed an item, returns a `true` to place into the resulting array.
`thisObj`	Object	The `this` reference when the function is called.

Returns: Object[] -

An array of values extracted from this Bag.

find

Returns nth item in this Bag which elicits a truthy return value from the provided matcher function fn.

Parameter	Type	Description
`fn`	function	A function which, when passed an item, returns `true` to select the item as a match.
`nth`	Number	The index of the matching item. By default, 0 returns the first item that matches according to `fn`. Negative numbers index for the last item. For example, -1 returns the last matching item, -2 the 2nd to last matching item etc..

Returns: Object -

The matched item, or undefined.

forEach

Executes the passed function for each item in this Bag, passing in the item.

Parameter	Type	Description
`fn`	function	The function to execute.
`thisObj`	Object	The `this` reference when the function is called.

get

Returns the item with the passed id.

Parameter	Type	Description
`id`	*	The `id` to find.

Returns: Object -

The found item, or undefined.

includes

Returns true if this Collection includes an item with the same id as the passed item.

Parameter	Type	Description
`item`	Object \| String \| Number	The item to find, or an `id` to find.

Returns: Boolean -

True if the passed item is found.

map

Extracts the content of this Bag into an array based upon the passed value extraction function.

Parameter	Type	Description
`fn`	function	A function, which, when passed an item, returns a value to place into the resulting array.
`thisObj`	Object	The `this` reference when the function is called.

Returns: Object[] -

An array of values extracted from this Bag.

remove

Removes the passed item(s) from this Bag.

Parameter	Type	Description
`toRemove`	Object \| Object[]	Item(s) to remove.

sort

Sort the values of this Bag using the passed comparison function.

Setting this property replaces the data set.

Parameter	Type	Description
`fn`	function	Comparison function which returns -ve, 0, or +ve