Looking for community feedback on Angular Query

[arnoud-dv]

👋 Hi everyone,

I've been working on a pull request for adding an Angular adapter to TanStack Query, and it's now approaching completion.

To give you a better idea of its functionality, here are two sandboxes:

1. Angular Query: Simple Example Ported from React Query.
2. Angular Query: Basic Example Ported from React Query, which includes reactivity in the Post component.

These sandboxes are interactive, allowing you to edit the code and see how it works in your own forked sandbox.

The adapter exclusively uses Angular signals, but integrating it with RxJS is quite straightforward thanks to the Angular RxJS interop. With Tanstack / Angular Query, you can potentially replace most, if not all, RxJS-based server-side state synchronization code. That said, I believe RxJS still has significant applications in modern Angular apps, even after the introduction of signals in the framework. For instance, signals derived from an RxJS stream can be easily integrated into query options for reactive behavior.

For the time being, I'm naming the adapter "experimental." This is primarily to allow for the possibility of making breaking API changes in the future. However, I am quite satisfied with its API, especially with createQuery.

I'm looking forward to read your thoughts and feedback! If you have suggestions for API changes or any other improvements, now is the perfect time to share them.

[arnoud-dv]

Edit: changed it from query = inject(CreateQuery)(() => ({ to query = injectQuery(() => ({ as suggested, thanks!

A convincing case is made by @eneajaho (thanks for the incredible amount of feedback so quickly!) to rename the create* functions to inject*.

Example:
query = inject(CreateQuery)(() => ({

would become

query = injectQuery(() => ({

benefit is also getting rid of a pair of parentheses. Opinions? If nobody objects I will rename this as suggested.

[eneajaho]

This kind of API would also have other benefits later.

For example, let's take this mutation with invalidation.

import { useMutation, useQueryClient } from '@tanstack/react-query'

const queryClient = useQueryClient()

// When this mutation succeeds, invalidate any queries with the `todos` or `reminders` query key
const mutation = useMutation({
  mutationFn: addTodo,
  onSuccess: () => {
    queryClient.invalidateQueries({ queryKey: ['todos'] })
    queryClient.invalidateQueries({ queryKey: ['reminders'] })
  },
})

Using a setup function like API (almost same as rxState) it would become sth like this in Angular

@Component()
export class Cmp {
  mutation = injectMutation(({ invalidateQueries, /* maybe some other helper api-s here, setQueryData ?*/ }) => {
   return {
      mutationFn: addTodo,
      onSuccess: () => {
         invalidateQueries({ queryKey: ['todos'] })
         invalidateQueries({ queryKey: ['reminders'] })
      },
   }
 }); 
}

Because we can use inject underneath, we can give the devs some helpers under the hood we can get directly from the query client, the devs won't have to import anything else, because we expose methods directly from the injectMutation setup function. And everything becomes clear.

Of course, the will be able to do the same thing if they inject the query client from the outside, but enabling these API-s by default is so much better.

[kuncevic]

Looks super cool, Is is something that can leverage https://github.com/ngneat/query by @NetanelBasal?
Are there any chances that effort might became a part of an official TanStack query offer? //cc @TkDodo

[NetanelBasal]

Hello @kuncevic,

I'm currently in the process of updating the library to version 5 and am contemplating the inclusion of signal support. However, I have reservations about its suitability for our use case. RxJS provides a far more robust solution when handling requests. Furthermore, I believe there's a significant concern with the use of signals within templates, particularly because of the challenges associated with type guarding. For instance:

<div *ngIf="result().isSuccess">
  {{ result().data }} <== data still typed as undefined | T
</div>

[arnoud-dv]

The NgNeat adapter is a completely different approach by basing it on RxJS and of course signals weren't available in Angular back then. The adapter I wrote works with signals but should interop with RxJS well.

[ayush-sd]

Hi @NetanelBasal, I see you mentioned that you were in the process of upgrading the library to version 5, but in the repo I see that the last tag says 3.0.0, I want to ask you if your adapter is still being maintained/developed? Me and my team are starting migration to angular v16 and we want to start using tanstack query but we are still trying to decide which of these 2 adapters should we use. Any points you can provide towards helping us choose the better adapter for us would be very appreciated as well, thank you.

@arnoud-dv any inputs from you would also be very helpful here

[ducin]

@arnoud-dv awesome amount of work! Definitely the amount of parenthesis might discourage people from trying that out, so 👍 for query = injectQuery(() => ({

Question 1: Not sure if core tanstack/query is capable of supporting streams. Hardly anybody in angular area is using axios directly. Would rxjs-based HTTP work out of the box with the queryFn? Did you consider auto-convertion like Observable<T> | Promise<T> -> if(isObservable(queryFn)) queryFn().toPromise()` or would you rather developers do that explicitly?

Question 2: would providing an example basing on NgModules-based components require extra-effort? Such example might attract more people who didn't move to standalone yet.

Again, awesome work, IMO the community needs such port very much.

[rbalet]

@alexciesielski No it isn't but feel free to download the repo and test it out ;). -> Reason: this is a function, not a service

That said, this way of writing is Not yet approved by @arnoud-dv, so maybe better waits his approval, or changes before learning from this demo.

I'm just filling in this demo how I'm actually using TanStack query with angular, inside my own project, as it may helps others

[alexciesielski]

it throws

[rbalet]

@alexciesielski Interesting, do you use the same repo ? Can you provide a step to reproduce (Even if that sounds numb, cause I do not have this error) I'd be glad to search & fix the error :)

[JulienLecoq]

@rbalet It has nothing to do with being a function or service, it depends where you call this function. If this function is called inside an injection context it's fine otherwise it will throw an error.

[BThomann]

@rbalet there is now a very nice example of how to use the query options pattern in Angular:
https://tanstack.com/query/latest/docs/framework/angular/examples/query-options-from-a-service
This currently my goto way for queries. I am still looking for a nice pattern for mutations.

[theo-matzavinos]

The queryOptions function is pretty useful. It would be nice to have something similar for mutations.

[TkDodo]

the use-case for query options is mainly to share them between useQuery, useQueries, useSuspenseQuery and imperative methods like queryClient.fetchQuery. What would be the use-case for mutation options?

[theo-matzavinos]

The idea is to define the mutations in a service with some predefined options (usually mutationFn and onSuccess). A function would help with the inference of the generics.

[theo-matzavinos]

I rescind this comment. I have since figured out we don't need services. Too much angular brain, I guess.

[PhillipNinan]

I thought this code from your sandbox was nifty. I frequently have a use case where i need to wait for some data (id, form, etc) before creating the query. it would be nice if you could somehow create a dummy query until you have what you need to make the request.

export class PostComponent {
  @Output() setPostId = new EventEmitter<number>()

  // Until Angular supports signal-based inputs, we have to set a signal
  @Input({ required: true })
  set postId(value: number) {
    this.postIdSignal.set(value)
  }
  postIdSignal = signal<number>(0)
  postQuery = inject(CreateQuery)(() => ({
    enabled: this.postIdSignal() > 0,
    queryKey: ['post', this.postIdSignal()],
    queryFn: async (): Promise<Post> => {
      const { data } = await axios.get(
        `https://jsonplaceholder.typicode.com/posts/${this.postIdSignal()}`,
      )
      return data
    },
  }))

  queryClient = inject(UseQueryClient)
}

I don't think this code made it into the current release. I'm not sure what the purpose of CreateQuery was. for now i have a lot of code like this.

  @Input()
  set personId(personId: number) {
    runInInjectionContext(this.injector, () => {
      this.query = this.evalService.getEvalsForPlayer(personId);
    });
  }

i tried to do something like this but it did not seem to work.

  _personId = signal(-1);
  @Input()
  set personId(personId: number) {
    // runInInjectionContext(this.injector, () => {
    //   this.query = this.evalService.getEvalsForPlayer(personId);
    // });
    this._personId.set(personId);
  }

  query = injectQuery(() => ({
    enabled: this._personId() > 0,
    queryKey: [evalKeys.forPlayer(this._personId())] as const,
    queryFn: () => {
      return lastValueFrom(inject(EvalService).getEvalsForPlayer(this._personId()));
    },
  }));

[arnoud-dv]

Hi, I don't fully understand what you're trying to do. In any case, I wouldn't recommend injecting a new query after the class (component or service) is instantiated. Probably TanStack Query already has you covered and it's just a matter of setting query properties and the right states will be changed, your queryFn gets executed if needed and templates rendered through the signals reactively for you.

For instance, if you need data in your query before it's fetched you can use placeholder query data. But in most cases simply rendering some static content in your template will suffice.

I am working on porting all the React Query documentation to Angular but in the meantime I would suggest checking out the documentation for React Query, in most cases it will be very similar. Also TkDodo's blog is highly recommended.

If you cannot find it there and could elaborate what you are trying to accomplish I could probably help you so let me know.

[JulienLecoq]

I have the same issue than @PhillipNinan, it's often that I need some extra data to build my queries and having them to be constructed inside an injection context feels too restrictive and annoying to deal with.

I also sometimes have queries built from a loop, so I don't know in advance how many of them I'll need. Hence, having the possibility to build them later on (outside an injection context) would be very cool.

Furthermore, I don't even see the benefits of having to build them inside an injection context, what does it brings positively? I would much prefer having something like this:

query = new Query(() => ({
    queryKey: [".."],
    queryFn: () => {},
})) 

And another variant which does not require to pass a function, making the code less verbose:

query = new Query({
    queryKey: [".."],
    queryFn: () => {},
})

Or function based since it seems to be fashionable:

productQuery = query(() => ({ 
    queryKey: [".."],
    queryFn: () => {},
}))

productQuery = query({
    queryKey: [".."],
    queryFn: () => {},
})

[arnoud-dv]

it's often that I need some extra data to build my queries and having them to be constructed inside an injection context feels too restrictive and annoying to deal with.

Can you elaborate on this? I really wouldn't know a use case for when you'd want to have a query outside an injection context. Injection context fits reactive programming very well and enables automatic unsubscription. I will soon add support for required input signals which should reduce the need to disable queries until the input is available.

Note you can actually use injectQuery outside an injection context but you'd need to pass an injector manually.

I also sometimes have queries built from a loop, so I don't know in advance how many of them I'll need. Hence, having the possibility to build them later on (outside an injection context) would be very cool.

This will be supported by injectQueries which I will re-implement before the first non-experimental release. This will also be in an injectionContext - or using the manually passed injector.

Furthermore, I don't even see the benefits of having to build them inside an injection context, what does it brings positively? I would much prefer having something like this

I have the feeling this need results from imperative code? Can you tell me more about why you'd want this?

[jmleep]

I really love how simple this is to use. It would probably be useful to see an example that exists in a service as most Angular devs are going to be using that as a simple way to manage things like API calls and global state in their applications.

Any updates on when stable is going to be released?

[NetanelBasal]

Try https://github.com/ngneat/query

[arnoud-dv]

Thank you @jmleep, great to hear that!

I'd say at this point what is left to do:

• redo injectQueries
• injectInfiniteQuery. I am working on this at the moment including docs and examples.
• examples more representative of real-world applications including services. This also serves as validation for the public API of Angular Query.
• SSR needs to be tested.

"when" is hard to say but expect at least a few more weeks. I tried to do as much as possible at the end of the year when I had some time off but I'm working full time again now so I can only work in the weekends and evenings on Angular Query.

It's open source so anyone can help out. What would help me the most at the moment is feedback on the public API of Angular Query and testing and reporting any bugs.

[Xample]

@NetanelBasal it's another projet / another thread, but I'm experimenting both project to see which one is most suitable. My concern yet is to see which one works best with the Signals. While ngneat/query works like a charm with observables, the injection context seems not to work as expected. What people need is an easy way to fetch data based on signals (the new angular's signal input), and get a query based on that input. However, this requires to create a signal holding the result at some point. And to create that one, we need to provide an injector (which I did not manage to make it work yet). We could cheat keeping the service's injector and use it to create the signal but we would be unsubscribing on the service's lifecircle instead of the component or directive one.

[JulienLecoq]

refetch method could be named fetch instead. It would be more appropriate to what it does and be less verbose, since in the case that you have a query which is not enabled, refetch is just a simple fetch.

Example:

query = injectQuery(() => ({
  enabled: false,
  queryKey: ["test"],
  queryFn: () => 1,
}))

query.refetch() // Does not make sense, it's just a fetch, not a refetch.

"Improved version":

query = injectQuery(() => ({
  enabled: false,
  queryKey: ["test"],
  queryFn: () => 1,
}))

query.fetch() // Makes more sense.

[JulienLecoq]

Make a version of the query that works with errors as values. Errors as values are recently used more and more and are recognised as a better pattern to manage errors. They allow to have typed errors, compared to thrown error that are "unknown" as gotten in a catch block. They allow to immediately see that a function can return an error, compared to thrown errors that are invisible from the function signature. And allow other powerful/better things than thrown errors.
Imho, thrown errors should be avoided as much as possible and returned errors be used instead.

Some popular libraries already started to use returned errors instead of thrown ones.

Example from Supabase documentation:

Since this kind of error handling is becoming more and more popular, I would like to have a version of injectQuery that handles errors like so instead of having to throw errors in the queryFn. This would remove the annoying thing of having to create wrappers to manage this kind of cases.

[hichemfantar]

What exactly is the different between this and ngneat/query?

[bjesuiter]

This is an official adapter where the dev connects closely with the devs of tanstack/query.
ngneat/query on the other hand is basically a 3rd party implementation of tanstack/query for angular and since it started earlier, it's a little more feature rich. But the dev behind it did not want to publish it's adapter under the @TanStack umbrella but to put it under his own umbrella @ngneat.
Also, it's documentation is not as good, as I hoped.

I'm betting on this official adapter and beta-testing it, since I think, in the long run it's the better bet.

[ayush-sd]

@bjesuiter me and my company are also now trying to decide which adapter to use, did you finally figure out which one to use? Any problems you faced with either adapter so far?

[bjesuiter]

I'm now using the @tanstack/angular-query-experimental in production.
It's absolutely great.
It's very compatible with Angular Signals. And since it's based on the pure tan-stack query core, I have more hope that it will be nearer to the core of tanstack and not deviate too much.

I'm using it!

[IamSAL]

I'm a developer shifting to angular from react world. It'll genuinely be a great time saver handling out data-fetching responsibilities to query. I checked the code examples in the documentation, seems interfaces are same as react-query. I'll definitely adopt it in real projects as soon as it comes out of the experimental stage!

[johngrimsey]

Am trying AQ out now and really enjoying the reduction in boilerplate from NgRx (a library I love very much). This is great work! 🙏

[Kerrick]

This looks pretty great, and has been experimental for a while now. With no non-chore, non-release commits in about a month, it seems stable enough to release to me. Is there anything keeping the library experimental besides inertia? I'd love to know what blockers exist to marking it as "ready to use in production."

[riccardoperra]

I’m interested as well. We’ve used Angular Query for an experimental production app some months ago and it was “ready” (except for something like signal required input etc which was released in that time). I would like to introduce it in our bigger projects, but as it's experimental I'm not 100% sure

[hichemfantar]

@TkDodo Perhaps marking the integration as Beta instead of experimental will encourage people to use it more thus increasing the feedback loop and improving it faster.

[arnoud-dv]

Any chance you'd be willing to soften the tone of the disclaimer? Something like

Done

[jon9090]

@TkDodo:

In my opinion, people don't use it because it's still experimental. If it were an official release, it would likely see more usage. I'm not sure why it's still in this state, because every package should have a stable version released (the current package works fine). When there's a major breaking change, you should just update the main version to indicate a possible breaking change to users. I find it odd that after such a long time, with zero issues reported on this package in Angular, you're still waiting for feedback that isn't coming. People rarely provide feedback unless they're actively interested, which is uncommon in the GitHub community.

[TkDodo]

people don't use it because it's still experimental

yes, that's a problem, but I don't think the fix is to just mark it stable, but rather to get users to use it anyhow :)

If they don't want to use it - fine, then don't. If you want to use it, please do. I think comments like "I'm waiting for this to be stable so that I can FINALLY use it" are not helpful and just show that people don't understand how open source works (I'm not saying you said that btw).

@arnoud-dv posted a todo-list of his not too long ago, so we're definitely still in the "figuring it out phase". I'm happy that you have no issues with the adapter, so if that's the case - why is it a problem for you if it says "experimental" or not?

When there's a major breaking change, you should just update the main version to indicate a possible breaking change to users.

I think I already said that this isn't easily possible in a monorepo where we have react/vue/solid/svelte and now an angular adapter that all have to be on the same major version. The version of the query-core has to match the versions of the adapters. That's certainly a constraint, but that's how it is.

And frankly, we can't just make a major version bump for everybody just because we got something wrong in the angular adapter. It's (sadly) just not how it works. React Query has 5.3 million downloads per week, and this would seriously anger a lot of people because their automatic dependabot upgrades won't work anymore. Coincidentally, my talk at React Advanced later this year will touch on that topic, too :)

[arnoud-dv]

people don't use it

Compared to React Query it's rookie numbers but it's downloaded in the thousands a week. Except for injectQueries which needs work I would use it on production myself if accepting the possibility of API changes which the experimental naming is mostly about.

Todo list is public, PRs are open and people are contributing. Anyone who wants to collaborate on the adapter can contact me on Twitter or Discord. Also consider the Angular APIs this is built on are partly in developer preview.

you're still waiting for feedback that isn't coming

Feedback is still welcome but I'm in this stage not waiting for it to release a non-experimental.

you should just update the main version

I'd rather avoid breaking changes, we have way too much churn in the FE world as is. I am working on a solution for the fixed major version number. The main challenge here is supported Angular versions.

[ThiloAschebrock]

I have been using Angular query in medium sized projects for two months now and I am really enjoying it, especially that it is working with signals as opposed to observables. I am coming from a React background (including react query) and missed the ease of data fetching and handling that this library enables.

My only major struggle so far is the typing of CreateQueryResult, which makes it nearly impossible to use with generics and, thus, for building generic component, see TS playground example.

Even without a official plugin, persisting the cache with session storage using @tanstack/query-sync-storage-persister was surprisingly simple.

[NateRadebaugh]

@arnoud-dv is there anything published on the timeline and what's remaining to upgrade @tanstack/angular-query-experimental to non-experimental?

I'd like to avoid scrutiny from using something called "experimental" in production deployments.

[arnoud-dv]

Yes, see my answer from last week.

To the people pushing for a non-experimental release I would like to say see the experimental phase as an opportunity too. In this phase a lot more is possible to get to a very nice API and DX. Try it, test it, if you have any ideas share them. And PRs are open, multiple people have contributed already.

I think it's worth it as we'll all be benefiting from this for years to come.

[NateRadebaugh]

Thanks for the response. I see 5 todos in your comment from last week. And would be interested in spending some time making some movement on these.

1. Angular doesn't handle signal types well
   I think this is likely an Angular/Typescript level change that the Angular team is working to improve and shouldn't require updates to this library.

2. Inject function APIs will change
   Is there a proposal you're wanting feedback or implementation help on?

3. SSR doesn't work well
   Is SSR support strictly required for the initial stable release? I know Angular team is currently revamping support for SSR and streaming/hydration, so I'm wondering if the plan would be to wait until that work is more further flushed out by the framework, possibly not until post-ng18. Not sure if it's entirely broken if SSR is enabled, or whether it would gracefully fallback to client-side initial data fetching

4. InjectQueries doesn't work well
   Are there test failures or scenarios you want help investigating?

5. queryFn should support returning observables
   I think this PR is heading in the right direction you're talking about? feat(angular-query): added observable support #6726

[ghazi-git]

Great work with the adapter!! I love how it works seamlessly with signals. As for the feedback:

1. since it's still experimental, what do you think about renaming injectQuery?
   with the name containing the word "inject", it emphasizes too much dependency injection which is the norm in angular. Also, the fact that injectQuery provides a reactive context for signals was surprising to me (in a good way of course). Somehow, I didn't expect a function that emphasizes injection to be reactive, and it seems to me the guest in this youtube video felt the same way. As for a new name, I would suggest just query, it sounds similar to other signal API names (effect, model, input, ...). Another option is to just emphasize the reactive context more in the docs. Right now, that is mainly mentioned at the end of the query keys page. Highlighting it from the quick start example would be great.

2. How do I implement an autocomplete scenario that involves observables and uses injectQuery?
   Most angular codebases still use observables today, that's why I'm trying to figure out how to get that to work with angular query. In this example, I next into a subject on input change, then make an API call after a debounce. However, I am not sure how to set the input value as part of the query key?

click to see the example code

import {Component, inject,} from '@angular/core'
import {injectQuery,} from '@tanstack/angular-query-experimental'
import {debounceTime, fromEvent, lastValueFrom, Subject, switchMap, takeUntil} from 'rxjs'
import {HttpClient} from "@angular/common/http";

@Component({
  selector: 'address',
  standalone: true,
  template: `<input (input)="setInputValue($event)">`,
})
export class AddressComponent {
  subject: Subject<string> = new Subject()
  setInputValue($event: any) {
    this.subject.next($event.target.value);
  }

  #http = inject(HttpClient)
  addressQuery = injectQuery(() => ({
    queryKey: ['address'],  // <--- I want to add the search value here
    queryFn: ({signal}) => {
      return lastValueFrom(
        this.subject.pipe(
          debounceTime(250),
          switchMap((value) => {
            return this.#http
              .get<any[]>(`https://some-url-that.returns/addresses`, {params: {search: value}})
              .pipe(takeUntil(fromEvent(signal, 'abort')))
          }),
        )
      )
    },
  }))
}

[arnoud-dv]

Thank you, feedback on the public API is especially helpful as API design is really difficult.

1. I've had pretty much the same thoughts recently. query is probably a better name and in general shorter names are preferable. Disadvantage is that Angular already has a query function in @angular/animations. Most Angular applications will have it added as default dependency by ng new or create-nx-workspace. IDEs will suggest both functions as import and that will get annoying.

2. Set up an RxJs stream as normal, use toSignal to derive a signal, feed that to queryKey and probably queryFn.

In your example there’s no need to setup a subject or have a complicated observable in the queryFn. I’ll add a simpler example tomorrow. Key with rxjs, signals and Tanstack query is for code to be as declarative as possible.

[ghazi-git]

thank you for taking the time to respond.

1. yeah, it's quite unfortunate that angular already exposes query as part of its public API. On the other hand, I realized that it's actually nice that angular query functions all start with inject, they get listed together once you start typing

vscode autocomplete example

vscode_autocomplete.mp4

2. Just to clear why I set up a subject there. The main idea is to explore the easiest path to integrate angular query in a codebase that relies mainly on observables and rxjs operators. There are 2 main cases I have to consider:
   • the first is an observable chain that starts with a behavior subject (or a source with an initial value), then triggers an API call. Your toSignal suggestion makes it quite easy to introduce angular query and leverage its goodness.
   • the second is an observable chain that starts with a subject (or a source that doesn't emit until an event happens), then triggers an API call. The problem here is that toSignal is eager, so it will trigger the API call as soon as I call it. For this case, my goal is to find the easiest way to integrate angular query given the below code (hopefully without having to completely ditch the observable chain). btw, I found out about toLazySignal from ngextension but it has the same issue as toSignal since the signal would be read in the template.

code using observables

@Component({
  selector: 'posts1',
  standalone: true,
  template: `
    <input (input)="setInputValue($event)">
    <h1>Results</h1>
    <p *ngFor="let post of posts$|async">{{post.title}}</p>
  `,
  imports: [AsyncPipe, CommonModule]
})
export class Posts1Component {
  #http = inject(HttpClient);
  subject: Subject<string> = new Subject()
  posts$ = this.subject.pipe(
    debounceTime(100),
    switchMap(value => {
      const url = `https://jsonplaceholder.typicode.com/posts`
      const params = {search: value};
      return this.#http.get<any[]>(url, {params})
    })
  )

  setInputValue($event: any) {
    this.subject.next($event.target.value);
  }
}

[arnoud-dv]

I think it's best to have two separate observables.

1. The one from HttpClient, that's used inside queryFn.
2. One with debounce and resulting in the search parameter. If you derive this from Angular's built-in valueChanges Forms observable you won't need a subject. This should be converted into a signal using toSignal and given to queryKey and queryFn can pass this to a function that invokes HttpClient.

To prevent the API call from triggering too soon you can simply set enabled to false so then you won't need debounceTime in posts$. Using a signal or an inline expression accompanying one such as enabled: searchParam() !== '' it will then be set to enabled automatically at the moment you want that.

[ghazi-git]

thank you very much, that solves the issue

[ciekawy]

as I got interested in Angular Query, seeing I am getting signal in a response I actually thought, expected that this is obvious natural way for dynamic parameters to get handled, so I can have sort of dynamic query where I can get the output signal in advance and by providing dynamic param value, the signal would get updated with the response....

[nothendev]

It's amazing! But SSR not being officially implemented is kind of a pain point.

Posting a solution (this is for an @NgModule based app):

1. Put this in your app.module.server.ts's @NgModule definition

  providers: [
    {
      provide: BEFORE_APP_SERIALIZED,
      useFactory: (doc: Document) => {
        return () => {
          const script = doc.createElement('script');
          script.innerText = `window.__QUERY_STATE__ = ${JSON.stringify(dehydrate(queryClient))}`;
          doc.head.appendChild(script);
        };
      },
      deps: [DOCUMENT],
      multi: true,
    },
  ],

Imports are:

import { BEFORE_APP_SERIALIZED } from '@angular/platform-server';
import { queryClient } from './app.module';
import { dehydrate } from '@tanstack/angular-query-experimental';
import { DOCUMENT } from '@angular/common';

2. Define queryClient in app.module.ts and provide it:

export const queryClient = new QueryClient();

// ...
@NgModule({
  // ...
  providers: [
    // ...
    provideAngularQuery(queryClient)
  ],
  // ...
})
export class AppModule {}

3. Put this in your main.ts before the bootstrapModule call:

import { queryClient } from './app/app.module'
import { hydrate } from '@tanstack/angular-query-experimental';

// @ts-ignore
if (window.__QUERY_STATE__) {
  // @ts-ignore
  const state: any & {} = window.__QUERY_STATE__;
  hydrate(queryClient, state);

  console.log('hydrated QueryClient successfully', state);
}

Also, why was hiding the actual injection token necessary? You could just define ɵprov like TransferState did but like:

QueryClient.ɵprov = ɵɵdefineInjectable({
  token: QueryClient,
  providedIn: 'root',
  factory: () => new QueryClient(),
})

[jhk-mjolner]

I've been trying to use this, just experimentally to learn, and I feel a typical use case is slightly less ergonomical/simple than I had hoped. It works, but I was hoping I could simplify it further.

The situation is:

1. I want to reuse queries, and my component should know/care as little about the query creation as possible, so the creation of the query should be put into a function somewhere (raw exported, static on a class, or on an injected service).
2. I have queries that require a parameter.
3. I want both the query creation function, and the component using the query creation function to not care about the details of where the parameter was acquired. E.g. it shouldn't care or know about the ActivatedRoute.

Number 3 means I will likely bind the id into the component either using @Input() or an input signal.
injectQuery can only be called in an injection context, and the bound input value will only be available in ngOnInit or later.
By the time ngOnInit has run, no "natural" injection context is available afaik. That is, both the constructor and field initializers have already run. And I'd like to avoid manually handling an Injector.

I have found something that works, but is slightly less ergonomical/simple than I'd like.
I can create static or service functions that encapsulate creation of the query, but because they must be called before the bound id value is available, they must take a signal containing the value or undefined instead.
I can then use the enabled callback to check if the signal has a non-undefined value, and enable the query when it has.

The query creation looks like this:

export class SomeQueries {
  static someQuery(someId: Signal<string | undefined>) { // I'd like to avoid "| undefined"
    const backendService = inject(BackendService); // some code-generated service for calling the backend
    return injectQuery(() => ({
      queryKey: ['someQuery', someId()],
      queryFn: () => lastValueFrom(backendService.getSomeResource(someId()!)), // I'd like to avoid the !
      enabled: () => someId() !== undefined, // I'd like to avoid this check, if possible
    }));
  }
}

And usage:

@Component({...})
export class SomeComponent {
  someId = input<string>();
  someQuery = SomeQueries.someQuery(this.someId);
}

Is this the recommended way of handling this case?
Can the enabled callback be avoided somehow? Or must it be used every time I have a query with a parameter that isn't known at compile-time?
Can I avoid using ! or similar to tell the query function that someId now has a value?
Is there a way to take a signal in my query creation function without undefined? Using input.required<string>() to ensure it has a value will throw runtime errors about the signal being required but the value not being available yet. I guess it's just a limitation from the late binding of Angular's change detection. It's my impression that React's prop passing doesn't have this issue.

[arnoud-dv]

Later, an innocent developer introduces Component B and uses the same query (and crucially same query key), but modifies the behavior, maybe even disables the query until some component-specific condition is met.

If the query instance would be disabled that would just be the instance in that component, another instance in another component wouldn't be affected. So it's exactly what you'd want. Especially when using queryOptions I do not see value in building abstractions over injectQuery, it just complicates matters.

[nothendev]

@jhk-mjolner

Will 3. happen in that scenario? Or is Component A somehow protected from modifications to the query it used?

yep :)
Also i think for "global ish data" (meaning data that would be used in more than 2 pages/routes) you should use the Tracked approach with some service like ApiService that'd contain that observable and related logic.

For example the project i snipped Tracked from i have KenosService which does api stuff. And contains site which is a huge object that has:

1. user details
2. stuff for navbar, title and favicon (site name, icon, etc.)

And having it centralized makes sense, but that kind of data fetching would occur once or twice in the entirety of your app

[jhk-mjolner]

@arnoud-dv @nothendev Fantastic! That settles it, for me: using injectQuery in the component is better.

@ciekawy Yeah, I'm all for signals where an observable isn't necessary. My concern in the above was about introducing TanStack Query in an existing project with Observables, where it would be preferable to adapt the codebase slowly, replacing observables with signals one by one, and not have one change force too much other change. But the case I've found here still seems fairly small and manageable.

[arnoud-dv]

Also i think for "global ish data" (meaning data that would be used in more than 2 pages/routes) you should use the Tracked approach with some service like ApiService that'd contain that observable and related logic.

A huge benefit of TanStack Query is that you don't need to worry about situations like this. Just inject the query at two places. Request deduplication and caching will take care of this. This alone allows removing a ton of code and complexity.

[ciekawy]

A huge benefit of TanStack Query is that you don't need to worry about situations like this. Just inject the query at two places. Request deduplication and caching will take care of this. This alone allows removing a ton of code and complexity.

just the queries in majority do have parameters and main point of using signal is to have the data updated as the parameters change.

[GurovDmitriy]

why does no one give production examples of use. since examples are described in the documentation, they are written only on the fence. In the real world, I do not want to take a tool and use it in components, make several levels of abstraction and see if your tool is good, if it integrates well into the framework. make at least an example of todoApiService, todoQueryService, todoService,
on the component side, create a presentation model using the domain todoService, why should the client in the person of the component depend on the query tool, the domain layer todoService should not distinguish between working with api or query...

[BThomann]

Would love to see a "real live" example on the queryOptions factory pattern. Currently we are using a pattern similar the to one from @PhillipNinan that works good for us.

I can not see whats the advantage of using the queryOptions pattern over the one where you also call the injectQuery Function inside the service. One would maybe be if you want to modify some options for a single query!?

[arnoud-dv]

I can not see whats the advantage of using the queryOptions pattern over the one where you also call the injectQuery Function inside the service.

queryOptions can be used not just in queries but also APIs like queryClient.invalidateQueries. You'd lose that when calling injectQuery and returning the result.

One would maybe be if you want to modify some options for a single query!?

Yes, you can just spread the object and override a property.

[BThomann]

Not sure if it was already mentioned somewhere but I just read this article by @TkDodo on queryOptions: https://tkdodo.eu/blog/the-query-options-api and now it made click in my head and I now get the point why this has an advantage! I also like this queryOptions Factory pattern. Will have to give it a try.

But not sure if its better of in a service or with standalone functions that use the injection function for the http services inside of each query option generator?

Wondering what's the best approach to reuse mutations though? Currently I am using a similar service approach like for injectQuery.

[GurovDmitriy]

this division into functions is useless. are you familiar with oop, cleanArch? you must have an abstraction and an implementation. it's not serious. getTasksForPlayer is a public method for the client, the client should not know about the implementation, and you directly throw the tan result out of the function. now everything - your service, js in the component, js in the template is tightly coupled and depends on the implementation. you just pulled the code apart into functions. this is not design. It's not OOP or FP. you only have procedures.

[BThomann]

Well... for sure you could introduce some layers of abstraction here like move the http client to a standalone service that does just that. But as this is an example on how to possible use angular query I would not be to harsh on some implementation details.

Other than that you could abstract away the tanstack query result by using your own result object and run everything behind a facade. This can then get very tedious (speaking of experience) because the tanstack query library is quit neatly typed.

So in some way if you would like to use that library (because of obvious benefits) or any other lib at some point you will have to introduce some sort of coupling. And I would not say that the division into functions or queryOptions is useless - rather the opposite.

[buffos]

I have worked with Tanstack query for Angular for a little bit, and it is a great tool. Below I will add what I think should be added in the API to make easier and more natural to work with

1. The main "problem" with query.data() signal is that when it updates, it is set to undefined and then back to a value. This will cause the UI to flash (especially tables). This is more apparent when the query depends on signals and it chances reactively. What I do now every single time is the following

resolvedData = ReturningType[] = []
resolvedDataSignal = computed(() => {
    if (this.myInjectedQuery.data()) {
      this.resolvedData = this.myInjectedQuery.data()!;
    }
    return this.resolvedData ;
  });

Now I use the resolvedDataSignal instead of the data() signal.

** Proposal 1 **
Introduce the resolvedData signal in the api and also initialResolvedData. That way we do not have to worry about stale data of initialData, and it actually does what the user expects. Have the resolved data without getting in and out of undefined state

2. BeforeStart, OnSuccess and OnError hooks

I have a global service to notify loading (this.loadingService.start("message")). This sets some signals to make global loading available.
Initially, before adding tanstack, those calls were before and after each http call. Adding tanstack introduced errors, since those requests are now made inside the query, which is obviously some effect or computed signal and throws errors about writeable signals.

For this reason I had to move them to the query level and that is fine. The problem now is that there is no signal to stop loading so I have to to the following (I can also add a finally clause to stopLoading, but that's fine)

 queryFn: async () => {
      loadingService.startLoading('Loading customer bookings...');
      try {
        const bookings = await customerService.getCustomerBookings(
          customer_id(),
          limit(),
          offset(),
          isCancelled ? isCancelled() : undefined,
        );
        loadingService.stopLoading();
        return bookings;
      } catch (error) {
        loadingService.stopLoading();
        return Promise.reject([]);
      }
    },

This works ok but its not pretty. It would be much nicer to have separate hooks for pre , onSuccess and onError hook functions

I did not have any other issues so far.

[BThomann]

Point number 1 seems interesting did not notice that behavior in my apps - could you provide a minimal example that shows that behavior ?

To point number 2: I did not use it my self but it seems there is already a global error handling via the QueryCache available see:

• https://tanstack.com/query/latest/docs/reference/QueryCache
• https://medium.com/@valerasheligan/how-to-handle-global-errors-in-react-query-v5-4f8b919ee47a

You could also provide some meta information like here: https://tkdodo.eu/blog/automatic-query-invalidation-after-mutations#use-the-meta-option Its a different use case but could be adapted.

But if you want to do It on query level I guess you have to do something in the query function.

[buffos]

• For point 2, I didn't notice the QueryCache and it looks very very good. I will look into it
• For point 1. For example

export function injectCustomerListQuery(limit: Signal<number>, offset: Signal<number>, filter: Signal<string>) {
  const customerService = inject(CustomerService);
  const loadingService = inject(LoadingService);

  return injectQuery(() => {
    return {
      queryKey: customerKeys.allCustomers(limit(), offset(), filter()),
      queryFn: async () => {
        loadingService.startLoading('Loading customers...');
        try {
          const customers = await customerService.getCustomers(limit(), offset(), filter());
          loadingService.stopLoading();
          return customers;
        } catch (error) {
          loadingService.stopLoading();
          return Promise.reject([]);
        }
      },
      staleTime: staleTime,
      retry: retry,
    };
  });
}

• I feed the results to a CustomDataSource for material tables. When the signals change, the table flashes because you get a new key, which is of course undefined, and wait to get resolved. You will not notice the flashes for something that is very minor, but for a table the flashes are very annoying.
• The try catch blocks were inserted because the loading service changes a signal and had to be removed from the actual call that was initially close (I was getting an error about writing signals inside a compute or effect)

Having a resolved state and a resolved initial state will simply solve all the problems, because the resolvedState would not be key dependent but a general blanket of the query. And we will have an initialResolved State that will be replaced as soon as a new resolved state is there

For example, we have the query key ["customers", 1 ,1] , where 1,1 are some parameters. The InitialresolvedState is set to []. and the resolvedState is undefined ?? InitialresolvedState. When and IF the query resolves, the resolvedState will get a new value.
Now we change the key to ["customers", 1 ,2] there is no change in resolvedState until the query resolves and we get a new value

This is at least my solution to all be tables. Make a computed that does exactly that, but it would be better to avoid the repetition and have it inside the project.

[BThomann]

Ah now I understand your "problem". So basically it works as expected - new query key, new request, new loading state new data.

Have you already looked into using maybe placeholder data for that. This example from the react docs: https://tanstack.com/query/latest/docs/framework/react/guides/placeholder-query-data#placeholder-data-as-a-function
seems like its what you want tough. Disclaimer: had not yet the possibility to check if it also works for the Angular adapter already.

[buffos]

Yes. It works as expected. I am just proposing adding those two states to the query to make it seamless.
I find myself reimplementing the following code and seems logical to create a seamless transition. It does not break anything, just expands the API

resolvedData = ReturningType[] = []
resolvedDataSignal = computed(() => {
    if (this.myInjectedQuery.data()) {
      this.resolvedData = this.myInjectedQuery.data()!;
    }
    return this.resolvedData ;
  });

Writing code for the placeholder is more work than pasting those lines in every pieces I use inject query.
I just thought to share my experience and my solution to the problem I had.

[BThomann]

Writing code for the placeholder is more work than pasting those lines in every pieces I use inject query.

Why more work? It seems to be a one liner in the example I linked. It seems to solve the issue you have or am I wrong?

I also think it's going to be hard to get something into the QueryOptions core api "just" for an Angular use case.

[moxaj]

I have 2 questions:

First, how do I wait for a value to arrive and do something with it once the view has been rendered? For now, I have:

  injector = inject(Injector)
  apis = injectQuery(...)

  constructor() {
    afterNextRender(() => {
      toObservable(this.apis.data, { injector: this.injector })
        .pipe(
          filter((apis) => apis !== undefined),
          first()
        )
        .subscribe((apis) => {
          if (!apis) {
            return
          }
      
          // ...
        })
    })
  }

Feels a bit too complicated.

Second, say I have

  foo = injectQuery(() => ({
    queryKey: ['foo'],
    queryFn: () => 'foo',
  }))

and another value bar which depends on the value of foo. What is the best way to initialize bar?

Option 1 (built in computed):

  bar1 = computed(() => (!this.foo.isSuccess() ? undefined : 'bar'))

The problem with this is that if undefined would be a valid value for bar, then I cannot differentiate between that and the loading state (unless I use foo.status).s

Option 2 (ngxtension library):

  bar2 = derivedAsync(() =>
    toObservable(this.foo.data).pipe(
      filter((data) => data !== undefined),
      map((data) => 'bar')
    )
  )

I think this is functionally the same, and has the same issue with undefined.

Option 3 (dependant query):

  bar3 = injectQuery(() => ({
    queryKey: ['bar'],
    queryFn: () => 'bar',
    enabled: !!this.foo.data(),
  }))

I don't think queries are meant to be used with regular derived values, so this one feels like a hack, but at least it has the nice status API.

[moxaj]

@arnoud-dv I see you've given the thumbs up for that answer, could you please then clarify these in the documentation (assuming you are the one responsible for them)?

[BThomann]

How would you like the docs to be clarified? Any suggestions?

One thing I learned: a lot of things that can be done in react (where the documentation is more mature and there are more blogs etc online) can be transferred to the Angular world. So don't be fully focused on Angular when searching for solutions in Angular (Tanstack) Query.

[arnoud-dv]

One thing I learned: a lot of things that can be done in react (where the documentation is more mature and there are more blogs etc online) can be transferred to the Angular world.

Yes it was my intention when developing the Angular adapter to stay close to the React Query API and its reactive principles while also integrating well with Angular signals. So yeah Angular signals are very different from how React works but APIs are similar between the Angular and React adapters and ideas about reactive programming should transfer well.

[moxaj]

I think it should mention how you can make a synchronous operation depend on a value from injectQuery. Right now the only example is a follow-up http request.

And, reading the react docs, I realize this is pretty much the same in react land:

const { data: user } = useQuery({
  queryKey: ['user', email],
  queryFn: getUserByEmail,
})

const userId = user?.id

Here, if for some reason the id can be undefined, then some information is lost at user?.id. Is the value actually undefined, or did the parent request fail / is it still pending? For the query, this is encoded at the type level, it's like a monad, and if it had a map operation, you could map the user query to userId, and then you could do

if (userId.isSuccess()) { .. }

without having to know that userId depended on a specific query.

[arnoud-dv]

I think it should mention how you can make a synchronous operation depend on a value from injectQuery

No different from other signals: create a computed, or effect if you need to perform a side effect like calling imperative code.

then some information is lost at user?.id

It's not lost, it's in the original query result. If you choose to build an abstraction over that it's hidden behind the abstraction yes. I would generally not recommend that. It would mean hiding types and functionality as well which you will then probably need to re-implement.

[rbalet]

Hi @arnoud-dv.

I'm currently migrating from @ngneat/query to your library.
Appart from this small issue, the migration has been smooth and easy to understand. Big thanks for the excellent work! ❤️

Now that you're handling signal — which was the main reason I originally chose the ngneat library — I was wondering: have you considered reaching out to the ngneat/query maintainer, to see if he'd be interested in collaborating on your library instead, and potentially marking his as deprecated?

Thanks again for all your efforts!

[arnoud-dv]

I was wondering: have you considered reaching out to the ngneat/query maintainer, to see if he'd be interested in collaborating on your library instead

PRs are open for everybody so he's welcome if he wants to collaborate.

[hoangvutruong513]

Hello @arnoud-dv, really really appreciate your hard work on this Angular adapter for Tanstack Query. I was lucky enough to start a new Angular project and immediately jumps onto this train the moment I saw the documentation. Happy to report that I have encountered 0 production bugs so far, and the app itself is a huge internal enterprise application.

This library has dramatically changed the way I approached state management in general, and asynchronous state management in particular.

Angular devs tend to over-burden ourselves with services injecting/co-ordinating other services, and worrying about at which layers should we load/fire our request to make sure our data is available. Also using a bunch of RxJs operators like distinctUntilChanged, debounceTime, switchMap, tap to perform repetitive tasks like debouncing, de-duping requests, setLoading, setError, etc. So happy that I no longer have to think so much about those things with Angular/Tanstack Query.

The built-in query-key cache management, request de-dup/cancellation, active/inactive query management on component mount/unmount (via injection context), etc have been amazing to work with. I am honestly impressed with the perfect balance between declarative and imperative APIs available to developers.

Big kudos to you and the team's work. Look forward to next stage of the library, graduation from experimental!

[moxaj]

How do you test query data? In my unit tests (jest), my query is stuck in pending state. Things I've tried:

• fixture.detectChanges()
• TestBed.flushEffects()
• the experimental await component.query.promise()
• manually refetching the query with await component.query.refetch()

The only thing that works is manually waiting for some arbitrary duration:

fixture.detectChanges()
await new Promise((r) => setTimeout(r, 1000))

but obviously, that's super brittle (fails with 500ms for example).

FWIW, as per https://tanstack.com/query/latest/docs/framework/react/guides/testing#our-first-test, in react you can simply do:

await waitFor(() => result.current.isSuccess)

[arnoud-dv]

A testing guide needs to be written (that's also an invitation to anyone who wants to do that).

For now I would suggest to look at the Angular adapters own tests. It uses Vitest but APIs of Vitest and Jest are almost the same.

The Angular team is working on making testing signals easier, so keep an eye out on any updates on signal testing in general.

[moxaj]

@arnoud-dv those tests were very helpful! The trick for me was:

// component created, data is still undefined
fixture.detectChanges()
tick()
TestBed.flushEffects()
// now status is 'success' and data is available

[wilson-webdev]

I found that this worked when using with Spectator and Jest.

spectator.detectChanges();
await jest.advanceTimersToNextTimerAsync();

[Kibadango13]

Is there any update on a stable version? I'm eager to use this in my application.

[arnoud-dv]

Made a lot of progress recently, keep an eye on the issues - I'll add one about how to get to stable within a few days.

[moxaj]

Angular 19 is introducing an experimental resource function:

@Component(...)
export class UserProfile {
  userId = input<number>();

  userService = inject(UserService);

  user = resource({
    request: this.userId,
    loader: async ({request: id}) => await userService.getUser(id),
  });
}

The resulting Resource instance, which exposes signals that communicate both the value (when available) as well as the current status of the resource (loading, resolved, errored, etc).

This looks an awful lot like injectQuery, so I wonder how this is going to affect this library. Probably not too much in the short term, as without all the useful middleware (retries, caching, invalidation, etc.) it's very barebones.

[moxaj]

enabled and skipToken feel a bit awkward to use when checking for falsy values. In the official example:

  todosQuery = injectQuery(() => ({
    queryKey: ['todos', this.filter()],
    queryFn: this.filter() ? () => fetchTodos(this.filter()) : skipToken,
  }))

The compiler doesn't know when the queryFn would be called, so it cannot deduce that this.filter() would still be truthy value, so you would have to check again inside queryFn:

  todosQuery = injectQuery(() => ({
    queryKey: ['todos', this.filter()],
    queryFn: !this.filter()
      ? skipToken
      : () => {
          const filter = this.filter()
          if (!filter) {
            throw new Error('yikes')
          }

          return fetchTodos(filter)
        },
  }))

But since the argument given to injectQuery is already a function, maybe you could do this?

  todosQuery = injectQuery(() => {
    const filter = this.filter()
    return !filter
      ? { queryFn: skipToken } // Can I omit queryKey?
      : {
          queryKey: ['todos', filter],
          queryFn: () => fetchTodos(filter),
        }
  })

At which point, if skipToken is only ever used here, you could rename it to something like skipQuery and do:

  todosQuery = injectQuery(() => {
    const filter = this.filter()
    return !filter
      ? skipQuery
      : {
          queryKey: ['todos', filter],
          queryFn: () => fetchTodos(filter),
        }
  })

[BThomann]

I guess this would be a good usecase for the Query Options API? You could do something like this:

function todosQueryOptions(filter: string | undefined) {
  return queryOptions({
    queryKey: ['todos', filter],
    queryFn: filter ? () => fetchTodos(filter) : skipToken
  });
}

const todosQuery = injectQuery(() => todosQueryOptions(filter()));

This a pretty neat solution and typed well.

[moxaj]

@BThomann I think this is functionally equivalent to my 3rd example, no? queryOptions simply returns whatever is passed to it, as per the docs, and also it's for cases when you want to reuse stuff (which isn't true for this case).

At the very least, I think the docs should be improved, as fetchTodos(this.filter()) is very likely wrong: the definition for fetchTodos isn't there, but I don't believe it would accept nullish values, and if it would, why would you disable the query?

[BThomann]

Yes its an adaption of your third option. I am just a fan of the query options API and move them to a service like one would do also for the http client.

Thats ah valid observation with the docs I guess I would be much appreciated if you could create a PR with your suggested improvements 👍🏻

[arnoud-dv]

I think the docs should be improved, as fetchTodos(this.filter()) is very likely wrong: the definition for fetchTodos isn't there

I attempted to create real implementations of all the code examples in the docs to validate them but it was just too much. If you find that an example doesn't work, a PR is welcome!