immutable-models

Immutable Models

Create immutable models driven by Immutable.js iterables.

Installation

Immutable Models requires Immutable.js 3.8.0 or later.

npm install --save immutable-models

This assumes that you’re using npm package manager with a module bundler like Webpack or Browserify to consume CommonJS modules.

Motivation

Immutable.js is a great library for dealing with immutable data. However, it doesn't provide the easy way for hermetization. Because of that, we can't create simple and defined model interfaces - everything is public and (excluding Records) there is no way to put additional logic in these models.

Immutable Models wraps immutable structures and provides interfaces defined by a developer.

Let's see some example:

import { Model } from 'immutable-models';
import { Permission } from './Permission';
import { Set } from 'immutable';

interface UserShape {
  userName: string
  createdBy?: User;
  permissions?: Set<Permission>;
}

export class User extends Model<UserShape> {
  getUserName(): string {
    return this.get('userName');
  }
    
  getCreatedBy(): User {
    return this.get('createdBy');
  }
  
  isAdmin(): boolean {
    return this.hasPermission(Permission.ADMIN);
  }
  
  isCreatedByAdmin(): boolean {
    return this.getCreatedBy() ? this.getCreatedBy().isAdmin() : false;
  }
  
  getPermissions(): Set<Permission> {
    return this.get('permissions', Set<Permission>());
  }
  
  hasPermission(permission: Permission): boolean {
    return this.getPermissions().contains(permission);
  }
  
  addPermission(permission: Permission): this {
    return this.update('permissions', permissions => permissions.add(permission));
  }
}

// example usage
const user = new User({ 
  userName: 'piotr', 
  permissions: Set([Permission.DEVELOPER]) 
});

user.getUserName(); // > piotr
user.isAdmin(); // false


// create admin user based on user - immutable data
const adminUser = user.addPermission(Permission.ADMIN); // make me an admin!

adminUser.getUserName(); // > piotr
adminUser.isAdmin(); // > true
user.isAdmin(); // > false


// create another user
const anotherUser = new User({
  userName: 'lukasz',
  createdBy: adminUser
});

anotherUser.isAdmin(); // > false
anotherUser.isCreatedByAdmin(); // > true

Like you see, User class hides complexity of Immutable.js structures and contains business logic.

Documentation

It's not completed but we are working on it:

• API Reference

Typings

If you are using TypeScript, you don't have to install typings - they are provided in npm package.

License

MIT

Changelog

v0.1.2

• Add update and has methods to Model
• Add has method to ReadonlyModel
• Add notSetValue argument to get method in ReadonlyModel