atom.io 0.33.21 → 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(),

package/src/realtime-client/realtime-client-stores/client-sync-store.ts

@@ -4,12 +4,12 @@ export const optimisticUpdateQueue: AtomIO.RegularAtomToken<
 	AtomIO.TransactionUpdate<any>[]
 > = AtomIO.atom<AtomIO.TransactionUpdate<any>[]>({
 	key: `updateQueue`,
-	default: [],
+	default: () => [],
 })
 
 export const confirmedUpdateQueue: AtomIO.RegularAtomToken<
 	AtomIO.TransactionUpdate<any>[]
 > = AtomIO.atom<AtomIO.TransactionUpdate<any>[]>({
 	key: `serverConfirmedUpdateQueue`,
-	default: [],
+	default: () => [],
 })

package/src/realtime-testing/setup-realtime-test.tsx

@@ -192,11 +192,6 @@ export const setupRealtimeTestClient = (
 			auth: { token: `test`, username: `${name}-${testNumber}` },
 		})
 		const silo = new AtomIO.Silo({ name, lifespan: `ephemeral` }, IMPLICIT.STORE)
-		for (const [key, value] of silo.store.valueMap.entries()) {
-			if (Array.isArray(value)) {
-				silo.store.valueMap.set(key, [...value])
-			}
-		}
 		silo.setState(RTC.myUsernameState, `${name}-${testNumber}`)
 
 		const { document } = new Happy.Window()