538 lines
18 KiB
Markdown
538 lines
18 KiB
Markdown
# ⚙ automat
|
||
|
||
> Observable state management for React `PureComponent`.
|
||
> State lives **independently of component lifecycle** — mounts and unmounts freely without losing state.
|
||
> **No wrappers, no HOCs, no `connect()` — purely direct access and lifecycle subscriber handling.**
|
||
|
||
```bash
|
||
npm run dev
|
||
```
|
||
|
||
---
|
||
|
||
## Motivation
|
||
|
||
Redux separates state from UI, but brings boilerplate and pushes toward hooks. Higher-order wrappers and `connect()` introduce indirection, wrapper nesting, and tricky state hydration.
|
||
|
||
`automat` provides a clean, direct approach centered on standard `React.PureComponent`:
|
||
|
||
1. **Instantiate first**: The Automat instance is created outside React's render tree.
|
||
2. **Direct constructor access**: Components initialize directly from `automat.state` (or `getState()`) — never stale, even after transitions prior to mounting.
|
||
3. **Lifecycle subscriber handling**: In `componentDidMount`, register the component with `automat.subscribe(this)`. In `componentWillUnmount`, call `this.unsubscribe()` or `automat.unsubscribe(this)`.
|
||
4. **Direct event wiring**: Call `automat.actions.actionName()` or `automat.setState(...)` directly in `onClick` handlers. No dispatchers, actions creators, or prop drilling.
|
||
5. **Render minimization**: Standard `PureComponent` shallow state comparison prevents unnecessary re-renders automatically without extra layers.
|
||
|
||
---
|
||
|
||
## Direct PureComponent Pattern (Wired Click Example)
|
||
|
||
Here is a complete, two-component example showing how clicks trigger actions and synchronize independent components:
|
||
|
||
```jsx
|
||
import { PureComponent } from 'react';
|
||
import { Automat } from 'automat';
|
||
|
||
// 1. Instantiate the automat outside React:
|
||
const counterAutomat = new Automat(
|
||
{ count: 0 },
|
||
{
|
||
increment(step = 1) {
|
||
counterAutomat.setState({ count: counterAutomat.state.count + step });
|
||
},
|
||
decrement(step = 1) {
|
||
counterAutomat.setState({ count: counterAutomat.state.count - step });
|
||
},
|
||
reset() {
|
||
counterAutomat.setState({ count: 0 });
|
||
},
|
||
}
|
||
);
|
||
|
||
// 2. Controller component: buttons trigger actions, hybrid state tracks local clicks
|
||
class CounterButton extends PureComponent {
|
||
constructor(props) {
|
||
super(props);
|
||
// 💡 HYBRID STATE:
|
||
// Shared count comes from the automat; step & localClicks are local
|
||
this.state = {
|
||
count: counterAutomat.state.count, // ← from automat
|
||
step: 1, // ← component-local state
|
||
localClicks: 0, // ← component-local state
|
||
};
|
||
}
|
||
|
||
componentDidMount() {
|
||
// Subscribe component to automat updates
|
||
this.unsubscribe = counterAutomat.subscribe(this);
|
||
}
|
||
|
||
componentWillUnmount() {
|
||
this.unsubscribe();
|
||
}
|
||
|
||
// 💡 CLICK HANDLERS: update local state AND trigger automat actions
|
||
handleIncrement = () => {
|
||
const { step, localClicks } = this.state;
|
||
this.setState({ localClicks: localClicks + 1 });
|
||
counterAutomat.actions.increment(step); // ← Triggers automat!
|
||
};
|
||
|
||
handleDecrement = () => {
|
||
const { step, localClicks } = this.state;
|
||
this.setState({ localClicks: localClicks + 1 });
|
||
counterAutomat.actions.decrement(step); // ← Triggers automat!
|
||
};
|
||
|
||
handleReset = () => {
|
||
this.setState({ localClicks: 0 });
|
||
counterAutomat.actions.reset(); // ← Triggers automat!
|
||
};
|
||
|
||
render() {
|
||
const { count, step, localClicks } = this.state;
|
||
return (
|
||
<div className="card">
|
||
<p>Count: {count} · Local Clicks: {localClicks}</p>
|
||
|
||
{/* 💡 WIRED ONCLICK: calls handlers directly */}
|
||
<button onClick={this.handleDecrement}>−{step}</button>
|
||
<button onClick={this.handleIncrement}>+{step}</button>
|
||
<button onClick={this.handleReset}>Reset</button>
|
||
</div>
|
||
);
|
||
}
|
||
}
|
||
|
||
// 3. Independent Display component: reads same automat with ZERO props passed
|
||
class CounterDisplay extends PureComponent {
|
||
constructor(props) {
|
||
super(props);
|
||
// Reads directly from automat in constructor:
|
||
this.state = counterAutomat.state;
|
||
}
|
||
|
||
componentDidMount() {
|
||
// Automatically re-renders when CounterButton triggers an increment/decrement
|
||
this.unsubscribe = counterAutomat.subscribe(this);
|
||
}
|
||
|
||
componentWillUnmount() {
|
||
this.unsubscribe();
|
||
}
|
||
|
||
render() {
|
||
return <h1>Display: {this.state.count}</h1>;
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### Why Hybrid State works seamlessly with React PureComponent
|
||
|
||
When `counterAutomat.setState({ count: 42 })` notifies the subscriber:
|
||
1. It calls `this.setState({ count: 42 })` on the component instance.
|
||
2. React's class component `setState` performs a **shallow merge** into `this.state`.
|
||
3. Local fields (`step`, `localClicks`, `inputValue`) remain untouched.
|
||
4. `PureComponent`'s shallow comparison ensures renders happen only when values change.
|
||
|
||
```jsx
|
||
class SearchBox extends PureComponent {
|
||
constructor(props) {
|
||
super(props);
|
||
this.state = {
|
||
...searchAutomat.state, // results, loading, etc.
|
||
inputValue: '', // component-local input
|
||
};
|
||
}
|
||
|
||
componentDidMount() {
|
||
this.unsubscribe = searchAutomat.subscribe(this);
|
||
}
|
||
|
||
componentWillUnmount() {
|
||
this.unsubscribe();
|
||
}
|
||
|
||
handleInput = (e) => {
|
||
this.setState({ inputValue: e.target.value });
|
||
};
|
||
|
||
// 💡 Wired form submission / click:
|
||
handleSubmit = (e) => {
|
||
e.preventDefault();
|
||
const query = this.state.inputValue.trim();
|
||
if (query) {
|
||
searchAutomat.actions.search(query); // ← Triggers async search action
|
||
}
|
||
};
|
||
|
||
render() {
|
||
const { loading, results, inputValue } = this.state;
|
||
return (
|
||
<form onSubmit={this.handleSubmit}>
|
||
<input
|
||
type="text"
|
||
value={inputValue}
|
||
onChange={this.handleInput}
|
||
placeholder="Search items…"
|
||
/>
|
||
{/* 💡 Click triggers handleSubmit → searchAutomat.actions.search() */}
|
||
<button type="submit" disabled={loading}>
|
||
{loading ? 'Searching…' : 'Search'}
|
||
</button>
|
||
|
||
<ul>
|
||
{results?.map((item) => (
|
||
<li key={item.id}>{item.title}</li>
|
||
))}
|
||
</ul>
|
||
</form>
|
||
);
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## Core API
|
||
|
||
### `new Automat(initialState, actions?)`
|
||
|
||
```js
|
||
import { Automat } from './src/lib/index.js';
|
||
|
||
const counterAutomat = new Automat(
|
||
{ count: 0 },
|
||
{
|
||
increment(step = 1) {
|
||
counterAutomat.setState({ count: counterAutomat.state.count + step });
|
||
},
|
||
decrement(step = 1) {
|
||
counterAutomat.setState({ count: counterAutomat.state.count - step });
|
||
},
|
||
reset() {
|
||
counterAutomat.setState({ count: 0 });
|
||
},
|
||
}
|
||
);
|
||
```
|
||
|
||
| Member | Description |
|
||
|---|---|
|
||
| `automat.state` | Direct getter for current state snapshot (ideal for `constructor`) |
|
||
| `automat.getState()` | Returns current state snapshot |
|
||
| `automat.setState(partial)` | Merges partial into state and notifies all subscribers |
|
||
| `automat.subscribe(target, selector?)` | Subscribes a component (`this`) or callback. Supports key string, key array, or selector function. Avoids unnecessary re-renders via shallow equality check. |
|
||
| `automat.select(selector)` | Returns a sliced view `{ readonly state, subscribe(target) }` for direct constructor reads and scoped subscriptions. |
|
||
| `automat.unsubscribe(target)` | Unsubscribes a component instance or callback function |
|
||
| `automat.subscribeTo(upstream, transform)` | Notification cascade: derives state from an upstream automat |
|
||
| `automat.actions` | Named action callbacks passed to constructor — call directly from `onClick` |
|
||
| `automat.dispose()` | Tears down all upstream subscriptions and clears all subscribers |
|
||
|
||
---
|
||
|
||
## Subscribing to Part of the State (Slice Subscriptions)
|
||
|
||
When an automat has multiple fields (e.g. `{ count, filter, theme, user }`), subscribing without a selector will cause any state change to trigger `this.setState()` on the subscriber.
|
||
|
||
When a component only cares about a subset of the automat's state, subscribe with a **slice selector**. `Automat` performs an internal shallow equality check (`shallowEqual(lastSlice, nextSlice)`), ensuring updates to other unrelated fields **never trigger `setState` or re-renders**:
|
||
|
||
### 1. Single Key String
|
||
```jsx
|
||
// Subscribes only to changes in 'count'. Unrelated fields will NOT trigger setState:
|
||
this.unsubscribe = myAutomat.subscribe(this, 'count');
|
||
```
|
||
|
||
### 2. Array of Keys
|
||
```jsx
|
||
// Subscribes only to 'count' and 'step':
|
||
this.unsubscribe = myAutomat.subscribe(this, ['count', 'step']);
|
||
```
|
||
|
||
### 3. Custom Selector Function
|
||
```jsx
|
||
// Computes a derived slice; returning null/undefined skips updates:
|
||
this.unsubscribe = myAutomat.subscribe(this, (state) => ({
|
||
count: state.count,
|
||
isEven: state.count % 2 === 0,
|
||
}));
|
||
```
|
||
|
||
### 4. Automat Slicing with `.select()`
|
||
```jsx
|
||
const countSlice = myAutomat.select('count');
|
||
this.state = countSlice.state; // { count: 0 }
|
||
this.unsubscribe = countSlice.subscribe(this);
|
||
```
|
||
|
||
---
|
||
|
||
## Notification Cascade (Wired Example)
|
||
|
||
### How `subscribeTo()` Works (Reactive Pipeline)
|
||
|
||
`subscribeTo()` establishes a **reactive pipeline between two automats** without React components in the middle. Think of it like a database trigger or spreadsheet formula: when the upstream changes, the downstream automatically derives new state.
|
||
|
||
```
|
||
┌─────────────────┐ setState() ┌─────────────────────────┐
|
||
│ counterAutomat │ ───────────────────> │ notificationAutomat │
|
||
│ (Upstream) │ │ (Downstream) │
|
||
└─────────────────┘ └────────────┬────────────┘
|
||
│ notifies
|
||
▼
|
||
┌─────────────────────────┐
|
||
│ NotificationBar │
|
||
│ (PureComponent UI) │
|
||
└─────────────────────────┘
|
||
```
|
||
|
||
#### Code Anatomy:
|
||
|
||
```js
|
||
// 1. Upstream automat (e.g. holds raw counter)
|
||
const counterAutomat = new Automat({ count: 0 }, {
|
||
increment(step = 1) {
|
||
counterAutomat.setState({ count: counterAutomat.state.count + step });
|
||
},
|
||
});
|
||
|
||
// 2. Downstream automat (e.g. maintains an event/audit log)
|
||
const notificationAutomat = new Automat(
|
||
{ messages: [] },
|
||
{
|
||
clear() { notificationAutomat.setState({ messages: [] }); },
|
||
}
|
||
);
|
||
|
||
// 3. Connect downstream to upstream (returns null to filter, or state object):
|
||
notificationAutomat.subscribeTo(
|
||
counterAutomat,
|
||
(upstream, my) =>
|
||
upstream.count === 0
|
||
? null
|
||
: {
|
||
messages: [
|
||
{
|
||
id: Date.now(),
|
||
text: `Counter changed to ${upstream.count}`,
|
||
time: new Date().toLocaleTimeString(),
|
||
count: upstream.count,
|
||
},
|
||
...my.messages.slice(0, 9), // Caps list at 10 items
|
||
],
|
||
}
|
||
);
|
||
```
|
||
|
||
#### Parameter Breakdown:
|
||
|
||
| Parameter | What it receives | Purpose |
|
||
|---|---|---|
|
||
| `upstreamAutomat` | `counterAutomat` | The automat to watch. Any time it calls `setState()`, the transform runs. |
|
||
| `upstreamState` | `{ count: 42 }` | The **new state snapshot** of the upstream automat. |
|
||
| `myState` | `{ messages: [...] }` | The **current state snapshot** of *this* downstream automat right before updating. Essential for accumulating history, comparing previous values, or merging. |
|
||
| **Return value** | `{ messages: [...] }` | A **partial state object** passed to `this.setState(partial)`. Returning `null` skips the update. |
|
||
|
||
#### Filtering Updates (Conditional Derivation):
|
||
|
||
You can selectively ignore upstream events by returning `null`:
|
||
|
||
```js
|
||
// Only log notifications when count exceeds 10:
|
||
notificationAutomat.subscribeTo(counterAutomat, (upstreamState, myState) => {
|
||
if (upstreamState.count < 10) {
|
||
return null; // 💡 Returning null skips setState — no re-renders!
|
||
}
|
||
return {
|
||
messages: [{ id: Date.now(), text: `High value reached: ${upstreamState.count}` }, ...myState.messages],
|
||
};
|
||
});
|
||
```
|
||
|
||
#### Multiple Upstream Sources & Chaining:
|
||
|
||
`subscribeTo()` returns `this`, so an automat can aggregate from multiple independent sources:
|
||
|
||
```js
|
||
dashboardAutomat
|
||
.subscribeTo(userAutomat, (user) => ({ username: user.name }))
|
||
.subscribeTo(cartAutomat, (cart) => ({ cartItemCount: cart.items.length }));
|
||
```
|
||
|
||
#### Teardown:
|
||
|
||
Calling `notificationAutomat.dispose()` unsubscribes all upstream listeners automatically to prevent memory leaks when an automat is torn down.
|
||
|
||
|
||
### Wiring the Cascade in UI:
|
||
|
||
```jsx
|
||
// 4. Controller component: buttons trigger the UPSTREAM automat
|
||
class CascadeControls extends PureComponent {
|
||
handleTrigger = (step) => {
|
||
// 💡 CLICK WIRED HERE:
|
||
// Calling counterAutomat triggers notificationAutomat downstream!
|
||
counterAutomat.actions.increment(step);
|
||
};
|
||
|
||
handleClear = () => {
|
||
notificationAutomat.actions.clear();
|
||
};
|
||
|
||
render() {
|
||
return (
|
||
<div>
|
||
<button onClick={() => this.handleTrigger(1)}>Trigger (+1)</button>
|
||
<button onClick={() => this.handleTrigger(5)}>Trigger (+5)</button>
|
||
<button onClick={this.handleClear}>Clear Stream</button>
|
||
</div>
|
||
);
|
||
}
|
||
}
|
||
|
||
// 5. Downstream component: automatically receives derived cascade messages
|
||
class NotificationBar extends PureComponent {
|
||
constructor(props) {
|
||
super(props);
|
||
this.state = {
|
||
messages: notificationAutomat.state.messages, // ← from cascade
|
||
filter: 'all', // ← component-local
|
||
};
|
||
}
|
||
|
||
componentDidMount() {
|
||
this.unsub = notificationAutomat.subscribe(this);
|
||
}
|
||
|
||
componentWillUnmount() {
|
||
this.unsub();
|
||
}
|
||
|
||
render() {
|
||
const { messages } = this.state;
|
||
return (
|
||
<ul>
|
||
{messages.map((m) => (
|
||
<li key={m.id}>{m.text} ({m.time})</li>
|
||
))}
|
||
</ul>
|
||
);
|
||
}
|
||
}
|
||
```
|
||
|
||
When `counterAutomat.setState()` fires → `transform` runs → `notificationAutomat.setState()` fires → `NotificationBar` automatically re-renders.
|
||
|
||
---
|
||
|
||
## API-Backed Auto-Sync Counter (POST)
|
||
|
||
An automat can perform optimistic state updates immediately for instant UI feedback, while automatically synchronizing mutations to the backend via HTTP POST in the background:
|
||
|
||
```js
|
||
// syncCounterAutomat.js
|
||
const syncCounterAutomat = new Automat(
|
||
{
|
||
index: 0,
|
||
count: 0,
|
||
syncStatus: 'synced', // 'syncing' | 'synced' | 'error'
|
||
lastSyncedAt: null,
|
||
},
|
||
{
|
||
async increment(step = 1) {
|
||
const { index, count } = syncCounterAutomat.state;
|
||
const nextCount = count + step;
|
||
|
||
// 1. Optimistic update (UI updates immediately):
|
||
syncCounterAutomat.setState({ count: nextCount, syncStatus: 'syncing' });
|
||
|
||
// 2. Automatic background sync via POST /api/counter:
|
||
try {
|
||
const res = await fetch('/api/counter', {
|
||
method: 'POST',
|
||
headers: { 'Content-Type': 'application/json' },
|
||
body: JSON.stringify({ index, count: nextCount }),
|
||
});
|
||
const data = await res.json();
|
||
syncCounterAutomat.setState({ syncStatus: 'synced', lastSyncedAt: data.savedAt });
|
||
} catch (err) {
|
||
syncCounterAutomat.setState({ syncStatus: 'error', error: err.message });
|
||
}
|
||
},
|
||
}
|
||
);
|
||
```
|
||
|
||
### Component Wiring:
|
||
|
||
```jsx
|
||
class SyncCounterControls extends PureComponent {
|
||
state = syncCounterAutomat.state;
|
||
|
||
componentDidMount() {
|
||
this.unsubscribe = syncCounterAutomat.subscribe(this);
|
||
}
|
||
|
||
componentWillUnmount() {
|
||
this.unsubscribe();
|
||
}
|
||
|
||
render() {
|
||
const { index, count, syncStatus, lastSyncedAt } = this.state;
|
||
return (
|
||
<div>
|
||
<h3>Counter #{index}: {count}</h3>
|
||
<button onClick={() => syncCounterAutomat.actions.increment(1)}>+1</button>
|
||
<span>Status: {syncStatus === 'syncing' ? 'POST in flight…' : `Synced (${lastSyncedAt})`}</span>
|
||
</div>
|
||
);
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## Building the Standalone Library
|
||
|
||
```bash
|
||
npm run build:lib
|
||
```
|
||
|
||
Produces minified, zero-dependency bundles in `dist/`:
|
||
- `dist/automat.es.js` (~1.14 kB raw / **545 B** gzipped)
|
||
- `dist/automat.umd.js` (~1.09 kB raw / **552 B** gzipped)
|
||
|
||
---
|
||
|
||
## Project Structure
|
||
|
||
```
|
||
src/
|
||
├── lib/
|
||
│ ├── Automat.js ← core observable state class
|
||
│ └── index.js ← public re-exports
|
||
│
|
||
└── examples/
|
||
├── automats/
|
||
│ ├── counterAutomat.js ← local memory automat
|
||
│ ├── notificationAutomat.js ← subscribes to counter (cascade)
|
||
│ ├── syncCounterAutomat.js ← API-backed auto-sync indexed counter (POST)
|
||
│ └── indexAutomat.js ← shared index + dynamic window.automats Map
|
||
└── components/
|
||
├── CounterButton.jsx ← PureComponent with direct constructor & subscribe
|
||
├── CounterDisplay.jsx ← independent PureComponent synced via counterAutomat
|
||
├── CascadeControls.jsx ← PureComponent driving and demonstrating upstream cascade
|
||
├── NotificationBar.jsx ← independent PureComponent displaying cascade stream
|
||
├── SyncCounterControls.jsx ← PureComponent driving auto-sync indexed counter
|
||
├── SyncBackendMonitor.jsx ← PureComponent inspecting backend DB and POST payload
|
||
├── IndexSelector.jsx ← PureComponent driving shared index counter
|
||
└── DynamicAutomatSubscriber.jsx ← dynamically resubscribes to window.automats by index
|
||
```
|
||
|
||
---
|
||
|
||
## License
|
||
|
||
MIT
|