Skip to main content

observable

@bedrock-core/observable provides reactive values and transient signals. Values expose get and subscribe, with set on writable sources; signals expose cleanup-return subscriptions and retain no current value.

What is @bedrock-core/observable?​

Config leaves, database documents, Sync state handles and imported addon API observables use this value contract. computed, effect and debounce compose with those values; last retains the latest payload from a standard or native signal.

The main entry is engine-independent, including toSignal, which adapts callback-removal event sources. @bedrock-core/observable/minecraft also exports the adapter and adds afterTicks for tick scheduling and toNative for data-driven UI observables.

Install​

npm install @bedrock-core/observable

Import reactive primitives from the main entry and Minecraft adapters from /minecraft:

import { observable, signal, toSignal, computed, effect, batch, last, debounce } from '@bedrock-core/observable';
import { afterTicks, toNative } from '@bedrock-core/observable/minecraft';

The /minecraft entry imports @minecraft/server (>=2.0.0) and @minecraft/server-ui (>=2.1.0). Both are optional peer dependencies when using only the main entry.

Usage​

import { observable, computed, effect, batch, last } from '@bedrock-core/observable';

const phase = observable<'lobby' | 'fight' | 'end'>('lobby');
const alive = observable(new Set<string>());
const aliveCount = computed(() => alive.get().size, [alive]);

effect(() => bossBar.setTitle(phase.get()), [phase]); // runs now and on every change
aliveCount.subscribe((next, prev) => scoreboard.set(next));

batch(() => { // one notification per observable
phase.set('end');
alive.set(new Set());
});

const spawn = last(world.afterEvents.playerSpawn); // undefined, then each payload

Debounce in Minecraft ticks​

import { debounce, observable } from '@bedrock-core/observable';
import { afterTicks } from '@bedrock-core/observable/minecraft';

const count = observable(0);
const settledCount = debounce(count, afterTicks(5));

settledCount.subscribe((next, prev) => console.warn(`${prev} -> ${next}`));
count.set(1);
count.set(2);
count.set(3);

Each change restarts the wait. After five quiet ticks, the listener receives (3, 0). count.get() changes immediately; settledCount.get() retains the last published value until delivery. Call settledCount.dispose() when its owner ends to cancel pending delivery and release the source subscription.

What you get​

  • Synchronous by default — a listener runs inside the set that changed the value. batch delivers at its end, in order; debounce publishes a derived value after a scheduled quiet period.
  • Replacement updates, Object.is by default — replace object values when changing them. Observables do not clone or freeze values; in-place mutation is not detected. Pass equals to customize equality.
  • Listed dependencies — computed and effect take their dependencies explicitly: no proxy, no tracking, no cost on reads.
  • Isolated listeners — one that throws is reported with the observable's label and skipped; the rest still run, so one screen's bug cannot stop another's update.
  • ReadonlyObservable<T> — what computed returns and what anything exposing a value it owns hands out, so a consumer cannot set what is not theirs.
  • last — an event as a value: the most recent payload, undefined before the first, from any signal with subscribe.
  • debounce — the latest source value after a quiet period, with caller-provided scheduling and cancellation.

Next steps​

  • signal — transient payloads with typed subscriptions
  • observable — a value with get, set and subscribe
  • computed — a read-only value derived from others
  • effect — run something now and whenever a dependency changes
  • batch — several writes, one notification each
  • last — an event's most recent payload as a value
  • debounce — publish the latest value after a quiet period
  • afterTicks — schedule delivery in Minecraft ticks
  • toSignal — convert native event subscriptions to cleanup-return signals
  • toNative — bind one to a data-driven form's own observable