package.json

{
  "name": "immutable",
  "version": "2.0.17",
  "description": "Immutable Data Collections",
  "homepage": "https://github.com/facebook/immutable-js",
  "author": {
    "name": "Lee Byron",
    "url": "https://github.com/leebyron"
  },
  "repository": {
    "type": "git",
    "url": "git://github.com/facebook/immutable-js.git"
  },
  "bugs": {
    "url": "https://github.com/facebook/immutable-js/issues"
  },
  "main": "dist/Immutable.js",
  "scripts": {
    "test": "jest"
  },
  "jest": {
    "scriptPreprocessor": "resources/jestPreprocessor.js",
    "testFileExtensions": [
      "js",
      "ts"
    ],
    "persistModuleRegistryBetweenSpecs": true
  },
  "devDependencies": {
    "grunt": "^0.4.5",
    "grunt-contrib-copy": "^0.5.0",
    "grunt-contrib-jshint": "^0.10.0",
    "grunt-contrib-clean": "^0.5.0",
    "grunt-jest": "^0.1.0",
    "react-tools": "^0.11.1",
    "ts-compiler": "^2.0.0",
    "grunt-release": "^0.7.0",
    "traceur": "0.0.55",
    "smash": "0.0.12",
    "uglify-js": "^2.4.15",
    "jasmine-check": "^0.1.2"
  },
  "engines": {
    "node": ">=0.8.0"
  },
  "files": [
    "dist",
    "README.md",
    "LICENSE",
    "PATENTS"
  ],
  "keywords": [
    "immutable",
    "persistent",
    "lazy",
    "data",
    "datastructure",
    "functional",
    "collection",
    "stateless",
    "sequence",
    "iteration"
  ],
  "license": "BSD",
  "readme": "Immutable Data Collections\n==========================\n\nImmutable data cannot be changed once created, leading to much simpler\napplication development and enabling techniques from functional programming such\nas lazy evaluation. Immutable JS provides a lazy `Sequence`, allowing efficient\nchaining of sequence methods like `map` and `filter` without creating\nintermediate representations.\n\n`immutable` provides `Sequence`, `Range`, `Repeat`, `Map`, `OrderedMap`, `Set`\nand a sparse `Vector` by using lazy sequences and [hash maps tries](http://en.wikipedia.org/wiki/Hash_array_mapped_trie).\nThey achieve efficiency by using structural sharing and minimizing the need to\ncopy or cache data.\n\n\nGetting started\n---------------\n\nInstall `immutable` using npm\n\n```shell\nnpm install immutable\n```\n\nThen require it into any module.\n\n```javascript\nvar Immutable = require('immutable');\nvar map = Immutable.Map({a:1, b:2, c:3});\n```\n\n### Browser\n\nTo use `immutable` from a browser, download [dist/Immutable.min.js](./dist/Immutable.min.js).\n\nThen, add it as a script tag to your page:\n\n```html\n<script src=\"Immutable.min.js\"></script>\n<script>\n    var map = Immutable.Map({a:1, b:2, c:3});\n    map = map.set('b', 20);\n    map.get('b'); // 20\n</script>\n```\n\nOr use an AMD loader (such as [RequireJS](http://requirejs.org/)):\n\n```javascript\nrequire(['./Immutable.min.js'], function (Immutable) {\n    var map = Immutable.Map({a:1, b:2, c:3});\n    map = map.set('b', 20);\n    map.get('b'); // 20\n});\n```\n\n### TypeScript\nUse these Immutable collections and sequences as you would use native\ncollections in your [TypeScript](http://typescriptlang.org) programs while still taking\nadvantage of type generics, error detection, and auto-complete in your IDE.\n\nJust add a reference with a relative path to the type declarations at the top\nof your file.\n\n```javascript\n///<reference path='./node_modules/immutable/dist/Immutable.d.ts'/>\nimport Immutable = require('immutable');\nvar map: Immutable.Map<string, number>;\nmap = Immutable.Map({a:1, b:2, c:3});\nmap = map.set('b', 20);\nmap.get('b'); // 20\n```\n\n\nThe case for Immutability\n-------------------------\n\nMuch of what makes application development difficult is tracking mutation and\nmaintaining state. Developing with immutable data encourages you to think\ndifferently about how data flows through your application.\n\nSubscribing to data events throughout your application, by using\n`Object.observe`, or any other mechanism, creates a huge overhead of\nbook-keeping which can hurt performance, sometimes dramatically, and creates\nopportunities for areas of your application to get out of sync with each other\ndue to simple programmer error. Since immutable data never changes, subscribing\nto changes throughout the model is a dead-end and new data can only ever be\npassed from above.\n\nThis model of data flow aligns well with the architecture of [React](http://facebook.github.io/react/)\nand especially well with an application designed using the ideas of [Flux](http://facebook.github.io/react/docs/flux-overview.html).\n\nWhen data is passed from above rather than being subscribed to, and you're only\ninterested in doing work when something has changed, you can use equality.\n`immutable` always returns itself when a mutation results in an identical\ncollection, allowing for using `===` equality to determine if something\nhas changed.\n\n```javascript\nvar map1 = Immutable.Map({a:1, b:2, c:3});\nvar map2 = map1.set('b', 2);\nassert(map1 === map2);\n```\n\nIf an object is immutable, it can be \"cloned\" simply by making another reference\nto it instead of copying the entire object. Because a reference is much smaller\nthan the object itself, this results in memory savings and a potential boost in\nexecution speed for programs which rely on copies (such as an undo-stack).\n\n```javascript\nvar map1 = Immutable.Map({a:1, b:2, c:3});\nvar clone = map1;\n```\n\n\nJavaScript-first API\n--------------------\n\nWhile `immutable` is inspired by Clojure, Haskell and other functional\nprogramming environments, it's designed to bring these powerful concepts to\nJavaScript, and therefore has an Object-Oriented API that closely mirrors that\nof [Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array),\n[Map](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map), and\n[Set](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set).\n\nThe difference for the immutable collections is that methods which would mutate\nthe collection, like `push`, `set`, `unshift` or `splice` instead return a new\nimmutable collection. Methods which return new arrays like `slice` or `concat`\ninstead return new immutable collections.\n\n```javascript\nvar vect1 = Immutable.Vector(1, 2);\nvar vect2 = vect1.push(3, 4, 5);\nvar vect3 = vect2.unshift(0);\nvar vect4 = vect1.concat(vect2, vect3);\nassert(vect1.length === 2);\nassert(vect2.length === 5);\nassert(vect3.length === 6);\nassert(vect4.length === 13);\nassert(vect4.get(0) === 1);\n```\n\nAlmost all of the methods on `Array` will be found in similar form on\n`Immutable.Vector`, those of `Map` found on `Immutable.Map`, and those of `Set`\nfound on `Immutable.Set`, including sequence operations like `forEach` and `map`.\n\n```javascript\nvar alpha = Immutable.Map({a:1, b:2, c:3, d:4});\nalpha.map((v, k) => k.toUpperCase()).join();\n// 'A,B,C,D'\n```\n\n### Accepts raw JavaScript objects.\n\nDesigned to inter-operate with your existing JavaScript, `immutable`\naccepts plain JavaScript Arrays and Objects anywhere a method expects a\n`Sequence` with no performance penalty.\n\n```javascript\nvar map1 = Immutable.Map({a:1, b:2, c:3, d:4});\nvar map2 = Immutable.Map({c:10, a:20, t:30});\nvar obj = {d:100, o:200, g:300};\nvar map3 = map1.merge(map2, obj);\n// Map { a: 20, b: 2, c: 10, d: 100, t: 30, o: 200, g: 300 }\n```\n\nThis is possible because `immutable` can treat any JavaScript Array or Object\nas a Sequence. You can take advantage of this in order to get sophisticated\nsequence methods on JavaScript Objects, which otherwise have a very sparse\nnative API. Because Sequences evaluate lazily and do not cache intermediate\nresults, these operations are extremely efficient.\n\n```javascript\nvar myObject = {a:1,b:2,c:3};\nSequence(myObject).map(x => x * x).toObject();\n// { a: 1, b: 4, c: 9 }\n```\n\n### Converts back to raw JavaScript objects.\n\nAll `immutable` Sequences can be converted to plain JavaScript Arrays and\nObjects shallowly with `toArray()` and `toObject()` or deeply with `toJS()`.\nAll sequences also implement `toJSON()` allowing them to be passed to\n`JSON.stringify` directly.\n\n```javascript\nvar deep = Immutable.Map({a:1, b:2, c:Immutable.Vector(3,4,5)});\ndeep.toObject() // { a: 1, b: 2, c: Vector [ 3, 4, 5 ] }\ndeep.toArray() // [ 1, 2, Vector [ 3, 4, 5 ] ]\ndeep.toJS() // { a: 1, b: 2, c: [ 3, 4, 5 ] }\nJSON.stringify(deep) // '{\"a\":1,\"b\":2,\"c\":[3,4,5]}'\n```\n\n\nNested Structures\n-----------------\n\nThe collections in `immutable` are intended to be nested, allowing for deep\ntrees of data, similar to JSON.\n\n```javascript\nvar nested = Immutable.fromJS({a:{b:{c:[3,4,5]}}});\n// Map { a: Map { b: Map { c: Vector [ 3, 4, 5 ] } } }\n```\n\nA few power-tools allow for reading and operating on nested data. The\nmost useful are `mergeDeep`, `getIn` and `updateIn`, found on `Vector`, `Map`\nand `OrderedMap`.\n\n```javascript\nvar nested2 = nested.mergeDeep({a:{b:{d:6}}});\n// Map { a: Map { b: Map { c: Vector [ 3, 4, 5 ], d: 6 } } }\n```\n\n```javascript\nnested2.getIn(['a', 'b', 'd']); // 6\n\nvar nested3 = nested2.updateIn(['a', 'b', 'd'], value => value + 1);\n// Map { a: Map { b: Map { c: Vector [ 3, 4, 5 ], d: 7 } } }\n\nvar nested4 = nested3.updateIn(['a', 'b', 'c'], vect => vect.push(6));\n// Map { a: Map { b: Map { c: Vector [ 3, 4, 5, 6 ], d: 7 } } }\n```\n\n\nLazy Sequences\n--------------\n\nThe `Sequence` is a set of (key, value) entries which can be iterated, and\nis the base class for all collections in `immutable`, allowing them to make\nuse of all the Sequence methods (such as `map` and `filter`).\n\n**Sequences are immutable** — Once a sequence is created, it cannot be\nchanged, appended to, rearranged or otherwise modified. Instead, any mutative\nmethod called on a sequence will return a new immutable sequence.\n\n**Sequences are lazy** — Sequences do as little work as necessary to respond\nto any method call.\n\nFor example, the following performs no work, because the resulting sequence is\nnever used:\n\n    var oddSquares = Immutable.Sequence(1,2,3,4,5,6,7,8)\n      .filter(x => x % 2).map(x => x * x);\n\nOnce the sequence is used, it performs only the work necessary. In this\nexample, no intermediate arrays are ever created, filter is only called\ntwice, and map is only called once:\n\n    console.log(oddSquares.last()); // 49\n\nLazy Sequences allow for the efficient chaining of sequence operations, allowing\nfor the expression of logic that can otherwise be very tedious:\n\n    Immutable.Sequence({a:1, b:1, c:1})\n      .flip().map(key => key.toUpperCase()).flip().toObject();\n    // Map { A: 1, B: 1, C: 1 }\n\nAs well as expressing logic that would otherwise seem memory-limited:\n\n    Immutable.Range(1, Infinity)\n      .skip(1000)\n      .map(n => -n)\n      .filter(n => n % 2 === 0)\n      .take(2)\n      .reduce((r, n) => r * n, 1);\n    // 1006008\n\nNote: A sequence is always iterated in the same order, however that order may\nnot always be well defined, as is the case for the `Map`.\n\n\nEquality treats Collections as Data\n-----------------------------------\n\n`immutable` provides equality which treats immutable data structures as\npure data, performing a deep equality check if necessary.\n\n```javascript\nvar map1 = Immutable.Map({a:1, b:1, c:1});\nvar map2 = Immutable.Map({a:1, b:1, c:1});\nassert(map1 !== map2);\nassert(Immutable.is(map1, map2) === true);\n```\n\n`Immutable.is` uses the same measure of equality as [Object.is](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/is)\nincluding if both are immutable sequences and all keys and values are equal\nusing the same measure of equality.\n\n\nCursors\n-------\n\nCursors allow you to hold a reference to a path in a nested immutable data\nstructure, allowing you to pass smaller sections of a larger nested\ncollection to portions of your application while maintaining a central point\naware of changes to the entire data structure: an `onChange` function which is\ncalled whenever a cursor or sub-cursor calls `update`.\n\nThis is particularly useful when used in conjuction with component-based UI\nlibraries like [React](http://facebook.github.io/react/) or to simulate\n\"state\" throughout an application while maintaining a single flow of logic.\n\n\n```javascript\nvar data = Immutable.fromJS({ a: { b: { c: 1 } } });\nvar cursor = data.cursor(['a', 'b', 'c'], newData => {\n  data = newData;\n});\n\n// ... elsewhere ...\n\ncursor.deref(); // 1\ncursor = cursor.update(x => x + 1);\ncursor.deref(); // 2\n\n// ... back to data ...\n\ndata.getIn(['a', 'b', 'c']); // 2\n```\n\n\nBatching Mutations\n------------------\n\n> If a tree falls in the woods, does it make a sound?\n>\n> If a pure function mutates some local data in order to produce an immutable\n> return value, is that ok?\n>\n> — Rich Hickey, Clojure\n\nApplying a mutation to create a new immutable object will result in a performance penalty.\nIf you need to apply a series of mutations, `immutable` gives you the ability to create a\ntemporary mutable copy of a collection and apply a batch of mutations in a highly\nperformant manner by using `withMutations`. In fact, this is exactly how `immutable`\napplies complex mutations itself.\n\nAs an example, this results in the creation of 2, not 4, new immutable Vectors.\n\n```javascript\nvar vect1 = Immutable.Vector(1,2,3);\nvar vect2 = vect1.withMutations(function (vect) {\n  vect.push(4).push(5).push(6);\n});\nassert(vect1.length === 3);\nassert(vect2.length === 6);\n```\n\nNote: `immutable` also provides `asMutable` and `asImmutable`, but only\nencourages their use when `withMutations` will not suffice.\n\n\nAPI Documentation\n-----------------\n\nAll documentation is contained within the type definition file, [Immutable.d.ts](./type-definitions/Immutable.d.ts).\n\n\nContribution\n------------\n\nUse [Github issues](https://github.com/facebook/immutable-js/issues) for requests.\n\nWe actively welcome pull requests, learn how to [contribute](./CONTRIBUTING.md).\n\n\nThanks\n------\n\n[Hugh Jackson](https://github.com/hughfdjackson/), for providing the npm package\nname. If you're looking for his unsupported package, see [v1.4.1](https://www.npmjs.org/package/immutable/1.4.1).\n\n\nLicense\n-------\n\n`immutable` is [BSD-licensed](./LICENSE). We also provide an additional [patent grant](./PATENTS).\n",
  "readmeFilename": "README.md",
  "_id": "immutable@2.0.17",
  "dist": {
    "shasum": "8340af44155e61ea0acd4a0d696b4ef861c0516a"
  },
  "_from": "immutable@~2.0.17",
  "_resolved": "https://registry.npmjs.org/immutable/-/immutable-2.0.17.tgz"
}