Zedux v2 Roadmap

[bowheart]

Zedux v2 is on the horizon! Here's what we're planning on adding, deprecating, and removing plus some stuff we're still figuring out.

Planned Deprecations

• AtomInstance#getState - replaced with GraphNode#get (which AtomInstance inherits).
• AtomInstance#setState - replaced with AtomInstance#set (a thin wrapper around SignalInstance#set).
• AtomInstance#setStateDeep - replaced with AtomInstance#mutate(a thin wrapper around SignalInstance#mutate).
• The getInstance atom getter - replaced with getNode.
• The select atom getter - replaced with get.
• useAtomSelector - replaced with useAtomValue.
• injectAtomSelector - replaced with injectAtomValue or the get atom getter.
• AtomInstance#setStateDeep. This has problems with undefined in TS (see TypeScript: Store values should probably all infer as optional #95). The Store class will retain its setStateDeep method but changed to make undefined values a no op. Both AtomInstance and SignalInstance will instead have mutate methods that finally introduce immer-style proxies natively to Zedux and fix the undefined problem naturally since they won't deal with any RecursivePartial types.
• injectStore - replaced with injectSignal (this deprecation will almost definitely not be part of v2 initial release, but a minor version after).
• The Store class and all helpers associated with it - createStore, getMetaData, removeAllMeta, removeMeta, all store-specific zeduxTypes (see New Signal Primitive #115), actionFactory, createReducer, and all type helpers for stores, actions, reducers, and subscribers.
• All Atom*Type type utils - replaced with *Of (e.g. AtomStateType<myAtom> -> StateOf<myAtom>).
• The action property on evaluation reasons.

Planned Removals

• The Selectors class (see feat!: make instances valid graph nodes and jobs #114).
• The Graph class (see feat!: make instances valid graph nodes and jobs #114).
• The EvaluationStack class (see feat!: make instances valid graph nodes and jobs #114).
• The AtomInstanceBase class (see feat!: make instances valid graph nodes and jobs #114).
• The SelectorCache class (see feat!: make instances valid graph nodes and jobs #114) - replaced with SelectorInstance.
• AtomInstance#addDependent and Selectors#addDependent are replaced with GraphNode#on (see feat!: make instances valid graph nodes and jobs #114).
• The IdGenerator class - replaced with methods on Ecosystem.
• The ZeduxPlugin class and its actions - plugins are being completely reworked (see below).
• internalStore and getEcosystem - Zedux will no longer store ecosystems in its module-level state. This keeps it pure(r) and prevents GC surprises - if an ecosystem with no callbacks registered with the JS runtime goes completely out of scope, it and all its atoms should be able to be cleaned up.
• The sourceType property on evaluation reasons.
• Ecosystem#registerPlugin - replaced with Ecosystem#on.
• Ecosystem#unregisterPlugin - replaced with calling the cleanup function returned from Ecosystem#on.
• injectInvalidate. This is already deprecated, replaced by injectSelf().invalidate. V2 removes it.
• manualHydration atom config option - Zedux will instead auto-detect any usages of the hydrate option in injectSignal.
• The AtomSelectorOrConfig type - replaced with SelectorTemplate.
• The AtomTemplateBase class - renamed to NodeTemplate. ._createInstance renamed to .new and .getInstanceId renamed to .hash.
• The flags atom config option - renamed to tags. This will affect the options passed to Ecosystem#dehydrate (and now Ecosystem#findAll) - excludeFlags renamed to excludeTags and includeFlags renamed to includeTags.
• The store property returned from getInternals - no direct replacement. Ecosystems will no longer be stored internally in Zedux module-level state. The @@global ecosystem will be returned from createEcosystem({ id: '@@global' })
• getEcosystem - removed with no replacement. For multi-window setups that leverage getInternals/setInternals, share your ecosystem reference across windows yourself rather than using getEcosystem('my-id') after calling setInternals in the child window. This should be about the same amount of code with less magic.
• wipe (the top-level exported function) - removed with no replacement. There's no internal store to clear.
• The hierarchy config from stores (see feat(core)!: remove hierarchy config #94)
• The synchronous option of injectEffect. All effects will now run as soon as the atom's state factory returns. This solves the problem that synchronous was trying to solve - where manual subscriptions aren't registered before the atom can be used - and also solves the problems with synchronous itself - where its atom getter calls register graph edges.
• Ecosystem#_incrementRefCount, Ecosystem#_decrementRefCount, Ecosystem#_refCount, and the destroyOnUnmount ecosystem config option. EcosystemProvider will destroy on unmount instead. And custom ecosystems should handle ecosystem destruction manually (or just not, that's fine for most apps).
• Ecosystem#wipe. This is just being hidden. It's always been recommended to use Ecosystem#reset or Ecosystem#destroy instead. Now we won't have to recommend it.
• Ecosystem#atomDefaults. This is unnecessary bloat. Users can create atom factories themselves for defining standardized atom types. That gives full flexibility, is already documented, and has no real disadvantages to this ecosystem config option.

Planned Features

• The new Signal primitive (see New Signal Primitive #115)
• New plugin system (see New Plugin System #119)
• api.set to set all properties of an AtomAPI at once.
• Remove the string key requirement of atom. Keys will be auto-generated if not provided (but it's strongly recommended to pass one or use a build tool plugin to generate them for you).
• Events (see New Signal Primitive #115). In addition to the signal built-in events, atoms will have .on('invalidate', cb). If we remove lifecycles from signals, atoms will also have .on('cycle', cb). Ecosystems will also have "plugin events" (see New Plugin System #119)
• optimize option for Ecosystem#batch that will disable evaluation reason tracking for all updates resulting from any calls in the .batch callback.
• Automatic dependency tracking for injectEffect, injectPromise, injectCallback, and injectMemo - omit the deps array and Zedux will make the callback a reactive context similar to signals libs.
• Improved parameters to Ecosystem#findAll. Besides those already in feat!: make instances valid graph nodes and jobs #114, a .findAll(callback) overload for full control. That overload will apply to Ecosystem#dehydrate as well.

Stuff We're Still Figuring Out

• Will phase 2 of the graph perf improvements be part of Zedux v2 or pushed back to v3?
• Is the lifecycle status property of graph nodes used enough to merit it getting a status getter on top of the obfuscated single-letter lifecycleStatus property added by feat!: make instances valid graph nodes and jobs #114? We've never used it TMK for any purpose, but it's featured prominently in the docs. Maybe it just shouldn't be? We will add a status getter because we're further obfuscating lifecycleStatus by making its value a number. The status getter will translate the number to a user-friendly string.
• Should we cut a v2 of the docs and leave v1 alone? Or should we update the existing doc pages.
• Can the new signal primitive be made so it can use the TC39 proposal internally when (if) it's finalized?
• The new type (introduced in feat!: make instances valid graph nodes and jobs #114) for arguments passed to ecosystem.dehydrate and ecosystem.findAll doesn't have a way to specify that only a certain type of node should be returned - atoms or selectors (or signals soon) or a custom node type. What would this argument look like?
• Instead of the new ecosystem.live atom getters, should we make the ecosystem's own atom getters reactive by default? We would then add getOnce and getNodeOnce methods which would have the current behavior of get and getNode respectively. This would get rid of the concept of atom getters and make the ecosystem all you need to know. It would also be able to have parity with signals - signal.get and signal.getOnce. It would also replace injectAtomGetters with injectEcosystem for better parity with Zedux's hooks.
• The timeline! When will Zedux v2 be available?