Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/surrealdb/surrealdb.js
SurrealDB driver 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: 3 months ago
JSON representation
SurrealDB driver for JavaScript
- Host: GitHub
- URL: https://github.com/surrealdb/surrealdb.js
- Owner: surrealdb
- License: apache-2.0
- Created: 2022-04-07T16:17:54.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2024-02-02T17:36:24.000Z (5 months ago)
- Last Synced: 2024-03-02T21:42:53.559Z (4 months 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: 162 KB
- Stars: 235
- Watchers: 19
- Forks: 35
- Open Issues: 22
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS
- Security: SECURITY.md
Lists
- 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)
- awesome-surrealdb - surrealdb.js - Official driver for JS / TS runtimes. ![node] ![deno] ![bun] ![web] (Resources / Libraries for surealdb)
README
# surrealdb.js
The official SurrealDB library for JavaScript.
[](https://github.com/surrealdb/surrealdb.js)
[](https://surrealdb.com/docs/integration/libraries/javascript)
[](https://github.com/surrealdb/surrealdb.js)
[](https://www.npmjs.com/package/surrealdb.js)
[](https://deno.land/x/surrealdb)
## Quickstart-Guide
### Install
#### Deno
Import it with
```ts
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/[email protected]/mod.ts`
#### NodeJS, or browser with a bundler
For NodeJS or a browser with bundler (for example: rollup, vite, or webpack) you can just:
install the npm package:
```sh
npm i surrealdb.js
# or with yarn
yarn add surrealdb.js
# or with pnpm
pnpm i surrealdb.js
```
then, just import it with:
```ts
import Surreal from "surrealdb.js";
```
or when you use CommonJS
```ts
const { default: Surreal } = require("surrealdb.js");
```
#### CDN for Browser
For fast prototyping we provide a browser-ready bundle. You can import it with
```ts
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!**_
### Getting started
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).
```ts
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);
}
```
## More informations
The docs of this libary are located at
[https://surrealdb.com/docs/integration/libraries/javascript](https://surrealdb.com/docs/integration/libraries/javascript)
## Contribution notes
### Local setup
This is a [Deno](https://deno.land) 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.
#### Supported environments
- [Deno](https://deno.land)
- [NodeJS](https://nodejs.org)
- [Bun](https://bun.sh)
- Web Browsers
### Requirements
- Deno
- npm
- NodeJS
- Docker (for e2e tests)
- Bun (for e2e tests)
### Build for all supported environments
For Deno, no build is needed. For all other environments run
`deno task build`.
### Formatting
`deno fmt`
### Linting
`deno lint`
### PRs
Before you commit, please format and lint your code accordingly to check for
errors.
### Local setup
For local development the
[Deno extension](https://marketplace.visualstudio.com/items?itemName=denoland.vscode-deno)
for VSCode is helpful (hint: local Deno installation required).
### Directory structure
- `./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`.