TypeScript guidelines: Add Derive types from authoritative sources guideline - #178
Open
MajorLift wants to merge 4 commits into
Open
TypeScript guidelines: Add Derive types from authoritative sources guideline#178MajorLift wants to merge 4 commits into
Derive types from authoritative sources guideline#178MajorLift wants to merge 4 commits into
Conversation
MajorLift
changed the title
Derive types from authoritative sources guidelineDerive types from authoritative sources guideline
Two failure modes the subsection did not yet cover, both from reviewing a real JS→TS migration: - The restatement is not always *wider*. Where it is narrower, it is usually because a `| undefined` was dropped — which erases the compiler's record of why a runtime guard exists, so the guard reads as dead code and gets deleted in the same edit, with nothing reported. - The risk peaks where the compiler *cannot* contradict the guess: a JS caller (`checkJs` is off) or a value arriving as `any` means a hand-written parameter type is checked against nothing and can drift indefinitely. Partially-migrated modules are full of these boundaries. Adds a second example showing both together: the parameter's real type is already named in a JSDoc annotation at the call site, the conversion drops its `| undefined`, and the default parameter that handled the nullable case is removed alongside it.
MajorLift
force-pushed
the
jongsun/typescript/derive-from-authoritative-types
branch
from
July 30, 2026 13:21
12a2c8f to
3c9b1bb
Compare
… statements "Almost always wider", "the most common way", and "usually a dropped `| undefined`" are distributional claims made from a single observed migration. One of them is contradicted by a case in the same evidence set: a generic result pinned to one concrete type is a narrowing that involves no nullability at all. States the two directions a restatement can miss without ranking them, gives three examples of the narrower direction rather than one presented as typical, and turns the deleted-guard consequence into a conditional rather than a tendency.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds a
Derive types from authoritative sources instead of re-declaring themsubsection to the Type Inference section.The section already covers preferring inference for values and avoiding accidental widening, but not the common case (especially with AI) of hand-writing a type that restates one an authoritative source already defines.
Includes counterexamples.
Note
Low Risk
Documentation-only change to internal TypeScript guidelines; no runtime or build behavior.
Overview
Adds a Type Inference subsection, Derive types from authoritative sources instead of re-declaring them, to
docs/typescript.md. It tells contributors to use indexed access,typeof,ReturnType/Parameters, andPick/Omit/Partialinstead of hand-written types that duplicate controller state, package exports, or other canonical shapes.The text covers duplication, overly wide or narrow restatements (including dropped
| undefinedand “dead” guards), drift when the source changes, and extra risk at JS/anyboundaries where restated parameter types are never checked. Two 🚫/✅ examples showRecord<string, unknown>and casts vsTokenListState, and a JS caller withStorageShape | undefinedvs a narrowed parameter that invites removing a default.A small formatting tweak adds a blank line before a bullet under Avoid
any.Reviewed by Cursor Bugbot for commit b87151f. Bugbot is set up for automated code reviews on this repo. Configure here.