endBatch

Close a manual batch and flush notifications when the outer batch ends.

endBatchObservation and Batch

Close a manual batch and flush notifications when the outer batch ends.

Overview

The endBatch function is used in conjunction with the startBatchfunction to end a batch of ref updates and notify observers of the changes made during the batch. Batching ref updates using startBatch and endBatch can improve application performance by reducing the number of observer notifications and triggers during a series of updates.

Try it live

Same writes, different notification countsLive API

Live preview

0Source value

0Observer callbacks

Choose an update strategy.

Each action adds three. Compare notification counts for the same amount of state change.

batching.ts

import { batch, endBatch, html, observe, ref, startBatch } from 'regor'

export function createBatching(interactive = false) {
  const source = ref(0),
    notifications = ref(0),
    value = ref(0)
  const mode = ref('Choose an update strategy.')
  observe(source, () => notifications(notifications() + 1))
  const update = (strategy: string) => {
    notifications(0)
    const writes = () => {
      for (let i = 0; i < 3; i++) source(source() + 1)
    }
    if (strategy === 'batch') batch(writes)
    else if (strategy === 'manual') {
      startBatch()
      try {
        writes()
      } finally {
        endBatch()
      }
    } else writes()
    value(source())
    mode(
      strategy === 'plain'
        ? 'Three separate writes'
        : strategy === 'batch'
          ? 'One batch callback'
          : 'startBatch + finally endBatch',
    )
  }
  return {
    interactive,
    notifications,
    value,
    mode,
    plain: () => update('plain'),
    grouped: () => update('batch'),
    manual: () => update('manual'),
  }
}

export const batchingTemplate = html` <div class="guide-demo">
  <div class="guide-session-bar">
    <button type="button" @click="plain" :disabled="!interactive">
      Three plain writes</button
    ><button type="button" @click="grouped" :disabled="!interactive">
      Use batch</button
    ><button type="button" @click="manual" :disabled="!interactive">
      Start / end batch
    </button>
  </div>
  <div class="guide-metrics api-metrics-pair">
    <div><output>{{ value }}</output><span>Source value</span></div>
    <div>
      <output>{{ notifications }}</output><span>Observer callbacks</span>
    </div>
  </div>
  <p class="guide-event" role="status">{{ mode }}</p>
  <p class="guide-hint">
    Each action adds three. Compare notification counts for the same amount of
    state change.
  </p>
</div>`

browser.ts

import { createApp, RegorConfig, useScope } from 'regor'
import { apiExamples } from './examples'

const element = document.getElementById('api-demo')
const name = element?.dataset.example
if (element && name && Object.hasOwn(apiExamples, name)) {
  const example = apiExamples[name as keyof typeof apiExamples]
  const scope = useScope<object>(() => example.create(true))
  const config =
    'config' in scope.context && scope.context.config instanceof RegorConfig
      ? scope.context.config
      : undefined
  createApp(scope, { element, template: example.template }, config)
}

Each action adds three to one ref. Compare plain writes, batch, and a manual start/end pair.

Usage

Ending a Batch

To end a batch of ref updates, call the endBatch function. When a batch is ended, observers are notified of the changes made to refs during the batch, but this notification is performed only once, optimizing performance.

import { batch, startBatch, endBatch, ref } from 'regor'

const myRef1 = ref(5)
const myRef2 = ref(10)

startBatch() // Start a batch

myRef1.value = 15
myRef2.value = 20

endBatch() // End the batch and notify observers

// Observers are notified only once at the end of the batch
// Outputs:
// Observer triggered: 20

Pair the start and end

Prefer batch for a callback-sized update. Use a manual pair only when it makes ownership clearer.

Notes

The endBatch function is used in conjunction with the startBatch function to finalize a batch of ref updates. It ensures that observers are notified of the ref changes made during the batch in an optimized manner, reducing unnecessary notifications.
Batching updates with startBatch and endBatch can significantly improve the performance of your application, especially when multiple changes are made to refs in rapid succession. It minimizes the number of observer notifications and triggers.
It's important to call the endBatch function to conclude a batch and ensure that observers are informed of the changes made during the batch.
Important: When using the batch functions, keep in mind that reads of refs within the batch can return potentially stale or outdated values due to pausing auto-updates. Ensure that your code logic accounts for this situation when reading refs within a batch.