npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

fluxible-immutable-utils

v0.5.10

Published

A collection of utilities that provide convenience methods for using Immutable.js with a fluxible based application

Downloads

36

Readme

fluxible-immutable-utils

npm version Build Status Dependency Status devDependency Status Coverage Status

This package provides easy to use mixins/utils for both fluxible stores and react components.

$ npm install --save fluxible-immutable-utils

createImmutableContainer

This method creates an immutable higher order component.


var MyComponent = createReactClass({
    displayName: 'MyComponent',

    ...
});

var createImmutableContainer = require('fluxible-immutable-utils').createImmutableContainer;

// Wraps your component in an immutable container.
// Prevents renders when props are the same
module.exports = createImmutableContainer(MyComponent);

// Wraps your component in an immutable container that listens to stores
// and pass its state down as props
module.exports = createImmutableContainer(MyComponent, {
    stores: [SomeStore],
    getStateFromStores: {
        SomeStore: function (store) {
            return {
                someState: store.state;
            }
        }
    }
});

ComponentMixin

A mixin that provides convenience methods for using Immutable.js inside of react components. Note that this mixin uses the initializeComponent method for setup, and any components that use this mixin should define a 'getStateOnChange' function for generating component state (see below).

This mixin has several purposes:

  • Checks that the objects in state/props of each component are an Immutable Map.
  • Implements a default shouldComponentUpdate method.
  • Provides a convenience method for dealing with state changes/component initialization.

Immutalizing State

The mixin uses the initalizeState method to set up all default functions, and checks for a method named 'getStateOnChange' in order to get the initial state object. If used with fluxible's FluxibleMixin, getStateOnChange will also be called whenever a store is updated (if onChange is not defined). This allows a reduction in boilerplate by not having to define separate functions for app initialization/store updates (since components should handle state the same in either case).

The mixin expects props/state to remain immutable throughout a component's lifecycle and only shallowly examines the props object when checking for data equality. Thus it is HIGHLY recommended to pass in immutable objects as props/state to a component using this mixin (the mixin will warn when not doing so). You may configure which objects to check by setting the ignoreImmutableObjects static property (example below).

shouldComponentUpdate

The immutable mixin implements a version of shouldComponentUpdate to prevent needless re-rendering of components when the props/state haven't changed (by checking if the new props/state have been changed from the old props/state). If a component provides its own shouldComponentUpdate method, then the default implementation will not be used.

getStateOnChange

Since ImmutableMixin must use the initializeComponent method for setting up default methods, it cannot be used by the components. Instead, ImmutableMixin will call the 'getStateOnChange' method in getInitialState. This method will also be called if used with the FluxibleMixin on store changes (again, only if onChange is not defined) which helps to reduce boilerplate within components.

API

shouldUpdate (nextProps, nextState)

Utility method that is set as the shouldComponentUpdate method in a component unless it is already defined. Checks whether the props/state of the component has changed so that we know whether to render or not.

  1. {Object} The next props object
  2. {Object} The next state object

defaultOnChange ()

Utility method that is set as the onChange method. A default onChange function that sets the the components state from the getStateOnChange method. This is only set if a component does not implement its own onChange function. Typically used with the fluxibleMixin.

getInitialState ()

Called internally by React. Sets up a few of the immutable methods and then returns the state of the component, after ensuring it is immutable. If getStateOnChange() is not defined, then just sets the state to null.

Example

// MyReactComponent.jsx

var ImmutableMixin = require('fluxible-immutable-utils').ComponentMixin;

module.exports = createReactClass({
    displayName: 'MyReactComponent',
    mixins: [ImmutableMixin],
    getStateOnChange: function () {
        if (!this.state) {
            //initialize here if needed
        }
        return {
            someStateProperty: 'foo'
        };
    },

    render: function () {
        return <span>My React Component</span>;
    }
});

var myObject = {
    foo: 'bar'
};
<MyReactComponent
    someKey={myObject} // fine, because we set this key to be ignored
    aNonImmutableObject={myObject} // will cause a console.warn statement because we are passing a non-immutable object
/>

Configuring the Mixin

If you are using third party libraries/have a special case where you don't want the mixin to consider some of the keys of props/state, you have two options. First, you can set the ignoreImmutableCheck object to skip the check for immutability for any keys you decide. Second, if you want the mixin to also ignore a key when checking for data equality in props/state, you can set the key value to the flag SKIP_SHOULD_UPDATE. You must set these values inside a component's statics field (or in a config, see below), and they must be set seperately for props/state. You can also turn off all warnings by settings the ignoreAllWarnings flag.

Example

// MyReactComponent.jsx

var ImmutableMixin = require('fluxible-immutable-utils').ComponentMixin;

module.exports = createReactClass({
    displayName: 'MyReactComponent',
    mixins: [ImmutableMixin],
    statics: {
        ignoreAllWarnings: (process.env.NODE_ENV !== 'dev') // turn off all warnings when not in dev mode
        ignoreImmutableCheck:  {
            props: {
                someKey: true // don't check someKey for immutablility in props
            },
            state: {
                anotherKey: 'SKIP_SHOULD_UPDATE' // don't check anotherKey for immutablility in props, AND don't check its value is shouldComponentUpdate
            }

        }
    },

    ...rest of component follows...
});

If you want to just pass around a common config, then use:

var ImmutableMixin = require('fluxible-immutable-utils').createComponentMixin(myConfig);

Where myConfig has the same structure as the statics above.

ImmutableStore

A class to inherit similar to the fluxible addon BaseStore. Internally it inherits 'fluxible/addons/BaseStore.

The main use case for this method is to reduce boilerplate when implementing immutable fluxible stores.

The helper adds a new property and some helper methods to the created store

  • _state {Map} - The root Immutable where all data in the store will be saved.

  • setState(newState, [event], [payload]) {Function} - This method replaces this._state with newState (unless they were the same) and then calls this.emit(event, payload).

    • If event is falsy it will call this.emitChange(payload)
    • The method also ensures that _state remains immutable by auto-converting newState to an immutable object.
  • mergeState(newState, [event], [payload]) {Function} - This method does a shallow merge with this._state and then calls this.emit(event, payload).

    • If event is falsy it will call this.emitChange(payload)
    • The method also ensures that _state remains immutable by auto-converting newState to an immutable object.
  • getState() {Function} - This method returns the this._state.

  • get(key) {Function} - Get a value by key from the store.

and creates defaults for the following fluxible store methods

  • constructor() - The default implementations creates a _state property on the store and initializes it to Immutable.Map

  • rehydrate(state) - The default implementation hydrates _state

  • dehydrate() - The default implementation simply returns _state which is Immutable (due to all Immutable objects implementing a toJSON function, _state can be directly passed to JSON.stringify)

Note that all defaults can still be overwritten when creating the store.

Note 2 Avoid returning a _state.toJS() from a store when using it with the createImmutableContainer since an ImmutableContainer expects and uses the Immutable data to do comparisons when deciding to re-render.

Example Usage

// FooStore.js

import {ImmutableStore} from 'fluxible-immutable-utils';

class FooStore extends ImmutableStore {
    // public accessors
    getBar: function (id) {
        return this._state.get('bar');
    }

    // private mutators, these should only be called via dispatch
    _onNewFoo(data) {
        // data = { foo: 'Hello', bar: 'World' }            
        this.setState(data);        
    }

    _onNewBar(bar) {
        // This will just update bar and leave foo with the same state
        this.mergeState({ bar: bar });
    }
}

FooStore.storeName = 'FooStore';

FooStore.handlers = {
    NEW_FOO: '_onNewFooBar',
    NEW_FOOS: '_onNewBar'  
};

export default FooStore;