Zos/Skills/@be/node_modules/supersimplestorage/README.md

#SuperSimpleStorage
##A simple persistance layer library to store and retrieve data in Node.js without using a full blown database.

###Introduction
Often in a Node.js application there is a need to store some pieces data. Nothing big to justify a full blown database.
For those cases SuperSimpleStorage is handy tool that allows you to easily store and retrieve data from the filesystem.

SuperSimpleStorage is able to store:

- strings
- integers
- javascript data objects (that are automatically converted to and from JSON)

###Instalation

Install SuperSimpleStorage through NPM

```
npm install supersimplestorage --save
```

This will install SuperSimpleStorage as a dependency and update your package.json automatically.

Next require SuperSimpleStorage in your Node.js script, like this:

```
var supersimplestorage = require('supersimplestorage');
```

###Usage

####Initializing the storage

Before we can store and retrieve storage items, we first need to initialize the storage. We do this by creating a new storage object. When creating a new object we can pass configuration options. When no configuration options are passed (or only partially), default values are used.

```
var storage = new SuperSimpleStorage({
		storageFolder: 'my_storage_folder',
		dotsToFolders: true,
		fileExtension: 'txt'
});
```

The following configuration options are available:

- **storageFolder** - Folder where the storage items are stored. Defaults to '*storage*'
- **dotsToFolders** - Whether to translate a dots to slahes in order to store items in a file structure. Defaults to '*true*'
- **fileExtension** - The file extension used for the storage files. Defaults to '*data*'.

####Retrieving data from a storage item

Retrieving data from a storage item is done by calling the ```open``` method. The open-method accepts 3 parameters:

- **name** - The name of the storage item. When dotsToFolder is set to true, dots will translate to a file tree.
- **successCallback** - Function to call when the storage item has successfully been retrieved
- **errorCallback** - Function to call when an error has occurred while retrieving the item

It is important to realize that retrieving data from storage is *asynchronous*. That means that we can't assign the result of the open method directly to a variable. Instead we pass a success callback, which will receive the data as soon as it becomes available, where it can be processed further.

```
storage.open('foo', function(content) {

	console.log('Successfully opened foo');
	console.log(content);

}, function(error) {

	console.log('An error has occured');
	console.log(error);

});
```

####Saving data in a storage item

Storing data into a storage item is done by calling the ```save``` method. The save method accepts 4 parameters:

- **name** - The name of the storage item. When dotsToFolder is set to true, dots will translate to a file tree.
- **content** - The content to save in the storage item
- **successCallback** - Function to call when the storage item has successfully been saved
- **errorCallback** - Function to call when an error has occurred while storing the item

```
var data = {
	'foo': 'bar',
	'bar': 'foo'
}

// store JSON content
storage.save('foo.bar', data, function(content) {

	console.log('The content has been saved')

}, function(error) {

	console.log('An error has occured');
	console.log(error);

});
```

It is important to realize that saving data in storage also is *asynchronous*. If we want to act upon successfully saving data, we have to pass a callback, which will be executed as soon as the item has been stored.