@foundcareers/redux-entity

This library contains a bunch of helpers to manage entity collections in a redux store.

Installation

Install via npm: npm i -s @foundcareers/redux-entity

Install via yarn: yarn add @foundcareers/redux-entity

Example Collection State

Here's an example store that works with @foundcareers/redux-entity.

{
  todos: {
    entities: {
      'be9a-423mfas5345sd': {
        id: 'be9a-423mfas5345sd',
        value: 'Write todo'
      },
      'be9a-a245gf2033a20': {
        id: 'be9a-a245gf2033a20',
        value: 'Grill salmon'
      },      
    },
    meta: {
      currentPage: 2,
      nextPage: 3,
      prevPage: 1,
      totalPages: 4,
      totalCount: 12,
    },
    selectedEntityId: 'be9a-a245gf2033a20',
  },
  users: {
    entities: {
      'be9a-a245gf2033a21': {
        id: 'be9a-a245gf2033a21',
        name: 'Bob cutlass'
      },
      'ke9a-a245gf2033a22': {
        id: 'ke9a-a245gf2033a22',
        name: 'Peter Noopter'
      },
    },
    meta: {
      currentPage: 2,
      nextPage: 1,
      prevPage: 1,
      totalPages: 2,
      totalCount: 3,
    },
    selectedEntityId: 'ke9a-a245gf2033a22',
  },
}

Documentation

Table of Contents

• Actions
  • createActionsConfig
    • Parameters
    • Examples
  • createActions
    • Parameters
    • Examples
• Selectors
  • getEntities
    • Parameters
  • getEntitiesArray
    • Parameters
    • Examples
  • getSelectedEntityId
    • Parameters
  • getMeta
    • Parameters
  • getNextPage
    • Parameters
  • getPrevPage
    • Parameters
  • getStartCursor
    • Parameters
  • getEndCursor
    • Parameters
  • hasNextPage
    • Parameters
• Factories
  • createCollectionState
    • Parameters
    • Examples
• Reducers
  • addEntity
    • Parameters
  • addEntities
    • Parameters
  • removeEntity
    • Parameters
  • removeEntities
    • Parameters
  • removeSelectedEntity
    • Parameters
  • addMeta
    • Parameters
  • select
    • Parameters
  • reset
    • Parameters
  • createReducer
    • Parameters
    • Examples

Actions

createActionsConfig

Helps create an actions config (used in Actions::createActions).

Parameters

• config Array<string> Array of strings containing actions in camelCase. (optional, default [])

Examples

import { createActionsConfig } from '@foundcareers/redux-entity';

const config = createActionsConfig(['fetch', 'delete'])

// config
[
   'addEntity',
   'addEntities',
   'removeEntity',
   'removeEntities',
   'removeSelectedEntity',
   'addMeta',
   'select',
   'reset',
   // Custom config
   'fetch',
   'delete'
]

createActions

Creates an object containing action types and creators.

Parameters

• namespace string Action types namespace in camelCase. (optional, default 'undefined')
• config Array<string> Array of strings containing actions in camelCase. (optional, default [])

Examples

import { createActionsConfig } from '@foundcareers/redux-entity';

const { types, creators } = createActions('collection',
 ['addEntity', 'removeEntity']
);

// types
{
 REMOVE_ENTITY: '[Collection] Remove Entity',
 ADD_ENTITY: '[Collection] Add Entity'
}

// creators
{
 removeEntity: payload => ({ type: '[Collection] Remove Entity', payload }),
 addEntity: payload => ({ type: '[Collection] Add Entity', payload })
}

Selectors

getEntities

Get entities from a collection state.

Parameters

• state Object Collection state.

getEntitiesArray

Get a sorted array of entities from a collection state.

Parameters

• state Object Collection state.
• compareFunction function Comparator used to compare two objects.

Examples

import {getEntitiesArray} from '@foundcareers/redux-entity';

const todoState = {
 entities: {
   'be9a-423mfas5345sd': {
     id: 'be9a-a25d21033a20',
     value: 'Write todo'
   },
   'be9a-a245gf2033a20': {
     id: 'be9a-a245gf2033a20',
     value: 'Grill salmon'
   }
 },
 meta: {
   currentPage: 2,
   nextPage: 3,
   prevPage: 1,
   totalPages: 4,
   totalCount: 12,
 },
 selectedEntityId: 'be9a-a245gf2033a20'
};

const compareFunction = (a, b) => a.value.localeCompare(b.value);

const entities = getEntitiesArray(todoState, compareFunction);

// Resulting in the following entities array
[
 {
   id: 'be9a-a245gf2033a20',
   value: 'Grill salmon'
 },
 {
   id: 'be9a-423mfas5345sd',
   value: 'Write todo'
 }
]

getSelectedEntityId

Get the selected entity id from a collection state.

Parameters

• state Object Collection state.

getMeta

Get meta from a collection state.

Parameters

• state Object Collection state.

getNextPage

Get next page from a collection meta.

Parameters

• state Object Collection state.

getPrevPage

Get previous page from a collection meta.

Parameters

• state Object Collection state.

getStartCursor

Get start cursor from a collection meta.

Parameters

• state Object Collection state.

getEndCursor

Get end cursor from a collection state.

Parameters

• state Object Collection state.

hasNextPage

Get hasNext within cursor meta from a collection state.

Parameters

• state Object Collection state.

Factories

createCollectionState

Creates an initial collection state object with standard or cursor meta.

Parameters

• state Object Object that's spread into the collection state. (optional, default {})
• options Object Configuration object. (optional, default {})
  • options.useCursor boolean Set to true to use cursor meta. false for default meta.

Examples

import { createCollectionState } from '@foundcareers/redux-entity';

// State with Cursor Pagination
const stateWithMetaPagination = createCollectionState({}, {
 useCursor: true
});

// stateWithMetaPagination
{
 entities: {},
 meta: {
   endCursor: null,
   hasNextPage: null,
   startCursor: null
 },
 selectedEntityId: null,
}

Reducers

addEntity

Add an entity to the collection state.

Parameters

• state Object Collection state.
• payload Object The entity object you'd like to add. Must contain an id attribute.

addEntities

Adds entities to the collection state.

Parameters

• state Object Collection state.
• payload Object Object containing entities you'd like to add to the collection.

removeEntity

Remove an entity from the collection state.

Parameters

• state Object Collection state.
• id string Id of entity you'd like to remove from the collection state.

removeEntities

Removes entities from the collection state.

Parameters

• state Object Collection state.
• ids Array<string> An array of entity ids.

removeSelectedEntity

Remove the selected entity.

Parameters

• state Object Collection state.

addMeta

Add a meta object to the collection state.

Parameters

• state Object Collection state.
• payload Object The meta object.

select

Select an entity in the collection state.

Parameters

• state Object Collection state.
• selectedEntityId string Entity Id that's being selected.

reset

Reset the collection state.

Parameters

• state Object Current Collection state.
• initialState Object Initial Collection state (refer to createCollectionState).

createReducer

Creates an returns a custom reducer function.

Parameters

• initialState Object Collection state.
• actionTypes Object Object containing required action types.
• handlers Object Object containing custom reducer action creators. (optional, default {})

Examples

// job.actions.js
export default {
 ADD_ENTITY: '[Job] Add Entity',
 REMOVE_ENTITY: '[Job] Remove Entity',
 CUSTOM: '[Job] Custom'
 ...
}

// job.reducer.js
import { createReducer, createCollectionState } from '@foundcareers/redux-entity';
import jobActionTypes from './job.action';

// Creating a reducer for a collection of entities (default case)
export const reducer = createReducer(
 createCollectionState(),
 jobActionTypes
);

// Creating a reducer for a collection of entities (*customized case)
export const reducer = createReducer(
 createCollectionState(),
 jobActionTypes,
 {
   [jobActionTypes.CUSTOM]: (state, payload) => ({
     ...state, custom: payload
   })
 }
);