assign-gingerly 0.0.11 → 0.0.12

package/README.md

@@ -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> {
+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:**

package/assignGingerly.js

@@ -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;
+                    }
                 }
             }
         }
@@ -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> {
-  config: EnhancementConfig<T>;
-}
+
+import { EnhancementConfig } from "./types";
 
 /**
  * @deprecated Use EnhancementConfig instead
@@ -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;
+          }
         }
+
       }
     }
   }
@@ -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 = { config: 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 = { config: 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 = { config: 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;

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 = { config: 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 = { config: 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 = { config: 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]) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "assign-gingerly",
-  "version": "0.0.11",
+  "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> {
+export interface SpawnContext<T = any, TMountContext = any> {
   config: EnhancementConfig<T>;
+  mountCtx?: TMountContext;
 }
 
 /**