atom.io 0.34.1 → 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,25 +1,32 @@
 import type { Count, Flat } from "atom.io/internal"
 
+/** Tuples of `[key, value]` pairs, as returned from `Object.entries` */
 export type Entries<K extends PropertyKey = PropertyKey, V = any> = [K, V][]
 
+/** 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
 
+/** 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`]>]
 
+/** 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>
 }>
 
+/** Typed form of `Object.fromEntries` */
 export function fromEntries<E extends Entries>(entries: E): FromEntries<E> {
 	return Object.fromEntries(entries) as FromEntries<E>
 }
 
-export function toEntries<T extends object>(
-	obj: T,
-): Entries<keyof T, T[keyof T]> {
+/** The type of an object T in {@link Entries} form */
+export type ToEntries<T extends object> = Entries<keyof T, T[keyof T]>
+
+/** 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/json/index.ts

@@ -15,6 +15,7 @@ export namespace Json {
 		export type Node = Fork | Leaf
 	}
 
+	/** A value can survive being {@link JSON.stringify}-ed and {@link JSON.parse}-d fully intact */
 	export type Serializable =
 		| primitive
 		| Readonly<{ [key: string]: Serializable }>
@@ -29,33 +30,55 @@ export namespace Json {
 		ReadonlyArray<Element>
 }
 
-export type stringified<J extends Json.Serializable> = J extends string
-	? `"${J}"`
-	: J extends number
-		? `${J}`
-		: J extends true
-			? `true`
-			: J extends false
-				? `false`
-				: J extends boolean
-					? `false` | `true`
-					: J extends null
-						? `null`
-						: string & { __json?: J }
-
+/** A generic that retains the type information of a {@link Json.Serializable} value while in string form */
+// biome-ignore format: long silly ternary
+export type stringified<J extends Json.Serializable> = (
+      J extends string
+    ? `"${J}"`
+    : J extends number
+    ? `${J}`
+    : J extends true
+    ? `true`
+    : J extends false
+    ? `false`
+    : J extends boolean
+    ? `false` | `true`
+    : J extends null
+    ? `null`
+    : J extends []
+    ? `[]`
+    : J extends [infer Element extends Json.Serializable]
+    ? `[${stringified<Element>}]`
+    : J extends [
+					infer Element1 extends Json.Serializable,
+					infer Element2 extends Json.Serializable,
+				]
+    ? `[${stringified<Element1>}, ${stringified<Element2>}]`
+    : J extends [
+					infer Element1 extends Json.Serializable,
+					infer Element2 extends Json.Serializable,
+					infer Element3 extends Json.Serializable,
+				]
+    ? `[${stringified<Element1>}, ${stringified<Element2>}, ${stringified<Element3>}]`
+    : J extends any[]
+    ? `[${string}]` & { __json?: J }
+    : string & { __json?: J }
+  )
+
+/** Type-safe wrapper for {@link JSON.parse} */
 export const parseJson = <S extends stringified<Json.Serializable>>(
 	str: S | string,
 ): S extends stringified<infer J> ? J : Json.Serializable => JSON.parse(str)
 
+/** Type-safe wrapper for {@link JSON.stringify} */
 export const stringifyJson = <J extends Json.Serializable>(
 	json: J,
 ): stringified<J> => JSON.stringify(json) as stringified<J>
 
-/**
- * Always serializes to the same string.
- */
+/** Only Canonical values should be used for keys because they always serialize to the same string */
 export type Canonical = primitive | ReadonlyArray<Canonical>
 
+/** A function whose parameters and return value are {@link Json.Serializable} */
 export type JsonIO = (...params: Json.Serializable[]) => Json.Serializable | void
 
 export type JsonInterface<T, J extends Json.Serializable = Json.Serializable> = {