atom.io 0.37.0 → 0.38.0

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

@@ -1,63 +1,60 @@
 import type {
-	MutableAtomFamilyToken,
 	MutableAtomToken,
-	ReadableFamilyToken,
 	ReadableToken,
-	ReadonlyPureSelectorFamilyToken,
 	ReadonlyPureSelectorToken,
-	RegularAtomFamilyToken,
 	RegularAtomToken,
-	WritableFamilyToken,
-	WritablePureSelectorFamilyToken,
 	WritablePureSelectorToken,
 	WritableToken,
 } from "atom.io"
 import type { Canonical } from "atom.io/json"
 
+import type {
+	MutableAtomFamily,
+	ReadableFamily,
+	ReadonlyPureSelectorFamily,
+	RegularAtomFamily,
+	WritableFamily,
+	WritablePureSelectorFamily,
+} from ".."
 import type { Transceiver } from "../mutable"
-import type { Store } from "../store"
+import { type Store, withdraw } from "../store"
 
 export function getFamilyOfToken<
 	T extends Transceiver<any, any, any>,
 	K extends Canonical,
->(
-	store: Store,
-	token: MutableAtomToken<T, K>,
-): MutableAtomFamilyToken<T, K> | undefined
+>(store: Store, token: MutableAtomToken<T, K>): MutableAtomFamily<T, K>
 
 export function getFamilyOfToken<T, K extends Canonical>(
 	store: Store,
 	token: RegularAtomToken<T, K>,
-): RegularAtomFamilyToken<T, K> | undefined
+): RegularAtomFamily<T, K>
 
 export function getFamilyOfToken<T, K extends Canonical>(
 	store: Store,
 	token: WritablePureSelectorToken<T, K>,
-): WritablePureSelectorFamilyToken<T, K> | undefined
+): WritablePureSelectorFamily<T, K>
 
 export function getFamilyOfToken<T, K extends Canonical>(
 	store: Store,
 	token: ReadonlyPureSelectorToken<T, K>,
-): ReadonlyPureSelectorFamilyToken<T, K> | undefined
+): ReadonlyPureSelectorFamily<T, K>
 
 export function getFamilyOfToken<T, K extends Canonical>(
 	store: Store,
 	token: WritableToken<T, K>,
-): WritableFamilyToken<T, K> | undefined
-
+): WritableFamily<T, K>
 export function getFamilyOfToken<T, K extends Canonical>(
 	store: Store,
 	token: ReadableToken<T, K>,
-): ReadableFamilyToken<T, K> | undefined
+): ReadableFamily<T, K>
 
 export function getFamilyOfToken(
 	store: Store,
 	token: ReadableToken<any, any>,
-): ReadableFamilyToken<any, any> | undefined {
-	if (token.family) {
-		const family = store.families.get(token.family.key)
-		if (family) {
-			return family
-		}
-	}
+): ReadableFamily<any, any> {
+	return withdraw(store, {
+		// biome-ignore lint/style/noNonNullAssertion: family is required
+		key: token.family!.key,
+		type: `${token.type}_family`,
+	})
 }

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

@@ -9,66 +9,90 @@ import { stringifyJson } from "atom.io/json"
 
 import { newest } from "../lineage"
 import type { Store } from "../store"
-import { counterfeit } from "../store"
+import { COUNTERFEIT, mint } from "../store"
 import { isChildStore, isRootStore } from "../transaction"
 import { initFamilyMemberInStore } from "./init-family-member"
 
+export const MUST_CREATE: unique symbol = Symbol(`MUST_NOT_EXIST`)
+
 export function mintInStore<T, K extends Canonical, Key extends K>(
 	store: Store,
 	familyToken: WritableFamilyToken<T, K>,
 	key: Key,
+	init?: typeof MUST_CREATE,
 ): WritableToken<T, K>
 export function mintInStore<T, K extends Canonical, Key extends K>(
 	store: Store,
 	familyToken: ReadableFamilyToken<T, K>,
 	key: Key,
+	init?: typeof MUST_CREATE,
 ): ReadableToken<T, K>
 export function mintInStore<T, K extends Canonical, Key extends K>(
 	store: Store,
 	familyToken: ReadableFamilyToken<T, K>,
 	key: Key,
+	shouldCreate?: typeof MUST_CREATE,
 ): ReadableToken<T, K> {
+	let stateToken: ReadableToken<T, K>
+
+	let willCreate: boolean
+	switch (shouldCreate) {
+		case MUST_CREATE:
+			willCreate = true
+			break
+		case undefined:
+			willCreate = false
+			break
+	}
+
 	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.`,
+		const fakeToken = mint(familyToken, key, COUNTERFEIT)
+		store.logger.warn(
+			`💣`,
+			`key`,
+			stringKey,
+			`was used to mint a counterfeit token for`,
+			familyToken.type,
+			`"${familyToken.key}"`,
 		)
 		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
+
+	if (willCreate) {
+		stateToken = initFamilyMemberInStore(store, familyToken, key)
+		const target = newest(store)
+		if (stateToken.family) {
+			if (isRootStore(target)) {
+				switch (stateToken.type) {
+					case `atom`:
+					case `mutable_atom`:
+						store.on.atomCreation.next(stateToken)
+						break
+					case `writable_pure_selector`:
+					case `readonly_pure_selector`:
+					case `writable_held_selector`:
+					case `readonly_held_selector`:
+						store.on.selectorCreation.next(stateToken)
+						break
+				}
+			} else if (
+				isChildStore(target) &&
+				target.on.transactionApplying.state === null
+			) {
+				target.transactionMeta.update.subEvents.push({
+					type: `state_creation`,
+					token: stateToken,
+					timestamp: Date.now(),
+				})
 			}
-		} 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)
+		}
+	} else {
+		stateToken = mint(familyToken, key)
 	}
-	if (molecule) {
-		target.moleculeData.set(stringKey, familyToken.key)
-	}
-	return newStateToken
+	return stateToken
 }

package/src/internal/get-state/get-fallback.ts

@@ -0,0 +1,57 @@
+import type { ReadableToken } from "atom.io"
+import { type Canonical, stringifyJson } from "atom.io/json"
+
+import type { ReadableFamily } from ".."
+import type { Store } from "../store"
+
+export function getFallback<T, K extends Canonical>(
+	store: Store,
+	token: ReadableToken<T, K>,
+	family: ReadableFamily<T, K>,
+	subKey: K,
+): T {
+	const disposal = store.disposalTraces.buffer.find(
+		(item) => item?.key === stringifyJson(subKey),
+	)
+	store.logger.error(
+		`❌`,
+		token.type,
+		token.key,
+		`gets a fallback value because key`,
+		subKey,
+		`is not allocated`,
+		disposal
+			? `This key was previously disposed:\n${disposal.trace}`
+			: `(no previous disposal trace found)`,
+	)
+	switch (family.type) {
+		case `mutable_atom_family`: {
+			if (store.defaults.has(family.key)) {
+				return store.defaults.get(family.key)
+			}
+			const defaultValue = new family.class()
+			store.defaults.set(family.key, defaultValue)
+			return defaultValue
+		}
+		case `atom_family`: {
+			if (store.defaults.has(family.key)) {
+				return store.defaults.get(family.key)
+			}
+			const def = family.default as (key: K) => T
+			const defaultValue = def(subKey)
+			store.defaults.set(family.key, defaultValue)
+			return defaultValue
+		}
+		case `readonly_pure_selector_family`:
+		case `writable_pure_selector_family`:
+		case `readonly_held_selector_family`:
+		case `writable_held_selector_family`: {
+			if (store.defaults.has(family.key)) {
+				return store.defaults.get(family.key)
+			}
+			const defaultValue = family.default(subKey)
+			store.defaults.set(family.key, defaultValue)
+			return defaultValue
+		}
+	}
+}

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

@@ -1,10 +1,10 @@
 import type { ReadableFamilyToken, ReadableToken } from "atom.io"
 import type { Canonical } from "atom.io/json"
 
-import { findInStore } from "../families"
-import type { Store } from "../store"
-import { withdraw } from "../store"
+import { type Store, withdraw } from "../store"
+import { getFallback } from "./get-fallback"
 import { readOrComputeValue } from "./read-or-compute-value"
+import { reduceReference } from "./reduce-reference"
 
 export function getFromStore<T>(store: Store, token: ReadableToken<T>): T
 
@@ -20,50 +20,13 @@ export function getFromStore(
 		| [token: ReadableFamilyToken<any, any>, key: Canonical]
 		| [token: ReadableToken<any>]
 ): any {
-	let token: ReadableToken<any>
-	let family: ReadableFamilyToken<any, Canonical> | null
-	let key: Canonical | null
-	if (params.length === 1) {
-		token = params[0]
-	} else {
-		family = params[0]
-		key = params[1]
-		token = findInStore(store, family, key)
-	}
-	if (`counterfeit` in token && `family` in token) {
-		// biome-ignore lint/style/noNonNullAssertion: family must be present
-		family = store.families.get(token.family.key)!
-		const subKey = token.family.subKey
-		const disposal = store.disposalTraces.buffer.find(
-			(item) => item?.key === subKey,
-		)
-		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 `readonly_pure_selector_family`:
-			case `writable_pure_selector_family`:
-			case `readonly_held_selector_family`:
-			case `writable_held_selector_family`: {
-				if (store.defaults.has(family.key)) {
-					return store.defaults.get(token.family.key)
-				}
-				3
-				const defaultValue = withdraw(store, family).default(subKey)
-				store.defaults.set(family.key, defaultValue)
-				return defaultValue
-			}
-		}
+	const { token, familyToken, subKey } = reduceReference(store, ...params)
+
+	if (`counterfeit` in token && familyToken && subKey) {
+		const family = withdraw(store, familyToken)
+		return getFallback(store, token, family, subKey)
 	}
+	const state = withdraw(store, token)
 
-	return readOrComputeValue(store, withdraw(store, token))
+	return readOrComputeValue(store, state)
 }

package/src/internal/get-state/reduce-reference.ts

@@ -0,0 +1,66 @@
+import type { ReadableFamilyToken, ReadableToken } from "atom.io"
+import { type Canonical, parseJson } from "atom.io/json"
+
+import { seekInStore } from "../families"
+import { getFamilyOfToken } from "../families/get-family-of-token"
+import { mintInStore, MUST_CREATE } from "../families/mint-in-store"
+import type { Store } from "../store"
+import { withdraw } from "../store"
+
+export function reduceReference<T, K extends Canonical>(
+	store: Store,
+	...params:
+		| [token: ReadableFamilyToken<T, K>, key: K]
+		| [token: ReadableToken<T>]
+): {
+	token: ReadableToken<T>
+	familyToken: ReadableFamilyToken<T, K> | undefined
+	subKey: K | undefined
+	isNew: boolean
+} {
+	let existingToken: ReadableToken<T> | undefined
+	let brandNewToken: ReadableToken<T> | undefined
+	let familyToken: ReadableFamilyToken<T, K> | undefined
+	let subKey: K | undefined
+	let token: ReadableToken<T, K>
+	if (params.length === 1) {
+		token = params[0]
+		if (`family` in token) {
+			familyToken = getFamilyOfToken(store, token)
+			withdraw(store, familyToken)
+			subKey = parseJson(token.family.subKey)
+			existingToken = seekInStore(store, familyToken, subKey)
+			if (`counterfeit` in token) {
+				return {
+					token,
+					familyToken,
+					subKey,
+					isNew: false,
+				}
+			}
+			if (!existingToken) {
+				brandNewToken = mintInStore(store, familyToken, subKey, MUST_CREATE)
+				token = brandNewToken
+			} else {
+				token = existingToken
+			}
+		}
+	} else {
+		familyToken = params[0]
+		subKey = params[1]
+		existingToken = seekInStore(store, familyToken, subKey)
+		if (!existingToken) {
+			brandNewToken = mintInStore(store, familyToken, subKey, MUST_CREATE)
+			token = brandNewToken
+		} else {
+			token = existingToken
+		}
+	}
+
+	return {
+		token,
+		familyToken,
+		subKey,
+		isNew: Boolean(brandNewToken),
+	}
+}

package/src/internal/index.ts

@@ -1,5 +1,4 @@
 import type {
-	AtomToken,
 	FamilyMetadata,
 	MutableAtomFamilyToken,
 	MutableAtomToken,
@@ -9,8 +8,6 @@ import type {
 	ReadonlyPureSelectorToken,
 	RegularAtomFamilyToken,
 	RegularAtomToken,
-	StateCreationEvent,
-	StateDisposalEvent,
 	StateLifecycleEvent,
 	StateUpdate,
 	WritableHeldSelectorFamilyToken,
@@ -48,7 +45,6 @@ export * from "./molecule"
 export * from "./mutable"
 export * from "./not-found-error"
 export * from "./operation"
-export * from "./pretty-print"
 export * from "./reserved-keys"
 export * from "./selector"
 export * from "./set-state"
@@ -131,23 +127,26 @@ export type ReadableState<T> = Atom<T> | Selector<T>
 
 // biome-ignore format: intersection
 export type RegularAtomFamily<T, K extends Canonical> =
-	& RegularAtomFamilyToken<T, K>
-	& {
-		(key: K): RegularAtomToken<T>
-		install: (store: Store) => void
-		internalRoles: string[] | undefined
-		subject: Subject<StateCreationEvent<AtomToken<T>> | StateDisposalEvent<AtomToken<T>>>
-	}
+	& Flat<
+		& RegularAtomFamilyToken<T, K>
+		& {
+			default: T | ((key: K) => T)
+			install: (store: Store) => void
+			internalRoles: string[] | undefined
+			subject: Subject<StateLifecycleEvent<RegularAtomToken<T>>>
+		}
+	>
+	& ((key: K) => RegularAtomToken<T>)
 
 // biome-ignore format: intersection
 export type MutableAtomFamily<
-	// C extends TransceiverConstructor<any,any>,
 	T extends Transceiver<any, any, any>,
 	K extends Canonical,
 > =
 	& Flat<
 		& MutableAtomFamilyToken<T, K>
 		& {
+				class: ConstructorOf<T>
 				install: (store: Store) => void
 				internalRoles: string[] | undefined
 				subject: Subject<StateLifecycleEvent<MutableAtomToken<T>>>
@@ -167,13 +166,10 @@ export type WritablePureSelectorFamily<T, K extends Canonical> =
 			default: (key: K) => T,
 			install: (store: Store) => void
 			internalRoles: string[] | undefined
-			subject: Subject<
-				| StateCreationEvent<WritablePureSelectorToken<T>>
-				| StateDisposalEvent<WritablePureSelectorToken<T>>
-			>
+			subject: Subject<StateLifecycleEvent<WritablePureSelectorToken<T>>>
 		}
 	>
-  & ((key: K) => WritablePureSelectorToken<T>)
+	& ((key: K) => WritablePureSelectorToken<T>)
 
 // biome-ignore format: intersection
 export type WritableHeldSelectorFamily<T , K extends Canonical> =
@@ -183,13 +179,10 @@ export type WritableHeldSelectorFamily<T , K extends Canonical> =
 			default: (key: K) => T,
 			install: (store: Store) => void
 			internalRoles: string[] | undefined
-			subject: Subject<
-				| StateCreationEvent<WritableHeldSelectorToken<T>>
-				| StateDisposalEvent<WritableHeldSelectorToken<T>>
-			>
+			subject: Subject<StateLifecycleEvent<WritableHeldSelectorToken<T>>>
 		}
 	>
-  & ((key: K) => WritableHeldSelectorToken<T>)
+	& ((key: K) => WritableHeldSelectorToken<T>)
 
 // biome-ignore format: intersection
 export type ReadonlyPureSelectorFamily<T, K extends Canonical> =
@@ -199,10 +192,7 @@ export type ReadonlyPureSelectorFamily<T, K extends Canonical> =
 			default: (key: K) => T,
 			install: (store: Store) => void
 			internalRoles: string[] | undefined
-			subject: Subject<
-				| StateCreationEvent<ReadonlyPureSelectorToken<T>>
-				| StateDisposalEvent<ReadonlyPureSelectorToken<T>>
-			>
+			subject: Subject<StateLifecycleEvent<ReadonlyPureSelectorToken<T>>>
 		}
 	>
 	& ((key: K) => ReadonlyPureSelectorToken<T>)
@@ -215,10 +205,7 @@ export type ReadonlyHeldSelectorFamily<T , K extends Canonical> =
 			default: (key: K) => T,
 			install: (store: Store) => void
 			internalRoles: string[] | undefined
-			subject: Subject<
-				| StateCreationEvent<ReadonlyHeldSelectorToken<T>>
-				| StateDisposalEvent<ReadonlyHeldSelectorToken<T>>
-			>
+			subject: Subject<StateLifecycleEvent<ReadonlyHeldSelectorToken<T>>>
 		}
 	>
 	& ((key: K) => ReadonlyHeldSelectorToken<T>)

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

@@ -8,7 +8,8 @@ import type {
 } from "atom.io"
 import { parseJson, stringifyJson } from "atom.io/json"
 
-import { disposeFromStore, findInStore } from "../families"
+import { disposeFromStore } from "../families"
+import { mintInStore, MUST_CREATE } from "../families/mint-in-store"
 import {
 	allocateIntoStore,
 	claimWithinStore,
@@ -61,7 +62,7 @@ function createInStore(
 	if (familyMeta) {
 		const family = store.families.get(familyMeta.key)
 		if (family) {
-			findInStore(store, family, parseJson(familyMeta.subKey))
+			mintInStore(store, family, parseJson(familyMeta.subKey), MUST_CREATE)
 		}
 	}
 }
@@ -98,7 +99,7 @@ export function ingestMoleculeDisposalEvent(
 				for (const [familyKey, value] of update.values) {
 					const family = store.families.get(familyKey)
 					if (family) {
-						findInStore(store, family, update.key)
+						mintInStore(store, family, update.key, MUST_CREATE)
 						const memberKey = `${familyKey}(${stringifyJson(update.key)})`
 						store.valueMap.set(memberKey, value)
 					}

package/src/internal/molecule.ts

@@ -97,7 +97,7 @@ export function allocateIntoStore<
 		)
 		store.logger.error(
 			`❌`,
-			`molecule`,
+			`key`,
 			key,
 			`allocation failed:`,
 			`Could not allocate to ${claim} in store "${store.config.name}".`,
@@ -147,7 +147,7 @@ export function deallocateFromStore<H extends Hierarchy, V extends Vassal<H>>(
 		)
 		store.logger.error(
 			`❌`,
-			`molecule`,
+			`key`,
 			claim,
 			`deallocation failed:`,
 			`Could not find allocation for ${stringKey} in store "${store.config.name}".`,
@@ -244,8 +244,8 @@ export function claimWithinStore<
 		)
 		store.logger.error(
 			`❌`,
-			`molecule`,
-			claim,
+			`key`,
+			stringKey,
 			`claim failed:`,
 			`Could not allocate to ${stringKey} in store "${store.config.name}".`,
 			disposal
@@ -263,7 +263,7 @@ export function claimWithinStore<
 		)
 		store.logger.error(
 			`❌`,
-			`molecule`,
+			`key`,
 			claim,
 			`claim failed:`,
 			`Could not allocate to ${newProvenanceKey} in store "${store.config.name}".`,

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

@@ -6,14 +6,11 @@ import type {
 	MutableAtomToken,
 	StateLifecycleEvent,
 } from "atom.io"
+import { PRETTY_TOKEN_TYPES } from "atom.io"
 import type { Canonical } from "atom.io/json"
 import { stringifyJson } from "atom.io/json"
 
-import {
-	createWritablePureSelectorFamily,
-	type MutableAtomFamily,
-	prettyPrintTokenType,
-} from ".."
+import { createWritablePureSelectorFamily, type MutableAtomFamily } from ".."
 import { newest } from "../lineage"
 import { createMutableAtom } from "../mutable"
 import type { Store } from "../store"
@@ -41,9 +38,7 @@ export function createMutableAtomFamily<
 			`❗`,
 			`mutable_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.`,
+			`Overwriting an existing ${PRETTY_TOKEN_TYPES[existing.type]} "${existing.key}" in store "${store.config.name}". You can safely ignore this warning if it is due to hot module replacement.`,
 		)
 	}
 
@@ -70,6 +65,7 @@ export function createMutableAtomFamily<
 	}
 
 	const atomFamily = Object.assign(familyFunction, familyToken, {
+		class: options.class,
 		subject,
 		install: (s: Store) => createMutableAtomFamily(s, options),
 		internalRoles,

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

@@ -3,6 +3,7 @@ import type {
 	WritablePureSelectorFamilyToken,
 	WritablePureSelectorToken,
 } from "atom.io"
+import { parseJson } from "atom.io/json"
 
 import { findInStore } from "../families"
 import { newest } from "../lineage"
@@ -21,7 +22,7 @@ export const getJsonToken = <T extends Transceiver<any, any, any>>(
 			type: `writable_pure_selector_family`,
 		}
 		const family = withdraw(target, jsonFamilyToken)
-		const subKey = JSON.parse(mutableAtomToken.family.subKey)
+		const subKey = parseJson(mutableAtomToken.family.subKey)
 		const jsonToken = findInStore(store, family, subKey)
 		return jsonToken
 	}

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

@@ -1,13 +1,12 @@
-import type { AtomIOToken } from "atom.io"
+import { type AtomIOToken, PRETTY_TOKEN_TYPES } from "atom.io"
 import { stringifyJson } from "atom.io/json"
 
-import { prettyPrintTokenType } from "./pretty-print"
 import type { Store } from "./store"
 
 export class NotFoundError extends Error {
 	public constructor(token: AtomIOToken, store: Store) {
 		super(
-			`${prettyPrintTokenType(token)} ${stringifyJson(token.key)} not found in store "${
+			`${PRETTY_TOKEN_TYPES[token.type]} ${stringifyJson(token.key)} not found in store "${
 				store.config.name
 			}".`,
 		)

package/src/internal/operation.ts

@@ -23,7 +23,7 @@ export function openOperation(
 	if (store.operation.open) {
 		const rejectionTime = performance.now()
 		store.logger.info(
-			`❗`,
+			`🚫`,
 			token.type,
 			token.key,
 			`deferring setState at T-${rejectionTime} until setState for "${store.operation.token.key}" is done`,