@CodeOMat HistoryCache

VERSION 0.0.1x Alpha: March 3, 2018

HistoryCache is a wrapper for Immutable Map that functions like a version repository for local data..

HistoryCache is not intended for nested maps, but it is useful for storing properties where the history of properties will be needed later.

Basic Usage and data access.

Creation

    import HistoryCache from 'history-cache';

    var defaultData = { 
      name: 'Robert LaMarca',
      age: 103,
      birthplace: 'Croatia',
      voice: 'Flat',
      eyes: 'sensitive',
      [FEELING]: 'groovy'
    };

    const cache = new HistoryCache(defaultData);

Accessors

• get(key, default): Just like Map.get, retrieves a value at key.

• getFrom(key, versionSearchTerm, default): Like get, but will look for the value from a previous data version. (See the section on versionSearching)

• set(key, value): calls Map.set, but stores the original Map in the HistoryCache and advances the version. every time you set any item, the history cache advances one. This is like calling commit automatically with a git repo.

• merge(newData): calls Map.merge. NewData can be either a Map or a standard JavaScript object;

• index(): returns the index that will be assigned to the next version. Since this is a simple index starting at 0, index is also the number of versions available.

Settings:

• limit(limitValue = -1): Sets the limit for how many versions you wish to store in the history. If no value passed in returns the current setting. Default has no limit.

Accessor Examples.

    const name = cache.get('name', 'default'); //Robert LaMarca

    const sunSign = cache.get('sign', 'default'); // default because there is no such data.

    cache.index(); // 1; .. the index of the version when something is set next.

    cache.set('name', 'Grace Hopper'); // returns the cache instance.
    cache.set('age', 33.33333).set('voice');
    cache.get('age', 'default'); // Grace Hopper


    cache.index(); // 2 because now there are two entries, 0 and 1.

    const originalData = cache.version(0); // Immutable Map from the original
    originalData.get('age'); // 103

    // Get data from a particular version.
    cache.getFrom('age', 0, 'default'); // 103;
    cache.getFrom('age'); // 33.33333

Versioning.

The commands set and checkout create new versions: In either case, the following data is added to the history for the current state:

• Date: The exact date and time this version was put to history.
• data: The Immutable map of the data of this version.
• UID: A unique identfier for this version. ( created with uuid/v4 );
• event: A description of what triggered the new version. For example, setting name would create an event name of: 'set name = Edith Bunker';
• comment: not used yet.
• tag: A note of the tag for this version.

There are three ways to access old versions of the data:

• getFromCommand: Gets a data item from a particular version.
• version: returns an Immutable Map from a particular version.
• checkout: gets an earlier version and makes it the current one. This adds the current one to the history as if a set command were called.

Versions can be searched by the following methods: All the above commands use the same search terms when accessing versions.

• index: This is the simplest and fastest. Simply use the index of the version. Indices of versions start at 0 for the initial data and advance from there by ones.

• UID: Access the version by its UID number. (see the logging section for how to access the UID)

• Event: Access the version by its Event name. (event names can be accessed by logging or by inferring from the commands that were used to create a version)

• Tag: Access the version by a tag.

Tagging:

Tagging is similar to git tagging. Simply use the tag command to add a comment that will be associated with the next set of checkout run. This comment can later be used to find the version.

Examples

    cache.index(); // 3 
    cache.set('birthplace', 'Joplin');
    cache.index(); // 4 

    cache.version(3); // gets the Map created when birthplace was set.

    cache.tag('usetofind');
    cache.set('voice', 'alto');

    cache.index(5);
    cache.set('voice', 'sweet');
    cache.get('voice'); // sweet;
    cache.getFrom('voice', 4); // alto;
    cache.getFrom('voice', 'usetofind'); // alto.

    const cacheData4 = cache.version(4);
    cacheData4.get('voice'); // alto;

    const cacheData4too = cache.version('usetofind');
    cacheData4too.get('voice'); // alto;

    cache.checkout(4);

    cache.index(); // 6;
    cache.get('voice'); // alto;
    cache.getFrom('voice', 5); // sweet;

    cache.checkout(5);
    cache.index(); // 7;
    cache.get('voice'); // sweet;

    cache.checkout('usetofind');
    cache.index(8);
    cache.get('voice'); // alto;

Logs

HistoryCache provides access to logging meta data. Logging has its own API which can be used select the form in which this meta data is returned.

Each version in the HistoryCache has a meta data item in the log. This item contains the following:

• Date
• Comment
• Event
• Tag ( if available )
• UID

Log meta data can be returned in the following forms:

• Immutable List:

    cache.log().log();// returns Immutable List;
    cache.log().list(); // so does this;
    cache.log().$(); // and this;

• JavaScript Array:

    cache.log().js(); // returns JavaScript Array;

• JSON Array:

    cache.log().json(); // returns JSON Array.

• Formatted Text for Console View:

    cache.log().text(); // returns a formatted string.

    // looks like: 
    something like....
    History Cache Log for anon:
        showing    items:
        ===============
        --------------
        Sat Mar 03 2018 20:56:23 GMT-0500 (EST)
        No Tag
        94c74643-69a3-4ddd-841b-a2efb8e016a0
        START
        DEFAULT STATE
----------------------
        Sat Mar 03 2018 20:56:23 GMT-0500 (EST)
        No Tag
        465c6da7-a0de-4a64-9cbe-48d165115688
        set name = Edith Bunker
        Revision: 1 

        ...