Terraformer

# GeoStore Data Stores

Data stores are the foundation of the GeoStore. They are `key/value` storage devices that allow for creating entries, updating, deleting, and retrieving single `Feature` objects in GeoJSON.

Data Stores are designed to be asyncronous, using Node.js style callbacks. In syncronough stores, like `Terraformer.Store.Memory` and `Terraformer.Store.LocalStorage` callbacks are executed immediately, but in truly asyncronous stores they behave as expected.

## Link Existing Data Stores Back to Top

There are a couple of existing Data Stores that help you get started storing data immediately.

- LocalStorage - works in the browser only
- Memory - works in both the browser and Node.js
- LevelDB - works in Node.js

## Link Writing a DataStore Back to Top

Since Data Stores are simply `key/value` stores, it is very easy to write additional Data Stores as long as the method signatures are correct.

### Link Methods Back to Top

#### Link new DataStore() Back to Top

Instantiating a `DataStore` should return a new object containing method signatures conforming to the `DataStore` interface.

You can pass any needed arguments while instantiating.

Example:

    var ds = new DataStore({
      "path": "some_path",
      "username": "me",
      "password": "mypass"
    });

#### Link DataStore.add(geostore, callback) Back to Top

Add a `geojson` object to a DataStore. In the case of a `Feature`, the `id` should be used as the primary key for storage and retrieval:

    // get the id
    var id = geojson.id;

    // store the data
    this.magicdb.put(geojson.id, JSON.stringify(geojson));

If a `FeatureCollection` is passed in instead, each `Feature` inside of the `FeatureCollection` needs to be added before the `callback` is called.

Option | Value | Description
--- | --- | ---
`GeoJSON` | `object` | Must be either a `Feature` or `FeatureCollection` and contain an `id`
callback | `function` | Callback to be fired when the `add` has been completed

Example:

    ds.add(geojson, function (err, res) {
      // Node.js style callback
    });

#### Link DataStore.update(geostore, callback) Back to Top

Update a `geojson` object already in a DataStore. Only a `Feature` should be able to be updated, the `id` should be used as the primary key for update:

Option | Value | Description
--- | --- | ---
`GeoJSON` | `object` | Must be a `Feature` and contain an `id`
callback | `function` | Callback to be fired when the `update` has been completed

Example:

    ds.update(geojson, function (err, res) {
      // Node.js style callback
    });

#### Link DataStore.remove(id, callback) Back to Top

Remove a `geojson` object from the DataStore by `id`.

Option | Value | Description
--- | --- | ---
id | `String` or `Number` | The `id` of the `Feature` to be removed
callback | `function` | Callback to be fired when the `remove` has been completed

Example:

    ds.remove(id, function (err, res) {
      // Node.js style callback
    });

#### Link DataStore.get(id, callback) Back to Top

Retrieves a `geojson` object from the DataStore by `id`.

Option | Value | Description
--- | --- | ---
id | `String` or `Number` | The `id` of the `Feature` to be retrieved
callback | `function` | Callback to be fired when the `remove` has been completed

Example:

    ds.get(id, function (err, res) {
      // Node.js style callback
    });