assign-gingerly 0.0.12 → 0.0.14

package/assignGingerly.ts

@@ -1,6 +1,6 @@
 
 
-import { EnhancementConfig } from "./types";
+import { EnhancementConfig } from "./types/assign-gingerly/types";
 
 /**
  * @deprecated Use EnhancementConfig instead

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "assign-gingerly",
-  "version": "0.0.12",
+  "version": "0.0.14",
   "description": "This package provides a utility function for carefully merging one object into another.",
   "homepage": "https://github.com/bahrus/assign-gingerly#readme",
   "bugs": {
@@ -13,28 +13,36 @@
   "license": "MIT",
   "author": "Bruce B. Anderson <andeson.bruce.b@gmail.com>",
   "type": "module",
-  "types": "types.d.ts",
+  "types": "types/assign-gingerly/types.d.ts",
   "files": [
     "*.js",
     "*.ts",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "types/assign-gingerly/types.d.ts"
   ],
   "exports": {
     ".": {
       "default": "./index.js",
-      "types": "./types.d.ts"
+      "types": "./index.ts"
     },
     "./assignGingerly.js": {
       "default": "./assignGingerly.js",
-      "types": "./types.d.ts"
+      "types": "./assignGingerly.ts"
     },
     "./assignTentatively.js": {
       "default": "./assignTentatively.js",
-      "types": "./types.d.ts"
+      "types": "./assignTentatively.ts"
     },
     "./waitForEvent.js": {
       "default": "./waitForEvent.js"
+    },
+    "./parserRegistry.js": {
+      "default": "./parserRegistry.js"
+    },
+    "./parseWithAttrs.js": {
+      "default": "./parseWithAttrs.js",
+      "types": "./parseWithAttrs.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 { AttrPatterns, AttrConfig } from './types/assign-gingerly/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);

package/parserRegistry.js

@@ -0,0 +1,71 @@
+/**
+ * Registry for named parsers that can be referenced by string name
+ * Enables JSON serialization of configs with custom parsers
+ */
+export class ParserRegistry {
+    parsers = new Map();
+    /**
+     * Register a parser with a given name
+     * @param name - The name to register the parser under
+     * @param parser - The parser function
+     */
+    register(name, parser) {
+        if (this.parsers.has(name)) {
+            console.warn(`Parser "${name}" already registered, overwriting`);
+        }
+        this.parsers.set(name, parser);
+    }
+    /**
+     * Get a parser by name
+     * @param name - The name of the parser
+     * @returns The parser function or undefined if not found
+     */
+    get(name) {
+        return this.parsers.get(name);
+    }
+    /**
+     * Check if a parser is registered
+     * @param name - The name to check
+     * @returns True if the parser exists
+     */
+    has(name) {
+        return this.parsers.has(name);
+    }
+    /**
+     * Unregister a parser
+     * @param name - The name of the parser to remove
+     * @returns True if the parser was removed, false if it didn't exist
+     */
+    unregister(name) {
+        return this.parsers.delete(name);
+    }
+    /**
+     * Get all registered parser names
+     * @returns Array of parser names
+     */
+    getNames() {
+        return Array.from(this.parsers.keys());
+    }
+}
+/**
+ * Global parser registry instance
+ * Use this to register parsers that can be referenced by name in configs
+ */
+export const globalParserRegistry = new ParserRegistry();
+// Register common built-in parsers
+globalParserRegistry.register('timestamp', (v) => v ? new Date(v).getTime() : null);
+globalParserRegistry.register('date', (v) => v ? new Date(v) : null);
+globalParserRegistry.register('csv', (v) => v ? v.split(',').map(s => s.trim()) : []);
+globalParserRegistry.register('int', (v) => v ? parseInt(v, 10) : null);
+globalParserRegistry.register('float', (v) => v ? parseFloat(v) : null);
+globalParserRegistry.register('boolean', (v) => v !== null);
+globalParserRegistry.register('json', (v) => {
+    if (v === null || v === '')
+        return null;
+    try {
+        return JSON.parse(v);
+    }
+    catch (e) {
+        throw new Error(`Failed to parse JSON: "${v}". Error: ${e}`);
+    }
+});

package/parserRegistry.ts

@@ -0,0 +1,94 @@
+/**
+ * Registry for named parsers that can be referenced by string name
+ * Enables JSON serialization of configs with custom parsers
+ */
+export class ParserRegistry {
+  private parsers = new Map<string, (v: string | null) => any>();
+  
+  /**
+   * Register a parser with a given name
+   * @param name - The name to register the parser under
+   * @param parser - The parser function
+   */
+  register(name: string, parser: (v: string | null) => any): void {
+    if (this.parsers.has(name)) {
+      console.warn(`Parser "${name}" already registered, overwriting`);
+    }
+    this.parsers.set(name, parser);
+  }
+  
+  /**
+   * Get a parser by name
+   * @param name - The name of the parser
+   * @returns The parser function or undefined if not found
+   */
+  get(name: string): ((v: string | null) => any) | undefined {
+    return this.parsers.get(name);
+  }
+  
+  /**
+   * Check if a parser is registered
+   * @param name - The name to check
+   * @returns True if the parser exists
+   */
+  has(name: string): boolean {
+    return this.parsers.has(name);
+  }
+  
+  /**
+   * Unregister a parser
+   * @param name - The name of the parser to remove
+   * @returns True if the parser was removed, false if it didn't exist
+   */
+  unregister(name: string): boolean {
+    return this.parsers.delete(name);
+  }
+  
+  /**
+   * Get all registered parser names
+   * @returns Array of parser names
+   */
+  getNames(): string[] {
+    return Array.from(this.parsers.keys());
+  }
+}
+
+/**
+ * Global parser registry instance
+ * Use this to register parsers that can be referenced by name in configs
+ */
+export const globalParserRegistry = new ParserRegistry();
+
+// Register common built-in parsers
+globalParserRegistry.register('timestamp', (v) => 
+  v ? new Date(v).getTime() : null
+);
+
+globalParserRegistry.register('date', (v) => 
+  v ? new Date(v) : null
+);
+
+globalParserRegistry.register('csv', (v) => 
+  v ? v.split(',').map(s => s.trim()) : []
+);
+
+globalParserRegistry.register('int', (v) => 
+  v ? parseInt(v, 10) : null
+);
+
+globalParserRegistry.register('float', (v) => 
+  v ? parseFloat(v) : null
+);
+
+globalParserRegistry.register('boolean', (v) => 
+  v !== null
+);
+
+globalParserRegistry.register('json', (v) => {
+  if (v === null || v === '') return null;
+  try {
+    return JSON.parse(v);
+  } catch (e) {
+    throw new Error(`Failed to parse JSON: "${v}". Error: ${e}`);
+  }
+});

package/types/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bruce B. Anderson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/types/README.md

@@ -0,0 +1,2 @@
+# types
+Common Shared Type Definitions

package/{types.d.ts → types/assign-gingerly/types.d.ts}

@@ -88,9 +88,29 @@ export interface AttrConfig<T = any> {
     | `${pathString} -=`
   
   /**
-   * Optional parser function to transform attribute string value
+   * Parser to transform attribute string value
+   * - Function: Inline parser function (not JSON serializable)
+   * - String: Named parser reference (JSON serializable)
+   *   - Simple name: Looks up in global parser registry (e.g., 'timestamp', 'csv')
+   *   - Dot notation: Looks up static method on custom element (e.g., 'my-widget.parseSpecial')
+   *     Falls back to global registry if custom element not found
    */
-  parser?: (attrValue: string | null) => any;
+  parser?: ((attrValue: string | null) => any) | string;
+  
+  /**
+   * Default value to use when attribute is missing
+   * If defined, bypasses parser when attribute is not present
+   * If undefined, property is not added to initVals when attribute is missing
+   */
+  valIfNull?: any;
+  
+  /**
+   * Enable caching of parsed attribute values
+   * - 'shared': Cache and reuse the same parsed object (fast, but enhancements must not mutate)
+   * - 'cloned': Cache and return a structural clone (safer, but slower)
+   * Note: Parsers should be pure functions when using caching
+   */
+  parseCache?: 'shared' | 'cloned';
   
   // /**
   //  * Whether to only read the initial value (true) or continue observing changes (false)