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. The defaults that matter:

{
  "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 inference example below — strictNullChecks in particular is what makes this.args correctly Args | undefined and what forces you to narrow discriminated unions. Without it the examples still compile, but the safety they demonstrate is gone.

Decorators are optional. The @blac(...) configuration decorator works as either a legacy (experimentalDecorators) decorator or a TC39/stage-3 decorator — pick whichever your toolchain emits. If you’d rather not touch decorator flags at all, the functional form needs none:

const AuthCubit = blac({ keepAlive: true })(
  class extends Cubit<{ user: string | null }> {
    constructor() {
      super({ user: null });
    }
  },
);

blac(opts)(class) is a plain higher-order function — no compiler flag, no syntax proposal. The decorator form is sugar over exactly this. See Configuration for the full options union (keepAlive, equality, excludeFromDevTools, key).

Match getting-started

The tsconfig block above is the same one in Getting Started. If you change one, change both.

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> {}

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

So:

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. Hover any of these and you’ll see the concrete type, not any:

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 the value update’s callback returns 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:

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

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

  bad() {
    this.emit({ count: 1 }); // missing `label` — emit replaces, so this is an error
Error ts(2345)  ― Argument of type '{ count: number; }' is not assignable to parameter of type 'CounterState'.
  Property 'label' is missing in type '{ count: number; }' but required in type 'CounterState'.
  }
}

Getters as derived state

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

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;
  }
}

Getters track in render

Reading cart.total directly in render is reactive: the bloc returned by useBloc is proxied, and this.state inside the getter records through the current state proxy. Use select (select: (state, bloc) => [bloc.total]) only when the getter’s return value should be the explicit re-render boundary. This is a runtime tracking rule, not a type rule — the types let you read cart.total anywhere. See Dependency Tracking.

Discriminated unions and narrowing

The single most useful TypeScript pattern in BlaC is a discriminated-union state. Model a request as a status tag and the compiler will force you to handle every case and forbid you from reading a field before it exists.

Declare the union as the state type. Each variant carries only the data that’s valid in that state:

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>;

Because emit wants the full UserState, you can’t emit { status: 'success' } without a user — the variant’s required fields are checked at the emit site:

type UserState =
  | { status: 'idle' }
  | { status: 'success'; user: { id: string } };

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

  oops() {
    this.emit({ status: 'success' }); // forgot `user`
Error ts(2345)  ― Argument of type '{ status: "success"; }' is not assignable to parameter of type 'UserState'.
  Property 'user' is missing in type '{ status: "success"; }' but required in type '{ status: "success"; user: { id: string; }; }'.
  }
}

Narrowing on the read side

The payoff is on the read side. Switch on state.status and inside each branch TypeScript narrows the union — state.user exists only in the success arm, state.error only in error. Here the consumer is a plain function so the inference is visible; in a component the same state comes out of useBloc:

function userLabel(): string {
  const [state] = useBloc(UserCubit);

  switch (state.status) {
    case 'idle':
      return 'Not loaded';
    case 'loading':
      return 'Loading…';
    case 'success':
      return `Hello ${state.user.name}`;
user: User
    case 'error':
      return `Failed: ${state.error}`;
  }
}

Rendered in a component, that’s an ordinary switch over state.status:

function UserCard() {
  const [state] = useBloc(UserCubit);

  switch (state.status) {
    case 'idle':
      return <p>Not loaded</p>;
    case 'loading':
      return <p>Loading…</p>;
    case 'success':
      return <p>Hello {state.user.name}</p>; // state.user only exists here
    case 'error':
      return <p>Failed: {state.error}</p>;
  }
}

Reaching for a field outside its variant is a compile error, which is exactly the bug class discriminated unions exist to kill:

function userName(): string {
  const [state] = useBloc(UserCubit);
  // no narrowing yet — `user` doesn't exist on the `loading` arm
  return state.user.name;
Error ts(2339)  ― Property 'user' does not exist on type 'Readonly<UserState>'.
  Property 'user' does not exist on type 'Readonly<{ status: "loading"; }>'.
}

Exhaustiveness checking

Give your switch a default that assigns state to never. Add a new variant later and forget to handle it, and the assignment fails to compile — a free reminder.

function render(): string {
  switch (state.status) {
    case 'idle':
      return 'idle';
    // forgot the 'loading' case
    default: {
      const _exhaustive: never = state; // error: 'loading' is not assignable to never
Error ts(2322)  ― Type '{ status: "loading"; }' is not assignable to type 'never'.
      return _exhaustive;
    }
  }
}

Narrowing works identically inside a getter — derive a flag once and read it everywhere:

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

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

  get displayName(): string {
    const s = this.state;
    return s.status === 'success' ? s.user.name : 'Guest';
user: {
    name: string;
}
  }
}

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). The return type is unknown[], an array of whatever values gate the re-render:

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 — you may omit it and the hook will inherit args from a <BlocProvider> ancestor, or fall back to the default instance key. When the bloc’s Args is the default void, passing args is forbidden. The type system enforces both directions through a conditional option type (verified in @blac/react’s types.ts):

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

ExtractArgs<T> pulls the second generic off the class. If it’s void, the option becomes { args?: never } — present-but-forbidden. Otherwise it’s { args?: Args } — optional and typed.

A void-args bloc rejects args (the option’s type there is never):

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 as optional — omitting it inherits args from a <BlocProvider> ancestor, else the default key is used. When you do pass args, it is 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] = useBloc(UserCubit, { args: { userId: '42' } });
  return state.name;
}

Provide it correctly and args is type-checked against the declared shape:

function userName(userId: string): string {
  const [state, user] = useBloc(UserCubit, { args: { userId } });
const user: InstanceReadonlyState<typeof UserCubit>
  return state.name;
}

Inside the bloc, the args getter is Args | undefined (it’s unset until the instance is acquired), so reach for the value init(args) hands you when you need it non-optionally:

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 — let it flow:

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;
  }
}

// Custom hook: no explicit return annotation needed — it's inferred as
// [Readonly<TodoState>, InstanceReadonlyState<typeof TodoCubit>, ...]
function useTodos() {
  return useBloc(TodoCubit);
}

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

For a hook that takes arguments, type the parameters and forward them — the bloc’s Args requirement still applies at the call site inside the hook:

interface UserState {
  name: string;
}

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

// the hook's signature documents what the feature needs
function useUser(userId: string) {
  return useBloc(UserCubit, { args: { userId } });
}

function profileName(id: string): string {
  const [state] = useUser(id);
  return state.name;
}

If you do want to annotate the return — for a public package API, say — derive it from the bloc rather than restating the shape. ExtractState and InstanceReadonlyState are exported from @blac/core:

type TodoState = ExtractState<typeof TodoCubit>;
type TodoState = {
    readonly items: string[];
}
type TodoBloc = InstanceReadonlyState<typeof TodoCubit>;

function useTodos(): [TodoState, TodoBloc] {
  const [state, bloc] = useBloc(TodoCubit);
  return [state, bloc];
}

These utilities, plus ExtractArgs, ExtractDeps, and the rest, are documented in full in Core Types.

See also

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