@wordpress/core-data 4.6.0 → 4.9.0

package/src/entity-types/entities.ts

@@ -0,0 +1,130 @@
+/**
+ * Internal dependencies
+ */
+import type { Context } from './helpers';
+import type { EntityRecord } from './index';
+
+/**
+ * HTTP Query parameters sent with the API request to fetch the entity records.
+ */
+export type EntityQuery<
+	C extends Context,
+	Fields extends string[] | undefined = undefined
+> = Record< string, any > & {
+	context?: C;
+	/**
+	 * The requested fields. If specified, the REST API will remove from the response
+	 * any fields not on that list.
+	 */
+	_fields?: Fields;
+};
+
+interface Edit {}
+
+/**
+ * Helper type that transforms "raw" entity configuration from entities.ts
+ * into a format that makes searching by root and kind easy and extensible.
+ *
+ * This is the foundation of return type inference in calls such as:
+ * `getEntityRecord( "root", "comment", 15 )`.
+ *
+ * @see EntityRecordOf
+ * @see getEntityRecord
+ */
+export type EntityType<
+	Config extends Pick< EntityConfig< Record, Ctx >, RequiredConfigKeys >,
+	Record extends EntityRecord< Ctx >,
+	Ctx extends Context
+> = {
+	record: Record;
+	config: Omit< EntityConfig< Record, Ctx >, RequiredConfigKeys > & Config;
+	key: Config[ 'key' ] extends string ? Config[ 'key' ] : 'id';
+	defaultContext: Config[ 'baseURLParams' ] extends {
+		context: infer InferredContext;
+	}
+		? InferredContext
+		: 'view';
+};
+
+type RequiredConfigKeys = 'name' | 'kind' | 'key' | 'baseURLParams';
+
+export interface EntityConfig<
+	R extends EntityRecord< C >,
+	C extends Context
+> {
+	/** Path in WP REST API from which to request records of this entity. */
+	baseURL: string;
+
+	/** Arguments to supply by default to API requests for records of this entity. */
+	baseURLParams?: EntityQuery< Context >;
+
+	/**
+	 * Returns the title for a given record of this entity.
+	 *
+	 * Some entities have an associated title, such as the name of a
+	 * particular template part ("full width") or of a menu ("main nav").
+	 */
+	getTitle?: ( record: R ) => string;
+
+	/**
+	 * Indicates an alternate field in record that can be used for identification.
+	 *
+	 * e.g. a post has an id but may also be uniquely identified by its `slug`
+	 */
+	key?: string;
+
+	/**
+	 * Collection in which to classify records of this entity.
+	 *
+	 * 'root' is a special name given to the core entities provided by the editor.
+	 *
+	 * It may be the case that we request an entity record for which we have no
+	 * valid config in memory. In these cases the editor will look for a loader
+	 * function to requests more entity configs from the server for the given
+	 * "kind." This is how WordPress defers loading of template entity configs.
+	 */
+	kind: string;
+
+	/** Translated form of human-recognizable name or reference to records of this entity. */
+	label: string;
+
+	mergedEdits?: {
+		meta?: boolean;
+	};
+
+	/** Name given to records of this entity, e.g. 'media', 'postType', 'widget' */
+	name: string;
+
+	/**
+	 * Manually provided plural form of the entity name.
+	 *
+	 * When not supplied the editor will attempt to auto-generate a plural form.
+	 */
+	plural?: string;
+
+	/**
+	 * Fields in record of this entity which may appear as a compound object with
+	 * a source value (`raw`) as well as a processed value (`rendered`).
+	 *
+	 * e.g. a post's `content` in the edit context contains the raw value stored
+	 *      in the database as well as the rendered version with shortcodes replaced,
+	 *      content texturized, blocks transformed, etc…
+	 */
+	rawAttributes?: ( keyof R )[];
+
+	/**
+	 * Which transient edit operations records of this entity support.
+	 */
+	transientEdits?: {
+		blocks?: boolean;
+		selection?: boolean;
+	};
+
+	// Unstable properties
+
+	/** Returns additional changes before applying edits to a record of this entity. */
+	__unstablePrePersist?: ( record: R, edits: Edit[] ) => Edit[];
+
+	/** Used in `canEdit()` */
+	__unstable_rest_base?: string;
+}

package/src/entity-types/index.ts

@@ -20,7 +20,9 @@ import type { Widget } from './widget';
 import type { WidgetType } from './widget-type';
 import type { WpTemplate } from './wp-template';
 import type { WpTemplatePart } from './wp-template-part';
+import type { CoreEntities } from '../entities';
 
+export type { EntityType } from './entities';
 export type { BaseEntityRecords } from './base-entity-records';
 
 export type {
@@ -46,24 +48,117 @@ export type {
 	WpTemplatePart,
 };
 
-export type EntityRecord< C extends Context > =
-	| Attachment< C >
-	| Comment< C >
-	| MenuLocation< C >
-	| NavMenu< C >
-	| NavMenuItem< C >
-	| Page< C >
-	| Plugin< C >
-	| Post< C >
-	| Settings< C >
-	| Sidebar< C >
-	| Taxonomy< C >
-	| Theme< C >
-	| Type< C >
-	| User< C >
-	| Widget< C >
-	| WidgetType< C >
-	| WpTemplate< C >
-	| WpTemplatePart< C >;
-
 export type UpdatableEntityRecord = Updatable< EntityRecord< 'edit' > >;
+
+/**
+ * An interface that may be extended to add types for new entities. Each entry
+ * must be a union of entity definitions adhering to the EntityInterface type.
+ *
+ * Example:
+ *
+ * ```ts
+ * import type { Context } from '@wordpress/core-data';
+ * // ...
+ *
+ * interface Order {
+ *   id: number;
+ *   clientId: number;
+ *   // ...
+ * }
+ *
+ * type OrderEntity = {
+ *   kind: 'myPlugin';
+ *   name: 'order';
+ *   recordType: Order;
+ * }
+ *
+ * declare module '@wordpress/core-data' {
+ *     export interface PerPackageEntities< C extends Context > {
+ *         myPlugin: OrderEntity | ClientEntity
+ *     }
+ * }
+ *
+ * const c = getEntityRecord( 'myPlugin', 'order', 15 );
+ * // c is of the type Order
+ * ```
+ */
+export interface PerPackageEntityConfig< C extends Context > {
+	core: CoreEntities< C >;
+}
+
+/**
+ * A union of all the registered entities.
+ */
+type EntityConfig< C extends Context = any > =
+	PerPackageEntityConfig< C >[ keyof PerPackageEntityConfig< C > ];
+
+/**
+ * A union of all known record types.
+ */
+export type EntityRecord< C extends Context = any > =
+	EntityConfig< C >[ 'record' ];
+
+/**
+ * An entity corresponding to a specified record type.
+ */
+export type EntityConfigOf<
+	RecordOrKind extends EntityRecord | Kind,
+	N extends Name | undefined = undefined
+> = RecordOrKind extends EntityRecord
+	? Extract< EntityConfig, { record: RecordOrKind } >
+	: Extract< EntityConfig, { config: { kind: RecordOrKind; name: N } } >;
+
+/**
+ * Name of the requested entity.
+ */
+export type NameOf< R extends EntityRecord > =
+	EntityConfigOf< R >[ 'config' ][ 'name' ];
+
+/**
+ * Kind of the requested entity.
+ */
+export type KindOf< R extends EntityRecord > =
+	EntityConfigOf< R >[ 'config' ][ 'kind' ];
+
+/**
+ * Primary key type of the requested entity, sourced from PerPackageEntities.
+ *
+ * For core entities, the key type is computed using the entity configuration in entities.js.
+ */
+export type KeyOf<
+	RecordOrKind extends EntityRecord | Kind,
+	N extends Name | undefined = undefined,
+	E extends EntityConfig = EntityConfigOf< RecordOrKind, N >
+> = ( E[ 'key' ] extends keyof E[ 'record' ]
+	? E[ 'record' ][ E[ 'key' ] ]
+	: never ) &
+	( number | string );
+
+/**
+ * Default context of the requested entity, sourced from PerPackageEntities.
+ *
+ * For core entities, the default context is extracted from the entity configuration
+ * in entities.js.
+ */
+export type DefaultContextOf<
+	RecordOrKind extends EntityRecord | Kind,
+	N extends Name | undefined = undefined
+> = EntityConfigOf< RecordOrKind, N >[ 'defaultContext' ];
+
+/**
+ * An entity record type associated with specified kind and name, sourced from PerPackageEntities.
+ */
+export type EntityRecordOf<
+	K extends Kind,
+	N extends Name,
+	C extends Context = DefaultContextOf< K, N >
+> = Extract< EntityConfig< C >, { config: { kind: K; name: N } } >[ 'record' ];
+
+/**
+ * A union of all known entity kinds.
+ */
+export type Kind = EntityConfig[ 'config' ][ 'kind' ];
+/**
+ * A union of all known entity names.
+ */
+export type Name = EntityConfig[ 'config' ][ 'name' ];

package/src/entity-types/menu-location.ts

@@ -4,6 +4,7 @@
 import type { Context, OmitNevers } from './helpers';
 
 import type { BaseEntityRecords as _BaseEntityRecords } from './base-entity-records';
+import type { DefaultContextOf } from './index';
 
 declare module './base-entity-records' {
 	export namespace BaseEntityRecords {
@@ -24,6 +25,6 @@ declare module './base-entity-records' {
 	}
 }
 
-export type MenuLocation< C extends Context > = OmitNevers<
-	_BaseEntityRecords.MenuLocation< C >
->;
+export type MenuLocation<
+	C extends Context = DefaultContextOf< 'root', 'menuLocation' >
+> = OmitNevers< _BaseEntityRecords.MenuLocation< C > >;

package/src/entity-types/nav-menu-item.ts

@@ -9,6 +9,7 @@ import type {
 } from './helpers';
 
 import type { BaseEntityRecords as _BaseEntityRecords } from './base-entity-records';
+import type { DefaultContextOf } from './index';
 
 export type NavMenuItemType =
 	| 'taxonomy'
@@ -106,6 +107,6 @@ declare module './base-entity-records' {
 	}
 }
 
-export type NavMenuItem< C extends Context > = OmitNevers<
-	_BaseEntityRecords.NavMenuItem< C >
->;
+export type NavMenuItem<
+	C extends Context = DefaultContextOf< 'root', 'menuItem' >
+> = OmitNevers< _BaseEntityRecords.NavMenuItem< C > >;

package/src/entity-types/nav-menu.ts

@@ -4,6 +4,7 @@
 import type { Context, ContextualField, OmitNevers } from './helpers';
 
 import type { BaseEntityRecords as _BaseEntityRecords } from './base-entity-records';
+import { DefaultContextOf } from './index';
 
 declare module './base-entity-records' {
 	export namespace BaseEntityRecords {
@@ -48,6 +49,5 @@ declare module './base-entity-records' {
 	}
 }
 
-export type NavMenu< C extends Context > = OmitNevers<
-	_BaseEntityRecords.NavMenu< C >
->;
+export type NavMenu< C extends Context = DefaultContextOf< 'root', 'menu' > > =
+	OmitNevers< _BaseEntityRecords.NavMenu< C > >;

package/src/entity-types/page.ts

@@ -12,6 +12,7 @@ import type {
 } from './helpers';
 
 import type { BaseEntityRecords as _BaseEntityRecords } from './base-entity-records';
+import type { DefaultContextOf } from './index';
 
 declare module './base-entity-records' {
 	export namespace BaseEntityRecords {
@@ -139,6 +140,5 @@ declare module './base-entity-records' {
 	}
 }
 
-export type Page< C extends Context > = OmitNevers<
-	_BaseEntityRecords.Page< C >
->;
+export type Page< C extends Context = DefaultContextOf< 'postType', 'page' > > =
+	OmitNevers< _BaseEntityRecords.Page< C > >;

package/src/entity-types/plugin.ts

@@ -9,6 +9,7 @@ import type {
 } from './helpers';
 
 import type { BaseEntityRecords as _BaseEntityRecords } from './base-entity-records';
+import type { DefaultContextOf } from './index';
 
 declare module './base-entity-records' {
 	export namespace BaseEntityRecords {
@@ -74,6 +75,5 @@ declare module './base-entity-records' {
 }
 
 export type PluginStatus = 'active' | 'inactive';
-export type Plugin< C extends Context > = OmitNevers<
-	_BaseEntityRecords.Plugin< C >
->;
+export type Plugin< C extends Context = DefaultContextOf< 'root', 'plugin' > > =
+	OmitNevers< _BaseEntityRecords.Plugin< C > >;

package/src/entity-types/post.ts

@@ -13,6 +13,7 @@ import type {
 } from './helpers';
 
 import type { BaseEntityRecords as _BaseEntityRecords } from './base-entity-records';
+import type { DefaultContextOf } from './index';
 
 declare module './base-entity-records' {
 	export namespace BaseEntityRecords {
@@ -148,6 +149,5 @@ declare module './base-entity-records' {
 	}
 }
 
-export type Post< C extends Context > = OmitNevers<
-	_BaseEntityRecords.Post< C >
->;
+export type Post< C extends Context = DefaultContextOf< 'postType', 'post' > > =
+	OmitNevers< _BaseEntityRecords.Post< C > >;

package/src/entity-types/settings.ts

@@ -9,6 +9,7 @@ import type {
 } from './helpers';
 
 import type { BaseEntityRecords as _BaseEntityRecords } from './base-entity-records';
+import type { DefaultContextOf } from './index';
 
 declare module './base-entity-records' {
 	export namespace BaseEntityRecords {
@@ -93,6 +94,5 @@ declare module './base-entity-records' {
 	}
 }
 
-export type Settings< C extends Context > = OmitNevers<
-	_BaseEntityRecords.Settings< C >
->;
+export type Settings< C extends Context = DefaultContextOf< 'root', 'site' > > =
+	OmitNevers< _BaseEntityRecords.Settings< C > >;

package/src/entity-types/sidebar.ts

@@ -4,6 +4,7 @@
 import type { Context, OmitNevers } from './helpers';
 
 import type { BaseEntityRecords as _BaseEntityRecords } from './base-entity-records';
+import type { DefaultContextOf } from './index';
 
 declare module './base-entity-records' {
 	export namespace BaseEntityRecords {
@@ -54,6 +55,6 @@ declare module './base-entity-records' {
 
 type SidebarStatus = 'active' | 'inactive';
 
-export type Sidebar< C extends Context > = OmitNevers<
-	_BaseEntityRecords.Sidebar< C >
->;
+export type Sidebar<
+	C extends Context = DefaultContextOf< 'root', 'sidebar' >
+> = OmitNevers< _BaseEntityRecords.Sidebar< C > >;

package/src/entity-types/taxonomy.ts

@@ -4,6 +4,7 @@
 import type { Context, ContextualField, OmitNevers } from './helpers';
 
 import type { BaseEntityRecords as _BaseEntityRecords } from './base-entity-records';
+import type { DefaultContextOf } from './index';
 
 declare module './base-entity-records' {
 	export namespace BaseEntityRecords {
@@ -87,6 +88,6 @@ declare module './base-entity-records' {
 	}
 }
 
-export type Taxonomy< C extends Context > = OmitNevers<
-	_BaseEntityRecords.Taxonomy< C >
->;
+export type Taxonomy<
+	C extends Context = DefaultContextOf< 'postType', 'taxonomy' >
+> = OmitNevers< _BaseEntityRecords.Taxonomy< C > >;

package/src/entity-types/theme.ts

@@ -4,6 +4,7 @@
 import type { Context, PostFormat, RenderedText, OmitNevers } from './helpers';
 
 import type { BaseEntityRecords as _BaseEntityRecords } from './base-entity-records';
+import type { DefaultContextOf } from './index';
 
 declare module './base-entity-records' {
 	export namespace BaseEntityRecords {
@@ -217,6 +218,5 @@ declare module './base-entity-records' {
 	}
 }
 
-export type Theme< C extends Context > = OmitNevers<
-	_BaseEntityRecords.Theme< C >
->;
+export type Theme< C extends Context = DefaultContextOf< 'root', 'theme' > > =
+	OmitNevers< _BaseEntityRecords.Theme< C > >;

package/src/entity-types/type.ts

@@ -4,6 +4,7 @@
 import type { Context, ContextualField, OmitNevers } from './helpers';
 
 import type { BaseEntityRecords as _BaseEntityRecords } from './base-entity-records';
+import type { DefaultContextOf } from './index';
 
 declare module './base-entity-records' {
 	export namespace BaseEntityRecords {
@@ -75,6 +76,5 @@ declare module './base-entity-records' {
 	}
 }
 
-export type Type< C extends Context > = OmitNevers<
-	_BaseEntityRecords.Type< C >
->;
+export type Type< C extends Context = DefaultContextOf< 'root', 'postType' > > =
+	OmitNevers< _BaseEntityRecords.Type< C > >;

package/src/entity-types/user.ts

@@ -9,6 +9,7 @@ import type {
 } from './helpers';
 
 import type { BaseEntityRecords as _BaseEntityRecords } from './base-entity-records';
+import type { DefaultContextOf } from './index';
 
 declare module './base-entity-records' {
 	export namespace BaseEntityRecords {
@@ -109,6 +110,5 @@ declare module './base-entity-records' {
 	}
 }
 
-export type User< C extends Context > = OmitNevers<
-	_BaseEntityRecords.User< C >
->;
+export type User< C extends Context = DefaultContextOf< 'root', 'user' > > =
+	OmitNevers< _BaseEntityRecords.User< C > >;

package/src/entity-types/widget-type.ts

@@ -4,6 +4,7 @@
 import type { Context, OmitNevers } from './helpers';
 
 import type { BaseEntityRecords as _BaseEntityRecords } from './base-entity-records';
+import type { DefaultContextOf } from './index';
 
 declare module './base-entity-records' {
 	export namespace BaseEntityRecords {
@@ -32,6 +33,6 @@ declare module './base-entity-records' {
 	}
 }
 
-export type WidgetType< C extends Context > = OmitNevers<
-	_BaseEntityRecords.WidgetType< C >
->;
+export type WidgetType<
+	C extends Context = DefaultContextOf< 'root', 'widgetType' >
+> = OmitNevers< _BaseEntityRecords.WidgetType< C > >;

package/src/entity-types/widget.ts

@@ -4,6 +4,7 @@
 import type { Context, ContextualField, OmitNevers } from './helpers';
 
 import type { BaseEntityRecords as _BaseEntityRecords } from './base-entity-records';
+import type { DefaultContextOf } from './index';
 
 declare module './base-entity-records' {
 	export namespace BaseEntityRecords {
@@ -59,6 +60,5 @@ declare module './base-entity-records' {
 	}
 }
 
-export type Widget< C extends Context > = OmitNevers<
-	_BaseEntityRecords.Widget< C >
->;
+export type Widget< C extends Context = DefaultContextOf< 'root', 'widget' > > =
+	OmitNevers< _BaseEntityRecords.Widget< C > >;

package/src/entity-types/wp-template-part.ts

@@ -10,6 +10,7 @@ import type {
 } from './helpers';
 
 import type { BaseEntityRecords as _BaseEntityRecords } from './base-entity-records';
+import type { DefaultContextOf } from './index';
 
 declare module './base-entity-records' {
 	export namespace BaseEntityRecords {
@@ -89,6 +90,6 @@ declare module './base-entity-records' {
 	}
 }
 
-export type WpTemplatePart< C extends Context > = OmitNevers<
-	_BaseEntityRecords.WpTemplatePart< C >
->;
+export type WpTemplatePart<
+	C extends Context = DefaultContextOf< 'postType', 'wp_template_part' >
+> = OmitNevers< _BaseEntityRecords.WpTemplatePart< C > >;

package/src/entity-types/wp-template.ts

@@ -10,6 +10,7 @@ import type {
 } from './helpers';
 
 import type { BaseEntityRecords as _BaseEntityRecords } from './base-entity-records';
+import type { DefaultContextOf } from './index';
 
 declare module './base-entity-records' {
 	export namespace BaseEntityRecords {
@@ -89,6 +90,6 @@ declare module './base-entity-records' {
 	}
 }
 
-export type WpTemplate< C extends Context > = OmitNevers<
-	_BaseEntityRecords.WpTemplate< C >
->;
+export type WpTemplate<
+	C extends Context = DefaultContextOf< 'postType', 'wp_template' >
+> = OmitNevers< _BaseEntityRecords.WpTemplate< C > >;

package/src/fetch/test/__experimental-fetch-link-suggestions.js

@@ -175,8 +175,7 @@ describe( 'fetchLinkSuggestions', () => {
 				{
 					id: 54,
 					title: 'Some Test Media Title',
-					url:
-						'http://localhost:8888/wp-content/uploads/2022/03/test-pdf.pdf',
+					url: 'http://localhost:8888/wp-content/uploads/2022/03/test-pdf.pdf',
 					type: 'attachment',
 					kind: 'media',
 				},
@@ -225,8 +224,7 @@ describe( 'fetchLinkSuggestions', () => {
 				{
 					id: 54,
 					title: 'Some Test Media Title',
-					url:
-						'http://localhost:8888/wp-content/uploads/2022/03/test-pdf.pdf',
+					url: 'http://localhost:8888/wp-content/uploads/2022/03/test-pdf.pdf',
 					type: 'attachment',
 					kind: 'media',
 				},

package/src/hooks/constants.ts

@@ -1,5 +1,4 @@
-/* eslint-disable-next-line no-shadow */
-export enum Status {
+export const enum Status {
 	Idle = 'IDLE',
 	Resolving = 'RESOLVING',
 	Error = 'ERROR',

package/src/hooks/index.ts

@@ -0,0 +1,8 @@
+export {
+	default as useEntityRecord,
+	__experimentalUseEntityRecord,
+} from './use-entity-record';
+export {
+	default as useEntityRecords,
+	__experimentalUseEntityRecords,
+} from './use-entity-records';

package/src/hooks/test/use-query-select.js

@@ -145,8 +145,10 @@ describe( 'useQuerySelect', () => {
 					} ),
 				},
 				resolvers: {
-					getResolvedFoo: () => ( { dispatch } ) =>
-						dispatch.receiveFoo( 5 ),
+					getResolvedFoo:
+						() =>
+						( { dispatch } ) =>
+							dispatch.receiveFoo( 5 ),
 				},
 				selectors: {
 					getResolvedFoo: ( state, arg ) => state.resolvedFoo + arg,