Normalized Reducer

A zero-boilerplate higher-order reducer for managing normalized relational data

🐒 easy to get started and use without writing any action/reducer logic

✨ handles basic CRUD, plus complex updates like entity associations and cascading changes from deletes

📦 dependency-free and framework-agnostic; use with or without Redux

🔌 integrates with Normalizr and Redux-Toolkit

Table of Contents:

The Problem

Managing normalized relational data presents various complexities such as:

deleting an entity must result in its id being removed from all of its attached entities
attaching/detaching two related entities requires the id of each entity being added/removed in the other
implementation of relational behavior differs depending on the cardinality
most behavior varies based on current state, not just action inputs
scaling a robust solution without abstraction results in lots of repeated logic

The Solution

Normalized Reducer helps you manage normalized relational state without requiring any reducer/action boilerplate. Simply provide a declarative relational schema, and it gives you the reducers, actions, and selectors to read and write state according to that schema.

Install

yarn add normalized-reducer

Quick Start

Define a schema that describes your data's relationships.

const mySchema = {
  list: {
    'itemIds': { type: 'item', cardinality: 'many', reciprocal: 'listId' }
  },
  item: {
    'listId': { type: 'list', cardinality: 'one', reciprocal: 'itemIds' },
    'tagIds': { type: 'tag', cardinality: 'many', reciprocal: 'itemIds'}
  },
  tag: {
    'itemIds': { type: 'item', cardinality: 'many', reciprocal: 'tagIds' }
  }
}

More info at: Top-level API > Parameter: schema

Pass in the schema, and get back a reducer, action-creators, action-types, selectors, and empty state.

import { makeNormalizedSlice } from 'normalized-reducer'

const {
  reducer,
  actionCreators,
  actionTypes,
  selectors,
  emptyState,
} = makeNormalizedSlice(mySchema)

More info at: Top-level API > Return Value

Use the reducer and actions to update the state. The following example assumes the use of dispatch from either React or React-Redux.

With React:

const [state, dispatch] = useReducer(reducer, emptyState);

With React-Redux:

const dispatch = useDispatch();

Usage:

// add entities
dispatch(actionCreators.create('item', 'i1')) // add an 'item' entity with an id of 'i1' 
dispatch(actionCreators.create('list', 'l1', { title: 'first list' }), 3) // add a 'list' with id 'l1', with data, at index 3


// delete entities
dispatch(actionCreators.delete('list', 'l1')) // delete a 'list' entity whose id is 'l1' 

// update entities
dispatch(actionCreators.update('item', 'i1', { value: 'do a barrel roll!' })) // update 'item' whose id is 'l1', patch (partial update)
dispatch(actionCreators.update('item', 'i1', { value: 'the sky is falling!' }, { method: 'put' })) // update, put (replacement update)

// change an entity's ordinal value 
dispatch(actionCreators.move('item', 0, 1)) // move the 'item' entity at index 0 to index 1

// attach entities
dispatch(actionCreators.attach('list', 'l1', 'item', 'i1')) // attach list l1 to item i1

// detach entities
dispatch(actionCreators.detach('list', 'l1', 'item', 'i1')) // detach list l1 from item i1

// change an entity's ordinal value with respect to another entity
dispatch(actionCreators.moveAttached('list', 'l1', 'itemIds', 1 , 3)) // in item l1's .itemIds, move the itemId at index 1 to index 3  

// batch: all changes will occur in a single action
dispatch(actionCreators.batch(
  actionCreators.create('list', 'l10'),
  actionCreators.create('item', 'i20'),
  actionCreators.attach('item', 'i20', 'listId', 'l10'),
))

// sort entities
dispatch(actionCreators.sort('item', (a, b) => (a.title > b.title ? 1 : -1))) // sort items by title

// sort entities with respect to an attached entity
dispatch(actionCreators.sortAttached('list', 'l1', 'itemIds', (a, b) => (a.value > b.value ? 1 : -1))) // in item l1's .itemIds, sort by value

More info at: Action-creators API

Use the selectors to read state.

const itemIds = selectors.getIds(state, { type: 'item' }) // ['i1', 'i2']
const items = selectors.getEntities(state, { type: 'item' }) // { 'i1': { ... }, 'i2': { ... } }
const item = selectors.getEntity(state, { type: 'item', id: 'i2' }) // { value: 'the sky is falling!', listId: 'l1' }

More info at: Selectors API

The empty state shape looks like:

{
  "entities": {
    "list": {},
    "item": {},
    "tag": {}
  },
  "ids": {
    "list": [],
    "item": [],
    "tag": []
  }
}

And a populated state could look like:

{
  "entities": {
    "list": { 
      "l1": { "itemIds": ["i1", "i2"] } 
    },
    "item": {
      "i1": { "listId": "l1" },
      "i2": { "listId": "l1", "tagIds": ["t1"] }    
    },
    "tag": {
      "t1": { "itemIds": ["i2"] }
    }
  },
  "ids": {
    "list": ["l1"],
    "item": ["i1", "i2"],
    "tag": ["t1"]
  }
}

Demo

Action demos and usage examples

Demos:

Example usage:

Demo source repo

Comparison to Alternatives

Normalized Reducer is comparable to Redux ORM and Redux Toolkit's entity adapter.

Comparison to Redux ORM:

Normalized Reducer
- does not depend on Redux
- supports ordering of children (attached entities),
- does not require any non-declarative logic
- is lighter and dependency-free
Redux ORM
- has more advanced selectors features
- is more mature

Comparison to Redux Tookit's entity adapter

Normalized Reducer
- performs relational state management
- is dependency-free
Redux Tookit's entity adapter
- supports automatic entity ordering
- is more mature and backed by Redux authorities

Top-level API

The top-level default export is a higher-order function that accepts a schema and an optional namespaced argument and returns a reducer, action-creators, action-types, selectors, and empty state.

makeNormalizedSlice<S>(schema: ModelSchema, namespaced?: Namespaced): {
    reducer: Reducer<S>,
    actionCreators: ActionCreators<S>,
    actionTypes: ActionTypes,
    selectors: Selectors<S>,
    emptyState: S,
}

Example:

import { makeNormalizedSlice } from 'normalized-reducer';

const {
  reducer,
  actionCreators,
  actionTypes,
  selectors,
  emptyState,
} = makeNormalizedSlice(mySchema, namespaced);

Parameter: `schema`

The schema is an object literal that defines each entity and its relationships.

interface Schema {
  [entityType: string]: {
    [relationKey: string]: {
      type: string; 
      reciprocal: string;
      cardinality: 'one'|'many';
    }
  }
}

Example:

const schema = {
  list: {
    // Each list has many items, specified by the .itemIds attribute
    // On each item, the attribute which points back to its list is .listId
    itemIds: { 
      type: 'item', // points to schema.item
      reciprocal: 'listId', // points to schema.item.listId
      cardinality: 'many'
    }
  },
  item: {
    // Each item has one list, specified by the attribute .listId
    // On each list, the attribute which points back to the attached items is .itemIds
    listId: { 
      type: 'list', // points to schema.list
      reciprocal: 'itemIds', // points to schema.list.itemIds
      cardinality: 'one'
    },
  },
};

Note that type must be an entity type (a top-level key) within the schema, and reciprocal must be a relation key within that entity's definition.

Parameter: `namespaced`

This is an optional argument that lets you namespace the action-types, which is useful if you are going to compose the Normalized Reducer slice with other reducer slices in your application.

Example:

const namespaced = actionType => `my-custom-namespace/${actionType}`;

If the namespaced argument is not passed in, it defaults to normalized/.

Generic Parameter: `<S extends State>`

The shape of the state, which must overlap with the following interface:

export type State = {
  entities: {
    [type: string]: {
      [id in string|number]: { [k: string]: any }
    }
  },
  ids: {
    [type: string]: (string|number)[]
  },
};

Example:

interface List {
  itemIds: string[]
}

interface Item {
  listId: string
}

interface State {
  entities: {
    list: Record<string, List>,
    item: Record<string, Item>
  },
  ids: {
    list: string[],
    item: string[]
  }
}

const normalizedSlice = makeNormalizedSlice<State>(schema)

Return Value

Calling the top-level function will return an object literal containing the things to help you manage state:

reducer
actionCreators
actionTypes
selectors
emptyState

`reducer`

A function that accepts a state + action, and then returns the next state.

reducer(state: S, action: { type: string }): S

In a React setup, pass the reducer into useReducer:

function MyComponent() {
  const [normalizedState, dispatch] = useReducer(reducer, emptyState)
}

In a Redux setup, compose the reducer with other reducers, or use it as the root reducer:

const { reducer } = makeNormalizedSlice(schema)

// compose it with combineReducers
const reduxReducer = combineReducers({
  normalizedData: reducer,
  //...
})

// or used it as the root reducer
const store = createStore(reducer)

`actionCreators`

An object literal containing action-creators. See the Action-creators API section.

`actionTypes`

An object literal containing the action-types.

const {
    CREATE,
    DELETE,
    UPDATE,
    MOVE,
    ATTACH,
    DETACH,
    MOVE_ATTACHED,
    SORT,
    SORT_ATTACHED,
    BATCH,
    SET_STATE,
} = actionTypes

Their values are namespaced according to the namespaced parameter of the top-level function. Example: normalized/CREATE

`selectors`

An object literal containing the selectors. See the Selectors API section.

`emptyState`

An object containing empty collections of each entity.

Example:

{
  "entities": {
    "list": {},
    "item": {},
    "tag": {}
  },
  "ids": {
    "list": [],
    "item": [],
    "tag": []
  }
}

Action-creators API

An action-creator is a function that takes parameters and returns an object literal describing how the reducer should enact change upon state.

`create`

Creates a new entity

( entityType: string, 
  id: string|number, 
  data?: object, 
  index?: number
): CreateAction

Parameters:

entityType: the entity type
id: an id that doesn't belong to an existing entity
data: optional, an object of arbitrary, non-relational data
index: optional, a number greater than 0

Note:

the id should be a string or number provided by your code, such as a generated uuid
if the id already belongs to an existing entity, then the action will be ignored.
if no data is provided, then the entity will be initialized as an empty object.
if relational attributes are in the data, then they will be ignored; to add relational data, use the attach action-creator after creating the entity.
if an index is provided, then the entity will be inserted at that position in the collection, and if no index is provided the entity will be appended at the end of the collection.

Example:

// create a list with a random uuid as the id, and a title, inserted at index 3 
const creationAction = actionCreators.create('list', uuid(), { title: 'shopping list' }, 3)

Demos:

`delete`

Deletes an existing entity

( entityType: string, 
  id: string|number, 
  cascade?: SelectorTreeSchema
): DeleteAction

Parameters:

entityType: the entity type
id: the id of an existing entity
cascade: optional, an object literal describing a cascading deletion

Note:

any entities that are attached to the deletable entity will be automatically detached from it.
pass in cascade to delete entities that are attached to the deletable entity

Basic Example:

// deletes a list whose id is 'l1', and automatically detaches any entities currently attached to it
const deletionAction = actionCreators.delete('list', 'l1');

Cascade Example:

/*
deletes list whose id is 'l1', 
deletes any items attached to 'l1'
deletes any tags attached to those items
detaches any entities attached to the deleted entities
*/
const deletion = actionCreators.delete('list', 'l1', { itemIds: { tagIds: {} } });

Demos:

`update`

Updates an existing entity

( entityType: string, 
  id: string|number, 
  data: object,
  options?: { method?: 'patch'|'put' }
): UpdateAction

Parameters:

entityType: the entity type
id: the id of an existing entity
data: an object of any arbitrary, non-relational data
options.method: optional, whether to partially update or completely replace the entity's non-relational data

Note:

if an entity with the id does not exist, then the action will be ignored
if relational attributes are in the data, then they will be ignored; to update relational data, use the attach and detach action-creators.
if no method option is provided, then it will default to a patch (partial update)

Example:

// updates a list whose id is 'l1', partial-update
const updateAction = actionCreators.update('list', 'l1', { title: 'do now!' })

// updates a list whose id is 'l1', full replacement
const updateAction = actionCreators.update('list', 'l1', { title: 'do later' }, { method: 'put' })

Demos:

Update

`attach`

Attaches two existing related entities

( entityType: string, 
  id: string|number, 
  relation: string,
  relatedId: string|number,
  options?: { index?: number; reciprocalIndex?: number }
): AttachAction

Parameters:

entityType: the entity type
id: the id of an existing entity
relation: a relation key or relation type
attachableId: the id of an existing entity to be attached
options.index: optional, the insertion index within the entity's attached-id's collection
options.reciprocalIndex: optional, same as options.index, but the opposite direction

Note:

if either entity does not exist, then the action will be ignored
if the relation does not exist as defined by the schema, then the action will be ignored,
a has-one attachment can be displaced by a new attachment, and such a case, those displaced entities will automatically be detached
if indexing is not applicable for a given relationship, i.e. a has-one, then the indexing option will be ignored

Example:

/*
attaches item 'i1' to tag 't1'
in item i1's tagIds array, t1 will be inserted at index 2
in tag t1's itemIds array, i1 will be inserted at index 3
*/
const attachmentAction = actionCreators.attach('item', 'i1', 'tagIds', 't1', 2, 3);

Displacement example:

// attach list 'l1' to item 'i1'
const firstAttachment = actionCreators.attach('list', 'l1', 'itemId', 'i1');

// attach list 'l20' to item 'i1'
// this will automatically detach item 'i1' from list 'l1'
const secondAttachment = actionCreators.attach('list', 'l20', 'itemId', 'i1');

Demos:

`detach`

Detaches two attached entities

( entityType: string,
  id: string|number,
  relation: string,
  detachableId: string|number
): DetachAction

Parameters:

entityType: the entity type
id: the id of an existing entity
relation: a relation key or relation type
detachableId: the id on an existing entity to be attached

Example:

// detach item 'i1' from tag 't1'
const detachmentAction = actionCreators.detach('item', 'i1', 'tagIds', 't1')

Demos:

`move`

Changes an entity's ordinal position

( entityType: string,
  src: number,
  dest: number
): MoveAction

Parameters:

entityType: the entity type
src: the source/starting index of the entity to reposition
dest: the destination/ending index; where to move the entity to

Note:

if either src or dest is less than 0, then the action will be ignored
if src greater than the highest index, then the last entity will be moved
if dest greater than the highest index, then, the entity will be move to last position

Example:

// move the item at index 2 to index 5
const moveAction = actionCreators.move('item', 2, 5)

Demos:

Move

`moveAttached`

Changes an entity's ordinal position with respect to an attached entity

( entityType: string,
  id: string|number,
  relation: string,
  src: number,
  dest: number
): MoveAttachedAction

Parameters:

entityType: the entity type
id: the id of an existing entity
relation: the relation key of the collection containing the id to move
src: the source/starting index of the entity to reposition
dest: the destination/ending index; where to move the entity to

Note:

if an entity with the id does not exist, then the action will be ignored
if the relation is a has-one relation, then the action will be ignored
if either src or dest is less than 0, then the action will be ignored
if src greater than the highest index, then the last entity will be moved
if dest greater than the highest index, then the entity will be move to last position

Example:

// in list l1's itemIds array, move itemId at index 2 to index 5
const moveAction = actionCreators.moveAttached('list', 'l1', 'itemIds', 2, 5)

Demos:

Move attached

`sort`

Sorts a top-level entity ids collection

<T>(
  entityType: string,
  compare: (a: T, b: T) => number
): SortAction

Parameters:

entityType: the entity type
compare: the sorting comparison function

Example:

// sort list ids (state.ids.list) by title 
const sortAction = actionCreators.sort('list', (a, b) => (a.title > b.title ? 1 : -1))

Demos:

Sort

`sortAttached`

Sorts an entity's attached-ids collection

<T>(
  entityType: string,
  id: string|number,
  relation: string,
  compare: Compare<T>
): SortAction

Parameters:

entityType: the entity type
id: the id of an existing entity
relation: the relation key or relation type of the collection to sort
compare: the sorting comparison function

Note:

if an entity with the id does not exist, then the action will be ignored
if the relation is a has-one, then the action will be ignored

Example:

// in list l1, sort the itemsIds array by by value 
const sortAction = actionCreators.sort('list', 'l1', 'itemIds', (a, b) => (a.value > b.value ? 1 : -1))

Demos:

Sort attached

`batch`

Runs a batch of actions in a single reduction

(...actions: Action[]): BatchAction

Parameters:

...actions: Normalized Reducer actions excluding batch and setState

Note:

each action acts upon the state produced by the previous action

Example:

// create list 'l1', then create item 'i1', then attach them to each other
const batchAction = actionCreators.batch(
  actionCreators.create('list', 'l1'),
  actionCreators.create('item', 'i1'),
  actionCreators.attach('list', 'l1', 'itemIds', 'i1'), // 'l1' and 'i1' would exist during this action due to the previous actions
  // nested batch-actions are also accepted
  actionCreators.batch(
    actionCreators.create('item', 'i2'),
    actionCreators.create('item', 'i3'),
  )
)

Demos:

Batch

`setState`

Sets the normalized state

(state: S): SetStateAction

Parameters:

state: the state to set

Note:

intended for initializing state
does not guard against invalid data

Example:

const state = {
  entities: {
    list: { 
      l1: { title: 'first list', itemIds: ['i1'] },
      l2: {} 
    },
    item: {
      i1: { value: 'do a barrel roll', listId: 'l1', tagIds: ['t1'] }
    },
    tag: {
      t1: { itemIds: ['i1'], value: 'urgent' }
    }
  },
  ids: {
    list: ['l1', 'l2'],
    item: ['i1'],
    tag: ['t1']
  }
}

const setStateAction = actionCreators.setState(state)

Demos:

Set state

Selectors API

Each selector is a function that takes the normalized state and returns a piece of the state. Currently, the selectors API is minimal, but are enough to access any part of the state slice so that you can build your own application-specific selectors.

`getIds`

Returns an array of ids of a given entity type

(state: S, args: { type: string }): (string|number)[]

Parameters:

state: the normalized state
args.type: the entity type

Example:

const listIds = selectors.getIds(state, { type: 'item' }) // ['l1', 'l2']

`getEntities`

Returns an object literal mapping each entity's id to its data

<E>(state: S, args: { type: string }): Record<(string|number), E>

Parameters:

state: the normalized state
args.type: the entity type

Generic Parameters:

<E>: the entity's type

Example:

const lists = selectors.getEntities(state, { type: 'item' })
/*
{ 
  l1: { title: 'first list', itemIds: ['i1', 'i2'] },
  l2: { title: 'second list', itemIds: [] } 
} 
*/

`getEntity`

Returns an entity by its type and id

<E>(state: S, args: { type: string; id: string|number }): E | undefined

Parameters:

state: the normalized state
args.type: the entity type
args.id: the entity id

Generic Parameters:

<E>: the entity's type

Note:

if the entity does not exist, then undefined will be returned

Example:

const lists = selectors.getEntity(state, { type: 'item', id: 'i1' })
/*
{ title: 'first list', itemIds: ['i1', 'i2'] }
*/

Normalizr Integration

The top-level named export fromNormalizr takes normalized data produced by a normalizr normalize call and returns state that can be fed into the reducer.

Example:

import { normalize } from 'normalizr'
import { fromNormalizr } from 'normalized-reducer'

const denormalizedData = {...}
const normalizrSchema = {...}

const normalizedData = normalize(denormalizedData, normalizrSchema);
const initialState = fromNormalizr(normalizedData);

Demos:

Normalizr Integration

LICENSE

MIT

normalized-reducer normalized-reducer copied to clipboard

Metadata

Normalized Reducer

The Problem

The Solution

Install

Quick Start

Demo

Action demos and usage examples

Comparison to Alternatives

Top-level API

Parameter: schema

Parameter: namespaced

Generic Parameter: <S extends State>

Return Value

reducer

actionCreators

actionTypes

selectors

emptyState

Action-creators API

create

delete

update

attach

detach

move

moveAttached

sort

sortAttached

batch

setState

Selectors API

getIds

getEntities

getEntity

Normalizr Integration

LICENSE

← Metadata

Owner

Metadata

normalized-reducer
normalized-reducer copied to clipboard

Parameter: `schema`

Parameter: `namespaced`

Generic Parameter: `<S extends State>`

`reducer`

`actionCreators`

`actionTypes`

`selectors`

`emptyState`

`create`

`delete`

`update`

`attach`

`detach`

`move`

`moveAttached`

`sort`

`sortAttached`

`batch`

`setState`

`getIds`

`getEntities`

`getEntity`