Core Data: Retrieve the pagination totals in the getEntityRecords cal…

…ls (#55164)

docs/reference-guides/data/data-core.md

@@ -299,6 +299,36 @@ _Returns_
 
 -   `EntityRecord[] | null`: Records.
 
+### getEntityRecordsTotalItems
+
+Returns the Entity's total available records for a given query (ignoring pagination).
+
+_Parameters_
+
+-   _state_ `State`: State tree
+-   _kind_ `string`: Entity kind.
+-   _name_ `string`: Entity name.
+-   _query_ `GetRecordsHttpQuery`: Optional terms query. If requesting specific fields, fields must always include the ID. For valid query parameters see the [Reference](https://developer.wordpress.org/rest-api/reference/) in the REST API Handbook and select the entity kind. Then see the arguments available for "List [Entity kind]s".
+
+_Returns_
+
+-   `number | null`: number | null.
+
+### getEntityRecordsTotalPages
+
+Returns the number of available pages for the given query.
+
+_Parameters_
+
+-   _state_ `State`: State tree
+-   _kind_ `string`: Entity kind.
+-   _name_ `string`: Entity name.
+-   _query_ `GetRecordsHttpQuery`: Optional terms query. If requesting specific fields, fields must always include the ID. For valid query parameters see the [Reference](https://developer.wordpress.org/rest-api/reference/) in the REST API Handbook and select the entity kind. Then see the arguments available for "List [Entity kind]s".
+
+_Returns_
+
+-   `number | null`: number | null.
+
 ### getLastEntityDeleteError
 
 Returns the specified entity record's last delete error.
@@ -630,6 +660,7 @@ _Parameters_
 -   _query_ `?Object`: Query Object.
 -   _invalidateCache_ `?boolean`: Should invalidate query caches.
 -   _edits_ `?Object`: Edits to reset.
+-   _meta_ `?Object`: Meta information about pagination.
 
 _Returns_
 

packages/core-data/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## Unreleased
 
+## Enhancements
+
+-   Add `getEntityRecordsTotalItems` and `getEntityRecordsTotalPages` selectors. [#55164](https://github.com/WordPress/gutenberg/pull/55164).
+
 ## 6.20.0 (2023-10-05)
 
 ## 6.19.0 (2023-09-20)

packages/core-data/README.md

@@ -217,6 +217,7 @@ _Parameters_
 -   _query_ `?Object`: Query Object.
 -   _invalidateCache_ `?boolean`: Should invalidate query caches.
 -   _edits_ `?Object`: Edits to reset.
+-   _meta_ `?Object`: Meta information about pagination.
 
 _Returns_
 
@@ -592,6 +593,36 @@ _Returns_
 
 -   `EntityRecord[] | null`: Records.
 
+### getEntityRecordsTotalItems
+
+Returns the Entity's total available records for a given query (ignoring pagination).
+
+_Parameters_
+
+-   _state_ `State`: State tree
+-   _kind_ `string`: Entity kind.
+-   _name_ `string`: Entity name.
+-   _query_ `GetRecordsHttpQuery`: Optional terms query. If requesting specific fields, fields must always include the ID. For valid query parameters see the [Reference](https://developer.wordpress.org/rest-api/reference/) in the REST API Handbook and select the entity kind. Then see the arguments available for "List [Entity kind]s".
+
+_Returns_
+
+-   `number | null`: number | null.
+
+### getEntityRecordsTotalPages
+
+Returns the number of available pages for the given query.
+
+_Parameters_
+
+-   _state_ `State`: State tree
+-   _kind_ `string`: Entity kind.
+-   _name_ `string`: Entity name.
+-   _query_ `GetRecordsHttpQuery`: Optional terms query. If requesting specific fields, fields must always include the ID. For valid query parameters see the [Reference](https://developer.wordpress.org/rest-api/reference/) in the REST API Handbook and select the entity kind. Then see the arguments available for "List [Entity kind]s".
+
+_Returns_
+
+-   `number | null`: number | null.
+
 ### getLastEntityDeleteError
 
 Returns the specified entity record's last delete error.

packages/core-data/src/actions.js

@@ -80,6 +80,7 @@ export function addEntities( entities ) {
  * @param {?Object}      query           Query Object.
  * @param {?boolean}     invalidateCache Should invalidate query caches.
  * @param {?Object}      edits           Edits to reset.
+ * @param {?Object}      meta            Meta information about pagination.
  * @return {Object} Action object.
  */
 export function receiveEntityRecords(
@@ -88,7 +89,8 @@ export function receiveEntityRecords(
 	records,
 	query,
 	invalidateCache = false,
-	edits
+	edits,
+	meta
 ) {
 	// Auto drafts should not have titles, but some plugins rely on them so we can't filter this
 	// on the server.
@@ -102,9 +104,9 @@ export function receiveEntityRecords(
 	}
 	let action;
 	if ( query ) {
-		action = receiveQueriedItems( records, query, edits );
+		action = receiveQueriedItems( records, query, edits, meta );
 	} else {
-		action = receiveItems( records, edits );
+		action = receiveItems( records, edits, meta );
 	}
 
 	return {

packages/core-data/src/entities.js

@@ -120,6 +120,7 @@ export const rootEntitiesConfig = [
 		plural: 'mediaItems',
 		label: __( 'Media' ),
 		rawAttributes: [ 'caption', 'title', 'description' ],
+		supportsPagination: true,
 	},
 	{
 		name: 'taxonomy',
@@ -326,6 +327,7 @@ async function loadPostTypeEntities() {
 			},
 			syncObjectType: 'postType/' + postType.name,
 			getSyncObjectId: ( id ) => id,
+			supportsPagination: true,
 		};
 	} );
 }

packages/core-data/src/hooks/test/use-entity-records.js

@@ -51,6 +51,8 @@ describe( 'useEntityRecords', () => {
 			hasResolved: false,
 			isResolving: false,
 			status: 'IDLE',
+			totalItems: null,
+			totalPages: null,
 		} );
 
 		// Fetch request should have been issued
@@ -65,6 +67,8 @@ describe( 'useEntityRecords', () => {
 			hasResolved: true,
 			isResolving: false,
 			status: 'SUCCESS',
+			totalItems: null,
+			totalPages: null,
 		} );
 	} );
 } );

packages/core-data/src/hooks/use-entity-records.ts

@@ -3,6 +3,7 @@
  */
 import { addQueryArgs } from '@wordpress/url';
 import deprecated from '@wordpress/deprecated';
+import { useSelect } from '@wordpress/data';
 
 /**
  * Internal dependencies
@@ -28,6 +29,16 @@ interface EntityRecordsResolution< RecordType > {
 
 	/** Resolution status */
 	status: Status;
+
+	/**
+	 * The total number of available items (if not paginated).
+	 */
+	totalItems: number | null;
+
+	/**
+	 * The total number of pages.
+	 */
+	totalPages: number | null;
 }
 
 const EMPTY_ARRAY = [];
@@ -97,8 +108,34 @@ export default function useEntityRecords< RecordType >(
 		[ kind, name, queryAsString, options.enabled ]
 	);
 
+	const { totalItems, totalPages } = useSelect(
+		( select ) => {
+			if ( ! options.enabled ) {
+				return {
+					totalItems: null,
+					totalPages: null,
+				};
+			}
+			return {
+				totalItems: select( coreStore ).getEntityRecordsTotalItems(
+					kind,
+					name,
+					queryArgs
+				),
+				totalPages: select( coreStore ).getEntityRecordsTotalPages(
+					kind,
+					name,
+					queryArgs
+				),
+			};
+		},
+		[ kind, name, queryAsString, options.enabled ]
+	);
+
 	return {
 		records,
+		totalItems,
+		totalPages,
 		...rest,
 	};
 }

packages/core-data/src/queried-data/actions.js

@@ -3,14 +3,16 @@
  *
  * @param {Array}   items Items received.
  * @param {?Object} edits Optional edits to reset.
+ * @param {?Object} meta  Meta information about pagination.
  *
  * @return {Object} Action object.
  */
-export function receiveItems( items, edits ) {
+export function receiveItems( items, edits, meta ) {
 	return {
 		type: 'RECEIVE_ITEMS',
 		items: Array.isArray( items ) ? items : [ items ],
 		persistedEdits: edits,
+		meta,
 	};
 }
 
@@ -41,12 +43,13 @@ export function removeItems( kind, name, records, invalidateCache = false ) {
  * @param {Array}   items Queried items received.
  * @param {?Object} query Optional query object.
  * @param {?Object} edits Optional edits to reset.
+ * @param {?Object} meta  Meta information about pagination.
  *
  * @return {Object} Action object.
  */
-export function receiveQueriedItems( items, query = {}, edits ) {
+export function receiveQueriedItems( items, query = {}, edits, meta ) {
 	return {
-		...receiveItems( items, edits ),
+		...receiveItems( items, edits, meta ),
 		query,
 	};
 }

packages/core-data/src/queried-data/reducer.js

@@ -222,19 +222,22 @@ const receiveQueries = compose( [
 	// Queries shape is shared, but keyed by query `stableKey` part. Original
 	// reducer tracks only a single query object.
 	onSubKey( 'stableKey' ),
-] )( ( state = null, action ) => {
+] )( ( state = {}, action ) => {
 	const { type, page, perPage, key = DEFAULT_ENTITY_KEY } = action;
 
 	if ( type !== 'RECEIVE_ITEMS' ) {
 		return state;
 	}
 
-	return getMergedItemIds(
-		state || [],
-		action.items.map( ( item ) => item[ key ] ),
-		page,
-		perPage
-	);
+	return {
+		itemIds: getMergedItemIds(
+			state?.itemIds || [],
+			action.items.map( ( item ) => item[ key ] ),
+			page,
+			perPage
+		),
+		meta: action.meta,
+	};
 } );
 
 /**
@@ -263,9 +266,13 @@ const queries = ( state = {}, action ) => {
 							Object.entries( contextQueries ).map(
 								( [ query, queryItems ] ) => [
 									query,
-									queryItems.filter(
-										( queryId ) => ! removedItems[ queryId ]
-									),
+									{
+										...queryItems,
+										itemIds: queryItems.itemIds.filter(
+											( queryId ) =>
+												! removedItems[ queryId ]
+										),
+									},
 								]
 							)
 						),

packages/core-data/src/queried-data/selectors.js

@@ -33,7 +33,7 @@ function getQueriedItemsUncached( state, query ) {
 	let itemIds;
 
 	if ( state.queries?.[ context ]?.[ stableKey ] ) {
-		itemIds = state.queries[ context ][ stableKey ];
+		itemIds = state.queries[ context ][ stableKey ].itemIds;
 	}
 
 	if ( ! itemIds ) {
@@ -118,3 +118,15 @@ export const getQueriedItems = createSelector( ( state, query = {} ) => {
 	queriedItemsCache.set( query, items );
 	return items;
 } );
+
+export function getQueriedTotalItems( state, query = {} ) {
+	const { stableKey, context } = getQueryParts( query );
+
+	return state.queries?.[ context ]?.[ stableKey ]?.meta?.totalItems ?? null;
+}
+
+export function getQueriedTotalPages( state, query = {} ) {
+	const { stableKey, context } = getQueryParts( query );
+
+	return state.queries?.[ context ]?.[ stableKey ]?.meta?.totalPages ?? null;
+}

packages/core-data/src/queried-data/test/reducer.js

@@ -159,7 +159,7 @@ describe( 'reducer', () => {
 				default: { 1: true },
 			},
 			queries: {
-				default: { 's=a': [ 1 ] },
+				default: { 's=a': { itemIds: [ 1 ] } },
 			},
 		} );
 	} );
@@ -200,8 +200,8 @@ describe( 'reducer', () => {
 			},
 			queries: {
 				default: {
-					'': [ 1, 2, 3, 4 ],
-					's=a': [ 1, 3 ],
+					'': { itemIds: [ 1, 2, 3, 4 ] },
+					's=a': { itemIds: [ 1, 3 ] },
 				},
 			},
 		} );
@@ -218,8 +218,8 @@ describe( 'reducer', () => {
 			},
 			queries: {
 				default: {
-					'': [ 1, 2, 4 ],
-					's=a': [ 1 ],
+					'': { itemIds: [ 1, 2, 4 ] },
+					's=a': { itemIds: [ 1 ] },
 				},
 			},
 		} );
@@ -238,8 +238,8 @@ describe( 'reducer', () => {
 			},
 			queries: {
 				default: {
-					'': [ 'foo//bar1', 'foo//bar2', 'foo//bar3' ],
-					's=2': [ 'foo//bar2' ],
+					'': { itemIds: [ 'foo//bar1', 'foo//bar2', 'foo//bar3' ] },
+					's=2': { itemIds: [ 'foo//bar2' ] },
 				},
 			},
 		} );
@@ -258,8 +258,8 @@ describe( 'reducer', () => {
 			},
 			queries: {
 				default: {
-					'': [ 'foo//bar1', 'foo//bar3' ],
-					's=2': [],
+					'': { itemIds: [ 'foo//bar1', 'foo//bar3' ] },
+					's=2': { itemIds: [] },
 				},
 			},
 		} );