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
- yarn
- pnpm
npm install @bedrock-core/observable
yarn add @bedrock-core/observable
pnpm add @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
setthat changed the value.batchdelivers at its end, in order;debouncepublishes a derived value after a scheduled quiet period. - Replacement updates,
Object.isby default — replace object values when changing them. Observables do not clone or freeze values; in-place mutation is not detected. Passequalsto customize equality. - Listed dependencies —
computedandeffecttake their dependencies explicitly: no proxy, no tracking, no cost on reads. - Isolated listeners — one that throws is reported with the observable's
labeland skipped; the rest still run, so one screen's bug cannot stop another's update. ReadonlyObservable<T>— whatcomputedreturns and what anything exposing a value it owns hands out, so a consumer cannotsetwhat is not theirs.last— an event as a value: the most recent payload,undefinedbefore the first, from any signal withsubscribe.debounce— the latest source value after a quiet period, with caller-provided scheduling and cancellation.
Next steps
signal— transient payloads with typed subscriptionsobservable— a value withget,setandsubscribecomputed— a read-only value derived from otherseffect— run something now and whenever a dependency changesbatch— several writes, one notification eachlast— an event's most recent payload as a valuedebounce— publish the latest value after a quiet periodafterTicks— schedule delivery in Minecraft tickstoSignal— convert native event subscriptions to cleanup-return signalstoNative— bind one to a data-driven form's own observable