Real-time collaboration: Refetch entity when it is saved by a peer

Author: chriszarate

packages/core-data/src/actions.js

@@ -712,6 +712,20 @@ export const saveEntityRecord =
 						true,
 						edits
 					);
+					if (
+						window.__experimentalEnableSync &&
+						entityConfig.syncConfig
+					) {
+						if ( globalThis.IS_GUTENBERG_PLUGIN ) {
+							getSyncManager()?.update(
+								`${ kind }/${ name }`,
+								recordId,
+								updatedRecord,
+								LOCAL_EDITOR_ORIGIN,
+								true // isSave
+							);
+						}
+					}
 				}
 			} catch ( _error ) {
 				hasError = true;

packages/core-data/src/resolvers.js

@@ -215,6 +215,15 @@ export const getEntityRecord =
 									name,
 									key
 								),
+							// Refect 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(

packages/core-data/src/test/resolvers.js

@@ -175,6 +175,7 @@ describe( 'getEntityRecord', () => {
 			{
 				editRecord: expect.any( Function ),
 				getEditedRecord: expect.any( Function ),
+				refetchRecord: expect.any( Function ),
 				saveRecord: expect.any( Function ),
 			}
 		);
@@ -229,6 +230,7 @@ describe( 'getEntityRecord', () => {
 			{
 				editRecord: expect.any( Function ),
 				getEditedRecord: expect.any( Function ),
+				refetchRecord: expect.any( Function ),
 				saveRecord: expect.any( Function ),
 			}
 		);

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
 

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';
 

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,

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';
@@ -75,6 +78,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 => {
@@ -100,6 +105,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;
+				}
+			} );
+		};
+
 		if ( syncConfig.supports?.undo ) {
 			undoManager.addToScope( recordMap );
 		}
@@ -128,6 +155,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 );
@@ -226,12 +254,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 );
@@ -244,6 +274,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 );
 	}
 

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';
@@ -540,6 +543,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(
@@ -555,10 +571,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', () => {
@@ -615,6 +638,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', () => {

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 >;
 }
 
@@ -96,7 +97,8 @@ export interface SyncManager {
 		objectType: ObjectType,
 		objectId: ObjectID,
 		changes: Partial< ObjectData >,
-		origin: string
+		origin: string,
+		isSave?: boolean
 	) => void;
 }