@wordpress/data 10.24.0 → 10.26.0

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## Unreleased
 
+## 10.26.0 (2025-06-25)
+
+### Bug Fixes
+
+-   Add support for private selectors to `resolveSelect` and `suspendSelect` ([#52036](https://github.com/WordPress/gutenberg/pull/52036)).
+
+## 10.25.0 (2025-06-04)
+
 ## 10.24.0 (2025-05-22)
 
 ## 10.23.0 (2025-05-07)

package/build/redux-store/index.js

@@ -106,19 +106,28 @@ 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;
     }
   };
 }
+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
@@ -176,42 +185,68 @@ 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;
         }
       };
       const store = instantiateReduxStore(key, options, registry, thunkArgs);
+
       // Expose the private registration functions on the store
       // so they can be copied to a sub registry in registry.js.
       (0, _lockUnlock.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];
-        }
-      });
-      const thunkActions = new Proxy(allActions, {
-        apply: (target, thisArg, [action]) => store.dispatch(action)
+
+      // 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));
+
+      // 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.
       (0, _lockUnlock.lock)(actions, allActions);
-      const resolvers = options.resolvers ? mapResolvers(options.resolvers) : {};
+
+      // If we have selector resolvers, convert them to a normalized form.
+      const resolvers = 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;
@@ -219,8 +254,7 @@ 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;
           }
@@ -236,47 +270,84 @@ function createReduxStore(key, options) {
           boundSelector.hasResolver = false;
           return boundSelector;
         }
-        return mapSelectorWithResolver(boundSelector, selectorName, resolver, store, resolversCache);
+        return mapSelectorWithResolver(boundSelector, selectorName, resolver, store, resolversCache, boundMetadataSelectors);
       }
-      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];
 
+      // Metadata selectors are bound differently: different state (`state.metadata`), no resolvers,
+      // normalization depending on the target selector.
+      function bindMetadataSelector(metaDataSelector) {
+        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.
       (0, _lockUnlock.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`.
+      (0, _lockUnlock.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`.
+      (0, _lockUnlock.lock)(suspendSelectors, allSuspendSelectors);
       const getSelectors = () => selectors;
       const getActions = () => actions;
       const getResolveSelectors = () => resolveSelectors;
@@ -325,7 +396,7 @@ 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.
   (0, _lockUnlock.lock)(storeDescriptor, privateRegistrationFunctions);
   return storeDescriptor;
 }
@@ -372,113 +443,99 @@ 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(selectorName, args);
-          if (hasFailed) {
-            const error = selectors.getResolutionError(selectorName, args);
-            reject(error);
-          } else {
-            resolve(result);
-          }
-        };
-        const getResult = () => selector.apply(null, args);
-        // Trigger the selector (to trigger the resolver)
-        const result = getResult();
+    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 = boundMetadataSelectors.getResolutionError(selectorName, args);
+          reject(error);
+        } else {
+          resolve(result);
+        }
+      };
+      const getResult = () => selector.apply(null, args);
+
+      // Trigger the selector (to trigger the resolver)
+      const result = getResult();
+      if (hasFinished()) {
+        return finalize(result);
+      }
+      const unsubscribe = store.subscribe(() => {
         if (hasFinished()) {
-          return finalize(result);
+          unsubscribe();
+          finalize(getResult());
         }
-        const unsubscribe = store.subscribe(() => {
-          if (hasFinished()) {
-            unsubscribe();
-            finalize(getResult());
-          }
-        });
       });
-    };
-  });
+    });
+  };
 }
 
 /**
  * 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;
     }
     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;
       }
       throw new Promise(resolve => {
         const unsubscribe = store.subscribe(() => {
-          if (selectors.hasFinishedResolution(selectorName, args)) {
+          if (boundMetadataSelectors.hasFinishedResolution(selectorName, args)) {
             resolve();
             unsubscribe();
           }
         });
       });
     };
-  });
+  };
 }
 
 /**
- * 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;
-    }
-    return {
-      ...resolver,
-      // Copy the enumerable properties of the resolver function.
-      fulfill: resolver // Add the fulfill method.
-    };
-  });
+function mapResolver(resolver) {
+  if (resolver.fulfill) {
+    return resolver;
+  }
+  return {
+    ...resolver,
+    // Copy the enumerable properties of the resolver function.
+    fulfill: resolver // Add the fulfill method.
+  };
 }
 
 /**
@@ -486,22 +543,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) {
+function mapSelectorWithResolver(selector, selectorName, resolver, store, resolversCache, boundMetadataSelectors) {
   function fulfillSelector(args) {
     const state = store.getState();
     if (resolversCache.isRunning(selectorName, args) || typeof resolver.isFulfilled === 'function' && resolver.isFulfilled(state, ...args)) {
       return;
     }
-    const {
-      metadata
-    } = store.__unstableOriginalGetState();
-    if (metadataSelectors.hasStartedResolution(metadata, selectorName, args)) {
+    if (boundMetadataSelectors.hasStartedResolution(selectorName, args)) {
       return;
     }
     resolversCache.markAsRunning(selectorName, args);