atom.io 0.33.21 → 0.34.1

package/src/internal/get-state/read-or-compute-value.ts

@@ -1,5 +1,5 @@
 import type { ReadableState } from ".."
-import { readCachedValue } from "../caching"
+import { cacheValue, readCachedValue } from "../caching"
 import type { Store } from "../store"
 
 export const readOrComputeValue = <T>(
@@ -7,7 +7,6 @@ export const readOrComputeValue = <T>(
 	state: ReadableState<T>,
 ): T => {
 	if (target.valueMap.has(state.key)) {
-		target.logger.info(`📖`, state.type, state.key, `reading cached value`)
 		return readCachedValue(state, target)
 	}
 	switch (state.type) {
@@ -20,20 +19,26 @@ export const readOrComputeValue = <T>(
 		case `atom`:
 		case `mutable_atom`: {
 			const def = state.default
-			let fallback: T
+			let defaultValue: T
 			if (def instanceof Function) {
-				fallback = def()
+				defaultValue = def()
 			} else {
-				fallback = def
+				defaultValue = def
 			}
+			const cachedValue = cacheValue(
+				target,
+				state.key,
+				defaultValue,
+				state.subject,
+			)
 			target.logger.info(
 				`💁`,
 				`atom`,
 				state.key,
 				`could not find cached value; using default`,
-				fallback,
+				defaultValue,
 			)
-			return fallback
+			return cachedValue
 		}
 	}
 }

package/src/internal/join/create-join.ts

@@ -0,0 +1,27 @@
+import type { JoinOptions, JoinToken } from "atom.io"
+import type { Store } from "atom.io/internal"
+import { Join } from "atom.io/internal"
+import type { Json } from "atom.io/json"
+
+export function createJoin<
+	ASide extends string,
+	AType extends string,
+	BSide extends string,
+	BType extends string,
+	Cardinality extends `1:1` | `1:n` | `n:n`,
+	Content extends Json.Object,
+>(
+	store: Store,
+	options: JoinOptions<ASide, AType, BSide, BType, Cardinality, Content>,
+	defaultContent: Content | undefined,
+): JoinToken<ASide, AType, BSide, BType, Cardinality, Content> {
+	store.joins.set(options.key, new Join(options, defaultContent, store))
+	const token: JoinToken<ASide, AType, BSide, BType, Cardinality, Content> = {
+		key: options.key,
+		type: `join`,
+		a: options.between[0],
+		b: options.between[1],
+		cardinality: options.cardinality,
+	}
+	return token
+}

package/src/internal/join/index.ts

@@ -1,3 +1,4 @@
+export * from "./create-join"
 export * from "./edit-relations-in-store"
 export * from "./find-relations-in-store"
 export * from "./get-internal-relations-from-store"

package/src/internal/junction.ts

@@ -18,7 +18,9 @@ export interface JunctionEntries<
 		JunctionEntriesBase<AType, BType, Content> {}
 
 export type JunctionSchemaBase<ASide extends string, BSide extends string> = {
+	/** Description of the relationship between the two sides */
 	readonly between: [a: ASide, b: BSide]
+	/** How many relations are allowed in each direction? */
 	readonly cardinality: `1:1` | `1:n` | `n:n`
 }
 export interface JunctionSchema<ASide extends string, BSide extends string>

package/src/internal/mutable/create-mutable-atom.ts

@@ -8,7 +8,7 @@ import type { Json } from "atom.io/json"
 import { selectJson } from "atom.io/json"
 
 import type { MutableAtom } from ".."
-import { cacheValue, resetInStore, setIntoStore } from ".."
+import { resetInStore, setIntoStore } from ".."
 import { newest } from "../lineage"
 import { deposit, type Store } from "../store"
 import { Subject } from "../subject"
@@ -31,7 +31,7 @@ export function createMutableAtom<
 		`creating in store "${store.config.name}"`,
 	)
 	const target = newest(store)
-	const { key, default: def } = options
+	const { key } = options
 	const existing = target.atoms.get(key)
 	const type = `mutable_atom`
 	if (existing && existing.type === type) {
@@ -56,9 +56,7 @@ export function createMutableAtom<
 	if (family) {
 		newAtom.family = family
 	}
-	const initialValue = def()
 	target.atoms.set(newAtom.key, newAtom)
-	cacheValue(target, key, initialValue, subject)
 	const token = deposit(newAtom)
 	if (options.effects) {
 		let effectIndex = 0

package/src/internal/selector/create-readonly-held-selector.ts

@@ -23,6 +23,16 @@ export const createReadonlyHeldSelector = <T extends object>(
 	const type = `readonly_held_selector` as const
 	const { get, find, json } = registerSelector(target, type, key, covered)
 	const getSelf = () => {
+		const innerTarget = newest(store)
+		const upstreamStates = innerTarget.selectorGraph.getRelationEntries({
+			downstreamSelectorKey: key,
+		})
+		for (const [downstreamSelectorKey, { source }] of upstreamStates) {
+			if (source !== key) {
+				innerTarget.selectorGraph.delete(downstreamSelectorKey, key)
+			}
+		}
+		innerTarget.selectorAtoms.delete(key)
 		options.get({ get, find, json }, constant)
 		cacheValue(newest(store), key, constant, subject)
 		covered.clear()

package/src/internal/selector/create-readonly-pure-selector.ts

@@ -23,10 +23,21 @@ export const createReadonlyPureSelector = <T>(
 	const type = `readonly_pure_selector` as const
 	const { get, find, json } = registerSelector(target, type, key, covered)
 	const getSelf = () => {
+		const innerTarget = newest(store)
+		const upstreamStates = innerTarget.selectorGraph.getRelationEntries({
+			downstreamSelectorKey: key,
+		})
+		for (const [downstreamSelectorKey, { source }] of upstreamStates) {
+			if (source !== key) {
+				innerTarget.selectorGraph.delete(downstreamSelectorKey, key)
+			}
+		}
+		innerTarget.selectorAtoms.delete(key)
 		const value = options.get({ get, find, json })
-		cacheValue(newest(store), key, value, subject)
+		const cached = cacheValue(innerTarget, key, value, subject)
+		store.logger.info(`✨`, type, key, `=`, cached)
 		covered.clear()
-		return value
+		return cached
 	}
 
 	const readonlySelector: ReadonlyPureSelector<T> = {
@@ -38,8 +49,6 @@ export const createReadonlyPureSelector = <T>(
 		...(family && { family }),
 	}
 	target.readonlySelectors.set(key, readonlySelector)
-	const initialValue = getSelf()
-	store.logger.info(`✨`, type, key, `=`, initialValue)
 	const token: ReadonlyPureSelectorToken<T> = {
 		key,
 		type,

package/src/internal/selector/create-writable-held-selector.ts

@@ -29,8 +29,18 @@ export const createWritableHeldSelector = <T extends object>(
 	const getterToolkit = { find, get, json }
 
 	const getSelf = (getFn = options.get, innerTarget = newest(store)): T => {
+		const upstreamStates = innerTarget.selectorGraph.getRelationEntries({
+			downstreamSelectorKey: key,
+		})
+		for (const [downstreamSelectorKey, { source }] of upstreamStates) {
+			if (source !== key) {
+				innerTarget.selectorGraph.delete(downstreamSelectorKey, key)
+			}
+		}
+		innerTarget.selectorAtoms.delete(key)
 		getFn(getterToolkit, constant)
 		cacheValue(innerTarget, key, constant, subject)
+		store.logger.info(`✨`, type, key, `=`, constant)
 		covered.clear()
 		return constant
 	}
@@ -57,8 +67,7 @@ export const createWritableHeldSelector = <T extends object>(
 		...(family && { family }),
 	}
 	target.writableSelectors.set(key, mySelector)
-	const initialValue = getSelf()
-	store.logger.info(`✨`, type, key, `=`, initialValue)
+	// const initialValue = getSelf()
 
 	const token: WritableHeldSelectorToken<T> = { key, type }
 	if (family) {

package/src/internal/selector/create-writable-pure-selector.ts

@@ -29,8 +29,18 @@ export const createWritablePureSelector = <T>(
 	const getterToolkit = { find, get, json }
 
 	const getSelf = (getFn = options.get, innerTarget = newest(store)): T => {
+		const upstreamStates = innerTarget.selectorGraph.getRelationEntries({
+			downstreamSelectorKey: key,
+		})
+		for (const [downstreamSelectorKey, { source }] of upstreamStates) {
+			if (source !== key) {
+				innerTarget.selectorGraph.delete(downstreamSelectorKey, key)
+			}
+		}
+		innerTarget.selectorAtoms.delete(key)
 		const value = getFn(getterToolkit)
-		cacheValue(innerTarget, key, value, subject)
+		const cached = cacheValue(innerTarget, key, value, subject)
+		store.logger.info(`✨`, type, key, `=`, cached)
 		covered.clear()
 		return value
 	}

package/src/internal/selector/trace-selector-atoms.ts

@@ -1,51 +1,29 @@
-import type { Atom, Selector, Store } from ".."
-import type { AtomKey, StateKey } from "../keys"
+import type { Atom, Store } from ".."
 import { isAtomKey } from "../keys"
 import { getSelectorDependencyKeys } from "./get-selector-dependency-keys"
 
-export const traceSelectorAtoms = (
+export const traceRootSelectorAtoms = (
 	store: Store,
-	directDependencyKey: StateKey<unknown>,
-	covered: Set<string>,
-): AtomKey<unknown>[] => {
-	const rootKeys: AtomKey<unknown>[] = []
+	selectorKey: string,
+	covered: Set<string> = new Set<string>(),
+): Map<string, Atom<unknown>> => {
+	const dependencies = getSelectorDependencyKeys(store, selectorKey)
 
-	const indirectDependencyKeys = getSelectorDependencyKeys(
-		store,
-		directDependencyKey,
-	)
-	while (indirectDependencyKeys.length > 0) {
+	const roots = new Map<string, Atom<unknown>>()
+
+	while (dependencies.length > 0) {
 		// biome-ignore lint/style/noNonNullAssertion: just checked length ^^^
-		const indirectDependencyKey = indirectDependencyKeys.shift()!
-		if (covered.has(indirectDependencyKey)) {
+		const dependencyKey = dependencies.pop()!
+		if (covered.has(dependencyKey)) {
 			continue
 		}
-		covered.add(indirectDependencyKey)
-
-		if (!isAtomKey(store, indirectDependencyKey)) {
-			indirectDependencyKeys.push(
-				...getSelectorDependencyKeys(store, indirectDependencyKey),
-			)
-		} else if (!rootKeys.includes(indirectDependencyKey)) {
-			rootKeys.push(indirectDependencyKey)
+		covered.add(dependencyKey)
+		if (isAtomKey(store, dependencyKey)) {
+			const atom = store.atoms.get(dependencyKey) as Atom<unknown>
+			roots.set(atom.key, atom)
+		} else {
+			dependencies.push(...getSelectorDependencyKeys(store, dependencyKey))
 		}
 	}
-
-	return rootKeys
-}
-
-export const traceAllSelectorAtoms = (
-	selector: Selector<any>,
-	store: Store,
-): Atom<unknown>[] => {
-	const selectorKey = selector.key
-	const directDependencyKeys = getSelectorDependencyKeys(store, selectorKey)
-	const covered = new Set<string>()
-	return directDependencyKeys
-		.flatMap((depKey) =>
-			isAtomKey(store, depKey)
-				? depKey
-				: traceSelectorAtoms(store, depKey, covered),
-		)
-		.map((atomKey) => store.atoms.get(atomKey) as Atom<unknown>)
+	return roots
 }

package/src/internal/selector/update-selector-atoms.ts

@@ -2,7 +2,7 @@ import type { ReadonlyPureSelectorToken, WritableToken } from "atom.io"
 
 import { newest } from "../lineage"
 import type { Store } from "../store"
-import { traceSelectorAtoms } from "./trace-selector-atoms"
+import { traceRootSelectorAtoms } from "./trace-selector-atoms"
 
 export const updateSelectorAtoms = (
 	store: Store,
@@ -29,16 +29,16 @@ export const updateSelectorAtoms = (
 			`discovers root atom "${dependencyKey}"`,
 		)
 	} else {
-		const rootKeys = traceSelectorAtoms(store, dependencyKey, covered)
+		const rootKeys = traceRootSelectorAtoms(store, dependencyKey, covered)
 		store.logger.info(
 			`🔍`,
 			selectorType,
 			selectorKey,
-			`discovers root atoms: [ ${rootKeys
-				.map((key) => `"${key}"`)
+			`discovers root atoms: [ ${[...rootKeys.values()]
+				.map((root) => `"${root.key}"`)
 				.join(`, `)} ]`,
 		)
-		for (const atomKey of rootKeys) {
+		for (const { key: atomKey } of rootKeys.values()) {
 			target.selectorAtoms = target.selectorAtoms.set({
 				selectorKey,
 				atomKey,

package/src/internal/set-state/evict-downstream.ts

@@ -29,7 +29,7 @@ export function evictDownStream(store: Store, atom: Atom<any>): void {
 			if (isDone(target, key)) {
 				continue
 			}
-			evictCachedValue(key, target)
+			evictCachedValue(target, key)
 			markDone(target, key)
 		}
 	}
@@ -49,7 +49,7 @@ export function evictDownStreamFromSelector(
 		if (isDone(target, downstreamSelectorKey)) {
 			continue
 		}
-		evictCachedValue(downstreamSelectorKey, target)
+		evictCachedValue(target, downstreamSelectorKey)
 		markDone(target, downstreamSelectorKey)
 	}
 }

package/src/internal/set-state/reset-atom-or-selector.ts

@@ -1,5 +1,5 @@
 import type { Atom, WritableState } from ".."
-import { traceAllSelectorAtoms } from ".."
+import { traceRootSelectorAtoms } from ".."
 import type { Store } from "../store"
 import { setAtom } from "./set-atom"
 
@@ -23,8 +23,8 @@ export function resetAtomOrSelector(
 		case `writable_pure_selector`:
 		case `writable_held_selector`:
 			{
-				const atoms = traceAllSelectorAtoms(state, store)
-				for (const atom of atoms) {
+				const atoms = traceRootSelectorAtoms(store, state.key)
+				for (const atom of atoms.values()) {
 					resetAtom(store, atom)
 				}
 			}

package/src/internal/store/store.ts

@@ -193,7 +193,6 @@ export class Store implements Lineage {
 			...config,
 		}
 		if (store !== null) {
-			this.valueMap = new Map(store?.valueMap)
 			this.operation = { ...store?.operation }
 			if (isRootStore(store)) {
 				this.transactionMeta = {

package/src/internal/subscribe/subscribe-to-root-atoms.ts

@@ -1,46 +1,50 @@
-import type { Selector } from ".."
+import type { Atom, Selector } from ".."
 import { readOrComputeValue } from "../get-state/read-or-compute-value"
-import { newest } from "../lineage"
-import { traceAllSelectorAtoms } from "../selector"
 import type { Store } from "../store"
 import { recallState } from "./recall-state"
 
-export const subscribeToRootAtoms = <T>(
-	store: Store,
-	selector: Selector<T>,
-): (() => void)[] => {
-	const target = newest(store)
-	const dependencySubscriptions = traceAllSelectorAtoms(selector, store).map(
-		(atom) => {
-			return atom.subject.subscribe(
-				`${selector.type}:${selector.key}`,
-				(atomChange) => {
-					store.logger.info(
-						`📢`,
-						selector.type,
-						selector.key,
-						`root`,
-						atom.key,
-						`went`,
-						atomChange.oldValue,
-						`->`,
-						atomChange.newValue,
-					)
-					const oldValue = recallState(target, selector)
-					const newValue = readOrComputeValue(target, selector)
-					store.logger.info(
-						`✨`,
-						selector.type,
-						selector.key,
-						`went`,
-						oldValue,
-						`->`,
-						newValue,
-					)
-					selector.subject.next({ newValue, oldValue })
-				},
+export const subscribeToRootDependency = (
+	target: Store,
+	selector: Selector<any>,
+	atom: Atom<any>,
+): (() => void) => {
+	return atom.subject.subscribe(
+		`${selector.type}:${selector.key}`,
+		(atomChange) => {
+			target.logger.info(
+				`📢`,
+				selector.type,
+				selector.key,
+				`root`,
+				atom.key,
+				`went`,
+				atomChange.oldValue,
+				`->`,
+				atomChange.newValue,
 			)
+			const oldValue = recallState(target, selector)
+			const newValue = readOrComputeValue(target, selector)
+			target.logger.info(
+				`✨`,
+				selector.type,
+				selector.key,
+				`went`,
+				oldValue,
+				`->`,
+				newValue,
+			)
+			selector.subject.next({ newValue, oldValue })
 		},
 	)
-	return dependencySubscriptions
 }
+
+// export const subscribeToRootAtoms = (
+// 	store: Store,
+// 	selector: Selector<any>,
+// ): (() => void)[] => {
+// 	const target = newest(store)
+// 	const dependencySubscriptions = traceAllSelectorAtoms(selector, store).map(
+// 		(atom) => subscribeToRootDependency(target, selector, atom),
+// 	)
+// 	return dependencySubscriptions
+// }

package/src/internal/subscribe/subscribe-to-state.ts

@@ -1,8 +1,10 @@
 import type { ReadableToken, StateUpdate, UpdateHandler } from "atom.io"
 
+import { readOrComputeValue } from "../get-state"
+import { traceRootSelectorAtoms } from "../selector"
 import type { Store } from "../store"
 import { withdraw } from "../store"
-import { subscribeToRootAtoms } from "./subscribe-to-root-atoms"
+import { subscribeToRootDependency } from "./subscribe-to-root-atoms"
 
 export function subscribeToState<T>(
 	store: Store,
@@ -28,14 +30,26 @@ export function subscribeToState<T>(
 	const isSelector =
 		state.type === `writable_pure_selector` ||
 		state.type === `readonly_pure_selector`
-	let dependencyUnsubFunctions: (() => void)[] | null = null
+	const rootSubs = new Map<string, () => void>()
 	let updateHandler: UpdateHandler<T> = safelyHandleUpdate
 	if (isSelector) {
-		dependencyUnsubFunctions = subscribeToRootAtoms(store, state)
-		updateHandler = (update) => {
-			if (dependencyUnsubFunctions) {
-				dependencyUnsubFunctions.length = 0
-				dependencyUnsubFunctions.push(...subscribeToRootAtoms(store, state))
+		readOrComputeValue(store, state)
+		for (const [atomKey, atom] of traceRootSelectorAtoms(store, state.key)) {
+			rootSubs.set(atomKey, subscribeToRootDependency(store, state, atom))
+		}
+		updateHandler = function updateRootsBeforeHandlingUpdate(update) {
+			const dependencies = traceRootSelectorAtoms(store, state.key)
+			for (const [previousRootKey, unsub] of rootSubs) {
+				const currentRoot = dependencies.get(previousRootKey)
+				if (currentRoot) {
+					dependencies.delete(previousRootKey)
+				} else {
+					unsub()
+					rootSubs.delete(previousRootKey)
+				}
+			}
+			for (const [atomKey, atom] of dependencies) {
+				rootSubs.set(atomKey, subscribeToRootDependency(store, state, atom))
 			}
 			safelyHandleUpdate(update)
 		}
@@ -49,10 +63,8 @@ export function subscribeToState<T>(
 			`Removing subscription "${key}"`,
 		)
 		mainUnsubFunction()
-		if (dependencyUnsubFunctions) {
-			for (const unsubFromDependency of dependencyUnsubFunctions) {
-				unsubFromDependency()
-			}
+		for (const unsubFromDependency of rootSubs.values()) {
+			unsubFromDependency()
 		}
 	}
 

package/src/json/index.ts

@@ -51,6 +51,9 @@ export const stringifyJson = <J extends Json.Serializable>(
 	json: J,
 ): stringified<J> => JSON.stringify(json) as stringified<J>
 
+/**
+ * Always serializes to the same string.
+ */
 export type Canonical = primitive | ReadonlyArray<Canonical>
 
 export type JsonIO = (...params: Json.Serializable[]) => Json.Serializable | void

package/src/main/atom.ts

@@ -22,7 +22,6 @@ import type { AtomToken, MutableAtomToken, RegularAtomToken, Setter } from "."
 export function atom<T extends Transceiver<any>, J extends Json.Serializable>(
 	options: MutableAtomOptions<T, J>,
 ): MutableAtomToken<T, J>
-
 /**
  * @public
  * Create a regular atom, a global reactive variable in the implicit store
@@ -71,14 +70,24 @@ export type RegularAtomOptions<T> = {
 	/** Hooks used to run side effects when the atom is set */
 	effects?: AtomEffect<T>[]
 }
-// biome-ignore format: complex intersection
-export type MutableAtomOptions<T extends Transceiver<any>, J extends Json.Serializable> = 
+
+/** @public */
+// biome-ignore format: intersection
+export type MutableAtomOptions<
+	T extends Transceiver<any>,
+	J extends Json.Serializable,
+> = 
 	& JsonInterface<T, J>
-	& Omit<RegularAtomOptions<T>, `default`> 
-	& { 
-			default: ()	=> T
-			mutable: true
-		}
+	& {
+		/** Used to signal that the atom is mutable */
+		mutable: true
+		/** The unique identifier of the atom */
+		key: string
+		/** A function to create an initial value for the atom */
+		default: () => T
+		/** Hooks used to run side effects when the atom is set */
+		effects?: AtomEffect<T>[]
+	}
 
 /** @public */
 export type RegularAtomFamilyOptions<T, K extends Canonical> = {
@@ -91,24 +100,33 @@ export type RegularAtomFamilyOptions<T, K extends Canonical> = {
 }
 
 export type RegularAtomFamilyToken<T, K extends Canonical> = {
+	/** The unique identifier of the atom family */
 	key: string
+	/** Discriminator */
 	type: `atom_family`
+	/** Never present. This is a marker that preserves the type of atoms in this family */
 	__T?: T
+	/** Never present. This is a marker that preserves the type of keys used for atoms in this family */
 	__K?: K
 }
 
+/** @public */
 // biome-ignore format: intersection
 export type MutableAtomFamilyOptions<
 	T extends Transceiver<any>,
 	J extends Json.Serializable,
 	K extends Canonical,
-> = 
-	& JsonInterface<T, J>
-	& { 
+> =
+	& JsonInterface<T, J> 
+	& {
+		/** Used to signal that the atoms created from this family are mutable */
+		mutable: true
+		/** The unique identifier of the atom family */
 		key: string
+		/** A function to create an initial value for each atom in the family */
 		default: (key: K) => T
+		/** Hooks used to run side effects when an atom in the family is set  */
 		effects?: (key: K) => AtomEffect<T>[]
-		mutable: true,
 	}
 
 export type MutableAtomFamilyToken<
@@ -116,22 +134,45 @@ export type MutableAtomFamilyToken<
 	J extends Json.Serializable,
 	K extends Canonical,
 > = {
+	/** The unique identifier of the atom family */
 	key: string
+	/** Discriminator */
 	type: `mutable_atom_family`
+	/** Never present. This is a marker that preserves the type of atoms in this family */
 	__T?: T
+	/** Never present. This is a marker that preserves the type of the JSON form of atoms in this family */
 	__J?: J
+	/** Never present. This is a marker that preserves the type of keys used for atoms in this family */
 	__K?: K
 }
-
 export type AtomFamilyToken<T, K extends Canonical = Canonical> =
 	| MutableAtomFamilyToken<T extends Transceiver<any> ? T : never, any, K>
 	| RegularAtomFamilyToken<T, K>
 
+/**
+ * @public
+ * Create a family of mutable atoms, allowing for the dynamic creation and disposal of atoms.
+ *
+ * The value of a mutable atom must be some kind of {@link Transceiver}.
+ *
+ * @param options - {@link MutableAtomFamilyOptions}
+ * @returns
+ * A reference to the atom family created: a {@link MutableAtomFamilyToken}
+ * @overload Mutable
+ */
 export function atomFamily<
 	T extends Transceiver<any>,
 	J extends Json.Serializable,
 	K extends Canonical,
 >(options: MutableAtomFamilyOptions<T, J, K>): MutableAtomFamilyToken<T, J, K>
+/**
+ * @public
+ * Create a family of regular atoms, allowing for the dynamic creation and disposal of atoms.
+ * @param options - {@link RegularAtomFamilyOptions}
+ * @returns
+ * A reference to the atom family created: a {@link RegularAtomFamilyToken}
+ * @overload Regular
+ */
 export function atomFamily<T, K extends Canonical>(
 	options: RegularAtomFamilyOptions<T, K>,
 ): RegularAtomFamilyToken<T, K>

package/src/main/dispose-state.ts

@@ -5,14 +5,20 @@ import type { ReadableFamilyToken, ReadableToken } from "."
 
 /**
  * @public
- * Disposes of a state in the implicit store
+ * Disposes of a state in the implicit store.
+ *
+ * Only family members can be disposed of.
+ *
  * @param token - The token of the state to dispose
  * @overload Default
  */
 export function disposeState(token: ReadableToken<any>): void
 /**
  * @public
- * Disposes of a state family in the implicit store
+ * Disposes of a state in the implicit store.
+ *
+ * Only family members can be disposed of.
+ *
  * @param token - The token of the state family to dispose
  * @param key - The unique key of the state to dispose
  */