Core Data: TypeScript definitions for entity records.

packages/core-data/package.json

@@ -25,6 +25,7 @@
 	"main": "build/index.js",
 	"module": "build-module/index.js",
 	"react-native": "src/index",
+	"types": "src/types/index.ts",
 	"sideEffects": [
 		"{src,build,build-module}/index.js"
 	],

packages/core-data/src/index.js

@@ -76,3 +76,4 @@ register( store );
 export { default as EntityProvider } from './entity-provider';
 export * from './entity-provider';
 export * from './fetch';
+export * from './types';

packages/core-data/src/types/README.md

@@ -0,0 +1,238 @@
+# 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.
+
+## Extending
+
+You can extend the entity record definitions using [TypeScript's declaration merging](https://www.typescriptlang.org/docs/handbook/declaration-merging.html).
+
+For example, if you're building a plugin that displays a number of views of each comment, you can add a new `numberOfViews` field to the `Comment` type like this:
+
+```ts
+// In core-data
+export namespace WPBaseTypes {
+	// This is the parent interface – it can be extended
+	export interface Comment< C extends Context > {
+		id: number;
+		// ...
+	}
+}
+
+// This the child type used in function signatures – it cannot be extended
+export type Comment< C extends Context > = OmitNevers<
+	WPBaseTypes.Comment< C >
+>;
+
+// In the plugin
+import type { Context } from '@wordpress/core-data';
+// Target the core-data module
+declare module '@wordpress/core-data' {
+	// Extend the WPBaseTypes namespace through declaration merging
+	export namespace WPBaseTypes {
+		// Extend the parent Commet interface through declaration merging
+		export interface Comment< C extends Context > {
+			numberOfViews: number;
+		}
+	}
+}
+
+import type { Comment } from '@wordpress/core-data';
+// Create an instance of the child type
+const c : Comment< 'view' > = ...;
+
+// Extending the parent had the desired effect on the child type:
+// c.numberOfViews is a number
+// c.id is still present
+```
+
+Of course, you will also need to extend the REST API to expose the numberOfViews property.

packages/core-data/src/types/attachment.ts

@@ -0,0 +1,146 @@
+/**
+ * Internal dependencies
+ */
+import {
+	Context,
+	ContextualField,
+	MediaType,
+	PostStatus,
+	RenderedText,
+	OmitNevers,
+	CommentingStatus,
+	PingStatus,
+} from './helpers';
+
+import { WPBaseTypes as _WPBaseTypes } from './wp-base-types';
+
+declare module './wp-base-types' {
+	export namespace WPBaseTypes {
+		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<
+	_WPBaseTypes.Attachment< C >
+>;