state-history

A basic state history manager.

Install

npm i state-history

Basic usage

import { StateHistory } from 'state-history';
// or
const { StateHistory } = require('state-history');

// create history
const history = new StateHistory();

// push some states
history.push({ a: 1 });
history.push({ a: 2 });
history.push({ a: 3 }); // current history is { a: 3 }

history.goPrev(); // current history is now { a: 2 }
history.goNext(); // current history is now { a: 3 }
history.go(-2); // current history is now { a: 1 }

// listen to history changes
history.subscribe(newState => console.log(newState));
history.push({ a: 1 }); // triggers an history change
history.goPrev(); // also triggers an history change

Properties

// number of past states in the history
// it should be checked to be greater than 0 before calling `goPrev`
numPrev: number;

// number of future states in the history
// it should be checked to be greater than 0 before calling `goNext`
numNext: number;

Methods

// push a new entry onto the history stack
// and returns it
push(state: T): T;

// moves the pointer in the history stack to the previous entry
// and returns the new current state
// it is equivalent to `go(-1)`
goPrev(): T;

// moves the pointer in the history stack to the next entry
// and returns the new current state
// it is equivalent to `go(1)`
goNext(): T;

// moves the pointer in the history stack to the last entry
// and returns the new current state
// it is  equivalent to `go(numNext)`
goLast(): T;

// moves the pointer in the history stack by `i` entries
// a negative number will go to the `-i`th previous entry
// and a positive number will go to the `i`th next entry
go(i: number): T;

// get a specific entry from the history stack
// ie: `-1` for the previous entry, `1` for the next entry
get(i: number): T;

// register a callback function that will be called every time
// a new entry is added or when the pointer in the history stack is moved
subscribe(callback: (state: T) => void): void;

// unregister a callback function
unsubscribe(callback: (state: T) => void): void;

// unregister all callback functions
unsubscribeAll(): void;

// remove all entries from the state history
clear(): void