@kdeveloper/kvark 0.14.0 → 0.14.1

package/README.md

@@ -509,6 +509,56 @@ postFamily.invalidate(42);
 postFamily.invalidateAll();
 ```
 
+### `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.
+
+```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()),
+});
+
+const profileAtom = atom({
+  dependencies: { user: userFamily },
+  get: async (ctx) => {
+    const user = await ctx.get("user", 7); // resolves userFamily(7)
+    return `profile-of-${user.name}`;
+  },
+});
+
+// Invalidating a read family member cascades to consumers
+userFamily.invalidate(7); // marks profileAtom stale
+```
+
+The signature of `ctx.get` 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 |
+
+```ts
+const a = atom({
+  dependencies: { base: countAtom, user: userFamily },
+  get: async (ctx) => {
+    await ctx.get("base"); // ok
+    await ctx.get("user", 1); // ok
+
+    // @ts-expect-error family-key requires a parameter
+    ctx.get("user");
+    // @ts-expect-error plain atom-key does not accept a parameter
+    ctx.get("base", 1);
+    // @ts-expect-error param type must match the family's `Param`
+    ctx.get("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.
+
 ### Object params and `paramKey`
 
 By default atoms are cached by **reference** (`===`). When you want equality-by-value — for example when the param is a filter object — supply a `paramKey` function that maps the param to a stable primitive key:

package/package.json

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