@kdeveloper/kvark 0.17.0 → 1.0.0

package/README.md

@@ -11,12 +11,12 @@ Inspired by Jotai, but built around a key difference: dependencies are declared
 |                        | Jotai                            | Kvark                                           |
 | ---------------------- | -------------------------------- | ----------------------------------------------- |
 | Dependency declaration | Implicit (via `get(atom)` calls) | Explicit, via `dependencies` field              |
-| `atom()` signature     | `atom(read, write?)`             | `atom({ get, set?, dependencies? })`            |
-| Async model            | Optional                         | `get`, `set`, `ctx.get` — always `async`        |
+| `atom()` signature     | `atom(read, write?)`             | `atom({ read, write?, dependencies? })`         |
+| Async model            | Optional                         | `read`, `write`, `ctx.read` — always `async`    |
 | Parallel loading       | Manual `Promise.all`             | Built-in through `dependencies`                 |
 | Stale-while-revalidate | Re-suspends on revalidation      | Shows stale data; Suspense only on first load   |
 | `atomFamily`           | External (`jotai/utils`)         | Core, with LRU and invalidation                 |
-| External invalidation  | `store.set()`                    | Explicit `store.invalidate()` / `StoreClient`   |
+| External invalidation  | Manual via store mutation APIs   | Explicit `store.invalidate()` / `StoreClient`   |
 | TypeScript strictness  | `strict: true` recommended       | `strict: true` + 8 extra flags, `any` forbidden |
 
 ## Installation
@@ -30,20 +30,20 @@ pnpm add @kdeveloper/kvark
 
 ```tsx
 import { atom, createStore } from "@kdeveloper/kvark";
-import { Provider, useAtomValue, useSetAtom } from "@kdeveloper/kvark/react";
+import { Provider, useApplyAtom, useAtomValue } from "@kdeveloper/kvark/react";
 
 // 1. Create atoms
 const userIdAtom = atom({
   debugLabel: "userId",
-  get: async () => 1,
-  set: async (_ctx, _id: number) => {},
+  read: async () => 1,
+  write: async (_ctx, _id: number) => {},
 });
 
 const userAtom = atom({
   debugLabel: "user",
   dependencies: { userId: userIdAtom },
-  get: async (ctx) => {
-    const id = await ctx.get("userId");
+  read: async (ctx) => {
+    const id = await ctx.read("userId");
     const res = await fetch(`/api/users/${id}`, { signal: ctx.signal });
     return res.json();
   },
@@ -75,14 +75,14 @@ function UserCard() {
 The same atoms and store work with `@kdeveloper/kvark/preact` — the API is identical to the React integration. Replace the React import with the Preact one:
 
 ```tsx
-import { Provider, useAtomValue, useSetAtom } from "@kdeveloper/kvark/preact";
+import { Provider, useApplyAtom, useAtomValue } from "@kdeveloper/kvark/preact";
 ```
 
 Hooks use only `preact` and `preact/hooks` internally — no `preact/compat` aliases required.
 
 ### Vue 3
 
-The same atoms and store work with `@kdeveloper/kvark/vue`. Composables mirror the React hooks; `useAtomValue` returns an **awaitable** [`shallowRef`](https://vuejs.org/api/reactivity-advanced.html#shallowref) — use `.value` in `<script setup>` (templates unwrap refs automatically). Until the first `get` resolves, that ref’s value is `undefined`; TypeScript types it as `V | undefined` (`ThenableShallowRef<V>`). After `await useAtomValue(atom)` you get `Readonly<ShallowRef<V>>` with a defined `.value`. The ref also implements `PromiseLike`, so awaiting it in an async `setup` suspends until the first `get` resolves — see [Suspense (Vue 3)](#suspense-vue-3).
+The same atoms and store work with `@kdeveloper/kvark/vue`. Composables mirror the React hooks; `useAtomValue` returns an **awaitable** [`shallowRef`](https://vuejs.org/api/reactivity-advanced.html#shallowref) — use `.value` in `<script setup>` (templates unwrap refs automatically). Until the first `read` resolves, that ref’s value is `undefined`; TypeScript types it as `V | undefined` (`ThenableShallowRef<V>`). After `await useAtomValue(atom)` you get `Readonly<ShallowRef<V>>` with a defined `.value`. The ref also implements `PromiseLike`, so awaiting it in an async `setup` suspends until the first `read` resolves — see [Suspense (Vue 3)](#suspense-vue-3).
 
 Composables must run **inside** a `Provider` subtree. Put `useAtomValue` / `useAtom` in a child component (or a nested route), not in the same component that renders `Provider` without passing the store through a wrapper.
 
@@ -93,15 +93,15 @@ import { atom } from "@kdeveloper/kvark";
 
 export const userIdAtom = atom({
   debugLabel: "userId",
-  get: async () => 1,
-  set: async () => {},
+  read: async () => 1,
+  write: async () => {},
 });
 
 export const userAtom = atom({
   debugLabel: "user",
   dependencies: { userId: userIdAtom },
-  get: async (ctx) => {
-    const id = await ctx.get("userId");
+  read: async (ctx) => {
+    const id = await ctx.read("userId");
     const res = await fetch(`/api/users/${id}`, { signal: ctx.signal });
     return res.json();
   },
@@ -149,7 +149,7 @@ Unlike React, Vue’s `<Suspense>` only activates for **async** child components
 
 ## Store Context
 
-Kvark can inject arbitrary application context into every atom and mutation callback through the store, similar to router context in TanStack Router. The context is immutable for the lifetime of a store and is available in `get`, `set`, `onMount`, `mutation`, `batch.fetch`, and `infinityAtom.queryFn`.
+Kvark can inject arbitrary application context into every atom and mutation callback through the store, similar to router context in TanStack Router. The context is immutable for the lifetime of a store and is available in `read`, `write`, `onMount`, `mutation`, `batch.fetch`, and `infinityAtom.queryFn`.
 
 First, declare the context type once with module augmentation:
 
@@ -186,10 +186,10 @@ import { atom, mutation } from "@kdeveloper/kvark";
 
 const userAtom = atom({
   dependencies: { userId: userIdAtom },
-  get: async (ctx) => {
-    return ctx.global.apiClient.users.get(await ctx.get("userId"));
+  read: async (ctx) => {
+    return ctx.global.apiClient.users.get(await ctx.read("userId"));
   },
-  set: async (ctx, patch: Partial<User>) => {
+  write: async (ctx, patch: Partial<User>) => {
     await ctx.global.apiClient.users.update(ctx.global.currentUser.id, patch);
   },
 });
@@ -224,7 +224,7 @@ Batch families receive it via `input.ctx.global` inside `batch.fetch`.
 
 ### Atoms
 
-An atom is the smallest unit of state. Its `get` function is always `async`, and dependencies must be declared explicitly.
+An atom is the smallest unit of state. Its `read` function is always `async`, and dependencies must be declared explicitly.
 
 ```ts
 import { atom } from "@kdeveloper/kvark";
@@ -232,16 +232,16 @@ import { atom } from "@kdeveloper/kvark";
 // Primitive atom — no dependencies
 const countAtom = atom({
   debugLabel: "count",
-  get: async () => 0,
-  set: async (_ctx, _value: number) => {},
+  read: async () => 0,
+  write: async (_ctx, _value: number) => {},
 });
 
 // Derived atom — reads from another atom
 const doubleAtom = atom({
   debugLabel: "double",
   dependencies: { count: countAtom },
-  get: async (ctx) => {
-    const n = await ctx.get("count");
+  read: async (ctx) => {
+    const n = await ctx.read("count");
     return n * 2;
   },
 });
@@ -249,7 +249,7 @@ const doubleAtom = atom({
 
 #### Simple primitive atom (`atom(initialValue)`)
 
-For purely client-side state — counters, toggles, draft fields — there is a shorthand: pass an initial value directly. The result is a `WritableAtom` whose setter accepts either the next value or an updater function `(prev) => next`. Both `store.set(atom, value)` and `store.write(atom, value)` are supported, and React/Preact/Vue hooks (`useAtomValue`, `useSetAtom`, `useAtom`) work as usual.
+For purely client-side state — counters, toggles, draft fields — there is a shorthand: pass an initial value directly. The result is a `WritableAtom` whose apply function accepts either the next value or an updater function `(prev) => next`. Both `store.apply(atom, value)` and `store.write(atom, value)` are supported: `apply` runs the atom's `write` callback, while `write` pushes straight into the cache. React/Preact/Vue hooks (`useAtomValue`, `useApplyAtom`, `useAtom`) work as usual.
 
 ```ts
 import { atom, createStore } from "@kdeveloper/kvark";
@@ -268,27 +268,27 @@ const clockAtom = atom(Date.now(), {
 
 const store = createStore();
 
-await store.set(counterAtom, 5);
-await store.set(counterAtom, (prev) => prev + 1);
+await store.apply(counterAtom, 5);
+await store.apply(counterAtom, (prev) => prev + 1);
 store.write(counterAtom, 42);
 ```
 
-The shorthand is intentionally limited to `debugLabel` and `onMount`; for `dependencies`, `stalePolicy`, `retry`, or async loading use the full `atom({ get, set?, ... })` form.
+The shorthand is intentionally limited to `debugLabel` and `onMount`; for `dependencies`, `stalePolicy`, `retry`, or async loading use the full `atom({ read, write?, ... })` form.
 
-> Note: if your initial value is itself an object that exposes a `get` method (and would be parsed as an atom config), use the explicit form: `atom({ get: async () => obj, set: async (ctx, next) => ctx.setOptimisticValue(next) })`.
+> Note: if your initial value is itself an object that exposes a `read` method (and would be parsed as an atom config), use the explicit form: `atom({ read: async () => obj, write: async (ctx, next) => ctx.setOptimisticValue(next) })`.
 
 ### 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.
+An atom is writable when its config includes a `write` function. The return type becomes `WritableAtom<Value, Args>`, where `Args` is the tuple of arguments accepted by `store.apply(atom, ...args)` / `useApplyAtom(atom)(...args)`.
 
 ```ts
 const profileAtom = atom({
   debugLabel: "profile",
-  get: async () => {
+  read: async () => {
     const res = await fetch("/api/profile");
     return res.json() as Promise<Profile>;
   },
-  set: async (ctx, patch: Partial<Profile>) => {
+  write: async (ctx, patch: Partial<Profile>) => {
     await fetch("/api/profile", {
       method: "PATCH",
       body: JSON.stringify(patch),
@@ -298,11 +298,11 @@ const profileAtom = atom({
 });
 ```
 
-**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).
+**Lifecycle after `apply`:** the store calls `config.write(ctx, ...args)`, waits for the returned promise, then calls `invalidate` on the atom. This marks it `stale` and triggers a background refetch via `read` — the same stale-while-revalidate flow described [above](#stale-while-revalidate).
 
-The `ctx` passed to `set` provides:
+The `ctx` passed to `write` provides:
 
-- **`ctx.get(key)`** — read any declared dependency (same as in `get`).
+- **`ctx.read(key)`** — read any declared dependency (same as in `read`).
 - **`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). Also accepts a mutator `(prev) => next`.
 - **`ctx.writeOptimistic(atom, value)`** — synchronously write into another atom's cache with automatic rollback on error (see [Dependent mutations](#dependent-mutations)). Also accepts a mutator.
@@ -310,16 +310,16 @@ The `ctx` passed to `set` provides:
 
 #### 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.
+Call `ctx.setOptimisticValue(value)` inside `write` 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 () => {
+  read: async () => {
     const res = await fetch("/api/todo");
     return res.json() as Promise<Todo>;
   },
-  set: async (ctx, title: string) => {
+  write: async (ctx, title: string) => {
     ctx.setOptimisticValue({ title, done: false });
     await fetch("/api/todo", {
       method: "PUT",
@@ -333,17 +333,17 @@ const todoAtom = atom({
 `setOptimisticValue` also accepts a mutator function — the callback receives the previous value (or `undefined` if pending) and returns the next one:
 
 ```ts
-set: async (ctx) => {
+write: async (ctx) => {
   ctx.setOptimisticValue((prev) => ({ ...prev, loading: true }));
   await fetch("/api/update", { signal: ctx.signal });
 },
 ```
 
-If the `PUT` fails, the atom reverts to whatever value `get` had loaded before the optimistic update — no manual rollback needed.
+If the `PUT` fails, the atom reverts to whatever value `read` had loaded before the optimistic update — no manual rollback needed.
 
 #### Dependent mutations
 
-The `ctx` inside `set` also provides methods for cross-atom side-effects:
+The `ctx` inside `write` also provides methods for cross-atom side-effects:
 
 - **`ctx.invalidate(atom)`** — mark another atom as `stale` and schedule a refetch. Does **not** participate in rollback; best called after the async work succeeds.
 - **`ctx.invalidateMany(atoms)`** — same as `invalidate`, but for multiple atoms at once.
@@ -354,7 +354,7 @@ A common pattern is a list atom alongside per-item atoms managed by `atomFamily`
 ```ts
 const todosListAtom = atom({
   debugLabel: "todosList",
-  get: async () => {
+  read: async () => {
     const res = await fetch("/api/todos");
     return res.json() as Promise<Todo[]>;
   },
@@ -362,11 +362,11 @@ const todosListAtom = atom({
 
 const todoAtom = atomFamily({
   debugLabel: "todo",
-  get: (id: number) => async () => {
+  read: (id: number) => async () => {
     const res = await fetch(`/api/todos/${id}`);
     return res.json() as Promise<Todo>;
   },
-  set: (id: number) => async (ctx, patch: Partial<Todo>) => {
+  write: (id: number) => async (ctx, patch: Partial<Todo>) => {
     ctx.setOptimisticValue((prev) => ({ ...prev!, ...patch }));
     ctx.writeOptimistic(todosListAtom, (list) =>
       list?.map((t) => (t.id === id ? { ...t, ...patch } : t)),
@@ -387,20 +387,20 @@ If the `PATCH` fails, both the item and the list revert to their pre-optimistic
 
 Sometimes a server action updates **several** atoms at once, and there is no single writable atom that should own the mutation. Use **`mutation(fn)`** to define that work once, then run it with **`store.mutate(m, ...args)`** or **`useMutation(m)`** in components.
 
-The callback receives a **`MutationContext`** (the same optimistic and invalidation helpers as in `set`, but **without** `setOptimisticValue` or `ctx.signal`). Standalone mutations can read any atom with **`ctx.get(atom)`**. In contrast, inside **`set`**, **`ctx.get(...)`** still means "read a declared dependency by key":
+The callback receives a **`MutationContext`** (the same optimistic and invalidation helpers as in `write`, but **without** `setOptimisticValue` or `ctx.signal`). Standalone mutations can read any atom with **`ctx.read(atom)`**. In contrast, inside **`write`**, **`ctx.read(...)`** still means "read a declared dependency by key":
 
-- **`ctx.get(atom)`** — resolve any atom with the same semantics as `store.get(atom)` / `client.get(atom)`.
-- **`ctx.writeOptimistic(atom, value | mutator)`** — same semantics as inside `set`. On throw, every atom touched by `writeOptimistic` rolls back to its state before the first optimistic write in this run.
+- **`ctx.read(atom)`** — read any atom with the same semantics as `store.read(atom)` / `client.read(atom)`.
+- **`ctx.writeOptimistic(atom, value | mutator)`** — same semantics as inside `write`. On throw, every atom touched by `writeOptimistic` rolls back to its state before the first optimistic write in this run.
 - **`ctx.invalidate` / `ctx.invalidateMany`** — mark atoms stale (not rolled back on error).
 
-Unlike **`set`**, a successful **`mutate` does not invalidate any atom automatically**. Call `ctx.invalidate` / `ctx.invalidateMany` when you want stale-while-revalidate after the request completes.
+Unlike **`write`**, a successful **`mutate` does not invalidate any atom automatically**. Call `ctx.invalidate` / `ctx.invalidateMany` when you want stale-while-revalidate after the request completes.
 
 ```ts
 import { atom, mutation, createStore } from "@kdeveloper/kvark";
 
 const listAtom = atom({
   debugLabel: "list",
-  get: async () => {
+  read: async () => {
     const res = await fetch("/api/items");
     return res.json() as Promise<string[]>;
   },
@@ -408,7 +408,7 @@ const listAtom = atom({
 
 const countAtom = atom({
   debugLabel: "count",
-  get: async () => {
+  read: async () => {
     const res = await fetch("/api/count");
     return (await res.json()) as { n: number };
   },
@@ -452,22 +452,22 @@ const runAddItem = useMutation(addItem);
 
 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 |
+|                  | `write`                                       | `onMount`                              |
+| ---------------- | --------------------------------------------- | -------------------------------------- |
+| **Triggered by** | Explicit call (`store.apply`, `useApplyAtom`) | First subscriber mounts                |
+| **After update** | `invalidate` → refetch via `read`             | 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 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`.
+Optional lifecycle hook that runs when the atom **first gains a subscriber** in a store (for example when a 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 `read`.
 
 You may return a cleanup function; it runs when the **last** subscriber unsubscribes (for example when the last mounted consumer unmounts). If several components subscribe to the same atom, `onMount` runs once and the cleanup runs once after all of them unsubscribe.
 
 ```ts
 const clockAtom = atom({
   debugLabel: "clock",
-  get: async () => new Date().toISOString(),
+  read: async () => new Date().toISOString(),
   onMount: (set) => {
     const id = setInterval(() => {
       set(new Date().toISOString());
@@ -479,13 +479,13 @@ const clockAtom = atom({
 
 ### Parallel loading
 
-Declaring multiple dependencies causes the Store to resolve them in parallel before calling `get`. Inside `get` you control the parallelism explicitly.
+Declaring multiple dependencies causes the Store to start loading them in parallel before calling `read`. Inside `read` you control the parallelism explicitly.
 
 ```ts
 const dashboardAtom = atom({
   dependencies: { user: userAtom, settings: settingsAtom },
-  get: async (ctx) => {
-    const [user, settings] = await Promise.all([ctx.get("user"), ctx.get("settings")]);
+  read: async (ctx) => {
+    const [user, settings] = await Promise.all([ctx.read("user"), ctx.read("settings")]);
     return { user, settings };
   },
 });
@@ -528,13 +528,13 @@ Available `stalePolicy` values:
 
 ### Retry on error
 
-By default a failed `get` immediately sets the atom to `error` state. You can opt into automatic retries with the `retry` and `retryDelay` options:
+By default a failed `read` immediately sets the atom to `error` state. You can opt into automatic retries with the `retry` and `retryDelay` options:
 
 ```ts
 const userAtom = atom({
   retry: 3,
   retryDelay: (attempt) => Math.min(1000 * 2 ** attempt, 30_000),
-  get: async (ctx) => {
+  read: async (ctx) => {
     const res = await fetch("/api/user", { signal: ctx.signal });
     if (!res.ok) throw new Error("Failed to fetch user");
     return res.json();
@@ -553,7 +553,7 @@ The same options are available in `atomFamily` and `infinityAtom`.
 
 ### `atomFamily`
 
-Create a family of atoms parametrised by a key. Atoms are cached by param; supports LRU eviction.
+Create a family of atoms parametrised by a key. Members use `read(param)` and optional `write(param)` callbacks, are cached by param, and support LRU eviction.
 
 ```ts
 import { atomFamily } from "@kdeveloper/kvark/family";
@@ -563,8 +563,8 @@ const postFamily = atomFamily({
   cachePolicy: "lru",
   lruSize: 50,
   dependencies: (_postId: number) => ({ user: userAtom }),
-  get: (postId) => async (ctx) => {
-    const user = await ctx.get("user");
+  read: (postId) => async (ctx) => {
+    const user = await ctx.read("user");
     const res = await fetch(`/api/posts/${postId}?userId=${user.id}`, {
       signal: ctx.signal,
     });
@@ -581,24 +581,32 @@ postFamily.invalidate(42);
 
 // Invalidate everything (e.g. on logout)
 postFamily.invalidateAll();
+
+// Cache helpers
+postFamily.has(42);
+postFamily.peek(42); // Atom<Post> | undefined, does not create a member
+postFamily.remove(42);
+postFamily.clear();
 ```
 
+`atomFamily` and `infinityAtomFamily` expose the same cache helper shape: `has(param)`, `peek(param)`, `remove(param)`, `clear()`, and `getCache()`. `peek`/`has` inspect the current cache without creating a new atom; calling the family itself still creates or touches the member and updates LRU order.
+
 ### `atomFamily` as a dependency
 
-A `dependencies` entry can be either a regular `Atom` or an `atomFamily`. When the entry is a family, supply the param at the call site as the **second positional argument** to `ctx.get`. Each unique param resolves to its own family member; reverse-dependency edges are wired up automatically, so invalidating any read member (or the whole family) propagates `stale` to the consumer.
+A `dependencies` entry can be either a regular `Atom` or an `atomFamily`. When the entry is a family, supply the param at the call site as the **second positional argument** to `ctx.read`. Each unique param maps to its own family member; reverse-dependency edges are wired up automatically, so invalidating any read member (or the whole family) propagates `stale` to the consumer.
 
 ```ts
 import { atom } from "@kdeveloper/kvark";
 import { atomFamily } from "@kdeveloper/kvark/family";
 
 const userFamily = atomFamily({
-  get: (id: number) => async () => fetch(`/api/users/${id}`).then((r) => r.json()),
+  read: (id: number) => async () => fetch(`/api/users/${id}`).then((r) => r.json()),
 });
 
 const profileAtom = atom({
   dependencies: { user: userFamily },
-  get: async (ctx) => {
-    const user = await ctx.get("user", 7); // resolves userFamily(7)
+  read: async (ctx) => {
+    const user = await ctx.read("user", 7); // reads userFamily(7)
     return `profile-of-${user.name}`;
   },
 });
@@ -607,31 +615,31 @@ const profileAtom = atom({
 userFamily.invalidate(7); // marks profileAtom stale
 ```
 
-The signature of `ctx.get` is keyed on the dependency entry:
+The signature of `ctx.read` is keyed on the dependency entry:
 
-| Entry        | Call form             | Compile-time errors                                  |
-| ------------ | --------------------- | ---------------------------------------------------- |
-| `Atom<V>`    | `ctx.get(key)`        | passing a second arg → error                         |
-| `atomFamily` | `ctx.get(key, param)` | omitting `param` → error; wrong `param` type → error |
+| Entry        | Call form              | Compile-time errors                                  |
+| ------------ | ---------------------- | ---------------------------------------------------- |
+| `Atom<V>`    | `ctx.read(key)`        | passing a second arg → error                         |
+| `atomFamily` | `ctx.read(key, param)` | omitting `param` → error; wrong `param` type → error |
 
 ```ts
 const a = atom({
   dependencies: { base: countAtom, user: userFamily },
-  get: async (ctx) => {
-    await ctx.get("base"); // ok
-    await ctx.get("user", 1); // ok
+  read: async (ctx) => {
+    await ctx.read("base"); // ok
+    await ctx.read("user", 1); // ok
 
     // @ts-expect-error family-key requires a parameter
-    ctx.get("user");
+    ctx.read("user");
     // @ts-expect-error plain atom-key does not accept a parameter
-    ctx.get("base", 1);
+    ctx.read("base", 1);
     // @ts-expect-error param type must match the family's `Param`
-    ctx.get("user", "not-a-number");
+    ctx.read("user", "not-a-number");
   },
 });
 ```
 
-Repeated reads with the same `param` are deduplicated through the in-flight promise of the resolved family member; reads with different params resolve to distinct atoms (and run independently). Family-typed dependencies are **not** pre-resolved before `get` runs (the param is only known at the `ctx.get` call site), so unread members never trigger a fetch.
+Repeated reads with the same `param` are deduplicated through the in-flight promise of the already-read family member; reads with different params use distinct atoms and run independently. Family-typed dependencies are **not** preloaded before `read` runs (the param is only known at the `ctx.read` call site), so unread members never trigger a fetch.
 
 ### Object params and `paramKey`
 
@@ -643,14 +651,14 @@ import { atomFamily, stableFamilyKey } from "@kdeveloper/kvark/family";
 const searchFamily = atomFamily({
   // Two different object literals with the same fields → same atom
   paramKey: (filters) => stableFamilyKey(filters),
-  get: (filters) => async () => fetchResults(filters),
+  read: (filters) => async () => fetchResults(filters),
 });
 
 searchFamily({ page: 1, query: "hello" }); // creates atom, key = '{"page":1,"query":"hello"}'
 searchFamily({ query: "hello", page: 1 }); // returns the same atom (fields are sorted)
 ```
 
-The `paramKey` function is called once per `family(param)` invocation. The returned key is used for all cache operations (`get`, `set`, `invalidate`, `remove`, LRU). The original `param` is still passed to `get`, `set`, and `dependencies`.
+The `paramKey` function is called once per `family(param)` invocation. The returned key is used for all cache operations (`read`, `apply`, `invalidate`, `remove`, LRU). The original `param` is still passed to `read`, `write`, and `dependencies`.
 
 #### `stableFamilyKey(value)`
 
@@ -663,7 +671,7 @@ A built-in helper that serialises plain objects and arrays into a deterministic
 
 ### Batching (`atomFamily` with `batch`)
 
-Instead of fetching each atom individually, you can batch multiple concurrent requests into a single call — inspired by [`@yornaath/batshit`](https://www.npmjs.com/package/@yornaath/batshit). Replace `get` with `batch`:
+Instead of fetching each atom individually, you can batch multiple concurrent requests into a single call — inspired by [`@yornaath/batshit`](https://www.npmjs.com/package/@yornaath/batshit). Replace `read` with `batch`:
 
 ```ts
 import { atomFamily, windowScheduler } from "@kdeveloper/kvark/family";
@@ -674,7 +682,7 @@ const userFamily = atomFamily({
   batch: {
     scheduler: windowScheduler(10),
     fetch: async ({ keys, params, signal, ctx }) => {
-      const auth = await ctx.get("auth");
+      const auth = await ctx.read("auth");
       const res = await fetch(`/api/users?ids=${keys.join(",")}`, {
         headers: { Authorization: auth.token },
         signal,
@@ -685,13 +693,13 @@ const userFamily = atomFamily({
   },
 });
 
-// Each call returns an atom; concurrent resolves within the scheduler
+// Each call returns an atom; concurrent reads within the scheduler
 // window are batched into a single fetch.
 const alice = useAtomValue(userFamily(1));
 const bob = useAtomValue(userFamily(2));
 ```
 
-**How it works:** when multiple atoms are resolved concurrently (e.g. several components mount at once), each atom's `get` enqueues its key into the batch coordinator. The scheduler decides when to flush the queue: the default `microtaskScheduler` flushes at the end of the current microtask; `windowScheduler(ms)` waits up to `ms` milliseconds.
+**How it works:** when multiple atoms are read concurrently (e.g. several components mount at once), each atom's `read` enqueues its key into the batch coordinator. The scheduler decides when to flush the queue: the default `microtaskScheduler` flushes at the end of the current microtask; `windowScheduler(ms)` waits up to `ms` milliseconds.
 
 `batch.fetch` receives:
 
@@ -762,9 +770,9 @@ type InfiniteData<Page, Cursor> = {
 };
 ```
 
-Call `store.set(projectsAtom, "loadNext")` (or `useSetAtom(projectsAtom)("loadNext")`) to fetch and append the next page. If `hasNextPage` is `false`, the call is a no-op.
+Call `store.apply(projectsAtom, "loadNext")` (or `useApplyAtom(projectsAtom)("loadNext")`) to fetch and append the next page. If `hasNextPage` is `false`, the call is a no-op.
 
-When the atom is invalidated, `get` re-fetches every cached page **sequentially** by replaying the stored `pageCursors` — the same stale-while-revalidate flow as regular atoms.
+When the atom is invalidated, `read` re-fetches every cached page **sequentially** by replaying the stored `pageCursors` — the same stale-while-revalidate flow as regular atoms.
 
 Use `maxPages` to cap the number of pages held in memory and re-fetched on invalidation:
 
@@ -799,8 +807,8 @@ const userPostsFamily = infinityAtomFamily({
 });
 
 const aliceFeed = useAtomValue(userPostsFamily(1));
-const setAliceFeed = useSetAtom(userPostsFamily(1));
-await setAliceFeed("loadNext");
+const applyAliceFeed = useApplyAtom(userPostsFamily(1));
+await applyAliceFeed("loadNext");
 
 userPostsFamily.invalidate(1);
 userPostsFamily.invalidateAll();
@@ -814,7 +822,7 @@ All hooks must be used inside a `<Provider>`.
 
 ### `useStore`
 
-Returns the `Store` instance from context — for advanced cases (e.g. calling `store.resolve` in async setup patterns) or when you need the store outside atom helpers.
+Returns the `Store` instance from context — for advanced cases (e.g. calling `store.read` in async setup patterns) or when you need the store outside atom helpers.
 
 ### `useAtomValue`
 
@@ -828,13 +836,13 @@ const user = useAtomValue(userAtom);
 const { value, isStale, error } = useAtomValue(userAtom, { observe: true });
 ```
 
-### `useSetAtom`
+### `useApplyAtom`
 
-Returns the setter for a writable atom, without subscribing to the value.
+Returns a stable function that calls `store.apply` for a writable atom, without subscribing to the value.
 
 ```tsx
-const setCount = useSetAtom(countAtom);
-await setCount(42);
+const applyCount = useApplyAtom(countAtom);
+await applyCount(42);
 ```
 
 ### `useMutation`
@@ -848,10 +856,10 @@ await runReorder(itemId, newIndex);
 
 ### `useAtom`
 
-Combines `useAtomValue` and `useSetAtom` into a `[value, setter]` tuple.
+Combines `useAtomValue` and `useApplyAtom` into a `[value, apply]` tuple.
 
 ```tsx
-const [count, setCount] = useAtom(countAtom);
+const [count, applyCount] = useAtom(countAtom);
 ```
 
 ### `useAtomContext`
@@ -860,7 +868,7 @@ Imperative access to the `StoreClient` inside a callback. Does not subscribe.
 
 ```tsx
 const readBalance = useAtomContext(async (client) => {
-  return client.get(balanceAtom);
+  return client.read(balanceAtom);
 });
 
 // Call imperatively, e.g. in an event handler
@@ -869,21 +877,21 @@ const balance = await readBalance();
 
 ## Preact (`@kdeveloper/kvark/preact`)
 
-Same hook names, signatures, and behaviour as the React integration: `Provider`, `useStore`, `useAtomValue`, `useSetAtom`, `useMutation`, `useAtom`, `useAtomContext`. All hooks must be used inside a `<Provider>`.
+Same hook names, signatures, and behaviour as the React integration: `Provider`, `useStore`, `useAtomValue`, `useApplyAtom`, `useMutation`, `useAtom`, `useAtomContext`. All hooks must be used inside a `<Provider>`.
 
 Internally the entry imports only from `preact` and `preact/hooks` — there is **no dependency on `preact/compat`**, so your app does not need any React compatibility aliases.
 
 ## Vue 3 (`@kdeveloper/kvark/vue`)
 
-Same composable names and behaviour as React: `Provider`, `useStore`, `useAtomValue`, `useSetAtom`, `useMutation`, `useAtom`, `useAtomContext`. Wrap your app (or subtree) with `Provider` and pass `:store="store"`.
+Same composable names and behaviour as React: `Provider`, `useStore`, `useAtomValue`, `useApplyAtom`, `useMutation`, `useAtom`, `useAtomContext`. Wrap your app (or subtree) with `Provider` and pass `:store="store"`.
 
 Exported types: **`ThenableShallowRef<V>`** (default `useAtomValue`), **`ThenableObservedShallowRef<V>`** and **`ObservedValue<V>`** (with `{ observe: true }`). They encode pending vs resolved ref shapes for TypeScript.
 
-`useAtomValue` / `useAtom` expose values as **awaitable shallow refs** (`PromiseLike`) — in script code use `.value`; in templates Vue unwraps refs for you. `await useAtomValue(atom)` in an async setup suspends until the atom's first `get` resolves, integrating with `<Suspense>`.
+`useAtomValue` / `useAtom` expose values as **awaitable shallow refs** (`PromiseLike`) — in script code use `.value`; in templates Vue unwraps refs for you. `await useAtomValue(atom)` in an async setup suspends until the atom's first `read` resolves, integrating with `<Suspense>`.
 
 ### Suspense (Vue 3)
 
-Vue’s `<Suspense>` boundary applies to **async** components (e.g. **`async setup`** or [top-level `await` in `<script setup>`](https://vuejs.org/guide/built-ins/suspense.html#async-setup)), not to composables alone. Because `useAtomValue` and `useAtom` return `PromiseLike` refs, you can simply `await` them to suspend until the first `get` resolves.
+Vue’s `<Suspense>` boundary applies to **async** components (e.g. **`async setup`** or [top-level `await` in `<script setup>`](https://vuejs.org/guide/built-ins/suspense.html#async-setup)), not to composables alone. Because `useAtomValue` and `useAtom` return `PromiseLike` refs, you can simply `await` them to suspend until the first `read` resolves.
 
 `atoms.ts`
 
@@ -891,7 +899,7 @@ Vue’s `<Suspense>` boundary applies to **async** components (e.g. **`async set
 import { atom } from "@kdeveloper/kvark";
 
 export const slowAtom = atom({
-  get: async () => {
+  read: async () => {
     await new Promise((r) => setTimeout(r, 50));
     return "ready";
   },
@@ -939,7 +947,7 @@ const store = createStore();
 </template>
 ```
 
-Alternatively, use **`defineComponent({ async setup() { ... } })`** and `await useAtomValue(slowAtom)` before returning the render function — the same pattern as in `test/vue/hooks.test.ts`. `useAtom` is also awaitable: `const [ref, set] = await useAtom(writableAtom)`.
+Alternatively, use **`defineComponent({ async setup() { ... } })`** and `await useAtomValue(slowAtom)` before returning the render function — the same pattern as in `test/vue/hooks.test.ts`. `useAtom` is also awaitable: `const [ref, apply] = await useAtom(writableAtom)`.
 
 ## External Invalidation
 
@@ -980,9 +988,23 @@ const unsub = client.subscribe(userAtom, (state) => {
 });
 ```
 
+`client.observe(atom, listener)` is an explicit alias for state-bearing external subscriptions. `client.subscribe` remains available for compatibility and has the same state-bearing callback shape on `StoreClient`.
+
+### Cache-first reads
+
+Use `read(atom)` when you want Kvark's normal async read semantics. For imperative code that prefers cached data when available, use:
+
+```ts
+const state = client.get(userAtom); // AtomState<User>, sync
+const cached = client.peek(userAtom); // User | undefined, sync
+const user = await client.ensure(userAtom); // cached fresh/stale value, otherwise read()
+```
+
+`get(atom)` mirrors `getSnapshot(atom)`. `peek(atom)` returns the current cached value from `fresh`, `stale`, or retained `error` states without starting a read. `ensure(atom)` resolves immediately for cached `fresh`/`stale` values, or for an `error` state that retained a non-`undefined` value; otherwise it delegates to `read(atom)`.
+
 ### Direct Write
 
-When the server pushes a complete, authoritative value (e.g. via WebSocket or SSE), use `client.write` to store it directly — no refetch through `get` is triggered. Any in-flight `get` for the atom is aborted, and derived atoms that depend on it are marked `stale` so they re-compute.
+When the server pushes a complete, authoritative value (e.g. via WebSocket or SSE), use `store.write` / `client.write` to store it directly — no refetch through `read` is triggered, and the atom's `write` callback is not invoked. Any in-flight `read` for the atom is aborted, and derived atoms that depend on it are marked `stale` so they re-compute.
 
 ```ts
 ws.addEventListener("message", (event) => {
@@ -1001,24 +1023,45 @@ client.write(counterAtom, (prev) => (prev ?? 0) + 1);
 
 > If `V` itself is a function type, pass a mutator that returns it: `write(atom, () => myFn)`.
 
-`write` works on any `Atom<V>` — the atom does not need a `set` config. This makes it the right tool when you already have the final value and want to skip a redundant network round-trip.
+`write` works on any `Atom<V>` — the atom does not need a `write` config. This makes it the right tool when you already have the final value and want to skip a redundant network round-trip. Use `apply` when you want to run the atom's async `write` callback instead.
+
+`set(atom, value | mutator)` is an alias for `write(atom, ...)`; `run(atom, ...args)` is an alias for `apply(atom, ...args)`; `runMutation(m, ...args)` is an alias for `mutate(m, ...args)`.
+
+### Inspect and dispose
+
+For devtools and diagnostics, `inspect(atom)` returns lightweight metadata: label, current status, dependency counts, listener count, mount count, and whether a read promise is in flight.
+
+Call `dispose()` when a store is scoped to a request, test, or worker lifetime. It aborts in-flight reads, calls active `onMount` cleanups, clears listeners, and unregisters family invalidation hooks. After disposal, store methods throw `Store has been disposed`; calling `dispose()` again is a no-op.
 
 ### `StoreClient` interface
 
-The concrete `Store` class exposes the same surface as `getClient()` — e.g. `store.mutate(m, ...args)` and `client.mutate(m, ...args)`.
+The concrete `Store` class exposes the same surface as `getClient()` — e.g. `store.read(atom)` / `client.read(atom)`, `store.apply(atom, ...args)` / `client.apply(atom, ...args)`, and `store.mutate(m, ...args)` / `client.mutate(m, ...args)`.
 
 ```ts
-import type { Atom, WritableAtom, AtomState, Mutation } from "@kdeveloper/kvark";
+import type { Atom, WritableAtom, AtomState, Mutation, StoreInspection } from "@kdeveloper/kvark";
 
 interface StoreClient {
-  get<V>(atom: Atom<V>): Promise<V>;
-  set<V, A extends readonly unknown[]>(atom: WritableAtom<V, A>, ...args: A): Promise<void>;
+  get<V>(atom: Atom<V>): AtomState<V>;
+  peek<V>(atom: Atom<V>): V | undefined;
+  ensure<V>(atom: Atom<V>): Promise<V>;
+  read<V>(atom: Atom<V>): Promise<V>;
+  run<V, A extends readonly unknown[]>(atom: WritableAtom<V, A>, ...args: A): Promise<void>;
+  apply<V, A extends readonly unknown[]>(atom: WritableAtom<V, A>, ...args: A): Promise<void>;
+  runMutation<Args extends readonly unknown[]>(
+    mutation: Mutation<Args>,
+    ...args: Args
+  ): Promise<void>;
   mutate<Args extends readonly unknown[]>(mutation: Mutation<Args>, ...args: Args): Promise<void>;
+  set<V>(atom: Atom<V>, value: V): void;
+  set<V>(atom: Atom<V>, mutate: (prev: V | undefined) => V): void;
   write<V>(atom: Atom<V>, value: V): void;
   write<V>(atom: Atom<V>, mutate: (prev: V | undefined) => V): void;
   invalidate(atom: Atom<unknown>): void;
   invalidateMany(atoms: ReadonlyArray<Atom<unknown>>): void;
+  observe<V>(atom: Atom<V>, listener: (state: AtomState<V>) => void): () => void;
   subscribe<V>(atom: Atom<V>, listener: (state: AtomState<V>) => void): () => void;
+  inspect(atom: Atom<unknown>): StoreInspection;
+  dispose(): void;
 }
 ```
 
@@ -1071,16 +1114,16 @@ type PostArgs = AtomArgs<typeof postAtom>; // → [postId: number]
 type Writable = IsWritable<typeof countAtom>; // → true | false
 ```
 
-`WritableAtomContext` extends `MutationContext` — the same `writeOptimistic` / `invalidate` / `invalidateMany` helpers appear on both standalone mutations and writable `set` callbacks.
+`WritableAtomContext` extends `MutationContext` — the same `writeOptimistic` / `invalidate` / `invalidateMany` helpers appear on both standalone mutations and writable `write` callbacks.
 
 ## Package Structure
 
 | Import                     | Contents                                                                                                                                                                                                                                                                                                                                                         |
 | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `@kdeveloper/kvark`        | `atom`, `infinityAtom`, `infinityAtomFamily`, `mutation`, `createStore`, all types (including `Mutation`, `MutationContext`)                                                                                                                                                                                                                                     |
-| `@kdeveloper/kvark/react`  | `Provider`, `useStore`, `useAtomValue`, `useSetAtom`, `useMutation`, `useAtom`, `useAtomContext`                                                                                                                                                                                                                                                                 |
-| `@kdeveloper/kvark/preact` | `Provider`, `useStore`, `useAtomValue`, `useSetAtom`, `useMutation`, `useAtom`, `useAtomContext`                                                                                                                                                                                                                                                                 |
-| `@kdeveloper/kvark/vue`    | `Provider`, `useStore`, `useAtomValue`, `useSetAtom`, `useMutation`, `useAtom`, `useAtomContext`; types `ThenableShallowRef`, `ThenableObservedShallowRef`, `ObservedValue`                                                                                                                                                                                      |
+| `@kdeveloper/kvark`        | `atom`, `infinityAtom`, `infinityAtomFamily`, `mutation`, `createStore`, all types (including `Store`, `StoreClient`, `StoreInspection`, `Mutation`, `MutationContext`)                                                                                                                                                                                          |
+| `@kdeveloper/kvark/react`  | `Provider`, `useStore`, `useAtomValue`, `useApplyAtom`, `useMutation`, `useAtom`, `useAtomContext`                                                                                                                                                                                                                                                               |
+| `@kdeveloper/kvark/preact` | `Provider`, `useStore`, `useAtomValue`, `useApplyAtom`, `useMutation`, `useAtom`, `useAtomContext`                                                                                                                                                                                                                                                               |
+| `@kdeveloper/kvark/vue`    | `Provider`, `useStore`, `useAtomValue`, `useApplyAtom`, `useMutation`, `useAtom`, `useAtomContext`; types `ThenableShallowRef`, `ThenableObservedShallowRef`, `ObservedValue`                                                                                                                                                                                    |
 | `@kdeveloper/kvark/family` | `atomFamily`, `infinityAtomFamily`, `stableFamilyKey`, `microtaskScheduler`, `windowScheduler`, `maxBatchSizeScheduler`, `windowedFiniteBatchScheduler`, re-exports `atom`, `infinityAtom`, `mutation`, `createStore`; types include `AtomFamily`, `InfinityAtomFamily`, `BatchScheduler`, `BatchFetchInput`, `Mutation`, `MutationContext`, and core atom types |
 
 The core (`@kdeveloper/kvark`) has **zero runtime dependencies**. **React**, **Preact**, and **Vue** are optional peer dependencies — install the framework you use and import from `/react`, `/preact`, or `/vue`.