{"id":20038497,"url":"https://github.com/yahoo/fluxible-immutable-utils","last_synced_at":"2025-09-07T14:36:52.998Z","repository":{"id":28885195,"uuid":"32409804","full_name":"yahoo/fluxible-immutable-utils","owner":"yahoo","description":"A mixin that provides a convenient interface for using Immutable.js inside react components.","archived":false,"fork":false,"pushed_at":"2023-03-21T05:01:00.000Z","size":114,"stargazers_count":24,"open_issues_count":13,"forks_count":15,"subscribers_count":13,"default_branch":"master","last_synced_at":"2025-05-05T06:37:18.388Z","etag":null,"topics":["flux","fluxible","immutablejs","javascript","react","react-components","web"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/yahoo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-03-17T17:41:20.000Z","updated_at":"2023-12-11T12:29:26.000Z","dependencies_parsed_at":"2024-06-21T15:21:24.244Z","dependency_job_id":"589f9552-f564-4fd4-9f55-b7e227497f4c","html_url":"https://github.com/yahoo/fluxible-immutable-utils","commit_stats":{"total_commits":103,"total_committers":19,"mean_commits":5.421052631578948,"dds":0.7378640776699029,"last_synced_commit":"a0c4ebd8df2c173e145627fc440b503b38e1aa7c"},"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"purl":"pkg:github/yahoo/fluxible-immutable-utils","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yahoo%2Ffluxible-immutable-utils","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yahoo%2Ffluxible-immutable-utils/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yahoo%2Ffluxible-immutable-utils/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yahoo%2Ffluxible-immutable-utils/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yahoo","download_url":"https://codeload.github.com/yahoo/fluxible-immutable-utils/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yahoo%2Ffluxible-immutable-utils/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267299950,"owners_count":24066069,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-27T02:00:11.917Z","response_time":82,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["flux","fluxible","immutablejs","javascript","react","react-components","web"],"created_at":"2024-11-13T10:29:32.821Z","updated_at":"2025-07-27T04:35:18.856Z","avatar_url":"https://github.com/yahoo.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# fluxible-immutable-utils\n\n[![npm version](https://badge.fury.io/js/fluxible-immutable-utils.svg)](http://badge.fury.io/js/fluxible-immutable-utils)\n[![Build Status](https://travis-ci.org/yahoo/fluxible-immutable-utils.svg?branch=master)](https://travis-ci.org/yahoo/fluxible-immutable-utils)\n[![Dependency Status](https://david-dm.org/yahoo/fluxible-immutable-utils.svg)](https://david-dm.org/yahoo/fluxible-immutable-utils)\n[![devDependency Status](https://david-dm.org/yahoo/fluxible-immutable-utils/dev-status.svg)](https://david-dm.org/yahoo/fluxible-immutable-utils#info=devDependencies)\n[![Coverage Status](https://coveralls.io/repos/yahoo/fluxible-immutable-utils/badge.svg)](https://coveralls.io/r/yahoo/fluxible-immutable-utils)\n\nThis package provides easy to use mixins/utils for both fluxible stores and react components.\n\n```bash\n$ npm install --save fluxible-immutable-utils\n```\n\n## `createImmutableContainer`\n\nThis method creates an immutable higher order component.\n\n```js\n\nvar MyComponent = createReactClass({\n    displayName: 'MyComponent',\n\n    ...\n});\n\nvar createImmutableContainer = require('fluxible-immutable-utils').createImmutableContainer;\n\n// Wraps your component in an immutable container.\n// Prevents renders when props are the same\nmodule.exports = createImmutableContainer(MyComponent);\n\n// Wraps your component in an immutable container that listens to stores\n// and pass its state down as props\nmodule.exports = createImmutableContainer(MyComponent, {\n    stores: [SomeStore],\n    getStateFromStores: {\n        SomeStore: function (store) {\n            return {\n                someState: store.state;\n            }\n        }\n    }\n});\n```\n\n## `ComponentMixin`\nA 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).\n\nThis mixin has several purposes:\n-  Checks that the objects in state/props of each component are an Immutable Map.\n-  Implements a default shouldComponentUpdate method.\n-  Provides a convenience method for dealing with state changes/component\ninitialization.\n\n### Immutalizing State\nThe 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).\n\nThe 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).\n\n### shouldComponentUpdate\nThe 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.\n\n### getStateOnChange\nSince 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.\n\n### API\n\n#### shouldUpdate (nextProps, nextState)\n\nUtility 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.\n\n1. {Object} The next props object\n2. {Object} The next state object\n\n#### defaultOnChange ()\n\nUtility 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.\n\n#### getInitialState ()\n\n 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.\n\n**Example**\n\n```jsx\n// MyReactComponent.jsx\n\nvar ImmutableMixin = require('fluxible-immutable-utils').ComponentMixin;\n\nmodule.exports = createReactClass({\n    displayName: 'MyReactComponent',\n    mixins: [ImmutableMixin],\n    getStateOnChange: function () {\n        if (!this.state) {\n            //initialize here if needed\n        }\n        return {\n            someStateProperty: 'foo'\n        };\n    },\n\n    render: function () {\n        return \u003cspan\u003eMy React Component\u003c/span\u003e;\n    }\n});\n\nvar myObject = {\n    foo: 'bar'\n};\n\u003cMyReactComponent\n    someKey={myObject} // fine, because we set this key to be ignored\n    aNonImmutableObject={myObject} // will cause a console.warn statement because we are passing a non-immutable object\n/\u003e\n```\n\n#### Configuring the Mixin\nIf 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.\n\n**Example**\n\n```jsx\n// MyReactComponent.jsx\n\nvar ImmutableMixin = require('fluxible-immutable-utils').ComponentMixin;\n\nmodule.exports = createReactClass({\n    displayName: 'MyReactComponent',\n    mixins: [ImmutableMixin],\n    statics: {\n        ignoreAllWarnings: (process.env.NODE_ENV !== 'dev') // turn off all warnings when not in dev mode\n        ignoreImmutableCheck:  {\n            props: {\n                someKey: true // don't check someKey for immutablility in props\n            },\n            state: {\n                anotherKey: 'SKIP_SHOULD_UPDATE' // don't check anotherKey for immutablility in props, AND don't check its value is shouldComponentUpdate\n            }\n\n        }\n    },\n\n    ...rest of component follows...\n});\n```\n\nIf you want to just pass around a common config, then use:\n```jsx\nvar ImmutableMixin = require('fluxible-immutable-utils').createComponentMixin(myConfig);\n```\nWhere myConfig has the same structure as the statics above.\n\n## `ImmutableStore`\n\nA class to inherit similar to the fluxible addon `BaseStore`. Internally it inherits [`'fluxible/addons/BaseStore`](https://github.com/yahoo/fluxible/blob/master/docs/api/addons/BaseStore.md).\n\nThe main use case for this method is to reduce boilerplate when implementing immutable [`fluxible`](fluxible.io) stores.\n\nThe helper adds a new property and some helper methods to the created store\n* `_state` {[Map](http://facebook.github.io/immutable-js/docs/#/Map)} - The root `Immutable` where all data in the store will be saved.\n\n* `setState(newState, [event], [payload])` {Function} - This method replaces `this._state` with `newState` (unless they were the same) and then calls `this.emit(event, payload)`.\n    * If `event` is *falsy* it will call `this.emitChange(payload)`\n    * The method also ensures that `_state` remains immutable by auto-converting `newState` to an immutable object.\n\n* `mergeState(newState, [event], [payload])` {Function} - This method does a shallow merge with `this._state` and then calls `this.emit(event, payload)`.\n    * If `event` is *falsy* it will call `this.emitChange(payload)`\n    * The method also ensures that `_state` remains immutable by auto-converting `newState` to an immutable object.\n\n* `getState()` {Function} - This method returns the `this._state`.\n\n* `get(key)` {Function} - Get a value by key from the store.\n\nand creates defaults for the following [fluxible store](http://fluxible.io/api/stores.html) methods\n* [`constructor()`](http://fluxible.io/api/stores.html#constructor) - The default implementations creates a `_state` property on the store and initializes it to [`Immutable.Map`](http://facebook.github.io/immutable-js/docs/#/Map)\n\n* [`rehydrate(state)`](http://fluxible.io/api/stores.html#rehydrate-state-) - The default implementation hydrates `_state`\n\n* [`dehydrate()`](http://fluxible.io/api/stores.html#dehydrate-) - The default implementation simply returns `_state` which is `Immutable` (due to all `Immutable` objects implementing a [`toJSON`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#toJSON_behavior) function, `_state` can be directly passed to `JSON.stringify`)\n\n**Note** that all defaults can still be overwritten when creating the store.\n\n**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.\n\n### Example Usage\n\n```js\n// FooStore.js\n\nimport {ImmutableStore} from 'fluxible-immutable-utils';\n\nclass FooStore extends ImmutableStore {\n    // public accessors\n    getBar: function (id) {\n        return this._state.get('bar');\n    }\n\n    // private mutators, these should only be called via dispatch\n    _onNewFoo(data) {\n        // data = { foo: 'Hello', bar: 'World' }            \n        this.setState(data);        \n    }\n\n    _onNewBar(bar) {\n        // This will just update bar and leave foo with the same state\n        this.mergeState({ bar: bar });\n    }\n}\n\nFooStore.storeName = 'FooStore';\n\nFooStore.handlers = {\n    NEW_FOO: '_onNewFooBar',\n    NEW_FOOS: '_onNewBar'  \n};\n\nexport default FooStore;\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyahoo%2Ffluxible-immutable-utils","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyahoo%2Ffluxible-immutable-utils","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyahoo%2Ffluxible-immutable-utils/lists"}