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.