surrealism

A SurrealDB Driver.

Getting Started

> WARN: As of SurrealDB 1.0.0-beta.9, WebSockets in Bun currently do not work as intended.
> As a workaround, use HTTP-only connections.
> See: surrealdb/surrealdb.js#159.

$3

Import the module from deno.land:

``ts
import { Surreal } from "https://deno.land/x/surrealism/mod.ts";
`

$3

Add Surrealism as a dependency:

`sh
$ npm i surrealism
`

Then, import it in your code:

`js
import { Surreal } from 'surrealism'
`

Alternatively, a bundle in CommonJS format is included:

`js
const { Surreal } = require('surrealism')
`

Connecting to SurrealDB

`js
// connect using an http url, with ws url inferred
const db = await Surreal
.new('http://localhost:8000', {
user: 'root',
pass: 'root',
})
.use({ ns: 'test', db: 'test' })

// connect using a ws url, with http url inferred
const db = await Surreal
.new('ws://localhost:8000/rpc', {
user: 'root',
pass: 'root',
})
.use({ ns: 'test', db: 'test' })

// connect using explicit ws and http urls,
// omitting the url removes the driver for that protocol
const db = await Surreal
.new({
http: 'http://localhost:8000',
ws: 'ws://localhost:8000/rpc',
}, {
user: 'root',
pass: 'root',
})
.use({ ns: 'test', db: 'test' })

// connect as a namespaced user
const db = await Surreal
.new('http://localhost:5423', {
ns: 'test',
user: 'john.doe',
pass: '123456',
})
.use({ ns: 'test', db: 'test' })

// connect as a scoped user
const db = await Surreal
.new('http://localhost:5423', {
ns: 'test',
db: 'test',
sc: 'user_scope',
user: 'john.doe',
pass: '123456',
})

// for modern environments with explicit resource management,
// async disposal is available for the ws driver
await using db = await Surreal
.new('ws://localhost:5423/rpc', {
user: 'root',
pass: 'root',
})
.use({ ns: 'test', db: 'test' })
`

Using Surrealism

$3

`js
await db.use({ ns: 'foo', db: 'bar' })
`

$3

`js
// get all records on table "foo"
const result = await db.get('foo')

// get record with id "bar" on table "foo"
const result = await db.get('foo', 'bar')
`

> Works with: HTTP, WS driver

$3

`js
// create a new record on table "foo" with random id
const result = await db.create('foo', { value: 0 })

// create a new record with id "bar" on table "foo"
const result = await db.create('foo', 'bar', { value: 0 })
`

> Works with: HTTP, WS driver

$3

`js
// delete all records in table "foo"
const result = await db.delete('foo')

// delete record with id "bar" in table "foo"
const result = await db.delete('foo', 'bar')
`

> Works with: HTTP, WS driver

$3

`js
// update record with id "bar" on table "foo" with data "{ value: 1 }"
const result = await db.update('foo', 'bar', { value: 1 })
`

> Works with: HTTP, WS driver

$3

`js
// set property of "value" to "1" on record with id "bar" on table "foo"
const result = await db.mutate('foo', 'bar', { value: 1 })
`

> Works with: HTTP driver

$3

`js
// apply patches to all records on table "foo"
const result = await db.patch('foo', [
{ op: 'add', path: '/value', value: 0 },
])

// apply patches to record with id "bar" on table "foo"
const result = await db.patch('foo', 'bar', [
{ op: 'replace', path: '/value', value: 1 },
])
`

> Works with: WS driver

$3

`js
// execute raw queries
const result = await db.sqlSELECT * FROM foo

// execute raw queries with variables
// variables are automatically escaped as LET parameters
const result = await db.sqlSELECT * FROM foo WHERE id > ${0}
`

> Works with: HTTP, WS driver

$3

`js
// execute a live query using async iterators
for await (const result of db.liveSELECT * FROM foo WHERE value > ${0}) {
break // stop live query
}

// execute a live query using a listener
const kill = await db.liveSELECT * FROM foo WHERE value > ${0}(data => {
})
await kill() // stop live query

// queries can be saved and reused,
// each starting a new live query
const liveQuery = db.liveSELECT * FROM foo WHERE value > ${0}

const kill1 = await liveQuery(data => {
})

const kill2 = await liveQuery(data => {
})

for await (const result of liveQuery) {
}
`

> Works with: WS driver

$3

`js
const result = await db.health()
`

> Works with: HTTP driver

$3

`js
// get connected database's version
const result = await db.version()
`

> Works with: HTTP driver

$3

`js
// close current connection
await db.close()
``

> Works with: WS driver