@kdeveloper/kvark 0.2.0 → 0.3.0

package/README.md

@@ -39,7 +39,7 @@ import { Provider, useAtomValue, useSetAtom } from "@kdeveloper/kvark/react";
 const userIdAtom = atom({
   debugLabel: "userId",
   get: async () => 1,
-  set: async (_ctx, id: number) => id,
+  set: async (_ctx, _id: number) => {},
 });
 
 const userAtom = atom({
@@ -86,7 +86,7 @@ import { atom } from "@kdeveloper/kvark";
 const countAtom = atom({
   debugLabel: "count",
   get: async () => 0,
-  set: async (_ctx, value: number) => value,
+  set: async (_ctx, _value: number) => {},
 });
 
 // Derived atom — reads from another atom
@@ -100,6 +100,69 @@ const doubleAtom = atom({
 });
 ```
 
+### Writable atoms
+
+An atom is writable when its config includes a `set` function. The return type becomes `WritableAtom<Value, Args>`, where `Args` is the tuple of arguments the setter accepts.
+
+```ts
+const profileAtom = atom({
+  debugLabel: "profile",
+  get: async () => {
+    const res = await fetch("/api/profile");
+    return res.json() as Promise<Profile>;
+  },
+  set: async (ctx, patch: Partial<Profile>) => {
+    await fetch("/api/profile", {
+      method: "PATCH",
+      body: JSON.stringify(patch),
+      signal: ctx.signal,
+    });
+  },
+});
+```
+
+**Lifecycle after `set`:** the store calls `config.set(ctx, ...args)`, waits for the returned promise, then calls `invalidate` on the atom. This marks it `stale` and triggers a background refetch via `get` — the same stale-while-revalidate flow described [above](#stale-while-revalidate).
+
+The `ctx` passed to `set` provides:
+
+- **`ctx.get(key)`** — read any declared dependency (same as in `get`).
+- **`ctx.signal`** — an `AbortSignal` tied to the atom's lifecycle, useful for cancelling in-flight requests.
+- **`ctx.setOptimisticValue(value)`** — synchronously update the atom's cached value before the async work completes (see below).
+
+#### Optimistic updates
+
+Call `ctx.setOptimisticValue(value)` inside `set` to immediately reflect the new value in the UI while the mutation runs in the background. If the mutation throws (or the signal aborts), the store automatically rolls back to the state captured before the first `setOptimisticValue` call. Derived atoms that depend on this atom are marked `stale` so they re-render too.
+
+```ts
+const todoAtom = atom({
+  debugLabel: "todo",
+  get: async () => {
+    const res = await fetch("/api/todo");
+    return res.json() as Promise<Todo>;
+  },
+  set: async (ctx, title: string) => {
+    ctx.setOptimisticValue({ title, done: false });
+    await fetch("/api/todo", {
+      method: "PUT",
+      body: JSON.stringify({ title }),
+      signal: ctx.signal,
+    });
+  },
+});
+```
+
+If the `PUT` fails, the atom reverts to whatever value `get` had loaded before the optimistic update — no manual rollback needed.
+
+#### Writable atoms vs `onMount`
+
+Both can update an atom's cached value, but they serve different purposes:
+
+| | `set` | `onMount` |
+|-|-------|-----------|
+| **Triggered by** | Explicit call (`store.set`, `useSetAtom`) | First subscriber mounts |
+| **After update** | `invalidate` → refetch via `get` | No refetch — value stays as-is |
+| **Use case** | Mutations, API calls, optimistic updates | Timers, subscriptions, imperative push |
+
 ### `onMount`
 
 Optional lifecycle hook that runs when the atom **first gains a subscriber** in a store (for example when a React component using `useAtomValue` mounts). It receives a synchronous `set(value)` that marks the atom `fresh` and notifies listeners — useful for timers, subscriptions, or imperative updates that should not go through `get`.
@@ -320,7 +383,7 @@ export function App() {
 ## Utility Types
 
 ```ts
-import type { AtomValue, AtomArgs, IsWritable } from "@kdeveloper/kvark";
+import type { AtomValue, AtomArgs, IsWritable, WritableAtomContext } from "@kdeveloper/kvark";
 
 type UserData = AtomValue<typeof userAtom>; // → User
 type PostArgs = AtomArgs<typeof postAtom>; // → [postId: number]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kdeveloper/kvark",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Atomic state management with explicit dependency graphs",
   "license": "MIT",
   "files": [