reactive/data-client / .agents/skills/data-client-manager
data-client-manager
VerifiedWrite @data-client Managers, the runtime layer that bridges the store to the world outside the view framework: global side effects and real-time data such as websockets, SSE and polling. A Manager reacts to every request or to events from outside the app, and moves data into or out of the store. Use one instead of useEffect for behavior that belongs to the whole app, such as error toasts and reporting, logging and analytics, auth failures, refetching on focus or reconnect, and cross-tab sync. Not for the shape of data: data built from responses (joined, derived, or accumulated) is defined in a schema, so use data-client-schema.
Managers: the store's bridge to the world outside the view framework
Data Client keeps three layers apart. The data definition is the data model (schemas) and the API definition
(endpoints): the operations on that data model. Hooks are the runtime in the view framework.
Managers are the runtime outside it: they bridge the store to sockets, timers, browser events,
other tabs, logging and reporting services, as useEffect bridges a component to what is outside React.
The store is flux: unidirectional data flow through a pure reducer. Managers orchestrate its global side effects, in two directions:
- In: an outside event becomes an action, dispatched through Controller: a socket message, a timer, a window focus.
- Out: an action causes an effect outside the store, from the Manager's redux middleware: a log line, a toast, a report.
A Manager does not define data. The data model stays in the schema, also when a Manager delivers the data: the Manager
calls controller.set(), and the Entity's process() and merge() decide what the store keeps. Data joined, derived,
or accumulated from responses needs no Manager of its own: write it in the schema (skill "data-client-schema").
Single Responsibility
One concern per Manager; compose many small managers (e.g. transport, subscriptions, logging, auth) rather than one large one.
Every Manager defines a middleware property and a cleanup() method. A Manager with nothing to intercept passes actions through: middleware: Middleware = controller => next => async action => next(action);
Each store gets its own Managers, so code lives at one of three lifetimes:
| Lifetime | Lasts | Holds |
|---|---|---|
| Config | the page | constructor options, like a URL or callbacks. The constructor only stores them |
| Store | one store | instance fields about the store, like the controller and fetches in flight |
| Active | init() to cleanup() | timers, intervals, connections and listeners |
cleanup() pauses Managers without ending the store: React StrictMode and <Activity> hiding DataProvider call cleanup() and later init() on the same store, and actions keep arriving in between. So:
- Keep the controller from
middleware(this.controller = controller) to use ininit().init(state)gets the store's current state, also on resume. - Don't reset state about the store, like fetches in flight, in
cleanup(). - Guard side effects in
middlewarewith a fieldcleanup()clears, likethis.channel?.postMessage().
Use cases
Minimal working examples for each use case live in references/managers.md (see the named section) unless another file is linked:
| Use case | Reference | Key technique |
|---|---|---|
| Logging actions/state | "Middleware logging" in managers.md | log around await next(action) |
| Error reporting/monitoring (Sentry) | "Error reporting" in managers.md | SET_RESPONSE with action.error |
| Analytics/metrics (fetch timing) | "Metrics" in managers.md | FETCH action's action.meta.promise |
| Toast notifications on mutations | "Notifications" in managers.md | SET_RESPONSE with action.endpoint.sideEffect |
| Refetch on window focus / network reconnect | "Refresh on focus or reconnect" in managers.md | controller.expireAll() from event listeners in init()/cleanup() |
| Cross-tab sync | "Cross-tab synchronization" in managers.md | BroadcastChannel + controller.expireAll() |
| Offline persistence (IndexedDB) | "Offline persistence" in managers.md | debounced IndexedDB write of controller.getState() (drop optimistic - not cloneable); restore via DataProvider initialState. Never use localStorage (blocking) |
| Websocket/SSE push streams | "Middleware data stream" in managers.md | controller.set() on message; connect in init(), close in cleanup() |
| High-frequency streams / snapshots | "Batching high-frequency updates" in managers.md | buffer, then one controller.set([Entity], rows) per flush |
| Polling/interval updates (ticker) | "Dispatching Actions" in Manager.md; TimeManager below | setInterval in init() + controller.set() |
| Custom transport subscriptions | "Reading and Consuming Actions" in Manager.md | consume SUBSCRIBE/UNSUBSCRIBE without calling next |
| Auth: logout on 401, reset store on deauth | LogoutManager.md | handleLogout(controller) + controller.resetEntireStore() |
References
Vue projects: read <name>.vue.md instead of <name>.md when it exists.
For detailed API documentation, see the references directory:
- Manager - Manager interface and lifecycle
- Actions - Action types and payloads
- Controller - Imperative actions
- LogoutManager - Handling logout/cleanup
- getDefaultManagers - Default manager configuration
- managers - Managers concept guide
Always use actionTypes when comparing action.type. Refer to Actions for list of actions and their payloads.
Dispatching actions
Controller has dispatchers: ctrl.fetch(), ctrl.fetchIfStale(), ctrl.expireAll(), ctrl.invalidate(), ctrl.invalidateAll(), ctrl.setResponse(), ctrl.set(), ctrl.setError(), ctrl.resetEntireStore(), ctrl.subscribe(), ctrl.unsubscribe().
import type { Controller, Manager, Middleware } from '@data-client/react'; // or '@data-client/vue'
import CurrentTime from './CurrentTime';
export default class TimeManager implements Manager {
declare protected controller: Controller;
declare protected intervalID?: ReturnType<typeof setInterval>;
middleware: Middleware = controller => {
this.controller = controller;
return next => async action => next(action);
};
init() {
this.intervalID = setInterval(() => {
this.controller.set(CurrentTime, { id: 1 }, { id: 1, time: Date.now() });
}, 1000);
}
cleanup() {
clearInterval(this.intervalID);
}
}
Write many entities in one store update with controller.set([Entity], rows) (websocket snapshots, buffered stream messages). Never loop controller.set(Entity, args, row) per row, and never add an endpoint or setResponse() just to batch.
Reading and Consuming Actions
Controller has data accessors: ctrl.getResponse(), ctrl.getState(), ctrl.get(), ctrl.getError(), ctrl.snapshot().
import type { Manager, Middleware } from '@data-client/react';
import { actionTypes } from '@data-client/react';
export default class LoggingManager implements Manager {
middleware: Middleware = controller => next => async action => {
switch (action.type) {
case actionTypes.SET_RESPONSE:
if (action.endpoint.sideEffect) {
console.info(
`${action.endpoint.name} ${JSON.stringify(action.response)}`,
);
// wait for state update to be committed to React
await next(action);
// get the data from the store, which may be merged with existing state
const { data } = controller.getResponse(
action.endpoint,
...action.args,
controller.getState(),
);
console.info(`${action.endpoint.name} ${JSON.stringify(data)}`);
return;
}
// actions must be explicitly passed to next middleware
default:
return next(action);
}
};
cleanup() {}
}
Always use actionTypes members to check action.type.
actionTypes has: FETCH, SET, SET_RESPONSE, RESET, SUBSCRIBE, UNSUBSCRIBE, INVALIDATE, INVALIDATEALL, EXPIREALL
actions docs details the action types and their payloads.
Consuming actions
import type { Manager, Middleware, EntityInterface } from '@data-client/react';
import { actionTypes } from '@data-client/react';
import isEntity from './isEntity';
export default class CustomSubsManager implements Manager {
declare protected entities: Record<string, EntityInterface>;
middleware: Middleware = controller => next => async action => {
switch (action.type) {
case actionTypes.SUBSCRIBE:
case actionTypes.UNSUBSCRIBE:
const { schema } = action.endpoint;
// only process registered entities
if (schema && isEntity(schema) && schema.key in this.entities) {
if (action.type === actionTypes.SUBSCRIBE) {
this.subscribe(schema.key, action.args[0]?.product_id);
} else {
this.unsubscribe(schema.key, action.args[0]?.product_id);
}
// consume subscription to prevent it from being processed by other managers
return Promise.resolve();
}
default:
return next(action);
}
};
cleanup() {}
subscribe(channel: string, product_id: string) {}
unsubscribe(channel: string, product_id: string) {}
}
Usage
Pass a function that returns the managers, defined at module level; it runs once per store. Create each Manager inside the function: an instance made outside it is shared by every store.
List custom managers before ...getDefaultManagers(). Actions pass through managers in array order, and NetworkManager (one of the defaults) resolves each FETCH itself instead of passing it on (only optimistic mutations continue), so a manager listed after it misses most fetches:
import { DataProvider, getDefaultManagers } from '@data-client/react';
import { createRoot } from 'react-dom/client';
const managers = () => [new MyManager(), ...getDefaultManagers()];
createRoot(document.body).render(
<DataProvider managers={managers}>
<App />
</DataProvider>,
);
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| deprecation-and-migrationaddyosmani/agent-skillsManages deprecation and migration. Use when removing old systems, APIs, or features. Use when migrating users from one implementation to another. Use when migrating a database schema in production, such as renaming or dropping a column without downtime (expand/contract). Use when deciding whether to maintain or sunset existing code. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| performance-optimizationaddyosmani/agent-skillsOptimizes application performance across frontend, backend, queries, and databases. Use when performance requirements exist, when you suspect performance regressions, when Core Web Vitals or load times need improvement, when N+1 query patterns need fixing, or when profiling reveals bottlenecks. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| Agent Cost Reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json. | Stars: 117k | Updated | Claude CodeCodex | Verified | Install |
| Agent Cost Reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json. | Stars: 117k | Updated | Claude CodeCodex | Verified | Install |