assign-gingerly 0.0.31 → 0.0.32

package/README.md

@@ -411,25 +411,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 +470,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 +970,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 +1001,7 @@ class YourEnhancement{
 }
 
 class EnhancementRegistry{
-    push(IEnhancementRegistryItem | IEnhancementRegistryItem[]){
+    push(EnhancementConfig | EnhancementConfig[]){
         ...
     }
 }
@@ -1035,7 +1358,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 +1412,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 +1552,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 +2133,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

package/assignFrom.js

@@ -0,0 +1,27 @@
+/**
+ * Resolve RHS path strings against a source object, then assign the
+ * resolved values into a target using assignGingerly.
+ *
+ * Combines resolveValues + assignGingerly into a single call.
+ * Inherits all assignGingerly options (withMethods, aka, signal, etc.).
+ *
+ * @param target - Object to merge resolved values into
+ * @param pattern - Object whose RHS values may contain `?.` path strings
+ * @param options - Options including `from` (source object) and any assignGingerly options
+ * @returns The target object after merging
+ *
+ * @example
+ * const source = { theme: { color: 'red' }, label: 'Hello' };
+ * const target = { color: 'blue', text: '' };
+ * assignFrom(target, {
+ *   color: '?.theme?.color',
+ *   text: '?.label'
+ * }, { from: source });
+ * // target is now { color: 'red', text: 'Hello' }
+ */
+import { resolveValues } from './resolveValues.js';
+import assignGingerly from './assignGingerly.js';
+export function assignFrom(target, pattern, options) {
+    const resolved = resolveValues(pattern, options.from);
+    return assignGingerly(target, resolved, options);
+}

package/assignFrom.ts

@@ -0,0 +1,37 @@
+/**
+ * Resolve RHS path strings against a source object, then assign the
+ * resolved values into a target using assignGingerly.
+ * 
+ * Combines resolveValues + assignGingerly into a single call.
+ * Inherits all assignGingerly options (withMethods, aka, signal, etc.).
+ * 
+ * @param target - Object to merge resolved values into
+ * @param pattern - Object whose RHS values may contain `?.` path strings
+ * @param options - Options including `from` (source object) and any assignGingerly options
+ * @returns The target object after merging
+ * 
+ * @example
+ * const source = { theme: { color: 'red' }, label: 'Hello' };
+ * const target = { color: 'blue', text: '' };
+ * assignFrom(target, {
+ *   color: '?.theme?.color',
+ *   text: '?.label'
+ * }, { from: source });
+ * // target is now { color: 'red', text: 'Hello' }
+ */
+import { resolveValues } from './resolveValues.js';
+import assignGingerly, { IAssignGingerlyOptions } from './assignGingerly.js';
+
+export interface AssignFromOptions extends IAssignGingerlyOptions {
+  /** Source object to resolve RHS path strings against */
+  from: any;
+}
+
+export function assignFrom(
+  target: any,
+  pattern: Record<string, any>,
+  options: AssignFromOptions
+): any {
+  const resolved = resolveValues(pattern, options.from);
+  return assignGingerly(target, resolved, options);
+}