atom.io 0.40.1 → 0.40.2

package/src/main/selector.ts

@@ -17,19 +17,23 @@ import type {
 } from "./tokens"
 import type { Read, Write } from "./transaction"
 
-export type WritablePureSelectorOptions<T> = {
+export type WritablePureSelectorOptions<T, E = never> = {
 	/** The unique identifier of the selector */
 	key: string
 	/** For each instantiated selector, a function that computes its value */
 	get: Read<() => T>
 	/** For each instantiated selector, a function that sets its value */
 	set: Write<(newValue: T) => void>
+	/** The classes of errors that might be thrown when deriving the atom's default value */
+	catch?: readonly (new () => E)[]
 }
-export type ReadonlyPureSelectorOptions<T> = {
+export type ReadonlyPureSelectorOptions<T, E = never> = {
 	/** The unique identifier of the selector */
 	key: string
 	/** For each instantiated selector, a function that computes its value */
 	get: Read<() => T>
+	/** The classes of errors that might be thrown when deriving the atom's default value */
+	catch?: readonly (new () => E)[]
 }
 export type ReadonlyHeldSelectorOptions<T extends object> = {
 	/** The unique identifier of the selector */
@@ -104,9 +108,9 @@ export function selector<T extends object>(
  * The token for your selector.
  * @overload WritablePure
  */
-export function selector<T>(
-	options: WritablePureSelectorOptions<T>,
-): WritablePureSelectorToken<T>
+export function selector<T, E = never>(
+	options: WritablePureSelectorOptions<T, E>,
+): WritablePureSelectorToken<T, any, E>
 /**
  * Declare a selector. The value of a selector should depend
  * on the value of atoms or other selectors in the store.
@@ -121,36 +125,48 @@ export function selector<T>(
  * The token for your selector.
  * @overload ReadonlyPure
  */
-export function selector<T>(
-	options: ReadonlyPureSelectorOptions<T>,
-): ReadonlyPureSelectorToken<T>
+export function selector<T, E = never>(
+	options: ReadonlyPureSelectorOptions<T, E>,
+): ReadonlyPureSelectorToken<T, any, E>
 export function selector(
 	options:
 		| ReadonlyHeldSelectorOptions<any>
-		| ReadonlyPureSelectorOptions<any>
+		| ReadonlyPureSelectorOptions<any, any>
 		| WritableHeldSelectorOptions<any>
-		| WritablePureSelectorOptions<any>,
+		| WritablePureSelectorOptions<any, any>,
 ):
 	| ReadonlyHeldSelectorToken<any>
-	| ReadonlyPureSelectorToken<any>
+	| ReadonlyPureSelectorToken<any, any, any>
 	| WritableHeldSelectorToken<any>
-	| WritablePureSelectorToken<any> {
+	| WritablePureSelectorToken<any, any, any> {
 	return createStandaloneSelector(IMPLICIT.STORE, options)
 }
 
-export type WritablePureSelectorFamilyOptions<T, K extends Canonical> = {
+export type WritablePureSelectorFamilyOptions<
+	T,
+	K extends Canonical,
+	E = never,
+> = {
 	/** The unique identifier of the family */
 	key: string
 	/** For each instantiated family member, a function that computes its value */
 	get: (key: K) => Read<() => T>
 	/** For each instantiated family member, a function that sets its value */
 	set: (key: K) => Write<(newValue: T) => void>
+	/** The classes of errors that might be thrown when deriving the atom's default value */
+	catch?: readonly (new () => E)[]
 }
-export type ReadonlyPureSelectorFamilyOptions<T, K extends Canonical> = {
+export type ReadonlyPureSelectorFamilyOptions<
+	T,
+	K extends Canonical,
+	E = never,
+> = {
 	/** The unique identifier of the family */
 	key: string
 	/** For each instantiated family member, a function that computes its value */
 	get: (key: K) => Read<() => T>
+	/** The classes of errors that might be thrown when deriving the atom's default value */
+	catch?: readonly (new () => E)[]
 }
 export type WritableHeldSelectorFamilyOptions<
 	T extends object,
@@ -234,9 +250,9 @@ export function selectorFamily<T extends object, K extends Canonical>(
  * A reference to the selector family created: a {@link TransientWritableSelectorFamilyToken}
  * @overload WritablePure
  */
-export function selectorFamily<T, K extends Canonical>(
-	options: WritablePureSelectorFamilyOptions<T, K>,
-): WritablePureSelectorFamilyToken<T, K>
+export function selectorFamily<T, K extends Canonical, E = never>(
+	options: WritablePureSelectorFamilyOptions<T, K, E>,
+): WritablePureSelectorFamilyToken<T, K, E>
 /**
  * Create a family of selectors, allowing for the dynamic creation and disposal of selectors.
  *
@@ -252,19 +268,19 @@ export function selectorFamily<T, K extends Canonical>(
  * A reference to the selector family created: a {@link ReadonlyPureSelectorFamilyToken}
  * @overload ReadonlyPure
  */
-export function selectorFamily<T, K extends Canonical>(
-	options: ReadonlyPureSelectorFamilyOptions<T, K>,
-): ReadonlyPureSelectorFamilyToken<T, K>
+export function selectorFamily<T, K extends Canonical, E = never>(
+	options: ReadonlyPureSelectorFamilyOptions<T, K, E>,
+): ReadonlyPureSelectorFamilyToken<T, K, E>
 export function selectorFamily(
 	options:
 		| ReadonlyHeldSelectorFamilyOptions<any, any>
-		| ReadonlyPureSelectorFamilyOptions<any, any>
+		| ReadonlyPureSelectorFamilyOptions<any, any, any>
 		| WritableHeldSelectorFamilyOptions<any, any>
-		| WritablePureSelectorFamilyOptions<any, any>,
+		| WritablePureSelectorFamilyOptions<any, any, any>,
 ):
 	| ReadonlyHeldSelectorFamilyToken<any, any>
-	| ReadonlyPureSelectorFamilyToken<any, any>
+	| ReadonlyPureSelectorFamilyToken<any, any, any>
 	| WritableHeldSelectorFamilyToken<any, any>
-	| WritablePureSelectorFamilyToken<any, any> {
+	| WritablePureSelectorFamilyToken<any, any, any> {
 	return createSelectorFamily(IMPLICIT.STORE, options)
 }

package/src/main/set-state.ts

@@ -19,7 +19,7 @@ export type Setter<T, New extends T> = (oldValue: T) => New
  * @default
  */
 export function setState<T, New extends T>(
-	token: WritableToken<T>,
+	token: WritableToken<T, any, any>,
 	value: New | Setter<T, New>,
 ): void
 
@@ -31,15 +31,19 @@ export function setState<T, New extends T>(
  * @overload Streamlined
  */
 export function setState<T, K extends Canonical, New extends T, Key extends K>(
-	token: WritableFamilyToken<T, K>,
+	token: WritableFamilyToken<T, K, any>,
 	key: Key,
 	value: New | Setter<T, New>,
 ): void
 
 export function setState<T, K extends Canonical, New extends T, Key extends K>(
 	...params:
-		| [token: WritableFamilyToken<T, K>, key: Key, value: New | Setter<T, New>]
-		| [token: WritableToken<T>, value: New | Setter<T, New>]
+		| [
+				token: WritableFamilyToken<T, K, any>,
+				key: Key,
+				value: New | Setter<T, New>,
+		  ]
+		| [token: WritableToken<T, any, any>, value: New | Setter<T, New>]
 ): void {
 	setIntoStore(IMPLICIT.STORE, ...params)
 }

package/src/main/timeline.ts

@@ -2,13 +2,15 @@ import { createTimeline, IMPLICIT, timeTravel } from "atom.io/internal"
 
 import type { AtomFamilyToken, AtomToken, TimelineToken } from "."
 
-export type TimelineManageable = AtomFamilyToken<any, any> | AtomToken<any>
+export type TimelineManageable =
+	| AtomFamilyToken<any, any, any>
+	| AtomToken<any, any, any>
 export type AtomOnly<M extends TimelineManageable> = M extends AtomFamilyToken<
 	any,
 	any
 >
-	? AtomToken<any>
-	: M extends AtomToken<any>
+	? AtomToken<any, any, any>
+	: M extends AtomToken<any, any, any>
 		? M
 		: never
 

package/src/main/tokens.ts

@@ -13,31 +13,31 @@ import type { Canonical, stringified } from "atom.io/json"
  * Tokens are fully serializable, so they can be passed between processes.
  */
 export type AtomIOToken =
-	| ReadableFamilyToken<any, any>
-	| ReadableToken<any>
+	| ReadableFamilyToken<any, any, any>
+	| ReadableToken<any, any, any>
 	| TimelineToken<any>
 	| TransactionToken<any>
 
-export type ReadableToken<T, K extends Canonical = any> =
-	| AtomToken<T, K>
-	| SelectorToken<T, K>
+export type ReadableToken<T, K extends Canonical = any, E = never> =
+	| AtomToken<T, K, E>
+	| SelectorToken<T, K, E>
 
-export type WritableToken<T, K extends Canonical = any> =
-	| AtomToken<T, K>
-	| WritableSelectorToken<T, K>
+export type WritableToken<T, K extends Canonical = any, E = never> =
+	| AtomToken<T, K, E>
+	| WritableSelectorToken<T, K, E>
 
 /**
  * States belonging to this family can be read from the store.
  */
-export type ReadableFamilyToken<T, K extends Canonical> =
-	| AtomFamilyToken<T, K>
-	| SelectorFamilyToken<T, K>
+export type ReadableFamilyToken<T, K extends Canonical, E = never> =
+	| AtomFamilyToken<T, K, E>
+	| SelectorFamilyToken<T, K, E>
 /**
  * States belonging to this family can be written directly.
  */
-export type WritableFamilyToken<T, K extends Canonical> =
-	| AtomFamilyToken<T, K>
-	| WritableSelectorFamilyToken<T, K>
+export type WritableFamilyToken<T, K extends Canonical, E = never> =
+	| AtomFamilyToken<T, K, E>
+	| WritableSelectorFamilyToken<T, K, E>
 
 export type TimelineToken<M> = {
 	/** The unique identifier of the timeline */
@@ -57,10 +57,10 @@ export type TransactionToken<F extends Fn> = {
 	__F?: F
 }
 
-export type AtomToken<T, K extends Canonical = any> =
+export type AtomToken<T, K extends Canonical = any, E = never> =
 	| MutableAtomToken<T extends Transceiver<any, any, any> ? T : never, K>
-	| RegularAtomToken<T, K>
-export type RegularAtomToken<T, K extends Canonical = any> = {
+	| RegularAtomToken<T, K, E>
+export type RegularAtomToken<T, K extends Canonical = any, E = never> = {
 	/** The unique identifier of the atom. */
 	key: string
 	/** Discriminator. */
@@ -69,6 +69,8 @@ export type RegularAtomToken<T, K extends Canonical = any> = {
 	family?: FamilyMetadata<K>
 	/** Never present. This is a marker that preserves the type of the atom's value. */
 	__T?: T
+	/** Never present. This is a marker that preserves the type of errors this atom is capable of catching and setting as its value. */
+	__E?: E
 }
 export type MutableAtomToken<
 	T extends Transceiver<any, any, any>,
@@ -84,23 +86,27 @@ export type MutableAtomToken<
 	__J?: AsJSON<T>
 }
 
-export type SelectorToken<T, K extends Canonical = any> =
-	| ReadonlySelectorToken<T, K>
-	| WritableSelectorToken<T, K>
-export type ReadonlySelectorToken<T, K extends Canonical = any> =
+export type SelectorToken<T, K extends Canonical = any, E = never> =
+	| ReadonlySelectorToken<T, K, E>
+	| WritableSelectorToken<T, K, E>
+export type ReadonlySelectorToken<T, K extends Canonical = any, E = never> =
 	| ReadonlyHeldSelectorToken<T, K>
-	| ReadonlyPureSelectorToken<T, K>
-export type WritableSelectorToken<T, K extends Canonical = any> =
+	| ReadonlyPureSelectorToken<T, K, E>
+export type WritableSelectorToken<T, K extends Canonical = any, E = never> =
 	| WritableHeldSelectorToken<T, K>
-	| WritablePureSelectorToken<T, K>
-export type PureSelectorToken<T, K extends Canonical = any> =
-	| ReadonlyPureSelectorToken<T, K>
-	| WritablePureSelectorToken<T, K>
+	| WritablePureSelectorToken<T, K, E>
+export type PureSelectorToken<T, K extends Canonical = any, E = never> =
+	| ReadonlyPureSelectorToken<T, K, E>
+	| WritablePureSelectorToken<T, K, E>
 export type HeldSelectorToken<T, K extends Canonical = any> =
 	| ReadonlyHeldSelectorToken<T, K>
 	| WritableHeldSelectorToken<T, K>
 
-export type WritablePureSelectorToken<T, K extends Canonical = any> = {
+export type WritablePureSelectorToken<
+	T,
+	K extends Canonical = any,
+	E = never,
+> = {
 	/** The unique identifier of the selector. */
 	key: string
 	/** Discriminator. */
@@ -109,6 +115,8 @@ export type WritablePureSelectorToken<T, K extends Canonical = any> = {
 	family?: FamilyMetadata<K>
 	/** Never present. This is a marker that preserves the type of the selector's value. */
 	__T?: T
+	/** Never present. This is a marker that preserves the type of errors this selector is capable of catching and setting as its value. */
+	__E?: E
 }
 export type WritableHeldSelectorToken<T, K extends Canonical = any> = {
 	/** The unique identifier of the selector. */
@@ -120,7 +128,11 @@ export type WritableHeldSelectorToken<T, K extends Canonical = any> = {
 	/** Never present. This is a marker that preserves the type of the selector's value. */
 	__T?: T
 }
-export type ReadonlyPureSelectorToken<T, K extends Canonical = any> = {
+export type ReadonlyPureSelectorToken<
+	T,
+	K extends Canonical = any,
+	E = never,
+> = {
 	/** The unique identifier of the selector. */
 	key: string
 	/** Discriminator. */
@@ -129,6 +141,8 @@ export type ReadonlyPureSelectorToken<T, K extends Canonical = any> = {
 	family?: FamilyMetadata<K>
 	/** Never present. This is a marker that preserves the type of the selector's value. */
 	__T?: T
+	/** Never present. This is a marker that preserves the type of errors this selector is capable of catching and setting as its value. */
+	__E?: E
 }
 export type ReadonlyHeldSelectorToken<T, K extends Canonical = any> = {
 	/** The unique identifier of the selector. */
@@ -151,10 +165,10 @@ export type FamilyMetadata<K extends Canonical = any> = {
 	subKey: stringified<K>
 }
 
-export type AtomFamilyToken<T, K extends Canonical = Canonical> =
+export type AtomFamilyToken<T, K extends Canonical = Canonical, E = never> =
 	| MutableAtomFamilyToken<T extends Transceiver<any, any, any> ? T : never, K>
-	| RegularAtomFamilyToken<T, K>
-export type RegularAtomFamilyToken<T, K extends Canonical> = {
+	| RegularAtomFamilyToken<T, K, E>
+export type RegularAtomFamilyToken<T, K extends Canonical, E = never> = {
 	/** The unique identifier of the atom family */
 	key: string
 	/** Discriminator */
@@ -163,6 +177,8 @@ export type RegularAtomFamilyToken<T, K extends Canonical> = {
 	__T?: T
 	/** Never present. This is a marker that preserves the type of keys used for atoms in this family */
 	__K?: K
+	/** Never present. This is a marker that preserves the type of errors this family is capable of catching and setting as its value. */
+	__E?: E
 }
 export type MutableAtomFamilyToken<
 	T extends Transceiver<any, any, any>,
@@ -178,23 +194,27 @@ export type MutableAtomFamilyToken<
 	__K?: K
 }
 
-export type SelectorFamilyToken<T, K extends Canonical> =
-	| ReadonlySelectorFamilyToken<T, K>
-	| WritableSelectorFamilyToken<T, K>
-export type ReadonlySelectorFamilyToken<T, K extends Canonical> =
+export type SelectorFamilyToken<T, K extends Canonical, E = never> =
+	| ReadonlySelectorFamilyToken<T, K, E>
+	| WritableSelectorFamilyToken<T, K, E>
+export type ReadonlySelectorFamilyToken<T, K extends Canonical, E = never> =
 	| ReadonlyHeldSelectorFamilyToken<T, K>
-	| ReadonlyPureSelectorFamilyToken<T, K>
-export type WritableSelectorFamilyToken<T, K extends Canonical> =
+	| ReadonlyPureSelectorFamilyToken<T, K, E>
+export type WritableSelectorFamilyToken<T, K extends Canonical, E = never> =
 	| WritableHeldSelectorFamilyToken<T, K>
-	| WritablePureSelectorFamilyToken<T, K>
-export type PureSelectorFamilyToken<T, K extends Canonical> =
-	| ReadonlyPureSelectorFamilyToken<T, K>
-	| WritablePureSelectorFamilyToken<T, K>
+	| WritablePureSelectorFamilyToken<T, K, E>
+export type PureSelectorFamilyToken<T, K extends Canonical, E = never> =
+	| ReadonlyPureSelectorFamilyToken<T, K, E>
+	| WritablePureSelectorFamilyToken<T, K, E>
 export type HeldSelectorFamilyToken<T, K extends Canonical> =
 	| ReadonlyHeldSelectorFamilyToken<T, K>
 	| WritableHeldSelectorFamilyToken<T, K>
 
-export type WritablePureSelectorFamilyToken<T, K extends Canonical> = {
+export type WritablePureSelectorFamilyToken<
+	T,
+	K extends Canonical,
+	E = never,
+> = {
 	/** The unique identifier of the family */
 	key: string
 	/** Discriminator */
@@ -203,8 +223,14 @@ export type WritablePureSelectorFamilyToken<T, K extends Canonical> = {
 	__T?: T
 	/** Never present. This is a marker that preserves the type of keys used for each family member */
 	__K?: K
+	/** Never present. This is a marker that preserves the type of errors this family is capable of catching and setting as its value. */
+	__E?: E
 }
-export type ReadonlyPureSelectorFamilyToken<T, K extends Canonical> = {
+export type ReadonlyPureSelectorFamilyToken<
+	T,
+	K extends Canonical,
+	E = never,
+> = {
 	/** The unique identifier of the family */
 	key: string
 	/** Discriminator */
@@ -213,6 +239,8 @@ export type ReadonlyPureSelectorFamilyToken<T, K extends Canonical> = {
 	__T?: T
 	/** Never present. This is a marker that preserves the type of keys used for each family member */
 	__K?: K
+	/** Never present. This is a marker that preserves the type of errors this family is capable of catching and setting as its value. */
+	__E?: E
 }
 export type WritableHeldSelectorFamilyToken<T, K extends Canonical> = {
 	/** The unique identifier of the family */

package/src/main/validators.ts

@@ -16,8 +16,8 @@ import type {
 
 export type TokenType<
 	Comparison extends
-		| ReadableFamilyToken<any, any>
-		| ReadableToken<any>
+		| ReadableFamilyToken<any, any, any>
+		| ReadableToken<any, any, any>
 		| TransactionToken<any>,
 > = Comparison extends ReadableToken<infer RepresentedValue>
 	? RepresentedValue
@@ -27,9 +27,9 @@ export type TokenType<
 			? Fn
 			: never
 
-export function isToken<KnownToken extends RegularAtomToken<any>>(
+export function isToken<KnownToken extends RegularAtomToken<any, any, any>>(
 	knownToken: KnownToken,
-	unknownToken: ReadableToken<any>,
+	unknownToken: ReadableToken<any, any, any>,
 ): unknownToken is RegularAtomToken<TokenType<KnownToken>>
 export function isToken<KnownToken extends MutableAtomToken<any, any>>(
 	knownToken: KnownToken,

package/src/react/parse-state-overloads.ts

@@ -8,21 +8,21 @@ import type { Store } from "atom.io/internal"
 import { findInStore } from "atom.io/internal"
 import type { Canonical } from "atom.io/json"
 
-export function parseStateOverloads<T, K extends Canonical>(
+export function parseStateOverloads<T, K extends Canonical, Key extends K, E>(
 	store: Store,
-	...rest: [WritableFamilyToken<T, K>, K] | [WritableToken<T>]
-): WritableToken<T>
+	...rest: [WritableFamilyToken<T, K, E>, Key] | [WritableToken<T, any, E>]
+): WritableToken<T, K, E>
 
-export function parseStateOverloads<T, K extends Canonical>(
+export function parseStateOverloads<T, K extends Canonical, Key extends K, E>(
 	store: Store,
-	...rest: [ReadableFamilyToken<T, K>, K] | [ReadableToken<T>]
-): ReadableToken<T>
+	...rest: [ReadableFamilyToken<T, K, E>, Key] | [ReadableToken<T, any, E>]
+): ReadableToken<T, K, E>
 
-export function parseStateOverloads<T, K extends Canonical>(
+export function parseStateOverloads<T, K extends Canonical, Key extends K, E>(
 	store: Store,
-	...rest: [ReadableFamilyToken<T, K>, K] | [ReadableToken<T>]
-): ReadableToken<T> {
-	let token: ReadableToken<any>
+	...rest: [ReadableFamilyToken<T, K, E>, Key] | [ReadableToken<T, any, E>]
+): ReadableToken<T, K, E> {
+	let token: ReadableToken<any, any, any>
 	if (rest.length === 2) {
 		const family = rest[0]
 		const key = rest[1]

package/src/react/use-i.ts

@@ -7,16 +7,16 @@ import { parseStateOverloads } from "./parse-state-overloads"
 import { StoreContext } from "./store-context"
 
 export function useI<T>(
-	token: WritableToken<T>,
+	token: WritableToken<T, any, any>,
 ): <New extends T>(next: New | ((old: T) => New)) => void
 
-export function useI<T, K extends Canonical>(
-	token: WritableFamilyToken<T, K>,
-	key: K,
+export function useI<T, K extends Canonical, Key extends K>(
+	token: WritableFamilyToken<T, K, any>,
+	key: Key,
 ): <New extends T>(next: New | ((old: T) => New)) => void
 
-export function useI<T, K extends Canonical>(
-	...params: [WritableFamilyToken<T, K>, K] | [WritableToken<T>]
+export function useI<T, K extends Canonical, Key extends K>(
+	...params: [WritableFamilyToken<T, K, any>, Key] | [WritableToken<T, any, any>]
 ): <New extends T>(next: New | ((old: T) => New)) => void {
 	const store = React.useContext(StoreContext)
 	const token = parseStateOverloads(store, ...params)

package/src/react/use-loadable.ts

@@ -4,32 +4,32 @@ import type { Canonical } from "atom.io/json"
 import { useO } from "atom.io/react"
 import React from "react"
 
-export function useLoadable<T>(
-	token: ReadableToken<Loadable<T>>,
-): `LOADING` | { loading: boolean; value: T }
+export function useLoadable<T, E>(
+	token: ReadableToken<Loadable<T>, any, E>,
+): `LOADING` | { loading: boolean; value: E | T }
 
-export function useLoadable<T, K extends Canonical>(
-	token: ReadableFamilyToken<Loadable<T>, K>,
+export function useLoadable<T, K extends Canonical, E>(
+	token: ReadableFamilyToken<Loadable<T>, K, E>,
 	key: K,
-): `LOADING` | { loading: boolean; value: T }
+): `LOADING` | { loading: boolean; value: E | T }
 
-export function useLoadable<T, F extends T>(
-	token: ReadableToken<Loadable<T>>,
+export function useLoadable<T, F extends T, E>(
+	token: ReadableToken<Loadable<T>, any, E>,
 	fallback: F,
 ): { loading: boolean; value: T }
 
-export function useLoadable<T, K extends Canonical, F extends T>(
-	token: ReadableFamilyToken<Loadable<T>, K>,
+export function useLoadable<T, K extends Canonical, F extends T, E>(
+	token: ReadableFamilyToken<Loadable<T>, K, E>,
 	key: K,
 	fallback: F,
-): { loading: boolean; value: T }
+): { loading: boolean; value: E | T }
 
 export function useLoadable(
 	...params:
-		| readonly [ReadableFamilyToken<any, Canonical>, Canonical, unknown]
-		| readonly [ReadableFamilyToken<any, Canonical>, Canonical]
-		| readonly [ReadableToken<any>, unknown]
-		| readonly [ReadableToken<any>]
+		| readonly [ReadableFamilyToken<any, Canonical, any>, Canonical, unknown]
+		| readonly [ReadableFamilyToken<any, Canonical, any>, Canonical]
+		| readonly [ReadableToken<any, any, any>, unknown]
+		| readonly [ReadableToken<any, any, any>]
 ): `LOADING` | { loading: boolean; value: unknown } {
 	let state: unknown
 	let fallback: unknown

package/src/react/use-o.ts

@@ -6,20 +6,20 @@ import * as React from "react"
 import { parseStateOverloads } from "./parse-state-overloads"
 import { StoreContext } from "./store-context"
 
-export function useO<T>(token: ReadableToken<T>): T
+export function useO<T, E>(token: ReadableToken<T, any, E>): E | T
 
-export function useO<T, K extends Canonical>(
-	token: ReadableFamilyToken<T, K>,
-	key: K,
-): T
+export function useO<T, K extends Canonical, Key extends K, E>(
+	token: ReadableFamilyToken<T, K, E>,
+	key: Key,
+): E | T
 
-export function useO<T, K extends Canonical>(
-	...params: [ReadableFamilyToken<T, K>, K] | [ReadableToken<T>]
-): T {
+export function useO<T, K extends Canonical, Key extends K, E>(
+	...params: [ReadableFamilyToken<T, K, E>, Key] | [ReadableToken<T, any, E>]
+): E | T {
 	const store = React.useContext(StoreContext)
 	const token = parseStateOverloads(store, ...params)
 	const id = React.useId()
-	return React.useSyncExternalStore<T>(
+	return React.useSyncExternalStore<E | T>(
 		(dispatch) => subscribeToState(store, token, `use-o:${id}`, dispatch),
 		() => getFromStore(store, token),
 		() => getFromStore(store, token),

package/src/react-devtools/StateEditor.tsx

@@ -5,7 +5,7 @@ import type { FC } from "react"
 import { JsonEditor } from "./json-editor"
 
 export const StateEditor: FC<{
-	token: WritableToken<unknown>
+	token: WritableToken<unknown, any, unknown>
 }> = ({ token }) => {
 	const set = useI(token)
 	const data = useO(token)
@@ -23,7 +23,7 @@ export const StateEditor: FC<{
 }
 
 export const ReadonlySelectorViewer: FC<{
-	token: ReadonlySelectorToken<unknown>
+	token: ReadonlySelectorToken<unknown, any, unknown>
 }> = ({ token }) => {
 	const data = useO(token)
 	const metaPath = token.family
@@ -41,7 +41,9 @@ export const ReadonlySelectorViewer: FC<{
 }
 
 export const StoreEditor: FC<{
-	token: ReadonlySelectorToken<unknown> | WritableToken<unknown>
+	token:
+		| ReadonlySelectorToken<unknown, any, unknown>
+		| WritableToken<unknown, any, unknown>
 }> = ({ token }) => {
 	switch (token.type) {
 		case `readonly_pure_selector`:

package/src/react-devtools/StateIndex.tsx

@@ -25,7 +25,7 @@ import { DevtoolsContext } from "./store"
 /* eslint-disable no-console */
 
 export const StateIndexLeafNode: FC<{
-	node: ReadableToken<unknown>
+	node: ReadableToken<unknown, any, unknown>
 	isOpenState: RegularAtomToken<boolean>
 	typeState: ReadonlyPureSelectorToken<Loadable<string>>
 	dispose?: (() => void) | undefined
@@ -95,7 +95,7 @@ export const StateIndexLeafNode: FC<{
 	)
 }
 export const StateIndexTreeNode: FC<{
-	node: FamilyNode<ReadableToken<unknown>>
+	node: FamilyNode<ReadableToken<unknown, any, unknown>>
 	isOpenState: RegularAtomToken<boolean>
 }> = ({ node, isOpenState }) => {
 	const setIsOpen = useI(isOpenState)
@@ -147,7 +147,9 @@ export const StateIndexTreeNode: FC<{
 }
 
 export const StateIndexNode: FC<{
-	node: FamilyNode<ReadableToken<unknown>> | ReadableToken<unknown>
+	node:
+		| FamilyNode<ReadableToken<unknown, any, unknown>>
+		| ReadableToken<unknown, any, unknown>
 	isOpenState: RegularAtomToken<boolean>
 	typeState: ReadonlyPureSelectorToken<Loadable<string>>
 	dispose?: () => void
@@ -169,7 +171,7 @@ export const StateIndexNode: FC<{
 }
 
 export const StateIndex: FC<{
-	tokenIndex: AtomToken<WritableTokenIndex<ReadableToken<unknown>>>
+	tokenIndex: AtomToken<WritableTokenIndex<ReadableToken<unknown, any, unknown>>>
 }> = ({ tokenIndex }) => {
 	const tokenIds = useO(tokenIndex)
 

package/src/react-devtools/Updates.tsx

@@ -13,7 +13,7 @@ import * as React from "react"
 
 const AtomUpdateFC: React.FC<{
 	serialNumber: number
-	atomUpdate: AtomUpdateEvent<AtomToken<unknown>>
+	atomUpdate: AtomUpdateEvent<AtomToken<unknown, any, any>>
 }> = ({ atomUpdate }) => {
 	return (
 		<article