.change(replacer | (store) => storeType | void): Collection (self)

Change modifies the store value in one of two ways:

  1. if a function is passed, a clone of the store is the input. you can

    • modify the store and not return any value,
    • return a new value,
    • modify and return the clone.

  2. any other type of value is used to replace the store.

(this is patterned after Immer's produce method)

Its best practice not to directly modify the collections' store; change provides a method of injecting a new value over the old one in the collection.

.change will fail if the injected/returned value is not the same form as the collections' original value. If you have circumstances where you want to use a different type in a circumstance, use create(newValue) rather than trying to modify an existing collection. Each collection instance is fine-tuned to manage a specific form of store, and cannot process a store of any other type.

.clone(options?: {quiet: boolean, compKeys, compItems}): Collection

returns a new collection with a copy of the store. Cloning the collection also clones the collection store using lodash.cloneDeep(). This breaks all references in the store and its contents recursively.

.cloneShallow(options?): Collection

This returns a new collection with a new store -- however it doesn't clone the items of the collection. For instance, if you .cloneShallow a collection that has a store of an array of {username: string, id: int} objects, the new collection will have a new array -- but the contents of the array will be the same as that of the source collection.

If, for instance you want to create an array of the usernames, both of theses methods will work:

const users = create(
  [
  {username: 'bob', id: 1},
  {username: 'jeff', id: 2},
  {username: 'stan', id: 3}
]
);
// method 1
const userNames = users.clone().map((u) => u.username);
// method2
const alsoUserNames = users.cloneShallow().map((u) => u.username);

however the first method will needlessly duplicate each object in the array -- since your map operation doesn't change the original object, there is no reason to replicate the object prior to extracting the username.

.cloneEmpty(options?: {quiet: boolean, compKeys, compItems}): Collection

returns a new collection with an "empty" item in it: i.e., cloneEmpty() any collection containing an Object returns an ObjectCollection containing {}; cloneEmpty() any Map collection returns a MapCollection containing an empty Map() instance. Useful if you want to create a new collection with a few sparse members/derivatives of the original.

💡

The options allow you to update the configurations which are also cloned from the target collection. In normal use you should not have to worry about this. Any configuration you don't provide a key for will inherit from the target collection.

set(key, item) : self

Sets the value at the given key. Returns the target collection.

deleteKey(key | key[]) : self

removes one (or more) items, by key. Accepts an array of keys, or a single item. Returns the target collection.

deleteItem(item | items[]) : self

removes one (or more) items -- by identity. Accepts an array of items, or a single item. Returns the target collection.

💡

Note on Map types: Maps accept literally anything as keys or values -- including arrays. Because the delete functions interpret arrays as lists of input if you want to delete an item that is an array or is keyed by an array, you need to wrap that key/item in another array. note, by default, referential identity is used to compare arrays.

clear() : self

clears all the items. Returns the target collection.

sort(sortFn? comparatorFn): self

Sorts the items; the sort function uses the technique described in Array.sort. The comparator function is optional; scalar data is sorted alphanumerically. Returns the target collection.