# railgun.records

The records module contains the powerful Record class, which is a sort of data warehouse for information
about requests. It is a [Tree data structure](https://en.wikipedia.org/wiki/Tree_(data_structure)) that
contains requests and their child requests- i.e. requests that have been made with the former as a "parent".
The spider, for example, uses `railgun.records.Record` to record information about requests it makes so that
users can later perform meaningful analysis.

Example:

```js
const railgun = require('railgun')

let firstPage = new railgun.Request('GET', 'http://site1.cat')
let record = new railgun.records.Record(firstPage)

let secondPage = new railgun.Request('GET', 'http://site1.cat/video.html')
let child = record.addChild(secondPage)

let thirdPage = new railgun.Request('GET', 'http://youtube.com/cutecatvideo')
child.addChild(thirdPage)

record.setResponse({
  // We would normally want to use an actual response object here.
  body: 'meow'
})

// We can use find to get an array of nodes from the record tree that satisfy some predicate.
let youtube = record.find((node) => /youtube/.test(node.url))[0]

console.log('Found a youtube URL at depth', youtube.depth())

record.store('./requests.json')
.then(() => {
  let reloaded = railgun.records.load('./requests.json')
  // Do more analysis with reloaded
})
.catch(console.error)
```

## Module functions

### railgun.records.load

records.load accepts a path to a file on disk that contains the JSON contents of a record and loads
that data into memory as a Record object.

## Methods

### railgun.records.Record#constructor

The Record constructor accepts a request builder and creates a record node with an empty response,
an empty array of child nodes, etc.

### railgun.records.Record#addChild

records.record#addChild adds a child to a record node, indicating that it (the child) is a request
that was made after requesting the document described in the node that the child is being added to.
The child node will be returned.

### railgun.records.Record#setResponse

records.record#setResponse updates the node's response object to contain the data held in a response
builder. It will return the node upon which the method is called.

### railgun.records.Record#find

records.Record#find performs a breadth-first search on the record tree and returns an array of nodes
that satisfy a given predicate. This predicate function is the only argument accepted by find and
takes the form

```js
function (request) {
  return // true if the request meets our criteria else false
}
```

### railgun.records.Record#equals

records.Record#equals is used to determine if a node is equal to another node. The test returns true
if the two nodes were created at the same time, contain the same URL, and have the same internal
identifier.

### railgun.records.Record#depth

records.Record#depth gets the depth of the node in the record tree.

### railgun.records.Record#store

records.Record#store accepts a path to a file that it can write to and converts the record tree into
JSON and writes it to that file.