chore: init docs

.gitignore

@@ -66,3 +66,5 @@ Temporary Items
 .apdisk
 
 # Project specific
+docs/.vitepress/dist
+docs/.vitepress/cache

docs/.vitepress/config.ts

@@ -0,0 +1,55 @@
+import { defineConfig } from 'vitepress'
+
+const guide = {
+  text: 'Guide',
+  items: [
+    { text: 'Getting Started', link: '/getting-started' },
+    { text: 'Database Presets', link: '/database-presets' },
+  ],
+}
+
+const methods = {
+  text: 'RPC Methods',
+  items: [
+    {
+      text: '',
+      items: [
+        { text: 'All RPC Methods', link: '/rpc-methods' },
+      ],
+    },
+    {
+      text: '',
+      items: [
+        { text: 'All WS Methods', link: '/ws-methods' },
+      ],
+    },
+  ],
+}
+
+// https://vitepress.dev/reference/site-config
+export default defineConfig({
+  title: 'Nuxt SurrealDB',
+  description: 'A Nuxt module aimed to simplify the use of SurrealDB.',
+  cleanUrls: true,
+  themeConfig: {
+    // https://vitepress.dev/reference/default-theme-config
+    nav: [
+      guide,
+      methods,
+    ],
+
+    sidebar: [
+      guide,
+      methods,
+    ],
+
+    footer: {
+      message: 'Released under MIT License.',
+      copyright: 'Copyright © 2024 Sandro Circi',
+    },
+
+    socialLinks: [
+      { icon: 'github', link: 'https://github.com/sandros94/nuxt-surrealdb' },
+    ],
+  },
+})

docs/.vitepress/theme/custom.css

@@ -0,0 +1,6 @@
+/* .vitepress/theme/custom.css */
+:root {
+  --vp-c-brand-1: #f73bc6 !important;
+  --vp-c-brand-2: #d134bb !important;
+  --vp-c-brand-3: #731dc5 !important;
+}

docs/.vitepress/theme/index.js

@@ -0,0 +1,5 @@
+// .vitepress/theme/index.js
+import DefaultTheme from 'vitepress/theme'
+import './custom.css'
+
+export default DefaultTheme

docs/database-presets.md

@@ -0,0 +1,175 @@
+# Database Presets
+
+You can define as many Database Presets as you want, both editable at runtime via `nuxt.config.ts` or via `.env`.
+
+## Basic Usage
+
+Database Presets are available under `surrealdb.databases` inside your `nuxt.config.ts`. Each preset will use the default database as the the starting point (using [`defu`](https://github.com/unjs/defu) under the hood).
+
+```ts
+export default defineNuxtConfig({
+  modules: ['nuxt-surrealdb'],
+  surrealdb: {
+    databases: {
+      default: {
+        host: 'https://example.com',
+        ws: 'wss://example.com',
+        NS: 'production',
+        DB: 'example',
+      },
+
+      website: {
+        DB: 'website',
+      },
+
+      crm: {
+        host: 'https://crm.example.com',
+        ws: 'wss://crm.example.com',
+        NS: 'demo',
+        DB: 'crm',
+        // The following bearer auth is exposed client side!
+        auth: 'mySuperLongBearerToken',
+      },
+
+      shop: {
+        host: '', // initialize any property that will be set via `.env`
+        ws: '',
+        NS: '',
+        DB: '',
+      },
+    },
+  },
+})
+```
+
+```dotenv
+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"
+```
+
+::: tip
+When editing variables via `.env` to a custom preset, like the `shop` preset above, it is important to initialize any parameter as an empty string inside your `nuxt.config.ts`.
+:::
+
+### Database Presets for development
+
+If you want to use different Database Presets between development and production, please use Nuxt's native [`$development` and `$production` properties](https://nuxt.com/docs/getting-started/configuration#environment-overrides) within your `nuxt.config.ts` like in the example below.
+
+```ts
+export default defineNuxtConfig({
+  modules: ['nuxt-surrealdb'],
+  surrealdb: {
+    databases: {
+      default: {
+        host: 'https://example.com',
+        ws: 'wss://example.com',
+        NS: 'production',
+        DB: 'example',
+      },
+    },
+  },
+  $development: {
+    surrealdb: {
+      databases: {
+        default: {
+          host: 'http://localhost:8000',
+          ws: 'ws://localhost:8000',
+          NS: 'development',
+        }
+      }
+    }
+  },
+  // ...
+})
+```
+
+## Set a Preset as the Default Database
+
+It is also possible to set a particular Preset as the Default Database, with the ability to set a different one between client and server side.
+
+```ts
+export default defineNuxtConfig({
+  modules: ['nuxt-surrealdb'],
+  surrealdb: {
+    defaultDatabase: 'website',
+    databases: {
+      default: {
+        host: 'https://example.com',
+        ws: 'wss://example.com',
+        NS: 'production',
+        DB: 'example',
+      },
+      website: {
+        DB: 'website',
+      }
+    }
+  }
+})
+```
+
+## Server-Side Database Presets
+
+It is also possible to expand or change preset properties to be available only server-side. This becomes particularly useful for a more traditional database auth approach without exposing credentials client-side or to use a different `host` address in a private network. Server-Side Presets are availbale under `surrealdb.server.databases` (or `runtimeConfig.surrealdb.databases`) inside your `nuxt.config.ts`.
+
+```ts
+export default defineNuxtConfig({
+  modules: ['nuxt-surrealdb'],
+  surrealdb: {
+    databases: {
+      default: {
+        host: 'https://example.com',
+        ws: 'wss://example.com',
+        NS: 'production',
+        DB: 'example',
+      },
+    },
+    server: {
+      databases: {
+        default: {
+          auth: {
+            user: '', // then edit it via .env
+            pass: '', // then edit it via .env
+          },
+        },
+      },
+    },
+  },
+})
+```
+
+```dotenv
+NUXT_SURREALDB_DATABASES_SHOP_AUTH_USER="root"
+NUXT_SURREALDB_DATABASES_SHOP_AUTH_PASS="password"
+```
+
+## Using Database Presets
+
+To use any of your Database Preset you just have to set it within the last parameter of each main composable (functions destructured from `useSurrealDB` also support this override).
+
+```ts
+// 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',
+    },
+  },
+)
+```

docs/getting-started.md

@@ -0,0 +1,42 @@
+# Getting Started
+
+This page demonstrates how to get started with the `nuxt-surrealdb` module.
+
+## Quick Setup
+
+Install the module to your Nuxt application:
+
+```bash
+npx nuxi module add nuxt-surrealdb
+```
+
+Then edit the `default` Database Preset inside your `nuxt.config.ts`
+
+```ts
+export default defineNuxtConfig({
+  modules: ['nuxt-surrealdb'],
+  surrealdb: {
+    databases: {
+      default: {
+        host: 'https://example.com',
+        ws: 'wss://example.com',
+        NS: 'example',
+        DB: 'example',
+      },
+    },
+  },
+})
+```
+
+## Environmental variables
+
+Instead of hardcoding a Database preset inside the `nuxt.config.ts` you can edit it via env variables at runtime:
+
+```dotenv
+NUXT_PUBLIC_SURREALDB_DATABASES_DEFAULT_HOST="https://example.com"
+NUXT_PUBLIC_SURREALDB_DATABASES_DEFAULT_WS="wss://example.com"
+NUXT_PUBLIC_SURREALDB_DATABASES_DEFAULT_NS="example"
+NUXT_PUBLIC_SURREALDB_DATABASES_DEFAULT_DB="example"
+```
+
+More on this in the dedicated [Database Preset guide](/database-presets).

docs/index.md

@@ -0,0 +1,38 @@
+---
+# https://vitepress.dev/reference/default-theme-home-page
+layout: home
+
+hero:
+  name: "Nuxt SurrealDB"
+  text: "A Nuxt module aimed to simplify the use of SurrealDB."
+  image:
+    src: /surrealdb-logo.png
+    alt: SurrealDB
+  actions:
+    - theme: brand
+      text: Getting Started
+      link: /getting-started
+    - theme: alt
+      text: DB Presets
+      link: /database-presets
+    - theme: alt
+      text: RPC Methods
+      link: /rpc-methods
+    - theme: alt
+      text: View on GitHub
+      link: https://github.com/sandros94/nuxt-surrealdb
+
+features:
+  - title: Custom Database Presets
+    details: Quickly access multiple Namespaces and Databases. Presets can have different properties between client and server side use.
+    icon: 📦
+  - title: Nuxt-optimized fetch composables
+    details: Built-in <b>$surrealFetch</b> and <strong>useSurrealFetch</strong>, based on <strong>$fetch</strong> and <strong>useFetch</strong> respectively.
+    icon: 🚀
+  - title: SurrealDB RPC Methods
+    details: With <strong>$surrealRPC</strong> and <strong>useSurrealRPC</strong> it is possible to directly communicate with SurrealDB's RPC endpoint. Each RPC method is also mapped to a <strong>useSurrealDB</strong> exported function.
+    icon: 🏗️
+  - title: Built-in support for Websockets
+    details: Thanks to <strong>useSurrealWS</strong> a live connection to SurrealDB is automated and augmented via available RPC methods.
+    icon: ⚡️
+---

docs/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "nuxt-surrealdb-docs",
+  "version": "0.0.0",
+  "private": "true",
+  "type": "module",
+  "scripts": {
+    "dev": "vitepress dev",
+    "build": "vitepress build",
+    "preview": "vitepress preview",
+    "serve": "pnpm run build && serve .vitepress/dist"
+  },
+  "devDependencies": {
+    "vitepress": "latest"
+  }
+}

docs/rpc-methods.md

@@ -0,0 +1,29 @@
+# RPC Methods
+
+The main `useSurrealDB` exports a number of functions that directly communicate with the RPC endpoint. Each function has two variants, one starts with `$` and one without. The first is based on `$surrealRPC`, that provides the plain function, while the latter uses `useSurrealRPC`, taking advantage of `useSurrealFetch` (and thus, [`useFetch`](https://nuxt.com/docs/api/composables/use-fetch)).
+
+Here the full list:
+
+```ts
+const {
+  authenticate, // $authenticate
+  create,       // $create
+  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()
+```
+
+:::tip
+`sql` method is an alias for `query` while `version` uses its [HTTP endpoint](https://surrealdb.com/docs/surrealdb/integration/http#version).
+:::