Nuxt SurrealDB

一个旨在简化 SurrealDB 使用的 Nuxt 模块。

快速设置

将模块安装到您的 Nuxt 应用程序中

npx nuxi module add nuxt-surrealdb

然后编辑您的默认数据库预设并在您的 Nuxt 应用程序中使用 Nuxt SurrealDB ✨

功能

📦 自定义数据库预设，以便能够在可组合/每个函数的基础上使用多个数据库。
🚀 自定义内置的 $surrealFetch 和 useSurrealFetch，分别基于 $fetch 和 useFetch。
⚡️ 内置支持通过 $surrealRPC 和 useSurrealRPC 使用 RPC 端点。
🏗️ 内置 Nuxt 服务器 useSurrealRPC 实用程序，具有服务器端私有 DB 预设，用于与 SurrealDB 进行私有网络通信。
💡 每个 RPC 方法都映射到一个 useSurrealDB 导出的函数。
🌟 内置支持使用 useSurrealWS 可组合组件通过 Websockets 与 RPC 方法进行通信。

数据库预设

可以通过 nuxt.config.ts 或 .env 自定义 default 预设或定义您自己的数据库预设。

!注意将变量传递给自定义预设（例如下面的 shop）时，务必在 nuxt.config.ts 中将其初始化为空对象

NUXT_PUBLIC_SURREALDB_DATABASES_SHOP_HOST="https://example.com"
NUXT_PUBLIC_SURREALDB_DATABASES_SHOP_WS="wss://example.com"
NUXT_PUBLIC_SURREALDB_DATABASES_SHOP_NS="surrealdb"
NUXT_PUBLIC_SURREALDB_DATABASES_SHOP_DB="docs"
NUXT_PUBLIC_SURREALDB_DATABASES_SHOP_SC="user"

# To add authentication server side (this does not override the client's token)
# As a Bearer
NUXT_SURREALDB_DATABASES_SHOP_AUTH="mySuperLongBearerToken"
# Or as an object
NUXT_SURREALDB_DATABASES_SHOP_AUTH_USER="root"
NUXT_SURREALDB_DATABASES_SHOP_AUTH_PASS="root"

export default defineNuxtConfig({
  modules: ['nuxt-surrealdb'],
  surrealdb: {
    databases: {
      default: {
        host: 'https://example.com',
        ws: 'wss://example.com',
        NS: 'production',
        DB: 'website'
      },

      crm: {
        host: 'https://crm.example.com',
        ws: 'wss://crm.example.com',
        NS: 'demo',
        DB: 'crm',
        // The following auth example is exposed client side!
        auth: 'mySuperLongBearerToken'
      },

      shop: {},
    },
    server: { // the following add auth only server side
      databases: {
        default: {
          auth: '', // then edit it via NUXT_SURREALDB_DATABASES_DEFAULT_AUTH
          // OR
          auth: {
            user: '', // then edit it via NUXT_SURREALDB_DATABASES_DEFAULT_AUTH_USER
            pass: '' // then edit it via NUXT_SURREALDB_DATABASES_DEFAULT_AUTH_PASS
          }
        }
      }
    }
  },
  // To change a db preset during development it is best to do the following
  $development: {
    surrealdb: {
      databases: {
        default: {
          host: 'https://127.0.0.1:8000',
          ws: 'ws://127.0.0.1:8000'
        }
      }
    }
  },
  // ...
})

!注意如果您希望在开发和生产环境之间使用不同的 db 预设，请像上面示例中那样在您的 nuxt.config.ts 中使用 Nuxt 原生的 $development 和 $production 属性。

还可以扩展或更改服务器端数据库属性（如上面的 surrealdb.server.databases.default.auth）。这对于更传统的数据库身份验证方法特别有用，无需在客户端公开凭据或在私有网络中使用不同的 host 地址。

然后，要使用数据库预设，您只需在每个主要可组合组件的最后一个参数中设置它即可（从 useSurrealDB 解构的函数也支持此覆盖）。

// all the functions destructured will be executed against the CRM database
const { query, select } = useSurrealDB({
  database: 'crm',
})

// only the following select will be made against the default database
const { data } = await select('products', {
  database: 'default',
})

// you could also define a one-time only preset
const { data } = await sql(
  'SELECT * FROM products WHERE price < $maxPrice;',
  { maxPrice: 500 },
  {
    database: {
      host: 'https://surrealdb.example.com',
      NS: 'demo',
      DB: 'shop',
    },
  },
)

RPC 方法

主要的 useSurrealDB 导出许多直接与 RPC 端点通信的函数。每个函数都有两个变体，一个以 $ 开头，一个不以 $ 开头。第一个基于 $surrealRPC，它提供普通函数，而第二个使用 useSurrealRPC，利用 useSurrealFetch（因此，useFetch）。

以下是完整列表

const {
  authenticate, // $authenticate
  create,       // $create
  delete,       // $delete
  info,         // $info
  insert,       // $insert
  invalidate,   // $invalidate
  merge,        // $merge
  patch,        // $patch
  query,        // $query
  remove,       // $remove
  select,       // $select
  signin,       // $signin
  signup,       // $signup
  sql,          // $sql
  update,       // $update
  version,      // $version
} = useSurrealDB()

!注意 sql 方法是 query 的别名，而 version 使用其 HTTP 端点。

useSurrealWS 可组合组件公开了 Websocket 连接以处理与 SurrealDB 的实时通信。它在后台使用 @vueuse/core 中的 useWebsocket，这意味着默认情况下 SSR、自动连接和自动断开连接会自动处理。数据在输入和 data 返回中都从 JSON 自动解析为 string。如果可用，在 Websocket 连接时，它将获取先前用户登录的任何身份验证令牌。数据库预设和 Websocket 选项可作为可组合组件的主要参数使用。

以下是可组合组件 Websocket 提供的主要方法列表

const {
  authenticate,
  close,
  create,
  data,
  set,      // alias for `let`
  info,
  insert,
  invalidate,
  kill,
  let,
  live,
  merge,
  open,
  patch,
  query,
  remove,
  rpc,
  select,
  send,
  signin,
  signup,
  sql,      // alias for `query`
  status,
  unset,
  update,
  use,
  ws,
} = useSurrealWS()

!警告当前，虽然 signin 和 signup 方法可用，但它们仅限于当前的 Websocket 连接。因此，如果在该 websocket 连接之外需要身份验证，建议使用主要 useSurrealAuth 可组合组件进行 SCOPE 用户身份验证。

贡献

本地开发

# Install dependencies
npm install

# Generate type stubs
npm run dev:prepare

# Develop with the playground
npm run dev

# Build the playground
npm run dev:build

# Run ESLint
npm run lint

# Run Vitest
npm run test
npm run test:watch

# Release new version
npm run release

nuxt-surrealdb

Nuxt SurrealDB

快速设置

功能

数据库预设

RPC 方法

RPC Websocket

贡献