TypeScript

BlaC is written in TypeScript and assumes you are too. Almost everything you need — state shape, action signatures, the args a consumer must pass — flows from a single class declaration, so most of this page is about reading the inference rather than writing annotations.

This is the discoverable, example-driven tour. For the exhaustive list of exported type utilities (ExtractState, ExtractArgs, ExtractDeps, InstanceReadonlyState, and friends), see Core Types.

Compiler posture

BlaC works with a standard strict React setup:

{
  "compilerOptions": {
    "target": "ESNext",
    "jsx": "react-jsx",
    "strict": true,
    "useDefineForClassFields": true,
    "experimentalDecorators": true, // only if you use @blac(...) decorator syntax
  },
}

strict: true is the assumption behind every example below — strictNullChecks in particular is what makes this.args correctly Args | undefined and what forces you to narrow discriminated unions.

Decorators are optional. @blac(...) works as either a legacy (experimentalDecorators) decorator or a TC39 stage-3 decorator. If you’d rather not touch decorator flags, blac(opts)(class) is a plain higher-order function the decorator form is sugar over — see Configuration for the full options union and both call forms.

The three generics

Both Cubit and StateContainer take the same three type parameters, in the same order — State, Args, Deps:

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

Param	Constraint	Default	What it is
S	extends object	any	The state shape. Always provide it.
Args	none	void	Typed construction input passed to init(args).
Deps	extends object	Record<string, never>	Non-serializable handles read via this.deps.

You only declare the ones you use, left to right. State-only is the common case:

interface CounterState {
  count: number;
}

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

  increment = () => this.emit({ count: this.state.count + 1 });
}

How inference flows from S

Declaring S is the only annotation you need — state, emit, update, and patch all specialize from it:

interface CounterState {
  count: number;
  label: string;
}

class CounterCubit extends Cubit<CounterState> {
  constructor() {
    super({ count: 0, label: 'start' });
  }

  demo() {
    const c = this.state.count;
const c: number
    this.emit({ count: 1, label: 'a' }); // emit/update take the FULL state
    this.update((s) => ({ ...s, count: s.count + 1 }));
    this.patch({ count: 2 }); // patch takes DeepPartial<S>
  }
}

emit and update’s returned value both require the complete S — omit a key and it’s a type error, which is the compiler enforcing the replace-not-merge rule. patch accepts a DeepPartial<S>, so partial objects are legal there and only there.

Getters as derived state

Anything computed from state belongs in a getter. Getters infer their return type and can’t drift from the state they read:

interface CartState {
  items: { price: number; qty: number }[];
}

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

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

  get isEmpty() {
    // return type inferred as boolean — no annotation needed
    return this.state.items.length === 0;
  }
}

Reading cart.total in render is reactive without any type-level support — see Dependency Tracking for the runtime rule.

Discriminated unions for state

Model a request as a status tag and the compiler forces you to handle every case and forbids reading a field before it exists — because emit wants the full variant, you can’t emit { status: 'success' } without the fields that variant requires:

interface User {
  id: string;
  name: string;
}

type UserState =
  | { status: 'idle' }
  | { status: 'loading' }
  | { status: 'success'; user: User }
  | { status: 'error'; error: string };

class UserCubit extends Cubit<UserState> {
  constructor() {
    super({ status: 'idle' });
  }

  load = async (id: string) => {
    this.emit({ status: 'loading' });
    try {
      const user = await fetchUser(id);
      this.emit({ status: 'success', user });
    } catch (e) {
      this.emit({ status: 'error', error: String(e) });
    }
  };
}

declare function fetchUser(id: string): Promise<User>;

On the read side, switching on state.status (from const [state] = useBloc(UserCubit)) narrows the union — state.user exists only in the success arm, state.error only in error, ordinary TypeScript control-flow narrowing with no BlaC-specific machinery involved. Narrowing works identically inside a getter — derive a flag once and read it everywhere. Give a switch’s default an assignment to never for exhaustiveness checking (add a variant later and forget a case, and the assignment fails to compile).

Typing select

select lets a consumer use an explicit dependency array instead of auto-tracked reads. The component re-renders only when one of those values changes (compared per-index with Object.is). Its signature is:

type Select<TBloc extends StateContainerConstructor> = (
  state: ExtractState<TBloc>,
  bloc: InstanceReadonlyState<TBloc>,
) => unknown[];

Both arguments are fully inferred from the bloc you pass to useBloc — state is the readonly state, bloc is the readonly instance (so getters are reachable):

interface CartState {
  items: { price: number; qty: number }[];
  coupon: string | null;
}

class CartCubit extends Cubit<CartState> {
  constructor() {
    super({ items: [], coupon: null });
  }
  get total() {
    return this.state.items.reduce((s, i) => s + i.price * i.qty, 0);
  }
}

function cartTotal(): number {
  // re-renders only when `total` or item count changes
  const [, cart] = useBloc(CartCubit, {
    select: (state, bloc) => [bloc.total, state.items.length],
bloc: InstanceReadonlyState<typeof CartCubit>
  });
  return cart.total;
}

state is Readonly, so select can’t accidentally mutate it; that’s also why reading a getter here (bloc.total) is the supported way to make a derived value drive re-renders. Keep the selector referentially stable — a fresh function each render re-keys the subscription. See useBloc.

Conditional args

When a bloc declares an Args type, args in useBloc is optional — omit it and the hook inherits args from a <BlocProvider> ancestor, or falls back to the default instance key. When the bloc’s Args is the default void, passing args is forbidden. A conditional option type enforces both directions:

type ArgsOption<T extends StateContainerConstructor> =
  ExtractArgs<T> extends void ? { args?: never } : { args?: ExtractArgs<T> };

A void-args bloc rejects args:

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

function count(): number {
  // CounterCubit has no Args → passing `args` is a type error
  const [state] = useBloc(CounterCubit, { args: { foo: 1 } });
Error ts(2322)  ― Type '{ foo: number; }' is not assignable to type 'undefined'.
  return state.count;
}

A bloc that declares Args accepts it, type-checked against the declared shape:

interface UserState {
  name: string;
}

class UserCubit extends Cubit<UserState, { userId: string }> {
  constructor() {
    super({ name: '' });
  }
  protected init(args: { userId: string }) {
    void args.userId;
  }
}

function userName(): string {
  // args is optional — omit to inherit from BlocProvider, or pass explicitly:
  const [state, user] = useBloc(UserCubit, { args: { userId: '42' } });
const user: InstanceReadonlyState<typeof UserCubit>
  return state.name;
}

Inside the bloc, the args getter is Args | undefined (unset until the instance is acquired) — init(args) hands you the non-optional value instead:

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

  protected init(args: { userId: string }) {
    // `args` here is the non-optional declared shape
    void this.fetch(args.userId);
  }

  retry() {
    // the `args` GETTER is `Args | undefined` — guard it
    const id = this.args?.userId;
const id: string | undefined
    if (id) void this.fetch(id);
  }

  private async fetch(_id: string) {}
}

A typed custom hook

Wrapping useBloc in a domain hook is the idiomatic way to give a feature a named, typed entry point. Inference is preserved end to end as long as you don’t widen the return:

interface TodoState {
  items: string[];
  filter: 'all' | 'active' | 'done';
}

class TodoCubit extends Cubit<TodoState> {
  constructor() {
    super({ items: [], filter: 'all' });
  }
  add = (t: string) => this.patch({ items: [...this.state.items, t] });
  get count() {
    return this.state.items.length;
  }
}

// no explicit return annotation needed — it's inferred
function useTodos() {
  return useBloc(TodoCubit);
}

function todoCount(): number {
  const [state, todo] = useTodos();
const todo: InstanceReadonlyState<typeof TodoCubit>
  todo.add('x');
  return state.items.length;
}

If you do want to annotate the return — for a public package API, say — derive it from the bloc with ExtractState/InstanceReadonlyState rather than restating the shape by hand; both are exported from @blac/core and documented in Core Types.

See also

• Core Types — the exhaustive reference for every exported type utility
• useBloc — the hook, its option surface, and select
• Passing Inputs — the args / deps model in depth
• Dependency Tracking — how getter reads participate in auto-tracking