geekskai Logogeekskai
ToolsBlogPricing
Sign in
Sign in
ToolsBlogSign in
Sunday, September 22, 2024|5.205Mins Read

Rename TypeScript Fields: Source Refactoring, Mapped Types and JSDoc

Authors
  • avatar
    Name
    Geeks Kai
    Twitter
    @KaiGeeks
Discuss on Twitter • View on GitHub

Tags

typescriptrefactoringjsdoccode-maintenanceprogramming

Previous Article

CSS :first-child Best Practices with Tailwind CSS Examples

Next Article

Check if a Key Exists in JavaScript: Own vs Inherited Properties
← Back to the blog
geekskai Logo
geekskai

Public tools for developers and creators, plus optional Geekskai Audio Toolkit plans. Built with care.

Popular Tools

SoundCloud DownloaderSoundCloud to MP3SoundCloud to WAVSoundCloud PlaylistSoundCloud Artwork
View All Tools

Resources

BlogAbout MePricingTagsProjectsPrivacy PolicyTerms of ServiceRefund Policy

Connect With Us

mailMail
githubGitHub
twitterTwitter
linkedinLinkedin
© 2026 geekskai • All rights reserved

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.

Rename the source property with the language service

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.

A mapped type is a new type, not a runtime rename

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.

Check source comments, types and editor documentation separately

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
QuestionWhat 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.

When custom tooling is justified

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.

Frequently asked questions

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.

References

  • VS Code: Rename Symbol and refactoring preview
  • TypeScript: key remapping in mapped types
  • TypeScript: indexed access types
  • TypeScript: Pick utility type
  • TypeScript: JSDoc reference
  • TypeScript 6.0.3 language-service interfaces