feat(descriptors): minimize blocking the UI

This adds a "pauser" into the descriptor converter which avoids blocking
the UI by scheduling idle callbacks. See the comment in the code for
justification and potential follow-up work.

Author: judofyr

packages/@sanity/schema/src/descriptors/convert.ts

@@ -51,6 +51,64 @@ const MAX_DEPTH_UKNOWN = 5
 
 type UnknownRecord<T> = {[P in keyof T]: unknown}
 
+/**
+ * A helper class for doing work without interrupting the UI.
+ * This also records the duration that did indeed block the UI.
+ */
+class Pauser {
+  durations: number[]
+  lastNow: number | undefined
+
+  constructor(durations: number[]) {
+    this.durations = durations
+  }
+
+  /**
+   * Yields control back to the UI.
+   */
+  pause(): Promise<void> {
+    return new Promise((resolve) => {
+      const done = () => {
+        this._recordDuration()
+        resolve()
+      }
+
+      if (typeof requestIdleCallback === 'function') {
+        requestIdleCallback(done, {timeout: 10})
+      } else if (typeof requestAnimationFrame === 'function') {
+        requestAnimationFrame(done)
+      } else {
+        setTimeout(done, 0)
+      }
+    })
+  }
+
+  /**
+   * This should be invoked when it's done in order to record the final duration as well.
+   **/
+  end() {
+    this._recordDuration()
+  }
+
+  /** Executes a function for each item while pausing in between. */
+  async map<T, U>(arr: T[], fn: (val: T) => U): Promise<U[]> {
+    const result: U[] = []
+    for (const val of arr) {
+      await this.pause()
+      result.push(fn(val))
+    }
+    return result
+  }
+
+  _recordDuration() {
+    const now = performance.now()
+    if (this.lastNow) {
+      this.durations.push(now - this.lastNow)
+    }
+    this.lastNow = now
+  }
+}
+
 export class DescriptorConverter {
   cache: WeakMap<Schema, SetSynchronization<RegistryType>> = new WeakMap()
 
@@ -59,18 +117,49 @@ export class DescriptorConverter {
    *
    * This is automatically cached in a weak map.
    */
-  async get(schema: Schema): Promise<SetSynchronization<RegistryType>> {
+  async get(
+    schema: Schema,
+    opts?: {
+      /** If present, this array will be populated with the durations we blocked the UI. */
+      pauseDurations?: number[]
+    },
+  ): Promise<SetSynchronization<RegistryType>> {
+    /*
+      Converting the schema into a descriptor consists of two parts:
+
+      1. Traversing the type into a descriptor.
+      2. Serializing the descriptor, including SHA256 hashing.
+
+      Note that only (2) can be done in a background worker since the type
+      itself isn't serializable (which is a requirement for a background
+      worker). In addition, we expect (2) to scale in the same way as (1): If it
+      takes X milliseconds to traverse the type into a descriptor it will
+      probably take c*X milliseconds to serialize it.
+
+      This means that a background worker actually doesn't give us that much
+      value. A huge type will either way be expensive to convert from a type to
+      a descriptor. Therefore this function currently only avoid blocking by
+      only processing each type separately.
+
+      If we want to minimize the blocking further we would have to restructure
+      this converter to be able to convert the types asynchronously and _then_
+      it might make sense to the serialization step itself in a background
+      worker.
+    */
     let value = this.cache.get(schema)
     if (value) return value
 
+    const pauseDurations = opts?.pauseDurations || []
+    const pauser = new Pauser(pauseDurations)
+
     const options: Options = {
       fields: new Map(),
       duplicateFields: new Map(),
       arrayElements: new Map(),
       duplicateArrayElements: new Map(),
     }
 
-    const namedTypes = schema.getLocalTypeNames().map((name) => {
+    const namedTypes = await pauser.map(schema.getLocalTypeNames(), (name) => {
       const typeDef = convertTypeDef(schema.get(name)!, name, options)
       return {name, typeDef}
     })
@@ -90,23 +179,27 @@ export class DescriptorConverter {
 
     // Now we can build the de-duplicated objects:
     for (const [fieldDef, key] of options.duplicateFields.entries()) {
+      await pauser.pause()
       builder.addObject('sanity.schema.hoisted', {key, value: {...fieldDef}})
     }
 
     for (const [arrayElem, key] of options.duplicateArrayElements.entries()) {
+      await pauser.pause()
       builder.addObject('sanity.schema.hoisted', {key, value: {...arrayElem}})
     }
 
     for (const namedType of namedTypes) {
+      await pauser.pause()
       builder.addObject('sanity.schema.namedType', namedType)
     }
 
     if (schema.parent) {
-      builder.addSet(await this.get(schema.parent))
+      builder.addSet(await this.get(schema.parent, {pauseDurations}))
     }
 
     value = builder.build('sanity.schema.registry')
     this.cache.set(schema, value)
+    pauser.end()
     return value
   }
 }

packages/sanity/src/core/config/uploadSchema.ts

@@ -5,6 +5,7 @@ import {
 } from '@sanity/schema/_internal'
 import {type Schema} from '@sanity/types'
 import debugit from 'debug'
+import {max, sum} from 'lodash'
 import {firstValueFrom} from 'rxjs'
 
 import {isDev} from '../environment'
@@ -13,7 +14,7 @@ import {DESCRIPTOR_CONVERTER} from '../schema'
 
 const debug = debugit('sanity:config')
 
-const TOGGLE = 'toggle.schema.upload'
+const TOGGLE = 'toggle.schema.upload-pause'
 
 async function isEnabled(client: SanityClient): Promise<boolean> {
   if (typeof process !== 'undefined' && process?.env?.SANITY_STUDIO_SCHEMA_DESCRIPTOR) {
@@ -72,12 +73,24 @@ export async function uploadSchema(
   // The second step is then to actually synchronize it. This is a multi-step
   // process where it tries to synchronize as much as possible in each step.
 
+  const pauseDurations: number[] = []
   const before = performance.now()
-  const sync = await DESCRIPTOR_CONVERTER.get(schema)
+  const sync = await DESCRIPTOR_CONVERTER.get(schema, {pauseDurations})
   const after = performance.now()
+
+  const totalPause = sum(pauseDurations) || 0
+  const maxPause = max(pauseDurations) || 0
+  const avgPause = pauseDurations.length === 0 ? 0 : totalPause / pauseDurations.length
   const duration = after - before
+
   if (duration > 1000) {
-    console.warn(`Building schema for synchronization took more than 1 second (${duration}ms)`)
+    console.warn(`Building schema for synchronization took more than 1 second (${totalPause}ms)`)
+  }
+
+  if (maxPause > 100) {
+    console.warn(
+      `Building schema for synchronization blocked UI for more than 100ms (${maxPause}ms)`,
+    )
   }
 
   const descriptorId = sync.set.id
@@ -87,13 +100,22 @@ export async function uploadSchema(
 
   const claimRequest: ClaimRequest = {descriptorId, contextKey}
 
+  const clientTimings = {
+    convertSchema: duration,
+    convertSchemaPauseTotal: totalPause,
+    convertSchemaPauseMax: maxPause,
+    convertSchemaPauseAvg: avgPause,
+  }
+
   const claimResponse = await client.request<ClaimResponse>({
     uri: '/descriptors/claim',
     method: 'POST',
     body: claimRequest,
     headers: {
       // We mirror the format of Server-Timing: https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Server-Timing
-      'Client-Timing': `convertSchema;dur=${duration}`,
+      'Client-Timing': Object.entries(clientTimings)
+        .map(([name, dur]) => `${name};dur=${dur}`)
+        .join(','),
     },
   })