Rename TypeScript Fields: Source Refactoring, Mapped Types and JSDoc
- Authors

- Name
- Geeks Kai
- @KaiGeeks
Three operations are easy to confuse: renaming a source symbol, defining a new type with a different property key, and displaying documentation in an editor. I check each separately. A missing hover description for a mapped property does not prove that a source rename deleted its JSDoc.
For a normal refactor, use your editor's Rename Symbol command on the property declaration and preview the references. In VS Code the default shortcut is F2. A symbol-aware rename can update typed references while leaving the adjacent JSDoc comment in place; duplicating the comment manually is not a prerequisite for every rename.
This is the complete starting file. The local firstName binding and the Person.firstName property share spelling but are different symbols.
person.ts
export interface Person {
/** The person's first name. */
firstName: string
/** The person's last name. */
lastName: string
}
export const firstName = "Ada"
export const person: Person = { firstName, lastName: "Lovelace" }
export const label = person.firstName + " " + person.lastName
Rename the property declaration to givenName. The following is the expected replacement for person.ts, not a second file. Notice that the shorthand object entry expands to givenName: firstName, preserving the local variable.
export interface Person {
/** The person's first name. */
givenName: string
/** The person's last name. */
lastName: string
}
export const firstName = "Ada"
export const person: Person = { givenName: firstName, lastName: "Lovelace" }
export const label = person.givenName + " " + person.lastName
The declaration comment still describes the same field, and the typed property access changes. Review the preview before applying it: JSON payloads, database columns, string-based lookups, generated clients and external consumers may need a separate migration. A source refactor alone does not migrate those contracts.
Key remapping with as changes the resulting type's property names. An indexed access such as OriginalPerson["firstName"] supplies a value type; it is not a general instruction to copy every documentation comment to a new property. Pick retains selected keys, while a newly declared givenName is a different case.
The following independent file keeps OriginalPerson available as the source type. The explicit adapter creates a runtime object with a givenName key. Writing a type alias alone would leave original.firstName unchanged.
derived-types.ts
export interface OriginalPerson {
/** The person's first name. */
firstName: string
/** The person's last name. */
lastName: string
}
export type RemappedPerson = {
[Key in keyof OriginalPerson as Key extends "firstName" ? "givenName" : Key]: OriginalPerson[Key]
}
export type IndexedPerson = Pick<OriginalPerson, "lastName"> & {
givenName: OriginalPerson["firstName"]
}
export interface DocumentedPerson {
/**
* The person's given name.
* @see OriginalPerson.firstName
*/
givenName: string
/** The person's last name. */
lastName: string
}
export const original: OriginalPerson = { firstName: "Ada", lastName: "Lovelace" }
export const picked: Pick<OriginalPerson, "firstName"> = original
// A type transformation does not rename the keys of the existing runtime object.
export const remapped: RemappedPerson = {
givenName: original.firstName,
lastName: original.lastName,
}
export const indexed: IndexedPerson = remapped
export const documented: DocumentedPerson = remapped
export const pickedName = picked.firstName
export const remappedName = remapped.givenName
export const indexedName = indexed.givenName
export const documentedName = documented.givenName
DocumentedPerson declares its own description for the public field. The @see target exists because OriginalPerson.firstName is still declared. By contrast, renaming Person.firstName away and leaving only @see Person.firstName creates a stale reference. @see is a documentation reference, not a command that universally inherits another symbol's hover text.
For a reproducible compiler check, install a fixed TypeScript version in a separate example directory. The files above use TypeScript 6.0.3 for this exercise; this is a version boundary, not a claim that every editor or later compiler behaves identically.
npm install --save-dev --save-exact [email protected]
npx tsc --strict --noEmit --target ES2022 --module ESNext --moduleResolution bundler person.ts derived-types.ts
| Question | What to inspect |
|---|---|
| Did Rename Symbol preserve the source comment? | The actual declaration and reviewed reference edits |
| Did references still type-check? | Compiler diagnostics after the rename |
| Does the language service return a description? | QuickInfo documentation and tags for each specific property |
| Does my editor show it? | The project's selected TypeScript version and the actual editor hover |
| Does a published declaration expose it? | The emitted .d.ts and the consumer's tooling; declaration emission may copy or omit different source material |
In the derived example, inspect picked.firstName, remapped.givenName, indexed.givenName and documented.givenName independently. Do not infer all four descriptions from their shared string type. Source comments, QuickInfo, emitted declarations and VS Code rendering are related evidence, but they are not the same output.
Start with the built-in rename preview for ordinary symbol changes. If a repeatable migration truly needs a custom tool, use the TypeScript language service or syntax tree, preserve comments, apply edits by source span, and type-check the result. A text-wide replacement can change unrelated symbols and external strings. A generic codemod is not necessary for this example.
Does TypeScript have a built-in rename mechanism? Its language service supports symbol rename and reference edits, which editors such as VS Code expose. That is different from guaranteeing documentation propagation for every derived type.
Does Pick rename firstName to givenName? No. Pick selects existing keys. The added givenName declaration in IndexedPerson uses the original field's value type; it does not by itself rename a runtime object.
Will @see restore a missing hover description? Do not rely on that. Keep the reference valid and write the new field's own documentation when readers need a dependable public description.
Does a successful compiler check prove my editor hover is correct? No. Check the actual editor and its selected TypeScript version. A fixed-version language-service test establishes that service's result, not every editor integration.