Selectors
The Selectors class manages all selector-related tasks for the ecosystem.
Since atom selectors are meant to feel lightweight, they don't have to be instances of a class - they'll often be standalone or even inline functions. This class handles all the logic that atom selectors would handle themselves if they were classes - instantiation, cache management, and destruction.
On top of that, it provides methods for pre-caching selectors and finding selector caches.
Every ecosystem creates a single Selectors instance - ecosystem.selectors.
Methods
Manually adds a graph edge between an atom selector and a new external "pseudo" graph node.
Signature:
addDependent = (cacheItem, config?) => cleanup
Required. A SelectorCache instance.
This is the dependency you're adding a dependent to.
Optional. An object containing the following optional properties:
{ callback, operation }
A DependentCallback function.
A string. Can be anything. This can be useful when debugging your selector graph. It essentially labels the edge, showing what operation caused the graph edge to be added.
Gets a snapshot of current cache item values.
Signature:
dehydrate = (selectableOrName?) => cacheItems
Optional. One of:
- A string
- An atom selector
- An AtomSelectorConfig object
- A SelectorCache instance (accepted for consistency, but really you'd never pass this)
If passed, filters the returned object to only contain cache values of the passed selector or caches whose key includes the passed string (case-insensitive).
Destroys a cached atom selector. Similar to instance.destroy().
Like instance.destroy(), destruction bails out by default if the selector node has dependents. Pass true as the 3rd parameter to force destruction anyway, triggering dependents to recreate the cache.
Signature:
destroyCache = (selectable, args?, force?) => void
Required. An atom selector, AtomSelectorConfig object, or SelectorCache instance.
Similar to selectors.getCache(), returns a SelectorCache instance for the given selector + args combo. However, unlike .getCache(), .find() does not run the selector or cache the result if it hasn't been cached already - it simply returns undefined.
Signature is almost the same as .getCache(), except that .find() also accepts a fuzzy search string which, when passed, returns the first found SelectorCache whose id includes the passed string (case-insensitive).
Gets a snapshot of current cache items. The selector equivalent of ecosystem.findAll().
Signature:
findAll = (selectableOrName?) => cacheItems
Optional. One of:
- A string
- An atom selector
- An AtomSelectorConfig object
- A SelectorCache instance (accepted for consistency with similar methods, but really you'd never pass this)
If passed, filters the returned object to only contain caches of the passed selector or caches whose key includes the passed string (case-insensitive).
Returns a SelectorCache instance for the given selector + args combo. If the selector + args combo has never been cached before, .getCache() runs the selector and caches the result before returning the cache item.
Contrast this to ecosystem.select() which does not cache the result. That means selectors.getCache() is the selector equivalent of ecosystem.getInstance().
Signature:
getCache = (selectable, args?) => cacheItem
Required. An atom selector, AtomSelectorConfig object, or SelectorCache instance.
.getCache() has no special functionality if a SelectorCache instance is passed - it simply returns the passed cache item.
Returns the fully qualified id string that this Selectors class instance will use for the given selector + args combo.
Signature:
getCacheId = (selectable, args?, weak?) => id
Required. An atom selector, AtomSelectorConfig object, or SelectorCache instance.
.getCacheId() creates and stores an id for the given selector + args combo if none exists yet. Pass true to disable this.A string prefixed with @@selector- containing a set, derived, or generated name for the passed selector and a deterministic hash of all the passed args. If true was passed for the 3rd "weak" arg, returns undefined if no id has been stored for given selector + args combo yet.