Better types

oandregal · oandregal · commit 988a195e880a · 2025-11-13T13:24:15.000+01:00
diff --git a/packages/dataviews/src/types/field-api.ts b/packages/dataviews/src/types/field-api.ts
@@ -337,7 +337,7 @@ export type DayString =
 	| 'friday'
 	| 'saturday';
 
-export type NormalizedField< Item > = Omit< Field< Item >, 'Edit' > & {
+type NormalizedFieldBase< Item > = Omit< Field< Item >, 'Edit' > & {
 	label: string;
 	header: string | ReactElement;
 	getValue: ( args: { item: Item } ) => any;
@@ -351,9 +351,22 @@ export type NormalizedField< Item > = Omit< Field< Item >, 'Edit' > & {
 	enableSorting: boolean;
 	filterBy: NormalizedFilterByConfig | false;
 	readOnly: boolean;
-	format: {} | Required< FormatDate >;
 };
 
+type NormalizedFieldDate< Item > = NormalizedFieldBase< Item > & {
+	type: 'date';
+	format: Required< FormatDate >;
+};
+
+type NormalizedFieldGeneric< Item > = NormalizedFieldBase< Item > & {
+	type?: Exclude< FieldType, 'date' >;
+	format: {};
+};
+
+export type NormalizedField< Item > =
+	| NormalizedFieldGeneric< Item >
+	| NormalizedFieldDate< Item >;
+
 /**
  * A collection of dataview fields for a data type.
  */
diff --git a/packages/dataviews/src/utils/normalize-fields.ts b/packages/dataviews/src/utils/normalize-fields.ts
@@ -189,24 +189,22 @@ export default function normalizeFields< Item >(
 
 		const filterBy = getFilterBy( field, fieldTypeDefinition );
 
-		let format = {};
-		if ( field.type === 'date' ) {
-			format = {
-				date:
-					field.format?.date !== undefined &&
-					typeof field.format.date === 'string'
-						? field.format.date
-						: getSettings().formats.date,
-				weekStartsOn: DAYS_OF_WEEK.includes(
-					field.format?.weekStartsOn as DayString
-				)
-					? field?.format?.weekStartsOn
-					: numberToWeekStartsOn( getSettings().l10n.startOfWeek ),
-			};
-		}
-
-		return {
-			...field,
+		/**
+		 * NormalizedField is a discriminated union type: the shape of the format property
+		 * depends on the type property. For example, for the 'date' type, the format
+		 * contains date or weekStartsOn — which are not valid for other types.
+		 *
+		 * Being type and format interdependent, we need to write the code
+		 * in a way that TypeScript is able to statically infer the types.
+		 * That's why we have a return branch for every item in the union type.
+		 *
+		 * See a longer explanation with examples at
+		 * https://github.com/WordPress/gutenberg/pull/72999#discussion_r2523145453
+		 */
+		const { type, ...fieldWithoutType } = field;
+
+		const baseField = {
+			...fieldWithoutType,
 			label: field.label || field.id,
 			header: field.header || field.label || field.id,
 			getValue,
@@ -223,7 +221,30 @@ export default function normalizeFields< Item >(
 				true,
 			filterBy,
 			readOnly: field.readOnly ?? fieldTypeDefinition.readOnly ?? false,
-			format,
+			format: {},
 		};
+
+		if ( field.type === 'date' ) {
+			const format = {
+				date:
+					field.format?.date !== undefined &&
+					typeof field.format.date === 'string'
+						? field.format.date
+						: getSettings().formats.date,
+				weekStartsOn: DAYS_OF_WEEK.includes(
+					field.format?.weekStartsOn as DayString
+				)
+					? field?.format?.weekStartsOn
+					: numberToWeekStartsOn( getSettings().l10n.startOfWeek ),
+			};
+
+			return {
+				...baseField,
+				type: 'date',
+				format,
+			};
+		}
+
+		return { ...baseField, type: field.type, format: {} };
 	} );
 }
