atom.io 0.42.0 → 0.42.2

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

@@ -5,7 +5,7 @@ import type {
 	UpdateHandler,
 } from "atom.io"
 
-import { newest } from "../lineage"
+import { eldest, newest } from "../lineage"
 import { createStandaloneSelector } from "../selector"
 import { resetInStore, setIntoStore } from "../set-state"
 import type { MutableAtom } from "../state-types"
@@ -58,6 +58,18 @@ export function createMutableAtom<T extends Transceiver<any, any, any>>(
 	}
 	target.atoms.set(newAtom.key, newAtom)
 	const token = deposit(newAtom)
+
+	new Tracker(token, store)
+	if (!family) {
+		createStandaloneSelector(store, {
+			key: `${key}:JSON`,
+			get: ({ get }) => get(token).toJSON(),
+			set: ({ set }, newValue) => {
+				set(token, options.class.fromJSON(newValue))
+			},
+		})
+	}
+
 	if (options.effects) {
 		let effectIndex = 0
 		const cleanupFunctions: (() => void)[] = []
@@ -71,6 +83,8 @@ export function createMutableAtom<T extends Transceiver<any, any, any>>(
 				},
 				onSet: (handle: UpdateHandler<T>) =>
 					subscribeToState(store, token, `effect[${effectIndex}]`, handle),
+				token: token as any,
+				store: eldest(store),
 			})
 			if (cleanup) {
 				cleanupFunctions.push(cleanup)
@@ -84,16 +98,6 @@ export function createMutableAtom<T extends Transceiver<any, any, any>>(
 		}
 	}
 
-	new Tracker(token, store)
-	if (!family) {
-		createStandaloneSelector(store, {
-			key: `${key}:JSON`,
-			get: ({ get }) => get(token).toJSON(),
-			set: ({ set }, newValue) => {
-				set(token, options.class.fromJSON(newValue))
-			},
-		})
-	}
 	store.on.atomCreation.next(token)
 	return token
 }

package/src/internal/store/store.ts

@@ -107,20 +107,7 @@ export class Store implements Lineage {
 		new CircularBuffer(100)
 
 	public molecules: Map<string, Molecule<Canonical>> = new Map()
-	public moleculeJoins: Junction<
-		`moleculeKey`,
-		stringified<Canonical>,
-		`joinKey`,
-		string
-	> = new Junction(
-		{
-			between: [`moleculeKey`, `joinKey`],
-			cardinality: `n:n`,
-		},
-		{
-			makeContentKey: (...keys) => keys.sort().join(`:`),
-		},
-	)
+
 	public moleculeGraph: Junction<
 		`upstreamMoleculeKey`,
 		stringified<Canonical> | `"root"`,
@@ -150,6 +137,20 @@ export class Store implements Lineage {
 			makeContentKey: (...keys) => keys.sort().join(`:`),
 		},
 	)
+	public keyRefsInJoins: Junction<
+		`moleculeKey`,
+		stringified<Canonical>,
+		`joinKey`,
+		string
+	> = new Junction(
+		{
+			between: [`moleculeKey`, `joinKey`],
+			cardinality: `n:n`,
+		},
+		{
+			makeContentKey: (...keys) => keys.sort().join(`:`),
+		},
+	)
 	public miscResources: Map<string, Disposable> = new Map()
 
 	public on: StoreEventCarrier = {

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

@@ -54,7 +54,7 @@ export const buildTransaction = (
 		molecules: new MapOverlay(parent.molecules),
 		moleculeGraph: parent.moleculeGraph.overlay(),
 		moleculeData: parent.moleculeData.overlay(),
-		moleculeJoins: parent.moleculeJoins.overlay(),
+		keyRefsInJoins: parent.keyRefsInJoins.overlay(),
 		miscResources: new MapOverlay(parent.miscResources),
 	}
 	const epoch = getEpochNumberOfAction(store, token.key)

package/src/main/atom.ts

@@ -1,4 +1,4 @@
-import type { ConstructorOf, Ctor, Transceiver } from "atom.io/internal"
+import type { ConstructorOf, Ctor, Store, Transceiver } from "atom.io/internal"
 import {
 	createMutableAtom,
 	createMutableAtomFamily,
@@ -10,6 +10,7 @@ import type { Canonical } from "atom.io/json"
 
 import type { StateUpdate } from "./events"
 import type {
+	AtomToken,
 	MutableAtomFamilyToken,
 	MutableAtomToken,
 	RegularAtomFamilyToken,
@@ -22,7 +23,7 @@ export type RegularAtomOptions<T, E = never> = {
 	/** The starting value of the atom */
 	default: T | (() => T)
 	/** Hooks used to run side effects when the atom is set */
-	effects?: readonly AtomEffect<T>[]
+	effects?: readonly AtomEffect<T, E>[]
 	/** The classes of errors that might be thrown when deriving the atom's default value */
 	catch?: readonly Ctor<E>[]
 }
@@ -67,8 +68,10 @@ export function mutableAtom<T extends Transceiver<any, any, any>>(
  * @returns
  * Optionally, a cleanup function that will be called when the atom is disposed
  */
-export type AtomEffect<T> = (tools: Effectors<T>) => (() => void) | void
-export type Effectors<T> = {
+export type AtomEffect<T, E = never> = (
+	tools: Effectors<T, E>,
+) => (() => void) | void
+export type Effectors<T, E = never> = {
 	/**
 	 * Reset the value of the atom to its default
 	 */
@@ -79,7 +82,13 @@ export type Effectors<T> = {
 	 */
 	setSelf: <New extends T>(next: New | ((old: T) => New)) => void
 	/** Subscribe to changes to the atom */
-	onSet: (callback: (options: StateUpdate<T>) => void) => void
+	onSet: (callback: (options: StateUpdate<E | T>) => void) => void
+	/** The token of the atom */
+	token: T extends Transceiver<any, any, any>
+		? MutableAtomToken<T>
+		: AtomToken<T, any, E>
+	/** The store in which the atom exists */
+	store: Store
 }
 
 export type RegularAtomFamilyOptions<T, K extends Canonical, E = never> = {
@@ -88,7 +97,7 @@ export type RegularAtomFamilyOptions<T, K extends Canonical, E = never> = {
 	/** The starting value of the atom family */
 	default: T | ((key: K) => T)
 	/** Hooks used to run side effects when an atom in the family is set  */
-	effects?: (key: K) => AtomEffect<T>[]
+	effects?: (key: K) => AtomEffect<T, E>[]
 	/** The classes of errors that might be thrown when deriving the atom's default value */
 	catch?: readonly Ctor<E>[]
 }

package/src/main/realm.ts

@@ -14,16 +14,20 @@ import type { Canonical } from "atom.io/json"
 
 import type { TransactionToken } from "./tokens"
 
-export const $claim: unique symbol = Symbol.for(`claim`)
-export type Claim<K extends Canonical> = K & { [$claim]?: true }
+export const $validatedKey: unique symbol = Symbol.for(`claim`)
+export type ValidKey<K extends Canonical> = K & { [$validatedKey]?: true }
+
+export function simpleCompound(a: string, b: string): string {
+	return [a, b].sort().join(`\u001F`)
+}
 
 export class Realm<H extends Hierarchy> {
 	public store: RootStore
-	public deallocateTX: TransactionToken<(claim: Claim<Vassal<H>>) => void>
+	public deallocateTX: TransactionToken<(claim: ValidKey<Vassal<H>>) => void>
 	public claimTX: TransactionToken<
 		<V extends Exclude<Vassal<H>, CompoundTypedKey>, A extends Above<V, H>>(
 			newProvenance: A,
-			claim: Claim<V>,
+			claim: ValidKey<V>,
 			exclusive?: `exclusive`,
 		) => void
 	>
@@ -42,13 +46,13 @@ export class Realm<H extends Hierarchy> {
 	 * @param key - A unique identifier for the new subject
 	 * @param attachmentStyle - The attachment style of new subject to its owner(s). `any` means that if any owners remain, the subject will be retained. `all` means that the subject be retained only if all owners remain .
 	 * @returns
-	 * The subject's key, given status as a true {@link Claim}
+	 * The subject's key, given status as a true {@link ValidKey}
 	 */
 	public allocate<V extends Vassal<H>, A extends Above<V, H>>(
 		provenance: A,
 		key: V,
 		attachmentStyle?: `all` | `any`,
-	): Claim<V> {
+	): ValidKey<V> {
 		return allocateIntoStore<H, V, A>(
 			this.store,
 			provenance,
@@ -62,7 +66,7 @@ export class Realm<H extends Hierarchy> {
 	 * @param reagentA - the left reagent of the compound
 	 * @param reagentB - the right reagent of the compound
 	 * @returns
-	 * The compound's key, given status as a true {@link Claim}
+	 * The compound's key, given status as a {@link ValidKey}
 	 */
 	public fuse<
 		C extends CompoundFrom<H>,
@@ -73,14 +77,14 @@ export class Realm<H extends Hierarchy> {
 		type: T,
 		reagentA: SingularTypedKey<A>,
 		reagentB: SingularTypedKey<B>,
-	): Claim<CompoundTypedKey<T, A, B>> {
+	): ValidKey<CompoundTypedKey<T, A, B>> {
 		return fuseWithinStore<H, C, T, A, B>(this.store, type, reagentA, reagentB)
 	}
 	/**
 	 * Remove a subject from the realm
 	 * @param claim - The subject to be deallocated
 	 */
-	public deallocate<V extends Vassal<H>>(claim: Claim<V>): void {
+	public deallocate<V extends Vassal<H>>(claim: ValidKey<V>): void {
 		actUponStore(this.store, this.deallocateTX, arbitrary())(claim)
 	}
 	/**
@@ -89,12 +93,12 @@ export class Realm<H extends Hierarchy> {
 	 * @param claim - The subject to be claimed
 	 * @param exclusive - Whether the subjects previous owners should be detached from it
 	 * @returns
-	 * The subject's key, given status as a true {@link Claim}
+	 * The subject's key, given status as a true {@link ValidKey}
 	 */
 	public claim<
 		V extends Exclude<Vassal<H>, CompoundTypedKey>,
 		A extends Above<V, H>,
-	>(newProvenance: A, claim: Claim<V>, exclusive?: `exclusive`): void {
+	>(newProvenance: A, claim: ValidKey<V>, exclusive?: `exclusive`): void {
 		actUponStore(this.store, this.claimTX, arbitrary())(
 			newProvenance,
 			claim,
@@ -157,10 +161,47 @@ export class Anarchy {
 	): void {
 		claimWithinStore<any, any, any>(this.store, newProvenance, key, exclusive)
 	}
+	/**
+	 * Fuse two reagents into a compound
+	 * @param type - the name of the compound that is being fused
+	 * @param reagentA - the left reagent of the compound
+	 * @param reagentB - the right reagent of the compound
+	 * @returns
+	 * The compound's key, given status as a {@link ValidKey}
+	 */
+	public fuse<T extends string, A extends string, B extends string>(
+		type: T,
+		reagentA: SingularTypedKey<A>,
+		reagentB: SingularTypedKey<B>,
+	): ValidKey<CompoundTypedKey<T, A, B>> {
+		return fuseWithinStore<any, any, T, A, B>(
+			this.store,
+			type,
+			reagentA,
+			reagentB,
+		)
+	}
+}
+
+export function decomposeCompound(
+	compound: Canonical,
+): [type: string, a: string, b: string] | null {
+	if ((typeof compound === `string`) === false) {
+		return null
+	}
+	const [typeTag, components] = compound.split(`==`)
+	if (!components) {
+		return null
+	}
+	const type = typeTag.slice(4)
+	const [a, b] = components.split(`++`)
+	if (type && a && b) {
+		return [type, a, b]
+	}
+	return null
 }
 
-export const T$ = `T$`
-export type T$ = typeof T$
+export type T$ = `T$`
 export type TypeTag<T extends string> = `${T$}--${T}`
 export type SingularTypedKey<T extends string = string> = `${T}::${string}`
 export type CompoundTypedKey<

package/src/transceivers/o-list/index.ts

@@ -1 +1,2 @@
 export * from "./o-list"
+export * from "./o-list-disposed-key-cleanup-effect"

package/src/transceivers/o-list/o-list-disposed-key-cleanup-effect.ts

@@ -0,0 +1,153 @@
+import type { AtomEffect } from "atom.io"
+import { getFromStore, getUpdateToken, subscribeInStore } from "atom.io/internal"
+import { type primitive, stringifyJson } from "atom.io/json"
+
+import { OList } from "./o-list"
+
+export function filterOutInPlace<T>(arr: T[], toRemove: T): T[] {
+	let writeIndex = 0
+
+	// eslint-disable-next-line @typescript-eslint/prefer-for-of
+	for (let readIndex = 0; readIndex < arr.length; readIndex++) {
+		if (toRemove !== arr[readIndex]) {
+			arr[writeIndex] = arr[readIndex]
+			writeIndex++
+		}
+	}
+
+	arr.length = writeIndex
+	return arr
+}
+
+export const oListDisposedKeyCleanupEffect: AtomEffect<OList<primitive>> = ({
+	token,
+	setSelf,
+	store,
+}) => {
+	const disposalSubscriptions = new Map<primitive, () => void>()
+	const updateToken = getUpdateToken(token)
+
+	const addedValues = new Set<primitive>()
+	const removedValues = new Set<primitive>()
+	function updateSubscriptions() {
+		for (const addedValue of addedValues) {
+			const molecule = store.molecules.get(stringifyJson(addedValue))
+			if (molecule) {
+				disposalSubscriptions.set(
+					addedValue,
+					molecule.subject.subscribe(token.key, () => {
+						disposalSubscriptions.get(addedValue)?.()
+						disposalSubscriptions.delete(addedValue)
+						setSelf((self) => {
+							filterOutInPlace(self, addedValue)
+							return self
+						})
+					}),
+				)
+			} else {
+				store.logger.warn(
+					`❌`,
+					token.type,
+					token.key,
+					`Added "${addedValue}" to ${token.key} but it has not been allocated.`,
+				)
+			}
+		}
+		for (const removedValue of removedValues) {
+			if (disposalSubscriptions.has(removedValue)) {
+				disposalSubscriptions.get(removedValue)?.()
+				disposalSubscriptions.delete(removedValue)
+			}
+		}
+	}
+	subscribeInStore(
+		store,
+		updateToken,
+		function manageAutoDeletionTriggers({ newValue }) {
+			const currentList = getFromStore(store, token)
+			const unpacked = OList.unpackUpdate(newValue)
+			switch (unpacked.type) {
+				case `extend`:
+				case `reverse`:
+				case `sort`:
+					break // these don't change what values are present in the list
+
+				case `set`:
+					{
+						const { next } = unpacked
+						if (`prev` in unpacked && !currentList.includes(unpacked.prev)) {
+							removedValues.add(unpacked.prev)
+						}
+						if (!disposalSubscriptions.has(next)) {
+							addedValues.add(next)
+						}
+					}
+					break
+				case `truncate`:
+					{
+						for (const item of unpacked.items) {
+							if (!currentList.includes(item)) {
+								removedValues.add(item)
+							}
+						}
+					}
+					break
+				case `shift`:
+				case `pop`:
+					{
+						const { value } = unpacked
+						if (value !== undefined && !currentList.includes(value)) {
+							removedValues.add(value)
+						}
+					}
+					break
+				case `push`:
+				case `unshift`:
+					for (const item of unpacked.items) {
+						if (!disposalSubscriptions.has(item)) {
+							addedValues.add(item)
+						}
+					}
+					break
+				case `copyWithin`:
+					for (const item of unpacked.prev) {
+						if (!currentList.includes(item)) {
+							removedValues.add(item)
+						}
+					}
+					break
+				case `fill`:
+					{
+						const { value } = unpacked
+						if (value !== undefined) {
+							if (!disposalSubscriptions.has(value)) {
+								addedValues.add(value)
+							}
+						}
+						for (const item of unpacked.prev) {
+							if (!currentList.includes(item)) {
+								removedValues.add(item)
+							}
+						}
+					}
+					break
+				case `splice`:
+					for (const item of unpacked.deleted) {
+						if (!currentList.includes(item)) {
+							removedValues.add(item)
+						}
+					}
+					for (const addedItem of unpacked.items) {
+						if (!disposalSubscriptions.has(addedItem)) {
+							addedValues.add(addedItem)
+						}
+					}
+					break
+			}
+			updateSubscriptions()
+			addedValues.clear()
+			removedValues.clear()
+		},
+		`set-auto-deletion-triggers`,
+	)
+}

package/src/transceivers/u-list/index.ts

@@ -1 +1,2 @@
 export * from "./u-list"
+export * from "./u-list-disposed-key-cleanup-effect"

package/src/transceivers/u-list/u-list-disposed-key-cleanup-effect.ts

@@ -0,0 +1,47 @@
+import type { AtomEffect } from "atom.io"
+import { getUpdateToken, subscribeInStore } from "atom.io/internal"
+import { type primitive, stringifyJson } from "atom.io/json"
+
+import { UList } from "./u-list"
+
+export const uListDisposedKeyCleanupEffect: AtomEffect<UList<primitive>> = ({
+	token,
+	setSelf,
+	store,
+}) => {
+	const disposalSubscriptions = new Map<primitive, () => void>()
+	const updateToken = getUpdateToken(token)
+	subscribeInStore(
+		store,
+		updateToken,
+		function setAutoDeletionTriggers({ newValue }) {
+			const unpacked = UList.unpackUpdate(newValue)
+			switch (unpacked.type) {
+				case `add`:
+					{
+						const molecule = store.molecules.get(stringifyJson(unpacked.value))
+						if (molecule) {
+							disposalSubscriptions.set(
+								unpacked.value,
+								molecule.subject.subscribe(token.key, () => {
+									setSelf((self) => {
+										self.delete(unpacked.value)
+										return self
+									})
+								}),
+							)
+						}
+					}
+					break
+				case `delete`:
+					disposalSubscriptions.get(unpacked.value)?.()
+					disposalSubscriptions.delete(unpacked.value)
+					break
+				case `clear`:
+					for (const unsub of disposalSubscriptions.values()) unsub()
+					disposalSubscriptions.clear()
+			}
+		},
+		`set-auto-deletion-triggers`,
+	)
+}