assign-gingerly 0.0.22 → 0.0.24

package/handleIshProperty.ts

@@ -0,0 +1,115 @@
+import type { IAssignGingerlyOptions, ItemscopeManagerConfig } from './assignGingerly.js';
+
+/**
+ * Handle the 'ish' property assignment for HTMLElements with itemscope attributes.
+ * This function validates the element and value, then defines or updates the 'ish' property.
+ * 
+ * @param element - The HTMLElement to assign the 'ish' property to
+ * @param value - The value to assign (must be an object)
+ * @param options - Optional assignGingerly options
+ * @param assignGingerlyFn - Reference to the assignGingerly function for recursive calls
+ */
+export async function handleIshProperty(
+  element: HTMLElement,
+  value: any,
+  options: IAssignGingerlyOptions | undefined,
+  assignGingerlyFn: (target: any, source: any, options?: IAssignGingerlyOptions) => any
+): Promise<void> {
+  // Validate itemscope attribute
+  const itemscopeValue = element.getAttribute('itemscope');
+  if (typeof itemscopeValue !== 'string' || itemscopeValue.length === 0) {
+    throw new Error('Element must have itemscope attribute set to a non-empty string value');
+  }
+
+  // Validate value is an object
+  if (typeof value !== 'object' || value === null) {
+    throw new Error('ish property value must be an object');
+  }
+
+  // Get or create the 'ish' property on the element
+  if (!('ish' in element)) {
+    await defineIshProperty(element, itemscopeValue, options, assignGingerlyFn);
+  }
+
+  // Queue the value for assignment
+  const ishDescriptor = Object.getOwnPropertyDescriptor(element, 'ish');
+  if (ishDescriptor && ishDescriptor.set) {
+    ishDescriptor.set.call(element, value);
+  }
+}
+
+/**
+ * Define the 'ish' property on an HTMLElement with itemscope attribute.
+ * This function handles both immediate and lazy manager instantiation.
+ * 
+ * @param element - The HTMLElement to define the 'ish' property on
+ * @param managerName - The name of the manager (from itemscope attribute)
+ * @param options - Optional assignGingerly options
+ * @param assignGingerlyFn - Reference to the assignGingerly function for recursive calls
+ */
+async function defineIshProperty(
+  element: HTMLElement,
+  managerName: string,
+  options: IAssignGingerlyOptions | undefined,
+  assignGingerlyFn: (target: any, source: any, options?: IAssignGingerlyOptions) => any
+): Promise<void> {
+  // Determine which registry to use
+  const registry = (element as any).customElementRegistry?.itemscopeRegistry
+    ?? (typeof customElements !== 'undefined' ? customElements.itemscopeRegistry : undefined);
+
+  if (!registry) {
+    throw new Error('ItemscopeRegistry not available');
+  }
+
+  // Check if manager is registered
+  let config = registry.get(managerName);
+
+  // If not registered, wait for registration
+  if (!config) {
+    const { waitForEvent } = await import('./waitForEvent.js');
+    await waitForEvent(registry, managerName);
+    config = registry.get(managerName);
+    
+    if (!config) {
+      throw new Error(`Manager "${managerName}" not found after registration event`);
+    }
+  }
+
+  // Create manager instance
+  let managerInstance: any = null;
+  const valueQueue: any[] = [];
+
+  // Define the 'ish' property
+  Object.defineProperty(element, 'ish', {
+    get() {
+      return managerInstance;
+    },
+    set(newValue: any) {
+      // If setting the same instance, do nothing
+      if (newValue === managerInstance) {
+        return;
+      }
+
+      // Queue the value
+      valueQueue.push(newValue);
+
+      // If manager not yet instantiated, create it
+      if (!managerInstance) {
+        // Merge all queued values for initVals
+        const initVals = Object.assign({}, ...valueQueue);
+        managerInstance = new config!.manager(element, initVals);
+        valueQueue.length = 0; // Clear queue
+      } else {
+        // Process queue asynchronously
+        (async () => {
+          while (valueQueue.length > 0) {
+            const queuedValue = valueQueue.shift();
+            await assignGingerlyFn(managerInstance, queuedValue, options);
+          }
+        })();
+      }
+    },
+    enumerable: true,
+    configurable: true,
+  });
+}

package/index.js

@@ -1,6 +1,6 @@
 export { assignGingerly } from './assignGingerly.js';
 export { assignTentatively } from './assignTentatively.js';
-export { EnhancementRegistry } from './assignGingerly.js';
+export { EnhancementRegistry, ItemscopeRegistry, EnhancementRegisteredEvent } from './assignGingerly.js';
 export { waitForEvent } from './waitForEvent.js';
 export { ParserRegistry, globalParserRegistry } from './parserRegistry.js';
 export { parseWithAttrs } from './parseWithAttrs.js';

package/index.ts

@@ -1,6 +1,6 @@
 export {assignGingerly} from './assignGingerly.js';
 export {assignTentatively} from './assignTentatively.js';
-export {EnhancementRegistry} from './assignGingerly.js';
+export {EnhancementRegistry, ItemscopeRegistry, EnhancementRegisteredEvent} from './assignGingerly.js';
 export {waitForEvent} from './waitForEvent.js';
 export {ParserRegistry, globalParserRegistry} from './parserRegistry.js';
 export {parseWithAttrs} from './parseWithAttrs.js';

package/object-extension.js

@@ -1,4 +1,4 @@
-import assignGingerly, { EnhancementRegistry, getInstanceMap } from './assignGingerly.js';
+import assignGingerly, { EnhancementRegistry, ItemscopeRegistry, getInstanceMap } from './assignGingerly.js';
 import { parseWithAttrs } from './parseWithAttrs.js';
 /**
  * Normalizes lifecycleKeys to always return an object with dispose and resolved keys
@@ -34,6 +34,25 @@ if (typeof CustomElementRegistry !== 'undefined') {
         enumerable: false,
         configurable: true,
     });
+    /**
+     * Adds itemscopeRegistry to CustomElementRegistry prototype as a lazy getter
+     */
+    Object.defineProperty(CustomElementRegistry.prototype, 'itemscopeRegistry', {
+        get: function () {
+            // Create a new ItemscopeRegistry instance on first access and cache it
+            const registry = new ItemscopeRegistry();
+            // Replace the getter with the actual value
+            Object.defineProperty(this, 'itemscopeRegistry', {
+                value: registry,
+                writable: true,
+                enumerable: false,
+                configurable: true,
+            });
+            return registry;
+        },
+        enumerable: false,
+        configurable: true,
+    });
 }
 /**
  * Enhancement container class for Element.prototype.enh

package/object-extension.ts

@@ -1,4 +1,4 @@
-import assignGingerly, { EnhancementRegistry, IAssignGingerlyOptions, getInstanceMap, INSTANCE_MAP_GUID } from './assignGingerly.js';
+import assignGingerly, { EnhancementRegistry, ItemscopeRegistry, IAssignGingerlyOptions, getInstanceMap, INSTANCE_MAP_GUID } from './assignGingerly.js';
 import { parseWithAttrs } from './parseWithAttrs.js';
 
 /**
@@ -17,11 +17,12 @@ function normalizeLifecycleKeys(lifecycleKeys: true | { dispose?: string | symbo
 }
 
 /**
- * Extends the CustomElementRegistry interface to include enhancementRegistry
+ * Extends the CustomElementRegistry interface to include enhancementRegistry and itemscopeRegistry
  */
 declare global {
   interface CustomElementRegistry {
     enhancementRegistry: typeof EnhancementRegistry | EnhancementRegistry;
+    itemscopeRegistry: ItemscopeRegistry;
   }
   
   interface Element {
@@ -97,6 +98,26 @@ if (typeof CustomElementRegistry !== 'undefined') {
     enumerable: false,
     configurable: true,
   });
+
+  /**
+   * Adds itemscopeRegistry to CustomElementRegistry prototype as a lazy getter
+   */
+  Object.defineProperty(CustomElementRegistry.prototype, 'itemscopeRegistry', {
+    get: function () {
+      // Create a new ItemscopeRegistry instance on first access and cache it
+      const registry = new ItemscopeRegistry();
+      // Replace the getter with the actual value
+      Object.defineProperty(this, 'itemscopeRegistry', {
+        value: registry,
+        writable: true,
+        enumerable: false,
+        configurable: true,
+      });
+      return registry;
+    },
+    enumerable: false,
+    configurable: true,
+  });
 }
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "assign-gingerly",
-  "version": "0.0.22",
+  "version": "0.0.24",
   "description": "This package provides a utility function for carefully merging one object into another.",
   "homepage": "https://github.com/bahrus/assign-gingerly#readme",
   "bugs": {
@@ -65,7 +65,7 @@
   "devDependencies": {
     "@playwright/test": "1.59.0-alpha-2026-02-28",
     "spa-ssi": "0.0.27",
-    "@types/node": "^25.3.3",
-    "typescript": "^5.9.3"
+    "@types/node": "25.5.0",
+    "typescript": "6.0.2"
   }
 }

package/parseWithAttrs.js

@@ -23,35 +23,38 @@ function resolveParser(parserSpec) {
     if (typeof parserSpec === 'function') {
         return parserSpec;
     }
-    // String reference - resolve it
-    if (typeof parserSpec === 'string') {
-        // Check if it's a custom element reference (contains dot)
-        if (parserSpec.includes('.')) {
-            const dotIndex = parserSpec.indexOf('.');
-            const elementName = parserSpec.substring(0, dotIndex);
-            const methodName = parserSpec.substring(dotIndex + 1);
-            // Try custom element lookup
-            if (typeof customElements !== 'undefined') {
-                try {
-                    const ctr = customElements.get(elementName);
-                    if (ctr && typeof ctr[methodName] === 'function') {
-                        return ctr[methodName];
-                    }
-                }
-                catch (e) {
-                    // customElements.get might throw, fall through to registry
-                }
+    // Tuple [CustomElementName, StaticMethodName] - resolve custom element static method
+    if (Array.isArray(parserSpec)) {
+        const [elementName, methodName] = parserSpec;
+        if (typeof customElements === 'undefined') {
+            throw new Error(`Cannot resolve parser [${elementName}, ${methodName}]: customElements is not available`);
+        }
+        try {
+            const ctr = customElements.get(elementName);
+            if (!ctr) {
+                throw new Error(`Cannot resolve parser [${elementName}, ${methodName}]: custom element "${elementName}" not found`);
             }
-            // Fall through to global registry (allows dot notation in registry too)
+            if (typeof ctr[methodName] !== 'function') {
+                throw new Error(`Cannot resolve parser [${elementName}, ${methodName}]: static method "${methodName}" not found on custom element "${elementName}"`);
+            }
+            return ctr[methodName];
+        }
+        catch (e) {
+            if (e instanceof Error && e.message.startsWith('Cannot resolve parser')) {
+                throw e;
+            }
+            throw new Error(`Cannot resolve parser [${elementName}, ${methodName}]: ${e instanceof Error ? e.message : String(e)}`);
         }
-        // Try global registry
+    }
+    // String reference - resolve from global registry
+    if (typeof parserSpec === 'string') {
         const parser = globalParserRegistry.get(parserSpec);
         if (parser) {
             return parser;
         }
-        // Not found anywhere
-        throw new Error(`Parser "${parserSpec}" not found. ` +
-            `Check that it's registered in globalParserRegistry or exists as a static method on the custom element.`);
+        // Not found in registry
+        throw new Error(`Parser "${parserSpec}" not found in globalParserRegistry. ` +
+            `If you want to reference a custom element static method, use tuple syntax: ["element-name", "methodName"]`);
     }
     return undefined;
 }
@@ -71,6 +74,9 @@ function getCacheKey(config) {
     else if (typeof config.parser === 'string') {
         parserStr = `named:${config.parser}`;
     }
+    else if (Array.isArray(config.parser)) {
+        parserStr = `tuple:${config.parser[0]}.${config.parser[1]}`;
+    }
     else {
         parserStr = 'custom';
     }

package/parseWithAttrs.ts

@@ -17,7 +17,9 @@ const parseCache = new Map<string, Map<string, any>>();
  * @returns The resolved parser function
  * @throws Error if parser cannot be resolved
  */
-function resolveParser(parserSpec: ((v: string | null) => any) | string | undefined): ((v: string | null) => any) | undefined {
+function resolveParser(
+  parserSpec: ((v: string | null) => any) | string | [string, string] | undefined
+): ((v: string | null) => any) | undefined {
   // Undefined - no parser specified
   if (parserSpec === undefined) {
     return undefined;
@@ -28,39 +30,52 @@ function resolveParser(parserSpec: ((v: string | null) => any) | string | undefi
     return parserSpec;
   }
   
-  // String reference - resolve it
-  if (typeof parserSpec === 'string') {
-    // Check if it's a custom element reference (contains dot)
-    if (parserSpec.includes('.')) {
-      const dotIndex = parserSpec.indexOf('.');
-      const elementName = parserSpec.substring(0, dotIndex);
-      const methodName = parserSpec.substring(dotIndex + 1);
+  // Tuple [CustomElementName, StaticMethodName] - resolve custom element static method
+  if (Array.isArray(parserSpec)) {
+    const [elementName, methodName] = parserSpec;
+    
+    if (typeof customElements === 'undefined') {
+      throw new Error(
+        `Cannot resolve parser [${elementName}, ${methodName}]: customElements is not available`
+      );
+    }
+    
+    try {
+      const ctr = customElements.get(elementName);
+      if (!ctr) {
+        throw new Error(
+          `Cannot resolve parser [${elementName}, ${methodName}]: custom element "${elementName}" not found`
+        );
+      }
       
-      // Try custom element lookup
-      if (typeof customElements !== 'undefined') {
-        try {
-          const ctr = customElements.get(elementName);
-          if (ctr && typeof (ctr as any)[methodName] === 'function') {
-            return (ctr as any)[methodName];
-          }
-        } catch (e) {
-          // customElements.get might throw, fall through to registry
-        }
+      if (typeof (ctr as any)[methodName] !== 'function') {
+        throw new Error(
+          `Cannot resolve parser [${elementName}, ${methodName}]: static method "${methodName}" not found on custom element "${elementName}"`
+        );
       }
       
-      // Fall through to global registry (allows dot notation in registry too)
+      return (ctr as any)[methodName];
+    } catch (e) {
+      if (e instanceof Error && e.message.startsWith('Cannot resolve parser')) {
+        throw e;
+      }
+      throw new Error(
+        `Cannot resolve parser [${elementName}, ${methodName}]: ${e instanceof Error ? e.message : String(e)}`
+      );
     }
-    
-    // Try global registry
+  }
+  
+  // String reference - resolve from global registry
+  if (typeof parserSpec === 'string') {
     const parser = globalParserRegistry.get(parserSpec);
     if (parser) {
       return parser;
     }
     
-    // Not found anywhere
+    // Not found in registry
     throw new Error(
-      `Parser "${parserSpec}" not found. ` +
-      `Check that it's registered in globalParserRegistry or exists as a static method on the custom element.`
+      `Parser "${parserSpec}" not found in globalParserRegistry. ` +
+      `If you want to reference a custom element static method, use tuple syntax: ["element-name", "methodName"]`
     );
   }
   
@@ -82,6 +97,8 @@ function getCacheKey(config: AttrConfig<any>): string {
     parserStr = 'builtin';
   } else if (typeof config.parser === 'string') {
     parserStr = `named:${config.parser}`;
+  } else if (Array.isArray(config.parser)) {
+    parserStr = `tuple:${config.parser[0]}.${config.parser[1]}`;
   } else {
     parserStr = 'custom';
   }

package/playwright.config.ts

@@ -20,7 +20,7 @@ export default defineConfig({
   /* Opt out of parallel tests on CI. */
   workers: process.env.CI ? 1 : undefined,
   /* Reporter to use. See https://playwright.dev/docs/test-reporters */
-  reporter: 'html',
+  reporter: [ ['html', { open: 'never' }] ],
   /* Shared settings for all the projects below. See https://playwright.dev/docs/api/class-testoptions. */
   use: {
     /* Base URL to use in actions like `await page.goto('/')`. */
@@ -34,15 +34,15 @@ export default defineConfig({
       use: { ...devices['Desktop Chrome'] },
     },
 
-    {
-      name: 'firefox',
-      use: { ...devices['Desktop Firefox'] },
-    },
+    // {
+    //   name: 'firefox',
+    //   use: { ...devices['Desktop Firefox'] },
+    // },
 
-    {
-      name: 'webkit',
-      use: { ...devices['Desktop Safari'] },
-    },
+    // {
+    //   name: 'webkit',
+    //   use: { ...devices['Desktop Safari'] },
+    // },
   ],
 
   /* Run your local dev server before starting the tests */

package/types/assign-gingerly/types.d.ts

@@ -30,35 +30,40 @@ export type Spawner<T = any, Obj = Element> = {
   canSpawn?: (obj: any, ctx?: SpawnContext<T>) => boolean;
 }
 
+export interface EnhancementConfigBase<T = any> {
+    //Allow unprefixed attributes for custom elements and SVG when element tag name matches pattern
+    allowUnprefixed?: string | RegExp;
+    
+    //keys of type symbol are used for dependency injection
+    //and are used by assign-gingerly
+    symlinks?: { [key: symbol]: keyof T };
+    
+    lifecycleKeys?: 
+    | true  // Use standard names: "dispose" method, "resolved" property/event
+    | {
+        dispose?: string | symbol,
+        resolved?: string | symbol
+      }
+    //used by mount-observer, not by assign-gingerly
+    //impossible to polyfill, but will always be disposed
+    //when oElement's reference count goes to zero
+    disposeOn?: DisposeEvent | DisposeEvent[]
+}
+
 /**
  * Configuration for enhancing elements with class instances
  * Defines how to spawn and initialize enhancement classes
  */
-export interface EnhancementConfig<T = any, Obj = Element> {
+export interface EnhancementConfig<T = any, Obj = Element> extends EnhancementConfigBase<T> {
   
   spawn: Spawner<T, Obj>;
   
   //Applicable to passing in the initVals during the spawn lifecycle event
   withAttrs?: AttrPatterns<T>;
   
-  //Allow unprefixed attributes for custom elements and SVG when element tag name matches pattern
-  allowUnprefixed?: string | RegExp;
-  
-  //keys of type symbol are used for dependency injection
-  //and are used by assign-gingerly
-  symlinks?: { [key: symbol]: keyof T };
+
   //only applicable when spawning from a DOM Element reference
   enhKey?: EnhKey;
-  lifecycleKeys?: 
-    | true  // Use standard names: "dispose" method, "resolved" property/event
-    | {
-        dispose?: string | symbol,
-        resolved?: string | symbol
-      }
-  //used by mount-observer, not by assign-gingerly
-  //impossible to polyfill, but will always be disposed
-  //when oElement's reference count goes to zero
-  disposeOn?: DisposeEvent | DisposeEvent[]
     
 }
 
@@ -66,6 +71,9 @@ export type Constructor = new (...args: any[]) => any;
 
 export type pathString = `?.${string}`;
 
+export type CustomElementName = string;
+export type CustomElementConstructorStaticMethodName = string;
+
 export interface AttrConfig<T = any> {
   /**
    * Type of the property value (JSON-serializable string format)
@@ -92,12 +100,14 @@ export interface AttrConfig<T = any> {
   /**
    * Parser to transform attribute string value
    * - Function: Inline parser function (not JSON serializable)
-   * - String: Named parser reference (JSON serializable)
-   *   - Simple name: Looks up in global parser registry (e.g., 'timestamp', 'csv')
-   *   - Dot notation: Looks up static method on custom element (e.g., 'my-widget.parseSpecial')
-   *     Falls back to global registry if custom element not found
+   * - String: Named parser reference (JSON serializable) - looks up in global parser registry (e.g., 'timestamp', 'csv')
+   * - Tuple: [CustomElementName, StaticMethodName] - looks up static method on custom element constructor (e.g., ['my-widget', 'parseSpecial'])
    */
-  parser?: ((attrValue: string | null) => any) | string;
+  parser?: 
+    | ((attrValue: string | null) => any) 
+    | string 
+    | [CustomElementName, CustomElementConstructorStaticMethodName]
+  ;
   
   /**
    * Default value to use when attribute is missing
@@ -161,10 +171,20 @@ export interface IAssignGingerlyOptions {
   bypassChecks?: boolean;
 }
 
+/**
+ * Event dispatched when enhancement configs are registered
+ */
+export declare class EnhancementRegisteredEvent extends Event {
+  static eventName: string;
+  config: EnhancementConfig | EnhancementConfig[];
+  constructor(config: EnhancementConfig | EnhancementConfig[]);
+}
+
 /**
  * Base registry class for managing enhancement configurations
+ * Extends EventTarget to dispatch events when configs are registered
  */
-export declare class EnhancementRegistry {
+export declare class EnhancementRegistry extends EventTarget {
   private items;
   push(items: EnhancementConfig | EnhancementConfig[]): void;
   getItems(): EnhancementConfig[];
@@ -172,6 +192,43 @@ export declare class EnhancementRegistry {
   findByEnhKey(enhKey: string | symbol): EnhancementConfig | undefined;
 }
 
+/**
+ * Constructor signature for ItemScope Manager classes
+ */
+export type ItemscopeManager<T = any> = {
+  new (element: HTMLElement, initVals?: Partial<T>): T;
+}
+
+/**
+ * Configuration for ItemScope Manager registration
+ */
+export interface ItemscopeManagerConfig<T = any> {
+  /**
+   * Manager class constructor
+   */
+  manager: ItemscopeManager<T>;
+  
+  /**
+   * Optional lifecycle method keys
+   * - dispose: Method name to call when manager is disposed
+   * - resolved: Property/event name indicating manager is ready
+   */
+  lifecycleKeys?: {
+    dispose?: string | symbol;
+    resolved?: string | symbol;
+  };
+}
+
+/**
+ * Registry for ItemScope Manager configurations
+ * Extends EventTarget to support lazy registration via events
+ */
+export declare class ItemscopeRegistry extends EventTarget {
+  define(name: string, config: ItemscopeManagerConfig): void;
+  get(name: string): ItemscopeManagerConfig | undefined;
+  whenDefined(name: string): Promise<void>;
+}
+
 /**
  * Main assignGingerly function
  */

package/types/global.d.ts

@@ -23,3 +23,7 @@ interface WeakMap<K extends object, V> {
    */
   getOrInsertComputed(key: K, insert: () => V): V;
 }
+
+interface HTMLTemplateElement {
+  remoteContent?: Node;
+}

package/waitForEvent.js

@@ -3,17 +3,31 @@
  * @param et - The EventTarget to listen on
  * @param eventName - The event name to wait for (resolves the promise)
  * @param failureEventName - Optional event name that rejects the promise
+ * @param timeout - Optional timeout in milliseconds (rejects if exceeded)
  * @returns Promise that resolves with the event
  */
-export function waitForEvent(et, eventName, failureEventName) {
+export function waitForEvent(et, eventName, failureEventName, timeout) {
     return new Promise((resolve, reject) => {
+        let timeoutId;
+        const cleanup = () => {
+            if (timeoutId !== undefined) {
+                clearTimeout(timeoutId);
+            }
+        };
         et.addEventListener(eventName, (e) => {
+            cleanup();
             resolve(e);
         }, { once: true });
         if (failureEventName !== undefined) {
             et.addEventListener(failureEventName, (e) => {
+                cleanup();
                 reject(e);
             }, { once: true });
         }
+        if (timeout !== undefined && timeout > 0) {
+            timeoutId = setTimeout(() => {
+                reject(new Error(`Timeout waiting for event '${eventName}' after ${timeout}ms`));
+            }, timeout);
+        }
     });
 }

package/waitForEvent.ts

@@ -3,17 +3,28 @@
  * @param et - The EventTarget to listen on
  * @param eventName - The event name to wait for (resolves the promise)
  * @param failureEventName - Optional event name that rejects the promise
+ * @param timeout - Optional timeout in milliseconds (rejects if exceeded)
  * @returns Promise that resolves with the event
  */
 export function waitForEvent<TEvent extends Event = Event>(
   et: EventTarget,
   eventName: string,
-  failureEventName?: string
+  failureEventName?: string,
+  timeout?: number
 ): Promise<TEvent> {
   return new Promise((resolve, reject) => {
+    let timeoutId: number | undefined;
+    
+    const cleanup = () => {
+      if (timeoutId !== undefined) {
+        clearTimeout(timeoutId);
+      }
+    };
+    
     et.addEventListener(
       eventName,
       (e) => {
+        cleanup();
         resolve(e as TEvent);
       },
       { once: true }
@@ -23,10 +34,17 @@ export function waitForEvent<TEvent extends Event = Event>(
       et.addEventListener(
         failureEventName,
         (e) => {
+          cleanup();
           reject(e as TEvent);
         },
         { once: true }
       );
     }
+    
+    if (timeout !== undefined && timeout > 0) {
+      timeoutId = setTimeout(() => {
+        reject(new Error(`Timeout waiting for event '${eventName}' after ${timeout}ms`));
+      }, timeout) as unknown as number;
+    }
   });
 }