🌀 NGX Query

A minimal, reactive, and type-safe data-fetching library for Angular — inspired by TanStack Query.

---

📖 Overview

NGX Query is a lightweight, observable-based query library built specifically for Angular.
It helps you manage server state, caching, and synchronization between your backend and UI — all without boilerplate.

It takes the best ideas from TanStack Query but rethinks them for Angular’s ecosystem, not just as an adapter for React concepts :

• Native Dependency Injection instead of context providers
• RxJS Observables instead of Promises

---

✨ Features

• ✅ Observable-first — built for Angular, not adapted from React.
• 🧠 Fluent API — declare queries and mutations with expressive builders.
• 🔁 Caching & Invalidation — configurable stale and GC times, precise invalidation.
• ⚡ Optimistic Updates — instant UI feedback with rollback on error.
• 🔄 Refetch on Focus & Reconnect — stay synced with network and tab activity.
• 🧩 Error & Retry Strategies — configurable backoff and retry handling.

---

🚀 Installation

npm install @coresync/ngx-query

or

yarn add @coresync/ngx-query
# or pnpm / bun

Requires Angular 20+ and RxJS 7+

---

⚡ Quick Start

1. Provide the QueryClient

// app.config.ts
import { ApplicationConfig } from "@angular/core";
import { provideHttpClient, withFetch } from "@angular/common/http";
import { provideQueryClient } from "@coresync/ngx-query";

export const appConfig: ApplicationConfig = {
  providers: [
    provideHttpClient(withFetch()),
    provideQueryClient({
      staleTime: 60_000,
      gcTime: 10 * 60_000,
      retry: 3,
      refetchOnFocus: true,
      refetchOnReconnect: true,
    }),
  ],
};

2. Create a Query

import { Component, inject } from "@angular/core";
import { CommonModule } from "@angular/common";
import { HttpClient } from "@angular/common/http";
import { queryBuilder, injectQueryClient } from "@coresync/ngx-query";

interface UserDto {
  id: string;
  name: string;
}

@Component({
  standalone: true,
  selector: "user-list",
  imports: [CommonModule],
  template: `
    <h2>Users</h2>
    @if (users$ | async; as users) {
    <ul>
      @for (user of users; track user.id) {
      <li>{{ user.name }}</li>
      }
    </ul>
    }
  `,
})
export class UserListComponent {
  private http = inject(HttpClient);
  private queryClient = injectQueryClient();

  users$ = queryBuilder<UserDto[]>(this.queryClient)
    .key(["users"])
    .fetcher(() => this.http.get<UserDto[]>("/api/users"))
    .build().data$;
}

3. Mutate Data

import { mutationBuilder, injectQueryClient } from "@coresync/ngx-query";

const queryClient = injectQueryClient();

const createUser = mutationBuilder<UserDto, CreateUserInput>(queryClient)
  .key(["users", "create"])
  .affects(["users"])
  .mutateFn((input) => http.post<UserDto>("/api/users", input))
  .build();

---

🧩 API Highlights

Feature	Description
queryBuilder	Creates reactive, observable queries with caching and status tracking
mutationBuilder	Builds mutations with optimistic updates and invalidation
provideQueryClient	Configures global cache and retry policies
injectQueryClient	Retrieves the current QueryClient from DI

---

🔮 Roadmap

Feature	Status
✅ Queries & Mutations	Implemented
✅ Optimistic Updates	Implemented
🧪 Infinite Queries	Planned
⚡ Query Suspense	Planned
⚙️ SSR / TransferState	Planned
🧰 DevTools	Planned

---

🧱 Comparison with TanStack Query

The comparison below refers specifically to @tanstack/angular-query-experimental.

Aspect	TanStack Query (Angular Adapter)	NGX Query
Maturity	Experimental, API evolving	Experimental, API evolving
Angular support	Angular v16+	Angular v20+
Core primitives	Signals-centric API with injectQuery/injectMutation returning signal-like getters (data(), error(), isPending())	Observable-first streams with a fluent builder (queryBuilder/mutationBuilder)
Fetcher style	Typically Promise-based	Observable-based by default; no Promise requirement
Optimistic updates	Supported via mutation options	Supported via optimistic, rollback, onSuccess methods

Both projects share the same goal: robust server-state management. Choose based on your app’s primitives: signals + promises vs observables + builders.

---

📚 Documentation

Full documentation with examples and guides is available at:
👉 https://doc.coresync.fr/ngx-query

---

💡 Philosophy

“Keep it reactive, declarative, and Angular-native.”

NGX Query aims to give Angular developers the power of React Query,
but in a form that fits naturally into Angular’s ecosystem — DI, Observables, and Signals.

---

⚖️ License

MIT License © 2025 CoreSyncHub