atom.io 0.31.0 → 0.32.0

package/realtime-testing/dist/index.js

@@ -1,15 +1,13 @@
+import { RealtimeProvider } from '../../dist/chunk-354XQWHH.js';
+import { myUsernameState } from '../../dist/chunk-Z2UJW4NQ.js';
+import { socketAtoms, usersOfSockets, userIndex, socketIndex, roomSelectors } from '../../dist/chunk-R3ZUK5EH.js';
+import { roomIndex } from '../../dist/chunk-NF7FJKJD.js';
+import '../../dist/chunk-4LWKCEW3.js';
+import { StoreProvider } from '../../dist/chunk-5F2V7S3B.js';
+import { Silo, IMPLICIT, Realm, findInStore, setIntoStore, editRelationsInStore, toEntries, findRelationsInStore, getFromStore, AtomIOLogger, clearStore } from '../../dist/chunk-GY2XQYZY.js';
 import '../../dist/chunk-XWL6SNVU.js';
 import * as http from 'node:http';
 import { render, prettyDOM } from '@testing-library/react';
-import * as AtomIO from 'atom.io';
-import { editRelationsInStore, findRelationsInStore } from 'atom.io/data';
-import { IMPLICIT, findInStore, setIntoStore, getFromStore, clearStore } from 'atom.io/internal';
-import { toEntries } from 'atom.io/json';
-import * as AR from 'atom.io/react';
-import * as RT from 'atom.io/realtime';
-import * as RTC from 'atom.io/realtime-client';
-import * as RTR from 'atom.io/realtime-react';
-import * as RTS from 'atom.io/realtime-server';
 import * as Happy from 'happy-dom';
 import * as SocketIO from 'socket.io';
 import { io } from 'socket.io-client';
@@ -17,7 +15,7 @@ import { jsx } from 'react/jsx-runtime';
 
 var testNumber = 0;
 function prefixLogger(store, prefix) {
-  store.loggers[0] = new AtomIO.AtomIOLogger(`info`, undefined, {
+  store.loggers[0] = new AtomIOLogger(`info`, undefined, {
     info: (...args) => {
       console.info(prefix, ...args);
     },
@@ -31,14 +29,14 @@ function prefixLogger(store, prefix) {
 }
 var setupRealtimeTestServer = (options) => {
   ++testNumber;
-  const silo = new AtomIO.Silo(
+  const silo = new Silo(
     {
       name: `SERVER-${testNumber}`,
       lifespan: options.immortal?.server ? `immortal` : `ephemeral`
     },
     IMPLICIT.STORE
   );
-  const socketRealm = new AtomIO.Realm(silo.store);
+  const socketRealm = new Realm(silo.store);
   const httpServer = http.createServer((_, res) => res.end(`Hello World!`));
   const address = httpServer.listen(options.port).address();
   const port = typeof address === `string` ? null : address === null ? null : address.port;
@@ -48,22 +46,21 @@ var setupRealtimeTestServer = (options) => {
     if (token === `test` && socket.id) {
       const userClaim = socketRealm.allocate(`root`, `user::${username}`);
       const socketClaim = socketRealm.allocate(`root`, `socket::${socket.id}`);
-      const socketState = findInStore(silo.store, RTS.socketAtoms, socketClaim);
+      const socketState = findInStore(silo.store, socketAtoms, socketClaim);
       setIntoStore(silo.store, socketState, socket);
       editRelationsInStore(
-        RTS.usersOfSockets,
+        usersOfSockets,
         (relations) => {
           relations.set(userClaim, socketClaim);
         },
         silo.store
       );
-      setIntoStore(silo.store, RTS.userIndex, (index) => index.add(userClaim));
+      setIntoStore(silo.store, userIndex, (index) => index.add(userClaim));
       setIntoStore(
         silo.store,
-        RTS.socketIndex,
+        socketIndex,
         (index) => index.add(socketClaim)
       );
-      console.log(`${username} connected on ${socket.id}`);
       next();
     } else {
       next(new Error(`Authentication error`));
@@ -73,7 +70,7 @@ var setupRealtimeTestServer = (options) => {
     let userKey = null;
     function enableLogging() {
       const userKeyState = findRelationsInStore(
-        RTS.usersOfSockets,
+        usersOfSockets,
         `socket::${socket.id}`,
         silo.store
       ).userKeyOfSocket;
@@ -85,17 +82,17 @@ var setupRealtimeTestServer = (options) => {
       socket.onAnyOutgoing((event, ...args) => {
         console.log(`\u{1F6F0}  >>`, userKey, event, ...args);
       });
+      socket.on(`disconnect`, () => {
+        console.log(`${userKey} disconnected`);
+      });
     }
     options.server({ socket, enableLogging, silo });
-    socket.on(`disconnect`, () => {
-      console.log(`${userKey} disconnected`);
-    });
   });
   const dispose = async () => {
     await server.close();
-    const roomKeys = getFromStore(silo.store, RT.roomIndex);
+    const roomKeys = getFromStore(silo.store, roomIndex);
     for (const roomKey of roomKeys) {
-      const roomState = findInStore(silo.store, RTS.roomSelectors, roomKey);
+      const roomState = findInStore(silo.store, roomSelectors, roomKey);
       const room = getFromStore(silo.store, roomState);
       if (room && !(room instanceof Promise)) {
         room.process.kill();
@@ -117,17 +114,17 @@ var setupRealtimeTestClient = (options, name, port) => {
     const socket = io(`http://localhost:${port}/`, {
       auth: { token: `test`, username: `${name}-${testNumber}` }
     });
-    const silo = new AtomIO.Silo({ name, lifespan: `ephemeral` }, IMPLICIT.STORE);
+    const silo = new Silo({ name, lifespan: `ephemeral` }, IMPLICIT.STORE);
     for (const [key, value] of silo.store.valueMap.entries()) {
       if (Array.isArray(value)) {
         silo.store.valueMap.set(key, [...value]);
       }
     }
-    silo.setState(RTC.myUsernameState, `${name}-${testNumber}`);
+    silo.setState(myUsernameState, `${name}-${testNumber}`);
     const { document } = new Happy.Window();
     document.body.innerHTML = `<div id="app"></div>`;
     const renderResult = render(
-      /* @__PURE__ */ jsx(AR.StoreProvider, { store: silo.store, children: /* @__PURE__ */ jsx(RTR.RealtimeProvider, { socket, children: /* @__PURE__ */ jsx(options.client, {}) }) }),
+      /* @__PURE__ */ jsx(StoreProvider, { store: silo.store, children: /* @__PURE__ */ jsx(RealtimeProvider, { socket, children: /* @__PURE__ */ jsx(options.client, {}) }) }),
       {
         container: document.querySelector(`#app`)
       }

package/realtime-testing/src/setup-realtime-test.tsx

@@ -3,11 +3,12 @@ import * as http from "node:http"
 import type { RenderResult } from "@testing-library/react"
 import { prettyDOM, render } from "@testing-library/react"
 import * as AtomIO from "atom.io"
-import { editRelationsInStore, findRelationsInStore } from "atom.io/data"
 import type { Store } from "atom.io/internal"
 import {
 	clearStore,
+	editRelationsInStore,
 	findInStore,
+	findRelationsInStore,
 	getFromStore,
 	IMPLICIT,
 	setIntoStore,
@@ -130,7 +131,7 @@ export const setupRealtimeTestServer = (
 			setIntoStore(silo.store, RTS.socketIndex, (index) =>
 				index.add(socketClaim),
 			)
-			console.log(`${username} connected on ${socket.id}`)
+			// console.log(`${username} connected on ${socket.id}`)
 			next()
 		} else {
 			next(new Error(`Authentication error`))
@@ -153,11 +154,11 @@ export const setupRealtimeTestServer = (
 			socket.onAnyOutgoing((event, ...args) => {
 				console.log(`🛰  >>`, userKey, event, ...args)
 			})
+			socket.on(`disconnect`, () => {
+				console.log(`${userKey} disconnected`)
+			})
 		}
 		options.server({ socket, enableLogging, silo })
-		socket.on(`disconnect`, () => {
-			console.log(`${userKey} disconnected`)
-		})
 	})
 
 	const dispose = async () => {

package/src/atom.ts

@@ -6,59 +6,83 @@ import {
 } from "atom.io/internal"
 import type { Canonical, Json, JsonInterface } from "atom.io/json"
 
-import type { AtomToken, MutableAtomToken, RegularAtomToken } from "."
-
-export type Effectors<T> = {
-	setSelf: <V extends T>(next: V | ((oldValue: T) => V)) => void
-	onSet: (callback: (options: { newValue: T; oldValue: T }) => void) => void
-}
-
-export type AtomEffect<T> = (tools: Effectors<T>) => (() => void) | void
-
-export type RegularAtomOptions<T> = {
-	key: string
-	default: T | (() => T)
-	effects?: AtomEffect<T>[]
-}
-// biome-ignore format: complex intersection
-export type MutableAtomOptions<T extends Transceiver<any>, J extends Json.Serializable> = 
-	& JsonInterface<T, J>
-	& Omit<RegularAtomOptions<T>, `default`> 
-	& { 
-			default: ()	=> T
-			mutable: true
-		}
+import type { AtomToken, MutableAtomToken, RegularAtomToken, Setter } from "."
 
 /**
  * @public
- * Declare a mutable global reactive variable.
- * @param options - Configuration for this mutable atom.
+ * 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}.
+ *
+ * @param options - {@link MutableAtomOptions}.
  * @returns
- * The token for your mutable atom.
+ * 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>
+
 /**
  * @public
- * Declare a regular global reactive variable.
- * @param options - Configuration for this regular atom.
+ * Create a regular atom, a global reactive variable in the implicit store
+ * @param options - {@link RegularAtomOptions}.
  * @returns
- * The token for your regular atom.
+ * A reference to the atom created: a {@link RegularAtomToken}
  * @overload Regular
  */
 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 Effectors<T> = {
+	/**
+	 * Set the value of the atom
+	 * @param next - The new value of the atom, or a setter function
+	 */
+	setSelf: <New extends T>(next: New | Setter<T, New>) => void
+	/** Subscribe to changes to the atom */
+	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>[]
+}
+// biome-ignore format: complex intersection
+export type MutableAtomOptions<T extends Transceiver<any>, J extends Json.Serializable> = 
+	& JsonInterface<T, J>
+	& Omit<RegularAtomOptions<T>, `default`> 
+	& { 
+			default: ()	=> T
+			mutable: true
+		}
+
+/** @public */
 export type RegularAtomFamilyOptions<T, K extends Canonical> = {
+	/** The unique identifier of the atom family */
 	key: string
+	/** The starting value of the atom family */
 	default: T | ((key: K) => T)
+	/** Hooks used to run side effects when an atom in the family is set  */
 	effects?: (key: K) => AtomEffect<T>[]
 }
 

package/src/dispose-state.ts

@@ -3,13 +3,23 @@ import type { Canonical } from "atom.io/json"
 
 import type { ReadableFamilyToken, ReadableToken } from "."
 
+/**
+ * @public
+ * Disposes of a state in the implicit store
+ * @param token - The token of the state to dispose
+ * @overload Default
+ */
 export function disposeState(token: ReadableToken<any>): void
-
+/**
+ * @public
+ * Disposes of a state family in the implicit store
+ * @param token - The token of the state family to dispose
+ * @param key - The unique key of the state to dispose
+ */
 export function disposeState<K extends Canonical>(
 	token: ReadableFamilyToken<any, K>,
 	key: K,
 ): void
-
 export function disposeState(
 	...[token, key]:
 		| [token: ReadableFamilyToken<any, any>, key: Canonical]

package/{ephemeral/src → src}/find-state.ts

@@ -17,12 +17,13 @@ import { findInStore, IMPLICIT } from "atom.io/internal"
 import type { Canonical, Json } from "atom.io/json"
 
 /**
- * @overload Mutable Atom
- * Finds a {@link MutableAtomToken} in the store.
- * @param token - A {@link MutableAtomFamilyToken}.
- * @param key - The key of the state.
+ * @public
+ * Finds a {@link MutableAtomToken} in the store
+ * @param token - A {@link MutableAtomFamilyToken}
+ * @param key - The key of the state
  * @returns
- * The current value of the state.
+ * The current value of the state
+ * @overload Mutable Atom
  */
 export function findState<
 	T extends Transceiver<any>,
@@ -31,44 +32,52 @@ export function findState<
 	Key extends K,
 >(token: MutableAtomFamilyToken<T, J, K>, key: Key): MutableAtomToken<T, J, K>
 /**
- * Finds a state in the store.
- * @param token - The token of the state family.
- * @param key - The key of the state.
+ * @public
+ * Finds a state in the store
+ * @param token - The token of the state family
+ * @param key - The key of the state
  * @returns
- * The current value of the state.
+ * The current value of the state
+ * @overload Regular Atom
  */
 export function findState<T, K extends Canonical, Key extends K>(
 	token: RegularAtomFamilyToken<T, K>,
 	key: Key,
 ): RegularAtomToken<T, K>
 /**
- * Finds a state in the store.
- * @param token - The token of the state family.
- * @param key - The key of the state.
+ * @public
+ * Finds a state in the store
+ * @param token - The token of the state family
+ * @param key - The key of the state
  * @returns
- * The current value of the state.
+ * The current value of the state
+ * @overload Writable Selector
  */
 export function findState<T, K extends Canonical, Key extends K>(
 	token: WritableSelectorFamilyToken<T, K>,
 	key: Key,
 ): WritableSelectorToken<T, K>
 /**
- * Finds a state in the store.
- * @param token - The token of the state family.
- * @param key - The key of the state.
+ * @public
+ * Finds a state in the store
+ * @param token - The token of the state family
+ * @param key - The key of the state
  * @returns
- * The current value of the state.
+ * The current value of the state
+ * @overload Readonly Selector
  */
 export function findState<T, K extends Canonical, Key extends K>(
 	token: ReadonlySelectorFamilyToken<T, K>,
 	key: Key,
 ): ReadonlySelectorToken<T, K>
 /**
- * Finds a state in the store.
- * @param token - The token of the state family.
- * @param key - The key of the state.
+ * @public
+ * Finds a state in the store
+ * @param token - The token of the state family
+ * @param key - The key of the state
  * @returns
- * The current value of the state.
+ * The current value of the state
+ * @overload Writable State
  */
 export function findState<T, K extends Canonical, Key extends K>(
 	token: WritableFamilyToken<T, K>,
@@ -76,12 +85,13 @@ export function findState<T, K extends Canonical, Key extends K>(
 ): WritableToken<T, K>
 /**
  * @public
- * Finds a {@link ReadableToken} in the store.
- * @param token - A {@link ReadableFamilyToken}.
- * @param key - The key of the state.
+ * Finds a {@link ReadableToken} in the store
+ * @param token - A {@link ReadableFamilyToken}
+ * @param key - The key of the state
  * @returns
- * The current value of the state.
+ * The current value of the state
  * @overload Unknown
+ * @default
  */
 export function findState<T, K extends Canonical, Key extends K>(
 	token: ReadableFamilyToken<T, K>,

package/src/get-state.ts

@@ -3,8 +3,24 @@ import type { Canonical } from "atom.io/json"
 
 import type { ReadableFamilyToken, ReadableToken } from "."
 
+/**
+ * @public
+ * Get the current value of a state
+ * @param token - The token of the state to get
+ * @return The current value of the state
+ * @overload Default
+ * @default
+ */
 export function getState<T>(token: ReadableToken<T>): T
 
+/**
+ * @public
+ * Get the current value of a state family
+ * @param token - The token of a state family
+ * @param key - The unique key of the state to get
+ * @return The current value of the state
+ * @overload Streamlined
+ */
 export function getState<T, K extends Canonical, Key extends K>(
 	token: ReadableFamilyToken<T, K>,
 	key: Key,

package/src/index.ts

@@ -1,18 +1,27 @@
 import type { Transceiver } from "atom.io/internal"
 import type { Canonical, Json, stringified } from "atom.io/json"
 
-import type { AtomFamilyToken } from "./atom"
+import type { atom, AtomFamilyToken } from "./atom"
+import type { getState } from "./get-state"
 import type {
 	SelectorFamilyToken,
 	WritableSelectorFamilyToken,
 } from "./selector"
+import type { setState } from "./set-state"
+import type { TimelineToken } from "./timeline"
+import type {
+	runTransaction,
+	transaction,
+	TransactionToken,
+} from "./transaction"
 
-export * from "./allocate"
 export * from "./atom"
 export * from "./dispose-state"
+export * from "./find-state"
 export * from "./get-state"
+export * from "./join"
 export * from "./logger"
-export * from "./molecule"
+export * from "./realm"
 export * from "./selector"
 export * from "./set-state"
 export * from "./silo"
@@ -21,58 +30,123 @@ export * from "./timeline"
 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 WritableSelectorToken<T, K extends Canonical = any> = {
+	/** The unique identifier of the selector. */
 	key: string
+	/** Discriminator. */
 	type: `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 ReadonlySelectorToken<T, K extends Canonical = any> = {
+	/** The unique identifier of the selector. */
 	key: string
+	/** Discriminator. */
 	type: `readonly_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 SelectorToken<T, K extends Canonical = any> =
 	| ReadonlySelectorToken<T, K>
 	| WritableSelectorToken<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>
 }
+
+export type Loadable<T> = Promise<T> | T