nebenan-redux-tools

A set of redux helpers.

• Experiments Middleware
• Token Middleware
• Promise Middleware
• Network Middleware
  • Trustworthy Endpoints
  • API Token
  • X-Translations-Lang Header
  • Should Request
  • Abort Callback
  • Request Types
  • Pagination
  • Mock Responses
  • Standalone Request
  • Customize

Experiments Middleware

Setup

NOT COMPLETE

import { reducer as experiments } from 'nebenan-redux-tools/lib/experiments/state';

const reducers = { 
  // It is assumed that the experiment reducer's state
  // is available under `state.experiments`
  experiments 
};

// ...

const createFromState = (initialState) => (
  createStore(
    combineReducers(reducers),
    initialState,
    composeEnhancers(applyMiddleware(...middleware)),
  )
);

export default createFromState

Token Middleware

Setup

NOT COMPLETE

import { reducer as token } from 'nebenan-redux-tools/lib/token';

const reducers = {
  // It is assumed that the experiment reducer's state
  // is available under `state.token`
  token
};

// ...

const createFromState = (initialState) => (
  createStore(
    combineReducers(reducers),
    initialState,
    composeEnhancers(applyMiddleware(...middleware)),
  )
);

export default createFromState

Promise Middleware

The promise middleware gets triggered by dispatching actions with promise key in payload. The middleware will dispatch resolved or rejected actions when the promise is fulfilled.

dispatch({
  type: types.GET_USERS,
  promise: {
    getPromise: () => getUsersFromStorageAsync(),
    
    // Ensures the returned promise by the dispatched action to resolve even if the provided promise rejected
    // graceful: true
  }
})

// reducer
import { resolved, rejected } from 'nebenan-redux-tools/lib/promise';

export default (state = getDefaultState(), action) => {
  switch(action.type) {
    case resolved(types.GET_USERS): {
      const usersFromStorage = action.payload;

      return { ...state, users: usersFromStorage };
    }

    case rejected(types.GET_USERS): {
      const usersFromStorage = [];

      return { ...state, users: usersFromStorage };
    }

    default: {
      return state;
    }
  }
} 

Should Execute

Prevents unnecessary promise executions by checking state beforehand. Dispatches resolved action on prevented execution.

dispatch({
  type: types.GET_USERS,
  promise: {
    getPromise: () => getUsersFromStorageAsync(),
    shouldExecute: (state) => !state.isFetched,
  }
})

Network Middleware

The network middleware gets triggered by dispatching actions with request in payload. The middleware will fire the request and dispatches resolved or rejected actions when the request is finished.

Example:

dispatch({
  type: types.GET_USERS,
  request: {
    url: "/users"
  }
})

import { resolved, rejected } from 'nebenan-redux-tools/lib/network/types';

export default (state = getDefaultState(), action) => {
  switch(action.type) {
    case resolved(types.GET_USERS): {
      const usersFromResponse = action.payload;
      
      return { ...state, users: usersFromResponse };
    }
    
    case rejected(types.GET_USERS): {
      const usersFromResponse = [];
      
      return { ...state, users: usersFromResponse };
    }
    
    default: {
      return state;
    }
  }
} 

Trustworthy Endpoints

Requests to trustworthy endpoints will enable the X-Translations-Lang Header and API Token features.

Set trusted domain via global config:

import { configureNetwork } from 'nebenan-redux-tools/lib/network';

configureNetwork({
  trustedDomain: "nebenan.de",
  ...otherSettings
})

API Token

Requests to trustworthy endpoints will have the X-AUTH-TOKEN header set, containing the api token configured in request options or through token middleware.

Default: state.token (see token middleware)

Overwrite:

dispatch({
  type: "some-type", 
  request: {
    url: "/some/endpoint",
    token: "special-api-token"
  }
})

X-Translations-Lang Header

Requests to trustworthy endpoints will have the X-Translations-Lang header set, containing the locale configured in request options or through global config.

Default via global config:

import { configureNetwork } from 'nebenan-redux-tools/lib/network';

configureNetwork({
  locale: 'de-DE',
  ...otherSettings
})

Overwrite:

dispatch({
  type: "some-type",
  request: {
    url: "/some/endpoint",
    locale: "en-US"  
  }
})

Should Request

Prevents unnecessary requests by checking state beforehand.

dispatch({
  type: "some-type",
  request: {
    url: "/some/endpoint",
    shouldRequest(state) {
     return !state.isFetched;
    }
  }
})

Aborting

Allows to cancel running requests. Just pass in a AbortSignal.

const controller = new AbortController();

dispatch({
  type: "some-type",
  request: {
    url: "/some/endpoint",
    signal: controller.signal,
  }
})


// later in app
controller.abort();

Request Types

request.type determines used HTTP method

query

Sends out GET request. Collects parameters from request.query and applies pagination query options if there are any.

dispatch({
  type: "some-type",
  request: {
     url: "/users",
     type: 'query',
     query: { q: 'Peter' } 
  }
})

delete / post / put

dispatch({
  type: "some-type",
  request: {
    url: "/some/endpoint/123",
    type: 'put',
    payload: { user: { email, password }}
  }  
})

Pagination

There is some boilerplate needed to fully support paginated lists loaded over the network. These helpers help with managing state and sending pagination params over the network.

The endpoint you are accessing needs to fulfill following requirements:

• Parameters
  • per_page
  • lower / higher
• Response
  • total_count (state.total needs to be updated manually if field does not exist)

assignPaginationDefaults / paginationGenerator helpers

import { paginationGenerator, assignPaginationDefaults } from 'nebenan-redux-tools/lib/network/pagination';

const getDefaultState = () => assignPaginationDefaults({ entities: {} });
const getPaginationUpdates = paginationGenerator(types.BOOKMARKS_FETCH);

export const reducer = (state = getDefaultState(), action) => {
  let newState = state;
  
  const update = getPaginationUpdates(newState, action);
  if (update) newState = updeep(update, newState);
  
  switch (action.type) {
    case resolved(types.BOOKMARKS_FETCH): {
      const { result, entities } = parse(action.payload);

      const collection = newState.collection.concat(result.bookmarks);

      return updeep({ collection, entities }, newState);
    }
    
    default: {
      return newState;
    }
  }
}

The state now holds the following information

{
  // (managed by paginationGenerator)
  currentPage: 0, 
  // datetime of last fetch (managed by paginationGenerator)
  lastFetched: 0,
  // request in progress (managed by paginationGenerator)
  isFetching: false,
  // request failed (managed by paginationGenerator) 
  isFailed: false,  
  // total amount of items over all pages (managed by paginationGenerator)
  total: null,
  // item ids for current page  
  collection: [],
}

Actions

Pagination query params will be added for query requests with either request.pagination.first or request.pagination.last set.

Only works for endpoints supporting lower/higher params.

dispatch({
  type: types.GET_USERS,
  request: {
    url: "/users",
    type: 'query',
    pagination: {
      per_page: 10, // optional
      first: firstUserId, // optional
      last: lastUserId // optional
    }
  }
})

Mock Response

Responses can be mocked by using the promise middleware. You can keep all of your request options in the action and don't need to modify reducers. Quite useful during development if you are waiting for backend to support new endpoints.

dispatch({
  type: types.GET_USERS,
  promise: Promise.resolve([
    {
      id: 1,
      name: "Peter"
    },
    {
      id: 2,
      name: "Christina"
    }
  ]),
  request: {
    url: "/users",
    type: 'query'
  }
})

// reducer
import { resolved } from 'nebenan-redux-tools/lib/network/types';

export default (state = getDefaultState(), action) => {
  switch(action.type) {
    case resolved(types.GET_USERS): {
      const usersFromResponse = action.payload;
      
      return { ...state, users: usersFromResponse };
    }
    
    default: {
      return state;
    }
  }
} 

Standalone Request

Requests can be created programmatically too.

import { createRequest } from 'nebenan-redux-tools/lib/network';

const sendFile = (file, token) => (
  createRequest({
    token,
    payload: { file },
    url: '/file-upload',
    type: 'post',
    multipart: true,
  }) 
)

const handleSuccess = (payload) => {
  // same as action.payload
  console.log(payload);
}

sendFile(newFile, token).then(handleSuccess);

Customize

The network layer uses axios under the hood. To access axios specific features or extend functionality you can hook into request / response generation on a global or local scale.

Hooks:

• requestHook(requestConfig, requestOptions)
  • requestConfig the axios request config to be mutated
  • requestOptions the request object provided inside the action
• responseHook(body, requestConfig, requestOptions)
  • body response data to be mutated
  • requestConfig the axios request config
  • requestOptions the request object provided inside the action

Setup global hooks

import { configureNetwork } from 'nebenan-redux-tools/lib/network';

configureNetwork({
  requestHook: (requestConfig, requestOptions) => {
    // ...
  },
  responseHook: (body, requestConfig, requestOptions) => {
    // ...
  },
  ...networkSettings
})

Action level request hook

import { createRequest } from 'nebenan-redux-tools/lib/network';

const sendFile = (file, token, onProgress) => (
  createRequest({
    token,
    payload: { file },
    url: '/file-upload',
    type: 'post',
    multipart: true,
    // same as requestHook
    customize: (requestConfig) => {
      requestConfig.onUploadProgress = onProgress;
    }
  })
)