fix: full rewrite of ScopeProvider to address known issues

Author: dmaskasky

eslint.config.ts

@@ -27,6 +27,7 @@ export default tseslint.config(
       eqeqeq: 'error',
       'no-console': 'off',
       'no-inner-declarations': 'off',
+      'no-sparse-arrays': 'off',
       'no-var': 'error',
       'prefer-const': 'error',
       'sort-imports': [

notes/new.md

@@ -0,0 +1,60 @@
+## Goals
+
+1. don't copy atoms
+2. remove writable hack
+
+### explicitly scoped
+
+```ts
+if (explicit.has(atom)) {
+  // handle explicit
+  return atom
+}
+```
+
+### implicitly scoped
+
+```ts
+
+else if (implicit.has(atom)) {
+  return currentScope.getAtom(atom)
+  // handle implicit
+}
+```
+
+### inherited scoped
+
+```ts
+/** returns nearest ancestor scope if atom is explicitly scoped in any ancestor store */
+const scope = searchAncestorScopes(atom)
+else if (scope) {
+  // handle inherited
+  return scope.getAtom(atom)
+}
+```
+
+### inherited implicitly scoped
+
+else if the dependent atom is explicitly or implicitly scoped in an ancestor store, current atom is implicitly scoped in that ancestor store if it is not
+how: ???
+
+```ts
+else if (searchAncestorScopes(dependentAtom)) {
+  isScopedAtom(dependentAtom)
+  // handle implicit
+}
+```
+
+### unscoped
+
+else atom is unscoped
+
+#### unscoped derived
+
+if atom is derived, it can access scoped atoms
+how: ???
+
+### unscoped writable
+
+if atom is writable, it can access scoped atoms
+how: ???

notes/notes

@@ -0,0 +1,31 @@
+just intercept the getter of the store everywhere all the way up to the base store.
+
+---
+
+computed atoms are like implicit atoms but reverse
+computed atoms are not copied
+reverseImplicitSet is a set of computed atoms to indicate whether a computed atom should be treated as a reverse implicit
+the atom is removed from the set between recomputations
+by intercepting the readFn, if an atom is `get` that is either an explicit or reverse implicit,
+
+- then the atom is added to the reverse implicit set
+
+only the readFn determines if the atom is added to the reverse implicit set
+intercepting the readFn and writeFn is used to get the "correct" atom
+when a computed atom converts to reverse implicit,
+
+- its atomState is created from scratch
+- this is because the atomState stores a different value for the scoped atom and can have different dependencies
+
+**Special Case:** on first read, when a computed atom reads a scoped atom,
+
+1. it is added to the reverse implicit set
+1. the atomState is copied from the unscoped atomState
+1. getAtomState points to the scoped atomState
+
+the atomStateProxy is no longer needed.
+
+# Implementation
+
+readAtomTrap:
+getter:

notes/readAtomState.md

@@ -0,0 +1,13 @@
+## Objectives
+
+1. Derived atoms are copied even if they don’t depend on scoped atoms.
+2. If the derived atom has already mounted, don't call onMount again.
+   Fixes:
+
+- [Scope caused atomWithObservable to be out of sync](https://github.com/jotaijs/jotai-scope/issues/36)
+- [Computed atoms get needlessly triggered again](https://github.com/jotaijs/jotai-scope/issues/25)
+
+## Requirements
+
+1. Some way to get whether the atom has been mounted.
+2. Some way to bypass the onMount call if the atom is already mounted.

notes/unstable_derive.md

@@ -0,0 +1,81 @@
+# Objectives
+
+1. Derived atoms are not copied if they don’t depend on scoped atoms.
+2. When a derived atom starts depending on a scoped atom, a new atom state is created as the scoped atom state.
+3. When a derived atom stops depending on a scoped atom, it must be removed from the scope state and restored to the original atom state.
+   a. When changing between scoped and unscoped, all subscibers must be notified.
+
+   Fixes:
+
+   - [Scope caused atomWithObservable to be out of sync](https://github.com/jotaijs/jotai-scope/issues/36)
+   - [Computed atoms get needlessly triggered again](https://github.com/jotaijs/jotai-scope/issues/25)
+
+# Requirements
+
+1. Some way to track dependencies of computed atoms not in the scope without copying them.
+2. Some way to get whether the atom has been mounted.
+
+# Problem Statement
+
+A computed atom may or may not consume scoped atoms. This may also change as state changes.
+
+```tsx
+const providerAtom = atom('unscoped')
+const scopedProviderAtom = atom('scoped')
+const shouldConsumeScopedAtom = atom(false)
+const consumerAtom = atom((get) => {
+  if (get(shouldConsumeScopedAtom)) {
+    return get(scopedProviderAtom)
+  }
+  return get(providerAtom)
+})
+
+function Component() {
+  const value = useAtomValue(consumerAtom)
+  return value
+}
+
+function App() {
+  const setShouldConsumeScopedAtom = useSetAtom(shouldConsumeScopedAtom)
+  useEffect(() => {
+    const timeoutId = setTimeout(setShouldConsumeScopedAtom, 1000, true)
+    return () => clearTimeout(timeoutId)
+  }, [])
+
+  return (
+    <ScopeProvider atoms={[scopedProviderAtom]}>
+      <Component />
+    </ScopeProvider>
+  )
+}
+```
+
+To properly handle `consumerAtom`, we need to track the dependencies of the computed atom.
+
+# Proxy State
+
+Atom state has the following shape;
+
+```ts
+type AtomState = {
+  d: Map<AnyAtom, number>; // map of atom consumers to their epoch number
+  p: Set<AnyAtom>; // set of pending atom consumers
+  n: number; // epoch number
+  m?: {
+    l: Set<() => void>; // set of listeners
+    d: Set<AnyAtom>; // set of mounted atom consumers
+    t: Set<AnyAtom>; // set of mounted atom providers
+    u?: (setSelf: () => any) => (void | () => void); // unmount function
+  };
+  v?: any; // value
+  e?: any; // error
+};
+```
+
+All computed atoms (`atom.read !== defaultRead`) will have their base atomState converted to a proxy state. The proxy state will track dependencies and notify when they change.
+
+0. Update all computed atoms with a proxy state in the parent store.
+1. If a computer atom does not depend on any scoped atoms, remove it from the unscopedComputed set
+2. If a computed atom starts depending on a scoped atom, add it to the scopedComputed set.
+   a. If the scoped state does not already exist, create a new scoped atom state.
+3. If a computed atom stops depending on a scoped atom, remove it from the scopedComputed set.

pnpm-lock.yaml

@@ -10,6 +10,8 @@ import {
   type Store,
 } from '../types'
 import { createScope } from './scope'
+import type { AnyAtom, AnyAtomFamily, Store } from './types'
+import { isEqualSet } from './utils'
 
 type ScopeProviderBaseProps = PropsWithChildren<{
   atoms?: Iterable<AnyAtom | AtomDefault>
@@ -45,7 +47,22 @@ export function ScopeProvider({
 
   const atoms = Array.from(atomsOrTuples, (a) => (Array.isArray(a) ? a[0] : a))
 
-  // atomSet is used to detect if the atoms prop has changed.
+export function ScopeProvider(
+  props: { atoms: Iterable<Atom<unknown>> } & BaseScopeProviderProps
+): JSX.Element
+
+export function ScopeProvider(
+  props: { atomFamilies: Iterable<AnyAtomFamily> } & BaseScopeProviderProps
+): JSX.Element
+
+export function ScopeProvider({
+  atoms,
+  atomFamilies,
+  children,
+  debugName,
+  ...options
+}: BaseScopeProviderProps) {
+  const baseStore = useStore(options)
   const atomSet = new Set(atoms)
   const atomFamilySet = new Set(atomFamilies)