atom.io 0.35.0 → 0.36.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "atom.io",
-  "version": "0.35.0",
+  "version": "0.36.1",
   "description": "Composable and testable reactive data library.",
   "homepage": "https://atom.io.fyi",
   "sideEffects": false,
@@ -60,12 +60,12 @@
     }
   },
   "devDependencies": {
-    "@eslint/core": "0.15.1",
+    "@eslint/core": "0.15.2",
     "@storybook/addon-docs": "9.1.1",
     "@storybook/addon-onboarding": "9.1.1",
     "@storybook/react-vite": "9.1.1",
     "@testing-library/react": "16.3.0",
-    "@types/bun": "npm:bun-types@1.2.19",
+    "@types/bun": "npm:bun-types@1.2.20",
     "@types/eslint": "9.6.1",
     "@types/estree": "1.0.8",
     "@types/http-proxy": "1.17.16",
@@ -80,7 +80,7 @@
     "concurrently": "9.2.0",
     "drizzle-kit": "0.31.4",
     "drizzle-orm": "0.44.4",
-    "eslint": "9.32.0",
+    "eslint": "9.33.0",
     "happy-dom": "18.0.1",
     "http-proxy": "1.18.1",
     "motion": "12.23.12",
@@ -95,8 +95,8 @@
     "socket.io": "4.8.1",
     "socket.io-client": "4.8.1",
     "storybook": "9.1.1",
-    "tmp": "0.2.4",
-    "tsdown": "0.13.3",
+    "tmp": "0.2.5",
+    "tsdown": "0.14.0",
     "tsx": "4.20.3",
     "typescript": "5.9.2",
     "vite": "7.1.1",

package/src/eslint-plugin/index.ts

@@ -7,7 +7,6 @@ export { Rules }
 const plugin: ESLint.Plugin = {
 	rules: {
 		"explicit-state-types": Rules.explicitStateTypes as any,
-		"synchronous-selector-dependencies": Rules.synchronousSelectorDependencies,
 	},
 } satisfies ESLint.Plugin
 

package/src/eslint-plugin/rules/explicit-state-types.ts

@@ -5,7 +5,14 @@ const createRule = ESLintUtils.RuleCreator(
 	(name) => `https://atom.io.fyi/docs/eslint-plugin#${name}`,
 )
 
-const STATE_FUNCTIONS = [`atom`, `atomFamily`, `selector`, `selectorFamily`]
+const STATE_FUNCTIONS = [
+	`atom`,
+	`atomFamily`,
+	`mutableAtom`,
+	`mutableAtomFamily`,
+	`selector`,
+	`selectorFamily`,
+]
 
 export const explicitStateTypes: ESLintUtils.RuleModule<
 	`noTypeArgument`,

package/src/eslint-plugin/rules/index.ts

@@ -1,2 +1 @@
 export * from "./explicit-state-types"
-export * from "./synchronous-selector-dependencies"

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

@@ -11,11 +11,13 @@ import type { Store } from "../store"
 import { deposit } from "../store"
 import { Subject } from "../subject"
 import { subscribeToState } from "../subscribe"
+import type { internalRole } from "./has-role"
 
 export function createRegularAtom<T>(
 	store: Store,
 	options: RegularAtomOptions<T>,
 	family: FamilyMetadata | undefined,
+	internalRoles?: internalRole[],
 ): RegularAtomToken<T> {
 	const type = `atom`
 	const { key } = options
@@ -49,12 +51,10 @@ export function createRegularAtom<T>(
 	if (family) {
 		newAtom.family = family
 	}
-	// let initialValue = def
-	// if (def instanceof Function) {
-	// 	initialValue = def()
-	// }
+	if (internalRoles) {
+		newAtom.internalRoles = internalRoles
+	}
 	target.atoms.set(key, newAtom)
-	// cacheValue(target, key, initialValue, subject)
 	const token = deposit(newAtom)
 	if (options.effects) {
 		let effectIndex = 0

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

@@ -29,6 +29,7 @@ export function disposeAtom(store: Store, atomToken: AtomToken<unknown>): void {
 		target.valueMap.delete(key)
 		target.selectorAtoms.delete(key)
 		target.atomsThatAreDefault.delete(key)
+		target.moleculeData.delete(family.key, family.subKey)
 		store.timelineTopics.delete(key)
 
 		if (atomToken.type === `mutable_atom`) {

package/src/internal/atom/has-role.ts

@@ -0,0 +1,12 @@
+import type { Atom } from ".."
+
+export const INTERNAL_ROLES = [`tracker:signal`] as const
+export type internalRole = (typeof INTERNAL_ROLES)[number]
+
+export function hasRole(atom: Atom<any>, role: internalRole): boolean {
+	if (`internalRoles` in atom === false) {
+		return false
+	}
+
+	return atom.internalRoles.includes(role)
+}

package/src/internal/atom/index.ts

@@ -1,2 +1,3 @@
 export * from "./create-regular-atom"
 export * from "./dispose-atom"
+export * from "./has-role"

package/src/internal/caching.ts

@@ -1,9 +1,8 @@
 import type { StateUpdate } from "atom.io"
 
-import type { ReadableState } from "."
-import { closeOperation, isChildStore, openOperation } from "."
+import type { ReadableState, Transceiver } from "."
+import { closeOperation, isChildStore, openOperation, Tracker } from "."
 import { Future } from "./future"
-import { copyMutableIfNeeded } from "./set-state/copy-mutable-if-needed"
 import {
 	evictDownStream,
 	evictDownStreamFromSelector,
@@ -11,19 +10,19 @@ import {
 import type { Store } from "./store"
 import type { Subject } from "./subject"
 
-export function cacheValue<T>(
-	store: Store,
+export function writeToCache<T>(
+	target: Store,
 	key: string,
 	value: T,
 	subject: Subject<StateUpdate<unknown>>,
 ): T
-export function cacheValue<T extends Promise<any>>(
-	store: Store,
+export function writeToCache<T extends Promise<any>>(
+	target: Store,
 	key: string,
 	value: T,
 	subject: Subject<StateUpdate<unknown>>,
-): Future<T>
-export function cacheValue<T>(
+): Future<Awaited<T>>
+export function writeToCache<T>(
 	target: Store,
 	key: string,
 	value: T,
@@ -46,7 +45,7 @@ export function cacheValue<T>(
 			.then(function handleResolvedFuture(resolved) {
 				const current = target.valueMap.get(key)
 				if (current === future) {
-					cacheValue(target, key, resolved, subject)
+					writeToCache(target, key, resolved, subject)
 					const atom = target.atoms.get(key)
 					if (atom) {
 						openOperation(target, atom)
@@ -74,21 +73,44 @@ export function cacheValue<T>(
 	return value
 }
 
-export const readCachedValue = <T>(
-	state: ReadableState<any>,
+/**
+ * @param target - the newest layer of the store
+ * @param state - the state to read from cache
+ * @param mut - whether the value is intended to be mutable
+ * @returns the state's current value
+ */
+export function readFromCache<T>(
 	target: Store,
-): T => {
+	state: ReadableState<T>,
+	mut: `mut` | undefined,
+): T {
 	target.logger.info(`📖`, state.type, state.key, `reading cached value`)
 	let value = target.valueMap.get(state.key) as T
-	if (state.type === `mutable_atom` && isChildStore(target)) {
+
+	const mayNeedToBeCopied =
+		mut === `mut` && state.type === `mutable_atom` && isChildStore(target)
+	if (mayNeedToBeCopied) {
+		const mutableAtom = state
 		const { parent } = target
-		const copiedValue = copyMutableIfNeeded(target, state, parent)
+
+		if (target.valueMap.hasOwn(mutableAtom.key)) {
+			return value
+		}
+
+		const parentValue = parent.valueMap.get(mutableAtom.key) as T &
+			Transceiver<any, any, any>
+
+		target.logger.info(`📃`, `atom`, mutableAtom.key, `copying`)
+		const jsonValue = parentValue.toJSON()
+		const copiedValue = mutableAtom.class.fromJSON(jsonValue)
+		target.valueMap.set(mutableAtom.key, copiedValue)
+		new Tracker(mutableAtom, parent)
 		value = copiedValue
 	}
 	return value
 }
 
-export const evictCachedValue = (target: Store, key: string): void => {
+export function evictCachedValue(target: Store, key: string): void {
 	const currentValue = target.valueMap.get(key)
 	if (currentValue instanceof Future) {
 		const selector =

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

@@ -16,7 +16,7 @@ import type {
 	WritablePureSelectorToken,
 	WritableToken,
 } from "atom.io"
-import { type Canonical, type Json, stringifyJson } from "atom.io/json"
+import { type Canonical, stringifyJson } from "atom.io/json"
 
 import { newest } from "../lineage"
 import type { Transceiver } from "../mutable"
@@ -25,15 +25,14 @@ import { initFamilyMemberInStore } from "./init-family-member"
 import { seekInStore } from "./seek-in-store"
 
 export function findInStore<
-	T extends Transceiver<any>,
-	J extends Json.Serializable,
+	T extends Transceiver<any, any, any>,
 	K extends Canonical,
 	Key extends K,
 >(
 	store: Store,
-	token: MutableAtomFamilyToken<T, J, K>,
+	token: MutableAtomFamilyToken<T, K>,
 	key: Key,
-): MutableAtomToken<T, J, K>
+): MutableAtomToken<T, K>
 
 export function findInStore<T, K extends Canonical, Key extends K>(
 	store: Store,

package/src/internal/families/get-family-of-token.ts

@@ -12,19 +12,18 @@ import type {
 	WritablePureSelectorToken,
 	WritableToken,
 } from "atom.io"
-import type { Canonical, Json } from "atom.io/json"
+import type { Canonical } from "atom.io/json"
 
 import type { Transceiver } from "../mutable"
 import type { Store } from "../store"
 
 export function getFamilyOfToken<
-	T extends Transceiver<any>,
-	J extends Json.Serializable,
+	T extends Transceiver<any, any, any>,
 	K extends Canonical,
 >(
 	store: Store,
-	token: MutableAtomToken<T, J, K>,
-): MutableAtomFamilyToken<T, J, K> | undefined
+	token: MutableAtomToken<T, K>,
+): MutableAtomFamilyToken<T, K> | undefined
 
 export function getFamilyOfToken<T, K extends Canonical>(
 	store: Store,

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

@@ -25,15 +25,14 @@ import type { Store } from "../store"
 import { isChildStore, isRootStore } from "../transaction"
 
 export function initFamilyMemberInStore<
-	T extends Transceiver<any>,
-	J extends Json.Serializable,
+	T extends Transceiver<any, any, any>,
 	K extends Canonical,
 	Key extends K,
 >(
 	store: Store,
-	token: MutableAtomFamilyToken<T, J, K>,
+	token: MutableAtomFamilyToken<T, K>,
 	key: Key,
-): MutableAtomToken<T, J, K>
+): MutableAtomToken<T, K>
 
 export function initFamilyMemberInStore<T, K extends Canonical, Key extends K>(
 	store: Store,

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

@@ -16,7 +16,7 @@ import type {
 	WritablePureSelectorToken,
 	WritableToken,
 } from "atom.io"
-import type { Canonical, Json } from "atom.io/json"
+import type { Canonical } from "atom.io/json"
 import { stringifyJson } from "atom.io/json"
 
 import type { Molecule, ReadableState } from ".."
@@ -25,15 +25,14 @@ import type { Transceiver } from "../mutable"
 import { deposit, type Store } from "../store"
 
 export function seekInStore<
-	T extends Transceiver<any>,
-	J extends Json.Serializable,
+	T extends Transceiver<any, any, any>,
 	K extends Canonical,
 	Key extends K,
 >(
 	store: Store,
-	token: MutableAtomFamilyToken<T, J, K>,
+	token: MutableAtomFamilyToken<T, K>,
 	key: Key,
-): MutableAtomToken<T, J, K> | undefined
+): MutableAtomToken<T, K> | undefined
 
 export function seekInStore<T, K extends Canonical, Key extends K>(
 	store: Store,

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

@@ -1,13 +1,24 @@
-import type { ReadableState } from ".."
-import { cacheValue, readCachedValue } from "../caching"
+import type { ReadableState, ViewOf } from ".."
+import { readFromCache, writeToCache } from "../caching"
 import type { Store } from "../store"
 
-export const readOrComputeValue = <T>(
+export function readOrComputeValue<T>(
 	target: Store,
 	state: ReadableState<T>,
-): T => {
+	mut?: undefined,
+): ViewOf<T>
+export function readOrComputeValue<T>(
+	target: Store,
+	state: ReadableState<T>,
+	mut: `mut`,
+): T
+export function readOrComputeValue<T>(
+	target: Store,
+	state: ReadableState<T>,
+	mut: `mut` | undefined,
+): T {
 	if (target.valueMap.has(state.key)) {
-		return readCachedValue(state, target)
+		return readFromCache(target, state, mut)
 	}
 	switch (state.type) {
 		case `readonly_held_selector`:
@@ -16,27 +27,37 @@ export const readOrComputeValue = <T>(
 		case `writable_pure_selector`:
 			target.logger.info(`🧮`, state.type, state.key, `computing value`)
 			return state.get()
-		case `atom`:
-		case `mutable_atom`: {
-			const def = state.default
-			let defaultValue: T
-			if (def instanceof Function) {
-				defaultValue = def()
+		case `atom`: {
+			let def: T
+			if (state.default instanceof Function) {
+				def = state.default()
 			} else {
-				defaultValue = def
+				def = state.default
 			}
-			const cachedValue = cacheValue(
+			const cachedValue = writeToCache(target, state.key, def, state.subject)
+			target.logger.info(
+				`💁`,
+				`atom`,
+				state.key,
+				`could not find cached value; using default`,
+				def,
+			)
+			return cachedValue
+		}
+		case `mutable_atom`: {
+			const instance = new state.class()
+			const cachedValue = writeToCache(
 				target,
 				state.key,
-				defaultValue,
+				instance,
 				state.subject,
 			)
 			target.logger.info(
 				`💁`,
-				`atom`,
+				`mutable_atom`,
 				state.key,
 				`could not find cached value; using default`,
-				defaultValue,
+				instance,
 			)
 			return cachedValue
 		}

package/src/internal/index.ts

@@ -11,14 +11,16 @@ import type {
 	RegularAtomToken,
 	StateCreation,
 	StateDisposal,
+	StateLifecycleEvent,
 	WritableHeldSelectorFamilyToken,
 	WritableHeldSelectorToken,
 	WritablePureSelectorFamilyToken,
 	WritablePureSelectorToken,
 } from "atom.io"
-import type { Canonical, Json, JsonInterface } from "atom.io/json"
+import type { Canonical } from "atom.io/json"
 
-import type { Transceiver } from "./mutable"
+import type { internalRole } from "./atom/has-role"
+import type { ConstructorOf, Transceiver } from "./mutable"
 import type { Store } from "./store"
 import type { Subject } from "./subject"
 import type { Timeline } from "./timeline"
@@ -67,22 +69,19 @@ export type RegularAtom<T> = Flat<
 		type: `atom`
 		default: T | (() => T)
 		cleanup?: () => void
+		internalRoles?: internalRole[]
 	}
 >
-export type MutableAtom<
-	T extends Transceiver<any>,
-	J extends Json.Serializable,
-> = Flat<
-	AtomIOState &
-		JsonInterface<T, J> & {
-			type: `mutable_atom`
-			default: () => T
-			cleanup?: () => void
-		}
+export type MutableAtom<T extends Transceiver<any, any, any>> = Flat<
+	AtomIOState & {
+		type: `mutable_atom`
+		class: ConstructorOf<T>
+		cleanup?: () => void
+	}
 >
 export type Atom<T> =
 	| RegularAtom<T>
-	| (T extends Transceiver<any> ? MutableAtom<T, any> : never)
+	| (T extends Transceiver<any, any, any> ? MutableAtom<T> : never)
 
 export type WritableHeldSelector<T> = Flat<
 	AtomIOState & {
@@ -141,23 +140,22 @@ export type RegularAtomFamily<T, K extends Canonical> =
 
 // biome-ignore format: intersection
 export type MutableAtomFamily<
-T extends Transceiver<any>,
-J extends Json.Serializable,
-K extends Canonical,
+	// C extends TransceiverConstructor<any,any>,
+	T extends Transceiver<any, any, any>,
+	K extends Canonical,
 > =
 	& Flat<
-		& JsonInterface<T, J>
-		& MutableAtomFamilyToken<T, J, K>
+		& MutableAtomFamilyToken<T, K>
 		& {
 				install: (store: Store) => void
 				internalRoles: string[] | undefined
-				subject: Subject<StateCreation<MutableAtomToken<T, J>> | StateDisposal<MutableAtomToken<T, J>>>
+				subject: Subject<StateLifecycleEvent<MutableAtomToken<T>>>
 			}
 	>
-	& ((key: K) => MutableAtomToken<T, J>)
+	& ((key: K) => MutableAtomToken<T>)
 
 export type AtomFamily<T, K extends Canonical = Canonical> =
-	| MutableAtomFamily<T extends Transceiver<any> ? T : never, any, K>
+	| MutableAtomFamily<T extends Transceiver<any, any, any> ? T : never, K>
 	| RegularAtomFamily<T, K>
 
 // biome-ignore format: intersection

package/src/internal/ingest-updates/ingest-creation-disposal.ts

@@ -115,25 +115,28 @@ export function ingestMoleculeTransferEvent(
 	switch (applying) {
 		case `newValue`:
 			{
-				const provenance = update.to.length === 1 ? update.to[0] : update.to
-				claimWithinStore<any, any, any>(
-					store,
-					provenance,
-					update.key,
-					`exclusive`,
-				)
+				for (const newOwner of update.to) {
+					claimWithinStore<any, any, any>(
+						store,
+						newOwner,
+						update.key,
+						update.exclusive ? `exclusive` : undefined,
+					)
+				}
 			}
 			break
 		case `oldValue`:
 			{
-				const provenance =
-					update.from.length === 1 ? update.from[0] : update.from
-				claimWithinStore<any, any, any>(
-					store,
-					provenance,
-					update.key,
-					`exclusive`,
-				)
+				let exclusivity: `exclusive` | undefined = `exclusive`
+				for (const previousOwner of update.from) {
+					claimWithinStore<any, any, any>(
+						store,
+						previousOwner,
+						update.key,
+						exclusivity,
+					)
+					exclusivity = undefined
+				}
 			}
 			break
 	}

package/src/internal/ingest-updates/ingest-selector-update.ts

@@ -1,5 +1,7 @@
+import type { TimelineManageable } from "atom.io"
+
 import type { Store } from "../store"
-import type { TimelineSelectorUpdate } from "../timeline"
+import type { TimelineAtomUpdate, TimelineSelectorUpdate } from "../timeline"
 import { ingestAtomUpdate } from "./ingest-atom-update"
 
 export function ingestSelectorUpdate(
@@ -7,10 +9,12 @@ export function ingestSelectorUpdate(
 	selectorUpdate: TimelineSelectorUpdate<any>,
 	store: Store,
 ): void {
-	const updates =
-		applying === `newValue`
-			? selectorUpdate.atomUpdates
-			: selectorUpdate.atomUpdates.toReversed()
+	let updates: Omit<TimelineAtomUpdate<TimelineManageable>, `timestamp`>[]
+	if (applying === `newValue`) {
+		updates = selectorUpdate.atomUpdates
+	} else {
+		updates = selectorUpdate.atomUpdates.toReversed()
+	}
 	for (const atomUpdate of updates) {
 		ingestAtomUpdate(applying, atomUpdate, store)
 	}

package/src/internal/join/get-internal-relations-from-store.ts

@@ -1,5 +1,5 @@
 import type { JoinToken, MutableAtomFamilyToken } from "atom.io"
-import type { SetRTX, SetRTXJson } from "atom.io/transceivers/set-rtx"
+import type { SetRTX } from "atom.io/transceivers/set-rtx"
 
 import type { Store } from "../store"
 import { getJoin } from "./get-join"
@@ -7,7 +7,7 @@ import { getJoin } from "./get-join"
 export function getInternalRelationsFromStore(
 	token: JoinToken<any, any, any, any, any, any>,
 	store: Store,
-): MutableAtomFamilyToken<SetRTX<string>, SetRTXJson<string>, string> {
+): MutableAtomFamilyToken<SetRTX<string>, string> {
 	const myJoin = getJoin(token, store)
 	const family = myJoin.core.relatedKeysAtoms
 	return family

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

@@ -14,7 +14,6 @@ import type {
 import { Anarchy } from "atom.io"
 import type { Canonical, Json, stringified } from "atom.io/json"
 import { stringifyJson } from "atom.io/json"
-import type { SetRTXJson } from "atom.io/transceivers/set-rtx"
 import { SetRTX } from "atom.io/transceivers/set-rtx"
 
 import { capitalize } from "../capitalize"
@@ -30,6 +29,7 @@ import type {
 } from "../junction"
 import { Junction } from "../junction"
 import type { Molecule } from "../molecule"
+import type { ViewOf } from "../mutable"
 import { createMutableAtomFamily, getJsonFamily, getJsonToken } from "../mutable"
 import { setIntoStore } from "../set-state"
 import type { Store } from "../store"
@@ -143,11 +143,7 @@ export class Join<
 		Content
 	>
 	public core: {
-		relatedKeysAtoms: MutableAtomFamilyToken<
-			SetRTX<string>,
-			SetRTXJson<string>,
-			string
-		>
+		relatedKeysAtoms: MutableAtomFamilyToken<SetRTX<string>, string>
 	}
 	public transact(
 		toolkit: WriterToolkit,
@@ -193,17 +189,11 @@ export class Join<
 
 		const aSide: ASide = options.between[0]
 		const bSide: BSide = options.between[1]
-		const relatedKeysAtoms = createMutableAtomFamily<
-			SetRTX<string>,
-			SetRTXJson<string>,
-			string
-		>(
+		const relatedKeysAtoms = createMutableAtomFamily<SetRTX<string>, string>(
 			store,
 			{
 				key: `${options.key}/relatedKeys`,
-				default: () => new SetRTX(),
-				fromJson: (json) => SetRTX.fromJSON(json),
-				toJson: (set) => set.toJSON(),
+				class: SetRTX,
 			},
 			[`join`, `relations`],
 		)
@@ -354,8 +344,10 @@ export class Join<
 				[`join`, `content`],
 			)
 
-			const getContent: Read<(key: string) => Content | null> = ({ get }, key) =>
-				get(contentAtoms, key)
+			const getContent: Read<(key: string) => ViewOf<Content> | null> = (
+				{ get },
+				key,
+			) => get(contentAtoms, key)
 			const setContent: Write<(key: string, content: Content) => void> = (
 				{ set },
 				key,
@@ -444,7 +436,7 @@ export class Join<
 			)
 		}
 		const createSingleEntrySelectorFamily = () =>
-			createReadonlyPureSelectorFamily<[string, Content] | null, string>(
+			createReadonlyPureSelectorFamily<[string, ViewOf<Content>] | null, string>(
 				store,
 				{
 					key: `${options.key}/singleRelatedEntry`,
@@ -467,7 +459,7 @@ export class Join<
 				[`join`, `entries`],
 			)
 		const getMultipleEntrySelectorFamily = () =>
-			createReadonlyPureSelectorFamily<[string, Content][], string>(
+			createReadonlyPureSelectorFamily<[string, ViewOf<Content>][], string>(
 				store,
 				{
 					key: `${options.key}/multipleRelatedEntries`,

package/src/internal/molecule.ts

@@ -293,6 +293,7 @@ export function claimWithinStore<
 	const transferEvent: MoleculeTransfer = {
 		type: `molecule_transfer`,
 		key: molecule.key,
+		exclusive: Boolean(exclusive),
 		from: priorProvenance,
 		to: [newProvenanceMolecule.key],
 	}