How are people implementing immutable data structures in JavaScript when the language doesn't offer any obvious way of implementing immutability?

Although JavaScript lacks immutable built-in data structures, immutable state is still possible.

As you know, variables store a program's state. Functional languages like Lisp usually change program state by taking the current state as input and returning the new updated state as output (which is used as input for another function; repeat).

JavaScript programs usually change program state by mutating variables, but the method used by Lisp described above can also be used. Instead of writing functions that mutate variables, simply write functions that input the current state and return a new output state without modifying any of the inputs.

You may run into some drawbacks when programming in an immutable style in JavaScript:

• JavaScript is optimized for mutation, not immutability. So there may be a memory/performance penalty. The immutable paradigm prefers generating new values over mutating existing values. (On the other hand Lisp-like languages are optimized for a bias towards immutability over mutation.)
• Mutation may "leak" into your program if you use any of the many JavaScript primitives that mutate data (like Array.sort()).

Libraries that assist in using the immutable paradigm in JS

Immer

Immer is a JS library that helps use immutable state in JS:

The basic idea is that you will apply all your changes to a temporary draftState, which is a proxy of the currentState. Once all your mutations are completed, Immer will produce the nextState based on the mutations to the draft state. This means that you can interact with your data by simply modifying it while keeping all the benefits of immutable data.

Immutable.js

Immutable.js is another JS library that helps implement immutable state in JS:

Immutable.js provides many Persistent Immutable data structures including: List, Stack, Map, OrderedMap, Set, OrderedSet and Record.

These data structures are highly efficient on modern JavaScript VMs by using structural sharing via hash maps tries and vector tries as popularized by Clojure and Scala, minimizing the need to copy or cache data.

Mori

Mori extracts ClojureScript's optimized immutable data structures so you can use them in vanilla JS. (ClojureScript is a Lisp that compiles to JavaScript.)

List of JavaScript immutable libraries

This list of immutable libraries is divided into two main categories:

• Persistent Data Structures w/structural sharing
• Immutable helpers (simply shallow copy JS objects)

An even longer list of resources for functional programming in JavaScript

https://project-awesome.org/stoeffel/awesome-fp-js

Finally, ProseMirror is good real-world example of immutable state in JavaScript:

ProseMirror is an editor written in JavaScript that uses a persistent data structure to store the document data.

• Note this data structure is immutable by convention. The developer must ensure the data structure is not mutated. It is possible to mutate the data structure, but the results are undefined and most likely undesired. So ProseMirror provides documentation and functions to support immutability.
• It would be possible to enforce immutability of this data structure using Object.freeze(), but this is generally avoided because it incurs a huge performance penalty.
• Also note immutability is not "all or nothing." The main data structure is immutable, but mutable variables are used where they make more sense (like loop variables.)

One idea (of many) may be to wrap objects in a Proxy. Something like the snippet:

See also...

function createObject(someObject) {
  const localScores = {value: {history: [], current: []}, writable: true};
  const proxyHandler = {
    get: (target, prop) => {
      if (!(prop in target)) {
        console.log(`'${prop}' is a non existing property`);
        return null;
      }
      return target[prop].value;
    },
    set: (obj, prop, value) => {
      if (obj[prop] && obj[prop].writable) {
        obj[prop].value = value;
        return value;
      }
      console.log(`'${prop}' is not writable, sorry`);
    },
  };  
  return new Proxy(
    {...someObject, ...{ local: localScores } }, 
    proxyHandler
  );
}
const obj = createObject({
  prop1: {value: 'some string 1', writable: false}, 
  prop2: {value: '', writable: true}, 
  prop3: {value: 42, writable: false},
});

obj.nothing;
obj.prop1 = 'no dice';
obj.prop2 = 'apples & bananas!';
obj.local = { 
  history: [...obj.local.history, obj.local.current], 
  current: [...obj.local.current, ...[1,2,3]] };
obj.local = { 
  history: [...obj.local.history, obj.local.current], 
  current: [...obj.local.current, obj.prop3] };
obj.local = { 
  history: [...obj.local.history, obj.local.current], 
  current: [...obj.local.current, ...[123, 321]] };
console.log(`obj.prop1: ${obj.prop1}`);
console.log(`obj.prop2 has a new value: ${obj.prop2}`);
console.log(`obj.local: ${JSON.stringify(obj.local)}`);

JavaScript doesn't really have a way of implementing Immutable data, at least not a way that is obvious.

You might be new to JS, but the obvious way to make an object immutable is to freeze it:

const obj = Object.freeze({
  prop_2() { return this.prop_3 }
  prop_3: '',
});

obj.prop_3 = 'apples & bananas'; // throws as expected
console.log(obj.prop_3);

If objects are immutable, we need to create new ones with the new values that we want instead of assigning to their properties. Spread property syntax in object literals helps us to achieve this, as do helper methods:

const base = {
  withProp(newVal) {
    return { withProp: this.withProp, prop: newVal };
  },
  prop: '';
};

const obj1 = base.withProp('apples & bananas');
console.log(obj1.prop);
const obj2 = {...base, prop: obj1.prop + ' & oranges'};
console.log(obj2.prop);

With enough self-restraint (or drill, or code reviews, or tooling like typecheckers and linters), this programming style of cloning objects becomes natural, and you won't make mistakes with accidental assignments any more.

Of course, doing this with more complicated (nested) structures is cumbersome, so there exist quite some libraries that provide helper functions, and there are also implementations of more advanced purely functional data structures available that are more efficient than cloning your whole data every time.

Welcome to Functional Programming!

One solution is using ES6 class. getter returns property's deep copy, setter throws error.

Example Code:

class Person {
  _name = "";
  constructor(name) {
    this._name = name;
  }

  get name() {
    return this.name;
  }

  set name(name) {
    throw new Error("Can't reassign a Person's name");
  }
}

class ImmutableArray {
  _arr = [];
  constructor(arr) {
    this._arr = [...arr];
  }
  get arr() {
    return [...this._arr];
  }
  set arr(arr) {
    throw new Error("Can't reassign a ImmutableArray");
  }
}

const aPerson = new Person("jiho");
aPerson.name = "W3Dojo"; // Error: Can't reassign a Person's name

const aImmutableArray = new ImmutableArray([1, 2, 3]);
aImmutableArray.arr = [2]; // Error: Can't reassign a ImmutableArray

const arr = aImmutableArray.arr;
arr[2] = 20;
console.log(aImmutableArray.arr[2]); // 3

In this methodology, a property inside class is immutable.

Learn More

Private class fields in MDN, but it's on Stage 3.