: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 <>. 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 <>.

getBetween :: SID, PID -> Promise Edge

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

getFrom :: PID -> Promise [Edge]

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

getTo :: SID -> Promise [Edge]

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

getAll :: ID -> Promise [Edge]

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

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 <>.

destroy :: SID, PID -> Promise Edge

Returns the destroyed edge. Can throw error <>.

endpointDestroy :: ID -> Promise [Edge]

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

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 <>). The value published is always a JSON stringified array of <> 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