Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/igalklebanov/kysely-surrealdb
Kysely dialects, plugins and other goodies for SurrealDB
https://github.com/igalklebanov/kysely-surrealdb
kysely kysely-dialect query-builder sql surrealdb surrealdb-driver type-safe typescript
Last synced: 23 days ago
JSON representation
Kysely dialects, plugins and other goodies for SurrealDB
- Host: GitHub
- URL: https://github.com/igalklebanov/kysely-surrealdb
- Owner: igalklebanov
- License: mit
- Created: 2022-10-12T19:24:07.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2024-04-03T22:45:31.000Z (10 months ago)
- Last Synced: 2024-12-23T16:10:14.706Z (about 1 month ago)
- Topics: kysely, kysely-dialect, query-builder, sql, surrealdb, surrealdb-driver, type-safe, typescript
- Language: TypeScript
- Homepage:
- Size: 359 KB
- Stars: 69
- Watchers: 3
- Forks: 2
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-surreal - kysely-surrealdb - Kysely (type-safe sql query builder) dialects, plugins and other goodies for SurrealDB. (Libraries)
README
# kysely-surrealdb
[Kysely](https://github.com/koskimas/kysely) dialects, plugins and other goodies for [SurrealDB](https://www.surrealdb.com/).
[SurrealQL](https://surrealdb.com/docs/surrealql) is based on SQL, so why not? :trollface:
## Installation
#### NPM 7+
```bash
npm i kysely-surrealdb
```
#### NPM <7
```bash
npm i kysely-surrealdb kysely surrealdb.js
```
#### Yarn
```bash
yarn add kysely-surrealdb kysely surrealdb.js
```
#### PNPM
```bash
pnpm add kysely-surrealdb kysely surrealdb.js
```
> `surrealdb.js` is an optional peer dependency. It's only needed if you want to use `SurrealDbWebSocketsDialect`. If you don't need it, you can remove `surreal.js` from the install commands above.
### Deno
This package uses/extends some [Kysely](https://github.com/koskimas/kysely) types and classes, which are imported using its NPM package name -- not a relative file path or CDN url.
`SurrealDbWebSocketsDialect` uses `surrealdb.js` which is imported using its NPM package name -- not a relative file path or CDN url.
To fix that, add an [`import_map.json`](https://deno.land/[email protected]/linking_to_external_code/import_maps) file.
```json
{
"imports": {
"kysely": "npm:kysely@^0.25.0",
"surrealdb.js": "https://deno.land/x/[email protected]" // optional - only if you're using `SurrealDbWebSocketsDialect`
}
}
```
## Usage
### HTTP Dialect
[SurrealDB](https://www.surrealdb.com/)'s [HTTP endpoints](https://surrealdb.com/docs/integration/http) allow executing [SurrealQL](https://surrealdb.com/docs/surrealql) queries in the browser and are a great fit for serverless functions and other auto-scaling compute services.
#### Node.js 16.8+
Older node versions are supported as well, just swap [`undici`](https://github.com/nodejs/undici) with [`node-fetch`](https://github.com/node-fetch/node-fetch).
```ts
import {Kysely} from 'kysely'
import {SurrealDatabase, SurrealDbHttpDialect, type SurrealEdge} from 'kysely-surrealdb'
import {fetch} from 'undici'
interface Database {
person: {
first_name: string | null
last_name: string | null
age: number
}
own: SurrealEdge<{
time: {
adopted: string
} | null
}>
pet: {
name: string
owner_id: string | null
}
}
const db = new Kysely>({
dialect: new SurrealDbHttpDialect({
database: '',
fetch,
hostname: '', // e.g. 'localhost:8000'
namespace: '',
password: '',
username: '',
}),
})
```
### WebSockets Dialect
```ts
import {Kysely} from 'kysely'
import {SurrealDatabase, SurrealDbWebSocketsDialect, type SurrealEdge} from 'kysely-surrealdb'
import Surreal from 'surrealdb.js'
interface Database {
person: {
first_name: string | null
last_name: string | null
age: number
}
own: SurrealEdge<{
time: {
adopted: string
} | null
}>
pet: {
name: string
owner_id: string | null
}
}
// with username and password
const db = new Kysely>({
dialect: new SurrealDbWebSocketsDialect({
database: '',
Driver: Surreal,
hostname: '', // e.g. 'localhost:8000'
namespace: '',
password: '',
// scope: '', // optional
username: '',
}),
})
// alternatively, with a token
const dbWithToken = new Kysely>({
dialect: new SurrealDbWebSocketsDialect({
database: '',
Driver: Surreal,
hostname: '', // e.g. 'localhost:8000'
namespace: '',
token: '',
}),
})
```
### SurrealKysely Query Builder
The awesomeness of Kysely, with some SurrealQL query builders patched in.
> This example uses `SurrealDbHttpDialect` but `SurrealDbWebSocketsDialect` works just as well.
```ts
import {SurrealDbHttpDialect, SurrealKysely, type SurrealEdge} from 'kysely-surrealdb'
import {fetch} from 'undici'
interface Database {
person: {
first_name: string | null
last_name: string | null
age: number
}
own: SurrealEdge<{
time: {
adopted: string
} | null
}>
pet: {
name: string
owner_id: string | null
}
}
const db = new SurrealKysely({
dialect: new SurrealDbHttpDialect({
database: '',
fetch,
hostname: '',
namespace: '',
password: '',
username: '',
}),
})
await db
.create('person:100')
.set({
first_name: 'Jennifer',
age: 15,
})
.return('none')
.execute()
```
#### Supported SurrealQL specific statements:
[create](https://surrealdb.com/docs/surrealql/statements/create),
[if else](https://surrealdb.com/docs/surrealql/statements/ifelse),
[relate](https://surrealdb.com/docs/surrealql/statements/relate).
#### Why not write a query builder from scratch
Kysely is growing to be THE sql query builder solution in the typescript ecosystem.
Koskimas' dedication, attention to detail, experience from creating objection.js, project structure, simplicity, design patterns and philosophy,
made adding code to that project a really good experience as a contributor. Taking
what's great about that codebase, and patching in SurrealQL stuff seems like an easy
win in the short-medium term.
## License
MIT License, see `LICENSE`