docs: document functionalities

Author: sandros94

docs/content/1.getting-started/1.index.md

@@ -26,4 +26,4 @@ There are available a number of client composables and server utilities. Used in
 
 ### Server-Side
 
-- `defineReactiveWSHandler`: wraps Nitro's `defineWebSocketHandler` to provide additional configuration, hooks and automatic topic subscription.
+- `defineWSHandler`: wraps Nitro's `defineWebSocketHandler` to provide additional configuration, hooks and automatic topic subscription.

docs/content/2.usage/1.topics.md

@@ -0,0 +1,141 @@
+---
+title: useWS
+description: The all-in-one composable to manage reactive WebSocket connections from client-side.
+navigation.icon: i-lucide-smartphone-nfc
+---
+
+The `useWS` will be the main composable to manage WebSocket connections client-side. It automatically manage the states of the subscribed topics and the connection itself.
+
+Used in conjunction with [`defineWSHandler`](/usage/defineWSHandler) and [runtime configuration](/getting-started/configuration), it will provide a seamless experience for real-time communication as simple as doing `const { states, send } = useWS()`.
+
+## Arguments
+
+It only accepts two arguments, both of them optional.
+
+### `topics`
+
+An array of strings representing the topics to subscribe to. These should not include those defined in your runtime configuration.
+
+```ts
+const { states, send } = useWS(['session', 'info'])
+```
+
+### `options`
+
+An optional object to override the default options for the WebSocket connection.
+
+::field-group
+  ::field{name="route" type="string"}
+    Defines the default route for `useWS` to connect to the WebSocket server. - Default to runtime configuration
+  ::
+
+  ::field{name="heartbeat" type="boolean | object"}
+    Enables or disables the heartbeat mechanism. If an object is provided, it is possible to define the interval and the message to send. - Default to `false`
+  ::
+
+  ::field{name="autoReconnect" type="boolean | object"}
+    Enables or disables the auto-reconnect mechanism. If an object is provided, it is possible to define the interval and the maximum number of attempts. - Default to `false`
+  ::
+
+  ::field{name="immediate" type="boolean"}
+    The connection will be established immediately. - Default to `true`
+  ::
+
+  ::field{name="autoConnect" type="boolean"}
+    Automatically connect to the websocket when `route` changes. - Default to `true`
+  ::
+
+  ::field{name="autoClose" type="boolean"}
+    Automatically close the websocket when the component is unmounted. - Default to `true`
+  ::
+
+  ::field{name="protocols" type="string[]"}
+    An array of strings representing the sub-protocols to use. - Default to `[]`
+  ::
+::
+
+## Returns
+
+It returns a number of properties and methods to manage the WebSocket connection and the subscribed topics.
+
+### `states`
+
+A reactive object containing the states of all the subscribed topics.
+
+```ts
+const { states, send } = useWS<{
+  session: {
+    users: number
+  }
+}>(['session'])
+
+console.log(states.session.users)
+```
+
+### `send`
+
+A function to send messages to the WebSocket server. It can accept multiple arguments, based on use-case, but always returns a boolean indicating if the message was sent successfully.
+
+- `send(payload: string | ArrayBuffer | Blob): boolean`
+- `send(type: 'subscribe' | 'unsubscribe', topic: string): boolean`
+- `send(type: 'publish', topic: string, payload: any): boolean`
+
+The last two methods will always be transformed to string before being sent to the server.
+
+```ts
+const { states, send } = useWS<{
+  chat: {
+    user?: string,
+    text: string,
+  }[]
+}>(['chat'])
+
+const file = new Blob(['Hello, World!'], { type: 'text/plain' })
+send(file)
+
+send('publish', 'chat', { text: 'Hello, World!' })
+```
+
+::note
+Sending a `payload` directly without specifying the type and topic will send them as is and will not be automatically handled server-side.
+
+By contrast, specifying the type and topic will be handled automatically by the server if [`defineWSHandler`](/usage/defineWSHandler) is used and the target is not an internal topic.
+::
+
+### `data`
+
+A ref containing any extra data received from the server and not handled by `states` automatically.
+
+```ts
+const { data } = useWS()
+
+// server sends 'Hello, World!' directly without publishing to a topic
+
+console.log(data.value) // 'Hello, World!'
+```
+
+### `status`
+
+A ref containing the current status of the WebSocket connection.
+
+```ts
+const { status } = useWS()
+
+console.log(status.value) // 'OPEN' | 'CONNECTING' | 'CLOSED'
+```
+
+### `open`/`close`
+
+Methods to manually open and close the WebSocket connection.
+
+### Internals
+
+The following properties and methods are considered internal and should not be used directly. I decided to expose them for debugging purposes or advanced use-cases.
+
+- `ws`: The WebSocket instance.
+- `_data`: It contains any raw data received from the server.
+- `_send`: It is used under the hood to send messages to the server.
+
+## Type Support
+
+As you might have noticed in the examples above, `useWS` accepts a type parameter. This is to provide type support for the states object.

docs/content/2.usage/1.useWS.md

@@ -0,0 +1,81 @@
+---
+title: defineWSHandler
+description: The all-in-one utility to manage reactive WebSocket connections from server-side.
+navigation.icon: i-lucide-arrow-left-right
+---
+
+The `defineWSHandler` will be the main utility to manage WebSocket connections server-side. It handles automatically the subscription of topics defined in the runtime configuration while also proving a hooking system to trigger messages globally from other part of the application server-side.
+
+::callout{icon="i-lucide-triangle-alert" color="warning" to="https://nitro.build/guide/websocket#usage" _target="blank"}
+Please first read the upstream Nitro documentation on `defineWebSocketHandler` to understand the basic usage.
+::
+
+## Example
+
+```ts [/server/routes/_ws.ts]
+import * as v from 'valibot'
+
+export default defineWSHandler({
+  async open(peer) {
+    // Update peer with 'chat' data from storage
+    const chat = await useStorage('ws').getItem('chat')
+    if (chat)
+      peer.send(JSON.stringify({
+        topic: 'chat',
+        payload: chat,
+      }), { compress: true })
+
+    // Update everyone's session metadata
+    const payload = JSON.stringify({ topic: 'session', payload: { users: peer.peers.size } })
+    peer.send(payload, { compress: true })
+    peer.publish('session', payload, { compress: true })
+  },
+
+  async message(peer, message) {
+    // Validate the incoming chat message
+    const parsedMessage = await wsValidateMessage( // built-in validation util
+      v.object({
+        type: v.literal('publish'),
+        topic: v.literal('chat'),
+        payload: v.object({ text: v.string() }),
+      }),
+      message,
+    )
+
+    // Update chat data in storage
+    const mem = useStorage('ws')
+    const { topic, payload } = parsedMessage
+    const _chat = await mem.getItem<Array<{ user: string, text: string }>>('chat') || []
+    const newChat = [..._chat, { ...payload, user: peer.id }]
+    await mem.setItem(topic, newChat)
+
+    // Broadcast the updated chat to everyone
+    peer.send(JSON.stringify({ topic, payload: newChat }), { compress: true })
+    peer.publish(topic, JSON.stringify({ topic, payload: newChat }), { compress: true })
+  },
+
+  close(peer) {
+    // Update everyone's session metadata
+    peer.publish(
+      'session',
+      JSON.stringify({
+        topic: 'session',
+        payload: {
+          users: peer.peers.size,
+        },
+      }),
+      { compress: true },
+    )
+  },
+})
+```
+
+## Parsing messages
+
+A small `wsParseMessage` utility is provided to parse JSON content from incoming messages. This uses [`destr`](https://github.com/unjs/destr) under the hood to parse the message and not throw an error if the message is not a valid JSON string.
+
+This is also used under the hood by [validation utilities](/usage/validation).
+
+## Authentication
+
+You can easily validate user's sessions with modules like `nuxt-auth-utils` as described in [the documentation](https://github.com/atinux/nuxt-auth-utils?tab=readme-ov-file#websocket-support).

docs/content/2.usage/2.defineWSHandler.md

@@ -0,0 +1,106 @@
+---
+title: Validation
+description: Validation utils for incoming messages from the client.
+navigation.icon: i-lucide-hammer
+---
+
+Two validation utilities are available server-side to validate incoming messages from the client. They are based on [Standard Schema](https://github.com/standard-schema/standard-schema), allowing you to use your preferred validation library.
+
+- `wsValidateMessage`
+- `wsSafeValidateMessage`
+
+## `wsValidateMessage`
+
+Validates a WebSocket message against a given schema. If the message is invalid, the function throws an error with the validation issues. Otherwise, it returns the validated message. If the message is a Message object, it's parsed with [`wsParseMessage`](/usage/definewshandler#parsing-message) before validation.
+
+::code-group
+
+```ts [valibot]
+import * as v from 'valibot'
+
+message(peer, message) {
+  const parsedMessage = await wsValidateMessage(
+    v.object({
+      type: v.picklist(['subscribe', 'unsubscribe']),
+      topic: v.picklist(['chat', 'notifications']),
+    }),
+    message,
+  )
+
+  // or directly the incoming message type
+  const blob = await wsValidateMessage(v.blob(), message.blob())
+  const helloWorld = await wsValidateMessage(v.literal('Hellow World'), message.text())
+}
+```
+
+```ts [zod]
+import { z } from 'zod'
+
+message(peer, message) {
+  const parsedMessage = await wsValidateMessage(
+    z.object({
+      type: z.enum(['subscribe', 'unsubscribe']),
+      topic: z.enum(['chat', 'notifications']),
+    }),
+    message,
+  )
+
+  // or directly the incoming message type
+  const blob = await wsValidateMessage(z.blob(), message.blob())
+  const helloWorld = await wsValidateMessage(z.literal('Hellow World'), message.text())
+}
+```
+
+::
+
+## `wsSafeValidateMessage`
+
+Same as `wsValidateMessage`, but instead of throwing an error, it returns an object with the validation issues if the message is invalid. Otherwise, it returns the validated message.
+
+::code-group
+
+```ts [valibot]
+import * as v from 'valibot'
+
+message(peer, message) {
+  const parsedMessage = await wsSafeValidateMessage(
+    v.object({
+      type: v.picklist(['subscribe', 'unsubscribe']),
+      topic: v.picklist(['chat', 'notifications']),
+    }),
+    message,
+  )
+
+  if (parsedMessage.issues) {
+    console.error('WebSocket:', peer.id, parsedMessage.issues)
+    peer.send(JSON.stringify({
+      topic: '_internal', // Assuming being used
+      message: `Invalid message: ${parsedMessage.issues}`
+    }))
+  }
+  // else do something with parsedMessage.value
+}
+```
+
+```ts [zod]
+import { z } from 'zod'
+
+message(peer, message) {
+  const parsedMessage = await wsSafeValidateMessage(
+    z.object({
+      type: z.enum(['subscribe', 'unsubscribe']),
+      topic: z.enum(['chat', 'notifications']),
+    }),
+    message,
+  )
+
+  if (parsedMessage.issues) {
+    console.error('WebSocket:', peer.id, parsedMessage.issues)
+    peer.send(JSON.stringify({
+      topic: '_internal', // Assuming being used
+      message: `Invalid message: ${parsedMessage.issues}`
+    }))
+  }
+  // else do something with parsedMessage.value
+}
+```

docs/content/2.usage/3.validation.md

@@ -0,0 +1,55 @@
+---
+title: Topics
+description: Automatic topic subscriptions and reactive shared state management.
+navigation.icon: i-lucide-messages-square
+---
+
+Both `useWS` for the client and `defineWSHandler` for the server handle automatic topic subscriptions. This means that when a connection is established, the client will automatically subscribe to the topics defined in the runtime configuration. The server can then publish messages to these topics, and the client will receive them.
+
+`useWS` also accept the topic parameter as a reactive array. This allows to automatically and dynamically subscribe and unsubscribe to topics after the connection is established.
+
+## Example
+
+```vue
+<template>
+  <div>
+    <div>
+      <ul>
+        <li v-for="topic in availableTopics" :key="topic">
+          <label>
+            <input type="checkbox" v-model="topics" :value="topic" />
+            {{ topic }}
+          </label>
+        </li>
+      </ul>
+    </div>
+    <div v-if="states['chat']">
+      <div v-for="(message, key) in states['chat']" :key>
+        <strong>{{ message.user }}</strong>: {{ message.text }}
+      </div>
+    </div>
+    <div v-if="states['notifications']">
+      {{ notification.message }}
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+const availableTopics = ref(['chat', 'notifications'])
+const topics = ref(['chat'])
+
+const { states, send } = useWS<{
+  chat?: {
+    user?: string,
+    text: string,
+  }[],
+  notifications?: {
+    message: string,
+  },
+}>(topics)
+</script>
+```
+
+::note
+Make sure to type any dynamic topic as optional, as they might not be available.
+::