Published and updated 31 July 2026 · TypeScript Foundations
Published and updated 31 July 2026 · TypeScript Foundations
TypeScript Foundations: Model Values, Functions, and Valid States connects the essential decisions in this stage of frontend engineering. You will learn each browser or framework model from first principles, apply it to the progressive Learning Atlas product, diagnose a realistic failure from evidence, and direct an AI collaborator with explicit constraints. The goal is independent judgment, not memorized syntax.
You will advance a typed data layer for Learning Atlas. By the end, you can explain every topic in this chapter, implement one focused slice per topic, adapt those slices under new constraints, and defend the result with browser evidence, strict types, accessibility checks, security boundaries, and a production build.
Bring forward learning-atlas/src/learning.ts and tsconfig.json and the verification notes from the preceding chapter. Create a narrow Git branch, read the repository rules, and inspect existing changes before editing. When a tool or file is introduced for the first time, its purpose is explained before its syntax.
Use these project-orientation commands:
Before beginning TypeScript Foundations: Model Values, Functions, and Valid States, stop if the working tree contains files you do not understand. Do not delete, reset, or rewrite another person's work to make the lesson cleaner.
A type is an executable agreement about the shapes and states your code accepts. TypeScript moves many disagreements from a user's browser into the editor and build, where they are cheaper to understand and repair. The topics below are ordered because each creates evidence needed by the next. Experienced readers may jump to a topic, but should still complete its failure investigation and adaptation task.
TypeScript checks relationships before code reaches a user. Its value is not decorating variables; it is making assumptions about data, states, component contracts, and refactors visible and searchable across the program.
The current artifact for why typescript changes frontend engineering is learning-atlas/src/learning.ts. Before editing, predict the visible behavior and name the source of truth. Then implement or study this complete focused slice:
Scenario: An API returns null for an optional field, but a broad interface marks it as a string and the page crashes only for one production record.
Evidence to collect: Inspect the raw boundary value, generated or declared type, strict compiler settings, narrowing path, and the production stack at the first invalid assumption.
Minimal repair rule: For why typescript changes frontend engineering, correct the first boundary that violates the documented model, preserve the rest of the working path, and add a regression check based on the observed evidence.
Model one real API response with absent, null, success, and error cases, then make the compiler reject an unhandled state.
Types describe what callers may provide and what a function or component guarantees in return. Name types at durable boundaries, let local inference reduce noise, and make illegal combinations difficult to construct.
The current artifact for types for values, functions, objects, and component contracts is learning-atlas/src/contracts.ts. Before editing, predict the visible behavior and name the source of truth. Then implement or study this complete focused slice:
Scenario: A progress component accepts negative completed lessons and a total of zero, producing a misleading percentage and inaccessible label.
Evidence to collect: Trace values from caller to prop type to calculation, test boundary numbers, and decide whether validation or a richer domain type owns the invariant.
Minimal repair rule: For types for values, functions, objects, and component contracts, correct the first boundary that violates the documented model, preserve the rest of the working path, and add a regression check based on the observed evidence.
Design a component contract for progress that addresses zero totals, invalid counts, labels, and user actions without exposing internal state.
A discriminated union gives each valid state a stable tag and state-specific data. Narrowing proves which member is present; an exhaustive switch makes a new state a compile-time decision instead of an accidental blank screen.
The current artifact for unions, narrowing, discriminated states, and exhaustiveness is learning-atlas/src/state.ts. Before editing, predict the visible behavior and name the source of truth. Then implement or study this complete focused slice:
Scenario: The server adds a partial-success state, but the client falls through to the loading branch and announces that loading never ends.
Evidence to collect: Inspect the network payload, discriminant values, switch branches, unreachable helper, and tests for every state tag.
Minimal repair rule: For unions, narrowing, discriminated states, and exhaustiveness, correct the first boundary that violates the documented model, preserve the rest of the working path, and add a regression check based on the observed evidence.
Add a stale-data state carrying both cached items and a warning; update rendering so the compiler identifies every missing decision.
A generic preserves a relationship between inputs and outputs when the concrete type varies. Utility types transform existing contracts. Use them when they clarify a repeated relationship; prefer a direct named type when abstraction hides domain meaning.
The current artifact for generics, utility types, inference, and when not to be clever is learning-atlas/src/collections.ts. Before editing, predict the visible behavior and name the source of truth. Then implement or study this complete focused slice:
Scenario: A reusable table generic accepts any string key through an assertion, so a misspelled column renders empty cells with no compiler error.
Evidence to collect: Remove assertions, inspect inferred key types at each call, test heterogeneous values, and compare the generic API with two explicit domain components.
Minimal repair rule: For generics, utility types, inference, and when not to be clever, correct the first boundary that violates the documented model, preserve the rest of the working path, and add a regression check based on the observed evidence.
Build an indexById helper that preserves item types, then write a domain case where a generic would make the call site harder to understand.
Modules define runtime and type dependency boundaries. Package exports, module resolution, declaration files, and tsconfig options must agree with the actual runtime. A type error is evidence about a broken relationship, not an obstacle to suppress.
The current artifact for modules, third-party types, tsconfig, and debugging type errors is learning-atlas/tsconfig.json. Before editing, predict the visible behavior and name the source of truth. Then implement or study this complete focused slice:
Scenario: The editor resolves a package's types while the production runtime cannot import the same path because the package export map forbids it.
Evidence to collect: Compare package exports, import path, moduleResolution, emitted or bundled output, Node runtime, lockfile version, and the production error.
Minimal repair rule: For modules, third-party types, tsconfig, and debugging type errors, correct the first boundary that violates the documented model, preserve the rest of the working path, and add a regression check based on the observed evidence.
Turn on one stricter compiler option, classify every new error by root cause, and repair boundaries without assertions or ignore directives.
Goal: Advance a typed data layer for Learning Atlas through one learning outcome at a time while keeping the implementation understandable and reversible.
Context to attach: the current typescript foundations outcome, the product brief, repository rules, package versions, relevant files and callers, shared types or tokens, the current Git diff, and the latest observed failure or command output.
Constraints: while advancing a typed data layer for Learning Atlas, preserve concurrent work; use semantic HTML and strict TypeScript; keep Server Components as the default in Next.js; validate untrusted data on the server; do not expose secrets; include loading, empty, error, success, disabled, and partial states when relevant; make one bounded change.
Acceptance criteria: the typescript foundations adaptation works from 320 pixels upward; keyboard and focus behavior are complete; color is not the only signal; authorization and validation are enforced at authoritative boundaries; the relevant type, lint, build, and browser checks pass.
Reusable prompt:
We are implementing one outcome from “TypeScript Foundations: Model Values, Functions, and Valid States” in the Learning Atlas. Read the attached repository rules, outcome text, relevant files, current diff, and verification evidence. Restate the user-visible result, source of truth, trust boundary, valid states, and unknowns. Propose the smallest reversible vertical slice. Implement only that slice. Then report the exact diff, criterion-to-evidence mapping, remaining risks, and the next discriminating check. Stop before dependency installation, destructive action, public-contract change, authentication decision, or deployment unless explicitly authorized.
For TypeScript Foundations: Model Values, Functions, and Valid States, inspect the response without relying on its summary. Read every changed line, compare it with the actual source of truth, and reproduce the evidence yourself. Reject unexplained assertions, broad client boundaries, missing states, invented APIs, suppressed errors, or tests that merely restate implementation details.
An unvalidated API value is asserted into a success type, then a new union state renders as loading forever. Trace unknown input, narrowing, discriminant, exhaustive branch, and compiler evidence. Write exact reproduction steps and expected versus observed behavior. Follow the value across every relevant boundary until you find the first contradiction.
Within the explain stage of TypeScript Foundations: Model Values, Functions, and Valid States, change one cause, not several symptoms. Rerun the original reproduction, one adjacent failure case, keyboard navigation, and the focused static checks. The lab is complete only when you can explain why the repair works and which regression check would have failed before it.
Run the scripts that this project actually defines:
If your learning project later defines a test script, run it as an additional gate; do not report tests as passing when no test command exists. In the browser, run the strict type checker, deliberately pass invalid data, and confirm the error points to the broken contract. Repeat the primary journey at 320, 768, and wide desktop widths, at 200% zoom, in both themes, by keyboard, and with reduced motion. For networked work, simulate slow, malformed, unauthorized, empty, and failed responses.
Close TypeScript Foundations: Model Values, Functions, and Valid States and draw its models from memory. Pick two outcomes and explain how a decision in the first can cause a failure in the second. Then complete three levels of practice:
You have treated typescript foundations as a connected engineering system rather than isolated syntax. The durable result is not the example code; it is the ability to predict behavior, expose assumptions, collect evidence, bound AI work, and repair the first broken boundary. Carry the product files and evidence log into the next stage.