Documenting Signals State for Review: Derived Selectors, Mutators, and Analytics Hooks That Hiring Teams Can Trust (Angular 20+ with SignalStore)

A real scene from an upgrade review

A VP joined a review call asking why an analytics widget jittered on scroll and why our metrics disagreed with GA4. The team had great Signals usage—but no shared language for selectors, mutators, and analytics. We created a contract per store and the confusion disappeared in one sprint.

As companies plan 2025 Angular roadmaps

If you want to hire an Angular developer or bring in an Angular consultant, giving them documented state contracts reduces onboarding time and increases confidence in your codebase.

• Angular 20+ Signals and SignalStore are mainstream

• Hiring committees skim repos for clarity and risk

• Documentation that connects state → UI → telemetry is a differentiator

Three artifacts, one story

When these three are named, typed, and cross-linked, reviewers can follow business flows without reading every component. Add Angular DevTools traces and Firebase logs, and your story becomes verifiable.

• Selectors: what can I read?

• Mutators: how can I change state safely?

• Analytics hooks: how do changes show up in metrics?

Signals-specific expectations

In Angular 20+, I keep selectors pure and derived via computed, guard mutators with preconditions, and wire analytics as typed events fired from effects—not components.

• Derived selectors are computed and memoized

• Mutators are pure and side-effects are explicit (effects/commands)

• Zoneless-friendly change detection and stable signatures

1) Define the store contract

Start with a typed contract that mirrors how reviewers think: selectors, mutators, analytics. Use TSDoc tags to make TypeDoc generate a clean table.

• Treat the SignalStore as a public API

• Co-locate a README and generate TypeDoc

Code: Store contract + implementation (Angular 20, NgRx Signals)

// libs/employees/data-access/src/lib/employee.store.ts
import { signalStore, withState, withComputed, withMethods, patchState } from '@ngrx/signals';
import { computed, inject } from '@angular/core';
import { AnalyticsService, EmployeeClockedIn, ShiftAdjusted } from '../telemetry/analytics';

export interface EmployeeState {
  employees: Record<string, { id: string; name: string; role: 'agent'|'supervisor'; clockedIn: boolean; }>; 
  selectedId: string | null;
}

const initialState: EmployeeState = { employees: {}, selectedId: null };

/**
 * Store Contract
 * @selectors
 *  - selectAllEmployees: list of employees (sorted by name)
 *  - selectSelectedEmployee: the currently selected employee or null
 *  - selectClockedInCount: derived count of clocked-in employees
 * @mutators
 *  - setSelected(id): set selected employee
 *  - toggleClockedIn(id): toggle employee clock-in state
 *  - upsertEmployees(list): merge employees
 * @analytics
 *  - EmployeeClockedIn
 *  - ShiftAdjusted
 */
export const EmployeeStore = signalStore(
  { providedIn: 'root' },
  withState(initialState),
  withComputed((state) => ({
    /**
     * @selector selectAllEmployees
     * @derived sorted by name; memoized
     */
    selectAllEmployees: computed(() =>
      Object.values(state.employees()).sort((a, b) => a.name.localeCompare(b.name))
    ),
    /**
     * @selector selectSelectedEmployee
     */
    selectSelectedEmployee: computed(() =>
      state.selectedId() ? state.employees()[state.selectedId()!] ?? null : null
    ),
    /**
     * @selector selectClockedInCount
     * @derived cached count
     */
    selectClockedInCount: computed(() =>
      Object.values(state.employees()).filter(e => e.clockedIn).length
    ),
  })),
  withMethods((state) => {
    const analytics = inject(AnalyticsService);

    return {
      /**
       * @mutator setSelected
       * @precondition id must exist in employees
       * @postcondition selectedId updated; no analytics side-effect
       */
      setSelected(id: string) {
        if (!state.employees()[id]) throw new Error('Employee not found');
        patchState(state, { selectedId: id });
      },

      /**
       * @mutator toggleClockedIn
       * @sideEffects fires EmployeeClockedIn when changing to true
       */
      toggleClockedIn(id: string) {
        const emp = state.employees()[id];
        if (!emp) return;
        const next = { ...emp, clockedIn: !emp.clockedIn };
        patchState(state, { employees: { ...state.employees(), [id]: next } });
        if (next.clockedIn) {
          analytics.emit<EmployeeClockedIn>({
            name: 'EmployeeClockedIn',
            payload: { employeeId: id },
          });
        }
      },

      /**
       * @mutator upsertEmployees
       */
      upsertEmployees(list: EmployeeState['employees'][string][]) {
        const map = { ...state.employees() };
        for (const e of list) map[e.id] = e;
        patchState(state, { employees: map });
      }
    };
  })
);

2) Typed analytics hooks that mirror state

// libs/employees/data-access/src/lib/telemetry/analytics.ts
export type EmployeeClockedIn = {
  name: 'EmployeeClockedIn';
  payload: { employeeId: string };
  tenantId?: string; userId?: string; timestamp?: number;
};
export type ShiftAdjusted = {
  name: 'ShiftAdjusted';
  payload: { employeeId: string; minutes: number };
  tenantId?: string; userId?: string; timestamp?: number;
};
export type AppEvent = EmployeeClockedIn | ShiftAdjusted;

export class AnalyticsService {
  emit<T extends AppEvent>(evt: T) {
    // Bridge to Firebase Analytics or GA4; add defaults
    const enriched = { ...evt, timestamp: evt.timestamp ?? Date.now() };
    // window.gtag('event', enriched.name, enriched.payload) or Firebase logEvent
  }
}

Now your analytics stream and your store contract use the same names. During a review, a hiring manager can search the repo for “EmployeeClockedIn” and see selectors, mutators, tests, and GA4 dashboards line up.

• One union of events, emitted from effects/methods

• Attach tenant/user context and timestamps

3) Add store-level README with a review checklist

# EmployeeStore (Signals + SignalStore)

Owns: employee directory and selection.

Selectors
- selectAllEmployees: Employee[] — sorted by name
- selectSelectedEmployee: Employee | null
- selectClockedInCount: number

Mutators
- setSelected(id)
- toggleClockedIn(id)
- upsertEmployees(list)

Analytics
- EmployeeClockedIn(payload: { employeeId }) → GA4 event employee_clocked_in
- ShiftAdjusted(payload: { employeeId, minutes }) → GA4 event shift_adjusted

Review Checklist
- Are derived selectors pure and memoized? ✅
- Do mutators document side-effects? ✅
- Do analytics events map 1:1 to business flows? ✅

• What this store owns

• Selectors/mutators table

• Telemetry mapping and example dashboards

4) Automate docs and enforce in CI with Nx + TypeDoc

// tools/typedoc/typedoc.json
{
  "entryPoints": ["libs/employees/data-access/src/public-api.ts"],
  "out": "docs/employees",
  "tsconfig": "tsconfig.base.json"
}

# .github/workflows/ci.yml (excerpt)
name: ci
on: [push, pull_request]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 20 }
      - run: npm ci
      - run: npx nx affected -t lint,test,build
      - run: npx typedoc --options tools/typedoc/typedoc.json
      - name: Docs up-to-date
        run: git diff --exit-code docs || (echo "Docs changed. Commit generated docs." && exit 1)

This gives recruiters a /docs folder they can skim. For larger repos, I publish to GitHub Pages from CI.

• Generate TypeDoc from TSDoc tags

• Fail CI if docs are stale

• Lint naming patterns

5) Prove it works: tests + DevTools + Firebase Emulator

In IntegrityLens, I test derived selectors with deterministic fixtures and assert that mutators don’t emit analytics until postconditions are met. Cypress intercepts Firebase logEvent and verifies typed payloads. Angular DevTools confirms computed selectors aren’t recomputing on unrelated changes.

• Unit tests for selectors and mutators

• Cypress asserts analytics events via emulator

• Angular DevTools traces for derived selectors

Employee tracking (global entertainment)

We documented presence selectors (selectOnlineAgents, selectSupervisorsOnDuty), mutators (setShift, toggleBreak), and analytics (AgentOnBreak, ShiftStarted). Recruiters could trace a late-escalation bug from selector → mutator → GA4 in under 5 minutes.

• WebSocket presence updates

• Role-based selectors in multi-tenant contexts

• 99.98% uptime on gitPlumbers modernization work

Advertising analytics (telecom)

Derived selectors powered jitter-free charts in Highcharts, while analytics events like CampaignFilterChanged matched store mutators. The documentation parity made vendor audits painless.

• Data virtualization for 200k rows with PrimeNG

• Telemetry pipeline with typed event schemas

• Dashboards aligned with GA4 nomenclature

My 5-day onboarding pattern

If you need an Angular expert to formalize this quickly, this is the playbook I run as a remote Angular developer. It’s repeatable in Nx monorepos and compatible with Angular Material or PrimeNG UIs.

• Day 1: Inventory stores, name drift, and missing analytics

• Day 2: Add contracts + TSDoc + README for the top slice

• Day 3: Wire typed events and emulator tests

• Day 4: TypeDoc + CI gates + DevTools traces

• Day 5: Review with PMs and publish dashboards

Signals migration stalled or metrics don’t match

If any of these smell like your repo, hire an Angular developer with Fortune 100 experience to impose a standard without slowing delivery. The outcome is faster reviews, safer changes, and metrics your leadership trusts.

• Selectors are scattered in components

• Mutators have hidden side-effects

• Analytics events are unnamed or untyped

Expected timeline and outcomes

This mirrors what I’ve delivered on IntegrityLens (12k+ interviews), SageStepper (320+ communities, +28% score lift), and gitPlumbers (70% velocity increase).

• 2–4 weeks to standardize 4–6 stores

• CI + docs + emulator tests in place

• Visible in analytics within the first week

Naming

• Selectors: selectThing, selectDerivedMetric

• Mutators: setX, patchX, addX, removeX, toggleX

• Analytics: NounVerbPastTense (EmployeeClockedIn)

TSDoc tags

Keep tags consistent; your TypeDoc renders will look like an API spec.

• @selector, @derived, @mutator, @sideEffects, @precondition, @postcondition, @analytics

Component wiring

Use effects or store methods to fire analytics so you can test and refactor without touching UI code.

• Read selectors in components

• Call mutators from UI intents

• Never call analytics directly in components