# atomirx
**Opinionated, Batteries-Included Reactive State Management for React**
[](https://www.npmjs.com/package/atomirx)
[](https://www.npmjs.com/package/atomirx)
[](https://bundlephobia.com/package/atomirx)
[](./LICENSE)
---
## Overview
atomirx is a reactive state management library that combines the simplicity of atoms with powerful async handling. Built with TypeScript-first design, it provides a complete solution for managing application state with first-class support for async operations, computed values, and React integration.
### Key Features
- **Atoms** - Simple, reactive state containers
- **Derived Atoms** - Computed values with automatic dependency tracking
- **Effects** - Side effects that react to state changes
- **Pools** - Parameterized atom families with automatic garbage collection
- **Async-First** - Built-in Suspense support for async operations
- **React Integration** - Hooks and utilities for seamless React usage
- **TypeScript** - Full type safety with excellent inference
- **Tiny** - Zero dependencies (except lodash for deep equality)
## Installation
```bash
npm install atomirx
# or
pnpm add atomirx
# or
yarn add atomirx
```
## Quick Start
```tsx
import { atom, derived, effect } from 'atomirx';
import { useSelector, rx } from 'atomirx/react';
// Create a mutable atom
const count$ = atom(0);
// Create a derived atom (computed value)
const doubled$ = derived(({ read }) => read(count$) * 2);
// Create a side effect
effect(({ read }) => {
console.log('Count changed:', read(count$));
});
// Use in React
function Counter() {
const count = useSelector(count$);
const doubled = useSelector(doubled$);
return (
Count: {count}
Doubled: {doubled}
);
}
```
## Table of Contents
- [Core Concepts](#core-concepts)
- [Atoms](#atoms)
- [Derived Atoms](#derived-atoms)
- [Effects](#effects)
- [Pools](#pools)
- [Batching](#batching)
- [Modules (define)](#modules-define)
- [React Integration](#react-integration)
- [useSelector](#useselector)
- [rx](#rx)
- [useAction](#useaction)
- [useStable](#usestable)
- [Async Operations](#async-operations)
- [Suspense Support](#suspense-support)
- [Async Utilities](#async-utilities)
- [Promise State Tracking](#promise-state-tracking)
- [Advanced Topics](#advanced-topics)
- [Select Context](#select-context)
- [Equality Functions](#equality-functions)
- [Error Handling](#error-handling)
- [DevTools & Hooks](#devtools--hooks)
- [API Reference](#api-reference)
- [Documentation](#documentation)
---
## Core Concepts
### Atoms
Atoms are the fundamental building blocks - simple reactive containers that hold a single value.
```ts
import { atom } from 'atomirx';
// Create an atom with initial value
const count$ = atom(0);
// Read the current value
count$.get(); // 0
// Update the value
count$.set(5);
count$.set(prev => prev + 1); // Reducer pattern
// Reset to initial value
count$.reset();
// Subscribe to changes
const unsubscribe = count$.on(() => {
console.log('Count changed:', count$.get());
});
```
#### Lazy Initialization
```ts
// Value computed at creation time
const timestamp$ = atom(() => Date.now());
// Reset re-runs the initializer
timestamp$.reset(); // Gets new timestamp
```
#### Storing Functions
```ts
// To store a function as a value, wrap it
const callback$ = atom(() => () => console.log('hello'));
```
#### Atom with Context
```ts
const data$ = atom((context) => {
// Access AbortSignal for cancellation
const signal = context.signal;
// Register cleanup function
context.onCleanup(() => {
console.log('Cleanup on value change');
});
return fetchData({ signal });
});
```
### Derived Atoms
Derived atoms compute values from other atoms with automatic dependency tracking.
```ts
import { derived } from 'atomirx';
const firstName$ = atom('John');
const lastName$ = atom('Doe');
// Simple derived value
const fullName$ = derived(({ read }) =>
`${read(firstName$)} ${read(lastName$)}`
);
// Access the computed value (always returns Promise)
await fullName$.get(); // "John Doe"
// Access stale/cached value synchronously
fullName$.staleValue; // "John Doe" or undefined if not computed yet
// Check current state
fullName$.state(); // { status: "ready", value: "John Doe" }
// Force recomputation
fullName$.refresh();
```
#### Derived with Fallback
```ts
const posts$ = atom(fetchPosts()); // Async atom
// Without fallback - staleValue can be undefined
const postCount$ = derived(({ read }) => read(posts$).length);
postCount$.staleValue; // number | undefined
// With fallback - staleValue is guaranteed
const postCountSafe$ = derived(
({ read }) => read(posts$).length,
{ fallback: 0 }
);
postCountSafe$.staleValue; // number (0 during loading)
```
### Effects
Effects run side effects in response to atom changes.
```ts
import { effect } from 'atomirx';
// Basic effect
const dispose = effect(({ read }) => {
const count = read(count$);
localStorage.setItem('count', String(count));
});
// Stop the effect
dispose();
```
#### Effect with Cleanup
```ts
effect(({ read, onCleanup }) => {
const interval = read(interval$);
const id = setInterval(() => console.log('tick'), interval);
// Cleanup runs before next execution or on dispose
onCleanup(() => clearInterval(id));
});
```
#### Effect with AbortSignal
Effects provide a `signal` for cancelling async operations:
```ts
effect(({ read, signal }) => {
const userId = read(userId$);
// Signal is automatically aborted when effect re-runs or disposes
fetch(`/api/users/${userId}`, { signal })
.then(r => r.json())
.then(user => user$.set(user))
.catch(err => {
if (err.name !== 'AbortError') throw err;
});
});
```
### Pools
Pools are parameterized collections of atoms with automatic garbage collection.
```ts
import { pool } from 'atomirx';
// Create a pool with GC after 60 seconds of inactivity
const userPool = pool(
(id: string) => fetchUser(id),
{ gcTime: 60_000 }
);
// Get/set values directly
const user = userPool.get('user-1');
userPool.set('user-1', { name: 'John', email: 'john@example.com' });
// Check existence
userPool.has('user-1'); // true
// Remove entry
userPool.remove('user-1');
// Clear all entries
userPool.clear();
// Subscribe to changes
userPool.onChange((id, value) => console.log('Changed:', id, value));
userPool.onRemove((id, value) => console.log('Removed:', id, value));
```
#### Pool in Reactive Context
```ts
// Use from() in derived/effect/useSelector
const userPosts$ = derived(({ read, from }) => {
const userId = read(currentUserId$);
const user = read(from(userPool, userId)); // Creates VirtualAtom
return user.posts;
});
```
### Batching
Batch multiple updates to prevent intermediate renders.
```ts
import { batch } from 'atomirx';
const firstName$ = atom('');
const lastName$ = atom('');
// Without batch: 2 notifications
firstName$.set('John');
lastName$.set('Doe');
// With batch: 1 notification after both updates
batch(() => {
firstName$.set('John');
lastName$.set('Doe');
});
```
### Modules (define)
Create swappable lazy singleton stores for better organization and testing.
```ts
import { define, atom, readonly } from 'atomirx';
const counterModule = define(() => {
const count$ = atom(0);
return {
// Expose as read-only to consumers
count$: readonly(count$),
// Actions
increment: () => count$.set(c => c + 1),
decrement: () => count$.set(c => c - 1),
reset: () => count$.reset(),
};
});
// Usage
const { count$, increment } = counterModule();
increment();
```
#### Override for Testing
```ts
// In tests
beforeEach(() => {
counterModule.override(() => ({
count$: atom(999),
increment: vi.fn(),
decrement: vi.fn(),
reset: vi.fn(),
}));
});
afterEach(() => {
counterModule.reset();
});
```
---
## React Integration
### useSelector
React hook for selecting values from atoms with automatic subscriptions.
```tsx
import { useSelector } from 'atomirx/react';
function Counter() {
// Single atom
const count = useSelector(count$);
// Derived value with selector
const doubled = useSelector(({ read }) => read(count$) * 2);
// Multiple atoms
const fullName = useSelector(({ read }) =>
`${read(firstName$)} ${read(lastName$)}`
);
return
{count} - {doubled} - {fullName}
;
}
```
### rx
Inline reactive component for fine-grained updates.
```tsx
import { rx } from 'atomirx/react';
function Counter() {
// Only the rx component re-renders when count changes
return (