Add wp-data-sync package

[manzoorwanijk]

Often, when working on settings page UIs, we need to fetch the settings from and sync back to the server. This results in a lot of boilerplate code to define actions, action type constants, thunks, selectors, resolvers and reducers, which are often repeated for different sections.

This new package abstracts that boilerplate away and adds a way to simply define what data you need and where to get from, and then it gives you the required selectors, actions, resolvers, and a reducer, which you can pass to @wordpress/data store.

Proposed changes:

• Create a package named wp-data-sync
• This package exports a function named createWpDataSync which lets you avoid creating all the boilerplate code mentioned above.

Usage

Step 1: Create the data sync

// store.ts
import { createWpDataSync } from '@automattic/wp-data-sync';
import { combineReducers, createReduxStore, register } from '@wordpress/data';

// Define the shape of the settings, if you use TypeScript.
type PluginSettings = {
	fieldOne: string;
	fieldTwo: number;
	fieldThree?: boolean;
};

// Define the initial state of your data
const initialState: PluginSettings = {
	fieldOne: 'some value',
	fieldTwo: 5,
};

// Create the data sync
const myPluginSettings = createWpDataSync( 'myPluginSettings', {
	endpoint: '/wp/v2/settings',
	getSliceFromState( state: SocialStoreState ) {
		return state.settings.myPluginSettings;
	},
	extractFetchResponse: response => response.my_plugin_settings, // Optional
	prepareUpdateRequest: data => ( { my_plugin_settings: data } ), // Optional
} );

Step 2: Pass the data sync to the store

// You can use only the parts you need.
// For example, if you only need the selectors, you can pass only the selectors.
export const store = createReduxStore( 'some-store-id', {
	reducer: combineReducers( {
		myPluginSettings: myPluginSettings.reducer,
		// Other reducers
	} ),
	actions: {
		...myPluginSettings.actions,
		// Other actions
	},
	selectors: {
		...myPluginSettings.selectors,
		// Other selectors
	},
	resolvers: {
		...myPluginSettings.resolvers,
		// Other resolvers
	},
	initialState: {
		settings: {
			myPluginSettings: initialState,
		},
	},
} );

register( store );

Step 3: Use it in your components

import { useDispatch, useSelect } from '@wordpress/data';
import { useCallback } from 'react';
import { store } from './store';

export const TestComponent = () => {
	const { settings, status, lastError } = useSelect( select => {
		return {
			settings: select( store ).getMyPluginSettings(),
			status: select( store ).getMyPluginSettingsStatus(),
			lastError: select( store ).getMyPluginSettingsLastError(),
		};
	}, [] );

	const { updateMyPluginSettings } = useDispatch( store );

	const onSubmit = useCallback( async () => {
		await updateMyPluginSettings( {
			fieldOne: 'some value from the UI',
			fieldTwo: 10,
			fieldThree: false,
		} );
	}, [ updateMyPluginSettings ] );

	return (
		<form onSubmit={ onSubmit }>
			{ status === 'fetching' ? (
				<p>Loading...</p>
			) : (
				<div>
					<input
						name="fieldOne"
						value={ settings.fieldOne }
						// other props
					/>
				</div>
			) }
			<br />
			<pre>{ JSON.stringify( { settings, status, lastError }, null, 2 ) }</pre>
		</form>
	);
};

Type safety

All the selectors and actions returned are type safe and allow you to auto-complete suggestions

• Action auto completion
  
• Selector auto completion
  
• Action data auto completion
  
• Status auto-completion
  

Other information:

• Have you written new tests for your changes, if applicable?
• Have you checked the E2E test CI results, and verified that your changes do not break them?
• Have you tested your changes on WordPress.com, if applicable (if so, you'll see a generated comment below with a script to run)?

Jetpack product discussion

Does this pull request change what data or activity we track or use?

Testing instructions:

• Just confirm that the code looks good and CI is happy
• You can also test Social: Migrate Social Image Generator settings initial state #39904 which uses these changes

[github-actions]

Thank you for your PR!

When contributing to Jetpack, we have a few suggestions that can help us test and review your patch:

• ✅ Include a description of your PR changes.
  
• ✅ Add a "[Status]" label (In Progress, Needs Team Review, ...).
  
• ✅ Add testing instructions.
  
• ✅ Specify whether this PR includes any changes to data or privacy.
  
• ✅ Add changelog entries to affected projects
  

This comment will be updated as you work on your PR and make changes. If you think that some of those checks are not needed for your PR, please explain why you think so. Thanks for cooperation 🤖

---

The e2e test report can be found here. Please note that it can take a few minutes after the e2e tests checks are complete for the report to be available.

---

Follow this PR Review Process:

1. Ensure all required checks appearing at the bottom of this PR are passing.
2. Choose a review path based on your changes:
   • A. Team Review: add the "[Status] Needs Team Review" label
     • For most changes, including minor cross-team impacts.
     • Example: Updating a team-specific component or a small change to a shared library.
   • B. Crew Review: add the "[Status] Needs Review" label
     • For significant changes to core functionality.
     • Example: Major updates to a shared library or complex features.
   • C. Both: Start with Team, then request Crew
     • For complex changes or when you need extra confidence.
     • Example: Refactor affecting multiple systems.
3. Get at least one approval before merging.

Still unsure? Reach out in #jetpack-developers for guidance!

[github-actions]

Are you an Automattician? Please test your changes on all WordPress.com environments to help mitigate accidental explosions.

• To test on WoA, go to the Plugins menu on a WordPress.com Simple site. Click on the "Upload" button and follow the upgrade flow to be able to upload, install, and activate the Jetpack Beta plugin. Once the plugin is active, go to Jetpack > Jetpack Beta, select your plugin, and enable the add/wp-data-sync-package branch.

  • For jetpack-mu-wpcom changes, also add define( 'JETPACK_MU_WPCOM_LOAD_VIA_BETA_PLUGIN', true ); to your wp-config.php file.

• To test on Simple, run the following command on your sandbox:

  bin/jetpack-downloader test jetpack add/wp-data-sync-package
  

  bin/jetpack-downloader test jetpack-mu-wpcom-plugin add/wp-data-sync-package
  

Interested in more tips and information?

• In your local development environment, use the jetpack rsync command to sync your changes to a WoA dev blog.
• Read more about our development workflow here: PCYsg-eg0-p2
• Figure out when your changes will be shipped to customers here: PCYsg-eg5-p2

[pablinos]

This looks useful. I wonder if we are, to some extent, reimplementing @wordpress/core-data. I've noticed that doesn't expose some of the useful methods used for generating the selectors, so maybe it's not useful in this instance, but the generic getEntityRecord methods, which already have aliases for Settings might be useful?

I'd also want to make sure that this is generally useful for Jetpack and the other plugins in the repository. I think we should discuss it with other teams.

[manzoorwanijk]

This looks useful. I wonder if we are, to some extent, reimplementing @wordpress/core-data. I've noticed that doesn't expose some of the useful methods used for generating the selectors, so maybe it's not useful in this instance, but the generic getEntityRecord methods, which already have aliases for Settings might be useful?

I did explore that before coming up with this solution. The entity related selectors you are referring to, are mostly related to the core entities like post, user, taxonomy, comment etc. and then there is a special case for settings and all of those entities are hard-coded here. You cannot add your own entities.

I'd also want to make sure that this is generally useful for Jetpack and the other plugins in the repository. I think we should discuss it with other teams.

Yeah, that is the goal. Initially I thought of using React Query but I didn't want to have an additional dependency when we can achieve our goal using what we already use, i.e. the @wordpress/data stores.

[tyxla]

At a first glance, I'm not convinced we need yet another abstraction on top of @wordpress/data and potentially @wordpress/core-data. We should be able to achieve what this package provides by extending core APIs. Also, I think if we really need one, the ideal place for it would be in the WordPress core, and not here. After all, I don't really see anything Jetpack-specific here.

I did explore that before coming up with this solution. The entity related selectors you are referring to, are mostly related to the core entities like post, user, taxonomy, comment etc. and then there is a special case for settings and all of those entities are hard-coded here. You cannot add your own entities.

Unless I'm missing something, this isn't true. You can actually use:

registry.dispatch( coreStore ).addEntities()

to register custom entities, and @wordpress/core-data will pick them up, where you'll be able to use all the regular features for retrieving / saving data, without the need to add a bunch of boilerplate. There are some examples in these articles:

• https://wordpress.stackexchange.com/questions/352500/get-post-from-custom-rest-endpoint-in-gutenberg
• https://wordpress.stackexchange.com/questions/381036/how-to-properly-add-custom-entities-in-gutenberg

This should cover the needs for handling a custom endpoint.

And if you need to expose a custom setting through the existing /settings endpoint, you should be able to register that custom setting and enable it in REST, as demonstrated here. If anything isn't possible, we should consider extending the core APIs to make it possible.

On type safety / IDE autocompletion - it's possible that the dev experience might actually be suboptimal if you use the core features (since @wordpress/core-data is not fully typed). If that's the case, I'd encourage you to consider contributing to core and improving the types - this would be of great benefit to everyone using @wordpress/data stores and @wordpress/core-data.

[jsnajdr]

This is a nice library, however, I think the core data entities already provide the same functionality. You register a new entity, and the library auto-generates all the actions, resolvers and selectors.

Namely the /wp/v2/settings are already exposed there as the root/site entity.

[jsnajdr]

Well-written endpoints like wp/v2/settings return the modified settings in the POST response. You don't need to fetchAfterUpdate, because the data are already in the POST response. You just need to use them instead of ignoring them (i.e., not using the await apiFetch() return value.

This should be the default behavior. fetchAfterUpdate might make sense only for endpoints that are not written that well.

Also, for a really correct behavior you'll need two setter actions:

• setSomething is useful for merging a slice of the data into the current data
• replaceSomething replaces the data completely. It should be used by fetchSomething and also for storing the response in updateSomething.

If you have only setSomething then stale data might be stored in the state, namely the fields that were removed on the server.

[manzoorwanijk]

Thank you @pablinos @tyxla @jsnajdr for your inputs.

I have updated the dependent PR (#39904) to use @wordpress/core-data. There are a few things to deal or live with when using that approach:

1. There is no way to find out whether a particular settings field is being saved. You can only know about the settings in general.
2. DX is not great because of types being messy

[tyxla]

There is no way to find out whether a particular settings field is being saved. You can only know about the settings in general.

What about isResolving (if necessary, in conjunction with manual startResolution / finishResolution calls)? Also isSavingEntityRecord might be worth taking a look at.

DX is not great because of types being messy

Yes, as mentioned in my earlier review, this part can use some love. You might consider contributing some types, that would be awesome 😉

[manzoorwanijk]

What about isResolving (if necessary, in conjunction with manual startResolution / finishResolution calls)?

Again, too much boilerplate and in that case you need to keep track of isUpdating flag and store the value somewhere.

Also isSavingEntityRecord might be worth taking a look at.

That is what I used in that PR.

[tyxla]

Again, too much boilerplate and in that case you need to keep track of isUpdating flag and store the value somewhere.

This is good feedback for the core project - would you like to try improving the core experience so there's some middleware, flag, or API to use that allows tracking the status of particular thunk-kind actions without the boilerplate?

[manzoorwanijk]

This is good feedback for the core project - would you like to try improving the core experience so there's some middleware, flag, or API to use that allows tracking the status of particular thunk-kind actions without the boilerplate?

Yeah, that's a good idea. Will see what I can do. Thanks