cyypher

Cypher ORM + client for redis-graph.

Inspiration

This project powers the Rel backend framework. We needed a more robust, relational client for redis-graph.

If you are looking for a more complete schema -> GraphQL server, definitely take a look at our framework.

Quickstart

1. Install npm package

Add the cyypher npm package via your package manager of choice.

npm install cyypher

yarn add cyypher

pnpm add cyypher

2. Initialize the client

import cyypher from "cyypher"

or with custom connection

import { Client } from "cyypher"

const cyypher = new Client({
  host: "...",
  port: 1234,
  auth: {
    username: "redis",
    password: "1234
  }
})

Usage

find(label, where)

Finds a single node by label and params.

cyypher.find('Person', { _id: '123' })
cyypher.find('Person', { name: 'Ian' })

list(label, where)

List multiple nodes by label and params.

// List everyone
cyypher.list('Person', {})

// List only admins
cyypher.list('Person', { where: { admin: true } })

count(label, where)

Count number of matching nodes.

// total count of a label
cyypher.count('Person')

// with where params
cyypher.count('Person', { where: { admin: true } })

create(label, where)

cyypher.create('Person', { name: 'Inigo Montoya' })

Ensure uniqueness across a field:

cyypher.create('Person', { name: 'Inigo Montoya' })

// this call is idempotent
cyypher.create('Person', { name: 'Inigo Montoya', __unique: 'name' })

findOrCreate(label, where, updateParams)

A find() and then create() call that will return an existing node if found.

cyypher.findOrCreate('Person', { name: 'Inigo Montoya' })
// this won't create a new node
cyypher.findOrCreate('Person', { name: 'Inigo Montoya' })
// this will create a new node
cyypher.findOrCreate('Person', { name: 'Vizzini' })

Optional: create params:

cyypher.findOrCreate(
  'Person',
  { _id: '1xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' },
  { name: 'Inigo Montoya' }
)

Note: It is not necessary to re-specify find params in the create params, the two will be merged together.

merge(label, where, updateParams)

Similar to findOrCreate but uses cypher's native merge command:

cyypher.merge('Person', { name: 'Inigo Montoya' })

update(label, id, updateParams)

Update a node based on ID.

cyypher.merge('Person', '123', { name: 'Inigo Montoya' })

updateBy(label, where, updateParams)

Update multiple nodes by params.

cyypher.updateBy(
  'Person',
  { name: 'Inigo Montoya' },
  { name: 'Mandy Patinkin' }
)

delete(label, id)

Delete a node by ID.

cyypher.delete('Person', '123')

deleteBy(label, params)

Delete multiple nodes by params.

cyypher.deleteBy('Person', { name: 'Inigo Montoya' })

listRelationship(from, rel, to, opts)

List relationships between nodes.

| Param | Type | Required | Description | Default | | :--------- | :----------------------------- | -------- | ------------------------------ | ------- | | from | string | object | Node | yes | From node | | rel | string | object | Node | yes | Relationship | | to | string | object | Node | yes | To node | | Options | | | | | | singular | boolean | | Singular relationship? | false | | skip | number | | Skip offset | 0 | | limit | number | | Number of results | | order | object | | Order the results | | orderRaw | string | | Direct order string to pass in |

// List N-1 between many nodes
cyypher.listRelationship('Person', 'FRIEND', { _id: '456' })

// List all FRIEND relationships between Persons
cyypher.listRelationship('Person', 'FRIEND', 'Person')

// List 1-1 between two nodes
cyypher.listRelationship({ _id: '123' }, 'FRIEND', { _id: '456' })

// You can also pass a node instance
import { ref } from 'cyypher'
const fromNode = await cyypher.find('Person', 'ID')
const toNode = await cyypher.find('Person', 'ID2')

cyypher.listRelationship(ref(fromNode), 'FRIEND', ref(toNode))

// List 1-1 between two nodes with types
cyypher.listRelationship({ __typename: 'Person', _id: '123' }, 'FRIEND', {
  __typename: 'Person',
  _id: '456',
})

// List 1-1 between two nodes with relation params
cyypher.listRelationship(
  { _id: '123' },
  { __typename: 'FRIEND', relation: 'close', metAt: new Date() },
  { _id: '456' }
)

// List directed relationship (IN, OUT, NONE)
cyypher.listRelationship(
  { _id: '123' },
  { __typename: 'FRIEND', __direction: 'OUT' },
  { _id: '456' }
)

createRelationship(from, rel, to, opts)

Create relationship(s) between two or more nodes.

| Param | Type | Required | Description | Default | | :--------- | :----------------------------- | -------- | ---------------------- | ------- | | from | string | object | Node | yes | From node | | rel | string | object | Node | yes | Relationship | | to | string | object | Node | yes | To node | | Options | | | | | | singular | boolean | | Singular relationship? | false |

// Using params
cyypher.createRelationship({ _id: '123' }, 'FRIEND', { _id: '456' })

// Using node references
import { ref } from 'cyypher'
const fromNode = await cyypher.find('Person', 'ID')
const toNode = await cyypher.find('Person', 'ID2')
cyypher.createRelationship(ref(fromNode), 'FRIEND', ref(toNode))

// Singular
cyypher.createRelationship(
  { _id: '123' },
  'FRIEND',
  { _id: '456' },
  { singular: true }
)

clearRelationship()

Clear all relationships between two or more nodes.

| Param | Type | Required | Description | Default | | :----- | :----------------------------- | -------- | ------------ | ------- | | from | string | object | Node | yes | From node | | rel | string | object | Node | yes | Relationship |

// Using params
cyypher.clearRelationship({ _id: '123' }, 'FRIEND')

deleteRelationship()

Delete relationship(s) between two or more nodes.

| Param | Type | Required | Description | Default | | :----- | :----------------------------- | -------- | ------------ | ------- | | from | string | object | Node | yes | From node | | rel | string | object | Node | yes | Relationship | | to | string | object | Node | yes | To node |

// Using params
cyypher.deleteRelationship({ _id: '123' }, 'FRIEND', { _id: '456' })

// Using node references
import { ref } from 'cyypher'
const fromNode = await cyypher.find('Person', 'ID')
const toNode = await cyypher.find('Person', 'ID2')
cyypher.deleteRelationship(ref(fromNode), 'FRIEND', ref(toNode))