atom.io 0.34.0 → 0.34.2

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>

package/src/main/subscribe.ts

@@ -11,7 +11,9 @@ import type {
 	TransactionUpdate,
 } from "."
 
+/** @public */
 export type StateUpdate<T> = { newValue: T; oldValue: T }
+/** @public */
 export type KeyedStateUpdate<T> = Flat<
 	StateUpdate<T> & {
 		key: string
@@ -19,22 +21,50 @@ export type KeyedStateUpdate<T> = Flat<
 		family?: FamilyMetadata
 	}
 >
+/** @public */
 export type UpdateHandler<T> = (update: StateUpdate<T>) => void
-
+/** @public */
 export 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
+ */
 export 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
+ */
 export 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
+ */
 export function subscribe<M extends TimelineManageable>(
 	token: TimelineToken<M>,
 	handleUpdate: (update: TimelineUpdate<M> | `redo` | `undo`) => void,

package/src/main/timeline.ts

@@ -12,7 +12,9 @@ import { createTimeline, IMPLICIT, timeTravel } from "atom.io/internal"
 
 import type { AtomFamilyToken, AtomToken } from "."
 
+/** @public */
 export type TimelineManageable = AtomFamilyToken<any, any> | AtomToken<any>
+/** @public */
 export type AtomOnly<M extends TimelineManageable> = M extends AtomFamilyToken<
 	any,
 	any
@@ -22,21 +24,34 @@ export type AtomOnly<M extends TimelineManageable> = M extends AtomFamilyToken<
 		? M
 		: never
 
+/** @public */
 export 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
 }
 
-export type TimelineOptions<ManagedAtom extends TimelineManageable> = {
-	key: string
-	scope: ManagedAtom[]
-	shouldCapture?: (
-		update: TimelineUpdate<ManagedAtom>,
-		timeline: Timeline<TimelineManageable>,
-	) => boolean
+/**
+ * @public
+ * If there is an update ahead of the cursor (in the future of this {@link timeline}), apply it and move the cursor to the next update
+ * @param timeline - A {@link TimelineToken}
+ */
+export const redo = (timeline: TimelineToken<any>): void => {
+	timeTravel(IMPLICIT.STORE, `redo`, timeline)
+}
+/**
+ * @public
+ * Reverse the last update on the {@link timeline} and move the cursor to the previous update
+ * @param timeline - A {@link TimelineToken}
+ */
+export const undo = (timeline: TimelineToken<any>): void => {
+	timeTravel(IMPLICIT.STORE, `undo`, timeline)
 }
 
+/** @public */
 export type TimelineUpdate<ManagedAtom extends TimelineManageable> =
 	| TimelineAtomUpdate<ManagedAtom>
 	| TimelineMoleculeCreation
@@ -46,16 +61,27 @@ export type TimelineUpdate<ManagedAtom extends TimelineManageable> =
 	| TimelineStateDisposal<AtomOnly<ManagedAtom>>
 	| TimelineTransactionUpdate
 
+/** @public */
+export 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
+ * 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}
+ */
 export const timeline = <ManagedAtom extends TimelineManageable>(
 	options: TimelineOptions<ManagedAtom>,
 ): TimelineToken<ManagedAtom> => {
 	return createTimeline(IMPLICIT.STORE, options)
 }
-
-export const redo = (tl: TimelineToken<any>): void => {
-	timeTravel(IMPLICIT.STORE, `redo`, tl)
-}
-
-export const undo = (tl: TimelineToken<any>): void => {
-	timeTravel(IMPLICIT.STORE, `undo`, tl)
-}

package/src/main/transaction.ts

@@ -18,37 +18,47 @@ import type {
 } from "."
 import type { resetState } from "./reset-state"
 
+/** @public */
 export 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 */
 export type StateCreation<Token extends ReadableToken<any>> = {
 	type: `state_creation`
 	token: Token
 }
+/** @public */
 export type AtomDisposal<Token extends ReadableToken<any>> = {
 	type: `state_disposal`
 	subType: `atom`
 	token: Token
 	value: TokenType<Token>
 }
+/** @public */
 export type SelectorDisposal<Token extends ReadableToken<any>> = {
 	type: `state_disposal`
 	subType: `selector`
 	token: Token
 }
+/** @public */
 export type StateDisposal<Token extends ReadableToken<any>> =
 	| AtomDisposal<Token>
 	| SelectorDisposal<Token>
 
+/** @public */
 export type MoleculeCreation = {
 	type: `molecule_creation`
 	key: Canonical
 	provenance: Canonical
 }
 
+/** @public */
 export type MoleculeDisposal = {
 	type: `molecule_disposal`
 	key: Canonical
@@ -56,6 +66,7 @@ export type MoleculeDisposal = {
 	values: [key: string, value: any][]
 }
 
+/** @public */
 export type MoleculeTransfer = {
 	type: `molecule_transfer`
 	key: Canonical
@@ -63,6 +74,7 @@ export type MoleculeTransfer = {
 	to: Canonical[]
 }
 
+/** @public */
 export type TransactionUpdateContent =
 	| KeyedStateUpdate<unknown>
 	| MoleculeCreation
@@ -72,6 +84,7 @@ export type TransactionUpdateContent =
 	| StateDisposal<ReadableToken<unknown>>
 	| TransactionUpdate<Func>
 
+/** @public */
 export type TransactionUpdate<F extends Func> = {
 	type: `transaction_update`
 	key: string
@@ -82,7 +95,9 @@ export type TransactionUpdate<F extends Func> = {
 	output: ReturnType<F>
 }
 
+/** @public */
 export type GetterToolkit = Pick<SetterToolkit, `find` | `get` | `json`>
+/** @public */
 export type SetterToolkit = Readonly<{
 	get: typeof getState
 	set: typeof setState
@@ -91,6 +106,7 @@ export type SetterToolkit = Readonly<{
 		state: MutableAtomToken<T, J>,
 	) => WritablePureSelectorToken<J>
 }>
+/** @public */
 export type ActorToolkit = Readonly<{
 	get: typeof getState
 	set: typeof setState
@@ -104,35 +120,55 @@ export type ActorToolkit = Readonly<{
 	env: () => EnvironmentData
 }>
 
+/** @public */
 export type Read<F extends Func> = (
 	toolkit: GetterToolkit,
 	...parameters: Parameters<F>
 ) => ReturnType<F>
 
+/** @public */
 export type Write<F extends Func> = (
 	toolkit: SetterToolkit,
 	...parameters: Parameters<F>
 ) => ReturnType<F>
 
+/** @public */
 export type Transact<F extends Func> = (
 	toolkit: ActorToolkit,
 	...parameters: Parameters<F>
 ) => ReturnType<F>
 
+/** @public */
+export type TransactionIO<Token extends TransactionToken<any>> =
+	Token extends TransactionToken<infer F> ? F : never
+
+/** @public */
 export type TransactionOptions<F extends Func> = {
+	/** The unique identifier of the transaction */
 	key: string
+	/** The operation to perform */
 	do: Transact<F>
 }
 
-export 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}
+ */
 export function transaction<F extends Func>(
 	options: TransactionOptions<F>,
 ): TransactionToken<F> {
 	return createTransaction(IMPLICIT.STORE, options)
 }
 
+/**
+ * @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
+ */
 export function runTransaction<F extends Func>(
 	token: TransactionToken<F>,
 	id: string = arbitrary(),