@kdeveloper/kvark 0.6.0 → 0.6.1

package/README.md

@@ -1,12 +1,12 @@
 # @kdeveloper/kvark
 
-Atomic state management for React with **explicit dependency graphs**, stale-while-revalidate, and first-class external invalidation.
+Atomic state management for **React** and **Vue 3** with **explicit dependency graphs**, stale-while-revalidate, and first-class external invalidation.
 
-Inspired by Jotai, but built around a key difference: dependencies are declared upfront rather than inferred at runtime. This makes the data graph statically analysable, enables parallel loading, and allows invalidation from anywhere — WebSocket handlers, SSE streams, timers, Service Workers — without any React hooks.
+Inspired by Jotai, but built around a key difference: dependencies are declared upfront rather than inferred at runtime. This makes the data graph statically analysable, enables parallel loading, and allows invalidation from anywhere — WebSocket handlers, SSE streams, timers, Service Workers — without framework hooks.
 
-```
-npm install @kdeveloper/kvark
-# peer dependency: react >=18
+```bash
+pnpm add @kdeveloper/kvark
+# optional peers: react >=18 and/or vue >=3.4 (install the one you use)
 ```
 
 ## Why Kvark?
@@ -26,7 +26,7 @@ npm install @kdeveloper/kvark
 
 ```bash
 pnpm add @kdeveloper/kvark
-# react >=18 is a peer dependency
+# optional peers: react >=18 and/or vue >=3.4
 ```
 
 ## Quick Start
@@ -73,6 +73,69 @@ function UserCard() {
 }
 ```
 
+### Vue 3
+
+The same atoms and store work with `@kdeveloper/kvark/vue`. Composables mirror the React hooks; `useAtomValue` returns a [`shallowRef`](https://vuejs.org/api/reactivity-advanced.html#shallowref) to the value — use `.value` in `<script setup>` (templates unwrap refs automatically).
+
+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.
+
+`atoms.ts` — lift the atom definitions from the Quick Start into a shared module:
+
+```ts
+import { atom } from "@kdeveloper/kvark";
+
+export const userIdAtom = atom({
+  debugLabel: "userId",
+  get: async () => 1,
+  set: async () => {},
+});
+
+export const userAtom = atom({
+  debugLabel: "user",
+  dependencies: { userId: userIdAtom },
+  get: async (ctx) => {
+    const id = await ctx.get("userId");
+    const res = await fetch(`/api/users/${id}`, { signal: ctx.signal });
+    return res.json();
+  },
+});
+```
+
+`UserCard.vue`
+
+```vue
+<script setup lang="ts">
+import { useAtomValue } from "@kdeveloper/kvark/vue";
+import { userAtom } from "./atoms";
+
+const user = useAtomValue(userAtom);
+</script>
+
+<template>
+  <div>{{ user.name }}</div>
+</template>
+```
+
+`App.vue`
+
+```vue
+<script setup lang="ts">
+import { createStore } from "@kdeveloper/kvark";
+import { Provider } from "@kdeveloper/kvark/vue";
+import UserCard from "./UserCard.vue";
+
+const store = createStore();
+</script>
+
+<template>
+  <Provider :store="store">
+    <UserCard />
+  </Provider>
+</template>
+```
+
+Unlike React’s `Suspense` around `useAtomValue`, Vue’s `<Suspense>` only activates for **async** child components. To show a fallback until the first `get` completes, use **`async setup`**, `useStore()`, `useAtomValue(atom)`, then **`await store.resolve(atom)`**, and wrap that child in `<Suspense>` — see [Suspense (Vue 3)](#suspense-vue-3).
+
 ## Core Concepts
 
 ### Atoms
@@ -174,7 +237,7 @@ Both can update an atom's cached value, but they serve different purposes:
 
 ### `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`.
+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`.
 
 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.
 
@@ -300,10 +363,14 @@ A built-in helper that serialises plain objects and arrays into a deterministic
 - Not supported: class instances (other than plain `Object`/`Array`), `Map`, `Set`, `Symbol`, functions, circular references.
 - Memoises by object reference via a `WeakMap` — repeated calls with the **same object reference** are O(1). Treat param objects as **immutable** after the first call; mutating an object after it has been memoised will silently return the stale key.
 
-## React Hooks
+## React (`@kdeveloper/kvark/react`)
 
 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.
+
 ### `useAtomValue`
 
 Reads an atom value and subscribes to updates. Suspends on first load.
@@ -346,9 +413,77 @@ const readBalance = useAtomContext(async (client) => {
 const balance = await readBalance();
 ```
 
+## Vue 3 (`@kdeveloper/kvark/vue`)
+
+Same composable names and behaviour as React: `Provider`, `useStore`, `useAtomValue`, `useSetAtom`, `useAtom`, `useAtomContext`. Wrap your app (or subtree) with `Provider` and pass `:store="store"`.
+
+`useAtomValue` / `useAtom` expose values as **shallow refs** — in script code use `.value`; in templates Vue unwraps refs for you.
+
+### 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. To get a loading fallback until the first `get` finishes, the child that uses `useAtomValue` should **`await store.resolve(atom)`** after subscribing, and be wrapped in `<Suspense>`.
+
+`atoms.ts`
+
+```ts
+import { atom } from "@kdeveloper/kvark";
+
+export const slowAtom = atom({
+  get: async () => {
+    await new Promise((r) => setTimeout(r, 50));
+    return "ready";
+  },
+});
+```
+
+`AsyncRead.vue` (under `Provider`; top-level `await` makes this component async for Suspense)
+
+```vue
+<script setup lang="ts">
+import { useAtomValue, useStore } from "@kdeveloper/kvark/vue";
+import { slowAtom } from "./atoms";
+
+const store = useStore();
+const value = useAtomValue(slowAtom);
+await store.resolve(slowAtom);
+</script>
+
+<template>
+  <div>{{ value }}</div>
+</template>
+```
+
+`App.vue`
+
+```vue
+<script setup lang="ts">
+import { Suspense } from "vue";
+import { createStore } from "@kdeveloper/kvark";
+import { Provider } from "@kdeveloper/kvark/vue";
+import AsyncRead from "./AsyncRead.vue";
+
+const store = createStore();
+</script>
+
+<template>
+  <Provider :store="store">
+    <Suspense>
+      <template #default>
+        <AsyncRead />
+      </template>
+      <template #fallback>
+        <div>Loading…</div>
+      </template>
+    </Suspense>
+  </Provider>
+</template>
+```
+
+Alternatively, use **`defineComponent({ async setup() { ... } })`** and `await store.resolve(slowAtom)` before returning the render function — the same pattern as in `test/vue/hooks.test.ts`.
+
 ## External Invalidation
 
-`StoreClient` exposes the store's full capabilities outside of React — useful for WebSocket handlers, SSE streams, polling timers, and Service Workers.
+`StoreClient` exposes the store's full capabilities outside your component tree — useful for WebSocket handlers, SSE streams, polling timers, and Service Workers.
 
 ```ts
 import { createStore } from "@kdeveloper/kvark";
@@ -377,7 +512,7 @@ sse.addEventListener("prices.updated", () => {
 // Polling
 setInterval(() => client.invalidate(statusAtom), 30_000);
 
-// Subscribe to state changes outside React
+// Subscribe to state changes outside components
 const unsub = client.subscribe(userAtom, (state) => {
   if (state.status === "fresh") {
     analytics.identify(state.value.id);
@@ -424,6 +559,8 @@ interface StoreClient {
 
 ## Provider and Store Setup
 
+**React**
+
 ```tsx
 // store.ts
 import { createStore } from "@kdeveloper/kvark";
@@ -442,6 +579,23 @@ export function App() {
 }
 ```
 
+**Vue 3**
+
+```vue
+<script setup lang="ts">
+import { createStore } from "@kdeveloper/kvark";
+import { Provider } from "@kdeveloper/kvark/vue";
+
+const store = createStore();
+</script>
+
+<template>
+  <Provider :store="store">
+    <RouterView />
+  </Provider>
+</template>
+```
+
 ## Utility Types
 
 ```ts
@@ -454,19 +608,21 @@ type Writable = IsWritable<typeof countAtom>; // → true | false
 
 ## Package Structure
 
-| Import                     | Contents                                                              |
-| -------------------------- | --------------------------------------------------------------------- |
-| `@kdeveloper/kvark`        | `atom`, `createStore`, all types                                      |
-| `@kdeveloper/kvark/react`  | `Provider`, `useAtomValue`, `useSetAtom`, `useAtom`, `useAtomContext` |
-| `@kdeveloper/kvark/family` | `atomFamily`                                                          |
+| Import                     | Contents                                                                                    |
+| -------------------------- | ------------------------------------------------------------------------------------------- |
+| `@kdeveloper/kvark`        | `atom`, `createStore`, all types                                                            |
+| `@kdeveloper/kvark/react`  | `Provider`, `useStore`, `useAtomValue`, `useSetAtom`, `useAtom`, `useAtomContext`           |
+| `@kdeveloper/kvark/vue`    | `Provider`, `useStore`, `useAtomValue`, `useSetAtom`, `useAtom`, `useAtomContext`           |
+| `@kdeveloper/kvark/family` | `atomFamily`, `stableFamilyKey`, re-exports `atom` / `createStore` and core types           |
 
-The core (`@kdeveloper/kvark`) has **zero runtime dependencies**. React is a peer dependency only needed when using the `/react` subpath.
+The core (`@kdeveloper/kvark`) has **zero runtime dependencies**. **React** and **Vue** are optional peer dependencies — install the framework you use and import from `/react` or `/vue`.
 
 ## Requirements
 
 - **Node.js** ≥ 20
 - **TypeScript** ≥ 6 (strict mode recommended)
-- **React** ≥ 18 (for `@kdeveloper/kvark/react`)
+- **React** ≥ 18 (optional peer, for `@kdeveloper/kvark/react`)
+- **Vue** ≥ 3.4 (optional peer, for `@kdeveloper/kvark/vue`)
 
 ## License
 

package/package.json

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