surrealdb.js

 

The official SurrealDB SDK for JavaScript.

       

     

surrealdb.js

The official SurrealDB SDK for JavaScript.

Documentation

View the SDK documentation here.

How to install

Install for Deno

Import it with:

import Surreal from "https://deno.land/x/surrealdb/mod.ts";

For best results, set a version in the url:

import Surreal from "https://deno.land/x/surrealdb@1.0.0/mod.ts";

Install for Node.js

Install it with:

# using npm
npm i surrealdb.js
# or using pnpm
pnpm i surrealdb.js
# or using yarn
yarn add surrealdb.js

Next, just import it with:

const { Surreal } = require("surrealdb.js");

or when you use modules:

import Surreal from "surrealdb.js";

Install for the browser

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

# using npm
npm i surrealdb.js
# or using pnpm
pnpm i surrealdb.js
# or using yarn
yarn add surrealdb.js

Next, just import it with:

import Surreal from "surrealdb.js";

or when you use CommonJS:

const { Surreal } = require("surrealdb.js");

Install for the browser with a CDN

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

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

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.

import { Surreal, RecordId, Table } from "surrealdb.js";

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

Local setup

This is a Deno project, not Node.js. For example, this means import paths include the .ts file extension. However, to also support other JavaScript environments, a build has been added to create a npm package that works for Node.js, Bun, browsers with bundlers.

Supported environments

• Deno
• Node.js
• Bun
• Web Browsers

Requirements

• Deno
• SurrealDB (for testing)

Build for all supported environments

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

deno task build.

Formatting

deno fmt

Linting

deno lint

Run tests

deno task test

Run tests and update snapshots

deno task test:update

PRs

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

Local setup

For local development the Deno extension for VSCode is helpful (hint: local Deno installation required).

Directory structure

• ./mod.ts is the deno entypoint. This is just a reexport of ./src/index.ts
• ./deno.json include settings for linting, formatting and testing.
• ./compile.ts include the build script for the npm package.
• ./src includes all source code. ./src/index.ts is the main entrypoint.
• ./npm is build by ./compile.ts and includes the generated npm package.
• ./tests includes all test files.