Merge pull request #30 from sikanhe/add-event-emitter

Add EventEmitter module

Author: austindd

.gitignore

@@ -8,7 +8,5 @@ bsb
 *.bs.js
 package-lock.json
 
-src/ScratchPadJs.js
-src/ScratchRE.re
-src/ScratchML.ml
-src/Events.re
+src/ScratchRe.re
+src/ScratchMl.ml

package.json

@@ -5,7 +5,10 @@
     "build": "bsb -make-world",
     "start": "bsb -make-world -w",
     "clean": "bsb -clean-world",
-    "test": "jest"
+    "test": "jest",
+    "clean-build": "bsb -clean-world && bsb -make-world",
+    "clean-start": "bsb -clean-world && bsb -make-world -w",
+    "clean-test": "bsb -clean-world && jest"
   },
   "keywords": [
     "BuckleScript"

src/Event.re

@@ -0,0 +1,45 @@
+/**
+ * The `Event` type represents the strings/symbols used in Node to
+ * identify event types for `EventEmitter` and its subclasses, including
+ * streams, sockets, and servers.
+ * 
+ * Given a type signature `Event.t('a => 'b, 'ty)`, the first type
+ * variable, `'a => 'b`, denotes the type signature of the event listener
+ * function, and `'ty` denotes the type of the associated `EventEmitter`.
+ * 
+ * These abstract `Event.t` types must be passed to `EventEmitter`
+ * functions to register event listeners or emit events. By encoding the
+ * listener function type in a type variable, we can ensure that each
+ * listener has the correct type. The type parameter for the emitter
+ * prevents two different emitters from using each other's events.
+ * 
+ * While this gives us some degree of type safety, it is still possible
+ * to introduce runtime errors with this API. In particular, two or more
+ * `Event.t` types can be defined from the same string/symbol, but with
+ * different listener types. Therefore, we strongly recommend using
+ * 100% unique strings/symbols to define events.
+ * 
+ */
+type t('listener, 'ty);
+external fromString: string => t('a => 'b, 'ty) = "%identity";
+external fromSymbol: Js.Types.symbol => t('a => 'b, 'ty) = "%identity";
+external unsafeToString: t('a => 'b, 'ty) => string = "%identity";
+external unsafeToSymbol: t('a => 'b, 'ty) => Js.Types.symbol = "%identity";
+type case =
+  | String(string)
+  | Symbol(Js.Types.symbol)
+  | Unknown;
+let classify = evt => {
+  switch (Js.typeof(evt)) {
+  | "string" => String(unsafeToString(evt))
+  | "symbol" => Symbol(unsafeToSymbol(evt))
+  | _ => Unknown
+  };
+};
+let eq = (event1, event2) => {
+  switch (Js.typeof(event1), Js.typeof(event2)) {
+  | ("string", "string") => Obj.magic(event1) === Obj.magic(event2)
+  | ("symbol", "symbol") => Obj.magic(event1) === Obj.magic(event2)
+  | _ => false
+  };
+};

src/EventEmitter.re

@@ -0,0 +1,147 @@
+/**
+ * `Impl` is a functor which generates FFI bindings to Node's `EventEmitter`
+ * class for any type `t`. This is not inherently type-safe. Type-safety can
+ * be achieved by implementing the known `Event.t('a => 'b, t)` types
+ */
+module Impl = (T: {type t;}) => {
+  /**
+   * `addListener(emitter, event, listener)`
+   *
+   * Adds a new event listener function to the event emitter.
+   */
+  [@bs.send]
+  external addListener: (T.t, Event.t('a => 'b, T.t), 'a => 'b) => T.t =
+    "addListener";
+
+  [@bs.send]
+  external emit: (T.t, Event.t('a => 'b, T.t), 'a) => bool = "emit";
+
+  [@bs.get] external errorMonitor: T.t => Js.Types.symbol = "errorMonitor";
+
+  [@bs.send]
+  external eventNames:
+    (T.t, Event.t('a => 'b, T.t)) => array(Event.t('a => 'b, T.t)) =
+    "eventNames";
+
+  [@bs.send] external getMaxListeners: T.t => int = "getMaxListeners";
+
+  [@bs.send]
+  external listenerCount: (T.t, Event.t('a => 'b, T.t)) => int =
+    "listenerCount";
+  [@bs.send]
+  external listeners: (T.t, Event.t('a => 'b, T.t)) => array('a => 'b) =
+    "listeners";
+
+  /**
+   * `on(emitter, event, listener)`
+   *
+   * Adds a new event listener function to the event emitter.
+   * Alias for `addListener`.
+   */
+  [@bs.send]
+  external on: (T.t, Event.t('a => 'b, T.t), 'a => 'b) => T.t = "on";
+
+  /**
+   * `once(emitter, event, listener)`
+   *
+   * Adds a new **single-use** event listener function to the event
+   * emitter. Then next time the given event is emitted, this listener
+   * will fire exactly once, and then be removed from the emitter's
+   * internal listener array.
+   */
+  [@bs.send]
+  external once: (T.t, Event.t('a => 'b, T.t), 'a => 'b) => T.t = "once";
+
+  /**
+   * `off(emitter, event, listener)`
+   *
+   * Removes the listener function from the event emitter.
+   *
+   * The specified listener function is compared by **referential
+   * equality** to each function in the emitter's internal listener
+   * array.
+   *
+   * This means that, when the target listener is initially added, that
+   * exact function reference must be maintained and provided here
+   * in order to ensure removal.
+   *
+   * Alias for `removeListener`.
+   */
+  [@bs.send]
+  external off: (T.t, Event.t('a => 'b, T.t), 'a => 'b) => T.t = "off";
+
+  /**
+   * `prependListener(emitter, event, listener)`
+   *
+   * Adds a new event listener function to the event emitter.
+   *
+   * Unlike `on` and `addListener`, `prependListener` adds the listener
+   * function to the front of the internal listener array, ensuring
+   * that this function is called before the rest of the listeners for
+   * the given event.
+   */
+  [@bs.send]
+  external prependListener: (T.t, Event.t('a => 'b, T.t), 'a => 'b) => T.t =
+    "prependListener";
+
+  /**
+   * `prependListenerOnce(emitter, event, listener)`
+   *
+   * Adds a new **single-use** event listener function to the event
+   * emitter. Then next time the given event is emitted, this listener
+   * will fire exactly once, and then be removed from the emitter's
+   * internal listener array.
+   *
+   * Unlike `once`, `prependListenerOnce` adds the listener function
+   * to the front of the internal listener array, ensuring that this
+   * function is called before the rest of the listeners for the
+   * given event.
+   */
+  [@bs.send]
+  external prependOnceListener: (T.t, Event.t('a => 'b, T.t), 'a => 'b) => T.t =
+    "prependOnceListener";
+
+  [@bs.send] external removeAllListeners: T.t => T.t = "removeAllListeners";
+
+  /**
+   * `removeListener(emitter, event, listener)`
+   *
+   * Removes the listener function from the event emitter.
+   *
+   * The specified listener function is compared by **referential
+   * equality** to each function in the emitter's internal listener
+   * array.
+   *
+   * This means that, when the target listener is initially added, that
+   * exact function reference must be maintained and provided here
+   * in order to ensure removal.
+   */
+  [@bs.send]
+  external removeListener: (T.t, Event.t('a => 'b, T.t), 'a => 'b) => T.t =
+    "removeListener";
+
+  /**
+   * `setMaxListeners(emitter, numberOfListeners)`
+   *
+   * Sets the maximum number of event listeners that may be added to
+   * an event emitter before Node begins emitting warnings.
+   *
+   * By default, each event emitter has this value set to 10. This is
+   * intended to warn the user about possible memory leaks.
+   * `setMaxListeners` will increase this threshold.
+   */
+  [@bs.send]
+  external setMaxListeners: (T.t, int) => T.t = "setMaxListeners";
+};
+
+/**
+ * A generative functor that creates a unique type `t` with the `EventEmitter`
+ * interface bindings.
+*/
+module Make = (()) => {
+  type t;
+  include Impl({
+    type nonrec t = t;
+  });
+  [@bs.module "events"] [@bs.new] external make: unit => t = "EventEmitter";
+};

test/__tests__/EventEmitter_test.re

@@ -0,0 +1,122 @@
+open Jest;
+
+describe("EventEmitter", () => {
+  test(
+    "'Emitter.make' should create a new emitter instance that is defined", () => {
+    open! ExpectJs;
+    open! EventEmitterTestLib;
+    let emitter = Emitter1.make();
+    expect(emitter->Js.Undefined.return) |> toBeDefined;
+  });
+
+  test("'Emitter.addListener' should add a new event listener", () => {
+    open! ExpectJs;
+    open! EventEmitterTestLib;
+    let listeners =
+      Emitter1.(
+        {
+          make()->addListener(Events.text, _ => ())->listeners(Events.text);
+        }
+      );
+    expect(Array.length(listeners)) |> toBe(1);
+  });
+
+  test("'Emitter.on' should add a new event listener", () => {
+    open! ExpectJs;
+    open! EventEmitterTestLib;
+    let listeners =
+      Emitter1.(
+        {
+          make()->on(Events.text, _ => ())->listeners(Events.text);
+        }
+      );
+    expect(Array.length(listeners)) |> toBe(1);
+  });
+
+  test("'Emitter.on' should add a new event listener", () => {
+    open! ExpectJs;
+    open! EventEmitterTestLib;
+    let listeners =
+      Emitter1.(
+        {
+          make()->on(Events.text, _ => ())->listeners(Events.text);
+        }
+      );
+    expect(Array.length(listeners)) |> toBe(1);
+  });
+
+  test("'Emitter.removeListener' should remove the event listener", () => {
+    open! ExpectJs;
+    open! EventEmitterTestLib;
+    let eventListener = (_) => ();
+    let listeners =
+      Emitter1.(
+        {
+          make()
+            |> on(_, Events.text, eventListener)
+            |> removeListener(_, Events.text, eventListener)
+            |> listeners(_, Events.text);
+        }
+      );
+    expect(Array.length(listeners)) |> toBe(0);
+  });
+
+  test("'Emitter.off' should remove the event listener", () => {
+    open! ExpectJs;
+    open! EventEmitterTestLib;
+    let eventListener = (_) => ();
+    let listeners =
+      Emitter1.(
+        {
+          make()
+            |> on(_, Events.text, eventListener)
+            |> off(_, Events.text, eventListener)
+            |> listeners(_, Events.text);
+        }
+      );
+    expect(Array.length(listeners)) |> toBe(0);
+  });
+
+  test("'Emitter.emit' should execute each listener for the correct event", () => {
+    open! ExpectJs;
+    open! EventEmitterTestLib;
+    let ref1 = ref(0);
+    let ref2 = ref(0);
+    let data1 = 1;
+    let data2 = 2;
+    let listener1 = (_) => { ref1 := data1; };
+    let listener2 = (_) => { ref2 := data2; };
+    Emitter1.({
+        let emitter =
+          make()
+          |> on(_, Events.integer, listener1)
+          |> on(_, Events.integer, listener2);
+          emit(emitter, Events.integer, data1)->ignore;
+          emit(emitter, Events.integer, data2)->ignore;
+    });
+    Assert.strictEqual(ref1^, 1);
+    Assert.strictEqual(ref2^, 2);
+    expect(ref1^ === 1 && ref2^ === 2) |> toBe(true);
+  });
+
+  test("'Emitter.removeAllListeners' should remove all event listeners", () => {
+    open! ExpectJs;
+    open! EventEmitterTestLib;
+    let eventListener = (_) => ();
+    let emitter =
+      Emitter1.(
+        {
+          make()
+            |> on(_, Events.text, eventListener)
+            |> on(_, Events.text, eventListener)
+            |> on(_, Events.text, eventListener)
+        }
+      );
+    // Make sure 3 listeners were indeed added:
+    Assert.strictEqual(Emitter1.(listeners(emitter, Events.text))->Array.length, 3);
+    // Remove all the listeners:
+    Emitter1.removeAllListeners(emitter)->ignore;
+    expect(Emitter1.(listeners(emitter, Events.text))->Array.length) |> toBe(0);
+  });
+
+});

test/test_lib/EventEmitterTestLib.re

@@ -0,0 +1,14 @@
+module Emitter1 = {
+  include EventEmitter.Make();
+
+  let uniqueSymbol: Js.Types.symbol = [%raw {|Symbol("emitter1")|}];
+
+  module Events = {
+    let symbol: Event.t(Js.Types.symbol => unit, t) = Event.fromSymbol(uniqueSymbol);
+    let text: Event.t(string => unit, t) = Event.fromString("text");
+    let integer: Event.t(int => unit, t) = Event.fromString("integer");
+    let textAndInteger: Event.t((string, int) => unit, t) = Event.fromString("textAndInteger");
+  };
+
+};
+