npm:imumo | Skypack

README

Extends ImmutableJS Records enabling class inheritance

Dependencies

ImmutableJS

Getting Started

npm install imumo --save

Usage

import { ImmutableModel } from  'imumo';

class BaseModel extends ImmutableModel {
  // Define getters to expose easy access to properties
  get value() {
    return this.get('value', null);
  }
  isComplete() {
    return true;
  }
  isValid() {
    return true;
  }
}

class TextModel extends BaseModel {
  // create synthetic properties
  get length() {
    return this.value.length;
  }
  // override default values
  get value() {
    return this.get('value', '');
  }
  isComplete() {
    return this.value.length !== 0;
  }
  isValid() {
    return typeof this.value === 'string';
  }
  // 'Mutable' methods should all return a new immutable instance
  toLower() {
    return this.set('value', this.value.toLocaleLowerCase());
  }
}

class EmailModel extends TextModel {
  isValid() {
    return super.isValid() && /^[^@]+@[^\.]+\.(?:com|edu|biz)$/.test(this.value);
  }
}

class NumberModel extends BaseModel {
  get units() {
    return this.get('units', null);
  }
  get value() {
    return this.get('value', 0);
  }
  isValid() {
    return typeof this.value === "number";
  }
  add(val) {
    return this.set('value', this.value + val);
  }
  toString() {
    return this.units ? `${this.value} ${this.units}` : this.value;
  }
}



const bobsEmail = new EmailModel({value: 'bob@gmail.com'});
console.log(bobsEmail.isValid()); // true
console.log(bobsEmail.set('value', 'bobATgmailDOTcom').isValid()); // false
console.log(bobsEmail.isValid()); // true -- bobsEmail has not been mutated

const myBank = new NumberModel({units: 'dollars'});
console.log(myBank.toString()); // 0 dollars
const myBankAfterDreamOfWinningLotto = myBank.add(100000000);
console.log(myBankAfterDreamOfWinningLotto.toString()); // 100000000 dollars
console.log(myBank.toString()); // 0 dollars -- myBank was not mutated :(

Performance

Since the models are immutable, we can store memoized results of method calls on our model instances. Since memoization is stored on the instance, any mutations will invalidate the cache and gargabe collection comes for free. This lets you write expensive getters without having to worry too much about the performance impact. This also allows you to use strict equality checking against derived data (Pure render all the views). Note: Since the constructor is only run when new is called, you need to put your memoizers in the didCreateInstance lifecycle hook. Note: Memoization uses strict equality to check for matches, so passing in a new instance of an Immutable List, for example, will not be memoized. Remember to set the cache size if you think there will be a large number or unique calls.

import { List } from 'immutable';
import { ImmutableModel, memoize } from 'imumo';

class InboxModel extends ImmutableModel {
  didCreateInstance() {
    this.getUnreadEmails = memoize(this.getUnreadEmails.bind(this));
    this.getEmailsFromUser = memoize(this.getEmailsFromUser.bind(this));
  }
  get emails() { return this.get('emails', new List()); }
  getUnreadEmails() {
    return this.emails.filter(email => !email.read);
  }
  getEmailsFromUser(user) {
    return this.emails.filter(email => email.user === user);
  }
}

const inbox = new InboxModel(List([...]));
console.log(inbox.getUnreadEmails() === inbox.getUnreadEmails()); // true
console.log(inbox.getEmailsFromUser('bobby@gmail.com') === inbox.getEmailsFromUser('bobby@gmail.com')); // true

Methods ImmutableModel

Signatures using flow notation [functionName]([arg] : [argType]) : [returnType]. Note that T denotes either the same instance or a new instance of the same type. ImmutableModels create new instances with the same type whenever a mutation occurs.

signature	description
`didCreateInstance()`	Lifecycle method called after new instance is made (due to 'mutation')
`toString(): String`	Returns string representation of model
`get(key: String, notSetVal: any): any`	Gets value by key if exists, otherwise returns `notSetVal`
`clear(): T`	Returns self or new `T` without any values in backing Map
`set(key: String, val: any): T`	Returns self or new `T` with key set to value
`remove(key: String): T`	Returns self or new `T` with value at key removed
`removeIn(keyPath: Array<any>): T`	Returns self or new `T` with value at keypath removed
`merge()`	see Map.merge()
`mergeWith()`	see Map.mergeWith()
`mergeIn()`	see Map.mergeIn()
`mergeDeep()`	see Map.mergeDeep()
`mergeDeepWith()`	see Map.mergeDeepWith()
`mergeDeepIn()`	see Map.mergeDeepIn()
`setIn()`	see Map.setIn()
`update()`	see Map.update()
`updateIn()`	see Map.updateIn()
`withMutations()`	see Map.withMutations()
`asMutable()`	see Map.asMutable()
`asImmutable()`	see Map.asImmutable()

Many methods are duplicates/copies of Immutable Map methods, which have more thorough documentation and examples.

Credits

ImmutableJS for underlying data structures
npm-starter
Airbnb for the work they've put into the javascript style guide and into the ESlint package.

License

MIT @ Joe Delgado

Usage no npm install needed!