The official SurrealDB SDK for JavaScript.

 

 

 

 

 

 

 

surrealdb

The official SurrealDB SDK for JavaScript.

Documentation

View the SDK documentation here.

Learn SurrealDB

- SurrealDB University: https://surrealdb.com/learn/fundamentals
- Aeon's Surreal Renaissance (Interative book): https://surrealdb.com/learn/book
- Documentation: https://surrealdb.com/docs

How to install

$3

Import it with:

``ts
import Surreal from "@surrealdb/surrealdb";
`

$3

Install it with:

`sh

using npm

npm i surrealdb

or using pnpm

pnpm i surrealdb

or using yarn

yarn add surrealdb
`

Next, just import it with:

`ts
const { Surreal } = require("surrealdb");
`

or when you use modules:

`ts
import Surreal from "surrealdb";
`

$3

For usage in a browser environment, when using a bundler (e.g. Rollup, Vite, or webpack) you can install it with:

`sh

using npm

npm i surrealdb

or using pnpm

pnpm i surrealdb

or using yarn

yarn add surrealdb
`

Next, just import it with:

`ts
import Surreal from "surrealdb";
`

or when you use CommonJS:

`ts
const { Surreal } = require("surrealdb");
`

$3

For fast prototyping we provide a browser-ready bundle. You can import it with:

`ts
import Surreal from "https://unpkg.com/surrealdb";
// or
import Surreal from "https://cdn.jsdelivr.net/npm/surrealdb";
`

_NOTE: this bundle is not optimized for production! So don't use it in production!_

Getting started

In the example below you can see how to connect to a remote instance of SurrealDB, authenticating with the database, and issuing queries for creating, updating, and selecting data from records.

> This example requires SurrealDB to be installed and running on port 8000.

> This example makes use of top level await, available in modern browsers, Deno and Node.js >= 14.8.

`ts
import { Surreal, RecordId, Table } from "surrealdb";

const db = new Surreal();

// Connect to the database
await db.connect("http://127.0.0.1:8000/rpc");

// Select a specific namespace / database
await db.use({
namespace: "test",
database: "test"
});

// Signin as a namespace, database, or root user
await db.signin({
username: "root",
password: "root",
});

// Create a new person with a random id
let created = await db.create("person", {
title: "Founder & CEO",
name: {
first: "Tobie",
last: "Morgan Hitchcock",
},
marketing: true,
});

// Update a person record with a specific id
let updated = await db.merge(new RecordId('person', 'jaime'), {
marketing: true,
});

// Select all people records
let people = await db.select("person");

// Perform a custom advanced query
let groups = await db.query(
"SELECT marketing, count() FROM $tb GROUP BY marketing",
{
tb: new Table("person"),
},
);
`

Contributing

$3

This is a Bun project, not Node.js. It works across all major runtimes, however.

#### Supported environments

- Deno
- Node.js
- Bun
- Web Browsers

$3

- Bun
- SurrealDB (for testing)

$3

For Deno, no build is needed. For all other environments run

bun run build.

$3

bun quality:apply

$3

bun quality:apply:unsafe

$3

bun test

$3

SURREAL_PROTOCOL=http bun test

$3

Before you commit, please format and lint your code accordingly to check for
errors, and ensure all tests still pass

$3

For local development the
Bun extension and Biome extension
for VSCode are helpful.

$3

- ./biome.json include settings for code quality.
- ./scripts include the build scripts for NPM and JSR.
- ./src includes all source code. ./src/index.ts is the main entrypoint.
- ./dist is build by ./scripts/build.ts and includes the compiled and minified bundles for ESM, CJS and bundled ESM targets.
- ./tests` includes all test files.