lifecycleion 0.0.20 → 0.0.21

package/dist/lib/safe-handle-callback.d.cts

@@ -1,11 +1,16 @@
 /**
- * Safely handles a callback function by catching any errors and reporting them
- * using the global `reportError` event (supported in Node.js 25+, Bun, Deno, and browsers).
+ * Safely handles a callback function by catching any errors and reporting them via
+ * Lifecycleion's `'reportError'` reporting convention, built from web-standard primitives
+ * (`ErrorEvent` + global `EventTarget` methods).
  * This function can seamlessly handle both synchronous and asynchronous (Promise-based) callback functions.
  *
  * Errors are dispatched as ErrorEvent objects with type 'reportError' via `globalThis.dispatchEvent()`.
  * You can listen for these errors using `globalThis.addEventListener('reportError', handler)`.
  *
+ * Browsers, Bun, and Deno expose these globals natively. Node.js provides `ErrorEvent` (Node 25+)
+ * but not the global event methods, so importing this module installs them via a shared
+ * `EventTarget` (see `global-event-target`) without overwriting existing implementations.
+ *
  * This function is a "fire-and-forget" type of function, meaning it doesn't wait
  * for the callback to complete and doesn't return any result or error. If you need
  * to handle the result or error of the callback, consider using the
@@ -23,14 +28,19 @@ interface CallbackResult<T> {
     error?: Error;
 }
 /**
- * Safely handles a callback function by catching any errors and reporting them
- * using the global `reportError` event (supported in Node.js 25+, Bun, Deno, and browsers).
+ * Safely handles a callback function by catching any errors and reporting them via
+ * Lifecycleion's `'reportError'` reporting convention, built from web-standard primitives
+ * (`ErrorEvent` + global `EventTarget` methods).
  * This function can seamlessly handle both synchronous and asynchronous (Promise-based) callback
  * functions, and it waits for the callback to complete before returning the result or an error.
  *
  * Errors are dispatched as ErrorEvent objects with type 'reportError' via `globalThis.dispatchEvent()`.
  * You can listen for these errors using `globalThis.addEventListener('reportError', handler)`.
  *
+ * Browsers, Bun, and Deno expose these globals natively. Node.js provides `ErrorEvent` (Node 25+)
+ * but not the global event methods, so importing this module installs them via a shared
+ * `EventTarget` (see `global-event-target`) without overwriting existing implementations.
+ *
  * @param {string} callbackName - The name of the callback function, used for error reporting.
  * @param {unknown} callback - The callback function to be executed. It can be either a
  *                             synchronous function or a function that returns a Promise.

package/dist/lib/safe-handle-callback.d.ts

@@ -1,11 +1,16 @@
 /**
- * Safely handles a callback function by catching any errors and reporting them
- * using the global `reportError` event (supported in Node.js 25+, Bun, Deno, and browsers).
+ * Safely handles a callback function by catching any errors and reporting them via
+ * Lifecycleion's `'reportError'` reporting convention, built from web-standard primitives
+ * (`ErrorEvent` + global `EventTarget` methods).
  * This function can seamlessly handle both synchronous and asynchronous (Promise-based) callback functions.
  *
  * Errors are dispatched as ErrorEvent objects with type 'reportError' via `globalThis.dispatchEvent()`.
  * You can listen for these errors using `globalThis.addEventListener('reportError', handler)`.
  *
+ * Browsers, Bun, and Deno expose these globals natively. Node.js provides `ErrorEvent` (Node 25+)
+ * but not the global event methods, so importing this module installs them via a shared
+ * `EventTarget` (see `global-event-target`) without overwriting existing implementations.
+ *
  * This function is a "fire-and-forget" type of function, meaning it doesn't wait
  * for the callback to complete and doesn't return any result or error. If you need
  * to handle the result or error of the callback, consider using the
@@ -23,14 +28,19 @@ interface CallbackResult<T> {
     error?: Error;
 }
 /**
- * Safely handles a callback function by catching any errors and reporting them
- * using the global `reportError` event (supported in Node.js 25+, Bun, Deno, and browsers).
+ * Safely handles a callback function by catching any errors and reporting them via
+ * Lifecycleion's `'reportError'` reporting convention, built from web-standard primitives
+ * (`ErrorEvent` + global `EventTarget` methods).
  * This function can seamlessly handle both synchronous and asynchronous (Promise-based) callback
  * functions, and it waits for the callback to complete before returning the result or an error.
  *
  * Errors are dispatched as ErrorEvent objects with type 'reportError' via `globalThis.dispatchEvent()`.
  * You can listen for these errors using `globalThis.addEventListener('reportError', handler)`.
  *
+ * Browsers, Bun, and Deno expose these globals natively. Node.js provides `ErrorEvent` (Node 25+)
+ * but not the global event methods, so importing this module installs them via a shared
+ * `EventTarget` (see `global-event-target`) without overwriting existing implementations.
+ *
  * @param {string} callbackName - The name of the callback function, used for error reporting.
  * @param {unknown} callback - The callback function to be executed. It can be either a
  *                             synchronous function or a function that returns a Promise.

package/dist/lib/safe-handle-callback.js

@@ -714,18 +714,204 @@ function isFunction(value) {
   return typeof value === "function" || value instanceof Function;
 }
 
+// src/lib/global-event-target.ts
+var GLOBAL_KEY = "__lifecycleion_global_event_target__";
+var METHOD_NAMES = [
+  "addEventListener",
+  "removeEventListener",
+  "dispatchEvent"
+];
+var g = globalThis;
+function getState() {
+  const value = readGlobal(GLOBAL_KEY);
+  return value === UNREADABLE ? void 0 : asUsableState(value);
+}
+function asUsableState(value) {
+  if (typeof value !== "object" || value === null) {
+    return void 0;
+  }
+  return asUsableTarget(readMember(value, "target")) === null ? void 0 : value;
+}
+function asUsableTarget(value) {
+  if (typeof value !== "object" || value === null) {
+    return null;
+  }
+  for (const name of METHOD_NAMES) {
+    if (typeof readMember(value, name) !== "function") {
+      return null;
+    }
+  }
+  return value;
+}
+function bindTargetMethods(target) {
+  const bound = {};
+  for (const name of METHOD_NAMES) {
+    const method = readMember(target, name);
+    if (typeof method !== "function") {
+      return null;
+    }
+    let boundMethod;
+    try {
+      boundMethod = method.bind(target);
+    } catch {
+      return null;
+    }
+    if (typeof boundMethod !== "function") {
+      return null;
+    }
+    bound[name] = boundMethod;
+  }
+  return bound;
+}
+function isStateInstalled(state) {
+  return state !== void 0 && readMember(state, "isInstalled") === true;
+}
+function readStateTarget(state) {
+  if (state === void 0) {
+    return null;
+  }
+  return asUsableTarget(readMember(state, "target"));
+}
+var UNREADABLE = /* @__PURE__ */ Symbol("lifecycleion.unreadable");
+function readGlobal(name) {
+  try {
+    return g[name];
+  } catch {
+    return UNREADABLE;
+  }
+}
+function readMember(source, key) {
+  try {
+    return source[key];
+  } catch {
+    return UNREADABLE;
+  }
+}
+function probeMember(name) {
+  const value = readGlobal(name);
+  if (value === UNREADABLE) {
+    return "hostile";
+  }
+  if (typeof value === "function") {
+    return "usable";
+  }
+  return value === void 0 ? "absent" : "occupied";
+}
+function canDefineProperty(key) {
+  const descriptor = Object.getOwnPropertyDescriptor(g, key);
+  if (descriptor === void 0) {
+    return Object.isExtensible(g);
+  }
+  return descriptor.configurable === true;
+}
+function installGlobalEventTarget() {
+  const members = METHOD_NAMES.map((name) => probeMember(name));
+  if (members.every((member) => member === "usable")) {
+    return isStateInstalled(getState()) ? "already-installed" : "native";
+  }
+  if (members.some((member) => member !== "absent")) {
+    return "partial";
+  }
+  const eventTargetConstructor = readGlobal("EventTarget");
+  if (typeof eventTargetConstructor !== "function") {
+    return "unsupported";
+  }
+  const isDefinable = [...METHOD_NAMES, GLOBAL_KEY].every(
+    (key) => canDefineProperty(key)
+  );
+  if (!isDefinable) {
+    return "blocked";
+  }
+  const existingState = getState();
+  const defined = [];
+  const priorStateDescriptor = Object.getOwnPropertyDescriptor(g, GLOBAL_KEY);
+  const rollback = () => {
+    for (const key of defined) {
+      if (key === GLOBAL_KEY && priorStateDescriptor !== void 0) {
+        try {
+          Object.defineProperty(g, GLOBAL_KEY, priorStateDescriptor);
+        } catch {
+        }
+        continue;
+      }
+      try {
+        Reflect.deleteProperty(g, key);
+      } catch {
+      }
+    }
+  };
+  const reusableTarget = readStateTarget(existingState);
+  const reusableMethods = reusableTarget === null ? null : bindTargetMethods(reusableTarget);
+  let state;
+  let methods;
+  try {
+    if (existingState === void 0 || reusableMethods === null) {
+      let target;
+      try {
+        target = new eventTargetConstructor();
+      } catch {
+        return "unsupported";
+      }
+      const freshMethods = bindTargetMethods(target);
+      if (freshMethods === null) {
+        return "unsupported";
+      }
+      state = { target, isInstalled: false };
+      methods = freshMethods;
+      Object.defineProperty(g, GLOBAL_KEY, {
+        value: state,
+        enumerable: false,
+        writable: false,
+        configurable: true
+      });
+      defined.push(GLOBAL_KEY);
+    } else {
+      state = existingState;
+      methods = reusableMethods;
+    }
+    for (const name of METHOD_NAMES) {
+      Object.defineProperty(g, name, {
+        value: methods[name],
+        enumerable: false,
+        writable: true,
+        configurable: true
+      });
+      defined.push(name);
+    }
+    if (readMember(state, "isInstalled") !== true) {
+      state.isInstalled = true;
+    }
+  } catch {
+    rollback();
+    return "blocked";
+  }
+  return "installed";
+}
+function isGlobalEventTargetAvailable() {
+  return METHOD_NAMES.every((name) => probeMember(name) === "usable") && probeMember("ErrorEvent") === "usable";
+}
+
 // src/lib/safe-handle-callback.ts
+installGlobalEventTarget();
+function reportCallbackError(callbackName, error) {
+  installGlobalEventTarget();
+  if (!isGlobalEventTargetAvailable()) {
+    return;
+  }
+  try {
+    globalThis.dispatchEvent(
+      new ErrorEvent("reportError", {
+        error: new Error(
+          `Error in a callback ${callbackName}: ${DOUBLE_EOL}${errorToString(error)}`
+        )
+      })
+    );
+  } catch {
+  }
+}
 function safeHandleCallback(callbackName, callback, ...args) {
   const handleError = (error) => {
-    if (typeof globalThis.dispatchEvent === "function") {
-      globalThis.dispatchEvent(
-        new ErrorEvent("reportError", {
-          error: new Error(
-            `Error in a callback ${callbackName}: ${DOUBLE_EOL}${errorToString(error)}`
-          )
-        })
-      );
-    }
+    reportCallbackError(callbackName, error);
   };
   if (isFunction(callback)) {
     try {
@@ -746,15 +932,7 @@ function safeHandleCallback(callbackName, callback, ...args) {
 }
 async function safeHandleCallbackAndWait(callbackName, callback, ...args) {
   const handleError = (error) => {
-    if (typeof globalThis.dispatchEvent === "function") {
-      globalThis.dispatchEvent(
-        new ErrorEvent("reportError", {
-          error: new Error(
-            `Error in a callback ${callbackName}: ${DOUBLE_EOL}${errorToString(error)}`
-          )
-        })
-      );
-    }
+    reportCallbackError(callbackName, error);
     return { success: false, error };
   };
   if (isFunction(callback)) {