atom.io 0.34.1 → 0.35.0

package/src/main/transaction.ts

@@ -1,4 +1,3 @@
-import type { findState, getState, setState } from "atom.io"
 import type { EnvironmentData, Func, Transceiver } from "atom.io/internal"
 import {
 	actUponStore,
@@ -8,65 +7,51 @@ import {
 } from "atom.io/internal"
 import type { Canonical, Json, stringified } from "atom.io/json"
 
+import type { disposeState } from "./dispose-state"
+import type { findState } from "./find-state"
+import type { getState } from "./get-state"
+import type { resetState } from "./reset-state"
+import type { setState } from "./set-state"
+import type { KeyedStateUpdate } from "./subscribe"
 import type {
-	disposeState,
-	KeyedStateUpdate,
 	MutableAtomToken,
 	ReadableToken,
-	TokenType,
+	TransactionToken,
 	WritablePureSelectorToken,
-} from "."
-import type { resetState } from "./reset-state"
+} from "./tokens"
+import type { TokenType } from "./validators"
 
-/** @public */
-export type TransactionToken<F extends Func> = {
-	/** The unique identifier of the transaction */
-	key: string
-	/** Discriminator */
-	type: `transaction`
-	/** Never present. This is a marker that preserves the type of the transaction function */
-	__F?: F
-}
-
-/** @public */
 export type StateCreation<Token extends ReadableToken<any>> = {
 	type: `state_creation`
 	token: Token
 }
-/** @public */
+export type StateDisposal<Token extends ReadableToken<any>> =
+	| AtomDisposal<Token>
+	| SelectorDisposal<Token>
+
 export type AtomDisposal<Token extends ReadableToken<any>> = {
 	type: `state_disposal`
 	subType: `atom`
 	token: Token
 	value: TokenType<Token>
 }
-/** @public */
 export type SelectorDisposal<Token extends ReadableToken<any>> = {
 	type: `state_disposal`
 	subType: `selector`
 	token: Token
 }
-/** @public */
-export type StateDisposal<Token extends ReadableToken<any>> =
-	| AtomDisposal<Token>
-	| SelectorDisposal<Token>
 
-/** @public */
 export type MoleculeCreation = {
 	type: `molecule_creation`
 	key: Canonical
 	provenance: Canonical
 }
-
-/** @public */
 export type MoleculeDisposal = {
 	type: `molecule_disposal`
 	key: Canonical
 	provenance: stringified<Canonical>[]
 	values: [key: string, value: any][]
 }
-
-/** @public */
 export type MoleculeTransfer = {
 	type: `molecule_transfer`
 	key: Canonical
@@ -74,7 +59,6 @@ export type MoleculeTransfer = {
 	to: Canonical[]
 }
 
-/** @public */
 export type TransactionUpdateContent =
 	| KeyedStateUpdate<unknown>
 	| MoleculeCreation
@@ -84,7 +68,6 @@ export type TransactionUpdateContent =
 	| StateDisposal<ReadableToken<unknown>>
 	| TransactionUpdate<Func>
 
-/** @public */
 export type TransactionUpdate<F extends Func> = {
 	type: `transaction_update`
 	key: string
@@ -95,18 +78,8 @@ export type TransactionUpdate<F extends Func> = {
 	output: ReturnType<F>
 }
 
-/** @public */
-export type GetterToolkit = Pick<SetterToolkit, `find` | `get` | `json`>
-/** @public */
-export type SetterToolkit = Readonly<{
-	get: typeof getState
-	set: typeof setState
-	find: typeof findState
-	json: <T extends Transceiver<any>, J extends Json.Serializable>(
-		state: MutableAtomToken<T, J>,
-	) => WritablePureSelectorToken<J>
-}>
-/** @public */
+export type ReaderToolkit = Pick<ActorToolkit, `find` | `get` | `json`>
+export type WriterToolkit = Pick<ActorToolkit, `find` | `get` | `json` | `set`>
 export type ActorToolkit = Readonly<{
 	get: typeof getState
 	set: typeof setState
@@ -120,29 +93,20 @@ export type ActorToolkit = Readonly<{
 	env: () => EnvironmentData
 }>
 
-/** @public */
 export type Read<F extends Func> = (
-	toolkit: GetterToolkit,
+	toolkit: ReaderToolkit,
 	...parameters: Parameters<F>
 ) => ReturnType<F>
-
-/** @public */
 export type Write<F extends Func> = (
-	toolkit: SetterToolkit,
+	toolkit: WriterToolkit,
 	...parameters: Parameters<F>
 ) => ReturnType<F>
-
-/** @public */
 export type Transact<F extends Func> = (
 	toolkit: ActorToolkit,
 	...parameters: Parameters<F>
 ) => ReturnType<F>
-
-/** @public */
 export type TransactionIO<Token extends TransactionToken<any>> =
 	Token extends TransactionToken<infer F> ? F : never
-
-/** @public */
 export type TransactionOptions<F extends Func> = {
 	/** The unique identifier of the transaction */
 	key: string
@@ -151,7 +115,6 @@ export type TransactionOptions<F extends Func> = {
 }
 
 /**
- * @public
  * Create a transaction, a mechanism for batching updates multiple states in a single, all-or-nothing operation
  * @param options - {@link TransactionOptions}
  * @returns A reference to the transaction created: a {@link TransactionToken}
@@ -163,7 +126,6 @@ export function transaction<F extends Func>(
 }
 
 /**
- * @public
  * Execute a {@link transaction}
  * @param token - A {@link TransactionToken}
  * @param id - A unique identifier for the transaction. If not provided, a random identifier will be generated

package/src/main/validators.ts

@@ -11,7 +11,7 @@ import type {
 	WritablePureSelectorFamilyToken,
 	WritablePureSelectorToken,
 	WritableToken,
-} from "atom.io"
+} from "./tokens"
 
 export type TokenType<
 	Comparison extends ReadableFamilyToken<any, any> | ReadableToken<any>,

package/src/react-devtools/store.ts

@@ -6,8 +6,8 @@ import type {
 	TransactionToken,
 } from "atom.io"
 import {
-	createAtomFamily,
-	createStandaloneAtom,
+	createRegularAtom,
+	createRegularAtomFamily,
 	createTransaction,
 	type Store,
 } from "atom.io/internal"
@@ -39,53 +39,69 @@ export function attachDevtoolsStates(
 ): DevtoolsStates & IntrospectionStates & { store: Store } {
 	const introspectionStates = attachIntrospectionStates(store)
 
-	const devtoolsAreHiddenAtom = createStandaloneAtom<boolean>(store, {
-		key: `🔍 Devtools Are Hidden`,
-		default: hideByDefault,
-		effects:
-			typeof window === `undefined`
-				? []
-				: [
-						persistSync(window.localStorage, JSON, `🔍 Devtools Are Hidden`),
-						({ setSelf }) => {
-							window.addEventListener(`keydown`, (e) => {
-								if (e.ctrlKey && e.shiftKey && e.key.toLowerCase() === `a`) {
-									e.preventDefault()
-									setSelf((state) => !state)
-								}
-							})
-						},
-					],
-	})
+	const devtoolsAreHiddenAtom = createRegularAtom<boolean>(
+		store,
+		{
+			key: `🔍 Devtools Are Hidden`,
+			default: hideByDefault,
+			effects:
+				typeof window === `undefined`
+					? []
+					: [
+							persistSync(window.localStorage, JSON, `🔍 Devtools Are Hidden`),
+							({ setSelf }) => {
+								window.addEventListener(`keydown`, (e) => {
+									if (e.ctrlKey && e.shiftKey && e.key.toLowerCase() === `a`) {
+										e.preventDefault()
+										setSelf((state) => !state)
+									}
+								})
+							},
+						],
+		},
+		undefined,
+	)
 
-	const devtoolsAreOpenAtom = createStandaloneAtom<boolean>(store, {
-		key: `🔍 Devtools Are Open`,
-		default: true,
-		effects:
-			typeof window === `undefined`
-				? []
-				: [persistSync(window.localStorage, JSON, `🔍 Devtools Are Open`)],
-	})
+	const devtoolsAreOpenAtom = createRegularAtom<boolean>(
+		store,
+		{
+			key: `🔍 Devtools Are Open`,
+			default: true,
+			effects:
+				typeof window === `undefined`
+					? []
+					: [persistSync(window.localStorage, JSON, `🔍 Devtools Are Open`)],
+		},
+		undefined,
+	)
 
-	const devtoolsViewSelectionAtom = createStandaloneAtom<DevtoolsView>(store, {
-		key: `🔍 Devtools View Selection`,
-		default: `atoms`,
-		effects:
-			typeof window === `undefined`
-				? []
-				: [persistSync(window.localStorage, JSON, `🔍 Devtools View`)],
-	})
+	const devtoolsViewSelectionAtom = createRegularAtom<DevtoolsView>(
+		store,
+		{
+			key: `🔍 Devtools View Selection`,
+			default: `atoms`,
+			effects:
+				typeof window === `undefined`
+					? []
+					: [persistSync(window.localStorage, JSON, `🔍 Devtools View`)],
+		},
+		undefined,
+	)
 
-	const devtoolsViewOptionsAtom = createStandaloneAtom<DevtoolsView[]>(store, {
-		key: `🔍 Devtools View Options`,
-		default: [`atoms`, `selectors`, `transactions`, `timelines`],
-		effects:
-			typeof window === `undefined`
-				? []
-				: [persistSync(window.localStorage, JSON, `🔍 Devtools View Options`)],
-	})
+	const devtoolsViewOptionsAtom = createRegularAtom<DevtoolsView[]>(
+		store,
+		{
+			key: `🔍 Devtools View Options`,
+			default: [`atoms`, `selectors`, `transactions`, `timelines`],
+			effects:
+				typeof window === `undefined`
+					? []
+					: [persistSync(window.localStorage, JSON, `🔍 Devtools View Options`)],
+		},
+		undefined,
+	)
 
-	const viewIsOpenAtoms = createAtomFamily<
+	const viewIsOpenAtoms = createRegularAtomFamily<
 		boolean,
 		readonly (number | string)[]
 	>(store, {

package/src/realtime/shared-room-store.ts

@@ -3,16 +3,15 @@ import type {
 	MutableAtomToken,
 	ReadonlyPureSelectorFamilyToken,
 } from "atom.io"
-import { atom, getInternalRelations, join, selectorFamily } from "atom.io"
+import { getInternalRelations, join, mutableAtom, selectorFamily } from "atom.io"
 import type { SetRTXJson } from "atom.io/transceivers/set-rtx"
 import { SetRTX } from "atom.io/transceivers/set-rtx"
 
 export const usersInThisRoomIndex: MutableAtomToken<
 	SetRTX<string>,
 	SetRTXJson<string>
-> = atom<SetRTX<string>, SetRTXJson<string>>({
+> = mutableAtom<SetRTX<string>, SetRTXJson<string>>({
 	key: `usersInRoomIndex`,
-	mutable: true,
 	default: () => new SetRTX<string>(),
 	toJson: (set) => set.toJSON(),
 	fromJson: (json) => SetRTX.fromJSON(json),
@@ -21,10 +20,9 @@ export const usersInThisRoomIndex: MutableAtomToken<
 export const roomIndex: MutableAtomToken<
 	SetRTX<string>,
 	SetRTXJson<string>
-> = atom<SetRTX<string>, SetRTXJson<string>>({
+> = mutableAtom<SetRTX<string>, SetRTXJson<string>>({
 	key: `roomIndex`,
 	default: () => new SetRTX<string>(),
-	mutable: true,
 	toJson: (set) => set.toJSON(),
 	fromJson: (json) => SetRTX.fromJSON(json),
 })

package/src/realtime-server/realtime-server-stores/server-user-store.ts

@@ -4,7 +4,7 @@ import type {
 	MutableAtomToken,
 	RegularAtomFamilyToken,
 } from "atom.io"
-import { atom, atomFamily, join } from "atom.io"
+import { atomFamily, join, mutableAtom } from "atom.io"
 import type { SetRTXJson } from "atom.io/transceivers/set-rtx"
 import { SetRTX } from "atom.io/transceivers/set-rtx"
 
@@ -32,9 +32,8 @@ export const socketAtoms: RegularAtomFamilyToken<Socket | null, SocketKey> =
 export const socketIndex: MutableAtomToken<
 	SetRTX<SocketKey>,
 	SetRTXJson<SocketKey>
-> = atom<SetRTX<SocketKey>, SetRTXJson<SocketKey>>({
+> = mutableAtom<SetRTX<SocketKey>, SetRTXJson<SocketKey>>({
 	key: `socketsIndex`,
-	mutable: true,
 	default: () => new SetRTX(),
 	toJson: (set) => set.toJSON(),
 	fromJson: (json) => SetRTX.fromJSON(json),
@@ -42,9 +41,8 @@ export const socketIndex: MutableAtomToken<
 export const userIndex: MutableAtomToken<
 	SetRTX<UserKey>,
 	SetRTXJson<UserKey>
-> = atom<SetRTX<UserKey>, SetRTXJson<UserKey>>({
+> = mutableAtom<SetRTX<UserKey>, SetRTXJson<UserKey>>({
 	key: `usersIndex`,
-	mutable: true,
 	default: () => new SetRTX(),
 	toJson: (set) => set.toJSON(),
 	fromJson: (json) => SetRTX.fromJSON(json),

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

@@ -1,39 +0,0 @@
-import type {
-	AtomToken,
-	MutableAtomOptions,
-	MutableAtomToken,
-	RegularAtomOptions,
-	RegularAtomToken,
-} from "atom.io"
-import type { Json } from "atom.io/json"
-
-import type { Transceiver } from "../mutable"
-import { createMutableAtom } from "../mutable"
-import type { Store } from "../store"
-import { createRegularAtom } from "./create-regular-atom"
-
-export function createStandaloneAtom<T>(
-	store: Store,
-	options: RegularAtomOptions<T>,
-): RegularAtomToken<T>
-
-export function createStandaloneAtom<
-	T extends Transceiver<any>,
-	J extends Json.Serializable,
->(store: Store, options: MutableAtomOptions<T, J>): MutableAtomToken<T, J>
-
-export function createStandaloneAtom<T>(
-	store: Store,
-	options: MutableAtomOptions<any, any> | RegularAtomOptions<T>,
-): AtomToken<T> {
-	const isMutable = `mutable` in options
-
-	if (isMutable) {
-		const state = createMutableAtom(store, options, undefined)
-		store.on.atomCreation.next(state)
-		return state
-	}
-	const state = createRegularAtom(store, options, undefined)
-	store.on.atomCreation.next(state)
-	return state
-}

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

@@ -1,38 +0,0 @@
-import type {
-	AtomFamilyToken,
-	MutableAtomFamilyOptions,
-	MutableAtomFamilyToken,
-	RegularAtomFamilyOptions,
-	RegularAtomFamilyToken,
-} from "atom.io"
-import type { Canonical, Json } from "atom.io/json"
-
-import { createMutableAtomFamily, type Transceiver } from "../mutable"
-import type { Store } from "../store"
-import { createRegularAtomFamily } from "./create-regular-atom-family"
-
-export function createAtomFamily<
-	T extends Transceiver<any>,
-	J extends Json.Serializable,
-	K extends Canonical,
->(
-	store: Store,
-	options: MutableAtomFamilyOptions<T, J, K>,
-): MutableAtomFamilyToken<T, J, K>
-export function createAtomFamily<T, K extends Canonical>(
-	store: Store,
-	options: RegularAtomFamilyOptions<T, K>,
-): RegularAtomFamilyToken<T, K>
-export function createAtomFamily<T, K extends Canonical>(
-	store: Store,
-	options:
-		| MutableAtomFamilyOptions<any, any, any>
-		| RegularAtomFamilyOptions<T, K>,
-): AtomFamilyToken<any, any> {
-	const isMutable = `mutable` in options
-
-	if (isMutable) {
-		return createMutableAtomFamily(store, options)
-	}
-	return createRegularAtomFamily<T, K>(store, options)
-}