@wordpress/core-data 7.37.1-next.ba3aee3a2.0 → 7.38.0

package/src/utils/crdt.ts

@@ -1,7 +1,7 @@
 /**
  * External dependencies
  */
-import fastDeepEqual from 'fast-deep-equal/es6';
+import fastDeepEqual from 'fast-deep-equal/es6/index.js';
 
 /**
  * WordPress dependencies
@@ -26,8 +26,16 @@ import {
 	CRDT_RECORD_MAP_KEY,
 	WORDPRESS_META_KEY_FOR_CRDT_DOC_PERSISTENCE,
 } from '../sync';
-import type { WPBlockSelection, WPSelection } from '../types';
-
+import type { WPSelection } from '../types';
+import {
+	createYMap,
+	getRootMap,
+	isYMap,
+	type YMapRecord,
+	type YMapWrap,
+} from './crdt-utils';
+
+// Changes that can be applied to a post entity record.
 export type PostChanges = Partial< Post > & {
 	blocks?: Block[];
 	excerpt?: Post[ 'excerpt' ] | string;
@@ -35,8 +43,24 @@ export type PostChanges = Partial< Post > & {
 	title?: Post[ 'title' ] | string;
 };
 
-// Hold a reference to the last known selection to help compute Y.Text deltas.
-let lastSelection: WPBlockSelection | null = null;
+// A post record as represented in the CRDT document (Y.Map).
+export interface YPostRecord extends YMapRecord {
+	author: number;
+	blocks: YBlocks;
+	comment_status: string;
+	date: string | null;
+	excerpt: string;
+	featured_media: number;
+	format: string;
+	meta: YMapWrap< YMapRecord >;
+	ping_status: string;
+	slug: string;
+	status: string;
+	sticky: boolean;
+	tags: number[];
+	template: string;
+	title: string;
+}
 
 // Properties that are allowed to be synced for a post.
 const allowedPostProperties = new Set< string >( [
@@ -47,8 +71,8 @@ const allowedPostProperties = new Set< string >( [
 	'excerpt',
 	'featured_media',
 	'format',
-	'ping_status',
 	'meta',
+	'ping_status',
 	'slug',
 	'status',
 	'sticky',
@@ -74,7 +98,7 @@ export function defaultApplyChangesToCRDTDoc(
 	ydoc: CRDTDoc,
 	changes: ObjectData
 ): void {
-	const ymap = ydoc.getMap( CRDT_RECORD_MAP_KEY );
+	const ymap = getRootMap( ydoc, CRDT_RECORD_MAP_KEY );
 
 	Object.entries( changes ).forEach( ( [ key, newValue ] ) => {
 		// Cannot serialize function values, so cannot sync them.
@@ -82,17 +106,12 @@ export function defaultApplyChangesToCRDTDoc(
 			return;
 		}
 
-		// Set the value in the root document.
-		function setValue< T = unknown >( updatedValue: T ): void {
-			ymap.set( key, updatedValue );
-		}
-
 		switch ( key ) {
 			// Add support for additional data types here.
 
 			default: {
 				const currentValue = ymap.get( key );
-				mergeValue( currentValue, newValue, setValue );
+				updateMapValue( ymap, key, currentValue, newValue );
 			}
 		}
 	} );
@@ -112,60 +131,60 @@ export function applyPostChangesToCRDTDoc(
 	changes: PostChanges,
 	_postType: Type // eslint-disable-line @typescript-eslint/no-unused-vars
 ): void {
-	const ymap = ydoc.getMap( CRDT_RECORD_MAP_KEY );
+	const ymap = getRootMap< YPostRecord >( ydoc, CRDT_RECORD_MAP_KEY );
 
-	Object.entries( changes ).forEach( ( [ key, newValue ] ) => {
+	Object.keys( changes ).forEach( ( key ) => {
 		if ( ! allowedPostProperties.has( key ) ) {
 			return;
 		}
 
+		const newValue = changes[ key ];
+
 		// Cannot serialize function values, so cannot sync them.
 		if ( 'function' === typeof newValue ) {
 			return;
 		}
 
-		// Set the value in the root document.
-		function setValue< T = unknown >( updatedValue: T ): void {
-			ymap.set( key, updatedValue );
-		}
-
 		switch ( key ) {
 			case 'blocks': {
-				let currentBlocks = ymap.get( 'blocks' ) as YBlocks;
+				let currentBlocks = ymap.get( key );
 
 				// Initialize.
 				if ( ! ( currentBlocks instanceof Y.Array ) ) {
 					currentBlocks = new Y.Array< YBlock >();
-					setValue( currentBlocks );
+					ymap.set( key, currentBlocks );
 				}
 
 				// Block[] from local changes.
 				const newBlocks = ( newValue as PostChanges[ 'blocks' ] ) ?? [];
 
+				// Block changes from typing are bundled with a 'selection' update.
+				// Pass the resulting cursor position to the mergeCrdtBlocks function.
+				const cursorPosition =
+					changes.selection?.selectionStart?.offset ?? null;
+
 				// Merge blocks does not need `setValue` because it is operating on a
 				// Yjs type that is already in the Y.Doc.
-				mergeCrdtBlocks( currentBlocks, newBlocks, lastSelection );
+				mergeCrdtBlocks( currentBlocks, newBlocks, cursorPosition );
 				break;
 			}
 
 			case 'excerpt': {
-				const currentValue = ymap.get( 'excerpt' ) as
-					| string
-					| undefined;
+				const currentValue = ymap.get( 'excerpt' );
 				const rawNewValue = getRawValue( newValue );
 
-				mergeValue( currentValue, rawNewValue, setValue );
+				updateMapValue( ymap, key, currentValue, rawNewValue );
 				break;
 			}
 
 			// "Meta" is overloaded term; here, it refers to post meta.
 			case 'meta': {
-				let metaMap = ymap.get( 'meta' ) as Y.Map< unknown >;
+				let metaMap = ymap.get( 'meta' );
 
 				// Initialize.
-				if ( ! ( metaMap instanceof Y.Map ) ) {
-					metaMap = new Y.Map();
-					setValue( metaMap );
+				if ( ! isYMap( metaMap ) ) {
+					metaMap = createYMap< YMapRecord >();
+					ymap.set( 'meta', metaMap );
 				}
 
 				// Iterate over each meta property in the new value and merge it if it
@@ -176,12 +195,11 @@ export function applyPostChangesToCRDTDoc(
 							return;
 						}
 
-						mergeValue(
+						updateMapValue(
+							metaMap,
+							metaKey,
 							metaMap.get( metaKey ), // current value in CRDT
-							metaValue, // new value from changes
-							( updatedMetaValue: unknown ): void => {
-								metaMap.set( metaKey, updatedMetaValue );
-							}
+							metaValue // new value from changes
 						);
 					}
 				);
@@ -195,13 +213,13 @@ export function applyPostChangesToCRDTDoc(
 					break;
 				}
 
-				const currentValue = ymap.get( 'slug' ) as string;
-				mergeValue( currentValue, newValue, setValue );
+				const currentValue = ymap.get( key );
+				updateMapValue( ymap, key, currentValue, newValue );
 				break;
 			}
 
 			case 'title': {
-				const currentValue = ymap.get( 'title' ) as string | undefined;
+				const currentValue = ymap.get( key );
 
 				// Copy logic from prePersistPostType to ensure that the "Auto
 				// Draft" template title is not synced.
@@ -210,27 +228,22 @@ export function applyPostChangesToCRDTDoc(
 					rawNewValue = '';
 				}
 
-				mergeValue( currentValue, rawNewValue, setValue );
+				updateMapValue( ymap, key, currentValue, rawNewValue );
 				break;
 			}
 
-			// Add support for additional data types here.
+			// Add support for additional properties here.
 
 			default: {
 				const currentValue = ymap.get( key );
-				mergeValue( currentValue, newValue, setValue );
+				updateMapValue( ymap, key, currentValue, newValue );
 			}
 		}
 	} );
-
-	// Update the lastSelection for use in computing Y.Text deltas.
-	if ( 'selection' in changes ) {
-		lastSelection = changes.selection?.selectionStart ?? null;
-	}
 }
 
 export function defaultGetChangesFromCRDTDoc( crdtDoc: CRDTDoc ): ObjectData {
-	return crdtDoc.getMap( CRDT_RECORD_MAP_KEY ).toJSON();
+	return getRootMap( crdtDoc, CRDT_RECORD_MAP_KEY ).toJSON();
 }
 
 /**
@@ -248,7 +261,7 @@ export function getPostChangesFromCRDTDoc(
 	editedRecord: Post,
 	_postType: Type // eslint-disable-line @typescript-eslint/no-unused-vars
 ): PostChanges {
-	const ymap = ydoc.getMap( CRDT_RECORD_MAP_KEY );
+	const ymap = getRootMap< YPostRecord >( ydoc, CRDT_RECORD_MAP_KEY );
 
 	let allowedMetaChanges: Post[ 'meta' ] = {};
 
@@ -394,19 +407,25 @@ function getRawValue( value?: unknown ): string | undefined {
 	return undefined;
 }
 
-function haveValuesChanged< ValueType = any >(
-	currentValue: ValueType,
-	newValue: ValueType
+function haveValuesChanged< ValueType >(
+	currentValue: ValueType | undefined,
+	newValue: ValueType | undefined
 ): boolean {
 	return ! fastDeepEqual( currentValue, newValue );
 }
 
-function mergeValue< ValueType = any >(
-	currentValue: ValueType,
-	newValue: ValueType,
-	setValue: ( value: ValueType ) => void
+function updateMapValue< T extends YMapRecord, K extends keyof T >(
+	map: YMapWrap< T >,
+	key: K,
+	currentValue: T[ K ] | undefined,
+	newValue: T[ K ] | undefined
 ): void {
-	if ( haveValuesChanged< ValueType >( currentValue, newValue ) ) {
-		setValue( newValue );
+	if ( undefined === newValue ) {
+		map.delete( key );
+		return;
+	}
+
+	if ( haveValuesChanged< T[ K ] >( currentValue, newValue ) ) {
+		map.set( key, newValue );
 	}
 }

package/src/utils/test/crdt.ts

@@ -19,17 +19,17 @@ import {
 	applyPostChangesToCRDTDoc,
 	getPostChangesFromCRDTDoc,
 	type PostChanges,
+	type YPostRecord,
 } from '../crdt';
 import type { YBlock, YBlocks } from '../crdt-blocks';
+import { createYMap, getRootMap, type YMapWrap } from '../crdt-utils';
 import type { Post, Type } from '../../entity-types';
 
 describe( 'crdt', () => {
 	let doc: Y.Doc;
-	let map: Y.Map< string | object | YBlocks >;
 
 	beforeEach( () => {
 		doc = new Y.Doc();
-		map = doc.getMap( CRDT_RECORD_MAP_KEY );
 		jest.clearAllMocks();
 	} );
 
@@ -40,6 +40,12 @@ describe( 'crdt', () => {
 	describe( 'applyPostChangesToCRDTDoc', () => {
 		const mockPostType = {} as Type;
 
+		let map: YMapWrap< YPostRecord >;
+
+		beforeEach( () => {
+			map = getRootMap< YPostRecord >( doc, CRDT_RECORD_MAP_KEY );
+		} );
+
 		it( 'applies simple property changes', () => {
 			const changes = {
 				title: 'New Title',
@@ -164,7 +170,7 @@ describe( 'crdt', () => {
 				},
 			};
 
-			const metaMap = new Y.Map< unknown >();
+			const metaMap = createYMap();
 			metaMap.set( 'some_meta', 'old value' );
 			map.set( 'meta', metaMap );
 
@@ -180,7 +186,7 @@ describe( 'crdt', () => {
 				},
 			};
 
-			const metaMap = new Y.Map< unknown >();
+			const metaMap = createYMap();
 			metaMap.set( 'some_meta', 'old value' );
 			map.set( 'meta', metaMap );
 
@@ -201,9 +207,9 @@ describe( 'crdt', () => {
 
 			applyPostChangesToCRDTDoc( doc, changes, mockPostType );
 
-			const metaMap = map.get( 'meta' ) as Y.Map< unknown >;
+			const metaMap = map.get( 'meta' );
 			expect( metaMap ).toBeInstanceOf( Y.Map );
-			expect( metaMap.get( 'custom_field' ) ).toBe( 'value' );
+			expect( metaMap?.get( 'custom_field' ) ).toBe( 'value' );
 		} );
 	} );
 
@@ -216,7 +222,10 @@ describe( 'crdt', () => {
 			},
 		} as unknown as Type;
 
+		let map: YMapWrap< YPostRecord >;
+
 		beforeEach( () => {
+			map = getRootMap< YPostRecord >( doc, CRDT_RECORD_MAP_KEY );
 			map.set( 'title', 'CRDT Title' );
 			map.set( 'status', 'draft' );
 			map.set( 'date', '2025-01-01' );
@@ -344,9 +353,9 @@ describe( 'crdt', () => {
 		} );
 
 		it( 'includes meta in changes', () => {
-			map.set( 'meta', {
-				public_meta: 'new value',
-			} );
+			const metaMap = createYMap();
+			metaMap.set( 'public_meta', 'new value' );
+			map.set( 'meta', metaMap );
 
 			const editedRecord = {
 				meta: {
@@ -366,9 +375,9 @@ describe( 'crdt', () => {
 		} );
 
 		it( 'includes non-single meta in changes', () => {
-			map.set( 'meta', {
-				public_meta: [ 'value', 'value 2' ],
-			} );
+			const metaMap = createYMap();
+			metaMap.set( 'public_meta', [ 'value', 'value 2' ] );
+			map.set( 'meta', metaMap );
 
 			const editedRecord = {
 				meta: {
@@ -388,10 +397,13 @@ describe( 'crdt', () => {
 		} );
 
 		it( 'excludes disallowed meta keys in changes', () => {
-			map.set( 'meta', {
-				public_meta: 'new value',
-				[ WORDPRESS_META_KEY_FOR_CRDT_DOC_PERSISTENCE ]: 'exclude me',
-			} );
+			const metaMap = createYMap();
+			metaMap.set( 'public_meta', 'new value' );
+			metaMap.set(
+				WORDPRESS_META_KEY_FOR_CRDT_DOC_PERSISTENCE,
+				'exclude me'
+			);
+			map.set( 'meta', metaMap );
 
 			const editedRecord = {
 				meta: {