atom.io 0.36.2 → 0.37.0

package/src/internal/transaction/build-transaction.ts

@@ -4,6 +4,7 @@ import type {
 	getState,
 	resetState,
 	setState,
+	TransactionToken,
 } from "atom.io"
 
 import { arbitrary } from "../arbitrary"
@@ -23,7 +24,7 @@ import type { ChildStore, RootStore } from "./is-root-store"
 
 export const buildTransaction = (
 	store: Store,
-	key: string,
+	token: TransactionToken<any>,
 	params: any[],
 	id: string,
 ): ChildStore => {
@@ -65,15 +66,16 @@ export const buildTransaction = (
 		}),
 		miscResources: new LazyMap(parent.miscResources),
 	}
-	const epoch = getEpochNumberOfAction(store, key)
+	const epoch = getEpochNumberOfAction(store, token.key)
 	const transactionMeta: TransactionProgress<Fn> = {
 		phase: `building`,
 		update: {
-			type: `transaction_update`,
-			key,
+			type: `transaction_outcome`,
+			token,
 			id,
 			epoch: epoch === undefined ? Number.NaN : epoch + 1,
-			updates: [],
+			timestamp: Date.now(),
+			subEvents: [],
 			params,
 			output: undefined,
 		},
@@ -86,11 +88,10 @@ export const buildTransaction = (
 			reset: ((...ps: Parameters<typeof resetState>) => {
 				resetInStore(child, ...ps)
 			}) as typeof resetState,
-			run: (token, identifier = arbitrary()) =>
-				actUponStore(child, token, identifier),
+			run: (t, identifier = arbitrary()) => actUponStore(child, t, identifier),
 			find: ((...ps: Parameters<typeof findState>) =>
 				findInStore(store, ...ps)) as typeof findState,
-			json: (token) => getJsonToken(child, token),
+			json: (t) => getJsonToken(child, t),
 			dispose: ((...ps: Parameters<typeof disposeState>) => {
 				disposeFromStore(child, ...ps)
 			}) as typeof disposeState,
@@ -104,7 +105,7 @@ export const buildTransaction = (
 	store.logger.info(
 		`🛫`,
 		`transaction`,
-		key,
+		token.key,
 		`Building transaction with params:`,
 		params,
 	)

package/src/internal/transaction/create-transaction.ts

@@ -1,7 +1,7 @@
 import type {
 	TransactionOptions,
+	TransactionOutcomeEvent,
 	TransactionToken,
-	TransactionUpdate,
 } from "atom.io"
 
 import { newest } from "../lineage"
@@ -17,7 +17,7 @@ export type Transaction<F extends Fn> = {
 	key: string
 	type: `transaction`
 	install: (store: Store) => void
-	subject: Subject<TransactionUpdate<F>>
+	subject: Subject<TransactionOutcomeEvent<TransactionToken<F>>>
 	run: (parameters: Parameters<F>, id?: string) => ReturnType<F>
 }
 
@@ -31,7 +31,8 @@ export function createTransaction<F extends Fn>(
 		key,
 		type: `transaction`,
 		run: (params: Parameters<F>, id: string) => {
-			const childStore = buildTransaction(store, key, params, id)
+			const token = deposit(newTransaction)
+			const childStore = buildTransaction(store, token, params, id)
 			try {
 				const target = newest(store)
 				const { toolkit } = childStore.transactionMeta

package/src/internal/transaction/index.ts

@@ -1,4 +1,8 @@
-import type { ActorToolkit, TransactionUpdate } from "atom.io"
+import type {
+	ActorToolkit,
+	TransactionOutcomeEvent,
+	TransactionToken,
+} from "atom.io"
 
 import type { Junction } from "../junction"
 import type { Fn } from "../utility-types"
@@ -18,7 +22,7 @@ export type TransactionPhase = (typeof TRANSACTION_PHASES)[number]
 
 export type TransactionProgress<F extends Fn> = {
 	phase: `applying` | `building`
-	update: TransactionUpdate<F>
+	update: TransactionOutcomeEvent<TransactionToken<F>>
 	toolkit: ActorToolkit
 }
 

package/src/introspection/attach-introspection-states.ts

@@ -3,8 +3,8 @@ import type {
 	Loadable,
 	ReadonlyPureSelectorFamilyToken,
 	TimelineToken,
+	TransactionOutcomeEvent,
 	TransactionToken,
-	TransactionUpdate,
 } from "atom.io"
 import type { Fn, Store, Timeline } from "atom.io/internal"
 
@@ -22,7 +22,7 @@ export type IntrospectionStates = {
 	selectorIndex: AtomToken<SelectorTokenIndex>
 	transactionIndex: AtomToken<TransactionToken<Fn>[]>
 	transactionLogSelectors: ReadonlyPureSelectorFamilyToken<
-		TransactionUpdate<Fn>[],
+		TransactionOutcomeEvent<TransactionToken<Fn>>[],
 		string
 	>
 	timelineIndex: AtomToken<TimelineToken<any>[]>

package/src/introspection/attach-transaction-logs.ts

@@ -1,12 +1,19 @@
-import type { ReadonlyPureSelectorFamilyToken, TransactionUpdate } from "atom.io"
-import type { Fn, Store } from "atom.io/internal"
+import type {
+	ReadonlyPureSelectorFamilyToken,
+	TransactionOutcomeEvent,
+	TransactionToken,
+} from "atom.io"
+import type { Store } from "atom.io/internal"
 import { createRegularAtomFamily, createSelectorFamily } from "atom.io/internal"
 
 export const attachTransactionLogs = (
 	store: Store,
-): ReadonlyPureSelectorFamilyToken<TransactionUpdate<Fn>[], string> => {
+): ReadonlyPureSelectorFamilyToken<
+	TransactionOutcomeEvent<TransactionToken<any>>[],
+	string
+> => {
 	const transactionUpdateLogAtoms = createRegularAtomFamily<
-		TransactionUpdate<Fn>[],
+		TransactionOutcomeEvent<TransactionToken<any>>[],
 		string
 	>(store, {
 		key: `🔍 Transaction Update Log (Internal)`,
@@ -15,7 +22,7 @@ export const attachTransactionLogs = (
 			({ setSelf }) => {
 				const tx = store.transactions.get(key)
 				tx?.subject.subscribe(`introspection`, (transactionUpdate) => {
-					if (transactionUpdate.key === key) {
+					if (transactionUpdate.token.key === key) {
 						setSelf((state) => [...state, transactionUpdate])
 					}
 				})
@@ -23,7 +30,7 @@ export const attachTransactionLogs = (
 		],
 	})
 	const findTransactionUpdateLogState = createSelectorFamily<
-		TransactionUpdate<Fn>[],
+		TransactionOutcomeEvent<TransactionToken<any>>[],
 		string
 	>(store, {
 		key: `🔍 Transaction Update Log`,

package/src/json/index.ts

@@ -1,3 +1,5 @@
+import type { ViewOf } from "atom.io"
+
 export * from "./entries"
 
 export type primitive = boolean | number | string | null
@@ -80,7 +82,7 @@ export type Canonical = primitive | ReadonlyArray<Canonical>
 export type JsonIO = (...params: Json.Serializable[]) => Json.Serializable | void
 
 export type JsonInterface<T, J extends Json.Serializable = Json.Serializable> = {
-	toJson: (t: T) => J
+	toJson: (t: ViewOf<T>) => J
 	fromJson: (json: J) => T
 }
 

package/src/main/atom.ts

@@ -8,6 +8,7 @@ import {
 } from "atom.io/internal"
 import type { Canonical } from "atom.io/json"
 
+import type { StateUpdate } from "./events"
 import type { Setter } from "./set-state"
 import type {
 	MutableAtomFamilyToken,
@@ -75,7 +76,7 @@ export type Effectors<T> = {
 	 */
 	setSelf: <New extends T>(next: New | Setter<T, New>) => void
 	/** Subscribe to changes to the atom */
-	onSet: (callback: (options: { newValue: T; oldValue: T }) => void) => void
+	onSet: (callback: (options: StateUpdate<T>) => void) => void
 }
 
 export type RegularAtomFamilyOptions<T, K extends Canonical> = {

package/src/main/events.ts

@@ -0,0 +1,109 @@
+import type { ViewOf } from "atom.io"
+import type { Canonical, stringified } from "atom.io/json"
+
+import type { AtomOnly, TimelineManageable } from "./timeline"
+import type {
+	AtomToken,
+	ReadableToken,
+	SelectorToken,
+	TransactionToken,
+} from "./tokens"
+import type { TokenType } from "./validators"
+
+export type StateUpdate<T> = {
+	readonly oldValue: ViewOf<T>
+	readonly newValue: ViewOf<T>
+}
+
+export type AtomUpdateEvent<A extends AtomToken<any>> = {
+	type: `atom_update`
+	token: A
+	update: StateUpdate<TokenType<A>>
+	timestamp: number
+}
+
+export type TimelineSelectorUpdateEvent<A extends TimelineManageable> = {
+	type: `selector_update`
+	token: SelectorToken<any>
+	atomUpdates: AtomUpdateEvent<AtomOnly<A>>[]
+	timestamp: number
+}
+
+export type StateLifecycleEvent<R extends ReadableToken<any>> =
+	| StateCreationEvent<R>
+	| StateDisposalEvent<R>
+export type StateCreationEvent<R extends ReadableToken<any>> = {
+	type: `state_creation`
+	token: R
+	timestamp: number
+}
+export type StateDisposalEvent<R extends ReadableToken<any>> =
+	| AtomDisposalEvent<R>
+	| SelectorDisposalEvent<R>
+
+export type AtomDisposalEvent<R extends ReadableToken<any>> = {
+	type: `state_disposal`
+	subType: `atom`
+	token: R
+	value: TokenType<R>
+	timestamp: number
+}
+export type SelectorDisposalEvent<R extends ReadableToken<any>> = {
+	type: `state_disposal`
+	subType: `selector`
+	token: R
+	timestamp: number
+}
+
+export type MoleculeCreationEvent = {
+	type: `molecule_creation`
+	key: Canonical
+	provenance: Canonical
+	timestamp: number
+}
+
+export type MoleculeDisposalEvent = {
+	type: `molecule_disposal`
+	key: Canonical
+	provenance: stringified<Canonical>[]
+	values: [key: string, value: any][]
+	timestamp: number
+}
+
+export type MoleculeTransferEvent = {
+	type: `molecule_transfer`
+	key: Canonical
+	exclusive: boolean
+	from: Canonical[]
+	to: Canonical[]
+	timestamp: number
+}
+
+export type TransactionSubEvent =
+	| AtomUpdateEvent<AtomToken<any>>
+	| MoleculeCreationEvent
+	| MoleculeDisposalEvent
+	| MoleculeTransferEvent
+	| StateCreationEvent<ReadableToken<unknown>>
+	| StateDisposalEvent<ReadableToken<unknown>>
+	| TransactionOutcomeEvent<TransactionToken<any>>
+
+export type TransactionOutcomeEvent<T extends TransactionToken<any>> = {
+	type: `transaction_outcome`
+	token: T
+	id: string
+	epoch: number
+	timestamp: number
+	subEvents: TransactionSubEvent[]
+	params: Parameters<TokenType<T>>
+	output: ReturnType<TokenType<T>>
+}
+
+export type TimelineEvent<ManagedAtom extends TimelineManageable> =
+	| AtomUpdateEvent<AtomOnly<ManagedAtom>>
+	| MoleculeCreationEvent
+	| MoleculeDisposalEvent
+	| StateCreationEvent<AtomOnly<ManagedAtom>>
+	| StateDisposalEvent<AtomOnly<ManagedAtom>>
+	| TimelineSelectorUpdateEvent<ManagedAtom>
+	| TransactionOutcomeEvent<TransactionToken<any>>

package/src/main/get-state.ts

@@ -1,4 +1,4 @@
-import type { ViewOf } from "atom.io/internal"
+import type { ViewOf } from "atom.io"
 import { getFromStore, IMPLICIT } from "atom.io/internal"
 import type { Canonical } from "atom.io/json"
 

package/src/main/index.ts

@@ -1,5 +1,6 @@
 export * from "./atom"
 export * from "./dispose-state"
+export type * from "./events"
 export * from "./find-state"
 export * from "./get-state"
 export * from "./join"
@@ -23,3 +24,5 @@ export * from "./validators"
  * 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
+
+export type ViewOf<T> = T extends { READONLY_VIEW: infer View } ? View : T

package/src/main/subscribe.ts

@@ -1,27 +1,17 @@
-import type { Flat, Fn } from "atom.io/internal"
+import type { Fn } from "atom.io/internal"
 import { arbitrary, IMPLICIT, subscribeInStore } from "atom.io/internal"
 
 import type {
-	FamilyMetadata,
-	ReadableToken,
-	TimelineManageable,
-	TimelineToken,
-	TimelineUpdate,
-	TransactionToken,
-	TransactionUpdate,
-} from "."
+	StateUpdate,
+	TimelineEvent,
+	TransactionOutcomeEvent,
+} from "./events"
+import type { TimelineManageable } from "./timeline"
+import type { ReadableToken, TimelineToken, TransactionToken } from "./tokens"
 
-export type StateUpdate<T> = { newValue: T; oldValue: T }
-export type KeyedStateUpdate<T> = Flat<
-	StateUpdate<T> & {
-		key: string
-		type: `atom_update` | `selector_update`
-		family?: FamilyMetadata
-	}
->
 export type UpdateHandler<T> = (update: StateUpdate<T>) => void
 export type TransactionUpdateHandler<F extends Fn> = (
-	data: TransactionUpdate<F>,
+	data: TransactionOutcomeEvent<TransactionToken<F>>,
 ) => void
 
 /**
@@ -60,7 +50,7 @@ export function subscribe<F extends Fn>(
  */
 export function subscribe<M extends TimelineManageable>(
 	token: TimelineToken<M>,
-	handleUpdate: (update: TimelineUpdate<M> | `redo` | `undo`) => void,
+	handleUpdate: (update: TimelineEvent<M> | `redo` | `undo`) => void,
 	key?: string,
 ): () => void
 export function subscribe(

package/src/main/timeline.ts

@@ -1,16 +1,7 @@
-import type {
-	Timeline,
-	TimelineAtomUpdate,
-	TimelineMoleculeCreation,
-	TimelineMoleculeDisposal,
-	TimelineSelectorUpdate,
-	TimelineStateCreation,
-	TimelineStateDisposal,
-	TimelineTransactionUpdate,
-} from "atom.io/internal"
+import type { Timeline } from "atom.io/internal"
 import { createTimeline, IMPLICIT, timeTravel } from "atom.io/internal"
 
-import type { AtomFamilyToken, AtomToken, TimelineToken } from "."
+import type { AtomFamilyToken, AtomToken, TimelineEvent, TimelineToken } from "."
 
 export type TimelineManageable = AtomFamilyToken<any, any> | AtomToken<any>
 export type AtomOnly<M extends TimelineManageable> = M extends AtomFamilyToken<
@@ -37,15 +28,6 @@ export const undo = (timeline: TimelineToken<any>): void => {
 	timeTravel(IMPLICIT.STORE, `undo`, timeline)
 }
 
-export type TimelineUpdate<ManagedAtom extends TimelineManageable> =
-	| TimelineAtomUpdate<ManagedAtom>
-	| TimelineMoleculeCreation
-	| TimelineMoleculeDisposal
-	| TimelineSelectorUpdate<ManagedAtom>
-	| TimelineStateCreation<AtomOnly<ManagedAtom>>
-	| TimelineStateDisposal<AtomOnly<ManagedAtom>>
-	| TimelineTransactionUpdate
-
 export type TimelineOptions<ManagedAtom extends TimelineManageable> = {
 	/** The unique identifier of the timeline */
 	key: string
@@ -53,7 +35,7 @@ export type TimelineOptions<ManagedAtom extends TimelineManageable> = {
 	scope: ManagedAtom[]
 	/** A function that determines whether a given update should be recorded */
 	shouldCapture?: (
-		update: TimelineUpdate<ManagedAtom>,
+		update: TimelineEvent<ManagedAtom>,
 		timeline: Timeline<TimelineManageable>,
 	) => boolean
 }

package/src/main/transaction.ts

@@ -5,82 +5,17 @@ import {
 	createTransaction,
 	IMPLICIT,
 } from "atom.io/internal"
-import type { Canonical, stringified } from "atom.io/json"
 
 import type { disposeState } from "./dispose-state"
 import type { findState } from "./find-state"
 import type { getState } from "./get-state"
 import type { resetState } from "./reset-state"
 import type { setState } from "./set-state"
-import type { KeyedStateUpdate } from "./subscribe"
 import type {
 	MutableAtomToken,
-	ReadableToken,
 	TransactionToken,
 	WritablePureSelectorToken,
 } from "./tokens"
-import type { TokenType } from "./validators"
-
-export type StateCreation<Token extends ReadableToken<any>> = {
-	type: `state_creation`
-	token: Token
-}
-export type StateDisposal<Token extends ReadableToken<any>> =
-	| AtomDisposal<Token>
-	| SelectorDisposal<Token>
-export type StateLifecycleEvent<Token extends ReadableToken<any>> =
-	| StateCreation<Token>
-	| StateDisposal<Token>
-
-export type AtomDisposal<Token extends ReadableToken<any>> = {
-	type: `state_disposal`
-	subType: `atom`
-	token: Token
-	value: TokenType<Token>
-}
-export type SelectorDisposal<Token extends ReadableToken<any>> = {
-	type: `state_disposal`
-	subType: `selector`
-	token: Token
-}
-
-export type MoleculeCreation = {
-	type: `molecule_creation`
-	key: Canonical
-	provenance: Canonical
-}
-export type MoleculeDisposal = {
-	type: `molecule_disposal`
-	key: Canonical
-	provenance: stringified<Canonical>[]
-	values: [key: string, value: any][]
-}
-export type MoleculeTransfer = {
-	type: `molecule_transfer`
-	key: Canonical
-	exclusive: boolean
-	from: Canonical[]
-	to: Canonical[]
-}
-
-export type TransactionUpdateContent =
-	| KeyedStateUpdate<unknown>
-	| MoleculeCreation
-	| MoleculeDisposal
-	| MoleculeTransfer
-	| StateCreation<ReadableToken<unknown>>
-	| StateDisposal<ReadableToken<unknown>>
-	| TransactionUpdate<Fn>
-
-export type TransactionUpdate<F extends Fn> = {
-	type: `transaction_update`
-	key: string
-	id: string
-	epoch: number
-	updates: TransactionUpdateContent[]
-	params: Parameters<F>
-	output: ReturnType<F>
-}
 
 export type ReaderToolkit = Pick<ActorToolkit, `find` | `get` | `json`>
 export type WriterToolkit = Pick<ActorToolkit, `find` | `get` | `json` | `set`>

package/src/main/validators.ts

@@ -7,6 +7,7 @@ import type {
 	ReadonlyPureSelectorToken,
 	RegularAtomFamilyToken,
 	RegularAtomToken,
+	TransactionToken,
 	WritableFamilyToken,
 	WritablePureSelectorFamilyToken,
 	WritablePureSelectorToken,
@@ -14,12 +15,17 @@ import type {
 } from "./tokens"
 
 export type TokenType<
-	Comparison extends ReadableFamilyToken<any, any> | ReadableToken<any>,
+	Comparison extends
+		| ReadableFamilyToken<any, any>
+		| ReadableToken<any>
+		| TransactionToken<any>,
 > = Comparison extends ReadableToken<infer RepresentedValue>
 	? RepresentedValue
 	: Comparison extends ReadableFamilyToken<infer RepresentedValue, any>
 		? RepresentedValue
-		: never
+		: Comparison extends TransactionToken<infer Fn>
+			? Fn
+			: never
 
 export function isToken<KnownToken extends RegularAtomToken<any>>(
 	knownToken: KnownToken,

package/src/react-devtools/TimelineIndex.tsx

@@ -68,7 +68,7 @@ export const TimelineLog: FC<{
 						update.type !== `molecule_disposal` &&
 						update.type !== `state_creation` &&
 						update.type !== `state_disposal` ? (
-							<Fragment key={update.key + index + timeline.at}>
+							<Fragment key={update.token.key + index + timeline.at}>
 								{index === timeline.at ? <YouAreHere /> : null}
 								<article.TimelineUpdate
 									timelineUpdate={update}

package/src/react-devtools/TransactionIndex.tsx

@@ -1,8 +1,8 @@
 import type {
 	ReadonlyPureSelectorToken,
 	RegularAtomToken,
+	TransactionOutcomeEvent,
 	TransactionToken,
-	TransactionUpdate,
 } from "atom.io"
 import { findInStore, type Fn } from "atom.io/internal"
 import { useI, useO } from "atom.io/react"
@@ -15,7 +15,9 @@ import { article } from "./Updates"
 export const TransactionLog: FC<{
 	token: TransactionToken<Fn>
 	isOpenState: RegularAtomToken<boolean>
-	logState: ReadonlyPureSelectorToken<TransactionUpdate<Fn>[]>
+	logState: ReadonlyPureSelectorToken<
+		TransactionOutcomeEvent<TransactionToken<Fn>>[]
+	>
 }> = ({ token, isOpenState, logState }) => {
 	const log = useO(logState)
 	const isOpen = useO(isOpenState)
@@ -41,7 +43,7 @@ export const TransactionLog: FC<{
 				<main>
 					{log.map((update, index) => (
 						<article.TransactionUpdate
-							key={update.key + index}
+							key={update.token.key + index}
 							serialNumber={index}
 							transactionUpdate={update}
 						/>