# @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 

        ...
        
```