atom.io 0.34.1 → 0.35.0

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,29 +93,26 @@ 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>,
 	J extends Json.Serializable,
 	K extends Canonical,
 > =
-	& JsonInterface<T, J> 
+	& 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.

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,
@@ -25,7 +24,7 @@ export type JoinOptions<
 	BType extends string,
 	Cardinality extends `1:1` | `1:n` | `n:n`,
 	Content extends Json.Object | null,
-> = 
+> =
 	Flat<
 		& JunctionSchemaBase<ASide, BSide>
 		& {
@@ -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.
@@ -91,19 +88,7 @@ export function join<
 	options: JoinOptions<ASide, AType, BSide, BType, Cardinality, null>,
 	defaultContent?: undefined,
 ): JoinToken<ASide, AType, BSide, BType, Cardinality, null>
-export function join<
-	const ASide extends string,
-	const AType extends string,
-	const BSide extends string,
-	const BType extends string,
-	const Cardinality extends `1:1` | `1:n` | `n:n`,
-	const Content extends Json.Object,
->(
-	options: JoinOptions<ASide, AType, BSide, BType, Cardinality, Content>,
-	defaultContent: Content,
-): JoinToken<ASide, AType, BSide, BType, Cardinality, Content>
 /**
- * @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.
@@ -116,6 +101,17 @@ export function join<
  * A reference to the join created: a {@link JoinToken}
  * @overload With Content
  */
+export function join<
+	const ASide extends string,
+	const AType extends string,
+	const BSide extends string,
+	const BType extends string,
+	const Cardinality extends `1:1` | `1:n` | `n:n`,
+	const Content extends Json.Object,
+>(
+	options: JoinOptions<ASide, AType, BSide, BType, Cardinality, Content>,
+	defaultContent: Content,
+): JoinToken<ASide, AType, BSide, BType, Cardinality, Content>
 export function join<
 	ASide extends string,
 	AType extends string,
@@ -130,7 +126,6 @@ export function join<
 	return createJoin(IMPLICIT.STORE, options, defaultContent)
 }
 
-/** @public */
 export type JoinStates<
 	ASide extends string,
 	AType extends string,
@@ -213,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
@@ -236,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
@@ -256,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.