DevsLane Mobx Entity Store Manager

---

Mobx Entity Store Manager is born from the need for an extensible yet easy-to-use solution that helps you manage your entities in Mobx store without writing any boilerplate code.

Table of Content

• Features

• Getting Started

• Usage

  • Example

• Documentation

  • Model Item
  • Model List
  • Paginated Model List
  • Entity Base Model

Features

• Easily manage your entities.
• Lesser boilerplate code.
• Comes with a Basic Entity Store setup .
• Support for Single Entity, Entity List and Paginated Entity List.

Getting Started

Install Mobx Entity Manager by running this command

$ yarn add @devslane/mobx-entity-manager

To finalize the setup, boot Mobx Entity Manager in your entry file, such as App.ts or index.ts, by adding the following code -

App.ts

import { ContextStatic } from '@devslane/mobx-entity-manager';
import { BaseApiService } from 'services';

ContextStatic.boot({
            api: BaseApiService.getInstance(),
        });

...

Now you are ready to use Mobx Entity Manager seamlessly.

Usage

Mobx Entity Manager provides multiple Model Classes that can be extended to create models of your entities. These Model classes provide helper methods that can be used out of the box.

Example -

A basic User Model extending EntityBaseModel class will look like -

UserModel.ts

import { EntityBaseModel, ModelList, ModelItem, ModelJson } from '@devslane/mobx-entity-manager';
import { UserStore } from 'stores';
import { observable } from 'mobx';
import { OccupationModel, EducationModel } from 'models';

class UserModel extends EntityBaseModel {
  static _store: UserStore;
  
  @observable
  name: string;
  
  @observable
  email: string;
  
  @observable
  occupations: ModelList<OccupationModel>;
  
  @observable
  education?: ModelItem<EducationModel>;
  
  deserialize_occupations(data: any[]) {
        this.occupations = new ModelList<OccupationModel>(OccupationModel);
        this.occupations.deserialize(data);
    }
  
  deserialize_education(data: ModelJson) {
        this.education = new ModelItem<EducationModel>(EducationModel);
        this.education.deserialize(data);
    }  
  
}

Documentation

• ModelItem

ModelItem wraps your single entity and provides you with all kind of basic methods.

Basic Usage -

import { ModelItem } from '@devslane/mobx-entity-manager';
import { UserModel } from 'models';

loggedInUser: ModelItem<UserModel> = new ModelItem<UserModel>(UserModel);

// Initializing value in ModelItem
await this.loggedInUser.load(`/your-api`, {
                param_key: param_value,
            });

// Accessing the entity stored in Model Item
console.log(loggedInUser.item);

// Accessing other helper properties
console.log('Is Item Loaded: ', loggedInUser.loaded);
console.log('Is Item Loading: ', loggedInUser.loading);

Methods available -

Methods	Arguments	Return Type	Description
setItem()	item: T	void	Sets the item received in argument in the ModelItem
deserialize()	item: ModelJson	void	Superset of setItem that converts the JSON object into Model class itself.
load()	url: string, params?: { [p: string]: any }, config?: { dataKey?: string; forceRefresh?: boolean; itemId?: number or string; useAuth?: boolean; }	Promise<void>	Loads your Model Item using response from a remote URL.
setLoading()	loading: boolean	void	Sets the loading property.
setLoaded()	loaded: boolean	void	Sets the loaded property.
setError()	error: BaseError or null	void	Sets the error property.

Properties available -

Properties	Return Type	Description
item	item or undefined	If set, fetches the wrapped item or undefined otherwise
loaded	boolean	Indicates whether item has been loaded or not
loading	boolean	Indicates whether item is currently being loaded
error	boolean	Indicates whether some error has occurred while loading the item

load() and deserialize() methods handle loaded, loading and error internally.

• ModelList

ModelList wraps your list of entities and provides you with all kind of basic methods to manage your list.

Basic Usage -

import { ModelList } from '@devslane/mobx-entity-manager';

users: ModelList<UserModel> = new ModelList<UserModel>(UserModel);

// Initializing value in ModelList
this.users.load('/your-api');

// Accessing the entity stored in Model List
users.items.map((item) => console.log(item));

// Accessing other helper properties
console.log('Is List Loaded: ', users.loaded);
console.log('Is List Loading: ', users.loading);

Methods available -

Methods	Arguments	Return Type	Description
setItems()	items: T[]	void	Clears the existing list and sets the items received in argument in the ModelList
appendItems()	items: T[]	void	Appends the items to already existing list
appendItem()	item: T	void	Appends an item to the end of list
unshiftItem()	item: T	void	Appends an item to the start of list
deserialize()	items: ModelJson[]	void	Superset of setItems that converts the JSON objects into Model class itself.
clearItems()	-	void	Clears all the existing items in the list and resets the loaded property.
setLoading()	loading: boolean	void	Sets the loading property.
setLoaded()	loaded: boolean	void	Sets the loaded property.
setError()	error: BaseError or null	void	Sets the error property.
load()	url: string, params?: { [p: string]: any }, config?: { dataKey?: string; forceRefresh?: boolean; itemId?: number or string; useAuth?: boolean; }	Promise<void>	Loads your Model List using response from a remote URL.

Properties available -

Properties	Return Type	Description
items	item[] or undefined	If set, fetches the wrapped list or undefined otherwise
loaded	boolean	Indicates whether list has been loaded or not
loading	boolean	Indicates whether list is currently being loaded
error	boolean	Indicates whether some error has occurred while loading the list

• PaginatedModelList

PaginatedModelList extends basic ModelList with all its features and additional support for pagination. This proves to be really helpful when dealing with entities whose lists are not fully loaded initially. So you don't have to worry about maintaining variables like lastPage, totalPages etc.

Basic Usage -

import { PaginatedModelList } from '@devslane/mobx-entity-manager';

users: PaginatedModelList<UserModel> = new PaginatedModelList<UserModel>(UserModel);

// Load initial values in PaginatedModelList
this.users.load('/your-api');

// Load next page of entities
this.users.loadNext();

// Accessing the entity stored in List
users.items.map((item) => console.log(item));

// Accessing other helper properties
console.log('Is Last Page: ', users.isLastPage);
console.log('Total Pages: ', users.totalPages);

Methods available -

Methods	Arguments	Return Type	Description
loadNext()	-	Promise<void>	Loads next page of entity items from the remote URL you passed in load method.
setIsLoadingNextPage()	loading: boolean	void	Sets the loading next page property.

Properties available -

Properties	Return Type	Description
isLoadingNextPage	boolean	Indicates whether next page is being loaded
totalPages	number	Returns total number of pages of entity
perPage	number	Returns number of items per page
lastPage	number	Returns last page number
currentPage	number	Returns current page number
nextPage	number	Returns next page number
prevPage	number	Returns previous page number
firstPageUrl	string	Returns url pointing to first page
lastPageUrl	string	Returns url pointing to last page
isFirstPage	boolean	Returns whether current page is the first page
isLastPage	boolean	Returns whether current page is the last page
isLoadedAll	boolean	Returns whether all the pages have been loaded

Since PaginatedModelList extends ModelList so all methods and properties of the latter are available in the former.

loadNext() method handles isLoadingNextPage internally.

• EntityBaseModel

Extending EntityBaseModel class in your Entity Model classes provides you with multiple ready to use properties without writing repetitive properties in each of your model.

Basic Usage -

class UserModel extends ChildStore<UserModel> {
    @observable loggedInUser?: UserModel;
    
    setLoggedInUser(data: ModelJson) {
        this.loggedInUser = UserModel.fromJson(data) as UserModel;
    }
    
    updateName(name: string) {
        this.loggedInUser.name = name;
    }
}

Example of a UserModel extending EntityBaseModel is shown above.

If you have ModelItem, or ModelList wrapped property inside Model Class then you will have to write a deserializer method for it.

• Deserializer method name must follow the convention deserializer_{property_name}

Check example for deserializer method above.

Static Methods -

Methods	Arguments	Return Type	Description
fromJson()	json: ModelJson, identifierKey?: string	EntityBaseModel or null	Create and returns a new entry in store if not already present, otherwise update and returns the existing entry.
getOrNew()	id: EntityIdentifier	EntityBaseModel	It looks for the item in store based on id and creates a new entry in store if not found
get()	id: EntityIdentifier	EntityBaseModel or undefined	Returns the item from store with same id or undefined if not found

Regular Methods -

Methods	Arguments	Return Type	Description
updateFromJson()	json: ModelJson	void	Updates the existing entry of item in the store.