@wordpress/preferences-persistence 1.0.0

package/src/create/test/index.js

@@ -0,0 +1,178 @@
+/**
+ * WordPress dependencies
+ */
+import apiFetch from '@wordpress/api-fetch';
+
+/**
+ * Internal dependencies
+ */
+import create from '..';
+
+jest.mock( '@wordpress/api-fetch' );
+
+describe( 'create', () => {
+	afterEach( () => {
+		apiFetch.mockReset();
+	} );
+
+	describe( 'set', () => {
+		it( 'stores backup restoration data in localStorage', () => {
+			apiFetch.mockResolvedValueOnce();
+			const spy = jest.spyOn( global.Storage.prototype, 'setItem' );
+
+			const localStorageRestoreKey = 'test';
+			const { set } = create( { localStorageRestoreKey } );
+
+			const data = { test: 1 };
+			set( data );
+
+			expect( spy ).toHaveBeenCalledWith(
+				localStorageRestoreKey,
+				expect.any( String )
+			);
+
+			// The second param of the call to `setItem` has been JSON.stringified.
+			// Parse it to check it contains the data.
+			const setItemDataParm = spy.mock.calls[ 0 ][ 1 ];
+			expect( JSON.parse( setItemDataParm ) ).toEqual(
+				expect.objectContaining( data )
+			);
+		} );
+
+		it( 'sends data to the `users/me` endpoint', () => {
+			apiFetch.mockResolvedValueOnce();
+
+			const { set } = create();
+
+			const data = { test: 1 };
+			set( data );
+
+			expect( apiFetch ).toHaveBeenCalledWith( {
+				path: '/wp/v2/users/me',
+				method: 'PUT',
+				keepalive: true,
+				data: {
+					meta: {
+						persisted_preferences: expect.objectContaining( data ),
+					},
+				},
+			} );
+		} );
+	} );
+
+	describe( 'get', () => {
+		it( 'avoids using the REST API or local storage when data is preloaded', async () => {
+			const getItemSpy = jest.spyOn(
+				global.Storage.prototype,
+				'getItem'
+			);
+
+			const preloadedData = { preloaded: true };
+			const { get } = create( { preloadedData } );
+			expect( await get() ).toBe( preloadedData );
+			expect( getItemSpy ).not.toHaveBeenCalled();
+			expect( apiFetch ).not.toHaveBeenCalled();
+		} );
+
+		it( 'returns from a local cache once `set` has been called', async () => {
+			const getItemSpy = jest.spyOn(
+				global.Storage.prototype,
+				'getItem'
+			);
+			apiFetch.mockResolvedValueOnce();
+
+			const data = { cached: true };
+			const { get, set } = create();
+
+			// apiFetch was called as a result of calling `set`.
+			set( data );
+			expect( apiFetch ).toHaveBeenCalled();
+			apiFetch.mockClear();
+
+			// Neither localStorage.getItem or apiFetch are called as a result
+			// of the call to `get`. A local cache is used.
+			expect( await get() ).toEqual( expect.objectContaining( data ) );
+			expect( getItemSpy ).not.toHaveBeenCalled();
+			expect( apiFetch ).not.toHaveBeenCalled();
+		} );
+
+		it( 'returns data from the users/me endpoint if there is no data in localStorage', async () => {
+			const data = {
+				__timestamp: 0,
+				test: 2,
+			};
+			apiFetch.mockResolvedValueOnce( {
+				meta: { persisted_preferences: data },
+			} );
+
+			jest.spyOn(
+				global.Storage.prototype,
+				'getItem'
+			).mockReturnValueOnce( 'null' );
+
+			const { get } = create();
+			expect( await get() ).toEqual( data );
+		} );
+
+		it( 'returns data from the REST API if it has a more recent modified date than localStorage', async () => {
+			const data = {
+				_modified: '2022-04-22T00:00:00.000Z',
+				test: 'api',
+			};
+			apiFetch.mockResolvedValueOnce( {
+				meta: { persisted_preferences: data },
+			} );
+
+			jest.spyOn(
+				global.Storage.prototype,
+				'getItem'
+			).mockReturnValueOnce(
+				JSON.stringify( {
+					_modified: '2022-04-21T00:00:00.000Z',
+					test: 'localStorage',
+				} )
+			);
+
+			const { get } = create();
+			expect( await get() ).toEqual( data );
+		} );
+
+		it( 'returns data from localStorage if it has a more recent modified date than data from the REST API', async () => {
+			apiFetch.mockResolvedValueOnce( {
+				meta: {
+					persisted_preferences: {
+						_modified: '2022-04-21T00:00:00.000Z',
+						test: 'api',
+					},
+				},
+			} );
+
+			const data = {
+				_modified: '2022-04-22T00:00:00.000Z',
+				test: 'localStorage',
+			};
+			jest.spyOn(
+				global.Storage.prototype,
+				'getItem'
+			).mockReturnValueOnce( JSON.stringify( data ) );
+
+			const { get } = create();
+			expect( await get() ).toEqual( data );
+		} );
+
+		it( 'returns an empty object if neither local storage or the REST API return any data', async () => {
+			apiFetch.mockResolvedValueOnce( {
+				meta: {
+					persisted_preferences: null,
+				},
+			} );
+			jest.spyOn(
+				global.Storage.prototype,
+				'getItem'
+			).mockReturnValueOnce( 'null' );
+
+			const { get } = create();
+			expect( await get() ).toEqual( {} );
+		} );
+	} );
+} );

package/src/index.js

@@ -0,0 +1,49 @@
+/**
+ * Internal dependencies
+ */
+import create from './create';
+import convertLegacyLocalStorageData from './migrations/legacy-local-storage-data';
+
+export { create };
+
+/**
+ * Creates the persistence layer with preloaded data.
+ *
+ * It prioritizes any data from the server, but falls back first to localStorage
+ * restore data, and then to any legacy data.
+ *
+ * This function is used internally by WordPress in an inline script, so
+ * prefixed with `__unstable`.
+ *
+ * @param {Object} serverData Preferences data preloaded from the server.
+ * @param {string} userId     The user id.
+ *
+ * @return {Object} The persistence layer initialized with the preloaded data.
+ */
+export function __unstableCreatePersistenceLayer( serverData, userId ) {
+	const localStorageRestoreKey = `WP_PREFERENCES_USER_${ userId }`;
+	const localData = JSON.parse(
+		window.localStorage.getItem( localStorageRestoreKey )
+	);
+
+	// Date parse returns NaN for invalid input. Coerce anything invalid
+	// into a conveniently comparable zero.
+	const serverModified =
+		Date.parse( serverData && serverData._modified ) || 0;
+	const localModified = Date.parse( localData && localData._modified ) || 0;
+
+	let preloadedData;
+	if ( serverData && serverModified >= localModified ) {
+		preloadedData = serverData;
+	} else if ( localData ) {
+		preloadedData = localData;
+	} else {
+		// Check if there is data in the legacy format from the old persistence system.
+		preloadedData = convertLegacyLocalStorageData( userId );
+	}
+
+	return create( {
+		preloadedData,
+		localStorageRestoreKey,
+	} );
+}

package/src/migrations/legacy-local-storage-data/README.md

@@ -0,0 +1,42 @@
+# Legacy local storage migrations
+
+This folder contains all the migration code for converting from the old `data` package persistence system.
+
+## History
+
+Previously, some packages could configure a store to persist particular parts of state. In this example, the post editor is configured to persist the state for its `preferences` reducer to local storage:
+```js
+registerStore(
+	'core/edit-post', {
+		selectors,
+		actions,
+		reducer,
+		persist: [ 'preferences' ],
+	},
+);
+```
+
+This would result in local storage data being saved in this format:
+```json
+{
+	"core/edit-post": {
+		"preferences": {
+			// ... preferences state from the post editor.
+		}
+	},
+	// ... other persisted state from other editors.
+}
+```
+
+And when an editor was reloaded, this would become the initial store state.
+
+The preferences package was later introduced, and this became a centralized place for managing and persisting preferences for other packages. The job of these migration functions is to migrate data from the old persistence system to the new format for the preferences store:
+```json
+{
+	"preferences": {
+		"core/edit-post": {
+			// ... preferences for the post editor.
+		}
+		// ... preferences for other editors
+	}
+}

package/src/migrations/legacy-local-storage-data/convert-edit-post-panels.js

@@ -0,0 +1,50 @@
+/**
+ * Convert the post editor's panels state from:
+ * ```
+ * {
+ *     panels: {
+ *         tags: {
+ *             enabled: true,
+ *             opened: true,
+ *         },
+ *         permalinks: {
+ *             enabled: false,
+ *             opened: false,
+ *         },
+ *     },
+ * }
+ * ```
+ *
+ * to a new, more concise data structure:
+ * {
+ *     inactivePanels: [
+ *         'permalinks',
+ *     ],
+ *     openPanels: [
+ *         'tags',
+ *     ],
+ * }
+ *
+ * @param {Object} preferences A preferences object.
+ *
+ * @return {Object} The converted data.
+ */
+export default function convertEditPostPanels( preferences ) {
+	const panels = preferences?.panels ?? {};
+	return Object.keys( panels ).reduce(
+		( convertedData, panelName ) => {
+			const panel = panels[ panelName ];
+
+			if ( panel?.enabled === false ) {
+				convertedData.inactivePanels.push( panelName );
+			}
+
+			if ( panel?.opened === true ) {
+				convertedData.openPanels.push( panelName );
+			}
+
+			return convertedData;
+		},
+		{ inactivePanels: [], openPanels: [] }
+	);
+}

package/src/migrations/legacy-local-storage-data/index.js

@@ -0,0 +1,102 @@
+/**
+ * Internal dependencies
+ */
+import moveFeaturePreferences from './move-feature-preferences';
+import moveThirdPartyFeaturePreferences from './move-third-party-feature-preferences';
+import moveIndividualPreference from './move-individual-preference';
+import moveInterfaceEnableItems from './move-interface-enable-items';
+import convertEditPostPanels from './convert-edit-post-panels';
+
+/**
+ * Gets the legacy local storage data for a given user.
+ *
+ * @param {string | number} userId The user id.
+ *
+ * @return {Object | null} The local storage data.
+ */
+function getLegacyData( userId ) {
+	const key = `WP_DATA_USER_${ userId }`;
+	const unparsedData = window.localStorage.getItem( key );
+	return JSON.parse( unparsedData );
+}
+
+/**
+ * Converts data from the old `@wordpress/data` package format.
+ *
+ * @param {Object | null | undefined} data The legacy data in its original format.
+ *
+ * @return {Object | undefined} The converted data or `undefined` if there was
+ *                              nothing to convert.
+ */
+export function convertLegacyData( data ) {
+	if ( ! data ) {
+		return;
+	}
+
+	// Move boolean feature preferences from each editor into the
+	// preferences store data structure.
+	data = moveFeaturePreferences( data, 'core/edit-widgets' );
+	data = moveFeaturePreferences( data, 'core/customize-widgets' );
+	data = moveFeaturePreferences( data, 'core/edit-post' );
+	data = moveFeaturePreferences( data, 'core/edit-site' );
+
+	// Move third party boolean feature preferences from the interface package
+	// to the preferences store data structure.
+	data = moveThirdPartyFeaturePreferences( data );
+
+	// Move and convert the interface store's `enableItems` data into the
+	// preferences data structure.
+	data = moveInterfaceEnableItems( data );
+
+	// Move individual ad-hoc preferences from various packages into the
+	// preferences store data structure.
+	data = moveIndividualPreference(
+		data,
+		{ from: 'core/edit-post', to: 'core/edit-post' },
+		'hiddenBlockTypes'
+	);
+	data = moveIndividualPreference(
+		data,
+		{ from: 'core/edit-post', to: 'core/edit-post' },
+		'editorMode'
+	);
+	data = moveIndividualPreference(
+		data,
+		{ from: 'core/edit-post', to: 'core/edit-post' },
+		'preferredStyleVariations'
+	);
+	data = moveIndividualPreference(
+		data,
+		{ from: 'core/edit-post', to: 'core/edit-post' },
+		'panels',
+		convertEditPostPanels
+	);
+	data = moveIndividualPreference(
+		data,
+		{ from: 'core/editor', to: 'core/edit-post' },
+		'isPublishSidebarEnabled'
+	);
+	data = moveIndividualPreference(
+		data,
+		{ from: 'core/edit-site', to: 'core/edit-site' },
+		'editorMode'
+	);
+
+	// The new system is only concerned with persisting
+	// 'core/preferences' preferences reducer, so only return that.
+	return data?.[ 'core/preferences' ]?.preferences;
+}
+
+/**
+ * Gets the legacy local storage data for the given user and returns the
+ * data converted to the new format.
+ *
+ * @param {string | number} userId The user id.
+ *
+ * @return {Object | undefined} The converted data or undefined if no local
+ *                              storage data could be found.
+ */
+export default function convertLegacyLocalStorageData( userId ) {
+	const data = getLegacyData( userId );
+	return convertLegacyData( data );
+}

package/src/migrations/legacy-local-storage-data/move-feature-preferences.js

@@ -0,0 +1,135 @@
+/**
+ * Move the 'features' object in local storage from the sourceStoreName to the
+ * preferences store data structure.
+ *
+ * Previously, editors used a data structure like this for feature preferences:
+ * ```js
+ * {
+ *     'core/edit-post': {
+ *         preferences: {
+ *             features; {
+ *                 topToolbar: true,
+ *                 // ... other boolean 'feature' preferences
+ *             },
+ *         },
+ *     },
+ * }
+ * ```
+ *
+ * And for a while these feature preferences lived in the interface package:
+ * ```js
+ * {
+ *     'core/interface': {
+ *         preferences: {
+ *             features: {
+ *                 'core/edit-post': {
+ *                     topToolbar: true
+ *                 }
+ *             }
+ *         }
+ *     }
+ * }
+ * ```
+ *
+ * In the preferences store, 'features' aren't considered special, they're
+ * merged to the root level of the scope along with other preferences:
+ * ```js
+ * {
+ *     'core/preferences': {
+ *         preferences: {
+ *             'core/edit-post': {
+ *                 topToolbar: true,
+ *                 // ... any other preferences.
+ *             }
+ *         }
+ *     }
+ * }
+ * ```
+ *
+ * This function handles moving from either the source store or the interface
+ * store to the preferences data structure.
+ *
+ * @param {Object} state           The state before migration.
+ * @param {string} sourceStoreName The name of the store that has persisted
+ *                                 preferences to migrate to the preferences
+ *                                 package.
+ * @return {Object} The migrated state
+ */
+export default function moveFeaturePreferences( state, sourceStoreName ) {
+	const preferencesStoreName = 'core/preferences';
+	const interfaceStoreName = 'core/interface';
+
+	// Features most recently (and briefly) lived in the interface package.
+	// If data exists there, prioritize using that for the migration. If not
+	// also check the original package as the user may have updated from an
+	// older block editor version.
+	const interfaceFeatures =
+		state?.[ interfaceStoreName ]?.preferences?.features?.[
+			sourceStoreName
+		];
+	const sourceFeatures = state?.[ sourceStoreName ]?.preferences?.features;
+	const featuresToMigrate = interfaceFeatures
+		? interfaceFeatures
+		: sourceFeatures;
+
+	if ( ! featuresToMigrate ) {
+		return state;
+	}
+
+	const existingPreferences = state?.[ preferencesStoreName ]?.preferences;
+
+	// Avoid migrating features again if they've previously been migrated.
+	if ( existingPreferences?.[ sourceStoreName ] ) {
+		return state;
+	}
+
+	let updatedInterfaceState;
+	if ( interfaceFeatures ) {
+		const otherInterfaceState = state?.[ interfaceStoreName ];
+		const otherInterfaceScopes =
+			state?.[ interfaceStoreName ]?.preferences?.features;
+
+		updatedInterfaceState = {
+			[ interfaceStoreName ]: {
+				...otherInterfaceState,
+				preferences: {
+					features: {
+						...otherInterfaceScopes,
+						[ sourceStoreName ]: undefined,
+					},
+				},
+			},
+		};
+	}
+
+	let updatedSourceState;
+	if ( sourceFeatures ) {
+		const otherSourceState = state?.[ sourceStoreName ];
+		const sourcePreferences = state?.[ sourceStoreName ]?.preferences;
+
+		updatedSourceState = {
+			[ sourceStoreName ]: {
+				...otherSourceState,
+				preferences: {
+					...sourcePreferences,
+					features: undefined,
+				},
+			},
+		};
+	}
+
+	// Set the feature values in the interface store, the features
+	// object is keyed by 'scope', which matches the store name for
+	// the source.
+	return {
+		...state,
+		[ preferencesStoreName ]: {
+			preferences: {
+				...existingPreferences,
+				[ sourceStoreName ]: featuresToMigrate,
+			},
+		},
+		...updatedInterfaceState,
+		...updatedSourceState,
+	};
+}

package/src/migrations/legacy-local-storage-data/move-individual-preference.js

@@ -0,0 +1,90 @@
+const identity = ( arg ) => arg;
+
+/**
+ * Migrates an individual item inside the `preferences` object for a package's store.
+ *
+ * Previously, some packages had individual 'preferences' of any data type, and many used
+ * complex nested data structures. For example:
+ * ```js
+ * {
+ *     'core/edit-post': {
+ *         preferences: {
+ *             panels: {
+ *                 publish: {
+ *                     opened: true,
+ *                     enabled: true,
+ *                 }
+ *             },
+ *             // ...other preferences.
+ *         },
+ *     },
+ * }
+ *
+ * This function supports moving an individual preference like 'panels' above into the
+ * preferences package data structure.
+ *
+ * It supports moving a preference to a particular scope in the preferences store and
+ * optionally converting the data using a `convert` function.
+ *
+ * ```
+ *
+ * @param {Object}    state        The original state.
+ * @param {Object}    migrate      An options object that contains details of the migration.
+ * @param {string}    migrate.from The name of the store to migrate from.
+ * @param {string}    migrate.to   The scope in the preferences store to migrate to.
+ * @param {string}    key          The key in the preferences object to migrate.
+ * @param {?Function} convert      A function that converts preferences from one format to another.
+ */
+export default function moveIndividualPreferenceToPreferences(
+	state,
+	{ from: sourceStoreName, to: scope },
+	key,
+	convert = identity
+) {
+	const preferencesStoreName = 'core/preferences';
+	const sourcePreference = state?.[ sourceStoreName ]?.preferences?.[ key ];
+
+	// There's nothing to migrate, exit early.
+	if ( sourcePreference === undefined ) {
+		return state;
+	}
+
+	const targetPreference =
+		state?.[ preferencesStoreName ]?.preferences?.[ scope ]?.[ key ];
+
+	// There's existing data at the target, so don't overwrite it, exit early.
+	if ( targetPreference ) {
+		return state;
+	}
+
+	const otherScopes = state?.[ preferencesStoreName ]?.preferences;
+	const otherPreferences =
+		state?.[ preferencesStoreName ]?.preferences?.[ scope ];
+
+	const otherSourceState = state?.[ sourceStoreName ];
+	const allSourcePreferences = state?.[ sourceStoreName ]?.preferences;
+
+	// Pass an object with the key and value as this allows the convert
+	// function to convert to a data structure that has different keys.
+	const convertedPreferences = convert( { [ key ]: sourcePreference } );
+
+	return {
+		...state,
+		[ preferencesStoreName ]: {
+			preferences: {
+				...otherScopes,
+				[ scope ]: {
+					...otherPreferences,
+					...convertedPreferences,
+				},
+			},
+		},
+		[ sourceStoreName ]: {
+			...otherSourceState,
+			preferences: {
+				...allSourcePreferences,
+				[ key ]: undefined,
+			},
+		},
+	};
+}