Fine-grained reactive signals for TypeScript and React. Computed values and effects track
their dependencies automatically, so there are no dependency arrays to maintain and no
manual update() calls. On top of the core you get deep reactive stores with immutable
snapshots, async resources that refetch, abort and ignore stale responses on their own, and
React hooks built on useSyncExternalStore. It is small (about 1.7 kB for the core
primitives) and has zero dependencies.
v1 is in beta (
1.0.0-beta.0). Coming from 0.2.x? See MIGRATION.md.
COZY stands for Compact, On-point, Zero-overhead, Yet-powerful.
A fine-tailored ecosystem of TypeScript libraries designed for your everyday needs—lightweight, efficient, and built to get the job done. No bloat, just pure performance. 🚀
- Install
- 30-second example
- React in 30 seconds
- Why not
useEffect? - Core API
- Store
- Async resources
- React
- Compat / 0.2.x API
- Bundle size
- Benchmarks
- TypeScript notes
- License
npm install cozyobserve
# or
yarn add cozyobserve
# or
pnpm add cozyobserveReact bindings live in cozyobserve/react and need react >= 18 (an optional peer dependency).
The main cozyobserve entry never imports React.
import { observable, computed, effect, batch } from 'cozyobserve';
const first = observable('Ada');
const last = observable('Lovelace');
const full = computed(() => `${first.value} ${last.value}`);
const stop = effect(() => {
console.log(full.value);
}); // logs "Ada Lovelace"
first.value = 'Grace'; // logs "Grace Lovelace"
batch(() => {
first.set('Alan');
last.set('Turing');
}); // logs "Alan Turing" once
stop(); // no more logsfull knows it depends on first and last because it read them. Nothing was declared.
import { observable, computed } from 'cozyobserve';
import { useObserver, tracked } from 'cozyobserve/react';
const count = observable(0);
const doubled = computed(() => count.value * 2);
function Counter() {
const n = useObserver(count);
return <button onClick={() => count.update((c) => c + 1)}>Clicked {n} times</button>;
}
// tracked(): every observable read during render is a dependency
const Doubled = tracked(() => <p>Doubled: {doubled.value}</p>);State lives outside components, so any component (or plain code) can read and write it. Only the components that read a value re-render when it changes.
useEffect is a sync-with-the-outside-world tool, but it often gets used for data fetching,
derived state and subscriptions. Each of those needs a hand-written dependency array, and
each has a bug you have to remember to avoid. Here is what the same three jobs look like with
CozyObserve.
Before: useState + useEffect.
function Profile({ id }: { id: number }) {
const [user, setUser] = useState<User | null>(null);
const [loading, setLoading] = useState(true);
useEffect(() => {
setLoading(true);
fetchUser(id).then((u) => {
setUser(u); // 🐛 if `id` changed meanwhile, a slow response for the OLD id can land last
setLoading(false);
});
}, [id]); // 🐛 forget `id` here and the component shows stale data
if (!user) return <p>Loading…</p>;
return <h1 style={{ opacity: loading ? 0.5 : 1 }}>{user.name}</h1>;
}Fixing it properly means an AbortController or an ignore flag in a cleanup function,
plus an error state, in every component that fetches.
After: resource + useResource.
import { observable, resource } from 'cozyobserve';
import { useResource } from 'cozyobserve/react';
const userId = observable(1);
const user = resource(async ({ signal }) => {
const id = userId.value; // tracked: read before the first `await`
return fetchUser(id, signal);
});
function Profile() {
const { value, loading, error } = useResource(user);
if (error) return <p>Failed to load</p>;
if (!value) return <p>Loading…</p>;
return <h1 style={{ opacity: loading ? 0.5 : 1 }}>{value.name}</h1>;
}
userId.set(2); // aborts the request for 1, fetches 2; a late answer for 1 is ignoredThe resource refetches when userId changes because the fetcher read it. Starting a new
fetch aborts the previous signal, and only the latest request can set the value.
Before: useMemo with a dependency array.
const visible = useMemo(
() => todos.filter((t) => filter === 'all' || t.done === (filter === 'done')),
[todos, filter], // must list every input by hand
);After: a getter passed to useObserver.
const todos = observable<Todo[]>([]);
const filter = observable<'all' | 'done' | 'open'>('all');
function TodoList() {
const visible = useObserver(() =>
todos.value.filter((t) => filter.value === 'all' || t.done === (filter.value === 'done')),
);
return <ul>{visible.map((t) => <li key={t.title}>{t.title}</li>)}</ul>;
}The getter tracks what it reads. It re-renders the component only when the result changes.
Before: subscribe in an effect, copy into state, unsubscribe in cleanup.
function Status() {
const [online, setOnline] = useState(navigator.onLine);
useEffect(() => {
const on = () => setOnline(true);
const off = () => setOnline(false);
window.addEventListener('online', on);
window.addEventListener('offline', off);
return () => {
window.removeEventListener('online', on);
window.removeEventListener('offline', off);
};
}, []);
return <span>{online ? 'Online' : 'Offline'}</span>;
}After: keep the value in an observable once; components just read it.
const online = observable(navigator.onLine);
window.addEventListener('online', () => online.set(true));
window.addEventListener('offline', () => online.set(false));
const Status = tracked(() => <span>{online.value ? 'Online' : 'Offline'}</span>);No state copy, no cleanup, and no window between render and subscribe where an update can
be missed (the hooks use useSyncExternalStore).
import {
observable, computed, effect, batch, untracked, watch, onCleanup, isObservable,
} from 'cozyobserve';const count = observable(0);
count.value; // 0, tracked read
count.get(); // 0, same as .value
count.peek(); // 0, untracked read (never registers a dependency)
count.value = 1;
count.set(2);
count.set((n) => n + 1); // a function is an updater → 3
count.update((n) => n * 2); // explicit updater → 6
// To store a function as the value, wrap it:
const handler = observable<() => void>(() => {});
handler.set(() => () => console.log('hi'));Setting an equal value is a no-op. Equality is Object.is by default; pass your own, or
false to notify on every write:
const pos = observable({ x: 0, y: 0 }, { equals: (a, b) => a.x === b.x && a.y === b.y });
pos.set({ x: 0, y: 0 }); // no-op
const tick = observable(0, { equals: false });
tick.set(0); // notifies anywayEvery observable and computed has subscribe. The callback gets (value, prev) after each
change (after the outermost batch). It returns an Unsubscribe function.
const off = count.subscribe((value, prev) => console.log(prev, '→', value));
count.set(7); // logs "6 → 7"
off();
count.subscribe((v) => console.log('now', v), { immediate: true }); // logs "now 7" right awayUnsubscribing from inside a callback is safe. Subscribing to a computed keeps it live (eagerly updated) until its last subscriber leaves.
const price = observable(10);
const qty = observable(3);
const total = computed(() => price.value * qty.value);
total.value; // 30- Lazy and cached.
fndoes not run until the first read, and reading again without changes does not re-run it. An unobserved computed holds no subscriptions, so it can be garbage-collected. - Dynamic dependencies. Dependencies are re-collected on every run; a branch that was not taken is not a dependency.
- Glitch-free. In a diamond (
a → b,a → c,b + c → d), settingarunsdonce with consistent values. - Equality cutoff. If a computed recomputes to an equal value, nothing downstream runs.
- Previous value.
fnreceives the previous value:computed<number>((prev) => Math.max(prev ?? 0, price.value)). - Errors thrown in
fnare cached and re-thrown on read until a dependency changes. - Writing to an observable inside a computed throws
Cannot write inside computed(useuntracked()if you really need to). Reading itself throws aCycle detectederror.
Runs fn now, then again whenever something it read changes. Returns a dispose function.
const intervalMs = observable(1000);
const stop = effect(() => {
const id = setInterval(() => console.log('tick'), intervalMs.value);
return () => clearInterval(id); // cleanup: before the next run and on dispose
});
intervalMs.set(500); // clears the old interval, starts a new one
stop();- Re-runs are synchronous, after the outermost
batchends. - An effect created inside another effect is owned by it: it is disposed when the parent
re-runs or is disposed. (
subscribe,watchandresourcecreated inside an effect are not owned; keep their dispose functions yourself.) - An error in one effect does not stop other effects in the same flush; the first error is re-thrown afterwards. An effect that throws keeps its dependencies and re-runs on the next change.
- An effect that keeps writing a value it reads throws
Cycle detectedafter 100 re-runs in one flush instead of hanging.
Registers a cleanup for the effect that is currently running. Useful from helper functions
called inside an effect. Outside an effect it does nothing. Order: onCleanup callbacks in
registration order, then the function returned by the effect.
effect(() => {
const ws = new WebSocket(url.value);
onCleanup(() => ws.close());
});Groups writes so effects and subscribers run once, at the end. Batches nest; batch
returns whatever fn returns. Reads inside the batch already see the new values.
const total = batch(() => {
a.set(10);
b.set(20);
return a.value + b.value; // 30
}); // effects that read a and b run once, hereReads inside fn do not become dependencies.
effect(() => {
// re-runs when `user` changes, not when `theme` changes
console.log(user.value, untracked(() => theme.value));
});Like subscribe, but the source can be a getter (auto-tracked selector), and cb gets an
onCleanup for per-call cleanup. cb only fires when the selected value changes.
const user = observable({ id: 1, name: 'Ada' });
const off = watch(
() => user.value.id,
(id, prevId, onCleanup) => {
const ctrl = new AbortController();
loadPermissions(id, ctrl.signal);
onCleanup(() => ctrl.abort()); // runs before the next call and on unsubscribe
},
);
user.set({ id: 1, name: 'Ada L.' }); // id unchanged → no call
user.set({ id: 2, name: 'Grace' }); // cb(2, 1, onCleanup)Options: immediate (call now; prev is undefined the first time), equals (custom
comparison for the selected value), once (unsubscribe after the first call; the immediate
call counts).
true for anything created by observable, computed or the compat classes.
Deep reactive objects, tracked per property.
import { store, snapshot, subscribeStore, toRaw, isStore, effect } from 'cozyobserve';
const state = store({
user: { name: 'Ada', tags: ['math'] },
todos: [{ title: 'Write docs', done: false }],
});
effect(() => {
console.log(state.user.name); // re-runs only when user.name (or user) changes
});
state.todos[0].done = true; // the effect above does not re-run
state.user.name = 'Grace'; // logs "Grace"
state.todos.push({ title: 'Ship', done: false }); // one notification per array method call
state.user = { name: 'Alan', tags: [] }; // replacing a parent re-runs readers of user.name → logs "Alan"- Reads of
in,Object.keys,for...inand array iteration/lengthare tracked too, so adding or removing keys re-runs them. - Proxies are created lazily and cached:
state.user === state.user. - Assigning the same value is a no-op. Assigning a store proxy stores its raw object.
A frozen plain copy of the current state, with structural sharing: unchanged subtrees keep the same reference, and calling it twice with no changes returns the identical object. This is what the React hooks render from.
const a = snapshot(state);
state.todos[0].done = false;
const b = snapshot(state);
a === b; // false
a.user === b.user; // true, unchanged subtree
Object.isFrozen(b); // trueInside an effect or computed, snapshot(s) tracks the whole tree.
Deep subscription. cb(nextSnapshot, prevSnapshot) runs once per batch.
const off = subscribeStore(state, (next, prev) => {
console.log(prev.user.name, '→', next.user.name);
});
batch(() => {
state.user.name = 'Grace';
state.todos.push({ title: 'Review', done: false });
}); // one calltoRaw returns the plain object behind a store proxy (non-store values pass through).
isStore tells you whether a value is a store proxy.
store()wraps the object you pass; it does not copy it. Writes through the proxy change the original object. Writing to the raw object directly (toRaw(s).x = 1) is not reactive.- Only plain objects and arrays are deep-reactive.
Map,Set,Date, class instances, promises and frozen objects are stored as plain values:state.tags.add('x')on aSetdoes not notify. Replace the value instead:state.tags = new Set([...state.tags, 'x']). - Symbol keys are not tracked, and snapshots copy own enumerable string keys only.
resource turns an async function into reactive state:
status ('idle' | 'loading' | 'success' | 'error'), value, error and loading.
All of them are tracked, so effects, computeds and components react to them.
import { observable, resource } from 'cozyobserve';
const userId = observable(1);
const user = resource(async ({ signal, prev }) => {
const id = userId.value; // tracked
const res = await fetch(`/api/users/${id}`, { signal });
if (!res.ok) throw new Error(res.statusText);
return (await res.json()) as User;
});
user.status; // 'loading'
await user.promise(); // resolves on the next success, rejects on error
user.value; // the user- Auto-refetch on dependencies. Observables read in the synchronous part of the fetcher
(before the first
await) are dependencies. ChanginguserIdstarts a new fetch. Read them at the top of the fetcher. - Abort. Each fetch gets an
AbortSignal. It is aborted when a newer fetch starts, and onabort(),mutate()anddispose(). Pass it tofetch. - Race safety. Only the latest fetch can write. A stale response is ignored even if it resolves after a newer one, and a stale rejection never surfaces as an unhandled rejection.
- Stale-while-revalidate.
valuekeeps the last successful value while a refetch is loading, anderroris kept until the next success. previn the fetcher context is the last successful value.
| Member | What it does |
|---|---|
value, error, status, loading |
Tracked reads. |
state |
A ReadonlyObservable<{ status, value, error }>, with stable identity while nothing changes. |
refresh() |
Fetch again now. Returns a promise for this run's value. |
mutate(v | prev => v) |
Set the value locally (optimistic update). Aborts an in-flight fetch; status becomes 'success'. |
abort() |
Abort the in-flight fetch and restore the status it had before loading. |
promise() |
Resolves on the next success (now, if already 'success'); rejects on the next error. |
dispose() |
Abort, and stop tracking dependencies. |
Options:
// lazy: status 'idle', nothing fetched until the first read of .value, refresh() or promise()
const stats = resource(fetchStats, { lazy: true });
// initial: value before the first fetch completes (status is still 'loading' while it runs)
const todos = resource(fetchTodos, { initial: [] as Todo[] });
// a plain promise works too
const config = resource(fetch('/config.json').then((r) => r.json()));import {
useObserver, useObservable, useComputed, useObserverEffect,
useStore, useResource, tracked, Observe,
} from 'cozyobserve/react';Every hook is built on useSyncExternalStore. That means no tearing in concurrent rendering
and no missed updates between render and subscription. They work with React 18 and 19, in
StrictMode, and with SSR (the server snapshot is the current value). Tracking scopes from a
render that never commits (StrictMode double render, discarded concurrent renders) are not
subscribed, so they cannot leak.
// 1. an observable or computed
const n = useObserver(count);
// 2. a selector: re-render only when the selected slice changes (optional equals)
const name = useObserver(user, (u) => u.name);
// 3. a getter: auto-tracked derived value, no deps array
const full = useObserver(() => `${first.value} ${last.value}`);The getter form without deps always uses the latest closure, so it can read props and state
safely: it is re-evaluated on each render and when what it read changes. If you pass deps
(useObserver(() => user.value.age * factor, [factor])), it is memoized per deps like
useMemo. Keep the call shape (with or without deps) stable at a call site.
A component-local observable with stable identity. Accepts a lazy initializer like useState.
function Search() {
const query = useObservable('');
return <input value={useObserver(query)} onChange={(e) => query.set(e.target.value)} />;
}A component-local computed you can pass to children or other hooks. Without deps its identity is stable for the component's lifetime and it always uses the latest closure. With deps it is recreated when they change.
const shout = useComputed(() => query.value.toUpperCase() + suffix); // `suffix` is a prop
const text = useObserver(shout);An auto-tracked effect with no deps array. Runs after mount, re-runs only when observables
it read change (not on every render), always calls the latest fn, and cleans up on unmount.
useObserverEffect(() => {
document.title = `${unread.value} unread`;
});
useObserverEffect(() => {
const ws = new WebSocket(url.value);
return () => ws.close();
});Renders from a store snapshot. Without a selector it re-renders on any deep change; with one,
only when the selected slice changes. Structural sharing keeps unchanged references stable, so
memo children and dependency arrays keep working.
const state = store({ user: { name: 'Ada' }, todos: [] as Todo[] });
function Todos() {
const snap = useStore(state); // DeepReadonly<typeof state>
return <ul>{snap.todos.map((t) => <li key={t.title}>{t.title}</li>)}</ul>;
}
function UserName() {
const name = useStore(state, (s) => s.user.name); // re-renders only when the name changes
return <b>{name}</b>;
}For per-property tracking, read the store directly inside tracked() (see below).
Returns { value, error, status, loading, refresh }. Counts as a read of .value, so it
starts a lazy resource on mount.
const stats = resource(fetchStats, { lazy: true });
function Stats() {
const { value, status, refresh } = useResource(stats);
if (status === 'loading' && !value) return <Spinner />;
return <button onClick={() => refresh()}>{value?.visits} visits (reload)</button>;
}Wraps a component so that every observable, computed, resource or store property read during
render is a dependency. The component re-renders only when one of those changes. The result is
memo-wrapped and keeps the original displayName.
const TodoCount = tracked(function TodoCount() {
const open = state.todos.filter((t) => !t.done).length; // per-property store tracking
return <span>{open} open</span>;
});A fine-grained island: only the children function re-renders.
<Observe>{() => <span>{count.value}</span>}</Observe>
// 0.2.x form, still supported
<Observe observer={count}>{(value) => <span>{value}</span>}</Observe>The 0.2.x names still work and are built on the v1 core, so they interoperate with everything
above. React hooks are now imported from cozyobserve/react. See MIGRATION.md
for the details.
import { Observer, ComputeObserver, AsyncObserver, deepObserver } from 'cozyobserve';
import { useComputeObserver, useAsyncObserver, useDeepObserver, Observe } from 'cozyobserve/react';
const observer = new Observer(10); // same class as observable(): has .value, peek(), update()...
const off = observer.subscribe((newValue, oldValue) => console.log(oldValue, '→', newValue));
observer.set(20); // logs "10 → 20"
off();
const a = new Observer(2);
const doubled = new ComputeObserver(() => a.get() * 2); // auto-tracks now; update() still works
a.set(5);
doubled.get(); // 10
const data = new AsyncObserver(fetch('/api/data').then((r) => r.json()));
data.get(); // null until resolved
await data.promise(); // resolves now if already resolved, rejects if the promise rejected
const { observer: person, unsubscribe } = deepObserver({ name: 'Alice', age: 25 }, (next, prev) => {
console.log(prev.age, '→', next.age); // frozen snapshots, once per batch
});
person.age = 26; // logs "25 → 26"
unsubscribe();| 0.2.x | v1 equivalent |
|---|---|
new Observer(v) |
observable(v) |
new ComputeObserver(fn) + update() |
computed(fn) (auto-tracked) |
new AsyncObserver(promise) |
resource(promise) or resource(fetcher) |
deepObserver(obj, cb) |
store(obj) + subscribeStore / effect |
useObserver(o) |
useObserver(o) from cozyobserve/react |
useComputeObserver(c) |
useObserver(c) |
useAsyncObserver(a) |
useResource(r) |
useDeepObserver(d) |
useStore(s) or tracked() |
Measured with npm run size (size-limit, minified and
brotlied, with all dependencies; react excluded):
| Import | Size |
|---|---|
{ observable, computed, effect, batch } from cozyobserve |
1.69 kB |
everything from cozyobserve (core, store, resource, compat) |
4.59 kB |
{ useObserver, useObserverEffect, tracked } from cozyobserve/react (incl. core) |
2.23 kB |
everything from cozyobserve/react (incl. the core it uses) |
4 kB |
The package is ESM + CJS, has sideEffects: false, and tree-shakes: you pay for what you
import.
Node 22, Apple M4, mitata. Average time per operation; lower is better. Numbers move by ±15% between runs, so treat small gaps as ties.
| Scenario | cozyobserve v1 | alien-signals | @preact/signals | MobX | cozyobserve 0.2 |
|---|---|---|---|---|---|
| Batch: 100 writes → 1 effect | 2.26 µs (fastest) | 2.69 µs | 2.95 µs | 5.67 µs | n/a |
| Create + dispose 1000 signals/effects | 50.9 µs | 48.9 µs | 63.5 µs | 549 µs | 50.5 µs |
| 1000-deep computed chain, write + read | 38.7 µs | 33.3 µs | 33.9 µs | 174 µs | 14.8 µs¹ |
| Fan-out: 1 → 1000 computeds → effect | 45.5 µs | 42.4 µs | 39.7 µs | 143 µs | 14.9 µs¹ |
Deep object a.b.count++ + listener |
350 ns | — | — | 609 ns | 795 ns |
| Same, with 200 sibling items | 384 ns (valtio 369 ns) | — | — | 622 ns | 112 µs |
¹ 0.2.x had no dependency tracking: every derived value had to be recomputed by hand with
update(), so it skips the bookkeeping that makes automatic updates possible.
The 7 scenarios and the sanity checks (which confirm every library does the same work) are in bench/README.md.
Run them yourself:
npm run benchSee bench/README.md for the scenarios, the libraries compared and the sanity checks each case passes before it is measured.
- Written in strict TypeScript; types ship with the package (ESM and CJS
.d.ts). Use TypeScript 5.4 or newer, and amoduleResolutionthat understandsexports(bundler,node16ornodenext) socozyobserve/reactresolves. - Types are inferred from the initial value. Widen when needed:
observable<Todo[]>([]),observable<string | null>(null). Observable<T>is writable;ReadonlyObservable<T>(whatcomputedreturns) is not. AcceptReadonlyObservable<T>in functions that only read.computedwith aprevargument needs the type spelled out:computed<number>((prev) => (prev ?? 0) + step.value).resourceinfersTfrom the fetcher's result, butctx.previsunknownunless you passTexplicitly:resource<Page>(async ({ prev }) => ...).snapshot()anduseStore()returnDeepReadonly<T>, so mutating a snapshot is a type error (and snapshots are frozen at runtime).- Exported types:
Observable,ReadonlyObservable,Unsubscribe,Equals,DeepReadonly,Resource,AsyncStatus,ResourceState,ResourceOptions,Fetcher,FetcherContext,ObserverCallback,ObserverSubscription, andUseResourceResultfromcozyobserve/react. - Runtime needs
Proxy,WeakMapand (forresource)AbortController. All modern browsers and Node 18+ have them.
MIT License. See the LICENSE file for details.
(Twitter/X: @papa_alpha_papa), (Mastodon: @papa_alpha_papa) (Bluesky: @erginturk.bsky.social)
Contributions are welcome! Feel free to open an issue or submit a pull request.
npm test # vitest
npm run typecheck
npm run size
npm run benchDeveloped with ❤️ by M. Ergin Turk
