@tai-kun/surrealdb
Version:
The SurrealDB SDK for JavaScript
114 lines (84 loc) • 4.19 kB
Markdown
A modular SurrealDB client working in major JavaScript runtimes.
[](https://github.com/tai-kun/surrealdb.js/actions/workflows/nodejs.yml)
[](https://github.com/tai-kun/surrealdb.js/actions/workflows/bun.yml)
[](https://github.com/tai-kun/surrealdb.js/actions/workflows/deno.yml)
[](https://github.com/tai-kun/surrealdb.js/actions/workflows/chromium.yml)
[](https://github.com/tai-kun/surrealdb.js/actions/workflows/firefox.yml)
[](https://github.com/tai-kun/surrealdb.js/actions/workflows/webkit.yml)
[](https://app.codecov.io/github/tai-kun/surrealdb.js)
[)](https://opensource.org/licenses/Apache-2.0)
[](https://www.npmjs.com/package/@tai-kun/surrealdb)
<!--  -->
> [!NOTE]
> The main branch is currently under development for SurrealDB v2.
> You can find the repository for SurrealDB v1 [here](https://github.com/tai-kun/surrealdb.js/tree/v1).
## Document (JA/EN/KO/zh-CN)
[https://tai-kun.github.io/surrealdb.js/getting-started/](https://tai-kun.github.io/surrealdb.js/getting-started/)
## Install
```sh
npm i @tai-kun/surrealdb
```
## Quick Start
```ts
import { Surreal } from "@tai-kun/surrealdb";
const db = new Surreal();
await db.connect("<your_surrealdb_server>"); // e.g. ws://localhost:8000
try {
await db.signin({ user: "root", pass: "root" });
await db.use("sample_namespace", "sample_database");
const results = await db.query<[number]>(/*surql*/ `RETURN 42;`);
console.log(results); // [ 42 ]
} finally {
await db.close();
}
```
## Customization
```ts
import { initSurreal } from "@tai-kun/surrealdb";
import Client from "@tai-kun/surrealdb/standard-client";
import HttpEngine from "@tai-kun/surrealdb/http-engine";
import JsonFormatter from "@tai-kun/surrealdb/json-formatter";
const { Surreal } = initSurreal({
Client: Client,
engines: {
http: config => new HttpEngine({
...config,
// fetch: <your custom fetch function>
}),
https: "http",
},
formatter: new JsonFormatter(),
});
```
## Requirements
SurrealDB >=2.1.0
The repository for SurrealDB v1 is [here](https://github.com/tai-kun/surrealdb.js/tree/v1).
## Recommended environment
| Env | Version |
| --- | --- |
| Node.js | `20.x`,`22.x` *1 |
| Deno | `1.x`, `2.x` *2 |
| Bun | `1.x` |
| Chromium | `>=104` *3 |
| Firefox | `>=100` *4 |
| WebKit | `>=15.4` *5 |
*1: Probably works with `18.x`
*2: Probably works with `^1.44.3`
*3: Probably works with `>=78`
*4: Probably works with `>=68`
*5: Probably works with `>=14`
## Fully Tested
| Env | Version |
| --- | --- |
| Node.js | `20.x`,`22.x`,`23.x` |
| Deno | `1.x`,`2.x` |
| Bun | `1.x` |
| Chromium | `>=104` |
## Partial Tested
| Env | Version |
| --- | --- |
| Node.js | `18.x` |
| Firefox | `>=100` |
| WebKit | `>=15.4` |
## License
[Apache-2.0](https://github.com/tai-kun/surrealdb.js/blob/main/LICENSE)