assign-gingerly 0.0.11 → 0.0.13

package/assignGingerly.js

@@ -344,9 +344,11 @@ export function assignGingerly(target, source, options) {
                     }
                 }
                 // Find the mapped property name
-                const mappedKey = registryItem.symlinks[sym];
-                if (mappedKey && instance && typeof instance === 'object') {
-                    instance[mappedKey] = value;
+                if (registryItem.symlinks) {
+                    const mappedKey = registryItem.symlinks[sym];
+                    if (mappedKey && instance && typeof instance === 'object') {
+                        instance[mappedKey] = value;
+                    }
                 }
             }
         }
@@ -397,9 +399,11 @@ export function assignGingerly(target, source, options) {
                                         target.enh[registryItem.enhKey] = instance;
                                     }
                                 }
-                                const mappedKey = registryItem.symlinks[prop];
-                                if (mappedKey && instance && typeof instance === 'object') {
-                                    instance[mappedKey] = value;
+                                if (registryItem.symlinks) {
+                                    const mappedKey = registryItem.symlinks[prop];
+                                    if (mappedKey && instance && typeof instance === 'object') {
+                                        instance[mappedKey] = value;
+                                    }
                                 }
                             }
                         }

package/assignGingerly.ts

@@ -1,22 +1,6 @@
-/**
- * Configuration for enhancing elements with class instances
- */
-export interface EnhancementConfig<T = any> {
-  spawn: { 
-    new (oElement?: Element, ctx?: SpawnContext<T>, initVals?: Partial<T>): T;
-    canSpawn?: (obj: any, ctx?: SpawnContext<T>) => boolean;
-  };
-  symlinks: { [key: string | symbol]: keyof T };
-  enhKey?: string;
-  lifecycleKeys?: {
-    dispose?: string;
-    resolved?: string;
-  };
-}
 
-export interface SpawnContext<T = any> {
-  config: EnhancementConfig<T>;
-}
+
+import { EnhancementConfig } from "./types";
 
 /**
  * @deprecated Use EnhancementConfig instead
@@ -411,10 +395,13 @@ export function assignGingerly(
         }
 
         // Find the mapped property name
-        const mappedKey = registryItem.symlinks[sym];
-        if (mappedKey && instance && typeof instance === 'object') {
-          (instance as any)[mappedKey] = value;
+        if(registryItem.symlinks){
+          const mappedKey = registryItem.symlinks[sym];
+          if (mappedKey && instance && typeof instance === 'object') {
+            (instance as any)[mappedKey] = value;
+          }
         }
+
       }
     }
   }
@@ -471,11 +458,13 @@ export function assignGingerly(
                       (target as any).enh[registryItem.enhKey] = instance;
                     }
                   }
-                  
-                  const mappedKey = registryItem.symlinks[prop];
-                  if (mappedKey && instance && typeof instance === 'object') {
-                    (instance as any)[mappedKey] = value;
+                  if(registryItem.symlinks){
+                    const mappedKey = registryItem.symlinks[prop];
+                    if (mappedKey && instance && typeof instance === 'object') {
+                      (instance as any)[mappedKey] = value;
+                    }
                   }
+
                 }
               }
               return true;

package/index.js

@@ -2,4 +2,6 @@ export { assignGingerly } from './assignGingerly.js';
 export { assignTentatively } from './assignTentatively.js';
 export { BaseRegistry } from './assignGingerly.js';
 export { waitForEvent } from './waitForEvent.js';
+export { ParserRegistry, globalParserRegistry } from './parserRegistry.js';
+export { parseWithAttrs } from './parseWithAttrs.js';
 import './object-extension.js';

package/index.ts

@@ -2,4 +2,6 @@ export {assignGingerly} from './assignGingerly.js';
 export {assignTentatively} from './assignTentatively.js';
 export {BaseRegistry} from './assignGingerly.js';
 export {waitForEvent} from './waitForEvent.js';
+export {ParserRegistry, globalParserRegistry} from './parserRegistry.js';
+export {parseWithAttrs} from './parseWithAttrs.js';
 import './object-extension.js';

package/object-extension.js

@@ -48,9 +48,10 @@ class ElementEnhancementContainer {
     /**
      * Get or spawn an instance for a registry item
      * @param registryItem - The registry item to get/spawn instance for
+     * @param mountCtx - Optional context to pass to the spawned instance
      * @returns The spawned instance
      */
-    get(registryItem) {
+    get(registryItem, mountCtx) {
         const element = this.element;
         // Get the registry from customElementRegistry
         const registry = element.customElementRegistry?.enhancementRegistry;
@@ -75,7 +76,7 @@ class ElementEnhancementContainer {
             const SpawnClass = registryItem.spawn;
             // Check canSpawn if it exists
             if (typeof SpawnClass.canSpawn === 'function') {
-                const ctx = { config: registryItem };
+                const ctx = { config: registryItem, mountCtx };
                 if (!SpawnClass.canSpawn(element, ctx)) {
                     // canSpawn returned false, return undefined
                     return undefined;
@@ -83,7 +84,7 @@ class ElementEnhancementContainer {
             }
             // Check if there's an enhKey
             if (registryItem.enhKey) {
-                const ctx = { config: registryItem };
+                const ctx = { config: registryItem, mountCtx };
                 const self = this;
                 // Parse attributes if withAttrs is defined
                 let attrInitVals = undefined;
@@ -111,7 +112,7 @@ class ElementEnhancementContainer {
             }
             else {
                 // No enhKey, just spawn with element
-                const ctx = { config: registryItem };
+                const ctx = { config: registryItem, mountCtx };
                 instance = new SpawnClass(element, ctx);
             }
             // Store in global instance map
@@ -152,16 +153,17 @@ class ElementEnhancementContainer {
     /**
      * Wait for an enhancement instance to be resolved
      * @param registryItem - The registry item to wait for
+     * @param mountCtx - Optional context to pass to the spawned instance
      * @returns Promise that resolves with the spawned instance
      */
-    async whenResolved(registryItem) {
+    async whenResolved(registryItem, mountCtx) {
         const lifecycleKeys = normalizeLifecycleKeys(registryItem?.lifecycleKeys);
         const resolvedKey = lifecycleKeys?.resolved;
         if (resolvedKey === undefined) {
             throw new Error('Must specify resolved key in lifecycleKeys');
         }
-        // Get or spawn the instance
-        const spawnedInstance = this.get(registryItem);
+        // Get or spawn the instance (pass mountCtx through)
+        const spawnedInstance = this.get(registryItem, mountCtx);
         // Check if already resolved
         if (spawnedInstance[resolvedKey]) {
             return spawnedInstance;

package/object-extension.ts

@@ -114,9 +114,10 @@ class ElementEnhancementContainer {
   /**
    * Get or spawn an instance for a registry item
    * @param registryItem - The registry item to get/spawn instance for
+   * @param mountCtx - Optional context to pass to the spawned instance
    * @returns The spawned instance
    */
-  get(registryItem: any): any {
+  get(registryItem: any, mountCtx?: any): any {
     const element = this.element;
     
     // Get the registry from customElementRegistry
@@ -148,7 +149,7 @@ class ElementEnhancementContainer {
       
       // Check canSpawn if it exists
       if (typeof SpawnClass.canSpawn === 'function') {
-        const ctx = { config: registryItem };
+        const ctx = { config: registryItem, mountCtx };
         if (!SpawnClass.canSpawn(element, ctx)) {
           // canSpawn returned false, return undefined
           return undefined;
@@ -157,7 +158,7 @@ class ElementEnhancementContainer {
       
       // Check if there's an enhKey
       if (registryItem.enhKey) {
-        const ctx = { config: registryItem };
+        const ctx = { config: registryItem, mountCtx };
         const self = this as any;
         
         // Parse attributes if withAttrs is defined
@@ -192,7 +193,7 @@ class ElementEnhancementContainer {
         self[registryItem.enhKey] = instance;
       } else {
         // No enhKey, just spawn with element
-        const ctx = { config: registryItem };
+        const ctx = { config: registryItem, mountCtx };
         instance = new SpawnClass(element, ctx);
       }
       
@@ -243,9 +244,10 @@ class ElementEnhancementContainer {
   /**
    * Wait for an enhancement instance to be resolved
    * @param registryItem - The registry item to wait for
+   * @param mountCtx - Optional context to pass to the spawned instance
    * @returns Promise that resolves with the spawned instance
    */
-  async whenResolved(registryItem: any): Promise<any> {
+  async whenResolved(registryItem: any, mountCtx?: any): Promise<any> {
     const lifecycleKeys = normalizeLifecycleKeys(registryItem?.lifecycleKeys);
     const resolvedKey = lifecycleKeys?.resolved;
     
@@ -253,8 +255,8 @@ class ElementEnhancementContainer {
       throw new Error('Must specify resolved key in lifecycleKeys');
     }
     
-    // Get or spawn the instance
-    const spawnedInstance = this.get(registryItem);
+    // Get or spawn the instance (pass mountCtx through)
+    const spawnedInstance = this.get(registryItem, mountCtx);
     
     // Check if already resolved
     if ((spawnedInstance as any)[resolvedKey]) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "assign-gingerly",
-  "version": "0.0.11",
+  "version": "0.0.13",
   "description": "This package provides a utility function for carefully merging one object into another.",
   "homepage": "https://github.com/bahrus/assign-gingerly#readme",
   "bugs": {
@@ -35,6 +35,13 @@
     },
     "./waitForEvent.js": {
       "default": "./waitForEvent.js"
+    },
+    "./parserRegistry.js": {
+      "default": "./parserRegistry.js"
+    },
+    "./parseWithAttrs.js": {
+      "default": "./parseWithAttrs.js",
+      "types": "./types.d.ts"
     }
   },
   "main": "index.js",

package/parseWithAttrs.js

@@ -1,3 +1,121 @@
+import { globalParserRegistry } from './parserRegistry.js';
+// Module-level cache for parsed attribute values
+// Structure: Map<configKey, Map<attrValue, parsedValue>>
+const parseCache = new Map();
+/**
+ * Resolves a parser specification to an actual parser function
+ * Supports:
+ * - Inline functions (direct use)
+ * - Named parsers from global registry
+ * - Custom element static methods (element-name.methodName)
+ *
+ * @param parserSpec - Parser function or string reference
+ * @returns The resolved parser function
+ * @throws Error if parser cannot be resolved
+ */
+function resolveParser(parserSpec) {
+    // Undefined - no parser specified
+    if (parserSpec === undefined) {
+        return undefined;
+    }
+    // Inline function - use directly
+    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
+                }
+            }
+            // Fall through to global registry (allows dot notation in registry too)
+        }
+        // Try global registry
+        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.`);
+    }
+    return undefined;
+}
+/**
+ * Creates a cache key from an AttrConfig
+ * Includes instanceOf and parser identifier to ensure correct cache hits
+ */
+function getCacheKey(config) {
+    const instanceOfStr = typeof config.instanceOf === 'function'
+        ? config.instanceOf.name
+        : (config.instanceOf || 'default');
+    // Include parser in cache key
+    let parserStr;
+    if (config.parser === undefined) {
+        parserStr = 'builtin';
+    }
+    else if (typeof config.parser === 'string') {
+        parserStr = `named:${config.parser}`;
+    }
+    else {
+        parserStr = 'custom';
+    }
+    return `${instanceOfStr}|${parserStr}`;
+}
+/**
+ * Gets a cached parsed value or parses and caches it
+ * @param attrValue - The attribute value to parse (or null)
+ * @param config - The attribute configuration
+ * @param parser - The parser function to use
+ * @returns The parsed value
+ */
+function parseWithCache(attrValue, config, parser) {
+    // Skip caching for Boolean (presence check doesn't benefit from caching)
+    if (config.instanceOf === 'Boolean') {
+        return parser(attrValue);
+    }
+    // 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);
+    // Use special key for null values
+    const valueCacheKey = attrValue === null ? '__NULL__' : attrValue;
+    // Check if we have a cached value
+    if (valueCache.has(valueCacheKey)) {
+        const cachedValue = valueCache.get(valueCacheKey);
+        // Return clone if requested
+        if (config.parseCache === 'cloned') {
+            // Use structuredClone for deep cloning
+            return structuredClone(cachedValue);
+        }
+        // Return shared reference
+        return cachedValue;
+    }
+    // Parse the value
+    const parsedValue = parser(attrValue);
+    // Store in cache
+    valueCache.set(valueCacheKey, parsedValue);
+    // Return clone if requested (even on first parse)
+    if (config.parseCache === 'cloned') {
+        return structuredClone(parsedValue);
+    }
+    return parsedValue;
+}
 /**
  * Checks if a string contains a dash or non-ASCII character
  */
@@ -188,14 +306,40 @@ export function parseWithAttrs(element, attrPatterns, allowUnprefixed) {
     // Second pass: read attributes and parse values
     for (const [key, { attrName, config }] of resolvedAttrs) {
         const attrValue = getAttributeValue(element, attrName, allowUnprefixed);
-        // Skip if attribute doesn't exist
-        if (attrValue === null && config.instanceOf !== 'Boolean') {
+        // Handle missing attribute
+        if (attrValue === null) {
+            // Use valIfNull if defined
+            if (config.valIfNull !== undefined) {
+                const mapsTo = config.mapsTo ?? (key === 'base' ? '.' : key);
+                if (mapsTo === '.') {
+                    // Spread into root
+                    if (typeof config.valIfNull === 'object' && config.valIfNull !== null) {
+                        Object.assign(result, config.valIfNull);
+                    }
+                }
+                else {
+                    result[mapsTo] = config.valIfNull;
+                }
+            }
+            // Skip if no valIfNull and not Boolean (Boolean uses presence check)
+            else if (config.instanceOf !== 'Boolean') {
+                continue;
+            }
+            // For Boolean without valIfNull, fall through to parser
+            else {
+                const parser = resolveParser(config.parser) || getDefaultParser(config.instanceOf);
+                const parsedValue = parser(attrValue);
+                const mapsTo = config.mapsTo ?? (key === 'base' ? '.' : key);
+                result[mapsTo] = parsedValue;
+            }
             continue;
         }
-        // Get parser
-        const parser = config.parser || getDefaultParser(config.instanceOf);
-        // Parse value
-        const parsedValue = parser(attrValue);
+        // Attribute exists - parse normally
+        const parser = resolveParser(config.parser) || getDefaultParser(config.instanceOf);
+        // Use cache if parseCache is specified
+        const parsedValue = config.parseCache
+            ? parseWithCache(attrValue, config, parser)
+            : parser(attrValue);
         // Determine target property
         const mapsTo = config.mapsTo ?? (key === 'base' ? '.' : key);
         // Add to result

package/parseWithAttrs.ts

@@ -1,4 +1,148 @@
 import { AttrPatterns, AttrConfig } from './types';
+import { globalParserRegistry } from './parserRegistry.js';
+
+// Module-level cache for parsed attribute values
+// Structure: Map<configKey, Map<attrValue, parsedValue>>
+const parseCache = new Map<string, Map<string, any>>();
+
+/**
+ * Resolves a parser specification to an actual parser function
+ * Supports:
+ * - Inline functions (direct use)
+ * - Named parsers from global registry
+ * - Custom element static methods (element-name.methodName)
+ * 
+ * @param parserSpec - Parser function or string reference
+ * @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 {
+  // Undefined - no parser specified
+  if (parserSpec === undefined) {
+    return undefined;
+  }
+  
+  // Inline function - use directly
+  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 as any)[methodName] === 'function') {
+            return (ctr as any)[methodName];
+          }
+        } catch (e) {
+          // customElements.get might throw, fall through to registry
+        }
+      }
+      
+      // Fall through to global registry (allows dot notation in registry too)
+    }
+    
+    // Try global registry
+    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.`
+    );
+  }
+  
+  return undefined;
+}
+
+/**
+ * Creates a cache key from an AttrConfig
+ * Includes instanceOf and parser identifier to ensure correct cache hits
+ */
+function getCacheKey(config: AttrConfig<any>): string {
+  const instanceOfStr = typeof config.instanceOf === 'function' 
+    ? config.instanceOf.name 
+    : (config.instanceOf || 'default');
+  
+  // Include parser in cache key
+  let parserStr: string;
+  if (config.parser === undefined) {
+    parserStr = 'builtin';
+  } else if (typeof config.parser === 'string') {
+    parserStr = `named:${config.parser}`;
+  } else {
+    parserStr = 'custom';
+  }
+  
+  return `${instanceOfStr}|${parserStr}`;
+}
+
+/**
+ * Gets a cached parsed value or parses and caches it
+ * @param attrValue - The attribute value to parse (or null)
+ * @param config - The attribute configuration
+ * @param parser - The parser function to use
+ * @returns The parsed value
+ */
+function parseWithCache(
+  attrValue: string | null,
+  config: AttrConfig<any>,
+  parser: (v: string | null) => any
+): any {
+  // Skip caching for Boolean (presence check doesn't benefit from caching)
+  if (config.instanceOf === 'Boolean') {
+    return parser(attrValue);
+  }
+  
+  // 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)!;
+  
+  // Use special key for null values
+  const valueCacheKey = attrValue === null ? '__NULL__' : attrValue;
+  
+  // Check if we have a cached value
+  if (valueCache.has(valueCacheKey)) {
+    const cachedValue = valueCache.get(valueCacheKey);
+    
+    // Return clone if requested
+    if (config.parseCache === 'cloned') {
+      // Use structuredClone for deep cloning
+      return structuredClone(cachedValue);
+    }
+    
+    // Return shared reference
+    return cachedValue;
+  }
+  
+  // Parse the value
+  const parsedValue = parser(attrValue);
+  
+  // Store in cache
+  valueCache.set(valueCacheKey, parsedValue);
+  
+  // Return clone if requested (even on first parse)
+  if (config.parseCache === 'cloned') {
+    return structuredClone(parsedValue);
+  }
+  
+  return parsedValue;
+}
 
 /**
  * Checks if a string contains a dash or non-ASCII character
@@ -221,16 +365,42 @@ export function parseWithAttrs<T = any>(
     for (const [key, { attrName, config }] of resolvedAttrs) {
         const attrValue = getAttributeValue(element, attrName, allowUnprefixed);
         
-        // Skip if attribute doesn't exist
-        if (attrValue === null && config.instanceOf !== 'Boolean') {
+        // Handle missing attribute
+        if (attrValue === null) {
+            // Use valIfNull if defined
+            if (config.valIfNull !== undefined) {
+                const mapsTo = config.mapsTo ?? (key === 'base' ? '.' : key);
+                
+                if (mapsTo === '.') {
+                    // Spread into root
+                    if (typeof config.valIfNull === 'object' && config.valIfNull !== null) {
+                        Object.assign(result, config.valIfNull);
+                    }
+                } else {
+                    result[mapsTo as string] = config.valIfNull;
+                }
+            }
+            // Skip if no valIfNull and not Boolean (Boolean uses presence check)
+            else if (config.instanceOf !== 'Boolean') {
+                continue;
+            }
+            // For Boolean without valIfNull, fall through to parser
+            else {
+                const parser = resolveParser(config.parser) || getDefaultParser(config.instanceOf);
+                const parsedValue = parser(attrValue);
+                const mapsTo = config.mapsTo ?? (key === 'base' ? '.' : key);
+                result[mapsTo as string] = parsedValue;
+            }
             continue;
         }
         
-        // Get parser
-        const parser = config.parser || getDefaultParser(config.instanceOf);
+        // Attribute exists - parse normally
+        const parser = resolveParser(config.parser) || getDefaultParser(config.instanceOf);
         
-        // Parse value
-        const parsedValue = parser(attrValue);
+        // Use cache if parseCache is specified
+        const parsedValue = config.parseCache 
+          ? parseWithCache(attrValue, config, parser)
+          : parser(attrValue);
         
         // Determine target property
         const mapsTo = config.mapsTo ?? (key === 'base' ? '.' : key);