Skip to content

CoreSyncHub/ngx-query

Folders and files

NameName
Last commit message
Last commit date

Latest commit

ย 

History

14 Commits
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 

Repository files navigation

๐ŸŒ€ NGX Query

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

npm version Angular RxJS License


๐Ÿ“– 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

About

Minimalistic Query-like library for Angular. RxJS only. DI native. SSR-friendly.

Resources

License

Stars

Watchers

Forks

Packages

No packages published