Browser-ORM
Note: This is a replacement for redux. This is NOT meant to integrate with any server databases directly, like sql. This makes all data constant by saving data to browser storage. The data is usually retrieved by an api. This makes it so all data is uniform and regular.
Simple state management with minimalistic API for angular 2+. This is similar to how mongoose / eloquent(laravel) (any orm) manages data on the backend. Bringing this functionality to the frontend is game changer, since anyone familiar with an orm can jump right in. This is made for Angular 2+ but may also work with react. Although redux is great this is meant to be a simpler and more effective solution to state managment.
Installation
npm i browser-orm
Doc Menu
- Purpose
- Getting Started
- Example Model
- Example Component
- Instance Methods
- Instance Hooks & Events
- Static Methods
- Static Events & Hooks
- Associations
Purpose
This is made to access and store data in the browser that is easily retrieved from different components in Angular. This is very similar to a model base system like an ODM/ORM. the syntax is very similar to Laravel's Eloquent. Each model has events that are triggered which allows for realtime view change. This is very useful for large apps when actively checking data slows down the app significantly.
This package may actually work with react. TBD
If you refresh the browser the data still exists inside, and is easily retrievable. Pretty awesome!
Getting Started
The standard way of getting set up is to create a directory called: models Then lets say I have user data, and post data. I create 2 files in the models directory called
- user.model.ts
- post.model.ts
My user model looks like:
Example Model
import { Model, Col } from 'browser-orm';
export class User extends Model {
@Col({primary:true})
id: number;
@Col()
first;
@Col()
last;
fullname(){
return this.first + ' ' + this.last;
}
}
Example Component
import { User } from './../models/user.model';
ngOnInit() {
let user1 = User.findOneAndUpdate({first:'Scott', last:'Thomas'}, {}, {upsert:true});
let user2 = User.findOneAndUpdate({first:'Brian', last:"Alois"},{}, {upsert:true});
console.log('user1', user1.fullname());
console.log('user2', user2.fullname());
user1.first = 'Jordan';
user1.save();
console.log('user1', user1.fullname());
}
Instance Methods
save
saves instance in web storage
let company = Company.findOne({name:'facebook'});
company.value = 500;
company.save()
remove
Removes object from web storage
let company = Company.findOne({name:'facebook'});
company.remove()
toObject
converts model to Javascript Object
let company = Company.findOne({name:'facebook'});
obj = company.toObject();
reload
reloads models instance data to match what is in browser storage
let company = Company.findOne({name:'facebook'});
company.name = 'google';
company.reload()
console.log(company.name); // will print out facebook
company.name = 'google';
company.save()
console.log(company.name); // will print out google
storage and instance differences
reloads models instance data to match what is in browser storage
let company = Company.findOne({name:'facebook'});
company.name = 'google';
let storage_dif = company.storageDifference();
console.log(storage_dif);//log {name:'facebook'}
let instance_dif = company.instanceDifference();
console.log(instance_dif);//log {name:'google'}
Instance Events & Hooks
On Save
company.on('save', ()=>{
console.log('company was saved');
});
On Remove
company.on('remove', ()=>{
console.log('company was deleted');
});
On Reload
company.on('reload', ()=>{
console.log('company was reloaded');
});
On Change
company.on('change', ()=>{
console.log('company was changed');
});
Custom Events
This is for the specific company
company.emit('added user');
company.on('added user', ()=>{
console.log('added user');
});
company.emit(['added product', 'created product'], {name:'shoes'});
company.on('added product', (product)=>{
console.log('added product: ', product.name);
});
//watch for 2 events at the same time
company.on(['added product', 'created product'], (product)=>{
console.log('added product: ', product.name);
});
Note: If you want the event to be thrown also as a static event add 3rd parameter as true
company.emit(['added product', 'created product'], {name:'shoes'}, true);
Company.on('added product', (data)=>{
console.log('product added');
});
Static Methods
create
creates new Instance of model
let company = Company.create({name:'google', value:'600'})
createOrUpdate
This will either create a new instance using the data, or given a primary key will update an already existing model with that key and return the corresponding instance.
let company = Company.createOrUpdate({id:4, name:'google', value:'600'})
remove
Removes all instances with the given value from web storage
Company.remove({name:'microsoft'})
update
Updates all instances with given value in web storage Company.update([query params], [new_data])
Company.update({value:500}, {name:'Orange'});
updateOne
Updates one instances with given value in web storage Company.update([query params], [new_data])
Company.updateOne({value:500}, {name:'Orange'});
find
returns an array of company instances with given value from web storage
let companies = Company.find({value:500});
findOne
returns an instance with given value from web storage
let company = Company.findOne({value:500});
findOneAndUpdate
Searches web storage for instance and then updates it. if option upsert is set to true, if it doesn't find the instance with the given object in web storage, it will create it.
let user1 = User.findOneAndUpdate({first:'Scott', last:'Thomas'}, {}, {upsert:true});
findById
returns one instance with given id in webstorage
let user1 = User.findById(2);
Static Events & Hooks
On Create
Company.on('create', ()=>{
console.log('A company was created and added to the web storage');
});
On Remove
Company.on('remove', ()=>{
console.log('a company was removed');
});
On Change
Company.on('change', ()=>{
console.log('any company was changed');
});
Custom Events
This is for any and all data in your model
Company.emit('added user');
Company.on('added user', ()=>{
console.log('added user');
});
Company.emit(['added product', 'created product'], {name:'shoes'});
Company.on('added product', (product)=>{
console.log('added product: ', product.name);
});
Company.on(['added product', 'created product'], (product)=>{
console.log('added product: ', product.name);
});
Associations
One to One
One-To-One associations are associations between exactly two models connected by a single foreign key. A simple example would be User that owns only one Post
hasOne
Example Model
import { Model, Col } from 'browser-orm';
export class User extends Model {
@Col({primary:true})
id:number;
@Col
name:string;
constructor(obj:object){
super(obj);
}
Post(){
return this.hasOne(Post, 'user_id', '_id');
}
}
export class Post extends Model {
@Col({primary:true})
id:number;
@Col()
post_name:string;
constructor(obj:object){
super(obj);
}
}
Then in the Component
ngOnInit() {
this.user = User.Auth();
this.post = this.user.Post();
console.log('post name', this.post.post_name);
}
belongsTo
Example Model
import { Model, Col } from 'browser-orm';
export class User extends Model {
@Col({primary:true})
id;
@Col()
name;
constructor(obj:object){
super(obj);
}
Post(){
return this.hasOne(Post, 'user_id', '_id');
}
}
export class Post extends Model {
@Col({primary:true})
id;
@Col
post_name;
constructor(obj:object){
super(obj);
}
User(){
return this.belongsTo(User, 'user_id', '_id');
}
}
Then in the Component
ngOnInit() {
this.post = Post.findById(1);
let user = this.post.User();
console.log('user name', user.name);
}
One to Many
hasMany
Lets say the user has many posts Example Model
import { Model, Col } from 'browser-orm';
export class User extends Model {
@Col({primary:true})
id;
@Col
name;
constructor(obj:object){
super(obj);
}
Posts(){
return this.hasMany(Post, 'user_id', '_id');
}
}
export class Post extends Model {
@Col({primary:true})
id:number;
@Col()
post_name:string;
constructor(obj:object){
super(obj);
}
User(){
return this.belongsTo(User, 'user_id', '_id');
}
}
Then in the Component
ngOnInit() {
this.user = User.findById(1);
let posts = this.user.Posts();
for(let i in posts){
let post = posts[i];
console.log('post name', post.post_name);
}
}
Many to Many
This gets more complicated. Functionality is completed, but has not been documented please comment here if you want this to be documented.