Custom SurrealDB SDK for JavaScript.
npm install kantara-db
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.