atom.io 0.29.5 → 0.30.1

package/realtime-testing/src/setup-realtime-test.tsx

@@ -3,6 +3,7 @@ import * as http from "node:http"
 import type { RenderResult } from "@testing-library/react"
 import { prettyDOM, render } from "@testing-library/react"
 import * as AtomIO from "atom.io"
+import { realm } from "atom.io"
 import { editRelationsInStore, findRelationsInStore } from "atom.io/data"
 import type { Store } from "atom.io/internal"
 import {
@@ -44,6 +45,7 @@ function prefixLogger(store: Store, prefix: string) {
 
 export type TestSetupOptions = {
 	port: number
+	immortal?: { server?: boolean }
 	server: (tools: {
 		socket: SocketIO.Socket
 		silo: AtomIO.Silo
@@ -97,9 +99,13 @@ export const setupRealtimeTestServer = (
 ): RealtimeTestServer => {
 	++testNumber
 	const silo = new AtomIO.Silo(
-		{ name: `SERVER-${testNumber}`, lifespan: `ephemeral` },
+		{
+			name: `SERVER-${testNumber}`,
+			lifespan: options.immortal?.server ? `immortal` : `ephemeral`,
+		},
 		IMPLICIT.STORE,
 	)
+	const socketRealm = realm<RTS.SocketSystemHierarchy>(silo.store)
 
 	const httpServer = http.createServer((_, res) => res.end(`Hello World!`))
 	const address = httpServer.listen(options.port).address()
@@ -110,12 +116,14 @@ export const setupRealtimeTestServer = (
 	const server = new SocketIO.Server(httpServer).use((socket, next) => {
 		const { token, username } = socket.handshake.auth
 		if (token === `test` && socket.id) {
-			const socketState = findInStore(silo.store, RTS.socketAtoms, socket.id)
+			const userClaim = socketRealm.allocate(`root`, `user::${username}`)
+			const socketClaim = socketRealm.allocate(`root`, `socket::${socket.id}`)
+			const socketState = findInStore(silo.store, RTS.socketAtoms, socketClaim)
 			setIntoStore(silo.store, socketState, socket)
 			editRelationsInStore(
 				RTS.usersOfSockets,
 				(relations) => {
-					relations.set(socket.id, username)
+					relations.set(userClaim, socketClaim)
 				},
 				silo.store,
 			)
@@ -133,7 +141,7 @@ export const setupRealtimeTestServer = (
 		function enableLogging() {
 			const userKeyState = findRelationsInStore(
 				RTS.usersOfSockets,
-				socket.id,
+				`socket::${socket.id}`,
 				silo.store,
 			).userKeyOfSocket
 			userKey = getFromStore(silo.store, userKeyState)

package/src/allocate.ts

@@ -0,0 +1,277 @@
+import type { Each, Store } from "atom.io/internal"
+import {
+	disposeFromStore,
+	isChildStore,
+	Molecule,
+	newest,
+} from "atom.io/internal"
+import type { Canonical } from "atom.io/json"
+import { stringifyJson } from "atom.io/json"
+
+import { makeRootMoleculeInStore } from "./molecule"
+import type {
+	MoleculeCreationModern,
+	MoleculeDisposalModern,
+} from "./transaction"
+
+export const $provenance = Symbol(`provenance`)
+export type Claim<
+	H extends Hierarchy,
+	V extends Vassal<H>,
+	A extends Above<V, H>,
+> = V & {
+	[$provenance]?: A
+}
+
+export function allocateIntoStore<
+	H extends Hierarchy,
+	V extends Vassal<H>,
+	A extends Above<V, H>,
+>(store: Store, provenance: A, key: V): Claim<H, V, A> {
+	const stringKey = stringifyJson(key)
+	try {
+		const above: Molecule<any>[] = []
+
+		let allocationAttachmentStyle: `all` | `any`
+		if (provenance === `root`) {
+			// biome-ignore lint/style/noNonNullAssertion: let's assume we made the root molecule to get here
+			above.push(store.molecules.get(`"root"`)!)
+			allocationAttachmentStyle = `all`
+		} else if (typeof provenance === `string` && provenance.startsWith(T$)) {
+			allocationAttachmentStyle = `any`
+			const provenanceKey = stringifyJson(provenance as Canonical)
+			const provenanceMolecule = store.molecules.get(provenanceKey)
+			if (!provenanceMolecule) {
+				throw new Error(
+					`Molecule ${provenanceKey} not found in store "${store.config.name}"`,
+				)
+			}
+			above.push(provenanceMolecule)
+		} else {
+			const allocationIsCompound = key.startsWith(`T$--`)
+			if (allocationIsCompound) {
+				allocationAttachmentStyle = `all`
+				for (const claim of provenance as SingularTypedKey[]) {
+					const provenanceKey = stringifyJson(claim)
+					const provenanceMolecule = store.molecules.get(provenanceKey)
+					if (!provenanceMolecule) {
+						throw new Error(
+							`Molecule ${provenanceKey} not found in store "${store.config.name}"`,
+						)
+					}
+					above.push(provenanceMolecule)
+				}
+			} else {
+				allocationAttachmentStyle = `any`
+				const provenanceKey = stringifyJson(provenance as Canonical)
+				const provenanceMolecule = store.molecules.get(provenanceKey)
+				if (!provenanceMolecule) {
+					throw new Error(
+						`Molecule ${provenanceKey} not found in store "${store.config.name}"`,
+					)
+				}
+				above.push(provenanceMolecule)
+			}
+		}
+
+		const molecule = new Molecule(above, key)
+		molecule._dependsOn = allocationAttachmentStyle
+
+		store.molecules.set(stringKey, molecule)
+
+		for (const aboveMolecule of above) {
+			aboveMolecule.below.set(molecule.stringKey, molecule)
+		}
+
+		const creationEvent: MoleculeCreationModern = {
+			type: `molecule_creation`,
+			subType: `modern`,
+			key: molecule.key,
+			provenance: provenance as Canonical,
+		}
+		const target = newest(store)
+		const isTransaction =
+			isChildStore(target) && target.transactionMeta.phase === `building`
+		if (isTransaction) {
+			target.transactionMeta.update.updates.push(creationEvent)
+		} else {
+			target.on.moleculeCreationStart.next(creationEvent)
+		}
+	} catch (thrown) {
+		if (thrown instanceof Error) {
+			store.logger.error(
+				`❌`,
+				`molecule`,
+				stringKey,
+				`allocation failed:`,
+				thrown.message,
+			)
+		}
+	}
+
+	return key as Claim<H, V, A>
+}
+
+export function deallocateFromStore<
+	H extends Hierarchy,
+	V extends Vassal<H>,
+	A extends Above<V, H>,
+>(store: Store, claim: Claim<H, V, A>): void {
+	const stringKey = stringifyJson(claim)
+	const molecule = store.molecules.get(stringKey)
+	if (!molecule) {
+		throw new Error(
+			`Molecule ${stringKey} not found in store "${store.config.name}"`,
+		)
+	}
+
+	for (const join of molecule.joins.values()) {
+		join.relations.delete(molecule.key)
+		join.molecules.delete(molecule.stringKey)
+	}
+
+	let provenance: Canonical
+	if (molecule.above.size === 1) {
+		const above = molecule.above.values().next().value
+		provenance = above.key
+	} else {
+		provenance = [...molecule.above.values()].map(({ key }) => key)
+	}
+	const values: [string, any][] = []
+	for (const stateToken of molecule.tokens.values()) {
+		// biome-ignore lint/style/noNonNullAssertion: tokens of molecules must have a family
+		const tokenFamily = stateToken.family!
+		values.push([tokenFamily.key, store.valueMap.get(stateToken.key)])
+	}
+
+	for (const state of molecule.tokens.values()) {
+		disposeFromStore(store, state)
+	}
+	for (const child of molecule.below.values()) {
+		if (child.dependsOn === `all`) {
+			deallocateFromStore<any, any, any>(store, child.key)
+		} else {
+			child.above.delete(molecule.stringKey)
+			if (child.above.size === 0) {
+				deallocateFromStore<any, any, any>(store, child.key)
+			}
+		}
+	}
+	molecule.below.clear()
+
+	const disposalEvent: MoleculeDisposalModern = {
+		type: `molecule_disposal`,
+		subType: `modern`,
+		key: molecule.key,
+		values,
+		provenance,
+	}
+	const target = newest(store)
+	const isTransaction =
+		isChildStore(target) && target.transactionMeta.phase === `building`
+	if (isTransaction) {
+		target.transactionMeta.update.updates.push(disposalEvent)
+	} else {
+		target.on.moleculeDisposal.next(disposalEvent)
+	}
+	target.molecules.delete(molecule.stringKey)
+
+	for (const parent of molecule.above.values()) {
+		parent.below.delete(molecule.stringKey)
+	}
+}
+
+// eslint-disable-next-line @typescript-eslint/explicit-module-boundary-types
+export function realm<H extends Hierarchy>(store: Store) {
+	const root = makeRootMoleculeInStore(`root`, store)
+	return {
+		root,
+		allocate: <V extends Vassal<H>, A extends Above<V, H>>(
+			provenance: A,
+			key: V,
+		): Claim<H, V, A> => {
+			return allocateIntoStore(store, provenance, key)
+		},
+		deallocate: <V extends Vassal<H>, A extends Above<V, H>>(
+			claim: Claim<H, V, A>,
+		): void => {
+			deallocateFromStore(store, claim)
+		},
+	}
+}
+
+export const T$ = `T$`
+export type T$ = typeof T$
+export type TypeTag<T extends string> = `${T$}--${T}`
+export type SingularTypedKey<T extends string = string> = `${T}::${string}`
+export type CompoundTypedKey<
+	A extends string = string,
+	B extends string = string,
+	C extends string = string,
+> = `${TypeTag<A>}==${SingularTypedKey<B>}++${SingularTypedKey<C>}`
+export type TypedKey<
+	A extends string = string,
+	B extends string = string,
+	C extends string = string,
+> = CompoundTypedKey<A, B, C> | SingularTypedKey<A>
+type Scope = SingularTypedKey[]
+type MutualFealty = {
+	above: Scope
+	below: CompoundTypedKey
+	style: `all` | `any`
+}
+type ExclusiveFealty = {
+	above: TypedKey | `root`
+	below: Scope
+}
+type Fealty = ExclusiveFealty | MutualFealty
+
+export type Hierarchy<F extends Fealty[] = Fealty[]> = Each<F>
+
+export type Vassal<H extends Hierarchy> = {
+	[K in keyof H]: H[K] extends MutualFealty
+		? H[K][`below`]
+		: H[K] extends { below: Array<infer V> }
+			? V extends TypedKey
+				? V
+				: never
+			: never
+}[keyof H]
+
+export type Above<TK extends TypedKey, H extends Hierarchy> = {
+	[K in keyof H]: H[K] extends MutualFealty
+		? TK extends H[K][`below`]
+			? H[K][`above`]
+			: never
+		: H[K] extends { below: Array<infer V> }
+			? TK extends V
+				? H[K] extends ExclusiveFealty
+					? H[K][`above`]
+					: never
+				: never
+			: never
+}[keyof H]
+
+export type Below<TK extends TypedKey | TypedKey[], H extends Hierarchy> = {
+	[K in keyof H]: H[K] extends MutualFealty
+		? TK extends H[K][`above`]
+			? H[K][`below`]
+			: TK extends H[K][`above`][number]
+				? H[K][`below`]
+				: never
+		: H[K] extends { above: infer V }
+			? TK extends V
+				? H[K] extends ExclusiveFealty
+					? H[K][`below`][number]
+					: never
+				: never
+			: never
+}[keyof H]
+
+export type Mutuals<TK extends TypedKey | TypedKey[], H extends Hierarchy> = {
+	[K in keyof H]: H[K] extends MutualFealty
+		? TK extends H[K][`above`][number]
+			? [mutual: Exclude<H[K][`above`][number], TK>, below: H[K][`below`]]
+			: never
+		: never
+}[keyof H]

package/src/index.ts

@@ -7,6 +7,7 @@ import type {
 	WritableSelectorFamilyToken,
 } from "./selector"
 
+export * from "./allocate"
 export * from "./atom"
 export * from "./dispose-state"
 export * from "./get-state"

package/src/molecule.ts

@@ -1,7 +1,9 @@
 import type {
 	ActorToolkit,
 	MoleculeCreation,
+	MoleculeCreationClassic,
 	MoleculeDisposal,
+	MoleculeDisposalClassic,
 	MutableAtomFamilyToken,
 	MutableAtomToken,
 	ReadableFamilyToken,
@@ -36,12 +38,14 @@ export type CtorToolkit<K extends Canonical> = Flat<
 		bond<T>(family: ReadonlySelectorFamilyToken<T, K>): ReadonlySelectorToken<T>
 		bond<T>(family: WritableFamilyToken<T, K>): WritableToken<T>
 		bond<T>(family: ReadableFamilyToken<T, K>): ReadableToken<T>
-		bond<J extends JoinToken<any, any, any, any>>(
+		bond<J extends JoinToken<any, any, any, any, any, any>>(
 			joinToken: J,
 			role: {
-				as: J extends JoinToken<infer A, infer B, any, any> ? A | B : never
+				as: J extends JoinToken<infer A, string, infer B, string, any, any>
+					? A | B
+					: never
 			},
-		): J extends JoinToken<any, any, any, infer Content>
+		): J extends JoinToken<any, any, any, any, any, infer Content>
 			? Content extends null
 				? { relatedKeys: ReadonlySelectorToken<string[]> }
 				: {
@@ -86,7 +90,7 @@ export type MoleculeFamilyToken<M extends MoleculeConstructor> = {
 }
 export type MoleculeFamily<M extends MoleculeConstructor> = Flat<
 	MoleculeFamilyToken<M> & {
-		subject: Subject<MoleculeCreation<M> | MoleculeDisposal>
+		subject: Subject<MoleculeCreationClassic<M> | MoleculeDisposalClassic>
 		dependsOn: `all` | `any`
 		new: M
 	}
@@ -121,7 +125,7 @@ export type MoleculeType<T extends MoleculeFamilyToken<any>> =
 			: never
 export type MoleculeKey<M extends MoleculeConstructor> = InstanceType<M>[`key`]
 
-export function makeRootMolecule(
+export function makeRootMoleculeInStore(
 	key: string,
 	store: Store = IMPLICIT.STORE,
 ): MoleculeToken<ObjectConstructor> {

package/src/transaction.ts

@@ -16,7 +16,7 @@ import {
 	createTransaction,
 	IMPLICIT,
 } from "atom.io/internal"
-import type { Json } from "atom.io/json"
+import type { Canonical, Json } from "atom.io/json"
 
 import type {
 	disposeState,
@@ -25,7 +25,6 @@ import type {
 	ReadableToken,
 	TokenType,
 	WritableSelectorToken,
-	WritableToken,
 } from "."
 
 export type TransactionToken<F extends Func> = {
@@ -44,20 +43,39 @@ export type StateDisposal<Token extends ReadableToken<any>> = {
 	value?: TokenType<Token>
 }
 
-export type MoleculeCreation<M extends MoleculeConstructor> = {
+export type MoleculeCreationClassic<M extends MoleculeConstructor> = {
 	type: `molecule_creation`
+	subType: `classic`
 	token: MoleculeToken<M>
 	family: MoleculeFamilyToken<M>
 	context: MoleculeToken<any>[]
 	params: MoleculeParams<M>
 }
-export type MoleculeDisposal = {
+export type MoleculeCreationModern = {
+	type: `molecule_creation`
+	subType: `modern`
+	key: Canonical
+	provenance: Canonical
+}
+export type MoleculeCreation<M extends MoleculeConstructor> =
+	| MoleculeCreationClassic<M>
+	| MoleculeCreationModern
+export type MoleculeDisposalClassic = {
 	type: `molecule_disposal`
+	subType: `classic`
 	token: MoleculeToken<any>
 	family: MoleculeFamilyToken<any>
 	context: MoleculeToken<any>[]
 	values: [key: string, value: any][]
 }
+export type MoleculeDisposalModern = {
+	type: `molecule_disposal`
+	subType: `modern`
+	key: Canonical
+	provenance: Canonical
+	values: [key: string, value: any][]
+}
+export type MoleculeDisposal = MoleculeDisposalClassic | MoleculeDisposalModern
 
 export type TransactionUpdateContent =
 	| KeyedStateUpdate<unknown>