Framework Adapter

Utilities for building framework integrations

← Back to @blac/core

Quick Reference

Classs: DependencyManager, ExternalDepsManager

Interfaces: AdapterState, ManualDepsConfig

Functions: autoTrackInit, autoTrackSnapshot, autoTrackSubscribe, disableGetterTracking, manualDepsInit, manualDepsSnapshot, manualDepsSubscribe, noTrackInit, noTrackSnapshot, noTrackSubscribe

Types: SnapshotFunction, SubscribeFunction, SubscriptionCallback

Classes

DependencyManager

Manages subscriptions to state container dependencies. Provides efficient sync mechanism to add/remove subscriptions as dependencies change between callback invocations.

export declare class DependencyManager

Methods:

add

Add a single dependency subscription.

add(dep: StateContainerInstance, onChange: () => void): void;

Parameter	Type	Description
dep	StateContainerInstance
onChange	() => void

cleanup

Clean up all active subscriptions.

cleanup(): void;

getDependencies

Get the current set of dependencies.

getDependencies(): Set<StateContainerInstance>;

has

Check if a dependency is currently subscribed.

has(dep: StateContainerInstance): boolean;

Parameter	Type	Description
dep	StateContainerInstance

sync

Sync subscriptions with a new set of dependencies. Adds subscriptions for new deps, removes subscriptions for stale deps.

sync(newDeps: Set<StateContainerInstance>, onChange: () => void, exclude?: StateContainerInstance): boolean;

Parameter	Type	Description
newDeps	Set<StateContainerInstance>	The new set of dependencies to subscribe to
onChange	() => void	Callback to invoke when any dependency changes
exclude	StateContainerInstance	Optional instance to exclude from subscriptions (e.g., primary bloc)

Returns: true if the dependency set changed, false if unchanged

---

ExternalDepsManager

Manages subscriptions to external bloc dependencies for getter tracking. When a getter accesses another bloc's state, this manager ensures re-renders occur when those external dependencies change.

export declare class ExternalDepsManager

Methods:

cleanup

Clean up all active subscriptions

cleanup(): void;

updateSubscriptions

Update subscriptions to external bloc dependencies. Creates subscriptions to blocs accessed via getters.

updateSubscriptions(getterState: GetterState | null, rawInstance: StateContainerInstance, onGetterChange: () => void): boolean;

Parameter	Type	Description
getterState	GetterState | null
rawInstance	StateContainerInstance	The primary bloc instance (excluded from subscriptions)
onGetterChange	() => void	Callback to invoke when external dependency changes

Returns: true if subscriptions were updated, false if unchanged

---

Interfaces

AdapterState

Internal state for framework adapters, holding tracking and caching data. @template TBloc - The state container type

export interface AdapterState<TBloc extends StateContainerConstructor>

Property	Type	Description
dependencyState	DependencyState<ExtractState<TBloc>> | null	Dependency tracker for state property access tracking
getterState	GetterState | null	Getter state for computed property tracking
manualDepsCache	unknown[] | null	Cached manual dependencies for comparison
proxiedBloc	InstanceState<TBloc> | null	Proxied bloc instance for auto-tracking

---

ManualDepsConfig

Configuration for manual dependency tracking mode @template TBloc - The state container type

export interface ManualDepsConfig<TBloc extends StateContainerConstructor>

Property	Type	Description
dependencies	(state: ExtractState<TBloc>, bloc: InstanceState<TBloc>) => any[]	Function that returns dependency array from state and bloc

---

Functions

autoTrackInit

Initialize adapter state for auto-tracking mode. Creates getter tracker and proxied bloc instance.

export declare function autoTrackInit<TBloc extends StateContainerConstructor>(instance: InstanceState<TBloc>): AdapterState<TBloc>;

Parameter	Type	Description
instance	InstanceState<TBloc>	The state container instance

Returns: Initialized adapter state

---

autoTrackSnapshot

Create a snapshot function for auto-tracking mode. Returns a proxied state that tracks property access.

export declare function autoTrackSnapshot<TBloc extends StateContainerConstructor>(instance: InstanceReadonlyState<TBloc>, adapterState: AdapterState<TBloc>): SnapshotFunction<ExtractState<TBloc>>;

Parameter	Type	Description
instance	InstanceReadonlyState<TBloc>	The state container instance
adapterState	AdapterState<TBloc>	The adapter state for tracking

Returns: Snapshot function for use with useSyncExternalStore

---

autoTrackSubscribe

Create a subscribe function for auto-tracking mode. Only triggers callback when tracked properties change.

export declare function autoTrackSubscribe<TBloc extends StateContainerConstructor>(instance: InstanceReadonlyState<TBloc>, adapterState: AdapterState<TBloc>): SubscribeFunction;

Parameter	Type	Description
instance	InstanceReadonlyState<TBloc>	The state container instance
adapterState	AdapterState<TBloc>	The adapter state for tracking

Returns: Subscribe function for use with useSyncExternalStore

---

disableGetterTracking

Disable getter tracking after render phase completes. Clears the active tracker to prevent tracking outside of render.

export declare function disableGetterTracking<TBloc extends StateContainerConstructor>(adapterState: AdapterState<TBloc>, rawInstance: InstanceState<TBloc>): void;

Parameter	Type	Description
adapterState	AdapterState<TBloc>	The adapter state
rawInstance	InstanceState<TBloc>	The raw bloc instance

---

manualDepsInit

Initialize adapter state for manual dependency tracking mode. No proxy is created; bloc is used directly.

export declare function manualDepsInit<TBloc extends StateContainerConstructor>(instance: InstanceState<TBloc>): AdapterState<TBloc>;

Parameter	Type	Description
instance	InstanceState<TBloc>	The state container instance

Returns: Initialized adapter state

---

manualDepsSnapshot

Create a snapshot function for manual dependency tracking mode. Caches dependencies for comparison on next render.

export declare function manualDepsSnapshot<TBloc extends StateContainerConstructor>(instance: InstanceState<TBloc>, adapterState: AdapterState<TBloc>, config: ManualDepsConfig<TBloc>): SnapshotFunction<ExtractState<TBloc>>;

Parameter	Type	Description
instance	InstanceState<TBloc>	The state container instance
adapterState	AdapterState<TBloc>	The adapter state for caching
config	ManualDepsConfig<TBloc>	Configuration with dependencies function

Returns: Snapshot function for use with useSyncExternalStore

---

manualDepsSubscribe

Create a subscribe function for manual dependency tracking mode. Only triggers callback when dependencies array changes.

export declare function manualDepsSubscribe<TBloc extends StateContainerConstructor>(instance: InstanceState<TBloc>, adapterState: AdapterState<TBloc>, config: ManualDepsConfig<TBloc>): SubscribeFunction;

Parameter	Type	Description
instance	InstanceState<TBloc>	The state container instance
adapterState	AdapterState<TBloc>	The adapter state for caching
config	ManualDepsConfig<TBloc>	Configuration with dependencies function

Returns: Subscribe function for use with useSyncExternalStore

---

noTrackInit

Initialize adapter state for no-tracking mode. No tracking or proxy is created.

export declare function noTrackInit<TBloc extends StateContainerConstructor>(instance: InstanceState<TBloc>): AdapterState<TBloc>;

Parameter	Type	Description
instance	InstanceState<TBloc>	The state container instance

Returns: Initialized adapter state

---

noTrackSnapshot

Create a snapshot function for no-tracking mode. Returns the raw state directly.

export declare function noTrackSnapshot<TBloc extends StateContainerConstructor>(instance: InstanceReadonlyState<TBloc>): SnapshotFunction<ExtractState<TBloc>>;

Parameter	Type	Description
instance	InstanceReadonlyState<TBloc>	The state container instance

Returns: Snapshot function for use with useSyncExternalStore

---

noTrackSubscribe

Create a subscribe function for no-tracking mode. Triggers callback on every state change.

export declare function noTrackSubscribe<TBloc extends StateContainerInstance>(instance: TBloc): SubscribeFunction;

Parameter	Type	Description
instance	TBloc	The state container instance

Returns: Subscribe function for use with useSyncExternalStore

---

Types

SnapshotFunction

Function that returns a snapshot of the current state @template TState - The state type

export type SnapshotFunction<TState> = () => TState;

SubscribeFunction

Function that subscribes to state changes and returns an unsubscribe function

export type SubscribeFunction = (callback: SubscriptionCallback) => () => void;

SubscriptionCallback

Callback function invoked when subscribed state changes

export type SubscriptionCallback = () => void;