feat: create shallowSsrRef (#49)

This helper creates a [`shallowRef`](https://vue-composition-api-rfc.netlify.app/api.html#shallowref) (a ref that tracks its own .value mutation but doesn't make its value reactive) that is synced between client & server.

Co-authored-by: Sebastian Krüger <2pi_r2@gmx.de>

docs/.vuepress/config.js

@@ -18,6 +18,7 @@ module.exports = {
           title: 'Helpers',
           collapsable: false,
           children: [
+            '/helpers/shallowSsrRef',
             '/helpers/ssrRef',
             '/helpers/useAsync',
             '/helpers/useContext',

docs/helpers/shallowSsrRef.md

@@ -0,0 +1,41 @@
+---
+---
+
+# shallowSsrRef
+
+This helper creates a [`shallowRef`](https://vue-composition-api-rfc.netlify.app/api.html#shallowref) (a ref that tracks its own .value mutation but doesn't make its value reactive) that is synced between client & server.
+
+```ts
+import { shallowSsrRef, onMounted } from 'nuxt-composition-api'
+
+const shallow = shallowSsrRef({ v: 'init' })
+if (process.server) shallow.value = { v: 'changed' }
+
+// On client-side, shallow.value will be { v: changed }
+onMounted(() => {
+  // This and other changes outside of setup won't trigger component updates.
+  shallow.value.v = 'Hello World'
+})
+```
+
+::: warning
+At the moment, an `shallowSsrRef` is only suitable for one-offs, unless you provide your own unique key.
+
+This is because server and client `shallowSsrRef` matches up based on line number within your code.
+
+```ts
+function useMyFeature() {
+  // Only one unique key is generated
+  const feature = shallowSsrRef('')
+  return feature
+}
+
+const a = useMyFeature()
+const b = useMyFeature()
+
+b.value = 'changed'
+// On client-side, a's value will also be initialised to 'changed'
+```
+
+If you want to use this pattern, make sure to set a unique key based on each calling of the function.
+:::

src/babel.ts

@@ -25,7 +25,7 @@ export default function ssrRefPlugin({ loadOptions, getEnv, types: t }: Babel) {
     CallExpression(path) {
       if (
         !('name' in path.node.callee) ||
-        !['ssrRef', 'useAsync'].includes(path.node.callee.name)
+        !['ssrRef', 'useAsync', 'shallowSsrRef'].includes(path.node.callee.name)
       )
         return
 

src/index.ts

@@ -44,7 +44,7 @@ export { defineComponent } from './component'
 export { useContext, withContext } from './context'
 export { useFetch } from './fetch'
 export { useMeta } from './meta'
-export { ssrRef, setSSRContext } from './ssr-ref'
+export { ssrRef, shallowSsrRef, setSSRContext } from './ssr-ref'
 
 export type {
   ComponentRenderProxy,

src/ssr-ref.ts

@@ -75,3 +75,61 @@ export const ssrRef = <T>(value: T | (() => T), key?: string): Ref<T> => {
 
   return proxy as Ref<T>
 }
+
+// TODO: remove when https://github.com/vuejs/composition-api/pull/311 is merged
+function shallowRef<T>(value: T): Ref<T> {
+  return computed({
+    get: () => value,
+    set: v => (value = v),
+  })
+}
+
+/**
+ * This helper creates a [`shallowRef`](https://vue-composition-api-rfc.netlify.app/api.html#shallowref) (a ref that tracks its own .value mutation but doesn't make its value reactive) that is synced between client & server.
+ * @param value This can be an initial value or a factory function that will be executed on server-side to get the initial value.
+ * @param key Under the hood, `shallowSsrRef` requires a key to ensure that the ref values match between client and server. If you have added `nuxt-composition-api` to your `buildModules`, this will be done automagically by an injected Babel plugin. If you need to do things differently, you can specify a key manually or add `nuxt-composition-api/babel` to your Babel plugins.
+ 
+ * @example
+  ```ts
+  import { shallowSsrRef, onMounted } from 'nuxt-composition-api'
+
+  const shallow = shallowSsrRef({ v: 'init' })
+  if (process.server) shallow.value = { v: 'changed' }
+
+  // On client-side, shallow.value will be { v: changed }
+  onMounted(() => {
+    // This and other changes outside of setup won't trigger component updates.
+    shallow.value.v = 'Hello World'
+  })
+  ```
+ */
+export const shallowSsrRef = <T>(
+  value: T | (() => T),
+  key?: string
+): Ref<T> => {
+  if (!key) {
+    throw new Error(
+      "You must provide a key. You can have it generated automatically by adding 'nuxt-composition-api/babel' to your Babel plugins."
+    )
+  }
+
+  if (process.client) {
+    return shallowRef(
+      (window as any).__NUXT__?.ssrRefs?.[key] ?? getValue(value)
+    )
+  }
+
+  let _val = getValue(value)
+
+  if (value instanceof Function) {
+    data[key] = sanitise(_val)
+  }
+
+  return computed({
+    get: () => _val,
+    set: v => {
+      data[key] = sanitise(v)
+      _val = v
+    },
+  })
+}

test/e2e/helpers/index.ts

@@ -7,12 +7,12 @@ export function navigateTo(path: string) {
 
 export function expectOnPage(text: string) {
   const selector = Selector('*').withText(new RegExp(text, 'i'))
-  return t.expect(selector.visible).ok()
+  return t.expect(selector.visible).ok(`${text} was not found on page`)
 }
 
 export function expectNotOnPage(text: string) {
   const selector = Selector('*').withText(new RegExp(text, 'i'))
-  return t.expect(selector.exists).notOk()
+  return t.expect(selector.exists).notOk(`${text} was found on page`)
 }
 
 export const getWindowPathname = ClientFunction(() => window.location.pathname)

test/e2e/ssr-refs.ts

@@ -15,10 +15,12 @@ test('Shows data on ssr-loaded page', async t => {
   await expectOnPage('function-runs SSR or client-side')
   await expectOnPage('prefetched-result')
   await expectOnPage('on: server')
+  await expectOnPage('shallow-server')
 
   await t.click(Selector('a').withText('home'))
   await t.click(Selector('a').withText('ssr refs'))
   await expectOnPage('ref-only SSR rendered')
+  await expectOnPage('shallow-client')
 })
 
 test('Shows appropriate data on client-loaded page', async t => {
@@ -28,6 +30,7 @@ test('Shows appropriate data on client-loaded page', async t => {
   await expectNotOnPage('ref-only SSR rendered')
   await expectOnPage('function-runs SSR or client-side')
   await expectOnPage('on: client')
+  await expectOnPage('shallow-client')
 })
 
 test('Shows SSR data when an ssrRef is defined outside setup', async () => {

test/fixture/pages/ssr-ref.vue

@@ -5,6 +5,7 @@
     <div>prefetched-{{ prefetchValue }}</div>
     <div>on: {{ asyncValue }}</div>
     <div>no-change: {{ noChange }}</div>
+    <div>shallow-{{ shallow.v.deep }}</div>
     <nuxt-link to="/">home</nuxt-link>
   </div>
 </template>
@@ -18,6 +19,8 @@ import {
   ssrRef,
   onServerPrefetch,
   useAsync,
+  shallowSsrRef,
+  onMounted,
 } from 'nuxt-composition-api'
 
 export function fetcher(result, time = 100) {
@@ -35,6 +38,12 @@ export default defineComponent({
     const funcValue = ssrRef(() => 'runs SSR or client-side') // function => in __NUXT__
     const noChange = ssrRef('initValue') // no Change => not in __NUXT__
 
+    const shallow = shallowSsrRef({ v: { deep: 'init' } })
+    if (process.server) shallow.value = { v: { deep: 'server' } }
+    onMounted(() => {
+      shallow.value.v.deep = 'client'
+    })
+
     const computedVal = computed(() => refValue.value)
 
     if (process.server) refValue.value = 'only SSR rendered'
@@ -58,6 +67,7 @@ export default defineComponent({
       prefetchValue,
       asyncValue,
       noChange,
+      shallow,
     }
   },
 })

test/tsd/ssr-ref.test-d.ts

@@ -1,6 +1,6 @@
 import { expectType } from 'tsd'
 
-import { ssrRef, Ref } from '../..'
+import { ssrRef, Ref, shallowSsrRef } from '../..'
 
 expectType<Ref<number>>(ssrRef(() => 42))
 expectType<Ref<string>>(ssrRef('thoughtless'))
@@ -9,3 +9,8 @@ interface Obj {
 }
 expectType<Ref<Obj>>(ssrRef({ name: 'today' }))
 expectType<Ref<null>>(ssrRef(null))
+
+expectType<Ref<number>>(shallowSsrRef(() => 42))
+expectType<Ref<string>>(shallowSsrRef('thoughtless'))
+expectType<Ref<Obj>>(shallowSsrRef({ name: 'today' }))
+expectType<Ref<null>>(shallowSsrRef(null))