silence

Exclude an action’s ref reads from active dependency collection.

silenceComputed and Effects

Exclude an action’s ref reads from active dependency collection.

Overview

The silence function is an internal utility provided by Regor. It is used to temporarily suspend the normal behavior of collecting refs within the callback of watchEffect, computed or collectRefs. This allows you to perform actions on refs excluded from normal behavior of watchEffect, computed or collectRefs. It is useful in specific scenarios when you want to prevent ref collection for some refs.

Try it live

See which reads become dependenciesLive API

Live preview

Current refs: 1 / 10

Last effect: 1 + 10 = 11

1Effect runs

0Effect cleanups

1Collected dependencies

The silenced read does not rerun the effect. collectRefs captures one dependency and returns the sampled sum: 11.

effects.ts

import { collectRefs, html, ref, silence, watchEffect } from 'regor'

export function createEffects(interactive = false) {
  const tracked = ref(1),
    untracked = ref(10)
  const runs = ref(0),
    cleanups = ref(0),
    result = ref('')
  const collected = ref(0),
    inspected = ref(0)
  watchEffect((onCleanup) => {
    const value = tracked()
    silence(() => {
      runs(runs() + 1)
      result(`${value} + ${untracked()} = ${value + untracked()}`)
    })
    onCleanup?.(() => silence(() => cleanups(cleanups() + 1)))
  })
  const inspect = () => {
    const read = collectRefs(() => tracked() + silence(() => untracked()))
    collected(read.refs.length)
    inspected(read.value)
  }
  inspect()
  return {
    interactive,
    tracked,
    untracked,
    runs,
    cleanups,
    result,
    collected,
    inspected,
    inspect,
    bumpTracked: () => tracked(tracked() + 1),
    bumpUntracked: () => untracked(untracked() + 1),
  }
}

export const effectsTemplate = html` <div class="guide-demo">
  <div class="guide-session-bar">
    <button type="button" @click="bumpTracked" :disabled="!interactive">
      Update tracked</button
    ><button type="button" @click="bumpUntracked" :disabled="!interactive">
      Update silenced read</button
    ><button type="button" @click="inspect" :disabled="!interactive">
      Collect the reads
    </button>
  </div>
  <p>Current refs: <strong>{{ tracked }} / {{ untracked }}</strong></p>
  <p class="guide-event">Last effect: {{ result }}</p>
  <div class="guide-metrics">
    <div><output>{{ runs }}</output><span>Effect runs</span></div>
    <div><output>{{ cleanups }}</output><span>Effect cleanups</span></div>
    <div>
      <output>{{ collected }}</output><span>Collected dependencies</span>
    </div>
  </div>
  <p class="guide-hint">
    The silenced read does not rerun the effect. collectRefs captures one
    dependency and returns the sampled sum: {{ inspected }}.
  </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)
}

Change the tracked and silenced values separately. Collect the reads to inspect the dependency count and returned result.

Usage

Silencing Ref Collection

To temporarily suspend ref collection within the callback of watchEffect, computed or collectRefs, you can wrap your action function with silence.

import { silence, watchEffect, ref } from 'regor'

const myRef = ref(5)
const anotherRef = ref(7)

watchEffect(() => {
  console.log(myRef.value) // myRef is collected and will be observed.

  silence(() => {
    anotherRef.value = 10 // anotherRef is excluded from the ref collection and will not be observed.
    console.log(anotherRef.value)
  })
})

myRef.value = 8 // watchEffect's callback will be invoked.
anotherRef.value = 9 // watchEffect's callback will not be invoked

Parameters

action: A function that performs some logic within the callback of watchEffect, computed or collectRefs but temporarily suspends ref collection. The function is executed within a scope where ref collection is silenced.

Return Value

The silence function returns the result of the action function, allowing you to access the outcome of the action.

Example

import { silence, watchEffect, ref } from 'regor'

const myRef = ref(5)

watchEffect(() => {
  console.log(myRef.value) // Outputs 5

  silence(() => {
    myRef.value = 10
    console.log(myRef.value) // Outputs 10
  })

  console.log(myRef.value) // Outputs 10
})

Silence controls collection, not notifications

Refs still hold reactive values. Their reads inside silence are excluded from the surrounding collector.