atom.io 0.27.4 → 0.28.0

package/internal/src/families/create-regular-atom-family.ts

@@ -10,16 +10,15 @@ import type {
 import type { Canonical } from "atom.io/json"
 import { stringifyJson } from "atom.io/json"
 
-import type { RegularAtomFamily } from ".."
+import { prettyPrintTokenType, type RegularAtomFamily } from ".."
 import { createRegularAtom } from "../atom"
 import { newest } from "../lineage"
 import type { Store } from "../store"
 import { Subject } from "../subject"
-import { throwInCaseOfConflictingFamily } from "./throw-in-case-of-conflicting-family"
 
 export function createRegularAtomFamily<T, K extends Canonical>(
-	options: RegularAtomFamilyOptions<T, K>,
 	store: Store,
+	options: RegularAtomFamilyOptions<T, K>,
 	internalRoles?: string[],
 ): RegularAtomFamilyToken<T, K> {
 	const familyToken = {
@@ -27,7 +26,17 @@ export function createRegularAtomFamily<T, K extends Canonical>(
 		type: `atom_family`,
 	} as const satisfies RegularAtomFamilyToken<T, K>
 
-	throwInCaseOfConflictingFamily(familyToken, store)
+	const existing = store.families.get(options.key)
+	if (existing) {
+		store.logger.error(
+			`❗`,
+			`atom_family`,
+			options.key,
+			`Overwriting an existing ${prettyPrintTokenType(
+				existing,
+			)} "${existing.key}" in store "${store.config.name}". You can safely ignore this warning if it is due to hot module replacement.`,
+		)
+	}
 
 	const subject = new Subject<
 		StateCreation<RegularAtomToken<T>> | StateDisposal<RegularAtomToken<T>>
@@ -48,7 +57,7 @@ export function createRegularAtomFamily<T, K extends Canonical>(
 			individualOptions.effects = options.effects(key)
 		}
 
-		const token = createRegularAtom(individualOptions, family, target)
+		const token = createRegularAtom(target, individualOptions, family)
 
 		subject.next({ type: `state_creation`, token })
 		return token
@@ -56,7 +65,7 @@ export function createRegularAtomFamily<T, K extends Canonical>(
 
 	const atomFamily = Object.assign(familyFunction, familyToken, {
 		subject,
-		install: (s: Store) => createRegularAtomFamily(options, s),
+		install: (s: Store) => createRegularAtomFamily(s, options),
 		internalRoles,
 	}) satisfies RegularAtomFamily<T, K>
 

package/internal/src/families/create-selector-family.ts

@@ -12,23 +12,23 @@ import { createReadonlySelectorFamily } from "./create-readonly-selector-family"
 import { createWritableSelectorFamily } from "./create-writable-selector-family"
 
 export function createSelectorFamily<T, K extends Canonical>(
-	options: WritableSelectorFamilyOptions<T, K>,
 	store: Store,
+	options: WritableSelectorFamilyOptions<T, K>,
 ): WritableSelectorFamilyToken<T, K>
 export function createSelectorFamily<T, K extends Canonical>(
-	options: ReadonlySelectorFamilyOptions<T, K>,
 	store: Store,
+	options: ReadonlySelectorFamilyOptions<T, K>,
 ): ReadonlySelectorFamilyToken<T, K>
 export function createSelectorFamily<T, K extends Canonical>(
+	store: Store,
 	options:
 		| ReadonlySelectorFamilyOptions<T, K>
 		| WritableSelectorFamilyOptions<T, K>,
-	store: Store,
 ): SelectorFamilyToken<T, K> {
 	const isWritable = `set` in options
 
 	if (isWritable) {
-		return createWritableSelectorFamily(options, store)
+		return createWritableSelectorFamily(store, options)
 	}
-	return createReadonlySelectorFamily(options, store)
+	return createReadonlySelectorFamily(store, options)
 }

package/internal/src/families/create-writable-selector-family.ts

@@ -1,5 +1,6 @@
 import type {
 	FamilyMetadata,
+	getState,
 	StateCreation,
 	StateDisposal,
 	WritableSelectorFamilyOptions,
@@ -15,6 +16,7 @@ import {
 	findInStore,
 	getFromStore,
 	getJsonToken,
+	prettyPrintTokenType,
 	seekInStore,
 	type WritableSelectorFamily,
 } from ".."
@@ -22,11 +24,10 @@ import { newest } from "../lineage"
 import { createWritableSelector } from "../selector"
 import type { Store } from "../store"
 import { Subject } from "../subject"
-import { throwInCaseOfConflictingFamily } from "./throw-in-case-of-conflicting-family"
 
 export function createWritableSelectorFamily<T, K extends Canonical>(
-	options: WritableSelectorFamilyOptions<T, K>,
 	store: Store,
+	options: WritableSelectorFamilyOptions<T, K>,
 	internalRoles?: string[],
 ): WritableSelectorFamilyToken<T, K> {
 	const familyToken = {
@@ -34,8 +35,17 @@ export function createWritableSelectorFamily<T, K extends Canonical>(
 		type: `selector_family`,
 	} as const satisfies WritableSelectorFamilyToken<T, K>
 
-	throwInCaseOfConflictingFamily(familyToken, store)
-
+	const existing = store.families.get(options.key)
+	if (existing) {
+		store.logger.error(
+			`❗`,
+			`selector_family`,
+			options.key,
+			`Overwriting an existing ${prettyPrintTokenType(
+				existing,
+			)} "${existing.key}" in store "${store.config.name}". You can safely ignore this warning if it is due to hot module replacement.`,
+		)
+	}
 	const subject = new Subject<
 		| StateCreation<WritableSelectorToken<T>>
 		| StateDisposal<WritableSelectorToken<T>>
@@ -48,13 +58,13 @@ export function createWritableSelectorFamily<T, K extends Canonical>(
 		const target = newest(store)
 
 		const token = createWritableSelector(
+			target,
 			{
 				key: fullKey,
 				get: options.get(key),
 				set: options.set(key),
 			},
 			family,
-			target,
 		)
 
 		subject.next({ type: `state_creation`, token })
@@ -64,14 +74,14 @@ export function createWritableSelectorFamily<T, K extends Canonical>(
 	const selectorFamily = Object.assign(familyFunction, familyToken, {
 		internalRoles,
 		subject,
-		install: (s: Store) => createWritableSelectorFamily(options, s),
+		install: (s: Store) => createWritableSelectorFamily(s, options),
 		default: (key: K) => {
 			const getFn = options.get(key)
 			return getFn({
-				get: (...params: [any]) => getFromStore(...params, store), // TODO: make store zero-arg
-				find: ((token, k) => findInStore(token, k, store)) as typeof findState,
-				seek: ((token, k) => seekInStore(token, k, store)) as typeof seekState,
-				json: (token) => getJsonToken(token, store),
+				get: ((...ps: [any]) => getFromStore(store, ...ps)) as typeof getState,
+				find: ((token, k) => findInStore(store, token, k)) as typeof findState,
+				seek: ((token, k) => seekInStore(store, token, k)) as typeof seekState,
+				json: (token) => getJsonToken(store, token),
 			})
 		},
 	}) satisfies WritableSelectorFamily<T, K>

package/internal/src/families/dispose-from-store.ts

@@ -6,68 +6,75 @@ import type {
 	ReadableFamilyToken,
 	ReadableToken,
 } from "atom.io"
-import { type Canonical, stringifyJson } from "atom.io/json"
+import type { Canonical } from "atom.io/json"
 
 import { disposeAtom } from "../atom"
 import { disposeMolecule } from "../molecule/dispose-molecule"
-import { NotFoundError } from "../not-found-error"
 import { disposeSelector } from "../selector"
-import type { Store } from "../store"
+import { counterfeit, type Store, withdraw } from "../store"
 import { findInStore } from "./find-in-store"
 import { seekInStore } from "./seek-in-store"
 
 export function disposeFromStore(
-	token: MoleculeToken<any> | ReadableToken<any>,
 	store: Store,
+	token: MoleculeToken<any> | ReadableToken<any>,
 ): void
 
 export function disposeFromStore<K extends Canonical>(
+	store: Store,
 	token: ReadableFamilyToken<any, K>,
 	key: K,
-	store: Store,
 ): void
 
 export function disposeFromStore<M extends MoleculeConstructor>(
+	store: Store,
 	token: MoleculeFamilyToken<M>,
 	key: MoleculeKey<M>,
-	store: Store,
 ): void
 
 export function disposeFromStore(
+	store: Store,
 	...params:
-		| [token: MoleculeFamilyToken<any>, key: MoleculeKey<any>, store: Store]
-		| [token: MoleculeToken<any> | ReadableToken<any>, store: Store]
-		| [token: ReadableFamilyToken<any, any>, key: Canonical, store: Store]
+		| [token: MoleculeFamilyToken<any>, key: MoleculeKey<any>]
+		| [token: MoleculeToken<any> | ReadableToken<any>]
+		| [token: ReadableFamilyToken<any, any>, key: Canonical]
 ): void {
 	let token: MoleculeToken<any> | ReadableToken<any>
-	let store: Store
-	if (params.length === 2) {
+	let fullKey: string
+	if (params.length === 1) {
 		token = params[0]
-		store = params[1]
+		fullKey = token.key
 	} else {
 		const family = params[0]
 		const key = params[1]
-		store = params[2]
 		const maybeToken =
 			family.type === `molecule_family`
-				? seekInStore(family, key, store)
-				: store.config.lifespan === `immortal`
-					? seekInStore(family, key, store)
-					: findInStore(family, key, store)
-		if (!maybeToken) {
-			store.logger.error(
-				`❗`,
-				family.type,
-				family.key,
-				`tried to dispose of member`,
-				stringifyJson(key),
-				`but it was not found in store`,
-				store.config.name,
-			)
-			return
-		}
+				? seekInStore(store, family, key) ?? counterfeit(family, key)
+				: findInStore(store, family, key)
 		token = maybeToken
 	}
+	try {
+		withdraw(token, store)
+	} catch (thrown) {
+		const disposal = store.disposalTraces.buffer.find(
+			(item) => item?.key === token.key,
+		)
+		console.log(
+			`seeking disposal trace for`,
+			token,
+			store.disposalTraces.buffer.filter(Boolean),
+		)
+		store.logger.error(
+			`❌`,
+			token.type,
+			token.key,
+			`could not be disposed because it was not found in the store "${store.config.name}".`,
+			disposal
+				? `\n   This state was most recently disposed\n${disposal.trace}`
+				: `No previous disposal trace was found.`,
+		)
+		return
+	}
 	switch (token.type) {
 		case `atom`:
 		case `mutable_atom`:
@@ -81,4 +88,11 @@ export function disposeFromStore(
 			disposeMolecule(token, store)
 			break
 	}
+
+	const { stack } = new Error()
+	if (stack) {
+		const trace = stack?.split(`\n`)?.slice(3)?.join(`\n`)
+		store.disposalTraces.add({ key: token.key, trace })
+		console.log(`added`, token)
+	}
 }

package/internal/src/families/find-in-store.ts

@@ -16,10 +16,11 @@ import type {
 	WritableSelectorToken,
 	WritableToken,
 } from "atom.io"
-import type { Canonical, Json } from "atom.io/json"
+import { type Canonical, type Json, stringifyJson } from "atom.io/json"
 
+import { growMoleculeInStore } from "../molecule"
 import type { Transceiver } from "../mutable"
-import type { Store } from "../store"
+import { counterfeit, type Store } from "../store"
 import { initFamilyMemberInStore } from "./init-family-member"
 import { seekInStore } from "./seek-in-store"
 
@@ -29,67 +30,76 @@ export function findInStore<
 	K extends Canonical,
 	Key extends K,
 >(
+	store: Store,
 	token: MutableAtomFamilyToken<T, J, K>,
 	key: Key,
-	store: Store,
 ): MutableAtomToken<T, J>
 
 export function findInStore<T, K extends Canonical, Key extends K>(
+	store: Store,
 	token: RegularAtomFamilyToken<T, K>,
 	key: Key,
-	store: Store,
 ): RegularAtomToken<T>
 
 export function findInStore<T, K extends Canonical, Key extends K>(
+	store: Store,
 	token: AtomFamilyToken<T, K>,
 	key: Key,
-	store: Store,
 ): AtomToken<T>
 
 export function findInStore<T, K extends Canonical, Key extends K>(
+	store: Store,
 	token: WritableSelectorFamilyToken<T, K>,
 	key: Key,
-	store: Store,
 ): WritableSelectorToken<T>
 
 export function findInStore<T, K extends Canonical, Key extends K>(
+	store: Store,
 	token: ReadonlySelectorFamilyToken<T, K>,
 	key: Key,
-	store: Store,
 ): ReadonlySelectorToken<T>
 
 export function findInStore<T, K extends Canonical, Key extends K>(
+	store: Store,
 	token: SelectorFamilyToken<T, K>,
 	key: Key,
-	store: Store,
 ): SelectorToken<T>
 
 export function findInStore<T, K extends Canonical, Key extends K>(
+	store: Store,
 	token: WritableFamilyToken<T, K>,
 	key: Key,
-	store: Store,
 ): WritableToken<T>
 
 export function findInStore<T, K extends Canonical, Key extends K>(
+	store: Store,
 	token: ReadableFamilyToken<T, K>,
 	key: Key,
-	store: Store,
 ): ReadableToken<T>
 
 export function findInStore(
+	store: Store,
 	token: ReadableFamilyToken<any, any>,
 	key: Json.Serializable,
-	store: Store,
 ): ReadableToken<any> {
-	if (store.config.lifespan === `immortal`) {
-		throw new Error(
-			`Do not use \`find\` or \`findState\` in an immortal store. Prefer \`seek\` or \`seekState\`.`,
-		)
-	}
-	let state = seekInStore(token, key, store)
+	let state = seekInStore(store, token, key)
 	if (state) {
 		return state
 	}
-	state = initFamilyMemberInStore(token, key, store)
+	const molecule = store.molecules.get(stringifyJson(key))
+	if (molecule) {
+		return growMoleculeInStore(molecule, token, store)
+	}
+	if (store.config.lifespan === `immortal`) {
+		const fakeToken = counterfeit(token, key)
+		store.logger.error(
+			`❌`,
+			fakeToken.type,
+			fakeToken.key,
+			`was not found in store "${store.config.name}"; returned a counterfeit token.`,
+		)
+		return fakeToken
+	}
+	state = initFamilyMemberInStore(store, token, key)
 	return state
 }

package/internal/src/families/init-family-member.ts

@@ -30,57 +30,57 @@ export function initFamilyMemberInStore<
 	K extends Canonical,
 	Key extends K,
 >(
+	store: Store,
 	token: MutableAtomFamilyToken<T, J, K>,
 	key: Key,
-	store: Store,
 ): MutableAtomToken<T, J>
 
 export function initFamilyMemberInStore<T, K extends Canonical, Key extends K>(
+	store: Store,
 	token: RegularAtomFamilyToken<T, K>,
 	key: Key,
-	store: Store,
 ): RegularAtomToken<T>
 
 export function initFamilyMemberInStore<T, K extends Canonical, Key extends K>(
+	store: Store,
 	token: AtomFamilyToken<T, K>,
 	key: Key,
-	store: Store,
 ): AtomToken<T>
 
 export function initFamilyMemberInStore<T, K extends Canonical, Key extends K>(
+	store: Store,
 	token: WritableSelectorFamilyToken<T, K>,
 	key: Key,
-	store: Store,
 ): WritableSelectorToken<T>
 
 export function initFamilyMemberInStore<T, K extends Canonical, Key extends K>(
+	store: Store,
 	token: ReadonlySelectorFamilyToken<T, K>,
 	key: Key,
-	store: Store,
 ): ReadonlySelectorToken<T>
 
 export function initFamilyMemberInStore<T, K extends Canonical, Key extends K>(
+	store: Store,
 	token: SelectorFamilyToken<T, K>,
 	key: Key,
-	store: Store,
 ): SelectorToken<T>
 
 export function initFamilyMemberInStore<T, K extends Canonical, Key extends K>(
+	store: Store,
 	token: WritableFamilyToken<T, K>,
 	key: Key,
-	store: Store,
 ): WritableToken<T>
 
 export function initFamilyMemberInStore<T, K extends Canonical, Key extends K>(
+	store: Store,
 	token: ReadableFamilyToken<T, K>,
 	key: Key,
-	store: Store,
 ): ReadableToken<T>
 
 export function initFamilyMemberInStore(
+	store: Store,
 	token: ReadableFamilyToken<any, any>,
 	key: Json.Serializable,
-	store: Store,
 ): ReadableToken<any> {
 	const familyKey = token.key
 	const family = store.families.get(familyKey)

package/internal/src/families/seek-in-store.ts

@@ -34,63 +34,63 @@ export function seekInStore<
 	K extends Canonical,
 	Key extends K,
 >(
+	store: Store,
 	token: MutableAtomFamilyToken<T, J, K>,
 	key: Key,
-	store: Store,
 ): MutableAtomToken<T, J> | undefined
 
 export function seekInStore<T, K extends Canonical, Key extends K>(
+	store: Store,
 	token: RegularAtomFamilyToken<T, K>,
 	key: Key,
-	store: Store,
 ): RegularAtomToken<T> | undefined
 
 export function seekInStore<T, K extends Canonical, Key extends K>(
+	store: Store,
 	token: AtomFamilyToken<T, K>,
 	key: Key,
-	store: Store,
 ): AtomToken<T> | undefined
 
 export function seekInStore<T, K extends Canonical, Key extends K>(
+	store: Store,
 	token: WritableSelectorFamilyToken<T, K>,
 	key: Key,
-	store: Store,
 ): WritableSelectorToken<T> | undefined
 
 export function seekInStore<T, K extends Canonical, Key extends K>(
+	store: Store,
 	token: ReadonlySelectorFamilyToken<T, K>,
 	key: Key,
-	store: Store,
 ): ReadonlySelectorToken<T> | undefined
 
 export function seekInStore<T, K extends Canonical, Key extends K>(
+	store: Store,
 	token: SelectorFamilyToken<T, K>,
 	key: Key,
-	store: Store,
 ): SelectorToken<T> | undefined
 
 export function seekInStore<T, K extends Canonical, Key extends K>(
+	store: Store,
 	token: WritableFamilyToken<T, K>,
 	key: Key,
-	store: Store,
 ): WritableToken<T> | undefined
 
 export function seekInStore<T, K extends Canonical, Key extends K>(
+	store: Store,
 	token: ReadableFamilyToken<T, K>,
 	key: Key,
-	store: Store,
 ): ReadableToken<T> | undefined
 
 export function seekInStore<M extends MoleculeConstructor>(
+	store: Store,
 	token: MoleculeFamilyToken<M>,
 	key: MoleculeKey<M>,
-	store: Store,
 ): MoleculeKey<M> | undefined
 
 export function seekInStore(
+	store: Store,
 	token: MoleculeFamilyToken<any> | ReadableFamilyToken<any, any>,
 	key: Canonical,
-	store: Store,
 ): MoleculeToken<any> | ReadableToken<any> | undefined {
 	const subKey = stringifyJson(key)
 	const fullKey = `${token.key}(${subKey})`

package/internal/src/get-state/get-from-store.ts

@@ -11,78 +11,101 @@ import { type Canonical, stringifyJson } from "atom.io/json"
 import { findInStore, seekInStore } from "../families"
 import { NotFoundError } from "../not-found-error"
 import type { Store } from "../store"
-import { withdraw } from "../store"
+import { counterfeit, withdraw } from "../store"
 import { readOrComputeValue } from "./read-or-compute-value"
 
-export function getFromStore<T>(token: ReadableToken<T>, store: Store): T
+export function getFromStore<T>(store: Store, token: ReadableToken<T>): T
 
 export function getFromStore<M extends MoleculeConstructor>(
-	token: MoleculeToken<M>,
 	store: Store,
-): InstanceType<M> | undefined
+	token: MoleculeToken<M>,
+): InstanceType<M>
 
 export function getFromStore<T, K extends Canonical>(
+	store: Store,
 	token: ReadableFamilyToken<T, K>,
 	key: K,
-	store: Store,
 ): T
 
 export function getFromStore<M extends MoleculeConstructor>(
+	store: Store,
 	token: MoleculeFamilyToken<M>,
 	key: MoleculeKey<M>,
-	store: Store,
 ): InstanceType<M>
 
-export function getFromStore<T>(
+export function getFromStore(
+	store: Store,
+	token: MoleculeToken<any> | ReadableToken<any>,
+): any
+
+export function getFromStore(
+	store: Store,
+	token: MoleculeFamilyToken<any> | ReadableFamilyToken<any, any>,
+	key: Canonical,
+): any
+
+export function getFromStore(
+	store: Store,
 	...params:
-		| [token: MoleculeFamilyToken<any>, key: MoleculeKey<any>, store: Store]
-		| [token: MoleculeToken<any>, store: Store]
-		| [token: ReadableFamilyToken<T, any>, key: Canonical, store: Store]
-		| [token: ReadableToken<T>, store: Store]
+		| [
+				token: MoleculeFamilyToken<any> | ReadableFamilyToken<any, any>,
+				key: Canonical,
+		  ]
+		| [token: MoleculeFamilyToken<any>, key: MoleculeKey<any>]
+		| [token: MoleculeToken<any> | ReadableToken<any>]
+		| [token: MoleculeToken<any>]
+		| [token: ReadableFamilyToken<any, any>, key: Canonical]
+		| [token: ReadableToken<any>]
 ): any {
-	let token: MoleculeToken<any> | ReadableToken<T>
-	let store: Store
-	if (params.length === 2) {
+	let token: MoleculeToken<any> | ReadableToken<any>
+	if (params.length === 1) {
 		token = params[0]
-		store = params[1]
 	} else {
 		const family = params[0]
 		const key = params[1]
-		store = params[2]
-		const maybeToken =
-			family.type === `molecule_family`
-				? seekInStore(family, key, store)
-				: store.config.lifespan === `immortal`
-					? seekInStore(family, key, store)
-					: findInStore(family, key, store)
-		if (!maybeToken) {
-			store.logger.error(
-				`❗`,
-				family.type,
-				family.key,
-				`tried to get member`,
-				stringifyJson(key),
-				`but it was not found in store`,
-				store.config.name,
-			)
-			switch (family.type) {
-				case `atom_family`:
-				case `mutable_atom_family`:
-					return store.defaults.get(family.key)
-				case `selector_family`:
-				case `readonly_selector_family`: {
-					if (store.defaults.has(family.key)) {
-						return store.defaults.get(family.key)
-					}
-					const defaultValue = withdraw(family, store).default(key)
-					store.defaults.set(family.key, defaultValue)
-					return defaultValue
+		let maybeToken: MoleculeToken<any> | ReadableToken<any>
+		if (family.type === `molecule_family`) {
+			maybeToken = seekInStore(store, family, key) ?? counterfeit(family, key)
+		} else {
+			maybeToken = findInStore(store, family, key)
+		}
+		token = maybeToken
+	}
+	if (`counterfeit` in token && `family` in token) {
+		const family =
+			token.type === `molecule`
+				? withdraw(token.family, store)
+				: // biome-ignore lint/style/noNonNullAssertion: family must be present
+					store.families.get(token.family.key)!
+		const subKey = token.type === `molecule` ? token.key : token.family.subKey
+		const disposal = store.disposalTraces.buffer.find(
+			(item) => item?.key === token.key,
+		)
+		store.logger.error(
+			`❌`,
+			token.type,
+			token.key,
+			`could not be retrieved because it was not found in the store "${store.config.name}".`,
+			disposal
+				? `This state was previously disposed:\n${disposal.trace}`
+				: `No previous disposal trace was found.`,
+		)
+		switch (family.type) {
+			case `atom_family`:
+			case `mutable_atom_family`:
+				return store.defaults.get(family.key)
+			case `selector_family`:
+			case `readonly_selector_family`: {
+				if (store.defaults.has(family.key)) {
+					return store.defaults.get(token.family.key)
 				}
-				case `molecule_family`:
-					throw new NotFoundError(family, key, store)
+				const defaultValue = withdraw(family, store).default(subKey)
+				store.defaults.set(family.key, defaultValue)
+				return defaultValue
 			}
+			case `molecule_family`:
+				throw new NotFoundError(family, subKey, store)
 		}
-		token = maybeToken
 	}
 	switch (token.type) {
 		case `atom`: