API Docs
signalium
signal
export function signal<T>(
initialValue: T,
opts?: SignalOptions<T>,
): StateSignal<T>;
Creates a new state signal with the given initial value. State signals are mutable values that can trigger reactivity when they change.
Signal<T> Interface
interface Signal<T> {
value: T; // the current value of the signal
update(updater: (value: T) => T): void; // Update using a function
}
reactive
export function reactive<T, Args extends unknown[]>(
fn: (...args: Args) => T,
opts?: SignalOptions<T, Args>,
): (...args: Args) => SignalValue<T>;
Creates a reactive function that tracks dependencies and automatically updates when those dependencies change.
task
export function task<T, Args extends unknown[]>(
fn: (...args: Args) => Promise<T>,
opts?: SignalOptions<T, Args>,
): TaskSignal<T, Args>;
Creates a reactive task for handling asynchronous operations. Tasks are similar to reactive functions but are specialized for promises.
TaskSignal<T, Args> Interface
interface TaskSignal<T, Args extends unknown[]> extends AsyncSignal<T> {
run(...args: Args): AsyncSignal<T>; // Manually trigger the task
}
relay
export function relay<T, Args extends unknown[]>(
fn: SignalActivate<T, Args>,
opts?: SignalOptionsWithInit<T, Args>,
): AsyncSignal<T>;
Creates a Relay for handling long-running, asymmetric async operations like websockets, polling, or event listeners.
watcher
export function watcher<T>(fn: () => T): Watcher<T>;
Creates a watcher that listens to updates from signals externally. Watchers are how signals are consumed by frameworks and applications.
callback
export function callback<T, Args extends unknown[]>(
fn: (...args: Args) => T,
): (...args: Args) => T;
Creates a callback function that is owned by the current reactive context. This essentially allows you to use the same contexts as the owner within the callback
context
export function context<T>(initialValue: T, description?: string): Context<T>;
Creates a context that can be used to provide values to a subtree of reactive functions.
useContext
export function useContext<T>(context: Context<T>): T;
Retrieves the value from a context. Must be called within a reactive function or a component that has a parent provider.
withContexts
export function withContexts<C extends unknown[], U>(
contexts: [...ContextPair<C>],
fn: () => U,
): U;
Executes a function with the provided context values, making them available to any reactive function called within.
Watcher<T> Interface
interface Watcher<T> {
addListener(listener: (value: T) => void): () => void; // Add a listener for changes
get(): T; // Get the current value and track dependencies
}
isAsyncSignal
export function isAsyncSignal(obj: unknown): boolean;
Checks if a value is a promise signal.
isTaskSignal
export function isTaskSignal(obj: unknown): boolean;
Checks if a value is a task signal.
isRelaySignal
export function isRelaySignal(obj: unknown): boolean;
Checks if a value is a relay signal.
hashValue
export function hashValue(value: unknown): number;
Generates a consistent hash for a value. Used internally for caching and memoization.
registerCustomHash
export function registerCustomHash<T>(
ctor: { new (): T },
hashFn: (obj: T) => number,
): void;
Registers a custom hash function for a specific class. Useful for objects that need special equality considerations.
signalium/react
setupReact
export function setupReact(): void;
Initializes the React integration. Call this once at or near the root of your application.
useStateSignal
export function useStateSignal<T>(
value: T,
opts?: SignalOptions<T, unknown[]>,
): StateSignal<T>;
Creates a component-scoped state signal that will be cleaned up when the component unmounts.
ContextProvider
export function ContextProvider({
contexts,
children,
}: {
contexts: ContextPair<unknown[]>;
children: React.ReactNode;
}): React.ReactElement;
A component that provides multiple Signalium contexts to a React component tree.