@imran3113/surreal-better-auth 0.1.0 → 0.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +143 -195
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,272 +1,220 @@
1
- <p align="center">
2
- <picture>
3
- <source media="(prefers-color-scheme: dark)" srcset="https://github.com/oskar-gmerek/surreal-better-auth/blob/beta/packages/surreal-better-auth/hero.webp?raw=true">
4
- <source media="(prefers-color-scheme: light)" srcset="https://github.com/oskar-gmerek/surreal-better-auth/blob/beta/packages/surreal-better-auth/hero-white.webp?raw=true">
5
- <img alt="surreal-better-auth banner" src="https://github.com/oskar-gmerek/surreal-better-auth/blob/beta/packages/surreal-better-auth/hero.webp?raw=true">
6
- </picture>
7
- </p>
1
+ # @imran3113/surreal-better-auth
8
2
 
9
- <h1 style="margin-top:40px;"> 🔐 SurrealDB Adapter for Better Auth </h1>
3
+ **SurrealDB v3 adapter for [Better Auth](https://better-auth.com)** — bringing the power of the multi-model database to your authentication system.
10
4
 
11
- ![GitHub Created At](https://img.shields.io/github/created-at/oskar-gmerek/surreal-better-auth?style=for-the-badge&color=%233ca916)
12
- ![NPM Last Update](https://img.shields.io/npm/last-update/surreal-better-auth?style=for-the-badge&color=%233ca916)
13
- ![NPM Version](https://img.shields.io/npm/v/surreal-better-auth?style=for-the-badge&color=%233ca916)
14
- ![NPM Unpacked Size](https://img.shields.io/npm/unpacked-size/surreal-better-auth?style=for-the-badge&color=%233ca916)
15
- ![NPM Downloads](https://img.shields.io/npm/dy/surreal-better-auth?style=for-the-badge&color=%233ca916)
16
- ![NPM License](https://img.shields.io/npm/l/surreal-better-auth?style=for-the-badge&color=%233ca916)
17
- [![Sponsor](https://img.shields.io/badge/sponsor-💖-ff69b4?style=for-the-badge&color=%23ffbdbd)](https://github.com/sponsors/oskar-gmerek)
5
+ This adapter integrates SurrealDB's advanced querying capabilities with Better Auth's comprehensive authentication features. It targets **SurrealDB v3** with the **`surrealdb@2.0.0`** JS SDK.
18
6
 
19
- **The unofficial [SurrealDB](https://app.surrealdb.com/referral?code=4pn5aba943lpbn8l) adapter for [better-auth](https://better-auth.com)** - bringing the power of the multi-model database to your authentication system.
20
-
21
- This adapter seamlessly integrates SurrealDB's advanced querying capabilities with better-auth's comprehensive authentication features, giving you a robust, scalable, and developer-friendly auth solution.
22
-
23
- > [!NOTE]
24
- > 🎁 **New to SurrealDB?** [Sign up with our referral link](https://app.surrealdb.com/referral?code=4pn5aba943lpbn8l) and get **free cloud hosting** plus a **special welcome discount** to kickstart your project!
7
+ > This package is a fork of [surreal-better-auth](https://github.com/oskar-gmerek/surreal-better-auth) by [Oskar Gmerek](https://github.com/oskar-gmerek), updated for SurrealDB v3 and `surrealdb@2.0.0` compatibility. Full credit to the original author for the foundational adapter design.
25
8
 
26
9
  ---
27
10
 
28
- ## ✨ Features
11
+ ## Features
29
12
 
30
- - 🚀 **Full better-auth compatibility** - Works with all better-auth features and plugins
31
- - 🔄 **Optimized for SurrealDB** - Uses direct record operations for maximum performance
32
- - 🎯 **Smart record links** - Uses record links instead of raw string wherever possible
33
- - 📋 **Schema generation support** - Works with Better Auth CLI, include support for official and unofficial plugins
34
- - 🔍 **Generating Indexes** - Creates necessary database indexes out of the box
35
- - 🆔 **Flexible ID formats** - Supports multiple ID generation strategies, full flexibility
36
- - 🌐 **Multi-format support** - ESM and CommonJS builds included
37
- - ⚡ **Lightweight** - Optimized bundle size
38
- - 📦 **No extra bloat** - This is a pure adapter. It has no direct dependencies and uses the `better-auth` and `surrealdb` you've already installed, giving you full control.
13
+ - **Full Better Auth compatibility** — Works with all Better Auth features and plugins
14
+ - **Optimized for SurrealDB v3** — Uses `BoundQuery`, direct record operations, and `type::record()`
15
+ - **Smart record links** — Automatic `record<table>` references instead of raw strings
16
+ - **Schema generation** — Works with Better Auth CLI for `.surql` schema output
17
+ - **Index generation** — Creates necessary database indexes out of the box
18
+ - **Flexible ID generation** — 8 strategies (ULID, UUID v4/v7, GUID, and more)
19
+ - **ESM and CommonJS** — Dual-format builds included
20
+ - **Zero extra dependencies** — Uses your existing `better-auth` and `surrealdb` packages
39
21
 
40
22
  ---
41
23
 
42
- ## ⭐ Show Your Support
43
-
44
- If this adapter helps your project, please consider:
45
-
46
- - ⭐ **Starring the project** - It helps others discover this adapter
47
- [![GitHub stars](https://img.shields.io/github/stars/oskar-gmerek/surreal-better-auth?style=social)](https://github.com/oskar-gmerek/surreal-better-auth)
48
- - 💖 **[Sponsoring the development](https://github.com/sponsors/oskar-gmerek)** - Even small contributions help maintain and improve the project
49
- [![Sponsor](https://img.shields.io/badge/sponsor-💖-ff69b4)](https://github.com/sponsors/oskar-gmerek)
50
-
51
- Your support helps us maintain and improve this adapter for the entire community.
52
-
53
- ---
54
-
55
- ## 📋 Requirements
24
+ ## Requirements
56
25
 
57
26
  - **Node.js**: >= 20.0.0 or **Bun**: >= 1.2.0
58
27
  - **better-auth**: ^1.3.7
59
- - **surrealdb**: ^1.3.2
28
+ - **surrealdb**: 2.0.0
29
+ - **SurrealDB server**: v3.x
60
30
 
61
31
  ---
62
32
 
63
- ## 🚀 Installation
33
+ ## Installation
64
34
 
65
35
  ```bash
66
- bun add surreal-better-auth
36
+ bun add @imran3113/surreal-better-auth surrealdb better-auth
67
37
  ```
68
38
 
69
39
  ```bash
70
- # Using other package managers
71
- npm install surreal-better-auth
72
- yarn add surreal-better-auth
73
- pnpm add surreal-better-auth
40
+ # Other package managers
41
+ npm install @imran3113/surreal-better-auth surrealdb better-auth
42
+ pnpm add @imran3113/surreal-better-auth surrealdb better-auth
74
43
  ```
75
44
 
76
45
  ---
77
46
 
78
- ## ⚙️ Configuration
79
-
80
- ### Adapter Options
81
-
82
- | Option | Type | Default | Description |
83
- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------- | --------------------------------------------------- |
84
- | `debugLogs` | `boolean` | `false` | Enable detailed logging for debugging |
85
- | `idGenerator` | `sdk.UUIDv4` \| `sdk.UUIDv7` \| `surreal` \| `surreal.ULID` \| `surreal.UUID` \| `surreal.UUIDv4` \| `surreal.UUIDv7` \| `surreal.guid` \| `undefined` | `undefined` | ID generation strategy (see ID Configuration below) |
86
- | `usePlural` | `boolean` | `false` | Use plural table names (e.g., `users` vs `user`) |
87
- | `allowPassingId` | `boolean` | `false` | Allow passing custom IDs when creating records |
47
+ ## Quick Start
88
48
 
89
- ### ID Configuration Options
49
+ ### 1. Set up SurrealDB connection
90
50
 
91
- You can configure ID generation in two ways:
51
+ ```ts
52
+ // lib/db.ts
53
+ import { Surreal } from "surrealdb";
92
54
 
93
- #### 1. Via Adapter Configuration
55
+ const db = new Surreal();
56
+ await db.connect("ws://localhost:8000");
57
+ await db.use({ namespace: "myapp", database: "production" });
94
58
 
95
- | `idGenerator` Value | Generated By | Description |
96
- | ------------------- | ------------ | ---------------------------------------------------------------------------- |
97
- | `"sdk.UUIDv4"` | Better Auth | Better Auth generates UUID via SurrealDB JS SDK function `Uuid.v4()` |
98
- | `"sdk.UUIDv7"` | Better Auth | Better Auth generates UUID via SurrealDB JS SDK function `Uuid.v7()` |
99
- | `"surreal"` | Database | SurrealDB generates `default` SurrealDB ID |
100
- | `"surreal.guid"` | Database | SurrealDB generates 20 digit alphanumeric `GUID` |
101
- | `"surreal.ULID"` | Database | SurrealDB generates `ULID` |
102
- | `"surreal.UUID"` | Database | SurrealDB generates default version `UUID` (currently v7) |
103
- | `"surreal.UUIDv4"` | Database | SurrealDB generates `UUID v4` (random-based, most common) |
104
- | `"surreal.UUIDv7"` | Database | SurrealDB generates `UUID v7` (time-based, sortable) |
105
- | `undefined` | Better Auth | Better Auth generates ID (`default`, or generated via `generateId` function) |
59
+ export { db };
60
+ ```
106
61
 
107
- #### 2. Via Better-Auth Advanced Configuration
62
+ ### 2. Configure Better Auth with the adapter
108
63
 
109
- ```typescript
64
+ ```ts
110
65
  // lib/auth.ts
66
+ import { betterAuth } from "better-auth";
67
+ import { surrealdbAdapter } from "@imran3113/surreal-better-auth";
68
+ import { db } from "./db";
69
+
111
70
  export const auth = betterAuth({
112
- database: surrealAdapter(db, {
113
- idGenerator: "surreal.UUIDv4", // This will be ignored, when generateId is provided!
71
+ database: surrealdbAdapter(db, {
72
+ idGenerator: "surreal.ULID", // recommended for v3
114
73
  }),
115
- advanced: {
116
- database: {
117
- generateId() {
118
- return "custom_" + Math.random().toString(36).substr(2, 9);
119
- },
120
- },
121
- },
74
+ emailAndPassword: { enabled: true },
122
75
  });
123
76
  ```
124
77
 
125
- ### ID Generation Precedence
78
+ ### 3. Generate and apply schema
126
79
 
127
- The ID generation follows this priority order:
80
+ ```bash
81
+ bunx @better-auth/cli generate --output schema.surql
82
+ ```
128
83
 
129
- 1. **`advanced.database.generateId()`** - Highest priority, overrides everything
130
- 2. **`idGenerator`** - Used only if `generateId()` is not defined
131
- 3. **Custom ID from data** - Used if `allowPassingId` is `true` and ID is provided in the data
132
- 4. **Better Auth default** - Used if `allowPassingId` is `true` and ID is NOT provided in the data
133
- 5. **Database default ID** - Used as fallback when all above conditions are not met, database generates default ID (same as setting `idGenerator: 'surreal'`)
84
+ Apply the schema to SurrealDB via [Surrealist](https://surrealist.app/) or CLI import **before** running the application.
85
+
86
+ ```bash
87
+ surreal import --conn ws://localhost:8000 --user root --pass root \
88
+ --ns myapp --db production schema.surql
89
+ ```
134
90
 
135
91
  ---
136
92
 
137
- ## 🏃‍♂️ Quick Start
93
+ ## Configuration
138
94
 
139
- ### 1. Set up your SurrealDB connection
95
+ ### Adapter Options
140
96
 
141
- ```typescript
142
- // lib/db.ts
143
- import Surreal from "surrealdb";
97
+ | Option | Type | Default | Description |
98
+ |---|---|---|---|
99
+ | `idGenerator` | `IdGenerator` | `undefined` | ID generation strategy (see below) |
100
+ | `usePlural` | `boolean` | `false` | Use plural table names (`users` vs `user`) |
101
+ | `allowPassingId` | `boolean` | `false` | Allow passing custom IDs when creating records |
102
+ | `debugLogs` | `boolean \| object` | `false` | Enable SurrealQL query logging |
103
+
104
+ ### ID Generation Strategies
105
+
106
+ | Value | Generated By | Description |
107
+ |---|---|---|
108
+ | `"surreal.ULID"` | Database | ULID — sortable, recommended |
109
+ | `"surreal.UUIDv7"` | Database | UUID v7 — time-based, sortable |
110
+ | `"surreal.UUIDv4"` | Database | UUID v4 — random |
111
+ | `"surreal.UUID"` | Database | Default UUID |
112
+ | `"surreal.guid"` | Database | 20-char alphanumeric GUID |
113
+ | `"surreal"` | Database | SurrealDB default ID |
114
+ | `"sdk.UUIDv4"` | JS SDK | UUID v4 via `Uuid.v4()` |
115
+ | `"sdk.UUIDv7"` | JS SDK | UUID v7 via `Uuid.v7()` |
116
+ | `undefined` | Better Auth | Better Auth default or `generateId` |
144
117
 
145
- const db = new Surreal();
146
- await db.connect("ws://localhost:8000");
147
- await db.use({ namespace: "production", database: "myapp" });
118
+ ### ID Generation Precedence
148
119
 
149
- export { db };
150
- ```
120
+ 1. **`advanced.database.generateId()`** — Highest priority, overrides everything
121
+ 2. **`idGenerator`** — Used if `generateId()` is not defined
122
+ 3. **Custom ID from data** — Used if `allowPassingId: true` and ID is provided
123
+ 4. **Better Auth default** — Used if `allowPassingId: true` and no ID in data
124
+ 5. **Database default** — Fallback (same as `idGenerator: "surreal"`)
125
+
126
+ ---
151
127
 
152
- ### 2. Configure better-auth with the SurrealDB adapter
128
+ ## Advanced Configuration
153
129
 
154
- ```typescript
130
+ ```ts
155
131
  // lib/auth.ts
156
132
  import { betterAuth } from "better-auth";
157
- import { surrealAdapter } from "surreal-better-auth";
133
+ import { surrealdbAdapter } from "@imran3113/surreal-better-auth";
158
134
  import { db } from "./db";
159
135
 
160
136
  export const auth = betterAuth({
161
- database: surrealAdapter(db),
162
- emailAndPassword: {
163
- enabled: true,
137
+ database: surrealdbAdapter(db, {
138
+ idGenerator: "surreal.ULID",
139
+ usePlural: false,
140
+ allowPassingId: true,
141
+ debugLogs: true,
142
+ }),
143
+ emailAndPassword: { enabled: true },
144
+ plugins: [
145
+ // All Better Auth plugins are supported
146
+ ],
147
+ });
148
+ ```
149
+
150
+ ### Granular Debug Logging
151
+
152
+ ```ts
153
+ surrealdbAdapter(db, {
154
+ debugLogs: {
155
+ create: true,
156
+ findOne: true,
157
+ findMany: false,
158
+ update: true,
159
+ updateMany: false,
160
+ delete: false,
161
+ deleteMany: false,
162
+ count: false,
164
163
  },
165
- socialProviders: {
166
- github: {
167
- clientId: process.env.GITHUB_CLIENT_ID!,
168
- clientSecret: process.env.GITHUB_CLIENT_SECRET!,
164
+ });
165
+ ```
166
+
167
+ ### Custom ID Generator
168
+
169
+ ```ts
170
+ export const auth = betterAuth({
171
+ database: surrealdbAdapter(db, {
172
+ idGenerator: "surreal.ULID", // Ignored when generateId is provided
173
+ }),
174
+ advanced: {
175
+ database: {
176
+ generateId: () => "custom_" + Math.random().toString(36).substr(2, 9),
169
177
  },
170
178
  },
171
179
  });
172
180
  ```
173
181
 
174
- ### 3. Use in your application
182
+ ---
183
+
184
+ ## SurrealDB v3 Notes
185
+
186
+ This adapter handles all SurrealDB v3 breaking changes automatically:
187
+
188
+ - **`DEFINE FIELD id` is invalid** — The `id` field is auto-managed; the schema generator omits it
189
+ - **`DEFINE INDEX ... COLUMNS id` is invalid** — Record IDs are inherently unique; no index needed
190
+ - **Non-existent tables throw errors** — Always apply schema before running the application
191
+ - **`type::thing()` renamed to `type::record()`** — The adapter uses `type::record()` internally
192
+ - **Hyphenated IDs are escaped** — `user:my-id` becomes `user:⟨my-id⟩`; prefer ULID/UUID generators
193
+
194
+ ---
175
195
 
176
- Example for [SvelteKit](https://svelte.dev/)
196
+ ## SvelteKit Example
177
197
 
178
- ```typescript
198
+ ```ts
179
199
  // src/hooks.server.ts
180
200
  import { auth } from "$lib/auth";
181
201
  import { svelteKitHandler } from "better-auth/svelte-kit";
182
- import { building } from "$app/environment";
183
202
 
184
- export const handle: Handle = async ({ event, resolve }) => {
185
- return svelteKitHandler({ event, resolve, auth, building });
186
- };
203
+ export const handle = ({ event, resolve }) =>
204
+ svelteKitHandler({ event, resolve, auth });
187
205
  ```
188
206
 
189
- ```typescript
207
+ ```ts
190
208
  // src/lib/auth-client.ts
191
209
  import { createAuthClient } from "better-auth/client";
192
210
 
193
211
  export const authClient = createAuthClient({
194
- baseURL: "http://localhost:5173", // Your app URL
212
+ baseURL: "http://localhost:5173",
195
213
  });
196
214
  ```
197
215
 
198
- ```typescript
199
- // src/routes/+page.svelte
200
- <script lang="ts">
201
- import { authClient } from "$lib/client";
202
- const session = authClient.useSession();
203
- </script>
204
-
205
- <div>
206
- {#if $session.data}
207
- <div>
208
- <p>
209
- {$session?.data?.user.name}
210
- </p>
211
- <button
212
- onclick={async () => {
213
- await authClient.signOut();
214
- }}
215
- >
216
- Sign Out
217
- </button>
218
- </div>
219
- {:else}
220
- <button
221
- onclick={async () => {
222
- await authClient.signIn.social({
223
- provider: "github",
224
- });
225
- }}
226
- >
227
- Continue with GitHub
228
- </button>
229
- {/if}
230
- </div>
231
- ```
232
-
233
216
  ---
234
217
 
235
- ## 🔧 Advanced Configuration
236
-
237
- ```typescript
238
- // lib/auth.ts
239
- import { betterAuth } from "better-auth";
240
- import { surrealdbAdapter } from "surreal-better-auth";
241
- import { db } from "./db";
218
+ ## License
242
219
 
243
- export const auth = betterAuth({
244
- database: surrealdbAdapter(db, {
245
- // Enable debug logging
246
- debugLogs: true,
247
- // Let SurrealDB generate ULID
248
- idGenerator: "surreal.ULID",
249
- // Use singular table names
250
- usePlural: false,
251
- // Allow passing custom IDs
252
- allowPassingId: true,
253
- }),
254
- emailAndPassword: {
255
- enabled: true,
256
- requireEmailVerification: true,
257
- },
258
- socialProviders: {
259
- github: {
260
- clientId: process.env.GITHUB_CLIENT_ID!,
261
- clientSecret: process.env.GITHUB_CLIENT_SECRET!,
262
- },
263
- google: {
264
- clientId: process.env.GOOGLE_CLIENT_ID!,
265
- clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
266
- },
267
- },
268
- plugins: [
269
- // Add any better-auth plugins here and configure them as usual.
270
- ],
271
- });
272
- ```
220
+ MIT
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@imran3113/surreal-better-auth",
3
3
  "description": "SurrealDB adapter for Better Auth",
4
- "version": "0.1.0",
4
+ "version": "0.1.2",
5
5
  "author": {
6
6
  "name": "cellograph",
7
7
  "github": "https://github.com/cellograph"