typescript-type-safety

# Represent State in TypeScript Types ## Use when Values change together, optional fields hide different states, outside input enters typed code, or the compiler asks for an assertion. Each of these signals a missing type or a missing check. ## Gates 1. Does each valid state have its own type, such as a member of a discriminated union? 2. Does outside input enter as `unknown`, and pass a type guard or a schema before use? 3. Is the code free of `any`, non-null assertions, and casts, except `as const`? 4. Does each switch over a union handle each member, so that a new member fails to compile? 5. Does a failure that callers must handle appear in the return type? ## Process 1. Name the valid states and the moves between them. Use a discriminated union when only some field combinations are valid. 2. Keep the relation between keys and values with generics, mapped types, or a typed setter. 3. Accept outside input as `unknown`. Check it at the boundary with a schema or a type guard. 4. Narrow values with control flow, type guards, or destructuring. Make a valid absence explicit. 5. Return a type that makes callers handle each meaningful failure. 6. Run the type check, and run the tests for the boundary checks. ## Example **Situation:** A function reads a config file and casts the parsed JSON to `Config`. **Easy route:** Keep the cast, because the file usually has the right shape. **Hidden cost:** A config file with one wrong field passes the cast. The program fails later, far from the cause. **Best route:** Parse the JSON with a schema at the boundary. Return a clear error that names the field. **Evidence:** A test with a wrong field type now fails at the boundary with "sources.git-metadata: expected boolean". The type check passed with no cast left. ## Guardrails - Keep one source of truth for each discriminator. - Keep literal types until a wider type is necessary. - Put an imprecise library type in one adapter that returns a precise project type. - Use a narrow assertion only for a fact that a runtime check cannot express, and write down why. - Follow the stricter rules of the repository where they apply. ## Completion - The type that now rejects the invalid state. - One example that the compiler now rejects, with its error line. - The type check command and the boundary test command, with their result lines.