assign-gingerly 0.0.10 → 0.0.12

package/README.md

@@ -607,7 +607,7 @@ When you access `element.enh.set.enhKey.property`, the proxy:
 
 1. **Checks the registry**: Looks for a registry item with `enhKey` matching the property name
 2. **Spawns if needed**: If found and the enhancement doesn't exist or is the wrong type:
-   - Creates a `SpawnContext` with `{ mountInfo: registryItem }`
+   - Creates a `SpawnContext` with `{ config: registryItem }`
    - Calls the constructor with `(element, ctx, initVals)`
    - If a non-matching object already exists at `element.enh[enhKey]`, it's passed as `initVals`
    - Stores the spawned instance at `element.enh[enhKey]`
@@ -628,23 +628,51 @@ This approach is part of a proposal to WHATWG for standardizing element enhancem
 Enhancement classes should follow this constructor signature:
 
 ```TypeScript
-interface SpawnContext<T> {
-  mountInfo: IBaseRegistryItem<T>;
+interface SpawnContext<T, TMountContext = any> {
+  config: IBaseRegistryItem<T>;
+  mountCtx?: TMountContext;  // Optional custom context passed by caller
 }
 
 class Enhancement {
   constructor(
     oElement?: Element,      // The element being enhanced
-    ctx?: SpawnContext,      // Context with registry item info
+    ctx?: SpawnContext,      // Context with registry item info and optional mountCtx
     initVals?: Partial<T>    // Initial values if property existed
   ) {
     // Your initialization logic
+    // Access custom context via ctx.mountCtx if provided
   }
 }
 ```
 
 All parameters are optional for backward compatibility with existing code.
 
+**Passing Custom Context:**
+
+You can pass custom context when calling `enh.get()` or `enh.whenResolved()`:
+
+```TypeScript
+// Pass custom context to the spawned instance
+const myContext = { userId: 123, permissions: ['read', 'write'] };
+const instance = element.enh.get(registryItem, myContext);
+
+// The constructor receives it via ctx.mountCtx
+class MyEnhancement {
+  constructor(oElement, ctx, initVals) {
+    console.log(ctx.mountCtx.userId);        // 123
+    console.log(ctx.mountCtx.permissions);   // ['read', 'write']
+  }
+}
+```
+
+This is useful for:
+- Passing authentication/authorization context
+- Providing configuration that varies per invocation
+- Sharing state between caller and enhancement
+- Dependency injection of services or utilities
+
+**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).
+
 ### Registry Item with enhKey
 
 Registry items now support optional `enhKey`, `withAttrs`, `canSpawn`, and `lifecycleKeys` properties:
@@ -1031,6 +1059,11 @@ const customRegistryItem = {
 // Wait for the enhancement to be fully initialized
 const instance = await element.enh.whenResolved(registryItem);
 console.log(instance.data); // Data is loaded and ready
+
+// With custom context
+const authContext = { token: 'abc123', userId: 456 };
+const instanceWithContext = await element.enh.whenResolved(registryItem, authContext);
+// The constructor receives authContext via ctx.mountCtx
 ```
 
 **How `enh.whenResolved()` works:**
@@ -1185,7 +1218,7 @@ static canSpawn(obj: any, ctx?: SpawnContext<T>): boolean
 ```
 
 - `obj`: The target object being enhanced (element, plain object, etc.)
-- `ctx`: Optional spawn context containing `{ mountInfo: IBaseRegistryItem<T> }`
+- `ctx`: Optional spawn context containing `{ config: IBaseRegistryItem<T> }`
 - Returns: `true` to allow spawning, `false` to block
 
 ### Use Cases

package/assignGingerly.js

@@ -315,7 +315,7 @@ export function assignGingerly(target, source, options) {
                     const SpawnClass = registryItem.spawn;
                     // Check canSpawn if it exists
                     if (typeof SpawnClass.canSpawn === 'function') {
-                        const ctx = { mountInfo: registryItem };
+                        const ctx = { config: registryItem };
                         if (!SpawnClass.canSpawn(target, ctx)) {
                             // canSpawn returned false, skip spawning
                             continue;
@@ -323,7 +323,7 @@ export function assignGingerly(target, source, options) {
                     }
                     // If target is an Element and registryItem has enhKey, pass element to constructor
                     if (registryItem.enhKey && typeof Element !== 'undefined' && target instanceof Element) {
-                        const ctx = { mountInfo: registryItem };
+                        const ctx = { config: registryItem };
                         const initVals = target.enh?.[registryItem.enhKey] &&
                             !(target.enh[registryItem.enhKey] instanceof SpawnClass)
                             ? target.enh[registryItem.enhKey]
@@ -344,9 +344,11 @@ export function assignGingerly(target, source, options) {
                     }
                 }
                 // Find the mapped property name
-                const mappedKey = registryItem.symlinks[sym];
-                if (mappedKey && instance && typeof instance === 'object') {
-                    instance[mappedKey] = value;
+                if (registryItem.symlinks) {
+                    const mappedKey = registryItem.symlinks[sym];
+                    if (mappedKey && instance && typeof instance === 'object') {
+                        instance[mappedKey] = value;
+                    }
                 }
             }
         }
@@ -370,7 +372,7 @@ export function assignGingerly(target, source, options) {
                                     const SpawnClass = registryItem.spawn;
                                     // Check canSpawn if it exists
                                     if (typeof SpawnClass.canSpawn === 'function') {
-                                        const ctx = { mountInfo: registryItem };
+                                        const ctx = { config: registryItem };
                                         if (!SpawnClass.canSpawn(target, ctx)) {
                                             // canSpawn returned false, skip spawning
                                             return true;
@@ -378,7 +380,7 @@ export function assignGingerly(target, source, options) {
                                     }
                                     // If target is an Element and registryItem has enhKey, pass element to constructor
                                     if (registryItem.enhKey && typeof Element !== 'undefined' && target instanceof Element) {
-                                        const ctx = { mountInfo: registryItem };
+                                        const ctx = { config: registryItem };
                                         const initVals = target.enh?.[registryItem.enhKey] &&
                                             !(target.enh[registryItem.enhKey] instanceof SpawnClass)
                                             ? target.enh[registryItem.enhKey]
@@ -397,9 +399,11 @@ export function assignGingerly(target, source, options) {
                                         target.enh[registryItem.enhKey] = instance;
                                     }
                                 }
-                                const mappedKey = registryItem.symlinks[prop];
-                                if (mappedKey && instance && typeof instance === 'object') {
-                                    instance[mappedKey] = value;
+                                if (registryItem.symlinks) {
+                                    const mappedKey = registryItem.symlinks[prop];
+                                    if (mappedKey && instance && typeof instance === 'object') {
+                                        instance[mappedKey] = value;
+                                    }
                                 }
                             }
                         }

package/assignGingerly.ts

@@ -1,22 +1,6 @@
-/**
- * Configuration for enhancing elements with class instances
- */
-export interface EnhancementConfig<T = any> {
-  spawn: { 
-    new (oElement?: Element, ctx?: SpawnContext<T>, initVals?: Partial<T>): T;
-    canSpawn?: (obj: any, ctx?: SpawnContext<T>) => boolean;
-  };
-  symlinks: { [key: string | symbol]: keyof T };
-  enhKey?: string;
-  lifecycleKeys?: {
-    dispose?: string;
-    resolved?: string;
-  };
-}
 
-export interface SpawnContext<T = any> {
-  mountInfo: EnhancementConfig<T>;
-}
+
+import { EnhancementConfig } from "./types";
 
 /**
  * @deprecated Use EnhancementConfig instead
@@ -379,7 +363,7 @@ export function assignGingerly(
           
           // Check canSpawn if it exists
           if (typeof SpawnClass.canSpawn === 'function') {
-            const ctx = { mountInfo: registryItem };
+            const ctx = { config: registryItem };
             if (!SpawnClass.canSpawn(target, ctx)) {
               // canSpawn returned false, skip spawning
               continue;
@@ -388,7 +372,7 @@ export function assignGingerly(
           
           // If target is an Element and registryItem has enhKey, pass element to constructor
           if (registryItem.enhKey && typeof Element !== 'undefined' && target instanceof Element) {
-            const ctx = { mountInfo: registryItem };
+            const ctx = { config: registryItem };
             const initVals = (target as any).enh?.[registryItem.enhKey] && 
                             !((target as any).enh[registryItem.enhKey] instanceof SpawnClass)
                             ? (target as any).enh[registryItem.enhKey]
@@ -411,10 +395,13 @@ export function assignGingerly(
         }
 
         // Find the mapped property name
-        const mappedKey = registryItem.symlinks[sym];
-        if (mappedKey && instance && typeof instance === 'object') {
-          (instance as any)[mappedKey] = value;
+        if(registryItem.symlinks){
+          const mappedKey = registryItem.symlinks[sym];
+          if (mappedKey && instance && typeof instance === 'object') {
+            (instance as any)[mappedKey] = value;
+          }
         }
+
       }
     }
   }
@@ -442,7 +429,7 @@ export function assignGingerly(
                     
                     // Check canSpawn if it exists
                     if (typeof SpawnClass.canSpawn === 'function') {
-                      const ctx = { mountInfo: registryItem };
+                      const ctx = { config: registryItem };
                       if (!SpawnClass.canSpawn(target, ctx)) {
                         // canSpawn returned false, skip spawning
                         return true;
@@ -451,7 +438,7 @@ export function assignGingerly(
                     
                     // If target is an Element and registryItem has enhKey, pass element to constructor
                     if (registryItem.enhKey && typeof Element !== 'undefined' && target instanceof Element) {
-                      const ctx = { mountInfo: registryItem };
+                      const ctx = { config: registryItem };
                       const initVals = (target as any).enh?.[registryItem.enhKey] && 
                                       !((target as any).enh[registryItem.enhKey] instanceof SpawnClass)
                                       ? (target as any).enh[registryItem.enhKey]
@@ -471,11 +458,13 @@ export function assignGingerly(
                       (target as any).enh[registryItem.enhKey] = instance;
                     }
                   }
-                  
-                  const mappedKey = registryItem.symlinks[prop];
-                  if (mappedKey && instance && typeof instance === 'object') {
-                    (instance as any)[mappedKey] = value;
+                  if(registryItem.symlinks){
+                    const mappedKey = registryItem.symlinks[prop];
+                    if (mappedKey && instance && typeof instance === 'object') {
+                      (instance as any)[mappedKey] = value;
+                    }
                   }
+
                 }
               }
               return true;

package/object-extension.js

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

package/object-extension.ts

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "assign-gingerly",
-  "version": "0.0.10",
+  "version": "0.0.12",
   "description": "This package provides a utility function for carefully merging one object into another.",
   "homepage": "https://github.com/bahrus/assign-gingerly#readme",
   "bugs": {

package/types.d.ts

@@ -121,8 +121,9 @@ export type AttrPatterns<T = any> = {
 };
 
 
-export interface SpawnContext<T = any> {
-  mountInfo: EnhancementConfig<T>;
+export interface SpawnContext<T = any, TMountContext = any> {
+  config: EnhancementConfig<T>;
+  mountCtx?: TMountContext;
 }
 
 /**