npm package: @littlebits/redis-graph
Description: CRUD actions against a graph model built on top of Redis
Author: Jason Kuhrt
Latest version: 0.6.2

:toc: macro
:toc-title:
:toclevels: 99

image:https://circleci.com/gh/littlebits/redis-graph.svg?style=svg["Circle CI", link="https://circleci.com/gh/littlebits/redis-graph"]

# Redis Graph
CRUD actions against a graph model built on top of Redis.

toc::[]



## Installation

```
npm install --save @littlebits/redis-graph
```



## API

### `export default` `Graph :: Settings -> GraphAPI`

#### `Settings :: {...}`

A hash of settings to use and customize the graph API. If you are going to interact with the key settings then be sure to read <<customizing-key-names>>. If you are just interested in what the key defaults are take a look at the link:https://github.com/littlebits/redis-graph/blob/master/lib/index.js#L20-L24[source code] responsible for resolving it.

##### `db :: RedisClient`
*Required*. An instance of link:https://github.com/luin/ioredis[ioredis].

[[keynamespace]]
##### `keyNamespace :: String`

Optional. Defaults to `graph`. The key to prefix before all keys entered into Redis. Also used as the channel name prefix where graph changes are published too.

##### `keyNode :: FormatPattern`

Optional. The key pattern for endpoints.

##### `keyFrom :: FormatPattern`
Optional. The key pattern for a publisher-position endpoint's index of subscriber-position endpoints.

##### `keyTo :: FormatPattern`

Optional. The key pattern for a subscriber-position endpoint's index of publisher-position endpoints.

##### `keyData :: FormatPattern`

Optional. The key pattern for edge data.



#### `GraphAPI :: {...}`

An API object of all the graph functions that will use the given redis connection. The following functions detail this API:

##### `create :: Edge -> Promise Edge`

Using the endpoints in the given edge create an edge between them using the given edge data. The given edge's publisher/subscriber endpoints will be automatically created if they do not exist.

##### `createStrict :: Edge -> Promise Edge`

Same as `create` except the given edge's publisher/subscriber endpoints are not automatically created; Instead a `ErrorNoSuchEndpoint` is thrown if either does not exist. Can throw error <<errornosuchendpoint>>.

##### `getBetween :: SID, PID -> Promise Edge`

Returns the edge between the given endpoints. Can throw error <<errornosuchedge>>.

##### `getFrom :: PID -> Promise [Edge]`

Returns all edges where the given endpoint is in publisher position. Can throw error <<errornosuchendpoint>>.

##### `getTo :: SID -> Promise [Edge]`

Returns all edges where the given endpoint is in subscriber position. Can throw error <<errornosuchendpoint>>.

##### `getAll :: ID -> Promise [Edge]`

Returns all edges where the given endpoint is in either subscriber or publisher position. Can throw error <<errornosuchendpoint>>.

##### `update :: Edge -> Promise Edge`

The endpoints in the given edge will be used to lookup the current edge and once found the current edge data will be replaced with the given edge's data. Can throw error <<errornosuchedge>>.

##### `destroy :: SID, PID -> Promise Edge`

Returns the destroyed edge. Can throw error <<errornosuchedge>>.

##### `endpointDestroy :: ID -> Promise [Edge]`

Returns all the edges that were destroyed. Can throw error <<errornosuchendpoint>>.

##### `endpointCreate :: ID -> Promise ID`

Creating endpoints is idempotent so no error is thrown if it already exists.



## Guide

### Customizing Key Names

If you are interested in using custom key names note the following. Individual naming given for a specific key will not have the namespace prefixed. This is so that you have maximum control and we think that customizing the key names is a low-level niche use-case that warrants our no-magic approach. The value given will be processed through link:https://nodejs.org/api/util.html#util_util_format_format[format]. Your key names must supply `%s` interpolation variables where you would like the key variables to be placed in your naming scheme. All keys only require a single interpolation variable except `keyData` which requires two. You may want to review the source code for key names to fully understand the system.

### Change Feeds

All graph functions cause their changes to be published via Redis PubSub over a channel that by default is named `graph:changes` (see  <<keynamespace>>). The value published is always a JSON stringified array of <<graphchange>> objects. The model design is based on link:http://rethinkdb.com/docs/changefeeds/javascript/[RethinkDB Change Feeds].


## Types

#### ID | PID | SID
```
String
```

`PID` is an endpoint in publisher position. `SID` is an endpoint in subscriber position. `ID` is an endpoint that can be in either position.

#### Edge
```
{
  sid: String
  pid: String
  data: {}
}
```

#### ErrorNoSuchEdge
```
message: String
code: 'REDIS_GRAPH_NO_SUCH_EDGE'
```

#### ErrorNoSuchEndpoint
```
message: String
code: 'REDIS_GRAPH_NO_SUCH_ENDPOINT'
```

#### GraphChange
```
before: Null | Edge
after: Null | Edge
```