atom.io 0.27.5 → 0.28.0

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

@@ -11,7 +11,7 @@ import { type Canonical, stringifyJson } from "atom.io/json"
 import { findInStore, seekInStore } from "../families"
 import { NotFoundError } from "../not-found-error"
 import type { Store } from "../store"
-import { withdraw } from "../store"
+import { counterfeit, withdraw } from "../store"
 import { readOrComputeValue } from "./read-or-compute-value"
 
 export function getFromStore<T>(store: Store, token: ReadableToken<T>): T
@@ -63,40 +63,49 @@ export function getFromStore(
 	} else {
 		const family = params[0]
 		const key = params[1]
-		const maybeToken =
-			family.type === `molecule_family`
-				? seekInStore(store, family, key)
-				: store.config.lifespan === `immortal`
-					? seekInStore(store, family, key)
-					: findInStore(store, family, key)
-		if (!maybeToken) {
-			store.logger.error(
-				`❗`,
-				family.type,
-				family.key,
-				`tried to get member`,
-				stringifyJson(key),
-				`but it was not found in store`,
-				store.config.name,
-			)
-			switch (family.type) {
-				case `atom_family`:
-				case `mutable_atom_family`:
-					return store.defaults.get(family.key)
-				case `selector_family`:
-				case `readonly_selector_family`: {
-					if (store.defaults.has(family.key)) {
-						return store.defaults.get(family.key)
-					}
-					const defaultValue = withdraw(family, store).default(key)
-					store.defaults.set(family.key, defaultValue)
-					return defaultValue
+		let maybeToken: MoleculeToken<any> | ReadableToken<any>
+		if (family.type === `molecule_family`) {
+			maybeToken = seekInStore(store, family, key) ?? counterfeit(family, key)
+		} else {
+			maybeToken = findInStore(store, family, key)
+		}
+		token = maybeToken
+	}
+	if (`counterfeit` in token && `family` in token) {
+		const family =
+			token.type === `molecule`
+				? withdraw(token.family, store)
+				: // biome-ignore lint/style/noNonNullAssertion: family must be present
+					store.families.get(token.family.key)!
+		const subKey = token.type === `molecule` ? token.key : token.family.subKey
+		const disposal = store.disposalTraces.buffer.find(
+			(item) => item?.key === token.key,
+		)
+		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 `selector_family`:
+			case `readonly_selector_family`: {
+				if (store.defaults.has(family.key)) {
+					return store.defaults.get(token.family.key)
 				}
-				case `molecule_family`:
-					throw new NotFoundError(family, key, store)
+				const defaultValue = withdraw(family, store).default(subKey)
+				store.defaults.set(family.key, defaultValue)
+				return defaultValue
 			}
+			case `molecule_family`:
+				throw new NotFoundError(family, subKey, store)
 		}
-		token = maybeToken
 	}
 	switch (token.type) {
 		case `atom`:

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

@@ -56,7 +56,16 @@ function createInStore(token: ReadableToken<any>, store: Store): void {
 				return
 			}
 			if (store.config.lifespan === `immortal`) {
-				throw new Error(`No molecule found for key "${token.family.subKey}"`)
+				store.logger.error(
+					`🐞`,
+					`atom`,
+					token.family.key,
+					`tried to create member`,
+					`"${token.family.subKey}"`,
+					`but a molecule with that key was not found in store`,
+					`"${store.config.name}"`,
+				)
+				return
 			}
 			initFamilyMemberInStore(store, family, parseJson(token.family.subKey))
 		}

package/internal/src/molecule/dispose-molecule.ts

@@ -15,22 +15,14 @@ export function disposeMolecule<M extends MoleculeConstructor>(
 	store: Store,
 ): void {
 	let molecule: Molecule<M>
-	try {
-		molecule = withdraw(token, store)
-	} catch (thrown) {
-		if (thrown instanceof Error) {
-			store.logger.error(
-				`🐞`,
-				`molecule`,
-				JSON.stringify(token.key),
-				`Failed to dispose molecule, because it was not found in the store.`,
-				thrown.message,
-			)
-		}
-		return
-	}
+	molecule = withdraw(token, store)
 	const { family } = token
 
+	for (const join of molecule.joins.values()) {
+		join.relations.delete(molecule.key)
+		join.molecules.delete(molecule.stringKey)
+	}
+
 	const context: MoleculeToken<any>[] = []
 	for (const above of molecule.above.values()) {
 		context.push(deposit(above))
@@ -79,9 +71,6 @@ export function disposeMolecule<M extends MoleculeConstructor>(
 		store.molecules.delete(molecule.stringKey)
 	}
 
-	for (const join of molecule.joins.values()) {
-		join.molecules.delete(molecule.stringKey)
-	}
 	for (const parent of molecule.above.values()) {
 		parent.below.delete(molecule.stringKey)
 	}

package/internal/src/pretty-print.ts

@@ -18,20 +18,5 @@ export type AtomIOToken =
 	| TransactionToken<any>
 
 export function prettyPrintTokenType(token: AtomIOToken): string {
-	switch (token.type) {
-		case `atom_family`:
-			return `Atom Family`
-		case `molecule_family`:
-			return `Molecule Family`
-		case `mutable_atom_family`:
-			return `Mutable Atom Family`
-		case `readonly_selector`:
-			return `Readonly Selector`
-		case `readonly_selector_family`:
-			return `Readonly Selector Family`
-		case `selector_family`:
-			return `Selector Family`
-		default:
-			return capitalize(token.type)
-	}
+	return token.type.split(`_`).map(capitalize).join(` `)
 }

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

@@ -9,15 +9,8 @@ export function disposeSelector(
 ): void {
 	const target = newest(store)
 	const { key } = selectorToken
-	const selector = target.selectors.get(key) ?? target.readonlySelectors.get(key)
-	if (!selector) {
-		store.logger.info(
-			`❌`,
-			`selector`,
-			key,
-			`Tried to dispose selector, but it does not exist in the store.`,
-		)
-	} else if (!selector.family) {
+	const selector = withdraw(selectorToken, target)
+	if (!selector.family) {
 		store.logger.error(
 			`❌`,
 			`selector`,

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

@@ -1,7 +1,7 @@
 import type { WritableFamilyToken, WritableToken } from "atom.io"
 import { type Canonical, stringifyJson } from "atom.io/json"
 
-import { findInStore, seekInStore } from "../families"
+import { findInStore } from "../families"
 import { closeOperation, openOperation } from "../operation"
 import type { Store } from "../store"
 import { withdraw } from "../store"
@@ -39,26 +39,24 @@ export function setIntoStore<T, New extends T>(
 		const family = params[0]
 		const key = params[1]
 		value = params[2]
-		const maybeToken =
-			store.config.lifespan === `ephemeral`
-				? findInStore(store, family, key)
-				: seekInStore(store, family, key)
-		if (!maybeToken) {
-			store.logger.error(
-				`❗`,
-				family.type,
-				family.key,
-				`tried to set member`,
-				stringifyJson(key),
-				`to`,
-				value,
-				`but it was not found in store`,
-				store.config.name,
-			)
-			return
-		}
+		const maybeToken = findInStore(store, family, key)
 		token = maybeToken
 	}
+	if (`counterfeit` in token) {
+		const disposal = store.disposalTraces.buffer.find(
+			(item) => item?.key === token.key,
+		)
+		store.logger.error(
+			`❌`,
+			token.type,
+			token.key,
+			`could not be set 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.`,
+		)
+		return
+	}
 
 	const rejectionTime = openOperation(token, store)
 	if (rejectionTime) {

package/internal/src/store/circular-buffer.ts

@@ -0,0 +1,34 @@
+export class CircularBuffer<T> {
+	protected _buffer: T[]
+	protected _index = 0
+	public constructor(array: T[])
+	public constructor(length: number)
+	public constructor(lengthOrArray: T[] | number) {
+		let length: number
+		if (typeof lengthOrArray === `number`) {
+			length = lengthOrArray
+		} else {
+			length = lengthOrArray.length
+		}
+		this._buffer = Array.from({ length })
+	}
+
+	public get buffer(): ReadonlyArray<T | undefined> {
+		return this._buffer
+	}
+
+	public get index(): number {
+		return this._index
+	}
+
+	public add(item: T): void {
+		this._buffer[this._index] = item
+		this._index = (this._index + 1) % this._buffer.length
+	}
+
+	public copy(): CircularBuffer<T> {
+		const copy = new CircularBuffer<T>([...this._buffer])
+		copy._index = this._index
+		return copy
+	}
+}

package/internal/src/store/counterfeit.ts

@@ -0,0 +1,109 @@
+import type {
+	AtomFamilyToken,
+	AtomToken,
+	MoleculeConstructor,
+	MoleculeFamilyToken,
+	MoleculeKey,
+	MoleculeToken,
+	MutableAtomFamilyToken,
+	MutableAtomToken,
+	ReadableFamilyToken,
+	ReadableToken,
+	ReadonlySelectorFamilyToken,
+	ReadonlySelectorToken,
+	RegularAtomFamilyToken,
+	RegularAtomToken,
+	SelectorFamilyToken,
+	SelectorToken,
+	WritableFamilyToken,
+	WritableSelectorFamilyToken,
+	WritableSelectorToken,
+	WritableToken,
+} from "atom.io"
+import type { Canonical, Json } from "atom.io/json"
+import { stringifyJson } from "atom.io/json"
+
+import type { Transceiver } from "../mutable"
+
+export const FAMILY_MEMBER_TOKEN_TYPES = {
+	atom_family: `atom`,
+	mutable_atom_family: `mutable_atom`,
+	selector_family: `selector`,
+	readonly_selector_family: `readonly_selector`,
+	molecule_family: `molecule`,
+} as const
+
+export function counterfeit<
+	T extends Transceiver<any>,
+	J extends Json.Serializable,
+	K extends Canonical,
+	Key extends K,
+>(token: MutableAtomFamilyToken<T, J, K>, key: Key): MutableAtomToken<T, J>
+
+export function counterfeit<T, K extends Canonical, Key extends K>(
+	token: RegularAtomFamilyToken<T, K>,
+	key: Key,
+): RegularAtomToken<T>
+
+export function counterfeit<T, K extends Canonical, Key extends K>(
+	token: AtomFamilyToken<T, K>,
+	key: Key,
+): AtomToken<T>
+
+export function counterfeit<T, K extends Canonical, Key extends K>(
+	token: WritableSelectorFamilyToken<T, K>,
+	key: Key,
+): WritableSelectorToken<T>
+
+export function counterfeit<T, K extends Canonical, Key extends K>(
+	token: ReadonlySelectorFamilyToken<T, K>,
+	key: Key,
+): ReadonlySelectorToken<T>
+
+export function counterfeit<T, K extends Canonical, Key extends K>(
+	token: SelectorFamilyToken<T, K>,
+	key: Key,
+): SelectorToken<T>
+
+export function counterfeit<T, K extends Canonical, Key extends K>(
+	token: WritableFamilyToken<T, K>,
+	key: Key,
+): WritableToken<T>
+
+export function counterfeit<T, K extends Canonical, Key extends K>(
+	token: ReadableFamilyToken<T, K>,
+	key: Key,
+): ReadableToken<T>
+
+export function counterfeit<M extends MoleculeConstructor>(
+	token: MoleculeFamilyToken<M>,
+	key: MoleculeKey<M>,
+): MoleculeKey<M>
+
+export function counterfeit(
+	token: MoleculeFamilyToken<any> | ReadableFamilyToken<any, any>,
+	key: Canonical,
+): MoleculeToken<any> | ReadableToken<any> {
+	const subKey = stringifyJson(key)
+	const fullKey = `${token.key}(${subKey})`
+	const type = FAMILY_MEMBER_TOKEN_TYPES[token.type]
+	const stateToken = {
+		key: fullKey,
+		type,
+	} satisfies MoleculeToken<any> | ReadableToken<any>
+	if (type === `molecule`) {
+		Object.assign(stateToken, {
+			key,
+			family: token,
+		})
+	} else {
+		Object.assign(stateToken, {
+			family: {
+				key: token.key,
+				subKey,
+			},
+		})
+	}
+	Object.assign(stateToken, { counterfeit: true })
+	return stateToken
+}

package/internal/src/store/deposit.ts

@@ -97,6 +97,20 @@ export function deposit(
 	state: Molecule<any> | ReadableState<any>,
 ): MoleculeToken<any> | ReadableToken<any>
 
+export function deposit(
+	state:
+		| Molecule<any>
+		| MoleculeFamily<any>
+		| ReadableFamily<any, any>
+		| ReadableState<any>
+		| Transaction<Func>,
+):
+	| MoleculeFamilyToken<any>
+	| MoleculeToken<any>
+	| ReadableFamilyToken<any, any>
+	| ReadableToken<any>
+	| TransactionToken<Func>
+
 export function deposit(
 	state:
 		| Molecule<any>

package/internal/src/store/index.ts

@@ -1,3 +1,4 @@
+export * from "./counterfeit"
 export * from "./deposit"
 export * from "./store"
 export * from "./withdraw"

package/internal/src/store/store.ts

@@ -36,6 +36,7 @@ import type {
 	TransactionProgress,
 } from "../transaction"
 import { isRootStore } from "../transaction"
+import { CircularBuffer } from "./circular-buffer"
 
 export class Store implements Lineage {
 	public parent: Store | null = null
@@ -94,6 +95,8 @@ export class Store implements Lineage {
 		cardinality: `1:n`,
 	})
 
+	public disposalTraces = new CircularBuffer<{ key: string; trace: string }>(100)
+
 	public molecules = new Map<string, Molecule<any>>()
 	public moleculeFamilies = new Map<string, MoleculeFamily<any>>()
 	public moleculeInProgress: string | null = null

package/internal/src/store/withdraw.ts

@@ -155,19 +155,24 @@ export function withdraw<T>(
 	token: TimelineToken<T>,
 	store: Store,
 ): Timeline<T extends TimelineManageable ? T : never>
-export function withdraw<T>(
+
+export function withdraw<T, M extends MoleculeConstructor>(
+	token: MoleculeToken<M> | ReadableToken<T>,
+	store: Store,
+): Molecule<M> | ReadableState<T>
+
+export function withdraw(
 	token:
 		| MoleculeFamilyToken<any>
 		| MoleculeToken<any>
-		| RegularAtomFamilyToken<T, any>
-		| RegularAtomToken<T>
-		| SelectorFamilyToken<T, any>
-		| SelectorToken<T>
-		| TimelineToken<T>
-		| TransactionToken<T extends Func ? T : never>
-		| (T extends Transceiver<any>
-				? MutableAtomFamilyToken<T, any, any> | MutableAtomToken<T, any>
-				: never),
+		| MutableAtomFamilyToken<any, any, any>
+		| MutableAtomToken<any, any>
+		| RegularAtomFamilyToken<any, any>
+		| RegularAtomToken<any>
+		| SelectorFamilyToken<any, any>
+		| SelectorToken<any>
+		| TimelineToken<any>
+		| TransactionToken<any>,
 	store: Store,
 ): Withdrawable {
 	let withdrawn: Withdrawable | undefined

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

@@ -49,6 +49,7 @@ export const buildTransaction = (
 		selectors: new LazyMap(parent.selectors),
 		valueMap: new LazyMap(parent.valueMap),
 		defaults: parent.defaults,
+		disposalTraces: store.disposalTraces.copy(),
 		molecules: new LazyMap(parent.molecules),
 		moleculeFamilies: new LazyMap(parent.moleculeFamilies),
 		moleculeInProgress: parent.moleculeInProgress,

package/introspection/dist/index.d.ts

@@ -1,6 +1,7 @@
 import { AtomToken, SelectorToken, ReadonlySelectorToken, TransactionToken, ReadonlySelectorFamilyToken, TransactionUpdate, TimelineToken, ReadableToken } from 'atom.io';
 import * as Internal from 'atom.io/internal';
-import { Func, Timeline } from 'atom.io/internal';
+import { Func, Timeline, Flat } from 'atom.io/internal';
+import { Json } from 'atom.io/json';
 
 type AtomTokenIndex = WritableTokenIndex<AtomToken<unknown>>;
 
@@ -10,9 +11,10 @@ declare const attachIntrospectionStates: (store?: Internal.Store) => {
     atomIndex: ReadonlySelectorToken<AtomTokenIndex>;
     selectorIndex: ReadonlySelectorToken<SelectorTokenIndex>;
     transactionIndex: ReadonlySelectorToken<TransactionToken<Func>[]>;
-    findTransactionLogState: ReadonlySelectorFamilyToken<TransactionUpdate<Func>[], string>;
+    transactionLogSelectors: ReadonlySelectorFamilyToken<TransactionUpdate<Func>[], string>;
     timelineIndex: ReadonlySelectorToken<TimelineToken<any>[]>;
-    findTimelineState: ReadonlySelectorFamilyToken<Timeline<any>, string>;
+    timelineSelectors: ReadonlySelectorFamilyToken<Timeline<any>, string>;
+    typeSelectors: ReadonlySelectorFamilyToken<string, string>;
 };
 
 type ListResourcesParam = {
@@ -52,10 +54,88 @@ declare class Auditor {
     [Symbol.dispose](): void;
 }
 
+type Refinement<A, B extends A> = (a: A) => a is B;
+type ClassSignature = abstract new (...args: any) => any;
+type RefinementStrategy = ClassSignature | Refinement<unknown, any>;
+type Supported<Refine extends RefinementStrategy> = Refine extends Refinement<unknown, infer T> ? T : Refine extends ClassSignature ? InstanceType<Refine> : never;
+type RefinementSupport = Record<string, RefinementStrategy>;
+declare class Refinery<SupportedTypes extends RefinementSupport> {
+    supported: SupportedTypes;
+    constructor(supported: SupportedTypes);
+    refine<T>(input: T): Flat<{
+        [K in keyof SupportedTypes]: T extends Supported<SupportedTypes[K]> ? {
+            type: K;
+            data: Supported<SupportedTypes[K]>;
+        } : Supported<SupportedTypes[K]> extends T ? {
+            type: K;
+            data: Supported<SupportedTypes[K]>;
+        } : never;
+    }>[keyof SupportedTypes] | (T extends Supported<SupportedTypes[keyof SupportedTypes]> ? never : null);
+}
+declare const primitiveRefinery: Refinery<{
+    number: (input: unknown) => input is number;
+    string: (input: unknown) => input is string;
+    boolean: (input: unknown) => input is boolean;
+    null: (input: unknown) => input is null;
+}>;
+declare const jsonTreeRefinery: Refinery<{
+    object: (input: unknown) => input is Json.Tree.Object;
+    array: (input: unknown) => input is Json.Tree.Array;
+}>;
+declare const jsonRefinery: Refinery<{
+    object: (input: unknown) => input is Json.Tree.Object;
+    array: (input: unknown) => input is Json.Tree.Array;
+    number: (input: unknown) => input is number;
+    string: (input: unknown) => input is string;
+    boolean: (input: unknown) => input is boolean;
+    null: (input: unknown) => input is null;
+}>;
+type JsonType = keyof typeof jsonRefinery.supported;
+declare const discoverType: (input: unknown) => JsonType | `Map` | `Set` | `undefined` | (string & {});
+
+declare function diffNumber(a: number, b: number): Delta;
+declare function diffString(a: string, b: string): Delta;
+declare function diffBoolean(a: boolean, b: boolean): Delta;
+declare function diffObject(a: Json.Tree.Object, b: Json.Tree.Object, recurse: Diff<unknown>): Delta;
+declare function diffArray(a: Json.Tree.Array, b: Json.Tree.Array, recurse: Diff<unknown>): Delta;
+type Delta = {
+    summary: string;
+    added?: [path: string, addedStringifiedValue: string][];
+    removed?: [path: string, removedStringifiedValue: string][];
+    changed?: [path: string, delta: Delta][];
+};
+type Diff<T> = (a: T, b: T) => Delta;
+type DiffTree<T> = (a: T, b: T, recurse: Differ<any, any>[`diff`]) => Delta;
+declare class Differ<Leaf extends Record<string, any>, Tree extends Record<string, any>> {
+    leafRefinery: Refinery<Leaf>;
+    treeRefinery: Refinery<Tree>;
+    leafDiffers: {
+        [KL in keyof Leaf]: Diff<Supported<Leaf[KL]>>;
+    };
+    treeDiffers: {
+        [KT in keyof Tree]: DiffTree<Supported<Tree[KT]>>;
+    };
+    constructor(leafRefinery: Refinery<Leaf>, treeRefinery: Refinery<Tree>, diffFunctions: {
+        [KT in keyof Tree]: DiffTree<Supported<Tree[KT]>>;
+    } & {
+        [KL in keyof Leaf]: Diff<Supported<Leaf[KL]>>;
+    });
+    diff(a: unknown, b: unknown): Delta;
+}
+declare const prettyJson: Differ<{
+    number: (input: unknown) => input is number;
+    string: (input: unknown) => input is string;
+    boolean: (input: unknown) => input is boolean;
+    null: (input: unknown) => input is null;
+}, {
+    object: (input: unknown) => input is Json.Tree.Object;
+    array: (input: unknown) => input is Json.Tree.Array;
+}>;
+
 type FamilyNode<Token extends ReadableToken<unknown>> = {
     key: string;
     familyMembers: Map<string, Token>;
 };
 type WritableTokenIndex<Token extends ReadableToken<unknown>> = Map<string, FamilyNode<Token> | Token>;
 
-export { Auditor, type FamilyNode, type ListResourcesParam, type WritableTokenIndex, attachIntrospectionStates };
+export { Auditor, type ClassSignature, Differ, type FamilyNode, type JsonType, type ListResourcesParam, type Refinement, type RefinementStrategy, type RefinementSupport, Refinery, type Supported, type WritableTokenIndex, attachIntrospectionStates, diffArray, diffBoolean, diffNumber, diffObject, diffString, discoverType, jsonRefinery, jsonTreeRefinery, prettyJson, primitiveRefinery };