feat: rename to useSession, allow partial options via defu (#5)

* feat!: rename useNuxtSession to just useSession (thx, @atinux)

* feat!: make some api options optional, actually rename composable file

* chore: update changelog to point to releases page

Author: BracketJohn

CHANGELOG.md

@@ -1,5 +1,7 @@
 # Changelog
 
+See more recent releases on the releases page: https://github.com/sidebase/nuxt-session/releases
+
 ## 0.1.2 (2022/10/13)
 
 - fix: remove dependency on self

README.md

@@ -9,13 +9,13 @@
 [![Follow us on Twitter](https://badgen.net/badge/icon/twitter?icon=twitter&label)](https://twitter.com/sidebase_io)
 [![Join our Discord](https://badgen.net/badge/icon/discord?icon=discord&label)](https://discord.gg/9MUHR8WT9B)
 
-> Nuxt session middleware to get a persistent session per app user, e.g., to store data across multiple requests. The nuxt session module provides the `useNuxtSession()` composable out of the box and sets up API endpoints to interact with your session to make working with sessions feel like a breeze.
+> Nuxt session middleware to get a persistent session per app user, e.g., to store data across multiple requests. The nuxt session module provides the `useSession()` composable out of the box and sets up API endpoints to interact with your session to make working with sessions feel like a breeze.
 
 ## Quick start
 
 1. Install the package:
     ```bash
-    npm i @sidebase/nuxt-session
+    npm i -D @sidebase/nuxt-session
     ```
 2. Add the package to your `nuxt.config.ts`:
     ```bash
@@ -26,7 +26,7 @@
 3. Done! Each client will now have a unique session you can access on the server- and client side:
     - client-side (from any `.vue` file):
         ```ts
-        const { session, refresh, update, reset } = await useNuxtSession()
+        const { session, refresh, update, reset } = await useSession()
 
         // Reactive session object that updates after methods calls below
         session.value
@@ -51,7 +51,7 @@ The `nuxt-session` library provide many helpers to interact with the session fro
 ## Features
 
 - ✔️ Persistent sessions across requests using cookies
-- ✔️ `useNuxtSession` composable for client side session-interaction
+- ✔️ `useSession` composable for client side session-interaction
 - ✔️ Configurable session endpoints out of the box:
     - `GET /api/session`: Get the current session
     - `DELETE /api/session`: Delete the current session
@@ -120,7 +120,7 @@ const {
   reset,
   update,
   overwrite
-} = await useNuxtSession()
+} = await useSession()
 
 // The session itself, a ref that automatically updates when you use the other methods below
 session.value
@@ -145,7 +145,7 @@ Per default all of the above is enabled. Read on if you want to learn how to con
 
 You can configure what endpoints and utilities `nuxt-session` adds for client-side use using the module configuration. The API is fully enabled per default. If you want to turn off the whole `nuxt-session` API you can set `session: { api: { isEnabled: false } }` in the module config in your `nuxt.config.ts`. If you want to keep the api enabled but allow just certain operation by the client-side, you can restrict the HTTP methods that should be allowed. E.g., `session: { api: { methods: ['get'] } }` would:
 - add only one endpoint that allows reading the current session data (per default: `GET /api/session`)
-- enable only the `session` and `refresh` properties of the `useNuxtSession` composable
+- enable only the `session` and `refresh` properties of the `useSession` composable
 
 After this, calling the `reset()` or `update()` functions from above would result in an error that the methods are not supported and the api endpoints would not be added to your nuxt-app. This way:
 - you cannot accidentaly call a composable-method during development and it later does not work in production,

package-lock.json

@@ -31,6 +31,7 @@
   "dependencies": {
     "@nuxt/kit": "^3.0.0-rc.12",
     "dayjs": "^1.11.5",
+    "defu": "^6.1.0",
     "h3": "^0.8.5",
     "unstorage": "^0.6.0"
   },

package.json

@@ -1,9 +1,9 @@
 <script setup lang="ts">
 import { useFetch } from '#app'
 import { computed, ref } from 'vue'
-import { useNuxtSession } from '#imports'
+import { useSession } from '#imports'
 
-const { session, refresh, reset, remove, update } = await useNuxtSession()
+const { session, refresh, reset, remove, update } = await useSession()
 
 // Counter demo
 const { refresh: increaseCountOnServer } = await useFetch('/api/count', { server: false, immediate: false })
@@ -33,7 +33,7 @@ const value = ref('')
     <hr>
     <div>
       <h3>Counting</h3>
-      <p>With nuxt-session you can either access the current user session safely on the server side using `event.context.session`. You can also use the `update`-method of the `useNuxtSession` composable that allows arbitrary updating of session data from the client-side.</p>
+      <p>With nuxt-session you can either access the current user session safely on the server side using `event.context.session`. You can also use the `update`-method of the `useSession` composable that allows arbitrary updating of session data from the client-side.</p>
       <p>Below both possible options are show-cased. One button triggers a request to the `/api/count` endpoint that increases the request count on the server side. The second button sends a JSON-payload to the nuxt-session API endpoint that allows arbitrary updating of session data with data sent from the client side.</p>
       <p>When you increase the count on the server-side, the session here will not change. You need to hit the `refresh` button above to see the changes! When we update it from the client-side using the nuxt-session composable `update` for it, we immeadiatly see the updates reflected, neat!</p>
       <p>NOTE: The server-side and client-side count update can collide with each other, e.g., if you update the count on the server side a couple of times and then update the count from the client side without refreshing the session. As the client only has the "old" count, it will send a different count than the count that the server currently knows and thus overwrite it.</p>

playground/app.vue

@@ -2,6 +2,7 @@ import { resolve } from 'path'
 import { fileURLToPath } from 'url'
 import { addImportsDir, addServerHandler, defineNuxtModule, useLogger } from '@nuxt/kit'
 import { CreateStorageOptions } from 'unstorage'
+import { defu } from 'defu'
 
 export type SameSiteOptions = 'lax' | 'strict' | 'none'
 export type SupportedSessionApiMethods = 'patch' | 'delete' | 'get' | 'post'
@@ -84,16 +85,32 @@ export interface ModuleOptions {
    * Configure session-behvaior
    * @type SessionOptions
    */
-  session: SessionOptions
+  session: Partial<SessionOptions>
   /**
    * Configure session-api and composable-behavior
    * @type ApiOptions
    */
-  api: ApiOptions
+  api: Partial<ApiOptions>
 }
 
 const PACKAGE_NAME = 'nuxt-session'
 
+const defaults: ModuleOptions = {
+  isEnabled: true,
+  session: {
+    expiryInSeconds: 60 * 10,
+    idLength: 64,
+    storePrefix: 'sessions',
+    cookieSameSite: 'lax',
+    storageOptions: {}
+  },
+  api: {
+    isEnabled: true,
+    methods: [],
+    basePath: '/api/session'
+  }
+}
+
 export default defineNuxtModule<ModuleOptions>({
   meta: {
     name: `@sidebase/${PACKAGE_NAME}`,
@@ -102,48 +119,24 @@ export default defineNuxtModule<ModuleOptions>({
       bridge: false
     }
   },
-  defaults: {
-    isEnabled: true,
-    session: {
-      expiryInSeconds: 60 * 10,
-      idLength: 64,
-      storePrefix: 'sessions',
-      cookieSameSite: 'lax',
-      storageOptions: {}
-    },
-    api: {
-      isEnabled: true,
-      methods: [],
-      basePath: '/api/session'
-    }
-  },
+  defaults,
   hooks: {},
-  setup (options, nuxt) {
+  setup (moduleOptions, nuxt) {
     const logger = useLogger(PACKAGE_NAME)
 
     // 1. Check if module should be enabled at all
-    if (!options.isEnabled) {
+    if (!moduleOptions.isEnabled) {
       logger.info(`Skipping ${PACKAGE_NAME} setup, as module is disabled`)
       return
     }
 
     logger.info('Setting up sessions...')
 
     // 2. Set public and private runtime configuration
-    const moduleOptions = {
-      ...options,
-      api: {
-        ...options.api,
-        methods: options.api.methods.length > 0 ? options.api.methods : ['patch', 'delete', 'get', 'post']
-      }
-    }
-    nuxt.options.runtimeConfig.session = moduleOptions
-    nuxt.options.runtimeConfig.public = {
-      ...(nuxt.options.runtimeConfig.public || {}),
-      session: {
-        api: moduleOptions.api
-      }
-    }
+    const options = defu(moduleOptions, defaults)
+    options.api.methods = moduleOptions.api.methods.length > 0 ? moduleOptions.api.methods : ['patch', 'delete', 'get', 'post']
+    nuxt.options.runtimeConfig.session = defu(nuxt.options.runtimeConfig.session, options)
+    nuxt.options.runtimeConfig.public = defu(nuxt.options.runtimeConfig.public, { session: { api: options.api } })
 
     // 3. Locate runtime directory and transpile module
     const runtimeDir = fileURLToPath(new URL('./runtime', import.meta.url))
@@ -157,12 +150,12 @@ export default defineNuxtModule<ModuleOptions>({
     nuxt.options.serverHandlers.unshift(serverHandler)
 
     // 5. Register desired session API endpoints
-    if (moduleOptions.api.isEnabled) {
-      for (const apiMethod of moduleOptions.api.methods) {
+    if (options.api.isEnabled) {
+      for (const apiMethod of options.api.methods) {
         const handler = resolve(runtimeDir, `server/api/session.${apiMethod}`)
-        addServerHandler({ handler, route: moduleOptions.api.basePath })
+        addServerHandler({ handler, route: options.api.basePath })
       }
-      logger.info(`Session API "${moduleOptions.api.methods.join(', ')}" endpoints registered at "${moduleOptions.api.basePath}"`)
+      logger.info(`Session API "${options.api.methods.join(', ')}" endpoints registered at "${options.api.basePath}"`)
     } else {
       logger.info('Session API disabled')
     }