atom.io 0.31.0 → 0.32.0

package/internal/src/molecule.ts

@@ -1,7 +1,306 @@
+import type {
+	Above,
+	Claim,
+	CompoundFrom,
+	CompoundTypedKey,
+	Hierarchy,
+	MoleculeCreation,
+	MoleculeDisposal,
+	MoleculeTransfer,
+	SingularTypedKey,
+	Vassal,
+} from "atom.io"
 import type { Canonical, stringified } from "atom.io/json"
+import { parseJson, stringifyJson } from "atom.io/json"
+
+import { disposeFromStore, findInStore } from "./families"
+import { getTrace } from "./get-trace"
+import { newest } from "./lineage"
+import type { Store } from "./store"
+import { IMPLICIT } from "./store"
+import { isChildStore } from "./transaction"
 
 export type Molecule<K extends Canonical> = {
 	readonly key: K
 	readonly stringKey: stringified<K>
 	readonly dependsOn: `all` | `any`
 }
+
+export function makeRootMoleculeInStore<S extends string>(
+	key: S,
+	store: Store = IMPLICIT.STORE,
+): S {
+	const molecule = {
+		key,
+		stringKey: stringifyJson(key),
+		dependsOn: `any`,
+	} satisfies Molecule<S>
+	store.molecules.set(stringifyJson(key), molecule)
+	return key
+}
+
+export function allocateIntoStore<
+	H extends Hierarchy,
+	V extends Vassal<H>,
+	A extends Above<V, H>,
+>(
+	store: Store,
+	provenance: A,
+	key: V,
+	dependsOn: `all` | `any` = `any`,
+): Claim<V> {
+	const origin = provenance as Canonical | [Canonical, Canonical]
+	const stringKey = stringifyJson(key)
+	const invalidKeys: stringified<Canonical>[] = []
+	const target = newest(store)
+
+	if (Array.isArray(origin)) {
+		for (const formerClaim of origin) {
+			const claimString = stringifyJson(formerClaim)
+			const claim = target.molecules.get(claimString)
+			if (claim) {
+				store.moleculeGraph.set(claimString, stringKey, { source: claimString })
+			} else {
+				invalidKeys.push(claimString)
+			}
+		}
+	} else {
+		const claimString = stringifyJson(origin)
+		const claim = target.molecules.get(claimString)
+		if (claim) {
+			store.moleculeGraph.set(claimString, stringKey, { source: claimString })
+		} else {
+			invalidKeys.push(claimString)
+		}
+	}
+	if (invalidKeys.length === 0) {
+		target.molecules.set(stringKey, { key, stringKey, dependsOn })
+	}
+
+	const creationEvent: MoleculeCreation = {
+		type: `molecule_creation`,
+		key,
+		provenance: origin,
+	}
+	const isTransaction =
+		isChildStore(target) && target.transactionMeta.phase === `building`
+	if (isTransaction) {
+		target.transactionMeta.update.updates.push(creationEvent)
+	} else {
+		target.on.moleculeCreation.next(creationEvent)
+	}
+
+	for (const claim of invalidKeys) {
+		const disposal = store.disposalTraces.buffer.find(
+			(item) => item?.key === claim,
+		)
+		store.logger.error(
+			`❌`,
+			`molecule`,
+			key,
+			`allocation failed:`,
+			`Could not allocate to ${claim} in store "${store.config.name}".`,
+			disposal
+				? `\n   ${claim} was most recently disposed\n${disposal.trace}`
+				: `No previous disposal trace for ${claim} was found.`,
+		)
+	}
+
+	return key as Claim<V>
+}
+
+export function fuseWithinStore<
+	H extends Hierarchy,
+	C extends CompoundFrom<H>,
+	T extends C extends CompoundTypedKey<infer t, any, any> ? t : never,
+	A extends C extends CompoundTypedKey<any, infer a, any> ? a : never,
+	B extends C extends CompoundTypedKey<any, any, infer b> ? b : never,
+>(
+	store: Store,
+	type: T,
+	sideA: SingularTypedKey<A>,
+	sideB: SingularTypedKey<B>,
+): Claim<CompoundTypedKey<T, A, B>> {
+	const compoundKey: CompoundTypedKey<T, A, B> =
+		`T$--${type}==${sideA}++${sideB}`
+	const above = [sideA, sideB] as Above<Vassal<H>, H>
+	allocateIntoStore<H, Vassal<H>, Above<Vassal<H>, H>>(
+		store,
+		above,
+		compoundKey as Vassal<H>,
+		`all`,
+	)
+	return compoundKey
+}
+
+export function deallocateFromStore<H extends Hierarchy, V extends Vassal<H>>(
+	store: Store,
+	claim: Claim<V>,
+): void {
+	const stringKey = stringifyJson(claim)
+
+	const molecule = store.molecules.get(stringKey)
+	if (!molecule) {
+		const disposal = store.disposalTraces.buffer.find(
+			(item) => item?.key === stringKey,
+		)
+		store.logger.error(
+			`❌`,
+			`molecule`,
+			claim,
+			`deallocation failed:`,
+			`Could not find allocation for ${stringKey} in store "${store.config.name}".`,
+			disposal
+				? `\n   This state was most recently deallocated\n${disposal.trace}`
+				: `No previous disposal trace for ${stringKey} was found.`,
+		)
+		return
+	}
+
+	const joinKeys = store.moleculeJoins.getRelatedKeys(
+		molecule.key as string /* 💥 RECONCILE */,
+	)
+	if (joinKeys) {
+		for (const joinKey of joinKeys) {
+			const join = store.joins.get(joinKey)
+			if (join) {
+				join.relations.delete(molecule.key)
+				join.molecules.delete(molecule.stringKey) // get rid of
+			}
+		}
+	}
+	store.moleculeJoins.delete(molecule.stringKey)
+
+	const provenance: stringified<Canonical>[] = []
+
+	const values: [string, any][] = []
+	const disposalEvent: MoleculeDisposal = {
+		type: `molecule_disposal`,
+		key: molecule.key,
+		values,
+		provenance,
+	}
+	const target = newest(store)
+	target.molecules.delete(stringKey)
+	const isTransaction =
+		isChildStore(target) && target.transactionMeta.phase === `building`
+	if (isTransaction) {
+		target.transactionMeta.update.updates.push(disposalEvent)
+	}
+	const relatedMolecules = store.moleculeGraph.getRelationEntries({
+		downstreamMoleculeKey: molecule.stringKey,
+	})
+	if (relatedMolecules) {
+		for (const [relatedStringKey, { source }] of relatedMolecules) {
+			if (source === molecule.stringKey) {
+				const relatedKey = parseJson(relatedStringKey)
+				deallocateFromStore<any, any>(store, relatedKey)
+			} else {
+				provenance.push(source)
+			}
+		}
+	}
+	const familyKeys = target.moleculeData.getRelatedKeys(molecule.stringKey)
+	if (familyKeys) {
+		for (const familyKey of familyKeys) {
+			// biome-ignore lint/style/noNonNullAssertion: tokens of molecules must have a family
+			const family = target.families.get(familyKey)!
+			const token = findInStore(store, family, molecule.key)
+			values.push([family.key, token])
+			disposeFromStore(store, token)
+		}
+	}
+
+	target.moleculeGraph.delete(molecule.stringKey)
+	target.moleculeJoins.delete(molecule.stringKey)
+	target.moleculeData.delete(molecule.stringKey)
+
+	if (!isTransaction) {
+		target.on.moleculeDisposal.next(disposalEvent)
+	}
+	target.molecules.delete(molecule.stringKey)
+
+	const trace = getTrace(new Error())
+	store.disposalTraces.add({ key: stringKey, trace })
+}
+export function claimWithinStore<
+	H extends Hierarchy,
+	V extends Exclude<Vassal<H>, CompoundTypedKey>,
+	A extends Above<V, H>,
+>(
+	store: Store,
+	newProvenance: A,
+	claim: Claim<V>,
+	exclusive?: `exclusive`,
+): Claim<V> {
+	const stringKey = stringifyJson(claim)
+	const target = newest(store)
+	const molecule = target.molecules.get(stringKey)
+	if (!molecule) {
+		const disposal = store.disposalTraces.buffer.find(
+			(item) => item?.key === stringKey,
+		)
+		store.logger.error(
+			`❌`,
+			`molecule`,
+			claim,
+			`claim failed:`,
+			`Could not allocate to ${stringKey} in store "${store.config.name}".`,
+			disposal
+				? `\n   ${stringKey} was most recently disposed\n${disposal.trace}`
+				: `No previous disposal trace for ${stringKey} was found.`,
+		)
+		return claim
+	}
+
+	const newProvenanceKey = stringifyJson(newProvenance as Canonical)
+	const newProvenanceMolecule = target.molecules.get(newProvenanceKey)
+	if (!newProvenanceMolecule) {
+		const disposal = store.disposalTraces.buffer.find(
+			(item) => item?.key === newProvenanceKey,
+		)
+		store.logger.error(
+			`❌`,
+			`molecule`,
+			claim,
+			`claim failed:`,
+			`Could not allocate to ${newProvenanceKey} in store "${store.config.name}".`,
+			disposal
+				? `\n   ${newProvenanceKey} was most recently disposed\n${disposal.trace}`
+				: `No previous disposal trace for ${newProvenanceKey} was found.`,
+		)
+		return claim
+	}
+
+	const priorProvenance = store.moleculeGraph
+		.getRelationEntries({
+			downstreamMoleculeKey: molecule.stringKey,
+		})
+		.filter(([, { source }]) => source !== stringKey)
+		.map(([key]) => parseJson(key))
+	if (exclusive) {
+		target.moleculeGraph.delete(stringKey)
+	}
+	target.moleculeGraph.set(
+		{
+			upstreamMoleculeKey: newProvenanceMolecule.stringKey,
+			downstreamMoleculeKey: molecule.stringKey,
+		},
+		{
+			source: newProvenanceMolecule.stringKey,
+		},
+	)
+	const transferEvent: MoleculeTransfer = {
+		type: `molecule_transfer`,
+		key: molecule.key,
+		from: priorProvenance,
+		to: [newProvenanceMolecule.key],
+	}
+	const isTransaction =
+		isChildStore(target) && target.transactionMeta.phase === `building`
+	if (isTransaction) {
+		target.transactionMeta.update.updates.push(transferEvent)
+	}
+
+	return claim
+}

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

@@ -80,7 +80,7 @@ export function createMutableAtomFamily<
 	}) satisfies MutableAtomFamily<T, J, K>
 
 	store.families.set(options.key, atomFamily)
-	selectJsonFamily(atomFamily, options, store)
+	selectJsonFamily(store, atomFamily, options)
 	new FamilyTracker(atomFamily, store)
 	return familyToken
 }

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

@@ -61,8 +61,8 @@ export function createMutableAtom<
 	}
 	const initialValue = options.default()
 	target.atoms.set(newAtom.key, newAtom)
-	markAtomAsDefault(options.key, store)
-	cacheValue(options.key, initialValue, subject, target)
+	markAtomAsDefault(store, options.key)
+	cacheValue(target, options.key, initialValue, subject)
 	const token = deposit(newAtom)
 	if (options.effects) {
 		let effectIndex = 0
@@ -73,7 +73,7 @@ export function createMutableAtom<
 					setIntoStore(store, token, next)
 				},
 				onSet: (handle: UpdateHandler<T>) =>
-					subscribeToState(token, handle, `effect[${effectIndex}]`, store),
+					subscribeToState(store, token, `effect[${effectIndex}]`, handle),
 			})
 			if (cleanup) {
 				cleanupFunctions.push(cleanup)

package/internal/src/mutable/get-json-token.ts

@@ -27,7 +27,7 @@ export const getJsonToken = <
 			key: jsonFamilyKey,
 			type: `selector_family`,
 		}
-		const family = withdraw(jsonFamilyToken, target)
+		const family = withdraw(target, jsonFamilyToken)
 		const subKey = JSON.parse(mutableAtomToken.family.subKey)
 		const jsonToken = findInStore(store, family, subKey)
 		return jsonToken

package/internal/src/mutable/tracker-family.ts

@@ -2,7 +2,7 @@ import type { Canonical } from "atom.io/json"
 import { parseJson } from "atom.io/json"
 
 import type { MutableAtomFamily, RegularAtomFamily } from ".."
-import { createRegularAtomFamily, seekInStore } from "../families"
+import { createRegularAtomFamily } from "../families"
 import { type Store, withdraw } from "../store"
 import { Tracker } from "./tracker"
 import type { Transceiver } from "./transceiver"
@@ -11,6 +11,7 @@ export class FamilyTracker<
 	Core extends Transceiver<any>,
 	FamilyMemberKey extends Canonical,
 > {
+	private trackers: Map<FamilyMemberKey, Tracker<Core>> = new Map()
 	private readonly Update: Core extends Transceiver<infer Signal>
 		? Signal
 		: never
@@ -36,26 +37,27 @@ export class FamilyTracker<
 			},
 			[`mutable`, `updates`],
 		)
-		this.latestUpdateAtoms = withdraw(updateAtoms, store)
+		this.latestUpdateAtoms = withdraw(store, updateAtoms)
 		this.mutableAtoms = mutableAtoms
 		this.mutableAtoms.subject.subscribe(
 			`store=${store.config.name}::tracker-atom-family`,
 			(event) => {
-				if (event.token.family) {
-					const key = parseJson(event.token.family.subKey) as FamilyMemberKey
-					seekInStore(store, this.latestUpdateAtoms, key)
-					new Tracker<Core>(event.token, store)
-				}
-			},
-		)
-		this.latestUpdateAtoms.subject.subscribe(
-			`store=${store.config.name}::tracker-atom-family`,
-			(event) => {
-				if (event.token.family) {
-					const key = parseJson(event.token.family.subKey) as FamilyMemberKey
-					const mutableAtomToken = seekInStore(store, this.mutableAtoms, key)
-					if (mutableAtomToken) {
-						new Tracker<Core>(mutableAtomToken, store)
+				const { type, token } = event
+				if (token.family) {
+					const key = parseJson(token.family.subKey)
+					switch (type) {
+						case `state_creation`:
+							this.trackers.set(key, new Tracker<Core>(token, store))
+							break
+						case `state_disposal`:
+							{
+								const tracker = this.trackers.get(key)
+								if (tracker) {
+									tracker[Symbol.dispose]()
+									this.trackers.delete(key)
+								}
+							}
+							break
 					}
 				}
 			},

package/internal/src/mutable/tracker.ts

@@ -70,7 +70,9 @@ export class Tracker<Mutable extends Transceiver<any>> {
 			},
 		)
 		this.unsubscribeFromState = subscribeToState(
+			target,
 			mutableState,
+			subscriptionKey,
 			(update) => {
 				if (update.newValue !== update.oldValue) {
 					this.unsubscribeFromInnerValue()
@@ -82,8 +84,6 @@ export class Tracker<Mutable extends Transceiver<any>> {
 					)
 				}
 			},
-			subscriptionKey,
-			target,
 		)
 	}
 
@@ -96,7 +96,9 @@ export class Tracker<Mutable extends Transceiver<any>> {
 			isChildStore(target) ? target.transactionMeta.update.key : `main`
 		}:${mutableState.key}`
 		subscribeToState(
+			target,
 			latestUpdateState,
+			subscriptionKey,
 			({ newValue, oldValue }) => {
 				const timelineId = target.timelineTopics.getRelatedKey(
 					latestUpdateState.key,
@@ -106,7 +108,9 @@ export class Tracker<Mutable extends Transceiver<any>> {
 					const timelineData = target.timelines.get(timelineId)
 					if (timelineData?.timeTraveling) {
 						const unsubscribe = subscribeToTimeline(
+							target,
 							{ key: timelineId, type: `timeline` },
+							subscriptionKey,
 							(update) => {
 								unsubscribe()
 								setIntoStore(target, mutableState, (transceiver) => {
@@ -118,8 +122,6 @@ export class Tracker<Mutable extends Transceiver<any>> {
 									return transceiver
 								})
 							},
-							subscriptionKey,
-							target,
 						)
 						return
 					}
@@ -152,15 +154,13 @@ export class Tracker<Mutable extends Transceiver<any>> {
 					},
 				)
 			},
-			subscriptionKey,
-			target,
 		)
 	}
 
 	public mutableState: MutableAtomToken<Mutable, Json.Serializable>
 	public latestUpdateState: RegularAtomToken<typeof this.Update | null>
 
-	public dispose: () => void
+	public [Symbol.dispose]: () => void
 
 	public constructor(
 		mutableState: MutableAtomToken<Mutable, Json.Serializable>,
@@ -172,7 +172,7 @@ export class Tracker<Mutable extends Transceiver<any>> {
 		this.observeCore(mutableState, this.latestUpdateState, target)
 		this.updateCore(mutableState, this.latestUpdateState, target)
 		target.trackers.set(mutableState.key, this)
-		this.dispose = () => {
+		this[Symbol.dispose] = () => {
 			this.unsubscribeFromInnerValue()
 			this.unsubscribeFromState()
 			target.trackers.delete(mutableState.key)

package/internal/src/not-found-error.ts

@@ -1,37 +1,15 @@
-import { type Json, stringifyJson } from "atom.io/json"
+import type { AtomIOToken } from "atom.io"
+import { stringifyJson } from "atom.io/json"
 
-import type { AtomIOToken } from "./pretty-print"
 import { prettyPrintTokenType } from "./pretty-print"
 import type { Store } from "./store"
 
 export class NotFoundError extends Error {
-	public constructor(token: AtomIOToken, store: Store)
-	public constructor(
-		familyToken: AtomIOToken,
-		key: Json.Serializable,
-		store: Store,
-	)
-	public constructor(
-		...params:
-			| [token: AtomIOToken, key: Json.Serializable, store: Store]
-			| [token: AtomIOToken, store: Store]
-	) {
-		const token: AtomIOToken = params[0]
-		const store: Store = params.length === 2 ? params[1] : params[2]
-
-		if (params.length === 2) {
-			super(
-				`${prettyPrintTokenType(token)} ${stringifyJson(token.key)} not found in store "${
-					store.config.name
-				}".`,
-			)
-		} else {
-			const key = params[1]
-			super(
-				`${prettyPrintTokenType(token)} "${token.key}" member ${stringifyJson(key)} not found in store "${
-					store.config.name
-				}".`,
-			)
-		}
+	public constructor(token: AtomIOToken, store: Store) {
+		super(
+			`${prettyPrintTokenType(token)} ${stringifyJson(token.key)} not found in store "${
+				store.config.name
+			}".`,
+		)
 	}
 }

package/internal/src/pretty-print.ts

@@ -1,17 +1,6 @@
-import type {
-	ReadableFamilyToken,
-	ReadableToken,
-	TimelineToken,
-	TransactionToken,
-} from "atom.io"
+import type { AtomIOToken } from "atom.io"
 
-const capitalize = (str: string) => str[0].toUpperCase() + str.slice(1)
-
-export type AtomIOToken =
-	| ReadableFamilyToken<any, any>
-	| ReadableToken<any>
-	| TimelineToken<any>
-	| TransactionToken<any>
+import { capitalize } from "./capitalize"
 
 export function prettyPrintTokenType(token: AtomIOToken): string {
 	return token.type.split(`_`).map(capitalize).join(` `)

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

@@ -19,14 +19,10 @@ export const createReadonlySelector = <T>(
 	const target = newest(store)
 	const subject = new Subject<{ newValue: T; oldValue: T }>()
 	const covered = new Set<string>()
-	const { get, find, seek, json } = registerSelector(
-		options.key,
-		covered,
-		target,
-	)
+	const { get, find, json } = registerSelector(options.key, covered, target)
 	const getSelf = () => {
-		const value = options.get({ get, find, seek, json })
-		cacheValue(options.key, value, subject, newest(store))
+		const value = options.get({ get, find, json })
+		cacheValue(newest(store), options.key, value, subject)
 		covered.clear()
 		return value
 	}

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

@@ -23,12 +23,12 @@ export const createWritableSelector = <T>(
 	const subject = new Subject<{ newValue: T; oldValue: T }>()
 	const covered = new Set<string>()
 	const setterToolkit = registerSelector(options.key, covered, target)
-	const { find, get, seek, json } = setterToolkit
-	const getterToolkit = { find, get, seek, json }
+	const { find, get, json } = setterToolkit
+	const getterToolkit = { find, get, json }
 
 	const getSelf = (getFn = options.get, innerTarget = newest(store)): T => {
 		const value = getFn(getterToolkit)
-		cacheValue(options.key, value, subject, innerTarget)
+		cacheValue(innerTarget, options.key, value, subject)
 		covered.clear()
 		return value
 	}
@@ -47,7 +47,7 @@ export const createWritableSelector = <T>(
 			newValue,
 			`)`,
 		)
-		cacheValue(options.key, newValue, subject, innerTarget)
+		cacheValue(innerTarget, options.key, newValue, subject)
 		markDone(innerTarget, options.key)
 		if (isRootStore(innerTarget)) {
 			subject.next({ newValue, oldValue })

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

@@ -1,15 +1,15 @@
-import type { ReadonlySelectorToken, WritableSelectorToken } from "atom.io"
+import type { SelectorFamilyToken, SelectorToken } from "atom.io"
 
 import type { Store } from ".."
 import { isChildStore, newest, withdraw } from ".."
 
 export function disposeSelector(
-	selectorToken: ReadonlySelectorToken<unknown> | WritableSelectorToken<unknown>,
 	store: Store,
+	selectorToken: SelectorToken<unknown>,
 ): void {
 	const target = newest(store)
 	const { key } = selectorToken
-	const selector = withdraw(selectorToken, target)
+	const selector = withdraw(target, selectorToken)
 	if (!selector.family) {
 		store.logger.error(
 			`❌`,
@@ -22,23 +22,31 @@ export function disposeSelector(
 		if (molecule) {
 			target.moleculeData.delete(selector.family.subKey, selector.family.key)
 		}
+		let familyToken: SelectorFamilyToken<any, any>
 		switch (selectorToken.type) {
 			case `selector`:
 				{
 					target.selectors.delete(key)
-					const family = withdraw(
-						{ key: selector.family.key, type: `selector_family` },
-						store,
-					)
+					familyToken = {
+						key: selector.family.key,
+						type: `selector_family`,
+					}
+					const family = withdraw(store, familyToken)
+					family.subject.next({
+						type: `state_disposal`,
+						subType: `selector`,
+						token: selectorToken,
+					})
 				}
 				break
 			case `readonly_selector`:
 				{
 					target.readonlySelectors.delete(key)
-					const family = withdraw(
-						{ key: selector.family.key, type: `readonly_selector_family` },
-						store,
-					)
+					familyToken = {
+						key: selector.family.key,
+						type: `readonly_selector_family`,
+					}
+					const family = withdraw(store, familyToken)
 					family.subject.next({
 						type: `state_disposal`,
 						subType: `selector`,
@@ -47,6 +55,7 @@ export function disposeSelector(
 				}
 				break
 		}
+
 		target.valueMap.delete(key)
 		target.selectorAtoms.delete(key)
 		target.selectorGraph.delete(key)

package/internal/src/selector/get-selector-dependency-keys.ts

@@ -15,6 +15,6 @@ export const getSelectorDependencyKeys = (
 		.selectorGraph.getRelationEntries({ downstreamSelectorKey: key })
 		.filter(([_, { source }]) => source !== key)
 		.map(([_, { source }]) => source)
-		.filter((source) => isStateKey(source, store))
+		.filter((source) => isStateKey(store, source))
 	return sources
 }