observeMany

Subscribe to multiple refs and receive their current values in one callback.

observeManyObservation and Batch

Subscribe to multiple refs and receive their current values in one callback.

Overview

The observeMany function allows you to create observers that react to changes in multiple ref objects simultaneously. This is useful for handling side effects or updating UI elements based on changes in multiple reactive data sources.

Try it live

Watch subscriptions start and stopLive API

Live preview

Source values: 0 / 0

0observe · left callbacks

0observeMany · callbacks

2Observers on left

After stopping, source values still change but the callback counts stay put.

observation.ts

import { html, observe, observeMany, observerCount, ref } from 'regor'

export function createObservation(interactive = false) {
  const left = ref(0),
    right = ref(0)
  const single = ref(0),
    multiple = ref(0),
    listening = ref(true)
  const count = ref(0)
  const stopSingle = observe(left, () => single(single() + 1))
  const stopMany = observeMany([left, right], () => multiple(multiple() + 1))
  // These source refs are not rendered directly, so this count isolates our observers.
  const refresh = () => count(observerCount(left))
  const values = ref('0 / 0')
  const bumpLeft = () => {
    left(left() + 1)
    values(`${left()} / ${right()}`)
    refresh()
  }
  const bumpRight = () => {
    right(right() + 1)
    values(`${left()} / ${right()}`)
    refresh()
  }
  const stop = () => {
    stopSingle()
    stopMany()
    listening(false)
    refresh()
  }
  refresh()
  return {
    interactive,
    values,
    single,
    multiple,
    listening,
    count,
    bumpLeft,
    bumpRight,
    stop,
  }
}

export const observationTemplate = html` <div class="guide-demo">
  <div class="guide-session-bar">
    <button type="button" @click="bumpLeft" :disabled="!interactive">
      Update left</button
    ><button type="button" @click="bumpRight" :disabled="!interactive">
      Update right</button
    ><button type="button" @click="stop" :disabled="!interactive || !listening">
      Stop observers
    </button>
  </div>
  <p>Source values: <strong>{{ values }}</strong></p>
  <div class="guide-metrics">
    <div>
      <output>{{ single }}</output><span>observe · left callbacks</span>
    </div>
    <div>
      <output>{{ multiple }}</output><span>observeMany · callbacks</span>
    </div>
    <div><output>{{ count }}</output><span>Observers on left</span></div>
  </div>
  <p class="guide-hint">
    After stopping, source values still change but the callback counts stay put.
  </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)
}

Update either source, then stop the observers. Their callback counts stop while source values keep changing.

Usage

Creating Observers for Multiple Refs

To create an observer for multiple ref objects, you can use the observeMany function, passing in an array of ref objects and a callback function.

import { observeMany, ref } from 'regor'

const ref1 = ref('Hello')
const ref2 = ref('World')

// Create an observer for multiple refs
const stopObserving = observeMany([ref1, ref2], (newValues) => {
  console.log('Values changed:', newValues)
})

Parameters

sources: An array of ref objects you want to observe for changes.
observer: A callback function that will be triggered whenever any of the ref values change. The callback receives an array of the current values of all observed refs.
init (optional): If true, the observer will be immediately invoked with the current values of the refs when it's created.

Return Value

The observeMany function returns a stopObserving function that allows you to stop the observer when it's no longer needed. Calling stopObserving will unsubscribe the observer from all the observed ref objects.

Example

import { observeMany, ref } from 'regor'

const ref1 = ref('Hello')
const ref2 = ref('World')

// Create an observer for multiple refs with init set to true
const stopObserving = observeMany(
  [ref1, ref2],
  (newValues) => {
    console.log('Values changed:', newValues)
  },
  true,
)

// Later, when the observer is no longer needed, stop it
stopObserving()

Multiple sources can cause multiple callbacks

A callback can run when either source changes. Batch related writes when you need grouped notifications.