@wordpress/core-data 4.1.1 → 4.1.2

package/src/types/README.md

@@ -0,0 +1,193 @@
+# Entity Records Types
+
+## Overview
+
+The types in this directory are designed to support the following use-cases:
+
+* Provide type-hinting and documentation for entity records fetched in the various REST API contexts.
+* Type-check the values we use to *edit* entity records, the values that are sent back to the server as updates.
+
+**Warning:** The types model the expected API responses which is **not** the same as having a full type safety for the API-related operations. The API responses are type-cast to these definitions and therefore may not match those expectations; for example, a plugin could modify the response, or the API endpoint could have a nuanced implementation in which strings are sometimes used instead of numbers.
+
+### Context-aware type checks for entity records
+
+WordPress REST API returns different responses based on the `context` query parameter, which typically is one of `view`, `edit`, or `embed`. See the [REST API documentation](https://developer.wordpress.org/rest-api/) to learn more.
+
+For example, requesting `/wp/v2/posts/1?context=view` yields:
+
+```js
+{
+  "content": {
+    "protected": false,
+    "rendered": "\n<p>Welcome to WordPress. This is your first post. Edit or delete it, then start writing!</p>\n"
+  },
+  "title": {
+    "rendered": "Hello world!"
+  }
+  // other fields
+}
+```
+
+While requesting `/wp/v2/posts/1?context=edit`, yields:
+
+```js
+{
+  "content": {
+    "block_version": 1,
+    "protected": false,
+    "raw": "<!-- wp:paragraph -->\n<p>Welcome to WordPress. This is your first post. Edit or delete it, then start writing!</p>\n<!-- /wp:paragraph -->",
+    "rendered": "\n<p>Welcome to WordPress. This is your first post. Edit or delete it, then start writing!</p>\n"
+  },
+  "title": {
+    "raw": "Hello world!",
+    "rendered": "Hello world!"
+  }
+  // other fields
+}
+```
+
+And, finally, requesting `/wp/v2/posts/1?context=embed` yields:
+
+```js
+{
+  // Note content is missing
+  "title": {
+    "rendered": "Hello world!"
+  }
+  // other fields
+}
+```
+
+These contexts are supported by the core-data resolvers like `getEntityRecord()` and `getEntityRecords()` to retrieve the appropriate "flavor" of the data.
+
+The types describing different entity records must thus be aware of the relevant API context. This is implemented using the `Context` type parameter. For example, the implementation of the `Post` type resembles the following snippet:
+
+```ts
+interface Post<C extends Context> {
+	/**
+	 * A named status for the post.
+	 */
+	status: ContextualField< PostStatus, 'view' | 'edit', C >;
+
+	// ... other fields ...
+}
+```
+
+The `status` field is a `PostStatus` when the requesting context is `view` or `edit`, but if requested with an `embed` context the field won't appear on the `Post` object at all.
+
+### Static type checks for *edited* entity records, where certain fields become strings instead of objects.
+
+When the `post` is retrieved using `getEntityRecord`, its `content` field is an object:
+
+```js
+const post = wp.data.select('core').getEntityRecord( 'postType', 'post', 1, { context: 'view' } )
+// `post.content` is an object with two fields: protected and rendered
+```
+
+The block markup stored in `content` can only be rendered on the server so the REST API exposes both the raw markup and the rendered version. For example, `content.rendered` could used as a visual preview, and `content.raw` could be used to populate the code editor.
+
+When updating that field from the JavaScript code, however, all we can set is the raw value that the server will eventually render. The API expects us to send a much simpler `string` form which is the raw form that needs to be stored in the database.
+
+The types reflect this through the `Updatable<EntityRecord>` wrapper:
+
+```ts
+interface Post< C extends Context > {
+  title: {
+    raw: string;
+    rendered: string;
+  }
+}
+
+const post : Post< 'edit' > = ...
+// post.title is an object with properties `raw` and `rendered`
+
+const post : Updatable<Post< 'edit' >> = ...
+// post.title is a string
+```
+
+The `getEditedEntityRecord` selector returns the Updatable version of the entity records:
+
+```js
+const post = wp.data.select('core').getEditedEntityRecord( 'postType', 'post', 1 );
+// `post.content` is a string
+```
+
+## Helpers
+
+### Context
+
+The REST API context parameter.
+
+### ContextualField
+
+`ContextualField` makes the field available only in the specified given contexts, and ensure the field is absent from the object when in a different context.
+
+Example:
+
+```ts
+interface Post< C extends Context > {
+	…
+	modified: ContextualField< string, 'edit' | 'view', C >;
+	password: ContextualField< string, 'edit', C >;
+	…
+}
+
+const post: Post<'edit'> = …
+// post.modified exists as a string
+// post.password exists as a string
+
+const post: Post<'view'> = …
+// post.modified still exists as a string
+// post.password is missing, undefined, because we're not in the `edit` context.
+```
+
+### OmitNevers
+
+Removes all the properties of type never, even the deeply nested ones.
+
+```ts
+type MyType = {
+  foo: string;
+  bar: never;
+  nested: {
+    foo: string;
+    bar: never;
+  }
+}
+const x = {} as OmitNevers<MyType>;
+// x is of type { foo: string; nested: { foo: string; }}
+// The `never` properties were removed entirely
+```
+
+### Updatable
+
+Updatable<EntityRecord> is a type describing Edited Entity Records. They are like
+regular Entity Records, but they have all the local edits applied on top of the REST API data.
+
+This turns certain field from an object into a string.
+
+Entities like Post have fields that only be rendered on the server, like title, excerpt,
+and content. The REST API exposes both the raw markup and the rendered version of those fields.
+For example, in the block editor, content.rendered could used as a visual preview, and
+content.raw could be used to populate the code editor.
+
+When updating these rendered fields, JavaScript is not be able to properly render arbitrary block
+markup. Therefore, it stores only the raw markup without the rendered part. And since that's a string,
+the entire field becomes a string.
+
+```ts
+type Post< C extends Context > {
+  title: RenderedText< C >;
+}
+const post = {} as Post;
+// post.title is an object with raw and rendered properties
+
+const updatablePost = {} as Updatable< Post >;
+// updatablePost.title is a string
+```
+
+### RenderedText
+
+A string that the server renders which often involves modifications from the raw source string.
+
+For example, block HTML with the comment delimiters exists in `post_content` but those comments are stripped out when rendering to a page view. Similarly, plugins might modify content or replace shortcodes.

package/src/types/attachment.ts

@@ -0,0 +1,146 @@
+/**
+ * Internal dependencies
+ */
+import {
+	Context,
+	ContextualField,
+	MediaType,
+	PostStatus,
+	RenderedText,
+	OmitNevers,
+	CommentingStatus,
+	PingStatus,
+} from './helpers';
+
+import { BaseEntityTypes as _BaseEntityTypes } from './base-entity-types';
+
+declare module './base-entity-types' {
+	export namespace BaseEntityTypes {
+		export interface Attachment< C extends Context > {
+			/**
+			 * The date the post was published, in the site's timezone.
+			 */
+			date: string | null;
+			/**
+			 * The date the post was published, as GMT.
+			 */
+			date_gmt: ContextualField< string | null, 'view' | 'edit', C >;
+			/**
+			 * The globally unique identifier for the post.
+			 */
+			guid: ContextualField< RenderedText< C >, 'view' | 'edit', C >;
+			/**
+			 * Unique identifier for the post.
+			 */
+			id: number;
+			/**
+			 * URL to the post.
+			 */
+			link: string;
+			/**
+			 * The date the post was last modified, in the site's timezone.
+			 */
+			modified: ContextualField< string, 'view' | 'edit', C >;
+			/**
+			 * The date the post was last modified, as GMT.
+			 */
+			modified_gmt: ContextualField< string, 'view' | 'edit', C >;
+			/**
+			 * An alphanumeric identifier for the post unique to its type.
+			 */
+			slug: string;
+			/**
+			 * A named status for the post.
+			 */
+			status: ContextualField< PostStatus, 'view' | 'edit', C >;
+			/**
+			 * Type of post.
+			 */
+			type: string;
+			/**
+			 * Permalink template for the post.
+			 */
+			permalink_template: ContextualField< string, 'edit', C >;
+			/**
+			 * Slug automatically generated from the post title.
+			 */
+			generated_slug: ContextualField< string, 'edit', C >;
+			/**
+			 * The title for the post.
+			 */
+			title: RenderedText< C >;
+			/**
+			 * The ID for the author of the post.
+			 */
+			author: number;
+			/**
+			 * Whether or not comments are open on the post.
+			 */
+			comment_status: ContextualField<
+				CommentingStatus,
+				'view' | 'edit',
+				C
+			>;
+			/**
+			 * Whether or not the post can be pinged.
+			 */
+			ping_status: ContextualField< PingStatus, 'view' | 'edit', C >;
+			/**
+			 * Meta fields.
+			 */
+			meta: ContextualField<
+				Record< string, string >,
+				'view' | 'edit',
+				C
+			>;
+			/**
+			 * The theme file to use to display the post.
+			 */
+			template: ContextualField< string, 'view' | 'edit', C >;
+			/**
+			 * Alternative text to display when attachment is not displayed.
+			 */
+			alt_text: string;
+			/**
+			 * The attachment caption.
+			 */
+			caption: ContextualField< string, 'edit', C >;
+			/**
+			 * The attachment description.
+			 */
+			description: ContextualField<
+				RenderedText< C >,
+				'view' | 'edit',
+				C
+			>;
+			/**
+			 * Attachment type.
+			 */
+			media_type: MediaType;
+			/**
+			 * The attachment MIME type.
+			 */
+			mime_type: string;
+			/**
+			 * Details about the media file, specific to its type.
+			 */
+			media_details: Record< string, string >;
+			/**
+			 * The ID for the associated post of the attachment.
+			 */
+			post: ContextualField< number, 'view' | 'edit', C >;
+			/**
+			 * URL to the original attachment file.
+			 */
+			source_url: string;
+			/**
+			 * List of the missing image sizes of the attachment.
+			 */
+			missing_image_sizes: ContextualField< string[], 'edit', C >;
+		}
+	}
+}
+
+export type Attachment< C extends Context > = OmitNevers<
+	_BaseEntityTypes.Attachment< C >
+>;

package/src/types/base-entity-types.ts

@@ -0,0 +1,36 @@
+/**
+ * This module exists solely to make the BaseEntityTypes namespace extensible
+ * with declaration merging:
+ *
+ * ```ts
+ * declare module './base-entity-types' {
+ *     export namespace BaseEntityTypes {
+ * 		     export interface Comment< C extends Context > {
+ * 		         id: number;
+ * 		         // ...
+ * 	       }
+ * 	   }
+ * }
+ * ```
+ *
+ * The huge upside is that consumers of @wordpress/core-data may extend the
+ * exported data types using interface merging as follows:
+ *
+ * ```ts
+ * import type { Context } from '@wordpress/core-data';
+ * declare module '@wordpress/core-data' {
+ *     export namespace BaseEntityTypes {
+ *         export interface Comment< C extends Context > {
+ *             numberOfViews: number;
+ *         }
+ *     }
+ * }
+ *
+ * import type { Comment } from '@wordpress/core-data';
+ * const c : Comment< 'view' > = ...;
+ *
+ * // c.numberOfViews is a number
+ * // c.id is still present
+ * ```
+ */
+export namespace BaseEntityTypes {}

package/src/types/comment.ts

@@ -0,0 +1,96 @@
+/**
+ * Internal dependencies
+ */
+import {
+	AvatarUrls,
+	Context,
+	ContextualField,
+	OmitNevers,
+	RenderedText,
+} from './helpers';
+import { BaseEntityTypes as _BaseEntityTypes } from './base-entity-types';
+
+export type CommentStatus = 'hold' | 'approve' | 'spam' | 'trash' | '1' | '0';
+
+declare module './base-entity-types' {
+	export namespace BaseEntityTypes {
+		export interface Comment< C extends Context > {
+			/**
+			 * Unique identifier for the comment.
+			 */
+			id: number;
+			/**
+			 * The ID of the user object, if author was a user.
+			 */
+			author: number;
+			/**
+			 * Email address for the comment author.
+			 */
+			author_email: ContextualField< string, 'edit', C >;
+			/**
+			 * IP address for the comment author.
+			 */
+			author_ip: ContextualField< string, 'edit', C >;
+			/**
+			 * Display name for the comment author.
+			 */
+			author_name: string;
+			/**
+			 * URL for the comment author.
+			 */
+			author_url: string;
+			/**
+			 * User agent for the comment author.
+			 */
+			author_user_agent: ContextualField< string, 'edit', C >;
+			/**
+			 * The content for the comment.
+			 */
+			content: RenderedText< C >;
+			/**
+			 * The date the comment was published, in the site's timezone.
+			 */
+			date: string;
+			/**
+			 * The date the comment was published, as GMT.
+			 */
+			date_gmt: ContextualField< string, 'view' | 'edit', C >;
+			/**
+			 * URL to the comment.
+			 */
+			link: string;
+			/**
+			 * The ID for the parent of the comment.
+			 */
+			parent: number;
+			/**
+			 * The ID of the associated post object.
+			 */
+			post: ContextualField< number, 'view' | 'edit', C >;
+			/**
+			 * State of the comment.
+			 */
+			status: ContextualField< CommentStatus, 'view' | 'edit', C >;
+			/**
+			 * Type of the comment.
+			 */
+			type: string;
+			/**
+			 * Avatar URLs for the comment author.
+			 */
+			author_avatar_urls: AvatarUrls;
+			/**
+			 * Meta fields.
+			 */
+			meta: ContextualField<
+				Record< string, string >,
+				'view' | 'edit',
+				C
+			>;
+		}
+	}
+}
+
+export type Comment< C extends Context > = OmitNevers<
+	_BaseEntityTypes.Comment< C >
+>;

package/src/types/helpers.ts

@@ -0,0 +1,153 @@
+/**
+ * Internal dependencies
+ */
+import { EntityRecord } from './index';
+
+export interface AvatarUrls {
+	/**
+	 * Avatar URL with image size of 24 pixels.
+	 */
+	'24': string;
+	/**
+	 * Avatar URL with image size of 48 pixels.
+	 */
+	'48': string;
+	/**
+	 * Avatar URL with image size of 96 pixels.
+	 */
+	'96': string;
+}
+
+export type MediaType = 'image' | 'file';
+export type CommentingStatus = 'open' | 'closed';
+export type PingStatus = 'open' | 'closed';
+export type PostStatus = 'publish' | 'future' | 'draft' | 'pending' | 'private';
+export type PostFormat =
+	| 'standard'
+	| 'aside'
+	| 'chat'
+	| 'gallery'
+	| 'link'
+	| 'image'
+	| 'quote'
+	| 'status'
+	| 'video'
+	| 'audio';
+
+/**
+ * The REST API context parameter.
+ */
+export type Context = 'view' | 'edit' | 'embed';
+
+/**
+ * ContextualField makes the field available only in the specified given contexts,
+ * and ensure the field is absent from the object when in a different context.
+ *
+ * @example
+ * ```ts
+ * interface Post< C extends Context > {
+ * 	…
+ * 	modified: ContextualField< string, 'edit' | 'view', C >;
+ * 	password: ContextualField< string, 'edit', C >;
+ * 	…
+ * }
+ *
+ * const post: Post<'edit'> = …
+ * // post.modified exists as a string
+ * // post.password exists as a string
+ *
+ * const post: Post<'view'> = …
+ * // post.modified still exists as a string
+ * // post.password is missing, undefined, because we're not in the `edit` context.
+ * ```
+ */
+export type ContextualField<
+	FieldType,
+	AvailableInContexts extends Context,
+	C extends Context
+> = AvailableInContexts extends C ? FieldType : never;
+
+/**
+ * Removes all the properties of type never, even the deeply nested ones.
+ *
+ * @example
+ * ```ts
+ * type MyType = {
+ *   foo: string;
+ *   bar: never;
+ *   nested: {
+ *     foo: string;
+ *     bar: never;
+ *   }
+ * }
+ * const x = {} as OmitNevers<MyType>;
+ * // x is of type { foo: string; nested: { foo: string; }}
+ * // The `never` properties were removed entirely
+ * ```
+ */
+export type OmitNevers<
+	T,
+	Nevers = {
+		[ K in keyof T ]: Exclude< T[ K ], undefined > extends never
+			? never
+			: T[ K ] extends Record< string, unknown >
+			? OmitNevers< T[ K ] >
+			: T[ K ];
+	}
+> = Pick<
+	Nevers,
+	{
+		[ K in keyof Nevers ]: Nevers[ K ] extends never ? never : K;
+	}[ keyof Nevers ]
+>;
+
+/**
+ * A string that the server renders which often involves
+ * modifications from the raw source string.
+ *
+ * For example, block HTML with the comment delimiters exists
+ * in `post_content` but those comments are stripped out when
+ * rendering to a page view. Similarly, plugins might modify
+ * content or replace shortcodes.
+ */
+export interface RenderedText< C extends Context > {
+	/**
+	 * The source string which will be rendered on page views.
+	 */
+	raw: ContextualField< string, 'edit', C >;
+	/**
+	 * The output of the raw source after processing and filtering on the server.
+	 */
+	rendered: string;
+}
+
+/**
+ * Updatable<EntityRecord> is a type describing Edited Entity Records. They are like
+ * regular Entity Records, but they have all the local edits applied on top of the REST API data.
+ *
+ * This turns certain field from an object into a string.
+ *
+ * Entities like Post have fields that only be rendered on the server, like title, excerpt,
+ * and content. The REST API exposes both the raw markup and the rendered version of those fields.
+ * For example, in the block editor, content.rendered could used as a visual preview, and
+ * content.raw could be used to populate the code editor.
+ *
+ * When updating these rendered fields, Javascript is not be able to properly render arbitrary block
+ * markup. Therefore, it stores only the raw markup without the rendered part. And since that's a string,
+ * the entire field becomes a string.
+ *
+ * @example
+ * ```ts
+ * type Post< C extends Context > {
+ *   title: RenderedText< C >;
+ * }
+ * const post = {} as Post;
+ * // post.title is an object with raw and rendered properties
+ *
+ * const updatablePost = {} as Updatable< Post >;
+ * // updatablePost.title is a string
+ * ```
+ */
+export type Updatable< T extends EntityRecord< 'edit' > > = {
+	[ K in keyof T ]: T[ K ] extends RenderedText< any > ? string : T[ K ];
+};

package/src/types/index.ts

@@ -0,0 +1,72 @@
+/**
+ * Internal dependencies
+ */
+import type { Attachment } from './attachment';
+import type { Comment } from './comment';
+import type { MenuLocation } from './menu-location';
+import type { NavMenu } from './nav-menu';
+import type { NavMenuItem } from './nav-menu-item';
+import type { NavigationArea } from './navigation-area';
+import type { Page } from './page';
+import type { Plugin } from './plugin';
+import type { Post } from './post';
+import type { Settings } from './settings';
+import type { Sidebar } from './sidebar';
+import type { Taxonomy } from './taxonomy';
+import type { Theme } from './theme';
+import type { User } from './user';
+import type { Type } from './type';
+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 { Context, Updatable } from './helpers';
+
+export type { BaseEntityTypes } from './base-entity-types';
+
+export type {
+	Context,
+	Updatable,
+	Attachment,
+	Comment,
+	MenuLocation,
+	NavMenu,
+	NavMenuItem,
+	NavigationArea,
+	Page,
+	Plugin,
+	Post,
+	Settings,
+	Sidebar,
+	Taxonomy,
+	Theme,
+	User,
+	Type,
+	Widget,
+	WidgetType,
+	WpTemplate,
+	WpTemplatePart,
+};
+
+export type EntityRecord< C extends Context > =
+	| Attachment< C >
+	| Comment< C >
+	| MenuLocation< C >
+	| NavMenu< C >
+	| NavMenuItem< C >
+	| NavigationArea< 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' > >;