atom.io 0.6.9 → 0.7.0

package/internal/src/families/create-selector-family.ts

@@ -0,0 +1,67 @@
+import type {
+	FamilyMetadata,
+	ReadonlySelectorFamily,
+	ReadonlySelectorFamilyOptions,
+	SelectorFamily,
+	SelectorFamilyOptions,
+	SelectorToken,
+} from "atom.io"
+import type { Json } from "atom.io/json"
+import { stringifyJson } from "atom.io/json"
+
+import { createSelector } from "../selector"
+import type { Store } from "../store"
+import { IMPLICIT, deposit } from "../store"
+import { Subject } from "../subject"
+import { target } from "../transaction"
+import { createReadonlySelectorFamily } from "./create-readonly-selector-family"
+
+export function createSelectorFamily<T, K extends Json.Serializable>(
+	options: SelectorFamilyOptions<T, K>,
+	store?: Store,
+): SelectorFamily<T, K>
+export function createSelectorFamily<T, K extends Json.Serializable>(
+	options: ReadonlySelectorFamilyOptions<T, K>,
+	store?: Store,
+): ReadonlySelectorFamily<T, K>
+export function createSelectorFamily<T, K extends Json.Serializable>(
+	options: ReadonlySelectorFamilyOptions<T, K> | SelectorFamilyOptions<T, K>,
+	store: Store = IMPLICIT.STORE,
+): ReadonlySelectorFamily<T, K> | SelectorFamily<T, K> {
+	const isReadonly = !(`set` in options)
+
+	if (isReadonly) {
+		return createReadonlySelectorFamily(options, store)
+	}
+	const core = target(store)
+	const subject = new Subject<SelectorToken<T>>()
+
+	const selectorFamily = Object.assign(
+		(key: K): SelectorToken<T> => {
+			const subKey = stringifyJson(key)
+			const family: FamilyMetadata = { key: options.key, subKey }
+			const fullKey = `${options.key}(${subKey})`
+			const existing = core.selectors.get(fullKey)
+			if (existing) {
+				return deposit(existing)
+			}
+			const token = createSelector<T>(
+				{
+					key: fullKey,
+					get: options.get(key),
+					set: options.set(key),
+				},
+				family,
+				store,
+			)
+			subject.next(token)
+			return token
+		},
+		{
+			key: options.key,
+			type: `selector_family`,
+		} as const,
+	) as SelectorFamily<T, K>
+	core.families.set(options.key, selectorFamily)
+	return selectorFamily
+}

package/internal/src/families/index.ts

@@ -0,0 +1,3 @@
+export * from "./create-atom-family"
+export * from "./create-readonly-selector-family"
+export * from "./create-selector-family"

package/internal/src/get-state-internal.ts

@@ -0,0 +1,23 @@
+import type { Atom } from "./atom"
+import { isValueCached, readCachedValue } from "./caching"
+import type { ReadonlySelector, Selector } from "./selector"
+import type { Store } from "./store"
+import { IMPLICIT } from "./store"
+
+export const getState__INTERNAL = <T>(
+	state: Atom<T> | ReadonlySelector<T> | Selector<T>,
+	store: Store = IMPLICIT.STORE,
+): T => {
+	if (isValueCached(state.key, store)) {
+		store.config.logger?.info(`>> read "${state.key}"`)
+		return readCachedValue(state.key, store)
+	}
+	if (state.type !== `atom`) {
+		store.config.logger?.info(`-> calc "${state.key}"`)
+		return state.get()
+	}
+	store.config.logger?.error(
+		`Attempted to get atom "${state.key}", which was never initialized in store "${store.config.name}".`,
+	)
+	return state.default
+}

package/internal/src/index.ts

@@ -0,0 +1,13 @@
+export * from "./atom"
+export * from "./caching"
+export * from "./families"
+export * from "./get-state-internal"
+export * from "./operation"
+export * from "./mutable"
+export * from "./selector"
+export * from "./set-state"
+export * from "./store"
+export * from "./subject"
+export * from "./subscribe"
+export * from "./timeline"
+export * from "./transaction"

package/internal/src/mutable/create-mutable-atom-family.ts

@@ -0,0 +1,25 @@
+import type * as AtomIO from "atom.io"
+import type { Json } from "atom.io/json"
+import { selectJsonFamily } from "atom.io/json"
+
+import type { Store } from ".."
+import { IMPLICIT, createAtomFamily } from ".."
+import { FamilyTracker } from "./tracker-family"
+import type { Transceiver } from "./transceiver"
+
+export function createMutableAtomFamily<
+	Core extends Transceiver<any>,
+	SerializableCore extends Json.Serializable,
+	Key extends string,
+>(
+	options: AtomIO.MutableAtomFamilyOptions<Core, SerializableCore, Key>,
+	store: Store = IMPLICIT.STORE,
+): AtomIO.MutableAtomFamily<Core, SerializableCore, Key> {
+	const coreFamily = Object.assign(
+		createAtomFamily<Core, Key>(options, store),
+		options,
+	) as AtomIO.MutableAtomFamily<Core, SerializableCore, Key>
+	selectJsonFamily(coreFamily, options)
+	new FamilyTracker(coreFamily, store)
+	return coreFamily
+}

package/internal/src/mutable/create-mutable-atom.ts

@@ -0,0 +1,49 @@
+import * as AtomIO from "atom.io"
+import type { Json } from "atom.io/json"
+import { selectJson } from "atom.io/json"
+
+import { createAtom } from "../atom"
+import type { Store } from "../store"
+import { IMPLICIT } from "../store"
+import { target } from "../transaction"
+import { Tracker } from "./tracker"
+import type { Transceiver } from "./transceiver"
+
+export function createMutableAtom<
+	Core extends Transceiver<any>,
+	SerializableCore extends Json.Serializable,
+>(
+	options: AtomIO.MutableAtomOptions<Core, SerializableCore>,
+	store: Store = IMPLICIT.STORE,
+): AtomIO.MutableAtomToken<Core, SerializableCore> {
+	store.config.logger?.info(
+		`🔧 creating mutable atom "${options.key}" in store "${store.config.name}"`,
+	)
+	const coreState = createAtom<Core>(options, undefined, store)
+	new Tracker(coreState, store)
+	const jsonState = selectJson(coreState, options, store)
+	AtomIO.subscribe(
+		jsonState,
+		() => {
+			store.config.logger?.info(
+				`🔍 tracker-initializer:${store?.config.name}:${
+					store.transactionStatus.phase === `idle`
+						? `main`
+						: store.transactionStatus.key
+				}`,
+				`Initializing tracker for ${coreState.key}`,
+			)
+
+			const trackerHasBeenInitialized = target(store).trackers.has(coreState.key)
+			if (!trackerHasBeenInitialized) {
+				new Tracker(coreState, store)
+			}
+		},
+		`tracker-initializer:${store?.config.name}:${
+			store.transactionStatus.phase === `idle`
+				? `main`
+				: store.transactionStatus.key
+		}`,
+	)
+	return coreState as AtomIO.MutableAtomToken<Core, SerializableCore>
+}

package/internal/src/mutable/get-json-token.ts

@@ -0,0 +1,22 @@
+import type { MutableAtomToken, SelectorToken } from "atom.io"
+import type { Json } from "atom.io/json"
+import type { Transceiver } from "./transceiver"
+
+export const getJsonToken = <
+	Core extends Transceiver<Json.Serializable>,
+	SerializableCore extends Json.Serializable,
+>(
+	mutableAtomToken: MutableAtomToken<Core, SerializableCore>,
+): SelectorToken<SerializableCore> => {
+	const key = mutableAtomToken.family
+		? `${mutableAtomToken.family.key}:JSON(${mutableAtomToken.family.subKey})`
+		: `${mutableAtomToken.key}:JSON`
+	const jsonToken: SelectorToken<SerializableCore> = { type: `selector`, key }
+	if (mutableAtomToken.family) {
+		jsonToken.family = {
+			key: `${mutableAtomToken.family.key}:JSON`,
+			subKey: mutableAtomToken.family.subKey,
+		}
+	}
+	return jsonToken
+}

package/internal/src/mutable/get-update-token.ts

@@ -0,0 +1,20 @@
+import type { AtomToken, MutableAtomToken } from "atom.io"
+import type { Json } from "atom.io/json"
+import type { Signal, Transceiver } from "./transceiver"
+
+export const getUpdateToken = <
+	Core extends Transceiver<Json.Serializable>,
+	SerializableCore extends Json.Serializable,
+>(
+	mutableAtomToken: MutableAtomToken<Core, SerializableCore>,
+): AtomToken<Signal<Core>> => {
+	const key = `*${mutableAtomToken.key}`
+	const updateToken: AtomToken<Signal<Core>> = { type: `atom`, key }
+	if (mutableAtomToken.family) {
+		updateToken.family = {
+			key: `*${mutableAtomToken.family.key}`,
+			subKey: mutableAtomToken.family.subKey,
+		}
+	}
+	return updateToken
+}

package/internal/src/mutable/index.ts

@@ -0,0 +1,17 @@
+import type { Atom } from "../atom"
+
+export * from "./create-mutable-atom"
+export * from "./create-mutable-atom-family"
+export * from "./get-json-token"
+export * from "./get-update-token"
+export * from "./is-atom-token-mutable"
+export * from "./tracker"
+export * from "./tracker-family"
+export * from "./transceiver"
+
+export interface MutableAtom<T> extends Atom<T> {
+	mutable: true
+}
+
+export const isAtomMutable = <T>(atom: Atom<T>): atom is MutableAtom<T> =>
+	`isMutable` in atom

package/internal/src/mutable/is-atom-token-mutable.ts

@@ -0,0 +1,7 @@
+import type * as AtomIO from "atom.io"
+
+export function isAtomTokenMutable(
+	token: AtomIO.AtomToken<any>,
+): token is AtomIO.MutableAtomToken<any, any> {
+	return token.key.endsWith(`::mutable`)
+}

package/internal/src/mutable/tracker-family.ts

@@ -0,0 +1,61 @@
+import type * as AtomIO from "atom.io"
+import type { Json } from "atom.io/json"
+import { parseJson } from "atom.io/json"
+
+import { createAtomFamily } from "../families"
+import type { Store } from "../store"
+import { IMPLICIT } from "../store"
+import { Tracker } from "./tracker"
+import type { Transceiver } from "./transceiver"
+
+export class FamilyTracker<
+	Core extends Transceiver<any>,
+	FamilyMemberKey extends Json.Serializable,
+> {
+	private readonly Update: Core extends Transceiver<infer Signal>
+		? Signal
+		: never
+
+	public readonly findLatestUpdateState: AtomIO.AtomFamily<
+		typeof this.Update | null,
+		FamilyMemberKey
+	>
+	public readonly findMutableState: AtomIO.AtomFamily<Core, FamilyMemberKey>
+
+	public constructor(
+		findMutableState: AtomIO.AtomFamily<Core, FamilyMemberKey>,
+		store: Store = IMPLICIT.STORE,
+	) {
+		this.findLatestUpdateState = createAtomFamily<
+			typeof this.Update | null,
+			FamilyMemberKey
+		>(
+			{
+				key: `*${findMutableState.key}`,
+				default: null,
+			},
+			store,
+		)
+		this.findMutableState = findMutableState
+		this.findMutableState.subject.subscribe(
+			`store=${store.config.name}::tracker-atom-family`,
+			(atomToken) => {
+				if (atomToken.family) {
+					const key = parseJson(atomToken.family.subKey) as FamilyMemberKey
+					this.findLatestUpdateState(key)
+					new Tracker<Core>(atomToken, store)
+				}
+			},
+		)
+		this.findLatestUpdateState.subject.subscribe(
+			`store=${store.config.name}::tracker-atom-family`,
+			(atomToken) => {
+				if (atomToken.family) {
+					const key = parseJson(atomToken.family.subKey) as FamilyMemberKey
+					const mutableAtomToken = this.findMutableState(key)
+					new Tracker<Core>(mutableAtomToken, store)
+				}
+			},
+		)
+	}
+}

package/internal/src/mutable/tracker.ts

@@ -0,0 +1,164 @@
+import * as AtomIO from "atom.io"
+import type { Json } from "atom.io/json"
+
+import type { Store } from ".."
+import { IMPLICIT } from ".."
+import { createAtom, deleteAtom } from "../atom"
+import { target } from "../transaction"
+import type { Transceiver } from "./transceiver"
+
+/**
+ * @internal Give the tracker a transceiver state and a store, and it will
+ * subscribe to the transceiver's inner value. When the inner value changes,
+ * the tracker will update its own state to reflect the change.
+ */
+export class Tracker<Mutable extends Transceiver<any>> {
+	private Update: Mutable extends Transceiver<infer Signal> ? Signal : never
+
+	private initializeState(
+		mutableState: AtomIO.MutableAtomToken<Mutable, Json.Serializable>,
+		store: Store = IMPLICIT.STORE,
+	): AtomIO.AtomToken<typeof this.Update | null> {
+		const latestUpdateStateKey = `*${mutableState.key}`
+		deleteAtom(latestUpdateStateKey, target(store))
+		const familyMetaData: AtomIO.FamilyMetadata | undefined = mutableState.family
+			? {
+					key: `*${mutableState.family.key}`,
+					subKey: mutableState.family.subKey,
+			  }
+			: undefined
+		const latestUpdateState = createAtom<
+			(Mutable extends Transceiver<infer Signal> ? Signal : never) | null
+		>(
+			{
+				key: latestUpdateStateKey,
+				default: null,
+			},
+			familyMetaData,
+			store,
+		)
+
+		return latestUpdateState
+	}
+
+	private unsubscribeFromInnerValue: (() => void) | null = null
+	private observeCore(
+		mutableState: AtomIO.MutableAtomToken<Mutable, Json.Serializable>,
+		latestUpdateState: AtomIO.AtomToken<typeof this.Update | null>,
+		store: Store = IMPLICIT.STORE,
+	): void {
+		const originalInnerValue = AtomIO.getState(mutableState, store)
+		this.unsubscribeFromInnerValue = originalInnerValue.subscribe(
+			`tracker:${store.config.name}:${
+				store.transactionStatus.phase === `idle`
+					? `main`
+					: store.transactionStatus.key
+			}`,
+			(update) => {
+				const unsubscribe = store.subject.operationStatus.subscribe(
+					mutableState.key,
+					() => {
+						unsubscribe()
+						AtomIO.setState(latestUpdateState, update, store)
+					},
+				)
+			},
+		)
+		AtomIO.subscribe(
+			mutableState,
+			(update) => {
+				if (update.newValue !== update.oldValue) {
+					this.unsubscribeFromInnerValue?.()
+					this.unsubscribeFromInnerValue = update.newValue.subscribe(
+						`tracker:${store.config.name}:${
+							store.transactionStatus.phase === `idle`
+								? `main`
+								: store.transactionStatus.key
+						}`,
+						(update) => {
+							const unsubscribe = store.subject.operationStatus.subscribe(
+								mutableState.key,
+								() => {
+									unsubscribe()
+									AtomIO.setState(latestUpdateState, update, store)
+								},
+							)
+						},
+					)
+				}
+			},
+			`${store.config.name}: tracker observing inner value`,
+			store,
+		)
+	}
+
+	private updateCore<Core extends Transceiver<any>>(
+		mutableState: AtomIO.MutableAtomToken<Core, Json.Serializable>,
+		latestUpdateState: AtomIO.AtomToken<typeof this.Update | null>,
+		store: Store = IMPLICIT.STORE,
+	): void {
+		AtomIO.subscribe(
+			latestUpdateState,
+			({ newValue, oldValue }) => {
+				const timelineId = store.timelineAtoms.getRelatedKey(
+					latestUpdateState.key,
+				)
+				if (timelineId) {
+					const timelineData = store.timelines.get(timelineId)
+					if (timelineData?.timeTraveling) {
+						const unsubscribe = AtomIO.subscribeToTimeline(
+							{ key: timelineId, type: `timeline` },
+							(update) => {
+								unsubscribe()
+								AtomIO.setState(
+									mutableState,
+									(transceiver) => {
+										if (update === `redo` && newValue) {
+											transceiver.do(newValue)
+										} else if (update === `undo` && oldValue) {
+											transceiver.undo(oldValue)
+										}
+										return transceiver
+									},
+									store,
+								)
+							},
+						)
+						return
+					}
+				}
+
+				const unsubscribe = store.subject.operationStatus.subscribe(
+					latestUpdateState.key,
+					() => {
+						unsubscribe()
+						if (newValue) {
+							AtomIO.setState(
+								mutableState,
+								(transceiver) => (transceiver.do(newValue), transceiver),
+								store,
+							)
+						}
+					},
+				)
+			},
+			`${store.config.name}: tracker observing latest update`,
+			store,
+		)
+	}
+
+	public mutableState: AtomIO.MutableAtomToken<Mutable, Json.Serializable>
+	public latestUpdateState: AtomIO.AtomToken<typeof this.Update | null>
+
+	public constructor(
+		mutableState: AtomIO.MutableAtomToken<Mutable, Json.Serializable>,
+		store: Store = IMPLICIT.STORE,
+	) {
+		this.mutableState = mutableState
+		this.latestUpdateState = this.initializeState(mutableState, store)
+		this.observeCore(mutableState, this.latestUpdateState, store)
+		this.updateCore(mutableState, this.latestUpdateState, store)
+		const core = target(store)
+		core.trackers.set(mutableState.key, this)
+	}
+}

package/internal/src/mutable/transceiver.ts

@@ -0,0 +1,110 @@
+import type { Json } from "atom.io/json"
+
+export interface Transceiver<Signal extends Json.Serializable> {
+	do: (update: Signal) => void
+	undo: (update: Signal) => void
+	subscribe: (key: string, fn: (update: Signal) => void) => () => void
+}
+
+export function isTransceiver(
+	value: unknown,
+): value is Transceiver<Json.Serializable> {
+	return (
+		typeof value === `object` &&
+		value !== null &&
+		`do` in value &&
+		`undo` in value &&
+		`subscribe` in value
+	)
+}
+
+export type TransceiverMode = `playback` | `record` | `transaction`
+
+export type Signal<TVR extends Transceiver<any>> = TVR extends Transceiver<
+	infer Signal
+>
+	? Signal
+	: never
+
+/*
+A transceiver may also keep a list of updates that have been applied to it.
+This is useful for undo/redo functionality, especially in the context of
+revising history. It is a good idea to accept a cache limit in your 
+constructor, and overwrite old updates. Here's an example of how we 
+might set that up:
+
+myTransceiver = Transceiver {
+	cacheUpdateNumber: number = 27
+	cacheIdx: number = 1
+	cacheLimit: number = 3
+	cache: Array<Update> = [
+		26=add:"x"
+		27=del:"x" (current)
+		25=add:"y"
+	]
+}
+
+CONFIRM/NO-OP
+Update `27=del:"x"` is passed to myTransceiver.do:
+- [updateNumber = 27, update = `del:"x"`]	
+- updateOffset = updateNumber - cacheUpdateNumber // 0
+- eventOffset < 1 // true (we're validating the past)
+- |eventOffset| < cacheLimit // true (we remember this update)
+- eventIdx = cacheIdx + updateOffset // 1
+- update === cache.get(eventIdx) // true
+- return null // 👍
+
+EXPECTED UPDATE
+Update `28=add:"x"` is passed to myTransceiver.do:
+- [updateNumber = 28, update = `add:"x"`]
+- updateOffset = updateNumber - cacheUpdateNumber // 1
+- eventOffset < 1 // false (we're in the future)
+- eventOffset === 1 // true (we're ready to apply this update)
+- cacheIdx += eventOffset // 2
+- cacheIdx %= cacheLimit // 2
+- cache[cacheIdx] = update // cache = <{ 0 => add:"x" }>
+- return null  // 👍
+
+UNEXPECTED UPDATE
+Update `29=del:"x"` is passed to myTransceiver.do:
+- [updateNumber = 29, update = `del:"x"`]
+- updateOffset = updateNumber - cacheUpdateNumber // 2
+- eventOffset < 1 // false (we're in the future)
+- eventOffset === 1 // false (we're NOT ready to apply this update)
+- updateIdx := cacheIdx + updateOffset // 3
+- updateIdx %= cacheLimit // 0
+- cache[updateIdx] = update // cache = <{ 0 => del:"x" }> 
+- expectedUpdateNumber = cacheUpdateNumber + 1 // 28
+- return expectedUpdateNumber // 🤨👂
+
+SUCCESSFUL ROLLBACK UPDATE
+Update `25=add:"z"` is passed to myTransceiver.do:
+- [updateNumber = 25, update = `add:"z"`]
+- updateOffset = updateNumber - cacheUpdateNumber // -2
+- eventOffset < 1 // true (we're validating the past)
+- |eventOffset| < cacheLimit // true (we remember this update)
+- eventIdx = cacheIdx + updateOffset // -1
+- eventIdx %= cacheLimit // 2
+- update === cache[eventIdx] // false (we're rolling back)
+- done := false
+- update := cache[cacheIdx] // update = `del:"x"`
+- undo(update) // myTransceiver.undo(`del:"x"`)
+- while (!done) {
+- 	cacheIdx -= 1 // 0, -1
+- 	cacheIdx %= cacheLimit // 0, 2
+- 	update = cache[cacheIdx] // update = `add:"y"`, `add:"x"`
+- 	undo(update) // myTransceiver.undo(`add:"y"`), myTransceiver.undo(`add:"x"`)
+- 	done = cacheIdx === eventIdx // false, true
+- }
+- do(update) // myTransceiver.do(`add:"z"`)
+- return null // 👍
+
+UNSUCCESSFUL ROLLBACK UPDATE
+Update `24=add:"z"` is passed to myTransceiver.do:
+- [updateNumber = 24, update = `add:"z"`]
+- updateOffset = updateNumber - cacheUpdateNumber // -3
+- eventOffset < 1 // true (we're validating the past)
+- |eventOffset| < cacheLimit // 3 < 3 // false (we don't remember this update)
+- return `OUT_OF_RANGE` // 😵‍💫👂
+
+*/

package/internal/src/operation.ts

@@ -0,0 +1,68 @@
+import type { StateToken } from "atom.io"
+
+import type { Store } from "./store"
+import { IMPLICIT } from "./store"
+import { target } from "./transaction"
+
+export type OperationProgress =
+	| {
+			open: false
+	  }
+	| {
+			open: true
+			done: Set<string>
+			prev: Map<string, any>
+			time: number
+			token: StateToken<any>
+	  }
+
+export const openOperation = (token: StateToken<any>, store: Store): void => {
+	const core = target(store)
+	if (core.operation.open) {
+		store.config.logger?.error(
+			`❌ failed to setState to "${token.key}" during a setState for "${core.operation.token.key}"`,
+		)
+		throw Symbol(`violation`)
+	}
+	core.operation = {
+		open: true,
+		done: new Set(),
+		prev: new Map(store.valueMap),
+		time: Date.now(),
+		token,
+	}
+	store.config.logger?.info(
+		`⭕ operation start from "${token.key}" in store "${store.config.name}"${
+			store.transactionStatus.phase === `idle`
+				? ``
+				: ` ${store.transactionStatus.phase} "${store.transactionStatus.key}"`
+		}`,
+	)
+}
+export const closeOperation = (store: Store): void => {
+	const core = target(store)
+	core.operation = { open: false }
+	store.config.logger?.info(`🔴 operation done`)
+	store.subject.operationStatus.next(core.operation)
+}
+
+export const isDone = (key: string, store: Store = IMPLICIT.STORE): boolean => {
+	const core = target(store)
+	if (!core.operation.open) {
+		store.config.logger?.warn(
+			`isDone called outside of an operation. This is probably a bug.`,
+		)
+		return true
+	}
+	return core.operation.done.has(key)
+}
+export const markDone = (key: string, store: Store = IMPLICIT.STORE): void => {
+	const core = target(store)
+	if (!core.operation.open) {
+		store.config.logger?.warn(
+			`markDone called outside of an operation. This is probably a bug.`,
+		)
+		return
+	}
+	core.operation.done.add(key)
+}