atom.io 0.34.2 → 0.35.0

package/src/internal/index.ts

@@ -23,6 +23,7 @@ import type { Store } from "./store"
 import type { Subject } from "./subject"
 import type { Timeline } from "./timeline"
 import type { Transaction } from "./transaction"
+import type { Flat } from "./utility-types"
 
 export * from "./arbitrary"
 export * from "./atom"
@@ -61,45 +62,56 @@ export type AtomIOState = {
 	install: (store: Store) => void
 	subject: Subject<{ newValue: any; oldValue: any }>
 }
-
-export type RegularAtom<T> = AtomIOState & {
-	type: `atom`
-	default: T | (() => T)
-	cleanup?: () => void
-}
+export type RegularAtom<T> = Flat<
+	AtomIOState & {
+		type: `atom`
+		default: T | (() => T)
+		cleanup?: () => void
+	}
+>
 export type MutableAtom<
 	T extends Transceiver<any>,
 	J extends Json.Serializable,
-> = AtomIOState &
-	JsonInterface<T, J> & {
-		type: `mutable_atom`
-		default: () => T
-		cleanup?: () => void
-	}
+> = Flat<
+	AtomIOState &
+		JsonInterface<T, J> & {
+			type: `mutable_atom`
+			default: () => T
+			cleanup?: () => void
+		}
+>
 export type Atom<T> =
 	| RegularAtom<T>
 	| (T extends Transceiver<any> ? MutableAtom<T, any> : never)
 
-export type WritableHeldSelector<T> = AtomIOState & {
-	type: `writable_held_selector`
-	const: T
-	get: () => T
-	set: (newValue: T | ((oldValue: T) => T)) => void
-}
-export type ReadonlyHeldSelector<T> = AtomIOState & {
-	type: `readonly_held_selector`
-	const: T
-	get: () => T
-}
-export type WritablePureSelector<T> = AtomIOState & {
-	type: `writable_pure_selector`
-	get: () => T
-	set: (newValue: T | ((oldValue: T) => T)) => void
-}
-export type ReadonlyPureSelector<T> = AtomIOState & {
-	type: `readonly_pure_selector`
-	get: () => T
-}
+export type WritableHeldSelector<T> = Flat<
+	AtomIOState & {
+		type: `writable_held_selector`
+		const: T
+		get: () => T
+		set: (newValue: T | ((oldValue: T) => T)) => void
+	}
+>
+export type ReadonlyHeldSelector<T> = Flat<
+	AtomIOState & {
+		type: `readonly_held_selector`
+		const: T
+		get: () => T
+	}
+>
+export type WritablePureSelector<T> = Flat<
+	AtomIOState & {
+		type: `writable_pure_selector`
+		get: () => T
+		set: (newValue: T | ((oldValue: T) => T)) => void
+	}
+>
+export type ReadonlyPureSelector<T> = Flat<
+	AtomIOState & {
+		type: `readonly_pure_selector`
+		get: () => T
+	}
+>
 export type ReadonlySelector<T> =
 	| ReadonlyHeldSelector<T>
 	| ReadonlyPureSelector<T>
@@ -118,13 +130,13 @@ export type WritableState<T> = Atom<T> | WritableSelector<T>
 export type ReadableState<T> = Atom<T> | Selector<T>
 
 // biome-ignore format: intersection
-export type RegularAtomFamily<T, K extends Canonical> = 
+export type RegularAtomFamily<T, K extends Canonical> =
 	& RegularAtomFamilyToken<T, K>
 	& {
 		(key: K): RegularAtomToken<T>
-		subject: Subject<StateCreation<AtomToken<T>> | StateDisposal<AtomToken<T>>>
 		install: (store: Store) => void
 		internalRoles: string[] | undefined
+		subject: Subject<StateCreation<AtomToken<T>> | StateDisposal<AtomToken<T>>>
 	}
 
 // biome-ignore format: intersection
@@ -132,75 +144,85 @@ export type MutableAtomFamily<
 T extends Transceiver<any>,
 J extends Json.Serializable,
 K extends Canonical,
-> = 
-	& JsonInterface<T, J>
-	& MutableAtomFamilyToken<T, J, K>
-	& {
-			(key: K): MutableAtomToken<T, J>
-			subject: Subject<StateCreation<MutableAtomToken<T, J>> | StateDisposal<MutableAtomToken<T, J>>>
-			install: (store: Store) => void
-			internalRoles: string[] | undefined
-		}
+> =
+	& Flat<
+		& JsonInterface<T, J>
+		& MutableAtomFamilyToken<T, J, K>
+		& {
+				install: (store: Store) => void
+				internalRoles: string[] | undefined
+				subject: Subject<StateCreation<MutableAtomToken<T, J>> | StateDisposal<MutableAtomToken<T, J>>>
+			}
+	>
+	& ((key: K) => MutableAtomToken<T, J>)
 
 export type AtomFamily<T, K extends Canonical = Canonical> =
 	| MutableAtomFamily<T extends Transceiver<any> ? T : never, any, K>
 	| RegularAtomFamily<T, K>
 
 // biome-ignore format: intersection
-export type WritablePureSelectorFamily<T, K extends Canonical> = 
-	& WritablePureSelectorFamilyToken<T, K> 
-	& ((key: K) => WritablePureSelectorToken<T>)
-	& {
-		default: (key: K) => T,
-		subject: Subject<
-			| StateCreation<WritablePureSelectorToken<T>>
-			| StateDisposal<WritablePureSelectorToken<T>>
-		>
-		install: (store: Store) => void
-		internalRoles : string[] | undefined
-	}
+export type WritablePureSelectorFamily<T, K extends Canonical> =
+	& Flat<
+		& WritablePureSelectorFamilyToken<T, K>
+		& {
+			default: (key: K) => T,
+			install: (store: Store) => void
+			internalRoles: string[] | undefined
+			subject: Subject<
+				| StateCreation<WritablePureSelectorToken<T>>
+				| StateDisposal<WritablePureSelectorToken<T>>
+			>
+		}
+	>
+  & ((key: K) => WritablePureSelectorToken<T>)
 
 // biome-ignore format: intersection
-export type WritableHeldSelectorFamily<T , K extends Canonical> = 
-	& WritableHeldSelectorFamilyToken<T, K> 
-	& ((key: K) => WritableHeldSelectorToken<T>)
-	& {
-		default: (key: K) => T,
-		subject: Subject<
-			| StateCreation<WritableHeldSelectorToken<T>>
-			| StateDisposal<WritableHeldSelectorToken<T>>
-		>
-		install: (store: Store) => void
-		internalRoles : string[] | undefined
-	}
+export type WritableHeldSelectorFamily<T , K extends Canonical> =
+	& Flat<
+		& WritableHeldSelectorFamilyToken<T, K>
+		& {
+			default: (key: K) => T,
+			install: (store: Store) => void
+			internalRoles: string[] | undefined
+			subject: Subject<
+				| StateCreation<WritableHeldSelectorToken<T>>
+				| StateDisposal<WritableHeldSelectorToken<T>>
+			>
+		}
+	>
+  & ((key: K) => WritableHeldSelectorToken<T>)
 
 // biome-ignore format: intersection
-export type ReadonlyPureSelectorFamily<T, K extends Canonical> = 
-	& ReadonlyPureSelectorFamilyToken<T, K>
+export type ReadonlyPureSelectorFamily<T, K extends Canonical> =
+	& Flat<
+		& ReadonlyPureSelectorFamilyToken<T, K>
+		& {
+			default: (key: K) => T,
+			install: (store: Store) => void
+			internalRoles: string[] | undefined
+			subject: Subject<
+				| StateCreation<ReadonlyPureSelectorToken<T>>
+				| StateDisposal<ReadonlyPureSelectorToken<T>>
+			>
+		}
+	>
 	& ((key: K) => ReadonlyPureSelectorToken<T>)
-	& {
-		default: (key: K) => T,
-		subject: Subject<
-			| StateCreation<ReadonlyPureSelectorToken<T>>
-			| StateDisposal<ReadonlyPureSelectorToken<T>>
-		>
-		install: (store: Store) => void
-		internalRoles : string[] | undefined
-	}
 
 // biome-ignore format: intersection
-export type ReadonlyHeldSelectorFamily<T , K extends Canonical> = 
-	& ReadonlyHeldSelectorFamilyToken<T, K>
+export type ReadonlyHeldSelectorFamily<T , K extends Canonical> =
+	& Flat<
+		& ReadonlyHeldSelectorFamilyToken<T, K>
+		& {
+			default: (key: K) => T,
+			install: (store: Store) => void
+			internalRoles: string[] | undefined
+			subject: Subject<
+				| StateCreation<ReadonlyHeldSelectorToken<T>>
+				| StateDisposal<ReadonlyHeldSelectorToken<T>>
+			>
+		}
+	>
 	& ((key: K) => ReadonlyHeldSelectorToken<T>)
-	& {
-		default: (key: K) => T,
-		subject: Subject<
-			| StateCreation<ReadonlyHeldSelectorToken<T>> 
-			| StateDisposal<ReadonlyHeldSelectorToken<T>>
-		>
-		install: (store: Store) => void
-		internalRoles : string[] | undefined
-	}
 
 export type PureSelectorFamily<T, K extends Canonical> =
 	| ReadonlyPureSelectorFamily<T, K>

package/src/internal/join/join-internal.ts

@@ -8,8 +8,8 @@ import type {
 	ReadonlyPureSelectorFamilyToken,
 	RegularAtomFamilyToken,
 	setState,
-	SetterToolkit,
 	Write,
+	WriterToolkit,
 } from "atom.io"
 import { Anarchy } from "atom.io"
 import type { Canonical, Json, stringified } from "atom.io/json"
@@ -129,7 +129,7 @@ export class Join<
 		BSide
 	> = CompoundTypedKey<`content`, ASide, BSide>,
 > {
-	private toolkit: SetterToolkit
+	private toolkit: WriterToolkit
 	public options: JoinOptions<ASide, AType, BSide, BType, Cardinality, Content>
 	public defaultContent: Content | undefined
 	public molecules: Map<string, Molecule<any>> = new Map()
@@ -150,7 +150,7 @@ export class Join<
 		>
 	}
 	public transact(
-		toolkit: SetterToolkit,
+		toolkit: WriterToolkit,
 		run: (join: Join<ASide, AType, BSide, BType, Cardinality, Content>) => void,
 	): void {
 		const originalToolkit = this.toolkit
@@ -202,7 +202,6 @@ export class Join<
 			{
 				key: `${options.key}/relatedKeys`,
 				default: () => new SetRTX(),
-				mutable: true,
 				fromJson: (json) => SetRTX.fromJSON(json),
 				toJson: (set) => set.toJSON(),
 			},

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

@@ -59,7 +59,6 @@ export function createMutableAtomFamily<
 			default: () => options.default(key),
 			toJson: options.toJson,
 			fromJson: options.fromJson,
-			mutable: true,
 		}
 		if (options.effects) {
 			individualOptions.effects = options.effects(key)

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

@@ -88,6 +88,6 @@ export function createMutableAtom<
 	if (!family) {
 		selectJson(token, options, store)
 	}
-
+	store.on.atomCreation.next(token)
 	return token
 }

package/src/internal/selector/register-selector.ts

@@ -3,9 +3,9 @@ import type {
 	ReadableFamilyToken,
 	ReadableToken,
 	setState,
-	SetterToolkit,
 	WritableFamilyToken,
 	WritableToken,
+	WriterToolkit,
 } from "atom.io"
 import type { Json } from "atom.io/json"
 
@@ -27,7 +27,7 @@ export const registerSelector = (
 		| `writable_pure_selector`,
 	selectorKey: string,
 	covered: Set<string>,
-): SetterToolkit => ({
+): WriterToolkit => ({
 	get: (
 		...params:
 			| [ReadableFamilyToken<any, any>, Json.Serializable]

package/src/json/entries.ts

@@ -1,32 +1,32 @@
 import type { Count, Flat } from "atom.io/internal"
 
-/** @public Tuples of `[key, value]` pairs, as returned from `Object.entries` */
+/** Tuples of `[key, value]` pairs, as returned from `Object.entries` */
 export type Entries<K extends PropertyKey = PropertyKey, V = any> = [K, V][]
 
-/** @public The collective or "union" type of the keys in a set of entries */
+/** The collective or "union" type of the keys in a set of entries */
 export type KeyOfEntries<E extends Entries> = E extends [infer K, any][]
 	? K
 	: never
 
-/** @public The type of the value of entry `K` in a set of entries `E` */
+/** The type of the value of entry `K` in a set of entries `E` */
 export type ValueOfEntry<E extends Entries, K extends KeyOfEntries<E>> = {
 	[P in Count<E[`length`]>]: E[P] extends [K, infer V] ? V : never
 }[Count<E[`length`]>]
 
-/** @public The type of a set of entries `E` in object form */
+/** The type of a set of entries `E` in object form */
 export type FromEntries<E extends Entries> = Flat<{
 	[K in KeyOfEntries<E>]: ValueOfEntry<E, K>
 }>
 
-/** @public Typed form of `Object.fromEntries` */
+/** Typed form of `Object.fromEntries` */
 export function fromEntries<E extends Entries>(entries: E): FromEntries<E> {
 	return Object.fromEntries(entries) as FromEntries<E>
 }
 
-/** @public The type of an object T in {@link Entries} form */
+/** The type of an object T in {@link Entries} form */
 export type ToEntries<T extends object> = Entries<keyof T, T[keyof T]>
 
-/** @public Typed form of `Object.entries` */
+/** Typed form of `Object.entries` */
 export function toEntries<T extends object>(obj: T): ToEntries<T> {
 	return Object.entries(obj) as Entries<keyof T, T[keyof T]>
 }

package/src/main/atom.ts

@@ -1,15 +1,54 @@
 import type { Transceiver } from "atom.io/internal"
 import {
-	createAtomFamily,
-	createStandaloneAtom,
+	createMutableAtom,
+	createMutableAtomFamily,
+	createRegularAtom,
+	createRegularAtomFamily,
 	IMPLICIT,
 } from "atom.io/internal"
 import type { Canonical, Json, JsonInterface } from "atom.io/json"
 
-import type { AtomToken, MutableAtomToken, RegularAtomToken, Setter } from "."
+import type { Setter } from "./set-state"
+import type {
+	MutableAtomFamilyToken,
+	MutableAtomToken,
+	RegularAtomFamilyToken,
+	RegularAtomToken,
+} from "./tokens"
 
+export type RegularAtomOptions<T> = {
+	/** The unique identifier of the atom */
+	key: string
+	/** The starting value of the atom */
+	default: T | (() => T)
+	/** Hooks used to run side effects when the atom is set */
+	effects?: AtomEffect<T>[]
+}
+/**
+ * Create a regular atom, a global reactive variable in the implicit store
+ * @param options - {@link RegularAtomOptions}.
+ * @returns
+ * A reference to the atom created: a {@link RegularAtomToken}
+ */
+export function atom<T>(options: RegularAtomOptions<T>): RegularAtomToken<T> {
+	return createRegularAtom(IMPLICIT.STORE, options, undefined)
+}
+
+// biome-ignore format: intersection
+export type MutableAtomOptions<
+	T extends Transceiver<any>,
+	J extends Json.Serializable,
+> =
+	& JsonInterface<T, J>
+	& {
+		/** The unique identifier of the atom */
+		key: string
+		/** A function to create an initial value for the atom */
+		default: () => T
+		/** Hooks used to run side effects when the atom is set */
+		effects?: AtomEffect<T>[]
+	}
 /**
- * @public
  * Create a mutable atom, a global reactive variable in the implicit store
  *
  * The value of a mutable atom must be some kind of {@link Transceiver}.
@@ -17,27 +56,21 @@ import type { AtomToken, MutableAtomToken, RegularAtomToken, Setter } from "."
  * @param options - {@link MutableAtomOptions}.
  * @returns
  * A reference to the atom created: a {@link MutableAtomToken}
- * @overload Mutable
  */
-export function atom<T extends Transceiver<any>, J extends Json.Serializable>(
-	options: MutableAtomOptions<T, J>,
-): MutableAtomToken<T, J>
+export function mutableAtom<
+	T extends Transceiver<any>,
+	J extends Json.Serializable,
+>(options: MutableAtomOptions<T, J>): MutableAtomToken<T, J> {
+	return createMutableAtom(IMPLICIT.STORE, options, undefined)
+}
+
 /**
- * @public
- * Create a regular atom, a global reactive variable in the implicit store
- * @param options - {@link RegularAtomOptions}.
+ * A function that runs side effects when the atom is set
+ * @param tools - {@link Effectors} that can be used to run side effects
  * @returns
- * A reference to the atom created: a {@link RegularAtomToken}
- * @overload Regular
+ * Optionally, a cleanup function that will be called when the atom is disposed
  */
-export function atom<T>(options: RegularAtomOptions<T>): RegularAtomToken<T>
-export function atom(
-	options: MutableAtomOptions<any, any> | RegularAtomOptions<any>,
-): AtomToken<any> {
-	return createStandaloneAtom(IMPLICIT.STORE, options)
-}
-
-/** @public */
+export type AtomEffect<T> = (tools: Effectors<T>) => (() => void) | void
 export type Effectors<T> = {
 	/**
 	 * Reset the value of the atom to its default
@@ -52,44 +85,6 @@ export type Effectors<T> = {
 	onSet: (callback: (options: { newValue: T; oldValue: T }) => void) => void
 }
 
-/**
- * @public
- * A function that runs side effects when the atom is set
- * @param tools - {@link Effectors} that can be used to run side effects
- * @returns
- * Optionally, a cleanup function that will be called when the atom is disposed
- */
-export type AtomEffect<T> = (tools: Effectors<T>) => (() => void) | void
-
-/** @public */
-export type RegularAtomOptions<T> = {
-	/** The unique identifier of the atom */
-	key: string
-	/** The starting value of the atom */
-	default: T | (() => T)
-	/** Hooks used to run side effects when the atom is set */
-	effects?: AtomEffect<T>[]
-}
-
-/** @public */
-// biome-ignore format: intersection
-export type MutableAtomOptions<
-	T extends Transceiver<any>,
-	J extends Json.Serializable,
-> =
-	& JsonInterface<T, J>
-	& {
-		/** Used to signal that the atom is mutable */
-		mutable: true
-		/** The unique identifier of the atom */
-		key: string
-		/** A function to create an initial value for the atom */
-		default: () => T
-		/** Hooks used to run side effects when the atom is set */
-		effects?: AtomEffect<T>[]
-	}
-
-/** @public */
 export type RegularAtomFamilyOptions<T, K extends Canonical> = {
 	/** The unique identifier of the atom family */
 	key: string
@@ -98,19 +93,18 @@ export type RegularAtomFamilyOptions<T, K extends Canonical> = {
 	/** Hooks used to run side effects when an atom in the family is set  */
 	effects?: (key: K) => AtomEffect<T>[]
 }
-
-export type RegularAtomFamilyToken<T, K extends Canonical> = {
-	/** The unique identifier of the atom family */
-	key: string
-	/** Discriminator */
-	type: `atom_family`
-	/** Never present. This is a marker that preserves the type of atoms in this family */
-	__T?: T
-	/** Never present. This is a marker that preserves the type of keys used for atoms in this family */
-	__K?: K
+/**
+ * Create a family of regular atoms, allowing for the dynamic creation and disposal of atoms.
+ * @param options - {@link RegularAtomFamilyOptions}
+ * @returns
+ * A reference to the atom family created: a {@link RegularAtomFamilyToken}
+ */
+export function atomFamily<T, K extends Canonical>(
+	options: RegularAtomFamilyOptions<T, K>,
+): RegularAtomFamilyToken<T, K> {
+	return createRegularAtomFamily(IMPLICIT.STORE, options)
 }
 
-/** @public */
 // biome-ignore format: intersection
 export type MutableAtomFamilyOptions<
 	T extends Transceiver<any>,
@@ -119,8 +113,6 @@ export type MutableAtomFamilyOptions<
 > =
 	& JsonInterface<T, J>
 	& {
-		/** Used to signal that the atoms created from this family are mutable */
-		mutable: true
 		/** The unique identifier of the atom family */
 		key: string
 		/** A function to create an initial value for each atom in the family */
@@ -128,29 +120,7 @@ export type MutableAtomFamilyOptions<
 		/** Hooks used to run side effects when an atom in the family is set  */
 		effects?: (key: K) => AtomEffect<T>[]
 	}
-
-export type MutableAtomFamilyToken<
-	T extends Transceiver<any>,
-	J extends Json.Serializable,
-	K extends Canonical,
-> = {
-	/** The unique identifier of the atom family */
-	key: string
-	/** Discriminator */
-	type: `mutable_atom_family`
-	/** Never present. This is a marker that preserves the type of atoms in this family */
-	__T?: T
-	/** Never present. This is a marker that preserves the type of the JSON form of atoms in this family */
-	__J?: J
-	/** Never present. This is a marker that preserves the type of keys used for atoms in this family */
-	__K?: K
-}
-export type AtomFamilyToken<T, K extends Canonical = Canonical> =
-	| MutableAtomFamilyToken<T extends Transceiver<any> ? T : never, any, K>
-	| RegularAtomFamilyToken<T, K>
-
 /**
- * @public
  * Create a family of mutable atoms, allowing for the dynamic creation and disposal of atoms.
  *
  * The value of a mutable atom must be some kind of {@link Transceiver}.
@@ -158,28 +128,11 @@ export type AtomFamilyToken<T, K extends Canonical = Canonical> =
  * @param options - {@link MutableAtomFamilyOptions}
  * @returns
  * A reference to the atom family created: a {@link MutableAtomFamilyToken}
- * @overload Mutable
  */
-export function atomFamily<
+export function mutableAtomFamily<
 	T extends Transceiver<any>,
 	J extends Json.Serializable,
 	K extends Canonical,
->(options: MutableAtomFamilyOptions<T, J, K>): MutableAtomFamilyToken<T, J, K>
-/**
- * @public
- * Create a family of regular atoms, allowing for the dynamic creation and disposal of atoms.
- * @param options - {@link RegularAtomFamilyOptions}
- * @returns
- * A reference to the atom family created: a {@link RegularAtomFamilyToken}
- * @overload Regular
- */
-export function atomFamily<T, K extends Canonical>(
-	options: RegularAtomFamilyOptions<T, K>,
-): RegularAtomFamilyToken<T, K>
-export function atomFamily<T, K extends Canonical>(
-	options:
-		| MutableAtomFamilyOptions<any, any, any>
-		| RegularAtomFamilyOptions<T, K>,
-): MutableAtomFamilyToken<any, any, any> | RegularAtomFamilyToken<T, K> {
-	return createAtomFamily(IMPLICIT.STORE, options)
+>(options: MutableAtomFamilyOptions<T, J, K>): MutableAtomFamilyToken<T, J, K> {
+	return createMutableAtomFamily(IMPLICIT.STORE, options)
 }

package/src/main/dispose-state.ts

@@ -4,7 +4,6 @@ import type { Canonical } from "atom.io/json"
 import type { ReadableFamilyToken, ReadableToken } from "."
 
 /**
- * @public
  * Disposes of a state in the implicit store.
  *
  * Only family members can be disposed of.
@@ -14,7 +13,6 @@ import type { ReadableFamilyToken, ReadableToken } from "."
  */
 export function disposeState(token: ReadableToken<any>): void
 /**
- * @public
  * Disposes of a state in the implicit store.
  *
  * Only family members can be disposed of.