Simple and fast JavaScript reactive programming library.
- Small. 2 KB minified and gzipped. No dependencies
- Fast. No unnecessary calculations and excellent performance
- Simple. Small API and autotracking of dependencies
- Well typed. Written in TypeScript
import { signal, effect, batch } from '@spred/core';
const formatter = new Intl.DateTimeFormat('en-GB');
const name = signal('Paul');
const instrument = signal('bass');
const birthday = signal('1942-06-18');
const formattedBirthday = signal(() =>
formatter.format(new Date(birthday.get()))
);
effect(() =>
console.log(
`Hello. My name is ${name.get()}, I play ${instrument.get()} ` +
`and I was born on ${formattedBirthday.get()}.`
)
);
// > Hello. My name is Paul, I play bass and I was born on 18/06/1942.
batch(() => {
name.set('Ringo');
instrument.set('drums');
birthday.set('1940-07-07');
});
// > Hello. My name is Ringo, I play drums and I was born on 07/07/1940.npm install @spred/core --saveSignal is the basic reactive primitive of the library. A signal stores a value and notifies its subscribers when it changes. To create a writable signal you should call the signal function with an initial value that is not a function.
import { signal, on } from '@spred/core';
const counter = signal(0);To get the current value of the signal, you need to call the get method.
/*...*/
console.log(counter.get());
// > 0To set a new value of a writable signal, you should call the set method with the new value.
/*...*/
counter.set(1);
console.log(counter.get());
// > 1A call of the signal function with a function argument will create a computed signal that automatically tracks dependencies and recalculates its own value when they change. The return value of the passed computation function must only depend on other signals.
/*...*/
const doubleCounter = signal(() => counter.get() * 2);
console.log(doubleCounter.get());
// > 2Signal value updates can be subscribed to using the subscribe method. The second argument of the method specifies whether the function should be called immediately after subscribing, and defaults to true. The method returns the unsubscribe function.
/*...*/
const unsub = doubleCounter.subscribe((value) =>
console.log('Double value is ' + value)
);
// > Double value is 2
counter.set(2);
// > Double value is 4
unsub();
counter.set(3);
// Nothing
console.log(doubleCounter.get());
// > 6You can also subscribe to a signal value updates without immediately executing the subscriber using on function, which is a shorthand for someSignal.subscribe(someFn, false).
/*...*/
on(doubleCounter, (value) => console.log('Double value is ' + value));
// Nothing
counter.set(4);
// > Double value is 8Computed signals initialize their values lazily. That means that the calculation function triggers only when the signal has at least one subscriber / dependent signal with a subscriber.
Writable signal updates are immediate and synchronous.
import { signal, batch, on } from '@spred/core';
const a = signal(0);
const b = signal(0);
const sum = signal(() => a.get() + b.get());
sum.subscribe((s) => console.log('a + b = ' + s));
// > a + b = 0
a.set(1);
// > a + b = 1
b.set(1);
// > a + b = 2You can commit several updates as a single transaction using the batch function.
/*...*/
batch(() => {
a.set(2);
b.set(2);
});
// > a + b = 4All updates inside subscriber functions and computations are batched by default.
const trigger = signal(0);
on(trigger, () => {
a.set(3);
b.set(3);
});
trigger.set(1);
// > a + b = 6By default all signals trigger their dependents and subscribers only if its value changes.
import { signal } from '@spred/core';
const counter = signal(0);
const doubleCounter = signal(() => counter.get() * 2);
const unsub = doubleCounter.subscribe((value) =>
console.log('Double value is ' + value)
);
// > Double value is 0
counter.set(0);
// Nothing
counter.set(1);
// > Double value is 2
unsub();Signals use Object.is to compare values, but you can set custom equality function in signal options.
/*...*/
const obj = signal(
{ value: 1 },
{
equal: (a, b) => a.value === (b && b.value),
}
);
obj.subscribe((obj) => console.log('Object value is ' + obj.value));
// > Object value is 1
obj.set({ value: 1 });
// Nothing
obj.set({ value: 2 });
// > Object value is 2Undefined values are ignored and can be used for filtering.
/*...*/
const oddCounter = signal(() => {
if (counter.get() % 2) return counter.get();
});
oddCounter.subscribe((value) => console.log('Odd value is ' + value));
// > Odd value is 1
counter.set(2);
// Nothing
counter.set(3);
// > Odd value is 3effect calls the passed function immediately and every time its dependencies change.
import { signal, effect, batch } from '@spred/core';
const a = signal('Hello');
const b = signal('World');
const dispose = effect(() => {
console.log(`${a.get()} ${b.get()}!`);
});
// > Hello World!
batch(() => {
a.set('Foo');
b.set('Bar');
});
// > Foo Bar!
dispose();
a.set('Hello');
// NothingUnder the hood, the effect is simply a computed signal that becomes active at the moment of creation.
Every signal has lifecycle hooks whose handlers can be set in the signal options.
onCreate- the signal is created;onActivate- the signal becomes active (has at least one subscriber / dependent signal with a subscriber);onDectivate- the signal becomes inactive (doesn't have any subscriber / dependent signal with a subscriber);onUpdate- the signal updates its value;onException- an unhandled exception occurs during the signal computation.
Spred signals implement Svelte store contract so you don't need any additional package to use them in Svelte apps.
Use the spred-react package.
Big thanks for inspiration to