atom.io 0.34.0 → 0.34.1

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,30 @@ 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
 }
 
+/** @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 */
 export type TimelineUpdate<ManagedAtom extends TimelineManageable> =
 	| TimelineAtomUpdate<ManagedAtom>
 	| TimelineMoleculeCreation
@@ -46,6 +57,12 @@ export type TimelineUpdate<ManagedAtom extends TimelineManageable> =
 	| 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}
+ */
 export const timeline = <ManagedAtom extends TimelineManageable>(
 	options: TimelineOptions<ManagedAtom>,
 ): TimelineToken<ManagedAtom> => {

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(),