Add a "debug" mode to expose performance timing of sync functions

chriszarate · chriszarate · commit 734045e50aa1 · 2026-01-28T13:51:58.000-05:00
diff --git a/packages/sync/README.md b/packages/sync/README.md
@@ -46,6 +46,10 @@ Y.Map key representing the Y.Doc client ID of the user who performed the last sa
 
 The sync manager orchestrates the lifecycle of syncing entity records. It creates Yjs documents, connects to providers, creates awareness instances, and coordinates with the `core-data` store.
 
+_Parameters_
+
+-   _debug_ Whether to enable performance and debug logging.
+
 ### Delta
 
 Deltas are used to calculate incremental Y.Text updates.
diff --git a/packages/sync/src/manager.ts b/packages/sync/src/manager.ts
@@ -12,6 +12,7 @@ import {
 	CRDT_RECORD_METADATA_MAP_KEY as RECORD_METADATA_KEY,
 	CRDT_RECORD_METADATA_SAVED_AT_KEY as SAVED_AT_KEY,
 } from './config';
+import { logPerformanceTiming, passThru } from './performance';
 import { createPersistedCRDTDoc, getPersistedCrdtDoc } from './persistence';
 import { getProviderCreators } from './providers';
 import type {
@@ -50,12 +51,28 @@ interface EntityState {
 	ydoc: CRDTDoc;
 }
 
+/**
+ * Get the entity ID for the given object type and object ID.
+ *
+ * @param {ObjectType}    objectType Object type.
+ * @param {ObjectID|null} objectId   Object ID.
+ */
+function getEntityId(
+	objectType: ObjectType,
+	objectId: ObjectID | null
+): EntityID {
+	return `${ objectType }_${ objectId }`;
+}
+
 /**
  * The sync manager orchestrates the lifecycle of syncing entity records. It
  * creates Yjs documents, connects to providers, creates awareness instances,
  * and coordinates with the `core-data` store.
+ *
+ * @param debug Whether to enable performance and debug logging.
  */
-export function createSyncManager(): SyncManager {
+export function createSyncManager( debug = false ): SyncManager {
+	const debugWrap = debug ? logPerformanceTiming : passThru;
 	const collectionStates: Map< ObjectType, CollectionState > = new Map();
 	const entityStates: Map< EntityID, EntityState > = new Map();
 
@@ -118,6 +135,15 @@ export function createSyncManager(): SyncManager {
 			return; // Already bootstrapped.
 		}
 
+		handlers = {
+			addUndoMeta: debugWrap( handlers.addUndoMeta ),
+			editRecord: debugWrap( handlers.editRecord ),
+			getEditedRecord: debugWrap( handlers.getEditedRecord ),
+			refetchRecord: debugWrap( handlers.refetchRecord ),
+			restoreUndoMeta: debugWrap( handlers.restoreUndoMeta ),
+			saveRecord: debugWrap( handlers.saveRecord ),
+		};
+
 		const ydoc = createYjsDoc( { objectType } );
 		const recordMap = ydoc.getMap( RECORD_KEY );
 		const recordMetaMap = ydoc.getMap( RECORD_METADATA_KEY );
@@ -149,7 +175,7 @@ export function createSyncManager(): SyncManager {
 				return;
 			}
 
-			void updateEntityRecord( objectType, objectId );
+			void internal.updateEntityRecord( objectType, objectId );
 		};
 
 		const onRecordMetaUpdate = (
@@ -209,7 +235,7 @@ export function createSyncManager(): SyncManager {
 		recordMetaMap.observe( onRecordMetaUpdate );
 
 		// Get and apply the persisted CRDT document, if it exists.
-		applyPersistedCrdtDoc( objectType, objectId, record );
+		internal.applyPersistedCrdtDoc( objectType, objectId, record );
 	}
 
 	/**
@@ -310,19 +336,6 @@ export function createSyncManager(): SyncManager {
 		updateCRDTDoc( objectType, null, {}, origin, { isSave: true } );
 	}
 
-	/**
-	 * Get the entity ID for the given object type and object ID.
-	 *
-	 * @param {ObjectType}    objectType Object type.
-	 * @param {ObjectID|null} objectId   Object ID.
-	 */
-	function getEntityId(
-		objectType: ObjectType,
-		objectId: ObjectID | null
-	): EntityID {
-		return `${ objectType }_${ objectId }`;
-	}
-
 	/**
 	 * Get the awareness instance for the given object type and object ID, if supported.
 	 *
@@ -353,7 +366,7 @@ export function createSyncManager(): SyncManager {
 	 * @param {ObjectID}   objectId   Object ID.
 	 * @param {ObjectData} record     Entity record representing this object type.
 	 */
-	function applyPersistedCrdtDoc(
+	function _applyPersistedCrdtDoc(
 		objectType: ObjectType,
 		objectId: ObjectID,
 		record: ObjectData
@@ -506,7 +519,7 @@ export function createSyncManager(): SyncManager {
 	 * @param {ObjectType} objectType Object type of record to update.
 	 * @param {ObjectID}   objectId   Object ID of record to update.
 	 */
-	async function updateEntityRecord(
+	async function _updateEntityRecord(
 		objectType: ObjectType,
 		objectId: ObjectID
 	): Promise< void > {
@@ -557,16 +570,23 @@ export function createSyncManager(): SyncManager {
 		return createPersistedCRDTDoc( entityState.ydoc );
 	}
 
+	// Collect internal functions so that they can be wrapped before calling.
+	const internal = {
+		applyPersistedCrdtDoc: debugWrap( _applyPersistedCrdtDoc ),
+		updateEntityRecord: debugWrap( _updateEntityRecord ),
+	};
+
+	// Wrap and return the public API.
 	return {
-		createMeta: createEntityMeta,
-		getAwareness,
-		load: loadEntity,
-		loadCollection,
+		createMeta: debugWrap( createEntityMeta ),
+		getAwareness: debugWrap( getAwareness ),
+		load: debugWrap( loadEntity ),
+		loadCollection: debugWrap( loadCollection ),
 		// Use getter to ensure we always return the current value of `undoManager`.
 		get undoManager(): SyncUndoManager | undefined {
 			return undoManager;
 		},
-		unload: unloadEntity,
-		update: updateCRDTDoc,
+		unload: debugWrap( unloadEntity ),
+		update: debugWrap( updateCRDTDoc ),
 	};
 }
diff --git a/packages/sync/src/performance.ts b/packages/sync/src/performance.ts
@@ -0,0 +1,31 @@
+/**
+ * Wraps a function and logs the time it takes to execute.
+ *
+ * @param fn - The function to be wrapped.
+ */
+export function logPerformanceTiming<
+	Params extends Array< unknown >,
+	ReturnType = void,
+>( fn: ( ...args: Params ) => ReturnType ): typeof fn {
+	return function ( this: unknown, ...args: Params ): ReturnType {
+		const start = performance.now();
+		const result = fn.apply( this, args );
+		const end = performance.now();
+
+		// eslint-disable-next-line no-console
+		console.log( `${ fn.name } took ${ ( end - start ).toFixed( 2 ) } ms` );
+
+		return result;
+	};
+}
+
+/**
+ * A pass-through function that invokes the provided function with its arguments
+ * without moidyfing its type.
+ *
+ * @param fn - The function to be invoked.
+ */
+export function passThru< T extends ( ...args: any[] ) => any >( fn: T ): T {
+	return ( ( ...args: Parameters< T > ): ReturnType< T > =>
+		fn( ...args ) ) as T;
+}
