assign-gingerly 0.0.17 → 0.0.19

package/README.md

@@ -23,8 +23,14 @@ One can achieve the same functionality with a little more work, and "playing nic
 
 Not only does this polyfill package allow merging data properties onto objects that are expecting them, this polyfill also provides the ability to merge *augmented behavior* onto run-time objects without sub classing all such objects of the same type. This includes the ability to spawn an instance of a class and "merge" it into the API of the original object in an elegant way that is easy to wrap one's brain around, without ever blocking access to the original object or breaking it.
 
+
+
 So we are providing a form of the ["Decorator Pattern"](https://en.wikipedia.org/wiki/Decorator_pattern) or perhaps more accurately the [Extension Object Pattern](https://swiftorial.com/swiftlessons/design-patterns/structural-patterns/extension-object-pattern) as tailored for the quirks of the web.  
 
+## Custom Enhancement Registry
+
+On top of that, this polyfill package builds on the newly minted Custom Element Registry, adding an additional EnhancementRegistry object on top of the customElementRegistry object associated with all elements, to be able to manage namespace conflicts, and, importantly, as a basis for defining custom attributes associated with the enhancements.
+
 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.
 
 Anyway, let's start out detailing the more innocent features of this package / polyfill.
@@ -33,7 +39,7 @@ The two utility functions are:
 
 ## assignGingerly
 
-assignGingerly builds on Object.assign.  Like Object.assign, the object getting assigned can be a JSON stringified object.  Some of the unusual syntax we see with assignGingerly is there to continue to support JSON deserialized objects as a viable argument to be passed.  
+assignGingerly builds on Object.assign.  Like Object.assign, the object getting assigned can often be a JSON stringified object.  Some of the unusual syntax we see with assignGingerly is there to continue to support JSON deserialized objects as a viable argument to be passed.  
 
 assign-gingerly adds support for:
 
@@ -96,7 +102,9 @@ 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).
 
-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
+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. 
+
+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.
 
 ## Example 4 - Incrementing values with += command
 
@@ -213,8 +221,7 @@ console.log(obj);
 - Non-existent properties are silently skipped
 - If the parent path doesn't exist, the command is silently skipped
 - For root-level deletion, use ` -=` (space before -=)
-//   }
-// }
+
 
 
 
@@ -285,9 +292,9 @@ This guarantees that applying the reversal object restores the object to its exa
 ## Dependency injection based on a registry object and a Symbolic reference mapping
 
 ```Typescript
-interface IBaseRegistryItem<T = any> {
-    spawn: {new(): T} | Promise<{new(): T}>
-    symlinks: {[key: symbol]: keyof T}
+interface IEnhancementRegistryItem<T = any, TObjToExtend = any> {
+    spawn: {new(objToExtend: TObjToExtend, ctx: SpawnContext, initVals: Partial<T>): T}
+    symlinks?: {[key: symbol]: keyof T}
     // Optional: for element enhancement access
     enhKey?: string
     // Optional: automatic attribute parsing 
@@ -310,15 +317,15 @@ class YourEnhancement{
     set madAboutFourteen(nv){}
 }
 
-class BaseRegistry{
-    push(IBaseRegistryItem | IBaseRegistryItem[]){
+class EnhancementRegistry{
+    push(IEnhancementRegistryItem | IEnhancementRegistryItem[]){
         ...
     }
 }
 
 //Here's where the dependency injection mapping takes place
-const baseRegistry = new BaseRegistry;
-baseRegistry.push([
+const EnhancementRegistry = new EnhancementRegistry;
+EnhancementRegistry.push([
     {
         symlinks: {
             [isHappy]: 'isHappy'
@@ -340,7 +347,7 @@ const result = assignGingerly({}, {
     '?.style?.height': '40px',
     '?.enh?.mellowYellow?.madAboutFourteen': true
 }, {
-    registry: BaseRegistry
+    registry: EnhancementRegistry
 });
 //result.set[isMellow] = false;
 ```
@@ -394,7 +401,7 @@ const registryItem = {
   enhKey: 'myEnh'
 };
 
-const registry = new BaseRegistry();
+const registry = new EnhancementRegistry();
 registry.push(registryItem);
 
 const element = document.createElement('div');
@@ -431,7 +438,7 @@ const registryItem = {
   }
 };
 
-const registry = new BaseRegistry();
+const registry = new EnhancementRegistry();
 registry.push(registryItem);
 
 const target = {};
@@ -458,7 +465,7 @@ const result = assignGingerly({}, {
     '?.style.height': '40px',
     '?.enh?.mellowYellow?.madAboutFourteen': true
 }, {
-    registry: BaseRegistry
+    registry: EnhancementRegistry
 });
 ```
 </details>
@@ -508,6 +515,9 @@ The prototype extensions are non-enumerable and won't appear in `Object.keys()`
 
 This package includes support for Chrome's scoped custom element registries, which automatically integrates dependency injection in harmony with scoped custom elements DOM sections or ShadowRoots.
 
+> [!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.
+
 <details>
   <summary>Automatic Registry Population</summary>
 
@@ -515,7 +525,6 @@ When `assignGingerly` or `assignTentatively` is called on an Element instance wi
 
 ```TypeScript
 import 'assign-gingerly/object-extension.js';
-import { BaseRegistry } from 'assign-gingerly';
 
 // Set up a registry on the custom element registry
 const myElement = document.createElement('div');
@@ -542,7 +551,7 @@ myElement.assignGingerly({
 <details>
 <summary>Lazy Registry Creation</summary>
 
-Each `CustomElementRegistry` instance gets its own `enhancementRegistry` property via a lazy getter. The `BaseRegistry` instance is created on first access and cached for subsequent uses:
+Each `CustomElementRegistry` instance gets its own `enhancementRegistry` property via a lazy getter. The `EnhancementRegistry` instance is created on first access and cached for subsequent uses:
 
 ```TypeScript
 const element1 = document.createElement('div');
@@ -563,7 +572,7 @@ console.log(registry1 === element1.customElementRegistry.enhancementRegistry); /
 You can still provide an explicit `registry` option to override the automatic behavior:
 
 ```TypeScript
-const customRegistry = new BaseRegistry();
+const customRegistry = new EnhancementRegistry();
 // ... configure customRegistry ...
 
 myElement.assignGingerly({
@@ -584,7 +593,7 @@ The `enh.set` proxy allows you to assign properties to enhancements using a clea
 
 ```TypeScript
 import 'assign-gingerly/object-extension.js';
-//import { BaseRegistry } from 'assign-gingerly';
+//import { EnhancementRegistry } from 'assign-gingerly';
 
 // Define an enhancement class
 class MyEnhancement {
@@ -649,15 +658,15 @@ This approach is part of a proposal to WHATWG for standardizing element enhancem
 
 ### Constructor Signature
 
-Enhancement classes should follow this constructor signature:
+Element enhancement classes should follow this constructor signature:
 
 ```TypeScript
 interface SpawnContext<T, TMountContext = any> {
-  config: IBaseRegistryItem<T>;
+  config: IEnhancementRegistryItem<T>;
   mountCtx?: TMountContext;  // Optional custom context passed by caller
 }
 
-class Enhancement {
+class Enhancement<T> {
   constructor(
     oElement?: Element,      // The element being enhanced
     ctx?: SpawnContext,      // Context with registry item info and optional mountCtx
@@ -671,6 +680,8 @@ class Enhancement {
 
 All parameters are optional for backward compatibility with existing code.
 
+Note that the class need not extend any base class or leverage any mixins.  In fact, ES5 prototype functions can be used, and in both cases are instanted using new ....  Arrow functions cannot be used.
+
 <details>
 <summary>Passing Custom Context</summary>
 
@@ -705,10 +716,10 @@ This is useful for:
 In addition to spawn and symlinks, registry items support optional properties `enhKey`, `withAttrs`, `canSpawn`, and `lifecycleKeys`:
 
 ```TypeScript
-interface IBaseRegistryItem<T> {
+interface IEnhancementRegistryItem<T, TObj = Element> {
   spawn: { 
-    new (oElement?: Element, ctx?: SpawnContext<T>, initVals?: Partial<T>): T;
-    canSpawn?: (obj: any, ctx?: SpawnContext<T>) => boolean;  // Optional spawn guard
+    new (obj?: TObj, ctx?: SpawnContext<T>, initVals?: Partial<T>): T;
+    canSpawn?: (obj: TObj, ctx?: SpawnContext<T>) => boolean;  // Optional spawn guard
   };
   symlinks?: { [key: string | symbol]: keyof T };
   enhKey?: string;  // String identifier for set proxy access
@@ -802,10 +813,10 @@ console.log(element.enh.plainData); // { prop1: 'value1', prop2: 'value2' }
 <details>
 <summary>Finding Registry Items by enhKey</summary>
 
-The `BaseRegistry` class includes a `findByEnhKey` method:
+The `EnhancementRegistry` class includes a `findByEnhKey` method:
 
 ```TypeScript
-const registry = new BaseRegistry();
+const registry = new EnhancementRegistry();
 registry.push({
   spawn: MyEnhancement,
   enhKey: 'myEnh'
@@ -818,7 +829,7 @@ console.log(item.enhKey); // 'myEnh'
 
 ### Programmatic Instance Spawning with `enh.get()`
 
-The `enh.get(registryItem)` method provides a programmatic way to spawn or retrieve enhancement instances:
+The `enh.get(registryItem)` method provides a programmatic way to spawn or retrieve previously instantiated enhancement instances:
 
 ```TypeScript
 const registryItem = {
@@ -948,9 +959,9 @@ Note: Symbol event names are not yet supported by the platform but have been req
 
 </details>
 
-### Disposing Enhancement Instances with `enh.dispose()`
+### Disposing Enhancement Instances with `enh.dispose(regItem)`
 
-The `enh.dispose()` method provides a way to clean up and remove enhancement instances:
+The `enh.dispose(regItem)` method provides a way to clean up and remove enhancement instances:
 
 ```TypeScript
 class MyEnhancement {
@@ -991,7 +1002,7 @@ const instance = element.enh.get(registryItem);
 element.enh.dispose(registryItem);
 ```
 
-**How `enh.dispose()` works:**
+**How `enh.dispose(regItem)` works:**
 
 1. **Retrieves instance**: Gets the spawned instance from the global instance map
 2. **Calls lifecycle method**: If `lifecycleKeys.dispose` is specified, calls that method on the instance (passing the registry item)
@@ -1043,9 +1054,9 @@ element.enh.dispose(registryItem); // Stops timer and cleans up
 - Calling `enh.get()` again will create a new instance
 - The enhancement property is removed from the enh container
 
-### Waiting for Async Initialization with `enh.whenResolved()`
+### Waiting for Async Initialization with `enh.whenResolved(regItem)`
 
-The `enh.whenResolved()` method provides a way to wait for asynchronous enhancement initialization:
+The `enh.whenResolved(regItem)` method provides a way to wait for asynchronous enhancement initialization:
 
 ```TypeScript
 class AsyncEnhancement extends EventTarget {
@@ -1217,7 +1228,7 @@ class DivOnlyEnhancement {
   }
 }
 
-const registry = new BaseRegistry();
+const registry = new EnhancementRegistry();
 registry.push({
   spawn: DivOnlyEnhancement,
   enhKey: 'divOnly'
@@ -1251,7 +1262,7 @@ static canSpawn(obj: any, ctx?: SpawnContext<T>): boolean
 ```
 
 - `obj`: The target object being enhanced (element, plain object, etc.)
-- `ctx`: Optional spawn context containing `{ config: IBaseRegistryItem<T> }`
+- `ctx`: Optional spawn context containing `{ config: IEnhancementRegistryItem<T> }`
 - Returns: `true` to allow spawning, `false` to block
 
 ### Use Cases
@@ -1318,7 +1329,7 @@ class ValidatedEnhancement {
 ### Example with Dependency Injection
 
 ```TypeScript
-import assignGingerly, { BaseRegistry } from 'assign-gingerly';
+import assignGingerly, { EnhancementRegistry } from 'assign-gingerly';
 
 class ElementOnlyEnhancement {
   value = null;
@@ -1328,7 +1339,7 @@ class ElementOnlyEnhancement {
   }
 }
 
-const registry = new BaseRegistry();
+const registry = new EnhancementRegistry();
 const enhSymbol = Symbol.for('myEnhancement');
 
 registry.push({
@@ -1351,11 +1362,11 @@ assignGingerly(element, { [enhSymbol]: 'test' }, { registry });
 
 ## Parsing Attributes with `parseWithAttrs`
 
-The `parseWithAttrs` function provides a declarative way to read and parse HTML attributes into structured data objects. It's particularly useful for custom elements and web components that need to extract configuration from attributes.
+The `parseWithAttrs` function provides a declarative way to read and parse HTML attributes and pass the parsed values into the spawned enhancement constructor. 
 
 ### Automatic Integration with Enhancement Spawning
 
-**Important**: When using the `enh.get()`, `enh.set`, or `assignGingerly()` methods with registry items, you typically **do not need to call `parseWithAttrs()` manually**. The attribute parsing happens automatically during enhancement spawning when you include a `withAttrs` property in your registry item.
+**Important**: When using the `enh.get()`, `enh.set`, or `assignGingerly()` methods with registry items, you typically **do not need to call `parseWithAttrs()` manually**. The attribute parsing happens automatically during enhancement spawning when you include a `withAttrs` property in your registry item configuration.
 
 ```html
 <my-element my-enhancement-count="42" my-enhancement-theme="dark"></my-element>
@@ -1747,6 +1758,8 @@ const result = parseWithAttrs(element, config);
 
 **Built-in Named Parsers:**
 
+[TODO]: Check if this is all needed
+
 The following parsers are pre-registered in `globalParserRegistry`:
 
 - `'timestamp'` - Parses ISO date string to Unix timestamp (milliseconds)
@@ -2209,7 +2222,11 @@ const elements = document.querySelectorAll(query);
 **Without selectors (matches any element):**
 
 ```TypeScript
+// Omit the selectors parameter
+const query = buildCSSQuery(config);
+// or explicitly pass empty string
 const query = buildCSSQuery(config, '');
+
 console.log(query);
 // '[my-component], [enh-my-component], [my-component-theme], [enh-my-component-theme]'
 
@@ -2300,7 +2317,7 @@ buildCSSQuery(config, 'div');
 
 ### Edge Cases
 
-**Empty selectors return attribute-only selectors:**
+**Omitting or empty selectors return attribute-only selectors:**
 ```TypeScript
 const config = {
   spawn: MyClass,
@@ -2310,8 +2327,10 @@ const config = {
   }
 };
 
-buildCSSQuery(config, '');
-// '[my-attr], [enh-my-attr], [my-attr-theme], [enh-my-attr-theme]'
+buildCSSQuery(config);  // Omit selectors parameter
+// or
+buildCSSQuery(config, '');  // Empty string
+// Both return: '[my-attr], [enh-my-attr], [my-attr-theme], [enh-my-attr-theme]'
 // Matches any element with these attributes
 ```
 
@@ -2338,7 +2357,7 @@ 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 query = buildCSSQuery(enhancementConfig);
    const observer = new MutationObserver(() => {
      const elements = document.querySelectorAll(query);
      elements.forEach(el => enhance(el));
@@ -2364,19 +2383,19 @@ buildCSSQuery(config, '  div  ,  span  ,  p  ');
 ```TypeScript
 function buildCSSQuery(
   config: EnhancementConfig,
-  selectors: string
+  selectors?: string
 ): string
 ```
 
 **Parameters:**
 - `config`: Enhancement configuration with `withAttrs` property
-- `selectors`: Comma-separated CSS selectors (e.g., `'div, span'`)
-  - If empty string or whitespace only, returns attribute selectors without element prefix
+- `selectors` (optional): Comma-separated CSS selectors (e.g., `'div, span'`)
+  - If omitted or empty string, returns attribute selectors without element prefix
   - This matches any element with the specified attributes
 
 **Returns:**
 - CSS query string with cross-product of selectors and attributes
-- If selectors is empty: returns attribute-only selectors (e.g., `'[attr], [enh-attr]'`)
+- If selectors is omitted or empty: returns attribute-only selectors (e.g., `'[attr], [enh-attr]'`)
 - If withAttrs is missing or empty: returns empty string
 
 **Throws:**

package/assignGingerly.js

@@ -1,3 +1,21 @@
+// Polyfill for Map.prototype.getOrInsert and WeakMap.prototype.getOrInsert
+if (typeof Map.prototype.getOrInsert !== 'function') {
+  Map.prototype.getOrInsert = function(key, insert) {
+    if (this.has(key)) return this.get(key);
+    const value = insert();
+    this.set(key, value);
+    return value;
+  };
+}
+if (typeof WeakMap.prototype.getOrInsert !== 'function') {
+  WeakMap.prototype.getOrInsert = function(key, insert) {
+    if (this.has(key)) return this.get(key);
+    const value = insert();
+    this.set(key, value);
+    return value;
+  };
+}
+
 /**
  * GUID for global instance map storage to ensure uniqueness across package versions
  */
@@ -16,7 +34,7 @@ export function getInstanceMap() {
 /**
  * Base registry class for managing enhancement configurations
  */
-export class BaseRegistry {
+export class EnhancementRegistry {
     items = [];
     push(items) {
         if (Array.isArray(items)) {
@@ -142,7 +160,7 @@ export function assignGingerly(target, source, options) {
     if (!target || typeof target !== 'object') {
         return target;
     }
-    const registry = options?.registry instanceof BaseRegistry
+    const registry = options?.registry instanceof EnhancementRegistry
         ? options.registry
         : options?.registry
             ? new options.registry()
@@ -305,10 +323,7 @@ export function assignGingerly(target, source, options) {
             if (registryItem) {
                 const instanceMap = getInstanceMap();
                 // Get or initialize the instances map for this target
-                if (!instanceMap.has(target)) {
-                    instanceMap.set(target, new Map());
-                }
-                const instances = instanceMap.get(target);
+                const instances = instanceMap.getOrInsert(target, () => new Map());
                 // Check if instance already exists (keyed by registryItem)
                 let instance = instances.get(registryItem);
                 if (!instance) {
@@ -363,10 +378,7 @@ export function assignGingerly(target, source, options) {
                             const registryItem = registry.findBySymbol(prop);
                             if (registryItem) {
                                 const instanceMap = getInstanceMap();
-                                if (!instanceMap.has(target)) {
-                                    instanceMap.set(target, new Map());
-                                }
-                                const instances = instanceMap.get(target);
+                                const instances = instanceMap.getOrInsert(target, () => new Map());
                                 let instance = instances.get(registryItem);
                                 if (!instance) {
                                     const SpawnClass = registryItem.spawn;

package/assignGingerly.ts

@@ -11,7 +11,7 @@ export type IBaseRegistryItem<T = any> = EnhancementConfig<T>;
  * Interface for the options passed to assignGingerly
  */
 export interface IAssignGingerlyOptions {
-  registry?: typeof BaseRegistry | BaseRegistry;
+  registry?: typeof EnhancementRegistry | EnhancementRegistry;
 }
 
 /**
@@ -34,7 +34,7 @@ export function getInstanceMap(): WeakMap<object, Map<EnhancementConfig, any>> {
 /**
  * Base registry class for managing enhancement configurations
  */
-export class BaseRegistry {
+export class EnhancementRegistry {
   private items: EnhancementConfig[] = [];
 
   push(items: EnhancementConfig | EnhancementConfig[]): void {
@@ -179,7 +179,7 @@ export function assignGingerly(
     return target;
   }
 
-  const registry = options?.registry instanceof BaseRegistry
+  const registry = options?.registry instanceof EnhancementRegistry
     ? options.registry
     : options?.registry
     ? new options.registry()
@@ -350,10 +350,7 @@ export function assignGingerly(
       if (registryItem) {
         const instanceMap = getInstanceMap();
         // Get or initialize the instances map for this target
-        if (!instanceMap.has(target)) {
-          instanceMap.set(target, new Map());
-        }
-        const instances = instanceMap.get(target)!;
+        const instances = instanceMap.getOrInsert(target, () => new Map());
 
         // Check if instance already exists (keyed by registryItem)
         let instance = instances.get(registryItem);
@@ -418,10 +415,7 @@ export function assignGingerly(
                 const registryItem = registry.findBySymbol(prop);
                 if (registryItem) {
                   const instanceMap = getInstanceMap();
-                  if (!instanceMap.has(target)) {
-                    instanceMap.set(target, new Map());
-                  }
-                  const instances = instanceMap.get(target)!;
+                  const instances = instanceMap.getOrInsert(target, () => new Map());
                   let instance = instances.get(registryItem);
 
                   if (!instance) {

package/buildCSSQuery.js

@@ -1,44 +1,11 @@
-/**
- * Resolves template variables in a string recursively
- * @param template - Template string with ${var} placeholders
- * @param patterns - The patterns object containing variable values
- * @param resolvedCache - Cache of already resolved values
- * @param visitedKeys - Set of keys being resolved (for cycle detection)
- * @returns Resolved string
- */
-function resolveTemplate(template, patterns, resolvedCache, visitedKeys = new Set()) {
-    return template.replace(/\$\{(\w+)\}/g, (match, varName) => {
-        // Check if already resolved
-        if (resolvedCache.has(varName)) {
-            return resolvedCache.get(varName);
-        }
-        // Check for circular reference
-        if (visitedKeys.has(varName)) {
-            throw new Error(`Circular reference detected in template variable: ${varName}`);
-        }
-        const value = patterns[varName];
-        if (value === undefined) {
-            throw new Error(`Undefined template variable: ${varName}`);
-        }
-        if (typeof value === 'string') {
-            // Recursively resolve
-            visitedKeys.add(varName);
-            const resolved = resolveTemplate(value, patterns, resolvedCache, visitedKeys);
-            visitedKeys.delete(varName);
-            resolvedCache.set(varName, resolved);
-            return resolved;
-        }
-        // Non-string value, return as-is
-        return String(value);
-    });
-}
+import { resolveTemplate } from './resolveTemplate.js';
 /**
  * Extracts attribute names from withAttrs configuration
  * Resolves template variables and excludes underscore-prefixed config keys
  * @param withAttrs - The attribute patterns configuration
  * @returns Array of resolved attribute names
  */
-function extractAttributeNames(withAttrs) {
+export function extractAttributeNames(withAttrs) {
     const names = [];
     const resolvedCache = new Map();
     // Add base if present
@@ -64,8 +31,8 @@ function extractAttributeNames(withAttrs) {
  * Creates a cross-product of selectors and attribute names (both prefixed and unprefixed)
  *
  * @param config - Enhancement configuration with withAttrs
- * @param selectors - Comma-separated CSS selectors to match (e.g., 'template, script')
- *                    If empty, returns just the attribute selectors without element prefix
+ * @param selectors - Optional comma-separated CSS selectors to match (e.g., 'template, script')
+ *                    If omitted or empty, returns just the attribute selectors without element prefix
  * @returns CSS query string with cross-product of selectors and attributes
  *
  * @example
@@ -83,6 +50,8 @@ function extractAttributeNames(withAttrs) {
  * //           div[my-attr-theme], span[my-attr-theme], div[enh-my-attr-theme], span[enh-my-attr-theme]'
  *
  * // Without selectors (matches any element)
+ * buildCSSQuery(config);
+ * // or
  * buildCSSQuery(config, '');
  * // Returns: '[my-attr], [enh-my-attr], [my-attr-theme], [enh-my-attr-theme]'
  */

package/buildCSSQuery.ts

@@ -1,49 +1,5 @@
 import { EnhancementConfig, AttrPatterns } from './types/assign-gingerly/types';
-
-/**
- * Resolves template variables in a string recursively
- * @param template - Template string with ${var} placeholders
- * @param patterns - The patterns object containing variable values
- * @param resolvedCache - Cache of already resolved values
- * @param visitedKeys - Set of keys being resolved (for cycle detection)
- * @returns Resolved string
- */
-function resolveTemplate(
-    template: string,
-    patterns: Record<string, any>,
-    resolvedCache: Map<string, string>,
-    visitedKeys: Set<string> = new Set()
-): string {
-    return template.replace(/\$\{(\w+)\}/g, (match, varName) => {
-        // Check if already resolved
-        if (resolvedCache.has(varName)) {
-            return resolvedCache.get(varName)!;
-        }
-        
-        // Check for circular reference
-        if (visitedKeys.has(varName)) {
-            throw new Error(`Circular reference detected in template variable: ${varName}`);
-        }
-        
-        const value = patterns[varName];
-        
-        if (value === undefined) {
-            throw new Error(`Undefined template variable: ${varName}`);
-        }
-        
-        if (typeof value === 'string') {
-            // Recursively resolve
-            visitedKeys.add(varName);
-            const resolved = resolveTemplate(value, patterns, resolvedCache, visitedKeys);
-            visitedKeys.delete(varName);
-            resolvedCache.set(varName, resolved);
-            return resolved;
-        }
-        
-        // Non-string value, return as-is
-        return String(value);
-    });
-}
+import { resolveTemplate } from './resolveTemplate.js';
 
 /**
  * Extracts attribute names from withAttrs configuration
@@ -51,7 +7,7 @@ function resolveTemplate(
  * @param withAttrs - The attribute patterns configuration
  * @returns Array of resolved attribute names
  */
-function extractAttributeNames(withAttrs: AttrPatterns<any>): string[] {
+export function extractAttributeNames(withAttrs: AttrPatterns<any>): string[] {
     const names: string[] = [];
     const resolvedCache = new Map<string, string>();
     
@@ -82,8 +38,8 @@ function extractAttributeNames(withAttrs: AttrPatterns<any>): string[] {
  * Creates a cross-product of selectors and attribute names (both prefixed and unprefixed)
  * 
  * @param config - Enhancement configuration with withAttrs
- * @param selectors - Comma-separated CSS selectors to match (e.g., 'template, script')
- *                    If empty, returns just the attribute selectors without element prefix
+ * @param selectors - Optional comma-separated CSS selectors to match (e.g., 'template, script')
+ *                    If omitted or empty, returns just the attribute selectors without element prefix
  * @returns CSS query string with cross-product of selectors and attributes
  * 
  * @example
@@ -101,12 +57,14 @@ function extractAttributeNames(withAttrs: AttrPatterns<any>): string[] {
  * //           div[my-attr-theme], span[my-attr-theme], div[enh-my-attr-theme], span[enh-my-attr-theme]'
  * 
  * // Without selectors (matches any element)
+ * buildCSSQuery(config);
+ * // or
  * buildCSSQuery(config, '');
  * // Returns: '[my-attr], [enh-my-attr], [my-attr-theme], [enh-my-attr-theme]'
  */
 export function buildCSSQuery(
     config: EnhancementConfig,
-    selectors: string
+    selectors?: string
 ): string {
     // Validate inputs
     if (!config.withAttrs) {

package/global.d.ts

@@ -0,0 +1,25 @@
+// Type declarations for Map.prototype.getOrInsert and WeakMap.prototype.getOrInsert
+// Feature is now supported in all modern browsers (Chrome 146+, Firefox 134+, Safari 18.2+)
+// See: https://web-platform-dx.github.io/web-features-explorer/features/getorinsert/
+
+interface Map<K, V> {
+  /**
+   * Returns the value associated with the key if it exists, otherwise inserts
+   * the value returned by the insert callback and returns it.
+   * @param key The key to look up
+   * @param insert A callback that returns the value to insert if the key doesn't exist
+   * @returns The existing or newly inserted value
+   */
+  getOrInsert(key: K, insert: () => V): V;
+}
+
+interface WeakMap<K extends object, V> {
+  /**
+   * Returns the value associated with the key if it exists, otherwise inserts
+   * the value returned by the insert callback and returns it.
+   * @param key The key to look up
+   * @param insert A callback that returns the value to insert if the key doesn't exist
+   * @returns The existing or newly inserted value
+   */
+  getOrInsert(key: K, insert: () => V): V;
+}

package/index.js

@@ -1,8 +1,9 @@
 export { assignGingerly } from './assignGingerly.js';
 export { assignTentatively } from './assignTentatively.js';
-export { BaseRegistry } from './assignGingerly.js';
+export { EnhancementRegistry } from './assignGingerly.js';
 export { waitForEvent } from './waitForEvent.js';
 export { ParserRegistry, globalParserRegistry } from './parserRegistry.js';
 export { parseWithAttrs } from './parseWithAttrs.js';
 export { buildCSSQuery } from './buildCSSQuery.js';
+export { resolveTemplate } from './resolveTemplate.js';
 import './object-extension.js';

package/index.ts

@@ -1,8 +1,9 @@
 export {assignGingerly} from './assignGingerly.js';
 export {assignTentatively} from './assignTentatively.js';
-export {BaseRegistry} from './assignGingerly.js';
+export {EnhancementRegistry} from './assignGingerly.js';
 export {waitForEvent} from './waitForEvent.js';
 export {ParserRegistry, globalParserRegistry} from './parserRegistry.js';
 export {parseWithAttrs} from './parseWithAttrs.js';
 export {buildCSSQuery} from './buildCSSQuery.js';
+export {resolveTemplate} from './resolveTemplate.js';
 import './object-extension.js';

package/object-extension.js

@@ -1,4 +1,22 @@
-import assignGingerly, { BaseRegistry, getInstanceMap } from './assignGingerly.js';
+// Polyfill for Map.prototype.getOrInsert and WeakMap.prototype.getOrInsert
+if (typeof Map.prototype.getOrInsert !== 'function') {
+  Map.prototype.getOrInsert = function(key, insert) {
+    if (this.has(key)) return this.get(key);
+    const value = insert();
+    this.set(key, value);
+    return value;
+  };
+}
+if (typeof WeakMap.prototype.getOrInsert !== 'function') {
+  WeakMap.prototype.getOrInsert = function(key, insert) {
+    if (this.has(key)) return this.get(key);
+    const value = insert();
+    this.set(key, value);
+    return value;
+  };
+}
+
+import assignGingerly, { EnhancementRegistry, getInstanceMap } from './assignGingerly.js';
 import { parseWithAttrs } from './parseWithAttrs.js';
 /**
  * Normalizes lifecycleKeys to always return an object with dispose and resolved keys
@@ -21,7 +39,7 @@ if (typeof CustomElementRegistry !== 'undefined') {
     Object.defineProperty(CustomElementRegistry.prototype, 'enhancementRegistry', {
         get: function () {
             // Create a new BaseRegistry instance on first access and cache it
-            const registry = new BaseRegistry();
+            const registry = new EnhancementRegistry();
             // Replace the getter with the actual value
             Object.defineProperty(this, 'enhancementRegistry', {
                 value: registry,
@@ -66,10 +84,7 @@ class ElementEnhancementContainer {
         }
         // Get or create instance using the global instance map
         const instanceMap = getInstanceMap();
-        if (!instanceMap.has(element)) {
-            instanceMap.set(element, new Map());
-        }
-        const instances = instanceMap.get(element);
+        const instances = instanceMap.getOrInsert(element, () => new Map());
         let instance = instances.get(registryItem);
         if (!instance) {
             // Need to spawn
@@ -201,10 +216,7 @@ class ElementEnhancementContainer {
                             const SpawnClass = registryItem.spawn;
                             // Check the global instance map first
                             const instanceMap = getInstanceMap();
-                            if (!instanceMap.has(element)) {
-                                instanceMap.set(element, new Map());
-                            }
-                            const instances = instanceMap.get(element);
+                            const instances = instanceMap.getOrInsert(element, () => new Map());
                             let instance = instances.get(registryItem);
                             if (!instance) {
                                 // Need to spawn
@@ -259,10 +271,7 @@ if (typeof Element !== 'undefined') {
     const enhContainerWeakMap = new WeakMap();
     Object.defineProperty(Element.prototype, 'enh', {
         get: function () {
-            if (!enhContainerWeakMap.has(this)) {
-                enhContainerWeakMap.set(this, new ElementEnhancementContainer(this));
-            }
-            return enhContainerWeakMap.get(this);
+            return enhContainerWeakMap.getOrInsert(this, () => new ElementEnhancementContainer(this));
         },
         enumerable: true,
         configurable: true,

package/object-extension.ts

@@ -1,4 +1,4 @@
-import assignGingerly, { BaseRegistry, IAssignGingerlyOptions, getInstanceMap, INSTANCE_MAP_GUID } from './assignGingerly.js';
+import assignGingerly, { EnhancementRegistry, IAssignGingerlyOptions, getInstanceMap, INSTANCE_MAP_GUID } from './assignGingerly.js';
 import { parseWithAttrs } from './parseWithAttrs.js';
 
 /**
@@ -21,7 +21,7 @@ function normalizeLifecycleKeys(lifecycleKeys: true | { dispose?: string | symbo
  */
 declare global {
   interface CustomElementRegistry {
-    enhancementRegistry: typeof BaseRegistry | BaseRegistry;
+    enhancementRegistry: typeof EnhancementRegistry | EnhancementRegistry;
   }
   
   interface Element {
@@ -84,7 +84,7 @@ if (typeof CustomElementRegistry !== 'undefined') {
   Object.defineProperty(CustomElementRegistry.prototype, 'enhancementRegistry', {
     get: function () {
       // Create a new BaseRegistry instance on first access and cache it
-      const registry = new BaseRegistry();
+      const registry = new EnhancementRegistry();
       // Replace the getter with the actual value
       Object.defineProperty(this, 'enhancementRegistry', {
         value: registry,
@@ -136,10 +136,7 @@ class ElementEnhancementContainer {
     
     // Get or create instance using the global instance map
     const instanceMap = getInstanceMap();
-    if (!instanceMap.has(element)) {
-      instanceMap.set(element, new Map());
-    }
-    const instances = instanceMap.get(element)!;
+    const instances = instanceMap.getOrInsert(element, () => new Map());
     
     let instance = instances.get(registryItem);
     
@@ -304,10 +301,7 @@ class ElementEnhancementContainer {
               
               // Check the global instance map first
               const instanceMap = getInstanceMap();
-              if (!instanceMap.has(element)) {
-                instanceMap.set(element, new Map());
-              }
-              const instances = instanceMap.get(element)!;
+              const instances = instanceMap.getOrInsert(element, () => new Map());
               
               let instance = instances.get(registryItem);
               
@@ -376,11 +370,7 @@ if (typeof Element !== 'undefined') {
   
   Object.defineProperty(Element.prototype, 'enh', {
     get: function (this: Element) {
-      if (!enhContainerWeakMap.has(this)) {
-        enhContainerWeakMap.set(this, new ElementEnhancementContainer(this));
-      }
-      
-      return enhContainerWeakMap.get(this);
+      return enhContainerWeakMap.getOrInsert(this, () => new ElementEnhancementContainer(this));
     },
     enumerable: true,
     configurable: true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "assign-gingerly",
-  "version": "0.0.17",
+  "version": "0.0.19",
   "description": "This package provides a utility function for carefully merging one object into another.",
   "homepage": "https://github.com/bahrus/assign-gingerly#readme",
   "bugs": {
@@ -47,6 +47,10 @@
     "./buildCSSQuery.js": {
       "default": "./buildCSSQuery.js",
       "types": "./buildCSSQuery.ts"
+    },
+    "./resolveTemplate.js": {
+      "default": "./resolveTemplate.js",
+      "types": "./resolveTemplate.ts"
     }
   },
   "main": "index.js",

package/parseWithAttrs.js

@@ -1,4 +1,23 @@
+// Polyfill for Map.prototype.getOrInsert and WeakMap.prototype.getOrInsert
+if (typeof Map.prototype.getOrInsert !== 'function') {
+  Map.prototype.getOrInsert = function(key, insert) {
+    if (this.has(key)) return this.get(key);
+    const value = insert();
+    this.set(key, value);
+    return value;
+  };
+}
+if (typeof WeakMap.prototype.getOrInsert !== 'function') {
+  WeakMap.prototype.getOrInsert = function(key, insert) {
+    if (this.has(key)) return this.get(key);
+    const value = insert();
+    this.set(key, value);
+    return value;
+  };
+}
+
 import { globalParserRegistry } from './parserRegistry.js';
+import { resolveTemplate } from './resolveTemplate.js';
 // Module-level cache for parsed attribute values
 // Structure: Map<configKey, Map<attrValue, parsedValue>>
 const parseCache = new Map();
@@ -89,10 +108,7 @@ function parseWithCache(attrValue, config, parser) {
     }
     // Get or create cache for this config
     const cacheKey = getCacheKey(config);
-    if (!parseCache.has(cacheKey)) {
-        parseCache.set(cacheKey, new Map());
-    }
-    const valueCache = parseCache.get(cacheKey);
+    const valueCache = parseCache.getOrInsert(cacheKey, () => new Map());
     // Use special key for null values
     const valueCacheKey = attrValue === null ? '__NULL__' : attrValue;
     // Check if we have a cached value
@@ -160,40 +176,6 @@ function getAttributeValue(element, attrName, allowUnprefixed) {
         return enhValue;
     return element.getAttribute(attrName);
 }
-/**
- * Resolves template variables in a string recursively
- * @param template - Template string with ${var} placeholders
- * @param patterns - The patterns object containing variable values
- * @param resolvedCache - Cache of already resolved values
- * @param visitedKeys - Set of keys being resolved (for cycle detection)
- * @returns Resolved string
- */
-function resolveTemplate(template, patterns, resolvedCache, visitedKeys = new Set()) {
-    return template.replace(/\$\{(\w+)\}/g, (match, varName) => {
-        // Check if already resolved
-        if (resolvedCache.has(varName)) {
-            return resolvedCache.get(varName);
-        }
-        // Check for circular reference
-        if (visitedKeys.has(varName)) {
-            throw new Error(`Circular reference detected in template variable: ${varName}`);
-        }
-        const value = patterns[varName];
-        if (value === undefined) {
-            throw new Error(`Undefined template variable: ${varName}`);
-        }
-        if (typeof value === 'string') {
-            // Recursively resolve
-            visitedKeys.add(varName);
-            const resolved = resolveTemplate(value, patterns, resolvedCache, visitedKeys);
-            visitedKeys.delete(varName);
-            resolvedCache.set(varName, resolved);
-            return resolved;
-        }
-        // Non-string value, return as-is
-        return String(value);
-    });
-}
 /**
  * Gets the default parser for a given instanceOf type
  */

package/parseWithAttrs.ts

@@ -1,5 +1,6 @@
 import { AttrPatterns, AttrConfig } from './types/assign-gingerly/types';
 import { globalParserRegistry } from './parserRegistry.js';
+import { resolveTemplate } from './resolveTemplate.js';
 
 // Module-level cache for parsed attribute values
 // Structure: Map<configKey, Map<attrValue, parsedValue>>
@@ -107,11 +108,7 @@ function parseWithCache(
   
   // Get or create cache for this config
   const cacheKey = getCacheKey(config);
-  if (!parseCache.has(cacheKey)) {
-    parseCache.set(cacheKey, new Map());
-  }
-  
-  const valueCache = parseCache.get(cacheKey)!;
+  const valueCache = parseCache.getOrInsert(cacheKey, () => new Map());
   
   // Use special key for null values
   const valueCacheKey = attrValue === null ? '__NULL__' : attrValue;
@@ -193,51 +190,6 @@ function getAttributeValue(
   return element.getAttribute(attrName);
 }
 
-/**
- * Resolves template variables in a string recursively
- * @param template - Template string with ${var} placeholders
- * @param patterns - The patterns object containing variable values
- * @param resolvedCache - Cache of already resolved values
- * @param visitedKeys - Set of keys being resolved (for cycle detection)
- * @returns Resolved string
- */
-function resolveTemplate(
-    template: string,
-    patterns: Record<string, any>,
-    resolvedCache: Map<string, string>,
-    visitedKeys: Set<string> = new Set()
-): string {
-    return template.replace(/\$\{(\w+)\}/g, (match, varName) => {
-        // Check if already resolved
-        if (resolvedCache.has(varName)) {
-            return resolvedCache.get(varName)!;
-        }
-        
-        // Check for circular reference
-        if (visitedKeys.has(varName)) {
-            throw new Error(`Circular reference detected in template variable: ${varName}`);
-        }
-        
-        const value = patterns[varName];
-        
-        if (value === undefined) {
-            throw new Error(`Undefined template variable: ${varName}`);
-        }
-        
-        if (typeof value === 'string') {
-            // Recursively resolve
-            visitedKeys.add(varName);
-            const resolved = resolveTemplate(value, patterns, resolvedCache, visitedKeys);
-            visitedKeys.delete(varName);
-            resolvedCache.set(varName, resolved);
-            return resolved;
-        }
-        
-        // Non-string value, return as-is
-        return String(value);
-    });
-}
-
 /**
  * Gets the default parser for a given instanceOf type
  */

package/resolveTemplate.js

@@ -0,0 +1,49 @@
+/**
+ * Resolves template variables in a string recursively
+ * Supports ${varName} syntax for variable substitution
+ *
+ * @param template - Template string with ${var} placeholders
+ * @param patterns - The patterns object containing variable values
+ * @param resolvedCache - Cache of already resolved values
+ * @param visitedKeys - Set of keys being resolved (for cycle detection)
+ * @returns Resolved string
+ *
+ * @throws Error if circular reference is detected
+ * @throws Error if template variable is undefined
+ *
+ * @example
+ * const patterns = {
+ *   base: 'my-component',
+ *   theme: '${base}-theme'
+ * };
+ * const cache = new Map();
+ *
+ * resolveTemplate('${theme}', patterns, cache);
+ * // Returns: 'my-component-theme'
+ */
+export function resolveTemplate(template, patterns, resolvedCache, visitedKeys = new Set()) {
+    return template.replace(/\$\{(\w+)\}/g, (_match, varName) => {
+        // Check if already resolved
+        if (resolvedCache.has(varName)) {
+            return resolvedCache.get(varName);
+        }
+        // Check for circular reference
+        if (visitedKeys.has(varName)) {
+            throw new Error(`Circular reference detected in template variable: ${varName}`);
+        }
+        const value = patterns[varName];
+        if (value === undefined) {
+            throw new Error(`Undefined template variable: ${varName}`);
+        }
+        if (typeof value === 'string') {
+            // Recursively resolve
+            visitedKeys.add(varName);
+            const resolved = resolveTemplate(value, patterns, resolvedCache, visitedKeys);
+            visitedKeys.delete(varName);
+            resolvedCache.set(varName, resolved);
+            return resolved;
+        }
+        // Non-string value, return as-is
+        return String(value);
+    });
+}

package/resolveTemplate.ts

@@ -0,0 +1,59 @@
+/**
+ * Resolves template variables in a string recursively
+ * Supports ${varName} syntax for variable substitution
+ * 
+ * @param template - Template string with ${var} placeholders
+ * @param patterns - The patterns object containing variable values
+ * @param resolvedCache - Cache of already resolved values
+ * @param visitedKeys - Set of keys being resolved (for cycle detection)
+ * @returns Resolved string
+ * 
+ * @throws Error if circular reference is detected
+ * @throws Error if template variable is undefined
+ * 
+ * @example
+ * const patterns = {
+ *   base: 'my-component',
+ *   theme: '${base}-theme'
+ * };
+ * const cache = new Map();
+ * 
+ * resolveTemplate('${theme}', patterns, cache);
+ * // Returns: 'my-component-theme'
+ */
+export function resolveTemplate(
+    template: string,
+    patterns: Record<string, any>,
+    resolvedCache: Map<string, string>,
+    visitedKeys: Set<string> = new Set()
+): string {
+    return template.replace(/\$\{(\w+)\}/g, (_match, varName) => {
+        // Check if already resolved
+        if (resolvedCache.has(varName)) {
+            return resolvedCache.get(varName)!;
+        }
+        
+        // Check for circular reference
+        if (visitedKeys.has(varName)) {
+            throw new Error(`Circular reference detected in template variable: ${varName}`);
+        }
+        
+        const value = patterns[varName];
+        
+        if (value === undefined) {
+            throw new Error(`Undefined template variable: ${varName}`);
+        }
+        
+        if (typeof value === 'string') {
+            // Recursively resolve
+            visitedKeys.add(varName);
+            const resolved = resolveTemplate(value, patterns, resolvedCache, visitedKeys);
+            visitedKeys.delete(varName);
+            resolvedCache.set(varName, resolved);
+            return resolved;
+        }
+        
+        // Non-string value, return as-is
+        return String(value);
+    });
+}

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

@@ -25,16 +25,18 @@ type DisposeEvent =
     //reference count outside any enhancements goes to zero
     | 'dispose'
 
+export type Spawner<T = any, Obj = Element> = {
+  new (obj?: Obj, ctx?: SpawnContext<T>, initVals?: Partial<T>): T;
+  canSpawn?: (obj: any, ctx?: SpawnContext<T>) => boolean;
+}
+
 /**
  * Configuration for enhancing elements with class instances
  * Defines how to spawn and initialize enhancement classes
  */
-export interface EnhancementConfig<T = any> {
+export interface EnhancementConfig<T = any, Obj = Element> {
   
-  spawn: { 
-    new (obj?: any, ctx?: SpawnContext<T>, initVals?: Partial<T>): T;
-    canSpawn?: (obj: any, ctx?: SpawnContext<T>) => boolean;
-  };
+  spawn: Spawner<T, Obj>;
   
   //Applicable to passing in the initVals during the spawn lifecycle event
   withAttrs?: AttrPatterns<T>;
@@ -180,3 +182,11 @@ export declare function assignGingerly(
 ): any;
 
 export default assignGingerly;
+
+export declare class ElementEnhancementGateway{
+  enh: ElementEnhancement;
+}
+
+export interface ElementEnhancement{
+  dispose(regItem: EnhancementConfig): void;
+}