🗄️ reactive-query-z

 !Downloads

LIVE EXAMPLE

reactive-query-z is a lightweight, reactive data-fetching library for React, built with hooks and TypeScript in mind.

> Minimal API surface, predictable behavior, and production-ready features.

---

✨ Why reactive-query-z

* ⚡ Lightweight & hook-based
* 🔁 REST + GraphQL support
* ✍️ Full CRUD mutations
* 💾 Cache with global invalidation
* 🚀 Optimistic UI updates
* ♻️ Stale-while-revalidate
* 📡 Real-time subscriptions (WebSocket / SSE)
* 🧩 Middleware system (auth, logging, retry, timeout…)
* 🧠 TypeScript-first API

Note: For full-featured query management, see React Query

---

📦 Installation

``bash
npm install reactive-query-z


or


yarn add reactive-query-z
`

---

🚀 Basic Usage

$3

`ts
import { useQuery, queryRegistry } from "reactive-query-z";

type User = { id: string; title: string };

function UserList() {
const {
data: users,
loading,
refetch,
error,
} = useQuery("https://jsonplaceholder.typicode.com/posts", {
cacheKey: "users-list",
// staleTime: 5000,
cacheTime: 10000,
// autoFetch: true,
headers: { "Content-Type": "application/json" },
});

return (



);
}
`

---

$3

`ts
import { useGraphQLQuery } from "reactive-query-z";

type Country = { code: string; name: string; emoji: string };

export function CountriesList() {
const { data, loading, error, refetch } = useGraphQLQuery<{ countries: Country[] }>(
"https://countries.trevorblades.com/",
{
query:
query {
countries { code name emoji }
}
,
cacheKey: "countries",
}
);

if (loading) return

Loading...

;
if (error) return

{error.message}

;

return (

Refetch


{data?.countries?.map(c => (

• {c.name} {c.emoji}

))}

);
}
`

---

$3

`ts
import { useMutation, queryRegistry } from "reactive-query-z";

type Post = {
userId: number;
id: number;
title: string;
body: string;
};

export function AddPost() {
const { mutate, loading } = useMutation(
"https://jsonplaceholder.typicode.com/posts",
{
cacheKey: "posts",
optimisticUpdate: (prev, newPost) => newPost,
onSuccess: () => queryRegistry.invalidate("posts"),
}
);

const handleAdd = () => {
mutate({
title: "New Post",
body: "This is a new post",
userId: 1,
});
};

return (

{loading ? "Adding..." : "Add Post"}

);
}
`

---

$3

`ts
import { useGraphQLMutation, queryRegistry } from "reactive-query-z";

export function AddPostGraphQL() {
const { mutate, loading } = useGraphQLMutation(
"https://graphqlzero.almansi.me/api",
{
mutation:
mutation ($title: String!, $body: String!, $userId: ID!) {
createPost(input: { title: $title, body: $body, userId: $userId }) {
id
title
body
}
}
,
variables: { title: "Hello", body: "World", userId: 122 },
onSuccess: () => queryRegistry.invalidate("postsGraphQL"),
}
);

return (

{loading ? "Adding..." : "Add Post"}

);
}
`

---

$3

`ts
import { queryRegistry, setGlobalErrorHandler } from "reactive-query-z";

queryRegistry.invalidate("users"); // specific
queryRegistry.invalidate(); // all queries

setGlobalErrorHandler((error, info) => {
console.error("Global fetch error:", error, info);
});
`

---

$3

`ts
import { useHybridQuery } from "reactive-query-z";

const { data } = useHybridQuery("/graphql", {
subscriptionUrl: "ws://localhost:4000",
cacheKey: "messages",
});
`

---

$3

#### 🔹 queryClient.fetchQuery

`ts
import { queryClient } from "reactive-query-z";

await queryClient.fetchQuery(
"https://jsonplaceholder.typicode.com/users",
{ cacheKey: "users" }
);
`

#### 🔹 queryClient.ensureQueryData (recommended)

`ts
import { queryClient, useQuery } from "reactive-query-z";

type User = { id: number; name: string };

async function preloadUsers() {
await queryClient.ensureQueryData(
"https://jsonplaceholder.typicode.com/users",
{ cacheKey: "users" }
);
}

function Users() {
const { data, loading } = useQuery(
"https://jsonplaceholder.typicode.com/users",
{ cacheKey: "users" }
);

if (loading) return

Loading...

;

return (

{data?.map((u) => (

• {u.name}

))}

);
}
`

---

🔧 API Reference

`ts
useQuery
useMutation
useGraphQLQuery
useGraphQLMutation
useHybridQuery

queryClient
queryRegistry

prefetchQuery
prefetchData
fetchWithRetry
commonFetch
setGlobalErrorHandler
``

---

⚖️ Comparison with Other Libraries

| Feature | reactive-query-z | React Query | SWR | Apollo Client |
| ------------------------- | ---------------- | ----------- | ---- | ------------- |
| REST support | ✅ | ✅ | ✅ | ⚠️ Partial |
| GraphQL support | ✅ | ⚠️ Plugin | ❌ | ✅ |
| Real-time subscription | ✅ | ⚠️ Plugin | ❌ | ✅ |
| Global cache invalidation | ✅ | ✅ | ⚠️ | ✅ |
| Optimistic updates | ✅ | ✅ | ⚠️ | ✅ |
| Stale-while-revalidate | ✅ | ✅ | ✅ | ✅ |
| Full CRUD mutations | ✅ | ✅ | ❌ | ✅ |
| TypeScript-first | ✅ | ✅ | ✅ | ✅ |
| Lightweight | ✅ | ⚠️ | ✅ | ⚠️ |
| Subscription built-in | ✅ | ❌ | ❌ | ✅ |

---

When to use

- You want full control over async orchestration
- You dislike heavy cache lifecycles
- You prefer explicit invalidation

---

When NOT to use

- You need background refetch
- You need offline persistence

---

📜 License

MIT