- Notifications
You must be signed in to change notification settings - Fork53
SurrealDB SDK for JavaScript
License
surrealdb/surrealdb.js
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Repository files navigation
The official SurrealDB SDK for JavaScript.
View the SDK documentationhere.
- SurrealDB University:https://surrealdb.com/learn/fundamentals
- Aeon's Surreal Renaissance (Interative book):https://surrealdb.com/learn/book
- Documentation:https://surrealdb.com/docs
Install forJSR/Deno
Import it with:
importSurrealfrom"@surrealdb/surrealdb";
Install forNode.js
Install it with:
# using npmnpm i surrealdb# or using pnpmpnpm i surrealdb# or using yarnyarn add surrealdb
Next, just import it with:
const{ Surreal}=require("surrealdb");
or when you use modules:
importSurrealfrom"surrealdb";
For usage in a browser environment, when using a bundler (e.g.Rollup,Vite, orwebpack) you can install it with:
# using npmnpm i surrealdb# or using pnpmpnpm i surrealdb# or using yarnyarn add surrealdb
Next, just import it with:
importSurrealfrom"surrealdb";
or when you use CommonJS:
const{ Surreal}=require("surrealdb");
For fast prototyping we provide a browser-ready bundle. You can import it with:
importSurrealfrom"https://unpkg.com/surrealdb";// orimportSurrealfrom"https://cdn.jsdelivr.net/npm/surrealdb";
NOTE: this bundle is not optimized for production! So don't use it in production!
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 beinstalled and running on port 8000.
This example makes use oftop level await, available inmodern browsers,Deno andNode.js >= 14.8.
import{Surreal,RecordId,Table}from"surrealdb";constdb=newSurreal();// Connect to the databaseawaitdb.connect("http://127.0.0.1:8000/rpc");// Select a specific namespace / databaseawaitdb.use({namespace:"test",database:"test"});// Signin as a namespace, database, or root userawaitdb.signin({username:"root",password:"root",});// Create a new person with a random idletcreated=awaitdb.create("person",{title:"Founder & CEO",name:{first:"Tobie",last:"Morgan Hitchcock",},marketing:true,});// Update a person record with a specific idletupdated=awaitdb.merge(newRecordId('person','jaime'),{marketing:true,});// Select all people recordsletpeople=awaitdb.select("person");// Perform a custom advanced queryletgroups=awaitdb.query("SELECT marketing, count() FROM $tb GROUP BY marketing",{tb:newTable("person"),},);
This is aBun project, not Node.js. It works across all major runtimes, however.
- Bun
- SurrealDB (for testing)
For Deno, no build is needed. For all other environments run
bun run build.
bun quality:apply
bun quality:apply:unsafe
bun test
SURREAL_PROTOCOL=http bun test
Before you commit, please format and lint your code accordingly to check forerrors, and ensure all tests still pass
For local development theBun extension andBiome extensionfor VSCode are helpful.
./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.
About
SurrealDB SDK for JavaScript