atom.io 0.40.8 → 0.40.10

package/dist/internal/index.js

@@ -1,5 +1,3 @@
-import { DO_NOT_CREATE, Future, INTERNAL_ROLES, JOIN_OP, NotFoundError, RESET_STATE, StatefulSubject, Subject, Tracker, become, closeOperation, createRegularAtom, deposit, eldest, evictCachedValue, evictDownstreamFromAtom, evictDownstreamFromSelector, getFallback, getFamilyOfToken, getFromStore, getSelectorDependencyKeys, hasRole, isAtomKey, isChildStore, isDone, isReadonlySelectorKey, isRootStore, isSelectorKey, isStateKey, isTransceiver, markDone, mintInStore, newest, openOperation, operateOnStore, readFromCache, readOrComputeValue, recallState, reduceReference, resetAtomOrSelector, resetInStore, seekInStore, setAtomOrSelector, setIntoStore, subscribeToRootDependency, subscribeToState, subscribeToTimeline, traceRootSelectorAtoms, withdraw, writeToCache } from "../has-role-CMlaUlaf.js";
-import { isFn } from "../is-fn-DY1wZ-md.js";
 import { Anarchy, AtomIOLogger, PRETTY_TOKEN_TYPES } from "atom.io";
 import { parseJson, stringifyJson } from "atom.io/json";
 import { SetRTX } from "atom.io/transceivers/set-rtx";
@@ -9,6 +7,120 @@ function arbitrary(random = Math.random) {
 	return random().toString(36).slice(2);
 }
 
+//#endregion
+//#region src/internal/lineage.ts
+function newest(scion) {
+	while (scion.child !== null) scion = scion.child;
+	return scion;
+}
+function eldest(scion) {
+	while (scion.parent !== null) scion = scion.parent;
+	return scion;
+}
+
+//#endregion
+//#region src/internal/is-fn.ts
+const NON_CTOR_FN_REGEX = /^\[object (?:Async|Generator|AsyncGenerator)?Function\]$/;
+function isFn(input) {
+	const protoString = Object.prototype.toString.call(input);
+	return NON_CTOR_FN_REGEX.test(protoString);
+}
+
+//#endregion
+//#region src/internal/set-state/become.ts
+function become(nextVersionOfThing, originalThing) {
+	if (isFn(nextVersionOfThing)) return nextVersionOfThing(originalThing);
+	return nextVersionOfThing;
+}
+
+//#endregion
+//#region src/internal/future.ts
+/**
+* A Promise whose incoming value can be hot swapped.
+* @internal
+* @private
+* @typeParam T The type of the value that the promise will resolve to.
+*
+* @remarks
+* Can be constructed like a Promise, or from an existing Promise.
+*/
+var Future = class extends Promise {
+	fate;
+	resolve;
+	reject;
+	done = false;
+	constructor(executor) {
+		let superResolve;
+		let superReject;
+		super((resolve, reject) => {
+			superResolve = resolve;
+			superReject = reject;
+		});
+		this.resolve = superResolve;
+		this.reject = superReject;
+		this.use(executor instanceof Promise ? executor : new Promise(executor));
+	}
+	pass(promise, value) {
+		if (promise === this.fate) {
+			this.resolve(value);
+			this.done = true;
+		}
+	}
+	fail(promise, reason) {
+		if (promise === this.fate) {
+			this.reject(reason);
+			this.done = true;
+		}
+	}
+	use(value) {
+		if (this === value) return;
+		if (value instanceof Promise) {
+			const promise = value;
+			this.fate = promise;
+			promise.then((resolved) => {
+				this.pass(promise, resolved);
+			}, (reason) => {
+				this.fail(promise, reason);
+			});
+		} else {
+			this.resolve(value);
+			this.fate = void 0;
+		}
+	}
+};
+
+//#endregion
+//#region src/internal/subject.ts
+var Subject = class {
+	Subscriber;
+	subscribers = /* @__PURE__ */ new Map();
+	subscribe(key, subscriber) {
+		this.subscribers.set(key, subscriber);
+		const unsubscribe = () => {
+			this.unsubscribe(key);
+		};
+		return unsubscribe;
+	}
+	unsubscribe(key) {
+		this.subscribers.delete(key);
+	}
+	next(value) {
+		const subscribers = this.subscribers.values();
+		for (const subscriber of subscribers) subscriber(value);
+	}
+};
+var StatefulSubject = class extends Subject {
+	state;
+	constructor(initialState) {
+		super();
+		this.state = initialState;
+	}
+	next(value) {
+		this.state = value;
+		super.next(value);
+	}
+};
+
 //#endregion
 //#region src/internal/store/circular-buffer.ts
 var CircularBuffer = class CircularBuffer {
@@ -37,6 +149,17 @@ var CircularBuffer = class CircularBuffer {
 	}
 };
 
+//#endregion
+//#region src/internal/store/deposit.ts
+function deposit(state) {
+	const token = {
+		key: state.key,
+		type: state.type
+	};
+	if (`family` in state) token.family = state.family;
+	return token;
+}
+
 //#endregion
 //#region src/internal/overlays/map-overlay.ts
 var MapOverlay = class extends Map {
@@ -760,6 +883,15 @@ function ingestTransactionOutcomeEvent(store, event, applying) {
 	}
 }
 
+//#endregion
+//#region src/internal/transaction/is-root-store.ts
+function isRootStore(store) {
+	return `epoch` in store.transactionMeta;
+}
+function isChildStore(store) {
+	return `phase` in store.transactionMeta;
+}
+
 //#endregion
 //#region src/internal/transaction/get-epoch-number.ts
 function getContinuityKey(store, transactionKey) {
@@ -1058,6 +1190,342 @@ const clearStore = (store) => {
 	store.config = config;
 };
 
+//#endregion
+//#region src/internal/not-found-error.ts
+var NotFoundError = class extends Error {
+	constructor(token, store) {
+		super(`${PRETTY_TOKEN_TYPES[token.type]} ${stringifyJson(token.key)} not found in store "${store.config.name}".`);
+	}
+};
+
+//#endregion
+//#region src/internal/store/withdraw.ts
+function withdraw(store, token) {
+	let withdrawn;
+	let target = store;
+	while (target !== null) {
+		switch (token.type) {
+			case `atom`:
+			case `mutable_atom`:
+				withdrawn = target.atoms.get(token.key);
+				break;
+			case `writable_pure_selector`:
+			case `writable_held_selector`:
+				withdrawn = target.writableSelectors.get(token.key);
+				break;
+			case `readonly_pure_selector`:
+			case `readonly_held_selector`:
+				withdrawn = target.readonlySelectors.get(token.key);
+				break;
+			case `atom_family`:
+			case `mutable_atom_family`:
+			case `writable_pure_selector_family`:
+			case `readonly_pure_selector_family`:
+			case `writable_held_selector_family`:
+			case `readonly_held_selector_family`:
+				withdrawn = target.families.get(token.key);
+				break;
+			case `timeline`:
+				withdrawn = target.timelines.get(token.key);
+				break;
+			case `transaction`:
+				withdrawn = target.transactions.get(token.key);
+				break;
+		}
+		if (withdrawn) return withdrawn;
+		target = target.child;
+	}
+	throw new NotFoundError(token, store);
+}
+
+//#endregion
+//#region src/internal/get-state/get-fallback.ts
+function getFallback(store, token, family, subKey) {
+	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.READONLY_VIEW;
+		}
+		case `atom_family`: {
+			if (store.defaults.has(family.key)) return store.defaults.get(family.key);
+			const def = family.default;
+			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;
+		}
+	}
+}
+
+//#endregion
+//#region src/internal/safe-compute.ts
+function safeCompute(target, state) {
+	const { type, key, catch: canCatch } = state;
+	switch (type) {
+		case `readonly_pure_selector`:
+		case `writable_pure_selector`: {
+			let val;
+			target.logger.info(`🧮`, type, key, `computing value`);
+			try {
+				val = state.getFrom(target);
+				if (val instanceof Promise) return val.catch((thrown) => {
+					target.logger.error(`💥`, type, key, `rejected:`, thrown);
+					if (canCatch) {
+						for (const Class of canCatch) if (thrown instanceof Class) return thrown;
+					}
+					throw thrown;
+				});
+			} catch (e) {
+				target.logger.error(`💥`, type, key, `rejected:`, e);
+				if (canCatch) {
+					for (const Class of canCatch) if (e instanceof Class) return writeToCache(target, state, e);
+				}
+				throw e;
+			}
+			return writeToCache(target, state, val);
+		}
+		case `atom`: {
+			let def;
+			if (isFn(state.default)) try {
+				def = state.default();
+				if (def instanceof Promise) def = def.catch((thrown) => {
+					target.logger.error(`💥`, type, key, `rejected:`, thrown);
+					if (canCatch) {
+						for (const Class of canCatch) if (thrown instanceof Class) return thrown;
+					}
+					throw thrown;
+				});
+			} catch (e) {
+				target.logger.error(`💥`, type, key, `rejected:`, e);
+				if (canCatch) {
+					for (const Class of canCatch) if (e instanceof Class) {
+						def = writeToCache(target, state, e);
+						target.logger.info(`✨`, state.type, key, `computed default`, def);
+						return def;
+					}
+				}
+				throw e;
+			}
+			else {
+				def = state.default;
+				target.logger.info(`✨`, state.type, key, `using static default`, def);
+			}
+			return writeToCache(target, state, def);
+		}
+	}
+}
+
+//#endregion
+//#region src/internal/get-state/read-or-compute-value.ts
+function readOrComputeValue(target, state, mut) {
+	if (target.valueMap.has(state.key)) return readFromCache(target, state, mut);
+	target.logger.info(`❔`, state.type, state.key, `value not found in cache`);
+	const { key } = state;
+	switch (state.type) {
+		case `readonly_held_selector`:
+		case `writable_held_selector`:
+			target.logger.info(`🧮`, state.type, key, `computing value`);
+			return state.getFrom(target);
+		case `writable_pure_selector`:
+		case `readonly_pure_selector`:
+		case `atom`: return safeCompute(target, state);
+		case `mutable_atom`: {
+			const instance = new state.class();
+			target.logger.info(`✨`, state.type, key, `created new instance`, instance);
+			return writeToCache(target, state, instance);
+		}
+	}
+}
+
+//#endregion
+//#region src/internal/families/get-family-of-token.ts
+function getFamilyOfToken(store, token) {
+	return withdraw(store, {
+		key: token.family.key,
+		type: `${token.type}_family`
+	});
+}
+
+//#endregion
+//#region src/internal/families/mint-in-store.ts
+const FAMILY_MEMBER_TOKEN_TYPES = {
+	atom_family: `atom`,
+	molecule_family: `molecule`,
+	mutable_atom_family: `mutable_atom`,
+	readonly_held_selector_family: `readonly_held_selector`,
+	readonly_pure_selector_family: `readonly_pure_selector`,
+	writable_held_selector_family: `writable_held_selector`,
+	writable_pure_selector_family: `writable_pure_selector`
+};
+const MUST_CREATE = Symbol(`MUST_CREATE`);
+const DO_NOT_CREATE = Symbol(`DO_NOT_CREATE`);
+function mintInStore(mustCreate, store, family, key) {
+	const stringKey = stringifyJson(key);
+	const molecule = store.molecules.get(stringKey);
+	if (!molecule && store.config.lifespan === `immortal`) {
+		const { type: familyType, key: familyKey } = family;
+		store.logger.warn(`💣`, `key`, stringKey, `was used to mint a counterfeit token for`, familyType, `"${familyKey}"`);
+		const fullKey = `${familyKey}(${stringKey})`;
+		const type = FAMILY_MEMBER_TOKEN_TYPES[familyType];
+		return {
+			counterfeit: true,
+			key: fullKey,
+			type,
+			family: {
+				key: familyKey,
+				subKey: stringKey
+			}
+		};
+	}
+	let token;
+	if (mustCreate === MUST_CREATE) {
+		store.logger.info(`👪`, family.type, family.key, `adds member`, typeof key === `string` ? `\`${key}\`` : key);
+		token = family.create(key);
+		if (molecule) store.moleculeData.set(stringKey, family.key);
+	} else {
+		const { type: familyType, key: familyKey } = family;
+		const fullKey = `${familyKey}(${stringKey})`;
+		const type = FAMILY_MEMBER_TOKEN_TYPES[familyType];
+		return {
+			key: fullKey,
+			type,
+			family: {
+				key: familyKey,
+				subKey: stringKey
+			}
+		};
+	}
+	return token;
+}
+
+//#endregion
+//#region src/internal/get-state/reduce-reference.ts
+function reduceReference(store, ...params) {
+	let existingToken;
+	let brandNewToken;
+	let family;
+	let subKey;
+	let token;
+	if (params.length === 1) {
+		token = params[0];
+		if (`family` in token) {
+			const familyToken = getFamilyOfToken(store, token);
+			family = withdraw(store, familyToken);
+			subKey = parseJson(token.family.subKey);
+			existingToken = seekInStore(store, familyToken, subKey);
+			if (`counterfeit` in token) return {
+				token,
+				family,
+				subKey,
+				isNew: false
+			};
+			if (!existingToken) {
+				brandNewToken = mintInStore(MUST_CREATE, store, familyToken, subKey);
+				token = brandNewToken;
+			} else token = existingToken;
+		}
+	} else {
+		family = withdraw(store, params[0]);
+		subKey = params[1];
+		existingToken = seekInStore(store, family, subKey);
+		if (!existingToken) {
+			brandNewToken = mintInStore(MUST_CREATE, store, family, subKey);
+			token = brandNewToken;
+		} else token = existingToken;
+	}
+	const isCounterfeit = `counterfeit` in token;
+	if (Boolean(brandNewToken) && isCounterfeit === false && family) {
+		let subType;
+		switch (token.type) {
+			case `readonly_pure_selector`:
+			case `readonly_held_selector`:
+				subType = `readable`;
+				break;
+			case `atom`:
+			case `mutable_atom`:
+			case `writable_pure_selector`:
+			case `writable_held_selector`:
+				subType = `writable`;
+				break;
+		}
+		const stateCreationEvent = {
+			type: `state_creation`,
+			subType,
+			token,
+			timestamp: Date.now()
+		};
+		family.subject.next(stateCreationEvent);
+		const target = newest(store);
+		if (token.family) {
+			if (isRootStore(target)) switch (token.type) {
+				case `atom`:
+				case `mutable_atom`:
+					store.on.atomCreation.next(token);
+					break;
+				case `writable_pure_selector`:
+				case `readonly_pure_selector`:
+				case `writable_held_selector`:
+				case `readonly_held_selector`:
+					store.on.selectorCreation.next(token);
+					break;
+			}
+			else if (isChildStore(target) && target.on.transactionApplying.state === null) target.transactionMeta.update.subEvents.push(stateCreationEvent);
+		}
+	}
+	return {
+		token,
+		family,
+		subKey,
+		isNew: Boolean(brandNewToken)
+	};
+}
+
+//#endregion
+//#region src/internal/get-state/get-from-store.ts
+function getFromStore(store, ...params) {
+	const { token, family, subKey } = reduceReference(store, ...params);
+	if (`counterfeit` in token && family && subKey) return getFallback(store, token, family, subKey);
+	const state = withdraw(store, token);
+	return readOrComputeValue(store, state);
+}
+
+//#endregion
+//#region src/internal/families/seek-in-store.ts
+function seekInStore(store, token, key) {
+	const subKey = stringifyJson(key);
+	const fullKey = `${token.key}(${subKey})`;
+	const target = newest(store);
+	let state;
+	switch (token.type) {
+		case `atom_family`:
+		case `mutable_atom_family`:
+			state = target.atoms.get(fullKey);
+			break;
+		case `writable_held_selector_family`:
+		case `writable_pure_selector_family`:
+			state = target.writableSelectors.get(fullKey);
+			break;
+		case `readonly_held_selector_family`:
+		case `readonly_pure_selector_family`:
+			state = target.readonlySelectors.get(fullKey);
+			break;
+	}
+	if (state) return deposit(state);
+	return state;
+}
+
 //#endregion
 //#region src/internal/families/find-in-store.ts
 function findInStore(store, familyToken, key) {
@@ -1316,6 +1784,330 @@ function disposeFromStore(store, ...params) {
 	}
 }
 
+//#endregion
+//#region src/internal/operation.ts
+function openOperation(store, token) {
+	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`);
+		return rejectionTime;
+	}
+	store.operation = {
+		open: true,
+		done: /* @__PURE__ */ new Set(),
+		prev: /* @__PURE__ */ new Map(),
+		timestamp: Date.now(),
+		token,
+		subEvents: []
+	};
+	store.logger.info(`⭕`, token.type, token.key, `operation start in store "${store.config.name}"${isChildStore(store) ? ` ${store.transactionMeta.phase} "${store.transactionMeta.update.token.key}"` : ``}`);
+	return store;
+}
+function closeOperation(store) {
+	if (store.operation.open) store.logger.info(`🔴`, store.operation.token.type, store.operation.token.key, `operation done in store "${store.config.name}"`);
+	store.operation = { open: false };
+	store.on.operationClose.next(store.operation);
+}
+const isDone = (store, key) => {
+	if (!store.operation.open) {
+		store.logger.error(`🐞`, `unknown`, key, `isDone called outside of an operation. This is probably a bug in AtomIO.`);
+		return true;
+	}
+	return store.operation.done.has(key);
+};
+const markDone = (store, key) => {
+	if (!store.operation.open) {
+		store.logger.error(`🐞`, `unknown`, key, `markDone called outside of an operation. This is probably a bug in AtomIO.`);
+		return;
+	}
+	store.operation.done.add(key);
+};
+
+//#endregion
+//#region src/internal/set-state/dispatch-state-update.ts
+function dispatchOrDeferStateUpdate(target, state, { oldValue, newValue }, stateIsNewlyCreated, family) {
+	const token = deposit(state);
+	if (stateIsNewlyCreated && family) {
+		state.subject.next({ newValue });
+		const stateCreationEvent = {
+			checkpoint: true,
+			type: `state_creation`,
+			subType: `writable`,
+			token,
+			timestamp: Date.now(),
+			value: newValue
+		};
+		target.operation.subEvents.push(stateCreationEvent);
+		family.subject.next(stateCreationEvent);
+		const innerTarget = newest(target);
+		if (token.family) {
+			if (isRootStore(innerTarget)) switch (token.type) {
+				case `atom`:
+				case `mutable_atom`:
+					target.on.atomCreation.next(token);
+					break;
+				case `writable_pure_selector`:
+				case `writable_held_selector`:
+					target.on.selectorCreation.next(token);
+					break;
+			}
+			else if (isChildStore(innerTarget) && innerTarget.on.transactionApplying.state === null) innerTarget.transactionMeta.update.subEvents.push(stateCreationEvent);
+		}
+		return;
+	}
+	const { key, subject, type } = state;
+	const update = {
+		oldValue: isTransceiver(oldValue) ? oldValue.READONLY_VIEW : oldValue,
+		newValue: isTransceiver(newValue) ? newValue.READONLY_VIEW : newValue
+	};
+	if (isRootStore(target)) {
+		switch (type) {
+			case `mutable_atom`:
+				target.logger.info(`📢`, type, key, `is now (`, newValue, `) subscribers:`, subject.subscribers.keys());
+				break;
+			case `atom`:
+			case `writable_pure_selector`:
+			case `writable_held_selector`: target.logger.info(`📢`, type, key, `went (`, oldValue, `->`, newValue, `) subscribers:`, subject.subscribers.keys());
+		}
+		subject.next(update);
+	}
+	if (isChildStore(target) && (type === `mutable_atom` || type === `atom`)) {
+		if (target.on.transactionApplying.state === null) {
+			if (isTransceiver(newValue)) return;
+			const { timestamp } = target.operation;
+			const atomUpdate = {
+				type: `atom_update`,
+				token,
+				timestamp,
+				update
+			};
+			target.transactionMeta.update.subEvents.push(atomUpdate);
+			target.logger.info(`📁`, `atom`, key, `stowed (`, oldValue, `->`, newValue, `)`);
+			return;
+		}
+		if (hasRole(state, `tracker:signal`)) {
+			const keyOfMutable = key.slice(1);
+			const mutable = target.atoms.get(keyOfMutable);
+			if (readOrComputeValue(target, mutable, `mut`).do(update.newValue) === null === true) evictDownstreamFromAtom(target, mutable);
+		}
+	}
+}
+
+//#endregion
+//#region src/internal/set-state/set-atom.ts
+const setAtom = (target, atom, next) => {
+	const oldValue = readOrComputeValue(target, atom, `mut`);
+	let newValue = become(next, oldValue);
+	target.logger.info(`⭐`, `atom`, atom.key, `setting value`, newValue);
+	newValue = writeToCache(target, atom, newValue);
+	markDone(target, atom.key);
+	evictDownstreamFromAtom(target, atom);
+	return {
+		oldValue,
+		newValue
+	};
+};
+
+//#endregion
+//#region src/internal/set-state/reset-atom-or-selector.ts
+function resetAtom(target, atom) {
+	switch (atom.type) {
+		case `mutable_atom`: return setAtom(target, atom, new atom.class());
+		case `atom`: {
+			let def;
+			if (isFn(atom.default)) def = safeCompute(target, atom);
+			else def = atom.default;
+			return setAtom(target, atom, def);
+		}
+	}
+}
+function resetAtomOrSelector(target, state) {
+	let protoUpdate;
+	switch (state.type) {
+		case `atom`:
+		case `mutable_atom`:
+			protoUpdate = resetAtom(target, state);
+			break;
+		case `writable_held_selector`:
+			{
+				const atoms = traceRootSelectorAtoms(target, state.key);
+				for (const atom of atoms.values()) {
+					const rootProtoUpdate = resetAtom(target, atom);
+					dispatchOrDeferStateUpdate(target, state, rootProtoUpdate, false);
+				}
+				const value = state.getFrom(target);
+				protoUpdate = {
+					oldValue: value,
+					newValue: value
+				};
+			}
+			break;
+		case `writable_pure_selector`:
+			{
+				const oldValue = safeCompute(target, state);
+				const atoms = traceRootSelectorAtoms(target, state.key);
+				for (const atom of atoms.values()) {
+					const rootProtoUpdate = resetAtom(target, atom);
+					dispatchOrDeferStateUpdate(target, state, rootProtoUpdate, false);
+				}
+				const newValue = safeCompute(target, state);
+				protoUpdate = {
+					oldValue,
+					newValue
+				};
+			}
+			break;
+	}
+	return protoUpdate;
+}
+
+//#endregion
+//#region src/internal/set-state/set-into-store.ts
+function setIntoStore(store, ...params) {
+	operateOnStore(OWN_OP, store, ...params);
+}
+
+//#endregion
+//#region src/internal/set-state/reset-in-store.ts
+const RESET_STATE = Symbol(`RESET`);
+function resetInStore(store, ...params) {
+	const subParams = [...params, RESET_STATE];
+	setIntoStore(store, ...subParams);
+}
+
+//#endregion
+//#region src/internal/set-state/set-selector.ts
+function setSelector(target, selector, next) {
+	let oldValue;
+	let newValue;
+	let constant;
+	const { type, key } = selector;
+	switch (selector.type) {
+		case `writable_pure_selector`:
+			oldValue = readOrComputeValue(target, selector, `mut`);
+			newValue = become(next, oldValue);
+			newValue = writeToCache(target, selector, newValue);
+			break;
+		case `writable_held_selector`:
+			constant = selector.const;
+			become(next, constant);
+			oldValue = constant;
+			newValue = constant;
+	}
+	target.logger.info(`⭐`, type, key, `setting to`, newValue);
+	markDone(target, key);
+	selector.setSelf(newValue);
+	return {
+		oldValue,
+		newValue
+	};
+}
+
+//#endregion
+//#region src/internal/set-state/set-atom-or-selector.ts
+const setAtomOrSelector = (target, state, value) => {
+	let protoUpdate;
+	switch (state.type) {
+		case `atom`:
+		case `mutable_atom`:
+			protoUpdate = setAtom(target, state, value);
+			break;
+		case `writable_pure_selector`:
+		case `writable_held_selector`:
+			protoUpdate = setSelector(target, state, value);
+			break;
+	}
+	return protoUpdate;
+};
+
+//#endregion
+//#region src/internal/set-state/operate-on-store.ts
+const OWN_OP = Symbol(`OWN_OP`);
+const JOIN_OP = Symbol(`JOIN_OP`);
+function operateOnStore(opMode, store, ...params) {
+	let existingToken;
+	let brandNewToken;
+	let token;
+	let family;
+	let key;
+	let value;
+	if (params.length === 2) {
+		token = params[0];
+		value = params[1];
+		if (`family` in token) {
+			family = getFamilyOfToken(store, token);
+			key = parseJson(token.family.subKey);
+			existingToken = seekInStore(store, family, key);
+			if (!existingToken) token = brandNewToken = mintInStore(MUST_CREATE, store, family, key);
+			else token = existingToken;
+		}
+	} else {
+		family = withdraw(store, params[0]);
+		key = params[1];
+		value = params[2];
+		existingToken = seekInStore(store, family, key);
+		if (!existingToken) token = brandNewToken = mintInStore(MUST_CREATE, store, family, key);
+		else token = existingToken;
+	}
+	const action = value === RESET_STATE ? `reset` : `set`;
+	let target;
+	if (opMode === OWN_OP) {
+		const result = openOperation(store, token);
+		if (typeof result === `number`) {
+			const rejectionTime = result;
+			const unsubscribe = store.on.operationClose.subscribe(`waiting to ${action} "${token.key}" at T-${rejectionTime}`, function waitUntilOperationCloseToSetState() {
+				unsubscribe();
+				store.logger.info(`🟢`, token.type, token.key, `resuming deferred`, action, `from T-${rejectionTime}`);
+				operateOnStore(opMode, store, token, value);
+			});
+			return;
+		}
+		target = result;
+	} else target = store;
+	if (`counterfeit` in token && `family` in token) {
+		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`, action, `because key`, subKey, `is not allocated.`, disposal ? `this key was previously disposed:${disposal.trace}` : `(no previous disposal trace found)`);
+		return;
+	}
+	const state = withdraw(target, token);
+	let protoUpdate;
+	if (value === RESET_STATE) protoUpdate = resetAtomOrSelector(target, state);
+	else protoUpdate = setAtomOrSelector(target, state, value);
+	dispatchOrDeferStateUpdate(target, state, protoUpdate, Boolean(brandNewToken), family);
+	if (opMode === OWN_OP) closeOperation(target);
+}
+
+//#endregion
+//#region src/internal/keys.ts
+const isAtomKey = (store, key) => newest(store).atoms.has(key);
+const isSelectorKey = (store, key) => newest(store).writableSelectors.has(key);
+const isReadonlySelectorKey = (store, key) => newest(store).readonlySelectors.has(key);
+const isStateKey = (store, key) => isAtomKey(store, key) || isSelectorKey(store, key) || isReadonlySelectorKey(store, key);
+
+//#endregion
+//#region src/internal/selector/get-selector-dependency-keys.ts
+function getSelectorDependencyKeys(store, key) {
+	return newest(store).selectorGraph.getRelationEntries({ downstreamSelectorKey: key }).filter(([_, { source }]) => source !== key).map(([_, { source }]) => source).filter((source) => isStateKey(store, source));
+}
+
+//#endregion
+//#region src/internal/selector/trace-selector-atoms.ts
+function traceRootSelectorAtoms(store, selectorKey, covered = /* @__PURE__ */ new Set()) {
+	const dependencies = getSelectorDependencyKeys(store, selectorKey);
+	const roots = /* @__PURE__ */ new Map();
+	while (dependencies.length > 0) {
+		const dependencyKey = dependencies.pop();
+		if (covered.has(dependencyKey)) continue;
+		covered.add(dependencyKey);
+		if (isAtomKey(store, dependencyKey)) {
+			const atom = store.atoms.get(dependencyKey);
+			roots.set(atom.key, atom);
+		} else dependencies.push(...getSelectorDependencyKeys(store, dependencyKey));
+	}
+	return roots;
+}
+
 //#endregion
 //#region src/internal/selector/update-selector-atoms.ts
 function updateSelectorAtoms(store, selectorType, selectorKey, dependency, covered) {
@@ -1648,6 +2440,82 @@ function disposeSelector(store, selectorToken) {
 	}
 }
 
+//#endregion
+//#region src/internal/subscribe/recall-state.ts
+const recallState = (store, state) => {
+	const target = newest(store);
+	if (target.operation.open) return target.operation.prev.get(state.key);
+	return target.valueMap.get(state.key);
+};
+
+//#endregion
+//#region src/internal/subscribe/subscribe-to-root-atoms.ts
+const subscribeToRootDependency = (target, selector, atom) => {
+	return atom.subject.subscribe(`${selector.type}:${selector.key}`, (atomChange) => {
+		target.logger.info(`📢`, selector.type, selector.key, `root`, atom.key, `went`, atomChange.oldValue, `->`, atomChange.newValue);
+		const oldValue = recallState(target, selector);
+		const newValue = readOrComputeValue(target, selector);
+		target.logger.info(`✨`, selector.type, selector.key, `went`, oldValue, `->`, newValue);
+		selector.subject.next({
+			newValue,
+			oldValue
+		});
+	});
+};
+
+//#endregion
+//#region src/internal/subscribe/subscribe-to-state.ts
+function subscribeToState(store, token, key, handleUpdate) {
+	function safelyHandleUpdate(update) {
+		if (store.operation.open) {
+			if (state?.type === `atom` && hasRole(state, `tracker:signal`) && `*` + store.operation.token.key === token.key && `inboundTracker` in handleUpdate) return;
+			const unsubscribe$1 = store.on.operationClose.subscribe(`state subscription ${key}`, () => {
+				unsubscribe$1();
+				handleUpdate(update);
+			});
+		} else handleUpdate(update);
+	}
+	reduceReference(store, token);
+	const state = withdraw(store, token);
+	store.logger.info(`👀`, state.type, state.key, `Adding subscription "${key}"`);
+	const isSelector = state.type === `writable_pure_selector` || state.type === `readonly_pure_selector`;
+	const rootSubs = /* @__PURE__ */ new Map();
+	let updateHandler = safelyHandleUpdate;
+	if (isSelector) {
+		readOrComputeValue(store, state);
+		for (const [atomKey, atom] of traceRootSelectorAtoms(store, state.key)) rootSubs.set(atomKey, subscribeToRootDependency(store, state, atom));
+		updateHandler = function updateRootsBeforeHandlingUpdate(update) {
+			const dependencies = traceRootSelectorAtoms(store, state.key);
+			for (const [previousRootKey, unsub] of rootSubs) if (dependencies.get(previousRootKey)) dependencies.delete(previousRootKey);
+			else {
+				unsub();
+				rootSubs.delete(previousRootKey);
+			}
+			for (const [atomKey, atom] of dependencies) rootSubs.set(atomKey, subscribeToRootDependency(store, state, atom));
+			safelyHandleUpdate(update);
+		};
+	}
+	const mainUnsubFunction = state.subject.subscribe(key, updateHandler);
+	const unsubscribe = () => {
+		store.logger.info(`🙈`, state.type, state.key, `Removing subscription "${key}"`);
+		mainUnsubFunction();
+		for (const unsubFromDependency of rootSubs.values()) unsubFromDependency();
+	};
+	return unsubscribe;
+}
+
+//#endregion
+//#region src/internal/subscribe/subscribe-to-timeline.ts
+const subscribeToTimeline = (store, token, key, handleUpdate) => {
+	const tl = withdraw(store, token);
+	store.logger.info(`👀`, `timeline`, token.key, `Adding subscription "${key}"`);
+	const unsubscribe = tl.subject.subscribe(key, handleUpdate);
+	return () => {
+		store.logger.info(`🙈`, `timeline`, token.key, `Removing subscription "${key}" from timeline`);
+		unsubscribe();
+	};
+};
+
 //#endregion
 //#region src/internal/subscribe/subscribe-to-transaction.ts
 const subscribeToTransaction = (store, token, key, handleUpdate) => {
@@ -1675,6 +2543,93 @@ function subscribeInStore(store, token, handleUpdate, key = arbitrary()) {
 	}
 }
 
+//#endregion
+//#region src/internal/mutable/tracker.ts
+/**
+* @internal Give the tracker a transceiver state and a store, and it will
+* subscribe to the transceiver's inner value. When the inner value changes,
+* the tracker will update its own state to reflect the change.
+*/
+var Tracker = class {
+	initializeSignalAtom(mutableState, store) {
+		const latestSignalStateKey = `*${mutableState.key}`;
+		store.atoms.delete(latestSignalStateKey);
+		store.valueMap.delete(latestSignalStateKey);
+		const familyMetaData = mutableState.family ? {
+			key: `*${mutableState.family.key}`,
+			subKey: mutableState.family.subKey
+		} : void 0;
+		const latestSignalState = createRegularAtom(store, {
+			key: latestSignalStateKey,
+			default: null
+		}, familyMetaData, [`tracker:signal`]);
+		if (store.parent?.valueMap.has(latestSignalStateKey)) {
+			const parentValue = store.parent.valueMap.get(latestSignalStateKey);
+			store.valueMap.set(latestSignalStateKey, parentValue);
+		}
+		return latestSignalState;
+	}
+	unsubscribeFromInnerValue;
+	unsubscribeFromState;
+	captureSignalsFromCore(mutableState, latestSignalState, target) {
+		const stateKey = mutableState.key;
+		const storeName = target.config.name;
+		const storeStatus = isChildStore(target) ? target.transactionMeta.update.token.key : `main`;
+		const subscriptionKey = `tracker-from-core:${storeName}:${storeStatus}:${stateKey}`;
+		const trackerCapturesOutboundSignal = (update) => {
+			operateOnStore(JOIN_OP, target, latestSignalState, update);
+		};
+		this.unsubscribeFromInnerValue = getFromStore(target, mutableState).subscribe(subscriptionKey, trackerCapturesOutboundSignal);
+		this.unsubscribeFromState = subscribeToState(target, mutableState, subscriptionKey, function trackerLooksForNewReference(update) {
+			if (update.newValue !== update.oldValue) {
+				this.unsubscribeFromInnerValue();
+				this.unsubscribeFromInnerValue = update.newValue.subscribe(subscriptionKey, trackerCapturesOutboundSignal);
+			}
+		}.bind(this));
+	}
+	supplySignalsToCore(mutableState, latestSignalState, target) {
+		const stateKey = mutableState.key;
+		const storeName = target.config.name;
+		const storeStatus = isChildStore(target) ? target.transactionMeta.update.token.key : `main`;
+		const subscriptionKey = `tracker-to-core:${storeName}:${storeStatus}:${stateKey}`;
+		subscribeToState(target, latestSignalState, subscriptionKey, Object.assign(function trackerCapturesInboundSignal({ newValue, oldValue }) {
+			const timelineId = target.timelineTopics.getRelatedKey(latestSignalState.key);
+			if (timelineId && target.timelines.get(timelineId)?.timeTraveling) {
+				const unsubscribe = subscribeToTimeline(target, {
+					key: timelineId,
+					type: `timeline`
+				}, subscriptionKey, function trackerWaitsForTimeTravelToFinish(update) {
+					unsubscribe();
+					setIntoStore(target, mutableState, (transceiver) => {
+						if (update === `redo` && newValue) transceiver.do(newValue);
+						else if (update === `undo` && oldValue) transceiver.undo(oldValue);
+						return transceiver;
+					});
+				});
+				return;
+			}
+			setIntoStore(target, mutableState, (transceiver) => (transceiver.do(newValue), transceiver));
+		}, { inboundTracker: true }));
+	}
+	mutableAtomToken;
+	latestSignalToken;
+	[Symbol.dispose];
+	constructor(mutableAtomToken, store) {
+		const target = newest(store);
+		const latestSignalToken = this.initializeSignalAtom(mutableAtomToken, target);
+		this.mutableAtomToken = mutableAtomToken;
+		this.latestSignalToken = latestSignalToken;
+		this.captureSignalsFromCore(mutableAtomToken, latestSignalToken, target);
+		this.supplySignalsToCore(mutableAtomToken, latestSignalToken, target);
+		target.trackers.set(mutableAtomToken.key, this);
+		this[Symbol.dispose] = () => {
+			this.unsubscribeFromInnerValue();
+			this.unsubscribeFromState();
+			target.trackers.delete(mutableAtomToken.key);
+		};
+	}
+};
+
 //#endregion
 //#region src/internal/mutable/create-mutable-atom.ts
 function createMutableAtom(store, options, family) {
@@ -1861,6 +2816,177 @@ const getUpdateToken = (mutableAtomToken) => {
 	return updateToken;
 };
 
+//#endregion
+//#region src/internal/mutable/transceiver.ts
+function isTransceiver(value) {
+	return typeof value === `object` && value !== null && `do` in value && `undo` in value && `subscribe` in value && `READONLY_VIEW` in value && `toJSON` in value;
+}
+
+//#endregion
+//#region src/internal/caching.ts
+function writeToCache(target, state, value) {
+	const { key, subject, type } = state;
+	const currentValue = target.valueMap.get(key);
+	if (currentValue instanceof Future && !currentValue.done) {
+		const future = currentValue;
+		if (value instanceof Promise) {
+			future.use(value);
+			return future;
+		}
+		target.valueMap.set(key, value);
+		return value;
+	}
+	if (value instanceof Promise) {
+		const future = new Future(value);
+		target.valueMap.set(key, future);
+		future.then(function handleResolvedFuture(resolved) {
+			if (target.valueMap.get(key) === future) {
+				openOperation(target, state);
+				writeToCache(target, state, resolved);
+				switch (type) {
+					case `atom`:
+						evictDownstreamFromAtom(target, state);
+						break;
+					case `readonly_pure_selector`:
+					case `writable_pure_selector`:
+						evictDownstreamFromSelector(target, key);
+						break;
+				}
+				closeOperation(target);
+				subject.next({
+					newValue: resolved,
+					oldValue: future
+				});
+			}
+		}).catch((thrown) => {
+			target.logger.error(`💥`, state.type, key, `rejected:`, thrown);
+		});
+		return future;
+	}
+	target.logger.info(`📝`, state.type, state.key, `writing to cache`, value);
+	target.valueMap.set(key, value);
+	return value;
+}
+/**
+* @param target - the newest layer of the store
+* @param state - the state to read from cache
+* @param mut - whether the value is intended to be mutable
+* @returns the state's current value
+*/
+function readFromCache(target, state, mut) {
+	target.logger.info(`📖`, state.type, state.key, `reading cached value`);
+	let value = target.valueMap.get(state.key);
+	if (mut === `mut` && state.type === `mutable_atom` && isChildStore(target)) {
+		const mutableAtom$1 = state;
+		const { parent } = target;
+		if (target.valueMap.hasOwn(mutableAtom$1.key)) return value;
+		const parentValue = parent.valueMap.get(mutableAtom$1.key);
+		target.logger.info(`📃`, `atom`, mutableAtom$1.key, `copying`);
+		const jsonValue = parentValue.toJSON();
+		const copiedValue = mutableAtom$1.class.fromJSON(jsonValue);
+		target.valueMap.set(mutableAtom$1.key, copiedValue);
+		new Tracker(mutableAtom$1, parent);
+		value = copiedValue;
+	}
+	return value;
+}
+function evictCachedValue(target, key) {
+	const currentValue = target.valueMap.get(key);
+	if (currentValue instanceof Future) {
+		const selector = target.writableSelectors.get(key) ?? target.readonlySelectors.get(key);
+		if (selector) selector.getFrom(target);
+		return;
+	}
+	if (target.operation.open) target.operation.prev.set(key, currentValue);
+	target.valueMap.delete(key);
+	target.logger.info(`🗑`, `state`, key, `evicted`);
+}
+
+//#endregion
+//#region src/internal/set-state/evict-downstream.ts
+function evictDownstreamFromAtom(store, atom) {
+	const target = newest(store);
+	const { key, type } = atom;
+	const downstreamKeys = target.selectorAtoms.getRelatedKeys(key);
+	target.logger.info(`🧹`, type, key, downstreamKeys ? `evicting ${downstreamKeys.size} states downstream:` : `no downstream states`, downstreamKeys ?? `to evict`);
+	if (downstreamKeys) {
+		if (target.operation.open) target.logger.info(`🧹`, type, key, `[ ${[...target.operation.done].join(`, `)} ] already done`);
+		for (const downstreamKey of downstreamKeys) {
+			if (isDone(target, downstreamKey)) continue;
+			evictCachedValue(target, downstreamKey);
+			markDone(target, downstreamKey);
+		}
+	}
+}
+function evictDownstreamFromSelector(store, selectorKey) {
+	const target = newest(store);
+	const relationEntries = target.selectorGraph.getRelationEntries({ upstreamSelectorKey: selectorKey }).filter(([_, { source }]) => source === selectorKey);
+	for (const [downstreamSelectorKey] of relationEntries) {
+		if (isDone(target, downstreamSelectorKey)) continue;
+		evictCachedValue(target, downstreamSelectorKey);
+		markDone(target, downstreamSelectorKey);
+		evictDownstreamFromSelector(store, downstreamSelectorKey);
+	}
+}
+
+//#endregion
+//#region src/internal/atom/create-regular-atom.ts
+function createRegularAtom(store, options, family, internalRoles) {
+	const type = `atom`;
+	const { key } = options;
+	store.logger.info(`🔨`, type, key, `is being created`);
+	const target = newest(store);
+	const existing = target.atoms.get(key);
+	if (existing && existing.type === type) {
+		store.logger.error(`❌`, `atom`, key, `Tried to create atom, but it already exists in the store.`);
+		return deposit(existing);
+	}
+	const subject = new Subject();
+	const newAtom = {
+		...options,
+		type,
+		install: (s) => {
+			s.logger.info(`🛠️`, type, key, `installing in store "${s.config.name}"`);
+			return createRegularAtom(s, options, family);
+		},
+		subject
+	};
+	if (family) newAtom.family = family;
+	if (internalRoles) newAtom.internalRoles = internalRoles;
+	target.atoms.set(key, newAtom);
+	const token = deposit(newAtom);
+	if (options.effects) {
+		let effectIndex = 0;
+		const cleanupFunctions = [];
+		for (const effect of options.effects) {
+			const cleanup = effect({
+				resetSelf: () => {
+					resetInStore(store, token);
+				},
+				setSelf: (next) => {
+					setIntoStore(store, token, next);
+				},
+				onSet: (handle) => subscribeToState(store, token, `effect[${effectIndex}]`, handle)
+			});
+			if (cleanup) cleanupFunctions.push(cleanup);
+			++effectIndex;
+		}
+		newAtom.cleanup = () => {
+			for (const cleanup of cleanupFunctions) cleanup();
+		};
+	}
+	store.on.atomCreation.next(token);
+	return token;
+}
+
+//#endregion
+//#region src/internal/atom/has-role.ts
+const INTERNAL_ROLES = [`tracker:signal`];
+function hasRole(atom, role) {
+	if (`internalRoles` in atom === false) return false;
+	return atom.internalRoles.includes(role);
+}
+
 //#endregion
 //#region src/internal/atom/dispose-atom.ts
 function disposeAtom(store, atomToken) {
@@ -2650,5 +3776,5 @@ const timeTravel = (store, action, token) => {
 };
 
 //#endregion
-export { CircularBuffer, FamilyTracker, Future, IMPLICIT, INTERNAL_ROLES, Join, Junction, MapOverlay, NotFoundError, RESET_STATE, RelationsOverlay, SetOverlay, StatefulSubject, Store, Subject, TRANSACTION_PHASES, Tracker, abortTransaction, actUponStore, allocateIntoStore, applyTransaction, arbitrary, assignTransactionToContinuity, become, buildTransaction, capitalize, claimWithinStore, clearStore, closeOperation, createClaimTX, createDeallocateTX, createJoin, createMutableAtom, createMutableAtomFamily, createReadonlyHeldSelector, createReadonlyPureSelector, createReadonlyPureSelectorFamily, createRegularAtom, createRegularAtomFamily, createSelectorFamily, createStandaloneSelector, createTimeline, createTransaction, createWritableHeldSelector, createWritablePureSelector, createWritablePureSelectorFamily, deallocateFromStore, deposit, disposeAtom, disposeFromStore, disposeSelector, editRelationsInStore, eldest, evictCachedValue, evictDownstreamFromAtom, evictDownstreamFromSelector, findInStore, findRelationsInStore, fuseWithinStore, getContinuityKey, getEnvironmentData, getEpochNumberOfAction, getEpochNumberOfContinuity, getFamilyOfToken, getFromStore, getInternalRelationsFromStore, getJoin, getJsonFamily, getJsonToken, getSelectorDependencyKeys, getTrace, getUpdateFamily, getUpdateToken, hasRole, ingestAtomUpdateEvent, ingestCreationEvent, ingestDisposalEvent, ingestMoleculeCreationEvent, ingestMoleculeDisposalEvent, ingestMoleculeTransferEvent, ingestSelectorUpdateEvent, ingestTransactionOutcomeEvent, installIntoStore, isAtomKey, isChildStore, isDone, isFn, isReadonlySelectorKey, isReservedIntrospectionKey, isRootStore, isSelectorKey, isStateKey, isTransceiver, makeRootMoleculeInStore, markDone, newest, openOperation, readFromCache, readOrComputeValue, recallState, registerSelector, resetAtomOrSelector, resetInStore, seekInStore, setAtomOrSelector, setEpochNumberOfAction, setEpochNumberOfContinuity, setIntoStore, subscribeInStore, subscribeToRootDependency, subscribeToState, subscribeToTimeline, subscribeToTransaction, timeTravel, traceRootSelectorAtoms, updateSelectorAtoms, withdraw, writeToCache };
+export { CircularBuffer, FamilyTracker, Future, IMPLICIT, INTERNAL_ROLES, JOIN_OP, Join, Junction, MapOverlay, NotFoundError, OWN_OP, RESET_STATE, RelationsOverlay, SetOverlay, StatefulSubject, Store, Subject, TRANSACTION_PHASES, Tracker, abortTransaction, actUponStore, allocateIntoStore, applyTransaction, arbitrary, assignTransactionToContinuity, become, buildTransaction, capitalize, claimWithinStore, clearStore, closeOperation, createClaimTX, createDeallocateTX, createJoin, createMutableAtom, createMutableAtomFamily, createReadonlyHeldSelector, createReadonlyPureSelector, createReadonlyPureSelectorFamily, createRegularAtom, createRegularAtomFamily, createSelectorFamily, createStandaloneSelector, createTimeline, createTransaction, createWritableHeldSelector, createWritablePureSelector, createWritablePureSelectorFamily, deallocateFromStore, deposit, disposeAtom, disposeFromStore, disposeSelector, editRelationsInStore, eldest, evictCachedValue, evictDownstreamFromAtom, evictDownstreamFromSelector, findInStore, findRelationsInStore, fuseWithinStore, getContinuityKey, getEnvironmentData, getEpochNumberOfAction, getEpochNumberOfContinuity, getFamilyOfToken, getFromStore, getInternalRelationsFromStore, getJoin, getJsonFamily, getJsonToken, getSelectorDependencyKeys, getTrace, getUpdateFamily, getUpdateToken, hasRole, ingestAtomUpdateEvent, ingestCreationEvent, ingestDisposalEvent, ingestMoleculeCreationEvent, ingestMoleculeDisposalEvent, ingestMoleculeTransferEvent, ingestSelectorUpdateEvent, ingestTransactionOutcomeEvent, installIntoStore, isAtomKey, isChildStore, isDone, isFn, isReadonlySelectorKey, isReservedIntrospectionKey, isRootStore, isSelectorKey, isStateKey, isTransceiver, makeRootMoleculeInStore, markDone, newest, openOperation, operateOnStore, readFromCache, readOrComputeValue, recallState, registerSelector, resetAtomOrSelector, resetInStore, seekInStore, setAtomOrSelector, setEpochNumberOfAction, setEpochNumberOfContinuity, setIntoStore, subscribeInStore, subscribeToRootDependency, subscribeToState, subscribeToTimeline, subscribeToTransaction, timeTravel, traceRootSelectorAtoms, updateSelectorAtoms, withdraw, writeToCache };
 //# sourceMappingURL=index.js.map