@code-o-mat/history-cache
Version:
A data object structure that logs all changes using the immutable library
191 lines (137 loc) • 6.26 kB
Markdown
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.
```
import HistoryCache from 'history-cache';
var defaultData = {
name: 'Robert LaMarca',
age: 103,
birthplace: 'Croatia',
voice: 'Flat',
eyes: 'sensitive',
[]: 'groovy'
};
const cache = new HistoryCache(defaultData);
```
* **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.
* **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.
```
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
```
**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 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.
```
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;
```
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
...
```