Relational Entities Reducer

Manage relational state via a simple, declarative API.

• pure functions (actions + reducers) and framework agnostic
• supports one and many cardinalities, and recursive/self-referencing relations

Examples

Live Demo

Source

Release status: :construction: not yet production ready

• API is subject to changes
• Needs higher test coverage

Basic Usage

Install: yarn add relational-entities-reducer

1. Define how your data are related to each other:

const schema = {
  user: {
    postIds: { has: 'many', type: 'post' }
  },
  post: {
    authorId: { has: 'one', type: 'user' },
    commentIds: { has: 'many', type: 'comment' }
  },
  comment: {
    commenterId: { has: 'one', type: 'user' },
    postId: { has: 'one', type: 'post' }
  }
};

2. Pass the schema to the library function.

import makeEntities from 'relational-entities-reducer';

const entities = makeEntities(schema);

const { 
  actionCreators,
  actionTypes,
  reducer,
  selectors,
  emptyState,
} = entities;

3. Wire up the reducer to your code.

The reducer is an pure function agnostic of libraries/frameworks, so it can be used with or without React, Redux, etc.

Redux:

import { createStore } from 'redux';

const store = createStore(entities.reducer, emptyState);

React Hooks:

import { useReducer } from 'react';

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

4. Pass actions to the reducer to write to state.

You can add, remove, edit, link, unlink, and reindex resources with the following action-creators:

const { 
  add, 
  remove, 
  edit, 
  link,
  unlink,
  reindex, 
  reindexRelated
} = entities.actionCreators;

add

Adds new resources to state. It takes one or more arguments, each a tuple or object describing a new resource.

add(
  { type: 'user', id: 'u3' },
  ['user', 'u4']
)

Optionally, a data object can be passed with each arg:

add(
  { type: 'user', id: 'u1', data: { userName: "axolotl" } },
  ['user', 'u2', { userName: 'AzureDiamond', password: 'hunter2' }],
)

Related id's can be passed in with the data object, and the reducer will attach id's to the corresponding resources to form the relationships. If the those related id's do not have an existing resource in state, then new ones will be created.

add(
  // object arg
  { type: 'post', id: 'p1', data: { authorId: 'u1' } },
  
  // tuple arg
  ['post', 'p2', { authorId: 'u2', commentIds: ['c1', 'c2'] }] 
)

remove

Removes existing resources from state. It takes one or more arguments, each a tuple or object describing a resource removal.

remove(
  // object arg
  { type: 'user', id: 'u3' },
  
  // tuple arg
  ['user', 'u4']
)

When a resource is removed, the reducer will detach any resources linked to the removed resources. In the above example, any resources linked to users u3, u4 would be unlinked from them.

You can also remove a chain of resources in one go. For example, you might want to remove a user, all its posts, and all comments of those posts. To do this, pass in an options object with a removalSchema that describes the chain of resource removals:

const userRemovalSchema = {
  postIds: {
    commentIds: {}
  }
}

remove(
  { type: 'user', id: 'u3', options: { removeRelated: userRemovalSchema } },
  ['user', '4', { removeRelated: userRemovalSchema }]
)

edit

Edits existing resources. It takes one or more arguments, each an object or tuple describing a resource modification.

edit(
  // object arg
  { type: 'user', id: 'u1', data: { userName: "axolotl1" } },
  
  // tuple arg
  ['user', 'u2', { userName: 'AzureDiamond10000', password: 'hunter2000' }],
)

The operation is a constructive operation. Only the data values passed in will be written to the resource; omitting fields from the data payload will not remove those fields from state.

Warning: do not modify relational data in the edit action. If you do, you will probably end up with invalid state. Instead use the link and unlink action creators. Modifying relational data via edit might be supported in the future.

reindex

Changes the index of a single resource with respect to its top-level order.

// move post at index 2 to index 5
reindex('post', 2, 5);

reindexRelated

Within a single resource, change the index of a single linked resource.

// in post p1, move comment at index 3 to index 6
reindexRelated('post', 'p1', 'commentIds', 3, 6);

link

Links resources by attaching their ids to one another. It takes one or more arguments, each an object or tuple describing which resources to link together.

link(
  // object arg, link post p1 to comment c1
  { type: 'post', id: 'p1', relation: 'commentIds', linkedId: 'c1', indices: [] }
  
  // tuple arg, link comment c2 to post p1
  ['comment', 'c2', 'postId', 'p1', []]
);

The array param is where you can specify the index at which each id should be within its linked resource.

link(
  // in post p1's commentIds, c1 will get added at index 2 
  ['post', 'p1', 'commentIds', 'c1', [2]] 
);

For a many-to-many relationship, you can pass in two indices.

link(
  // a post has-many tags, a tag has-many posts 
  // post p2 will have t2 at index 2, and tag t2 will have post p2 at index 5 
  ['post', 'p2', 'tagIds', 't2', [2, 5]] 
);

The indices arg will be optional in the future.

unlink

Unlinks resources by removing their ids from one another. It takes one or more arguments, each an object or tuple describing which resources to unlink.

unlink(
  // unlink post p1 from comment c1
  { type: 'post', id: 'p1', relation: 'commentIds', linkedId: 'c1' },
  
  // unlink comment c2 from post p2
  ['comment', 'c2', 'postId', 'p2']  
)

5. Use selectors to read from state

This library's function returns a selectors object containing simple selector functions that can read from the relation state.

const { selectors } = makeEntities(schema);

getEntityResources

Accepts state and the resource type and returns an object mapping the ids to their resources.

const resources = selectors.getEntityResources(state, { type: 'post' });
console.log(resources); // { p1: {...}, p2: {...}, ... }

getEntityIds

Accepts state and the resource type and returns an array of the top-level ids.

const ids = selectors.getEntityIds(state, { type: 'post' });
console.log(ids); // ['p1', 'p2', ...]

getResource

Accepts state, the resource type, and the resource id, and returns the resource if it exists.

const resource = selectors.getResource(state, { type: 'post', id: 'p1' });
console.log(resource); // { title: '...', commentIds: [...] }

Advanced Usage

Multiple foreign keys for a related entity

To have multiple foreign keys point to the same entity, define a reciprocalKey for both entities in the schema:

const schema = {
  user: {
    authoredPostIds: {
      has: 'many',
      type: 'post',
      reciprocalKey: 'authorId'
    },
    editablePostIds: {
      has: 'many',
      type: 'post',
      reciprocalKey: 'editorIds'
    }
  },
  post: {
    authorId: {
      has: 'one',
      type: 'user',
      reciprocalKey: 'authoredPostIds'
    },
    editorIds: {
      has: 'many',
      type: 'user',
      reciprocalKey: 'editablePostIds'
    }
  }
}

Self-referencing/recursive relationships

You might need a self-referencing/recursive resource, such as comment tree. To do this, define the schema as such:

const schema = {
  comment: {
    parentId: {
      has: 'one',
      type: 'comment',
      reciprocalKey: 'childIds'
    },
    childIds: {
      has: 'many',
      type: 'comment',
      reciprocalKey: 'parentId'
    }
  }
}

To remove a resource and child descendants recursively:

const commentRemovalSchema = () => ({
  childIds: commentRemovalSchema
});

const userRemovalSchema = () => ({
  postIds: {
    commentIds: commentRemovalSchema
  }
})

remove(
  ['comment', 'c1', { removeRelated: commentRemovalSchema }],
  ['user', 'u1', { removeRelated: userRemovalSchema }]
)