Entity Store Package

A set of base classes for defining entities, stores for each entity, and relationships between them, facilitating the tasks of creating, fetching, updating and deleting them.

[[TOC]]

Complete example

// entities/User.types.ts
export interface UserAttributes{
	id: number
	email: string
	fullName: string,
	avatarUrl: string,
}

export interface UserSerialization {
	id: number
	email: string
	full_name: string,
	avatar_url: string,
}

// entities/User.ts
import { StoreEntity, IRootStore } from '@amalgamaco/entity-store';
import { makeObservable, observable } from 'mobx';
import { UserAttributes, UserSerialization } from './User.types';

export default class User extends StoreEntity {
	id: number;
	email: string;
	fullName: string;
	avatarUrl: string;

	constructor( attributes: UserAttributes, rootStore?: IRootStore ) {
		super( rootStore );

		this.id = attributes.id;
		this.email = attributes.email;
		this.fullName = attributes.fullName;
		this.avatarUrl = attributes.avatarUrl;

		makeObservable( this, {
			id: observable,
			email: observable,
			fullName: observable,
			avatarUrl: observable
		} );
	}

	updateWith( other: User ): User {
		this.fullName = other.fullName;
		this.email = other.email;
		this.avatarUrl = other.avatarUrl;

		return this;
	}

	toJSON() {
		return {
			id: this.id,
			email: this.email,
			full_name: this.fullName,
			avatar_url: this.avatarUrl
		};
	}

	static fromJSON( attributes: UserSerialization, rootStore?: IRootStore ) {
		return new User( {
			id: attributes.id,
			email: attributes.email,
			fullName: attributes.full_name,
			avatarUrl: attributes.avatar_url
		}, rootStore );
	}
}

// stores/RootStore.types.ts
import type { AttrsType, EntityStore } from '@amalgamaco/entity-store';
import User, { UserSerialization } from '../entities/User';

export type UserStore = EntityStore<User, AttrsType<typeof User>>;

export type UsersStoreSerialization = UserSerialization[];

export interface RootStoreSerialization {
	usersStore?: UsersStoreSerialization
}

// stores/RootStore.ts
import { makeAutoObservable } from 'mobx';
import { PersistableRootStore } from '@amalgama/mobx-store-persistor'; // Private repository
import { EntityStore, AttrsType } from '@amalgamaco/entity-store';
import User from '../entities/User';
import {
	RootStoreSerialization, UsersStoreSerialization, UserStore
} from './RooStore.types';

export class RootStore implements PersistableRootStore {
	userStore: UserStore;
	// eslint-disable-next-line @typescript-eslint/no-explicit-any
	[ key: string ]: any;

	constructor() {
		this.userStore = new EntityStore<User, AttrsType<typeof User>>( User, this );

		makeAutoObservable( this );
	}

	serializationToPersist(): RootStoreSerialization {
		return {
			usersStore: this.userStore.serialize() as UsersStoreSerialization
		};
	}

	rehydrateWithSerialization( serialization: RootStoreSerialization ) {
		this.userStore.hydrate( serialization.usersStore || [] );
	}

	getStore( storeName: string ) {
		return this[ `${storeName}Store` ] || null;
	}

	clearStore() {
		this.userStore.clear();
	}
}

EntityStore

A store for entities of a given type.

import { EntityStore, AttrsType } from '@amalgamaco/entity-store';
import Item from '../entities/Item';
import { rootStore } from './shared';

const itemsStore = new EntityStore<Item, AttrsType<typeof Item>>( Item, rootStore );
rootStore.itemsStore = itemsStore;

const item = itemsStore.create( { id: 1, ... } );

Methods

constructor( EntityClass, rootStore ): EntityStore<Entity, EntityAttrs>

Creates a new store for the given EntityClass and rootStore.

Parameters

Name	Type	Description
EntityClass	IEntityClass<Entity, EntityAttrs>	The class of the entities that will be stored in this store.
rootStore	IRootStore	The root store that saves a reference to the stores that contain the relations for the entities stored in this store. When creating a new entity using the method create, this root store will be automatically set to the created store entity.

create( attributes: EntityAttrs )

Creates a new entity with the given attributes using the entity's constructor method. Sets the store's root store as the entity root store.

Parameters

Name	Type	Description
attributes	EntityAttrs which should extend IEntityRequiredAttributes	The attributes to create the entity with.

add( entity: Entity )

Adds a new entity to the store. If an entity with the same id already exists, it's updated with the passed entity by calling updateWith on the existing entity.

Parameters

Name	Type	Description
entity	Entity which should extend IEntity	The entity to add to the store.

has( id: ID ): boolean

Returns true if there is an entity with the passed id stored in the store. Returns false otherwise.

Parameters

Name	Type	Description
id	ID	The id to check.

get( id: ID ): Entity | null

Returns the entity with the passed id or null if there is no entity for that id.

Parameters

Name	Type	Description
id	ID	The id of the entity to retrieve from the store.

all(): Entity[]

Returns a list with all the entities stored in the store.

where( condition: ( entity: Entity ) => boolean ): Entity[]

Returns a list of all the entities stored in the store that meet the passed condition.

Parameters

Name	Type	Description
condition	( entity: Entity ) => boolean	The condition to check against the entities in the store. This callback receives an entity and must return a boolean indicating if the given entity meets the condition or not.

delete( id: ID )

Deletes the entity with the passed id from the store.

Parameters

Name	Type	Description
id	ID	The id of the entity to delete.

deleteAll( ids: ID[] )

Deletes all the entities identified by the passed ids list.

Parameters

Name	Type	Description
ids	ID[]	A list of ids of the entities to delete.

replace( entities: Entity[] )

Replaces the stored entities with the ones passed.

Parameters

Name	Type	Description
entities	Entity[] which should extend IEntity	The entities to replace the store content with.

clear()

Empties the store.

serialize(): IStoreSerialization

Serializes the store. It rerurns a list of the serializations for all the entities in the store.

hydrate( serialization : IStoreSerialization )

Fills the store with the entities created from the serialization passed.

Parameters

Name	Type	Description
serialization	IStoreSerialization	The serialization that will be used to fill the store.

Types

ID

The type of the id attribute of an entity.

type ID = number | string;

IRootStore

Represents the type of a EntityStore's root store.

interface IRootStore {
	[ key: string ]: IStore
}

IEntity

Represents the type of a entity that will be stored in a EntityStore.

interface IEntity {
	id: ID,
	rootStore?: IRootStore

	updateWith( anotherEntity: IEntity ): IEntity,
	toJSON(): IEntitySerialization,
}

IEntityClass

Represents the type of the class that contructs the entities that will be stored in a EntityStore.

interface IEntityClass<T extends IEntity, Attrs extends IEntityRequiredAttributes> {
	new( attributes: Attrs, rootStore?: IRootStore ): T
	fromJSON( attributes: IEntitySerialization, rootStore?: IRootStore ): T
}

IEntityRequiredAttributes

Represents the required atttributes for all entities.

interface IEntityRequiredAttributes {
	id: ID
}

AttrsType

Represents the attributes of an Entity. This attributes are calculated as the first parameter of the entity's constructor.

type AttrsType<T extends new ( ...args: any ) => any> = First<ConstructorParameters<T>>;

IEntitySerialization

Represents the serialization of an entity.

interface IEntitySerialization {
	id: ID
}

IStoreSerialization

Represents the serialization of a store.

type IStoreSerialization = IEntitySerialization[];

JSONValue

Represents any possible JSON value.

type JSONValue =
	| string
	| number
	| boolean
	| null
	| { [x: string]: JSONValue }
	| Array<JSONValue>;

StoreEntity

A base class for entities that will be stored using an EntityStore.

Relations

The are two ways to define relations between entities, one using Typescript property decorators and one using a static function defined in the Entity class. You can use the one you find more convinient for you.

decorators

This package provides two decorators to define properties that come from a related store: @hasMany and @belongsTo.

@hasMany

Specifies that the decorated property values will be retrieved from a related store.

parameters

Name	Description
storeName	The name of the store in the root store to retrieve the related entities from.
lkName	The name of the property in this entity that returns the ids of the related entities.

usage

import { StoreEntity, hasMany } from '@amalgamaco/entity-store';
import Comment from './Comment';

class Post extends StoreEntiy {
	// This property holds the ids of the related comments and
	// will be used to retrive the related comments from their store.
	commentIDs: number[];

	// Here we decorate the comments property with the @hasMany decorator
	// passing the name of the related entities store and the name of the
	// property that holds the releated entities ids.
	@hasMany( 'commentsStore', 'commentIDs' )
	comments!: Comment[];

	...
}

IMPORTANT: Don't forget to add the ! at the end of the decorated property definition telling Typescript that property will have a value (calculated by the decorator) even if we don't set a default one.

@belongsTo

Specifies that the decorated property value will be retrieved from a related store.

parameters

Name	Description
storeName	The name of the store in the root store to retrieve the related entity from.
lkName	The name of the property in this entity that returns the id of the related entity.

usage

import { StoreEntity, belongsTo } from '@amalgamaco/entity-store';
import User from './User';

class Post extends StoreEntiy {
	// This property holds the id of the related author and
	// will be used to retrive the related author from its store.
	authorID: number[];

	// Here we decorate the author property with the @belongsTo decorator
	// passing the name of the related entity store and the name of the
	// property that holds the releated entity id.
	@belongsTo( 'usersStore', 'authorID' )
	author?: User;

	...
}

IMPORTANT: Don't forget to add the ? at the end of the decorated property definition telling Typescript that property may be undefined and that we don't need to set a default value for it.

relationships static method

You can also specify the entity relations using the relationships static method. This method must return a list of IRelationshipConfig items.

IRelationshipConfig Each item on the relationships static method must meet the next interface:

export interface IRelationshipConfig {
	name: string,
	type: 'BELONGS_TO' | 'HAS_MANY',
	store: string,
	lookupKey: string,
}

• name: The name of the property that will hold the relationship.
• type: The type of relationship to define:
  • BELONGS_TO: This property will only return an entity whose id is indicated by the value of the property lookupKey .
  • HAS_MANY: This property willl return a list of entities whose ids are indicated by the value of the property lookupKey.
• store: The name of the store in the root store where the related entities are stored.
• lookupKey: The name of the property in the entity that holds the id or ids of the related entities.

usage

import { StoreEntity } from '@amalgamaco/entity-store';
import User from './User';
import Comment from './Comment';

class Post extends StoreEntiy {
	// This property holds the id of the related author and
	// will be used to retrive the related author from its store.
	authorID: number[];

	// This property holds the ids of the related comments and
	// will be used to retrive the related comments from their store.
	commentIDs: number[];

	author?: User;
	comments!: Comment[];


	static relationships(): IRelationshipConfig[] {
		return [
			{
				name: 'author',
				lookupKey: 'authorID',
				store: 'usersStore',
				type: 'BELONGS_TO'
			},
			{
				name: 'comments',
				lookupKey: 'commentIDs',
				store: 'commentsStore',
				type: 'HAS_MANY'
			}
		];
	}

	...
}

IMPORTANT: When declaring the properties that will return the related entities don't forget to add a ? at the end of the property name for BELONGS_TO relations and a ! at the end of the property name for HAS_MANY relations to prevent Typescript from asking to initialize the properties with default values.