A persistent data structure is immutable at the data-structure level: updating it creates a new version while preserving every previous version. This closes a safety gap left by ordinary immutable helper functions, where a developer can still accidentally mutate shared native data. section 9.0 section 9.2
When sharing stops being safe
A books map is copied into nextBooks with an immutable update to the publication year. Later, native assignment changes the shared authorIds array in books; nextBooks then reports the changed author name too. Persistent data structures prevent this kind of accidental mutation by exposing non-mutating operations instead of native setters. section 4.4
Persistent data structures address the two weaknesses of naive structural sharing:
- Safety: mutation methods are unavailable or raise an exception; JavaScript implementations expose their own access and update API. section 9.2
- Efficiency: versions share internal structure rather than copying an entire collection, so updates remain practical for very large collections. section 9.2 section 9.5
- History: modifying a collection never destroys its earlier version, making multiple versions safe to retain and compare. section 9.2
The implementation is not simply a frozen native collection. Persistent structures organize data to share unchanged branches internally. A linked list can add a new head that points to the old list; larger structures use branching trees so update cost depends chiefly on tree depth rather than total collection size. section 9.2 section 9.5
Integration depends on the language. Paguro collections implement the read-only portions of Java collection interfaces, support iteration and streams, and create versions with replace() or assoc(). Immutable.js uses its own API: fromJS() converts nested native data, get() and getIn() read it, set() and setIn() create versions, and toJS() converts it back. section 9.3.1 section 9.3.2
Persistent structural diff
A structural diff can recursively compare two Immutable.js values, reuse persistent collection operations, and return only changed fields. Comparing two nested values identifies changes to y.z and w while omitting equal data. section 9.4.4
Visualizes how a new list version shares unchanged structure with its predecessor. section 9.2
Listing 9.9 Conversion to immutable data
var libraryData = Immutable.fromJS({
"catalog": {
"booksByIsbn": {
"978-1779501127": {
"isbn": "978-1779501127",
"title": "Watchmen",
"publicationYear": 1987,
"authorIds": ["alan-moore",
"dave-gibbons"]
}
},
"authorsById": {
"alan-moore": {
"name": "Alan Moore",
"bookIsbns": ["978-1779501127"]
},
"dave-gibbons": {
"name": "Dave Gibbons",
"bookIsbns": ["978-1779501127"]
}
}
}
});
Shows recursive conversion of a nested JavaScript object into persistent Immutable.js data. section 9.3.2
