feat: add Angular NgRx best practices documentation
This commit is contained in:
Dennis Hundertmark
@@ -0,0 +1,305 @@
|
||||
---
|
||||
name: angular-signals
|
||||
description: Implement signal-based reactive state management in Angular v20+. Use for creating reactive state with signal(), derived state with computed(), dependent state with linkedSignal(), and side effects with effect(). Triggers on state management questions, converting from BehaviorSubject/Observable patterns to signals, or implementing reactive data flows.
|
||||
---
|
||||
|
||||
# Angular Signals
|
||||
|
||||
Signals are Angular's reactive primitive for state management. They provide synchronous, fine-grained reactivity.
|
||||
|
||||
## Core Signal APIs
|
||||
|
||||
### signal() - Writable State
|
||||
|
||||
```typescript
|
||||
import { signal } from "@angular/core";
|
||||
|
||||
// Create writable signal
|
||||
const count = signal(0);
|
||||
|
||||
// Read value
|
||||
console.log(count()); // 0
|
||||
|
||||
// Set new value
|
||||
count.set(5);
|
||||
|
||||
// Update based on current value
|
||||
count.update((c) => c + 1);
|
||||
|
||||
// With explicit type
|
||||
const user = signal<User | null>(null);
|
||||
user.set({ id: 1, name: "Alice" });
|
||||
```
|
||||
|
||||
### computed() - Derived State
|
||||
|
||||
```typescript
|
||||
import { signal, computed } from "@angular/core";
|
||||
|
||||
const firstName = signal("John");
|
||||
const lastName = signal("Doe");
|
||||
|
||||
// Derived signal - automatically updates when dependencies change
|
||||
const fullName = computed(() => `${firstName()} ${lastName()}`);
|
||||
|
||||
console.log(fullName()); // "John Doe"
|
||||
firstName.set("Jane");
|
||||
console.log(fullName()); // "Jane Doe"
|
||||
|
||||
// Computed with complex logic
|
||||
const items = signal<Item[]>([]);
|
||||
const filter = signal("");
|
||||
|
||||
const filteredItems = computed(() => {
|
||||
const query = filter().toLowerCase();
|
||||
return items().filter((item) => item.name.toLowerCase().includes(query));
|
||||
});
|
||||
|
||||
const totalPrice = computed(() =>
|
||||
filteredItems().reduce((sum, item) => sum + item.price, 0),
|
||||
);
|
||||
```
|
||||
|
||||
### linkedSignal() - Dependent State with Reset
|
||||
|
||||
```typescript
|
||||
import { signal, linkedSignal } from "@angular/core";
|
||||
|
||||
const options = signal(["A", "B", "C"]);
|
||||
|
||||
// Resets to first option when options change
|
||||
const selected = linkedSignal(() => options()[0]);
|
||||
|
||||
console.log(selected()); // "A"
|
||||
selected.set("B"); // User selects B
|
||||
console.log(selected()); // "B"
|
||||
options.set(["X", "Y"]); // Options change
|
||||
console.log(selected()); // "X" - auto-reset to first
|
||||
|
||||
// With previous value access
|
||||
const items = signal<Item[]>([]);
|
||||
|
||||
const selectedItem = linkedSignal<Item[], Item | null>({
|
||||
source: () => items(),
|
||||
computation: (newItems, previous) => {
|
||||
// Try to preserve selection if item still exists
|
||||
const prevItem = previous?.value;
|
||||
if (prevItem && newItems.some((i) => i.id === prevItem.id)) {
|
||||
return prevItem;
|
||||
}
|
||||
return newItems[0] ?? null;
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
### effect() - Side Effects
|
||||
|
||||
```typescript
|
||||
import { signal, effect, inject, DestroyRef } from '@angular/core';
|
||||
|
||||
@Component({...})
|
||||
export class Search {
|
||||
query = signal('');
|
||||
|
||||
constructor() {
|
||||
// Effect runs when query changes
|
||||
effect(() => {
|
||||
console.log('Search query:', this.query());
|
||||
});
|
||||
|
||||
// Effect with cleanup
|
||||
effect((onCleanup) => {
|
||||
const timer = setInterval(() => {
|
||||
console.log('Current query:', this.query());
|
||||
}, 1000);
|
||||
|
||||
onCleanup(() => clearInterval(timer));
|
||||
});
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Effect rules:**
|
||||
|
||||
- Run in injection context (constructor or with `runInInjectionContext`)
|
||||
- Automatically cleaned up when component destroys
|
||||
|
||||
## Component State Pattern
|
||||
|
||||
```typescript
|
||||
@Component({
|
||||
selector: "app-todo-list",
|
||||
template: `
|
||||
<input
|
||||
[value]="newTodo()"
|
||||
(input)="newTodo.set($any($event.target).value)"
|
||||
/>
|
||||
<button (click)="addTodo()" [disabled]="!canAdd()">Add</button>
|
||||
|
||||
<ul>
|
||||
@for (todo of filteredTodos(); track todo.id) {
|
||||
<li [class.done]="todo.done">
|
||||
{{ todo.text }}
|
||||
<button (click)="toggleTodo(todo.id)">Toggle</button>
|
||||
</li>
|
||||
}
|
||||
</ul>
|
||||
|
||||
<p>{{ remaining() }} remaining</p>
|
||||
`,
|
||||
})
|
||||
export class TodoList {
|
||||
// State
|
||||
todos = signal<Todo[]>([]);
|
||||
newTodo = signal("");
|
||||
filter = signal<"all" | "active" | "done">("all");
|
||||
|
||||
// Derived state
|
||||
canAdd = computed(() => this.newTodo().trim().length > 0);
|
||||
|
||||
filteredTodos = computed(() => {
|
||||
const todos = this.todos();
|
||||
switch (this.filter()) {
|
||||
case "active":
|
||||
return todos.filter((t) => !t.done);
|
||||
case "done":
|
||||
return todos.filter((t) => t.done);
|
||||
default:
|
||||
return todos;
|
||||
}
|
||||
});
|
||||
|
||||
remaining = computed(() => this.todos().filter((t) => !t.done).length);
|
||||
|
||||
// Actions
|
||||
addTodo() {
|
||||
const text = this.newTodo().trim();
|
||||
if (text) {
|
||||
this.todos.update((todos) => [
|
||||
...todos,
|
||||
{ id: crypto.randomUUID(), text, done: false },
|
||||
]);
|
||||
this.newTodo.set("");
|
||||
}
|
||||
}
|
||||
|
||||
toggleTodo(id: string) {
|
||||
this.todos.update((todos) =>
|
||||
todos.map((t) => (t.id === id ? { ...t, done: !t.done } : t)),
|
||||
);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## RxJS Interop
|
||||
|
||||
### toSignal() - Observable to Signal
|
||||
|
||||
```typescript
|
||||
import { toSignal } from '@angular/core/rxjs-interop';
|
||||
import { interval } from 'rxjs';
|
||||
|
||||
@Component({...})
|
||||
export class Timer {
|
||||
private http = inject(HttpClient);
|
||||
|
||||
// From observable - requires initial value or allowUndefined
|
||||
counter = toSignal(interval(1000), { initialValue: 0 });
|
||||
|
||||
// From HTTP - undefined until loaded
|
||||
users = toSignal(this.http.get<User[]>('/api/users'));
|
||||
|
||||
// With requireSync for synchronous observables (BehaviorSubject)
|
||||
private user$ = new BehaviorSubject<User | null>(null);
|
||||
currentUser = toSignal(this.user$, { requireSync: true });
|
||||
}
|
||||
```
|
||||
|
||||
### toObservable() - Signal to Observable
|
||||
|
||||
```typescript
|
||||
import { toObservable } from '@angular/core/rxjs-interop';
|
||||
import { switchMap, debounceTime } from 'rxjs';
|
||||
|
||||
@Component({...})
|
||||
export class Search {
|
||||
query = signal('');
|
||||
|
||||
private http = inject(HttpClient);
|
||||
|
||||
// Convert signal to observable for RxJS operators
|
||||
results = toSignal(
|
||||
toObservable(this.query).pipe(
|
||||
debounceTime(300),
|
||||
switchMap(q => this.http.get<Result[]>(`/api/search?q=${q}`))
|
||||
),
|
||||
{ initialValue: [] }
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
## Signal Equality
|
||||
|
||||
```typescript
|
||||
// Custom equality function
|
||||
const user = signal<User>(
|
||||
{ id: 1, name: "Alice" },
|
||||
{ equal: (a, b) => a.id === b.id },
|
||||
);
|
||||
|
||||
// Only triggers updates when ID changes
|
||||
user.set({ id: 1, name: "Alice Updated" }); // No update
|
||||
user.set({ id: 2, name: "Bob" }); // Triggers update
|
||||
```
|
||||
|
||||
## Untracked Reads
|
||||
|
||||
```typescript
|
||||
import { untracked } from "@angular/core";
|
||||
|
||||
const a = signal(1);
|
||||
const b = signal(2);
|
||||
|
||||
// Only depends on 'a', not 'b'
|
||||
const result = computed(() => {
|
||||
const aVal = a();
|
||||
const bVal = untracked(() => b());
|
||||
return aVal + bVal;
|
||||
});
|
||||
```
|
||||
|
||||
## Service State Pattern
|
||||
|
||||
```typescript
|
||||
@Injectable({ providedIn: "root" })
|
||||
export class Auth {
|
||||
// Private writable state
|
||||
private _user = signal<User | null>(null);
|
||||
private _loading = signal(false);
|
||||
|
||||
// Public read-only signals
|
||||
readonly user = this._user.asReadonly();
|
||||
readonly loading = this._loading.asReadonly();
|
||||
readonly isAuthenticated = computed(() => this._user() !== null);
|
||||
|
||||
private http = inject(HttpClient);
|
||||
|
||||
async login(credentials: Credentials): Promise<void> {
|
||||
this._loading.set(true);
|
||||
try {
|
||||
const user = await firstValueFrom(
|
||||
this.http.post<User>("/api/login", credentials),
|
||||
);
|
||||
this._user.set(user);
|
||||
} finally {
|
||||
this._loading.set(false);
|
||||
}
|
||||
}
|
||||
|
||||
logout(): void {
|
||||
this._user.set(null);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
For advanced patterns including resource(), see [references/signal-patterns.md](references/signal-patterns.md).
|
||||
Reference in New Issue
Block a user