useLive()

Async rendering of remotely triggered data mutations.

useSuspense() + useSubscription() in one composable.

useLive() is reactive to data mutations; rerendering only when necessary.

Usage

Ticker

AssetPrice.vue

<script setup lang="ts">
  import { computed } from 'vue';
  import { useLive } from '@data-client/vue';
  import { getTicker } from './Ticker';

  const props = defineProps<{ productId: string }>();
  // highlight-next-line
  const ticker = await useLive(getTicker, computed(() => ({
    productId: props.productId,
  })));
</script>

<template>
  <center>
    {{ productId }}
    <NumberFlow
      :value="ticker.price"
      :format="{ style: 'currency', currency: 'USD' }"
    />
  </center>
</template>

Like useSuspense(), useLive() returns a Promise, so it is used with await in <script setup> and requires a Suspense ancestor. The subscription is removed automatically when the component unmounts.

Behavior

Conditional Dependencies

Use null as the second argument to any Data Client hook means "do nothing."

// todo could be undefined if id is undefined
const todo = useLive(
  TodoResource.get,
  computed(() => (id.value ? { id: id.value } : null)),
);

Types

function useLive(
  endpoint: ReadEndpoint,
  ...args: MaybeRefsOrGetters<Parameters<typeof endpoint>> | [null]
): Promise<DeepReadonly<ComputedRef<Denormalize<typeof endpoint.schema>>>>;

Arguments can be plain values, refs (including computed), or getter functions like () => ({ id: props.id }). A plain object like { id: props.id } is read once and won't follow prop or route changes, so use a getter or computed when an argument can change.

The result updates (and the subscription is re-established) when the arguments change. While data for new arguments loads, the result keeps the previous data instead of becoming undefined. If that fetch fails, reading the result throws the error (per its error policy), so it reaches onErrorCaptured().

Examples

Bitcoin Price (polling)

When our component with useLive is rendered, getTicker will fetch at pollFrequency milliseconds.