Add RenameKeys type

index.d.ts

@@ -103,6 +103,7 @@ export type {KeyAsString} from './source/key-as-string.d.ts';
 export type {Exact} from './source/exact.d.ts';
 export type {ReadonlyTuple} from './source/readonly-tuple.d.ts';
 export type {OverrideProperties} from './source/override-properties.d.ts';
+export type {RenameKeys} from './source/rename-keys.d.ts';
 export type {OptionalKeysOf} from './source/optional-keys-of.d.ts';
 export type {IsOptionalKeyOf} from './source/is-optional-key-of.d.ts';
 export type {HasOptionalKeys} from './source/has-optional-keys.d.ts';

readme.md

@@ -121,6 +121,7 @@ Click the type names for complete docs.
 - [`MergeDeep`](source/merge-deep.d.ts) - Merge two objects or two arrays/tuples recursively into a new type.
 - [`MergeExclusive`](source/merge-exclusive.d.ts) - Create a type that has mutually exclusive keys.
 - [`OverrideProperties`](source/override-properties.d.ts) - Override existing properties of the given type. Similar to `Merge`, but enforces that the original type has the properties you want to override.
+- [`RenameKeys`](source/rename-keys.d.ts) - Rename keys in an object type according to a map of old-to-new names. Keys absent from the map are returned unchanged. The value type, the optional modifier, and the readonly modifier are applied to the new key.
 - [`RequireAtLeastOne`](source/require-at-least-one.d.ts) - Create a type that requires at least one of the given keys, while keeping the remaining keys as is.
 - [`RequireExactlyOne`](source/require-exactly-one.d.ts) - Create a type that requires exactly one of the given keys and disallows more, while keeping the remaining keys as is.
 - [`RequireAllOrNone`](source/require-all-or-none.d.ts) - Create a type that requires all of the given keys or none of the given keys, while keeping the remaining keys as is.

source/rename-keys.d.ts

@@ -0,0 +1,111 @@
+import type {IsLiteral} from './is-literal.d.ts';
+import type {ReadonlyKeysOf} from './readonly-keys-of.d.ts';
+import type {RequiredKeysOf} from './required-keys-of.d.ts';
+import type {OptionalKeysOf} from './optional-keys-of.d.ts';
+import type {OmitIndexSignature} from './omit-index-signature.d.ts';
+import type {SetRequired} from './set-required.d.ts';
+import type {SetReadonly} from './set-readonly.d.ts';
+import type {IfNotAnyOrNever, IsExactOptionalPropertyTypesEnabled} from './internal/type.d.ts';
+
+/**
+Rename keys in an object type according to a map of old-to-new names. Keys absent from the map are returned unchanged. The value type, the optional modifier, and the readonly modifier are applied to the new key.
+
+Distributes over a union of rename maps and over a union of source types.
+
+When multiple source keys map to the same target, the target's value type is the union of the contributors' value types. The target is optional only when every contributor is optional, and is `readonly` when any contributor is `readonly`. With `exactOptionalPropertyTypes` disabled, the value type of a mixed-optionality merge also includes `undefined`.
+
+A union target distributes, producing one output key per member. For example, `{a: 'b' | 'c'}` on a source with `a: string` produces both `b: string` and `c: string`.
+
+A rename map entry whose key is not a property of the source type is ignored, matching the result of `Omit`. An entry whose value is not a literal `PropertyKey` (such as `string`) is also ignored, leaving that key's name unchanged. The optional modifier on a rename map entry is ignored, so `{a?: 'alpha'}` produces the same result as `{a: 'alpha'}`.
+
+An `any` source returns `any`, and a `never` source returns `never`.
+
+@example
+```
+import type {RenameKeys} from 'type-fest';
+
+type User = {
+	id: string;
+	firstName: string;
+	createdAt: Date;
+};
+
+type Renamed = RenameKeys<User, {firstName: 'first_name'; createdAt: 'created_at'}>;
+//=> {id: string; first_name: string; created_at: Date}
+```
+
+@example
+```
+import type {RenameKeys} from 'type-fest';
+
+type SearchInput = {
+	textQuery: string;
+	voiceQuery: Blob;
+	imageQuery: File;
+};
+
+type Normalized = RenameKeys<SearchInput, {textQuery: 'query'; voiceQuery: 'query'; imageQuery: 'query'}>;
+//=> {query: string | Blob | File}
+```
+
+@category Object
+*/
+export type RenameKeys<
+	BaseType extends object,
+	RenameMap extends Record<PropertyKey, PropertyKey>,
+> = IfNotAnyOrNever<BaseType, {
+	ifNot: BaseType extends unknown // Distribute over a union source
+		? RenameMap extends unknown // Distribute over a union map
+			? _RenameOnce<BaseType, _NormalizeMap<RenameMap>>
+			: never
+		: never;
+}>;
+
+type _NormalizeMap<RenameMap extends Record<PropertyKey, PropertyKey>> = {
+	-readonly [Key in keyof RenameMap as true extends IsLiteral<RenameMap[Key]> ? Key : never]-?: RenameMap[Key];
+};
+
+type _TargetOf<SourceKey extends PropertyKey, RenameMap extends Record<PropertyKey, PropertyKey>> =
+	SourceKey extends keyof RenameMap ? RenameMap[SourceKey] : SourceKey;
+
+type _RenameOnce<BaseType extends object, RenameMap extends Record<PropertyKey, PropertyKey>> =
+	_RestoreMergedUndefined<BaseType, RenameMap,
+		_ApplyReadonly<BaseType, RenameMap,
+			_ApplyRequired<BaseType, RenameMap,
+				_RenameNaive<BaseType, RenameMap>>>>;
+
+type _RenameNaive<BaseType extends object, RenameMap extends Record<PropertyKey, PropertyKey>> = {
+	// Two keys mapping to one target produce a union value and keep only the first key's modifiers
+	// Like for example, {a?: 1; b: 2} with {a: 'x'; b: 'x'} produces {x?: 1 | 2}, taking a's optional
+	[Key in keyof BaseType as _TargetOf<Key, RenameMap>]: _SourceValue<BaseType, Key>;
+};
+
+type _SourceValue<BaseType extends object, Key extends keyof BaseType> =
+	// EOPT on: Required drops the implicit undefined from an optional value
+	(IsExactOptionalPropertyTypesEnabled extends true ? Required<BaseType> : BaseType)[Key];
+
+// A merged target kept only one modifier in _RenameNaive, so re-force these from every contributor.
+type _ApplyRequired<BaseType extends object, RenameMap extends Record<PropertyKey, PropertyKey>, Renamed> =
+	SetRequired<Renamed, _TargetOf<RequiredKeysOf<OmitIndexSignature<BaseType>>, RenameMap> & keyof Renamed>;
+
+type _ApplyReadonly<BaseType extends object, RenameMap extends Record<PropertyKey, PropertyKey>, Renamed> =
+	SetReadonly<Renamed, _TargetOf<ReadonlyKeysOf<OmitIndexSignature<BaseType>>, RenameMap> & keyof Renamed>;
+
+type _MergedTargets<BaseType extends object, RenameMap extends Record<PropertyKey, PropertyKey>> =
+	// Targets renamed from both a required and an optional key prefer the required modifier
+	// Required b and optional a both rename to x in {a?: 1; b: 2} with {a: 'x'; b: 'x'}
+	_TargetOf<RequiredKeysOf<OmitIndexSignature<BaseType>>, RenameMap>
+	& _TargetOf<OptionalKeysOf<OmitIndexSignature<BaseType>>, RenameMap>;
+
+// EOPT off keeps undefined on a target that merged a required and an optional source
+// Source {a?: 1; x: 2} with {a: 'x'} gives {x: 1 | 2 | undefined}
+type _RestoreMergedUndefined<BaseType extends object, RenameMap extends Record<PropertyKey, PropertyKey>, Result> =
+	IsExactOptionalPropertyTypesEnabled extends true
+		? Result
+		: {
+			[Key in keyof Result]: Key extends _MergedTargets<BaseType, RenameMap>
+				? Result[Key] | undefined
+				: Result[Key];
+		};
+
+export {};