assign-gingerly 0.0.12 → 0.0.13

package/README.md

@@ -288,8 +288,10 @@ This guarantees that applying the reversal object restores the object to its exa
 interface IBaseRegistryItem<T = any> {
     spawn: {new(): T} | Promise<{new(): T}>
     symlinks: {[key: symbol]: keyof T}
-    enhKey?: string  // Optional: for element enhancement access
-    withAttrs?: AttrPatterns<T>  // Optional: automatic attribute parsing
+    // Optional: for element enhancement access
+    enhKey?: string
+    // Optional: automatic attribute parsing 
+    withAttrs?: AttrPatterns<T>  
 }
 
 export const isHappy = Symbol.for('TFWsx0YH5E6eSfhE7zfLxA');
@@ -349,7 +351,8 @@ It also adds a lazy property to the first passed in parameter, "set", which retu
 
 The suggestion to use Symbol.for with a guid, as opposed to just Symbol(), is based on some negative experiences I've had with multiple versions of the same library being referenced, but is not required. Regular symbols could also be used when that risk can be avoided.
 
-### Global Instance Map for Cross-Version Compatibility
+<details>
+<summary>Global Instance Map for Cross-Version Compatibility</summary>
 
 To ensure instance uniqueness even when multiple versions of this package are loaded, spawned instances are stored in a global WeakMap at `globalThis['HDBhTPLuIUyooMxK88m68Q']`. This guarantees that:
 
@@ -443,7 +446,10 @@ console.log(target.set[symbol1].prop1); // 'value1'
 console.log(target.set[symbol1].prop2); // 'value2'
 ```
 
-## Support for JSON assignment with Symbol.for symbols
+</details>
+
+<details>
+  <summary>Support for JSON assignment with Symbol.for symbols</summary>
 
 ```JavaScript
 const result = assignGingerly({}, {
@@ -455,8 +461,13 @@ const result = assignGingerly({}, {
     registry: BaseRegistry
 });
 ```
+</details>
+
+
+<!--
 
 
+Already covered, I think 
 
 ## Object.prototype Extensions
 
@@ -491,11 +502,14 @@ console.log(obj); // { a: 1, b: { c: 2 }, d: 3 }
 
 The prototype extensions are non-enumerable and won't appear in `Object.keys()` or `for...in` loops.
 
+-->
+
 ## Custom Element Registry Integration (Chrome 146+)
 
-This package includes support for Chrome's scoped custom element registries, which automatically integrates dependency injection with custom elements.
+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.
 
-### Automatic Registry Population
+<details>
+  <summary>Automatic Registry Population</summary>
 
 When `assignGingerly` or `assignTentatively` is called on an Element instance without providing an explicit `registry` option, it automatically uses the registry from `element.customElementRegistry.enhancementRegistry`:
 
@@ -523,7 +537,10 @@ myElement.assignGingerly({
 });
 ```
 
-### Lazy Registry Creation
+</details>
+
+<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:
 
@@ -538,8 +555,10 @@ const registry2 = element2.customElementRegistry.enhancementRegistry;
 // Multiple accesses return the same instance
 console.log(registry1 === element1.customElementRegistry.enhancementRegistry); // true
 ```
+</details>
 
-### Explicit Registry Override
+<details>
+  <summary>Explicit Registry Override</summary>
 
 You can still provide an explicit `registry` option to override the automatic behavior:
 
@@ -549,10 +568,11 @@ const customRegistry = new BaseRegistry();
 
 myElement.assignGingerly({
   [mySymbol]: 'value'
-}, { registry: customRegistry }); // Uses customRegistry instead of customElementRegistry
+}, { registry: customRegistry }); // Uses customRegistry instead of customElementRegistry.enhancementRegistry
 ```
 
 **Browser Support**: This feature requires Chrome 146+ with scoped custom element registry support. The implementation is designed as a polyfill for the web standards proposal and does not include fallback behavior for older browsers.
+</details>
 
 ## Enhanced Element Property Assignment with `enh.set` Proxy (Chrome 146+)
 
@@ -564,7 +584,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 { BaseRegistry } from 'assign-gingerly';
 
 // Define an enhancement class
 class MyEnhancement {
@@ -588,7 +608,6 @@ const registry = myElement.customElementRegistry.enhancementRegistry;
 
 registry.push({
   spawn: MyEnhancement,
-  symlinks: {},
   enhKey: 'myEnh'  // Key identifier for this enhancement
 });
 
@@ -601,7 +620,10 @@ console.log(myElement.enh.myEnh.myProp); // 'hello'
 console.log(myElement.enh.myEnh.element === myElement); // true
 ```
 
-### How It Works
+<details>
+<summary>
+How It Works
+</summary>
 
 When you access `element.enh.set.enhKey.property`, the proxy:
 
@@ -614,12 +636,14 @@ When you access `element.enh.set.enhKey.property`, the proxy:
 3. **Reuses existing instances**: If the enhancement already exists and is the correct type, it reuses it
 4. **Falls back to plain objects**: If no registry item is found, creates a plain object at `element.enh[enhKey]`
 
+</details>
+
 ### Why the `enh` Namespace?
 
 The `enh` property provides a dedicated namespace for enhancements, similar to how `dataset` provides a namespace for data attributes. This prevents conflicts with:
 - Future platform properties that might be added to Element
 - Existing element properties and methods
-- Other libraries that might extend Element
+- Other libraries that might extend HTMLElement
 
 This approach is part of a proposal to WHATWG for standardizing element enhancements.
 
@@ -647,7 +671,8 @@ class Enhancement {
 
 All parameters are optional for backward compatibility with existing code.
 
-**Passing Custom Context:**
+<details>
+<summary>Passing Custom Context</summary>
 
 You can pass custom context when calling `enh.get()` or `enh.whenResolved()`:
 
@@ -673,9 +698,11 @@ This is useful for:
 
 **Note**: The `mountCtx` is only available when explicitly calling `enh.get()` or `enh.whenResolved()`. It's not available when accessing via the `enh.set` proxy (since that's a property getter with no way to pass parameters).
 
+</details>
+
 ### Registry Item with enhKey
 
-Registry items now support optional `enhKey`, `withAttrs`, `canSpawn`, and `lifecycleKeys` properties:
+In addition to spawn and symlinks, registry items support optional properties `enhKey`, `withAttrs`, `canSpawn`, and `lifecycleKeys`:
 
 ```TypeScript
 interface IBaseRegistryItem<T> {
@@ -683,7 +710,7 @@ interface IBaseRegistryItem<T> {
     new (oElement?: Element, ctx?: SpawnContext<T>, initVals?: Partial<T>): T;
     canSpawn?: (obj: any, ctx?: SpawnContext<T>) => boolean;  // Optional spawn guard
   };
-  symlinks: { [key: string | symbol]: keyof T };
+  symlinks?: { [key: string | symbol]: keyof T };
   enhKey?: string;  // String identifier for set proxy access
   withAttrs?: AttrPatterns<T>;  // Automatic attribute parsing during spawn
   lifecycleKeys?: 
@@ -697,11 +724,14 @@ interface IBaseRegistryItem<T> {
 
 The `withAttrs` property enables automatic attribute parsing when the enhancement is spawned. See the [Parsing Attributes with parseWithAttrs](#parsing-attributes-with-parsewithattrs) section for details.
 
+It also tips off extending polyfills / libraries, in particular mount-observer, to be on te lookout for the attributes specified by withAttrs.  But *assign-gingerly, by itself, performs **no** DOM observing to automatically spawn the class instance*.  It expects consumers of the polyfill to programmatically attach such behavior/enhancements, and/or rely on alternative, higher level packages to be vigilant for enhancement opportunities. 
+
 The `canSpawn` static method allows enhancement classes to conditionally block spawning based on the target object. See the [Conditional Spawning with canSpawn](#conditional-spawning-with-canspawn) section for details.
 
 The `lifecycleKeys` property configures lifecycle integration without requiring base classes. See the [Lifecycle Keys: Configuration vs Convention](#lifecycle-keys-configuration-vs-convention) section for details.
 
-### Advanced Examples
+<details>
+   <summary>Advanced Examples</summary>
 
 **Multiple Enhancements:**
 ```TypeScript
@@ -724,8 +754,8 @@ const element = document.createElement('div');
 const registry = element.customElementRegistry.enhancementRegistry;
 
 registry.push([
-  { spawn: StyleEnhancement, symlinks: {}, enhKey: 'styles' },
-  { spawn: DataEnhancement, symlinks: {}, enhKey: 'data' }
+  { spawn: StyleEnhancement, enhKey: 'styles' },
+  { spawn: DataEnhancement, enhKey: 'data' }
 ]);
 
 element.enh.set.styles.height = '100px';
@@ -742,7 +772,6 @@ const registry = element.customElementRegistry.enhancementRegistry;
 
 registry.push({
   spawn: MyEnhancement,
-  symlinks: {},
   enhKey: 'config'
 });
 
@@ -768,7 +797,10 @@ element.enh.set.plainData.prop2 = 'value2';
 console.log(element.enh.plainData); // { prop1: 'value1', prop2: 'value2' }
 ```
 
-### Finding Registry Items by enhKey
+</details>
+
+<details>
+<summary>Finding Registry Items by enhKey</summary>
 
 The `BaseRegistry` class includes a `findByEnhKey` method:
 
@@ -776,22 +808,21 @@ The `BaseRegistry` class includes a `findByEnhKey` method:
 const registry = new BaseRegistry();
 registry.push({
   spawn: MyEnhancement,
-  symlinks: {},
   enhKey: 'myEnh'
 });
 
 const item = registry.findByEnhKey('myEnh');
 console.log(item.enhKey); // 'myEnh'
 ```
+</details>
 
 ### Programmatic Instance Spawning with `enh.get()`
 
-The `enh.get()` method provides a programmatic way to spawn or retrieve enhancement instances:
+The `enh.get(registryItem)` method provides a programmatic way to spawn or retrieve enhancement instances:
 
 ```TypeScript
 const registryItem = {
   spawn: MyEnhancement,
-  symlinks: {},
   enhKey: 'myEnh'
 };
 
@@ -814,7 +845,9 @@ console.log(element.enh.myEnh === instance); // true
 - **Shared instances**: Uses the same global instance map as `assignGingerly` and `enh.set`, ensuring only one instance per registry item
 - **Auto-registration**: Automatically adds registry items to the element's registry if not present
 
-**Example with shared instances:**
+<details>
+<summary>Example with shared instances</summary>
+
 ```TypeScript
 const registryItem = {
   spawn: MyEnhancement,
@@ -837,7 +870,10 @@ console.log(element.enh.myEnh.prop2); // 'from set'
 console.log(element.enh.myEnh.value); // 'from assign'
 ```
 
-### Lifecycle Keys: Configuration vs Convention
+</details>
+
+<details>
+  <summary>Lifecycle Keys: Configuration vs Convention</summary>
 
 Enhancement classes can integrate with the lifecycle system through configurable method/property names, avoiding the need for base classes or mixins.
 
@@ -857,7 +893,6 @@ For convenience, you can use `lifecycleKeys: true` to adopt standard naming conv
 ```TypeScript
 const registryItem = {
   spawn: MyEnhancement,
-  symlinks: {},
   enhKey: 'myEnh',
   lifecycleKeys: true  // Uses standard names: "dispose" and "resolved"
 };
@@ -901,7 +936,6 @@ class MyEnhancement {
 
 const registryItem = {
   spawn: MyEnhancement,
-  symlinks: {},
   enhKey: 'myEnh',
   lifecycleKeys: {
     dispose: DISPOSE,
@@ -912,6 +946,8 @@ const registryItem = {
 
 Note: Symbol event names are not yet supported by the platform but have been requested. When supported, the `resolved` key will work as both property name and event name.
 
+</details>
+
 ### Disposing Enhancement Instances with `enh.dispose()`
 
 The `enh.dispose()` method provides a way to clean up and remove enhancement instances:
@@ -935,7 +971,6 @@ class MyEnhancement {
 
 const registryItem = {
   spawn: MyEnhancement,
-  symlinks: {},
   enhKey: 'myEnh',
   lifecycleKeys: true  // Standard: calls dispose() method
 };
@@ -943,7 +978,6 @@ const registryItem = {
 // Or with custom name:
 const customRegistryItem = {
   spawn: MyEnhancement,
-  symlinks: {},
   enhKey: 'myEnh',
   lifecycleKeys: {
     dispose: 'cleanup'  // Custom: calls cleanup() method
@@ -994,7 +1028,6 @@ class TimerEnhancement {
 
 const registryItem = {
   spawn: TimerEnhancement,
-  symlinks: {},
   enhKey: 'timer',
   lifecycleKeys: true  // Standard: calls dispose() method
 };
@@ -1041,7 +1074,6 @@ class AsyncEnhancement extends EventTarget {
 
 const registryItem = {
   spawn: AsyncEnhancement,
-  symlinks: {},
   enhKey: 'asyncEnh',
   lifecycleKeys: true  // Standard: watches "resolved" property and event
 };
@@ -1049,7 +1081,6 @@ const registryItem = {
 // Or with custom name:
 const customRegistryItem = {
   spawn: AsyncEnhancement,
-  symlinks: {},
   enhKey: 'asyncEnh',
   lifecycleKeys: {
     resolved: 'isReady'  // Custom: watches "isReady" property and event
@@ -1066,7 +1097,8 @@ const instanceWithContext = await element.enh.whenResolved(registryItem, authCon
 // The constructor receives authContext via ctx.mountCtx
 ```
 
-**How `enh.whenResolved()` works:**
+<details>
+<summary>How `enh.whenResolved()` works:</summary>
 
 1. **Validates configuration**: Throws error if `lifecycleKeys.resolved` is not specified
 2. **Gets instance**: Calls `enh.get()` to get or spawn the instance
@@ -1127,7 +1159,6 @@ class DataEnhancement extends EventTarget {
 
 const registryItem = {
   spawn: DataEnhancement,
-  symlinks: {},
   enhKey: 'data',
   lifecycleKeys: true  // Standard: watches "resolved" property and event
 };
@@ -1154,6 +1185,8 @@ console.log(instance1 === instance2); // true - same instance
 
 **Browser Support**: This feature requires Chrome 146+ with scoped custom element registry support.
 
+</details>
+
 ## Conditional Spawning with `canSpawn`
 
 Enhancement classes can implement a static `canSpawn` method to conditionally block spawning based on the target object. This is useful for:
@@ -1187,7 +1220,6 @@ class DivOnlyEnhancement {
 const registry = new BaseRegistry();
 registry.push({
   spawn: DivOnlyEnhancement,
-  symlinks: {},
   enhKey: 'divOnly'
 });
 
@@ -1203,7 +1235,8 @@ const spanInstance = span.enh.get(registry.getItems()[0]);
 console.log(spanInstance); // undefined
 ```
 
-### How It Works
+<details>
+  <summary>How It Works</summary>
 
 1. **Called before spawning**: When an enhancement is about to be spawned (via `assignGingerly`, `enh.get()`, or `enh.set`), the `canSpawn` method is called first
 2. **Receives context**: The method receives the target object and spawn context with registry item information
@@ -1314,6 +1347,8 @@ assignGingerly(element, { [enhSymbol]: 'test' }, { registry });
 // Enhancement created and value set
 ```
 
+</details>
+
 ## 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.
@@ -1322,19 +1357,21 @@ The `parseWithAttrs` function provides a declarative way to read and parse HTML
 
 **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.
 
+```html
+<my-element my-enhancement-count="42" my-enhancement-theme="dark"></my-element>
+```
+
 ```TypeScript
 import 'assign-gingerly/object-extension.js';
 
-// HTML: <my-element data-count="42" data-theme="dark"></my-element>
-
 class MyEnhancement {
-  element;
+  elementRef;
   ctx;
   count = 0;
   theme = 'light';
   
   constructor(oElement, ctx, initVals) {
-    this.element = oElement;
+    this.element = new WeakRef(oElement);
     this.ctx = ctx;
     // initVals automatically contains parsed attributes!
     if (initVals) {
@@ -1344,23 +1381,21 @@ class MyEnhancement {
 }
 
 const element = document.querySelector('my-element');
-const registry = element.customElementRegistry.enhancementRegistry;
-
-// Define withAttrs in the registry item
-registry.push({
+const enhancementConfig = {
   spawn: MyEnhancement,
-  symlinks: {},
   enhKey: 'myEnh',
   withAttrs: {
-    base: 'data-',
-    count: '${base}count',
+    base: 'my-enhancement',
+    count: '${base}-count',
     _count: { instanceOf: 'Number' },
-    theme: '${base}theme'
+    theme: '${base}-theme'
+
   }
-});
+};
+
 
 // Spawn the enhancement - attributes are automatically parsed!
-const instance = element.enh.get(registry.getItems()[0]);
+const instance = element.enh.get(enhancementConfig);
 console.log(instance.count);  // 42 (parsed from attribute)
 console.log(instance.theme);  // 'dark' (parsed from attribute)
 ```
@@ -1374,9 +1409,7 @@ console.log(instance.theme);  // 'dark' (parsed from attribute)
 
 **Precedence**: If both parsed attributes and existing `element.enh[enhKey]` values exist, the existing values take precedence over parsed attributes.
 
-### Manual Usage
 
-While automatic parsing is the recommended approach, you can also call `parseWithAttrs()` manually when needed:
 
 ### The `enh-` Prefix for Attribute Isolation
 
@@ -1412,7 +1445,6 @@ For custom elements and SVG, you can opt-in to reading unprefixed attributes by
 // Allow unprefixed for elements matching pattern
 registry.push({
   spawn: MyEnhancement,
-  symlinks: {},
   enhKey: 'myEnh',
   allowUnprefixed: '^my-',  // Only for elements starting with "my-"
   withAttrs: {
@@ -1425,7 +1457,6 @@ registry.push({
 // Or use RegExp for more complex patterns
 registry.push({
   spawn: MyEnhancement,
-  symlinks: {},
   enhKey: 'myEnh',
   allowUnprefixed: /^(my-|app-)/,  // For "my-*" or "app-*" elements
   withAttrs: {
@@ -1436,7 +1467,23 @@ registry.push({
 });
 ```
 
-When calling `parseWithAttrs()` manually, pass the pattern as the third parameter:
+<details>
+  <summary>Why use `enh-` prefix?</summary>
+
+1. **Avoid conflicts**: Custom elements may use unprefixed attributes for their own purposes
+2. **Clear intent**: Makes it obvious which attributes are for enhancements
+3. **Future-proof**: Protects against future attribute additions to custom elements
+4. **Consistency**: Provides a standard convention across all enhanced elements
+5. **Selective override**: Pattern-based `allowUnprefixed` lets you opt-in specific element families while maintaining strict isolation for others
+
+</details>
+
+<details>
+  <summary>Manual Usage</summary>
+
+While automatic parsing is the recommended approach, you can also call `parseWithAttrs()` manually when needed.
+
+When calling `parseWithAttrs()` manually, pass the pattern as the third (optional) parameter:
 
 ```TypeScript
 // Allow unprefixed only for elements matching pattern
@@ -1475,27 +1522,6 @@ const result2 = parseWithAttrs(
 // result2.count = undefined (unprefixed ignored because tag doesn't match)
 ```
 
-**Base Attribute Validation:**
-
-The `base` attribute must contain either a dash (`-`) or a non-ASCII character to prevent conflicts with native attributes:
-
-```TypeScript
-// Valid base attributes
-parseWithAttrs(element, { base: 'data-config' });     // Has dash
-parseWithAttrs(element, { base: '🎨-theme' });        // Has non-ASCII
-
-// Invalid - throws error
-parseWithAttrs(element, { base: 'config' });          // No dash or non-ASCII
-```
-
-**Why use `enh-` prefix?**
-
-1. **Avoid conflicts**: Custom elements may use unprefixed attributes for their own purposes
-2. **Clear intent**: Makes it obvious which attributes are for enhancements
-3. **Future-proof**: Protects against future attribute additions to custom elements
-4. **Consistency**: Provides a standard convention across all enhanced elements
-5. **Selective override**: Pattern-based `allowUnprefixed` lets you opt-in specific element families while maintaining strict isolation for others
-
 ### Basic Usage
 
 ```TypeScript
@@ -1512,7 +1538,59 @@ const config = parseWithAttrs(element, {
 });
 ```
 
-### AttrPatterns Configuration
+### Error Handling
+
+The function throws descriptive errors for common issues:
+
+```TypeScript
+// Circular reference
+parseWithAttrs(element, {
+  a: '${b}',
+  b: '${a}'  // Error: Circular reference detected
+});
+
+// Undefined variable
+parseWithAttrs(element, {
+  name: '${missing}'  // Error: Undefined template variable: missing
+});
+
+// Invalid JSON
+// HTML: <div data-obj='{invalid}'></div>
+parseWithAttrs(element, {
+  base: 'data-',
+  obj: '${base}obj',
+  _obj: { instanceOf: 'Object' }
+  // Error: Failed to parse JSON: "{invalid}"
+});
+
+// Invalid number
+// HTML: <div data-count="abc"></div>
+parseWithAttrs(element, {
+  base: 'data-',
+  count: '${base}count',
+  _count: { instanceOf: 'Number' }
+  // Error: Failed to parse number: "abc"
+});
+```
+
+</details>
+
+**Base Attribute Validation:**
+
+The `base` attribute must contain either a dash (`-`) or a non-ASCII character to prevent conflicts with native attributes:
+
+```TypeScript
+// Valid base attributes
+const enhConfig1 = { base: 'data-config' };     // Has dash
+const enhConfig2 =  { base: '🎨-theme' });        // Has non-ASCII (and dash)
+
+// Invalid - throws error
+const enhConig3 = { base: 'config' };          // No dash or non-ASCII
+```
+
+
+<details>
+  <summary>AttrPatterns Configuration</summary>
 
 The `parseWithAttrs` function accepts an `AttrPatterns` object that defines:
 
@@ -1597,6 +1675,139 @@ const result = parseWithAttrs(element, {
 // Result: { createdAt: 1705315800000 }
 ```
 
+### Named Parsers for Reusability and JSON Serialization
+
+Instead of inline functions, you can reference parsers by name, making configs JSON serializable and parsers reusable:
+
+```TypeScript
+import { globalParserRegistry, parseWithAttrs } from 'assign-gingerly';
+
+// Register parsers once (typically in app initialization)
+globalParserRegistry.register('timestamp', (v) => 
+  v ? new Date(v).getTime() : null
+);
+
+globalParserRegistry.register('csv', (v) => 
+  v ? v.split(',').map(s => s.trim()) : []
+);
+
+// Use by name - config is now JSON serializable!
+const config = {
+  base: 'data-',
+  created: '${base}created',
+  _created: {
+    parser: 'timestamp'  // String reference instead of function
+  },
+  tags: '${base}tags',
+  _tags: {
+    parser: 'csv'
+  }
+};
+
+// Can serialize to JSON
+const json = JSON.stringify(config);
+
+// Use the config
+const result = parseWithAttrs(element, config);
+```
+
+**Built-in Named Parsers:**
+
+The following parsers are pre-registered in `globalParserRegistry`:
+
+- `'timestamp'` - Parses ISO date string to Unix timestamp (milliseconds)
+- `'date'` - Parses string to Date object
+- `'csv'` - Splits comma-separated values into trimmed array
+- `'int'` - Parses integer with `parseInt(v, 10)`
+- `'float'` - Parses float with `parseFloat(v)`
+- `'boolean'` - Presence check (same as `instanceOf: 'Boolean'`)
+- `'json'` - Parses JSON (same as `instanceOf: 'Object'` or `'Array'`)
+
+**Custom Element Static Method Parsers:**
+
+You can also reference static methods on custom elements using dot notation:
+
+```TypeScript
+class MyWidget extends HTMLElement {
+  static parseSpecialFormat(v) {
+    return v ? v.toUpperCase() : null;
+  }
+  
+  static parseWithPrefix(v) {
+    return v ? `PREFIX:${v}` : null;
+  }
+}
+customElements.define('my-widget', MyWidget);
+
+// Reference custom element parsers
+const config = {
+  base: 'data-',
+  value: '${base}value',
+  _value: {
+    parser: 'my-widget.parseSpecialFormat'  // element-name.methodName
+  }
+};
+```
+
+**Parser Resolution Order:**
+
+When a string parser is specified:
+
+1. **Check for dot notation** - If parser contains `.`, try to resolve as `element-name.methodName`
+2. **Try custom element** - Look up element in `customElements` registry and check for static method
+3. **Fall back to global registry** - If custom element not found, check `globalParserRegistry`
+4. **Throw error** - If not found anywhere, throw descriptive error
+
+This allows:
+- Element-specific parsers to be scoped to their custom elements
+- Fallback to global registry for shared parsers
+- Dot notation in global registry names (e.g., `'utils.parseDate'`)
+
+**Example: Organizing Parsers**
+
+```TypeScript
+// parsers.js - Centralized parser definitions
+export function registerCommonParsers(registry) {
+  registry.register('uppercase', (v) => v ? v.toUpperCase() : null);
+  registry.register('lowercase', (v) => v ? v.toLowerCase() : null);
+  registry.register('trim', (v) => v ? v.trim() : null);
+  registry.register('phone', (v) => v ? v.replace(/\D/g, '') : null);
+}
+
+// app.js - Register at startup
+import { globalParserRegistry } from 'assign-gingerly';
+import { registerCommonParsers } from './parsers.js';
+
+registerCommonParsers(globalParserRegistry);
+
+// Now all configs can use these parsers by name
+```
+
+**Benefits of Named Parsers:**
+
+- ✅ **JSON serializable** - Configs can be stored/transmitted as JSON
+- ✅ **Reusable** - Define once, use everywhere
+- ✅ **Maintainable** - Update parser logic in one place
+- ✅ **Testable** - Test parsers independently
+- ✅ **Discoverable** - `globalParserRegistry.getNames()` lists all available parsers
+- ✅ **Backward compatible** - Inline functions still work
+
+**Mixing Inline and Named Parsers:**
+
+```TypeScript
+const config = {
+  base: 'data-',
+  created: '${base}created',
+  _created: {
+    parser: 'timestamp'  // Named parser
+  },
+  special: '${base}special',
+  _special: {
+    parser: (v) => v ? v.split('').reverse().join('') : null  // Inline
+  }
+};
+```
+
 ### Property Mapping with mapsTo
 
 The `mapsTo` property controls where parsed values are placed:
@@ -1630,6 +1841,250 @@ const result = parseWithAttrs(element, {
 // Result: { theme: 'dark', lang: 'en' }
 ```
 
+### Default Values with valIfNull
+
+The `valIfNull` property allows you to specify default values when attributes are missing:
+
+```TypeScript
+// HTML: <div></div>  (no attributes)
+
+const result = parseWithAttrs(element, {
+  base: 'data-',
+  theme: '${base}theme',
+  _theme: {
+    instanceOf: 'String',
+    valIfNull: 'light'  // Default when attribute is missing
+  },
+  count: '${base}count',
+  _count: {
+    instanceOf: 'Number',
+    valIfNull: 0  // Default to 0
+  }
+});
+// Result: { theme: 'light', count: 0 }
+```
+
+**How it works:**
+- **Attribute missing**: If the attribute doesn't exist and `valIfNull` is defined, the default value is used **without calling the parser**
+- **Attribute present**: If the attribute exists (even if empty string), the parser is called normally and `valIfNull` is ignored
+- **No valIfNull**: If `valIfNull` is undefined and the attribute is missing, the property is not added to the result (current behavior)
+
+**Important notes:**
+1. **Parser is bypassed**: When `valIfNull` is used, the parser is NOT called - the default value is used as-is
+2. **Empty string vs missing**: `valIfNull` only applies when the attribute is completely absent. If the attribute exists but is empty (`data-count=""`), the parser IS called
+3. **Any value allowed**: `valIfNull` can be any JavaScript value: string, number, boolean, object, array, null, etc.
+4. **Falsy values work**: Even falsy values like `0`, `false`, `''`, or `null` are valid defaults
+
+**Examples with different types:**
+
+```TypeScript
+// Object default
+const result1 = parseWithAttrs(element, {
+  base: 'config-',
+  settings: '${base}settings',
+  _settings: {
+    instanceOf: 'Object',
+    valIfNull: { enabled: false, mode: 'auto' }
+  }
+});
+// Result: { settings: { enabled: false, mode: 'auto' } }
+
+// Boolean default
+const result2 = parseWithAttrs(element, {
+  base: 'feature-',
+  enabled: '${base}enabled',
+  _enabled: {
+    instanceOf: 'Boolean',
+    valIfNull: false
+  }
+});
+// Result: { enabled: false }
+
+// Array default
+const result3 = parseWithAttrs(element, {
+  base: 'data-',
+  items: '${base}items',
+  _items: {
+    instanceOf: 'Array',
+    valIfNull: []
+  }
+});
+// Result: { items: [] }
+
+// null as default
+const result4 = parseWithAttrs(element, {
+  base: 'data-',
+  value: '${base}value',
+  _value: {
+    instanceOf: 'String',
+    valIfNull: null
+  }
+});
+// Result: { value: null }
+```
+
+**Comparison: Empty string vs missing attribute:**
+
+```html
+<!-- Attribute is missing -->
+<div></div>
+
+<!-- Attribute exists but is empty -->
+<div data-count=""></div>
+```
+
+```TypeScript
+const config = {
+  base: 'data-',
+  count: '${base}count',
+  _count: {
+    instanceOf: 'Number',
+    valIfNull: 99
+  }
+};
+
+// Missing attribute - uses valIfNull
+const result1 = parseWithAttrs(document.querySelector('div:nth-child(1)'), config);
+// Result: { count: 99 }
+
+// Empty string - calls parser (returns null for empty Number)
+const result2 = parseWithAttrs(document.querySelector('div:nth-child(2)'), config);
+// Result: { count: null }
+```
+
+### Performance Optimization with parseCache
+
+The `parseCache` property enables caching of parsed attribute values to improve performance when the same attribute values appear repeatedly throughout the document:
+
+```TypeScript
+// HTML: Multiple elements with same attribute values
+// <div data-config='{"theme":"dark","size":"large"}'></div>
+// <div data-config='{"theme":"dark","size":"large"}'></div>
+// <div data-config='{"theme":"dark","size":"large"}'></div>
+
+const config = {
+  base: 'data-',
+  config: '${base}config',
+  _config: {
+    instanceOf: 'Object',
+    parseCache: 'shared'  // Cache and reuse parsed objects
+  }
+};
+
+// First parse - parses and caches
+const result1 = parseWithAttrs(element1, config);
+
+// Subsequent parses - returns cached value (no parsing)
+const result2 = parseWithAttrs(element2, config);
+const result3 = parseWithAttrs(element3, config);
+```
+
+**Cache Strategies:**
+
+1. **`'shared'`**: Returns the same object reference from cache
+   - **Fastest**: No cloning overhead
+   - **Risk**: Enhancements that mutate the object will affect all instances
+   - **Best for**: Immutable data or when you trust enhancements not to mutate
+
+2. **`'cloned'`**: Returns a structural clone of the cached object
+   - **Safer**: Each instance gets its own copy
+   - **Slower**: Uses `structuredClone()` which has overhead
+   - **Best for**: Mutable data or when enhancements might modify values
+
+**Examples:**
+
+```TypeScript
+// Shared cache - fast but requires discipline
+const sharedConfig = {
+  base: 'data-',
+  settings: '${base}settings',
+  _settings: {
+    instanceOf: 'Object',
+    parseCache: 'shared'  // All instances share same object
+  }
+};
+
+// Cloned cache - safer for mutable data
+const clonedConfig = {
+  base: 'data-',
+  state: '${base}state',
+  _state: {
+    instanceOf: 'Object',
+    parseCache: 'cloned'  // Each instance gets a copy
+  }
+};
+
+// Custom parser with caching
+let parseCount = 0;
+const customConfig = {
+  base: 'data-',
+  timestamp: '${base}timestamp',
+  _timestamp: {
+    parser: (v) => {
+      parseCount++;  // Track parse calls
+      return v ? new Date(v).getTime() : null;
+    },
+    parseCache: 'shared'  // Parser only called once per unique value
+  }
+};
+```
+
+**Important Notes:**
+
+1. **Parser purity**: Parsers should be pure functions (no side effects) when using caching
+2. **Boolean types**: Caching is skipped for Boolean types (presence check doesn't benefit)
+3. **Cache scope**: Cache is module-level and persists across all `parseWithAttrs()` calls
+4. **Cache key**: Values are cached per `(instanceOf, parserType, attributeValue)` tuple
+5. **Memory**: Cache grows with unique attribute values encountered (no automatic cleanup)
+6. **Browser support**: `'cloned'` strategy requires `structuredClone()` (modern browsers)
+
+**Performance Considerations:**
+
+- **Shared cache**: Best for simple objects, arrays, or when parsing is expensive
+- **Cloned cache**: Overhead may negate benefits for simple values (strings, numbers)
+- **No cache**: Better for unique values or when parsing is trivial
+- **Custom parsers**: Caching is most beneficial when parser does expensive operations (Date parsing, complex transformations)
+
+**Example: Shared cache mutation risk**
+
+```TypeScript
+const config = {
+  base: 'data-',
+  items: '${base}items',
+  _items: {
+    instanceOf: 'Array',
+    parseCache: 'shared'
+  }
+};
+
+// HTML: <div data-items='[1,2,3]'></div>
+
+const result1 = parseWithAttrs(element1, config);
+result1.items.push(4);  // Mutation!
+
+const result2 = parseWithAttrs(element2, config);
+console.log(result2.items);  // [1,2,3,4] - mutation is visible!
+```
+
+**Example: Cloned cache safety**
+
+```TypeScript
+const config = {
+  base: 'data-',
+  items: '${base}items',
+  _items: {
+    instanceOf: 'Array',
+    parseCache: 'cloned'  // Safe from mutations
+  }
+};
+
+const result1 = parseWithAttrs(element1, config);
+result1.items.push(4);  // Mutation
+
+const result2 = parseWithAttrs(element2, config);
+console.log(result2.items);  // [1,2,3] - original value preserved
+```
+
 ### Base Attribute
 
 The special `base` property handles a single attribute that spreads into the result:
@@ -1654,6 +2109,15 @@ const result2 = parseWithAttrs(element, {
 // Result: { greetings: { hello: 'world', goodbye: 'Mars' } }
 ```
 
+### Best Practices
+
+1. **Use base for common prefixes**: Reduces repetition in attribute names
+2. **Leverage template variables**: Build complex attribute names from simple parts
+3. **Specify instanceOf**: Ensures proper type conversion
+4. **Use mapsTo for clarity**: Map attribute names to meaningful property names
+5. **Combine with assignGingerly**: Use nested paths (`?.`) for deep property assignment
+6. **Handle missing attributes**: Non-existent attributes are skipped (except Boolean types)
+
 ### Nested Paths with assignGingerly
 
 Combine `parseWithAttrs` with `assignGingerly` for nested property assignment:
@@ -1680,6 +2144,10 @@ assignGingerly(element, attrs);
 // element.moods.personIsHappy === true
 ```
 
+</details>
+
+<!--
+
 ### Complete Example
 
 ```TypeScript
@@ -1719,46 +2187,8 @@ console.log(result);
 // }
 ```
 
-### Error Handling
-
-The function throws descriptive errors for common issues:
-
-```TypeScript
-// Circular reference
-parseWithAttrs(element, {
-  a: '${b}',
-  b: '${a}'  // Error: Circular reference detected
-});
-
-// Undefined variable
-parseWithAttrs(element, {
-  name: '${missing}'  // Error: Undefined template variable: missing
-});
+-->
 
-// Invalid JSON
-// HTML: <div data-obj='{invalid}'></div>
-parseWithAttrs(element, {
-  base: 'data-',
-  obj: '${base}obj',
-  _obj: { instanceOf: 'Object' }
-  // Error: Failed to parse JSON: "{invalid}"
-});
 
-// Invalid number
-// HTML: <div data-count="abc"></div>
-parseWithAttrs(element, {
-  base: 'data-',
-  count: '${base}count',
-  _count: { instanceOf: 'Number' }
-  // Error: Failed to parse number: "abc"
-});
-```
 
-### Best Practices
 
-1. **Use base for common prefixes**: Reduces repetition in attribute names
-2. **Leverage template variables**: Build complex attribute names from simple parts
-3. **Specify instanceOf**: Ensures proper type conversion
-4. **Use mapsTo for clarity**: Map attribute names to meaningful property names
-5. **Combine with assignGingerly**: Use nested paths (`?.`) for deep property assignment
-6. **Handle missing attributes**: Non-existent attributes are skipped (except Boolean types)