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.

[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.

[arnoud-dv]

1. I will look into adding support for observables / HttpClient as it is the standard. Using overloads and not requiring the dev to think about this would be preferable I think.

2. Yes, an example specifically on using NgModules would be nice. The other examples should be all standalone components in my opinion. After it's merged to main we can also start accepting PR's for examples and other improvements.

[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.

[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

[Kerrick]

Most of those seem like improvements that could be made in a “post-experimental” phase, since none (except maybe the last one?) seem like showstoppers. Never let perfect be the enemy of good. May I suggest just removing the experimental flag so more people can use & contribute to it?

[TkDodo]

if you're post experimental, you can't make breaking API changes anymore. That's literally all the experimental postfix does. Angular Query would be bound to the lifecycle of the whole Query monorepo, which means all breaking changes would need to go into v6 (which we have no plans of doing right now).

so getting the API interface right is crucial. It's (somewhat) understandable that the -experimental flag makes some people not use it, but for everyone here on this thread it should be clear that if we take the code as it is right now, and do nothing but remove the -experimental post-fix, that doesn't make it any more "stable" in terms of runtime bugs or being "battle-tested".

So if you're interested in angular-query and want to help it succeed - use it now in the experimental state and help us get the API right. Because if we make it "stable" now, and then you use it and find out that something doesn't work as expected for your use-case, we might not be able to change it that easily anymore :)

[Kerrick]

At some companies, "Use at your own risk" in a disclaimer makes it a non-starter (even though we developers know that's how all third-party code goes, and even though that's also basically what the MIT license says). Any chance you'd be willing to soften the tone of the disclaimer? Something like:

VERY IMPORTANT: This library is currently in an experimental stage. This means that breaking changes will happen in minor AND patch releases. Upgrade carefully. If you use this production in an experimental stage, please lock your version to a patch-level version to avoid unexpected breaking changes.

More people able to use the library means more feedback (and maybe contributions), which is good for everybody.

[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

[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