Return a singleton instance for the given factory
Every call to $() with a given factory will return the same result. (Until
a new root job is started, or the result is overridden using
$cache.set, $cache.unset or $cache.replace.) On
first use, the factory is called (or constructed, if it's a class) and the
result (if not an error) is cached for future calls.
The SingletonFactory function or class whose shared/cached value you want to get. (See SingletonFactory for important details on how the factory is run and the restrictions on what it can do.)
ExperimentalCreate a per-signal lazy constant, via $``()
When you call $``(factory) inside a given signal function for the first
time, the ConstantFactory will be called (or constructed, if it's a
class) and the returned result will be cached for ALL future calls at the
same code location in that specific signal. An error results if called
outside a signal function. See the ConstantFactory docs for more
details on how the factory is called, and the restrictions on what it can do.
Lazy constants are somewhat similar in concept to a React useMemo(), but
also very different. React requires hooks to always be invoked in the same
order to match them up with their targets, but lazy constants do not need
this: they're tied to the line of code where they're called, and you can
branch, loop, skip, or call them out of order with no consequence. (They'll
just always return the same value each time if running in the same signal -
even in a loop or called in another function with different arguments, and
they don't support dependencies because you can use signals instead.)
(Also unlike React hooks, they can also be used in nested functions, as long as those functions are only invoked from within a relevant signal. Conversely, because they're keyed to a specific code location, you can't just call a wrapping function more than once in a signal, and expect to get different results: a lazy constant is a per-signal constant, not a React hook!)
Return a singleton instance for the given factory, or create a per-signal lazy constant (a bit like React's
useMemo, but without the deps or ordering constraints).$(factory)SingletonFactory<T> => T$``(factory)ConstantFactory<T> => TLazy-Initialized Singletons
In complex programs and frameworks, it's often beneficial to both 1) have a single access point for some functionality, and 2) not to need a specific point where that access is explicitly initialized. The
$()function lets you unobtrusively request a singleton instance to be instantiated on demand, then shared with all other access points in the program, and it does so without requiring any change to the target class or classes. (You can even override the target instance or replace its factory, as one might with a dependency-injection container.)Lazy Constants in Signal Functions
Within signal functions, there's often a need to have some state that carries across multiple calls to the function. (Like what other languages do with function-static variables.)
You can do something like this with a closure, of course, but it often increases code complexity, especially when writing signal functions. So the lazy-constant operator (
$``()) lets you write expressions likeconst myMap = $``(WeakMap<...>)instead of needing to initialize (or at least define)myMapoutside the signal function body.