@wordpress/core-data 7.27.0 → 7.28.0

package/src/private-actions.js

@@ -1,3 +1,13 @@
+/**
+ * WordPress dependencies
+ */
+import apiFetch from '@wordpress/api-fetch';
+
+/**
+ * Internal dependencies
+ */
+import { STORE_NAME } from './name';
+
 /**
  * Returns an action object used in signalling that the registered post meta
  * fields for a post type have been received.
@@ -14,3 +24,111 @@ export function receiveRegisteredPostMeta( postType, registeredPostMeta ) {
 		registeredPostMeta,
 	};
 }
+
+/**
+ * @typedef {Object} Modifier
+ * @property {string} [type] - The type of modifier.
+ * @property {Object} [args] - The arguments of the modifier.
+ */
+
+/**
+ * @typedef {Object} Edits
+ * @property {string}     [src]       - The URL of the media item.
+ * @property {Modifier[]} [modifiers] - The modifiers to apply to the media item.
+ */
+
+/**
+ * Duplicates a media (attachment) entity record and, optionally, modifies it.
+ *
+ * @param {string}   recordId                Entity record ID.
+ * @param {Edits}    edits                   Edits to apply to the record.
+ * @param {Object}   options                 Options object.
+ * @param {Function} options.__unstableFetch Custom fetch function.
+ * @param {boolean}  options.throwOnError    Whether to throw an error if the request fails.
+ *
+ * @return {Promise} Promise resolving to the updated record.
+ */
+export const editMediaEntity =
+	(
+		recordId,
+		edits = {},
+		{ __unstableFetch = apiFetch, throwOnError = false } = {}
+	) =>
+	async ( { dispatch, resolveSelect } ) => {
+		if ( ! recordId ) {
+			return;
+		}
+
+		const kind = 'postType';
+		const name = 'attachment';
+
+		const configs = await resolveSelect.getEntitiesConfig( kind );
+		const entityConfig = configs.find(
+			( config ) => config.kind === kind && config.name === name
+		);
+
+		if ( ! entityConfig ) {
+			return;
+		}
+
+		const lock = await dispatch.__unstableAcquireStoreLock(
+			STORE_NAME,
+			[ 'entities', 'records', kind, name, recordId ],
+			{ exclusive: true }
+		);
+
+		let updatedRecord;
+		let error;
+		let hasError = false;
+
+		try {
+			dispatch( {
+				type: 'SAVE_ENTITY_RECORD_START',
+				kind,
+				name,
+				recordId,
+			} );
+
+			try {
+				const path = `${ entityConfig.baseURL }/${ recordId }/edit`;
+				const newRecord = await __unstableFetch( {
+					path,
+					method: 'POST',
+					data: {
+						...edits,
+					},
+				} );
+
+				if ( newRecord ) {
+					dispatch.receiveEntityRecords(
+						kind,
+						name,
+						[ newRecord ],
+						undefined,
+						true,
+						undefined,
+						undefined
+					);
+					updatedRecord = newRecord;
+				}
+			} catch ( e ) {
+				error = e;
+				hasError = true;
+			}
+
+			dispatch( {
+				type: 'SAVE_ENTITY_RECORD_FINISH',
+				kind,
+				name,
+				recordId,
+				error,
+			} );
+
+			if ( hasError && throwOnError ) {
+				throw error;
+			}
+			return updatedRecord;
+		} finally {
+			dispatch.__unstableReleaseStoreLock( lock );
+		}
+	};

package/src/private-selectors.ts

@@ -9,6 +9,7 @@ import { createSelector, createRegistrySelector } from '@wordpress/data';
 import { getDefaultTemplateId, getEntityRecord, type State } from './selectors';
 import { STORE_NAME } from './name';
 import { unlock } from './lock-unlock';
+import logEntityDeprecation from './utils/log-entity-deprecation';
 
 type EntityRecordKey = string | number;
 
@@ -97,6 +98,7 @@ export function getEntityRecordPermissions(
 	name: string,
 	id: string
 ) {
+	logEntityDeprecation( kind, name, 'getEntityRecordPermissions' );
 	return getEntityRecordsPermissions( state, kind, name, id )[ 0 ];
 }
 

package/src/resolvers.js

@@ -479,7 +479,7 @@ export const getEmbedPreview =
  *
  * @param {string}        requestedAction Action to check. One of: 'create', 'read', 'update',
  *                                        'delete'.
- * @param {string|Object} resource        Entity resource to check. Accepts entity object `{ kind: 'root', name: 'media', id: 1 }`
+ * @param {string|Object} resource        Entity resource to check. Accepts entity object `{ kind: 'postType', name: 'attachment', id: 1 }`
  *                                        or REST base as a string - `media`.
  * @param {?string}       id              ID of the rest resource to check.
  */

package/src/selectors.ts

@@ -24,6 +24,7 @@ import {
 } from './utils';
 import type * as ET from './entity-types';
 import type { UndoManager } from '@wordpress/undo-manager';
+import logEntityDeprecation from './utils/log-entity-deprecation';
 
 // This is an incomplete, high-level approximation of the State type.
 // It makes the selectors slightly more safe, but is intended to evolve
@@ -272,6 +273,8 @@ export function getEntityConfig(
 	kind: string,
 	name: string
 ): any {
+	logEntityDeprecation( kind, name, 'getEntityConfig' );
+
 	return state.entities.config?.find(
 		( config ) => config.kind === kind && config.name === name
 	);
@@ -353,6 +356,8 @@ export const getEntityRecord = createSelector(
 		key?: EntityRecordKey,
 		query?: GetRecordsHttpQuery
 	): EntityRecord | undefined => {
+		logEntityDeprecation( kind, name, 'getEntityRecord' );
+
 		const queriedState =
 			state.entities.records?.[ kind ]?.[ name ]?.queriedData;
 		if ( ! queriedState ) {
@@ -450,6 +455,8 @@ export const getRawEntityRecord = createSelector(
 		name: string,
 		key: EntityRecordKey
 	): EntityRecord | undefined => {
+		logEntityDeprecation( kind, name, 'getRawEntityRecord' );
+
 		const record = getEntityRecord< EntityRecord >(
 			state,
 			kind,
@@ -512,6 +519,7 @@ export function hasEntityRecords(
 	name: string,
 	query?: GetRecordsHttpQuery
 ): boolean {
+	logEntityDeprecation( kind, name, 'hasEntityRecords' );
 	return Array.isArray( getEntityRecords( state, kind, name, query ) );
 }
 
@@ -567,6 +575,8 @@ export const getEntityRecords = ( <
 	name: string,
 	query: GetRecordsHttpQuery
 ): EntityRecord[] | null => {
+	logEntityDeprecation( kind, name, 'getEntityRecords' );
+
 	// Queried data state is prepopulated for all known entities. If this is not
 	// assigned for the given parameters, then it is known to not exist.
 	const queriedState =
@@ -594,6 +604,8 @@ export const getEntityRecordsTotalItems = (
 	name: string,
 	query: GetRecordsHttpQuery
 ): number | null => {
+	logEntityDeprecation( kind, name, 'getEntityRecordsTotalItems' );
+
 	// Queried data state is prepopulated for all known entities. If this is not
 	// assigned for the given parameters, then it is known to not exist.
 	const queriedState =
@@ -621,6 +633,8 @@ export const getEntityRecordsTotalPages = (
 	name: string,
 	query: GetRecordsHttpQuery
 ): number | null => {
+	logEntityDeprecation( kind, name, 'getEntityRecordsTotalPages' );
+
 	// Queried data state is prepopulated for all known entities. If this is not
 	// assigned for the given parameters, then it is known to not exist.
 	const queriedState =
@@ -774,6 +788,7 @@ export function getEntityRecordEdits(
 	name: string,
 	recordId: EntityRecordKey
 ): Optional< any > {
+	logEntityDeprecation( kind, name, 'getEntityRecordEdits' );
 	return state.entities.records?.[ kind ]?.[ name ]?.edits?.[
 		recordId as string | number
 	];
@@ -800,6 +815,7 @@ export const getEntityRecordNonTransientEdits = createSelector(
 		name: string,
 		recordId: EntityRecordKey
 	): Optional< any > => {
+		logEntityDeprecation( kind, name, 'getEntityRecordNonTransientEdits' );
 		const { transientEdits } = getEntityConfig( state, kind, name ) || {};
 		const edits = getEntityRecordEdits( state, kind, name, recordId ) || {};
 		if ( ! transientEdits ) {
@@ -835,6 +851,7 @@ export function hasEditsForEntityRecord(
 	name: string,
 	recordId: EntityRecordKey
 ): boolean {
+	logEntityDeprecation( kind, name, 'hasEditsForEntityRecord' );
 	return (
 		isSavingEntityRecord( state, kind, name, recordId ) ||
 		Object.keys(
@@ -860,6 +877,7 @@ export const getEditedEntityRecord = createSelector(
 		name: string,
 		recordId: EntityRecordKey
 	): ET.Updatable< EntityRecord > | false => {
+		logEntityDeprecation( kind, name, 'getEditedEntityRecord' );
 		const raw = getRawEntityRecord( state, kind, name, recordId );
 		const edited = getEntityRecordEdits( state, kind, name, recordId );
 		// Never return a non-falsy empty object. Unfortunately we can't return
@@ -910,6 +928,7 @@ export function isAutosavingEntityRecord(
 	name: string,
 	recordId: EntityRecordKey
 ): boolean {
+	logEntityDeprecation( kind, name, 'isAutosavingEntityRecord' );
 	const { pending, isAutosave } =
 		state.entities.records?.[ kind ]?.[ name ]?.saving?.[ recordId ] ?? {};
 	return Boolean( pending && isAutosave );
@@ -931,6 +950,7 @@ export function isSavingEntityRecord(
 	name: string,
 	recordId: EntityRecordKey
 ): boolean {
+	logEntityDeprecation( kind, name, 'isSavingEntityRecord' );
 	return (
 		state.entities.records?.[ kind ]?.[ name ]?.saving?.[
 			recordId as EntityRecordKey
@@ -954,6 +974,7 @@ export function isDeletingEntityRecord(
 	name: string,
 	recordId: EntityRecordKey
 ): boolean {
+	logEntityDeprecation( kind, name, 'isDeletingEntityRecord' );
 	return (
 		state.entities.records?.[ kind ]?.[ name ]?.deleting?.[
 			recordId as EntityRecordKey
@@ -977,6 +998,7 @@ export function getLastEntitySaveError(
 	name: string,
 	recordId: EntityRecordKey
 ): any {
+	logEntityDeprecation( kind, name, 'getLastEntitySaveError' );
 	return state.entities.records?.[ kind ]?.[ name ]?.saving?.[ recordId ]
 		?.error;
 }
@@ -997,6 +1019,7 @@ export function getLastEntityDeleteError(
 	name: string,
 	recordId: EntityRecordKey
 ): any {
+	logEntityDeprecation( kind, name, 'getLastEntityDeleteError' );
 	return state.entities.records?.[ kind ]?.[ name ]?.deleting?.[ recordId ]
 		?.error;
 }
@@ -1143,7 +1166,7 @@ export function isPreviewEmbedFallback( state: State, url: string ): boolean {
  *
  * @param state    Data state.
  * @param action   Action to check. One of: 'create', 'read', 'update', 'delete'.
- * @param resource Entity resource to check. Accepts entity object `{ kind: 'root', name: 'media', id: 1 }`
+ * @param resource Entity resource to check. Accepts entity object `{ kind: 'postType', name: 'attachment', id: 1 }`
  *                 or REST base as a string - `media`.
  * @param id       Optional ID of the rest resource to check.
  *
@@ -1160,6 +1183,9 @@ export function canUser(
 	if ( isEntity && ( ! resource.kind || ! resource.name ) ) {
 		return false;
 	}
+	if ( isEntity ) {
+		logEntityDeprecation( resource.kind, resource.name, 'canUser' );
+	}
 
 	const key = getUserPermissionCacheKey( action, resource, id );
 
@@ -1418,6 +1444,7 @@ export const getRevisions = (
 	recordKey: EntityRecordKey,
 	query?: GetRecordsHttpQuery
 ): RevisionRecord[] | null => {
+	logEntityDeprecation( kind, name, 'getRevisions' );
 	const queriedStateRevisions =
 		state.entities.records?.[ kind ]?.[ name ]?.revisions?.[ recordKey ];
 	if ( ! queriedStateRevisions ) {
@@ -1449,6 +1476,7 @@ export const getRevision = createSelector(
 		revisionKey: EntityRecordKey,
 		query?: GetRecordsHttpQuery
 	): RevisionRecord | Record< PropertyKey, never > | undefined => {
+		logEntityDeprecation( kind, name, 'getRevision' );
 		const queriedState =
 			state.entities.records?.[ kind ]?.[ name ]?.revisions?.[
 				recordKey

package/src/test/deprecated-entity-logging.js

@@ -0,0 +1,291 @@
+/**
+ * WordPress dependencies
+ */
+import deprecated from '@wordpress/deprecated';
+import { createRegistry } from '@wordpress/data';
+
+/**
+ * Internal dependencies
+ */
+import { store as coreDataStore } from '../index';
+
+jest.mock( '@wordpress/deprecated' );
+jest.mock( '@wordpress/api-fetch' );
+
+// Use fake timers within this file.
+// logEntityDeprecation() uses setTimeout() to avoid spurious logging, so fake timers are used to
+// ensure that the deprecation warning is logged correctly.
+jest.useFakeTimers();
+
+/**
+ * Returns the expected arguments for the deprecated function call.
+ *
+ * @param {string}  name                - The name of the function.
+ * @param {Array}   args                - The arguments for the function.
+ * @param {boolean} isShorthandSelector - Whether the function is a shorthand selector.
+ * @param {string}  alternativeFunction - The name of the alternative function.
+ * @return {Array} The expected arguments for the deprecated function call.
+ */
+function getExpectedDeprecationArgs(
+	name,
+	args,
+	isShorthandSelector,
+	alternativeFunction
+) {
+	const expectedMessage = isShorthandSelector
+		? `'${ name }'`
+		: `The 'root', 'media' entity (used via '${ name }')`;
+
+	let expectedAlternative = "the 'postType', 'attachment' entity";
+	if ( alternativeFunction ) {
+		expectedAlternative += ` via the '${ alternativeFunction }' function`;
+	}
+
+	return [
+		expectedMessage,
+		{
+			alternative: expectedAlternative,
+			since: '6.9',
+		},
+	];
+}
+
+/**
+ * Creates a test registry with the core-data store and sets up the deprecated media entity.
+ *
+ * This approach enables testing generated selections/actions (like `getMedia`), and simplifies
+ * the tests by avoiding an endless amount of mocks.
+ *
+ * It means the tests in this file are integration rather than unit tests, so they're kept
+ * separate from the selector.js/reducer.js tests.
+ *
+ * @return {Object} Registry with core-data store registered.
+ */
+function createTestRegistry() {
+	const registry = createRegistry();
+
+	// Register the core-data store
+	registry.register( coreDataStore );
+
+	// Set up the deprecated media entity configuration
+	const mediaEntityConfig = {
+		name: 'media',
+		kind: 'root',
+		baseURL: '/wp/v2/media',
+		baseURLParams: { context: 'edit' },
+		plural: 'mediaItems',
+		label: 'Media',
+		rawAttributes: [ 'caption', 'title', 'description' ],
+		supportsPagination: true,
+	};
+
+	// Add the media entity to the store
+	registry.dispatch( coreDataStore ).addEntities( [ mediaEntityConfig ] );
+
+	// Add a sample media record to the store for testing
+	const mediaRecord = {
+		id: '123',
+		title: 'Test Media',
+		content: 'Test content',
+		excerpt: 'Test excerpt',
+	};
+
+	registry
+		.dispatch( coreDataStore )
+		.receiveEntityRecords( 'root', 'media', mediaRecord );
+
+	jest.runAllTimers();
+
+	return registry;
+}
+
+describe( 'Deprecated entity logging', () => {
+	describe.each( [
+		{
+			type: 'selector',
+			name: 'getEntityConfig',
+			args: [ 'root', 'media' ],
+		},
+		{
+			type: 'selector',
+			name: 'getEntityRecord',
+			args: [ 'root', 'media', '123' ],
+		},
+		{
+			type: 'selector',
+			name: 'getRawEntityRecord',
+			args: [ 'root', 'media', '123' ],
+		},
+		{
+			type: 'selector',
+			name: 'hasEntityRecords',
+			args: [ 'root', 'media' ],
+		},
+		{
+			type: 'selector',
+			name: 'getEntityRecords',
+			args: [ 'root', 'media' ],
+		},
+		{
+			type: 'selector',
+			name: 'getEntityRecordsTotalItems',
+			args: [ 'root', 'media', { _fields: 'title' } ],
+		},
+		{
+			type: 'selector',
+			name: 'getEntityRecordsTotalPages',
+			args: [ 'root', 'media', { _fields: 'title' } ],
+		},
+		{
+			type: 'selector',
+			name: 'getEntityRecordEdits',
+			args: [ 'root', 'media', '123' ],
+		},
+		{
+			type: 'selector',
+			name: 'getEntityRecordNonTransientEdits',
+			args: [ 'root', 'media', '123' ],
+		},
+		{
+			type: 'selector',
+			name: 'hasEditsForEntityRecord',
+			args: [ 'root', 'media', '123' ],
+		},
+		{
+			type: 'selector',
+			name: 'getEditedEntityRecord',
+			args: [ 'root', 'media', '123' ],
+		},
+		{
+			type: 'selector',
+			name: 'isAutosavingEntityRecord',
+			args: [ 'root', 'media', '123' ],
+		},
+		{
+			type: 'selector',
+			name: 'isSavingEntityRecord',
+			args: [ 'root', 'media', '123' ],
+		},
+		{
+			type: 'selector',
+			name: 'isDeletingEntityRecord',
+			args: [ 'root', 'media', '123' ],
+		},
+		{
+			type: 'selector',
+			name: 'getLastEntitySaveError',
+			args: [ 'root', 'media', '123' ],
+		},
+		{
+			type: 'selector',
+			name: 'getLastEntityDeleteError',
+			args: [ 'root', 'media', '123' ],
+		},
+		{
+			type: 'selector',
+			name: 'canUser',
+			args: [ 'create', { kind: 'root', name: 'media' }, '123' ],
+		},
+		{
+			type: 'selector',
+			name: 'getRevisions',
+			args: [ 'root', 'media', '123' ],
+		},
+		{
+			type: 'selector',
+			name: 'getRevision',
+			args: [ 'root', 'media', '123', '10' ],
+		},
+		{
+			type: 'selector',
+			name: 'getMedia',
+			args: [ '123' ],
+			isShorthandSelector: true,
+			alternativeFunction: 'getEntityRecord',
+		},
+		{
+			type: 'selector',
+			name: 'getMediaItems',
+			args: [],
+			isShorthandSelector: true,
+			alternativeFunction: 'getEntityRecords',
+		},
+		{
+			type: 'action',
+			name: 'deleteEntityRecord',
+			args: [ 'root', 'media', '123' ],
+		},
+		{
+			type: 'action',
+			name: 'editEntityRecord',
+			args: [ 'root', 'media', '123', { title: 'Media' } ],
+		},
+		{
+			type: 'action',
+			name: 'saveEntityRecord',
+			args: [ 'root', 'media', { title: 'Media' } ],
+		},
+		{
+			type: 'action',
+			name: 'saveEditedEntityRecord',
+			args: [ 'root', 'media', '123' ],
+		},
+		{
+			type: 'action',
+			name: '__experimentalSaveSpecifiedEntityEdits',
+			args: [ 'root', 'media', '123', [ 'title' ] ],
+		},
+		{
+			type: 'action',
+			name: 'receiveRevisions',
+			args: [ 'root', 'media', '123', [ 'title' ] ],
+		},
+		{
+			type: 'action',
+			name: 'saveMedia',
+			args: [ { title: 'Media' } ],
+			alternativeFunction: 'saveEntityRecord',
+			isShorthandSelector: true,
+		},
+		{
+			type: 'action',
+			name: 'deleteMedia',
+			args: [ '123' ],
+			alternativeFunction: 'deleteEntityRecord',
+			isShorthandSelector: true,
+		},
+	] )(
+		'$name $type',
+		( { type, name, args, alternativeFunction, isShorthandSelector } ) => {
+			beforeEach( () => {
+				deprecated.mockReset();
+			} );
+
+			it( 'logs a deprecation warning when used with deprecated entities', () => {
+				// Create a test registry with the actual store
+				const registry = createTestRegistry();
+
+				if ( type === 'selector' ) {
+					// Dispatch the action.
+					registry.select( coreDataStore )[ name ]( ...args );
+				} else {
+					// Dispatch the action.
+					registry.dispatch( coreDataStore )[ name ]( ...args );
+				}
+
+				const [ expectedMessage, expectedOptions ] =
+					getExpectedDeprecationArgs(
+						name,
+						args,
+						isShorthandSelector,
+						alternativeFunction
+					);
+
+				expect( deprecated ).toHaveBeenCalledWith(
+					expectedMessage,
+					expectedOptions
+				);
+			} );
+		}
+	);
+} );