Add once method to event hubs

- Added a .once() method to the event hubs factory
- Bound $once to the new method
- Added tests

app/assets/javascripts/helpers/event_hub_factory.js

@@ -3,7 +3,16 @@ import mitt from 'mitt';
 export default () => {
   const emitter = mitt();
 
+  emitter.once = (event, handler) => {
+    const wrappedHandler = evt => {
+      handler(evt);
+      emitter.off(event, wrappedHandler);
+    };
+    emitter.on(event, wrappedHandler);
+  };
+
   emitter.$on = emitter.on;
+  emitter.$once = emitter.once;
   emitter.$off = emitter.off;
   emitter.$emit = emitter.emit;
 

doc/development/fe_guide/vue3_migration.md

@@ -16,7 +16,7 @@ Component's computed properties / methods or external helpers.
 
 **Why?**
 
-`$on` and `$off` methods [are removed](https://github.com/vuejs/rfcs/blob/master/active-rfcs/0020-events-api-change.md) from the Vue instance, so in Vue 3 it can't be used to create an event hub.
+`$on`, `$once`, and `$off` methods [are removed](https://github.com/vuejs/rfcs/blob/master/active-rfcs/0020-events-api-change.md) from the Vue instance, so in Vue 3 it can't be used to create an event hub.
 
 **What to use instead**
 
@@ -55,7 +55,7 @@ import createEventHub from '~/helpers/event_hub_factory';
 export default createEventHub();
 ```
 
-Event hubs created with the factory expose the same methods as Vue 2 event hubs (`$on`, `$off` and
+Event hubs created with the factory expose the same methods as Vue 2 event hubs (`$on`, `$once`, `$off` and
 `$emit`), making them backward compatible with our previous approach.
 
 ## <template functional>

spec/frontend/helpers/event_hub_factory_spec.js

 import createEventHub from '~/helpers/event_hub_factory';
-import mitt from 'mitt';
-
-jest.mock('mitt');
-
-mitt.mockReturnValue({
-  on: () => {},
-  off: () => {},
-  emit: () => {},
-});
 
 describe('event bus factory', () => {
   let eventBus;
@@ -20,17 +11,84 @@ describe('event bus factory', () => {
     eventBus = null;
   });
 
+  describe('underlying module', () => {
+    let mitt;
+
+    beforeEach(() => {
+      jest.resetModules();
+      jest.mock('mitt');
+
+      // eslint-disable-next-line global-require
+      mitt = require('mitt');
+      mitt.mockReturnValue(() => ({}));
+
+      const createEventHubActual = jest.requireActual('~/helpers/event_hub_factory').default;
+      eventBus = createEventHubActual();
+    });
+
     it('creates an emitter', () => {
       expect(mitt).toHaveBeenCalled();
     });
+  });
 
+  describe('instance', () => {
     it.each`
       method
       ${'on'}
+      ${'once'}
       ${'off'}
       ${'emit'}
     `('binds $$method to $method ', ({ method }) => {
       expect(typeof eventBus[method]).toBe('function');
       expect(eventBus[method]).toBe(eventBus[`$${method}`]);
     });
+  });
+
+  describe('once', () => {
+    const event = 'foobar';
+    let handler;
+
+    beforeEach(() => {
+      jest.spyOn(eventBus, 'on');
+      jest.spyOn(eventBus, 'off');
+      handler = jest.fn();
+      eventBus.once(event, handler);
+    });
+
+    it('calls on internally', () => {
+      expect(eventBus.on).toHaveBeenCalled();
+    });
+
+    it('calls handler when event is emitted', () => {
+      eventBus.emit(event);
+      expect(handler).toHaveBeenCalled();
+    });
+
+    it('calls off when event is emitted', () => {
+      eventBus.emit(event);
+      expect(eventBus.off).toHaveBeenCalled();
+    });
+
+    it('calls the handler only once when event is emitted multiple times', () => {
+      eventBus.emit(event);
+      eventBus.emit(event);
+      expect(handler).toHaveBeenCalledTimes(1);
+    });
+
+    describe('when the handler thows an error', () => {
+      beforeEach(() => {
+        handler = jest.fn().mockImplementation(() => {
+          throw new Error();
+        });
+        eventBus.once(event, handler);
+      });
+
+      it('calls off when event is emitted', () => {
+        expect(() => {
+          eventBus.emit(event);
+        }).toThrow();
+        expect(eventBus.off).toHaveBeenCalled();
+      });
+    });
+  });
 });