atom.io 0.34.0 → 0.34.2

package/src/main/atom.ts

@@ -22,7 +22,6 @@ import type { AtomToken, MutableAtomToken, RegularAtomToken, Setter } from "."
 export function atom<T extends Transceiver<any>, J extends Json.Serializable>(
 	options: MutableAtomOptions<T, J>,
 ): MutableAtomToken<T, J>
-
 /**
  * @public
  * Create a regular atom, a global reactive variable in the implicit store
@@ -71,14 +70,24 @@ export type RegularAtomOptions<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> = 
+
+/** @public */
+// biome-ignore format: intersection
+export type MutableAtomOptions<
+	T extends Transceiver<any>,
+	J extends Json.Serializable,
+> =
 	& JsonInterface<T, J>
-	& Omit<RegularAtomOptions<T>, `default`> 
-	& { 
-			default: ()	=> T
-			mutable: true
-		}
+	& {
+		/** Used to signal that the atom is mutable */
+		mutable: true
+		/** The unique identifier of the atom */
+		key: string
+		/** A function to create an initial value for the atom */
+		default: () => T
+		/** Hooks used to run side effects when the atom is set */
+		effects?: AtomEffect<T>[]
+	}
 
 /** @public */
 export type RegularAtomFamilyOptions<T, K extends Canonical> = {
@@ -91,24 +100,33 @@ export type RegularAtomFamilyOptions<T, K extends Canonical> = {
 }
 
 export type RegularAtomFamilyToken<T, K extends Canonical> = {
+	/** The unique identifier of the atom family */
 	key: string
+	/** Discriminator */
 	type: `atom_family`
+	/** Never present. This is a marker that preserves the type of atoms in this family */
 	__T?: T
+	/** Never present. This is a marker that preserves the type of keys used for atoms in this family */
 	__K?: K
 }
 
+/** @public */
 // biome-ignore format: intersection
 export type MutableAtomFamilyOptions<
 	T extends Transceiver<any>,
 	J extends Json.Serializable,
 	K extends Canonical,
-> = 
+> =
 	& JsonInterface<T, J>
-	& { 
+	& {
+		/** Used to signal that the atoms created from this family are mutable */
+		mutable: true
+		/** The unique identifier of the atom family */
 		key: string
+		/** A function to create an initial value for each atom in the family */
 		default: (key: K) => T
+		/** Hooks used to run side effects when an atom in the family is set  */
 		effects?: (key: K) => AtomEffect<T>[]
-		mutable: true,
 	}
 
 export type MutableAtomFamilyToken<
@@ -116,22 +134,45 @@ export type MutableAtomFamilyToken<
 	J extends Json.Serializable,
 	K extends Canonical,
 > = {
+	/** The unique identifier of the atom family */
 	key: string
+	/** Discriminator */
 	type: `mutable_atom_family`
+	/** Never present. This is a marker that preserves the type of atoms in this family */
 	__T?: T
+	/** Never present. This is a marker that preserves the type of the JSON form of atoms in this family */
 	__J?: J
+	/** Never present. This is a marker that preserves the type of keys used for atoms in this family */
 	__K?: K
 }
-
 export type AtomFamilyToken<T, K extends Canonical = Canonical> =
 	| MutableAtomFamilyToken<T extends Transceiver<any> ? T : never, any, K>
 	| RegularAtomFamilyToken<T, K>
 
+/**
+ * @public
+ * Create a family of mutable atoms, allowing for the dynamic creation and disposal of atoms.
+ *
+ * The value of a mutable atom must be some kind of {@link Transceiver}.
+ *
+ * @param options - {@link MutableAtomFamilyOptions}
+ * @returns
+ * A reference to the atom family created: a {@link MutableAtomFamilyToken}
+ * @overload Mutable
+ */
 export function atomFamily<
 	T extends Transceiver<any>,
 	J extends Json.Serializable,
 	K extends Canonical,
 >(options: MutableAtomFamilyOptions<T, J, K>): MutableAtomFamilyToken<T, J, K>
+/**
+ * @public
+ * Create a family of regular atoms, allowing for the dynamic creation and disposal of atoms.
+ * @param options - {@link RegularAtomFamilyOptions}
+ * @returns
+ * A reference to the atom family created: a {@link RegularAtomFamilyToken}
+ * @overload Regular
+ */
 export function atomFamily<T, K extends Canonical>(
 	options: RegularAtomFamilyOptions<T, K>,
 ): RegularAtomFamilyToken<T, K>

package/src/main/dispose-state.ts

@@ -5,14 +5,20 @@ import type { ReadableFamilyToken, ReadableToken } from "."
 
 /**
  * @public
- * Disposes of a state in the implicit store
+ * Disposes of a state in the implicit store.
+ *
+ * Only family members can be disposed of.
+ *
  * @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
+ * Disposes of a state in the implicit store.
+ *
+ * Only family members can be disposed of.
+ *
  * @param token - The token of the state family to dispose
  * @param key - The unique key of the state to dispose
  */

package/src/main/find-state.ts

@@ -3,13 +3,13 @@ import type {
 	MutableAtomToken,
 	ReadableFamilyToken,
 	ReadableToken,
-	ReadonlyPureSelectorFamilyToken,
-	ReadonlyPureSelectorToken,
+	ReadonlySelectorFamilyToken,
+	ReadonlySelectorToken,
 	RegularAtomFamilyToken,
 	RegularAtomToken,
 	WritableFamilyToken,
-	WritablePureSelectorFamilyToken,
-	WritablePureSelectorToken,
+	WritableSelectorFamilyToken,
+	WritableSelectorToken,
 	WritableToken,
 } from "atom.io"
 import type { Transceiver } from "atom.io/internal"
@@ -18,7 +18,12 @@ import type { Canonical, Json } from "atom.io/json"
 
 /**
  * @public
- * Finds a {@link MutableAtomToken} in the store
+ * Finds a {@link MutableAtomToken} in the store, without accessing its value.
+ *
+ * In an ephemeral store, this will create a new atom if one does not exist with the given key.
+ *
+ * In an immortal store, a "counterfeit" atom token will be returned in this case and a warning will be logged.
+ *
  * @param token - A {@link MutableAtomFamilyToken}
  * @param key - The key of the state
  * @returns
@@ -33,7 +38,12 @@ export function findState<
 >(token: MutableAtomFamilyToken<T, J, K>, key: Key): MutableAtomToken<T, J, K>
 /**
  * @public
- * Finds a state in the store
+ * Finds a {@link RegularAtomToken} in the store, without accessing its value.
+ *
+ * In an ephemeral store, this will create a new atom if one does not exist with the given key.
+ *
+ * In an immortal store, a "counterfeit" atom token will be returned in this case and a warning will be logged.
+ *
  * @param token - The token of the state family
  * @param key - The key of the state
  * @returns
@@ -46,7 +56,12 @@ export function findState<T, K extends Canonical, Key extends K>(
 ): RegularAtomToken<T, K>
 /**
  * @public
- * Finds a state in the store
+ * Finds a {@link WritableSelectorToken} in the store, without accessing its value.
+ *
+ * In an ephemeral store, this will create a new selector if one does not exist with the given key.
+ *
+ * In an immortal store, a "counterfeit" selector token will be returned in this case and a warning will be logged.
+ *
  * @param token - The token of the state family
  * @param key - The key of the state
  * @returns
@@ -54,12 +69,17 @@ export function findState<T, K extends Canonical, Key extends K>(
  * @overload Writable Selector
  */
 export function findState<T, K extends Canonical, Key extends K>(
-	token: WritablePureSelectorFamilyToken<T, K>,
+	token: WritableSelectorFamilyToken<T, K>,
 	key: Key,
-): WritablePureSelectorToken<T, K>
+): WritableSelectorToken<T, K>
 /**
  * @public
- * Finds a state in the store
+ * Finds a {@link ReadonlySelectorToken} in the store, without accessing its value.
+ *
+ * In an ephemeral store, this will create a new selector if one does not exist with the given key.
+ *
+ * In an immortal store, a "counterfeit" selector token will be returned in this case and a warning will be logged.
+ *
  * @param token - The token of the state family
  * @param key - The key of the state
  * @returns
@@ -67,12 +87,17 @@ export function findState<T, K extends Canonical, Key extends K>(
  * @overload Readonly Selector
  */
 export function findState<T, K extends Canonical, Key extends K>(
-	token: ReadonlyPureSelectorFamilyToken<T, K>,
+	token: ReadonlySelectorFamilyToken<T, K>,
 	key: Key,
-): ReadonlyPureSelectorToken<T, K>
+): ReadonlySelectorToken<T, K>
 /**
  * @public
- * Finds a state in the store
+ * Finds a {@link WritableToken} in the store, without accessing its value.
+ *
+ * In an ephemeral store, this will create a new atom or selector if one does not exist with the given key.
+ *
+ * In an immortal store, a "counterfeit" token will be returned in this case and a warning will be logged.
+ *
  * @param token - The token of the state family
  * @param key - The key of the state
  * @returns
@@ -85,7 +110,12 @@ export function findState<T, K extends Canonical, Key extends K>(
 ): WritableToken<T, K>
 /**
  * @public
- * Finds a {@link ReadableToken} in the store
+ * Finds a {@link MutableAtomToken} in the store, without accessing its value.
+ *
+ * In an ephemeral store, this will create a new atom or selector if one does not exist with the given key.
+ *
+ * In an immortal store, a "counterfeit" token will be returned in this case and a warning will be logged.
+ *
  * @param token - A {@link ReadableFamilyToken}
  * @param key - The key of the state
  * @returns

package/src/main/get-state.ts

@@ -5,7 +5,7 @@ import type { ReadableFamilyToken, ReadableToken } from "."
 
 /**
  * @public
- * Get the current value of a state
+ * Read or compute the current value of a state
  * @param token - The token of the state to get
  * @return The current value of the state
  * @overload Default
@@ -15,7 +15,7 @@ export function getState<T>(token: ReadableToken<T>): T
 
 /**
  * @public
- * Get the current value of a state family
+ * Read or compute the current value of a state
  * @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

package/src/main/index.ts

@@ -189,4 +189,12 @@ export type FamilyMetadata<K extends Canonical = any> = {
 	subKey: stringified<K>
 }
 
+/**
+ * @public
+ * Loadable is used to type atoms or selectors that may at some point be initialized to or set to a {@link Promise}.
+ *
+ * When a Promise is cached as the value of a state in atom.io, that state will be automatically set to the resolved value of the Promise when it is resolved.
+ *
+ * As a result, we consider any state that can be a set to a Promise to be a "loadable" state, whose value may or may not be a Promise at any given time.
+ */
 export type Loadable<T> = Promise<T> | T

package/src/main/join.ts

@@ -1,36 +1,46 @@
 import type { MutableAtomFamilyToken, ReadonlyPureSelectorToken } from "atom.io"
 import type {
+	Flat,
 	Junction,
 	JunctionEntriesBase,
 	JunctionSchemaBase,
 	Refinement,
-	Store,
 } from "atom.io/internal"
 import {
+	createJoin,
 	editRelationsInStore,
 	findRelationsInStore,
 	getInternalRelationsFromStore,
 	IMPLICIT,
-	Join,
 } from "atom.io/internal"
 import type { Json } from "atom.io/json"
 import type { SetRTX, SetRTXJson } from "atom.io/transceivers/set-rtx"
 
-export interface JoinOptions<
+/** @public */
+// biome-ignore format: intersection
+export type JoinOptions<
 	ASide extends string,
 	AType extends string,
 	BSide extends string,
 	BType extends string,
 	Cardinality extends `1:1` | `1:n` | `n:n`,
 	Content extends Json.Object | null,
-> extends JunctionSchemaBase<ASide, BSide>,
-		Partial<JunctionEntriesBase<AType, BType, Content>> {
-	readonly key: string
-	readonly cardinality: Cardinality
-	readonly isAType: Refinement<string, AType>
-	readonly isBType: Refinement<string, BType>
-}
+> =
+	Flat<
+		& JunctionSchemaBase<ASide, BSide>
+		& {
+			/** Unique identifier of the join */
+			readonly key: string
+			/** How many relations are allowed in each direction? */
+			readonly cardinality: Cardinality
+			/** Type guard for the type of the left side */
+			readonly isAType: Refinement<string, AType>
+			/** Type guard for the type of the right side */
+			readonly isBType: Refinement<string, BType>
+		}
+	> & Partial<JunctionEntriesBase<AType, BType, Content>>
 
+/** @public */
 export type JoinToken<
 	ASide extends string,
 	AType extends string,
@@ -39,16 +49,38 @@ export type JoinToken<
 	Cardinality extends `1:1` | `1:n` | `n:n`,
 	Content extends Json.Object | null = null,
 > = {
+	/** Unique identifier of the join */
 	key: string
+	/** Discriminator */
 	type: `join`
+	/** How many relations are allowed in each direction? */
 	cardinality: Cardinality
+	/** Name of the join's left side */
 	a: ASide
+	/** Name of the join's right side */
 	b: BSide
+	/** Never present. This is a marker that preserves the type of the left side's keys */
 	__aType?: AType
+	/** Never present. This is a marker that preserves the type of the right side's keys */
 	__bType?: BType
+	/** Never present. This is a marker that preserves the type of the data present for each relation */
 	__content?: Content
 }
 
+/**
+ * @public
+ * Create a join, an interface for managing relations between two sets of keys.
+ *
+ * Use joins when it is important to view relationships from either side.
+ *
+ * Under the hood, joins coordinate changes of multiple atoms to support that the desired relationships stay consistent.
+ *
+ * @param options - {@link JoinOptions}
+ * @param defaultContent - (undefined)
+ * @returns
+ * A reference to the join created: a {@link JoinToken}
+ * @overload No Content
+ */
 export function join<
 	const ASide extends string,
 	const AType extends string,
@@ -58,8 +90,21 @@ export function join<
 >(
 	options: JoinOptions<ASide, AType, BSide, BType, Cardinality, null>,
 	defaultContent?: undefined,
-	store?: Store,
 ): JoinToken<ASide, AType, BSide, BType, Cardinality, null>
+/**
+ * @public
+ * Create a join, an interface for managing relations between two sets of keys.
+ *
+ * Use joins when it is important to view relationships from either side.
+ *
+ * Under the hood, joins coordinate changes of multiple atoms to support that the desired relationships stay consistent.
+ *
+ * @param options - {@link JoinOptions}
+ * @param defaultContent - The default value for the content of each relation
+ * @returns
+ * A reference to the join created: a {@link JoinToken}
+ * @overload With Content
+ */
 export function join<
 	const ASide extends string,
 	const AType extends string,
@@ -70,7 +115,6 @@ export function join<
 >(
 	options: JoinOptions<ASide, AType, BSide, BType, Cardinality, Content>,
 	defaultContent: Content,
-	store?: Store,
 ): JoinToken<ASide, AType, BSide, BType, Cardinality, Content>
 export function join<
 	ASide extends string,
@@ -82,17 +126,8 @@ export function join<
 >(
 	options: JoinOptions<ASide, AType, BSide, BType, Cardinality, Content>,
 	defaultContent: Content | undefined,
-	store: Store = IMPLICIT.STORE,
 ): JoinToken<ASide, AType, BSide, BType, Cardinality, Content> {
-	store.joins.set(options.key, new Join(options, defaultContent, store))
-	const token: JoinToken<ASide, AType, BSide, BType, Cardinality, Content> = {
-		key: options.key,
-		type: `join`,
-		a: options.between[0],
-		b: options.between[1],
-		cardinality: options.cardinality,
-	}
-	return token
+	return createJoin(IMPLICIT.STORE, options, defaultContent)
 }
 
 export type JoinStates<
@@ -176,6 +211,15 @@ export type JoinStates<
 				}
 			: never
 
+/**
+ * @public
+ * Find the current value of a relation owned by a {@link join}
+ * @param token - The token of the join
+ * @param key - The key of the relation to find
+ * @returns
+ * A {@link JoinStates} interface to access the relation
+ * @overload Default
+ */
 export function findRelations<
 	ASide extends string,
 	AType extends string,
@@ -190,6 +234,12 @@ export function findRelations<
 	return findRelationsInStore(token, key, IMPLICIT.STORE)
 }
 
+/**
+ * @public
+ * Change one or multiple relations owned by a {@link join}
+ * @param token - The token of the join
+ * @param change - A function that takes a {@link Junction} interface to edit the relations
+ */
 export function editRelations<
 	ASide extends string,
 	AType extends string,
@@ -204,6 +254,12 @@ export function editRelations<
 	editRelationsInStore(token, change, IMPLICIT.STORE)
 }
 
+/**
+ * @public
+ * @param token - The token of the join
+ * @returns
+ * A {@link MutableAtomFamilyToken} to access the internal relations
+ */
 export function getInternalRelations<
 	ASide extends string,
 	AType extends string,

package/src/main/realm.ts

@@ -14,10 +14,21 @@ export type Claim<K extends Canonical> = K & { [$claim]?: true }
 
 export class Realm<H extends Hierarchy> {
 	public store: Store
+	/**
+	 * @param store - The store to which the realm will be attached
+	 */
 	public constructor(store: Store = IMPLICIT.STORE) {
 		this.store = store
 		makeRootMoleculeInStore(`root`, store)
 	}
+	/**
+	 * Make space for a new subject of the realm
+	 * @param provenance - A key for an owner {@link Above} the new subject in the realm's {@link 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}
+	 */
 	public allocate<V extends Vassal<H>, A extends Above<V, H>>(
 		provenance: A,
 		key: V,
@@ -30,6 +41,14 @@ export class Realm<H extends Hierarchy> {
 			attachmentStyle,
 		)
 	}
+	/**
+	 * 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 true {@link Claim}
+	 */
 	public fuse<
 		C extends CompoundFrom<H>,
 		T extends C extends CompoundTypedKey<infer t, any, any> ? t : never,
@@ -42,10 +61,21 @@ export class Realm<H extends Hierarchy> {
 	): Claim<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 {
 		deallocateFromStore<H, V>(this.store, claim)
 	}
+	/**
+	 * Transfer a subject of the realm from one owner to another
+	 * @param newProvenance - A key for an owner {@link Above} the new subject in the realm's {@link 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}
+	 */
 	public claim<
 		V extends Exclude<Vassal<H>, CompoundTypedKey>,
 		A extends Above<V, H>,
@@ -58,11 +88,19 @@ export class Anarchy {
 	public store: Store
 	public realm: Realm<any>
 
+	/**
+	 * @param store - The store to which the anarchy-realm will be attached
+	 */
 	public constructor(store: Store = IMPLICIT.STORE) {
 		this.store = store
 		this.realm = new Realm(store)
 	}
-
+	/**
+	 * Declare a new entity
+	 * @param provenance - A key for an owner of the entity
+	 * @param key - A unique identifier for the new entity
+	 * @param attachmentStyle - The attachment style of new entity 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 .
+	 */
 	public allocate(
 		provenance: Canonical,
 		key: Canonical,
@@ -75,11 +113,19 @@ export class Anarchy {
 			attachmentStyle,
 		)
 	}
-
+	/**
+	 * Remove an entity
+	 * @param key - The entity to be deallocated
+	 */
 	public deallocate(key: Canonical): void {
 		deallocateFromStore<any, any>(this.store, key)
 	}
-
+	/**
+	 * Transfer an entity from one owner to another
+	 * @param newProvenance - A key for an owner of the entity
+	 * @param key - The entity to be claimed
+	 * @param exclusive - Whether the entity's previous owners should be detached from it
+	 */
 	public claim(
 		newProvenance: Canonical,
 		key: Canonical,