Add RenameKeys type

[materwelonDhruv]

Renames one or more keys in an object type while preserving each value type and the ? / readonly modifiers. Distributes over union object types.

RenameKey is the single-key form; RenameKeys takes a map of old-to-new names for batch renames. Useful for deriving a JSON-shape from an internal type (camelCase to snake_case), relabeling a discriminator across a tagged union, or any spot where Merge / OverrideProperties would let you change a value type but not the key itself, as examples.

I use this in my framework, seedcord's, docs site, where I have a WithDeprecationStatus mixin that attaches a deprecationStatus field to entity types (classes, methods, properties). When rendering a child member of a deprecated parent, the section component needs to know the parent's status without claiming the child itself is deprecated, so I derive WithParentDeprecationStatus = RenameKey<WithDeprecationStatus, 'deprecationStatus', 'parentDeprecationStatus'>. Because of this, it's just one line and has no risk of the two types drifting. And renaming the source key automatically flags every downstream rename if I ever touch the mixin.

Some other examples below:

import type { RenameKey, RenameKeys } from 'type-fest';

type User = {
    readonly id: string;
    firstName: string;
    createdAt: Date;
};

type SingleRenamed = RenameKey<User, 'createdAt', 'created_at'>;
//=> {readonly id: string; firstName: string; created_at: Date}

type BatchRenamed = RenameKeys<User, { firstName: 'first_name'; createdAt: 'created_at' }>;
//=> {readonly id: string; first_name: string; created_at: Date}

type Event = { kind: 'click'; target: string } | { kind: 'submit'; target: HTMLFormElement };

type Renamed = RenameKey<Event, 'target', 'element'>;
//=> | {kind: 'click'; element: string}
//   | {kind: 'submit'; element: HTMLFormElement}

[sindresorhus]

I think this is close, but I would not merge it with collision support as-is.

The collision behavior is unsafe. The tests currently say that renaming a to an existing b should collapse the value types into b: number | string, but modifiers collapse too. For example:

type Result = RenameKey<{a?: number; b: string}, 'a', 'b'>;

This becomes {b?: number | string}, so this is accepted:

const value: Result = {};

That means renaming an optional key over a required key accidentally makes the required key optional. I think the simpler and better contract is to not support target-key collisions, except maybe renaming a key to itself. Supporting collisions correctly would need a lot more subtle modifier rules, and I don't think the use-case is worth it.

There is also a small issue with RenameKeys: optional entries in the rename map are accepted but silently ignored.

type Result = RenameKeys<{a: number; b: string}, {a?: 'alpha'}>;

This ends up as {a: number; b: string}, not {alpha: number; b: string}. Either the map entries should be required, or optional map entries should be rejected. Silently doing nothing is suprising.

Minor: there is a new unused eslint-disable-next-line no-lone-blocks warning in the tests.

[materwelonDhruv]

Thanks! That makes sense. I reworked it to drop collision support entirely and expanded tests with positive + negative coverage for a bunch of edge cases. The comments explain them.

Also, a consequence of this is that since the check is KeysOfUnion-based, a target present in another union member (or implied by a string index signature) is also rejected. I think that is good, actually.

I was also wondering about a RenameKeyDeep type which would be modeled on SetRequiredDeep + Paths. But that's for a later PR if you think it would be a good addition.

Re the lint: the lone blocks are intentional as each case block-scopes a reused local Source/Bad alias to keep the cases uniform. I replaced the per-line directives with a single paired file-level eslint-disable for no-lone-blocks, with a justification comment.

[som-sm]

These test cases fail currently:

type T1 = RenameKeys<{a: 1; b: 2}, {a: 'x'} | {b: 'y'}>;
//=> {a: 1; b: 2}

type T2 = RenameKeys<{a: 1; b: 2}, {a: 'b' | 'c'}>; // Doesn't error, but should
//=> {b: 1 | 2; c: 1}

type T3 = RenameKeys<{[x: string]: number; a: 1}, {a: 'b'}>; // Errors, but shouldn't

[som-sm]

A more nuanced issue:

type T = RenameKeys<{a: number; b: string}, {a: string}>;
//=> {[x: string]: number; b: string}

The output {[x: string]: number; b: string} is broken, refer:

This one would probably be quite hard to tackle properly.

[materwelonDhruv]

I'll work on all this feedback and set some stuff up in a TypeScript playground link so we can iterate more quickly before I push.

Ended up testing things in vscode itself...

[materwelonDhruv]

I pushed a redesign that addresses everything in the thread.

V imp. The constraint is now structural-only (Record<PropertyKey, PropertyKey>). All semantic validation moved into the body. This is the only constraint shape that defers cleanly under generic instantiation, which fixes the generic-test case @som-sm wrote above. The tradeoff is that a mistake when you use the type returns never from the body instead of erroring at the call site and the error surfaces when the result is consumed (assignment, indexing) rather than at the declaration. Probably better too I think per type-fest's role as a composable utility.

• sindre's collision concern (modifier collapse via optional → required): dropped collision support from the constraint. A body-side check returns never when any target in the rename map matches a kept literal key of the source (kept = literal keys minus the ones being renamed away). Swapping keys still works because both are simultaneously renamed away.

• sindre's optional-entry slip-through ({a?: 'b'} silently ignored): now returns never via HasOptionalKeys<RenameMap> in the body.

• sindre's unused no-lone-blocks lint: tests are rewritten in the inline expectType<X>({} as Y) style like the rest of the lib now.

• som-sm's T1 ({a: 'x'} | {b: 'y'} doesn't distribute): added explicit distribution via RenameMap extends RenameMap ? body : never. Each member of the rename-map union runs through the body independently.

• som-sm's T2 ({a: 'b' | 'c'} doesn't error) and the related {a: string} case: rejected via a body-side _AllTargetsAreSingleLiterals check that requires each target to be a single literal PropertyKey (no unions, no primitives like string).

• som-sm's T3 (index signature false-positive collision): kept-key set now excludes index signatures via OmitIndexSignature. A literal target onto a string-indexed object is no longer flagged; the index signature doesn't preclude adding a named property. RenameKey<{[x: string]: number; a: 1}, 'a', 'b'> now produces {[x: string]: number; b: 1} instead of erroring.

• som-sm's generic instantiation case ({[P in K]: \new_${P}`}` errors under generic T, K): works now too.

• som-sm on dropping RenameKey: I'd like to keep it. It's now a one-line wrapper:

export type RenameKey<BaseType, FromKey extends KeysOfUnion<BaseType>, ToKey extends PropertyKey> = RenameKeys<
    BaseType,
    { [Key in FromKey]: ToKey }
>;

The pair-of-surfaces pattern already exists in type-fest: And<A, B> wraps AndAll<[A, B]> (source/and.d.ts:80), and Or<A, B> wraps OrAll<[A, B]>. Both pairs ship together and cross-reference each other. RenameKey over RenameKeys follows the same shape. There's no duplicated logic since the wrapper delegates fully, so a fix to RenameKeys applies to RenameKey automatically. The positional form (RenameKey<User, 'createdAt', 'created_at'>) also reads more directly at the call site for the single-key case than the object-literal form. I also mentioned this above in the comments.

Two cases the constraint can't catch and the type doesn't reject cleanly so I short-circuit directly:

• IsAny<BaseType> returns never: matches the existing test's "can't prove safe" policy.
• IsNever<BaseType> returns never: needed because KeysOfUnion<never> evaluates to string | number | symbol (not never), so the natural constraint doesn't reject never BaseType.

[materwelonDhruv]

If I were to open a PR that sets up husky to run tests before push and lint-staged before commit, would that be merged? I feel that should definitely be there in a library like this.

[som-sm]

If I were to open a PR that sets up husky to run tests before push and lint-staged before commit, would that be merged? I feel that should definitely be there in a library like this.

No, I don’t think we want to add that. These tools add unnecessary friction, and blocking commits tends to make contributing more annoying than helpful. Contributors should be able to run checks locally when it makes sense, with CI checks acting as the final gate.

@sindresorhus

[sindresorhus]

Yeah, I don't want that. I had those in the past in other projects and caused more problems than they saved.

[som-sm]

Few thoughts:

• I think returning input object as-is is better than returning never in case of collisions.
• And, maybe it's better to just ignore keys that are not present in the input object. This pattern is kinda common, like Omit<{a: 1; b: 2}, 'a' | 'c'> returns back {b: 2}, ignoring 'c'.

IMO, returning never doesn't feel great!

[materwelonDhruv]

Hmmmmm. I do agree that never doesn't feel great as the result of a type. But, I think missing keys and collisions are different cases as well.

For missing keys ({nme: 'fullName'} on {name, id}) Omit style ignore is fine, ye. Like what I was doing before. Error when using the type itself via the type params.

For collisions tho ({a: 'b'} when b is kept), it should return something that the user HAS to pay attention to. The map said "overwrite b with the type of a under the name b", and returning the input as-is silently doesn't do that. That's a false-success I feel. Same goes for duplicate targets ({a: 'x'; b: 'x'}) where a pass through would have to pick one arbitrarily?

Maybe we go lenient on missing keys like Omit, and keep the never, so strict, on collisions, duplicate targets, basically anything that is "no this should not be allowed" vs "there isn't really a problem with not doing anything about this"

[som-sm]

@materwelonDhruv How hard do you think it would be to handle collisions?

I believe these are the only cases we need to consider when multiple properties p1, p2, …, pn are all being renamed to the same key new_p:

1. Optionality is uniform (all required or all optional)

   The value of new_p is a union of the values of p1, p2, …, pn, and the optional modifier is preserved.

   // All required → required
   type T = RenameKeys<{p1: string; p2: number; p3: bigint}, {p1: 'new_p'; p2: 'new_p'; p3: 'new_p'}>;
   //=> {new_p: string | number | bigint}

   // All optional → optional
   type T = RenameKeys<{p1?: string; p2?: number; p3?: bigint}, {p1: 'new_p'; p2: 'new_p'; p3: 'new_p'}>;
   //=> {new_p?: string | number | bigint}

2. Mixed optionality (at least one required, at least one optional)

   If at least one property is required, then new_p should be required. And it's value is a union of the values of p1, p2, …, pn.

   Note: In this case, the exactOptionalPropertyTypes compiler flag affects the result. When disabled, new_p's value should include an additional undefined, refer:

   // exactOptionalPropertyTypes: true
   type T = RenameKeys<{p1: string; p2?: number; p3: bigint}, {p1: 'new_p'; p2: 'new_p'; p3: 'new_p'}>;
   //=> {new_p: string | number | bigint}

   // exactOptionalPropertyTypes: false
   type T = RenameKeys<{p1: string; p2?: number; p3: bigint}, {p1: 'new_p'; p2: 'new_p'; p3: 'new_p'}>;
   //=> {new_p: string | number | bigint | undefined}

3. Mixed readonly modifiers

   If at least one source property is readonly, we could go either way on the result. I'd lean towards making new_p readonly; it's the safer, more conservative choice.

   type T = RenameKeys<{p1: string; readonly p2: number; p3: bigint}, {p1: 'new_p'; p2: 'new_p'; p3: 'new_p'}>;
   //=> {readonly new_p: string | number | bigint}

[materwelonDhruv]

@som-sm just to make sure I'm reading this right. You want these to be valid and produce a merged result, not return never? The current impl rejects duplicate targets like {p1: 'new_p'; p2: 'new_p'} outright, so I want to confirm you're asking me to drop that check and produce the merge instead. I'll try to figure that out then.

Do you think that has valid use cases? This is basically imitating a merge, right? Also, are you sure this being allowed is a good idea? We should guard against this kind of rename right? Why would someone want to do that? Why should someone want to rename keys this way?

[som-sm]

so I want to confirm you're asking me to drop that check and produce the merge instead.

Yup, correct!

This is basically imitating a merge, right?

Yeah kinda, just that merge is limited to only two items, this can happen with any no. of items.

There could be several valid use cases for merging. Here are some AI-suggested ones that look pretty reasonable:

type SearchInput = {
  textQuery: string;
  voiceQuery: Blob;
  imageQuery: File;
};

type Normalized = RenameKeys<SearchInput, {textQuery: 'query'; voiceQuery: 'query'; imageQuery: 'query'}>;
//=> {query: string | Blob | File}

type LegacyUser = {
  oldId?: string;
  numericId: number; 
  name: string;
};

type Migrated = RenameKeys<LegacyUser, {oldId: 'id'; numericId: 'id'}>;
//=> {id: string | number; name: string}

[materwelonDhruv]

oki imma try.

[materwelonDhruv]

We just came full circle lmao. Because I think @sindresorhus explicitly asked to reject such collisions where we end up in a union 😅

Some tests that currently reject this behavior will change now.

[som-sm]

The collision behavior is unsafe. The tests currently say that renaming a to an existing b should collapse the value types into b: number | string, but modifiers collapse too. For example:

type Result = RenameKey<{a?: number; b: string}, 'a', 'b'>;

This becomes {b?: number | string}, so this is accepted:

const value: Result = {};

That means renaming an optional key over a required key accidentally makes the required key optional. I think the simpler and better contract is to not support target-key collisions, except maybe renaming a key to itself. Supporting collisions correctly would need a lot more subtle modifier rules, and I don't think the use-case is worth it.

This was an issue because the merged result was incorrect; it would have been fine if the result were {b: number | string}.

And also, there aren't many cases here, so I guess it's worth solving it!

Some tests that currently reject this behavior will change now.

That's fine!

[materwelonDhruv]

okay that makes sense. I'm nearly done with it. testing with the cases you gave and some others of my own. and also simplifying the implementation a bit.

[som-sm]

This currently fails:

type T = RenameKeys<{a: string}, {a: 'b' | 'c'}>;
//=> Current: never
//=> Expected: {b: string; c: string}

[som-sm]

Doesn't seem to add | undefined when exactOptionalPropertyTypes is disabled, refer:

type T1 = RenameKeys<{a?: 1; b: 2}, {b: 'x'; a: 'x'}>;
// Current: {x: 1 | 2}
// Expected: {x: 1 | 2 | undefined}

type T2 = RenameKeys<{a?: 1; b: 2}, {b: 'a'}>;
// Current: {a: 1 | 2}
// Expected: {a: 1 | 2 | undefined}

type T3 = RenameKeys<{a?: 1; b: 2}, {a: 'b'}>;
// Current: {b: 1 | 2}
// Expected: {b: 1 | 2 | undefined}

[materwelonDhruv]

Fixed. The -? that forces a renamed key to required was also stripping the | undefined an option key carries. So when an optional key and a required key merged into the same name, the merged value lost its undefined. It only shows when exactOptionalPropertyTypes is off (with it on, there's no undefined to keep).

All three of your cases should now return the correct | undefined when EOPT is off. But, I wasn't able to add tests for this because the repo has it on. I tried adding a folder inside the tsd directory with its own tsconfig extending the base and setting EOPT off, but tsd doesn't care about nested folders with their own configs :( what to do? How do I add tests for this? @som-sm

I'm gonna check if some of my new impl can be replaced by any other type-fest types first before I commit.

And one other thing. Optional jeys show an explicit | undefined under EOPT off, e.g. b?: 1 | undefined where just b?: 1 would be enough. It's the same type, but not as clean, but it's explicit. It comes from _NewValue's off-branch. Since _RestoreMergedUndefined now adds undefined where it's actually needed, _NewValue could prolly be simplified to always strip, which would get the b? thingy. Not really needed tho. Wdyt?

[materwelonDhruv]

I can add a folder outside test-d/ for EOPT off tests. But that's outside the files this PR is currently about. So better to ask first

[som-sm]

How do I add tests for this?

It's fine, you don't need to add tests for exactOptionalPropertyTypes, you can just verify it manually!

And one other thing. Optional jeys show an explicit | undefined under EOPT off, e.g. b?: 1 | undefined where just b?: 1 would be enough.

That's fine too, with exactOptionalPropertyTypes disabled, b?: 1 and b?: 1 | undefined are the exact same thing.

[materwelonDhruv]

I already verified it manually 👍🏻 so it should be good on that front.

[som-sm]

I have not reviewed the implementation yet, I'll review that once everything else is sorted.

[materwelonDhruv]

bump @som-sm :)

[materwelonDhruv]

I'm testing that simplified version right now btw. Will reply to your review comments in a bit.

[materwelonDhruv]

Posted a comment above @som-sm
I can push with that additional helper for the EOPT fix if you're good with it.

[som-sm]

I can push with that additional helper for the EOPT fix if you're good with it.

Yeah, sure!

[materwelonDhruv]

OKAY. I think I'm done. Gonna push now. Also added like 3 more tests.

[materwelonDhruv]

I'm trying one other thing. If it's straightforward to get autocomplete on the second arg's map for the target keys. If it's too complex, it won't be worth it.

Edit: Not worth it.

[materwelonDhruv]

I like how this started with this 😭:

export type RenameKey<
	BaseType,
	FromKey extends KeysOfUnion<BaseType>,
	ToKey extends PropertyKey,
> = {
	[Key in keyof BaseType as Key extends FromKey ? ToKey : Key]: BaseType[Key];
};

Nice PR review. V good learning experience. Thanks som.

[materwelonDhruv]

Maybe worth it to add CodeRabbit and Greptile code reviews to the repo? Both are free for OSS.