atom.io 0.34.2 → 0.35.0

package/src/main/find-state.ts

@@ -1,11 +1,9 @@
 import type {
-	MutableAtomFamilyToken,
 	MutableAtomToken,
 	ReadableFamilyToken,
 	ReadableToken,
 	ReadonlySelectorFamilyToken,
 	ReadonlySelectorToken,
-	RegularAtomFamilyToken,
 	RegularAtomToken,
 	WritableFamilyToken,
 	WritableSelectorFamilyToken,
@@ -16,8 +14,9 @@ import type { Transceiver } from "atom.io/internal"
 import { findInStore, IMPLICIT } from "atom.io/internal"
 import type { Canonical, Json } from "atom.io/json"
 
+import type { MutableAtomFamilyToken, RegularAtomFamilyToken } from "./tokens"
+
 /**
- * @public
  * Finds a {@link MutableAtomToken} in the store, without accessing its value.
  *
  * In an ephemeral store, this will create a new atom if one does not exist with the given key.
@@ -37,7 +36,6 @@ export function findState<
 	Key extends K,
 >(token: MutableAtomFamilyToken<T, J, K>, key: Key): MutableAtomToken<T, J, K>
 /**
- * @public
  * Finds a {@link RegularAtomToken} in the store, without accessing its value.
  *
  * In an ephemeral store, this will create a new atom if one does not exist with the given key.
@@ -55,7 +53,6 @@ export function findState<T, K extends Canonical, Key extends K>(
 	key: Key,
 ): RegularAtomToken<T, K>
 /**
- * @public
  * Finds a {@link WritableSelectorToken} in the store, without accessing its value.
  *
  * In an ephemeral store, this will create a new selector if one does not exist with the given key.
@@ -73,7 +70,6 @@ export function findState<T, K extends Canonical, Key extends K>(
 	key: Key,
 ): WritableSelectorToken<T, K>
 /**
- * @public
  * Finds a {@link ReadonlySelectorToken} in the store, without accessing its value.
  *
  * In an ephemeral store, this will create a new selector if one does not exist with the given key.
@@ -91,7 +87,6 @@ export function findState<T, K extends Canonical, Key extends K>(
 	key: Key,
 ): ReadonlySelectorToken<T, K>
 /**
- * @public
  * Finds a {@link WritableToken} in the store, without accessing its value.
  *
  * In an ephemeral store, this will create a new atom or selector if one does not exist with the given key.
@@ -109,7 +104,6 @@ export function findState<T, K extends Canonical, Key extends K>(
 	key: Key,
 ): WritableToken<T, K>
 /**
- * @public
  * Finds a {@link MutableAtomToken} in the store, without accessing its value.
  *
  * In an ephemeral store, this will create a new atom or selector if one does not exist with the given key.
@@ -130,7 +124,7 @@ export function findState<T, K extends Canonical, Key extends K>(
 
 export function findState(
 	token: ReadableFamilyToken<any, any>,
-	key: Json.Serializable,
+	key: Canonical,
 ): ReadableToken<any> {
 	const state = findInStore(IMPLICIT.STORE, token, key)
 	return state

package/src/main/get-state.ts

@@ -4,7 +4,6 @@ import type { Canonical } from "atom.io/json"
 import type { ReadableFamilyToken, ReadableToken } from "."
 
 /**
- * @public
  * Read or compute the current value of a state
  * @param token - The token of the state to get
  * @return The current value of the state
@@ -14,7 +13,6 @@ import type { ReadableFamilyToken, ReadableToken } from "."
 export function getState<T>(token: ReadableToken<T>): T
 
 /**
- * @public
  * Read or compute the current value of a state
  * @param token - The token of a state family
  * @param key - The unique key of the state to get

package/src/main/index.ts

@@ -1,14 +1,3 @@
-import type { Transceiver } from "atom.io/internal"
-import type { Canonical, Json, stringified } from "atom.io/json"
-
-import type { AtomFamilyToken } from "./atom"
-import type {
-	SelectorFamilyToken,
-	WritableSelectorFamilyToken,
-} from "./selector"
-import type { TimelineToken } from "./timeline"
-import type { TransactionToken } from "./transaction"
-
 export * from "./atom"
 export * from "./dispose-state"
 export * from "./find-state"
@@ -22,175 +11,11 @@ export * from "./set-state"
 export * from "./silo"
 export * from "./subscribe"
 export * from "./timeline"
+export type * from "./tokens"
 export * from "./transaction"
 export * from "./validators"
 
 /**
- * @public
- * A token is an object that uniquely identifies a particular state, family, timeline, or transaction.
- *
- * While they represent one of these resources, they are not the resource itself. Think of them like paper currency representing money in the bank.
- *
- * Tokens are returned from resource creation functions, such as {@link atom} and {@link transaction}.
- *
- * Tokens can be used as parameters to functions that take a token, such as {@link getState}, {@link setState}, or {@link runTransaction}.
- *
- * Tokens are fully serializable, so they can be passed between processes.
- */
-export type AtomIOToken =
-	| ReadableFamilyToken<any, any>
-	| ReadableToken<any>
-	| TimelineToken<any>
-	| TransactionToken<any>
-
-/** @public */
-export type RegularAtomToken<T, K extends Canonical = any> = {
-	/** The unique identifier of the atom. */
-	key: string
-	/** Discriminator. */
-	type: `atom`
-	/** Present if the atom belongs to a family. */
-	family?: FamilyMetadata<K>
-	/** Never present. This is a marker that preserves the type of the atom's value. */
-	__T?: T
-}
-/** @public */
-export type MutableAtomToken<
-	T extends Transceiver<any>,
-	J extends Json.Serializable,
-	K extends Canonical = any,
-> = {
-	/** The unique identifier of the atom. */
-	key: string
-	/** Discriminator. */
-	type: `mutable_atom`
-	/** Present if the atom belongs to a family. */
-	family?: FamilyMetadata<K>
-	/** Never present. This is a marker that preserves the JSON form of the atom's transceiver value. */
-	__J?: J
-	/** Never present. This is a marker that preserves the type of the atom's transceiver value. */
-	__U?: T extends Transceiver<infer Update> ? Update : never
-}
-/** @public */
-export type AtomToken<T, K extends Canonical = any> =
-	| MutableAtomToken<T extends Transceiver<any> ? T : never, any, K>
-	| RegularAtomToken<T, K>
-
-/** @public */
-export type WritablePureSelectorToken<T, K extends Canonical = any> = {
-	/** The unique identifier of the selector. */
-	key: string
-	/** Discriminator. */
-	type: `writable_pure_selector`
-	/** Present if the selector belongs to a family. */
-	family?: FamilyMetadata<K>
-	/** Never present. This is a marker that preserves the type of the selector's value. */
-	__T?: T
-}
-/** @public */
-export type WritableHeldSelectorToken<T, K extends Canonical = any> = {
-	/** The unique identifier of the selector. */
-	key: string
-	/** Discriminator. */
-	type: `writable_held_selector`
-	/** Present if the selector belongs to a family. */
-	family?: FamilyMetadata<K>
-	/** Never present. This is a marker that preserves the type of the selector's value. */
-	__T?: T
-}
-/** @public */
-export type ReadonlyPureSelectorToken<T, K extends Canonical = any> = {
-	/** The unique identifier of the selector. */
-	key: string
-	/** Discriminator. */
-	type: `readonly_pure_selector`
-	/** Present if the selector belongs to a family. */
-	family?: FamilyMetadata<K>
-	/** Never present. This is a marker that preserves the type of the selector's value. */
-	__T?: T
-}
-/** @public */
-export type ReadonlyHeldSelectorToken<T, K extends Canonical = any> = {
-	/** The unique identifier of the selector. */
-	key: string
-	/** Discriminator. */
-	type: `readonly_held_selector`
-	/** Present if the selector belongs to a family. */
-	family?: FamilyMetadata<K>
-	/** Never present. This is a marker that preserves the type of the selector's value. */
-	__T?: T
-}
-
-/** @public */
-export type PureSelectorToken<T, K extends Canonical = any> =
-	| ReadonlyPureSelectorToken<T, K>
-	| WritablePureSelectorToken<T, K>
-
-/** @public */
-export type HeldSelectorToken<T, K extends Canonical = any> =
-	| ReadonlyHeldSelectorToken<T, K>
-	| WritableHeldSelectorToken<T, K>
-
-/** @public */
-export type ReadonlySelectorToken<T, K extends Canonical = any> =
-	| ReadonlyHeldSelectorToken<T, K>
-	| ReadonlyPureSelectorToken<T, K>
-
-/** @public */
-export type WritableSelectorToken<T, K extends Canonical = any> =
-	| WritableHeldSelectorToken<T, K>
-	| WritablePureSelectorToken<T, K>
-
-/** @public */
-export type SelectorToken<T, K extends Canonical = any> =
-	| ReadonlyHeldSelectorToken<T, K>
-	| ReadonlyPureSelectorToken<T, K>
-	| WritableHeldSelectorToken<T, K>
-	| WritablePureSelectorToken<T, K>
-
-/**
- * @public
- * These states can be set.
- */
-export type WritableToken<T, K extends Canonical = any> =
-	| AtomToken<T, K>
-	| WritableSelectorToken<T, K>
-/**
- * @public
- * These states cannot be set.
- */
-export type ReadableToken<T, K extends Canonical = any> =
-	| AtomToken<T, K>
-	| SelectorToken<T, K>
-
-/**
- * @public
- * States belonging to this family can be set.
- */
-export type WritableFamilyToken<T, K extends Canonical> =
-	| AtomFamilyToken<T, K>
-	| WritableSelectorFamilyToken<T, K>
-/**
- * @public
- * States belonging to this family cannot be set.
- */
-export type ReadableFamilyToken<T, K extends Canonical> =
-	| AtomFamilyToken<T, K>
-	| SelectorFamilyToken<T, K>
-
-/**
- * @public
- * Identifies a state's connection to its family.
- */
-export type FamilyMetadata<K extends Canonical = any> = {
-	/** The family's unique key. */
-	key: string
-	/** The family member's unique identifier, in the form of a string. */
-	subKey: stringified<K>
-}
-
-/**
- * @public
  * Loadable is used to type atoms or selectors that may at some point be initialized to or set to a {@link Promise}.
  *
  * When a Promise is cached as the value of a state in atom.io, that state will be automatically set to the resolved value of the Promise when it is resolved.

package/src/main/join.ts

@@ -16,7 +16,6 @@ import {
 import type { Json } from "atom.io/json"
 import type { SetRTX, SetRTXJson } from "atom.io/transceivers/set-rtx"
 
-/** @public */
 // biome-ignore format: intersection
 export type JoinOptions<
 	ASide extends string,
@@ -40,7 +39,6 @@ export type JoinOptions<
 		}
 	> & Partial<JunctionEntriesBase<AType, BType, Content>>
 
-/** @public */
 export type JoinToken<
 	ASide extends string,
 	AType extends string,
@@ -68,7 +66,6 @@ export type JoinToken<
 }
 
 /**
- * @public
  * Create a join, an interface for managing relations between two sets of keys.
  *
  * Use joins when it is important to view relationships from either side.
@@ -92,7 +89,6 @@ export function join<
 	defaultContent?: undefined,
 ): JoinToken<ASide, AType, BSide, BType, Cardinality, null>
 /**
- * @public
  * Create a join, an interface for managing relations between two sets of keys.
  *
  * Use joins when it is important to view relationships from either side.
@@ -212,7 +208,6 @@ export type JoinStates<
 			: never
 
 /**
- * @public
  * Find the current value of a relation owned by a {@link join}
  * @param token - The token of the join
  * @param key - The key of the relation to find
@@ -235,7 +230,6 @@ export function findRelations<
 }
 
 /**
- * @public
  * Change one or multiple relations owned by a {@link join}
  * @param token - The token of the join
  * @param change - A function that takes a {@link Junction} interface to edit the relations
@@ -255,7 +249,6 @@ export function editRelations<
 }
 
 /**
- * @public
  * @param token - The token of the join
  * @returns
  * A {@link MutableAtomFamilyToken} to access the internal relations

package/src/main/reset-state.ts

@@ -4,7 +4,6 @@ import type { Canonical } from "atom.io/json"
 import type { WritableFamilyToken, WritableToken } from "."
 
 /**
- * @public
  * Set the value of a state into the implicit store back to its default value.
  * @param token - An atom or writable selector token.
  * @overload Default
@@ -12,7 +11,6 @@ import type { WritableFamilyToken, WritableToken } from "."
  */
 export function resetState(token: WritableToken<any>): void
 /**
- * @public
  * Set the value of a state into the implicit store back to its default value.
  * @param token - An atom family or writable selector family token.
  * @param key - The unique key of the state to set.

package/src/main/selector.ts

@@ -6,11 +6,15 @@ import {
 import type { Canonical } from "atom.io/json"
 
 import type {
+	ReadonlyHeldSelectorFamilyToken,
 	ReadonlyHeldSelectorToken,
+	ReadonlyPureSelectorFamilyToken,
 	ReadonlyPureSelectorToken,
+	WritableHeldSelectorFamilyToken,
 	WritableHeldSelectorToken,
+	WritablePureSelectorFamilyToken,
 	WritablePureSelectorToken,
-} from "."
+} from "./tokens"
 import type { Read, Write } from "./transaction"
 
 export type WritablePureSelectorOptions<T> = {
@@ -47,7 +51,6 @@ export type WritableHeldSelectorOptions<T extends object> = {
 }
 
 /**
- * @public
  * Declare a selector. The value of a selector should depend
  * on the value of atoms or other selectors in the store, and
  * should be recycled when a root atom of the selector is set.
@@ -68,7 +71,6 @@ export function selector<T extends object>(
 	options: WritableHeldSelectorOptions<T>,
 ): WritableHeldSelectorToken<T>
 /**
- * @public
  * Declare a selector. The value of a selector should depend
  * on the value of atoms or other selectors in the store,
  * and should be recycled when a root atom of the selector is set.
@@ -87,7 +89,6 @@ export function selector<T extends object>(
 	options: ReadonlyHeldSelectorOptions<T>,
 ): ReadonlyHeldSelectorToken<T>
 /**
- * @public
  * Declare a selector. The value of a selector should depend
  * on the value of atoms or other selectors in the store.
  *
@@ -107,7 +108,6 @@ export function selector<T>(
 	options: WritablePureSelectorOptions<T>,
 ): WritablePureSelectorToken<T>
 /**
- * @public
  * Declare a selector. The value of a selector should depend
  * on the value of atoms or other selectors in the store.
  *
@@ -138,7 +138,6 @@ export function selector(
 	return createStandaloneSelector(IMPLICIT.STORE, options)
 }
 
-/** @public */
 export type WritablePureSelectorFamilyOptions<T, K extends Canonical> = {
 	/** The unique identifier of the family */
 	key: string
@@ -147,14 +146,12 @@ export type WritablePureSelectorFamilyOptions<T, K extends Canonical> = {
 	/** For each instantiated family member, a function that sets its value */
 	set: (key: K) => Write<(newValue: T) => void>
 }
-/** @public */
 export type ReadonlyPureSelectorFamilyOptions<T, K extends Canonical> = {
 	/** The unique identifier of the family */
 	key: string
 	/** For each instantiated family member, a function that computes its value */
 	get: (key: K) => Read<() => T>
 }
-/** @public */
 export type WritableHeldSelectorFamilyOptions<
 	T extends object,
 	K extends Canonical,
@@ -168,7 +165,6 @@ export type WritableHeldSelectorFamilyOptions<
 	/** For each instantiated family member, a function that sets its value */
 	set: (key: K) => Write<(newValue: T) => void>
 }
-/** @public */
 export type ReadonlyHeldSelectorFamilyOptions<
 	T extends object,
 	K extends Canonical,
@@ -181,67 +177,7 @@ export type ReadonlyHeldSelectorFamilyOptions<
 	get: (key: K) => Read<(permanent: T) => void>
 }
 
-export type WritablePureSelectorFamilyToken<T, K extends Canonical> = {
-	/** The unique identifier of the family */
-	key: string
-	/** Discriminator */
-	type: `writable_pure_selector_family`
-	/** Never present. This is a marker that preserves the type of the value of each family member */
-	__T?: T
-	/** Never present. This is a marker that preserves the type of keys used for each family member */
-	__K?: K
-}
-export type ReadonlyPureSelectorFamilyToken<T, K extends Canonical> = {
-	/** The unique identifier of the family */
-	key: string
-	/** Discriminator */
-	type: `readonly_pure_selector_family`
-	/** Never present. This is a marker that preserves the type of the value of each family member */
-	__T?: T
-	/** Never present. This is a marker that preserves the type of keys used for each family member */
-	__K?: K
-}
-export type WritableHeldSelectorFamilyToken<T, K extends Canonical> = {
-	/** The unique identifier of the family */
-	key: string
-	/** Discriminator */
-	type: `writable_held_selector_family`
-	/** Never present. This is a marker that preserves the type of the value of each family member */
-	__T?: T
-	/** Never present. This is a marker that preserves the type of keys used for each family member */
-	__K?: K
-}
-export type ReadonlyHeldSelectorFamilyToken<T, K extends Canonical> = {
-	/** The unique identifier of the family */
-	key: string
-	/** Discriminator */
-	type: `readonly_held_selector_family`
-	/** Never present. This is a marker that preserves the type of the value of each family member */
-	__T?: T
-	/** Never present. This is a marker that preserves the type of keys used for each family member */
-	__K?: K
-}
-
-export type PureSelectorFamilyToken<T, K extends Canonical> =
-	| ReadonlyPureSelectorFamilyToken<T, K>
-	| WritablePureSelectorFamilyToken<T, K>
-export type HeldSelectorFamilyToken<T, K extends Canonical> =
-	| ReadonlyHeldSelectorFamilyToken<T, K>
-	| WritableHeldSelectorFamilyToken<T, K>
-export type ReadonlySelectorFamilyToken<T, K extends Canonical> =
-	| ReadonlyHeldSelectorFamilyToken<T, K>
-	| ReadonlyPureSelectorFamilyToken<T, K>
-
-export type WritableSelectorFamilyToken<T, K extends Canonical> =
-	| WritableHeldSelectorFamilyToken<T, K>
-	| WritablePureSelectorFamilyToken<T, K>
-
-export type SelectorFamilyToken<T, K extends Canonical> =
-	| HeldSelectorFamilyToken<T, K>
-	| PureSelectorFamilyToken<T, K>
-
 /**
- * @public
  * Create a family of selectors, allowing for the dynamic creation and disposal of selectors.
  *
  * The value of a held selector should depend on the value of atoms or other selectors in the store,
@@ -263,7 +199,6 @@ export function selectorFamily<T extends object, K extends Canonical>(
 	options: WritableHeldSelectorFamilyOptions<T, K>,
 ): WritableHeldSelectorFamilyToken<T, K>
 /**
- * @public
  * Create a family of selectors, allowing for the dynamic creation and disposal of selectors.
  *
  * The value of a held selector should depend on the value of atoms or other selectors in the store,
@@ -283,7 +218,6 @@ export function selectorFamily<T extends object, K extends Canonical>(
 	options: ReadonlyHeldSelectorFamilyOptions<T, K>,
 ): ReadonlyHeldSelectorFamilyToken<T, K>
 /**
- * @public
  * Create a family of selectors, allowing for the dynamic creation and disposal of selectors.
  *
  * The value of a selector should depend on the value of atoms or other selectors in the store.
@@ -304,7 +238,6 @@ export function selectorFamily<T, K extends Canonical>(
 	options: WritablePureSelectorFamilyOptions<T, K>,
 ): WritablePureSelectorFamilyToken<T, K>
 /**
- * @public
  * Create a family of selectors, allowing for the dynamic creation and disposal of selectors.
  *
  * The value of a selector should depend on the value of atoms or other selectors in the store.

package/src/main/set-state.ts

@@ -1,10 +1,9 @@
 import * as Internal from "atom.io/internal"
 import type { Canonical } from "atom.io/json"
 
-import type { WritableFamilyToken, WritableToken } from "."
+import type { WritableFamilyToken, WritableToken } from "./tokens"
 
 /**
- * @public
  * A function that sets the value of a state.
  * @param oldValue - The current value of the state.
  * @returns
@@ -13,7 +12,6 @@ import type { WritableFamilyToken, WritableToken } from "."
 export type Setter<T, New extends T> = (oldValue: T) => New
 
 /**
- * @public
  * Set the value of a state into the implicit store.
  * @param token - An atom or writable selector token.
  * @param value - The new value of the state.
@@ -26,7 +24,6 @@ export function setState<T, New extends T>(
 ): void
 
 /**
- * @public
  * Set the value of a state into the implicit store.
  * @param token - An atom family or writable selector family token.
  * @param key - The unique key of the state to set.

package/src/main/silo.ts

@@ -2,9 +2,11 @@ import type { findState } from "atom.io"
 import {
 	actUponStore,
 	arbitrary,
-	createAtomFamily,
+	createMutableAtom,
+	createMutableAtomFamily,
+	createRegularAtom,
+	createRegularAtomFamily,
 	createSelectorFamily,
-	createStandaloneAtom,
 	createStandaloneSelector,
 	createTimeline,
 	createTransaction,
@@ -30,7 +32,7 @@ import type {
 	timeline,
 	undo,
 } from "."
-import type { atom, atomFamily } from "./atom"
+import type { atom, atomFamily, mutableAtom, mutableAtomFamily } from "./atom"
 import type { resetState } from "./reset-state"
 import type { selector, selectorFamily } from "./selector"
 import type { runTransaction, transaction } from "./transaction"
@@ -38,7 +40,9 @@ import type { runTransaction, transaction } from "./transaction"
 export class Silo {
 	public store: Store
 	public atom: typeof atom
+	public mutableAtom: typeof mutableAtom
 	public atomFamily: typeof atomFamily
+	public mutableAtomFamily: typeof mutableAtomFamily
 	public selector: typeof selector
 	public selectorFamily: typeof selectorFamily
 	public transaction: typeof transaction
@@ -57,9 +61,14 @@ export class Silo {
 	public constructor(config: Store[`config`], fromStore: Store | null = null) {
 		const s = (this.store = new Store(config, fromStore))
 		this.atom = ((options: Parameters<typeof atom>[0]) =>
-			createStandaloneAtom(s, options)) as typeof atom
+			createRegularAtom(s, options, undefined)) as typeof atom
+		this.mutableAtom = ((options: Parameters<typeof mutableAtom>[0]) =>
+			createMutableAtom(s, options, undefined)) as typeof mutableAtom
 		this.atomFamily = ((options: Parameters<typeof atomFamily>[0]) =>
-			createAtomFamily(s, options)) as typeof atomFamily
+			createRegularAtomFamily(s, options)) as typeof atomFamily
+		this.mutableAtomFamily = ((
+			options: Parameters<typeof mutableAtomFamily>[0],
+		) => createMutableAtomFamily(s, options)) as typeof mutableAtomFamily
 		this.selector = ((options: Parameters<typeof selector>[0]) =>
 			createStandaloneSelector(s, options)) as typeof selector
 		this.selectorFamily = ((options: Parameters<typeof selectorFamily>[0]) =>

package/src/main/subscribe.ts

@@ -11,9 +11,7 @@ import type {
 	TransactionUpdate,
 } from "."
 
-/** @public */
 export type StateUpdate<T> = { newValue: T; oldValue: T }
-/** @public */
 export type KeyedStateUpdate<T> = Flat<
 	StateUpdate<T> & {
 		key: string
@@ -21,15 +19,12 @@ export type KeyedStateUpdate<T> = Flat<
 		family?: FamilyMetadata
 	}
 >
-/** @public */
 export type UpdateHandler<T> = (update: StateUpdate<T>) => void
-/** @public */
 export type TransactionUpdateHandler<F extends Func> = (
 	data: TransactionUpdate<F>,
 ) => void
 
 /**
- * @public
  * Subscribe to a state in the implicit store
  * @param token - The token of the state to subscribe to
  * @param handleUpdate - A function that will be called when the state is updated
@@ -43,7 +38,6 @@ export function subscribe<T>(
 	key?: string,
 ): () => void
 /**
- * @public
  * Subscribe to a transaction in the implicit store
  * @param token - The token of the transaction to subscribe to
  * @param handleUpdate - A function that will be called when the transaction succeeds
@@ -57,7 +51,6 @@ export function subscribe<F extends Func>(
 	key?: string,
 ): () => void
 /**
- * @public
  * Subscribe to a timeline in the implicit store
  * @param token - The token of the timeline to subscribe to
  * @param handleUpdate - A function that will be called when a new update is available