atom.io 0.36.3 → 0.37.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "atom.io",
-  "version": "0.36.3",
+  "version": "0.37.1",
   "description": "Composable and testable reactive data library.",
   "homepage": "https://atom.io.fyi",
   "sideEffects": false,
@@ -72,9 +72,9 @@
     "@types/npmlog": "7.0.0",
     "@types/react": "19.1.10",
     "@types/tmp": "0.2.6",
-    "@typescript-eslint/parser": "8.39.1",
-    "@typescript-eslint/rule-tester": "8.39.1",
-    "@typescript-eslint/utils": "8.39.1",
+    "@typescript-eslint/parser": "8.40.0",
+    "@typescript-eslint/rule-tester": "8.40.0",
+    "@typescript-eslint/utils": "8.40.0",
     "@vitest/coverage-v8": "3.2.4",
     "@vitest/ui": "3.2.4",
     "concurrently": "9.2.0",
@@ -87,7 +87,7 @@
     "npmlog": "7.0.1",
     "nyc": "17.1.0",
     "postgres": "3.4.7",
-    "preact": "10.27.0",
+    "preact": "10.27.1",
     "react": "19.1.1",
     "react-dom": "19.1.1",
     "react-router-dom": "7.8.1",
@@ -99,7 +99,7 @@
     "tsdown": "0.14.1",
     "tsx": "4.20.4",
     "typescript": "5.9.2",
-    "vite": "7.1.2",
+    "vite": "7.1.3",
     "vite-tsconfig-paths": "5.1.4",
     "vitest": "3.2.4",
     "zod": "3.25.76",

package/src/internal/atom/dispose-atom.ts

@@ -1,9 +1,10 @@
-import type { AtomDisposal, AtomToken } from "atom.io"
+import type { AtomDisposalEvent, AtomToken, StateLifecycleEvent } from "atom.io"
 
-import type { Store } from ".."
+import type { Store, Subject } from ".."
 import { getUpdateToken, isChildStore, newest, withdraw } from ".."
+import { getFamilyOfToken } from "../families/get-family-of-token"
 
-export function disposeAtom(store: Store, atomToken: AtomToken<unknown>): void {
+export function disposeAtom(store: Store, atomToken: AtomToken<any>): void {
 	const target = newest(store)
 	const { key, family } = atomToken
 	const atom = withdraw(target, atomToken)
@@ -12,16 +13,22 @@ export function disposeAtom(store: Store, atomToken: AtomToken<unknown>): void {
 	} else {
 		atom.cleanup?.()
 		const lastValue = store.valueMap.get(atom.key)
-		const atomFamily = withdraw(store, { key: family.key, type: `atom_family` })
-
-		const disposal: AtomDisposal<AtomToken<unknown>> = {
+		// biome-ignore lint/style/noNonNullAssertion: family has been verified
+		const familyToken = getFamilyOfToken(store, atomToken)!
+		const atomFamily = withdraw(store, familyToken)
+		const subject = atomFamily.subject as Subject<
+			StateLifecycleEvent<AtomToken<any>>
+		>
+
+		const disposal: AtomDisposalEvent<AtomToken<any>> = {
 			type: `state_disposal`,
 			subType: `atom`,
 			token: atomToken,
 			value: lastValue,
+			timestamp: Date.now(),
 		}
 
-		atomFamily.subject.next(disposal)
+		subject.next(disposal)
 
 		const isChild = isChildStore(target)
 
@@ -39,14 +46,14 @@ export function disposeAtom(store: Store, atomToken: AtomToken<unknown>): void {
 		}
 		store.logger.info(`🔥`, `atom`, key, `deleted`)
 		if (isChild && target.transactionMeta.phase === `building`) {
-			const mostRecentUpdate = target.transactionMeta.update.updates.at(-1)
+			const mostRecentUpdate = target.transactionMeta.update.subEvents.at(-1)
 			const wasMoleculeDisposal = mostRecentUpdate?.type === `molecule_disposal`
 			const updateAlreadyCaptured =
 				wasMoleculeDisposal &&
 				mostRecentUpdate.values.some(([k]) => k === atom.family?.key)
 
 			if (!updateAlreadyCaptured) {
-				target.transactionMeta.update.updates.push(disposal)
+				target.transactionMeta.update.subEvents.push(disposal)
 			}
 		} else {
 			store.on.atomDisposal.next(atomToken)

package/src/internal/caching.ts

@@ -113,7 +113,7 @@ export function evictCachedValue(target: Store, key: string): void {
 		const selector =
 			target.writableSelectors.get(key) ?? target.readonlySelectors.get(key)
 		if (selector) {
-			selector.get()
+			selector.getFrom(target)
 		}
 		return
 	}

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

@@ -3,8 +3,7 @@ import type {
 	ReadonlyHeldSelectorFamilyOptions,
 	ReadonlyHeldSelectorFamilyToken,
 	ReadonlyHeldSelectorToken,
-	StateCreation,
-	StateDisposal,
+	StateLifecycleEvent,
 } from "atom.io"
 import type { Canonical } from "atom.io/json"
 import { stringifyJson } from "atom.io/json"
@@ -45,8 +44,7 @@ export function createReadonlyHeldSelectorFamily<
 	}
 
 	const subject = new Subject<
-		| StateCreation<ReadonlyHeldSelectorToken<T>>
-		| StateDisposal<ReadonlyHeldSelectorToken<T>>
+		StateLifecycleEvent<ReadonlyHeldSelectorToken<T>>
 	>()
 
 	const familyFunction = (key: K): ReadonlyHeldSelectorToken<T> => {
@@ -65,7 +63,7 @@ export function createReadonlyHeldSelectorFamily<
 			family,
 		)
 
-		subject.next({ type: `state_creation`, token })
+		subject.next({ type: `state_creation`, token, timestamp: Date.now() })
 		return token
 	}
 

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

@@ -5,8 +5,7 @@ import type {
 	ReadonlyPureSelectorFamilyOptions,
 	ReadonlyPureSelectorFamilyToken,
 	ReadonlyPureSelectorToken,
-	StateCreation,
-	StateDisposal,
+	StateLifecycleEvent,
 } from "atom.io"
 import type { Canonical } from "atom.io/json"
 import { stringifyJson } from "atom.io/json"
@@ -49,8 +48,7 @@ export function createReadonlyPureSelectorFamily<T, K extends Canonical>(
 	}
 
 	const subject = new Subject<
-		| StateCreation<ReadonlyPureSelectorToken<T>>
-		| StateDisposal<ReadonlyPureSelectorToken<T>>
+		StateLifecycleEvent<ReadonlyPureSelectorToken<T>>
 	>()
 
 	const familyFunction = (key: K): ReadonlyPureSelectorToken<T> => {
@@ -68,7 +66,7 @@ export function createReadonlyPureSelectorFamily<T, K extends Canonical>(
 			family,
 		)
 
-		subject.next({ type: `state_creation`, token })
+		subject.next({ type: `state_creation`, token, timestamp: Date.now() })
 		return token
 	}
 

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

@@ -4,8 +4,7 @@ import type {
 	RegularAtomFamilyToken,
 	RegularAtomOptions,
 	RegularAtomToken,
-	StateCreation,
-	StateDisposal,
+	StateLifecycleEvent,
 } from "atom.io"
 import type { Canonical } from "atom.io/json"
 import { stringifyJson } from "atom.io/json"
@@ -38,9 +37,7 @@ export function createRegularAtomFamily<T, K extends Canonical>(
 		)
 	}
 
-	const subject = new Subject<
-		StateCreation<RegularAtomToken<T>> | StateDisposal<RegularAtomToken<T>>
-	>()
+	const subject = new Subject<StateLifecycleEvent<RegularAtomToken<T>>>()
 
 	const familyFunction = (key: K): RegularAtomToken<any> => {
 		const subKey = stringifyJson(key)
@@ -59,17 +56,20 @@ export function createRegularAtomFamily<T, K extends Canonical>(
 
 		const token = createRegularAtom(target, individualOptions, family)
 
-		subject.next({ type: `state_creation`, token })
+		subject.next({ type: `state_creation`, token, timestamp: Date.now() })
 		return token
 	}
 
 	const atomFamily = Object.assign(familyFunction, familyToken, {
+		default: options.default,
 		subject,
 		install: (s: Store) => createRegularAtomFamily(s, options),
 		internalRoles,
 	}) satisfies RegularAtomFamily<T, K>
 
 	store.families.set(options.key, atomFamily)
-	store.defaults.set(options.key, options.default)
+	if (options.default instanceof Function === false) {
+		store.defaults.set(options.key, options.default)
+	}
 	return familyToken
 }

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

@@ -1,7 +1,6 @@
 import type {
 	FamilyMetadata,
-	StateCreation,
-	StateDisposal,
+	StateLifecycleEvent,
 	WritableHeldSelectorFamilyOptions,
 	WritableHeldSelectorFamilyToken,
 	WritableHeldSelectorToken,
@@ -43,8 +42,7 @@ export function createWritableHeldSelectorFamily<
 		)
 	}
 	const subject = new Subject<
-		| StateCreation<WritableHeldSelectorToken<T>>
-		| StateDisposal<WritableHeldSelectorToken<T>>
+		StateLifecycleEvent<WritableHeldSelectorToken<T>>
 	>()
 
 	const familyFunction = (key: K): WritableHeldSelectorToken<T> => {
@@ -64,7 +62,7 @@ export function createWritableHeldSelectorFamily<
 			family,
 		)
 
-		subject.next({ type: `state_creation`, token })
+		subject.next({ type: `state_creation`, token, timestamp: Date.now() })
 		return token
 	}
 

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

@@ -2,8 +2,7 @@ import type {
 	FamilyMetadata,
 	findState,
 	getState,
-	StateCreation,
-	StateDisposal,
+	StateLifecycleEvent,
 	WritablePureSelectorFamilyOptions,
 	WritablePureSelectorFamilyToken,
 	WritablePureSelectorToken,
@@ -48,8 +47,7 @@ export function createWritablePureSelectorFamily<T, K extends Canonical>(
 		)
 	}
 	const subject = new Subject<
-		| StateCreation<WritablePureSelectorToken<T>>
-		| StateDisposal<WritablePureSelectorToken<T>>
+		StateLifecycleEvent<WritablePureSelectorToken<T>>
 	>()
 
 	const familyFunction = (key: K): WritablePureSelectorToken<T> => {
@@ -68,7 +66,7 @@ export function createWritablePureSelectorFamily<T, K extends Canonical>(
 			family,
 		)
 
-		subject.next({ type: `state_creation`, token })
+		subject.next({ type: `state_creation`, token, timestamp: Date.now() })
 		return token
 	}
 

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

@@ -16,12 +16,11 @@ import type {
 	WritablePureSelectorToken,
 	WritableToken,
 } from "atom.io"
-import { type Canonical, stringifyJson } from "atom.io/json"
+import type { Canonical } from "atom.io/json"
 
-import { newest } from "../lineage"
 import type { Transceiver } from "../mutable"
-import { counterfeit, type Store } from "../store"
-import { initFamilyMemberInStore } from "./init-family-member"
+import type { Store } from "../store"
+import { mintInStore } from "./mint-in-store"
 import { seekInStore } from "./seek-in-store"
 
 export function findInStore<
@@ -30,77 +29,61 @@ export function findInStore<
 	Key extends K,
 >(
 	store: Store,
-	token: MutableAtomFamilyToken<T, K>,
+	familyToken: MutableAtomFamilyToken<T, K>,
 	key: Key,
 ): MutableAtomToken<T, K>
 
 export function findInStore<T, K extends Canonical, Key extends K>(
 	store: Store,
-	token: RegularAtomFamilyToken<T, K>,
+	familyToken: RegularAtomFamilyToken<T, K>,
 	key: Key,
 ): RegularAtomToken<T, K>
 
 export function findInStore<T, K extends Canonical, Key extends K>(
 	store: Store,
-	token: AtomFamilyToken<T, K>,
+	familyToken: AtomFamilyToken<T, K>,
 	key: Key,
 ): AtomToken<T, K>
 
 export function findInStore<T, K extends Canonical, Key extends K>(
 	store: Store,
-	token: WritablePureSelectorFamilyToken<T, K>,
+	familyToken: WritablePureSelectorFamilyToken<T, K>,
 	key: Key,
 ): WritablePureSelectorToken<T, K>
 
 export function findInStore<T, K extends Canonical, Key extends K>(
 	store: Store,
-	token: ReadonlyPureSelectorFamilyToken<T, K>,
+	familyToken: ReadonlyPureSelectorFamilyToken<T, K>,
 	key: Key,
 ): ReadonlyPureSelectorToken<T, K>
 
 export function findInStore<T, K extends Canonical, Key extends K>(
 	store: Store,
-	token: SelectorFamilyToken<T, K>,
+	familyToken: SelectorFamilyToken<T, K>,
 	key: Key,
 ): SelectorToken<T, K>
 
 export function findInStore<T, K extends Canonical, Key extends K>(
 	store: Store,
-	token: WritableFamilyToken<T, K>,
+	familyToken: WritableFamilyToken<T, K>,
 	key: Key,
 ): WritableToken<T, K>
 
 export function findInStore<T, K extends Canonical, Key extends K>(
 	store: Store,
-	token: ReadableFamilyToken<T, K>,
+	familyToken: ReadableFamilyToken<T, K>,
 	key: Key,
 ): ReadableToken<T, K>
 
 export function findInStore(
 	store: Store,
-	token: ReadableFamilyToken<any, any>,
+	familyToken: ReadableFamilyToken<any, any>,
 	key: Canonical,
 ): ReadableToken<any> {
-	let state = seekInStore(store, token, key)
-	if (state) {
-		return state
+	const existingStateToken = seekInStore(store, familyToken, key)
+	if (existingStateToken) {
+		return existingStateToken
 	}
-	const stringKey = stringifyJson(key)
-	const molecule = store.molecules.get(stringKey)
-	if (!molecule && 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)
-	if (molecule) {
-		const target = newest(store)
-		target.moleculeData.set(stringKey, token.key)
-	}
-	return state
+	const newStateToken = mintInStore(store, familyToken, key)
+	return newStateToken
 }

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

@@ -1,68 +1,13 @@
 import type {
-	AtomFamilyToken,
-	AtomToken,
-	MutableAtomFamilyToken,
-	MutableAtomToken,
 	ReadableFamilyToken,
 	ReadableToken,
-	ReadonlyPureSelectorFamilyToken,
-	ReadonlyPureSelectorToken,
-	RegularAtomFamilyToken,
-	RegularAtomToken,
-	SelectorFamilyToken,
-	SelectorToken,
 	WritableFamilyToken,
-	WritablePureSelectorFamilyToken,
-	WritablePureSelectorToken,
 	WritableToken,
 } from "atom.io"
-import type { Canonical, Json } from "atom.io/json"
+import type { Canonical } from "atom.io/json"
 
-import { newest } from "../lineage"
-import type { Transceiver } from "../mutable"
-import { NotFoundError } from "../not-found-error"
 import type { Store } from "../store"
-import { isChildStore, isRootStore } from "../transaction"
-
-export function initFamilyMemberInStore<
-	T extends Transceiver<any, any, any>,
-	K extends Canonical,
-	Key extends K,
->(
-	store: Store,
-	token: MutableAtomFamilyToken<T, K>,
-	key: Key,
-): MutableAtomToken<T, K>
-
-export function initFamilyMemberInStore<T, K extends Canonical, Key extends K>(
-	store: Store,
-	token: RegularAtomFamilyToken<T, K>,
-	key: Key,
-): RegularAtomToken<T, K>
-
-export function initFamilyMemberInStore<T, K extends Canonical, Key extends K>(
-	store: Store,
-	token: AtomFamilyToken<T, K>,
-	key: Key,
-): AtomToken<T, K>
-
-export function initFamilyMemberInStore<T, K extends Canonical, Key extends K>(
-	store: Store,
-	token: WritablePureSelectorFamilyToken<T, K>,
-	key: Key,
-): WritablePureSelectorToken<T, K>
-
-export function initFamilyMemberInStore<T, K extends Canonical, Key extends K>(
-	store: Store,
-	token: ReadonlyPureSelectorFamilyToken<T, K>,
-	key: Key,
-): ReadonlyPureSelectorToken<T, K>
-
-export function initFamilyMemberInStore<T, K extends Canonical, Key extends K>(
-	store: Store,
-	token: SelectorFamilyToken<T, K>,
-	key: Key,
-): SelectorToken<T, K>
+import { withdraw } from "../store"
 
 export function initFamilyMemberInStore<T, K extends Canonical, Key extends K>(
 	store: Store,
@@ -79,37 +24,10 @@ export function initFamilyMemberInStore<T, K extends Canonical, Key extends K>(
 export function initFamilyMemberInStore(
 	store: Store,
 	token: ReadableFamilyToken<any, any>,
-	key: Json.Serializable,
+	key: Canonical,
 ): ReadableToken<any> {
-	const family = store.families.get(token.key)
-	if (family === undefined) {
-		throw new NotFoundError(token, store)
-	}
+	const family = withdraw(store, token)
 	const state = family(key)
-	const target = newest(store)
-	if (state.family) {
-		if (isRootStore(target)) {
-			switch (state.type) {
-				case `atom`:
-				case `mutable_atom`:
-					store.on.atomCreation.next(state)
-					break
-				case `writable_pure_selector`:
-				case `readonly_pure_selector`:
-				case `writable_held_selector`:
-				case `readonly_held_selector`:
-					store.on.selectorCreation.next(state)
-					break
-			}
-		} else if (
-			isChildStore(target) &&
-			target.on.transactionApplying.state === null
-		) {
-			target.transactionMeta.update.updates.push({
-				type: `state_creation`,
-				token: state,
-			})
-		}
-	}
+
 	return state
 }

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

@@ -0,0 +1,74 @@
+import type {
+	ReadableFamilyToken,
+	ReadableToken,
+	WritableFamilyToken,
+	WritableToken,
+} from "atom.io"
+import type { Canonical } from "atom.io/json"
+import { stringifyJson } from "atom.io/json"
+
+import { newest } from "../lineage"
+import type { Store } from "../store"
+import { counterfeit } from "../store"
+import { isChildStore, isRootStore } from "../transaction"
+import { initFamilyMemberInStore } from "./init-family-member"
+
+export function mintInStore<T, K extends Canonical, Key extends K>(
+	store: Store,
+	familyToken: WritableFamilyToken<T, K>,
+	key: Key,
+): WritableToken<T, K>
+export function mintInStore<T, K extends Canonical, Key extends K>(
+	store: Store,
+	familyToken: ReadableFamilyToken<T, K>,
+	key: Key,
+): ReadableToken<T, K>
+export function mintInStore<T, K extends Canonical, Key extends K>(
+	store: Store,
+	familyToken: ReadableFamilyToken<T, K>,
+	key: Key,
+): ReadableToken<T, K> {
+	const stringKey = stringifyJson(key)
+	const molecule = store.molecules.get(stringKey)
+	if (!molecule && store.config.lifespan === `immortal`) {
+		const fakeToken = counterfeit(familyToken, key)
+		store.logger.error(
+			`❌`,
+			fakeToken.type,
+			fakeToken.key,
+			`was not found in store "${store.config.name}"; returned a counterfeit token.`,
+		)
+		return fakeToken
+	}
+	const newStateToken = initFamilyMemberInStore(store, familyToken, key)
+	const target = newest(store)
+	if (newStateToken.family) {
+		if (isRootStore(target)) {
+			switch (newStateToken.type) {
+				case `atom`:
+				case `mutable_atom`:
+					store.on.atomCreation.next(newStateToken)
+					break
+				case `writable_pure_selector`:
+				case `readonly_pure_selector`:
+				case `writable_held_selector`:
+				case `readonly_held_selector`:
+					store.on.selectorCreation.next(newStateToken)
+					break
+			}
+		} else if (
+			isChildStore(target) &&
+			target.on.transactionApplying.state === null
+		) {
+			target.transactionMeta.update.subEvents.push({
+				type: `state_creation`,
+				token: newStateToken,
+				timestamp: Date.now(),
+			})
+		}
+	}
+	if (molecule) {
+		target.moleculeData.set(stringKey, familyToken.key)
+	}
+	return newStateToken
+}

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

@@ -1,5 +1,5 @@
 import type { ReadableFamilyToken, ReadableToken } from "atom.io"
-import type { Canonical } from "atom.io/json"
+import { type Canonical, parseJson } from "atom.io/json"
 
 import { findInStore } from "../families"
 import type { Store } from "../store"
@@ -47,9 +47,23 @@ export function getFromStore(
 				: `No previous disposal trace was found.`,
 		)
 		switch (family.type) {
-			case `atom_family`:
-			case `mutable_atom_family`:
-				return store.defaults.get(family.key)
+			case `mutable_atom_family`: {
+				if (store.defaults.has(family.key)) {
+					return store.defaults.get(family.key)
+				}
+				const mutableFamily = withdraw(store, family)
+				const defaultValue = new mutableFamily.class()
+				store.defaults.set(family.key, defaultValue)
+				return defaultValue
+			}
+			case `atom_family`: {
+				if (store.defaults.has(family.key)) {
+					return store.defaults.get(token.family.key)
+				}
+				const defaultValue = withdraw(store, family).default(parseJson(subKey))
+				store.defaults.set(family.key, defaultValue)
+				return defaultValue
+			}
 			case `readonly_pure_selector_family`:
 			case `writable_pure_selector_family`:
 			case `readonly_held_selector_family`:
@@ -57,8 +71,7 @@ export function getFromStore(
 				if (store.defaults.has(family.key)) {
 					return store.defaults.get(token.family.key)
 				}
-				3
-				const defaultValue = withdraw(store, family).default(subKey)
+				const defaultValue = withdraw(store, family).default(parseJson(subKey))
 				store.defaults.set(family.key, defaultValue)
 				return defaultValue
 			}

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

@@ -1,4 +1,6 @@
-import type { ReadableState, ViewOf } from ".."
+import type { ViewOf } from "atom.io"
+
+import type { ReadableState } from ".."
 import { readFromCache, writeToCache } from "../caching"
 import type { Store } from "../store"
 
@@ -27,7 +29,7 @@ export function readOrComputeValue<T>(
 		case `writable_held_selector`:
 		case `writable_pure_selector`:
 			target.logger.info(`🧮`, state.type, key, `computing value`)
-			return state.get()
+			return state.getFrom(target)
 		case `atom`: {
 			let def: T
 			if (state.default instanceof Function) {