Cubit

Cubit is the class you subclass for almost everything in BlaC. This page is the class reference: the signature, its members, and the mutation semantics. For narrative (“why a class”, getters, args/deps lifecycle, async patterns) see Mental Model, Passing Inputs, and Best Practices.

class Cubit<
  S extends object = any,
  Args = void,
  Deps extends object = Record<string, never>,
> extends StateContainer<S, Args, Deps> {}

Type parameter	Default	Description
S	any	The state shape. Must be an object type (S extends object).
Args	void	Serializable construction/identity data delivered to init(args). See Passing Inputs.
Deps	Record<string, never>	Non-serializable handles injected per consumer, read via this.deps.

Cubit has an empty class body — it exists only so instance instanceof Cubit works. Every member below is declared on StateContainer; Cubit adds nothing.

Constructor

constructor(initialState: S, options?: StructuralContainerOptions)

The registry always builds instances zero-arg, so your subclass constructor takes no parameters of its own — it just calls super(initialState). Runs before init(args); use it solely to set the initial state.

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

class CounterCubit extends Cubit<{ count: number }> {
  constructor() {
    super({ count: 0 });
  }
}

Member table

Member	Visibility	Signature	Notes
$blac	public, readonly	BlacMeta<S>	Identity/lifecycle/hydration namespace. See System Events for hydration.
args	public getter	Args | undefined	Set from acquire-time config.
deps	public getter	Readonly<Deps>	Merged per-consumer deps view.
depend	protected	depend<T>(Type: T, defaultArgs?: ExtractArgs<T>): DepHandle<T>	Declares a cross-bloc dependency. See Bloc Communication.
init	protected	init(args: Args): void	Override hook, runs once after construction, before the first snapshot.
onSystemEvent	protected	onSystemEvent<E extends SystemEvent>(event: E, handler): () => void	E = 'stateChanged' | 'dispose' | 'hydrationChanged'. See System Events.
on	protected	on<P>(token: EventToken<P>, handler: (payload: P) => void): () => void	Cross-cutting event-bus subscribe; auto-unsubscribes on dispose. See Events.
emit	public	emit(next: S): void	Full replace. See Mutation methods.
update	public	update(fn: (state: S) => S): void	Sugar over emit. See Mutation methods.
patch	public	patch(partial: DeepPartial<S>): void	Deep merge. See Mutation methods.
dispose	public	dispose(): void	Idempotent.
onDepsChanged	protected, overridable	onDepsChanged(next: Readonly<Deps>, prev: Readonly<Deps>): void	No-op by default. Fires after each deps merge, and once more on dispose with everything cleared.

Also inherited from StructuralContainer<S> (not re-declared): state getter, channel, subscribe(interest, cb). Out of scope here — see watch: the low-level channel.subscribe.

Mutation methods

State is immutable from the outside — you never assign to this.state.x. Each method below hands the container a new value; the container diffs it against the previous one and wakes only the consumers whose read paths moved.

Method	Signature	Semantics
emit	emit(next: S): void	Full replace — does not merge. No-op if next is reference-equal to the current state, or if the configured equality function reports them equal.
update	update(fn: (state: S) => S): void	Sugar over emit: calls this.emit(fn(currentState)). fn must return the full next state, and inherits emit’s equality short-circuit.
patch	patch(partial: DeepPartial<S>): void	Deep merges along plain-object branches. Arrays, Date, Map, Set, and class instances are atomic leaves.

patch does NOT consult the equality function

The per-class/global equality function (see Configuration) gates emit and update only. patch runs its own Object.is pre-check on the provided top-level values, then value-filters the deep merge so only genuinely changed paths are marked dirty — a custom equality has no effect on patch.

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

interface ProfileState {
  loading: boolean;
  user: { profile: { name: string; age: number } };
}

class ProfileCubit extends Cubit<ProfileState> {
  constructor() {
    super({ loading: false, user: { profile: { name: '', age: 0 } } });
  }

  reset = () => this.emit({ loading: false, user: { profile: { name: '', age: 0 } } }); // full replace

  birthday = () =>
    this.update((s) => ({ ...s, user: { ...s.user, profile: { ...s.user.profile, age: s.user.profile.age + 1 } } })); // derive from current

  rename = (name: string) => this.patch({ user: { profile: { name } } }); // merge — age untouched
}

Scenario	Method
Full state replacement	emit
Derived from current state	update
Update a few fields	patch

Common mistake: emit with a partial object

emit replaces the whole state — passing a partial object silently drops every field you omit. Use patch for partial updates, or spread the existing state in update.

Immutability contract

Every mutator hands the container a new value rather than mutating in place. This is not a style preference — it’s what the diff-and-wake mechanism needs: tracking records which paths a consumer read, and on the next mutation the container compares old-state to new-state to find which paths moved. Mutating this.state directly leaves nothing to diff against, so the container has no way to know what changed (or that anything changed at all). Nested objects/arrays follow the same rule down the tree: replace the containing object at whatever depth you changed a leaf, rather than mutating that leaf’s parent in place.

depend(Type)

Declares a cross-bloc dependency; see Bloc Communication for the full pattern, .track()/.untracked(), and the lifecycle gotcha.

See also

• Bloc Communication — depend(), cross-bloc reads, .track()
• Instance Management — the registry, ref counting, and how instances are created/keyed
• Passing Inputs — the full args / deps identity model
• Mental Model — why class-based containers and proxy tracking