Have ideas to improve npm?Join in the discussion! »

    imumo

    1.1.1 • Public • Published

    Version Build Status MIT license dependencies devDependency Status airbnb code style


    Extends ImmutableJS Records enabling class inheritance

    Dependencies

    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

    Install

    npm i imumo

    DownloadsWeekly Downloads

    1

    Version

    1.1.1

    License

    MIT

    Last publish

    Collaborators

    • avatar