Real-time collaboration: Refetch entity when it is saved by a peer (#74637)

chriszarate · web-flow · commit be1c20e213e7 · 2026-01-15T08:53:01.000-07:00
* Refetch entity when it is saved by a peer

* tch
diff --git a/packages/core-data/src/actions.js b/packages/core-data/src/actions.js
@@ -714,6 +714,17 @@ export const saveEntityRecord =
 						true,
 						edits
 					);
+					if ( globalThis.IS_GUTENBERG_PLUGIN ) {
+						if ( entityConfig.syncConfig ) {
+							getSyncManager()?.update(
+								`${ kind }/${ name }`,
+								recordId,
+								updatedRecord,
+								LOCAL_EDITOR_ORIGIN,
+								true // isSave
+							);
+						}
+					}
 				}
 			} catch ( _error ) {
 				hasError = true;
diff --git a/packages/core-data/src/resolvers.js b/packages/core-data/src/resolvers.js
@@ -215,6 +215,15 @@ export const getEntityRecord =
 									name,
 									key
 								),
+							// Refetch the current entity record from the database.
+							refetchRecord: async () => {
+								dispatch.receiveEntityRecords(
+									kind,
+									name,
+									await apiFetch( { path, parse: true } ),
+									query
+								);
+							},
 							// Save the current entity record's unsaved edits.
 							saveRecord: () => {
 								dispatch.saveEditedEntityRecord(
diff --git a/packages/core-data/src/test/resolvers.js b/packages/core-data/src/test/resolvers.js
@@ -170,6 +170,7 @@ describe( 'getEntityRecord', () => {
 			{
 				editRecord: expect.any( Function ),
 				getEditedRecord: expect.any( Function ),
+				refetchRecord: expect.any( Function ),
 				saveRecord: expect.any( Function ),
 			}
 		);
@@ -222,6 +223,7 @@ describe( 'getEntityRecord', () => {
 			{
 				editRecord: expect.any( Function ),
 				getEditedRecord: expect.any( Function ),
+				refetchRecord: expect.any( Function ),
 				saveRecord: expect.any( Function ),
 			}
 		);
diff --git a/packages/sync/README.md b/packages/sync/README.md
@@ -20,7 +20,19 @@ CRDT documents can hold meta information in a map. This map exists only in memor
 
 ### CRDT_RECORD_MAP_KEY
 
-Root-level key for the CRDT document that holds the entity record data.
+Root-level key for the map that holds the entity record data.
+
+### CRDT_RECORD_METADATA_MAP_KEY
+
+Root-level key for the map that holds entity record metadata. This map should only contain metadata that is not represented by the entity record itself.
+
+### CRDT_RECORD_METADATA_SAVED_AT_KEY
+
+Y.Map key representing the timestamp of the last save operation.
+
+### CRDT_RECORD_METADATA_SAVED_BY_KEY
+
+Y.Map key representing the Y.Doc client ID of the user who performed the last save operation.
 
 ### createSyncManager
 
diff --git a/packages/sync/src/config.ts b/packages/sync/src/config.ts
@@ -13,13 +13,31 @@ export const CRDT_DOC_VERSION = 1;
 export const CRDT_DOC_META_PERSISTENCE_KEY = 'fromPersistence';
 
 /**
- * Root-level key for the CRDT document that holds the entity record data.
+ * Root-level key for the map that holds the entity record data.
  */
 export const CRDT_RECORD_MAP_KEY = 'document';
 
 /**
- * Root-level key for the CRDT document that holds the state descriptors (see
- * below).
+ * Root-level key for the map that holds entity record metadata. This map should
+ * only contain metadata that is not represented by the entity record itself.
+ */
+export const CRDT_RECORD_METADATA_MAP_KEY = 'documentMeta';
+
+/**
+ * Y.Map key representing the timestamp of the last save operation.
+ */
+export const CRDT_RECORD_METADATA_SAVED_AT_KEY = 'savedAt';
+
+/**
+ * Y.Map key representing the Y.Doc client ID of the user who performed the last
+ * save operation.
+ */
+export const CRDT_RECORD_METADATA_SAVED_BY_KEY = 'savedBy';
+
+/**
+ * Root-level key for the map that holds the state information about the CRDT
+ * document itself. It should not contain information related to the entity
+ * record.
  */
 export const CRDT_STATE_MAP_KEY = 'state';
 
diff --git a/packages/sync/src/index.ts b/packages/sync/src/index.ts
@@ -19,6 +19,9 @@ export { default as Delta } from './quill-delta/Delta';
 export {
 	CRDT_DOC_META_PERSISTENCE_KEY,
 	CRDT_RECORD_MAP_KEY,
+	CRDT_RECORD_METADATA_MAP_KEY,
+	CRDT_RECORD_METADATA_SAVED_AT_KEY,
+	CRDT_RECORD_METADATA_SAVED_BY_KEY,
 	LOCAL_EDITOR_ORIGIN,
 	LOCAL_SYNC_MANAGER_ORIGIN,
 	WORDPRESS_META_KEY_FOR_CRDT_DOC_PERSISTENCE,
diff --git a/packages/sync/src/manager.ts b/packages/sync/src/manager.ts
@@ -9,6 +9,9 @@ import * as Y from 'yjs';
 import {
 	CRDT_RECORD_MAP_KEY as RECORD_KEY,
 	LOCAL_SYNC_MANAGER_ORIGIN,
+	CRDT_RECORD_METADATA_MAP_KEY as RECORD_METADATA_KEY,
+	CRDT_RECORD_METADATA_SAVED_AT_KEY as SAVED_AT_KEY,
+	CRDT_RECORD_METADATA_SAVED_BY_KEY as SAVED_BY_KEY,
 } from './config';
 import { createPersistedCRDTDoc, getPersistedCrdtDoc } from './persistence';
 import { getProviderCreators } from './providers';
@@ -105,6 +108,8 @@ export function createSyncManager(): SyncManager {
 
 		const ydoc = createYjsDoc( { objectType } );
 		const recordMap = ydoc.getMap( RECORD_KEY );
+		const recordMetaMap = ydoc.getMap( RECORD_METADATA_KEY );
+		const now = Date.now();
 
 		// Clean up providers and in-memory state when the entity is unloaded.
 		const unload = (): void => {
@@ -130,6 +135,28 @@ export function createSyncManager(): SyncManager {
 			void updateEntityRecord( objectType, objectId );
 		};
 
+		const onRecordMetaUpdate = (
+			event: Y.YMapEvent< unknown >,
+			transaction: Y.Transaction
+		) => {
+			if ( transaction.local ) {
+				return;
+			}
+
+			event.keysChanged.forEach( ( key ) => {
+				switch ( key ) {
+					case SAVED_AT_KEY:
+						const newValue = recordMetaMap.get( SAVED_AT_KEY );
+						if ( 'number' === typeof newValue && newValue > now ) {
+							// Another peer has saved the record. Refetch it so that we have
+							// a correct understanding of our own unsaved edits.
+							void handlers.refetchRecord().catch( () => {} );
+						}
+						break;
+				}
+			} );
+		};
+
 		// Lazily create the undo manager when the first entity is loaded.
 		if ( ! undoManager ) {
 			undoManager = createUndoManager();
@@ -159,6 +186,7 @@ export function createSyncManager(): SyncManager {
 
 		// Attach observers.
 		recordMap.observeDeep( onRecordUpdate );
+		recordMetaMap.observe( onRecordMetaUpdate );
 
 		// Get and apply the persisted CRDT document, if it exists.
 		const isInvalid = applyPersistedCrdtDoc( syncConfig, ydoc, record );
@@ -257,12 +285,14 @@ export function createSyncManager(): SyncManager {
 	 * @param {ObjectID}              objectId   Object ID.
 	 * @param {Partial< ObjectData >} changes    Updates to make.
 	 * @param {string}                origin     The source of change.
+	 * @param {boolean}               isSave     Whether this update is part of a save operation.
 	 */
 	function updateCRDTDoc(
 		objectType: ObjectType,
 		objectId: ObjectID,
 		changes: Partial< ObjectData >,
-		origin: string
+		origin: string,
+		isSave: boolean = false
 	): void {
 		const entityId = getEntityId( objectType, objectId );
 		const entityState = entityStates.get( entityId );
@@ -275,6 +305,13 @@ export function createSyncManager(): SyncManager {
 
 		ydoc.transact( () => {
 			syncConfig.applyChangesToCRDTDoc( ydoc, changes );
+
+			if ( isSave ) {
+				// Mark the document as saved in the record metadata map.
+				const recordMeta = ydoc.getMap( RECORD_METADATA_KEY );
+				recordMeta.set( SAVED_AT_KEY, Date.now() );
+				recordMeta.set( SAVED_BY_KEY, ydoc.clientID );
+			}
 		}, origin );
 	}
 
diff --git a/packages/sync/src/test/manager.ts b/packages/sync/src/test/manager.ts
@@ -19,6 +19,9 @@ import {
 import { createSyncManager } from '../manager';
 import {
 	CRDT_RECORD_MAP_KEY,
+	CRDT_RECORD_METADATA_MAP_KEY as RECORD_METADATA_MAP_KEY,
+	CRDT_RECORD_METADATA_SAVED_AT_KEY as SAVED_AT_KEY,
+	CRDT_RECORD_METADATA_SAVED_BY_KEY as SAVED_BY_KEY,
 	WORDPRESS_META_KEY_FOR_CRDT_DOC_PERSISTENCE,
 } from '../config';
 import { createPersistedCRDTDoc } from '../persistence';
@@ -88,6 +91,7 @@ describe( 'SyncManager', () => {
 			getEditedRecord: jest.fn( async () =>
 				Promise.resolve( mockRecord )
 			),
+			refetchRecord: jest.fn( async () => Promise.resolve() ),
 			saveRecord: jest.fn( async () => Promise.resolve() ),
 		};
 	} );
@@ -520,6 +524,19 @@ describe( 'SyncManager', () => {
 
 	describe( 'update', () => {
 		it( 'updates CRDT document with local changes', async () => {
+			// Capture the Y.Doc from provider creator
+			let capturedDoc: Y.Doc | null = null;
+			mockProviderCreator.mockImplementation(
+				async (
+					_objectType: string,
+					_objectId: string,
+					ydoc: Y.Doc
+				) => {
+					capturedDoc = ydoc;
+					return mockProviderResult;
+				}
+			);
+
 			const manager = createSyncManager();
 
 			await manager.load(
@@ -535,10 +552,17 @@ describe( 'SyncManager', () => {
 			const changes = { title: 'Updated Title' };
 			manager.update( 'post', '123', changes, 'local-editor' );
 
+			// Verify that applyChangesToCRDTDoc was called with the changes.
 			expect( mockSyncConfig.applyChangesToCRDTDoc ).toHaveBeenCalledWith(
 				expect.any( Y.Doc ),
 				changes
 			);
+
+			// Verify that the record metadata was not updated.
+			const ydoc = capturedDoc as unknown as Y.Doc;
+			const metadataMap = ydoc.getMap( RECORD_METADATA_MAP_KEY );
+			expect( metadataMap.get( SAVED_AT_KEY ) ).toBeUndefined();
+			expect( metadataMap.get( SAVED_BY_KEY ) ).toBeUndefined();
 		} );
 
 		it( 'does not update when entity is not loaded', () => {
@@ -595,6 +619,52 @@ describe( 'SyncManager', () => {
 				customOrigin
 			);
 		} );
+
+		it( 'updates the record metadata when the update is associated with a save', async () => {
+			// Capture the Y.Doc from provider creator.
+			let capturedDoc: Y.Doc | null = null;
+			mockProviderCreator.mockImplementation(
+				async (
+					_objectType: string,
+					_objectId: string,
+					ydoc: Y.Doc
+				) => {
+					capturedDoc = ydoc;
+					return mockProviderResult;
+				}
+			);
+
+			const manager = createSyncManager();
+
+			await manager.load(
+				mockSyncConfig,
+				'post',
+				'123',
+				mockRecord,
+				mockHandlers
+			);
+
+			jest.clearAllMocks();
+
+			const changes = { title: 'Updated Title' };
+			const now = Date.now();
+
+			manager.update( 'post', '123', changes, 'local-editor', true );
+
+			// Verify that applyChangesToCRDTDoc was called with the changes.
+			expect( mockSyncConfig.applyChangesToCRDTDoc ).toHaveBeenCalledWith(
+				expect.any( Y.Doc ),
+				changes
+			);
+
+			// Verify that the record metadata was updated.
+			const ydoc = capturedDoc as unknown as Y.Doc;
+			const metadataMap = ydoc.getMap( RECORD_METADATA_MAP_KEY );
+			expect( metadataMap.get( SAVED_AT_KEY ) ).toBeGreaterThanOrEqual(
+				now
+			);
+			expect( metadataMap.get( SAVED_BY_KEY ) ).toBe( ydoc.clientID );
+		} );
 	} );
 
 	describe( 'CRDT doc observation', () => {
diff --git a/packages/sync/src/types.ts b/packages/sync/src/types.ts
@@ -63,6 +63,7 @@ export type ProviderCreator = (
 export interface RecordHandlers {
 	editRecord: ( data: Partial< ObjectData > ) => void;
 	getEditedRecord: () => Promise< ObjectData >;
+	refetchRecord: () => Promise< void >;
 	saveRecord: () => Promise< void >;
 }
 
@@ -97,7 +98,8 @@ export interface SyncManager {
 		objectType: ObjectType,
 		objectId: ObjectID,
 		changes: Partial< ObjectData >,
-		origin: string
+		origin: string,
+		isSave?: boolean
 	) => void;
 }
 

Original file line number	Diff line number	Diff line change
`@@ -170,6 +170,7 @@ describe( 'getEntityRecord', () => {`
`170`	`170`	`{`
`171`	`171`	`editRecord: expect.any( Function ),`
`172`	`172`	`getEditedRecord: expect.any( Function ),`
	`173`	`+ refetchRecord: expect.any( Function ),`
`173`	`174`	`saveRecord: expect.any( Function ),`
`174`	`175`	`}`
`175`	`176`	`);`
`@@ -222,6 +223,7 @@ describe( 'getEntityRecord', () => {`
`222`	`223`	`{`
`223`	`224`	`editRecord: expect.any( Function ),`
`224`	`225`	`getEditedRecord: expect.any( Function ),`
	`226`	`+ refetchRecord: expect.any( Function ),`
`225`	`227`	`saveRecord: expect.any( Function ),`
`226`	`228`	`}`
`227`	`229`	`);`