@atom.io/template-react-node-backend 0.0.103 → 0.0.104

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # @atom.io/template-react-node-backend
 
+## 0.0.104
+
+### Patch Changes
+
+- 4b4c19a: Document and demonstrate synchronous atom effects with direct state writes as the place to normalize accepted remote responses, keeping hydration behind stale-result protection. Update loader, refresh, mutation, and local-index guidance; explain shared-record revisions and how to avoid extra requests. Move the React/Node template's todo hydration into an effect and add an explicit response refresh action.
+- Updated dependencies [4b4c19a]
+- Updated dependencies [90f634c]
+- Updated dependencies [5f84875]
+- Updated dependencies [b166670]
+- Updated dependencies [ffbb22d]
+- Updated dependencies [06c8a0c]
+- Updated dependencies [90f634c]
+- Updated dependencies [4349006]
+- Updated dependencies [90f634c]
+- Updated dependencies [8b43951]
+- Updated dependencies [ccefaca]
+  - atom.io@0.54.6
+  - @atom.io/react@0.2.1
+
 ## 0.0.103
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atom.io/template-react-node-backend",
-  "version": "0.0.103",
+  "version": "0.0.104",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/jeremybanka/atom.io.git",
@@ -9,17 +9,17 @@
   "license": "Apache-2.0",
   "type": "module",
   "dependencies": {
-    "@atom.io/react": "0.2.0",
-    "atom.io": "0.54.5",
+    "@atom.io/react": "0.2.1",
+    "atom.io": "0.54.6",
     "react": "19.3.1",
     "react-dom": "19.3.1",
     "zod": "4.6.7"
   },
   "devDependencies": {
-    "@atom.io/eslint-plugin": "0.1.1",
-    "@dprint/json": "0.25.2",
-    "@dprint/markdown": "0.28.2",
-    "@dprint/oxc": "0.49.0",
+    "@atom.io/eslint-plugin": "0.1.2",
+    "@dprint/json": "0.26.0",
+    "@dprint/markdown": "0.29.0",
+    "@dprint/oxc": "0.49.1",
     "@eslint-react/eslint-plugin": "5.28.8",
     "@types/node": "26.6.6",
     "@types/react": "19.3.0",
@@ -34,11 +34,11 @@
     "eslint-plugin-react-refresh": "0.5.7",
     "globals": "17.14.0",
     "oxc-transform-react": "0.157.0",
-    "oxlint": "1.91.0",
-    "oxlint-tsgolint": "7.0.2005",
+    "oxlint": "1.92.0",
+    "oxlint-tsgolint": "7.0.2006",
     "typescript": "npm:@typescript/typescript6@6.0.2",
     "typescript-eslint": "8.72.1",
-    "vite": "8.3.5"
+    "vite": "8.3.6"
   },
   "publishConfig": {
     "access": "public"

package/src/App.tsx

@@ -21,32 +21,37 @@ const todoSchema = z.object({
 })
 type Todo = z.infer<typeof todoSchema>
 
-/**
- * This atom tells us what todos exist.
- *
- * `Loadable` means that the value of this atom may be a `Promise` sometimes.
- *
- * `useLoadable` from `"@atom.io/react"` makes this easy to use in components.
- */
-const todoKeysAtom = atom<Loadable<number[]>, Error>({
+/** Local membership also supports optimistic additions and deletions. */
+const todoKeysAtom = atom<number[]>({
 	key: `todoKeys`,
+	default: [],
+})
+
+/** Fetch a full response; normalize only after this loadable accepts it. */
+const todoListAtom = atom<Loadable<Todo[]>, Error>({
+	key: `todoList`,
 	default: async () => {
 		const url = new URL(`/todos`, SERVER_URL)
 		const response = await fetch(url, { credentials: `include` })
 		if (!response.ok) throw new Error(response.status.toString())
 		const json = await response.json()
-		const todos = todoSchema.array().parse(json)
-
-		/*
-			🚀	Performance hack!
-					We can make our client less chatty by pre-populating our todo atoms.
-					Comment out this line and watch the network tab to see the difference.
-		*/
-		for (const todo of todos) setState(todoAtoms, todo.id, todo)
-
-		return todos.map((todo) => todo.id)
+		return todoSchema.array().parse(json)
 	},
 	catch: [Error],
+	effects: [
+		({ onSet }) => {
+			onSet(({ newValue }) => {
+				if (newValue instanceof Promise || Error.isError(newValue)) return
+				// Synchronous hydration reuses the list records without per-todo GETs.
+				// Superseded responses never reach this resolved-value callback.
+				for (const todo of newValue) setState(todoAtoms, todo.id, todo)
+				setState(
+					todoKeysAtom,
+					newValue.map((todo) => todo.id),
+				)
+			})
+		},
+	],
 })
 
 /**
@@ -79,8 +84,9 @@ const todosStatsSelector = selector<
 >({
 	key: `todosStats`,
 	get: async ({ get }) => {
-		const todoKeys = await get(todoKeysAtom)
-		if (Error.isError(todoKeys)) return { total: 0, done: 0 }
+		const response = await get(todoListAtom)
+		if (Error.isError(response)) return { total: 0, done: 0 }
+		const todoKeys = get(todoKeysAtom)
 		const total = todoKeys.length
 		const todos = await Promise.all(todoKeys.map((id) => get(todoAtoms, id)))
 		const done = todos.filter((todo) => !Error.isError(todo) && todo.done).length
@@ -94,11 +100,7 @@ async function addTodo() {
 	const url = new URL(`todos`, SERVER_URL)
 	const tempId = Math.random()
 	setState(todoAtoms, tempId, { id: tempId, text, done: 0 })
-	setState(todoKeysAtom, async (loadable) => {
-		const prev = await loadable
-		if (Error.isError(prev)) return prev
-		return [...prev, tempId]
-	})
+	setState(todoKeysAtom, (prev) => [...prev, tempId])
 	const res = await fetch(url, {
 		method: `POST`,
 		credentials: `include`,
@@ -108,23 +110,16 @@ async function addTodo() {
 	const todo = await res.json()
 	const realId = todo.id
 	setState(todoAtoms, realId, todo)
-	setState(todoKeysAtom, async (loadable) => {
-		const prev = await loadable
-		if (Error.isError(prev)) return prev
-		return prev.map((id) => (id === tempId ? realId : id))
-	})
+	setState(todoKeysAtom, (prev) =>
+		prev.map((id) => (id === tempId ? realId : id)),
+	)
 }
 
 async function deleteTodo(todoKey: number) {
-	const todoKeys = await getState(todoKeysAtom)
-	if (Error.isError(todoKeys)) return
+	const todoKeys = getState(todoKeysAtom)
 	const todoToDelete = todoKeys.find((key) => key === todoKey)
 	if (todoToDelete === undefined) return
-	setState(todoKeysAtom, async (loadable) => {
-		const prev = await loadable
-		if (Error.isError(prev)) return prev
-		return prev.filter((id) => id !== todoToDelete)
-	})
+	setState(todoKeysAtom, (prev) => prev.filter((id) => id !== todoToDelete))
 	disposeState(todoAtoms, todoToDelete)
 	const url = new URL(`/todos`, SERVER_URL)
 	url.searchParams.set(`id`, todoToDelete.toString())
@@ -155,11 +150,14 @@ const SKELETON_KEYS = Array.from({ length: 5 }).map(Math.random)
 for (const KEY of SKELETON_KEYS) setState(todoAtoms, KEY, TODO_FALLBACK)
 
 export function App(): React.JSX.Element {
-	const todoKeys = useLoadable(todoKeysAtom, SKELETON_KEYS)
+	const todoList = useLoadable(todoListAtom, [])
+	const todoKeys = useO(todoKeysAtom)
+	const visibleKeys =
+		todoList.loading && todoKeys.length === 0 ? SKELETON_KEYS : todoKeys
 	const stats = useLoadable(todosStatsSelector, { total: 0, done: 0 })
 	return (
 		<>
-			{todoKeys.error ? (
+			{todoList.error ? (
 				<article className="takeover">
 					<main className="card">
 						<h1>Signed Out</h1>
@@ -177,9 +175,9 @@ export function App(): React.JSX.Element {
 			<header>
 				<LongLoadTimes />
 				<span className="spacer" />
-				{todoKeys.error ? (
+				{todoList.error ? (
 					<div className="pfp signed-out" />
-				) : todoKeys.loading ? (
+				) : todoList.loading ? (
 					<div className="pfp loading" />
 				) : (
 					<>
@@ -198,12 +196,20 @@ export function App(): React.JSX.Element {
 			<main>
 				<header>
 					<h1>todo list</h1>
+					<button
+						type="button"
+						onClick={() => {
+							resetState(todoListAtom)
+						}}
+					>
+						Refresh
+					</button>
 					<span>
 						{stats.value.done}/{stats.value.total} items done
 					</span>
 				</header>
 				<main>
-					{todoKeys.value.map((todoKey) => (
+					{visibleKeys.map((todoKey) => (
 						<Todo key={todoKey} todoKey={todoKey} />
 					))}
 					<NewTodo />