Data Module: Expose state using selectors

[youknowriad]

This is a POC, alternative to #4083 closes #2473

So the idea here is that a module that wants to expose a specific part of its state registers a set of selectors a consumer can access using the query Higher Order Component and the select helper passed as an argument. (This Higher Order Component could be written differently by wrapping each selector, It doesn't change the implementation a lot, I thought this want avoids creating these "unnecessary functions")

And a query Higher Order Component is also exposed to fetch data like so:

import { query } from '@wordpress/data';
const MyComponentWithData = query( ( select ) => {
	return {
		title: select( 'core/editor', 'getEditedPostTitle' ),
	};
} )( props =>
  <div>{ props.title || 'no title' }</div>
);

[youknowriad]

cc @atimmer

[gziolo]

We still need to pass ownProps here.

[gziolo]

I was thinking about having along those lines:

import { query } from '@wordpress/data';

const MyComponent = props => <div>{ props.title || 'no title' } { props.description || '' }</div>;

const MyComponentWithEditorData= query( 'core/editor', ( select, ownProps ) => {
	return {
		title: select( 'getEditedPostTitle', ownProps.id ),
	};
} )( MyComponent );

const MyComponentWithEditorAndPluginData= query( 'plugin/details', ( select, ownProps ) => {
	return {
		description: select( 'getEditedPostDescription', ownProps.id ),
	};
} )( MyComponent );

This means more typing, but it allows to take advantage of the fact that listeners are scoped to namespaces with the recently merged PR #4058. I don't know the underling implementation of connect but I assume it is triggered every time global state changes, which wouldn't take advantage of the recently introduces optimizations. This is something that needs to be investigated. I'm skeptical that this boilerplate is better than what @youknowriad originally proposed, but I wanted to make sure we take the aforementioned point into account :)

[gziolo]

Overall, I like what's proposed in this PR and would be happy to use it for plugin development. I like it more over GraphQL proposal only because I know this pattern well. Please keep in mind that I have zero GraphQL experience so I'm biased 😄

[gziolo]

I assume we could use the following:

import * as selectors from './selectors';

registerSelectors( MODULE_KEY, selectors );

We would have to try it.

[youknowriad]

I don't think we want to expose all selectors. Some are internal only.

[youknowriad]

@gziolo yep, your API proposal doesn’t allow to get data from several modules/plugins at the same time, you can still query twice. I don’t know if this would be common but that’s why I avoided it at first

[mcsf]

Overall, I like what's proposed in this PR and would be happy to use it for plugin development. I like it more over GraphQL proposal only because I know this pattern well. Please keep in mind that I have zero GraphQL experience so I'm biased 😄

I share @gziolo's bias (not enough experience in GraphQL, and a perception that it's not a necessary pattern if something like this here is possible). :) I like what's here.

I also second his suggestion to split the use of query by reducer. Using our common patterns in Gutenberg, that would look like:

// or: "selectEditorData"
const applyConnectEditor = query( 'core/editor', … );

const applyConnectPlugin = query( … );

export default flowRight( [
  applyConnectEditor,
  applyConnectPlugin,
] )( MyComponent );

Aside from the mere fact that it requires an author to think of the multitude of data sources (a benefit ipso facto), it allows better introspection than the more dynamic query( select => ( { foos: select( 'core/editor', 'getFoos' ) } ) ). Validators could look at the query source, warnings could be issued, dependency graphs could be inferred.

[youknowriad]

@mcsf @gziolo What about discoverability? How do you solve it with this approach, a "consumer" would have to know the selectors exposed from all the modules to be able to use them while he can just navigate GraphiQL to discover the available data? Also, what about the external API:

export default query( `{ 
 editor{ post { title } }
 yoast { keywords }
}`)( MyComponent )

const applyConnectEditor = query( 'core/editor', ( select ) => ( {
  title: select( 'getEditedPostTitle' )
} ) );
const applyConnectYoast = query( 'yoast', ( select ) => ( {
  keywords: select( 'getKeywords' )
} ) );

export default flowRight( [
  applyConnectEditor,
  applyConnectYoast,
] )( MyComponent );

Don't you think the external API is cleaner in GraphQL and corresponds exactly to the "data" requirements of the component?

[youknowriad]

Also, I think the same way "React" just by its name can create barriers to developers unware of its API (just simple functions), hearing "GraphQL" can create some barriers. What if we try to forget it as it's an implementation detail and think of this:

export default query( `{ 
 editor{ post { title } }
 yoast { keywords }
}`)( MyComponent )

as just an API to declare data needs.

[mcsf]

Adding to this discussion what we saw on Slack a couple of weeks ago, which is the idea that ES2015 Proxy could provide a more polished experience of the same approach:

const selectEditorData = query( 'core/editor', ( select ) => ( {
  title: select.getEditedPostTitle(),
  isPanelOpen: select.isEditorSidebarPanelOpen( 'post-taxonomies' ),
} ) );

Here's a jsfiddle that would implement this. Now, Proxy isn't ready for primetime, and we could either polyfill it, or address this some other way if we deem this experience nice enough.

---

What about discoverability? How do you solve it with this approach, a "consumer" would have to know the selectors exposed from all the modules to be able to use them while he can just navigate GraphiQL to discover the available data? Also, what about the external API:

That GrQL example is pretty nice :D, but — however terse and clean it looks — there would still be an issue of knowing what the possible entities, fields and hierarchies are, no? Selectors IMO have the advantage of being more tangible, i.e. more recognizable (for most consumers) artefacts in code to look for. For both approaches there are means to automatically gather query/selector documentation (cf. Calypso devdocs); the main challenge is making all that visible to authors.

[mcsf]

Don't you think the external API is cleaner in GraphQL and corresponds exactly to the "data" requirements of the component?

Yes, hard to refute. :)

[mcsf]

Don't you think the external API is cleaner in GraphQL and corresponds exactly to the "data" requirements of the component?

The downside is the experience for authors seeking to making their data sources available for consumption. Writing a selector is conceptually simpler than writing a resolver. In this sense, it's hard for me to consider GraphQL a nicer experience until we work on providing better defaults and good helpers for the most common use cases.

[youknowriad]

here would still be an issue of knowing what the possible entities, fields and hierarchies are, no?

The answer is no, try http://graphql.org/swapi-graphql/ click the "Docs" above and see how to can drill down/up in the data tree

For both approaches there are means to automatically gather query/selector documentation (cf. Calypso devdocs); the main challenge is making all that visible to authors.

GraphQL is auto-documented, you can use GraphiQL without any additional effort. (http://graphql.org/swapi-graphql this is GraphiQL)

[gziolo]

Out of curiosity, how can you pass own props to GraphQL? Like when you want for instance to get a block by uid or something similar. Do you need to express it as part of the query?

[youknowriad]

The downside is the experience for authors seeking to making their data sources available for consumption. Writing a selector is conceptually simpler than writing a resolver.

My experience with GraphQL is not very big and I think once you try it you quickly grasp the "resolvers", just a tree of functions. But it's true that it's still more complex than just registering the selectors. The question may be whether we want to optimize for consumption or for production?

[youknowriad]

Out of curiosity, how can you pass own props to GraphQL? Like when you want for instance to get a block by uid or something similar. Do you need to express it as part of the query?

yes:

{ block( :id ) }

and provide variables in the second parameter of the query HoC. I encourage you to try some queries in the GraphiQL shared above. you can navigate the docs to see what query you could run.

[mcsf]

click the "Docs" above and see how to can drill down/up in the data tree

I stand corrected. :)

My experience with GraphQL is not very big and I think once you try it you quickly grasp the "resolvers", just a tree of functions. But it's true that it's still more complex than just registering the selectors. The question maybe whether we want to optimize for consumption or for production?

Yes, @jorgefilipecosta and I were just discussing this. It sounds conceivable to provide some helpers to build schemas/resolvers from more selector-like functions, thinking of plugins with small state footprints for whom we can minimize the investment.

[jorgefilipecosta]

It looks like the GraphQL is very good for consumption. But it presents an overhead for exposing a simple selector. E.g: if I want to expose a simple counter, as @mcsf referred.
Maybe, we can have the best of both worlds, If we can present something that allows a simple way to expose basic selectors and handles the schema/resolver creation something along the lines of:

registerSelector(
	‘core/editor.post’,
	getEditedPostTitle,
 	{
		title: ‘String’
	},
       undefined //query parameters
);

Offcourse this would be limiting what GraphQL offers us and it would not be mandatory to use this, and maybe we would not use it for our core needs. But it would provide an answer for people needing to expose a very simple selector.

[atimmer]

First off: I have never used GraphQL.

My first impressions of GraphQL, I find edges -> node a really weird syntax:

allFilms {
  edges {
    node {
      id
    }
  }
}

Can we avoid that in our local implementation? Or is this something 'native' to the language?

export default query( `{ 
 editor{ post { title } }
 yoast { keywords }
}`)( MyComponent )

I think this is really amazing. It is an elegant way of querying cross component/plugin.

I also like the fact that both these APIs are inherently asynchronous. The consumer of the data doesn't have to know if the data is already available, or if it needs to be requested from the server. This could give way to really transparent lazy loading in the future.

These are my first impressions. I will look further into this.

[youknowriad]

I find edges -> node a really weird syntax:

Not sure I understand what you think is weird here? is it the fact than node is embeded in edges? I guess this is just a choice, you can flatten everything if you think it's better.

[atimmer]

I understand it better after reading this article: https://dev-blog.apollodata.com/explaining-graphql-connections-c48b7c3d6976. I think we should really document this stuff well because it isn't obvious at first.

[jaswrks]

Just adding a 👍 for selectors. I like @youknowriad's approach to registering reducers, and building on that I like @mcsf 's proxy idea best for selectors — or just reorganizing so the below is possible.

And I see it being more convenient to pass the registered reducer to select().

const selectData = query( ( select, ownProps ) => ( {
  isMobile: select( 'core/browser' ).isMobile(),
  title: select( 'core/editor' ).getEditedPostTitle(),
  isPanelOpen: select( 'core/editor' ).isEditorSidebarPanelOpen( 'post-taxonomies' ),
} ) );

---

Gutenberg has been my first real-world experience with React, but I used GraphQL on a small project once. I love it as a server-side REST alternative (truly awesome, and totally worth it to define a schema for the models that it handles). Using it to define schemas in client-side code might get tedious though. I have limited experience, just seems like extra work to me.

Maybe discoverability comes from the selectors themselves; i.e., docBlocks, articles written about them, examples of their use, and describing the object models they return.

As someone who recently jumped into Gutenberg completely new, I think it would be awesome if, in the future, reducers and selectors were split up and placed into subdirectories. Such that each reducer (or set of reducers) is accompanied by its selectors. It looks like that's the way things are headed already — making it easier to import them in sets, to be wrapped by select().

[moorscode]

Coming from a usability point of view I like to share my thoughts on using the different samples as a programmer. Note that I have been programming in React this year, but don't do it on a weekly basis at the moment, feeling this might provide a bit of distance in looking at the code.

Rename the query function in @wordpress/data

The way the code creates a component is to use the output of a query function.
This seem like something that could be made easier to understand by renaming the function to be used. Especially because query is also used in other aspects of the functionality.

As I understand it, what the function does is to inject the props into a new component and returning that component. The "querying" part is done in GraphQL or in functions configured somewhere else.

Breakdown of context/knowledge needed per example

Taking the GraphQL example

import gql from 'graphql-tag';
import { query } from '@wordpress/data';

const MY_QUERY = gql`query { editor { post { title } } }`;

const MyComponentWithData = query( MY_QUERY )( props => 
  <div>{ get( props.data, 'editor.post.title', 'no title' ) }</div>
);

1. + Knowing how to use the backtick notation is not really important, the syntax is pretty self-explanatory with the query followed by the arguments.
2. - Having to import from graphql-tag
3. - query is used twice, but these are not the same thing.
4. - Having to define the implementation of a query in a separate place disconnects from the retrieval of data, reducing context and increasing effort to understand what is happening.

Taking the selectors example

import { query } from '@wordpress/data';

const MyComponentWithData = query( ( select ) => {
	return {
		title: select( 'core/editor', 'getEditedPostTitle' ),
	};
} )( props =>
  <div>{ props.title || 'no title' }</div>
);

1. + Defining the actual implementation of a data-point in context with building the component
2. - I see is a lot of {}()=>; characters, this is scary because it feels that it is very specific what order things should be.
3. - This also makes reading it very hard, because I don't instantly see what is passed to what or used as an argument. (Keep in mind that I don't code ES6 on a daily basis).

Syntax wise it's a big jungle of specific order and character use. For experienced developers this might be second nature, but for all other people it takes a lot of effort to make sense of it all.

4. - Having to know that there is a core/editor instead of a post where the data has to come from feels like the different way around.
5. - Having to know the getEditedPostTitle function and using it in a string seems very specific and contextually hard.
6. - Why is it called edited post title? Having to use this specific name will stand in the way of future-compatibility.

Having pointed these things out, I think a lot of these could be resolved by reorganizing the code, so adding up the plusses and minuses does not give my total opinion.

Data-structure/namespace

In the GraphQL example the editor is used as top-level selector.
In the selectors example there is a core/editor namespace.

I understand these are just concepts, but I wanted to note that these are not consistent.

Globally defined core data retrieval

Do I understand correctly that the GraphQL implementation allows to define the default post data retrieval functions can be implemented in core itself?

It seems that only the plugin specific data exposing would have to implement specific retrieval separately to be used.

I think it would be nice to have the data "magically" provided for core data, if the data structure has been documented in depth somewhere.
This will allow us a lot of freedom to change the implementation under the hood in the future.

[youknowriad]

Thanks for these thoughts 👍, like you said, most of the - could be "fixed".

I think it would be nice to have the data "magically" provided for core data, if the data structure has been documented in depth somewhere.
This will allow us a lot of freedom to change the implementation under the hood in the future.

Yes, I thought about this, building "data-only" modules in Core, for example a @wordpress/media module don't do nothing aside registering a media reducer and exposing data. I think this is achievable regardless of the option we choose.

In the GraphQL implementation: This means triggering actions in resolvers if the data is not available yet.
In the Selectors implementation: This means these selectors become something else: selectors + triggering actions. It would be quite similar to the GraphQL implementation but we wouldn't register regular Redux selectors anymore.

Edit

• It may also make sense to define these "Core Data" selectors/resolvers in the data module itself.

[herregroen]

While my general preference goes to the GraphQL proposal, I would like to suggest one improvement to this PR.

Why not use plain old javascript for these selectors? Replacing query with something like the following ( read as pseudo-code, may need some changes :P ):

export const query = ( mapPropsToSelectors ) => ( WrappedComponent ) => {
	return connect( ( state ) => {
		const data = {};

		forOwn( selectors, ( functions, key ) => {
			const wrappedObject = {};

			// Wrap each selector to automatically pass the required state as first argument.
			forOwn( functions, ( selector, selectorKey ) => {
				wrappedObject[ selectorKey ] = ( ...args ) => selector( getState()[ key ], ...args );
			} );

			// Expand the keys by splitting on `/` and `.`.
			const keys = key.split( /\.\// );
			// Assign our wrapped function to a nested object with the correct keys.
			// `core/editor` => { getEditorPostTitle: fn }
			// will become { core: { editor: { getEditorPostTitle: fn } } }
			const obj = keys.reduceRight( ( previousObject, currentKey ) => {
				const currentObject = {};
				currentObject[ currentKey ] = previousObject;
				return currentObject;
			}, wrappedObject );
			// Merge our nested object with the data object.
			merge( data, obj );
		} );

		// Return the data object that can be called with plain javascript.
		return mapPropsToSelectors( data );
	} )( WrappedComponent );
}

Would enable this to be used like this in a wrapped component, which I feel is a much more natural way of calling functions that's more accessible to inexperienced developers. As an added benefit this would allow calling console.log on the data object to easily discover all available data.

import { query } from '@wordpress/data';
const MyComponentWithData = query( ( data ) => {
	return {
		title: data.core.editor.getEditedPostTitle(),
	};
} )( props =>
  <div>{ props.title || 'no title' }</div>
);

[youknowriad]

@herregroen Thanks for the proposal, while I think it's probably good to avoid using a "string" to call the selectors, I don't think we should try to map the namespace to an attribute. I'd personally prefer something closer to the API proposed here #4105 (comment)

maybe mix it with the data arg proposal data( 'core/editor' ).getEditedPostTitle().

[gziolo]

Should we put reducerKey here to align with the function definition?

[gziolo]

In docs we have selectors provided as the 2nd param, maybe we should use the same name here, what do you think?

[gziolo]

Okey, Eslint shadowing again. Maybe newSelectors then :)

[gziolo]

I would suggest making it more focused on the query HOC by moving ( { title } ) => <div>{ title }</div> to its own variable like this:

const Component = ( { title } ) => <div>{ title }</div>;

wp.data.query( select => {
 	return {
 		title: select( 'myPlugin', 'getTitle' ),
 	};
 } )( Component  );

[gziolo]

It looks really solid. I'm more than happy to move forward with it.

About the selectors discovery, I don't think making them accessible like this wp.data.selectors[ 'core/editor' ].getTitle() is a good option because we can't use Proxies yet :( and if we do want something to discover selectors, I think it should a more targed API wp.data.getSelectors( 'core/editor' )

We could discuss the different ways of exposing selectors for long, but we need to start using it first to see how it plays with the real code. I think the current proposal has a very straightforward implementation and a very performant one because it create only one function whenever the state changes.

[gziolo]

I added a change to the test file which makes sure that ownProps is properly consumed in query HOC. I think it is ready to go. I recommend having more eyes on this PR before proceeding including @atimmer or @omarreiss :)

[atimmer]

This looks good, let's get it in and iterate further.

[atimmer]

A typo in reduerKey.

[jaswrks]

Woohoo! Nice work. Love this API ❤️

[aduth]

Would proxying be the only approach to invoke the selectors as a function, if we could assume that connect mapping functions are only called after a selector has already been registered (i.e. the registration could ensure these functions are included in an object passed to the mapping function)?

Generally this looks quite fine to me. I see pros and cons to this vs. the subtly different variations (per-reducer-key query).

One other variation I pondered which doesn't seem to have been proposed yet:

// Simple case: Select from single reducer key
query( 'core/foo', ( select ) => ( {
	/* ... */
} ) )

// Select from multiple reducer keys
query( {
	'core/foo': ( select ) => ( {
		/* ... */
	} ),
	'core/bar': ( select ) => ( {
		/* ... */
	} ),
} );

[aduth]

Typo: "seclectors" -> "selectors"

[gziolo]

One other variation I pondered which doesn't seem to have been proposed yet:

// Simple case: Select from single reducer key
query( 'core/foo', ( select ) => ( {
	/* ... */
} ) )

// Select from multiple reducer keys
query( {
	'core/foo': ( select ) => ( {
		/* ... */
	} ),
	'core/bar': ( select ) => ( {
		/* ... */
	} ),
} );

I proposed to have the grouping, you mentioned, around the key reducer in one of my previous comments, and this makes it usable :)

I also figured out it is also possible to do the following with what we have coded:

query( ( select ) => {
	const fooSelect = select.bind( null,  'core/foo' );
	const barSelect = select.bind( null,  'core/bar' );
	return {
		foo: fooSelect( 'getFoo' ),
		bar: barSelect( 'getBar' ),
	};
} );

[youknowriad]

All these alternatives are valid. I personally don't have a strong preference for one over another. I'll just move forward. Better to try in real life and iterate.

[youknowriad]

Run the tests locally, merging.