atom.io 0.33.21 → 0.34.1

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,7 +90,6 @@ export function join<
 >(
 	options: JoinOptions<ASide, AType, BSide, BType, Cardinality, null>,
 	defaultContent?: undefined,
-	store?: Store,
 ): JoinToken<ASide, AType, BSide, BType, Cardinality, null>
 export function join<
 	const ASide extends string,
@@ -70,8 +101,21 @@ export function join<
 >(
 	options: JoinOptions<ASide, AType, BSide, BType, Cardinality, Content>,
 	defaultContent: Content,
-	store?: Store,
 ): JoinToken<ASide, AType, BSide, BType, Cardinality, 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 - 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<
 	ASide extends string,
 	AType extends string,
@@ -82,19 +126,11 @@ 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)
 }
 
+/** @public */
 export type JoinStates<
 	ASide extends string,
 	AType extends string,
@@ -176,6 +212,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 +235,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 +255,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,

package/src/main/selector.ts

@@ -14,23 +14,35 @@ import type {
 import type { Read, Write } from "./transaction"
 
 export type WritablePureSelectorOptions<T> = {
+	/** The unique identifier of the selector */
 	key: string
+	/** For each instantiated selector, a function that computes its value */
 	get: Read<() => T>
+	/** For each instantiated selector, a function that sets its value */
 	set: Write<(newValue: T) => void>
 }
 export type ReadonlyPureSelectorOptions<T> = {
+	/** The unique identifier of the selector */
 	key: string
+	/** For each instantiated selector, a function that computes its value */
 	get: Read<() => T>
 }
 export type ReadonlyHeldSelectorOptions<T extends object> = {
+	/** The unique identifier of the selector */
 	key: string
+	/** For each instantiated selector, a constant reference to a value that will not be replaced */
 	const: T
+	/** For each instantiated selector, a function that computes its value */
 	get: Read<(permanent: T) => void>
 }
 export type WritableHeldSelectorOptions<T extends object> = {
+	/** The unique identifier of the selector */
 	key: string
+	/** For each instantiated selector, a constant reference to a value that will not be replaced */
 	const: T
+	/** For each instantiated selector, a function that computes its value */
 	get: Read<(permanent: T) => void>
+	/** For each instantiated selector, a function that sets its value */
 	set: Write<(newValue: T) => void>
 }
 
@@ -44,7 +56,7 @@ export type WritableHeldSelectorOptions<T extends object> = {
  * The reference to that object is permanent and will not be replaced.
  *
  * A writable selector can be "set" to a new value.
- * It is advised to set its dependencies to values
+ * It is strongly advised to set its dependencies to values
  * that would produce the new value of the selector.
  *
  * @param options - {@link WritableHeldSelectorOptions}.
@@ -55,7 +67,6 @@ export type WritableHeldSelectorOptions<T extends object> = {
 export function selector<T extends object>(
 	options: WritableHeldSelectorOptions<T>,
 ): WritableHeldSelectorToken<T>
-
 /**
  * @public
  * Declare a selector. The value of a selector should depend
@@ -75,7 +86,6 @@ export function selector<T extends object>(
 export function selector<T extends object>(
 	options: ReadonlyHeldSelectorOptions<T>,
 ): ReadonlyHeldSelectorToken<T>
-
 /**
  * @public
  * Declare a selector. The value of a selector should depend
@@ -85,7 +95,7 @@ export function selector<T extends object>(
  * in order to be garbage collected when a root atom of the selector is set.
  *
  * A writable selector can be "set" to a new value.
- * It is advised to set its dependencies to values
+ * It is strongly advised to set its dependencies to values
  * that would produce the new value of the selector.
  *
  * @param options - {@link TransientWritableSelectorOptions}.
@@ -96,7 +106,6 @@ export function selector<T extends object>(
 export function selector<T>(
 	options: WritablePureSelectorOptions<T>,
 ): WritablePureSelectorToken<T>
-
 /**
  * @public
  * Declare a selector. The value of a selector should depend
@@ -115,7 +124,6 @@ export function selector<T>(
 export function selector<T>(
 	options: ReadonlyPureSelectorOptions<T>,
 ): ReadonlyPureSelectorToken<T>
-
 export function selector(
 	options:
 		| ReadonlyHeldSelectorOptions<any>
@@ -130,55 +138,87 @@ export function selector(
 	return createStandaloneSelector(IMPLICIT.STORE, options)
 }
 
+/** @public */
 export type WritablePureSelectorFamilyOptions<T, K extends Canonical> = {
+	/** The unique identifier of the family */
 	key: string
+	/** For each instantiated family member, a function that computes its value */
 	get: (key: K) => Read<() => T>
+	/** For each instantiated family member, a function that sets its value */
 	set: (key: K) => Write<(newValue: T) => void>
 }
+/** @public */
 export type ReadonlyPureSelectorFamilyOptions<T, K extends Canonical> = {
+	/** The unique identifier of the family */
 	key: string
+	/** For each instantiated family member, a function that computes its value */
 	get: (key: K) => Read<() => T>
 }
+/** @public */
 export type WritableHeldSelectorFamilyOptions<
 	T extends object,
 	K extends Canonical,
 > = {
+	/** The unique identifier of the family */
 	key: string
+	/** For each instantiated family member, a constant reference to a value that will not be replaced */
 	const: (key: K) => T
+	/** For each instantiated family member, a function that computes its value */
 	get: (key: K) => Read<(permanent: T) => void>
+	/** For each instantiated family member, a function that sets its value */
 	set: (key: K) => Write<(newValue: T) => void>
 }
+/** @public */
 export type ReadonlyHeldSelectorFamilyOptions<
 	T extends object,
 	K extends Canonical,
 > = {
+	/** The unique identifier of the family */
 	key: string
+	/** For each instantiated family member, a constant reference to a value that will not be replaced */
 	const: (key: K) => T
+	/** For each instantiated family member, a function that computes its value */
 	get: (key: K) => Read<(permanent: T) => void>
 }
 
 export type WritablePureSelectorFamilyToken<T, K extends Canonical> = {
+	/** The unique identifier of the family */
 	key: string
+	/** Discriminator */
 	type: `writable_pure_selector_family`
+	/** Never present. This is a marker that preserves the type of the value of each family member */
 	__T?: T
+	/** Never present. This is a marker that preserves the type of keys used for each family member */
 	__K?: K
 }
 export type ReadonlyPureSelectorFamilyToken<T, K extends Canonical> = {
+	/** The unique identifier of the family */
 	key: string
+	/** Discriminator */
 	type: `readonly_pure_selector_family`
+	/** Never present. This is a marker that preserves the type of the value of each family member */
 	__T?: T
+	/** Never present. This is a marker that preserves the type of keys used for each family member */
 	__K?: K
 }
 export type WritableHeldSelectorFamilyToken<T, K extends Canonical> = {
+	/** The unique identifier of the family */
 	key: string
+	/** Discriminator */
 	type: `writable_held_selector_family`
+	/** Never present. This is a marker that preserves the type of the value of each family member */
 	__T?: T
+	/** Never present. This is a marker that preserves the type of keys used for each family member */
 	__K?: K
 }
 export type ReadonlyHeldSelectorFamilyToken<T, K extends Canonical> = {
+	/** The unique identifier of the family */
 	key: string
+	/** Discriminator */
 	type: `readonly_held_selector_family`
+	/** Never present. This is a marker that preserves the type of the value of each family member */
 	__T?: T
+	/** Never present. This is a marker that preserves the type of keys used for each family member */
 	__K?: K
 }
 
@@ -200,15 +240,85 @@ export type SelectorFamilyToken<T, K extends Canonical> =
 	| HeldSelectorFamilyToken<T, K>
 	| PureSelectorFamilyToken<T, K>
 
+/**
+ * @public
+ * Create a family of selectors, allowing for the dynamic creation and disposal of selectors.
+ *
+ * The value of a held selector should depend on the value of atoms or other selectors in the store,
+ * and should be recycled when a root atom of the selector is set.
+ *
+ * A held selector's value must be some object.
+ * The reference to that object is permanent and will not be replaced.
+ *
+ * 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 WritableHeldSelectorFamilyOptions}.
+ * @returns
+ * A reference to the selector family created: a {@link WritableHeldSelectorFamilyToken}
+ * @overload WritableHeld
+ */
 export function selectorFamily<T extends object, K extends Canonical>(
 	options: WritableHeldSelectorFamilyOptions<T, K>,
 ): WritableHeldSelectorFamilyToken<T, K>
+/**
+ * @public
+ * Create a family of selectors, allowing for the dynamic creation and disposal of selectors.
+ *
+ * The value of a held selector should depend on the value of atoms or other selectors in the store,
+ * and should be recycled when a root atom of the selector is set.
+ *
+ * A held selector's value must be some object.
+ * The reference to that object is permanent and will not be replaced.
+ *
+ * A readonly selector can be "gotten" but not "set".
+ *
+ * @param options - {@link ReadonlyHeldSelectorFamilyOptions}.
+ * @returns
+ * A reference to the selector family created: a {@link ReadonlyHeldSelectorFamilyToken}
+ * @overload ReadonlyHeld
+ */
 export function selectorFamily<T extends object, K extends Canonical>(
 	options: ReadonlyHeldSelectorFamilyOptions<T, K>,
 ): ReadonlyHeldSelectorFamilyToken<T, K>
+/**
+ * @public
+ * Create a family of selectors, allowing for the dynamic creation and disposal of selectors.
+ *
+ * The value of a selector should depend on the value of atoms or other selectors in the store.
+ *
+ * A pure selector's current value is evicted from the store
+ * in order to be garbage collected when a root atom of the selector is set.
+ *
+ * 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 TransientWritableSelectorFamilyOptions}.
+ * @returns
+ * A reference to the selector family created: a {@link TransientWritableSelectorFamilyToken}
+ * @overload WritablePure
+ */
 export function selectorFamily<T, K extends Canonical>(
 	options: WritablePureSelectorFamilyOptions<T, K>,
 ): WritablePureSelectorFamilyToken<T, K>
+/**
+ * @public
+ * Create a family of selectors, allowing for the dynamic creation and disposal of selectors.
+ *
+ * The value of a selector should depend on the value of atoms or other selectors in the store.
+ *
+ * A pure selector's current value is evicted from the store
+ * in order to be garbage collected when a root atom of the selector is set.
+ *
+ * A readonly selector can be "gotten" but not "set".
+ *
+ * @param options - {@link ReadonlyPureSelectorFamilyOptions}.
+ * @returns
+ * A reference to the selector family created: a {@link ReadonlyPureSelectorFamilyToken}
+ * @overload ReadonlyPure
+ */
 export function selectorFamily<T, K extends Canonical>(
 	options: ReadonlyPureSelectorFamilyOptions<T, K>,
 ): ReadonlyPureSelectorFamilyToken<T, K>