visaljs 0.0.7 → 0.0.9

package/node/prelude/events.js

@@ -1,7 +1,15 @@
-// node:events (ADR 0012, layer 3): EventEmitter, Node's semantics for the common API:
+// node:events: EventEmitter, Node's semantics for the common API:
 // listeners in order (prepend first), once wrappers, 'newListener' and 'removeListener', an
-// 'error' with no listener thrown, and the max-listeners warning.
+// 'error' with no listener thrown (errorMonitor's listeners hear it first), the max-listeners
+// warning, and captureRejections. The functions on emitters and EventTargets: once and on (as
+// promises and an async iterator, with an AbortSignal), getEventListeners, the max-listener
+// counts, and addAbortListener.
+import { eventTargetListeners } from "visaljs:host";
+import { lazyClass, lazyFunction } from "./internal/features.js";
+
 const kCapture = Symbol("kCapture");
+export const captureRejectionSymbol = Symbol.for("nodejs.rejection");
+export const errorMonitor = Symbol("events.errorMonitor");
 
 function checkListener(listener) {
   if (typeof listener !== "function") {
@@ -24,6 +32,21 @@ export function EventEmitter(opts) {
 EventEmitter.prototype._events = undefined;
 EventEmitter.prototype._eventsCount = 0;
 EventEmitter.prototype._maxListeners = undefined;
+EventEmitter.prototype[kCapture] = false;
+
+/* emitters created after it's set catch their listeners' rejections */
+Object.defineProperty(EventEmitter, "captureRejections", {
+  enumerable: true,
+  get() {
+    return EventEmitter.prototype[kCapture];
+  },
+  set(value) {
+    validateBoolean(value, "EventEmitter.captureRejections");
+    EventEmitter.prototype[kCapture] = value;
+  },
+});
+EventEmitter.captureRejectionSymbol = captureRejectionSymbol;
+EventEmitter.errorMonitor = errorMonitor;
 
 let defaultMaxListeners = 10;
 Object.defineProperty(EventEmitter, "defaultMaxListeners", {
@@ -42,7 +65,10 @@ EventEmitter.init = function (opts) {
     this._eventsCount = 0;
   }
   this._maxListeners = this._maxListeners || undefined;
-  if (opts && opts.captureRejections) this[kCapture] = true;
+  if (opts?.captureRejections) {
+    validateBoolean(opts.captureRejections, "options.captureRejections");
+    this[kCapture] = Boolean(opts.captureRejections);
+  } else this[kCapture] = EventEmitter.prototype[kCapture];
 };
 
 EventEmitter.prototype.setMaxListeners = function (n) {
@@ -56,6 +82,7 @@ EventEmitter.prototype.getMaxListeners = function () {
 
 EventEmitter.prototype.emit = function (type, ...args) {
   const events = this._events;
+  if (type === "error" && events !== undefined && events[errorMonitor] !== undefined) this.emit(errorMonitor, ...args);
   if (type === "error" && (events === undefined || events.error === undefined)) {
     const er = args[0];
     if (er instanceof Error) throw er;
@@ -68,14 +95,43 @@ EventEmitter.prototype.emit = function (type, ...args) {
   const handler = events[type];
   if (handler === undefined) return false;
   if (typeof handler === "function") {
-    handler.apply(this, args);
+    const result = handler.apply(this, args);
+    if (result !== undefined && result !== null && this[kCapture]) addCatch(this, result, type, args);
   } else {
     const listeners = handler.slice();
-    for (let i = 0; i < listeners.length; i++) listeners[i].apply(this, args);
+    for (let i = 0; i < listeners.length; i++) {
+      const result = listeners[i].apply(this, args);
+      if (result !== undefined && result !== null && this[kCapture]) addCatch(this, result, type, args);
+    }
   }
   return true;
 };
 
+/* captureRejections: a listener's rejected promise becomes the emitter's 'error', or goes to its
+ * Symbol.for('nodejs.rejection') method */
+function addCatch(that, promise, type, args) {
+  try {
+    const then = promise.then;
+    if (typeof then === "function") then.call(promise, undefined, (err) => process.nextTick(emitRejection, that, err, type, args));
+  } catch (err) {
+    that.emit("error", err);
+  }
+}
+
+function emitRejection(emitter, err, type, args) {
+  if (typeof emitter[captureRejectionSymbol] === "function") {
+    emitter[captureRejectionSymbol](err, type, ...args);
+    return;
+  }
+  const prev = emitter[kCapture];
+  try {
+    emitter[kCapture] = false;  /* an 'error' listener's own rejection isn't caught again */
+    emitter.emit("error", err);
+  } finally {
+    emitter[kCapture] = prev;
+  }
+}
+
 function addListener(target, type, listener, prepend) {
   checkListener(listener);
   let events = target._events;
@@ -221,21 +277,97 @@ EventEmitter.prototype.eventNames = function () {
 
 EventEmitter.EventEmitter = EventEmitter;
 
-/** events.once(emitter, name): a promise of the next event's arguments. */
-export function once(emitter, name) {
+/* ---- the functions ---------------------------------------------------------------------- */
+
+function validateBoolean(value, name) {
+  if (typeof value !== "boolean") throw invalidArgType(name, "of type boolean", value);
+}
+
+function invalidArgType(name, expected, value) {
+  const what = name.includes(".") ? "property" : "argument";
+  const e = new TypeError('The "' + name + '" ' + what + " must be " + expected + ". Received " + describe(value));
+  e.code = "ERR_INVALID_ARG_TYPE";
+  return e;
+}
+
+function validateSignal(signal, name) {
+  if (signal !== undefined && (signal === null || typeof signal !== "object" || !("aborted" in signal))) {
+    throw invalidArgType(name, "an instance of AbortSignal", signal);
+  }
+}
+
+/* Node's AbortError: name and code, the signal's reason as its cause */
+function abortError(signal) {
+  const error = new Error("The operation was aborted", { cause: signal?.reason });
+  error.code = "ABORT_ERR";
+  error.name = "AbortError";
+  return error;
+}
+
+const isEventTarget = (target) => typeof target?.addEventListener === "function" && typeof target?.on !== "function";
+
+/** events.once(emitter, name[, { signal }]): a promise of the next event's arguments; an
+ *  EventTarget's event as [event]. An 'error' first rejects it. */
+export function once(emitter, name, options = {}) {
+  const signal = options?.signal;
+  validateSignal(signal, "options.signal");
+  if (signal?.aborted) return Promise.reject(abortError(signal));
   return new Promise((resolve, reject) => {
-    const onError = (err) => {
-      emitter.removeListener(name, onEvent);
-      reject(err);
+    let cleanup;
+    const onAbort = () => {
+      cleanup();
+      reject(abortError(signal));
     };
-    const onEvent = (...args) => {
-      if (name !== "error") emitter.removeListener("error", onError);
-      resolve(args);
-    };
-    emitter.once(name, onEvent);
-    if (name !== "error") emitter.once("error", onError);
+    if (isEventTarget(emitter)) {
+      const onEvent = (event) => {
+        signal?.removeEventListener("abort", onAbort);
+        resolve([event]);
+      };
+      cleanup = () => emitter.removeEventListener(name, onEvent);
+      emitter.addEventListener(name, onEvent, { once: true });
+    } else {
+      const onError = (err) => {
+        emitter.removeListener(name, onEvent);
+        signal?.removeEventListener("abort", onAbort);
+        reject(err);
+      };
+      const onEvent = (...args) => {
+        if (name !== "error") emitter.removeListener("error", onError);
+        signal?.removeEventListener("abort", onAbort);
+        resolve(args);
+      };
+      cleanup = () => {
+        emitter.removeListener(name, onEvent);
+        emitter.removeListener("error", onError);
+      };
+      emitter.once(name, onEvent);
+      if (name !== "error") emitter.once("error", onError);
+    }
+    signal?.addEventListener("abort", onAbort, { once: true });
   });
 }
 EventEmitter.once = once;
 
+/** events.on (internal/events_on.js, linked when the program names it). */
+export const on = lazyFunction("on", 3);
+EventEmitter.on = on;
+
+/* the rest, in internal/events_extras.js, linked when the program names them (internal/features.js) */
+export const getEventListeners = lazyFunction("getEventListeners", 2);
+export const getMaxListeners = lazyFunction("getMaxListeners", 1);
+export const setMaxListeners = lazyFunction("setMaxListeners");
+/** emitter.listenerCount(type), or an EventTarget's listeners for the type, as Node's. */
+export function listenerCount(emitterOrTarget, type) {
+  if (typeof emitterOrTarget?.listenerCount === "function") return emitterOrTarget.listenerCount(type);
+  const listeners = eventTargetListeners(emitterOrTarget, type);
+  if (listeners !== undefined) return listeners.length;
+  throw invalidArgType("emitter", "an instance of EventEmitter or EventTarget", emitterOrTarget);
+}
+export const addAbortListener = lazyFunction("addAbortListener", 2);
+export const usingDomains = false;
+export const EventEmitterAsyncResource = lazyClass("EventEmitterAsyncResource");
+
+Object.assign(EventEmitter, { getEventListeners, getMaxListeners, setMaxListeners, listenerCount, addAbortListener, usingDomains, EventEmitterAsyncResource });
+
+export { defaultMaxListeners };
 export default EventEmitter;