Docs: Update @wordpress/data README with API changes (#27180)

* Docs: Update `@wordpress/data` README with API changes

* Improve the documentation explaining how `createReduxStore` works

* Add deprecations to CHANGELOG

* Update README file for data package

packages/data/CHANGELOG.md

@@ -9,6 +9,11 @@
 -   Extended `select` and `dispatch` functions to accept a data store definition as their first param in addition to a string-based store name value [#26655](https://github.com/WordPress/gutenberg/pull/26655)).
 -   Extended `useDispatch` hook to accept a data store definition as their first param in addition to a string-based store name value [#26655](https://github.com/WordPress/gutenberg/pull/26655)).
 
+### Deprecations
+
+-   `registerGenericStore` has been deprecated. Use `register` instead.
+-   `registerStore` has been deprecated. Use `register` instead.
+
 ## 4.6.0 (2019-06-12)
 
 ### New Feature

packages/data/README.md

@@ -16,11 +16,11 @@ _This package assumes that your code will run in an **ES2015+** environment. If
 
 ## Registering a Store
 
-Use the `registerStore` function to add your own store to the centralized data registry. This function accepts two arguments: a name to identify the module, and an object with values describing how your state is represented, modified, and accessed. At a minimum, you must provide a reducer function describing the shape of your state and how it changes in response to actions dispatched to the store.
+Use the `register` function to add your own store to the centralized data registry. This function accepts one argument – a store definition object that can be created with `createReduxStore` factory function. `createReduxStore` accepts two arguments: a name to identify the module, and an object with values describing how your state is represented, modified, and accessed. At a minimum, you must provide a reducer function describing the shape of your state and how it changes in response to actions dispatched to the store.
 
 ```js
 import apiFetch from '@wordpress/api-fetch';
-import { registerStore } from '@wordpress/data';
+import { createReduxStore, register } from '@wordpress/data';
 
 const DEFAULT_STATE = {
 	prices: {},
@@ -51,7 +51,7 @@ const actions = {
 	},
 };
 
-registerStore( 'my-shop', {
+const store = createReduxStore( 'my-shop', {
 	reducer( state = DEFAULT_STATE, action ) {
 		switch ( action.type ) {
 			case 'SET_PRICE':
@@ -98,18 +98,22 @@ registerStore( 'my-shop', {
 		},
 	},
 } );
+
+register( store );
 ```
 
-The return value of `registerStore` is a [Redux-like store object](https://redux.js.org/basics/store) with the following methods:
+The return value of `createReduxStore` is the `WPDataStore` object that contains two properties:
 
--   `store.getState()`: Returns the state value of the registered reducer
-    -   _Redux parallel:_ [`getState`](https://redux.js.org/api/store#getstate)
--   `store.subscribe( listener: Function )`: Registers a function called any time the value of state changes.
-    -   _Redux parallel:_ [`subscribe`](https://redux.js.org/api/store#subscribelistener)
--   `store.dispatch( action: Object )`: Given an action object, calls the registered reducer and updates the state value.
-    -   _Redux parallel:_ [`dispatch`](https://redux.js.org/api/store#dispatchaction)
+-   `name` (`string`) – the name of the store
+-   `instantiate` (`Function`) - it returns a [Redux-like store object](https://redux.js.org/basics/store) with the following methods:
+    -   `getState()`: Returns the state value of the registered reducer
+        -   _Redux parallel:_ [`getState`](https://redux.js.org/api/store#getstate)
+    -   `subscribe( listener: Function )`: Registers a function called any time the value of state changes.
+        -   _Redux parallel:_ [`subscribe`](https://redux.js.org/api/store#subscribelistener)
+    -   `dispatch( action: Object )`: Given an action object, calls the registered reducer and updates the state value.
+        -   _Redux parallel:_ [`dispatch`](https://redux.js.org/api/store#dispatchaction)
 
-### Options
+### Redux Store Options
 
 #### `reducer`
 
@@ -308,7 +312,7 @@ reducing functions into a single reducing function you can pass to registerReduc
 _Usage_
 
 ```js
-import { combineReducers, registerStore } from '@wordpress/data';
+import { combineReducers, createReduxStore, register } from '@wordpress/data';
 
 const prices = ( state = {}, action ) => {
 	return action.type === 'SET_PRICE' ?
@@ -325,12 +329,13 @@ const discountPercent = ( state = 0, action ) => {
 		state;
 };
 
-registerStore( 'my-shop', {
+const store = createReduxStore( 'my-shop', {
 	reducer: combineReducers( {
 		prices,
 		discountPercent,
 	} ),
 } );
+register( store );
 ```
 
 _Parameters_
@@ -479,7 +484,7 @@ dispatch( 'my-shop' ).setPrice( 'hammer', 9.75 );
 
 _Parameters_
 
--   _name_ `string`: Store name.
+-   _storeNameOrDefinition_ `(string|WPDataStore)`: Unique namespace identifier for the store or the store definition.
 
 _Returns_
 
@@ -512,7 +517,7 @@ const store = createReduxStore( 'demo', {
         getValue: ( state ) => state,
     },
 } );
-registry.register( store );
+register( store );
 ```
 
 _Parameters_
@@ -521,6 +526,8 @@ _Parameters_
 
 <a name="registerGenericStore" href="#registerGenericStore">#</a> **registerGenericStore**
 
+> **Deprecated** Use `register` instead.
+
 Registers a generic store.
 
 _Parameters_
@@ -530,6 +537,8 @@ _Parameters_
 
 <a name="registerStore" href="#registerStore">#</a> **registerStore**
 
+> **Deprecated** Use `register` instead.
+
 Registers a standard `@wordpress/data` store.
 
 _Parameters_
@@ -584,7 +593,7 @@ example.
 
 <a name="select" href="#select">#</a> **select**
 
-Given the name of a registered store, returns an object of the store's selectors.
+Given the name or definition of a registered store, returns an object of the store's selectors.
 The selector functions are been pre-bound to pass the current state automatically.
 As a consumer, you need only pass arguments of the selector, if applicable.
 
@@ -598,7 +607,7 @@ select( 'my-shop' ).getPrice( 'hammer' );
 
 _Parameters_
 
--   _name_ `string`: Store name.
+-   _storeNameOrDefinition_ `(string|WPDataStore)`: Unique namespace identifier for the store or the store definition.
 
 _Returns_
 

packages/data/src/index.js

@@ -45,7 +45,7 @@ export { plugins };
  *
  * @example
  * ```js
- * import { combineReducers, registerStore } from '@wordpress/data';
+ * import { combineReducers, createReduxStore, register } from '@wordpress/data';
  *
  * const prices = ( state = {}, action ) => {
  * 	return action.type === 'SET_PRICE' ?
@@ -62,12 +62,13 @@ export { plugins };
  * 		state;
  * };
  *
- * registerStore( 'my-shop', {
+ * const store = createReduxStore( 'my-shop', {
  * 	reducer: combineReducers( {
  * 		prices,
  * 		discountPercent,
  * 	} ),
  * } );
+ * register( store );
  * ```
  *
  * @return {Function}       A reducer that invokes every reducer inside the reducers
@@ -76,11 +77,12 @@ export { plugins };
 export { combineReducers };
 
 /**
- * Given the name of a registered store, returns an object of the store's selectors.
+ * Given the name or definition of a registered store, returns an object of the store's selectors.
  * The selector functions are been pre-bound to pass the current state automatically.
  * As a consumer, you need only pass arguments of the selector, if applicable.
  *
- * @param {string} name Store name.
+ * @param {string|WPDataStore} storeNameOrDefinition Unique namespace identifier for the store
+ *                                                   or the store definition.
  *
  * @example
  * ```js
@@ -99,7 +101,8 @@ export const select = defaultRegistry.select;
  * and modified so that they return promises that resolve to their eventual values,
  * after any resolvers have ran.
  *
- * @param {string} name Store name.
+ * @param {string|WPDataStore} storeNameOrDefinition Unique namespace identifier for the store
+ *                                                   or the store definition.
  *
  * @example
  * ```js
@@ -120,7 +123,8 @@ export const __experimentalResolveSelect =
  * Note: Action creators returned by the dispatch will return a promise when
  * they are called.
  *
- * @param {string} name Store name.
+ * @param {string|WPDataStore} storeNameOrDefinition Unique namespace identifier for the store
+ *                                                   or the store definition.
  *
  * @example
  * ```js
@@ -157,6 +161,8 @@ export const subscribe = defaultRegistry.subscribe;
 /**
  * Registers a generic store.
  *
+ * @deprecated Use `register` instead.
+ *
  * @param {string} key    Store registry key.
  * @param {Object} config Configuration (getSelectors, getActions, subscribe).
  */
@@ -165,6 +171,8 @@ export const registerGenericStore = defaultRegistry.registerGenericStore;
 /**
  * Registers a standard `@wordpress/data` store.
  *
+ * @deprecated Use `register` instead.
+ *
  * @param {string} storeName Unique namespace identifier for the store.
  * @param {Object} options   Store description (reducer, actions, selectors, resolvers).
  *
@@ -194,7 +202,7 @@ export const use = defaultRegistry.use;
  *         getValue: ( state ) => state,
  *     },
  * } );
- * registry.register( store );
+ * register( store );
  * ```
  *
  * @param {WPDataStore} store Store definition.

packages/data/src/registry.js

@@ -149,13 +149,13 @@ export function createRegistry( storeConfigs = {}, parent = null ) {
 	 * and modified so that they return promises that resolve to their eventual values,
 	 * after any resolvers have ran.
 	 *
-	 * @param {string|Object} storeName Unique namespace identifier for the store
-	 *                                  or the store definition.
+	 * @param {string|WPDataStore} storeNameOrDefinition Unique namespace identifier for the store
+	 *                                                   or the store definition.
 	 *
 	 * @return {Object} Each key of the object matches the name of a selector.
 	 */
-	function __experimentalResolveSelect( storeName ) {
-		return getResolveSelectors( select( storeName ) );
+	function __experimentalResolveSelect( storeNameOrDefinition ) {
+		return getResolveSelectors( select( storeNameOrDefinition ) );
 	}
 
 	/**