// Copyright 2019-2021 Tauri Programme within The Commons Conservancy // SPDX-License-Identifier: Apache-2.0 // SPDX-License-Identifier: MIT /** * The event system allows you to emit events to the backend and listen to events from it. * * This package is also accessible with `window.__TAURI__.event` when `tauri.conf.json > build > withGlobalTauri` is set to true. * @module */ import { invokeTauriCommand } from './helpers/tauri' import { emit as emitEvent } from './helpers/event' import { transformCallback } from './tauri' import { LiteralUnion } from 'type-fest' interface Event { /** Event name */ event: EventName /** Event identifier used to unlisten */ id: number /** Event payload */ payload: T } type EventName = LiteralUnion< | 'tauri://update' | 'tauri://update-available' | 'tauri://update-install' | 'tauri://update-status' | 'tauri://resize' | 'tauri://move' | 'tauri://close-requested' | 'tauri://focus' | 'tauri://blur' | 'tauri://scale-change' | 'tauri://menu' | 'tauri://file-drop' | 'tauri://file-drop-hover' | 'tauri://file-drop-cancelled', string > type EventCallback = (event: Event) => void type UnlistenFn = () => void /** * Unregister the event listener associated with the given id. * * @ignore * @param eventId Event identifier * @returns */ async function _unlisten(eventId: number): Promise { return invokeTauriCommand({ __tauriModule: 'Event', message: { cmd: 'unlisten', eventId } }) } /** * Listen to an event from the backend. * * @param event Event name. Must include only alphanumeric characters, `-`, `/`, `:` and `_`. * @param handler Event handler callback. * @return A promise resolving to a function to unlisten to the event. */ async function listen( event: EventName, handler: EventCallback ): Promise { return invokeTauriCommand({ __tauriModule: 'Event', message: { cmd: 'listen', event, handler: transformCallback(handler) } }).then((eventId) => { return async () => _unlisten(eventId) }) } /** * Listen to an one-off event from the backend. * * @param event Event name. Must include only alphanumeric characters, `-`, `/`, `:` and `_`. * @param handler Event handler callback. * @returns A promise resolving to a function to unlisten to the event. */ async function once( event: EventName, handler: EventCallback ): Promise { return listen(event, (eventData) => { handler(eventData) _unlisten(eventData.id).catch(() => {}) }) } /** * Emits an event to the backend. * * @param event Event name. Must include only alphanumeric characters, `-`, `/`, `:` and `_`. * @param [payload] Event payload * @returns */ async function emit(event: string, payload?: unknown): Promise { return emitEvent(event, null, payload) } export type { Event, EventName, EventCallback, UnlistenFn } export { listen, once, emit }