[@wordpress/core-data] add new definitions (#37086)

* [@wordpress/core-data] add new definitions

* fix format

types/wordpress__core-data/actions.d.ts

@@ -0,0 +1,90 @@
+import { Schema } from '@wordpress/api-fetch';
+import { Autosave, Entity } from './';
+
+/**
+ * Adds new entities.
+ *
+ * @param entities - Entities received.
+ */
+export function addEntities(entities: Entity[]): void;
+
+/**
+ * Returns an action object used in signalling that the autosaves for a post have been received.
+ *
+ * @param postId - The id of the post that is parent to the autosave.
+ * @param autosaves - An array of autosaves or singular autosave object.
+ */
+export function receiveAutosaves(postId: number, autosaves: Autosave | Autosave[]): void;
+
+/**
+ * Returns an action used in signalling that the current user has been received.
+ *
+ * @param currentUser - Current user object.
+ */
+export function receiveCurrentUser(currentUser: Schema.User): void;
+
+/**
+ * Returns an action object used in signalling that the preview data for a given URl has been
+ * received.
+ *
+ * @param url - URL to preview the embed for.
+ * @param preview - Preview data.
+ */
+export function receiveEmbedPreview(url: string, preview: Record<string, any>): void;
+
+/**
+ * Returns an action object used in signalling that entity records have been received.
+ *
+ * @param kind - Kind of the received entity.
+ * @param name - Name of the received entity.
+ * @param records - Records received.
+ * @param query - Query Object.
+ * @param invalidateCache - Should invalidate query caches?
+ */
+export function receiveEntityRecords(
+    kind: string,
+    name: string,
+    records: Record<string, any> | Array<Record<string, any>>,
+    query?: Record<string, any>,
+    invalidateCache?: boolean
+): void;
+
+/**
+ * Returns an action object used in signalling that the index has been received.
+ *
+ * @param themeSupports - Theme support for the current theme.
+ */
+export function receiveThemeSupports(themeSupports: Schema.Theme['theme_supports']): void;
+
+/**
+ * Returns an action object used in signalling that Upload permissions have been received.
+ *
+ * @param hasUploadPermissions - Does the user have permission to upload files?
+ */
+export function receiveUploadPermissions(hasUploadPermissions: boolean): void;
+
+/**
+ * Returns an action object used in signalling that the current user has permission to perform an
+ * action on a REST resource.
+ *
+ * @param key - A key that represents the action and REST resource.
+ * @param isAllowed - Whether or not the user can perform the action.
+ */
+export function receiveUserPermission(key: string, isAllowed: boolean): void;
+
+/**
+ * Returns an action object used in signalling that authors have been received.
+ *
+ * @param queryID - Query ID.
+ * @param users - Users received.
+ */
+export function receiveUserQuery(queryID: string, users: Schema.User | Schema.User[]): void;
+
+/**
+ * Action triggered to save an entity record.
+ *
+ * @param kind - Kind of the received entity.
+ * @param name - Name of the received entity.
+ * @param record - Record to be saved.
+ */
+export function saveEntityRecord(kind: string, name: string, record: Record<string, any>): IterableIterator<void>;

types/wordpress__core-data/index.d.ts

@@ -0,0 +1,25 @@
+// Type definitions for @wordpress/core-data 2.4
+// Project: https://github.com/WordPress/gutenberg/tree/master/packages/core-data/README.md
+// Definitions by: Derek Sifford <https://github.com/dsifford>
+// Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
+// TypeScript Version: 3.5
+
+import { Schema } from '@wordpress/api-fetch';
+import { dispatch, select } from '@wordpress/data';
+
+declare module '@wordpress/data' {
+    function dispatch(key: 'core'): typeof import('./actions');
+    function select(key: 'core'): typeof import('./selectors');
+}
+
+export interface Autosave extends Schema.PostRevision<'edit'> {
+    preview_link: string;
+}
+
+export interface Entity {
+    baseURL: string;
+    key?: string;
+    kind: string;
+    name: string;
+    plural?: string;
+}

types/wordpress__core-data/selectors.d.ts

@@ -0,0 +1,161 @@
+import { Schema } from '@wordpress/api-fetch';
+
+import { Autosave, Entity } from './';
+
+/**
+ * Returns whether the current user can perform the given action on the given REST resource.
+ *
+ * Calling this may trigger an OPTIONS request to the REST API via the `canUser()` resolver.
+ *
+ * https://developer.wordpress.org/rest-api/reference/
+ *
+ * @param action - Action to check. One of: 'create', 'read', 'update', 'delete'.
+ * @param resource - REST resource to check, e.g. 'media' or 'posts'.
+ * @param id - Optional ID of the rest resource to check.
+ *
+ * @returns Whether or not the user can perform the action, or `undefined` if the OPTIONS request is
+ * still being made.
+ */
+export function canUser(
+    action: 'create' | 'read' | 'update' | 'delete',
+    resource: string,
+    id: string | number
+): boolean | undefined;
+
+/**
+ * Returns all available authors.
+ */
+export function getAuthors(): Schema.User[];
+
+/**
+ * Returns the autosave for the post and author.
+ *
+ * @param postType - The type of the parent post.
+ * @param postId - The id of the parent post.
+ * @param authorId - The id of the author.
+ *
+ * @returns The autosave for the post and author.
+ */
+export function getAutosave(postType: string, postId: number, authorId: number): Autosave | undefined;
+
+/**
+ * Returns the latest autosaves for the post.
+ *
+ * May return multiple autosaves since the backend stores one autosave per author for each post.
+ *
+ * @param postType - The type of the parent post.
+ * @param postId - The id of the parent post.
+ *
+ * @returns An array of autosaves for the post, or undefined if there is none.
+ */
+export function getAutosaves(postType: string, postId: number): Autosave[] | undefined;
+
+/**
+ * Returns the current user.
+ */
+export function getCurrentUser(): Schema.User;
+
+/**
+ * Returns the embed preview for the given URL.
+ *
+ * @param url - Embedded URL.
+ *
+ * @returns Undefined if the preview has not been fetched, otherwise, the preview fetched from the embed preview API.
+ */
+export function getEmbedPreview(url: string): Record<string, any> | undefined;
+
+/**
+ * Returns whether the entities for the give kind are loaded.
+ *
+ * @param kind - Entity kind.
+ */
+export function getEntitiesByKind(kind: string): Entity[];
+
+/**
+ * Returns the entity object given its kind and name.
+ *
+ * @param kind - Entity kind.
+ * @param name - Entity name.
+ */
+export function getEntity(kind: string, name: string): Entity | undefined;
+
+/**
+ * Returns the Entity's record object by key.
+ *
+ * @param kind - Entity kind.
+ * @param name - Entity name.
+ * @param key - Record's key
+ */
+export function getEntityRecord(kind: string, name: string, key: number): Record<string, any> | undefined;
+
+/**
+ * Returns the Entity's records.
+ *
+ * @param kind - Entity kind.
+ * @param name - Entity name.
+ * @param query - Optional terms query.
+ *
+ * @returns Records.
+ */
+export function getEntityRecords(kind: string, name: string, query?: Record<string, any>): Array<Record<string, any>>;
+
+/**
+ * Return theme supports data in the index.
+ */
+export function getThemeSupports(): Partial<Schema.Theme['theme_supports']>;
+
+/**
+ * Returns all the users returned by a query ID.
+ *
+ * @param queryID - Query ID.
+ *
+ * @returns Users list.
+ */
+export function getUserQueryResults(queryId: string): Schema.User[];
+
+/**
+ * Returns `true` if the REST request for autosaves has completed.
+ *
+ * @param postType - The type of the parent post.
+ * @param postId - The id of the parent post.
+ *
+ * @returns True if the REST request was completed. False otherwise.
+ */
+export function hasFetchedAutosaves(postType: string, postId: number): boolean;
+
+/**
+ * Returns whether the current user can upload media.
+ *
+ * Calling this may trigger an OPTIONS request to the REST API via the `canUser()` resolver.
+ *
+ * https://developer.wordpress.org/rest-api/reference/
+ *
+ * @deprecated since 5.0. Callers should use the more generic `canUser()` selector instead of
+ *                        `hasUploadPermissions()`, e.g. `canUser( 'create', 'media' )`.
+ *
+ * @returns Whether or not the user can upload media. Defaults to `true` if the OPTIONS request is
+ * being made.
+ */
+export function hasUploadPermissions(): boolean;
+
+/**
+ * Determines if the returned preview is an oEmbed link fallback.
+ *
+ * WordPress can be configured to return a simple link to a URL if it is not embeddable. We need to
+ * be able to determine if a URL is embeddable or not, based on what we get back from the oEmbed
+ * preview API.
+ *
+ * @param url - Embedded URL.
+ *
+ * @returns Is the preview for the URL an oEmbed link fallback.
+ */
+export function isPreviewEmbedFallback(url: string): boolean;
+
+/**
+ * Returns `true` if a request is in progress for embed preview data, or `false` otherwise.
+ *
+ * @param url - URL the preview would be for.
+ *
+ * @returns Whether a request is in progress for an embed preview.
+ */
+export function isRequestingEmbedPreview(url: string): boolean;

types/wordpress__core-data/tsconfig.json

@@ -0,0 +1,27 @@
+{
+    "compilerOptions": {
+        "module": "commonjs",
+        "lib": ["dom", "es6"],
+        "noImplicitAny": true,
+        "noImplicitThis": true,
+        "strictNullChecks": true,
+        "strictFunctionTypes": true,
+        "baseUrl": "../",
+        "typeRoots": ["../"],
+        "types": [],
+        "noEmit": true,
+        "forceConsistentCasingInFileNames": true,
+        "paths": {
+            "@wordpress/api-fetch": ["wordpress__api-fetch"],
+            "@wordpress/core-data": ["wordpress__core-data"],
+            "@wordpress/element": ["wordpress__element"],
+            "@wordpress/data": ["wordpress__data"]
+        }
+    },
+    "files": [
+        "actions.d.ts",
+        "index.d.ts",
+        "selectors.d.ts",
+        "wordpress__core-data-tests.ts"
+    ]
+}

types/wordpress__core-data/tslint.json

@@ -0,0 +1 @@
+{ "extends": "dtslint/dt.json" }

types/wordpress__core-data/wordpress__core-data-tests.ts

@@ -0,0 +1,84 @@
+import { Schema } from '@wordpress/api-fetch';
+import { dispatch, select } from '@wordpress/data';
+
+declare const USER_VIEW: Schema.User;
+
+//
+// actions
+//
+
+// $ExpectType void
+dispatch('core').addEntities([{ kind: 'postType', baseURL: '/wp/v2/pages', name: 'page' }]);
+
+// $ExpectType void
+dispatch('core').receiveAutosaves(123, []);
+
+// $ExpectType void
+dispatch('core').receiveCurrentUser(USER_VIEW);
+
+// $ExpectType void
+dispatch('core').receiveEmbedPreview('https://foo.bar', { foo: 'bar' });
+
+// $ExpectType void
+dispatch('core').receiveEntityRecords('postType', 'page', []);
+
+// $ExpectType void
+dispatch('core').receiveThemeSupports({ formats: [], 'responsive-embeds': true, 'post-thumbnails': true });
+
+// $ExpectType void
+dispatch('core').receiveUploadPermissions(true);
+
+// $ExpectType void
+dispatch('core').receiveUserPermission('media', true);
+
+// $ExpectType void
+dispatch('core').receiveUserQuery('foo', [USER_VIEW, USER_VIEW]);
+
+// $ExpectType void
+dispatch('core').receiveUserQuery('foo', USER_VIEW);
+
+// $ExpectType IterableIterator<void>
+dispatch('core').saveEntityRecord('foo', 'bar', { foo: 'bar' });
+
+//
+// selectors
+//
+
+// $ExpectType boolean | undefined
+select('core').canUser('create', 'media', 1);
+
+// $ExpectType Autosave | undefined
+select('core').getAutosave('post', 1, 1);
+
+// $ExpectType Autosave[] | undefined
+select('core').getAutosaves('post', 1);
+
+// $ExpectType Record<string, any> | undefined
+select('core').getEmbedPreview('https://foo.bar');
+
+// $ExpectType Entity[]
+select('core').getEntitiesByKind('postType');
+
+// $ExpectType Entity | undefined
+select('core').getEntity('foo', 'bar');
+
+// $ExpectType Record<string, any> | undefined
+select('core').getEntityRecord('postType', 'page', 1);
+
+// $ExpectType Record<string, any>[]
+select('core').getEntityRecords('foo', 'bar');
+
+// $ExpectType Record<string, any>[]
+select('core').getEntityRecords('foo', 'bar', { foo: 'foo', bar: { baz: 'baz' } });
+
+// $ExpectType boolean
+select('core').hasFetchedAutosaves('post', 1);
+
+// $ExpectType boolean
+select('core').hasUploadPermissions();
+
+// $ExpectType boolean
+select('core').isPreviewEmbedFallback('https://foo.bar');
+
+// $ExpectType boolean
+select('core').isRequestingEmbedPreview('https://foo.bar');