The official SurrealDB SDK for JavaScript.

surrealdb

The official SurrealDB SDK for JavaScript.

Documentation

View the SDK documentationhere.

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

Install forJSR/Deno

Import it with:

importSurrealfrom"@surrealdb/surrealdb";

Install forNode.js

Install it with:

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

Next, just import it with:

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

or when you use modules:

importSurrealfrom"surrealdb";

Install for the browser

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

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

Next, just import it with:

importSurrealfrom"surrealdb";

or when you use CommonJS:

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

Install for the browser with a CDN

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

importSurrealfrom"https://unpkg.com/surrealdb";
// or
importSurrealfrom"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 beinstalledand running on port 8000.

This example makes use oftop level await,available inmodern browsers,DenoandNode.js>= 14.8.

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

constdb=newSurreal();

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

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

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

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

// Update a person record with a specific id
letupdated=awaitdb.merge(newRecordId('person','jaime'),{
marketing:true,
});

// Select all people records
letpeople=awaitdb.select("person");

// Perform a custom advanced query
letgroups=awaitdb.query(
"SELECT marketing, count() FROM $tb GROUP BY marketing",
{
tb:newTable("person"),
},
);

Contributing

Local setup

This is aBunproject, not Node.js. It works across all major runtimes, however.

Supported environments

• Deno
• Node.js
• Bun
• Web Browsers

Requirements

• Bun
• SurrealDB (for testing)

Build for all supported environments

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

bun run build.

Code Quality Fixes

bun quality:apply

Code Quality unsafe fixes

bun quality:apply:unsafe

Run tests for WS

bun test

Run tests for HTTP

SURREAL_PROTOCOL=http bun test

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 Bun extensionandBiome extension for VSCode are helpful.

Directory structure

• ./biome.jsoninclude settings for code quality.
• ./scriptsinclude the build scripts for NPM and JSR.
• ./srcincludes all source code../src/index.tsis the main entrypoint.
• ./distis build by./scripts/build.tsand includes the compiled and minified bundles for ESM, CJS and bundled ESM targets.
• ./testsincludes all test files.