Framework: Add queried-data state helper utility

core-data/actions.js

@@ -4,19 +4,27 @@
 import { castArray } from 'lodash';
 
 /**
- * Returns an action object used in signalling that the request for a given
- * data type has been made.
+ * Internal dependencies
+ */
+import {
+	toggleIsRequesting,
+	receiveQueriedItems,
+} from './queried-data';
+
+/**
+ * Returns an action object used in signalling whether a request for a given
+ * terms of a taxonomy is in progress.
  *
- * @param {string}  dataType Data type requested.
- * @param {?string} subType  Optional data sub-type.
+ * @param {string}  taxonomy     Data type requested.
+ * @param {?Object} query        Optional terms query.
+ * @param {boolean} isRequesting Whether a request is in progress.
  *
  * @return {Object} Action object.
  */
-export function setRequested( dataType, subType ) {
+export function toggleIsRequestingTerms( taxonomy, query, isRequesting ) {
 	return {
-		type: 'SET_REQUESTED',
-		dataType,
-		subType,
+		...toggleIsRequesting( query, isRequesting ),
+		taxonomy,
 	};
 }
 
@@ -25,15 +33,15 @@ export function setRequested( dataType, subType ) {
  * for a given taxonomy.
  *
  * @param {string}   taxonomy Taxonomy name.
+ * @param {?Object}  query    Optional terms query.
  * @param {Object[]} terms    Terms received.
  *
  * @return {Object} Action object.
  */
-export function receiveTerms( taxonomy, terms ) {
+export function receiveTerms( taxonomy, query, terms ) {
 	return {
-		type: 'RECEIVE_TERMS',
+		...receiveQueriedItems( query, terms ),
 		taxonomy,
-		terms,
 	};
 }
 

core-data/queried-data/actions.js

@@ -0,0 +1,54 @@
+/**
+ * Internal dependencies
+ */
+import {
+	TOGGLE_IS_REQUESTING,
+	RECEIVE_ITEMS,
+} from './constant';
+
+/**
+ * Returns an action object used in signalling whether a request for queried
+ * data is in progress.
+ *
+ * @param {?Object} query        Optional query object.
+ * @param {boolean} isRequesting Whether request is in progress.
+ *
+ * @return {Object} Action object.
+ */
+export function toggleIsRequesting( query = {}, isRequesting ) {
+	return {
+		type: TOGGLE_IS_REQUESTING,
+		query,
+		isRequesting,
+	};
+}
+
+/**
+ * Returns an action object used in signalling that items have been received.
+ *
+ * @param {Array} items Items received.
+ *
+ * @return {Object} Action object.
+ */
+export function receiveItems( items ) {
+	return {
+		type: RECEIVE_ITEMS,
+		items,
+	};
+}
+
+/**
+ * Returns an action object used in signalling that queried data has been
+ * received.
+ *
+ * @param {?Object} query Optional query object.
+ * @param {Array}   items Queried items received.
+ *
+ * @return {Object} Action object.
+ */
+export function receiveQueriedItems( query = {}, items ) {
+	return {
+		...receiveItems( items ),
+		query,
+	};
+}

core-data/queried-data/constant.js

@@ -0,0 +1,14 @@
+/**
+ * Action type used in signalling that a queried items page has been received.
+ *
+ * @type {string}
+ */
+export const RECEIVE_ITEMS = '@@queried-data/RECEIVE_ITEMS';
+
+/**
+ * Action type used in signalling that a request has started or stopped for an
+ * items query.
+ *
+ * @type {string}
+ */
+export const TOGGLE_IS_REQUESTING = '@@queried-data/TOGGLE_IS_REQUESTING';

core-data/queried-data/get-query-parts.js

@@ -0,0 +1,64 @@
+/**
+ * Internal dependencies
+ */
+import { withWeakMapCache } from './utils';
+
+/**
+ * An object of properties describing a specific query.
+ *
+ * @typedef {WPQueriedDataQueryParts}
+ *
+ * @property {number} page      The query page (1-based index, default 1).
+ * @property {number} perPage   Items per page for query (default 10).
+ * @property {string} stableKey An encoded stable string of all non-pagination
+ *                              query parameters.
+ */
+
+/**
+ * Given a query object, returns an object of parts, including pagination
+ * details (`page` and `perPage`, or default values). All other properties are
+ * encoded into a stable (idempotent) `stableKey` value.
+ *
+ * @param {Object} query Optional query object.
+ *
+ * @return {WPQueriedDataQueryParts} Query parts.
+ */
+export function getQueryParts( query ) {
+	/**
+	 * @type {WPQueriedDataQueryParts}
+	 */
+	const parts = {
+		stableKey: '',
+		page: 1,
+		perPage: 10,
+	};
+
+	// Ensure stable key by sorting keys. Also more efficient for iterating.
+	const keys = Object.keys( query ).sort();
+
+	for ( let i = 0; i < keys.length; i++ ) {
+		const key = keys[ i ];
+		const value = query[ key ];
+
+		switch ( key ) {
+			case 'page':
+			case 'perPage':
+				parts[ key ] = value;
+				break;
+
+			default:
+				// While it's not required to be one, for simplicity's sake
+				// mimic querystring encoding for stable key.
+				parts.stableKey += (
+					( parts.stableKey ? '&' : '' ) +
+					encodeURIComponent( key ) +
+					'=' +
+					encodeURIComponent( value )
+				);
+		}
+	}
+
+	return parts;
+}
+
+export default withWeakMapCache( getQueryParts );

core-data/queried-data/index.js

@@ -0,0 +1,5 @@
+export * from './constant';
+export * from './actions';
+export * from './selectors';
+export { default as reducer } from './reducer';
+export { default as getQueryParts } from './get-query-parts';

core-data/queried-data/reducer.js

@@ -0,0 +1,146 @@
+/**
+ * External dependencies
+ */
+import { combineReducers } from 'redux';
+import { keyBy, map, flowRight, merge } from 'lodash';
+
+/**
+ * Internal dependencies
+ */
+import {
+	ifMatchingAction,
+	replaceAction,
+	onSubKey,
+} from './utils';
+import {
+	RECEIVE_ITEMS,
+	TOGGLE_IS_REQUESTING,
+} from './constant';
+import getQueryParts from './get-query-parts';
+
+/**
+ * Returns a merged array of item IDs, given details of the received paginated
+ * items. The array is sparse-like with `undefined` entries where holes exist.
+ *
+ * @param {?Array<number>} itemIds     Original item IDs (default empty array).
+ * @param {number[]}       nextItemIds Item IDs to merge.
+ * @param {number}         page        Page of items merged.
+ * @param {number}         perPage     Number of items per page.
+ *
+ * @return {number[]} Merged array of item IDs.
+ */
+export function getMergedItemIds( itemIds, nextItemIds, page, perPage ) {
+	const nextItemIdsStartIndex = ( page - 1 ) * perPage;
+
+	// If later page has already been received, default to the larger known
+	// size of the existing array, else calculate as extending the existing.
+	const size = Math.max(
+		itemIds.length,
+		nextItemIdsStartIndex + nextItemIds.length
+	);
+
+	// Preallocate array since size is known.
+	const mergedItemIds = new Array( size );
+
+	for ( let i = 0; i < size; i++ ) {
+		// Preserve existing item ID except for subset of range of next items.
+		const isInNextItemsRange = (
+			i >= nextItemIdsStartIndex &&
+			i < nextItemIdsStartIndex + nextItemIds.length
+		);
+
+		mergedItemIds[ i ] = isInNextItemsRange ?
+			nextItemIds[ i - nextItemIdsStartIndex ] :
+			itemIds[ i ];
+	}
+
+	return mergedItemIds;
+}
+
+/**
+ * Reducer tracking items state, keyed by ID. Items are assumed to be normal,
+ * where identifiers are common across all queries.
+ *
+ * @param {Object} state  Current state.
+ * @param {Object} action Dispatched action.
+ *
+ * @return {Object} Next state.
+ */
+function items( state = {}, action ) {
+	switch ( action.type ) {
+		case RECEIVE_ITEMS:
+			return {
+				...state,
+				...keyBy( action.items, 'id' ),
+			};
+	}
+
+	return state;
+}
+
+/**
+ * Reducer tracking queries state, keyed by stable query key. Each reducer
+ * query object includes `itemIds` and `requestingPageByPerPage`.
+ *
+ * @param {Object} state  Current state.
+ * @param {Object} action Dispatched action.
+ *
+ * @return {Object} Next state.
+ */
+const queries = flowRight( [
+	// Limit to matching action type so we don't attempt to replace action on
+	// an unhandled action.
+	ifMatchingAction( ( action ) => 'query' in action ),
+
+	// Inject query parts into action for use both in `onSubKey` and reducer.
+	replaceAction( ( action ) => {
+		// `ifMatchingAction` still passes on initialization, where state is
+		// undefined and a query is not assigned. Avoid attempting to parse
+		// parts. `onSubKey` will omit by lack of `stableKey`.
+		if ( action.query ) {
+			return {
+				...action,
+				...getQueryParts( action.query ),
+			};
+		}
+
+		return action;
+	} ),
+
+	// Queries shape is shared, but keyed by query `stableKey` part. Original
+	// reducer tracks only a single query object.
+	onSubKey( 'stableKey' ),
+] )( combineReducers( {
+	itemIds( state = null, action ) {
+		const { type, page, perPage } = action;
+
+		if ( type !== RECEIVE_ITEMS ) {
+			return state;
+		}
+
+		return getMergedItemIds(
+			state || [],
+			map( action.items, 'id' ),
+			page,
+			perPage
+		);
+	},
+	requestingPageByPerPage( state = {}, action ) {
+		const { type, page, perPage, isRequesting } = action;
+
+		if ( type !== TOGGLE_IS_REQUESTING ) {
+			return state;
+		}
+
+		return merge( {}, state, {
+			[ perPage ]: {
+				[ page ]: isRequesting,
+			},
+		} );
+	},
+} ) );
+
+export default combineReducers( {
+	items,
+	queries,
+} );