Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/surrealdb/surrealdb.js
SurrealDB SDK for JavaScript
https://github.com/surrealdb/surrealdb.js
database database-connector deno deno-library deno-module iot-database javascript javascript-library javascript-module realtime-database surreal surrealdb
Last synced: 20 days ago
JSON representation
SurrealDB SDK for JavaScript
- Host: GitHub
- URL: https://github.com/surrealdb/surrealdb.js
- Owner: surrealdb
- License: apache-2.0
- Created: 2022-04-07T16:17:54.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2024-10-11T10:06:20.000Z (23 days ago)
- Last Synced: 2024-10-12T18:04:25.194Z (22 days ago)
- Topics: database, database-connector, deno, deno-library, deno-module, iot-database, javascript, javascript-library, javascript-module, realtime-database, surreal, surrealdb
- Language: TypeScript
- Homepage: https://surrealdb.com
- Size: 399 KB
- Stars: 294
- Watchers: 19
- Forks: 48
- Open Issues: 32
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS
- Security: SECURITY.md
Awesome Lists containing this project
- awesome-surreal - surrealdb.js - <a href="https://surrealdb.com#gh-dark-mode-only" target="_blank"><img src="/img/white/text.svg" height="12" alt="SurrealDB"></a> <a href="https://surrealdb.com#gh-light-mode-only" target="_blank"><img src="/img/black/text.svg" height="12" alt="SurrealDB"></a> official driver for JavaScript. (Client libraries)
README
The official SurrealDB SDK for JavaScript.
# surrealdb
The official SurrealDB SDK for JavaScript.
## Documentation
View the SDK documentation [here](https://surrealdb.com/docs/integration/libraries/javascript).
## How to install
### Install for [JSR/Deno](https://jsr.io/@surrealdb/surrealdb)
Import it with:
```ts
import Surreal from "@surrealdb/surrealdb";
```
### Install for [Node.js](https://www.npmjs.com/package/surrealdb)
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";
```
### Install for the browser
For usage in a browser environment, when using a bundler (e.g. [Rollup](https://rollupjs.org/), [Vite](https://vitejs.dev/), or [webpack](https://webpack.js.org/)) 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");
```
### Install for the browser with a CDN
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](https://surrealdb.com/install) and running on port 8000.
> This example makes use of [top level await](https://v8.dev/features/top-level-await), available in [modern browsers](https://caniuse.com/mdn-javascript_operators_await_top_level), [Deno](https://deno.com/) and [Node.js](https://nodejs.org/) >= 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
### Local setup
This is a [Bun](https://bun.sh) project, not Node.js. It works across all major runtimes, however.
#### Supported environments
- [Deno](https://deno.land)
- [Node.js](https://nodejs.org)
- [Bun](https://bun.sh)
- 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 extension](https://marketplace.visualstudio.com/items?itemName=oven.bun-vscode) and [Biome extension](https://marketplace.visualstudio.com/items?itemName=biomejs.biome)
for VSCode are helpful.
### Directory structure
- `./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.