atom.io 0.24.7 → 0.25.0

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

@@ -1,39 +1,72 @@
-import type { MoleculeConstructor, MoleculeToken, ReadableToken } from "atom.io"
+import type {
+	MoleculeConstructor,
+	MoleculeFamilyToken,
+	MoleculeKey,
+	MoleculeToken,
+	ReadableFamilyToken,
+	ReadableToken,
+} from "atom.io"
+import type { Json } 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 { readOrComputeValue } from "./read-or-compute-value"
 
 export function getFromStore<T>(token: ReadableToken<T>, store: Store): T
+
 export function getFromStore<M extends MoleculeConstructor>(
 	token: MoleculeToken<M>,
 	store: Store,
 ): InstanceType<M> | undefined
-export function getFromStore<
-	T,
-	M extends MoleculeConstructor,
-	Token extends MoleculeToken<M> | ReadableToken<T>,
->(token: Token, store: Store): InstanceType<M> | T | undefined
-export function getFromStore<
-	Token extends MoleculeToken<any> | ReadableToken<any>,
->(
-	token: Token,
+
+export function getFromStore<T, K extends Json.Serializable>(
+	token: ReadableFamilyToken<T, K>,
+	key: K,
 	store: Store,
-):
-	| (Token extends MoleculeToken<infer M>
-			? InstanceType<M>
-			: Token extends ReadableToken<infer T>
-				? T
-				: never)
-	| undefined {
-	if (token.type === `molecule`) {
-		try {
-			const molecule = withdraw(token, store)
-			return molecule.instance
-		} catch (_) {
-			return undefined
+): T
+
+export function getFromStore<M extends MoleculeConstructor>(
+	token: MoleculeFamilyToken<M>,
+	key: MoleculeKey<M>,
+	store: Store,
+): InstanceType<M>
+
+export function getFromStore<T>(
+	...params:
+		| [token: MoleculeFamilyToken<any>, key: MoleculeKey<any>, store: Store]
+		| [token: MoleculeToken<any>, store: Store]
+		| [token: ReadableFamilyToken<T, any>, key: Json.Serializable, store: Store]
+		| [token: ReadableToken<T>, store: Store]
+): any {
+	let token: MoleculeToken<any> | ReadableToken<T>
+	let store: Store
+	if (params.length === 2) {
+		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) {
+			throw new NotFoundError(family, key, store)
 		}
+		token = maybeToken
+	}
+	switch (token.type) {
+		case `atom`:
+		case `mutable_atom`:
+		case `selector`:
+		case `readonly_selector`:
+			return readOrComputeValue(withdraw(token, store), store)
+		case `molecule`:
+			return withdraw(token, store).instance
 	}
-	const state = withdraw(token, store)
-	return readOrComputeValue(state, store)
 }

package/internal/src/molecule/make-molecule-in-store.ts

@@ -1,4 +1,5 @@
 import type {
+	CtorToolkit,
 	MK,
 	MoleculeConstructor,
 	MoleculeCreation,
@@ -6,10 +7,9 @@ import type {
 	MoleculeKey,
 	MoleculeParams,
 	MoleculeToken,
-	MoleculeTransactors,
 	ReadableFamilyToken,
 } from "atom.io"
-import { getJoin, type JoinToken } from "atom.io/data"
+import { findRelations, getJoin, type JoinToken } from "atom.io/data"
 import type { seekState } from "atom.io/immortal"
 import { stringifyJson } from "atom.io/json"
 
@@ -26,6 +26,10 @@ import { actUponStore, isChildStore, isRootStore } from "../transaction"
 import { growMoleculeInStore } from "./grow-molecule-in-store"
 import { Molecule } from "./molecule-internal"
 
+function capitalize<S extends string>(string: S): Capitalize<S> {
+	return (string[0].toUpperCase() + string.slice(1)) as Capitalize<S>
+}
+
 export function makeMoleculeInStore<M extends MoleculeConstructor>(
 	store: Store,
 	context: MoleculeToken<M> | MoleculeToken<M>[],
@@ -34,33 +38,34 @@ export function makeMoleculeInStore<M extends MoleculeConstructor>(
 	...params: MoleculeParams<M>
 ): MoleculeToken<M> {
 	const target = newest(store)
+	const stringKey = stringifyJson(key)
 
-	target.moleculeInProgress = key
+	target.moleculeInProgress = stringKey
 
 	const contextArray = Array.isArray(context) ? context : [context]
 	const owners = contextArray.map<Molecule<M>>((ctx) => {
 		if (ctx instanceof Molecule) {
 			return ctx
 		}
-		const stringKey = stringifyJson(ctx.key)
-		const molecule = store.molecules.get(stringKey)
+		const ctxStringKey = stringifyJson(ctx.key)
+		const molecule = store.molecules.get(ctxStringKey)
 
 		if (!molecule) {
 			throw new Error(
-				`Molecule ${stringKey} not found in store "${store.config.name}"`,
+				`Molecule ${ctxStringKey} not found in store "${store.config.name}"`,
 			)
 		}
 		return molecule
 	})
 
 	const molecule = new Molecule(owners, key, familyToken)
-	target.molecules.set(stringifyJson(key), molecule)
+	target.molecules.set(stringKey, molecule)
 	for (const owner of owners) {
 		owner.below.set(molecule.stringKey, molecule)
 	}
 
-	const transactors = {
-		get: (t) => getFromStore(t, newest(store)),
+	const toolkit = {
+		get: (t) => getFromStore(t, undefined, newest(store)),
 		set: (t, newValue) => {
 			setIntoStore(t, newValue, newest(store))
 		},
@@ -73,12 +78,49 @@ export function makeMoleculeInStore<M extends MoleculeConstructor>(
 			disposeFromStore(t, newest(store))
 		},
 		env: () => getEnvironmentData(newest(store)),
-		bond: ((f: ReadableFamilyToken<any, any>) =>
-			growMoleculeInStore(
-				molecule,
-				withdraw(f, store),
-				newest(store),
-			)) as MoleculeTransactors<MK<M>>[`bond`],
+		bond: ((
+			token: JoinToken<any, any, any, any> | ReadableFamilyToken<any, any>,
+			maybeRole,
+		) => {
+			if (token.type === `join`) {
+				const { as: role } = maybeRole
+				const join = getJoin(token, store)
+				join.molecules.set(stringKey, molecule)
+				molecule.joins.set(token.key, join)
+				const unsubFromFamily = family.subject.subscribe(
+					`join:${token.key}-${stringKey}`,
+					(event) => {
+						if (
+							event.type === `molecule_disposal` &&
+							stringifyJson(event.token.key) === stringKey
+						) {
+							unsubFromFamily()
+							join.molecules.delete(stringKey)
+						}
+					},
+				)
+
+				if (role === null) {
+					return
+				}
+				const otherRole = token.a === role ? token.b : token.a
+				const relations = findRelations(token, key)
+				const relatedKeys =
+					relations[
+						`${otherRole}KeysOf${capitalize(role)}` as keyof typeof relations
+					]
+				const relatedEntries =
+					relations[
+						`${otherRole}EntriesOf${capitalize(role)}` as keyof typeof relations
+					]
+				let tokens = { relatedKeys }
+				if (relatedEntries) {
+					tokens = Object.assign(tokens, { relatedEntries })
+				}
+				return tokens
+			}
+			return growMoleculeInStore(molecule, withdraw(token, store), newest(store))
+		}) as CtorToolkit<MK<M>>[`bond`],
 		claim: (below, options) => {
 			const { exclusive } = options
 			const belowMolecule = newest(store).molecules.get(stringifyJson(below.key))
@@ -96,12 +138,6 @@ export function makeMoleculeInStore<M extends MoleculeConstructor>(
 				}
 			}
 		},
-		join: <J extends JoinToken<any, any, any, any>>(joinToken: J) => {
-			const join = getJoin(joinToken, store)
-			join.molecules.set(stringifyJson(key), molecule)
-			molecule.joins.set(joinToken.key, join)
-			return joinToken
-		},
 		spawn: (f: MoleculeFamilyToken<any>, k: any, ...p: any[]) =>
 			makeMoleculeInStore(
 				newest(store),
@@ -110,12 +146,12 @@ export function makeMoleculeInStore<M extends MoleculeConstructor>(
 				k,
 				...p,
 			),
-	} satisfies MoleculeTransactors<MK<M>>
+	} satisfies CtorToolkit<MK<M>>
 
 	const family = withdraw(familyToken, store)
 	const Constructor = family.new
 
-	molecule.instance = new Constructor(transactors, key, ...params)
+	molecule.instance = new Constructor(toolkit, key, ...params)
 
 	const token = {
 		type: `molecule`,

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

@@ -6,6 +6,7 @@ import type {
 	TimelineToken,
 	TransactionToken,
 } from "atom.io"
+import { type Json, stringifyJson } from "atom.io/json"
 
 import type { Store } from "./store"
 
@@ -37,11 +38,33 @@ function prettyPrintTokenType(token: AtomIOToken) {
 }
 
 export class NotFoundError extends Error {
-	public constructor(token: AtomIOToken, store: Store) {
-		super(
-			`${prettyPrintTokenType(token)} "${token.key}" not found in store "${
-				store.config.name
-			}".`,
-		)
+	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)} "${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
+				}".`,
+			)
+		}
 	}
 }

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

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

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

@@ -21,13 +21,15 @@ export const createWritableSelector = <T>(
 ): WritableSelectorToken<T> => {
 	const target = newest(store)
 	const subject = new Subject<{ newValue: T; oldValue: T }>()
-	const transactors = registerSelector(options.key, target)
-	const { find, get, seek, json } = transactors
-	const readonlyTransactors = { find, get, seek, json }
+	const covered = new Set<string>()
+	const toolkit = registerSelector(options.key, covered, target)
+	const { find, get, seek, json } = toolkit
+	const getterToolkit = { find, get, seek, json }
 
 	const getSelf = (innerTarget = newest(store)): T => {
-		const value = options.get(readonlyTransactors)
+		const value = options.get(getterToolkit)
 		cacheValue(options.key, value, subject, innerTarget)
+		covered.clear()
 		return value
 	}
 
@@ -50,7 +52,7 @@ export const createWritableSelector = <T>(
 		if (isRootStore(innerTarget)) {
 			subject.next({ newValue, oldValue })
 		}
-		options.set(transactors, newValue)
+		options.set(toolkit, newValue)
 	}
 	const mySelector: WritableSelector<T> = {
 		...options,

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

@@ -1,17 +1,24 @@
 import type {
 	MoleculeConstructor,
+	MoleculeFamilyToken,
 	MoleculeToken,
+	ReadableFamilyToken,
 	ReadableToken,
-	Transactors,
+	setState,
+	SetterToolkit,
+	WritableSelectorFamilyToken,
+	WritableToken,
 } from "atom.io"
 import type { findState } from "atom.io/ephemeral"
 import type { seekState } from "atom.io/immortal"
+import type { Json } from "atom.io/json"
 
 import { findInStore, seekInStore } from "../families"
 import { getFromStore } from "../get-state"
 import { readOrComputeValue } from "../get-state/read-or-compute-value"
 import { newest } from "../lineage"
 import { getJsonToken } from "../mutable"
+import { NotFoundError } from "../not-found-error"
 import { setAtomOrSelector } from "../set-state"
 import type { Store } from "../store"
 import { withdraw } from "../store"
@@ -19,16 +26,33 @@ import { updateSelectorAtoms } from "./update-selector-atoms"
 
 export const registerSelector = (
 	selectorKey: string,
+	covered: Set<string>,
 	store: Store,
-): Transactors => ({
-	get: (dependency: MoleculeToken<MoleculeConstructor> | ReadableToken<any>) => {
+): SetterToolkit => ({
+	get: (
+		dependency:
+			| MoleculeFamilyToken<any>
+			| MoleculeToken<MoleculeConstructor>
+			| ReadableFamilyToken<any, any>
+			| ReadableToken<any>,
+		key?: Json.Serializable,
+	) => {
 		const target = newest(store)
 
+		if (key) {
+			switch (dependency.type) {
+				case `molecule_family`:
+					return getFromStore(dependency, key, store)
+				case `atom_family`:
+					dependency = seekInStore(dependency, key, store) as any
+			}
+		}
+
 		if (dependency.type === `molecule`) {
 			return getFromStore(dependency, store)
 		}
 
-		const dependencyState = withdraw(dependency, store)
+		const dependencyState = withdraw(dependency as ReadableToken<any>, store)
 		const dependencyValue = readOrComputeValue(dependencyState, store)
 
 		store.logger.info(
@@ -49,14 +73,40 @@ export const registerSelector = (
 				source: dependency.key,
 			},
 		)
-		updateSelectorAtoms(selectorKey, dependency, store)
+		updateSelectorAtoms(selectorKey, dependency as any, covered, store)
 		return dependencyValue
 	},
-	set: (WritableToken, newValue) => {
+	set: (<T, New extends T>(
+		...params:
+			| [
+					token: WritableSelectorFamilyToken<T, any>,
+					key: Json.Serializable,
+					value: New | ((oldValue: any) => New),
+			  ]
+			| [token: WritableToken<T>, value: New | ((oldValue: T) => New)]
+	) => {
+		let token: WritableToken<T>
+		let value: New | ((oldValue: T) => New)
+		if (params.length === 2) {
+			token = params[0]
+			value = params[1]
+		} else {
+			const family = params[0]
+			const key = params[1]
+			value = params[2]
+			const maybeToken =
+				store.config.lifespan === `ephemeral`
+					? findInStore(family, key, store)
+					: seekInStore(family, key, store)
+			if (!maybeToken) {
+				throw new NotFoundError(family, key, store)
+			}
+			token = maybeToken
+		}
 		const target = newest(store)
-		const state = withdraw(WritableToken, target)
-		setAtomOrSelector(state, newValue, target)
-	},
+		const state = withdraw(token, target)
+		setAtomOrSelector(state, value, target)
+	}) as typeof setState,
 	find: ((token, key) => findInStore(token, key, store)) as typeof findState,
 	seek: ((token, key) => seekInStore(token, key, store)) as typeof seekState,
 	json: (token) => getJsonToken(token, store),

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

@@ -4,8 +4,8 @@ import { isAtomKey } from "../keys"
 import { getSelectorDependencyKeys } from "./get-selector-dependency-keys"
 
 export const traceSelectorAtoms = (
-	selectorKey: string,
 	directDependencyKey: StateKey<unknown>,
+	covered: Set<string>,
 	store: Store,
 ): AtomKey<unknown>[] => {
 	const rootKeys: AtomKey<unknown>[] = []
@@ -14,16 +14,13 @@ export const traceSelectorAtoms = (
 		directDependencyKey,
 		store,
 	)
-	let depth = 0
 	while (indirectDependencyKeys.length > 0) {
 		// biome-ignore lint/style/noNonNullAssertion: just checked length ^^^
 		const indirectDependencyKey = indirectDependencyKeys.shift()!
-		++depth
-		if (depth > 99999) {
-			throw new Error(
-				`Maximum selector dependency depth exceeded (> 99999) in selector "${selectorKey}". This is likely due to a circular dependency.`,
-			)
+		if (covered.has(indirectDependencyKey)) {
+			continue
 		}
+		covered.add(indirectDependencyKey)
 
 		if (!isAtomKey(indirectDependencyKey, store)) {
 			indirectDependencyKeys.push(
@@ -43,9 +40,10 @@ export const traceAllSelectorAtoms = (
 ): AtomKey<unknown>[] => {
 	const selectorKey = selector.key
 	const directDependencyKeys = getSelectorDependencyKeys(selectorKey, store)
+	const covered = new Set<string>()
 	return directDependencyKeys.flatMap((depKey) =>
 		isAtomKey(depKey, store)
 			? depKey
-			: traceSelectorAtoms(selectorKey, depKey, store),
+			: traceSelectorAtoms(depKey, covered, store),
 	)
 }

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

@@ -7,6 +7,7 @@ import { traceSelectorAtoms } from "./trace-selector-atoms"
 export const updateSelectorAtoms = (
 	selectorKey: string,
 	dependency: ReadonlySelectorToken<unknown> | WritableToken<unknown>,
+	covered: Set<string>,
 	store: Store,
 ): void => {
 	const target = newest(store)
@@ -22,7 +23,7 @@ export const updateSelectorAtoms = (
 			`discovers root atom "${dependency.key}"`,
 		)
 	} else {
-		const rootKeys = traceSelectorAtoms(selectorKey, dependency.key, store)
+		const rootKeys = traceSelectorAtoms(dependency.key, covered, store)
 		store.logger.info(
 			`🔍`,
 			`selector`,
@@ -38,4 +39,5 @@ export const updateSelectorAtoms = (
 			})
 		}
 	}
+	covered.add(dependency.key)
 }

package/internal/src/set-state/set-into-store.ts

@@ -1,5 +1,8 @@
-import type { WritableToken } from "atom.io"
+import type { WritableFamilyToken, WritableToken } from "atom.io"
+import type { Json } from "atom.io/json"
 
+import { findInStore, seekInStore } from "../families"
+import { NotFoundError } from "../not-found-error"
 import { closeOperation, openOperation } from "../operation"
 import type { Store } from "../store"
 import { withdraw } from "../store"
@@ -9,7 +12,51 @@ export function setIntoStore<T, New extends T>(
 	token: WritableToken<T>,
 	value: New | ((oldValue: T) => New),
 	store: Store,
+): void
+
+export function setIntoStore<T, K extends Json.Serializable, New extends T>(
+	token: WritableFamilyToken<T, K>,
+	key: K,
+	value: New | ((oldValue: T) => New),
+	store: Store,
+): void
+
+export function setIntoStore<T, New extends T>(
+	...params:
+		| [
+				token: WritableFamilyToken<T, Json.Serializable>,
+				key: Json.Serializable,
+				value: New | ((oldValue: T) => New),
+				store: Store,
+		  ]
+		| [
+				token: WritableToken<T>,
+				value: New | ((oldValue: T) => New),
+				store: Store,
+		  ]
 ): void {
+	let token: WritableToken<T>
+	let value: New | ((oldValue: T) => New)
+	let store: Store
+	if (params.length === 3) {
+		token = params[0]
+		value = params[1]
+		store = params[2]
+	} else {
+		const family = params[0]
+		const key = params[1]
+		value = params[2]
+		store = params[3]
+		const maybeToken =
+			store.config.lifespan === `ephemeral`
+				? findInStore(family, key, store)
+				: seekInStore(family, key, store)
+		if (!maybeToken) {
+			throw new NotFoundError(family, key, store)
+		}
+		token = maybeToken
+	}
+
 	const rejectionTime = openOperation(token, store)
 	if (rejectionTime) {
 		const unsubscribe = store.on.operationClose.subscribe(

package/internal/src/store/store.ts

@@ -143,6 +143,10 @@ export class Store implements Lineage {
 	}
 
 	public constructor(config: Store[`config`], store: Store | null = null) {
+		this.config = {
+			...store?.config,
+			...config,
+		}
 		if (store !== null) {
 			this.valueMap = new Map(store?.valueMap)
 			this.operation = { ...store?.operation }
@@ -155,10 +159,6 @@ export class Store implements Lineage {
 				}
 			}
 
-			this.config = {
-				...store?.config,
-				...config,
-			}
 			for (const [, family] of store.families) {
 				family.install(this)
 			}

package/internal/src/transaction/build-transaction.ts

@@ -1,4 +1,4 @@
-import type { Func } from "atom.io"
+import type { disposeState, Func, getState, setState } from "atom.io"
 import type { findState } from "atom.io/ephemeral"
 import type { seekState } from "atom.io/immortal"
 
@@ -64,11 +64,12 @@ export const buildTransaction = (
 			params,
 			output: undefined,
 		},
-		transactors: {
-			get: (token) => getFromStore(token, child),
-			set: (token, value) => {
-				setIntoStore(token, value, child)
-			},
+		toolkit: {
+			get: ((...ps: Parameters<typeof getState>) =>
+				getFromStore(...ps, child)) as typeof getState,
+			set: ((...ps: Parameters<typeof setState>) => {
+				setIntoStore(...ps, child)
+			}) as typeof setState,
 			run: (token, identifier = arbitrary()) =>
 				actUponStore(token, identifier, child),
 			find: ((token, k) => findInStore(token, k, child)) as typeof findState,
@@ -76,9 +77,9 @@ export const buildTransaction = (
 			json: (token) => getJsonToken(token, child),
 			make: (context, family, k, ...args) =>
 				makeMoleculeInStore(child, context, family, k, ...args),
-			dispose: (token) => {
-				disposeFromStore(token, child)
-			},
+			dispose: ((...ps: Parameters<typeof disposeState>) => {
+				disposeFromStore(...ps, child)
+			}) as typeof disposeState,
 			env: () => getEnvironmentData(child),
 		},
 	}

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

@@ -32,8 +32,8 @@ export function createTransaction<F extends Func>(
 			const childStore = buildTransaction(options.key, params, store, id)
 			try {
 				const target = newest(store)
-				const { transactors } = childStore.transactionMeta
-				const output = options.do(transactors, ...params)
+				const { toolkit } = childStore.transactionMeta
+				const output = options.do(toolkit, ...params)
 				applyTransaction(output, target)
 				return output
 			} catch (thrown) {

package/internal/src/transaction/index.ts

@@ -1,4 +1,4 @@
-import type { Func, TransactionUpdate, TransactorsWithRunAndEnv } from "atom.io"
+import type { ActorToolkit, Func, TransactionUpdate } from "atom.io"
 import type { Junction } from "rel8/junction"
 
 export * from "./abort-transaction"
@@ -17,7 +17,7 @@ export type TransactionPhase = (typeof TRANSACTION_PHASES)[number]
 export type TransactionProgress<F extends Func> = {
 	phase: `applying` | `building`
 	update: TransactionUpdate<F>
-	transactors: TransactorsWithRunAndEnv
+	toolkit: ActorToolkit
 }
 
 export type TransactionEpoch = {