@kontsedal/olas-vue

The Vue 3 adapter for Olas. It turns Olas signals into Vue refs. The root is built outside Vue, once, and app.use(olasPlugin(root)) hands it to every component. Vue does not own a controller's lifetime, so a component that unmounts drops its subscriptions and nothing else.

Install

pnpm add @kontsedal/olas-vue @kontsedal/olas-core @preact/signals-core vue

vue >= 3.4 is a peer dependency.

Example

// counter.ts: the controller knows nothing about Vue
import { defineController, signal } from '@kontsedal/olas-core'

export const counter = defineController(() => {
  const count = signal(0)
  return { count, inc: () => count.set(count.peek() + 1) }
})

// main.ts: build the root once, then install it
import { createRoot } from '@kontsedal/olas-core'
import { olasPlugin } from '@kontsedal/olas-vue'
import { createApp } from 'vue'
import App from './App.vue'
import { counter } from './counter'

export const root = createRoot(counter, { deps: {} })
createApp(App).use(olasPlugin(root)).mount('#app')

// Register the root's type once, so `useRoot()` needs no type argument.
declare module '@kontsedal/olas-vue' {
  interface Register {
    root: typeof root
  }
}

<!-- App.vue: components read signals as refs -->
<script setup lang="ts">
import { useRoot, useValue } from '@kontsedal/olas-vue'

const api = useRoot()
const count = useValue(api.count)
</script>

<template>
  <button @click="api.inc">{{ count }}</button>
</template>

API

| Export | Purpose | |---|---| | olasPlugin(root) | The Vue plugin for app.use. It provides the root to the whole app. | | useRoot<Api>() | The root's api. Register types it; a type argument is an unchecked cast. Throws when no plugin provided a root, and when called outside a component's setup(). | | useValue(signal, { isEqual? }) | A read-only ref over any ReadSignal: a signal, a computed, a Field, a Form or a FieldArray. While isEqual calls a new value equal to the one the ref last returned, the ref keeps returning that one, as React's useValue does. | | useQuery(subscription) | One ref per AsyncState signal (data, status, isLoading, isFetching and the rest), plus refetch, reset and cancel. | | useInfiniteQuery(subscription) | useQuery's refs, plus pages, flat, the paging flags, fetchNextPage and fetchPreviousPage. | | useField(field) | A writable value ref for v-model, refs for the validation state, and the field's actions. | | useMutation(mutation) | Refs for data, error, status, isPending and lastVariables, plus mutate, run and reset. |

Register and RegisteredApi type useRoot(). Each hook's return type is exported as Use…Return, and Refs<T> is the shape they return their state in.

How it behaves

• A read does not lag a write. A ref's getter reads the signal's current value, so code that writes a signal and then reads the ref sees the new value. That holds inside a batch too, and useField's value reads the same way.
• Vue tracks each ref on its own. A template that reads data does not re-render when isFetching flips, because each field is a separate ref.
• Subscriptions end with the component. The adapter ties each one to the current effect scope with onScopeDispose. Called outside any scope, a hook still returns a working ref, but nothing ends its subscription. A development build warns about it once per hook, naming the hook. To use a hook outside a component, call it inside effectScope().run() and call stop() on the scope when you are done.
• A server render does not subscribe. Vue never stops a component's effect scope on the server, so a subscription made there would outlive the request. During renderToString, a hook's refs read each signal's current value and subscribe to nothing.
• mutate is fire-and-forget. It returns nothing, and a failure lands on error and status. The adapter catches the rejection, so it does not become an unhandled one. run returns the promise, and the caller owns its rejection.
• The refs are read-only. useValue ignores an assignment. Write through the signal, or through useField's value, which calls field.set.
• v-model binds a field's whole value. v-model="value" assigns the ref, which calls field.set. On an object-valued field, v-model="value.name" assigns name on the field's own value object instead: nothing calls field.set and no validator runs. The field keeps its baseline as a copy of its own, so reset() still restores. Bind a writable computed that sets a new object, computed({ get: () => value.value.name, set: (name) => set({ ...value.value, name }) }), or bind a Form's leaf field.

Testing

A controller tests without Vue, through createTestController from @kontsedal/olas-core/testing. examples/vue-tasks shows both halves: controller tests in plain Node, and one mounted run of the real app. packages/integration/tests/adapter-parity/ runs the same scenarios through this adapter, React, preact/compat and Svelte, and asserts the same DOM.