request by server-send events

strategy type

use hook

Before using extension hooks, make sure you are familiar with the basic usage of alova.

This hook is implemented using the EventSource API.

::: warning note

When you are not to be used in useSSE add custom header, because the standard does not contain the behavior

:::

Features

• Simpler and easier-to-use usage.
• Automatic connection management.

Install

vue

# npm
npm install @alova/scene-vue --save
#yarn
yarn add @alova/scene-vue

react

# npm
npm install @alova/scene-react --save
#yarn
yarn add @alova/scene-react

svelte

# npm
npm install @alova/scene-svelte --save
#yarn
yarn add @alova/scene-svelte

Usage

vue

import { useSSE } from '@alova/scene-vue';

const method = (value: string) => alova.Get('/api/source', { param: { key: value } });
const { data, eventSource, readyState, onMessage, onError, on, send, close } = useSSE(method, {
  initialData: 'initial-data' // Data initially in `data`
});

// Connect
send('value');

console.log(data.value); // Data is updated after receiving an event, by default it is `initialData`

// Corresponds to the `message` event of `eventsource`
const unbindMessage = onMessage(({ data }) => {
  console.log(data);
});

const unbindError = onError(({ error }) => {
  console.error('sse error', error);
  close();
});

// Unbind when needed
unbindMessage();
unbindError();

react

import { useSSE } from '@alova/scene-react';

const method = (value: string) => alova.Get('/api/source', { param: { key: value } });
const { data, eventSource, readyState, onMessage, onError, on, send, close } = useSSE(method, {
  initialData: 'initial-data' // Data initially in `data`
});

// Connect
send('value');

console.log(data); // Data is updated after receiving an event, by default it is `initialData`

// Corresponds to the `message` event of `eventsource`
const unbindMessage = onMessage(({ data }) => {
  console.log(data);
});

const unbindError = onError(({ error }) => {
  console.error('sse error', error);
  close();
});

// Unbind when needed
unbindMessage();
unbindError();

svelte

import { useSSE } from '@alova/scene-svelte';

const method = (value: string) => alova.Get('/api/source', { param: { key: value } });
const { data, eventSource, readyState, onMessage, onError, on, send, close } = useSSE(method, {
  initialData: 'initial-data' // Data initially in `data`
});

// Connect
send('value');

console.log(data); // Data is updated after receiving an event, by default it is `initialData`

// Corresponds to the `message` event of `eventsource`
const unbindMessage = onMessage(({ data }) => {
  console.log(data);
});

const unbindError = onError(({ error }) => {
  console.error('sse error', error);
  close();
});

// Unbind when needed
unbindMessage();
unbindError();

warning

Currently, useSSE can only connect to one source. This means that when attempting to connect to multiple targets, the previous connection will always be terminated.

const { data, eventSource, readyState, onMessage, onError, on, send, close } = useSSE(method);

send('value1');
send('value2'); // This will terminate the previous connection
send('value3'); // This will also terminate the previous connection

By default, no request is sent. However, by setting immediate = true, you can skip the manual send step.

const { data, eventSource, readyState, onMessage, onError, on, send, close } = useSSE(method, {
  immediate: true
});

// codes here...

Binding Custom Events

const { data, readyState, onMessage, on } = useSSE(method);

on('event-name', ({ data }) => {
  console.log(data);
});

Global Response Interception

By default, the response data is captured by the global response interceptors. If this is not the desired behavior, you can manually disable it.

const { data, readyState, onMessage, on } = useSSE(method, {
  interceptByGlobalResponded: false // Now the data will not be intercepted by the response interceptor
});

Type Declaration

const enum SSEHookReadyState {
  CONNECTING = 0,
  OPEN = 1,
  CLOSED = 2
};

type SSEHookConfig = {
  /**
   * Passed to new EventSource
   */
  withCredentials?: boolean;

  /**
   * Whether to be intercepted by the global responded interceptor of Alova instance
   * @default true
   */
  interceptByGlobalResponded?: boolean;

  /**
   * Initial data
   */
  initialData?: any;

  /**
   * Whether to initiate the request immediately
   * @default false
   */
  immediate?: boolean;
};

type SSEReturnType<S, Data> = {
  readyState: ExportedType<SSEHookReadyState, S>;
  data: ExportedType<Data | undefined, S>;
  eventSource: ExportedType<EventSource | undefined, S>;
  /**
   * Manually initiate the request. When `immediate: true` is used, this method is triggered automatically.
   * @param sendArgs Request parameters passed to the method
   */
  send: (...sendArgs: any[]) => Promise<void>;
  /**
   * Close the connection
   */
  close: () => void;
  /**
   * Register a callback function for the EventSource 'open' event
   * @param callback Callback function
   * @returns Function to unregister the callback
   */
  onOpen(callback: SSEOnOpenTrigger): () => void;

  /**
   * Register a callback function for the EventSource 'message' event
   * @param callback Callback function
   * @returns Function to unregister the callback
   */
  onMessage<T = Data>(callback: SSEOnMessageTrigger<T>): () => void;

  /**
   * Register a callback function for the EventSource 'error' event
   * @param callback Callback function
   * @returns Function to unregister the callback
   */
  onError(callback: SSEOnErrorTrigger): () => void;

  /**
   * @param eventName Event name, defaults to 'open' | 'error' | 'message'
   * @param handler Event handler
   */
  on(
    eventName: string,
    handler: (event: AlovaSSEMessageEvent<S, E, R, T, RC, RE, RH>) => void
  ) => () => void;
};