ngrx-wieder

 

ngrx-wieder is a lightweight yet configurable solution for implementing undo-redo in Angular apps on top of NgRx.
It's based on immer hence the name wieder (German for: again)

⚡ Example (Demo)

Prerequisites

Make sure you're using immer to update your NgRx (sub-)state. That means you're using mutating APIs to update the state while immer provides a new state behind the scenes. If you're just starting out, install immer with this command:

``bash
npm i immer
`

Installation

Install this library with the following command:

`bash
npm i ngrx-wieder
`

Usage

Firstly, extend the UndoRedoState with your custom state definition. This will prepare state properties for containing the undo-redo history. You can spread initialUndoRedoState into your initial state to initialze these properties:

`typescript
// todo.state.ts
import { UndoRedoState, initialUndoRedoState } from "ngrx-wieder";

export interface State extends UndoRedoState {
todos: Todo[];
}

export const initialState: State = {
todos: [],
...initialUndoRedoState,
};
`

Then, you'll initialize ngrx-wieder and optionally pass a custom config. It'll return an object with the function createUndoRedoReducer which you can use just like createReducer from NgRx, however, state inside on will be a immer draft of the last state. If you'd rather not return the state in each on-reducer, you can use produceOn instead.

Tip: Inside on or produceOn you can access the original state of an immer.js draft, therefore the last state, with the original function.

`ts
// todo.reducer.ts
import { undoRedo, produceOn } from "ngrx-wieder";

// initialize ngrx-wieder with custom config
const { createUndoRedoReducer } = undoRedo({
allowedActionTypes: [Actions.addTodo, Actions.removeTodo, Actions.toggleTodo],
});

export const reducer = createUndoRedoReducer(
initialState,
on(Actions.addTodo, (state, { text }) => {
state.todos.push({ id: nextId(), text, checked: false });
return state;
}),
on(Actions.toggleTodo, (state, { id }) => {
const todo = state.todos.find((t) => t.id === id);
todo.checked = !todo.checked;
return state;
}),
produceOn(Actions.removeTodo, (state, { id }) => {
state.todos.splice(
state.todos.findIndex((t) => t.id === id),
1
);
})
);
`

Then whenever you'd like to undo or redo one of the passed allowedActionTypes simply dispatch
the corresponding actions:

`ts
this.store.dispatch({ type: "UNDO" });
this.store.dispatch({ type: "REDO" });
`

$3

| Option | Default | Description |
| :--------------------- | :------------------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| allowedActionTypes | [] | Actions applicable for being undone/redone (leave empty to allow all actions) |
| mergeActionTypes | [] | Types of actions whose state difference should be merged when they appear consecutively |
| mergeRules | {} | Predicate dictionary for deciding whether differences from consecutive actions of the same type should be merged. Use action type as key and predicate as value. |
| maxBufferSize | 32 | How many state differences should be buffered in either direction |
| undoActionType | 'UNDO' | Override for the undo action's type |
| redoActionType | 'REDO' | Override for the redo action's type |
| breakMergeActionType | 'BREAK_MERGE' | Override for the break-merge action's type. |
| clearActionType | 'CLEAR' | Override for the clear action's type |
| trackActionPayload | false | Whether the action payloads should be kept in the history |
| segmentationOverride | (action: Action) => undefined | Override for active segmentation based on key resolved from action |

$3

You can access the undo-redo history through the included selectors after passing a selector that leads to your corresponding state feature to the createHistorySelectors factory function (you can also pass a segmenter as a second parameter):

`typescript
// todo.selectors.ts
import { createHistorySelectors } from "ngrx-wieder";

// in this example the whole state is undoable
// otherwise return feature state
const selectFeature = (state: State) => state;
export const {
selectHistory,
selectCanUndo,
selectCanRedo,
} = createHistorySelectors(selectFeature);
`

The generated selectors could be used like this:

`typescript
import * as fromTodo from "../todo.selectors";

@Component({
selector: "my-undo-redo",
template:
Undo
Redo
,
})
export class UndoRedoComponent {
canUndo$ = this.store.select(fromTodo.selectCanUndo());
canRedo$ = this.store.select(fromTodo.selectCanRedo());

constructor(private store: Store) {}
}
`

If you're using segmentation, you can override the history key by passing an object with a key property to the selector factory functions.

$3

Sometimes you want to enable undo/redo in broader chunks than the ones you actually use for
transforming your state. Take a range input for example:

`ts
@Component({
selector: 'my-slider',
template:
(change)="rangeChange()" (input)="rangeInput(rangeIn.value)">

})
export class SliderComponent {

// ...

rangeChange() {
this.store.dispatch({ type: 'BREAK_MERGE' })
}

rangeInput(count: number) {
this.store.dispatch(new CountChange({ count })
}
}
`

The method rangeInput will be called for any step that the slider is moved by the user. This method
may also dispatch an action to update the state and thus display the result of moving the slider.
When the user now wants to revert changing the range input, he'd have to retrace every single step that
he moved the slider. Instead a more expectable redo behaviour would place the slider back where the
user picked it up before.

To facilitate this you can specify the CountChange action as an action
whose state changes are merged consecutively by passing its type to the configuration property
mergeActionTypes (you can even get more fine grained by using predicates through the mergeRules property).

In order to break the merging at some point you can dispatch a special action of type BREAK_MERGE.
A good place to do this for the range input would be inside the change input - which is called when the user drops the range knob (this is also covered in the example).

$3

You can clear the stack for undoable and redoable actions by dispatching a special clearing action:

`ts
this.store.dispatch({ type: "CLEAR" });
`

$3

ngrx-wieder works by recording patches from immer and applying them based on dispatch of actions for perfoming undo and redo. While createUndoRedoReducer handles interaction with immer, this is not possible when you're using a reducer that is based on a switch-statement. In that case the reducer on which you want to apply the undo-redo feature has to update the NgRx state directly through immer. In order to let ngrx-wieder record the changes your reducer has to be adapted so that it can forward the patches from immer:

Before

`ts
import { produce } from "immer";

const reducer = (state: State, action: Actions): State =>
produce(state, (nextState) => {
switch (
action.type
/ action handling /
) {
}
});
`

After

`ts
import { produce, PatchListener } from "immer";

const reducer = (
state: State,
action: Actions,
patchListener?: PatchListener
): State =>
produce(
state,
(nextState) => {
switch (
action.type
/ action handling /
) {
}
},
patchListener
);
`

Next you'll configure the undo-redo behaviour by instantiating undoRedo and wrapping
your custom reducer with the wrapReducer function:

`ts
import { undoRedo } from "ngrx-wieder";

// initialize ngrx-wieder
const { wrapReducer } = undoRedo({
allowedActionTypes: [Actions.addTodo, Actions.removeTodo, Actions.toggleTodo],
});

// wrap reducer inside meta-reducer to make it undoable
const undoableReducer = wrapReducer(reducer);

// wrap into exported function to keep Angular AOT working
export function myReducer(state = initialState, action) {
return undoableReducer(state, action);
}
`

$3

Segmentation provides distinct undo-redo stacks for multiple instances of the same kind of state. For example, this allows you to implement an application that can have multiple documents open at the same time in multiple tabs as illustrated by this state:

`typescript
interface State {
activeDocument: string;
documents: { [id: string]: Document };
canUndo: boolean;
canRedo: boolean;
}
`

Now, when the user is viewing one document, he probably doesn't want to undo changes in a different one. In order to make this work, you need to inform ngrx-wieder about your segmentation by using createSegmentedUndoRedoReducer providing a segmenter. Note that any actions that change the result of the segmenter must not be undoable (here it's documentSwitch). Moreover, when tracking is active, canUndo and canRedo will reflect the active undo-redo stack.

`typescript
// helper function for manipulating active document in reducer
const activeDocument = (state: TestState): Document =>
state.documents[state.activeDocument];

const { createSegmentedUndoRedoReducer } = undoRedo({
allowedActionTypes: [nameChange.type],
track: true,
});

const reducer = createSegmentedUndoRedoReducer(
initialState,
(state) => state.activeDocument, // segmenter identifying undo-redo stack
produceOn(nameChange, (state, action) => {
activeDocument(state).name = action.name;
}),
produceOn(documentSwitch, (state, action) => {
state.activeDocument = action.document;
})
);
`

When you're using a switch-based reducer, simply pass the segmenter as a second argument to wrapReducer:

`typescript
const {wrapReducer} = undoRedo({...})
const reducer = (state = initialState, action: Actions, listener?: PatchListener): State =>
produce(state, next => {
switch (action.type) {
case nameChange.type:
activeDocument(next).name = action.name
return
case documentSwitch.type:
next.activeDocument = action.document
return
}
}, listener)
return wrapReducer(reducer, state => state.activeDocument)
`

You can override the segmentation based on an action by providing segmentationOverride to the config. This way you can target a specific - possibly non-active - segment with actions. For example, the actions from above could contain an optional property targetDocument which you'd resolve with the following segmentationOverride:

`typescript
const {createSegmentedUndoRedoReducer} = undoRedo({
...
segmentationOverride: action => action.targetDocument
})
``