@wordpress/data 10.25.0 → 10.26.0

package/src/redux-store/index.js

@@ -108,14 +108,18 @@ function createResolversCache() {
 	};
 }
 
-function createBindingCache( bind ) {
+function createBindingCache( getItem, bindItem ) {
 	const cache = new WeakMap();
 
 	return {
-		get( item, itemName ) {
+		get( itemName ) {
+			const item = getItem( itemName );
+			if ( ! item ) {
+				return null;
+			}
 			let boundItem = cache.get( item );
 			if ( ! boundItem ) {
-				boundItem = bind( item, itemName );
+				boundItem = bindItem( item, itemName );
 				cache.set( item, boundItem );
 			}
 			return boundItem;
@@ -123,6 +127,13 @@ function createBindingCache( bind ) {
 	};
 }
 
+function createPrivateProxy( publicItems, privateItems ) {
+	return new Proxy( publicItems, {
+		get: ( target, itemName ) =>
+			privateItems.get( itemName ) || Reflect.get( target, itemName ),
+	} );
+}
+
 /**
  * Creates a data store descriptor for the provided Redux store configuration containing
  * properties describing reducer, actions, selectors, controls and resolvers.
@@ -179,16 +190,20 @@ export default function createReduxStore( key, options ) {
 			 */
 			const listeners = new Set();
 			const reducer = options.reducer;
+
+			// Object that every thunk function receives as the first argument. It contains the
+			// `registry`, `dispatch`, `select` and `resolveSelect` fields. Some of them are
+			// constructed as getters to avoid circular dependencies.
 			const thunkArgs = {
 				registry,
 				get dispatch() {
-					return thunkActions;
+					return thunkDispatch;
 				},
 				get select() {
-					return thunkSelectors;
+					return thunkSelect;
 				},
 				get resolveSelect() {
-					return getResolveSelectors();
+					return resolveSelectors;
 				},
 			};
 
@@ -198,42 +213,61 @@ export default function createReduxStore( key, options ) {
 				registry,
 				thunkArgs
 			);
+
 			// Expose the private registration functions on the store
 			// so they can be copied to a sub registry in registry.js.
 			lock( store, privateRegistrationFunctions );
 			const resolversCache = createResolversCache();
 
+			// Binds an action creator (`action`) to the `store`, making it a callable function.
+			// These are the functions that are returned by `useDispatch`, for example.
+			// It always returns a `Promise`, although actions are not always async. That's an
+			// unfortunate backward compatibility measure.
 			function bindAction( action ) {
 				return ( ...args ) =>
 					Promise.resolve( store.dispatch( action( ...args ) ) );
 			}
 
+			/*
+			 * Object with all public actions, both metadata and store actions.
+			 */
 			const actions = {
 				...mapValues( metadataActions, bindAction ),
 				...mapValues( options.actions, bindAction ),
 			};
 
-			const boundPrivateActions = createBindingCache( bindAction );
-			const allActions = new Proxy( () => {}, {
-				get: ( target, prop ) => {
-					const privateAction = privateActions[ prop ];
-					return privateAction
-						? boundPrivateActions.get( privateAction, prop )
-						: actions[ prop ];
-				},
-			} );
+			// Object with both public and private actions. Private actions are accessed through a proxy,
+			// which looks them up in real time on the `privateActions` object. That's because private
+			// actions can be registered at any time with `registerPrivateActions`. Also once a private
+			// action creator is bound to the store, it is cached to give it a stable identity.
+			const allActions = createPrivateProxy(
+				actions,
+				createBindingCache(
+					( name ) => privateActions[ name ],
+					bindAction
+				)
+			);
 
-			const thunkActions = new Proxy( allActions, {
-				apply: ( target, thisArg, [ action ] ) =>
-					store.dispatch( action ),
-			} );
+			// An object that implements the `dispatch` object that is passed to thunk functions.
+			// It is callable (`dispatch( action )`) and also has methods (`dispatch.foo()`) that
+			// correspond to bound registered actions, both public and private. Implemented with the proxy
+			// `get` method, delegating to `allActions`.
+			const thunkDispatch = new Proxy(
+				( action ) => store.dispatch( action ),
+				{ get: ( target, name ) => allActions[ name ] }
+			);
 
+			// To the public `actions` object, add the "locked" `allActions` object. When used,
+			// `unlock( actions )` will return `allActions`, implementing a way how to get at the private actions.
 			lock( actions, allActions );
 
+			// If we have selector resolvers, convert them to a normalized form.
 			const resolvers = options.resolvers
-				? mapResolvers( options.resolvers )
+				? mapValues( options.resolvers, mapResolver )
 				: {};
 
+			// Bind a selector to the store. Call the selector with the current state, correct registry,
+			// and if there is a resolver, attach the resolver logic to the selector.
 			function bindSelector( selector, selectorName ) {
 				if ( selector.isRegistrySelector ) {
 					selector.registry = registry;
@@ -241,8 +275,7 @@ export default function createReduxStore( key, options ) {
 				const boundSelector = ( ...args ) => {
 					args = normalize( selector, args );
 					const state = store.__unstableOriginalGetState();
-					// Before calling the selector, switch to the correct
-					// registry.
+					// Before calling the selector, switch to the correct registry.
 					if ( selector.isRegistrySelector ) {
 						selector.registry = registry;
 					}
@@ -267,66 +300,137 @@ export default function createReduxStore( key, options ) {
 					selectorName,
 					resolver,
 					store,
-					resolversCache
+					resolversCache,
+					boundMetadataSelectors
 				);
 			}
 
+			// Metadata selectors are bound differently: different state (`state.metadata`), no resolvers,
+			// normalization depending on the target selector.
 			function bindMetadataSelector( metaDataSelector ) {
-				const boundSelector = ( ...args ) => {
-					const state = store.__unstableOriginalGetState();
-
-					const originalSelectorName = args && args[ 0 ];
-					const originalSelectorArgs = args && args[ 1 ];
-					const targetSelector =
-						options?.selectors?.[ originalSelectorName ];
-
+				const boundSelector = (
+					selectorName,
+					selectorArgs,
+					...args
+				) => {
 					// Normalize the arguments passed to the target selector.
-					if ( originalSelectorName && targetSelector ) {
-						args[ 1 ] = normalize(
-							targetSelector,
-							originalSelectorArgs
-						);
+					if ( selectorName ) {
+						const targetSelector =
+							options.selectors?.[ selectorName ];
+						if ( targetSelector ) {
+							selectorArgs = normalize(
+								targetSelector,
+								selectorArgs
+							);
+						}
 					}
 
-					return metaDataSelector( state.metadata, ...args );
+					const state = store.__unstableOriginalGetState();
+
+					return metaDataSelector(
+						state.metadata,
+						selectorName,
+						selectorArgs,
+						...args
+					);
 				};
 				boundSelector.hasResolver = false;
 				return boundSelector;
 			}
 
+			// Perform binding of both metadata and store selectors and combine them in one
+			// `selectors` object. These are all public selectors of the store.
+			const boundMetadataSelectors = mapValues(
+				metadataSelectors,
+				bindMetadataSelector
+			);
+
+			const boundSelectors = mapValues( options.selectors, bindSelector );
+
 			const selectors = {
-				...mapValues( metadataSelectors, bindMetadataSelector ),
-				...mapValues( options.selectors, bindSelector ),
+				...boundMetadataSelectors,
+				...boundSelectors,
 			};
 
-			const boundPrivateSelectors = createBindingCache( bindSelector );
+			// Cache of bould private selectors. They are bound only when first accessed, because
+			// new private selectors can be registered at any time (with `registerPrivateSelectors`).
+			// Once bound, they are cached to give them a stable identity.
+			const boundPrivateSelectors = createBindingCache(
+				( name ) => privateSelectors[ name ],
+				bindSelector
+			);
+
+			const allSelectors = createPrivateProxy(
+				selectors,
+				boundPrivateSelectors
+			);
 
 			// Pre-bind the private selectors that have been registered by the time of
 			// instantiation, so that registry selectors are bound to the registry.
-			for ( const [ selectorName, selector ] of Object.entries(
-				privateSelectors
-			) ) {
-				boundPrivateSelectors.get( selector, selectorName );
+			for ( const selectorName of Object.keys( privateSelectors ) ) {
+				boundPrivateSelectors.get( selectorName );
 			}
 
-			const allSelectors = new Proxy( () => {}, {
-				get: ( target, prop ) => {
-					const privateSelector = privateSelectors[ prop ];
-					return privateSelector
-						? boundPrivateSelectors.get( privateSelector, prop )
-						: selectors[ prop ];
-				},
-			} );
-
-			const thunkSelectors = new Proxy( allSelectors, {
-				apply: ( target, thisArg, [ selector ] ) =>
-					selector( store.__unstableOriginalGetState() ),
-			} );
+			// An object that implements the `select` object that is passed to thunk functions.
+			// It is callable (`select( selector )`) and also has methods (`select.foo()`) that
+			// correspond to bound registered selectors, both public and private. Implemented with the proxy
+			// `get` method, delegating to `allSelectors`.
+			const thunkSelect = new Proxy(
+				( selector ) => selector( store.__unstableOriginalGetState() ),
+				{ get: ( target, name ) => allSelectors[ name ] }
+			);
 
+			// To the public `selectors` object, add the "locked" `allSelectors` object. When used,
+			// `unlock( selectors )` will return `allSelectors`, implementing a way how to get at the private selectors.
 			lock( selectors, allSelectors );
 
-			const resolveSelectors = mapResolveSelectors( selectors, store );
-			const suspendSelectors = mapSuspendSelectors( selectors, store );
+			// For each selector, create a function that calls the selector, waits for resolution and returns
+			// a promise that resolves when the resolution is finished.
+			const bindResolveSelector = mapResolveSelector(
+				store,
+				boundMetadataSelectors
+			);
+
+			// Now apply this function to all bound selectors, public and private. We are excluding
+			// metadata selectors because they don't have resolvers.
+			const resolveSelectors = mapValues(
+				boundSelectors,
+				bindResolveSelector
+			);
+
+			const allResolveSelectors = createPrivateProxy(
+				resolveSelectors,
+				createBindingCache(
+					( name ) => boundPrivateSelectors.get( name ),
+					bindResolveSelector
+				)
+			);
+
+			// Lock the selectors so that `unlock( resolveSelectors )` returns `allResolveSelectors`.
+			lock( resolveSelectors, allResolveSelectors );
+
+			// Now, in a way very similar to `bindResolveSelector`, we create a function that maps
+			// selectors to functions that throw a suspense promise if not yet resolved.
+			const bindSuspendSelector = mapSuspendSelector(
+				store,
+				boundMetadataSelectors
+			);
+
+			const suspendSelectors = {
+				...boundMetadataSelectors, // no special suspense behavior
+				...mapValues( boundSelectors, bindSuspendSelector ),
+			};
+
+			const allSuspendSelectors = createPrivateProxy(
+				suspendSelectors,
+				createBindingCache(
+					( name ) => boundPrivateSelectors.get( name ),
+					bindSuspendSelector
+				)
+			);
+
+			// Lock the selectors so that `unlock( suspendSelectors )` returns 'allSuspendSelectors`.
+			lock( suspendSelectors, allSuspendSelectors );
 
 			const getSelectors = () => selectors;
 			const getActions = () => actions;
@@ -381,7 +485,7 @@ export default function createReduxStore( key, options ) {
 
 	// Expose the private registration functions on the store
 	// descriptor. That's a natural choice since that's where the
-	// public actions and selectors are stored .
+	// public actions and selectors are stored.
 	lock( storeDescriptor, privateRegistrationFunctions );
 
 	return storeDescriptor;
@@ -445,46 +549,37 @@ function instantiateReduxStore( key, options, registry, thunkArgs ) {
 }
 
 /**
- * Maps selectors to functions that return a resolution promise for them
+ * Maps selectors to functions that return a resolution promise for them.
  *
- * @param {Object} selectors Selectors to map.
- * @param {Object} store     The redux store the selectors select from.
+ * @param {Object} store                  The redux store the selectors are bound to.
+ * @param {Object} boundMetadataSelectors The bound metadata selectors.
  *
- * @return {Object} Selectors mapped to their resolution functions.
+ * @return {Function} Function that maps selectors to resolvers.
  */
-function mapResolveSelectors( selectors, store ) {
-	const {
-		getIsResolving,
-		hasStartedResolution,
-		hasFinishedResolution,
-		hasResolutionFailed,
-		isResolving,
-		getCachedResolvers,
-		getResolutionState,
-		getResolutionError,
-		hasResolvingSelectors,
-		countSelectorsByStatus,
-		...storeSelectors
-	} = selectors;
-
-	return mapValues( storeSelectors, ( selector, selectorName ) => {
+function mapResolveSelector( store, boundMetadataSelectors ) {
+	return ( selector, selectorName ) => {
 		// If the selector doesn't have a resolver, just convert the return value
 		// (including exceptions) to a Promise, no additional extra behavior is needed.
 		if ( ! selector.hasResolver ) {
 			return async ( ...args ) => selector.apply( null, args );
 		}
 
-		return ( ...args ) => {
-			return new Promise( ( resolve, reject ) => {
-				const hasFinished = () =>
-					selectors.hasFinishedResolution( selectorName, args );
-				const finalize = ( result ) => {
-					const hasFailed = selectors.hasResolutionFailed(
+		return ( ...args ) =>
+			new Promise( ( resolve, reject ) => {
+				const hasFinished = () => {
+					return boundMetadataSelectors.hasFinishedResolution(
 						selectorName,
 						args
 					);
+				};
+				const finalize = ( result ) => {
+					const hasFailed =
+						boundMetadataSelectors.hasResolutionFailed(
+							selectorName,
+							args
+						);
 					if ( hasFailed ) {
-						const error = selectors.getResolutionError(
+						const error = boundMetadataSelectors.getResolutionError(
 							selectorName,
 							args
 						);
@@ -494,6 +589,7 @@ function mapResolveSelectors( selectors, store ) {
 					}
 				};
 				const getResult = () => selector.apply( null, args );
+
 				// Trigger the selector (to trigger the resolver)
 				const result = getResult();
 				if ( hasFinished() ) {
@@ -507,20 +603,19 @@ function mapResolveSelectors( selectors, store ) {
 					}
 				} );
 			} );
-		};
-	} );
+	};
 }
 
 /**
  * Maps selectors to functions that throw a suspense promise if not yet resolved.
  *
- * @param {Object} selectors Selectors to map.
- * @param {Object} store     The redux store the selectors select from.
+ * @param {Object} store                  The redux store the selectors select from.
+ * @param {Object} boundMetadataSelectors The bound metadata selectors.
  *
- * @return {Object} Selectors mapped to their suspense functions.
+ * @return {Function} Function that maps selectors to their suspending versions.
  */
-function mapSuspendSelectors( selectors, store ) {
-	return mapValues( selectors, ( selector, selectorName ) => {
+function mapSuspendSelector( store, boundMetadataSelectors ) {
+	return ( selector, selectorName ) => {
 		// Selector without a resolver doesn't have any extra suspense behavior.
 		if ( ! selector.hasResolver ) {
 			return selector;
@@ -529,9 +624,22 @@ function mapSuspendSelectors( selectors, store ) {
 		return ( ...args ) => {
 			const result = selector.apply( null, args );
 
-			if ( selectors.hasFinishedResolution( selectorName, args ) ) {
-				if ( selectors.hasResolutionFailed( selectorName, args ) ) {
-					throw selectors.getResolutionError( selectorName, args );
+			if (
+				boundMetadataSelectors.hasFinishedResolution(
+					selectorName,
+					args
+				)
+			) {
+				if (
+					boundMetadataSelectors.hasResolutionFailed(
+						selectorName,
+						args
+					)
+				) {
+					throw boundMetadataSelectors.getResolutionError(
+						selectorName,
+						args
+					);
 				}
 
 				return result;
@@ -540,7 +648,10 @@ function mapSuspendSelectors( selectors, store ) {
 			throw new Promise( ( resolve ) => {
 				const unsubscribe = store.subscribe( () => {
 					if (
-						selectors.hasFinishedResolution( selectorName, args )
+						boundMetadataSelectors.hasFinishedResolution(
+							selectorName,
+							args
+						)
 					) {
 						resolve();
 						unsubscribe();
@@ -548,26 +659,24 @@ function mapSuspendSelectors( selectors, store ) {
 				} );
 			} );
 		};
-	} );
+	};
 }
 
 /**
- * Convert resolvers to a normalized form, an object with `fulfill` method and
+ * Convert a resolver to a normalized form, an object with `fulfill` method and
  * optional methods like `isFulfilled`.
  *
- * @param {Object} resolvers Resolver to convert
+ * @param {Function} resolver Resolver to convert
  */
-function mapResolvers( resolvers ) {
-	return mapValues( resolvers, ( resolver ) => {
-		if ( resolver.fulfill ) {
-			return resolver;
-		}
+function mapResolver( resolver ) {
+	if ( resolver.fulfill ) {
+		return resolver;
+	}
 
-		return {
-			...resolver, // Copy the enumerable properties of the resolver function.
-			fulfill: resolver, // Add the fulfill method.
-		};
-	} );
+	return {
+		...resolver, // Copy the enumerable properties of the resolver function.
+		fulfill: resolver, // Add the fulfill method.
+	};
 }
 
 /**
@@ -575,18 +684,20 @@ function mapResolvers( resolvers ) {
  * Resolvers are side effects invoked once per argument set of a given selector call,
  * used in ensuring that the data needs for the selector are satisfied.
  *
- * @param {Object} selector       The selector function to be bound.
- * @param {string} selectorName   The selector name.
- * @param {Object} resolver       Resolver to call.
- * @param {Object} store          The redux store to which the resolvers should be mapped.
- * @param {Object} resolversCache Resolvers Cache.
+ * @param {Object} selector               The selector function to be bound.
+ * @param {string} selectorName           The selector name.
+ * @param {Object} resolver               Resolver to call.
+ * @param {Object} store                  The redux store to which the resolvers should be mapped.
+ * @param {Object} resolversCache         Resolvers Cache.
+ * @param {Object} boundMetadataSelectors The bound metadata selectors.
  */
 function mapSelectorWithResolver(
 	selector,
 	selectorName,
 	resolver,
 	store,
-	resolversCache
+	resolversCache,
+	boundMetadataSelectors
 ) {
 	function fulfillSelector( args ) {
 		const state = store.getState();
@@ -599,14 +710,8 @@ function mapSelectorWithResolver(
 			return;
 		}
 
-		const { metadata } = store.__unstableOriginalGetState();
-
 		if (
-			metadataSelectors.hasStartedResolution(
-				metadata,
-				selectorName,
-				args
-			)
+			boundMetadataSelectors.hasStartedResolution( selectorName, args )
 		) {
 			return;
 		}

package/src/redux-store/test/index.js

@@ -309,10 +309,11 @@ describe( 'normalizing args', () => {
 
 		expect( normalizingFunction ).toHaveBeenCalledWith( [ 'foo', 'bar' ] );
 
-		// Needs to be called twice:
+		// Needs to be called three times:
 		// 1. When the selector is called.
-		// 2. When the resolver is fulfilled.
-		expect( normalizingFunction ).toHaveBeenCalledTimes( 2 );
+		// 2. When the resolver check if it's already running.
+		// 3. When the resolver is fulfilled.
+		expect( normalizingFunction ).toHaveBeenCalledTimes( 3 );
 	} );
 
 	it( 'should not call the __unstableNormalizeArgs method if there are no arguments passed to the selector (and thus the resolver)', async () => {

package/src/test/privateAPIs.js

@@ -124,6 +124,52 @@ describe( 'Private data APIs', () => {
 			);
 		} );
 
+		it( 'should support private selectors with resolvers', async () => {
+			const testStore = createReduxStore( 'test', {
+				reducer: ( state = {}, action ) => {
+					if ( action.type === 'RECEIVE' ) {
+						return { ...state, [ action.key ]: action.value };
+					}
+					return state;
+				},
+				selectors: {},
+				resolvers: {
+					get:
+						( key ) =>
+						async ( { dispatch } ) => {
+							const value = await ( 'resolved-' + key );
+							dispatch( { type: 'RECEIVE', key, value } );
+						},
+				},
+			} );
+			registry.register( testStore );
+			unlock( testStore ).registerPrivateSelectors( {
+				get: ( state, key ) => state[ key ],
+			} );
+
+			// Verify that the private selector is available in resolveSelect.
+			const resolved = await unlock(
+				registry.resolveSelect( testStore )
+			).get( 'x' );
+			expect( resolved ).toBe( 'resolved-x' );
+
+			// Verify that the private selector is available in suspendSelect.
+			let suspended;
+			try {
+				unlock( registry.suspendSelect( testStore ) ).get( 'y' );
+			} catch ( error ) {
+				suspended = error;
+			}
+
+			expect( suspended ).toBeInstanceOf( Promise );
+			await suspended;
+
+			// After the suspense promise resolves, the result should be ready.
+			expect(
+				unlock( registry.suspendSelect( testStore ) ).get( 'y' )
+			).toBe( 'resolved-y' );
+		} );
+
 		it( 'should give private selectors access to the state', () => {
 			const groceryStore = createStore();
 			unlock( groceryStore ).registerPrivateSelectors( {