assign-gingerly 0.0.31 → 0.0.33

package/README.md

@@ -110,7 +110,7 @@ console.log(obj);
 
 When the right hand side of an expression is an object, assignGingerly behavior depends on the context:
 - For **nested paths** (starting with `?.`): recursively merges into nested objects, creating them if needed
-- For **plain keys**: performs simple assignment (like `Object.assign`), unless the target property is readonly or a class instance (see Examples 3a and 3b below)
+- For **plain keys**: performs simple assignment (like `Object.assign`), unless the target property is readonly or an accessor (see Examples 3a and 3b below)
 
 Of course, just as Object.assign led to object spread notation, assignGingerly could lead to some sort of deep structural JavaScript syntax, but that is outside the scope of this polyfill package.
 
@@ -144,38 +144,40 @@ console.log(obj.config); // { theme: 'dark' } - intermediate object created
 
 ## Example 3a - Automatic Readonly Property Detection
 
-assignGingerly automatically detects readonly properties and merges into them instead of attempting to replace them. This makes working with DOM properties like `style` and `dataset` much more ergonomic:
+assignGingerly automatically detects readonly properties and merges into them instead of attempting to replace them. This makes working with DOM properties like `dataset` ergonomic:
 
 ```TypeScript
-// Instead of this verbose syntax:
 const div = document.createElement('div');
 assignGingerly(div, {
-    '?.style?.height': '15px',
-    '?.style?.width': '20px'
-});
-
-// You can now use this cleaner syntax:
-assignGingerly(div, {
-    style: {
-        height: '15px',
-        width: '20px'
+    dataset: {
+        userId: '123',
+        userName: 'Alice'
     }
 });
-console.log(div.style.height); // '15px'
-console.log(div.style.width);  // '20px'
+console.log(div.dataset.userId);   // '123'
+console.log(div.dataset.userName); // 'Alice'
 ```
 
 **How it works:**
 
 When assignGingerly encounters an object value being assigned to an existing property, it checks if that property is readonly:
 - **Data properties** with `writable: false`
-- **Accessor properties** with a getter but no setter
+- **Accessor properties** with a getter but no setter (e.g., `dataset`, `shadowRoot`)
 
 If the property is readonly and its current value is an object, assignGingerly automatically merges into it recursively.
 
-**Examples of readonly properties:**
-- `HTMLElement.style` - The CSSStyleDeclaration object
-- `HTMLElement.dataset` - The DOMStringMap object  
+**Note on `element.style`:** The `style` property has both a getter and a setter, so it is *not* treated as readonly. Use nested path syntax instead:
+
+```TypeScript
+// Use nested path syntax for style
+assignGingerly(div, {
+    '?.style?.height': '15px',
+    '?.style?.width': '20px'
+});
+```
+
+**Examples of readonly properties that trigger merging:**
+- `HTMLElement.dataset` - getter only, no setter
 - Custom objects with `Object.defineProperty(obj, 'prop', { value: {}, writable: false })`
 - Accessor properties with getter only: `Object.defineProperty(obj, 'prop', { get() { return {}; } })`
 
@@ -225,134 +227,54 @@ assignGingerly(config, {
 console.log(config.settings.theme); // 'dark'
 ```
 
-## Example 3b - Automatic Class Instance Preservation
+## Example 3b - Class Instances Are Replaced
 
-In addition to readonly property detection, assignGingerly automatically preserves class instances when merging. This is particularly useful when working with enhancement instances:
+Unlike readonly/accessor properties, class instances on writable properties are **replaced** by simple assignment, just like plain objects. This allows you to swap one object for another without unexpected merging:
 
 ```TypeScript
-import 'assign-gingerly/object-extension.js';
-
-// Define an enhancement class
-class MyEnhancement {
-  constructor(element, ctx, initVals) {
-    this.element = element;
-    this.instanceId = Math.random(); // Track instance identity
-    if (initVals) {
-      Object.assign(this, initVals);
-    }
+class FakeDocumentFragment {
+  constructor() {
+    this.nodeType = 11;
+    this.childNodes = [];
   }
-  prop1 = null;
-  prop2 = null;
 }
 
-const element = document.createElement('div');
-element.enh = {
-  myEnh: new MyEnhancement(element, {}, {})
+const obj = {
+  clone: new FakeDocumentFragment()
 };
 
-const originalId = element.enh.myEnh.instanceId;
-
-// Clean syntax - no need for ?.myEnh?.prop1 notation
-assignGingerly(element, {
-  enh: {
-    myEnh: {
-      prop1: 'value1',
-      prop2: 'value2'
-    }
-  }
-});
-
-console.log(element.enh.myEnh.instanceId === originalId); // true - instance preserved!
-console.log(element.enh.myEnh.prop1); // 'value1'
-console.log(element.enh.myEnh.prop2); // 'value2'
-```
-
-**How it works:**
-
-When assignGingerly encounters an object value being assigned to an existing property, it checks if the current value is a class instance (not a plain object):
-
-- **Class instances** are detected by checking if their prototype is something other than `Object.prototype` or `null`
-- **Plain objects** `{}` have `Object.prototype` as their prototype
-- **Class instances** have their class's prototype
-
-If the existing value is a class instance, assignGingerly merges into it instead of replacing it.
-
-**What counts as a class instance:**
-- Custom class instances: `new MyClass()`
-- Built-in class instances: `new Date()`, `new Map()`, `new Set()`, etc.
-- Enhancement instances on the `enh` property
-- Any object whose prototype is not `Object.prototype` or `null`
-
-**What doesn't count:**
-- Plain objects: `{}`, `{ a: 1 }`
-- Arrays: `[]`, `[1, 2, 3]` (arrays are replaced, not merged)
-- Primitives: strings, numbers, booleans
-
-**Benefits:**
-
-This feature enables clean, framework-friendly syntax for updating enhancements:
+const element = document.createElement('div');
 
-```TypeScript
-// Before: Verbose nested path syntax
-assignGingerly(element, {
-  '?.enh?.mellowYellow?.madAboutFourteen': true
+// Replace the DocumentFragment with the actual element
+assignGingerly(obj, {
+  clone: element
 });
 
-// After: Clean object syntax
-assignGingerly(element, {
-  enh: {
-    mellowYellow: {
-      madAboutFourteen: true
-    }
-  }
-});
+console.log(obj.clone === element); // true - replaced, not merged
 ```
 
-**Additional examples:**
-
-```TypeScript
-// Multiple enhancements at once
-assignGingerly(element, {
-  enh: {
-    enhancement1: { prop: 'value1' },
-    enhancement2: { prop: 'value2' }
-  }
-});
-
-// Works with built-in classes too
-const obj = {
-  timestamp: new Date('2024-01-01')
-};
-
-assignGingerly(obj, {
-  timestamp: {
-    customProp: 'metadata'
-  }
-});
+**Why replacement instead of merging?**
 
-console.log(obj.timestamp instanceof Date); // true - Date instance preserved
-console.log(obj.timestamp.customProp);      // 'metadata'
-```
+In real-world use cases, you often need to replace one object with another of a completely different type. For example, replacing a cloned DocumentFragment with the actual web component element. Automatic merging would corrupt the target by mixing properties from incompatible types.
 
-**Combined with readonly detection:**
+**Readonly/accessor properties are still merged:**
 
-Both readonly properties and class instances are preserved:
+The distinction is clear:
+- **Writable data properties**: always replaced (whether holding a plain object or class instance)
+- **Readonly data properties** (`writable: false`): merged into
+- **Getter-only accessor properties** (no setter): merged into
+- **Getter+setter accessor properties** (e.g., `style`): setter runs with the value as-is
 
 ```TypeScript
 const div = document.createElement('div');
-div.enh = {
-  myEnh: new MyEnhancement(div, {}, {})
-};
 
 assignGingerly(div, {
-  style: { height: '100px' },      // Readonly - merged
-  enh: {
-    myEnh: { prop: 'value' }       // Class instance - merged
-  },
-  dataset: { userId: '123' }       // Readonly - merged
+  dataset: { userId: '123' },       // Getter-only - merged
+  '?.style?.height': '100px'        // Use nested path for style
 });
 
-// All instances and readonly objects preserved
+console.log(div.dataset.userId);  // '123'
+console.log(div.style.height);    // '100px'
 ```
 
 ## Example 3c - Method Calls with withMethods
@@ -411,25 +333,31 @@ assignGingerly(elementRef, {
 // Equivalent to: elementRef.deref().classList.add('active')
 ```
 
-**Complex chaining:**
+**Complex chaining with real DOM elements:**
+
+Methods are called on the objects found through chained accessors, not just on the root object:
 
 ```TypeScript
-const shadowRoot = {
-  querySelector(selector) {
-    return this.elements[selector];
-  },
-  elements: {
-    'my-element': document.createElement('div')
-  }
-};
+const div = document.createElement('div');
+div.innerHTML = `
+  <my-element>
+    <your-element></your-element>
+  </my-element>
+`;
 
-assignGingerly(shadowRoot, {
-  '?.querySelector?.my-element?.classList?.add': 'highlighted'
+assignGingerly(div, {
+  '?.querySelector?.my-element?.querySelector?.your-element?.classList?.add': 'highlighted'
 }, { withMethods: ['querySelector', 'add'] });
 
-// Equivalent to: shadowRoot.querySelector('my-element').classList.add('highlighted')
+// Equivalent to:
+// div.querySelector('my-element').querySelector('your-element').classList.add('highlighted')
+
+const yourElement = div.querySelector('my-element')?.querySelector('your-element');
+console.log(yourElement?.classList.contains('highlighted')); // true
 ```
 
+The key insight: `querySelector` is called on each intermediate result in the chain. First on `div`, then on the `my-element` result, demonstrating that methods work naturally with the object hierarchy you're navigating.
+
 **Using Set for withMethods:**
 
 For better performance with many methods, use a Set:
@@ -464,6 +392,321 @@ assignGingerly(element, {
 - Silent failure for non-existent methods (garbage in, garbage out)
 - Supports method chaining and complex navigation patterns
 
+## Example 3d - Aliasing with aka
+
+The `aka` option allows you to define custom shortcuts (aliases) for property and method names, reducing verbosity in repetitive patterns. This is inspired by jQuery's `$` shortcut for `querySelectorAll`, but fully customizable.
+
+```TypeScript
+import assignGingerly from 'assign-gingerly';
+
+const div = document.createElement('div');
+div.innerHTML = `
+  <my-element>
+    <your-element></your-element>
+  </my-element>
+`;
+
+// Without aliases (verbose)
+assignGingerly(div, {
+  '?.querySelector?.my-element?.classList?.add': 'highlighted',
+  '?.querySelector?.your-element?.classList?.add': 'active'
+}, { withMethods: ['querySelector', 'add'] });
+
+// With aliases (concise)
+assignGingerly(div, {
+  '?.$?.my-element?.c?.+': 'highlighted',
+  '?.$?.your-element?.c?.+': 'active'
+}, { 
+  withMethods: ['querySelector', 'add'],
+  aka: { '$': 'querySelector', 'c': 'classList', '+': 'add' }
+});
+```
+
+**How it works:**
+
+- Aliases are substituted **before** path evaluation
+- Matches complete tokens between `?.` delimiters (not substrings)
+- Works for both properties and methods
+- Single or multi-character aliases supported
+
+**Reserved characters:**
+
+Cannot be used in aliases: space (` `), backtick (`` ` ``)
+
+**Multi-character aliases:**
+
+```TypeScript
+assignGingerly(element, {
+  '?.qs?.my-element?.cl?.add': 'highlighted'
+}, { 
+  withMethods: ['querySelector', 'add'],
+  aka: { 'qs': 'querySelector', 'cl': 'classList' }
+});
+```
+
+**Multiple aliases in one path:**
+
+```TypeScript
+assignGingerly(element, {
+  '?.c?.+': 'class1',
+  '?.p?.+': 'part1',
+  '?.ds?.userId': '123'
+}, { 
+  withMethods: ['add'],
+  aka: { 
+    'c': 'classList', 
+    'p': 'part',
+    'ds': 'dataset',
+    '+': 'add'
+  }
+});
+
+// Equivalent to:
+// element.classList.add('class1')
+// element.part.add('part1')
+// element.dataset.userId = '123'
+```
+
+**Benefits:**
+
+- Reduces verbosity in repetitive patterns
+- Fully customizable shortcuts
+- Improves readability when you have many similar operations
+- Works seamlessly with `withMethods`
+
+## Example 3e - ForEach with @each
+
+The `@each` symbol allows you to iterate over collections and apply operations to each item. This works with any iterable including Arrays, NodeList, HTMLCollection, and more.
+
+```TypeScript
+import assignGingerly from 'assign-gingerly';
+
+const div = document.createElement('div');
+div.innerHTML = `
+  <my-element></my-element>
+  <my-element></my-element>
+  <my-element></my-element>
+`;
+
+// Apply to each element in the collection
+assignGingerly(div, {
+  '?.querySelectorAll?.my-element?.@each?.classList?.add': 'highlighted'
+}, { withMethods: ['querySelectorAll', 'add'] });
+
+// All my-element elements now have the 'highlighted' class
+```
+
+**How it works:**
+
+- `@each` marks the point where iteration begins
+- Everything before `@each` navigates to the iterable
+- Everything after `@each` is applied to each item in the collection
+- Empty collections are handled gracefully (no errors)
+
+**With regular arrays:**
+
+```TypeScript
+const obj = {
+  items: [
+    { value: null },
+    { value: null },
+    { value: null }
+  ]
+};
+
+assignGingerly(obj, {
+  '?.items?.@each?.value': 'test'
+});
+
+// All items now have value: 'test'
+```
+
+**Nested forEach:**
+
+```TypeScript
+const obj = {
+  groups: [
+    { items: [{ value: null }, { value: null }] },
+    { items: [{ value: null }, { value: null }] }
+  ]
+};
+
+assignGingerly(obj, {
+  '?.groups?.@each?.items?.@each?.value': 'nested'
+});
+
+// All nested items now have value: 'nested'
+```
+
+**With aliases:**
+
+```TypeScript
+assignGingerly(div, {
+  '?.qsa?.my-element?.*?.c?.+': 'highlighted'
+}, { 
+  withMethods: ['querySelectorAll', 'add'],
+  aka: { 
+    'qsa': 'querySelectorAll',
+    'c': 'classList',
+    '+': 'add',
+    '*': '@each'  // Alias * to @each for brevity
+  }
+});
+```
+
+**Method calls on each item:**
+
+```TypeScript
+assignGingerly(div, {
+  '?.querySelectorAll?.div?.@each?.setAttribute': ['data-id', '123']
+}, { withMethods: ['querySelectorAll', 'setAttribute'] });
+
+// All div elements now have data-id="123"
+```
+
+**Accessing iterable properties:**
+
+When you omit `@each`, you access properties on the iterable itself, not its items:
+
+```TypeScript
+const obj = {
+  items: [1, 2, 3],
+  customProp: null
+};
+
+// Set property on the array itself
+assignGingerly(obj, {
+  '?.items?.customProp': 'test'
+});
+
+console.log(obj.items.customProp); // 'test'
+```
+
+**Benefits:**
+
+- Works with any iterable (Arrays, NodeList, HTMLCollection, etc.)
+- Supports nested iterations
+- Integrates seamlessly with `withMethods` and `aka`
+- Clear distinction between iterating and accessing iterable properties
+- Graceful handling of empty collections
+
+## Example 3f - Reactive Iteration with @eachTime
+
+The `@eachTime` symbol enables reactive iteration over elements as they mount or appear dynamically. Unlike `@each` which operates on static collections, `@eachTime` subscribes to events and applies operations to elements as they arrive over time.
+
+**Important:** This feature requires an `AbortSignal` for cleanup and is designed to work with EventTarget objects that emit 'mount' events (such as [mount-observer](https://github.com/bahrus/mount-observer)).
+
+```TypeScript
+import assignGingerly from 'assign-gingerly';
+
+const controller = new AbortController();
+const div = document.createElement('div');
+
+// Assume mountObserver is an IMountObserver instance that emits 'mount' events
+// when new elements matching 'my-element' are added to the DOM
+
+assignGingerly(div, {
+  '?.mountObserver?.@eachTime?.classList?.add': 'highlighted'
+}, { 
+  withMethods: ['add'],
+  signal: controller.signal  // Required for cleanup
+});
+
+// As elements mount, they automatically get the 'highlighted' class
+// Later, cleanup all listeners:
+controller.abort();
+```
+
+**How it works:**
+
+- `@eachTime` marks the point where reactive iteration begins
+- Everything before `@eachTime` must navigate to an EventTarget
+- The EventTarget must emit 'mount' events with a `mountedElement` property
+- Everything after `@eachTime` is applied to each mounted element
+- Event listeners are automatically cleaned up when the AbortSignal is aborted
+
+**With method calls:**
+
+```TypeScript
+const controller = new AbortController();
+
+assignGingerly(div, {
+  '?.mountObserver?.@eachTime?.setAttribute': ['data-mounted', 'true']
+}, { 
+  withMethods: ['setAttribute'],
+  signal: controller.signal
+});
+
+// Each mounted element gets data-mounted="true"
+```
+
+**With aliases:**
+
+```TypeScript
+const controller = new AbortController();
+
+assignGingerly(div, {
+  '?.mo?.@*?.c?.+': 'active'
+}, { 
+  withMethods: ['add'],
+  aka: { 
+    'mo': 'mountObserver',
+    '@*': '@eachTime',
+    'c': 'classList',
+    '+': 'add'
+  },
+  signal: controller.signal
+});
+```
+
+**Cleanup is required:**
+
+```TypeScript
+const controller = new AbortController();
+
+// Setup reactive iteration
+assignGingerly(div, {
+  '?.mountObserver?.@eachTime?.classList?.add': 'mounted'
+}, { 
+  withMethods: ['add'],
+  signal: controller.signal
+});
+
+// Later, when you're done observing:
+controller.abort();  // Removes all event listeners
+
+// Attempting to use @eachTime without a signal throws an error:
+assignGingerly(div, {
+  '?.mountObserver?.@eachTime?.classList?.add': 'mounted'
+}, { withMethods: ['add'] });
+// Error: @eachTime requires an AbortSignal in options.signal for cleanup
+```
+
+**Key differences from @each:**
+
+| Feature | @each | @eachTime |
+|---------|-------|-----------|
+| **Type** | Static iteration | Reactive iteration |
+| **Timing** | Immediate (synchronous) | Over time (asynchronous) |
+| **Use case** | Existing collections | Elements appearing dynamically |
+| **Cleanup** | Not needed | Required (AbortSignal) |
+| **Requirements** | Any iterable | EventTarget with 'mount' events |
+
+**Benefits:**
+
+- Declarative reactive programming without RxJS complexity
+- Automatic cleanup via standard AbortSignal API
+- JSON-serializable configuration (behavior is in implementation)
+- Fire-and-forget async pattern (doesn't block)
+- Minimal weight impact (~3% when not used, dynamically loaded when needed)
+
+**Limitations:**
+
+- Requires EventTarget that emits 'mount' events
+- AbortSignal is mandatory for cleanup
+- Testing is done in mount-observer package (no tests in assign-gingerly)
+- Single @eachTime per path (nested @eachTime not currently supported)
+
 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
@@ -649,10 +892,12 @@ console.log(string1 === string2); // true
 
 This guarantees that applying the reversal object restores the object to its exact original state.
 
+# Object and Element Enhancements via assign-gingerly
+
 ## Dependency injection based on a registry object and a Symbolic reference mapping
 
 ```Typescript
-interface IEnhancementRegistryItem<T = any, TObjToExtend = any> {
+interface EnhancementConfig<T = any, TObjToExtend = any> {
     spawn: {new(objToExtend: TObjToExtend, ctx: SpawnContext, initVals: Partial<T>): T}
     symlinks?: {[key: symbol]: keyof T}
     // Optional: for element enhancement access
@@ -678,7 +923,7 @@ class YourEnhancement{
 }
 
 class EnhancementRegistry{
-    push(IEnhancementRegistryItem | IEnhancementRegistryItem[]){
+    push(EnhancementConfig | EnhancementConfig[]){
         ...
     }
 }
@@ -1035,7 +1280,7 @@ Element enhancement classes should follow this constructor signature:
 
 ```TypeScript
 interface SpawnContext<T, TMountContext = any> {
-  config: IEnhancementRegistryItem<T>;
+  config: EnhancementConfig<T>;
   mountCtx?: TMountContext;  // Optional custom context passed by caller
 }
 
@@ -1089,7 +1334,7 @@ This is useful for:
 In addition to spawn and symlinks, registry items support optional properties `enhKey`, `withAttrs`, `canSpawn`, and `lifecycleKeys`:
 
 ```TypeScript
-interface IEnhancementRegistryItem<T, TObj = Element> {
+interface EnhancementConfig<T, TObj = Element> {
   spawn: { 
     new (obj?: TObj, ctx?: SpawnContext<T>, initVals?: Partial<T>): T;
     canSpawn?: (obj: TObj, ctx?: SpawnContext<T>) => boolean;  // Optional spawn guard
@@ -1229,6 +1474,37 @@ 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
 
+**Lookup by enhKey (string or symbol):**
+
+Instead of passing the full registry item object, you can pass a string or symbol matching the `enhKey` of a previously registered enhancement:
+
+```TypeScript
+// First, register the enhancement (e.g., via mount-observer or manually)
+registry.push({
+  spawn: MyEnhancement,
+  enhKey: 'myEnh'
+});
+
+// Later, retrieve by enhKey string
+const instance = element.enh.get('myEnh');
+
+// Or by symbol enhKey
+const enhSym = Symbol.for('myEnh');
+const instance2 = element.enh.get(enhSym);
+```
+
+If the enhKey is not found in the registry, an error is thrown: `"myEnh not in registry"`.
+
+This also works with `enh.dispose()` and `enh.whenResolved()`:
+
+```TypeScript
+// Dispose by enhKey
+element.enh.dispose('myEnh');
+
+// Wait for resolution by enhKey
+const resolved = await element.enh.whenResolved('myEnh');
+```
+
 <details>
 <summary>Example with shared instances</summary>
 
@@ -1779,7 +2055,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: IEnhancementRegistryItem<T> }`
+- `ctx`: Optional spawn context containing `{ config: EnhancementConfig<T> }`
 - Returns: `true` to allow spawning, `false` to block
 
 ### Use Cases