assign-gingerly 0.0.23 → 0.0.24

package/README.md

@@ -33,10 +33,14 @@ On top of that, this polyfill package builds on the newly minted Custom Element
 
 2.  [itemscopeRegistry for Itemscope Managers](#itemscoperegistry) to automatically associate a function prototype or class instance with the itemscope attribute of an HTMLElement.
 
-3.  Custom Element Features [TODO]
+3.  Default Support For Not Replacing one object with another if it is a subclass. [TODO]
+
+4.  Custom Element Features [TODO]
 
 So in our view this package helps fill the void left by not supporting the "is" attribute for built-in elements (but is not a complete solution, just a critical building block).  Mount-observer, mount-observer-script-element, and custom enhancements builds on top of the critical role that assign-gingerly plays.
 
+5.  Iterator upgrade support [TODO] -- limited to ish?
+
 Anyway, let's start out detailing the more innocent features of this package / polyfill.
 
 The two utility functions are:
@@ -106,7 +110,220 @@ console.log(obj);
 
 When the right hand side of an expression is an object, assignGingerly is recursively applied (passing the third argument in if applicable, which will be discussed below).
 
-Of course, just as Object.assign led to object spread notation, assignGingerly could lead to some sort of deep structural JavaScript syntax, but that is outside the scope of this polyfill package. 
+Of course, just as Object.assign led to object spread notation, assignGingerly could lead to some sort of deep structural JavaScript syntax, but that is outside the scope of this polyfill package.
+
+## Example 3a - Automatic Readonly Property Detection
+
+assignGingerly automatically detects readonly properties and merges into them instead of attempting to replace them. This makes working with DOM properties like `style` and `dataset` much more ergonomic:
+
+```TypeScript
+// Instead of this verbose syntax:
+const div = document.createElement('div');
+assignGingerly(div, {
+    '?.style?.height': '15px',
+    '?.style?.width': '20px'
+});
+
+// You can now use this cleaner syntax:
+assignGingerly(div, {
+    style: {
+        height: '15px',
+        width: '20px'
+    }
+});
+console.log(div.style.height); // '15px'
+console.log(div.style.width);  // '20px'
+```
+
+**How it works:**
+
+When assignGingerly encounters an object value being assigned to an existing property, it checks if that property is readonly:
+- **Data properties** with `writable: false`
+- **Accessor properties** with a getter but no setter
+
+If the property is readonly and its current value is an object, assignGingerly automatically merges into it recursively.
+
+**Examples of readonly properties:**
+- `HTMLElement.style` - The CSSStyleDeclaration object
+- `HTMLElement.dataset` - The DOMStringMap object  
+- Custom objects with `Object.defineProperty(obj, 'prop', { value: {}, writable: false })`
+- Accessor properties with getter only: `Object.defineProperty(obj, 'prop', { get() { return {}; } })`
+
+**Error handling:**
+
+If you try to merge an object into a readonly property whose current value is a primitive, assignGingerly throws a descriptive error:
+
+```TypeScript
+const obj = {};
+Object.defineProperty(obj, 'readonlyString', {
+    value: 'immutable',
+    writable: false
+});
+
+assignGingerly(obj, {
+    readonlyString: { nested: 'value' }
+});
+// Error: Cannot merge object into readonly primitive property 'readonlyString'
+```
+
+**Additional examples:**
+
+```TypeScript
+// Dataset property
+const div = document.createElement('div');
+assignGingerly(div, {
+    dataset: {
+        userId: '123',
+        userName: 'Alice'
+    }
+});
+console.log(div.dataset.userId);   // '123'
+console.log(div.dataset.userName); // 'Alice'
+
+// Custom readonly property
+const config = {};
+Object.defineProperty(config, 'settings', {
+    value: {},
+    writable: false
+});
+assignGingerly(config, {
+    settings: {
+        theme: 'dark',
+        lang: 'en'
+    }
+});
+console.log(config.settings.theme); // 'dark'
+```
+
+## Example 3b - Automatic Class Instance Preservation
+
+In addition to readonly property detection, assignGingerly automatically preserves class instances when merging. This is particularly useful when working with enhancement instances:
+
+```TypeScript
+import 'assign-gingerly/object-extension.js';
+
+// Define an enhancement class
+class MyEnhancement {
+  constructor(element, ctx, initVals) {
+    this.element = element;
+    this.instanceId = Math.random(); // Track instance identity
+    if (initVals) {
+      Object.assign(this, initVals);
+    }
+  }
+  prop1 = null;
+  prop2 = null;
+}
+
+const element = document.createElement('div');
+element.enh = {
+  myEnh: new MyEnhancement(element, {}, {})
+};
+
+const originalId = element.enh.myEnh.instanceId;
+
+// Clean syntax - no need for ?.myEnh?.prop1 notation
+assignGingerly(element, {
+  enh: {
+    myEnh: {
+      prop1: 'value1',
+      prop2: 'value2'
+    }
+  }
+});
+
+console.log(element.enh.myEnh.instanceId === originalId); // true - instance preserved!
+console.log(element.enh.myEnh.prop1); // 'value1'
+console.log(element.enh.myEnh.prop2); // 'value2'
+```
+
+**How it works:**
+
+When assignGingerly encounters an object value being assigned to an existing property, it checks if the current value is a class instance (not a plain object):
+
+- **Class instances** are detected by checking if their prototype is something other than `Object.prototype` or `null`
+- **Plain objects** `{}` have `Object.prototype` as their prototype
+- **Class instances** have their class's prototype
+
+If the existing value is a class instance, assignGingerly merges into it instead of replacing it.
+
+**What counts as a class instance:**
+- Custom class instances: `new MyClass()`
+- Built-in class instances: `new Date()`, `new Map()`, `new Set()`, etc.
+- Enhancement instances on the `enh` property
+- Any object whose prototype is not `Object.prototype` or `null`
+
+**What doesn't count:**
+- Plain objects: `{}`, `{ a: 1 }`
+- Arrays: `[]`, `[1, 2, 3]` (arrays are replaced, not merged)
+- Primitives: strings, numbers, booleans
+
+**Benefits:**
+
+This feature enables clean, framework-friendly syntax for updating enhancements:
+
+```TypeScript
+// Before: Verbose nested path syntax
+assignGingerly(element, {
+  '?.enh?.mellowYellow?.madAboutFourteen': true
+});
+
+// After: Clean object syntax
+assignGingerly(element, {
+  enh: {
+    mellowYellow: {
+      madAboutFourteen: true
+    }
+  }
+});
+```
+
+**Additional examples:**
+
+```TypeScript
+// Multiple enhancements at once
+assignGingerly(element, {
+  enh: {
+    enhancement1: { prop: 'value1' },
+    enhancement2: { prop: 'value2' }
+  }
+});
+
+// Works with built-in classes too
+const obj = {
+  timestamp: new Date('2024-01-01')
+};
+
+assignGingerly(obj, {
+  timestamp: {
+    customProp: 'metadata'
+  }
+});
+
+console.log(obj.timestamp instanceof Date); // true - Date instance preserved
+console.log(obj.timestamp.customProp);      // 'metadata'
+```
+
+**Combined with readonly detection:**
+
+Both readonly properties and class instances are preserved:
+
+```TypeScript
+const div = document.createElement('div');
+div.enh = {
+  myEnh: new MyEnhancement(div, {}, {})
+};
+
+assignGingerly(div, {
+  style: { height: '100px' },      // Readonly - merged
+  enh: {
+    myEnh: { prop: 'value' }       // Class instance - merged
+  },
+  dataset: { userId: '123' }       // Readonly - merged
+});
+
+// All instances and readonly objects preserved
+```
 
 While we are in the business of passing values of object A into object B, we might as well add some extremely common behavior that allows updating properties of object B based on the current values of object B -- things like incrementing, toggling, and deleting.  Deleting is critical for assignTentatively, but is included with both functions.
 
@@ -171,7 +388,7 @@ For existing values, the toggle is performed using JavaScript's logical NOT oper
 
 ## Example 6 - Deleting properties with -= command
 
-The `-=` command allows you to delete properties from objects:
+The `-=` command allows us to delete properties from objects:
 
 ```TypeScript
 const obj = {
@@ -348,8 +565,13 @@ EnhancementRegistry.push([
 const result = assignGingerly({}, {
     [isHappy]: true,
     [isMellow]: true,
-    '?.style?.height': '40px',
-    '?.enh?.mellowYellow?.madAboutFourteen': true
+    style:{
+      height: '40px',
+    }, 
+    enh: {
+      '?.mellowYellow?.madAboutFourteen': true
+    }
+    
 }, {
     registry: EnhancementRegistry
 });
@@ -466,8 +688,12 @@ console.log(target.set[symbol1].prop2); // 'value2'
 const result = assignGingerly({}, {
     "[Symbol.for('TFWsx0YH5E6eSfhE7zfLxA')]": true,
     "[Symbol.for('BqnnTPWRHkWdVGWcGQoAiw')]": true,
-    '?.style.height': '40px',
-    '?.enh?.mellowYellow?.madAboutFourteen': true
+    style: {
+      height: '40px'
+    }
+    enh: {
+      mellowYellow?.madAboutFourteen': true
+    }
 }, {
     registry: EnhancementRegistry
 });
@@ -519,7 +745,7 @@ The prototype extensions are non-enumerable and won't appear in `Object.keys()`
 
 This package polyfill adds an "enhancementRegistry" registry on the CustomElementRegistry prototype.
 
-In this way, we achieve dependency injection in harmony with scoped custom elements DOM registry scope islands.
+In this way, we achieve dependency injection in harmony with scoped custom elements DOM registry scopes.
 
 > [!NOTE]
 > Safari/WebKit played a critical role in pushing scoped custom element registries forward, and announced with little fanfare or documentation that [Safari 26 supports it](https://developer.apple.com/documentation/safari-release-notes/safari-26-release-notes).  However, the Playwright test machinery's cross platform Safari test browser doesn't yet support it.  For now, only Chrome 146+ has been tested / vetted for this functionality.
@@ -597,7 +823,7 @@ Building on the Custom Element Registry integration, this package provides a pow
 
 ### Basic Usage
 
-The `enh.set` proxy allows you to assign properties to enhancements using a clean, chainable syntax:
+The `enh.set` proxy allows us to assign properties to enhancements using a clean, chainable syntax:
 
 ```TypeScript
 import 'assign-gingerly/object-extension.js';
@@ -693,7 +919,7 @@ Note that the class need not extend any base class or leverage any mixins.  In f
 <details>
 <summary>Passing Custom Context</summary>
 
-You can pass custom context when calling `enh.get()` or `enh.whenResolved()`:
+You can pass custom context when calling `enh.get()` or `enh.whenResolved()` (discussed in detail below):
 
 ```TypeScript
 // Pass custom context to the spawned instance
@@ -1419,7 +1645,8 @@ console.log(instance.count);  // 42 (parsed from attribute)
 console.log(instance.theme);  // 'dark' (parsed from attribute)
 ```
 
-**Example without enhKey:**
+<details>
+  <summary>Example without enhKey</summary>
 
 ```TypeScript
 // withAttrs works even without enhKey
@@ -1453,16 +1680,21 @@ const instance = element.enh.get(config);
 console.log(instance.value);  // 'test123' (parsed from attribute)
 ```
 
-**How it works:**
+</details>
+
+<details>
+  <summary>How it works</summary>
+
 1. When an enhancement is spawned via `enh.get()`, `enh.set`, or `assignGingerly()`
 2. If the registry item has a `withAttrs` property defined
 3. `parseWithAttrs(element, registryItem.withAttrs)` is automatically called
 4. The parsed attributes are passed to the enhancement constructor as `initVals`
 5. If the registry item also has an `enhKey`, the parsed attributes are merged with any existing values from `element.enh[enhKey]` (existing values take precedence)
 
-**Note**: `withAttrs` works with or without `enhKey`. When there's no `enhKey`, the parsed attributes are passed directly to the constructor. When there is an `enhKey`, they're merged with any pre-existing values on the enh container.
-
+</details>
 
+> ![NOTE]
+> `withAttrs` works with or without `enhKey`. When there's no `enhKey`, the parsed attributes are passed directly to the constructor. When there is an `enhKey`, they're merged with any pre-existing values on the enh container.
 
 ### The `enh-` Prefix for Attribute Isolation
 
@@ -1919,7 +2151,7 @@ const result = parseWithAttrs(element, {
 
 ### Default Values with valIfNull
 
-The `valIfNull` property allows you to specify default values when attributes are missing:
+The `valIfNull` property allows us to specify default values when attributes are missing:
 
 ```TypeScript
 // HTML: <div></div>  (no attributes)
@@ -2386,13 +2618,17 @@ buildCSSQuery(config, '  div  ,  span  ,  p  ');
 1. **Mount Observer Integration**: Find elements that need enhancement
    ```TypeScript
    // Match any element with the attributes
-   const query = buildCSSQuery(enhancementConfig);
-   const observer = new MutationObserver(() => {
-     const elements = document.querySelectorAll(query);
-     elements.forEach(el => enhance(el));
+   const matching = buildCSSQuery(enhancementConfig);
+   const observer = new MountObserver({
+      matching,
+      do: (mountedElement) => {
+        enhance(mountedElement);
+      }
    });
    ```
 
+   See [Mount-Observer](https://github.com/bahrus/mount-observer).
+
 2. **Specific Element Types**: Enhance only certain element types
    ```TypeScript
    const query = buildCSSQuery(config, 'template, script');

package/assignGingerly.js

@@ -227,6 +227,49 @@ function ensureNestedPath(obj, pathParts) {
     }
     return current;
 }
+/**
+ * Helper function to check if a property is readonly
+ * A property is readonly if:
+ * - It's a data property with writable: false, OR
+ * - It's an accessor property with a getter but no setter
+ */
+function isReadonlyProperty(obj, propName) {
+    let descriptor = Object.getOwnPropertyDescriptor(obj, propName);
+    if (!descriptor) {
+        // Check prototype chain
+        let proto = Object.getPrototypeOf(obj);
+        while (proto) {
+            descriptor = Object.getOwnPropertyDescriptor(proto, propName);
+            if (descriptor)
+                break;
+            proto = Object.getPrototypeOf(proto);
+        }
+    }
+    if (!descriptor)
+        return false;
+    // If it's a data property, check writable flag
+    if ('value' in descriptor) {
+        return descriptor.writable === false;
+    }
+    // If it's an accessor property, check if it has only a getter (no setter)
+    if ('get' in descriptor) {
+        return descriptor.set === undefined;
+    }
+    return false;
+}
+/**
+ * Helper function to check if a value is a class instance (not a plain object)
+ * Returns true for instances of classes, false for plain objects, arrays, and primitives
+ */
+function isClassInstance(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    if (Array.isArray(value))
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    // Plain objects have Object.prototype or null as prototype
+    return proto !== Object.prototype && proto !== null;
+}
 /**
  * Main assignGingerly function
  */
@@ -397,11 +440,23 @@ export function assignGingerly(target, source, options) {
             const lastKey = pathParts[pathParts.length - 1];
             const parent = ensureNestedPath(target, pathParts);
             if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
-                // Recursively apply assignGingerly for nested objects
-                if (!(lastKey in parent) || typeof parent[lastKey] !== 'object') {
-                    parent[lastKey] = {};
+                // Check if property exists and is readonly OR is a class instance
+                if (lastKey in parent && (isReadonlyProperty(parent, lastKey) || isClassInstance(parent[lastKey]))) {
+                    // Property is readonly or a class instance - check if current value is an object
+                    const currentValue = parent[lastKey];
+                    if (typeof currentValue !== 'object' || currentValue === null) {
+                        throw new Error(`Cannot merge object into ${isReadonlyProperty(parent, lastKey) ? 'readonly ' : ''}primitive property '${String(lastKey)}'`);
+                    }
+                    // Recursively apply assignGingerly to the readonly object or class instance
+                    assignGingerly(currentValue, value, options);
+                }
+                else {
+                    // Property is writable and not a class instance - normal recursive merge
+                    if (!(lastKey in parent) || typeof parent[lastKey] !== 'object') {
+                        parent[lastKey] = {};
+                    }
+                    assignGingerly(parent[lastKey], value, options);
                 }
-                assignGingerly(parent[lastKey], value, options);
             }
             else {
                 parent[lastKey] = value;
@@ -409,11 +464,23 @@ export function assignGingerly(target, source, options) {
         }
         else {
             if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
-                // Recursively apply assignGingerly for nested objects
-                if (!(key in target) || typeof target[key] !== 'object') {
-                    target[key] = {};
+                // Check if property exists and is readonly OR is a class instance
+                if (key in target && (isReadonlyProperty(target, key) || isClassInstance(target[key]))) {
+                    // Property is readonly or a class instance - check if current value is an object
+                    const currentValue = target[key];
+                    if (typeof currentValue !== 'object' || currentValue === null) {
+                        throw new Error(`Cannot merge object into ${isReadonlyProperty(target, key) ? 'readonly ' : ''}primitive property '${String(key)}'`);
+                    }
+                    // Recursively apply assignGingerly to the readonly object or class instance
+                    assignGingerly(currentValue, value, options);
+                }
+                else {
+                    // Property is writable and not a class instance - normal recursive merge
+                    if (!(key in target) || typeof target[key] !== 'object') {
+                        target[key] = {};
+                    }
+                    assignGingerly(target[key], value, options);
                 }
-                assignGingerly(target[key], value, options);
             }
             else {
                 target[key] = value;

package/assignGingerly.ts

@@ -309,6 +309,53 @@ function ensureNestedPath(obj: any, pathParts: string[]): any {
   return current;
 }
 
+/**
+ * Helper function to check if a property is readonly
+ * A property is readonly if:
+ * - It's a data property with writable: false, OR
+ * - It's an accessor property with a getter but no setter
+ */
+function isReadonlyProperty(obj: any, propName: string | symbol): boolean {
+  let descriptor = Object.getOwnPropertyDescriptor(obj, propName);
+  
+  if (!descriptor) {
+    // Check prototype chain
+    let proto = Object.getPrototypeOf(obj);
+    while (proto) {
+      descriptor = Object.getOwnPropertyDescriptor(proto, propName);
+      if (descriptor) break;
+      proto = Object.getPrototypeOf(proto);
+    }
+  }
+  
+  if (!descriptor) return false;
+  
+  // If it's a data property, check writable flag
+  if ('value' in descriptor) {
+    return descriptor.writable === false;
+  }
+  
+  // If it's an accessor property, check if it has only a getter (no setter)
+  if ('get' in descriptor) {
+    return descriptor.set === undefined;
+  }
+  
+  return false;
+}
+
+/**
+ * Helper function to check if a value is a class instance (not a plain object)
+ * Returns true for instances of classes, false for plain objects, arrays, and primitives
+ */
+function isClassInstance(value: any): boolean {
+  if (!value || typeof value !== 'object') return false;
+  if (Array.isArray(value)) return false;
+  
+  const proto = Object.getPrototypeOf(value);
+  // Plain objects have Object.prototype or null as prototype
+  return proto !== Object.prototype && proto !== null;
+}
+
 /**
  * Main assignGingerly function
  */
@@ -497,21 +544,43 @@ export function assignGingerly(
       const parent = ensureNestedPath(target, pathParts);
 
       if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
-        // Recursively apply assignGingerly for nested objects
-        if (!(lastKey in parent) || typeof parent[lastKey] !== 'object') {
-          parent[lastKey] = {};
+        // Check if property exists and is readonly OR is a class instance
+        if (lastKey in parent && (isReadonlyProperty(parent, lastKey) || isClassInstance(parent[lastKey]))) {
+          // Property is readonly or a class instance - check if current value is an object
+          const currentValue = parent[lastKey];
+          if (typeof currentValue !== 'object' || currentValue === null) {
+            throw new Error(`Cannot merge object into ${isReadonlyProperty(parent, lastKey) ? 'readonly ' : ''}primitive property '${String(lastKey)}'`);
+          }
+          // Recursively apply assignGingerly to the readonly object or class instance
+          assignGingerly(currentValue, value, options);
+        } else {
+          // Property is writable and not a class instance - normal recursive merge
+          if (!(lastKey in parent) || typeof parent[lastKey] !== 'object') {
+            parent[lastKey] = {};
+          }
+          assignGingerly(parent[lastKey], value, options);
         }
-        assignGingerly(parent[lastKey], value, options);
       } else {
         parent[lastKey] = value;
       }
     } else {
       if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
-        // Recursively apply assignGingerly for nested objects
-        if (!(key in target) || typeof target[key] !== 'object') {
-          target[key] = {};
+        // Check if property exists and is readonly OR is a class instance
+        if (key in target && (isReadonlyProperty(target, key) || isClassInstance(target[key]))) {
+          // Property is readonly or a class instance - check if current value is an object
+          const currentValue = target[key];
+          if (typeof currentValue !== 'object' || currentValue === null) {
+            throw new Error(`Cannot merge object into ${isReadonlyProperty(target, key) ? 'readonly ' : ''}primitive property '${String(key)}'`);
+          }
+          // Recursively apply assignGingerly to the readonly object or class instance
+          assignGingerly(currentValue, value, options);
+        } else {
+          // Property is writable and not a class instance - normal recursive merge
+          if (!(key in target) || typeof target[key] !== 'object') {
+            target[key] = {};
+          }
+          assignGingerly(target[key], value, options);
         }
-        assignGingerly(target[key], value, options);
       } else {
         target[key] = value;
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "assign-gingerly",
-  "version": "0.0.23",
+  "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/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[]
     
 }
 

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;
+    }
   });
 }