@wordpress/core-data 4.1.1 → 4.2.0-next.e230fbab09.0

package/src/fetch/__experimental-fetch-link-suggestions.js

@@ -103,7 +103,7 @@ const fetchLinkSuggestions = async (
 						};
 					} );
 				} )
-				.catch( () => [] ) // fail by returning no results
+				.catch( () => [] ) // Fail by returning no results.
 		);
 	}
 
@@ -156,7 +156,7 @@ const fetchLinkSuggestions = async (
 	return Promise.all( queries ).then( ( results ) => {
 		return results
 			.reduce(
-				( accumulator, current ) => accumulator.concat( current ), //flatten list
+				( accumulator, current ) => accumulator.concat( current ), // Flatten list.
 				[]
 			)
 			.filter(

package/src/hooks/constants.ts

@@ -0,0 +1,7 @@
+/* eslint-disable-next-line no-shadow */
+export enum Status {
+	Idle = 'IDLE',
+	Resolving = 'RESOLVING',
+	Error = 'ERROR',
+	Success = 'SUCCESS',
+}

package/src/hooks/memoize.js

@@ -0,0 +1,7 @@
+/**
+ * External dependencies
+ */
+import memoize from 'memize';
+
+// re-export due to restrictive esModuleInterop setting
+export default memoize;

package/src/hooks/test/use-entity-record.js

@@ -0,0 +1,74 @@
+/**
+ * WordPress dependencies
+ */
+import triggerFetch from '@wordpress/api-fetch';
+import { createRegistry, RegistryProvider } from '@wordpress/data';
+
+jest.mock( '@wordpress/api-fetch' );
+
+/**
+ * External dependencies
+ */
+import { act, render } from '@testing-library/react';
+
+/**
+ * Internal dependencies
+ */
+import { store as coreDataStore } from '../../index';
+import useEntityRecord from '../use-entity-record';
+
+describe( 'useEntityRecord', () => {
+	let registry;
+	beforeEach( () => {
+		jest.useFakeTimers();
+
+		registry = createRegistry();
+		registry.register( coreDataStore );
+	} );
+
+	afterEach( () => {
+		jest.runOnlyPendingTimers();
+		jest.useRealTimers();
+	} );
+
+	const TEST_RECORD = { id: 1, hello: 'world' };
+
+	it( 'resolves the entity record when missing from the state', async () => {
+		// Provide response
+		triggerFetch.mockImplementation( () => TEST_RECORD );
+
+		let data;
+		const TestComponent = () => {
+			data = useEntityRecord( 'root', 'widget', 1 );
+			return <div />;
+		};
+		render(
+			<RegistryProvider value={ registry }>
+				<TestComponent />
+			</RegistryProvider>
+		);
+
+		expect( data ).toEqual( {
+			records: undefined,
+			hasResolved: false,
+			isResolving: false,
+			status: 'IDLE',
+		} );
+
+		await act( async () => {
+			jest.advanceTimersByTime( 1 );
+		} );
+
+		// Fetch request should have been issued
+		expect( triggerFetch ).toHaveBeenCalledWith( {
+			path: '/wp/v2/widgets/1?context=edit',
+		} );
+
+		expect( data ).toEqual( {
+			record: { hello: 'world', id: 1 },
+			hasResolved: true,
+			isResolving: false,
+			status: 'SUCCESS',
+		} );
+	} );
+} );

package/src/hooks/test/use-entity-records.js

@@ -0,0 +1,78 @@
+/**
+ * WordPress dependencies
+ */
+import triggerFetch from '@wordpress/api-fetch';
+import { createRegistry, RegistryProvider } from '@wordpress/data';
+
+jest.mock( '@wordpress/api-fetch' );
+
+/**
+ * External dependencies
+ */
+import { act, render } from '@testing-library/react';
+
+/**
+ * Internal dependencies
+ */
+import { store as coreDataStore } from '../../index';
+import useEntityRecords from '../use-entity-records';
+
+describe( 'useEntityRecords', () => {
+	let registry;
+	beforeEach( () => {
+		jest.useFakeTimers();
+
+		registry = createRegistry();
+		registry.register( coreDataStore );
+	} );
+
+	afterEach( () => {
+		jest.runOnlyPendingTimers();
+		jest.useRealTimers();
+	} );
+
+	const TEST_RECORDS = [
+		{ id: 1, hello: 'world1' },
+		{ id: 2, hello: 'world2' },
+		{ id: 3, hello: 'world3' },
+	];
+
+	it( 'resolves the entity records when missing from the state', async () => {
+		// Provide response
+		triggerFetch.mockImplementation( () => TEST_RECORDS );
+
+		let data;
+		const TestComponent = () => {
+			data = useEntityRecords( 'root', 'widget', { status: 'draft' } );
+			return <div />;
+		};
+		render(
+			<RegistryProvider value={ registry }>
+				<TestComponent />
+			</RegistryProvider>
+		);
+
+		expect( data ).toEqual( {
+			records: null,
+			hasResolved: false,
+			isResolving: false,
+			status: 'IDLE',
+		} );
+
+		await act( async () => {
+			jest.advanceTimersByTime( 1 );
+		} );
+
+		// Fetch request should have been issued
+		expect( triggerFetch ).toHaveBeenCalledWith( {
+			path: '/wp/v2/widgets?context=edit&status=draft',
+		} );
+
+		expect( data ).toEqual( {
+			records: TEST_RECORDS,
+			hasResolved: true,
+			isResolving: false,
+			status: 'SUCCESS',
+		} );
+	} );
+} );

package/src/hooks/test/use-query-select.js

@@ -0,0 +1,194 @@
+/**
+ * WordPress dependencies
+ */
+import {
+	createReduxStore,
+	createRegistry,
+	RegistryProvider,
+} from '@wordpress/data';
+
+/**
+ * External dependencies
+ */
+import { act, render } from '@testing-library/react';
+
+/**
+ * Internal dependencies
+ */
+import useQuerySelect from '../use-query-select';
+
+describe( 'useQuerySelect', () => {
+	let registry;
+	beforeEach( () => {
+		jest.useFakeTimers();
+
+		registry = createRegistry();
+		registry.registerStore( 'testStore', {
+			reducer: () => ( { foo: 'bar' } ),
+			selectors: {
+				getFoo: ( state ) => state.foo,
+				testSelector: ( state, key ) => state[ key ],
+			},
+		} );
+	} );
+
+	afterEach( () => {
+		jest.runOnlyPendingTimers();
+		jest.useRealTimers();
+	} );
+
+	const getTestComponent = ( mapSelectSpy, dependencyKey ) => ( props ) => {
+		const dependencies = props[ dependencyKey ];
+		mapSelectSpy.mockImplementation( ( select ) => ( {
+			results: select( 'testStore' ).testSelector( props.keyName ),
+		} ) );
+		const data = useQuerySelect( mapSelectSpy, [ dependencies ] );
+		return <div>{ data.results.data }</div>;
+	};
+
+	it( 'passes the relevant data to the component', () => {
+		const selectSpy = jest.fn();
+		const TestComponent = jest
+			.fn()
+			.mockImplementation( getTestComponent( selectSpy, 'keyName' ) );
+		const testInstance = render(
+			<RegistryProvider value={ registry }>
+				<TestComponent keyName="foo" />
+			</RegistryProvider>
+		);
+		// 2 times expected
+		// - 1 for initial mount
+		// - 1 for after mount before subscription set.
+		expect( selectSpy ).toHaveBeenCalledTimes( 2 );
+		expect( TestComponent ).toHaveBeenCalledTimes( 2 );
+
+		// ensure expected state was rendered
+		expect( testInstance.findByText( 'bar' ) ).toBeTruthy();
+	} );
+
+	it( 'uses memoized selectors', () => {
+		const selectors = [];
+		const TestComponent = jest.fn().mockImplementation( ( props ) => {
+			useQuerySelect(
+				function ( query ) {
+					selectors.push( query( 'testStore' ) );
+					selectors.push( query( 'testStore' ) );
+					return null;
+				},
+				[ props.keyName ]
+			);
+			return <div />;
+		} );
+
+		render(
+			<RegistryProvider value={ registry }>
+				<TestComponent keyName="foo" />
+			</RegistryProvider>
+		);
+
+		// ensure the selectors were properly memoized
+		expect( selectors ).toHaveLength( 4 );
+		expect( selectors[ 0 ] ).toHaveProperty( 'testSelector' );
+		expect( selectors[ 0 ] ).toBe( selectors[ 1 ] );
+		expect( selectors[ 1 ] ).toBe( selectors[ 2 ] );
+
+		// Re-render
+		render(
+			<RegistryProvider value={ registry }>
+				<TestComponent keyName="bar" />
+			</RegistryProvider>
+		);
+
+		// ensure we still got the memoized results after re-rendering
+		expect( selectors ).toHaveLength( 8 );
+		expect( selectors[ 3 ] ).toHaveProperty( 'testSelector' );
+		expect( selectors[ 5 ] ).toBe( selectors[ 6 ] );
+	} );
+
+	it( 'returns the expected "response" details – no resolvers and arguments', () => {
+		let querySelectData;
+		const TestComponent = jest.fn().mockImplementation( () => {
+			querySelectData = useQuerySelect( function ( query ) {
+				return query( 'testStore' ).getFoo();
+			}, [] );
+			return <div />;
+		} );
+
+		render(
+			<RegistryProvider value={ registry }>
+				<TestComponent />
+			</RegistryProvider>
+		);
+
+		expect( querySelectData ).toEqual( {
+			data: 'bar',
+			isResolving: false,
+			hasResolved: false,
+			status: 'IDLE',
+		} );
+	} );
+
+	it( 'returns the expected "response" details – resolvers and arguments', async () => {
+		registry.register(
+			createReduxStore( 'resolverStore', {
+				reducer: ( state = { resolvedFoo: 0 }, action ) => {
+					if ( action?.type === 'RECEIVE_FOO' ) {
+						return { ...state, resolvedFoo: action.value };
+					}
+					return state;
+				},
+				actions: {
+					receiveFoo: ( value ) => ( {
+						type: 'RECEIVE_FOO',
+						value,
+					} ),
+				},
+				resolvers: {
+					getResolvedFoo: () => ( { dispatch } ) =>
+						dispatch.receiveFoo( 5 ),
+				},
+				selectors: {
+					getResolvedFoo: ( state, arg ) => state.resolvedFoo + arg,
+				},
+			} )
+		);
+
+		let querySelectData;
+		const TestComponent = jest.fn().mockImplementation( () => {
+			querySelectData = useQuerySelect( function ( query ) {
+				return query( 'resolverStore' ).getResolvedFoo( 10 );
+			}, [] );
+			return <div />;
+		} );
+
+		// Initial render, expect default values
+		render(
+			<RegistryProvider value={ registry }>
+				<TestComponent />
+			</RegistryProvider>
+		);
+		expect( querySelectData ).toEqual( {
+			data: 10,
+			isResolving: false,
+			hasResolved: false,
+			status: 'IDLE',
+		} );
+
+		await act( async () => {
+			jest.advanceTimersToNextTimer();
+		} );
+
+		// Re-render, expect resolved data
+		render(
+			<RegistryProvider value={ registry }>
+				<TestComponent />
+			</RegistryProvider>
+		);
+		expect( querySelectData ).toEqual( {
+			data: 15,
+			isResolving: false,
+			hasResolved: true,
+			status: 'SUCCESS',
+		} );
+	} );
+} );

package/src/hooks/use-entity-record.ts

@@ -0,0 +1,72 @@
+/**
+ * Internal dependencies
+ */
+import useQuerySelect from './use-query-select';
+import { store as coreStore } from '../';
+import { Status } from './constants';
+
+interface EntityRecordResolution< RecordType > {
+	/** The requested entity record */
+	record: RecordType | null;
+
+	/**
+	 * Is the record still being resolved?
+	 */
+	isResolving: boolean;
+
+	/**
+	 * Is the record resolved by now?
+	 */
+	hasResolved: boolean;
+
+	/** Resolution status */
+	status: Status;
+}
+
+/**
+ * Resolves the specified entity record.
+ *
+ * @param  kind     Kind of the requested entity.
+ * @param  name     Name of the requested  entity.
+ * @param  recordId Record ID of the requested entity.
+ *
+ * @example
+ * ```js
+ * import { useEntityRecord } from '@wordpress/core-data';
+ *
+ * function PageTitleDisplay( { id } ) {
+ *   const { record, isResolving } = useEntityRecord( 'postType', 'page', id );
+ *
+ *   if ( isResolving ) {
+ *     return 'Loading...';
+ *   }
+ *
+ *   return record.title;
+ * }
+ *
+ * // Rendered in the application:
+ * // <PageTitleDisplay id={ 1 } />
+ * ```
+ *
+ * In the above example, when `PageTitleDisplay` is rendered into an
+ * application, the page and the resolution details will be retrieved from
+ * the store state using `getEntityRecord()`, or resolved if missing.
+ *
+ * @return {EntityRecordResolution<RecordType>} Entity record data.
+ * @template RecordType
+ */
+export default function __experimentalUseEntityRecord< RecordType >(
+	kind: string,
+	name: string,
+	recordId: string | number
+): EntityRecordResolution< RecordType > {
+	const { data: record, ...rest } = useQuerySelect(
+		( query ) => query( coreStore ).getEntityRecord( kind, name, recordId ),
+		[ kind, name, recordId ]
+	);
+
+	return {
+		record,
+		...rest,
+	};
+}

package/src/hooks/use-entity-records.ts

@@ -0,0 +1,89 @@
+/**
+ * WordPress dependencies
+ */
+import { addQueryArgs } from '@wordpress/url';
+
+/**
+ * Internal dependencies
+ */
+import useQuerySelect from './use-query-select';
+import { store as coreStore } from '../';
+import { Status } from './constants';
+
+interface EntityRecordsResolution< RecordType > {
+	/** The requested entity record */
+	records: RecordType[] | null;
+
+	/**
+	 * Is the record still being resolved?
+	 */
+	isResolving: boolean;
+
+	/**
+	 * Is the record resolved by now?
+	 */
+	hasResolved: boolean;
+
+	/** Resolution status */
+	status: Status;
+}
+
+/**
+ * Resolves the specified entity records.
+ *
+ * @param  kind      Kind of the requested entities.
+ * @param  name      Name of the requested entities.
+ * @param  queryArgs HTTP query for the requested entities.
+ * @example
+ * ```js
+ * import { useEntityRecord } from '@wordpress/core-data';
+ *
+ * function PageTitlesList() {
+ *   const { records, isResolving } = useEntityRecords( 'postType', 'page' );
+ *
+ *   if ( isResolving ) {
+ *     return 'Loading...';
+ *   }
+ *
+ *   return (
+ *     <ul>
+ *       {records.map(( page ) => (
+ *         <li>{ page.title }</li>
+ *       ))}
+ *     </ul>
+ *   );
+ * }
+ *
+ * // Rendered in the application:
+ * // <PageTitlesList />
+ * ```
+ *
+ * In the above example, when `PageTitlesList` is rendered into an
+ * application, the list of records and the resolution details will be retrieved from
+ * the store state using `getEntityRecords()`, or resolved if missing.
+ *
+ * @return {EntityRecordsResolution<RecordType>} Entity records data.
+ * @template RecordType
+ */
+export default function __experimentalUseEntityRecords< RecordType >(
+	kind: string,
+	name: string,
+	queryArgs: unknown = {}
+): EntityRecordsResolution< RecordType > {
+	// Serialize queryArgs to a string that can be safely used as a React dep.
+	// We can't just pass queryArgs as one of the deps, because if it is passed
+	// as an object literal, then it will be a different object on each call even
+	// if the values remain the same.
+	const queryAsString = addQueryArgs( '', queryArgs );
+
+	const { data: records, ...rest } = useQuerySelect(
+		( query ) =>
+			query( coreStore ).getEntityRecords( kind, name, queryArgs ),
+		[ kind, name, queryAsString ]
+	);
+
+	return {
+		records,
+		...rest,
+	};
+}

package/src/hooks/use-query-select.ts

@@ -0,0 +1,131 @@
+/**
+ * WordPress dependencies
+ */
+import { useSelect } from '@wordpress/data';
+
+/**
+ * Internal dependencies
+ */
+import memoize from './memoize';
+import { Status } from './constants';
+
+export const META_SELECTORS = [
+	'getIsResolving',
+	'hasStartedResolution',
+	'hasFinishedResolution',
+	'isResolving',
+	'getCachedResolvers',
+];
+
+interface QuerySelectResponse {
+	/** the requested selector return value */
+	data: Object;
+
+	/** is the record still being resolved? Via the `getIsResolving` meta-selector */
+	isResolving: boolean;
+
+	/** was the resolution started? Via the `hasStartedResolution` meta-selector */
+	hasStarted: boolean;
+
+	/** has the resolution finished? Via the `hasFinishedResolution` meta-selector. */
+	hasResolved: boolean;
+}
+
+/**
+ * Like useSelect, but the selectors return objects containing
+ * both the original data AND the resolution info.
+ *
+ * @param {Function} mapQuerySelect see useSelect
+ * @param {Array}    deps           see useSelect
+ *
+ * @example
+ * ```js
+ * import { useQuerySelect } from '@wordpress/data';
+ * import { store as coreDataStore } from '@wordpress/core-data';
+ *
+ * function PageTitleDisplay( { id } ) {
+ *   const { data: page, isResolving } = useQuerySelect( ( query ) => {
+ *     return query( coreDataStore ).getEntityRecord( 'postType', 'page', id )
+ *   }, [ id ] );
+ *
+ *   if ( isResolving ) {
+ *     return 'Loading...';
+ *   }
+ *
+ *   return page.title;
+ * }
+ *
+ * // Rendered in the application:
+ * // <PageTitleDisplay id={ 10 } />
+ * ```
+ *
+ * In the above example, when `PageTitleDisplay` is rendered into an
+ * application, the page and the resolution details will be retrieved from
+ * the store state using the `mapSelect` callback on `useQuerySelect`.
+ *
+ * If the id prop changes then any page in the state for that id is
+ * retrieved. If the id prop doesn't change and other props are passed in
+ * that do change, the title will not change because the dependency is just
+ * the id.
+ * @see useSelect
+ *
+ * @return {QuerySelectResponse} Queried data.
+ */
+export default function __experimentalUseQuerySelect( mapQuerySelect, deps ) {
+	return useSelect( ( select, registry ) => {
+		const resolve = ( store ) => enrichSelectors( select( store ) );
+		return mapQuerySelect( resolve, registry );
+	}, deps );
+}
+
+type QuerySelector = ( ...args ) => QuerySelectResponse;
+interface EnrichedSelectors {
+	[ key: string ]: QuerySelector;
+}
+
+/**
+ * Transform simple selectors into ones that return an object with the
+ * original return value AND the resolution info.
+ *
+ * @param {Object} selectors Selectors to enrich
+ * @return {EnrichedSelectors} Enriched selectors
+ */
+const enrichSelectors = memoize( ( selectors ) => {
+	const resolvers = {};
+	for ( const selectorName in selectors ) {
+		if ( META_SELECTORS.includes( selectorName ) ) {
+			continue;
+		}
+		Object.defineProperty( resolvers, selectorName, {
+			get: () => ( ...args ) => {
+				const { getIsResolving, hasFinishedResolution } = selectors;
+				const isResolving = !! getIsResolving( selectorName, args );
+				const hasResolved =
+					! isResolving &&
+					hasFinishedResolution( selectorName, args );
+				const data = selectors[ selectorName ]( ...args );
+
+				let status;
+				if ( isResolving ) {
+					status = Status.Resolving;
+				} else if ( hasResolved ) {
+					if ( data ) {
+						status = Status.Success;
+					} else {
+						status = Status.Error;
+					}
+				} else {
+					status = Status.Idle;
+				}
+
+				return {
+					data,
+					status,
+					isResolving,
+					hasResolved,
+				};
+			},
+		} );
+	}
+	return resolvers;
+} );

package/src/index.js

@@ -59,7 +59,6 @@ const storeConfig = () => ( {
 	actions: { ...actions, ...entityActions, ...createLocksActions() },
 	selectors: { ...selectors, ...entitySelectors },
 	resolvers: { ...resolvers, ...entityResolvers },
-	__experimentalUseThunks: true,
 } );
 
 /**
@@ -74,5 +73,8 @@ export const store = createReduxStore( STORE_NAME, storeConfig() );
 register( store );
 
 export { default as EntityProvider } from './entity-provider';
+export { default as __experimentalUseEntityRecord } from './hooks/use-entity-record';
+export { default as __experimentalUseEntityRecords } from './hooks/use-entity-records';
 export * from './entity-provider';
 export * from './fetch';
+export * from './entity-types';