@wonderlandlabs/collect

The Great Equalizer

@wonderlandlabs/collect is a unified interface into all of JavaScripts' base compound classes: Sets, Maps, Objects, Arrays and even Strings.

It allows you full interfaces into collections, their keys, and their items, as well as modification methods formerly exclusive to Arrays.

When a method doesn't have an explicit return value (eg get(key), first()), it returns the collection itself, for currying.

See "Getting Started" for examples of creation/usage of collections

See "Why Collect Exists" for a longer explanation of the purpose and impetus of Collect.

Reflection

• form string
• type string
• size int
• value raw
• hasKey(key)
• hasItem(item) bool
• first(count?): item[]
• last(count?) item[]
• firstItem item?
• lastItem item?

Access

• get(key): item
• set(key, value)
• deleteKey(key or keys)
• deleteItem(item or items)
• keyOf(item): key?
• keys: keys[]
• values: items[]

Loopers

• forEach(action)
• reduce(action) any
• map(action)

Iterators

• storeIter iterator
• itemIter iterator
• keyIter iterator

Append

• addBefore(item, key?)
• addAfter(item, key?)
• removeFirst(count?)
• removeLast(count?)

Utility

• clone(deep?)
• cloneEmpty()
• cloneShallow()
• clear()
• sort(ordFn)
• change(newStore)

Highlights

• custom comparators: store and look up keys with matching functions you can inject yourself
• set operations: merge in contents of any collections into the store type of your choice, or pick values based on value or key set.
• Robust: no caching -- only a single value is stored in each wrapper
• Broad: allows consistent access for Arrays, Maps, Objects, strings and Sets
• Very little external dependency: lodash.cloneDeep and lodash.toString are used; otherwise, this library uses 100% pure Javascript
• Cross-target appends: Adds push/pop/shift/unshift analogs (Appenders) to all classes

Most fundamentally: Collect is CONSISTENT. Every version has complete iterators, you can search by key AND by item, and full loopers for every type of content. As Javascript evolves, minor features just don't seem to get applied across all compound types

1.0 release

The 1.0 release is a complete rebuild of collect. the interface is meant to be almost completely identical to the pre-1.0 release. here are a few notable changes:

1. the core value is stored in the .value property instead of in store.
2. **the value formerly called items is now referred to as values.
3. **the technique to stop iterator functions(reduce, map, forEach) is different. (TLDR: throw {$STOP: true})
4. cloneShallow() has been replaced with .clone(true).

Under the hood

Previously, multiple classes were created for each possible type of inner value. This precludes changing the type of value stored (via change) from, say, an array to a Set. It also vastly complicated the TypeScript.

Instead, in 1.0, we dynamically choose a handler based on the form of the content on the fly.

Also, the type detection system has been moved to @wonderlandlabs/walrus, an independent module.