feat(Angular-query): add Angular auto-refetching example

examples/angular/auto-refetching/.devcontainer/devcontainer.json

@@ -0,0 +1,4 @@
+{
+  "name": "Node.js",
+  "image": "mcr.microsoft.com/devcontainers/javascript-node:18"
+}

examples/angular/auto-refetching/.eslintrc.cjs

@@ -0,0 +1,6 @@
+// @ts-check
+
+/** @type {import('eslint').Linter.Config} */
+const config = {}
+
+module.exports = config

examples/angular/auto-refetching/README.md

@@ -0,0 +1,6 @@
+# TanStack Query Angular auto-refetching example
+
+To run this example:
+
+- `npm install` or `yarn` or `pnpm i` or `bun i`
+- `npm run start` or `yarn start` or `pnpm start` or `bun start`

examples/angular/auto-refetching/angular.json

@@ -0,0 +1,104 @@
+{
+  "$schema": "./node_modules/@angular/cli/lib/config/schema.json",
+  "version": 1,
+  "cli": {
+    "packageManager": "pnpm",
+    "analytics": false,
+    "cache": {
+      "enabled": false
+    }
+  },
+  "newProjectRoot": "projects",
+  "projects": {
+    "auto-refetching": {
+      "projectType": "application",
+      "schematics": {
+        "@schematics/angular:component": {
+          "inlineTemplate": true,
+          "inlineStyle": true,
+          "skipTests": true
+        },
+        "@schematics/angular:class": {
+          "skipTests": true
+        },
+        "@schematics/angular:directive": {
+          "skipTests": true
+        },
+        "@schematics/angular:guard": {
+          "skipTests": true
+        },
+        "@schematics/angular:interceptor": {
+          "skipTests": true
+        },
+        "@schematics/angular:pipe": {
+          "skipTests": true
+        },
+        "@schematics/angular:resolver": {
+          "skipTests": true
+        },
+        "@schematics/angular:service": {
+          "skipTests": true
+        }
+      },
+      "root": "",
+      "sourceRoot": "src",
+      "prefix": "app",
+      "architect": {
+        "build": {
+          "builder": "@angular-devkit/build-angular:application",
+          "options": {
+            "outputPath": "dist/auto-refetching",
+            "index": "src/index.html",
+            "browser": "src/main.ts",
+            "polyfills": ["zone.js"],
+            "tsConfig": "tsconfig.app.json",
+            "assets": ["src/favicon.ico", "src/assets"],
+            "styles": [],
+            "scripts": []
+          },
+          "configurations": {
+            "production": {
+              "budgets": [
+                {
+                  "type": "initial",
+                  "maximumWarning": "500kb",
+                  "maximumError": "1mb"
+                },
+                {
+                  "type": "anyComponentStyle",
+                  "maximumWarning": "2kb",
+                  "maximumError": "4kb"
+                }
+              ],
+              "outputHashing": "all"
+            },
+            "development": {
+              "optimization": false,
+              "extractLicenses": false,
+              "sourceMap": true
+            }
+          },
+          "defaultConfiguration": "production"
+        },
+        "serve": {
+          "builder": "@angular-devkit/build-angular:dev-server",
+          "configurations": {
+            "production": {
+              "buildTarget": "auto-refetching:build:production"
+            },
+            "development": {
+              "buildTarget": "auto-refetching:build:development"
+            }
+          },
+          "defaultConfiguration": "development"
+        },
+        "extract-i18n": {
+          "builder": "@angular-devkit/build-angular:extract-i18n",
+          "options": {
+            "buildTarget": "auto-refetching:build"
+          }
+        }
+      }
+    }
+  }
+}

examples/angular/auto-refetching/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@tanstack/query-example-angular-auto-refetching",
+  "type": "module",
+  "scripts": {
+    "ng": "ng",
+    "start": "ng serve",
+    "build": "ng build",
+    "watch": "ng build --watch --configuration development"
+  },
+  "private": true,
+  "dependencies": {
+    "@angular/common": "^17.3.12",
+    "@angular/compiler": "^17.3.12",
+    "@angular/core": "^17.3.12",
+    "@angular/platform-browser": "^17.3.12",
+    "@angular/platform-browser-dynamic": "^17.3.12",
+    "@tanstack/angular-query-experimental": "^5.61.1",
+    "rxjs": "^7.8.1",
+    "tslib": "^2.6.3",
+    "zone.js": "^0.14.8"
+  },
+  "devDependencies": {
+    "@angular-devkit/build-angular": "^17.3.8",
+    "@angular/cli": "^17.3.8",
+    "@angular/compiler-cli": "^17.3.12",
+    "typescript": "5.3.3"
+  }
+}

examples/angular/auto-refetching/src/app/app.component.ts

@@ -0,0 +1,11 @@
+import { ChangeDetectionStrategy, Component } from '@angular/core'
+import { AutoRefetchingExampleComponent } from './components/auto-refetching.component'
+
+@Component({
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  selector: 'app-root',
+  standalone: true,
+  template: `<auto-refetching-example />`,
+  imports: [AutoRefetchingExampleComponent],
+})
+export class AppComponent {}

examples/angular/auto-refetching/src/app/app.config.ts

@@ -0,0 +1,37 @@
+import {
+  HTTP_INTERCEPTORS,
+  HttpClientModule,
+  provideHttpClient,
+  withFetch,
+} from '@angular/common/http'
+import {
+  QueryClient,
+  provideTanStackQuery,
+  withDevtools,
+} from '@tanstack/angular-query-experimental'
+import { importProvidersFrom } from '@angular/core'
+import { MockApiInterceptor } from './interceptor/mock-api.interceptor'
+import type { ApplicationConfig } from '@angular/core'
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideHttpClient(withFetch()),
+    provideTanStackQuery(
+      new QueryClient({
+        defaultOptions: {
+          queries: {
+            gcTime: 1000 * 60 * 60 * 24, // 24 hours
+          },
+        },
+      }),
+      withDevtools(),
+    ),
+    // Registers the MockApiInterceptor for simulating API calls
+    {
+      provide: HTTP_INTERCEPTORS,
+      useClass: MockApiInterceptor,
+      multi: true,
+    },
+    importProvidersFrom(HttpClientModule),
+  ],
+}

examples/angular/auto-refetching/src/app/components/auto-refetching.component.html

@@ -0,0 +1,23 @@
+<div>
+  <h1>Auto Refetch with stale-time set to {{ intervalMs() }}ms</h1>
+  <p>
+    This example is best experienced on your own machine, where you can open
+    multiple tabs to the same localhost server and see your changes propagate
+    between the two.
+  </p>
+  <label>
+    Query Interval speed (ms):
+    <input [value]="intervalMs()" (input)="inputChange($event)" />
+  </label>
+  <h2>Todo List</h2>
+
+  <input placeholder="Enter something" (keydown.enter)="addItem($event)" />
+  <ul>
+    @for (item of tasks.data(); track item) {
+      <li>{{ item }}</li>
+    }
+  </ul>
+  <div>
+    <button (click)="clearTasks()">Clear All</button>
+  </div>
+</div>

examples/angular/auto-refetching/src/app/components/auto-refetching.component.ts

@@ -0,0 +1,58 @@
+import {
+  ChangeDetectionStrategy,
+  Component,
+  inject,
+  signal,
+} from '@angular/core'
+import {
+  injectMutation,
+  injectQuery,
+} from '@tanstack/angular-query-experimental'
+import { fromEvent, lastValueFrom, takeUntil } from 'rxjs'
+import { TasksService } from '../services/tasks.service'
+
+@Component({
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  selector: 'auto-refetching-example',
+  standalone: true,
+  templateUrl: './auto-refetching.component.html',
+  imports: [],
+})
+export class AutoRefetchingExampleComponent {
+  #tasksService = inject(TasksService)
+
+  intervalMs = signal(1000)
+
+  tasks = injectQuery(() => ({
+    queryKey: ['tasks'],
+    queryFn: async (context) => {
+      // Cancels the request when component is destroyed before the request finishes
+      const abort$ = fromEvent(context.signal, 'abort')
+
+      return lastValueFrom(
+        this.#tasksService.allTasks$().pipe(takeUntil(abort$)),
+      )
+    },
+    // Refetch the data every second
+    refetchInterval: this.intervalMs(),
+  }))
+
+  addMutation = injectMutation(() => this.#tasksService.addTask())
+  clearMutation = injectMutation(() => this.#tasksService.clearAllTasks())
+
+  clearTasks() {
+    this.clearMutation.mutate()
+  }
+
+  inputChange($event: Event) {
+    const target = $event.target as HTMLInputElement
+    this.intervalMs.set(Number(target.value))
+  }
+
+  addItem($event: Event) {
+    const target = $event.target as HTMLInputElement
+    const value = target.value
+    this.addMutation.mutate(value)
+    target.value = ''
+  }
+}

examples/angular/auto-refetching/src/app/interceptor/mock-api.interceptor.ts

@@ -0,0 +1,55 @@
+/**
+ * MockApiInterceptor is used to simulate API responses for `/api/tasks` endpoints.
+ * It handles the following operations:
+ * - GET: Fetches all tasks from localStorage.
+ * - POST: Adds a new task to localStorage.
+ * - DELETE: Clears all tasks from localStorage.
+ * Simulated responses include a delay to mimic network latency.
+ */
+import { Injectable } from '@angular/core'
+import { HttpResponse } from '@angular/common/http'
+import { delay, of } from 'rxjs'
+import type {
+  HttpEvent,
+  HttpHandler,
+  HttpInterceptor,
+  HttpRequest,
+} from '@angular/common/http'
+import type { Observable } from 'rxjs'
+
+@Injectable()
+export class MockApiInterceptor implements HttpInterceptor {
+  intercept(
+    req: HttpRequest<any>,
+    next: HttpHandler,
+  ): Observable<HttpEvent<any>> {
+    if (req.url === '/api/tasks') {
+      switch (req.method) {
+        case 'GET':
+          return this.respondWith(
+            200,
+            JSON.parse(localStorage.getItem('tasks') || '[]'),
+          ).pipe(delay(100))
+        case 'POST':
+          const tasks = JSON.parse(localStorage.getItem('tasks') || '[]')
+          tasks.push(req.body)
+          localStorage.setItem('tasks', JSON.stringify(tasks))
+          return this.respondWith(201, {
+            status: 'success',
+            task: req.body,
+          }).pipe(delay(100))
+        case 'DELETE':
+          localStorage.removeItem('tasks')
+          return this.respondWith(200, { status: 'success' }).pipe(delay(100))
+      }
+    }
+    return next.handle(req)
+  }
+
+  private respondWith(
+    status: number,
+    body: any,
+  ): Observable<HttpResponse<any>> {
+    return of(new HttpResponse({ status, body }))
+  }
+}

examples/angular/auto-refetching/src/app/services/tasks.service.ts

@@ -0,0 +1,50 @@
+import { HttpClient } from '@angular/common/http'
+import { Injectable, inject } from '@angular/core'
+import {
+  QueryClient,
+  mutationOptions,
+} from '@tanstack/angular-query-experimental'
+import { Observable, lastValueFrom, map, tap } from 'rxjs'
+
+@Injectable({
+  providedIn: 'root',
+})
+export class TasksService {
+  #queryClient = inject(QueryClient) // Manages query state and caching
+  #http = inject(HttpClient) // Handles HTTP requests
+
+  /**
+   * Fetches all tasks from the API.
+   * Returns an observable containing an array of task strings.
+   */
+  allTasks$ = () => this.#http.get<Array<string>>('/api/tasks')
+
+  /**
+   * Creates a mutation for adding a task.
+   * On success, invalidates and refetches the "tasks" query cache to update the task list.
+   */
+  addTask() {
+    return mutationOptions({
+      mutationFn: (task: string) =>
+        lastValueFrom(this.#http.post('/api/tasks', task)),
+      mutationKey: ['tasks'],
+      onSuccess: () => {
+        this.#queryClient.invalidateQueries({ queryKey: ['tasks'] })
+      },
+    })
+  }
+
+  /**
+   * Creates a mutation for clearing all tasks.
+   * On success, invalidates and refetches the "tasks" query cache to ensure consistency.
+   */
+  clearAllTasks() {
+    return mutationOptions({
+      mutationFn: () => lastValueFrom(this.#http.delete('/api/tasks')),
+      mutationKey: ['clearTasks'],
+      onSuccess: () => {
+        this.#queryClient.invalidateQueries({ queryKey: ['tasks'] })
+      },
+    })
+  }
+}