feat!: implement untrack and rework injectors (#170)

@affects atoms, react, stores

packages/atoms/README.md

@@ -76,7 +76,6 @@ On top of this, `@zedux/atoms` exports the following APIs and many helper types
 - [`injectCallback()`](https://omnistac.github.io/zedux/docs/api/injectors/injectCallback)
 - [`injectEcosystem()`](https://omnistac.github.io/zedux/docs/api/injectors/injectEcosystem)
 - [`injectEffect()`](https://omnistac.github.io/zedux/docs/api/injectors/injectEffect)
-- [`injectInvalidate()`](https://omnistac.github.io/zedux/docs/api/injectors/injectInvalidate)
 - [`injectMappedSignal()`](https://omnistac.github.io/zedux/docs/api/injectors/injectMappedSignal)
 - [`injectMemo()`](https://omnistac.github.io/zedux/docs/api/injectors/injectMemo)
 - [`injectPromise()`](https://omnistac.github.io/zedux/docs/api/injectors/injectPromise)
@@ -90,6 +89,7 @@ On top of this, `@zedux/atoms` exports the following APIs and many helper types
 - [`getEcosystem()`](https://omnistac.github.io/zedux/docs/api/utils/internal-utils#getecosystem)
 - [`getInternals()`](https://omnistac.github.io/zedux/docs/api/utils/internal-utils#getinternals)
 - [`setInternals()`](https://omnistac.github.io/zedux/docs/api/utils/internal-utils#setinternals)
+- [`untrack()`](https://omnistac.github.io/zedux/docs/api/utils/internal-utils#untrack)
 - [`wipe()`](https://omnistac.github.io/zedux/docs/api/utils/internal-utils#wipe)
 
 ## For Authors

packages/atoms/src/classes/instances/AtomInstance.ts

@@ -9,7 +9,6 @@ import {
   AtomGenericsToAtomApiGenerics,
   Cleanup,
   ExportsInfusedSetter,
-  LifecycleStatus,
   PromiseState,
   PromiseStatus,
   DehydrationFilter,
@@ -33,7 +32,6 @@ import {
   getInitialPromiseState,
   getSuccessPromiseState,
 } from '@zedux/atoms/utils/promiseUtils'
-import { InjectorDescriptor } from '@zedux/atoms/utils/types'
 import { Ecosystem } from '../Ecosystem'
 import { AtomApi } from '../AtomApi'
 import { AtomTemplateBase } from '../templates/AtomTemplateBase'
@@ -60,6 +58,33 @@ import {
   sendImplicitEcosystemEvent,
 } from '@zedux/atoms/utils/events'
 
+export type InjectorDescriptor<T = any> = {
+  /**
+   * `c`leanup - tracks cleanup functions, e.g. those returned from
+   * `injectEffect` callbacks.
+   */
+  c: (() => void) | undefined
+
+  /**
+   * `i`nit - a callback that we need to call immediately after evaluation. This
+   * is how `injectEffect` works (without `synchronous: true`).
+   */
+  i: (() => void) | undefined
+
+  /**
+   * `t`ype - a unique injector name string. This is how we ensure the user
+   * didn't add, remove, or reorder injector calls in the state factory.
+   */
+  t: string
+
+  /**
+   * `v`alue - can be anything. For `injectRef`, this is the ref object. For
+   * `injectMemo` and `injectEffect`, this keeps track of the memoized value
+   * and/or dependency arrays.
+   */
+  v: T
+}
+
 /**
  * A standard atom's value can be one of:
  *
@@ -178,11 +203,6 @@ export class AtomInstance<
 > extends Signal<G> {
   public static $$typeof = Symbol.for(`${prefix}/AtomInstance`)
 
-  /**
-   * @see Signal.l
-   */
-  public l: LifecycleStatus = 'Initializing'
-
   public api?: AtomApi<AtomGenericsToAtomApiGenerics<G>>
 
   // @ts-expect-error this is set in `this.i`nit, right after instantiation, so
@@ -198,20 +218,30 @@ export class AtomInstance<
    */
   public a: boolean | undefined = undefined
 
+  /**
+   * @see Signal.c
+   */
+  public c?: Cleanup
+
+  /**
+   * `I`njectors - tracks injector calls from the last time the state factory
+   * ran. Initialized on-demand
+   */
+  public I: InjectorDescriptor[] | undefined = undefined
+
+  /**
+   * `N`extInjectors - tracks injector calls as they're made during evaluation
+   */
+  public N: InjectorDescriptor[] | undefined = undefined
+
   /**
    * `S`ignal - the signal returned from this atom's state factory. If this is
    * undefined, no signal was returned, and this atom itself becomes the signal.
    * If this is defined, this atom becomes a thin wrapper around this signal.
    */
   public S?: Signal<G>
 
-  /**
-   * @see Signal.c
-   */
-  public c?: Cleanup
-  public _injectors?: InjectorDescriptor[]
   public _isEvaluating?: boolean
-  public _nextInjectors?: InjectorDescriptor[]
   public _promiseError?: Error
   public _promiseStatus?: PromiseStatus
 
@@ -242,20 +272,11 @@ export class AtomInstance<
   public destroy(force?: boolean) {
     if (!destroyNodeStart(this, force)) return
 
-    // Clean up effect injectors first, then everything else
-    const nonEffectInjectors: InjectorDescriptor[] = []
-
-    this._injectors?.forEach(injector => {
-      if (injector.type !== '@@zedux/effect') {
-        nonEffectInjectors.push(injector)
-        return
+    if (this.I) {
+      for (const injector of this.I) {
+        injector.c?.()
       }
-      injector.cleanup?.()
-    })
-
-    nonEffectInjectors.forEach(injector => {
-      injector.cleanup?.()
-    })
+    }
 
     destroyNodeFinish(this)
   }
@@ -386,7 +407,6 @@ export class AtomInstance<
       return
     }
 
-    this._nextInjectors = []
     this._isEvaluating = true
     const prevNode = startBuffer(this)
 
@@ -434,10 +454,13 @@ export class AtomInstance<
         }
       }
     } catch (err) {
-      this._nextInjectors.forEach(injector => {
-        injector.cleanup?.()
-      })
+      if (this.N) {
+        for (const injector of this.N) {
+          injector.c?.()
+        }
+      }
 
+      this.N = undefined
       destroyBuffer(prevNode)
 
       throw err
@@ -456,7 +479,17 @@ export class AtomInstance<
       this.w = []
     }
 
-    this._injectors = this._nextInjectors
+    // kick off side effects and store the new injectors
+    if (this.N) {
+      if (!this.e.ssr) {
+        for (const injector of this.N) {
+          injector.i?.()
+        }
+      }
+
+      this.I = this.N
+      this.N = undefined
+    }
 
     // let this.i flush updates after status is set to Active
     this.l === 'Initializing' || flushBuffer(prevNode)

packages/atoms/src/index.ts

@@ -1,4 +1,3 @@
-import { createInjector } from './factories/createInjector'
 import {
   destroyBuffer,
   flushBuffer,
@@ -18,12 +17,12 @@ export * from './factories/index'
 export * from './injectors/index'
 export { getEcosystem, getInternals, setInternals, wipe } from './store/index'
 export * from './types/index'
+export { untrack } from './utils/evaluationContext'
 
 // These are very obfuscated on purpose. Don't use! They're for Zedux packages.
 export const zi = {
   a: scheduleStaticDependents,
   b: destroyNodeStart,
-  c: createInjector,
   d: destroyBuffer,
   e: destroyNodeFinish,
   i: sendImplicitEcosystemEvent,

packages/atoms/src/injectors/index.ts

@@ -6,7 +6,6 @@ export * from './injectAtomValue'
 export * from './injectCallback'
 export * from './injectEcosystem'
 export * from './injectEffect'
-export * from './injectInvalidate'
 export * from './injectMappedSignal'
 export * from './injectMemo'
 export * from './injectPromise'

packages/atoms/src/injectors/injectAtomGetters.ts

@@ -1,5 +1,4 @@
-import type { Ecosystem } from '../classes/Ecosystem'
-import { readInstance } from '../utils/evaluationContext'
+import { injectEcosystem } from './injectEcosystem'
 
 /**
  * injectAtomGetters
@@ -31,4 +30,4 @@ import { readInstance } from '../utils/evaluationContext'
  *
  * @see Ecosystem
  */
-export const injectAtomGetters = (): Ecosystem => readInstance().e
+export const injectAtomGetters = injectEcosystem

packages/atoms/src/injectors/injectAtomInstance.ts

@@ -8,7 +8,7 @@ import {
   ParamsOf,
   Selectable,
 } from '../types/index'
-import { readInstance } from '../utils/evaluationContext'
+import { injectSelf } from './injectSelf'
 
 const defaultOperation = 'injectAtomInstance'
 
@@ -65,7 +65,7 @@ export const injectAtomInstance: {
   params?: ParamsOf<A>,
   config?: InjectAtomInstanceConfig
 ) =>
-  readInstance().e.getNode(template, params, {
+  injectSelf().e.getNode(template, params, {
     f: config?.subscribe ? Eventless : EventlessStatic,
     op: config?.operation || defaultOperation,
   })

packages/atoms/src/injectors/injectAtomSelector.ts

@@ -1,15 +1,15 @@
 import { ParamsOf, Selectable, StateOf } from '../types/index'
-import { readInstance } from '../utils/evaluationContext'
+import { injectSelf } from './injectSelf'
 
 /**
+ * @deprecated use `injectAtomValue` instead
+ *
  * ```ts
  * injectAtomSelector(mySelector, arg1, arg2) // before
  * injectAtomValue(mySelector, [arg1, arg2]) // after
  * ```
- *
- * @deprecated use `injectAtomValue` instead
  */
 export const injectAtomSelector = <S extends Selectable>(
   selectable: S,
   ...args: ParamsOf<S>
-): StateOf<S> => readInstance().e.get(selectable, args)
+): StateOf<S> => injectSelf().e.get(selectable, args)

packages/atoms/src/injectors/injectEcosystem.ts

@@ -1,5 +1,5 @@
 import type { Ecosystem } from '../classes/Ecosystem'
-import { readInstance } from '../utils/evaluationContext'
+import { injectSelf } from './injectSelf'
 
 /**
  * injectEcosystem
@@ -29,4 +29,4 @@ import { readInstance } from '../utils/evaluationContext'
  *
  * @see Ecosystem
  */
-export const injectEcosystem = (): Ecosystem => readInstance().e
+export const injectEcosystem = (): Ecosystem => injectSelf().e