pause

Pause automatic notifications from a ref while retaining its stored value.

pauseReactivity

Pause automatic notifications from a ref while retaining its stored value.

Overview

The pause function is used to pause the automatic triggering of observers for a specific ref. When a ref is paused, its observers are temporarily deactivated, and changes to the ref's value will not trigger observer callbacks until it is resumed using the resume function.

Try it live

Separate stored values from notificationsLive API

Live preview

0Stored value

0Observer's last value

0Callbacks

Notifications are active.

Pause, write, then resume and trigger. The stored value and the last observed value show different responsibilities.

notifications.ts

import { html, observe, pause, ref, resume, trigger } from 'regor'

export function createNotifications(interactive = false) {
  const source = ref(0),
    stored = ref(0),
    seen = ref(0),
    callbacks = ref(0),
    paused = ref(false)
  observe(source, (value) => {
    seen(value)
    callbacks(callbacks() + 1)
  })
  return {
    interactive,
    stored,
    seen,
    callbacks,
    paused,
    write: () => {
      source(source() + 1)
      stored(source())
    },
    pauseSource: () => {
      pause(source)
      paused(true)
    },
    resumeSource: () => {
      resume(source)
      paused(false)
    },
    notify: () => trigger(source),
  }
}

export const notificationsTemplate = html` <div class="guide-demo">
  <div class="guide-session-bar">
    <button type="button" @click="write" :disabled="!interactive">
      Write +1</button
    ><button
      type="button"
      @click="pauseSource"
      :disabled="!interactive || paused"
    >
      Pause</button
    ><button
      type="button"
      @click="resumeSource"
      :disabled="!interactive || !paused"
    >
      Resume</button
    ><button type="button" @click="notify" :disabled="!interactive || paused">
      Trigger
    </button>
  </div>
  <div class="guide-metrics">
    <div><output>{{ stored }}</output><span>Stored value</span></div>
    <div><output>{{ seen }}</output><span>Observer's last value</span></div>
    <div><output>{{ callbacks }}</output><span>Callbacks</span></div>
  </div>
  <p class="guide-event">
    Notifications are {{ paused ? 'paused' : 'active' }}.
  </p>
  <p class="guide-hint">
    Pause, write, then resume and trigger. The stored value and the last
    observed value show different responsibilities.
  </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)
}

Pause, write, resume, and trigger. Compare the stored value with what the observer last received.

Usage

Pausing Observers

To pause the observers of a specific ref, call the pause function with the ref as the source argument. This will temporarily deactivate the observers associated with the ref.

import { pause, ref, observe } from 'regor'

const myRef = ref(5)

observe(myRef, () => {
  console.log('Observer triggered:', myRef.value)
})

myRef.value = 10 // The observer is automatically triggered

// Pause the observers of myRef
pause(myRef)

myRef.value = 15 // The observer is not triggered

// Resume the observers of myRef
resume(myRef)

myRef.value = 20 // The observer is triggered again

// Outputs:
// Observer triggered: 10
// Observer triggered: 20

Parameters

source: The ref for which you want to pause the automatic triggering of observers.

Stored state and notifications are separate

While paused, writes can change the stored value without updating observers. Inspect both in the preview.

Notes

The pause function is useful when you want to temporarily disable observer notifications for a ref, allowing you to make multiple changes to the ref's value without triggering observers in between.
Pausing a ref does not prevent manual triggering of observers using the trigger function.
To resume the observers of a paused ref, use the resume function.