Skip to content

reactive/data-client / .agents/skills/data-client-manager

data-client-manager

Verified

Write @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.

references/Manager.vue.md

View on GitHub
<!-- Generated by `yarn build:skills` from docs/core/api/Manager.md (vue). Edit the source doc, not this file. -->

# Manager

`Managers` handle global side effects. They are like [watchEffect()](https://vuejs.org/api/reactivity-core.html#watcheffect), but for the central data
store.

The default managers run the asynchronous behavior that Data Client provides,
such as fetching and subscriptions. Configure them with [getDefaultManagers()](./getDefaultManagers.vue.md), and add your
own `Managers`.

Each Manager implements [middleware](#middleware), which connects it to the store's [control flow](#control-flow).
[init()](#init) and [cleanup()](#cleanup) connect it to the store's lifecycle, for setup and teardown.

```typescript
type Dispatch = (action: ActionTypes) => Promise<void>;

type Middleware = (controller: Controller) => (next: Dispatch) => Dispatch;

interface Manager {
  middleware: Middleware;
  cleanup(): void;
  init?: (state: State<any>) => void;
}
```

## Lifetimes

Each store gets its own Managers. A Manager's code lives at one of three lifetimes:

| Lifetime | Lasts                                                       | Holds                                                      |
| -------- | ----------------------------------------------------------- | ---------------------------------------------------------- |
| Config   | the page                                                    | options passed to the constructor, like a URL or callbacks |
| Store    | one store, from the [managers](#adding) function to unmount | instance fields about the store, like fetches in flight    |
| Active   | [init()](#init) to [cleanup()](#cleanup)                    | timers, connections and listeners                          |

So a constructor only stores its options.&#x20;

## Lifecycle

### middleware

`middleware` works like a [redux middleware](https://redux.js.org/advanced/middleware), except that `next()` returns a
`Promise`.

This promise resolves when the [DataClientPlugin](https://dataclient.io/vue/api/DataClientPlugin) store commits the update, so a Manager can
await `next()` to work with the new state.

Middleware can [read actions](#reading-and-consuming-actions) as they are dispatched, and
[dispatch its own](#dispatching-actions).

### init(state) {#init}

Called when Managers start. Start timers and connections here.

### cleanup()

Called when Managers stop. Stop timers and connections here.

## Adding managers to Reactive Data Client {#adding}

Pass a function to the [managers](https://dataclient.io/vue/api/DataClientPlugin#managers) option of [DataClientPlugin](https://dataclient.io/vue/api/DataClientPlugin).
It runs once for each app.

```ts title="main.ts"
import { createApp } from 'vue';
import { DataClientPlugin, getDefaultManagers } from '@data-client/vue';
import App from './App.vue';
import MyManager from './MyManager';

const managers = () => [new MyManager(), ...getDefaultManagers()];

const app = createApp(App);
app.use(DataClientPlugin, { managers });
app.mount('#app');
```

Define the function at module level: it holds only config.

Actions pass through managers in array order. List custom managers before the defaults: [NetworkManager](https://dataclient.io/vue/api/NetworkManager)
resolves most FETCH actions itself instead of passing them on.

## Control flow

Managers connect to the DataClientPlugin store through their lifecycle methods and
middleware. They read and dispatch [actions](./Actions.vue.md), and read the store's state.

The job of `middleware` is to dispatch actions, respond to [actions](./Actions.vue.md), or both.

### Dispatching Actions

[Controller](./Controller.vue.md) provides type-safe action dispatchers.

```ts title="CurrentTime"
import { Entity } from '@data-client/rest';

export default class CurrentTime extends Entity {
  id = 0;
  time = 0;
}
```

```ts title="TimeManager"
import type { Controller, Manager, Middleware } from '@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);
  }
}
```

### Reading and Consuming Actions

`actionTypes` includes all constants to distinguish between different [actions](./Actions.vue.md).

```ts
import type { Manager, Middleware } from '@data-client/vue';
import { actionTypes } from '@data-client/vue';

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
          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() {}
}
```

Inside each `case`, TypeScript [narrows](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#working-with-union-types)
the action's type, so you can access its members safely.

To consume an [action](./Actions.vue.md), don't call `next()`.

```ts title="isEntity"
import type { Schema, EntityInterface } from '@data-client/vue';

export default function isEntity(
  schema: Schema,
): schema is EntityInterface {
  return schema !== null && (schema as any).pk !== undefined;
}
```

```ts title="SubsManager"
import type {
  Manager,
  Middleware,
  EntityInterface,
} from '@data-client/vue';
import { actionTypes } from '@data-client/vue';
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 if we use it
          return Promise.resolve();
        }
      default:
        return next(action);
    }
  };

  cleanup() {}

  subscribe(channel: string, product_id: string) {}
  unsubscribe(channel: string, product_id: string) {}
}
```

`return Promise.resolve();` instead of `next(action)` stops managers listed after this one from seeing the
[action](./Actions.vue.md).

Types: [`FETCH`](./Actions.vue.md#fetch), [`SET`](./Actions.vue.md#set), [`SET_RESPONSE`](./Actions.vue.md#set_response),
[`RESET`](./Actions.vue.md#reset), [`SUBSCRIBE`](./Actions.vue.md#subscribe), [`UNSUBSCRIBE`](./Actions.vue.md#unsubscribe),
[`INVALIDATE`](./Actions.vue.md#invalidate), [`INVALIDATEALL`](./Actions.vue.md#invalidateall), [`EXPIREALL`](./Actions.vue.md#expireall)

## Use cases

Minimal examples for common Manager use cases:

- [Logging](./managers.vue.md#middleware-logging)
- [Error reporting (monitoring)](./managers.vue.md#error-reporting)
- [Metrics (fetch timing)](./managers.vue.md#metrics)
- [Notifications (toasts)](./managers.vue.md#notifications)
- [Refresh on focus or reconnect](./managers.vue.md#refresh-on-focus)
- [Cross-tab synchronization](./managers.vue.md#cross-tab-sync)
- [Offline persistence](./managers.vue.md#persistence)
- [Data streams (websockets/SSE)](./managers.vue.md#data-stream)
- [Authentication: logout on 401](./LogoutManager.vue.md)
- [Periodic updates (interval/ticker)](#dispatching-actions)
- [Custom transport subscriptions](#reading-and-consuming-actions)
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: 118kUpdated Claude CodeCodexVerifiedInstall
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: 118kUpdated Claude CodeCodexVerifiedInstall
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: 118kUpdated Claude CodeCodexVerifiedInstall
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: 118kUpdated Claude CodeCodexVerifiedInstall