diff --git a/docs/reference-guides/data/data-core.md b/docs/reference-guides/data/data-core.md index 7818ccae12873..455808c6fda65 100644 --- a/docs/reference-guides/data/data-core.md +++ b/docs/reference-guides/data/data-core.md @@ -18,14 +18,14 @@ Calling this may trigger an OPTIONS request to the REST API via the _Parameters_ -- _state_ `Object`: Data state. +- _state_ `State`: Data state. - _action_ `string`: Action to check. One of: 'create', 'read', 'update', 'delete'. - _resource_ `string`: REST resource to check, e.g. 'media' or 'posts'. -- _id_ `string=`: Optional ID of the rest resource to check. +- _id_ `RecordKey`: Optional ID of the rest resource to check. _Returns_ -- `boolean|undefined`: Whether or not the user can perform the action, or `undefined` if the OPTIONS request is still being made. +- `boolean | undefined`: Whether or not the user can perform the action, or `undefined` if the OPTIONS request is still being made. ### canUserEditEntityRecord @@ -38,14 +38,14 @@ Calling this may trigger an OPTIONS request to the REST API via the _Parameters_ -- _state_ `Object`: Data state. +- _state_ `State`: Data state. - _kind_ `string`: Entity kind. - _name_ `string`: Entity name. -- _recordId_ `string`: Record's id. +- _recordId_ `RecordKey`: Record's id. _Returns_ -- `boolean|undefined`: Whether or not the user can edit, or `undefined` if the OPTIONS request is still being made. +- `boolean | undefined`: Whether or not the user can edit, or `undefined` if the OPTIONS request is still being made. ### getAuthors @@ -55,12 +55,12 @@ Returns all available authors. _Parameters_ -- _state_ `Object`: Data state. -- _query_ `Object|undefined`: Optional object of query parameters to include with request. +- _state_ `State`: Data state. +- _query_ `EntityQuery< any >`: Optional object of query parameters to include with request. _Returns_ -- `Array`: Authors list. +- `User< 'edit' >[]`: Authors list. ### getAutosave @@ -68,14 +68,14 @@ Returns the autosave for the post and author. _Parameters_ -- _state_ `Object`: State tree. +- _state_ `State`: State tree. - _postType_ `string`: The type of the parent post. -- _postId_ `number`: The id of the parent post. -- _authorId_ `number`: The id of the author. +- _postId_ `RecordKey`: The id of the parent post. +- _authorId_ `RecordKey`: The id of the author. _Returns_ -- `?Object`: The autosave for the post and author. +- `EntityRecord | undefined`: The autosave for the post and author. ### getAutosaves @@ -86,13 +86,13 @@ author for each post. _Parameters_ -- _state_ `Object`: State tree. +- _state_ `State`: State tree. - _postType_ `string`: The type of the parent post. -- _postId_ `number`: The id of the parent post. +- _postId_ `RecordKey`: The id of the parent post. _Returns_ -- `?Array`: An array of autosaves for the post, or undefined if there is none. +- `Array< any > | undefined`: An array of autosaves for the post, or undefined if there is none. ### getBlockPatternCategories @@ -100,11 +100,11 @@ Retrieve the list of registered block pattern categories. _Parameters_ -- _state_ `Object`: Data state. +- _state_ `State`: Data state. _Returns_ -- `Array`: Block pattern category list. +- `Array< any >`: Block pattern category list. ### getBlockPatterns @@ -112,11 +112,11 @@ Retrieve the list of registered block patterns. _Parameters_ -- _state_ `Object`: Data state. +- _state_ `State`: Data state. _Returns_ -- `Array`: Block pattern list. +- `Array< any >`: Block pattern list. ### getCurrentTheme @@ -124,11 +124,11 @@ Return the current theme. _Parameters_ -- _state_ `Object`: Data state. +- _state_ `State`: Data state. _Returns_ -- `Object`: The current theme. +- `any`: The current theme. ### getCurrentUser @@ -136,11 +136,11 @@ Returns the current user. _Parameters_ -- _state_ `Object`: Data state. +- _state_ `State`: Data state. _Returns_ -- `Object`: Current user object. +- `User< 'edit' >`: Current user object. ### getEditedEntityRecord @@ -148,14 +148,14 @@ Returns the specified entity record, merged with its edits. _Parameters_ -- _state_ `Object`: State tree. +- _state_ `State`: State tree. - _kind_ `string`: Entity kind. - _name_ `string`: Entity name. -- _recordId_ `number|string`: Record ID. +- _recordId_ `RecordKey`: Record ID. _Returns_ -- `Object?`: The entity record, merged with its edits. +- `EntityRecord | undefined`: The entity record, merged with its edits. ### getEmbedPreview @@ -163,12 +163,12 @@ Returns the embed preview for the given URL. _Parameters_ -- _state_ `Object`: Data state. +- _state_ `State`: Data state. - _url_ `string`: Embedded URL. _Returns_ -- `*`: Undefined if the preview has not been fetched, otherwise, the preview fetched from the embed preview API. +- `any`: Undefined if the preview has not been fetched, otherwise, the preview fetched from the embed preview API. ### getEntitiesByKind @@ -178,12 +178,12 @@ Returns the loaded entities for the given kind. _Parameters_ -- _state_ `Object`: Data state. +- _state_ `State`: Data state. - _kind_ `string`: Entity kind. _Returns_ -- `Array`: Array of entities with config matching kind. +- `Array< any >`: Array of entities with config matching kind. ### getEntitiesConfig @@ -191,12 +191,12 @@ Returns the loaded entities for the given kind. _Parameters_ -- _state_ `Object`: Data state. +- _state_ `State`: Data state. - _kind_ `string`: Entity kind. _Returns_ -- `Array`: Array of entities with config matching kind. +- `Array< any >`: Array of entities with config matching kind. ### getEntity @@ -206,13 +206,13 @@ Returns the entity config given its kind and name. _Parameters_ -- _state_ `Object`: Data state. +- _state_ `State`: Data state. - _kind_ `string`: Entity kind. - _name_ `string`: Entity name. _Returns_ -- `Object`: Entity config +- `any`: Entity config ### getEntityConfig @@ -220,13 +220,13 @@ Returns the entity config given its kind and name. _Parameters_ -- _state_ `Object`: Data state. +- _state_ `State`: Data state. - _kind_ `string`: Entity kind. - _name_ `string`: Entity name. _Returns_ -- `Object`: Entity config +- `any`: Entity config ### getEntityRecord @@ -236,15 +236,15 @@ entity object if it exists and is received. _Parameters_ -- _state_ `Object`: State tree +- _state_ `State`: State tree - _kind_ `string`: Entity kind. - _name_ `string`: Entity name. -- _key_ `number`: Record's key -- _query_ `?Object`: Optional query. +- _key_ `RecordKey`: Record's key +- _query_ `EntityQuery< any >`: Optional query. _Returns_ -- `Object|undefined`: Record. +- `EntityRecord | undefined`: Record. ### getEntityRecordEdits @@ -252,14 +252,14 @@ Returns the specified entity record's edits. _Parameters_ -- _state_ `Object`: State tree. +- _state_ `State`: State tree. - _kind_ `string`: Entity kind. - _name_ `string`: Entity name. -- _recordId_ `number`: Record ID. +- _recordId_ `RecordKey`: Record ID. _Returns_ -- `Object?`: The entity record's edits. +- `Optional< any >`: The entity record's edits. ### getEntityRecordNonTransientEdits @@ -271,14 +271,14 @@ They are defined in the entity's config. _Parameters_ -- _state_ `Object`: State tree. +- _state_ `State`: State tree. - _kind_ `string`: Entity kind. - _name_ `string`: Entity name. -- _recordId_ `number`: Record ID. +- _recordId_ `RecordKey`: Record ID. _Returns_ -- `Object?`: The entity record's non transient edits. +- `Optional< any >`: The entity record's non transient edits. ### getEntityRecords @@ -286,14 +286,14 @@ Returns the Entity's records. _Parameters_ -- _state_ `Object`: State tree +- _state_ `State`: State tree - _kind_ `string`: Entity kind. - _name_ `string`: Entity name. -- _query_ `?Object`: Optional terms query. +- _query_ `EntityQuery< any >`: Optional terms query. _Returns_ -- `?Array`: Records. +- `Array< EntityRecord > | undefined`: Records. ### getLastEntityDeleteError @@ -301,14 +301,14 @@ Returns the specified entity record's last delete error. _Parameters_ -- _state_ `Object`: State tree. +- _state_ `State`: State tree. - _kind_ `string`: Entity kind. - _name_ `string`: Entity name. -- _recordId_ `number`: Record ID. +- _recordId_ `RecordKey`: Record ID. _Returns_ -- `Object?`: The entity record's save error. +- `any`: The entity record's save error. ### getLastEntitySaveError @@ -316,14 +316,14 @@ Returns the specified entity record's last save error. _Parameters_ -- _state_ `Object`: State tree. +- _state_ `State`: State tree. - _kind_ `string`: Entity kind. - _name_ `string`: Entity name. -- _recordId_ `number`: Record ID. +- _recordId_ `RecordKey`: Record ID. _Returns_ -- `Object?`: The entity record's save error. +- `any`: The entity record's save error. ### getRawEntityRecord @@ -332,14 +332,14 @@ with its attributes mapped to their raw values. _Parameters_ -- _state_ `Object`: State tree. +- _state_ `State`: State tree. - _kind_ `string`: Entity kind. - _name_ `string`: Entity name. -- _key_ `number`: Record's key. +- _key_ `RecordKey`: Record's key. _Returns_ -- `Object?`: Object with the entity's raw attributes. +- `EntityRecord | undefined`: Object with the entity's raw attributes. ### getRedoEdit @@ -348,11 +348,11 @@ for the entity records edits history, if any. _Parameters_ -- _state_ `Object`: State tree. +- _state_ `State`: State tree. _Returns_ -- `Object?`: The edit. +- `Optional< any >`: The edit. ### getReferenceByDistinctEdits @@ -369,11 +369,11 @@ _Usage_ _Parameters_ -- _state_ `Object`: Editor state. +- _state_ `State`: Editor state. _Returns_ -- `*`: A value whose reference will change only when an edit occurs. +- A value whose reference will change only when an edit occurs. ### getThemeSupports @@ -381,11 +381,11 @@ Return theme supports data in the index. _Parameters_ -- _state_ `Object`: Data state. +- _state_ `State`: Data state. _Returns_ -- `*`: Index data. +- `any`: Index data. ### getUndoEdit @@ -394,11 +394,11 @@ for the entity records edits history, if any. _Parameters_ -- _state_ `Object`: State tree. +- _state_ `State`: State tree. _Returns_ -- `Object?`: The edit. +- `Optional< any >`: The edit. ### getUserQueryResults @@ -406,12 +406,12 @@ Returns all the users returned by a query ID. _Parameters_ -- _state_ `Object`: Data state. +- _state_ `State`: Data state. - _queryID_ `string`: Query ID. _Returns_ -- `Array`: Users list. +- `User< 'edit' >[]`: Users list. ### hasEditsForEntityRecord @@ -420,10 +420,10 @@ and false otherwise. _Parameters_ -- _state_ `Object`: State tree. +- _state_ `State`: State tree. - _kind_ `string`: Entity kind. - _name_ `string`: Entity name. -- _recordId_ `number|string`: Record ID. +- _recordId_ `RecordKey`: Record ID. _Returns_ @@ -436,10 +436,10 @@ or false otherwise. _Parameters_ -- _state_ `Object`: State tree +- _state_ `State`: State tree - _kind_ `string`: Entity kind. - _name_ `string`: Entity name. -- _query_ `?Object`: Optional terms query. +- _query_ `EntityQuery< any >`: Optional terms query. _Returns_ @@ -451,9 +451,9 @@ Returns true if the REST request for autosaves has completed. _Parameters_ -- _state_ `Object`: State tree. +- _state_ `State`: State tree. - _postType_ `string`: The type of the parent post. -- _postId_ `number`: The id of the parent post. +- _postId_ `RecordKey`: The id of the parent post. _Returns_ @@ -466,7 +466,7 @@ for the entity records edits history, and false otherwise. _Parameters_ -- _state_ `Object`: State tree. +- _state_ `State`: State tree. _Returns_ @@ -479,7 +479,7 @@ for the entity records edits history, and false otherwise. _Parameters_ -- _state_ `Object`: State tree. +- _state_ `State`: State tree. _Returns_ @@ -491,10 +491,10 @@ Returns true if the specified entity record is autosaving, and false otherwise. _Parameters_ -- _state_ `Object`: State tree. +- _state_ `State`: State tree. - _kind_ `string`: Entity kind. - _name_ `string`: Entity name. -- _recordId_ `number`: Record ID. +- _recordId_ `RecordKey`: Record ID. _Returns_ @@ -506,10 +506,10 @@ Returns true if the specified entity record is deleting, and false otherwise. _Parameters_ -- _state_ `Object`: State tree. +- _state_ `State`: State tree. - _kind_ `string`: Entity kind. - _name_ `string`: Entity name. -- _recordId_ `number`: Record ID. +- _recordId_ `RecordKey`: Record ID. _Returns_ @@ -525,7 +525,7 @@ get back from the oEmbed preview API. _Parameters_ -- _state_ `Object`: Data state. +- _state_ `State`: Data state. - _url_ `string`: Embedded URL. _Returns_ @@ -539,7 +539,7 @@ otherwise. _Parameters_ -- _state_ `Object`: Data state. +- _state_ `State`: Data state. - _url_ `string`: URL the preview would be for. _Returns_ @@ -552,10 +552,10 @@ Returns true if the specified entity record is saving, and false otherwise. _Parameters_ -- _state_ `Object`: State tree. +- _state_ `State`: State tree. - _kind_ `string`: Entity kind. - _name_ `string`: Entity name. -- _recordId_ `number|string`: Record ID. +- _recordId_ `RecordKey`: Record ID. _Returns_ diff --git a/packages/core-data/README.md b/packages/core-data/README.md index ea5395dbde413..319777841c313 100644 --- a/packages/core-data/README.md +++ b/packages/core-data/README.md @@ -265,14 +265,14 @@ Calling this may trigger an OPTIONS request to the REST API via the _Parameters_ -- _state_ `Object`: Data state. +- _state_ `State`: Data state. - _action_ `string`: Action to check. One of: 'create', 'read', 'update', 'delete'. - _resource_ `string`: REST resource to check, e.g. 'media' or 'posts'. -- _id_ `string=`: Optional ID of the rest resource to check. +- _id_ `RecordKey`: Optional ID of the rest resource to check. _Returns_ -- `boolean|undefined`: Whether or not the user can perform the action, or `undefined` if the OPTIONS request is still being made. +- `boolean | undefined`: Whether or not the user can perform the action, or `undefined` if the OPTIONS request is still being made. ### canUserEditEntityRecord @@ -285,14 +285,14 @@ Calling this may trigger an OPTIONS request to the REST API via the _Parameters_ -- _state_ `Object`: Data state. +- _state_ `State`: Data state. - _kind_ `string`: Entity kind. - _name_ `string`: Entity name. -- _recordId_ `string`: Record's id. +- _recordId_ `RecordKey`: Record's id. _Returns_ -- `boolean|undefined`: Whether or not the user can edit, or `undefined` if the OPTIONS request is still being made. +- `boolean | undefined`: Whether or not the user can edit, or `undefined` if the OPTIONS request is still being made. ### getAuthors @@ -302,12 +302,12 @@ Returns all available authors. _Parameters_ -- _state_ `Object`: Data state. -- _query_ `Object|undefined`: Optional object of query parameters to include with request. +- _state_ `State`: Data state. +- _query_ `EntityQuery< any >`: Optional object of query parameters to include with request. _Returns_ -- `Array`: Authors list. +- `User< 'edit' >[]`: Authors list. ### getAutosave @@ -315,14 +315,14 @@ Returns the autosave for the post and author. _Parameters_ -- _state_ `Object`: State tree. +- _state_ `State`: State tree. - _postType_ `string`: The type of the parent post. -- _postId_ `number`: The id of the parent post. -- _authorId_ `number`: The id of the author. +- _postId_ `RecordKey`: The id of the parent post. +- _authorId_ `RecordKey`: The id of the author. _Returns_ -- `?Object`: The autosave for the post and author. +- `EntityRecord | undefined`: The autosave for the post and author. ### getAutosaves @@ -333,13 +333,13 @@ author for each post. _Parameters_ -- _state_ `Object`: State tree. +- _state_ `State`: State tree. - _postType_ `string`: The type of the parent post. -- _postId_ `number`: The id of the parent post. +- _postId_ `RecordKey`: The id of the parent post. _Returns_ -- `?Array`: An array of autosaves for the post, or undefined if there is none. +- `Array< any > | undefined`: An array of autosaves for the post, or undefined if there is none. ### getBlockPatternCategories @@ -347,11 +347,11 @@ Retrieve the list of registered block pattern categories. _Parameters_ -- _state_ `Object`: Data state. +- _state_ `State`: Data state. _Returns_ -- `Array`: Block pattern category list. +- `Array< any >`: Block pattern category list. ### getBlockPatterns @@ -359,11 +359,11 @@ Retrieve the list of registered block patterns. _Parameters_ -- _state_ `Object`: Data state. +- _state_ `State`: Data state. _Returns_ -- `Array`: Block pattern list. +- `Array< any >`: Block pattern list. ### getCurrentTheme @@ -371,11 +371,11 @@ Return the current theme. _Parameters_ -- _state_ `Object`: Data state. +- _state_ `State`: Data state. _Returns_ -- `Object`: The current theme. +- `any`: The current theme. ### getCurrentUser @@ -383,11 +383,11 @@ Returns the current user. _Parameters_ -- _state_ `Object`: Data state. +- _state_ `State`: Data state. _Returns_ -- `Object`: Current user object. +- `User< 'edit' >`: Current user object. ### getEditedEntityRecord @@ -395,14 +395,14 @@ Returns the specified entity record, merged with its edits. _Parameters_ -- _state_ `Object`: State tree. +- _state_ `State`: State tree. - _kind_ `string`: Entity kind. - _name_ `string`: Entity name. -- _recordId_ `number|string`: Record ID. +- _recordId_ `RecordKey`: Record ID. _Returns_ -- `Object?`: The entity record, merged with its edits. +- `EntityRecord | undefined`: The entity record, merged with its edits. ### getEmbedPreview @@ -410,12 +410,12 @@ Returns the embed preview for the given URL. _Parameters_ -- _state_ `Object`: Data state. +- _state_ `State`: Data state. - _url_ `string`: Embedded URL. _Returns_ -- `*`: Undefined if the preview has not been fetched, otherwise, the preview fetched from the embed preview API. +- `any`: Undefined if the preview has not been fetched, otherwise, the preview fetched from the embed preview API. ### getEntitiesByKind @@ -425,12 +425,12 @@ Returns the loaded entities for the given kind. _Parameters_ -- _state_ `Object`: Data state. +- _state_ `State`: Data state. - _kind_ `string`: Entity kind. _Returns_ -- `Array`: Array of entities with config matching kind. +- `Array< any >`: Array of entities with config matching kind. ### getEntitiesConfig @@ -438,12 +438,12 @@ Returns the loaded entities for the given kind. _Parameters_ -- _state_ `Object`: Data state. +- _state_ `State`: Data state. - _kind_ `string`: Entity kind. _Returns_ -- `Array`: Array of entities with config matching kind. +- `Array< any >`: Array of entities with config matching kind. ### getEntity @@ -453,13 +453,13 @@ Returns the entity config given its kind and name. _Parameters_ -- _state_ `Object`: Data state. +- _state_ `State`: Data state. - _kind_ `string`: Entity kind. - _name_ `string`: Entity name. _Returns_ -- `Object`: Entity config +- `any`: Entity config ### getEntityConfig @@ -467,13 +467,13 @@ Returns the entity config given its kind and name. _Parameters_ -- _state_ `Object`: Data state. +- _state_ `State`: Data state. - _kind_ `string`: Entity kind. - _name_ `string`: Entity name. _Returns_ -- `Object`: Entity config +- `any`: Entity config ### getEntityRecord @@ -483,15 +483,15 @@ entity object if it exists and is received. _Parameters_ -- _state_ `Object`: State tree +- _state_ `State`: State tree - _kind_ `string`: Entity kind. - _name_ `string`: Entity name. -- _key_ `number`: Record's key -- _query_ `?Object`: Optional query. +- _key_ `RecordKey`: Record's key +- _query_ `EntityQuery< any >`: Optional query. _Returns_ -- `Object|undefined`: Record. +- `EntityRecord | undefined`: Record. ### getEntityRecordEdits @@ -499,14 +499,14 @@ Returns the specified entity record's edits. _Parameters_ -- _state_ `Object`: State tree. +- _state_ `State`: State tree. - _kind_ `string`: Entity kind. - _name_ `string`: Entity name. -- _recordId_ `number`: Record ID. +- _recordId_ `RecordKey`: Record ID. _Returns_ -- `Object?`: The entity record's edits. +- `Optional< any >`: The entity record's edits. ### getEntityRecordNonTransientEdits @@ -518,14 +518,14 @@ They are defined in the entity's config. _Parameters_ -- _state_ `Object`: State tree. +- _state_ `State`: State tree. - _kind_ `string`: Entity kind. - _name_ `string`: Entity name. -- _recordId_ `number`: Record ID. +- _recordId_ `RecordKey`: Record ID. _Returns_ -- `Object?`: The entity record's non transient edits. +- `Optional< any >`: The entity record's non transient edits. ### getEntityRecords @@ -533,14 +533,14 @@ Returns the Entity's records. _Parameters_ -- _state_ `Object`: State tree +- _state_ `State`: State tree - _kind_ `string`: Entity kind. - _name_ `string`: Entity name. -- _query_ `?Object`: Optional terms query. +- _query_ `EntityQuery< any >`: Optional terms query. _Returns_ -- `?Array`: Records. +- `Array< EntityRecord > | undefined`: Records. ### getLastEntityDeleteError @@ -548,14 +548,14 @@ Returns the specified entity record's last delete error. _Parameters_ -- _state_ `Object`: State tree. +- _state_ `State`: State tree. - _kind_ `string`: Entity kind. - _name_ `string`: Entity name. -- _recordId_ `number`: Record ID. +- _recordId_ `RecordKey`: Record ID. _Returns_ -- `Object?`: The entity record's save error. +- `any`: The entity record's save error. ### getLastEntitySaveError @@ -563,14 +563,14 @@ Returns the specified entity record's last save error. _Parameters_ -- _state_ `Object`: State tree. +- _state_ `State`: State tree. - _kind_ `string`: Entity kind. - _name_ `string`: Entity name. -- _recordId_ `number`: Record ID. +- _recordId_ `RecordKey`: Record ID. _Returns_ -- `Object?`: The entity record's save error. +- `any`: The entity record's save error. ### getRawEntityRecord @@ -579,14 +579,14 @@ with its attributes mapped to their raw values. _Parameters_ -- _state_ `Object`: State tree. +- _state_ `State`: State tree. - _kind_ `string`: Entity kind. - _name_ `string`: Entity name. -- _key_ `number`: Record's key. +- _key_ `RecordKey`: Record's key. _Returns_ -- `Object?`: Object with the entity's raw attributes. +- `EntityRecord | undefined`: Object with the entity's raw attributes. ### getRedoEdit @@ -595,11 +595,11 @@ for the entity records edits history, if any. _Parameters_ -- _state_ `Object`: State tree. +- _state_ `State`: State tree. _Returns_ -- `Object?`: The edit. +- `Optional< any >`: The edit. ### getReferenceByDistinctEdits @@ -616,11 +616,11 @@ _Usage_ _Parameters_ -- _state_ `Object`: Editor state. +- _state_ `State`: Editor state. _Returns_ -- `*`: A value whose reference will change only when an edit occurs. +- A value whose reference will change only when an edit occurs. ### getThemeSupports @@ -628,11 +628,11 @@ Return theme supports data in the index. _Parameters_ -- _state_ `Object`: Data state. +- _state_ `State`: Data state. _Returns_ -- `*`: Index data. +- `any`: Index data. ### getUndoEdit @@ -641,11 +641,11 @@ for the entity records edits history, if any. _Parameters_ -- _state_ `Object`: State tree. +- _state_ `State`: State tree. _Returns_ -- `Object?`: The edit. +- `Optional< any >`: The edit. ### getUserQueryResults @@ -653,12 +653,12 @@ Returns all the users returned by a query ID. _Parameters_ -- _state_ `Object`: Data state. +- _state_ `State`: Data state. - _queryID_ `string`: Query ID. _Returns_ -- `Array`: Users list. +- `User< 'edit' >[]`: Users list. ### hasEditsForEntityRecord @@ -667,10 +667,10 @@ and false otherwise. _Parameters_ -- _state_ `Object`: State tree. +- _state_ `State`: State tree. - _kind_ `string`: Entity kind. - _name_ `string`: Entity name. -- _recordId_ `number|string`: Record ID. +- _recordId_ `RecordKey`: Record ID. _Returns_ @@ -683,10 +683,10 @@ or false otherwise. _Parameters_ -- _state_ `Object`: State tree +- _state_ `State`: State tree - _kind_ `string`: Entity kind. - _name_ `string`: Entity name. -- _query_ `?Object`: Optional terms query. +- _query_ `EntityQuery< any >`: Optional terms query. _Returns_ @@ -698,9 +698,9 @@ Returns true if the REST request for autosaves has completed. _Parameters_ -- _state_ `Object`: State tree. +- _state_ `State`: State tree. - _postType_ `string`: The type of the parent post. -- _postId_ `number`: The id of the parent post. +- _postId_ `RecordKey`: The id of the parent post. _Returns_ @@ -713,7 +713,7 @@ for the entity records edits history, and false otherwise. _Parameters_ -- _state_ `Object`: State tree. +- _state_ `State`: State tree. _Returns_ @@ -726,7 +726,7 @@ for the entity records edits history, and false otherwise. _Parameters_ -- _state_ `Object`: State tree. +- _state_ `State`: State tree. _Returns_ @@ -738,10 +738,10 @@ Returns true if the specified entity record is autosaving, and false otherwise. _Parameters_ -- _state_ `Object`: State tree. +- _state_ `State`: State tree. - _kind_ `string`: Entity kind. - _name_ `string`: Entity name. -- _recordId_ `number`: Record ID. +- _recordId_ `RecordKey`: Record ID. _Returns_ @@ -753,10 +753,10 @@ Returns true if the specified entity record is deleting, and false otherwise. _Parameters_ -- _state_ `Object`: State tree. +- _state_ `State`: State tree. - _kind_ `string`: Entity kind. - _name_ `string`: Entity name. -- _recordId_ `number`: Record ID. +- _recordId_ `RecordKey`: Record ID. _Returns_ @@ -772,7 +772,7 @@ get back from the oEmbed preview API. _Parameters_ -- _state_ `Object`: Data state. +- _state_ `State`: Data state. - _url_ `string`: Embedded URL. _Returns_ @@ -786,7 +786,7 @@ otherwise. _Parameters_ -- _state_ `Object`: Data state. +- _state_ `State`: Data state. - _url_ `string`: URL the preview would be for. _Returns_ @@ -799,10 +799,10 @@ Returns true if the specified entity record is saving, and false otherwise. _Parameters_ -- _state_ `Object`: State tree. +- _state_ `State`: State tree. - _kind_ `string`: Entity kind. - _name_ `string`: Entity name. -- _recordId_ `number|string`: Record ID. +- _recordId_ `RecordKey`: Record ID. _Returns_ diff --git a/packages/core-data/src/selectors.ts b/packages/core-data/src/selectors.ts index 3f74187e9490b..ee1b4df38416d 100644 --- a/packages/core-data/src/selectors.ts +++ b/packages/core-data/src/selectors.ts @@ -18,6 +18,65 @@ import { STORE_NAME } from './name'; import { getQueriedItems } from './queried-data'; import { DEFAULT_ENTITY_KEY } from './entities'; import { getNormalizedCommaSeparable, isRawAttribute } from './utils'; +import type { Context, User, Theme, WpTemplate } from './entity-types'; + +// This is an incomplete, high-level approximation of the State type. +// It makes the selectors slightly more safe, but is intended to evolve +// into a more detailed representation over time. +// See https://github.com/WordPress/gutenberg/pull/40025#discussion_r865410589 for more context. +interface State { + autosaves: Record< string | number, Array< unknown > >; + blockPatterns: Array< unknown >; + blockPatternCategories: Array< unknown >; + currentGlobalStylesId: string; + currentTheme: Theme< 'edit' >; + currentUser: User< 'edit' >; + embedPreviews: Record< string, { html: string } >; + entities: EntitiesState; + themeBaseGlobalStyles: Record< string, Object >; + themeGlobalStyleVariations: Record< string, string >; + undo: UndoState; + users: UserState; +} + +interface EntitiesState { + config: EntityConfig[]; + records: Record< string, unknown >; +} + +interface EntityConfig { + name: string; + kind: string; +} + +interface UndoState extends Array< Object > { + flattenedUndo: unknown; + offset: number; +} + +interface UserState { + queries: Record< string, RecordKey[] >; + byId: Record< RecordKey, User< 'edit' > >; +} + +type RecordKey = number | string; +type EntityRecord = any; +type Optional< T > = T | undefined; + +/** + * 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; +}; /** * Shared reference to an empty object for cases where it is important to avoid @@ -32,13 +91,13 @@ const EMPTY_OBJECT = {}; * Returns true if a request is in progress for embed preview data, or false * otherwise. * - * @param {Object} state Data state. - * @param {string} url URL the preview would be for. + * @param state Data state. + * @param url URL the preview would be for. * - * @return {boolean} Whether a request is in progress for an embed preview. + * @return Whether a request is in progress for an embed preview. */ export const isRequestingEmbedPreview = createRegistrySelector( - ( select ) => ( state, url ) => { + ( select ) => ( state: State, url: string ): boolean => { return select( STORE_NAME ).isResolving( 'getEmbedPreview', [ url ] ); } ); @@ -48,12 +107,15 @@ export const isRequestingEmbedPreview = createRegistrySelector( * * @deprecated since 11.3. Callers should use `select( 'core' ).getUsers({ who: 'authors' })` instead. * - * @param {Object} state Data state. - * @param {Object|undefined} query Optional object of query parameters to - * include with request. - * @return {Array} Authors list. + * @param state Data state. + * @param query Optional object of query parameters to + * include with request. + * @return Authors list. */ -export function getAuthors( state, query ) { +export function getAuthors( + state: State, + query?: EntityQuery< any > +): User< 'edit' >[] { deprecated( "select( 'core' ).getAuthors()", { since: '5.9', alternative: "select( 'core' ).getUsers({ who: 'authors' })", @@ -69,41 +131,44 @@ export function getAuthors( state, query ) { /** * Returns the current user. * - * @param {Object} state Data state. + * @param state Data state. * - * @return {Object} Current user object. + * @return Current user object. */ -export function getCurrentUser( state ) { +export function getCurrentUser( state: State ): User< 'edit' > { return state.currentUser; } /** * Returns all the users returned by a query ID. * - * @param {Object} state Data state. - * @param {string} queryID Query ID. + * @param state Data state. + * @param queryID Query ID. * - * @return {Array} Users list. + * @return Users list. */ export const getUserQueryResults = createSelector( - ( state, queryID ) => { + ( state: State, queryID: string ): User< 'edit' >[] => { const queryResults = state.users.queries[ queryID ]; return map( queryResults, ( id ) => state.users.byId[ id ] ); }, - ( state, queryID ) => [ state.users.queries[ queryID ], state.users.byId ] + ( state: State, queryID: string ) => [ + state.users.queries[ queryID ], + state.users.byId, + ] ); /** * Returns the loaded entities for the given kind. * * @deprecated since WordPress 6.0. Use getEntitiesConfig instead - * @param {Object} state Data state. - * @param {string} kind Entity kind. + * @param state Data state. + * @param kind Entity kind. * - * @return {Array} Array of entities with config matching kind. + * @return Array of entities with config matching kind. */ -export function getEntitiesByKind( state, kind ) { +export function getEntitiesByKind( state: State, kind: string ): Array< any > { deprecated( "wp.data.select( 'core' ).getEntitiesByKind()", { since: '6.0', alternative: "wp.data.select( 'core' ).getEntitiesConfig()", @@ -114,12 +179,12 @@ export function getEntitiesByKind( state, kind ) { /** * Returns the loaded entities for the given kind. * - * @param {Object} state Data state. - * @param {string} kind Entity kind. + * @param state Data state. + * @param kind Entity kind. * - * @return {Array} Array of entities with config matching kind. + * @return Array of entities with config matching kind. */ -export function getEntitiesConfig( state, kind ) { +export function getEntitiesConfig( state: State, kind: string ): Array< any > { return filter( state.entities.config, { kind } ); } @@ -127,13 +192,13 @@ export function getEntitiesConfig( state, kind ) { * Returns the entity config given its kind and name. * * @deprecated since WordPress 6.0. Use getEntityConfig instead - * @param {Object} state Data state. - * @param {string} kind Entity kind. - * @param {string} name Entity name. + * @param state Data state. + * @param kind Entity kind. + * @param name Entity name. * - * @return {Object} Entity config + * @return Entity config */ -export function getEntity( state, kind, name ) { +export function getEntity( state: State, kind: string, name: string ): any { deprecated( "wp.data.select( 'core' ).getEntity()", { since: '6.0', alternative: "wp.data.select( 'core' ).getEntityConfig()", @@ -144,13 +209,17 @@ export function getEntity( state, kind, name ) { /** * Returns the entity config given its kind and name. * - * @param {Object} state Data state. - * @param {string} kind Entity kind. - * @param {string} name Entity name. + * @param state Data state. + * @param kind Entity kind. + * @param name Entity name. * - * @return {Object} Entity config + * @return Entity config */ -export function getEntityConfig( state, kind, name ) { +export function getEntityConfig( + state: State, + kind: string, + name: string +): any { return find( state.entities.config, { kind, name } ); } @@ -159,16 +228,22 @@ export function getEntityConfig( state, kind, name ) { * 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. + * @param state State tree + * @param kind Entity kind. + * @param name Entity name. + * @param key Record's key + * @param query Optional query. * - * @return {Object|undefined} Record. + * @return Record. */ export const getEntityRecord = createSelector( - ( state, kind, name, key, query ) => { + ( + state: State, + kind: string, + name: string, + key: RecordKey, + query?: EntityQuery< any > + ): EntityRecord | undefined => { const queriedState = get( state.entities.records, [ kind, name, @@ -202,7 +277,13 @@ export const getEntityRecord = createSelector( return item; }, - ( state, kind, name, recordId, query ) => { + ( + state: State, + kind: string, + name: string, + recordId: RecordKey, + query?: EntityQuery< any > + ) => { const context = query?.context ?? 'default'; return [ get( state.entities.records, [ @@ -228,19 +309,19 @@ export const getEntityRecord = createSelector( /** * Returns the Entity's record object by key. Doesn't trigger a resolver nor requests the entity records from the API if the entity record isn't available in the local state. * - * @param {Object} state State tree - * @param {string} kind Entity kind. - * @param {string} name Entity name. - * @param {number} key Record's key + * @param state State tree + * @param kind Entity kind. + * @param name Entity name. + * @param key Record's key * - * @return {Object|null} Record. + * @return Record. */ export function __experimentalGetEntityRecordNoResolver( - state, - kind, - name, - key -) { + state: State, + kind: string, + name: string, + key: RecordKey +): EntityRecord | null { return getEntityRecord( state, kind, name, key ); } @@ -248,15 +329,20 @@ export function __experimentalGetEntityRecordNoResolver( * Returns the entity's record object by key, * with its attributes mapped to their raw values. * - * @param {Object} state State tree. - * @param {string} kind Entity kind. - * @param {string} name Entity name. - * @param {number} key Record's key. + * @param state State tree. + * @param kind Entity kind. + * @param name Entity name. + * @param key Record's key. * - * @return {Object?} Object with the entity's raw attributes. + * @return Object with the entity's raw attributes. */ export const getRawEntityRecord = createSelector( - ( state, kind, name, key ) => { + ( + state: State, + kind: string, + name: string, + key: RecordKey + ): EntityRecord | undefined => { const record = getEntityRecord( state, kind, name, key ); return ( record && @@ -279,7 +365,13 @@ export const getRawEntityRecord = createSelector( }, {} ) ); }, - ( state, kind, name, recordId, query ) => { + ( + state: State, + kind: string, + name: string, + recordId: RecordKey, + query?: EntityQuery< any > + ) => { const context = query?.context ?? 'default'; return [ state.entities.config, @@ -307,28 +399,38 @@ export const getRawEntityRecord = createSelector( * Returns true if records have been received for the given set of parameters, * or false otherwise. * - * @param {Object} state State tree - * @param {string} kind Entity kind. - * @param {string} name Entity name. - * @param {?Object} query Optional terms query. + * @param state State tree + * @param kind Entity kind. + * @param name Entity name. + * @param query Optional terms query. * - * @return {boolean} Whether entity records have been received. + * @return Whether entity records have been received. */ -export function hasEntityRecords( state, kind, name, query ) { +export function hasEntityRecords( + state: State, + kind: string, + name: string, + query?: EntityQuery< any > +): boolean { return Array.isArray( getEntityRecords( state, kind, name, query ) ); } /** * Returns the Entity's records. * - * @param {Object} state State tree - * @param {string} kind Entity kind. - * @param {string} name Entity name. - * @param {?Object} query Optional terms query. + * @param state State tree + * @param kind Entity kind. + * @param name Entity name. + * @param query Optional terms query. * - * @return {?Array} Records. + * @return Records. */ -export function getEntityRecords( state, kind, name, query ) { +export function getEntityRecords( + state: State, + kind: string, + name: string, + query?: EntityQuery< any > +): Array< EntityRecord > | undefined { // Queried data state is prepopulated for all known entities. If this is not // assigned for the given parameters, then it is known to not exist. const queriedState = get( state.entities.records, [ @@ -342,15 +444,21 @@ export function getEntityRecords( state, kind, name, query ) { return getQueriedItems( queriedState, query ); } +type DirtyEntityRecord = { + title: string; + key: RecordKey; + name: string; + kind: string; +}; /** * Returns the list of dirty entity records. * - * @param {Object} state State tree. + * @param state State tree. * - * @return {[{ title: string, key: string, name: string, kind: string }]} The list of updated records + * @return The list of updated records */ export const __experimentalGetDirtyEntityRecords = createSelector( - ( state ) => { + ( state: State ): Array< DirtyEntityRecord > => { const { entities: { records }, } = state; @@ -360,7 +468,7 @@ export const __experimentalGetDirtyEntityRecords = createSelector( const primaryKeys = Object.keys( records[ kind ][ name ].edits ).filter( - ( primaryKey ) => + ( primaryKey: RecordKey ) => // The entity record must exist (not be deleted), // and it must have edits. getEntityRecord( state, kind, name, primaryKey ) && @@ -401,12 +509,12 @@ export const __experimentalGetDirtyEntityRecords = createSelector( /** * Returns the list of entities currently being saved. * - * @param {Object} state State tree. + * @param state State tree. * - * @return {[{ title: string, key: string, name: string, kind: string }]} The list of records being saved. + * @return The list of records being saved. */ export const __experimentalGetEntitiesBeingSaved = createSelector( - ( state ) => { + ( state: State ): Array< DirtyEntityRecord > => { const { entities: { records }, } = state; @@ -452,14 +560,19 @@ export const __experimentalGetEntitiesBeingSaved = createSelector( /** * Returns the specified entity record's edits. * - * @param {Object} state State tree. - * @param {string} kind Entity kind. - * @param {string} name Entity name. - * @param {number} recordId Record ID. + * @param state State tree. + * @param kind Entity kind. + * @param name Entity name. + * @param recordId Record ID. * - * @return {Object?} The entity record's edits. + * @return The entity record's edits. */ -export function getEntityRecordEdits( state, kind, name, recordId ) { +export function getEntityRecordEdits( + state: State, + kind: string, + name: string, + recordId: RecordKey +): Optional< any > { return get( state.entities.records, [ kind, name, 'edits', recordId ] ); } @@ -470,15 +583,20 @@ export function getEntityRecordEdits( state, kind, name, recordId ) { * are not considered for change detection. * They are defined in the entity's config. * - * @param {Object} state State tree. - * @param {string} kind Entity kind. - * @param {string} name Entity name. - * @param {number} recordId Record ID. + * @param state State tree. + * @param kind Entity kind. + * @param name Entity name. + * @param recordId Record ID. * - * @return {Object?} The entity record's non transient edits. + * @return The entity record's non transient edits. */ export const getEntityRecordNonTransientEdits = createSelector( - ( state, kind, name, recordId ) => { + ( + state: State, + kind: string, + name: string, + recordId: RecordKey + ): Optional< any > => { const { transientEdits } = getEntityConfig( state, kind, name ) || {}; const edits = getEntityRecordEdits( state, kind, name, recordId ) || {}; if ( ! transientEdits ) { @@ -491,7 +609,7 @@ export const getEntityRecordNonTransientEdits = createSelector( return acc; }, {} ); }, - ( state, kind, name, recordId ) => [ + ( state: State, kind: string, name: string, recordId: RecordKey ) => [ state.entities.config, get( state.entities.records, [ kind, name, 'edits', recordId ] ), ] @@ -501,14 +619,19 @@ export const getEntityRecordNonTransientEdits = createSelector( * Returns true if the specified entity record has edits, * and false otherwise. * - * @param {Object} state State tree. - * @param {string} kind Entity kind. - * @param {string} name Entity name. - * @param {number|string} recordId Record ID. + * @param state State tree. + * @param kind Entity kind. + * @param name Entity name. + * @param recordId Record ID. * - * @return {boolean} Whether the entity record has edits or not. + * @return Whether the entity record has edits or not. */ -export function hasEditsForEntityRecord( state, kind, name, recordId ) { +export function hasEditsForEntityRecord( + state: State, + kind: string, + name: string, + recordId: RecordKey +): boolean { return ( isSavingEntityRecord( state, kind, name, recordId ) || Object.keys( @@ -520,19 +643,30 @@ export function hasEditsForEntityRecord( state, kind, name, recordId ) { /** * Returns the specified entity record, merged with its edits. * - * @param {Object} state State tree. - * @param {string} kind Entity kind. - * @param {string} name Entity name. - * @param {number|string} recordId Record ID. + * @param state State tree. + * @param kind Entity kind. + * @param name Entity name. + * @param recordId Record ID. * - * @return {Object?} The entity record, merged with its edits. + * @return The entity record, merged with its edits. */ export const getEditedEntityRecord = createSelector( - ( state, kind, name, recordId ) => ( { + ( + state: State, + kind: string, + name: string, + recordId: RecordKey + ): EntityRecord | undefined => ( { ...getRawEntityRecord( state, kind, name, recordId ), ...getEntityRecordEdits( state, kind, name, recordId ), } ), - ( state, kind, name, recordId, query ) => { + ( + state: State, + kind: string, + name: string, + recordId: RecordKey, + query?: EntityQuery< any > + ) => { const context = query?.context ?? 'default'; return [ state.entities.config, @@ -560,14 +694,19 @@ export const getEditedEntityRecord = createSelector( /** * Returns true if the specified entity record is autosaving, and false otherwise. * - * @param {Object} state State tree. - * @param {string} kind Entity kind. - * @param {string} name Entity name. - * @param {number} recordId Record ID. + * @param state State tree. + * @param kind Entity kind. + * @param name Entity name. + * @param recordId Record ID. * - * @return {boolean} Whether the entity record is autosaving or not. + * @return Whether the entity record is autosaving or not. */ -export function isAutosavingEntityRecord( state, kind, name, recordId ) { +export function isAutosavingEntityRecord( + state: State, + kind: string, + name: string, + recordId: RecordKey +): boolean { const { pending, isAutosave } = get( state.entities.records, [ kind, name, 'saving', recordId ], @@ -579,14 +718,19 @@ export function isAutosavingEntityRecord( state, kind, name, recordId ) { /** * Returns true if the specified entity record is saving, and false otherwise. * - * @param {Object} state State tree. - * @param {string} kind Entity kind. - * @param {string} name Entity name. - * @param {number|string} recordId Record ID. + * @param state State tree. + * @param kind Entity kind. + * @param name Entity name. + * @param recordId Record ID. * - * @return {boolean} Whether the entity record is saving or not. + * @return Whether the entity record is saving or not. */ -export function isSavingEntityRecord( state, kind, name, recordId ) { +export function isSavingEntityRecord( + state: State, + kind: string, + name: string, + recordId: RecordKey +): boolean { return get( state.entities.records, [ kind, name, 'saving', recordId, 'pending' ], @@ -597,14 +741,19 @@ export function isSavingEntityRecord( state, kind, name, recordId ) { /** * Returns true if the specified entity record is deleting, and false otherwise. * - * @param {Object} state State tree. - * @param {string} kind Entity kind. - * @param {string} name Entity name. - * @param {number} recordId Record ID. + * @param state State tree. + * @param kind Entity kind. + * @param name Entity name. + * @param recordId Record ID. * - * @return {boolean} Whether the entity record is deleting or not. + * @return Whether the entity record is deleting or not. */ -export function isDeletingEntityRecord( state, kind, name, recordId ) { +export function isDeletingEntityRecord( + state: State, + kind: string, + name: string, + recordId: RecordKey +): boolean { return get( state.entities.records, [ kind, name, 'deleting', recordId, 'pending' ], @@ -615,14 +764,19 @@ export function isDeletingEntityRecord( state, kind, name, recordId ) { /** * Returns the specified entity record's last save error. * - * @param {Object} state State tree. - * @param {string} kind Entity kind. - * @param {string} name Entity name. - * @param {number} recordId Record ID. + * @param state State tree. + * @param kind Entity kind. + * @param name Entity name. + * @param recordId Record ID. * - * @return {Object?} The entity record's save error. + * @return The entity record's save error. */ -export function getLastEntitySaveError( state, kind, name, recordId ) { +export function getLastEntitySaveError( + state: State, + kind: string, + name: string, + recordId: RecordKey +): any { return get( state.entities.records, [ kind, name, @@ -635,14 +789,19 @@ export function getLastEntitySaveError( state, kind, name, recordId ) { /** * Returns the specified entity record's last delete error. * - * @param {Object} state State tree. - * @param {string} kind Entity kind. - * @param {string} name Entity name. - * @param {number} recordId Record ID. + * @param state State tree. + * @param kind Entity kind. + * @param name Entity name. + * @param recordId Record ID. * - * @return {Object?} The entity record's save error. + * @return The entity record's save error. */ -export function getLastEntityDeleteError( state, kind, name, recordId ) { +export function getLastEntityDeleteError( + state: State, + kind: string, + name: string, + recordId: RecordKey +): any { return get( state.entities.records, [ kind, name, @@ -659,11 +818,11 @@ export function getLastEntityDeleteError( state, kind, name, recordId ) { * of the history stack we are at. 0 is the * last edit, -1 is the second last, and so on. * - * @param {Object} state State tree. + * @param state State tree. * - * @return {number} The current undo offset. + * @return The current undo offset. */ -function getCurrentUndoOffset( state ) { +function getCurrentUndoOffset( state: State ): number { return state.undo.offset; } @@ -671,11 +830,11 @@ function getCurrentUndoOffset( state ) { * Returns the previous edit from the current undo offset * for the entity records edits history, if any. * - * @param {Object} state State tree. + * @param state State tree. * - * @return {Object?} The edit. + * @return The edit. */ -export function getUndoEdit( state ) { +export function getUndoEdit( state: State ): Optional< any > { return state.undo[ state.undo.length - 2 + getCurrentUndoOffset( state ) ]; } @@ -683,11 +842,11 @@ export function getUndoEdit( state ) { * Returns the next edit from the current undo offset * for the entity records edits history, if any. * - * @param {Object} state State tree. + * @param state State tree. * - * @return {Object?} The edit. + * @return The edit. */ -export function getRedoEdit( state ) { +export function getRedoEdit( state: State ): Optional< any > { return state.undo[ state.undo.length + getCurrentUndoOffset( state ) ]; } @@ -695,11 +854,11 @@ export function getRedoEdit( state ) { * Returns true if there is a previous edit from the current undo offset * for the entity records edits history, and false otherwise. * - * @param {Object} state State tree. + * @param state State tree. * - * @return {boolean} Whether there is a previous edit or not. + * @return Whether there is a previous edit or not. */ -export function hasUndo( state ) { +export function hasUndo( state: State ): boolean { return Boolean( getUndoEdit( state ) ); } @@ -707,56 +866,56 @@ export function hasUndo( state ) { * Returns true if there is a next edit from the current undo offset * for the entity records edits history, and false otherwise. * - * @param {Object} state State tree. + * @param state State tree. * - * @return {boolean} Whether there is a next edit or not. + * @return Whether there is a next edit or not. */ -export function hasRedo( state ) { +export function hasRedo( state: State ): boolean { return Boolean( getRedoEdit( state ) ); } /** * Return the current theme. * - * @param {Object} state Data state. + * @param state Data state. * - * @return {Object} The current theme. + * @return The current theme. */ -export function getCurrentTheme( state ) { +export function getCurrentTheme( state: State ): any { return getEntityRecord( state, 'root', 'theme', state.currentTheme ); } /** * Return the ID of the current global styles object. * - * @param {Object} state Data state. + * @param state Data state. * - * @return {string} The current global styles ID. + * @return The current global styles ID. */ -export function __experimentalGetCurrentGlobalStylesId( state ) { +export function __experimentalGetCurrentGlobalStylesId( state: State ): string { return state.currentGlobalStylesId; } /** * Return theme supports data in the index. * - * @param {Object} state Data state. + * @param state Data state. * - * @return {*} Index data. + * @return Index data. */ -export function getThemeSupports( state ) { +export function getThemeSupports( state: State ): any { return getCurrentTheme( state )?.theme_supports ?? EMPTY_OBJECT; } /** * Returns the embed preview for the given URL. * - * @param {Object} state Data state. - * @param {string} url Embedded URL. + * @param state Data state. + * @param url Embedded URL. * - * @return {*} Undefined if the preview has not been fetched, otherwise, the preview fetched from the embed preview API. + * @return Undefined if the preview has not been fetched, otherwise, the preview fetched from the embed preview API. */ -export function getEmbedPreview( state, url ) { +export function getEmbedPreview( state: State, url: string ): any { return state.embedPreviews[ url ]; } @@ -767,12 +926,12 @@ export function getEmbedPreview( state, url ) { * 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 {Object} state Data state. - * @param {string} url Embedded URL. + * @param state Data state. + * @param url Embedded URL. * - * @return {boolean} Is the preview for the URL an oEmbed link fallback. + * @return Is the preview for the URL an oEmbed link fallback. */ -export function isPreviewEmbedFallback( state, url ) { +export function isPreviewEmbedFallback( state: State, url: string ): boolean { const preview = state.embedPreviews[ url ]; const oEmbedLinkCheck = '' + url + ''; if ( ! preview ) { @@ -790,15 +949,20 @@ export function isPreviewEmbedFallback( state, url ) { * * https://developer.wordpress.org/rest-api/reference/ * - * @param {Object} state Data state. - * @param {string} action Action to check. One of: 'create', 'read', 'update', 'delete'. - * @param {string} resource REST resource to check, e.g. 'media' or 'posts'. - * @param {string=} id Optional ID of the rest resource to check. + * @param state Data state. + * @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. * - * @return {boolean|undefined} Whether or not the user can perform the action, + * @return Whether or not the user can perform the action, * or `undefined` if the OPTIONS request is still being made. */ -export function canUser( state, action, resource, id ) { +export function canUser( + state: State, + action: string, + resource: string, + id?: RecordKey +): boolean | undefined { const key = compact( [ action, resource, id ] ).join( '/' ); return get( state, [ 'userPermissions', key ] ); } @@ -811,14 +975,19 @@ export function canUser( state, action, resource, id ) { * * https://developer.wordpress.org/rest-api/reference/ * - * @param {Object} state Data state. - * @param {string} kind Entity kind. - * @param {string} name Entity name. - * @param {string} recordId Record's id. - * @return {boolean|undefined} Whether or not the user can edit, + * @param state Data state. + * @param kind Entity kind. + * @param name Entity name. + * @param recordId Record's id. + * @return Whether or not the user can edit, * or `undefined` if the OPTIONS request is still being made. */ -export function canUserEditEntityRecord( state, kind, name, recordId ) { +export function canUserEditEntityRecord( + state: State, + kind: string, + name: string, + recordId: RecordKey +): boolean | undefined { const entityConfig = getEntityConfig( state, kind, name ); if ( ! entityConfig ) { return false; @@ -834,27 +1003,36 @@ export function canUserEditEntityRecord( state, kind, name, recordId ) { * May return multiple autosaves since the backend stores one autosave per * author for each post. * - * @param {Object} state State tree. - * @param {string} postType The type of the parent post. - * @param {number} postId The id of the parent post. + * @param state State tree. + * @param postType The type of the parent post. + * @param postId The id of the parent post. * - * @return {?Array} An array of autosaves for the post, or undefined if there is none. + * @return An array of autosaves for the post, or undefined if there is none. */ -export function getAutosaves( state, postType, postId ) { +export function getAutosaves( + state: State, + postType: string, + postId: RecordKey +): Array< any > | undefined { return state.autosaves[ postId ]; } /** * Returns the autosave for the post and author. * - * @param {Object} state State tree. - * @param {string} postType The type of the parent post. - * @param {number} postId The id of the parent post. - * @param {number} authorId The id of the author. + * @param state State tree. + * @param postType The type of the parent post. + * @param postId The id of the parent post. + * @param authorId The id of the author. * - * @return {?Object} The autosave for the post and author. + * @return The autosave for the post and author. */ -export function getAutosave( state, postType, postId, authorId ) { +export function getAutosave( + state: State, + postType: string, + postId: RecordKey, + authorId: RecordKey +): EntityRecord | undefined { if ( authorId === undefined ) { return; } @@ -866,14 +1044,18 @@ export function getAutosave( state, postType, postId, authorId ) { /** * Returns true if the REST request for autosaves has completed. * - * @param {Object} state State tree. - * @param {string} postType The type of the parent post. - * @param {number} postId The id of the parent post. + * @param state State tree. + * @param postType The type of the parent post. + * @param postId The id of the parent post. * - * @return {boolean} True if the REST request was completed. False otherwise. + * @return True if the REST request was completed. False otherwise. */ export const hasFetchedAutosaves = createRegistrySelector( - ( select ) => ( state, postType, postId ) => { + ( select ) => ( + state: State, + postType: string, + postId: RecordKey + ): boolean => { return select( STORE_NAME ).hasFinishedResolution( 'getAutosaves', [ postType, postId, @@ -895,13 +1077,14 @@ export const hasFetchedAutosaves = createRegistrySelector( * ); * ``` * - * @param {Object} state Editor state. + * @param state Editor state. * - * @return {*} A value whose reference will change only when an edit occurs. + * @return A value whose reference will change only when an edit occurs. */ export const getReferenceByDistinctEdits = createSelector( - () => [], - ( state ) => [ + // This unused state argument is listed here for the documentation generating tool (docgen). + ( state: State ) => [], + ( state: State ) => [ state.undo.length, state.undo.offset, state.undo.flattenedUndo, @@ -911,12 +1094,15 @@ export const getReferenceByDistinctEdits = createSelector( /** * Retrieve the frontend template used for a given link. * - * @param {Object} state Editor state. - * @param {string} link Link. + * @param state Editor state. + * @param link Link. * - * @return {Object?} The template record. + * @return The template record. */ -export function __experimentalGetTemplateForLink( state, link ) { +export function __experimentalGetTemplateForLink( + state: State, + link: string +): WpTemplate< 'edit' > | null { const records = getEntityRecords( state, 'postType', 'wp_template', { 'find-template': link, } ); @@ -936,11 +1122,13 @@ export function __experimentalGetTemplateForLink( state, link ) { /** * Retrieve the current theme's base global styles * - * @param {Object} state Editor state. + * @param state Editor state. * - * @return {Object|null} The Global Styles object. + * @return The Global Styles object. */ -export function __experimentalGetCurrentThemeBaseGlobalStyles( state ) { +export function __experimentalGetCurrentThemeBaseGlobalStyles( + state: State +): any { const currentTheme = getCurrentTheme( state ); if ( ! currentTheme ) { return null; @@ -951,11 +1139,13 @@ export function __experimentalGetCurrentThemeBaseGlobalStyles( state ) { /** * Return the ID of the current global styles object. * - * @param {Object} state Data state. + * @param state Data state. * - * @return {string|null} The current global styles ID. + * @return The current global styles ID. */ -export function __experimentalGetCurrentThemeGlobalStylesVariations( state ) { +export function __experimentalGetCurrentThemeGlobalStylesVariations( + state: State +): string | null { const currentTheme = getCurrentTheme( state ); if ( ! currentTheme ) { return null; @@ -966,21 +1156,21 @@ export function __experimentalGetCurrentThemeGlobalStylesVariations( state ) { /** * Retrieve the list of registered block patterns. * - * @param {Object} state Data state. + * @param state Data state. * - * @return {Array} Block pattern list. + * @return Block pattern list. */ -export function getBlockPatterns( state ) { +export function getBlockPatterns( state: State ): Array< any > { return state.blockPatterns; } /** * Retrieve the list of registered block pattern categories. * - * @param {Object} state Data state. + * @param state Data state. * - * @return {Array} Block pattern category list. + * @return Block pattern category list. */ -export function getBlockPatternCategories( state ) { +export function getBlockPatternCategories( state: State ): Array< any > { return state.blockPatternCategories; }