Entity configuration types

[adamziel]

What?

This PR adds Entity configuration types to core-data/src/entities.ts.

It is an alternative to #40024. See also #39025, a mega branch that proposes TypeScript signatures for all @wordpress/core-data selectors.

Why?

Consider the getEntityRecord selector:

gutenberg/packages/core-data/src/selectors.js

Lines 157 to 171 in 395aea4

	/**
	* Returns the Entity's record object by key. Returns `null` if the value is not
	* yet received, undefined if the value entity is known to not exist, or the
	* entity object if it exists and is received.
	*
	* @param {Object} state State tree
	* @param {string} kind Entity kind.
	* @param {string} name Entity name.
	* @param {number} key Record's key
	* @param {?Object} query Optional query.
	*
	* @return {Object|undefined} Record.
	*/
	export const getEntityRecord = createSelector(
	( state, kind, name, key, query ) => {

Different entity kinds, like root, postType, taxonomy, are associated with different entity names. For example, kind: root, name: plugin is a valid combination, but kind: postType, name: plugin is not. Other valid combinations are configured in the entities.ts file via a JavaScript object.

An ideal getEntityRecord function signature would only accept valid combinations, then require the key to be either number or a string, and return the list of corresponding entity records.

Again, ideally, there would only be a single source of truth for all the information. That's exactly what this PR enables by introducing the Entity types:

type PluginEntity< C extends Context = Context > = EntityType<
	{
		name: 'plugin';
		kind: 'root';
		baseURLParams: { context: 'edit' };
		key: 'plugin';
	},
	Records.Plugin< C >,
	C
>;

const pluginConfig: PluginEntity[ 'config' ] = {
	label: __( 'Plugins' ),
	name: 'plugin',
	kind: 'root',
	baseURL: '/wp/v2/plugins',
	baseURLParams: { context: 'edit' },
	key: 'plugin',
};

// PluginEntity['config']['kind'] is "root"
// PluginEntity['defaultContext'] is "edit"

That PluginEntity type can then be reused to build the getEntityRecord signature.

Why write the kind and name twice?

This is a trade-off. I've spent hours exploring the available options with @dmsnell and we concluded that it's only possibl to either:

1. Infer it from const config = and miss out on autocompletion, config type validation, and require using as const. Reuse the JS entities configuration in the TypeScript type system #40024 explored that
2. Infer it from const config = and have all of the above, but at the cost of using super complex type plumbing. This TS playground explores that
3. Type it explicitly, have autocompletion and type validation without complex types, but duplicate a few lines of code.

This PR implements the latter approach.

Why have a new config type?

Good question! It's needed because entity configuration comes from three different sources:

• Hardcoded types in entities.ts
• Implicit knowledge about the entities loaded using the entity loaders, e.g. that the default context of all kind=postType is edit as seen in loadPostTypeEntities
• Any additional configuration provided by Gutenberg extenders.

A somewhat eccentric metaphor would be picturing it as a MySQL query that joins three tables:

SELECT
	kind,
	name,
	recordType,
	DEFAULT(key, 'id') as key,
	DEFAULT(baseURLParams['context'], 'view') as defaultContext
FROM rootEntitiesConfig_declared_in_entities_js d
INNER JOIN record_types r ON d.kind = r.kind AND d.name = r.name
UNION
SELECT VALUES
	ROW ( 'postType', 'post', 'id', 'Post', 'edit' ),
	ROW ( 'postType', 'page', 'id', 'Page', 'edit' ),
	ROW ( 'postType', 'wp_template', 'WpTemplate', 'id', 'edit' ),
	ROW ( 'postType', 'wp_template_part', 'WpTemplatePart', 'id', 'edit' ),
AS what_we_intrinsically_know_from_additionalEntityConfigLoaders
UNION
SELECT
	kind,
	name,
	recordType,
	key,
	defaultContext
FROM additional_configuration_provided_by_extenders

A common format like the PluginEntity makes reasoning about all these data sources much easier down the road, e.g. it enables the following succinct formulation of the Kind type:

export type KindOf< R extends EntityRecord > = EntityConfigOf< R >[ 'kind' ];

Test plan

Confirm the checks are green and that no entity configuration got changed when I split the large array into atomic declarations. The changes here should only affect the type system so there is nothing to test in the browser.

cc @dmsnell @jsnajdr @youknowriad @sarayourfriend @getdave @draganescu @scruffian

[dmsnell]

I don't want to hold this up, but I'd like to see some further exploration after this merges to move the individual configs into their entity type files rather than having them all here (as we did with entity-types).

Thanks for working so hard on this.