@wordpress/core-data 7.27.1-next.46f643fa0.0 → 7.28.0

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
+				);
+			} );
+		}
+	);
+} );

package/src/test/private-actions.js

@@ -24,8 +24,8 @@ describe( 'editMediaEntity', () => {
 		resolveSelect = {
 			getEntitiesConfig: jest.fn( () => [
 				{
-					kind: 'root',
-					name: 'media',
+					kind: 'postType',
+					name: 'attachment',
 					baseURL: '/wp/v2/media',
 				},
 			] ),
@@ -82,14 +82,14 @@ describe( 'editMediaEntity', () => {
 
 		expect( dispatch.__unstableAcquireStoreLock ).toHaveBeenCalledWith(
 			'core',
-			[ 'entities', 'records', 'root', 'media', recordId ],
+			[ 'entities', 'records', 'postType', 'attachment', recordId ],
 			{ exclusive: true }
 		);
 
 		expect( dispatch ).toHaveBeenCalledWith( {
 			type: 'SAVE_ENTITY_RECORD_START',
-			kind: 'root',
-			name: 'media',
+			kind: 'postType',
+			name: 'attachment',
 			recordId,
 		} );
 
@@ -100,8 +100,8 @@ describe( 'editMediaEntity', () => {
 		} );
 
 		expect( dispatch.receiveEntityRecords ).toHaveBeenCalledWith(
-			'root',
-			'media',
+			'postType',
+			'attachment',
 			[ updatedRecord ],
 			undefined,
 			true,
@@ -111,8 +111,8 @@ describe( 'editMediaEntity', () => {
 
 		expect( dispatch ).toHaveBeenCalledWith( {
 			type: 'SAVE_ENTITY_RECORD_FINISH',
-			kind: 'root',
-			name: 'media',
+			kind: 'postType',
+			name: 'attachment',
 			recordId,
 			error: undefined,
 		} );
@@ -137,15 +137,15 @@ describe( 'editMediaEntity', () => {
 
 		expect( dispatch ).toHaveBeenCalledWith( {
 			type: 'SAVE_ENTITY_RECORD_START',
-			kind: 'root',
-			name: 'media',
+			kind: 'postType',
+			name: 'attachment',
 			recordId,
 		} );
 
 		expect( dispatch ).toHaveBeenCalledWith( {
 			type: 'SAVE_ENTITY_RECORD_FINISH',
-			kind: 'root',
-			name: 'media',
+			kind: 'postType',
+			name: 'attachment',
 			recordId,
 			error: apiError,
 		} );

package/src/test/resolvers.js

@@ -379,8 +379,8 @@ describe( 'getEmbedPreview', () => {
 describe( 'canUser', () => {
 	const ENTITIES = [
 		{
-			name: 'media',
-			kind: 'root',
+			name: 'attachment',
+			kind: 'postType',
 			baseURL: '/wp/v2/media',
 			baseURLParams: { context: 'edit' },
 		},
@@ -417,7 +417,7 @@ describe( 'canUser', () => {
 			'create',
 			'media'
 		)( { dispatch, registry, resolveSelect } );
-		await canUser( 'create', { kind: 'root', name: 'media' } )( {
+		await canUser( 'create', { kind: 'postType', name: 'attachment' } )( {
 			dispatch,
 			registry,
 			resolveSelect,
@@ -469,7 +469,7 @@ describe( 'canUser', () => {
 			headers: new Map( [ [ 'allow', 'GET' ] ] ),
 		} ) );
 
-		await canUser( 'create', { kind: 'root', name: 'media' } )( {
+		await canUser( 'create', { kind: 'postType', name: 'attachment' } )( {
 			dispatch,
 			registry,
 			resolveSelect,
@@ -482,7 +482,7 @@ describe( 'canUser', () => {
 		} );
 
 		expect( dispatch.receiveUserPermission ).toHaveBeenCalledWith(
-			'create/root/media',
+			'create/postType/attachment',
 			false
 		);
 	} );
@@ -514,7 +514,7 @@ describe( 'canUser', () => {
 			headers: new Map( [ [ 'allow', 'POST, GET, PUT, DELETE' ] ] ),
 		} ) );
 
-		await canUser( 'create', { kind: 'root', name: 'media' } )( {
+		await canUser( 'create', { kind: 'postType', name: 'attachment' } )( {
 			dispatch,
 			registry,
 			resolveSelect,
@@ -527,7 +527,7 @@ describe( 'canUser', () => {
 		} );
 
 		expect( dispatch.receiveUserPermission ).toHaveBeenCalledWith(
-			'create/root/media',
+			'create/postType/attachment',
 			true
 		);
 	} );

package/src/test/selectors.js

@@ -24,6 +24,7 @@ import {
 	getRevisions,
 	getRevision,
 } from '../selectors';
+
 // getEntityRecord and __experimentalGetEntityRecordNoResolver selectors share the same tests.
 describe.each( [
 	[ getEntityRecord ],
@@ -52,6 +53,7 @@ describe.each( [
 			] );
 		} );
 	} );
+
 	it( 'should return undefined for unknown entity kind, name', () => {
 		const state = deepFreeze( {
 			entities: {
@@ -290,6 +292,7 @@ describe( 'getRawEntityRecord', () => {
 			},
 		},
 	};
+
 	it( 'should preserve the structure of `raw` field by default', () => {
 		const state = deepFreeze( {
 			entities: {
@@ -732,7 +735,7 @@ describe( 'canUser', () => {
 		} );
 		expect( canUser( state, 'create', 'media' ) ).toBe( undefined );
 		expect(
-			canUser( state, 'create', { kind: 'root', name: 'media' } )
+			canUser( state, 'create', { kind: 'postType', name: 'attachment' } )
 		).toBe( undefined );
 	} );
 
@@ -740,20 +743,24 @@ describe( 'canUser', () => {
 		const state = deepFreeze( {
 			userPermissions: {},
 		} );
-		expect( canUser( state, 'create', { name: 'media' } ) ).toBe( false );
-		expect( canUser( state, 'create', { kind: 'root' } ) ).toBe( false );
+		expect( canUser( state, 'create', { name: 'attachment' } ) ).toBe(
+			false
+		);
+		expect( canUser( state, 'create', { kind: 'postType' } ) ).toBe(
+			false
+		);
 	} );
 
 	it( 'returns whether an action can be performed', () => {
 		const state = deepFreeze( {
 			userPermissions: {
 				'create/media': false,
-				'create/root/media': false,
+				'create/postType/attachment': false,
 			},
 		} );
 		expect( canUser( state, 'create', 'media' ) ).toBe( false );
 		expect(
-			canUser( state, 'create', { kind: 'root', name: 'media' } )
+			canUser( state, 'create', { kind: 'postType', name: 'attachment' } )
 		).toBe( false );
 	} );
 
@@ -761,12 +768,16 @@ describe( 'canUser', () => {
 		const state = deepFreeze( {
 			userPermissions: {
 				'create/media/123': false,
-				'create/root/media/123': false,
+				'create/postType/attachment/123': false,
 			},
 		} );
 		expect( canUser( state, 'create', 'media', 123 ) ).toBe( false );
 		expect(
-			canUser( state, 'create', { kind: 'root', name: 'media', id: 123 } )
+			canUser( state, 'create', {
+				kind: 'postType',
+				name: 'attachment',
+				id: 123,
+			} )
 		).toBe( false );
 	} );
 } );

package/src/utils/log-entity-deprecation.ts

@@ -0,0 +1,67 @@
+/**
+ * WordPress dependencies
+ */
+import deprecated from '@wordpress/deprecated';
+
+/**
+ * Internal dependencies
+ */
+import { deprecatedEntities } from '../entities';
+
+let loggedAlready = false;
+
+/**
+ * Logs a deprecation warning for an entity, if it's deprecated.
+ *
+ * @param kind                            The kind of the entity.
+ * @param name                            The name of the entity.
+ * @param functionName                    The name of the function that was called with a deprecated entity.
+ * @param options                         The options for the deprecation warning.
+ * @param options.alternativeFunctionName The name of the alternative function that should be used instead.
+ * @param options.isShorthandSelector     Whether the function is a shorthand selector.
+ */
+export default function logEntityDeprecation(
+	kind: string,
+	name: string,
+	functionName: string,
+	{
+		alternativeFunctionName,
+		isShorthandSelector = false,
+	}: {
+		alternativeFunctionName?: string;
+		isShorthandSelector?: boolean;
+	} = {}
+) {
+	const deprecation = deprecatedEntities[ kind ]?.[ name ];
+	if ( ! deprecation ) {
+		return;
+	}
+
+	if ( ! loggedAlready ) {
+		const { alternative } = deprecation;
+
+		const message = isShorthandSelector
+			? `'${ functionName }'`
+			: `The '${ kind }', '${ name }' entity (used via '${ functionName }')`;
+
+		let alternativeMessage = `the '${ alternative.kind }', '${ alternative.name }' entity`;
+		if ( alternativeFunctionName ) {
+			alternativeMessage += ` via the '${ alternativeFunctionName }' function`;
+		}
+
+		deprecated( message, {
+			...deprecation,
+			alternative: alternativeMessage,
+		} );
+	}
+
+	// Only log an entity deprecation once per call stack,
+	// else there's spurious logging when selections or actions call through to other selectors or actions.
+	// Note: this won't prevent the deprecation warning being logged if a selector or action makes an async call
+	// to another selector or action, but this is probably the best we can do.
+	loggedAlready = true;
+	// At the end of the call stack, reset the flag.
+	setTimeout( () => {
+		loggedAlready = false;
+	}, 0 );
+}

package/src/utils/test/log-entity-deprecation.js

@@ -0,0 +1,130 @@
+/**
+ * WordPress dependencies
+ */
+import deprecated from '@wordpress/deprecated';
+
+/**
+ * Internal dependencies
+ */
+import logEntityDeprecation from '../log-entity-deprecation';
+
+jest.useFakeTimers();
+
+// Mock the deprecatedEntities import
+jest.mock( '../../entities', () => ( {
+	deprecatedEntities: {
+		root: {
+			media: {
+				since: '6.9',
+				alternative: {
+					kind: 'postType',
+					name: 'attachment',
+				},
+			},
+		},
+	},
+} ) );
+
+// Mock the deprecated function
+jest.mock( '@wordpress/deprecated' );
+
+describe( 'logEntityDeprecation', () => {
+	beforeEach( () => {
+		jest.clearAllMocks();
+
+		// Ensure the timeout that prevents spurious logging is cleared.
+		jest.runAllTimers();
+	} );
+
+	it( 'should call deprecated when entity is deprecated', () => {
+		logEntityDeprecation( 'root', 'media', 'getEntityRecord' );
+
+		expect( deprecated ).toHaveBeenCalledWith(
+			"The 'root', 'media' entity (used via 'getEntityRecord')",
+			{
+				since: '6.9',
+				alternative: "the 'postType', 'attachment' entity",
+			}
+		);
+	} );
+
+	it( 'should not call deprecated when entity is not deprecated', () => {
+		logEntityDeprecation( 'root', 'nonExistentEntity', 'getEntityRecord' );
+
+		expect( deprecated ).not.toHaveBeenCalled();
+	} );
+
+	it( 'should not call deprecated when kind is not deprecated', () => {
+		logEntityDeprecation( 'nonExistentKind', 'media', 'getEntityRecord' );
+
+		expect( deprecated ).not.toHaveBeenCalled();
+	} );
+
+	it( 'should handle different function names', () => {
+		logEntityDeprecation( 'root', 'media', 'saveEntityRecord' );
+
+		expect( deprecated ).toHaveBeenCalledWith(
+			"The 'root', 'media' entity (used via 'saveEntityRecord')",
+			{
+				since: '6.9',
+				alternative: "the 'postType', 'attachment' entity",
+			}
+		);
+	} );
+
+	it( 'should include alternative function name when provided', () => {
+		logEntityDeprecation( 'root', 'media', 'getEntityRecord', {
+			alternativeFunctionName: 'getPostTypeEntity',
+		} );
+
+		expect( deprecated ).toHaveBeenCalledWith(
+			"The 'root', 'media' entity (used via 'getEntityRecord')",
+			{
+				since: '6.9',
+				alternative:
+					"the 'postType', 'attachment' entity via the 'getPostTypeEntity' function",
+			}
+		);
+	} );
+
+	it( 'should handle isShorthandSelector', () => {
+		logEntityDeprecation( 'root', 'media', 'getMedia', {
+			isShorthandSelector: true,
+		} );
+
+		expect( deprecated ).toHaveBeenCalledWith( "'getMedia'", {
+			since: '6.9',
+			alternative: "the 'postType', 'attachment' entity",
+		} );
+	} );
+
+	it( 'should handle empty string parameters', () => {
+		logEntityDeprecation( '', '', '' );
+
+		expect( deprecated ).not.toHaveBeenCalled();
+	} );
+
+	it( 'should handle null parameters', () => {
+		logEntityDeprecation( null, null, null );
+
+		expect( deprecated ).not.toHaveBeenCalled();
+	} );
+
+	it( 'should handle undefined parameters', () => {
+		logEntityDeprecation( undefined, undefined, undefined );
+
+		expect( deprecated ).not.toHaveBeenCalled();
+	} );
+
+	it( 'should handle undefined options', () => {
+		logEntityDeprecation( 'root', 'media', 'getEntityRecord', undefined );
+
+		expect( deprecated ).toHaveBeenCalledWith(
+			"The 'root', 'media' entity (used via 'getEntityRecord')",
+			{
+				since: '6.9',
+				alternative: "the 'postType', 'attachment' entity",
+			}
+		);
+	} );
+} );