Initial OSS commit

packages/dataverse2/src/derivations/AbstractDerivation.ts

@@ -0,0 +1,199 @@
+import type {$IntentionalAny} from '../types'
+import type Tappable from '../utils/Tappable'
+import DerivationEmitter from './DerivationEmitter'
+import flatMap from './flatMap'
+import type {GraphNode, IDerivation} from './IDerivation'
+import map from './map'
+import {
+  reportResolutionEnd,
+  reportResolutionStart,
+} from './prism/discoveryMechanism'
+
+export default abstract class AbstractDerivation<V> implements IDerivation<V> {
+  readonly isDerivation: true = true
+  private _didMarkDependentsAsStale: boolean = false
+  private _isHot: boolean = false
+
+  private _isFresh: boolean = false
+  protected _lastValue: undefined | V = undefined
+
+  protected _dependents: Set<GraphNode> = new Set()
+  protected _dependencies: Set<IDerivation<$IntentionalAny>> = new Set()
+  /**
+   * _height is the maximum height of all dependents, plus one.
+   *
+   * -1 means it's not yet calculated
+   * 0 is reserved only for listeners
+   */
+  private _height: number = -1
+
+  private _graphNode: GraphNode
+
+  protected abstract _recalculate(): V
+  protected abstract _reactToDependencyBecomingStale(
+    which: IDerivation<unknown>,
+  ): void
+
+  constructor() {
+    const self = this
+    this._graphNode = {
+      get height() {
+        return self._height
+      },
+      recalculate() {
+        // @todo
+      },
+    }
+  }
+
+  get isHot(): boolean {
+    return this._isHot
+  }
+
+  get height() {
+    return this._height
+  }
+
+  protected _addDependency(d: IDerivation<$IntentionalAny>) {
+    if (this._dependencies.has(d)) return
+    this._dependencies.add(d)
+    if (this._isHot) d.addDependent(this._graphNode)
+  }
+
+  protected _removeDependency(d: IDerivation<$IntentionalAny>) {
+    if (!this._dependencies.has(d)) return
+    this._dependencies.delete(d)
+    if (this._isHot) d.removeDependent(this._graphNode)
+  }
+
+  changes(): Tappable<V> {
+    return new DerivationEmitter(this).tappable()
+  }
+
+  addDependent(d: GraphNode) {
+    const hadDepsBefore = this._dependents.size > 0
+    this._dependents.add(d)
+
+    if (d.height > this._height - 1) {
+      this._setHeight(d.height + 1)
+    }
+
+    if (!hadDepsBefore) {
+      this._reactToNumberOfDependentsChange()
+    }
+  }
+
+  /**
+   * @sealed
+   */
+  removeDependent(d: GraphNode) {
+    const hadDepsBefore = this._dependents.size > 0
+    this._dependents.delete(d)
+    const hasDepsNow = this._dependents.size > 0
+    if (hadDepsBefore !== hasDepsNow) {
+      this._reactToNumberOfDependentsChange()
+    }
+  }
+
+  reportDependentHeightChange(d: GraphNode) {
+    if (process.env.NODE_ENV === 'development') {
+      if (!this._dependents.has(d)) {
+        throw new Error(
+          `Got a reportDependentHeightChange from a non-dependent.`,
+        )
+      }
+    }
+    this._recalculateHeight()
+  }
+
+  private _recalculateHeight() {
+    let maxHeightOfDependents = -1
+    this._dependents.forEach((d) => {
+      maxHeightOfDependents = Math.max(maxHeightOfDependents, d.height)
+    })
+    const newHeight = maxHeightOfDependents + 1
+    if (this._height !== newHeight) {
+      this._setHeight(newHeight)
+    }
+  }
+
+  private _setHeight(h: number) {
+    this._height = h
+    this._dependencies.forEach((d) => {
+      d.reportDependentHeightChange(this._graphNode)
+    })
+  }
+
+  /**
+   * This is meant to be called by subclasses
+   *
+   * @sealed
+   */
+  protected _markAsStale(which: IDerivation<$IntentionalAny>) {
+    this._internal_markAsStale(which)
+  }
+
+  private _internal_markAsStale = (which: IDerivation<$IntentionalAny>) => {
+    this._reactToDependencyBecomingStale(which)
+
+    if (this._didMarkDependentsAsStale) return
+
+    this._didMarkDependentsAsStale = true
+    this._isFresh = false
+
+    this._dependents.forEach((dependent) => {
+      dependent.recalculate()
+    })
+  }
+
+  getValue(): V {
+    reportResolutionStart(this)
+
+    if (!this._isFresh) {
+      const newValue = this._recalculate()
+      this._lastValue = newValue
+      if (this.isHot) {
+        this._isFresh = true
+        this._didMarkDependentsAsStale = false
+      }
+    }
+
+    reportResolutionEnd(this)
+    return this._lastValue!
+  }
+
+  private _reactToNumberOfDependentsChange() {
+    const shouldBecomeHot = this._dependents.size > 0
+
+    if (shouldBecomeHot === this._isHot) return
+
+    this._isHot = shouldBecomeHot
+    this._didMarkDependentsAsStale = false
+    this._isFresh = false
+    if (shouldBecomeHot) {
+      this._dependencies.forEach((d) => {
+        d.addDependent(this._graphNode)
+      })
+      this._keepHot()
+    } else {
+      this._dependencies.forEach((d) => {
+        d.removeDependent(this._graphNode)
+      })
+      this._becomeCold()
+    }
+  }
+
+  protected _keepHot() {}
+
+  protected _becomeCold() {}
+
+  map<T>(fn: (v: V) => T): IDerivation<T> {
+    return map(this, fn)
+  }
+
+  flatMap<R>(
+    fn: (v: V) => R,
+  ): IDerivation<R extends IDerivation<infer T> ? T : R> {
+    return flatMap(this, fn)
+  }
+}

packages/dataverse2/src/derivations/AbstractDerivation.typeTest.ts

@@ -0,0 +1,36 @@
+import type {$IntentionalAny} from '../types'
+import type {IDerivation} from './IDerivation'
+
+const _any: $IntentionalAny = null
+
+// map
+;() => {
+  const a: IDerivation<string> = _any
+
+  // $ExpectType IDerivation<number>
+  // eslint-disable-next-line unused-imports/no-unused-vars-ts
+  a.map((s: string) => 10)
+
+  // @ts-expect-error
+  // eslint-disable-next-line unused-imports/no-unused-vars-ts
+  a.map((s: number) => 10)
+}
+
+// flatMap()
+/* eslint-disable unused-imports/no-unused-vars-ts */
+;() => {
+  const a: IDerivation<string> = _any
+
+  // okay
+  a.flatMap((s: string) => {})
+
+  // @ts-expect-error TypeTest
+  a.flatMap((s: number) => {})
+
+  // $ExpectType IDerivation<number>
+  a.flatMap((s): IDerivation<number> => _any)
+
+  // $ExpectType IDerivation<number>
+  a.flatMap((s): number => _any)
+}
+/* eslint-enable unused-imports/no-unused-vars-ts */

packages/dataverse2/src/derivations/ConstantDerivation.ts

@@ -0,0 +1,17 @@
+import AbstractDerivation from './AbstractDerivation'
+
+export default class ConstantDerivation<V> extends AbstractDerivation<V> {
+  _v: V
+
+  constructor(v: V) {
+    super()
+    this._v = v
+    return this
+  }
+
+  _recalculate() {
+    return this._v
+  }
+
+  _reactToDependencyBecomingStale() {}
+}

packages/dataverse2/src/derivations/DerivationEmitter.ts

@@ -0,0 +1,52 @@
+import Emitter from '../utils/Emitter'
+import type {default as Tappable} from '../utils/Tappable'
+import type {GraphNode, IDerivation} from './IDerivation'
+
+export default class DerivationEmitter<V> {
+  private _emitter: Emitter<V>
+  private _lastValue: undefined | V
+  private _lastValueRecorded: boolean
+  private _hadTappers: boolean
+  private _graphNode: GraphNode
+
+  constructor(private readonly _derivation: IDerivation<V>) {
+    this._emitter = new Emitter()
+    this._graphNode = {
+      height: 0,
+      recalculate: () => {
+        this._emit()
+      },
+    }
+    this._emitter.onNumberOfTappersChange(() => {
+      this._reactToNumberOfTappersChange()
+    })
+    this._hadTappers = false
+    this._lastValueRecorded = false
+    this._lastValue = undefined
+    return this
+  }
+
+  private _reactToNumberOfTappersChange() {
+    const hasTappers = this._emitter.hasTappers()
+    if (hasTappers !== this._hadTappers) {
+      this._hadTappers = hasTappers
+      if (hasTappers) {
+        this._derivation.addDependent(this._graphNode)
+      } else {
+        this._derivation.removeDependent(this._graphNode)
+      }
+    }
+  }
+
+  tappable(): Tappable<V> {
+    return this._emitter.tappable
+  }
+
+  private _emit = () => {
+    const newValue = this._derivation.getValue()
+    if (newValue === this._lastValue && this._lastValueRecorded === true) return
+    this._lastValue = newValue
+    this._lastValueRecorded = true
+    this._emitter.emit(newValue)
+  }
+}

packages/dataverse2/src/derivations/DerivationFromSource.ts

@@ -0,0 +1,53 @@
+import type {VoidFn} from '../types'
+import AbstractDerivation from './AbstractDerivation'
+
+const noop = () => {}
+
+export default class DerivationFromSource<V> extends AbstractDerivation<V> {
+  private _untapFromChanges: () => void
+  private _cachedValue: undefined | V
+  private _hasCachedValue: boolean
+
+  constructor(
+    private readonly _tapToSource: (listener: (newValue: V) => void) => VoidFn,
+    private readonly _getValueFromSource: () => V,
+  ) {
+    super()
+    this._untapFromChanges = noop
+    this._cachedValue = undefined
+    this._hasCachedValue = false
+  }
+
+  _recalculate() {
+    if (this.isHot) {
+      if (!this._hasCachedValue) {
+        this._cachedValue = this._getValueFromSource()
+        this._hasCachedValue = true
+      }
+      return this._cachedValue as V
+    } else {
+      return this._getValueFromSource()
+    }
+  }
+
+  _keepHot() {
+    this._hasCachedValue = false
+    this._cachedValue = undefined
+
+    this._untapFromChanges = this._tapToSource((newValue) => {
+      this._hasCachedValue = true
+      this._cachedValue = newValue
+      this._markAsStale(this)
+    })
+  }
+
+  _becomeCold() {
+    this._untapFromChanges()
+    this._untapFromChanges = noop
+
+    this._hasCachedValue = false
+    this._cachedValue = undefined
+  }
+
+  _reactToDependencyBecomingStale() {}
+}

packages/dataverse2/src/derivations/Freshener.ts

@@ -0,0 +1,5 @@
+import type {GraphNode} from './IDerivation'
+
+export default class Freshener {
+  schedulePeak(d: GraphNode) {}
+}

packages/dataverse2/src/derivations/IDerivation.ts

@@ -0,0 +1,29 @@
+import type Tappable from '../utils/Tappable'
+
+export type GraphNode = {
+  height: number
+  recalculate(): void
+}
+
+export interface IDerivation<V> {
+  isDerivation: true
+  isHot: boolean
+  changes(): Tappable<V>
+
+  addDependent(d: GraphNode): void
+  removeDependent(d: GraphNode): void
+
+  reportDependentHeightChange(d: GraphNode): void
+
+  getValue(): V
+
+  map<T>(fn: (v: V) => T): IDerivation<T>
+
+  flatMap<R>(
+    fn: (v: V) => R,
+  ): IDerivation<R extends IDerivation<infer T> ? T : R>
+}
+
+export function isDerivation(d: any): d is IDerivation<unknown> {
+  return d && d.isDerivation && d.isDerivation === true
+}

packages/dataverse2/src/derivations/flatMap.ts

@@ -0,0 +1,127 @@
+import type {$FixMe} from '../types'
+import AbstractDerivation from './AbstractDerivation'
+import type {IDerivation} from './IDerivation'
+
+enum UPDATE_NEEDED_FROM {
+  none = 0,
+  dep = 1,
+  inner = 2,
+}
+
+const makeFlatMapDerivationClass = () => {
+  class FlatMapDerivation<V, DepType> extends AbstractDerivation<V> {
+    private _innerDerivation: undefined | null | IDerivation<V>
+    private _staleDependency: UPDATE_NEEDED_FROM
+
+    static displayName = 'flatMap'
+
+    constructor(
+      readonly _depDerivation: IDerivation<DepType>,
+      readonly _fn: (v: DepType) => IDerivation<V> | V,
+    ) {
+      super()
+      this._innerDerivation = undefined
+      this._staleDependency = UPDATE_NEEDED_FROM.dep
+
+      this._addDependency(_depDerivation)
+
+      return this
+    }
+
+    _recalculateHot() {
+      const updateNeededFrom = this._staleDependency
+      this._staleDependency = UPDATE_NEEDED_FROM.none
+
+      if (updateNeededFrom === UPDATE_NEEDED_FROM.inner) {
+        // @ts-ignore
+        return this._innerDerivation.getValue()
+      }
+
+      const possibleInnerDerivation = this._fn(this._depDerivation.getValue())
+
+      if (possibleInnerDerivation instanceof AbstractDerivation) {
+        this._innerDerivation = possibleInnerDerivation
+        this._addDependency(possibleInnerDerivation)
+        return possibleInnerDerivation.getValue()
+      } else {
+        return possibleInnerDerivation
+      }
+    }
+
+    protected _recalculateCold() {
+      const possibleInnerDerivation = this._fn(this._depDerivation.getValue())
+
+      if (possibleInnerDerivation instanceof AbstractDerivation) {
+        return possibleInnerDerivation.getValue()
+      } else {
+        return possibleInnerDerivation
+      }
+    }
+
+    protected _recalculate() {
+      return this.isHot ? this._recalculateHot() : this._recalculateCold()
+    }
+
+    protected _reactToDependencyBecomingStale(
+      msgComingFrom: IDerivation<unknown>,
+    ) {
+      const updateNeededFrom =
+        msgComingFrom === this._depDerivation
+          ? UPDATE_NEEDED_FROM.dep
+          : UPDATE_NEEDED_FROM.inner
+
+      if (
+        updateNeededFrom === UPDATE_NEEDED_FROM.inner &&
+        msgComingFrom !== this._innerDerivation
+      ) {
+        throw Error(
+          `got a _pipostale() from neither the dep nor the inner derivation`,
+        )
+      }
+
+      if (this._staleDependency === UPDATE_NEEDED_FROM.none) {
+        this._staleDependency = updateNeededFrom
+
+        if (updateNeededFrom === UPDATE_NEEDED_FROM.dep) {
+          this._removeInnerDerivation()
+        }
+      } else if (this._staleDependency === UPDATE_NEEDED_FROM.dep) {
+      } else {
+        if (updateNeededFrom === UPDATE_NEEDED_FROM.dep) {
+          this._staleDependency = UPDATE_NEEDED_FROM.dep
+          this._removeInnerDerivation()
+        }
+      }
+    }
+
+    private _removeInnerDerivation() {
+      if (this._innerDerivation) {
+        this._removeDependency(this._innerDerivation)
+        this._innerDerivation = undefined
+      }
+    }
+
+    protected _keepHot() {
+      this._staleDependency = UPDATE_NEEDED_FROM.dep
+      this.getValue()
+    }
+
+    protected _becomeCold() {
+      this._staleDependency = UPDATE_NEEDED_FROM.dep
+      this._removeInnerDerivation()
+    }
+  }
+  return FlatMapDerivation
+}
+
+let cls: ReturnType<typeof makeFlatMapDerivationClass> | undefined = undefined
+
+export default function flatMap<V, R>(
+  dep: IDerivation<V>,
+  fn: (v: V) => R,
+): IDerivation<R extends IDerivation<infer T> ? T : R> {
+  if (!cls) {
+    cls = makeFlatMapDerivationClass()
+  }
+  return new cls(dep, fn) as $FixMe
+}

packages/dataverse2/src/derivations/iterateAndCountTicks.ts

@@ -0,0 +1,32 @@
+import {isPointer, valueDerivation} from '../Atom'
+import type {Pointer} from '../pointer'
+import type {IDerivation} from './IDerivation'
+import {isDerivation} from './IDerivation'
+
+export default function* iterateAndCountTicks<V>(
+  pointerOrDerivation: IDerivation<V> | Pointer<V>,
+): Generator<{value: V; ticks: number}, void, void> {
+  let d
+  if (isPointer(pointerOrDerivation)) {
+    d = valueDerivation(pointerOrDerivation) as IDerivation<V>
+  } else if (isDerivation(pointerOrDerivation)) {
+    d = pointerOrDerivation
+  } else {
+    throw new Error(`Only pointers and derivations are supported`)
+  }
+
+  let ticksCountedSinceLastYield = 0
+  const untap = d.changes().tap(() => {
+    ticksCountedSinceLastYield++
+  })
+
+  try {
+    while (true) {
+      const ticks = ticksCountedSinceLastYield
+      ticksCountedSinceLastYield = 0
+      yield {value: d.getValue(), ticks}
+    }
+  } finally {
+    untap()
+  }
+}

packages/dataverse2/src/derivations/iterateOver.test.ts

@@ -0,0 +1,19 @@
+import Atom from '../Atom'
+import iterateOver from './iterateOver'
+
+describe.skip(`iterateOver()`, () => {
+  test('it should work', () => {
+    const a = new Atom({a: 0})
+    let iter = iterateOver(a.pointer.a)
+    expect(iter.next().value).toEqual(0)
+    a.setIn(['a'], 1)
+    a.setIn(['a'], 2)
+    expect(iter.next()).toMatchObject({value: 2, done: false})
+    iter.return()
+    iter = iterateOver(a.pointer.a)
+    expect(iter.next().value).toEqual(2)
+    a.setIn(['a'], 3)
+    expect(iter.next()).toMatchObject({done: false, value: 3})
+    iter.return()
+  })
+})

packages/dataverse2/src/derivations/iterateOver.ts

@@ -0,0 +1,32 @@
+import {isPointer, valueDerivation} from '../Atom'
+import type {Pointer} from '../pointer'
+import Ticker from '../Ticker'
+import type {IDerivation} from './IDerivation'
+import {isDerivation} from './IDerivation'
+
+export default function* iterateOver<V>(
+  pointerOrDerivation: IDerivation<V> | Pointer<V>,
+): Generator<V, void, void> {
+  let d
+  if (isPointer(pointerOrDerivation)) {
+    d = valueDerivation(pointerOrDerivation) as IDerivation<V>
+  } else if (isDerivation(pointerOrDerivation)) {
+    d = pointerOrDerivation
+  } else {
+    throw new Error(`Only pointers and derivations are supported`)
+  }
+
+  const ticker = new Ticker()
+
+  const untap = d.changes().tap((v) => {})
+
+  try {
+    while (true) {
+      ticker.tick()
+
+      yield d.getValue()
+    }
+  } finally {
+    untap()
+  }
+}

packages/dataverse2/src/derivations/map.ts

@@ -0,0 +1,32 @@
+import AbstractDerivation from './AbstractDerivation'
+import type {IDerivation} from './IDerivation'
+
+// Exporting from a function because of the circular dependency with AbstractDerivation
+const makeMapDerivationClass = () =>
+  class MapDerivation<T, V> extends AbstractDerivation<V> {
+    constructor(
+      private readonly _dep: IDerivation<T>,
+      private readonly _fn: (t: T) => V,
+    ) {
+      super()
+      this._addDependency(_dep)
+    }
+
+    _recalculate() {
+      return this._fn(this._dep.getValue())
+    }
+
+    _reactToDependencyBecomingStale() {}
+  }
+
+let cls: ReturnType<typeof makeMapDerivationClass> | undefined = undefined
+
+export default function flatMap<V, R>(
+  dep: IDerivation<V>,
+  fn: (v: V) => R,
+): IDerivation<R> {
+  if (!cls) {
+    cls = makeMapDerivationClass()
+  }
+  return new cls(dep, fn)
+}

packages/dataverse2/src/derivations/prism/discoveryMechanism.ts

@@ -0,0 +1,50 @@
+import type {$IntentionalAny} from '../../types'
+import Stack from '../../utils/Stack'
+import type {IDerivation} from '../IDerivation'
+
+const noop = () => {}
+
+const stack = new Stack<Collector>()
+const noopCollector: Collector = noop
+
+type Collector = (d: IDerivation<$IntentionalAny>) => void
+
+export const collectObservedDependencies = (
+  cb: () => void,
+  collector: Collector,
+) => {
+  stack.push(collector)
+  cb()
+  stack.pop()
+}
+
+export const startIgnoringDependencies = () => {
+  stack.push(noopCollector)
+}
+
+export const stopIgnoringDependencies = () => {
+  if (stack.peek() !== noopCollector) {
+    if (process.env.NODE_ENV === 'development') {
+      console.warn('This should never happen')
+    }
+  } else {
+    stack.pop()
+  }
+}
+
+export const reportResolutionStart = (d: IDerivation<$IntentionalAny>) => {
+  const possibleCollector = stack.peek()
+  if (possibleCollector) {
+    possibleCollector(d)
+  }
+
+  stack.push(noopCollector)
+}
+
+export const reportResolutionEnd = (_d: IDerivation<$IntentionalAny>) => {
+  stack.pop()
+}
+
+export const isCollectingDependencies = () => {
+  return stack.peek() !== noopCollector
+}

packages/dataverse2/src/derivations/prism/prism.test.ts

@@ -0,0 +1,225 @@
+import Atom, {val} from '../../Atom'
+import Ticker from '../../Ticker'
+import type {$FixMe, $IntentionalAny} from '../../types'
+import ConstantDerivation from '../ConstantDerivation'
+import iterateAndCountTicks from '../iterateAndCountTicks'
+import prism, {PrismDerivation} from './prism'
+
+describe.skip('prism', () => {
+  let ticker: Ticker
+  beforeEach(() => {
+    ticker = new Ticker()
+  })
+
+  it('should work', () => {
+    const o = new Atom({foo: 'foo'})
+    const d = new PrismDerivation(() => {
+      return val(o.pointer.foo) + 'boo'
+    })
+    expect(d.getValue()).toEqual('fooboo')
+
+    const changes: Array<$FixMe> = []
+    d.changes().tap((c) => {
+      changes.push(c)
+    })
+
+    o.reduceState(['foo'], () => 'foo2')
+    ticker.tick()
+    expect(changes).toMatchObject(['foo2boo'])
+  })
+  it('should only collect immediate dependencies', () => {
+    const aD = new ConstantDerivation(1)
+    const bD = aD.map((v) => v * 2)
+    const cD = prism(() => {
+      return bD.getValue()
+    })
+    expect(cD.getValue()).toEqual(2)
+    expect((cD as $IntentionalAny)._dependencies.size).toEqual(1)
+  })
+
+  describe('prism.ref()', () => {
+    it('should work', () => {
+      const theAtom: Atom<{n: number}> = new Atom({n: 2})
+
+      const isEvenD = prism((): {isEven: boolean} => {
+        const ref = prism.ref<{isEven: boolean} | undefined>('cache', undefined)
+        const currentN = val(theAtom.pointer.n)
+
+        const isEven = currentN % 2 === 0
+        if (ref.current && ref.current.isEven === isEven) {
+          return ref.current
+        } else {
+          ref.current = {isEven}
+          return ref.current
+        }
+      })
+
+      const iterator = iterateAndCountTicks(isEvenD)
+
+      theAtom.reduceState(['n'], () => 3)
+
+      expect(iterator.next().value).toMatchObject({
+        value: {isEven: false},
+        ticks: 0,
+      })
+      theAtom.reduceState(['n'], () => 5)
+      theAtom.reduceState(['n'], () => 7)
+      expect(iterator.next().value).toMatchObject({
+        value: {isEven: false},
+        ticks: 1,
+      })
+      theAtom.reduceState(['n'], () => 2)
+      theAtom.reduceState(['n'], () => 4)
+      expect(iterator.next().value).toMatchObject({
+        value: {isEven: true},
+        ticks: 1,
+      })
+      expect(iterator.next().value).toMatchObject({
+        value: {isEven: true},
+        ticks: 0,
+      })
+    })
+  })
+
+  describe('prism.effect()', () => {
+    it('should work', async () => {
+      let iteration = 0
+      const sequence: unknown[] = []
+      let deps: unknown[] = []
+
+      const a = new Atom({letter: 'a'})
+
+      const derivation = prism(() => {
+        const n = val(a.pointer.letter)
+        const iterationAtTimeOfCall = iteration
+        sequence.push({derivationCall: iterationAtTimeOfCall})
+
+        prism.effect(
+          'f',
+          () => {
+            sequence.push({effectCall: iterationAtTimeOfCall})
+            return () => {
+              sequence.push({cleanupCall: iterationAtTimeOfCall})
+            }
+          },
+          [...deps],
+        )
+
+        return n
+      })
+
+      const untap = derivation.changes().tap((change) => {
+        sequence.push({change})
+      })
+
+      expect(sequence).toMatchObject([{derivationCall: 0}, {effectCall: 0}])
+      sequence.length = 0
+
+      iteration++
+      a.setIn(['letter'], 'b')
+      ticker.tick()
+      expect(sequence).toMatchObject([{derivationCall: 1}, {change: 'b'}])
+      sequence.length = 0
+
+      deps = [1]
+      iteration++
+      a.setIn(['letter'], 'c')
+      ticker.tick()
+      expect(sequence).toMatchObject([
+        {derivationCall: 2},
+        {cleanupCall: 0},
+        {effectCall: 2},
+        {change: 'c'},
+      ])
+      sequence.length = 0
+
+      untap()
+
+      // takes a tick before untap takes effect
+      await new Promise((resolve) => setTimeout(resolve, 1))
+      expect(sequence).toMatchObject([{cleanupCall: 2}])
+    })
+  })
+
+  describe('prism.memo()', () => {
+    it('should work', async () => {
+      let iteration = 0
+      const sequence: unknown[] = []
+      let deps: unknown[] = []
+
+      const a = new Atom({letter: 'a'})
+
+      const derivation = prism(() => {
+        const n = val(a.pointer.letter)
+        const iterationAtTimeOfCall = iteration
+        sequence.push({derivationCall: iterationAtTimeOfCall})
+
+        const resultOfMemo = prism.memo(
+          'memo',
+          () => {
+            sequence.push({memoCall: iterationAtTimeOfCall})
+            return iterationAtTimeOfCall
+          },
+          [...deps],
+        )
+
+        sequence.push({resultOfMemo})
+
+        return n
+      })
+
+      const untap = derivation.changes().tap((change) => {
+        sequence.push({change})
+      })
+
+      expect(sequence).toMatchObject([
+        {derivationCall: 0},
+        {memoCall: 0},
+        {resultOfMemo: 0},
+      ])
+      sequence.length = 0
+
+      iteration++
+      a.setIn(['letter'], 'b')
+      ticker.tick()
+      expect(sequence).toMatchObject([
+        {derivationCall: 1},
+        {resultOfMemo: 0},
+        {change: 'b'},
+      ])
+      sequence.length = 0
+
+      deps = [1]
+      iteration++
+      a.setIn(['letter'], 'c')
+      ticker.tick()
+      expect(sequence).toMatchObject([
+        {derivationCall: 2},
+        {memoCall: 2},
+        {resultOfMemo: 2},
+        {change: 'c'},
+      ])
+      sequence.length = 0
+
+      untap()
+    })
+  })
+
+  describe(`prism.scope()`, () => {
+    it('should prevent name conflicts', () => {
+      const d = prism(() => {
+        const thisNameWillBeUsedForBothMemos = 'blah'
+        const a = prism.scope('a', () => {
+          return prism.memo(thisNameWillBeUsedForBothMemos, () => 'a', [])
+        })
+
+        const b = prism.scope('b', () => {
+          return prism.memo(thisNameWillBeUsedForBothMemos, () => 'b', [])
+        })
+
+        return {a, b}
+      })
+      expect(d.getValue()).toMatchObject({a: 'a', b: 'b'})
+    })
+  })
+})

packages/dataverse2/src/derivations/prism/prism.ts

@@ -0,0 +1,331 @@
+import Box from '../../Box'
+import type {$IntentionalAny, VoidFn} from '../../types'
+import Stack from '../../utils/Stack'
+import AbstractDerivation from '../AbstractDerivation'
+import type {IDerivation} from '../IDerivation'
+import {
+  collectObservedDependencies,
+  startIgnoringDependencies,
+  stopIgnoringDependencies,
+} from './discoveryMechanism'
+
+const voidFn = () => {}
+
+export class PrismDerivation<V> extends AbstractDerivation<V> {
+  protected _cacheOfDendencyValues: Map<IDerivation<unknown>, unknown> =
+    new Map()
+  protected _possiblyStaleDeps = new Set<IDerivation<unknown>>()
+  private _prismScope = new PrismScope()
+
+  constructor(readonly _fn: () => V) {
+    super()
+  }
+
+  _recalculate() {
+    let value: V
+
+    if (this._possiblyStaleDeps.size > 0) {
+      let anActuallyStaleDepWasFound = false
+      startIgnoringDependencies()
+      for (const dep of this._possiblyStaleDeps) {
+        if (this._cacheOfDendencyValues.get(dep) !== dep.getValue()) {
+          anActuallyStaleDepWasFound = true
+          break
+        }
+      }
+      stopIgnoringDependencies()
+      this._possiblyStaleDeps.clear()
+      if (!anActuallyStaleDepWasFound) {
+        // console.log('ok')
+
+        return this._lastValue!
+      }
+    }
+
+    const newDeps: Set<IDerivation<unknown>> = new Set()
+    this._cacheOfDendencyValues.clear()
+    collectObservedDependencies(
+      () => {
+        hookScopeStack.push(this._prismScope)
+        try {
+          value = this._fn()
+        } catch (error) {
+          console.error(error)
+        } finally {
+          const topOfTheStack = hookScopeStack.pop()
+          if (topOfTheStack !== this._prismScope) {
+            console.warn(
+              // @todo guide the user to report the bug in an issue
+              `The Prism hook stack has slipped. This is a bug.`,
+            )
+          }
+        }
+      },
+      (observedDep) => {
+        newDeps.add(observedDep)
+        this._addDependency(observedDep)
+      },
+    )
+
+    this._dependencies.forEach((dep) => {
+      if (!newDeps.has(dep)) {
+        this._removeDependency(dep)
+      }
+    })
+
+    this._dependencies = newDeps
+
+    startIgnoringDependencies()
+    newDeps.forEach((dep) => {
+      this._cacheOfDendencyValues.set(dep, dep.getValue())
+    })
+    stopIgnoringDependencies()
+
+    return value!
+  }
+
+  _reactToDependencyBecomingStale(msgComingFrom: IDerivation<unknown>) {
+    this._possiblyStaleDeps.add(msgComingFrom)
+  }
+
+  _keepHot() {
+    this._prismScope = new PrismScope()
+    startIgnoringDependencies()
+    this.getValue()
+    stopIgnoringDependencies()
+  }
+
+  _becomeCold() {
+    cleanupScopeStack(this._prismScope)
+    this._prismScope = new PrismScope()
+  }
+}
+
+class PrismScope {
+  isPrismScope = true
+  private _subs: Record<string, PrismScope> = {}
+
+  sub(key: string) {
+    if (!this._subs[key]) {
+      this._subs[key] = new PrismScope()
+    }
+    return this._subs[key]
+  }
+
+  get subs() {
+    return this._subs
+  }
+}
+
+function cleanupScopeStack(scope: PrismScope) {
+  for (const [_, sub] of Object.entries(scope.subs)) {
+    cleanupScopeStack(sub)
+  }
+  cleanupEffects(scope)
+}
+
+function cleanupEffects(scope: PrismScope) {
+  const effects = effectsWeakMap.get(scope)
+  if (effects) {
+    for (const k of Object.keys(effects)) {
+      const effect = effects[k]
+      safelyRun(effect.cleanup, undefined)
+    }
+  }
+  effectsWeakMap.delete(scope)
+}
+
+function safelyRun<T, U>(
+  fn: () => T,
+  returnValueInCaseOfError: U,
+): {success: boolean; returnValue: T | U} {
+  let returnValue: T | U = returnValueInCaseOfError
+  let success = false
+  try {
+    returnValue = fn()
+    success = true
+  } catch (error) {
+    setTimeout(() => {
+      throw error
+    })
+  }
+  return {success, returnValue}
+}
+
+const hookScopeStack = new Stack<PrismScope>()
+
+const refsWeakMap = new WeakMap<PrismScope, Record<string, IRef<unknown>>>()
+
+type IRef<T> = {
+  current: T
+}
+const effectsWeakMap = new WeakMap<PrismScope, Record<string, IEffect>>()
+
+type IEffect = {
+  deps: undefined | unknown[]
+  cleanup: VoidFn
+}
+
+const memosWeakMap = new WeakMap<PrismScope, Record<string, IMemo>>()
+
+type IMemo = {
+  deps: undefined | unknown[]
+  cachedValue: unknown
+}
+
+function ref<T>(key: string, initialValue: T): IRef<T> {
+  const scope = hookScopeStack.peek()
+  if (!scope) {
+    throw new Error(`prism.ref() is called outside of a prism() call.`)
+  }
+  let refs = refsWeakMap.get(scope)
+  if (!refs) {
+    refs = {}
+    refsWeakMap.set(scope, refs)
+  }
+
+  if (refs[key]) {
+    return refs[key] as $IntentionalAny as IRef<T>
+  } else {
+    const ref: IRef<T> = {
+      current: initialValue,
+    }
+    refs[key] = ref
+    return ref
+  }
+}
+
+function effect(key: string, cb: () => () => void, deps?: unknown[]): void {
+  const scope = hookScopeStack.peek()
+  if (!scope) {
+    throw new Error(`prism.effect() is called outside of a prism() call.`)
+  }
+  let effects = effectsWeakMap.get(scope)
+
+  if (!effects) {
+    effects = {}
+    effectsWeakMap.set(scope, effects)
+  }
+
+  if (!effects[key]) {
+    effects[key] = {
+      cleanup: voidFn,
+      deps: [{}],
+    }
+  }
+
+  const effect = effects[key]
+  if (depsHaveChanged(effect.deps, deps)) {
+    effect.cleanup()
+
+    startIgnoringDependencies()
+    effect.cleanup = safelyRun(cb, voidFn).returnValue
+    stopIgnoringDependencies()
+    effect.deps = deps
+  }
+}
+
+function depsHaveChanged(
+  oldDeps: undefined | unknown[],
+  newDeps: undefined | unknown[],
+): boolean {
+  if (oldDeps === undefined || newDeps === undefined) {
+    return true
+  } else if (oldDeps.length !== newDeps.length) {
+    return true
+  } else {
+    return oldDeps.some((el, i) => el !== newDeps[i])
+  }
+}
+
+function memo<T>(
+  key: string,
+  fn: () => T,
+  deps: undefined | $IntentionalAny[],
+): T {
+  const scope = hookScopeStack.peek()
+  if (!scope) {
+    throw new Error(`prism.memo() is called outside of a prism() call.`)
+  }
+
+  let memos = memosWeakMap.get(scope)
+
+  if (!memos) {
+    memos = {}
+    memosWeakMap.set(scope, memos)
+  }
+
+  if (!memos[key]) {
+    memos[key] = {
+      cachedValue: null,
+      deps: [{}],
+    }
+  }
+
+  const memo = memos[key]
+  if (depsHaveChanged(memo.deps, deps)) {
+    startIgnoringDependencies()
+
+    memo.cachedValue = safelyRun(fn, undefined).returnValue
+    stopIgnoringDependencies()
+    memo.deps = deps
+  }
+
+  return memo.cachedValue as $IntentionalAny as T
+}
+
+function state<T>(key: string, initialValue: T): [T, (val: T) => void] {
+  const {b, setValue} = prism.memo(
+    'state/' + key,
+    () => {
+      const b = new Box<T>(initialValue)
+      const setValue = (val: T) => b.set(val)
+      return {b, setValue}
+    },
+    [],
+  )
+
+  return [b.derivation.getValue(), setValue]
+}
+
+function ensurePrism(): void {
+  const scope = hookScopeStack.peek()
+  if (!scope) {
+    throw new Error(`The parent function is called outside of a prism() call.`)
+  }
+}
+
+function scope<T>(key: string, fn: () => T): T {
+  const parentScope = hookScopeStack.peek()
+  if (!parentScope) {
+    throw new Error(`prism.memo() is called outside of a prism() call.`)
+  }
+  const subScope = parentScope.sub(key)
+  hookScopeStack.push(subScope)
+  const ret = safelyRun(fn, undefined).returnValue
+  hookScopeStack.pop()
+  return ret as $IntentionalAny as T
+}
+
+type IPrismFn = {
+  <T>(fn: () => T): IDerivation<T>
+  ref: typeof ref
+  effect: typeof effect
+  memo: typeof memo
+  ensurePrism: typeof ensurePrism
+  state: typeof state
+  scope: typeof scope
+}
+
+const prism: IPrismFn = (fn) => {
+  return new PrismDerivation(fn)
+}
+
+prism.ref = ref
+prism.effect = effect
+prism.memo = memo
+prism.ensurePrism = ensurePrism
+prism.state = state
+prism.scope = scope
+
+export default prism