nuxt-surrealdb

SurrealDB の利用を簡素化することを目的とした Nuxt モジュール

Nuxt SurrealDB

SurrealDB の利用を簡素化することを目的とした Nuxt モジュール。

クイックセットアップ

モジュールを Nuxt アプリケーションにインストールします

npx nuxi module add nuxt-surrealdb

次に、デフォルトのデータベースプリセットを編集し、Nuxt アプリで Nuxt SurrealDB を使用します ✨

機能

📦 カスタムデータベースプリセット。コンポーザブル/関数ごとに複数のデータベースを使用できます。
🚀 $fetch と useFetch に基づく、カスタム組み込み $surrealFetch と useSurrealFetch。
⚡️ $surrealRPC と useSurrealRPC を介した RPC エンドポイントの組み込みサポート。
🏗️ SurrealDB とのプライベートネットワーク通信のためのサーバーサイドプライベート DB プリセットを備えた組み込み Nuxt サーバー useSurrealRPC ユーティリティ。
💡 各 RPC メソッドは useSurrealDB エクスポート関数にマップされます。
🌟 useSurrealWS コンポーザブルを使用した RPC メソッドでの Websockets 通信の組み込みサポート。

データベースプリセット

default プリセットをカスタマイズしたり、nuxt.config.ts または .env を介して独自のデータベースプリセットを定義したりできます。

!NOTE 以下に示す 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://:8000',
          ws: 'ws://:8000'
        }
      }
    }
  },
  // ...
})

!NOTE 開発環境と本番環境で異なる 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',
    },
  },
)

主要な useSurrealDB は、RPC エンドポイントと直接通信する多数の関数をエクスポートします。各関数には2つのバリアントがあり、1つは $ で始まり、もう1つはそれなしです。前者はプレーンな関数を提供する $surrealRPC に基づいていますが、後者は useSurrealFetch（したがって useFetch）を利用する useSurrealRPC を使用します。

完全なリストはこちら

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()

!NOTE sql メソッドは query のエイリアスであり、version はその HTTP エンドポイントを使用します。

RPC Websocket

useSurrealWS コンポーザブルは、SurrealDB とのライブ通信を処理するための Websocket 接続を公開します。@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()

!WARNING 現在、signin および signup メソッドは利用可能ですが、現在の Websocket 接続に限定されています。したがって、その Websocket 接続以外で認証が必要な場合は、SCOPE ユーザー認証のためにメインの useSurrealAuth コンポーザブルを使用することをお勧めします。

貢献

ローカル開発

# 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

貢献