export const initialState: ExampleState = {
  model2: 'test',
  levelOne: {levelTwo: {nestedOne: {nestedTwo: ['a'], someData: 'b'}, someData: 'c'}, otherData: 'd'}
};

const exampleReducer = createReducer(initialState,
// 👇 Clone each level of object with spread operator                                    
  on(exampleAction, (state, {value}) => ({
    ...state, levelOne: {
      ...state.levelOne,
      levelTwo: {
        ...state.levelOne.levelTwo,
        nestedOne: {
          ...state.levelOne.levelTwo.nestedOne,
          nestedTwo: [...state.levelOne.levelTwo.nestedOne.nestedTwo, value]
        }
      }
    }
  })),
// 👇 Nornal JS mutation, Immer ensure the immutability on each level with produce function
  on(exampleAction, (state, {value}) =>
    produce(state, draft => {
      draft.levelOne.levelTwo.nestedOne.nestedTwo.push(value);
    })
  )
);

This code snippet shows what kind of problem Immer solves, reduces boilerplate with a simple JS API

export interface Feature1State {
  books: Book[];
}

export const initialState: Feature1State = {
  books: []
};

// Return type of the on fn. Contains the action reducer coupled to one or more action types.
const feature1Reducer = createReducer(
  initialState,
  on(getBooksSuccess, (state, { books }) =>
    // 👇 Produce is Immer's function to manage change in an immutable way
     produce(state, draft => {
      draft.model1 = books; // ERROR TS2551: Property 'model1' does not exist on type 'WritableDraft '.
    })
  ),
  on(getBooksSuccess, (state, { books }) => ({
    ...state,
    model1: books // no error => at runtime will create a model1 inside the Feature1State.
  })),
  on(getBooksSuccess,
    (state, { books }): Feature1State => ({
      ...state,
      model1: books // we got the Error only when specifing the return type on each reducer function
    })
  )
);

I'm going to spend some time talking about different ways to clone an object, what technique is used by Immer, and how it works under the hood. If you're only interested in how to use it with NgRx reducers, jump straight to the last section of the article.

What is Immer and how does it work?

produce(originalObject, recipe: (draft) => void): clonedObject

• recipe is a function, that takes a draft object that can be safely mutated, since draft is proxy object for the original one (using draft as a name is just a convention to signal "mutation is OK here")

Shallow-copy, deep-copy and structural-sharing

• shallow copy (shallow cloning) copies only one level of an object preserving the references to nested objects, hence if you mutate the property that points to a nested object, the cloned object will reflect the changes. Shallow copy can be performed with Object.assign or spread (...) operator.
• deep copy (deep cloning) can be achieved with a recursive algorithm that clones every property of the object, even if these properties won't need to be changed. For nested objects it creates new objects in memory with new references. This is, for example, what the cloneDeep function from Lodash library does. The deep clone is very expensive and is not really recommended for a general use.
• structural sharing is different from deep cloning because with this technique only the changed part of the data structure will be cloned (regardless of the nesting level). When we assign a new value to a property, the process known as copy-on-write takes place. When a property changes, all its parents will also be shallowly cloned, but the unmodified nested object will keep the original reference. For this reason it is common to freeze the entire data structure to make sure it doesn't break the immutability contract (a direct mutation of the object is forbidden).

Going deep into the Immer world

const target = {
  message1: "hello",
  message2: "everyone"
};

const traps = {
  get: function(target, prop, receiver) {
     if(Object.prototype.hasOwnProperty.call(target, prop)){
         return "property exist, hello! from proxy";
     }
    return undefined;
  }
};

const {proxy, revoke} = Proxy.revocable(target, traps);
console.log(proxy.message2) // "property exist, hello! from proxy"
console.log(proxy.message3) // undefined
revoke();
console.log(proxy.message2) // Cannot perform 'get' on a proxy that has been revoked 

this code snippet shows how a proxy object works

1. At the start create a Proxy root
2. Lazily create proxy when a field is dereferenced
3. Upon write, create shallow clone
4. Upon finish, combine clones, freeze the objects

export function createProxyProxy<T extends Objectish>(
	base: T,
	parent?: ImmerState
): Drafted<T, ProxyState> {
	const isArray = Array.isArray(base)
	const state: ProxyState = {
		type_: isArray ? ProxyType.ProxyArray : (ProxyType.ProxyObject as any),
		// Track which produce call this is associated with.
		scope_: parent ? parent.scope_ : getCurrentScope()!,
		// True for both shallow and deep changes.
		modified_: false,
		// Used during finalization.
		finalized_: false,
	  	// Track which properties have been assigned (true) or deleted (false).
		assigned_: {},
		// The parent draft state.
		parent_: parent,
		// The base state.
		base_: base,
		// The base proxy.
		draft_: null as any, // set below
		// The base copy with any updated values.
		copy_: null,
		// Called by the `produce` function.
		revoke_: null as any,
		isManual_: false
	}
	
	let target: T = state as any
	let traps: ProxyHandler<object | Array<any>> = objectTraps
	...
	const {revoke, proxy} = Proxy.revocable(target, traps)
	state.draft_ = proxy as any
	state.revoke_ = revoke
	return proxy as any
}

this code snippet extracted from the library shows what kind of information is stored by Immer and how the porxy is instantiated

// summary of the "get" trap
function readProperty(base, prop) {
    const draftState = findOrCreateDraftState(base)
    const value = draftState.modified
        ? draftState.copy[prop]
        : base[prop]
    if (isProxyable(value))
        return getOrCreateProxy(value)
    return value
}

// summary of the "set" trap
function setProperty(base, prop, value) {
    const draftState = findOrCreateDraftState(base)
    if (!draftState.modified) {
        draftState.modified = true
        draftState.copy = {...base}
        markParentsChanged(draftState)
    }
    draftState.copy[prop] = value
}

This code summarizes the logic contained in the 'get' and 'set' trap functions of the ProxyAuto freezeImmer performance

Something that isn't reflected in the numbers above, but in reality, Immer is sometimes significantly faster than a hand written reducer. The reason for that is that Immer will detect "no-op" state changes, and return the original state if nothing actually changed. Cases are known where simply applying Immer solved critical performance issues.

NgRx-Immer

NgRx-immer API for NgRx-Store:

// <------ createImmerReducer ------>
const todoReducer = createImmerReducer(
	{ todos: [] },
	on(completeTodo, (state, action) => {
		state.todos[action.index].completed = true;
		return state;
	}),
);

// <------ immerOn ------>
const todoReducer = createReducer(
	{ todos: [] },
	on(newTodo, (state, action) => {
		return {
			...state,
			todos: [...state.todos, action.todo],
		};
	}),
	immerOn(completeTodo, (state, action) => {
		state.todos[action.index].completed = true;
	}),
);

NgRx-immer API for NgRx-Store

NgRx-immer API for NgRx-Component-Store

import { ImmerComponentStore } from 'ngrx-immer/component-store';

@Injectable()
export class MoviesStore extends ImmerComponentStore<MoviesState> {
	constructor() {
		super({ movies: [] });
	}

	readonly addMovie = this.updater((state, movie: Movie) => {
		state.movies.push(movie);
	});
}

NgRx-immer API for NgRx-Component-StoreConclusion: Is it worth using Immer?