The official SurrealDB library for JavaScript.
Import it with
import Surreal from "https://deno.land/x/surrealdb/mod.ts";
Note you should set a version in the url! For example
https://deno.land/x/surrealdb@0.5.0/mod.ts
For NodeJS or a browser with bundler (for example: rollup, vite, or webpack) you can just: install the npm package:
npm i surrealdb.js
# or with yarn
yarn add surrealdb.js
# or with pnpm
pnpm i surrealdb.js
then, just import it with:
import Surreal from "surrealdb.js";
or when you use CommonJS
const { default: Surreal } = require("surrealdb.js");
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!
Here you have a simple example!
This example uses top level await wich is available in deno, node >= 14.8, modern browsers (https://caniuse.com/mdn-javascript_operators_await_top_level).
const db = new Surreal();
try {
// Connect to the database
await db.connect("http://127.0.0.1:8000/rpc");
// Signin as a namespace, database, or root user
await db.signin({
username: "root",
password: "root",
});
// Select a specific namespace / database
await db.use({ namespace: "test", database: "test" });
// 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,
identifier: Math.random().toString(36).substr(2, 10),
});
// Update a person record with a specific id
let updated = await db.merge("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 type::table($tb) GROUP BY marketing",
{
tb: "person",
},
);
} catch (e) {
console.error("ERROR", e);
}
The docs of this libary are located at https://surrealdb.com/docs/integration/libraries/javascript
This is a Deno project, not NodeJS. 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 NodeJS, Bun, browsers with bundlers.
- Deno
- npm
- NodeJS
- Docker (for e2e tests)
- Bun (for e2e tests)
For Deno, no build is needed. For all other environments run
deno task build
.
deno fmt
deno lint
Before you commit, please format and lint your code accordingly to check for errors.
For local development the Deno extension for VSCode is helpful (hint: local Deno installation required).
./mod.ts
is the deno entypoint. This is just a reexport of./src/index.ts
./deno.json
include settings for linting + formating../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../test
includes all test files. To add a test modify./test/e2e/shared.js
.