Documenting Angular 20+ Signals: Derived Selectors, Mutators, and Analytics Hooks Hiring Teams Can Trust

Why Document Signals in Angular 20+

The Minimum Viable Documentation Contract

Keep it boring and predictable. That’s what passes enterprise review and what I set up on AngularUX projects.

A Documented SignalStore Example

import { signalStore, withState, withComputed, withMethods, withHooks } from '@ngrx/signals';
import { computed, effect, signal } from '@angular/core';
import { inject } from '@angular/core';
import { FirebaseAnalytics } from '@angular/fire/analytics';

export interface Driver { id: string; name: string; score: number; lastTripMs: number }

interface UiEvent {
  name: 'filter_applied' | 'driver_upserted';
  params: Record<string, string | number | boolean>;
}

function logEvent(analytics: FirebaseAnalytics, e: UiEvent) {
  // Centralize to enforce naming, sampling, and PII policy
  // @sampling 10% production, 100% staging
  // @pii none — do not include names; use ids only
  analytics.logEvent(e.name, e.params);
}

const SAFE_SCORE = 80;

export const DriverStore = signalStore(
  withState({
    drivers: [] as Driver[],
    filter: '',
    lastUpdated: Date.now(),
  }),
  withComputed(({ drivers, filter }) => ({
    /**
     * @selector Safe drivers meeting threshold
     * @derivedFrom drivers, filter
     * @usage DriverTableComponent, SafeDriverChart
     * @perf O(n)
     */
    selectSafeDrivers: computed(() => {
      const q = filter().toLowerCase();
      return drivers().filter(d => d.score >= SAFE_SCORE && d.id.toLowerCase().includes(q));
    }),

    /**
     * @selector Highcharts/PrimeNG series derived from safe drivers
     * @derivedFrom selectSafeDrivers
     * @example chart opts consume: { name: 'Safe', data: selectChartSeries() }
     */
    selectChartSeries: computed(() => {
      return drivers().filter(d => d.score >= SAFE_SCORE).map(d => ({ name: d.id, y: d.score }));
    }),
  })),
  withMethods((store) => ({
    /**
     * @mutator Update filter used by listings and charts
     * @invariant filter length <= 50
     * @example setFilter('abc')
     */
    setFilter(q: string) {
      store.filter.set(q.slice(0, 50));
    },

    /**
     * @mutator Upsert driver by id
     * @invariant score: 0..100; lastUpdated monotonic
     * @example upsertDriver({ id:'d-1', score:92, name:'hidden', lastTripMs: 123 })
     */
    upsertDriver(d: Driver) {
      store.drivers.update(cur => {
        const i = cur.findIndex(x => x.id === d.id);
        const next = i >= 0 ? [...cur.slice(0, i), d, ...cur.slice(i + 1)] : [...cur, d];
        store.lastUpdated.set(Date.now());
        return next;
      });
    },
  })),
  withHooks((store) => ({
    /**
     * @analytics Track filter changes for funnel analysis
     * @derivedFrom filter
     * @pii none
     */
    onInit() {
      const analytics = inject(FirebaseAnalytics);
      effect(() => {
        const q = store.filter();
        if (q) logEvent(analytics, { name: 'filter_applied', params: { q_len: q.length } });
      });

      effect(() => {
        store.lastUpdated(); // dependency to catch upserts
        logEvent(analytics, { name: 'driver_upserted', params: { count: store.drivers().length } });
      });
    }
  }))
);

<!-- Example consumer: PrimeNG table + chart -->
<p-table [value]="store.selectSafeDrivers()"></p-table>
<p-chart type="bar" [data]="{ datasets: [{ label: 'Safe', data: store.selectChartSeries() }] }"></p-chart>

README.state.md Template Reviewers Skim

# Drivers State (SignalStore)

- Purpose: present safe-driver KPIs and tables
- Shape: drivers[], filter, lastUpdated
- Derived Selectors:
  - selectSafeDrivers — derivedFrom: drivers, filter — used by: table, chart
  - selectChartSeries — derivedFrom: selectSafeDrivers — used by: chart
- Mutators:
  - setFilter(q) — invariant: q.length <= 50
  - upsertDriver(driver) — invariant: score 0..100, lastUpdated monotonic
- Analytics Hooks:
  - filter_applied — pii: none — sampling: 10% prod
  - driver_upserted — pii: none — sampling: 10% prod
- Testing: see driver.store.spec.ts for selector/mutator cases
- Performance: Angular DevTools shows derived chain depth=2, 0 dropped frames @ 60fps

CI Guardrails for Documentation

// .eslintrc.json (excerpt)
{
  "overrides": [
    {
      "files": ["**/*.ts"],
      "plugins": ["jsdoc"],
      "rules": {
        "jsdoc/require-jsdoc": ["error", {
          "publicOnly": true,
          "contexts": [
            "TSMethodSignature[name=/^(set|update|upsert|patch)/]",
            "MethodDefinition[key.name=/^(set|update|upsert|patch)/]",
            "PropertyDefinition[key.name=/^select/]"
          ]
        }]
      }
    }
  ]
}

// typedoc.json
{
  "entryPoints": ["libs/drivers/state/index.ts"],
  "tsconfig": "tsconfig.base.json",
  "includeVersion": true,
  "sort": ["source-order"],
  "plugin": [],
  "readme": "none"
}

# .github/workflows/docs.yml
name: docs
on: [pull_request]
jobs:
  typedoc:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v3
        with: { version: 9 }
      - run: pnpm install --frozen-lockfile
      - run: pnpm nx run drivers-state:lint
      - run: pnpm typedoc
      - uses: actions/upload-artifact@v4
        with:
          name: state-docs
          path: docs

How an Angular Consultant Documents Signals State

When to Hire an Angular Developer for Legacy Rescue

If you’re mid‑migration to Signals or wrestling with NgRx/Signals hybrids, bring in an Angular expert early. We’ll preserve velocity while restoring review confidence.

Measurable Outcomes and Next Steps