TimeTraveler

TimeTraveler is a library to management of state. It becomes useful in scenarios that is necessary compose object (state) based on a sequence of steps (timeline).

Think in on behavior of your browser when you navigate between pages, it makes available to you go back and forward or jump to an specific page if you press and hold the button of Prev or Next. This concept of time traveling is the major feature of TimeTraveler but you can do more.

Demo: https://belchior.github.io/time-traveler/

Installation

Run the command to install

npm i @belchior/time-traveler

Import

// Default / TypeScript
import TimeTraveler from '@belchior/time-traveler';

// Node ECMAScript module
import TimeTraveler from '@belchior/time-traveler/lib/mjs';

// Node CommonJS
const TimeTraveler = require('@belchior/time-traveler/lib/cjs');

API

Class methods

constructor(timeline, initialState)

timeline required - A list of functions that will be used to produce new states

initialState optional - If passed will be the first state produced by TimeTraveler, otherwise the initialState will be produced by the execution of the first function into timeline

Returns a new instance of TimeTraveler

Usage

const timeline = [/* ... */];
const tt = new TimeTraveler(timeline);

create(timeline, initialState)

recommended Alias to constructor method. The lines above are equivalents

const tt = TimeTraveler.create(timeline);

const tt = new TimeTraveler(timeline);

Instance methods

add(fn) - return this

fn required - Function that will produce state

Adds fn at the end of the timeline

Usage

const timeline = [/* ... */];
const finalStep = state => {/* ... */};
const tt = TimeTraveler.create(timeline);
const tt.add(finalStep);

getState() - return current state

Return the current state produced by timeline

Usage

const timeline = [/* ... */];
const tt = TimeTraveler.create(timeline);
const currentState = tt.getState(); // the initial state

goTo(fn) - return this

fn required - Function belonging to timeline

Set the current state traveling the timeline in both direction or jumping to some point in "time". In case the received function have already been called the state will be taken from the cache, otherwise will be produced calling the received fn.

Note that the sequence matters, if goTo is used in a way that don't follow the timeline the methods next() and prev() will try to follow the timeline created by goTo and then get possibles states from the timeline. Try the demo to get more insides.

Usage

const initialState = () => {/* ... */}
const stepA = () => {/* ... */}
const timeline = [initialState, stepA];
const tt = TimeTraveler.create(timeline);

tt.goTo(stepA); // the current state is stepA
tt.goTo(initialState); // the current state is initialState

next() - return this

Set the current state traveling the timeline to the future.

Usage

const initialState = () => {/* ... */}
const stepA = () => {/* ... */}
const timeline = [initialState, stepA];
const tt = TimeTraveler.create(timeline);

tt.next(); // the current state is stepA

prev() - return this

Set the current state traveling the timeline to the past.

Usage

const initialState = () => {/* ... */}
const stepA = () => {/* ... */}
const timeline = [initialState, stepA];
const tt = TimeTraveler.create(timeline);

tt.next(); // the current state is stepA
tt.prev(); // the current state is initialState

reset() - return this

Clear the states produced by goTo(fn) and next(). Define the current state as the same produced by initialState

Usage

const initialState = () => {/* ... */}
const stepA = () => {/* ... */}
const stepB = () => {/* ... */}
const timeline = [initialState, stepA, stepB];
const tt = TimeTraveler.create(timeline);

tt.next().next(); // the current state is stepB
tt.reset(); // the stepA and stepB was removed and the current state is initialState

How to use

import TimeTraveler from '@belchior/time-traveler';

const initialState = () => ({ stepA: '', stepB: '', });
const stepA = state => ({ ...state, stepA: 'done', });
const stepB = state => ({ ...state, stepB: 'done', });
const timeline = [ initialState, stepA, stepB, ];

const tt = TimeTraveler.create(timeline);

console.log('initialState:', tt.getState());
tt.next();             console.log('next (stepA)', tt.getState());
tt.next();             console.log('next (stepB)', tt.getState());
tt.prev();             console.log('prev (stepA)', tt.getState());
tt.goTo(initialState); console.log('goTo (initialState):', tt.getState());
tt.goTo(stepB);        console.log('goTo (stepB):', tt.getState());