Skip to content

ReactiveService

katanakit-js / ReactiveService

Defined in: core/services/reactive.service.ts:45

ReactiveService — Singleton facade over fine-grained reactivity: signals, effects, memos and batching.

Applies the Singleton pattern (one shared instance via ReactiveService.getInstance) and the Facade pattern: each public method hides the subscription bookkeeping behind one call. The batching state (isBatching and the deferred-notification queue) and the active signal-read tracker used for dependency capture are private instance state — never module-level mutable globals — so reactivity is safe to share across environments (Node, Bun, browser, SSR).

Every public method uses the use* prefix per CONTRIBUTING.md; the module level use* functions below are thin wrappers kept for call-site ergonomics.

import { useCreateSignal } from "katanakit-js";
const [count, setCount] = useCreateSignal(0);
count(); // 0
setCount(1);
count(); // 1
useCreateBatch(): (callback) => void;

Defined in: core/services/reactive.service.ts:364

Returns a batch function that defers signal notifications until the callback completes. Nested calls are supported – only the outermost batch flushes the queue.

A batch(callback) function.

(callback) => void

const batch = useCreateBatch();
const [a, setA] = useCreateSignal(0);
const [b, setB] = useCreateSignal(0);
batch(() => {
setA(1);
setB(2);
// listeners fire only once here, not twice
});

IReactiveService.useCreateBatch


useCreateDebouncedSignal<T>(initialValue, delayMs?): [SignalGetter<T>, SignalSetter<T> & {
useCancel: () => void;
}];

Defined in: core/services/reactive.service.ts:316

Creates a signal whose setter debounces writes by delayMs milliseconds. Useful for search inputs or any value that triggers expensive work.

Type Parameter Description
T The signal value type.
Parameter Type Default value Description
initialValue T undefined The initial value.
delayMs? number 300 Debounce delay in milliseconds (defaults to 300).

[SignalGetter<T>, SignalSetter<T> & { useCancel: () => void; }]

A tuple of [getter, debouncedSetter]. The setter exposes a useCancel() method to abort a pending write.

const [query, setQuery] = useCreateDebouncedSignal("", 250);
setQuery("hello"); // won't update until 250ms of quiet
setQuery.useCancel(); // abort pending write

IReactiveService.useCreateDebouncedSignal


useCreateEffect(callback, signals?): () => void;

Defined in: core/services/reactive.service.ts:214

Creates a side effect that re-runs whenever a signal read by the callback changes. Explicit dependencies can also be provided for compatibility. An optional cleanup function returned from the callback is invoked before each re-run and on disposal.

Parameter Type Default value Description
callback () => void | (() => void) undefined Effect body. May return a cleanup function.
signals? Subscribable<unknown>[] [] Optional explicit dependencies, in addition to tracked reads.

A dispose function that tears down all subscriptions and runs the final cleanup.

() => void

const [name, setName] = useCreateSignal("world");
const dispose = useCreateEffect(() => {
console.log(`Hello, ${name()}!`);
return () => console.log("cleaning up");
});
setName("Katana"); // logs "Hello, Katana!"
dispose(); // logs "cleaning up"

IReactiveService.useCreateEffect


useCreateMemo<T>(computation, signals?): SignalGetter<T>;

Defined in: core/services/reactive.service.ts:266

Creates a memoised signal whose value is derived from a computation. The computation re-runs whenever a signal it reads changes. Explicit dependencies can also be provided for compatibility.

Type Parameter Description
T The computed value type.
Parameter Type Default value Description
computation () => T undefined Pure function that derives the value.
signals? Subscribable<unknown>[] [] Optional explicit dependencies, in addition to tracked reads.

SignalGetter<T>

A read-only getter for the memoised value.

const [a, setA] = useCreateSignal(2);
const [b, setB] = useCreateSignal(3);
const sum = useCreateMemo(() => a() + b());
sum(); // 5
setA(10);
sum(); // 13

IReactiveService.useCreateMemo


useCreateSignal<T>(initialValue): [SignalGetter<T>, SignalSetter<T>];

Defined in: core/services/reactive.service.ts:105

Creates a reactive signal with a getter and setter.

The getter is callable and also exposes a useSubscribe method for listening to value changes. The setter accepts either a direct value or an updater function.

Type Parameter Description
T The signal value type.
Parameter Type Description
initialValue T The initial value of the signal.

[SignalGetter<T>, SignalSetter<T>]

A tuple of [getter, setter].

const [count, setCount] = useCreateSignal(0);
count(); // 0
setCount(1);
count(); // 1
setCount(prev => prev + 1);
count(); // 2
const unsub = count.useSubscribe((newVal, oldVal) => {
console.log(`${oldVal} -> ${newVal}`);
});

IReactiveService.useCreateSignal


useCreateToggle(initialValue?): [SignalGetter<boolean>, ToggleSignalSetter];

Defined in: core/services/reactive.service.ts:292

Creates a boolean toggle signal.

Parameter Type Default value Description
initialValue? boolean false Starting value (defaults to false).

[SignalGetter<boolean>, ToggleSignalSetter]

A tuple of [getter, { useSet, useToggle }].

const [isOpen, { useSet, useToggle }] = useCreateToggle();
isOpen(); // false
useToggle();
isOpen(); // true
useSet(false);
isOpen(); // false

IReactiveService.useCreateToggle


static getInstance(): ReactiveService;

Defined in: core/services/reactive.service.ts:59

Returns the shared instance (Singleton).

ReactiveService