watch

useBloc connects a bloc to a React component. But state often needs to reach code that has no component to render: a logger, an analytics pipeline, a localStorage sync, a <canvas> driven by an imperative library, or a test assertion. watch is the escape hatch for those cases — it observes one or more blocs outside of React and runs a callback whenever their state changes.

watch fires on every change, not only on what you read

Unlike useBloc, watch does not auto-track which properties your callback reads. It subscribes to the bloc’s full state and invokes your callback on every change (and once immediately). If you need to react only to a specific field, compare it yourself inside the callback, or use the lower-level channel.subscribe(interest, cb) API. Auto-tracking is a React render-time feature — see Tracking.

watch(bloc, callback)

Observe one or more blocs outside React and run a callback on every state change.

// Single bloc
function watch<T extends StateContainerConstructor>(
  bloc: T | BlocRef<T>,
  callback: (bloc: InstanceType<T>) => void | typeof watch.STOP,
): () => void;

// Multiple blocs
function watch<T extends readonly BlocInput[]>(
  blocs: T,
  callback: (blocs: ExtractInstances<T>) => void | typeof watch.STOP,
): () => void;

Parameter	Type	Required	Description
bloc / blocs	T | BlocRef<T> or readonly BlocInput[]	yes	A bloc class (resolves to the default instance), an instance(Class, id) reference, or a readonly array of either.
callback	(bloc: InstanceType<T>) => void | typeof watch.STOP	yes	Runs once immediately with the current instance(s), then on every subsequent state change. Return watch.STOP to tear down the subscription from inside the callback.

Returns: a stop() function. Calling it unsubscribes and is idempotent — calling it more than once is safe.

Behavior. watch acquires each input from the registry with a counted ref — creating the instance if it does not exist yet. That ref keeps an otherwise-unused bloc alive for as long as the watch is active, and is dropped when you call stop() or return watch.STOP. If the instance is disposed elsewhere anyway (e.g. by clearAll()), watch re-acquires and resubscribes on the next microtask, then runs the callback again. Subscriptions are coalesced per microtask flush — several synchronous mutations produce a single callback run — so callbacks land asynchronously after emit(). The callback fires once immediately on setup with the current state, then again after every subsequent change.

import { watch } from '@blac/core';
import { Cubit } from '@blac/core';

class UserCubit extends Cubit<{ name: string }> {
  constructor() {
    super({ name: 'Alice' });
  }
}

const stop = watch(UserCubit, (user) => {
  console.log('User state changed:', user.state.name);
});

// later — e.g. in a cleanup or on teardown of your module:
stop();

instance(BlocClass, args?)

Create a reference to a specific keyed bloc instance for use with watch.

function instance<T extends StateContainerConstructor>(
  BlocClass: T,
  args?: ExtractArgs<T>,
): BlocRef<T>;

Parameter	Type	Required	Description
BlocClass	T extends StateContainerConstructor	yes	The bloc class to reference.
args	ExtractArgs<T>	no	The args identifying the instance — the same args you pass to useBloc. Resolved to a key via static key/structural hash.

Returns: a BlocRef<T> — a lightweight reference object that tells watch which keyed instance to resolve.

Behavior. By default watch(SomeCubit, ...) resolves the default instance. Wrap with instance(Class, args) to target the instance keyed by those args.

import { watch, instance } from '@blac/core';
import { Cubit } from '@blac/core';

class UserCubit extends Cubit<{ name: string }, { userId: string }> {
  static key = (a: { userId: string }) => a.userId;
  constructor() {
    super({ name: '' });
  }
}

const stop = watch(instance(UserCubit, { userId: 'user-123' }), (user) => {
  console.log(user.state.name);
});

Stopping a watch

A watch lives until you stop it. There are two ways, and forgetting both is the most common watch bug.

Call the returned stop function

import { watch } from '@blac/core';
import { Cubit } from '@blac/core';

class UserCubit extends Cubit<{ name: string }> {
  constructor() {
    super({ name: '' });
  }
}

const stop = watch(UserCubit, (user) => {
  console.log(user.state.name);
});

// later — e.g. in a cleanup, useEffect teardown, or on teardown of your module:
stop();

Return watch.STOP from the callback

For one-shot or self-terminating watches, return the watch.STOP sentinel and the subscription tears itself down:

import { watch } from '@blac/core';
import { Cubit } from '@blac/core';

class UserCubit extends Cubit<{ onboardingComplete: boolean }> {
  constructor() {
    super({ onboardingComplete: false });
  }
}

declare function runOnce(): void;

watch(UserCubit, (user) => {
  if (user.state.onboardingComplete) {
    runOnce();
    return watch.STOP; // stop after the condition is met
  }
});

Common mistake: leaking the watcher

A watch you never stop keeps its subscription forever, holding a reference to the bloc and re-running your callback for the life of the process. Always either store and call stop(), or return watch.STOP once the work is done. Inside React, prefer useBloc over watch; if you must watch from an effect, return stop from the effect:

import { useEffect } from 'react';
import { watch } from '@blac/core';

// (in a React component)
useEffect(() => {
  // const stop = watch(AuthCubit, (auth) => persistToken(auth.state.token));
  // return stop; // tear down on unmount
}, []);

Watching multiple blocs

Pass a readonly array to observe several blocs at once — the callback fires when any of them changes.

import { watch } from '@blac/core';
import { Cubit } from '@blac/core';

class UserCubit extends Cubit<{ name: string }> {
  constructor() {
    super({ name: '' });
  }
}

class SettingsCubit extends Cubit<{ theme: string }> {
  constructor() {
    super({ theme: 'light' });
  }
}

declare function syncToServer(name: string, theme: string): void;

// Watch several blocs at once; the callback fires when any of them changes.
const stop = watch([UserCubit, SettingsCubit] as const, ([user, settings]) => {
  syncToServer(user.state.name, settings.state.theme);
});

When to use watch

Scenario	Use
A React component needs state	useBloc
Non-React side effects (logging, analytics, syncing)	watch
Bridging a bloc to imperative / non-React UI	watch
Test assertions on state over time	watch
You need selective, path-scoped observation	container.channel.subscribe(interest, cb)

Examples

Logging state changes

import { watch } from '@blac/core';
import { Cubit } from '@blac/core';

interface CartItem {
  price: number;
}

class CartCubit extends Cubit<{ items: CartItem[] }> {
  constructor() {
    super({ items: [] });
  }

  get total() {
    return this.state.items.reduce((sum, i) => sum + i.price, 0);
  }
}

declare const logger: { info(msg: string, data: unknown): void };

const stop = watch(CartCubit, (cart) => {
  logger.info('cart changed', {
    itemCount: cart.state.items.length,
    total: cart.total, // getters work here too
  });
});

Bridging to non-React code

Drive an imperative library (a chart, a map, a canvas) from bloc state without a React wrapper:

import { watch } from '@blac/core';
import { Cubit } from '@blac/core';

class MetricsCubit extends Cubit<{ series: number[] }> {
  constructor() {
    super({ series: [] });
  }
}

declare function createChart(el: HTMLElement): {
  setData(series: number[]): void;
  destroy(): void;
};

function attachChart(el: HTMLElement) {
  const chart = createChart(el);
  const stop = watch(MetricsCubit, (metrics) => {
    chart.setData(metrics.state.series);
  });
  // hand the caller a teardown that stops the watch and the chart
  return () => {
    stop();
    chart.destroy();
  };
}

watch vs channel.subscribe

Both observe a single container outside React; both fire once per microtask flush. The differences:

• watch gives you the instance (so getters and methods are available), accepts multiple blocs, supports instance() references and the watch.STOP sentinel, and fires once immediately on setup.
• channel.subscribe is the lower-level path-scoped surface on a container’s channel. You pass an interest thunk (the paths you care about, or ALL_PATHS for everything) and a callback that fires when a matching path changes. It does not fire on setup and gives you the changed path set rather than the instance — read state off the container yourself. Prefer watch for whole-state observation; reach for channel.subscribe when you need path-scoped interest.

import { watch, ensure, ALL_PATHS } from '@blac/core';
import { Cubit } from '@blac/core';

class UserCubit extends Cubit<{ name: string }> {
  constructor() {
    super({ name: '' });
  }
}

const user = ensure(UserCubit);

// channel.subscribe: path-scoped, fires on change (not on setup)
const unsub = user.channel.subscribe(
  () => ALL_PATHS,
  () => {
    console.log(user.state.name);
  },
);

// watch: the instance, fires immediately, supports STOP and multiple blocs
const stop = watch(UserCubit, (u) => {
  console.log(u.state.name);
});

The channel.subscribe(interest, cb) signature

channel.subscribe is inherited from StructuralContainer (the structural layer under every Cubit) — watch is a thin wrapper around it (channel.subscribe(() => ALL_PATHS, ...) plus instance resolution, an immediate fire, and watch.STOP).

subscribe(interest: () => PathSet, cb: (dirty: PathSet) => void): () => void

Parameter	Type	Description
interest	() => PathSet	A thunk returning the region this subscriber cares about, re-evaluated lazily, once per flush. Return ALL_PATHS to be woken by everything.
cb	(dirty: PathSet) => void	Runs when dirty intersects interest(). container.state already reflects the new value when this fires.
returns	() => void	Idempotent unsubscribe.

ALL_PATHS (value) and the PathSet type are public, re-exported from @blac/core specifically so plugins can compose channel subscriptions. Minting a specific Set<PathId> requires the per-class PathInterner, which is @internal and not re-exported — so the only portable interest you can build from outside the framework is ALL_PATHS. The fine-grained Set<PathId> form is what useBloc’s render tracker assembles for itself; see Tracking.

Errors from a subscriber’s cb or interest thunk are collected, not swallowed: after all subscribers for a flush have run, a single error rethrows as-is, and multiple throw together as an AggregateError.

Reach for channel.subscribe only when composing directly on the channel (plugins, devtools, infra):

Where you are	Use	What you get
Inside a React component	useBloc	Auto-tracked, path-scoped re-renders; lifecycle tied to mount.
Outside React (logging, sync, imperative UI, tests)	watch	The bloc instance, fires once immediately, multi-bloc, watch.STOP.
Building a plugin / devtools / infra	channel.subscribe	Raw PathSet deltas, no instance sugar, no immediate fire.

watch vs observe

Both take a callback that runs on state change. They differ in setup semantics:

• watch resolves the instance itself via acquire (creating it if needed), fires the callback once immediately with the current state, and holds a counted registry ref until you stop it — so it keeps the instance alive.
• observe takes a live instance you already hold, does not fire on subscribe, and adds no registry ref — so it never keeps the instance alive. It is for hand-managed subscriptions against an instance whose lifecycle you’re not driving through watch.

The ref is the difference that bites: an observed instance can be disposed under you at refcount 0 (the subscription then tears itself down), whereas a watched one cannot go away while the watch is active.

Both are microtask-coalesced: several synchronous emits in one tick deliver a single callback call with the latest state.

import { watch, observe, ensure } from '@blac/core';
import { Cubit } from '@blac/core';

class UserCubit extends Cubit<{ name: string }> {
  constructor() {
    super({ name: 'Alice' });
  }
}

const user = ensure(UserCubit);

// observe: no immediate fire, no ref — for an instance you already hold
const stopObserving = observe(user, (state) => {
  console.log('changed:', state.name);
});

// watch: fires immediately with the current state, resolves its own instance
const stopWatching = watch(UserCubit, (u) => {
  console.log('current:', u.state.name);
});

stopObserving();
stopWatching();

See also

• System Events — the microtask flush and coalescing model behind watch
• Tracking — why watch does not auto-track, and how useBloc does
• Dependency Tracking — the React side of selective re-renders