Bloc communication

Real apps are made of several focused blocs — a cart, a shipping calculator, an auth session — that need to read each other’s state or trigger each other’s behavior. depend() lets one Cubit declare a dependency on another and read its state (or call its methods) without holding a hard reference and without the two classes importing each other’s instances. The dependency is resolved lazily from the registry, so each bloc stays decoupled from how the other is created or keyed.

Mental model

depend() records “I need to know about that bloc, but I don’t own it” and hands you a handle that fetches the live instance on demand — .untracked() for a plain read or method call, .track() to subscribe the reading component reactively.

depend(Type)

protected depend<T extends StateContainerConstructor>(
  Type: T,
  defaultArgs?: ExtractArgs<T>,
): DepHandle<T>

Parameter	Type	Required	Description
Type	T extends StateContainerConstructor	yes	The state-container class to depend on.
defaultArgs	ExtractArgs<T>	no	Args identifying which keyed instance to resolve when an accessor is called without its own args.

Returns: a DepHandle<T> with two accessors, both resolving lazily on each call (not at declaration time) — so a dep that was disposed and recreated is transparently picked up on the next call:

• .untracked(options?) — resolves the instance without subscribing anything. Use for imperative method calls and reads that shouldn’t wake the reader.
• .track(options?) — resolves the instance and, inside a React render, opts the current consumer into automatic cross-bloc re-renders (see below).

Both accept an optional { args } to resolve a specific keyed instance at call time, overriding defaultArgs.

depend() does not auto-subscribe

Declaring this.shipping = this.depend(ShippingCubit) only records the dependency. this.shipping.untracked().state.rate is a plain read — it does not make CartCubit re-emit when shipping changes. Reactivity is supplied by whoever reads the derived value: a React component via .track() (or the auto-tracking proxy), or non-React code via watch(). This is deliberate — a naive always-on bridge would loop on mutual deps.

Auto-tracking with .track()

A getter that calls .track() on the handle opts the current render’s consumer into a subscription on the dependency too, with no second useBloc call:

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

class PriceBloc extends Cubit<{ amount: number }> {
  constructor() {
    super({ amount: 100 });
  }
}

class CartBloc extends Cubit<{ qty: number }> {
  private price = this.depend(PriceBloc);
  constructor() {
    super({ qty: 2 });
  }

  get total() {
    const [priceState] = this.price.track(); // opt in to cross-bloc tracking
    return this.state.qty * priceState.amount;
  }
}

// In a React component:
const [, cart] = useBloc(CartBloc);
return <span>{cart.total}</span>; // re-renders when qty OR price.amount changes

handle.track() returns [trackedState, depProxy]: trackedState is what you read fields off of to record leaf paths, and depProxy is the dep wrapped in a tracking proxy so calling one of its getters records that getter’s own this.state reads too (deep chains work the same way — A.track(B) inside whose getter there’s B.track(C) wakes a reader of A on a C change). A few things worth knowing about .track():

• Render-aware. Outside a render (an event handler, a plain method) it degrades to a live read with no subscription — safe to call from anywhere.
• Conditional is fine. Calling it conditionally inside a getter adds/drops the subscription each render, based on whether that render actually took the branch.
• Mutual deps are cycle-safe. A.track(B) and B.track(A) together do not infinite-loop — the reconciler detects re-entrant tracking within the same render and unions the paths.
• select mode degrades it. When a consumer uses select on useBloc, .track() behaves like outside-render (live values, no subscription) — select is a manual subscription that opts out of auto-tracking entirely.

Imperative example: calling methods on a dependency

Dependencies aren’t just for reads — call methods to trigger side effects in another bloc. Method calls don’t need reactivity, so use .untracked():

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

class NotificationCubit extends Cubit<{ unread: number }> {
  constructor() {
    super({ unread: 0 });
  }
  incrementUnread = () => this.update((s) => ({ unread: s.unread + 1 }));
}

class ChannelCubit extends Cubit<{ messages: string[] }> {
  private notifications = this.depend(NotificationCubit);
  constructor() {
    super({ messages: [] });
  }

  receiveMessage = (text: string) => {
    this.update((s) => ({ messages: [...s.messages, text] }));
    // A method call needs no reactivity — .untracked() just resolves and calls.
    this.notifications.untracked().incrementUnread();
  };
}

A component that only calls a method on a dependency (never reads its state via .track()) does not re-render when that dependency changes — exactly right for action-only coordination.

Lifecycle: who keeps the dependency alive?

depend() resolves through ensure(), and ensure() takes no ref — it creates the instance if needed but does not increment its ref count.

A bloc you depend() on is not kept alive by you. If nothing else holds a ref to it, the registry may dispose it the moment its own ref count hits zero.

This is usually fine — the dependency is typically also mounted somewhere via useBloc. It bites when the dependency is a “pure derived” service nothing renders directly. Two ways to guarantee it survives:

• @blac({ keepAlive: true }) on the dependency class — the registry never auto-disposes it. See Configuration.
• Let the cascade do it. When a bloc that created its deps (via ensure) is disposed at zero refs, the registry cascades disposal to those deps if they too are at zero refs and not keepAlive — so a depend()-only graph tears itself down cleanly.

Because resolution is lazy per call, a disposed-and-recreated dependency is never a dangling pointer — the next .untracked()/.track() call simply gets the fresh instance (any state the old one held is gone; use keepAlive if that state must survive).

Avoiding cycles and constructor-time reads

Common mistakes

Reading a dependency’s state in the constructor. The dependency’s init() may not have run yet, so its state is still the raw initial value. Read deps inside getters or methods (or your own init), never the constructor.

Mutual depend() between two blocs. A depends on B and B depends on A. Declaring both is safe (resolution is lazy) — the cycle-safety above covers .track(). But if you also wire explicit imperative subscriptions both ways (e.g. two watch() calls), a change in one re-emits the other forever. If you find yourself wanting that, it usually signals the two blocs are really one concern, or that the shared state belongs in a third bloc both depend on, with the arrows pointing one way. See Best Practices.

Alternatives to depend()

Approach	Use when
this.depend(Class)	Ongoing dependency, read from getters or multiple methods
ensure(Class)	One-off access outside a class; creates if missing
borrow/borrowSafe(Class)	One-off access; instance must already exist (throws / returns { error, instance })

See Instance Management for the full registry surface.

See also

• Instance Management — the registry, ref counting, and ensure/borrow/acquire
• Passing Inputs — how args and static key resolve the instance a depend() targets
• Dependency Tracking — the React-side auto-tracking proxy that .track() plugs into
• Best Practices — when cross-bloc coupling is sound versus a smell