atom.io 0.31.0 → 0.31.1

package/src/atom.ts

@@ -6,59 +6,83 @@ import {
 } from "atom.io/internal"
 import type { Canonical, Json, JsonInterface } from "atom.io/json"
 
-import type { AtomToken, MutableAtomToken, RegularAtomToken } from "."
-
-export type Effectors<T> = {
-	setSelf: <V extends T>(next: V | ((oldValue: T) => V)) => void
-	onSet: (callback: (options: { newValue: T; oldValue: T }) => void) => void
-}
-
-export type AtomEffect<T> = (tools: Effectors<T>) => (() => void) | void
-
-export type RegularAtomOptions<T> = {
-	key: string
-	default: T | (() => T)
-	effects?: AtomEffect<T>[]
-}
-// biome-ignore format: complex intersection
-export type MutableAtomOptions<T extends Transceiver<any>, J extends Json.Serializable> = 
-	& JsonInterface<T, J>
-	& Omit<RegularAtomOptions<T>, `default`> 
-	& { 
-			default: ()	=> T
-			mutable: true
-		}
+import type { AtomToken, MutableAtomToken, RegularAtomToken, Setter } from "."
 
 /**
  * @public
- * Declare a mutable global reactive variable.
- * @param options - Configuration for this mutable atom.
+ * Create a mutable atom, a global reactive variable in the implicit store
+ *
+ * The value of a mutable atom must be some kind of {@link Transceiver}.
+ *
+ * @param options - {@link MutableAtomOptions}.
  * @returns
- * The token for your mutable atom.
+ * A reference to the atom created: a {@link MutableAtomToken}
  * @overload Mutable
  */
 export function atom<T extends Transceiver<any>, J extends Json.Serializable>(
 	options: MutableAtomOptions<T, J>,
 ): MutableAtomToken<T, J>
+
 /**
  * @public
- * Declare a regular global reactive variable.
- * @param options - Configuration for this regular atom.
+ * Create a regular atom, a global reactive variable in the implicit store
+ * @param options - {@link RegularAtomOptions}.
  * @returns
- * The token for your regular atom.
+ * A reference to the atom created: a {@link RegularAtomToken}
  * @overload Regular
  */
 export function atom<T>(options: RegularAtomOptions<T>): RegularAtomToken<T>
-
 export function atom(
 	options: MutableAtomOptions<any, any> | RegularAtomOptions<any>,
 ): AtomToken<any> {
 	return createStandaloneAtom(IMPLICIT.STORE, options)
 }
 
+/** @public */
+export type Effectors<T> = {
+	/**
+	 * Set the value of the atom
+	 * @param next - The new value of the atom, or a setter function
+	 */
+	setSelf: <New extends T>(next: New | Setter<T, New>) => void
+	/** Subscribe to changes to the atom */
+	onSet: (callback: (options: { newValue: T; oldValue: T }) => void) => void
+}
+
+/**
+ * @public
+ * A function that runs side effects when the atom is set
+ * @param tools - {@link Effectors} that can be used to run side effects
+ * @returns
+ * Optionally, a cleanup function that will be called when the atom is disposed
+ */
+export type AtomEffect<T> = (tools: Effectors<T>) => (() => void) | void
+
+/** @public */
+export type RegularAtomOptions<T> = {
+	/** The unique identifier of the atom */
+	key: string
+	/** The starting value of the atom */
+	default: T | (() => T)
+	/** Hooks used to run side effects when the atom is set */
+	effects?: AtomEffect<T>[]
+}
+// biome-ignore format: complex intersection
+export type MutableAtomOptions<T extends Transceiver<any>, J extends Json.Serializable> = 
+	& JsonInterface<T, J>
+	& Omit<RegularAtomOptions<T>, `default`> 
+	& { 
+			default: ()	=> T
+			mutable: true
+		}
+
+/** @public */
 export type RegularAtomFamilyOptions<T, K extends Canonical> = {
+	/** The unique identifier of the atom family */
 	key: string
+	/** 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>[]
 }
 

package/src/dispose-state.ts

@@ -3,13 +3,23 @@ import type { Canonical } from "atom.io/json"
 
 import type { ReadableFamilyToken, ReadableToken } from "."
 
+/**
+ * @public
+ * Disposes of a state in the implicit store
+ * @param token - The token of the state to dispose
+ * @overload Default
+ */
 export function disposeState(token: ReadableToken<any>): void
-
+/**
+ * @public
+ * Disposes of a state family in the implicit store
+ * @param token - The token of the state family to dispose
+ * @param key - The unique key of the state to dispose
+ */
 export function disposeState<K extends Canonical>(
 	token: ReadableFamilyToken<any, K>,
 	key: K,
 ): void
-
 export function disposeState(
 	...[token, key]:
 		| [token: ReadableFamilyToken<any, any>, key: Canonical]

package/src/get-state.ts

@@ -3,8 +3,24 @@ import type { Canonical } from "atom.io/json"
 
 import type { ReadableFamilyToken, ReadableToken } from "."
 
+/**
+ * @public
+ * Get the current value of a state
+ * @param token - The token of the state to get
+ * @return The current value of the state
+ * @overload Default
+ * @default
+ */
 export function getState<T>(token: ReadableToken<T>): T
 
+/**
+ * @public
+ * Get the current value of a state family
+ * @param token - The token of a state family
+ * @param key - The unique key of the state to get
+ * @return The current value of the state
+ * @overload Streamlined
+ */
 export function getState<T, K extends Canonical, Key extends K>(
 	token: ReadableFamilyToken<T, K>,
 	key: Key,

package/src/index.ts

@@ -1,18 +1,25 @@
 import type { Transceiver } from "atom.io/internal"
 import type { Canonical, Json, stringified } from "atom.io/json"
 
-import type { AtomFamilyToken } from "./atom"
+import type { atom, AtomFamilyToken } from "./atom"
+import type { getState } from "./get-state"
 import type {
 	SelectorFamilyToken,
 	WritableSelectorFamilyToken,
 } from "./selector"
+import type { setState } from "./set-state"
+import type { TimelineToken } from "./timeline"
+import type {
+	runTransaction,
+	transaction,
+	TransactionToken,
+} from "./transaction"
 
-export * from "./allocate"
 export * from "./atom"
 export * from "./dispose-state"
 export * from "./get-state"
 export * from "./logger"
-export * from "./molecule"
+export * from "./realm"
 export * from "./selector"
 export * from "./set-state"
 export * from "./silo"
@@ -21,58 +28,121 @@ export * from "./timeline"
 export * from "./transaction"
 export * from "./validators"
 
+/**
+ * @public
+ * A token is an object that uniquely identifies a particular state, family, timeline, or transaction.
+ *
+ * While they represent one of these resources, they are not the resource itself. Think of them like paper currency representing money in the bank.
+ *
+ * Tokens are returned from resource creation functions, such as {@link atom} and {@link transaction}.
+ *
+ * Tokens can be used as parameters to functions that take a token, such as {@link getState}, {@link setState}, or {@link runTransaction}.
+ *
+ * Tokens are fully serializable, so they can be passed between processes.
+ */
+export type AtomIOToken =
+	| ReadableFamilyToken<any, any>
+	| ReadableToken<any>
+	| TimelineToken<any>
+	| TransactionToken<any>
+
+/** @public */
 export type RegularAtomToken<T, K extends Canonical = any> = {
+	/** The unique identifier of the atom. */
 	key: string
+	/** Discriminator. */
 	type: `atom`
+	/** Present if the atom belongs to a family. */
 	family?: FamilyMetadata<K>
+	/** Never present. This is a marker that preserves the type of the atom's value. */
 	__T?: T
 }
+/** @public */
 export type MutableAtomToken<
 	T extends Transceiver<any>,
 	J extends Json.Serializable,
 	K extends Canonical = any,
 > = {
+	/** The unique identifier of the atom. */
 	key: string
+	/** Discriminator. */
 	type: `mutable_atom`
+	/** Present if the atom belongs to a family. */
 	family?: FamilyMetadata<K>
+	/** Never present. This is a marker that preserves the JSON form of the atom's transceiver value. */
 	__J?: J
+	/** Never present. This is a marker that preserves the type of the atom's transceiver value. */
 	__U?: T extends Transceiver<infer Update> ? Update : never
 }
+/** @public */
 export type AtomToken<T, K extends Canonical = any> =
 	| MutableAtomToken<T extends Transceiver<any> ? T : never, any, K>
 	| RegularAtomToken<T, K>
 
+/** @public */
 export type WritableSelectorToken<T, K extends Canonical = any> = {
+	/** The unique identifier of the selector. */
 	key: string
+	/** Discriminator. */
 	type: `selector`
+	/** Present if the selector belongs to a family. */
 	family?: FamilyMetadata<K>
+	/** Never present. This is a marker that preserves the type of the selector's value. */
 	__T?: T
 }
+/** @public */
 export type ReadonlySelectorToken<T, K extends Canonical = any> = {
+	/** The unique identifier of the selector. */
 	key: string
+	/** Discriminator. */
 	type: `readonly_selector`
+	/** Present if the selector belongs to a family. */
 	family?: FamilyMetadata<K>
+	/** Never present. This is a marker that preserves the type of the selector's value. */
 	__T?: T
 }
+/** @public */
 export type SelectorToken<T, K extends Canonical = any> =
 	| ReadonlySelectorToken<T, K>
 	| WritableSelectorToken<T, K>
 
+/**
+ * @public
+ * These states can be set.
+ */
 export type WritableToken<T, K extends Canonical = any> =
 	| AtomToken<T, K>
 	| WritableSelectorToken<T, K>
+/**
+ * @public
+ * These states cannot be set.
+ */
 export type ReadableToken<T, K extends Canonical = any> =
 	| AtomToken<T, K>
 	| SelectorToken<T, K>
 
+/**
+ * @public
+ * States belonging to this family can be set.
+ */
 export type WritableFamilyToken<T, K extends Canonical> =
 	| AtomFamilyToken<T, K>
 	| WritableSelectorFamilyToken<T, K>
+/**
+ * @public
+ * States belonging to this family cannot be set.
+ */
 export type ReadableFamilyToken<T, K extends Canonical> =
 	| AtomFamilyToken<T, K>
 	| SelectorFamilyToken<T, K>
 
+/**
+ * @public
+ * Identifies a state's connection to its family.
+ */
 export type FamilyMetadata<K extends Canonical = any> = {
+	/** The family's unique key. */
 	key: string
+	/** The family member's unique identifier, in the form of a string. */
 	subKey: stringified<K>
 }

package/src/realm.ts

@@ -0,0 +1,169 @@
+import type { Each, Store } from "atom.io/internal"
+import {
+	allocateIntoStore,
+	claimWithinStore,
+	deallocateFromStore,
+	fuseWithinStore,
+	IMPLICIT,
+	makeRootMoleculeInStore,
+} from "atom.io/internal"
+import type { Canonical } from "atom.io/json"
+
+export const $claim = Symbol(`claim`)
+export type Claim<K extends Canonical> = K & { [$claim]?: true }
+
+export class Realm<H extends Hierarchy> {
+	public store: Store
+	public constructor(store: Store = IMPLICIT.STORE) {
+		this.store = store
+		makeRootMoleculeInStore(`root`, store)
+	}
+	public allocate<V extends Vassal<H>, A extends Above<V, H>>(
+		provenance: A,
+		key: V,
+		attachmentStyle?: `all` | `any`,
+	): Claim<V> {
+		return allocateIntoStore<H, V, A>(
+			this.store,
+			provenance,
+			key,
+			attachmentStyle,
+		)
+	}
+	public fuse<
+		C extends CompoundFrom<H>,
+		T extends C extends CompoundTypedKey<infer t, any, any> ? t : never,
+		A extends C extends CompoundTypedKey<any, infer v, any> ? v : never,
+		B extends C extends CompoundTypedKey<any, any, infer m> ? m : never,
+	>(
+		type: T,
+		reagentA: SingularTypedKey<A>,
+		reagentB: SingularTypedKey<B>,
+	): Claim<CompoundTypedKey<T, A, B>> {
+		return fuseWithinStore<H, C, T, A, B>(this.store, type, reagentA, reagentB)
+	}
+
+	public deallocate<V extends Vassal<H>>(claim: Claim<V>): void {
+		deallocateFromStore<H, V>(this.store, claim)
+	}
+	public claim<
+		V extends Exclude<Vassal<H>, CompoundTypedKey>,
+		A extends Above<V, H>,
+	>(newProvenance: A, claim: Claim<V>, exclusive?: `exclusive`): Claim<V> {
+		return claimWithinStore<H, V, A>(this.store, newProvenance, claim, exclusive)
+	}
+}
+
+export class Anarchy {
+	public store: Store
+	public realm: Realm<any>
+
+	public constructor(store: Store = IMPLICIT.STORE) {
+		this.store = store
+		this.realm = new Realm(store)
+	}
+
+	public allocate(
+		provenance: Canonical,
+		key: Canonical,
+		attachmentStyle?: `all` | `any`,
+	): void {
+		allocateIntoStore<any, any, any>(
+			this.store,
+			provenance,
+			key,
+			attachmentStyle,
+		)
+	}
+
+	public deallocate(key: Canonical): void {
+		deallocateFromStore<any, any>(this.store, key)
+	}
+
+	public claim(
+		newProvenance: Canonical,
+		key: Canonical,
+		exclusive?: `exclusive`,
+	): void {
+		claimWithinStore<any, any, any>(this.store, newProvenance, key, exclusive)
+	}
+}
+
+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
+}
+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]
+
+export type CompoundFrom<H extends Hierarchy> = {
+	[K in keyof H]: H[K] extends MutualFealty ? H[K][`below`] : never
+}[keyof H]

package/src/selector.ts

@@ -18,9 +18,29 @@ export type ReadonlySelectorOptions<T> = {
 	get: Read<() => T>
 }
 
+/**
+ * @public
+ * Declare a selector. The value of a selector should depend
+ * on the value of atoms or other selectors in the store.
+ *
+ * A writable selector can be "set" to a new value.
+ * It is advised to set its dependencies to values
+ * that would produce the new value of the selector.
+ * @param options - {@link WritableSelectorOptions}.
+ * @returns
+ * The token for your selector.
+ * @overload Writable
+ */
 export function selector<T>(
 	options: WritableSelectorOptions<T>,
 ): WritableSelectorToken<T>
+
+/**
+ * @public
+ * Declare a selector. The value of a selector should depend
+ * on the value of atoms or other selectors in the store.
+ * @param options - {@link ReadonlySelectorOptions}.
+ */
 export function selector<T>(
 	options: ReadonlySelectorOptions<T>,
 ): ReadonlySelectorToken<T>

package/src/set-state.ts

@@ -3,41 +3,49 @@ import type { Canonical } from "atom.io/json"
 
 import type { WritableFamilyToken, WritableToken } from "."
 
+/**
+ * @public
+ * A function that sets the value of a state.
+ * @param oldValue - The current value of the state.
+ * @returns
+ * The new value of the state.
+ */
+export type Setter<T, New extends T> = (oldValue: T) => New
+
 /**
  * @public
  * Set the value of a state into the implicit store.
- * @param token - The unique identifier of the state to set.
+ * @param token - An atom or writable selector token.
  * @param value - The new value of the state.
  * @overload Default
  * @default
  */
 export function setState<T, New extends T>(
 	token: WritableToken<T>,
-	value: New | ((oldValue: T) => New),
+	value: New | Setter<T, New>,
 ): void
 
 /**
  * @public
  * Set the value of a state into the implicit store.
- * @param token - The unique identifier of a state family.
- * @param key - The key of the state to set.
+ * @param token - An atom family or writable selector family token.
+ * @param key - The unique key of the state to set.
  * @param value - The new value of the state.
  * @overload Streamlined
  */
 export function setState<T, K extends Canonical, New extends T, Key extends K>(
 	token: WritableFamilyToken<T, K>,
 	key: Key,
-	value: New | ((oldValue: T) => New),
+	value: New | Setter<T, New>,
 ): void
-
 export function setState<T, New extends T>(
 	...params:
 		| [
 				token: WritableFamilyToken<T, Canonical>,
 				key: Canonical,
-				value: New | ((oldValue: T) => New),
+				value: New | Setter<T, New>,
 		  ]
-		| [token: WritableToken<T>, value: New | ((oldValue: T) => New)]
+		| [token: WritableToken<T>, value: New | Setter<T, New>]
 ): void {
 	if (params.length === 2) {
 		Internal.setIntoStore(Internal.IMPLICIT.STORE, ...params)

package/src/silo.ts

@@ -11,13 +11,16 @@ import {
 	disposeFromStore,
 	findInStore,
 	getFromStore,
+	IMPLICIT,
 	setIntoStore,
 	Store,
 	subscribeInStore,
 	timeTravel,
 } from "atom.io/internal"
 
+import { installIntoStore } from "../internal/src/install-into-store"
 import type {
+	AtomIOToken,
 	disposeState,
 	getState,
 	redo,
@@ -45,11 +48,11 @@ export class Silo {
 	public subscribe: typeof subscribe
 	public undo: typeof undo
 	public redo: typeof redo
-
 	public runTransaction: typeof runTransaction
+	public install: (tokens: AtomIOToken[], store?: Store) => void
+
 	public constructor(config: Store[`config`], fromStore: Store | null = null) {
-		const s = new Store(config, fromStore)
-		this.store = s
+		const s = (this.store = new Store(config, fromStore))
 		this.atom = ((options: Parameters<typeof atom>[0]) =>
 			createStandaloneAtom(s, options)) as typeof atom
 		this.atomFamily = ((options: Parameters<typeof atomFamily>[0]) =>
@@ -79,5 +82,8 @@ export class Silo {
 			timeTravel(s, `redo`, token)
 		}
 		this.runTransaction = (token, id = arbitrary()) => actUponStore(token, id, s)
+		this.install = (tokens, source = IMPLICIT.STORE) => {
+			installIntoStore(tokens, s, source)
+		}
 	}
 }

package/transceivers/set-rtx/dist/index.js

@@ -85,7 +85,10 @@ var SetRTX = class _SetRTX extends Set {
         this.emit(`tx:${this.transactionUpdates.join(`;`)}`);
       }
     } catch (thrown) {
-      console.error(`Failed to apply transaction to SetRTX:`, thrown);
+      console.warn(
+        `Did not apply transaction to SetRTX; this error was thrown:`,
+        thrown
+      );
       throw thrown;
     } finally {
       unsubscribe();

package/transceivers/set-rtx/src/set-rtx.ts

@@ -111,7 +111,10 @@ export class SetRTX<P extends primitive>
 			}
 		} catch (thrown) {
 			/* eslint-disable-next-line no-console */
-			console.error(`Failed to apply transaction to SetRTX:`, thrown)
+			console.warn(
+				`Did not apply transaction to SetRTX; this error was thrown:`,
+				thrown,
+			)
 			throw thrown
 		} finally {
 			unsubscribe()