Sign Up for Free

RunKit +

Try any Node.js package right in your browser

This is a playground to test code. It runs a full Node.js environment and already has all of npm’s 400,000 packages pre-installed, including @nerdwallet/epic-state-subscriptions with all npm packages installed. Try it out:

require("redux-observable/package.json"); // redux-observable is a peer dependency. var epicStateSubscriptions = require("@nerdwallet/epic-state-subscriptions")

This service is provided by RunKit and is not affiliated with npm, Inc or the package authors.

@nerdwallet/epic-state-subscriptions v0.0.1

An epic state subscription library using Redux-Observable

Epic State Subscriptions

Epicly perform actions and side effects when *.the.paths.you.care.about change in the Redux store.

If you have not used Redux-Observable Epics before, here's a link to the documentation.

Installation

There is an additional peer dependency of redux-observable@^1.1.x

npm install epic-state-subscriptions

Basic Usage

Import the createStateSubscription operator and add it to your Epic like any other operator. Pass it the paths that you want to subscribe to in the Redux store and it will transform the action stream into a stream of path changes.

import { createStateSubscription } from 'epic-state-subscriptions';

const exampleEpic = (action$, state$) =>
  action$.pipe(
    createStateSubscription(state$, {
      paths: ['x.y.z', 'a.b.*', '*.c.d'],
    }),
    map(paths => {
      paths.forEach({ pathPattern, path } => {
        console.log(`path ${path} has been reported to change because of matched pattern ${pathPattern}`);
      });
      return sideEffectAction(changeSet);
    })
  );

The path changes are emitted as objects with the structure below:

KeyTypeDescription
pathStringThe path that changed in the Redux store
pathPatternStringThe state subscription path pattern that triggered the path to change
prevStateAnyThe previous state of the path that changed in the Redux store
nextStateAnyThe new state of the path that changed in the Redux store

In the above example, if path a.b.c had changed from false to true the path object emitted would be { prevState: false, nextState: true, path: 'a.b.c', pathPattern: 'a.b.*' }.

Note: Since operators do not normally get access to the state$ stream, it is passed explicitly as the first argument, followed by the configuration options.

Configuration Options

OptionTypeRequiredDefaultDescription
keyStringfalseRandom uuidOptional key name to identify the subscription
pathsArrayfalse[ ]The . delimited initial paths to watch in the Redux store with support for wildcards such as store.*.y

Advanced Subscriptions

As a standard RxJS operator, your Epic can chain createStateSubscription to support additional use cases like buffering path changes:

import { createStateSubscription } from 'epic-state-subscriptions';

const exampleEpic (action$, state$) =>
  action$.pipe(
    // Buffer the actions changes since they are frequent
    bufferTime(500),
    // Only emit updates to the state subscription if actions
    // have occurred in the buffer interval
    filter(actions => actions.length > 0),
    createStateSubscription(state$, {
      paths: ['a.b.c'],
    }),
    map(paths => {
      paths.forEach({ prevState, nextState, pathPattern, path } => {
        console.log(`path ${path} has been reported to change because of matched pattern ${pathPattern}`);
      });
      return sideEffectAction(changeSet);
    })
  );

Dynamic State Subscription Paths

If a config will need dynamic state subscription paths as the application runs, there is a provided state subscription reducer and action for overriding the default paths initialized in the config which you can use.

Include the state subscriptions reducer in your combineReducers redux configuration:

import { stateSubscriptionReducer } from 'epic-state-subscriptions';
import { combineReducers } from 'redux';

const rootReducer = combineReducers([...reducers, stateSubscriptionReducer]);

and then you can dispatch the overrideStateSubscriptionPaths action:

import { overrideStateSubscriptionPaths } from 'epic-state-subscriptions';

dispatch(overrideStateSubscriptionPaths({ key: 'exampleKey', paths: ['state.x.y'] });

The state subscription key passed in the action should match the key in the createStateSubscription config. It automatically will now favour configurations in the reducer at that subscription key over the static initial paths specified in the config.

FAQs

  1. My state subscription just needs to perform side effects and not fire any actions, how do I terminate my Epic?

You can use the tap operator to perform side effects and use the ignoreElements operator to instruct the stream to not emit elements and fire a termination event:

import { ignoreElements, tap } from 'rxjs/operators';
import { createStateSubscription } from 'epic-state-subscriptions';
import { sideEffectAction } from './actions';

const exampleEpic = (action$, state$) =>
  action$.pipe(
    createStateSubscription(state$, {
      paths: ['x.y.z', 'a.b.*', '*.c.d'],
    }),
    tap(paths => {
      paths.forEach({ pathPattern, path } => {
        console.log(`path ${path} has been reported to change because of matched pattern ${pathPattern}`);
      });
    }),
    ignoreElements()
  );
  1. My state subscription is created dynamically and it is updating incorrectly, what gives?

An operator that is applied to the observable more than once needs to share the same key as the previous iteration to preserve its cache. Specify a key in your subscription and it will behave as expected.

import { ignoreElements, tap } from 'rxjs/operators';
import { createStateSubscription } from 'epic-state-subscriptions';
import { sideEffectAction } from './actions';

const exampleEpic = (action$, state$) =>
  action$.pipe(
    mergeMap(action => {
      return of(action).pipe(
        createStateSubscription(state$, {
          key: 'dynamicSubscription',
          paths: ['x.y.z', 'a.b.*', '*.c.d'],
        }),
        tap(paths => {
          paths.forEach({ pathPattern, path } => {
          console.log(`path ${path} has been reported to change because of matched pattern ${pathPattern}`);
        }),
        ignoreElements()
      )
    }),
  );
RunKit is a free, in-browser JavaScript dev environment for prototyping Node.js code, with every npm package installed. Sign up to share your code.
Sign Up for Free