atom.io 0.33.21 → 0.34.1

package/dist/main/index.d.ts

@@ -1,6 +1,6 @@
 import { Each, EnvironmentData, Flat, Func, Junction, JunctionEntriesBase, JunctionSchemaBase, Refinement, Store, Timeline, TimelineAtomUpdate, TimelineMoleculeCreation, TimelineMoleculeDisposal, TimelineSelectorUpdate, TimelineStateCreation, TimelineStateDisposal, TimelineTransactionUpdate, Transceiver } from "atom.io/internal";
 import { Canonical, Json, JsonInterface, stringified } from "atom.io/json";
-import { MutableAtomFamilyToken as MutableAtomFamilyToken$1, MutableAtomToken as MutableAtomToken$1, ReadableFamilyToken as ReadableFamilyToken$1, ReadableToken as ReadableToken$1, ReadonlyPureSelectorFamilyToken as ReadonlyPureSelectorFamilyToken$1, ReadonlyPureSelectorToken as ReadonlyPureSelectorToken$1, RegularAtomFamilyToken as RegularAtomFamilyToken$1, RegularAtomToken as RegularAtomToken$1, WritableFamilyToken as WritableFamilyToken$1, WritablePureSelectorFamilyToken as WritablePureSelectorFamilyToken$1, WritablePureSelectorToken as WritablePureSelectorToken$1, WritableToken as WritableToken$1, findState as findState$1, getState as getState$1, setState as setState$1 } from "atom.io";
+import { MutableAtomFamilyToken as MutableAtomFamilyToken$1, MutableAtomToken as MutableAtomToken$1, ReadableFamilyToken as ReadableFamilyToken$1, ReadableToken as ReadableToken$1, ReadonlyPureSelectorFamilyToken as ReadonlyPureSelectorFamilyToken$1, ReadonlyPureSelectorToken as ReadonlyPureSelectorToken$1, ReadonlySelectorFamilyToken as ReadonlySelectorFamilyToken$1, ReadonlySelectorToken as ReadonlySelectorToken$1, RegularAtomFamilyToken as RegularAtomFamilyToken$1, RegularAtomToken as RegularAtomToken$1, WritableFamilyToken as WritableFamilyToken$1, WritablePureSelectorFamilyToken as WritablePureSelectorFamilyToken$1, WritablePureSelectorToken as WritablePureSelectorToken$1, WritableSelectorFamilyToken as WritableSelectorFamilyToken$1, WritableSelectorToken as WritableSelectorToken$1, WritableToken as WritableToken$1, findState as findState$1, getState as getState$1, setState as setState$1 } from "atom.io";
 import { SetRTX, SetRTXJson } from "atom.io/transceivers/set-rtx";
 
 //#region src/main/atom.d.ts
@@ -60,9 +60,16 @@ type RegularAtomOptions<T> = {
   /** Hooks used to run side effects when the atom is set */
   effects?: AtomEffect<T>[];
 };
-type MutableAtomOptions<T extends Transceiver<any>, J extends Json.Serializable> = JsonInterface<T, J> & Omit<RegularAtomOptions<T>, `default`> & {
-  default: () => T;
+/** @public */
+type MutableAtomOptions<T extends Transceiver<any>, J extends Json.Serializable> = JsonInterface<T, J> & {
+  /** 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 */
 type RegularAtomFamilyOptions<T, K extends Canonical> = {
@@ -74,26 +81,59 @@ type RegularAtomFamilyOptions<T, K extends Canonical> = {
   effects?: (key: K) => AtomEffect<T>[];
 };
 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 */
 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;
 };
 type MutableAtomFamilyToken<T extends Transceiver<any>, 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;
 };
 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
+*/
 declare 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
+*/
 declare function atomFamily<T, K extends Canonical>(options: RegularAtomFamilyOptions<T, K>): RegularAtomFamilyToken<T, K>;
 //#endregion
 //#region src/main/reset-state.d.ts
@@ -115,45 +155,58 @@ declare function resetState(token: WritableToken<any>): void;
 declare function resetState<K extends Canonical>(token: WritableFamilyToken<any, K>, key: K): void;
 //#endregion
 //#region src/main/transaction.d.ts
+/** @public */
 type TransactionToken<F extends Func> = {
+  /** The unique identifier of the transaction */
   key: string;
+  /** Discriminator */
   type: `transaction`;
+  /** Never present. This is a marker that preserves the type of the transaction function */
   __F?: F;
 };
+/** @public */
 type StateCreation<Token extends ReadableToken<any>> = {
   type: `state_creation`;
   token: Token;
 };
+/** @public */
 type AtomDisposal<Token extends ReadableToken<any>> = {
   type: `state_disposal`;
   subType: `atom`;
   token: Token;
   value: TokenType<Token>;
 };
+/** @public */
 type SelectorDisposal<Token extends ReadableToken<any>> = {
   type: `state_disposal`;
   subType: `selector`;
   token: Token;
 };
+/** @public */
 type StateDisposal<Token extends ReadableToken<any>> = AtomDisposal<Token> | SelectorDisposal<Token>;
+/** @public */
 type MoleculeCreation = {
   type: `molecule_creation`;
   key: Canonical;
   provenance: Canonical;
 };
+/** @public */
 type MoleculeDisposal = {
   type: `molecule_disposal`;
   key: Canonical;
   provenance: stringified<Canonical>[];
   values: [key: string, value: any][];
 };
+/** @public */
 type MoleculeTransfer = {
   type: `molecule_transfer`;
   key: Canonical;
   from: Canonical[];
   to: Canonical[];
 };
+/** @public */
 type TransactionUpdateContent = KeyedStateUpdate<unknown> | MoleculeCreation | MoleculeDisposal | MoleculeTransfer | StateCreation<ReadableToken<unknown>> | StateDisposal<ReadableToken<unknown>> | TransactionUpdate<Func>;
+/** @public */
 type TransactionUpdate<F extends Func> = {
   type: `transaction_update`;
   key: string;
@@ -163,13 +216,16 @@ type TransactionUpdate<F extends Func> = {
   params: Parameters<F>;
   output: ReturnType<F>;
 };
+/** @public */
 type GetterToolkit = Pick<SetterToolkit, `find` | `get` | `json`>;
+/** @public */
 type SetterToolkit = Readonly<{
   get: typeof getState$1;
   set: typeof setState$1;
   find: typeof findState$1;
   json: <T extends Transceiver<any>, J extends Json.Serializable>(state: MutableAtomToken<T, J>) => WritablePureSelectorToken<J>;
 }>;
+/** @public */
 type ActorToolkit = Readonly<{
   get: typeof getState$1;
   set: typeof setState$1;
@@ -180,36 +236,68 @@ type ActorToolkit = Readonly<{
   run: typeof runTransaction;
   env: () => EnvironmentData;
 }>;
+/** @public */
 type Read<F extends Func> = (toolkit: GetterToolkit, ...parameters: Parameters<F>) => ReturnType<F>;
+/** @public */
 type Write<F extends Func> = (toolkit: SetterToolkit, ...parameters: Parameters<F>) => ReturnType<F>;
+/** @public */
 type Transact<F extends Func> = (toolkit: ActorToolkit, ...parameters: Parameters<F>) => ReturnType<F>;
+/** @public */
+type TransactionIO<Token extends TransactionToken<any>> = Token extends TransactionToken<infer F> ? F : never;
+/** @public */
 type TransactionOptions<F extends Func> = {
+  /** The unique identifier of the transaction */
   key: string;
+  /** The operation to perform */
   do: Transact<F>;
 };
-type TransactionIO<Token extends TransactionToken<any>> = Token extends TransactionToken<infer F> ? F : never;
+/**
+* @public
+* Create a transaction, a mechanism for batching updates multiple states in a single, all-or-nothing operation
+* @param options - {@link TransactionOptions}
+* @returns A reference to the transaction created: a {@link TransactionToken}
+*/
 declare function transaction<F extends Func>(options: TransactionOptions<F>): TransactionToken<F>;
+/**
+* @public
+* Execute a {@link transaction}
+* @param token - A {@link TransactionToken}
+* @param id - A unique identifier for the transaction. If not provided, a random identifier will be generated
+* @returns A function that can be called to run the transaction with its {@link TransactionIO} parameters
+*/
 declare function runTransaction<F extends Func>(token: TransactionToken<F>, id?: string): (...parameters: Parameters<F>) => ReturnType<F>;
 //#endregion
 //#region src/main/selector.d.ts
 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>;
 };
 type ReadonlyPureSelectorOptions<T> = {
+  /** The unique identifier of the selector */
   key: string;
+  /** For each instantiated selector, a function that computes its value */
   get: Read<() => T>;
 };
 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>;
 };
 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>;
 };
 /**
@@ -222,7 +310,7 @@ 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}.
@@ -257,7 +345,7 @@ declare function selector<T extends object>(options: ReadonlyHeldSelectorOptions
 * 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}.
@@ -282,48 +370,80 @@ declare function selector<T>(options: WritablePureSelectorOptions<T>): WritableP
 * @overload ReadonlyPure
 */
 declare function selector<T>(options: ReadonlyPureSelectorOptions<T>): ReadonlyPureSelectorToken<T>;
+/** @public */
 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 */
 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 */
 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 */
 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>;
 };
 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;
 };
 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;
 };
 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;
 };
 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;
 };
 type PureSelectorFamilyToken<T, K extends Canonical> = ReadonlyPureSelectorFamilyToken<T, K> | WritablePureSelectorFamilyToken<T, K>;
@@ -331,25 +451,112 @@ type HeldSelectorFamilyToken<T, K extends Canonical> = ReadonlyHeldSelectorFamil
 type ReadonlySelectorFamilyToken<T, K extends Canonical> = ReadonlyHeldSelectorFamilyToken<T, K> | ReadonlyPureSelectorFamilyToken<T, K>;
 type WritableSelectorFamilyToken<T, K extends Canonical> = WritableHeldSelectorFamilyToken<T, K> | WritablePureSelectorFamilyToken<T, K>;
 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
+*/
 declare 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
+*/
 declare 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
+*/
 declare 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
+*/
 declare function selectorFamily<T, K extends Canonical>(options: ReadonlyPureSelectorFamilyOptions<T, K>): ReadonlyPureSelectorFamilyToken<T, K>;
 //#endregion
 //#region src/main/timeline.d.ts
+/** @public */
 type TimelineManageable = AtomFamilyToken<any, any> | AtomToken<any>;
+/** @public */
 type AtomOnly<M extends TimelineManageable> = M extends AtomFamilyToken<any, any> ? AtomToken<any> : M extends AtomToken<any> ? M : never;
+/** @public */
 type TimelineToken<M> = {
+  /** The unique identifier of the timeline */
   key: string;
+  /** Discriminator */
   type: `timeline`;
+  /** Never present. This is a marker that preserves the type of the managed atoms */
   __M?: M;
 };
+/** @public */
 type TimelineOptions<ManagedAtom extends TimelineManageable> = {
+  /** The unique identifier of the timeline */
   key: string;
+  /** The managed atoms (and families of atoms) to record */
   scope: ManagedAtom[];
+  /** A function that determines whether a given update should be recorded */
   shouldCapture?: (update: TimelineUpdate<ManagedAtom>, timeline: Timeline<TimelineManageable>) => boolean;
 };
+/** @public */
 type TimelineUpdate<ManagedAtom extends TimelineManageable> = TimelineAtomUpdate<ManagedAtom> | TimelineMoleculeCreation | TimelineMoleculeDisposal | TimelineSelectorUpdate<ManagedAtom> | TimelineStateCreation<AtomOnly<ManagedAtom>> | TimelineStateDisposal<AtomOnly<ManagedAtom>> | TimelineTransactionUpdate;
+/**
+* @public
+* Create a timeline, a mechanism for recording, undoing, and replaying changes to groups of atoms.
+* @param options - {@link TimelineOptions}
+* @returns A reference to the timeline created: a {@link TimelineToken}
+*/
 declare const timeline: <ManagedAtom extends TimelineManageable>(options: TimelineOptions<ManagedAtom>) => TimelineToken<ManagedAtom>;
 declare const redo: (tl: TimelineToken<any>) => void;
 declare const undo: (tl: TimelineToken<any>) => void;
@@ -357,14 +564,20 @@ declare const undo: (tl: TimelineToken<any>) => void;
 //#region src/main/dispose-state.d.ts
 /**
 * @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
 */
 declare 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
 */
@@ -373,7 +586,12 @@ declare function disposeState<K extends Canonical>(token: ReadableFamilyToken<an
 //#region src/main/find-state.d.ts
 /**
 * @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
@@ -383,7 +601,12 @@ declare function disposeState<K extends Canonical>(token: ReadableFamilyToken<an
 declare function findState<T extends Transceiver<any>, J extends Json.Serializable, K extends Canonical, Key extends K>(token: MutableAtomFamilyToken$1<T, J, K>, key: Key): MutableAtomToken$1<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
@@ -393,27 +616,42 @@ declare function findState<T extends Transceiver<any>, J extends Json.Serializab
 declare function findState<T, K extends Canonical, Key extends K>(token: RegularAtomFamilyToken$1<T, K>, key: Key): RegularAtomToken$1<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
 * The current value of the state
 * @overload Writable Selector
 */
-declare function findState<T, K extends Canonical, Key extends K>(token: WritablePureSelectorFamilyToken$1<T, K>, key: Key): WritablePureSelectorToken$1<T, K>;
+declare function findState<T, K extends Canonical, Key extends K>(token: WritableSelectorFamilyToken$1<T, K>, key: Key): WritableSelectorToken$1<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
 * The current value of the state
 * @overload Readonly Selector
 */
-declare function findState<T, K extends Canonical, Key extends K>(token: ReadonlyPureSelectorFamilyToken$1<T, K>, key: Key): ReadonlyPureSelectorToken$1<T, K>;
+declare function findState<T, K extends Canonical, Key extends K>(token: ReadonlySelectorFamilyToken$1<T, K>, key: Key): ReadonlySelectorToken$1<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
@@ -423,7 +661,12 @@ declare function findState<T, K extends Canonical, Key extends K>(token: Readonl
 declare function findState<T, K extends Canonical, Key extends K>(token: WritableFamilyToken$1<T, K>, key: Key): WritableToken$1<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
@@ -436,7 +679,7 @@ declare function findState<T, K extends Canonical, Key extends K>(token: Readabl
 //#region src/main/get-state.d.ts
 /**
 * @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
@@ -445,7 +688,7 @@ declare function findState<T, K extends Canonical, Key extends K>(token: Readabl
 declare 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
@@ -454,27 +697,77 @@ declare function getState<T>(token: ReadableToken<T>): T;
 declare function getState<T, K extends Canonical, Key extends K>(token: ReadableFamilyToken<T, K>, key: Key): T;
 //#endregion
 //#region src/main/join.d.ts
-interface 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>> {
+/** @public */
+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> = 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 */
 type JoinToken<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 = 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;
 };
-declare function join<const ASide extends string, const AType extends string, const BSide extends string, const BType extends string, const Cardinality extends `1:1` | `1:n` | `n:n`>(options: JoinOptions<ASide, AType, BSide, BType, Cardinality, null>, defaultContent?: undefined, store?: Store): JoinToken<ASide, AType, BSide, BType, Cardinality, null>;
-declare function join<const ASide extends string, const AType extends string, const BSide extends string, const BType extends string, const Cardinality extends `1:1` | `1:n` | `n:n`, const Content extends Json.Object>(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 - (undefined)
+* @returns
+* A reference to the join created: a {@link JoinToken}
+* @overload No Content
+*/
+declare function join<const ASide extends string, const AType extends string, const BSide extends string, const BType extends string, const Cardinality extends `1:1` | `1:n` | `n:n`>(options: JoinOptions<ASide, AType, BSide, BType, Cardinality, null>, defaultContent?: undefined): JoinToken<ASide, AType, BSide, BType, Cardinality, null>;
+declare function join<const ASide extends string, const AType extends string, const BSide extends string, const BType extends string, const Cardinality extends `1:1` | `1:n` | `n:n`, const Content extends Json.Object>(options: JoinOptions<ASide, AType, BSide, BType, Cardinality, Content>, defaultContent: Content): JoinToken<ASide, AType, BSide, BType, Cardinality, Content>;
+/** @public */
 type JoinStates<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> = Cardinality extends `1:1` ? (Content extends Json.Object ? { readonly [A in ASide as `${A}EntryOf${Capitalize<BSide>}`]: ReadonlyPureSelectorToken$1<[AType, Content] | null, BType> } & { readonly [B in BSide as `${B}EntryOf${Capitalize<ASide>}`]: ReadonlyPureSelectorToken$1<[BType, Content] | null, AType> } : {}) & { readonly [A in ASide as `${A}KeyOf${Capitalize<BSide>}`]: ReadonlyPureSelectorToken$1<AType | null, BType> } & { readonly [B in BSide as `${B}KeyOf${Capitalize<ASide>}`]: ReadonlyPureSelectorToken$1<BType | null, AType> } : Cardinality extends `1:n` ? (Content extends Json.Object ? { readonly [A in ASide as `${A}EntryOf${Capitalize<BSide>}`]: ReadonlyPureSelectorToken$1<[AType, Content] | null, BType> } & { readonly [B in BSide as `${B}EntriesOf${Capitalize<ASide>}`]: ReadonlyPureSelectorToken$1<[BType, Content][], AType> } : {}) & { readonly [A in ASide as `${A}KeyOf${Capitalize<BSide>}`]: ReadonlyPureSelectorToken$1<AType | null, BType> } & { readonly [B in BSide as `${B}KeysOf${Capitalize<ASide>}`]: ReadonlyPureSelectorToken$1<BType[], AType> } : Cardinality extends `n:n` ? (Content extends Json.Object ? { readonly [A in ASide as `${A}EntriesOf${Capitalize<BSide>}`]: ReadonlyPureSelectorToken$1<[AType, Content][], BType> } & { readonly [B in BSide as `${B}EntriesOf${Capitalize<ASide>}`]: ReadonlyPureSelectorToken$1<[BType, Content][], AType> } : {}) & { readonly [A in ASide as `${A}KeysOf${Capitalize<BSide>}`]: ReadonlyPureSelectorToken$1<AType[], BType> } & { readonly [B in BSide as `${B}KeysOf${Capitalize<ASide>}`]: ReadonlyPureSelectorToken$1<BType[], AType> } : 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
+*/
 declare function findRelations<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>(token: JoinToken<ASide, AType, BSide, BType, Cardinality, Content>, key: AType | BType): JoinStates<ASide, AType, BSide, BType, Cardinality, Content>;
+/**
+* @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
+*/
 declare function editRelations<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>(token: JoinToken<ASide, AType, BSide, BType, Cardinality, Content>, change: (relations: Junction<ASide, AType, BSide, BType, Content>) => void): void;
+/**
+* @public
+* @param token - The token of the join
+* @returns
+* A {@link MutableAtomFamilyToken} to access the internal relations
+*/
 declare function getInternalRelations<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>(token: JoinToken<ASide, AType, BSide, BType, Cardinality, Content>): MutableAtomFamilyToken$1<SetRTX<string>, SetRTXJson<string>, string>;
 //#endregion
 //#region src/main/logger.d.ts
@@ -555,18 +848,68 @@ type Claim<K extends Canonical> = K & {
 };
 declare class Realm<H extends Hierarchy> {
   store: Store;
+  /**
+  * @param store - The store to which the realm will be attached
+  */
   constructor(store?: 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}
+  */
   allocate<V extends Vassal<H>, A extends Above<V, H>>(provenance: A, key: V, attachmentStyle?: `all` | `any`): Claim<V>;
+  /**
+  * 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}
+  */
   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>>;
+  /**
+  * Remove a subject from the realm
+  * @param claim - The subject to be deallocated
+  */
   deallocate<V extends Vassal<H>>(claim: Claim<V>): void;
+  /**
+  * 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}
+  */
   claim<V extends Exclude<Vassal<H>, CompoundTypedKey>, A extends Above<V, H>>(newProvenance: A, claim: Claim<V>, exclusive?: `exclusive`): Claim<V>;
 }
 declare class Anarchy {
   store: Store;
   realm: Realm<any>;
+  /**
+  * @param store - The store to which the anarchy-realm will be attached
+  */
   constructor(store?: 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 .
+  */
   allocate(provenance: Canonical, key: Canonical, attachmentStyle?: `all` | `any`): void;
+  /**
+  * Remove an entity
+  * @param key - The entity to be deallocated
+  */
   deallocate(key: Canonical): void;
+  /**
+  * 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
+  */
   claim(newProvenance: Canonical, key: Canonical, exclusive?: `exclusive`): void;
 }
 declare const T$ = "T$";
@@ -649,19 +992,50 @@ declare class Silo {
 }
 //#endregion
 //#region src/main/subscribe.d.ts
+/** @public */
 type StateUpdate<T> = {
   newValue: T;
   oldValue: T;
 };
+/** @public */
 type KeyedStateUpdate<T> = Flat<StateUpdate<T> & {
   key: string;
   type: `atom_update` | `selector_update`;
   family?: FamilyMetadata;
 }>;
+/** @public */
 type UpdateHandler<T> = (update: StateUpdate<T>) => void;
+/** @public */
 type TransactionUpdateHandler<F extends Func> = (data: TransactionUpdate<F>) => void;
+/**
+* @public
+* Subscribe to a state in the implicit store
+* @param token - The token of the state to subscribe to
+* @param handleUpdate - A function that will be called when the state is updated
+* @param key - A unique key for the subscription. If not provided, a random key will be generated.
+* @returns A function that can be called to unsubscribe from the state
+* @overload State
+*/
 declare function subscribe<T>(token: ReadableToken<T>, handleUpdate: UpdateHandler<T>, key?: string): () => void;
+/**
+* @public
+* Subscribe to a transaction in the implicit store
+* @param token - The token of the transaction to subscribe to
+* @param handleUpdate - A function that will be called when the transaction succeeds
+* @param key - A unique key for the subscription. If not provided, a random key will be generated.
+* @returns A function that can be called to unsubscribe from the transaction
+* @overload Transaction
+*/
 declare function subscribe<F extends Func>(token: TransactionToken<F>, handleUpdate: TransactionUpdateHandler<F>, key?: string): () => void;
+/**
+* @public
+* Subscribe to a timeline in the implicit store
+* @param token - The token of the timeline to subscribe to
+* @param handleUpdate - A function that will be called when a new update is available
+* @param key - A unique key for the subscription. If not provided, a random key will be generated.
+* @returns A function that can be called to unsubscribe from the timeline
+* @overload Timeline
+*/
 declare function subscribe<M extends TimelineManageable>(token: TimelineToken<M>, handleUpdate: (update: TimelineUpdate<M> | `redo` | `undo`) => void, key?: string): () => void;
 //#endregion
 //#region src/main/validators.d.ts
@@ -803,6 +1177,14 @@ type FamilyMetadata<K extends Canonical = any> = {
   /** The family member's unique identifier, in the form of a string. */
   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.
+*/
 type Loadable<T> = Promise<T> | T;
 //#endregion
 export { $claim, Above, ActorToolkit, Anarchy, AtomDisposal, AtomEffect, AtomFamilyToken, AtomIOLogger, AtomIOToken, AtomOnly, AtomToken, Below, Claim, CompoundFrom, CompoundTypedKey, Effectors, FamilyMetadata, GetterToolkit, HeldSelectorFamilyToken, HeldSelectorToken, Hierarchy, JoinOptions, JoinStates, JoinToken, KeyedStateUpdate, LOG_LEVELS, Loadable, LogFilter, LogFn, LogLevel, Logger, LoggerIcon, MoleculeCreation, MoleculeDisposal, MoleculeTransfer, MutableAtomFamilyOptions, MutableAtomFamilyToken, MutableAtomOptions, MutableAtomToken, Mutuals, PureSelectorFamilyToken, PureSelectorToken, Read, ReadableFamilyToken, ReadableToken, ReadonlyHeldSelectorFamilyOptions, ReadonlyHeldSelectorFamilyToken, ReadonlyHeldSelectorOptions, ReadonlyHeldSelectorToken, ReadonlyPureSelectorFamilyOptions, ReadonlyPureSelectorFamilyToken, ReadonlyPureSelectorOptions, ReadonlyPureSelectorToken, ReadonlySelectorFamilyToken, ReadonlySelectorToken, Realm, RegularAtomFamilyOptions, RegularAtomFamilyToken, RegularAtomOptions, RegularAtomToken, SelectorDisposal, SelectorFamilyToken, SelectorToken, Setter, SetterToolkit, Silo, SingularTypedKey, StateCreation, StateDisposal, StateUpdate, T$, TimelineManageable, TimelineOptions, TimelineToken, TimelineUpdate, TokenDenomination, TokenType, Transact, TransactionIO, TransactionOptions, TransactionToken, TransactionUpdate, TransactionUpdateContent, TransactionUpdateHandler, TypeTag, TypedKey, UpdateHandler, Vassal, WritableFamilyToken, WritableHeldSelectorFamilyOptions, WritableHeldSelectorFamilyToken, WritableHeldSelectorOptions, WritableHeldSelectorToken, WritablePureSelectorFamilyOptions, WritablePureSelectorFamilyToken, WritablePureSelectorOptions, WritablePureSelectorToken, WritableSelectorFamilyToken, WritableSelectorToken, WritableToken, Write, atom, atomFamily, belongsTo, disposeState, editRelations, findRelations, findState, getInternalRelations, getState, isToken, join, redo, resetState, runTransaction, selector, selectorFamily, setState, simpleLog, simpleLogger, subscribe, timeline, transaction, undo };