# @bigcommerce/data-store

> A JavaScript library for managing application state

Latest version **1.0.3** (published 2025-09-05) · MIT license · 0 weekly downloads

## Install

```sh
npm install @bigcommerce/data-store
pnpm add @bigcommerce/data-store
yarn add @bigcommerce/data-store
bun add @bigcommerce/data-store
```

## Health

**Score 35/100 (D)** — status: maintenance-mode.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: stale; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.3 |
| Published | 2025-09-05 |
| First published | 2018-05-14 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 6 |
| Unpacked size | 60.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 6 |
| Author | BigCommerce |
| Maintainers | bcnpmuser, icatalina, chris.boulton, davidchin, pascal.zajac, chanceaclark, jairobc, jmwiese, jorgemoya, cilo, toma-r, leebigcommerce |

## Links

- npm: https://www.npmjs.com/package/@bigcommerce/data-store
- Repository: https://github.com/bigcommerce/data-store-js
- Issues: https://github.com/bigcommerce/data-store-js/issues
- npm.io page: https://npm.io/package/@bigcommerce/data-store

## Dependencies (6)

- [rxjs](https://npm.io/package/rxjs.md) ^6.6.7
- [tslib](https://npm.io/package/tslib.md) ^2.6.2
- [lodash](https://npm.io/package/lodash.md) ^4.17.4
- [shallowequal](https://npm.io/package/shallowequal.md) ^1.1.0
- [@types/lodash](https://npm.io/package/@types/lodash.md) ^4.14.92
- [@types/shallowequal](https://npm.io/package/@types/shallowequal.md) ^1.1.5

## Recent versions

- 1.0.3 (latest) — 2025-09-05
- 1.0.2 — 2024-01-23
- 1.0.1 — 2019-08-07
- 1.0.0 — 2019-08-05
- 0.2.7 — 2019-05-23
- 0.2.6 — 2019-01-08
- 0.2.5 — 2018-12-03
- 0.2.4 — 2018-11-15
- 0.2.3 — 2018-09-21
- 0.2.2 — 2018-08-23
- 0.2.1 — 2018-08-07
- 0.1.8 — 2018-05-27
- 0.1.7 — 2018-05-14
- 0.1.6 — 2018-05-14

## README

# @bigcommerce/data-store

[![Build Status](https://travis-ci.com/bigcommerce/data-store-js.svg?token=pywwZy8zX1F5AzeQ9WpL&branch=master)](https://travis-ci.com/bigcommerce/data-store-js)

A JavaScript library for managing application state.

It helps you to enforce unidirectional data flow in your application, by allowing you to:
* Subscribe to changes to the application state
* Update the state in a serial and immutable fashion


## Install

You can install this library using [npm](https://www.npmjs.com/get-npm).

```sh
npm install --save @bigcommerce/data-store
```


## Requirements

This library requires [Promise polyfill](https://github.com/stefanpenner/es6-promise) if you need to support older browsers, such as IE11.

You may need to create Observables when using this library (please refer to the usage section). We recommend you to use [rxjs](https://github.com/ReactiveX/rxjs) until the time comes when you can create them natively.


## Usage

### Create a store

```js
import { createDataStore } from '@bigcommerce/data-store';

const reducer = (state, action) => {
    switch (action.type) {
    case 'INCREMENT':
        return { ...state, count: state.count + 1 };

    case 'UPDATE_COUNT':
        return { ...state, count: action.payload };

    default:
        return state;
    }
};

const initialState = { count: 0 };
const store = createDataStore(reducer, initialState);
```

### To update the current state

```js
import { createAction } from '@bigcommerce/data-store';

store.dispatch(createAction('INCREMENT'));
store.dispatch(createAction('UPDATE_COUNT', 10)));
```

To update the state asynchronously, you need to create an observable that emits actions:

```js
import { Observable } from 'rxjs';

const action$ = Observable
    .ajax({ url: '/count' })
    .map(({ response }) => createAction('UPDATE_COUNT', response.count))

store.dispatch(action$);
```

To avoid race condition, actions get dispatched in a series unless you specify a different dispatch queue, i.e.:

```js
store.dispatch(action$);
store.dispatch(action$);

// The following call does not wait for the previous calls
store.dispatch(action$, { queueId: 'foobar' });
```

Wrap the observable in a closure if you want to access the store elsewhere but don't have direct access to it (i.e.: inside an action creator):

```js
// In an action creator
function updateAction() {
    return (store) => Observable
        .ajax({ url: '/count' })
        .map(({ response }) => {
            const { count } = store.getState();

            return createAction('UPDATE_COUNT', count + response.count);
        });
}
```

```js
// In a component
store.dispatch(updateAction());
```

To do something after an asynchronous dispatch:

```js
const { state } = await store.dispatch(action$);

console.log(state);
```

### To subscribe to changes

To changes and render the latest data:

```js
store.subscribe((state) => {
    console.log(state);
});
```

The subscriber will get triggered once when it is first subscribed. And it won't get triggered unless there's a data change.

To filter out irrelevant changes:

```js
// Only trigger the subscriber if `count` changes
store.subscribe(
    (state) => { console.log(state); },
    (state) => state.count
);
```

### To transform states and actions

To transform the return value of `getState` or parameter value of `subscribe`:

```js
const stateTransformer = (state) => ({ ...state, transformed: true });
const store = createDataStore(reducer, initialState, { stateTransformer });

console.log(store.getState()); // { count: 0, transformed: true }
```

To transform dispatched actions:

```js
const actionTransformer = (action) => ({ ...action, transformed: true });
const store = createDataStore(reducer, initialState, { actionTransformer });

console.log(store.dispatch(createAction('INCREMENT'))); // { type: 'INCREMENT', transformed: true }
```


## Contribution

To release:

```sh
npm run release
```

To see other available commands:

```sh
npm run
```

## License

MIT

---
_Source: https://npm.io/package/@bigcommerce/data-store · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._