refactor(core): add unlisten, once APIs to the event system (#1359)

Author: lucasfernog

.changes/event-unlisten-js.md

@@ -0,0 +1,6 @@
+---
+"tauri-api": minor
+"tauri": minor
+---
+
+Refactor the event callback payload and return an unlisten function on the `listen` API.

.changes/event-unlisten-rust.md

@@ -0,0 +1,5 @@
+---
+"tauri": minor
+---
+
+Adds `unlisten` and `once` APIs on the Rust event system.

api/src/helpers/event.ts

@@ -2,24 +2,45 @@ import { invokeTauriCommand } from './tauri'
 import { transformCallback } from '../tauri'
 
 export interface Event<T> {
-  type: string
+  /// event name.
+  event: string
+  /// event identifier used to unlisten.
+  id: number
+  /// event payload.
   payload: T
 }
 
 export type EventCallback<T> = (event: Event<T>) => void
 
+export type UnlistenFn = () => void
+
 async function _listen<T>(
   event: string,
-  handler: EventCallback<T>,
-  once: boolean
-): Promise<void> {
-  await invokeTauriCommand({
+  handler: EventCallback<T>
+): Promise<UnlistenFn> {
+  return invokeTauriCommand<number>({
     __tauriModule: 'Event',
     message: {
       cmd: 'listen',
       event,
-      handler: transformCallback(handler, once),
-      once
+      handler: transformCallback(handler)
+    }
+  }).then((eventId) => {
+    return async () => _unlisten(eventId)
+  })
+}
+
+/**
+ * Unregister the event listener associated with the given id.
+ *
+ * @param {number} eventId the event identifier
+ */
+async function _unlisten(eventId: number): Promise<void> {
+  return invokeTauriCommand({
+    __tauriModule: 'Event',
+    message: {
+      cmd: 'unlisten',
+      eventId
     }
   })
 }
@@ -29,12 +50,13 @@ async function _listen<T>(
  *
  * @param event the event name
  * @param handler the event handler callback
+ * @return {Promise<UnlistenFn>} a promise resolving to a function to unlisten to the event.
  */
 async function listen<T>(
   event: string,
   handler: EventCallback<T>
-): Promise<void> {
-  return _listen(event, handler, false)
+): Promise<UnlistenFn> {
+  return _listen(event, handler)
 }
 
 /**
@@ -46,8 +68,11 @@ async function listen<T>(
 async function once<T>(
   event: string,
   handler: EventCallback<T>
-): Promise<void> {
-  return _listen(event, handler, true)
+): Promise<UnlistenFn> {
+  return _listen<T>(event, (eventData) => {
+    handler(eventData)
+    _unlisten(eventData.id).catch(() => {})
+  })
 }
 
 /**

api/src/window.ts

@@ -1,5 +1,5 @@
 import { invokeTauriCommand } from './helpers/tauri'
-import { EventCallback, emit, listen, once } from './helpers/event'
+import { EventCallback, UnlistenFn, emit, listen, once } from './helpers/event'
 
 interface WindowDef {
   label: string
@@ -39,10 +39,14 @@ class WebviewWindowHandle {
    *
    * @param event the event name
    * @param handler the event handler callback
+   * @return {Promise<UnlistenFn>} a promise resolving to a function to unlisten to the event.
    */
-  async listen<T>(event: string, handler: EventCallback<T>): Promise<void> {
+  async listen<T>(
+    event: string,
+    handler: EventCallback<T>
+  ): Promise<UnlistenFn> {
     if (this._handleTauriEvent(event, handler)) {
-      return Promise.resolve()
+      return Promise.resolve(() => {})
     }
     return listen(event, handler)
   }
@@ -70,7 +74,7 @@ class WebviewWindowHandle {
     if (localTauriEvents.includes(event)) {
       // eslint-disable-next-line
       for (const handler of this.listeners[event] || []) {
-        handler({ type: event, payload })
+        handler({ event, id: -1, payload })
       }
       return Promise.resolve()
     }

examples/api/public/build/bundle.js

@@ -17,8 +17,8 @@ fn main() {
     .setup(|webview_manager| async move {
       let dispatcher = webview_manager.current_webview().unwrap();
       let dispatcher_ = dispatcher.clone();
-      dispatcher.listen("js-event", move |msg| {
-        println!("got js-event with message '{:?}'", msg);
+      dispatcher.listen("js-event", move |event| {
+        println!("got js-event with message '{:?}'", event.payload());
         let reply = Reply {
           data: "something else".to_string(),
         };

examples/api/public/build/bundle.js.map

@@ -61,6 +61,7 @@
 
   function onMessage(value) {
     responses += typeof value === "string" ? value : JSON.stringify(value);
+    responses += "\n";
   }
 
   function onLogoClick() {
@@ -72,38 +73,24 @@
   <div class="flex row noselect just-around" style="margin=1em;">
     <img src="tauri.png" height="60" on:click={onLogoClick} alt="logo" />
     <div>
-      <a
-        class="dark-link"
-        target="_blank"
-        href="https://tauri.studio/en/docs/getting-started/intro"
-      >
+      <a class="dark-link" target="_blank" href="https://tauri.studio/en/docs/getting-started/intro">
         Documentation
       </a>
-      <a
-        class="dark-link"
-        target="_blank"
-        href="https://github.com/tauri-apps/tauri"
-      >
+      <a class="dark-link" target="_blank" href="https://github.com/tauri-apps/tauri">
         Github
       </a>
-      <a
-        class="dark-link"
-        target="_blank"
-        href="https://github.com/tauri-apps/tauri/tree/dev/tauri/examples/api"
-      >
+      <a class="dark-link" target="_blank" href="https://github.com/tauri-apps/tauri/tree/dev/tauri/examples/api">
         Source
       </a>
     </div>
   </div>
   <div class="flex row">
     <div style="width:15em; margin-left:0.5em">
       {#each views as view}
-        <p
-          class="nv noselect {selected === view ? 'nv_selected' : ''}"
-          on:click={() => select(view)}
+      <p class="nv noselect {selected === view ? 'nv_selected' : ''}" on:click={()=> select(view)}
         >
-          {view.label}
-        </p>
+        {view.label}
+      </p>
       {/each}
     </div>
     <div class="content">
@@ -113,13 +100,10 @@
   <div id="response">
     <p class="flex row just-around">
       <strong>Tauri Console</strong>
-      <a
-        class="nv"
-        on:click={() => {
-          responses = [""];
-        }}>clear</a
-      >
+      <a class="nv" on:click={()=> {
+        responses = [""];
+        }}>clear</a>
     </p>
     {responses}
   </div>
-</main>
+</main>

examples/api/src-tauri/src/main.rs

@@ -4,7 +4,7 @@
 
   export let onMessage;
 
-  listen("rust-event", onMessage);
+  listen("rust-event", onMessage)
 
   function log() {
     invoke("log_operation", {