@dms/io/README.md

The official [Data Mining & Supply](https://datamining.supply) IO wrapper module. 
 
Currently, DMS is in a private beta release and this package requires an active DMS account. Once out of beta, installing and using public supplies will no longer require an account or login prompt. Full documentation and more information can be found in the [DMS Docs](https://datamining.supply/docs).

Loading the module:
-------------------
```
var supply = require('@dms/io');
```
The **@dms/io** wrapper module loads as a function. Calling this function loads and initializes an instance of the Supply class.

Initializing a Supply:
------

Some examples for loading a supply using the [/s/running-numbers](https://datamining.supply/s/running-numbers) supply:
```
// Using the default options
var mySupply = supply('running-numbers')
```


```
// If we have data that looks like this:
var data = [
  {
    id: "ABC",
    number: 10
  },
  {
    id: "ABC",
    number: 12
  },
  {
    id: "ABC",
    number: 15
  }
]


// ... then we might want to add some options
var mySupply = supply('supply-name', {
    inputs: { // Renaming inputs
      value: "number" 
    },
    parameters: { // tuning parameters
      population: false
    },
    bypass: [ "id" ] // adding bypass fields
  });
```
  
#### supply(name [,options])
- __name__ - string name of the supply to load

- __options__ - optional object
  - __inputs__ - object for remapping input names
  - __parameters__ - object for tuning this supply's parameters
  - __bypass__ - array of field names to pass around this supply's logic
  - __version__ - specific version to load, defaults to newest installed

---

Using a Supply
--------
Data can be sent through a supply as an array of data points, or one point at a time. The loaded supply object will remember whatever is required to mine the next data point. If the data argument is left out, it will default to `{}`.

__Using a supply's $main route__  
```
// asynchronously
mySupply(data, function(err, result){
  console.log(err, result);
});

// synchronously
var result = mySupply(data);
```


Some supplies have multiple routes for data:

__Using a supply's custom $on route__  
```
// asynchronously
mySupply.$on('routeName', data, function(err, result){
  console.log(err, result);
});

// synchronously
var result = mySupply.$on('routeName', data);
```

**Extra Stuff**
```
// Check how many points a supply has mined
console.log(mySupply.points_mined);

// Access a supply's internal memory
var memory = mySupply.$;

// Get the epoch time the supply was initialized
console.log(mySupply.created_on);
```

Check out [https://datamining.supply](https://datamining.supply) for more info.