[ReactiveElement] Adds scheduleUpdate()

[sorvell]

Fixes #2091. Fixes an issue where performUpdate was doing double duty as (1) make the element complete a pending update synchronously and (2) override to control update timing. Here scheduleUpdate() is added to satisfy (2), reserving (1) for performUpdate(). Since by default scheduleUpdate() just returns the value of performUpdate() this should not break any existing code. However, the docs are updated to recommend that for scheduling scheduleUpdate() be implemented in favor of performUpdate().

[changeset-bot]

🦋 Changeset detected

Latest commit: b2beae2

The changes in this PR will be included in the next version bump.

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[github-actions]

📊 Tachometer Benchmark Results

Summary

nop-update

• lit-html-kitchen-sink: unsure 🔍 -6% - +5% (-2.47ms - +2.31ms)
  ^{this-change vs tip-of-tree}

render

• lit-element-list: unsure 🔍 -4% - +3% (-5.13ms - +3.44ms)
  ^{this-change vs tip-of-tree}
• lit-html-kitchen-sink: unsure 🔍 -4% - +7% (-2.03ms - +3.30ms)
  ^{this-change vs tip-of-tree}
• lit-html-repeat: unsure 🔍 -3% - +5% (-0.46ms - +0.71ms)
  ^{this-change vs tip-of-tree}
• lit-html-template-heavy: unsure 🔍 -3% - +4% (-2.46ms - +3.51ms)
  ^{this-change vs tip-of-tree}
• reactive-element-list: unsure 🔍 -3% - +3% (-2.79ms - +2.09ms)
  ^{this-change vs tip-of-tree}

update

• lit-element-list: unsure 🔍 -3% - +2% (-28.79ms - +24.74ms)
  ^{this-change vs tip-of-tree}
• lit-html-kitchen-sink: unsure 🔍 -8% - +4% (-9.54ms - +5.54ms)
  ^{this-change vs tip-of-tree}
• lit-html-repeat: unsure 🔍 -1% - +4% (-6.40ms - +19.55ms)
  ^{this-change vs tip-of-tree}
• lit-html-template-heavy: unsure 🔍 -1% - +7% (-1.70ms - +11.27ms)
  ^{this-change vs tip-of-tree}
• reactive-element-list: unsure 🔍 -2% - +3% (-20.19ms - +35.27ms)
  ^{this-change vs tip-of-tree}

update-reflect

• lit-element-list: unsure 🔍 -4% - +3% (-36.55ms - +25.77ms)
  ^{this-change vs tip-of-tree}
• reactive-element-list: unsure 🔍 -1% - +4% (-13.80ms - +41.29ms)
  ^{this-change vs tip-of-tree}

Results

lit-element-list

• Browser: chrome-headless 92.0.4515.131
• Sample size: 50
• Built by: Benchmarks #1780

• Commit: 5a9eed8

render

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	115.53ms - 121.46ms	-	unsure 🔍 -4% - +3% -5.13ms - +3.44ms	faster ✔ 21% - 26% 31.09ms - 40.81ms
tip-of-tree tip-of-tree	116.25ms - 122.44ms	unsure 🔍 -3% - +4% -3.44ms - +5.13ms	-	faster ✔ 20% - 26% 30.17ms - 40.05ms
previous-release previous-release	150.60ms - 158.30ms	slower ❌ 26% - 35% 31.09ms - 40.81ms	slower ❌ 25% - 34% 30.17ms - 40.05ms	-

update

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	989.03ms - 1025.35ms	-	unsure 🔍 -3% - +2% -28.79ms - +24.74ms	faster ✔ 6% - 11% 63.70ms - 120.58ms
tip-of-tree tip-of-tree	989.55ms - 1028.87ms	unsure 🔍 -2% - +3% -24.74ms - +28.79ms	-	faster ✔ 6% - 11% 60.70ms - 119.53ms
previous-release previous-release	1077.45ms - 1121.22ms	slower ❌ 6% - 12% 63.70ms - 120.58ms	slower ❌ 6% - 12% 60.70ms - 119.53ms	-

update-reflect

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	998.13ms - 1043.22ms	-	unsure 🔍 -4% - +3% -36.55ms - +25.77ms	faster ✔ 3% - 9% 33.23ms - 100.11ms
tip-of-tree tip-of-tree	1004.56ms - 1047.57ms	unsure 🔍 -3% - +4% -25.77ms - +36.55ms	-	faster ✔ 3% - 9% 28.53ms - 94.03ms
previous-release previous-release	1062.65ms - 1112.04ms	slower ❌ 3% - 10% 33.23ms - 100.11ms	slower ❌ 3% - 9% 28.53ms - 94.03ms	-

lit-html-kitchen-sink

• Browser: chrome-headless 92.0.4515.131
• Sample size: 30
• Built by: Benchmarks #1780

• Commit: 5a9eed8

render

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	46.82ms - 51.05ms	-	unsure 🔍 -4% - +7% -2.03ms - +3.30ms	faster ✔ 12% - 21% 6.85ms - 12.22ms
tip-of-tree tip-of-tree	46.68ms - 49.92ms	unsure 🔍 -7% - +4% -3.30ms - +2.03ms	-	faster ✔ 14% - 21% 7.85ms - 12.49ms
previous-release previous-release	56.81ms - 60.13ms	slower ❌ 13% - 26% 6.85ms - 12.22ms	slower ❌ 16% - 26% 7.85ms - 12.49ms	-

update

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	117.39ms - 126.96ms	-	unsure 🔍 -8% - +4% -9.54ms - +5.54ms	unsure 🔍 -9% - +0% -11.63ms - +0.73ms
tip-of-tree tip-of-tree	118.34ms - 130.01ms	unsure 🔍 -5% - +8% -5.54ms - +9.54ms	-	unsure 🔍 -8% - +3% -10.47ms - +3.57ms
previous-release previous-release	123.72ms - 131.54ms	unsure 🔍 -1% - +10% -0.73ms - +11.63ms	unsure 🔍 -3% - +9% -3.57ms - +10.47ms	-

nop-update

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	41.96ms - 45.83ms	-	unsure 🔍 -6% - +5% -2.47ms - +2.31ms	slower ❌ 2% - 13% 0.67ms - 5.23ms
tip-of-tree tip-of-tree	42.58ms - 45.37ms	unsure 🔍 -5% - +6% -2.31ms - +2.47ms	-	slower ❌ 3% - 12% 1.18ms - 4.87ms
previous-release previous-release	39.74ms - 42.15ms	faster ✔ 2% - 12% 0.67ms - 5.23ms	faster ✔ 3% - 11% 1.18ms - 4.87ms	-

lit-html-repeat

• Browser: chrome-headless 92.0.4515.131
• Sample size: 30
• Built by: Benchmarks #1780

• Commit: 5a9eed8

render

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	14.21ms - 15.13ms	-	unsure 🔍 -3% - +5% -0.46ms - +0.71ms	faster ✔ 13% - 21% 2.18ms - 3.72ms
tip-of-tree tip-of-tree	14.18ms - 14.91ms	unsure 🔍 -5% - +3% -0.71ms - +0.46ms	-	faster ✔ 14% - 21% 2.36ms - 3.79ms
previous-release previous-release	17.00ms - 18.24ms	slower ❌ 14% - 26% 2.18ms - 3.72ms	slower ❌ 16% - 26% 2.36ms - 3.79ms	-

update

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	445.65ms - 463.37ms	-	unsure 🔍 -1% - +4% -6.40ms - +19.55ms	faster ✔ 27% - 30% 166.18ms - 193.76ms
tip-of-tree tip-of-tree	438.45ms - 457.41ms	unsure 🔍 -4% - +1% -19.55ms - +6.40ms	-	faster ✔ 27% - 31% 172.35ms - 200.74ms
previous-release previous-release	623.91ms - 645.04ms	slower ❌ 36% - 43% 166.18ms - 193.76ms	slower ❌ 38% - 45% 172.35ms - 200.74ms	-

lit-html-template-heavy

• Browser: chrome-headless 92.0.4515.131
• Sample size: 50
• Built by: Benchmarks #1780

• Commit: 5a9eed8

render

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	78.46ms - 82.50ms	-	unsure 🔍 -3% - +4% -2.46ms - +3.51ms	faster ✔ 13% - 18% 12.04ms - 17.26ms
tip-of-tree tip-of-tree	77.76ms - 82.15ms	unsure 🔍 -4% - +3% -3.51ms - +2.46ms	-	faster ✔ 13% - 19% 12.43ms - 17.92ms
previous-release previous-release	93.48ms - 96.78ms	slower ❌ 15% - 22% 12.04ms - 17.26ms	slower ❌ 15% - 23% 12.43ms - 17.92ms	-

update

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	168.57ms - 178.98ms	-	unsure 🔍 -1% - +7% -1.70ms - +11.27ms	faster ✔ 6% - 13% 10.96ms - 25.16ms
tip-of-tree tip-of-tree	165.11ms - 172.86ms	unsure 🔍 -6% - +1% -11.27ms - +1.70ms	-	faster ✔ 9% - 15% 16.65ms - 29.04ms
previous-release previous-release	187.00ms - 196.66ms	slower ❌ 6% - 15% 10.96ms - 25.16ms	slower ❌ 10% - 17% 16.65ms - 29.04ms	-

reactive-element-list

• Browser: chrome-headless 92.0.4515.131
• Sample size: 50
• Built by: Benchmarks #1780

• Commit: 5a9eed8

render

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	78.07ms - 81.27ms	-	unsure 🔍 -3% - +3% -2.79ms - +2.09ms	unsure 🔍 -2% - +3% -1.40ms - +2.59ms
tip-of-tree tip-of-tree	78.18ms - 81.87ms	unsure 🔍 -3% - +4% -2.09ms - +2.79ms	-	unsure 🔍 -2% - +4% -1.25ms - +3.14ms
previous-release previous-release	77.88ms - 80.27ms	unsure 🔍 -3% - +2% -2.59ms - +1.40ms	unsure 🔍 -4% - +2% -3.14ms - +1.25ms	-

update

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	999.00ms - 1041.05ms	-	unsure 🔍 -2% - +3% -20.19ms - +35.27ms	unsure 🔍 -2% - +3% -19.72ms - +34.02ms
tip-of-tree tip-of-tree	994.40ms - 1030.56ms	unsure 🔍 -3% - +2% -35.27ms - +20.19ms	-	unsure 🔍 -2% - +2% -25.03ms - +24.24ms
previous-release previous-release	996.14ms - 1029.61ms	unsure 🔍 -3% - +2% -34.02ms - +19.72ms	unsure 🔍 -2% - +2% -24.24ms - +25.03ms	-

update-reflect

Version	Avg time	vs this-change	vs tip-of-tree tip-of-tree	vs previous-release previous-release
this-change	1068.70ms - 1111.23ms	-	unsure 🔍 -1% - +4% -13.80ms - +41.29ms	unsure 🔍 -1% - +4% -14.36ms - +45.98ms
tip-of-tree tip-of-tree	1058.72ms - 1093.73ms	unsure 🔍 -4% - +1% -41.29ms - +13.80ms	-	unsure 🔍 -2% - +3% -25.58ms - +29.71ms
previous-release previous-release	1052.76ms - 1095.56ms	unsure 🔍 -4% - +1% -45.98ms - +14.36ms	unsure 🔍 -3% - +2% -29.71ms - +25.58ms	-

_{tachometer-reporter-action v2 for Benchmarks}

[kevinpschaaf]

Add that it should return a promise when overridden.

[sorvell]

Done.