lifecycleion 0.0.19 → 0.0.21

package/README.md

@@ -1,4 +1,4 @@
-# Lifecycleion v0.0.19
+# Lifecycleion v0.0.21
 
 [![npm version](https://badge.fury.io/js/lifecycleion.svg)](https://badge.fury.io/js/lifecycleion)
 
@@ -43,7 +43,9 @@ yarn add lifecycleion
 bun add lifecycleion
 ```
 
-For Node.js runtimes, Lifecycleion currently targets `Node >=25`. Some libraries, including `safe-handle-callback` and `lru-cache`'s `onChange`, rely on browser-style global error event APIs such as `ErrorEvent`, which are also available in Bun, Deno, and modern browsers.
+For Node.js runtimes, Lifecycleion currently targets `Node >=25`. Some libraries, including `safe-handle-callback`, `logger`'s `reportError` listener, and `lru-cache`'s `onChange`, report errors using Lifecycleion's `'reportError'` convention: an `ErrorEvent` dispatched through the global `EventTarget` methods. Those are web-standard primitives (the `'reportError'` event type itself is Lifecycleion's convention, not a web standard), and browsers, Bun, and Deno expose them on `globalThis` natively.
+
+Node.js is a partial case: `ErrorEvent` is native in Node 25+, but `globalThis` is still not an `EventTarget`, so Lifecycleion automatically supplies the missing global event methods without overwriting native or user-installed implementations. See [global-event-target](./docs/global-event-target.md).
 
 ## Quick Example
 
@@ -91,40 +93,41 @@ Tip: listen for `lifecycle-manager:shutdown-completed` when you want one place t
 
 Each library has comprehensive documentation in the [docs](./docs) folder. Click on any library name in the table below to view detailed usage examples, API references, and best practices.
 
-| Library                                                            | Import Path                                             | Description                                                                                                                              |
-| ------------------------------------------------------------------ | ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
-| [arrays](./docs/arrays.md)                                         | `lifecycleion/arrays`                                   | Array utility functions for filtering, comparison, deduplication, and string manipulation                                                |
-| [ascii-tables](./docs/ascii-tables.md)                             | `lifecycleion/ascii-tables`                             | Key-value and multi-column ASCII tables with word wrapping, nesting, and emoji support                                                   |
-| [clamp](./docs/clamp.md)                                           | `lifecycleion/clamp`                                    | Number clamping utilities with safe handling for non-finite values and nullish inputs                                                    |
-| [constants](./docs/constants.md)                                   | `lifecycleion/constants`                                | Common string constants including whitespace helpers and Python-style character sets                                                     |
-| [curly-brackets](./docs/curly-brackets.md)                         | `lifecycleion/curly-brackets`                           | String templating with `{{placeholders}}`, fallbacks, escaping, and compiled templates                                                   |
-| [deep-clone](./docs/deep-clone.md)                                 | `lifecycleion/deep-clone`                               | Deep clone utility with circular reference detection for objects, arrays, Maps, Sets, and more                                           |
-| [dev-mode](./docs/dev-mode.md)                                     | `lifecycleion/dev-mode`                                 | Runtime-settable dev/production mode flag with auto-detection from CLI args or NODE_ENV                                                  |
-| [domain-utils](./docs/domain-utils.md)                             | `lifecycleion/domain-utils`                             | Hardened helpers for normalizing and matching domains and origins for CORS and routing, with IDNA/TR46, IPv6, and wildcard semantics     |
-| [error-to-string](./docs/error-to-string.md)                       | `lifecycleion/error-to-string`                          | Format errors into readable ASCII tables with support for nested info and sensitive field masking                                        |
-| [event-emitter](./docs/event-emitter.md)                           | `lifecycleion/event-emitter`                            | Lightweight event emitter with protected and public variants, type safety, and memory management                                         |
-| [http-client](./docs/http-client.md)                               | `lifecycleion/http-client` (+ `-node`, `-xhr`, `-mock`) | Fluent HTTP client with Fetch, Node.js native, XHR, and Mock adapters, interceptors, observers, retries, cookies, and redirect control   |
-| [id-helpers](./docs/id-helpers.md)                                 | `lifecycleion/id-helpers`                               | Unified ID generation and validation for ObjectID, UUID v4, UUID v7, and ULID                                                            |
-| [is-boolean](./docs/is-boolean.md)                                 | `lifecycleion/is-boolean`                               | Type guard to check if a value is a boolean                                                                                              |
-| [is-function](./docs/is-function.md)                               | `lifecycleion/is-function`                              | Check whether a value is a function                                                                                                      |
-| [is-number](./docs/is-number.md)                                   | `lifecycleion/is-number`                                | Type guards to check whether a value is a valid number, with and without finite enforcement                                              |
-| [is-plain-object](./docs/is-plain-object.md)                       | `lifecycleion/is-plain-object`                          | Type guard to check if a value is a plain object (not null, not an array)                                                                |
-| [is-promise](./docs/is-promise.md)                                 | `lifecycleion/is-promise`                               | Thenable/promise detection following the Promises/A+ specification                                                                       |
-| [json-helpers](./docs/json-helpers.md)                             | `lifecycleion/json-helpers`                             | JSON formatting utilities                                                                                                                |
-| [lru-cache](./docs/lru-cache.md)                                   | `lifecycleion/lru-cache`                                | TTL-aware LRU cache with entry-count and size-based eviction, custom size calculators, and per-entry TTL overrides                       |
-| [lifecycle-manager](./docs/lifecycle-manager.md)                   | `lifecycleion/lifecycle-manager`                        | Lifecycle orchestration for managing startup, shutdown, and runtime control of application components                                    |
-| [logger](./docs/logger.md)                                         | `lifecycleion/logger`                                   | Flexible sink-based logger with log levels, redaction, template strings, and service scoping                                             |
-| [padding-utils](./docs/padding-utils.md)                           | `lifecycleion/padding-utils`                            | String padding utilities for left, right, and center alignment with a configurable pad character                                         |
-| [process-signal-manager](./docs/process-signal-manager.md)         | `lifecycleion/process-signal-manager`                   | Unified handler for process signals (SIGINT, SIGTERM, SIGHUP, etc.) and keyboard shortcuts with graceful shutdown and hot-reload support |
-| [promise-protected-resolver](./docs/promise-protected-resolver.md) | `lifecycleion/promise-protected-resolver`               | Promise wrapper with `resolveOnce` and `rejectOnce` that guarantee a promise is only settled once                                        |
-| [retry-utils](./docs/retry-utils.md)                               | `lifecycleion/retry-utils`                              | Retry logic with fixed and exponential backoff via `RetryPolicy` (low-level) and `RetryRunner` (high-level with events and cancellation) |
-| [safe-handle-callback](./docs/safe-handle-callback.md)             | `lifecycleion/safe-handle-callback`                     | Safely execute sync or async callbacks with automatic error reporting via browser-style `reportError`/`ErrorEvent` globals               |
-| [serialize-error](./docs/serialize-error.md)                       | `lifecycleion/serialize-error`                          | Convert any `Error` into a plain JSON-serializable object and back again for IPC, RPCs, and database storage                             |
-| [single-event-observer](./docs/single-event-observer.md)           | `lifecycleion/single-event-observer`                    | Lightweight type-safe observer pattern for a single event type, with public and protected notify variants                                |
-| [sleep](./docs/sleep.md)                                           | `lifecycleion/sleep`                                    | Pause async execution for a given number of milliseconds                                                                                 |
-| [strings](./docs/strings.md)                                       | `lifecycleion/strings`                                  | String type guard, case conversion (PascalCase, camelCase, CONSTANT_CASE), grapheme splitting, character filtering, and chopping helpers |
-| [tmp-dir](./docs/tmp-dir.md)                                       | `lifecycleion/tmp-dir`                                  | Create and automatically clean up uniquely-named temporary directories with configurable prefix, postfix, and unsafe cleanup support     |
-| [unix-time-helpers](./docs/unix-time-helpers.md)                   | `lifecycleion/unix-time-helpers`                        | Unix timestamp utilities for seconds, milliseconds, high-resolution timing, and unit conversion                                          |
+| Library                                                            | Import Path                                             | Description                                                                                                                                    |
+| ------------------------------------------------------------------ | ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| [arrays](./docs/arrays.md)                                         | `lifecycleion/arrays`                                   | Array utility functions for filtering, comparison, deduplication, and string manipulation                                                      |
+| [ascii-tables](./docs/ascii-tables.md)                             | `lifecycleion/ascii-tables`                             | Key-value and multi-column ASCII tables with word wrapping, nesting, and emoji support                                                         |
+| [clamp](./docs/clamp.md)                                           | `lifecycleion/clamp`                                    | Number clamping utilities with safe handling for non-finite values and nullish inputs                                                          |
+| [constants](./docs/constants.md)                                   | `lifecycleion/constants`                                | Common string constants including whitespace helpers and Python-style character sets                                                           |
+| [curly-brackets](./docs/curly-brackets.md)                         | `lifecycleion/curly-brackets`                           | String templating with `{{placeholders}}`, fallbacks, escaping, and compiled templates                                                         |
+| [deep-clone](./docs/deep-clone.md)                                 | `lifecycleion/deep-clone`                               | Deep clone utility with circular reference detection for objects, arrays, Maps, Sets, and more                                                 |
+| [dev-mode](./docs/dev-mode.md)                                     | `lifecycleion/dev-mode`                                 | Runtime-settable dev/production mode flag with auto-detection from CLI args or NODE_ENV                                                        |
+| [domain-utils](./docs/domain-utils.md)                             | `lifecycleion/domain-utils`                             | Hardened helpers for normalizing and matching domains and origins for CORS and routing, with IDNA/TR46, IPv6, and wildcard semantics           |
+| [error-to-string](./docs/error-to-string.md)                       | `lifecycleion/error-to-string`                          | Format errors into readable ASCII tables with support for nested info and sensitive field masking                                              |
+| [event-emitter](./docs/event-emitter.md)                           | `lifecycleion/event-emitter`                            | Lightweight event emitter with protected and public variants, type safety, and memory management                                               |
+| [global-event-target](./docs/global-event-target.md)               | `lifecycleion/global-event-target`                      | Conservative polyfill giving `globalThis` the `EventTarget` methods on Node.js, so `'reportError'` dispatch works there                        |
+| [http-client](./docs/http-client.md)                               | `lifecycleion/http-client` (+ `-node`, `-xhr`, `-mock`) | Fluent HTTP client with Fetch, Node.js native, XHR, and Mock adapters, interceptors, observers, retries, cookies, and redirect control         |
+| [id-helpers](./docs/id-helpers.md)                                 | `lifecycleion/id-helpers`                               | Unified ID generation and validation for ObjectID, UUID v4, UUID v7, and ULID                                                                  |
+| [is-boolean](./docs/is-boolean.md)                                 | `lifecycleion/is-boolean`                               | Type guard to check if a value is a boolean                                                                                                    |
+| [is-function](./docs/is-function.md)                               | `lifecycleion/is-function`                              | Check whether a value is a function                                                                                                            |
+| [is-number](./docs/is-number.md)                                   | `lifecycleion/is-number`                                | Type guards to check whether a value is a valid number, with and without finite enforcement                                                    |
+| [is-plain-object](./docs/is-plain-object.md)                       | `lifecycleion/is-plain-object`                          | Type guard to check if a value is a plain object (not null, not an array)                                                                      |
+| [is-promise](./docs/is-promise.md)                                 | `lifecycleion/is-promise`                               | Thenable/promise detection following the Promises/A+ specification                                                                             |
+| [json-helpers](./docs/json-helpers.md)                             | `lifecycleion/json-helpers`                             | JSON formatting utilities                                                                                                                      |
+| [lru-cache](./docs/lru-cache.md)                                   | `lifecycleion/lru-cache`                                | TTL-aware LRU cache with entry-count and size-based eviction, custom size calculators, and per-entry TTL overrides                             |
+| [lifecycle-manager](./docs/lifecycle-manager.md)                   | `lifecycleion/lifecycle-manager`                        | Lifecycle orchestration for managing startup, shutdown, and runtime control of application components                                          |
+| [logger](./docs/logger.md)                                         | `lifecycleion/logger`                                   | Flexible sink-based logger with log levels, redaction, template strings, and service scoping                                                   |
+| [padding-utils](./docs/padding-utils.md)                           | `lifecycleion/padding-utils`                            | String padding utilities for left, right, and center alignment with a configurable pad character                                               |
+| [process-signal-manager](./docs/process-signal-manager.md)         | `lifecycleion/process-signal-manager`                   | Unified handler for process signals (SIGINT, SIGTERM, SIGHUP, etc.) and keyboard shortcuts with graceful shutdown and hot-reload support       |
+| [promise-protected-resolver](./docs/promise-protected-resolver.md) | `lifecycleion/promise-protected-resolver`               | Promise wrapper with `resolveOnce` and `rejectOnce` that guarantee a promise is only settled once                                              |
+| [retry-utils](./docs/retry-utils.md)                               | `lifecycleion/retry-utils`                              | Retry logic with fixed and exponential backoff via `RetryPolicy` (low-level) and `RetryRunner` (high-level with events and cancellation)       |
+| [safe-handle-callback](./docs/safe-handle-callback.md)             | `lifecycleion/safe-handle-callback`                     | Safely execute sync or async callbacks with automatic error reporting via the `'reportError'` convention (`ErrorEvent` + global `EventTarget`) |
+| [serialize-error](./docs/serialize-error.md)                       | `lifecycleion/serialize-error`                          | Convert any `Error` into a plain JSON-serializable object and back again for IPC, RPCs, and database storage                                   |
+| [single-event-observer](./docs/single-event-observer.md)           | `lifecycleion/single-event-observer`                    | Lightweight type-safe observer pattern for a single event type, with public and protected notify variants                                      |
+| [sleep](./docs/sleep.md)                                           | `lifecycleion/sleep`                                    | Pause async execution for a given number of milliseconds                                                                                       |
+| [strings](./docs/strings.md)                                       | `lifecycleion/strings`                                  | String type guard, case conversion (PascalCase, camelCase, CONSTANT_CASE), grapheme splitting, character filtering, and chopping helpers       |
+| [tmp-dir](./docs/tmp-dir.md)                                       | `lifecycleion/tmp-dir`                                  | Create and automatically clean up uniquely-named temporary directories with configurable prefix, postfix, and unsafe cleanup support           |
+| [unix-time-helpers](./docs/unix-time-helpers.md)                   | `lifecycleion/unix-time-helpers`                        | Unix timestamp utilities for seconds, milliseconds, high-resolution timing, and unit conversion                                                |
 
 ## Change Log
 

package/dist/lib/event-emitter.cjs

@@ -751,18 +751,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 {