assign-gingerly 0.0.40 → 0.0.42

package/README.md

@@ -4617,13 +4617,24 @@ customElements.assignFeatures(MyBehaviors, { anything: { spawn: AnythingImpl } }
 
 ### Lifecycle callback forwarding with `callbackForwarding`
 
-Features can receive custom element lifecycle callbacks by declaring `callbackForwarding` in their config:
+Features can receive custom element lifecycle callbacks by declaring `callbackForwarding` in their config. This can be specified by the feature author (in `static supportedFeatures`) and/or by the consumer (in `assignFeatures`). Both are merged — the author declares what the feature intrinsically needs, the consumer can add more:
 
 ```JavaScript
+// Author declares what the feature needs
+class MyElement extends HTMLElement {
+    static supportedFeatures = {
+        reflector: {
+            fallbackSpawn: Reflector,
+            callbackForwarding: ['connectedCallback', 'disconnectedCallback']
+        }
+    }
+}
+
+// Consumer can add more (but not remove author's)
 customElements.assignFeatures(MyElement, {
     reflector: {
         spawn: Reflector,
-        callbackForwarding: ['connectedCallback', 'disconnectedCallback']
+        callbackForwarding: ['adoptedCallback'] // merged with author's
     }
 });
 ```
@@ -4712,6 +4723,62 @@ customElements.assignFeatures(MyElement, {
 
 **Note on `attributeChangedCallback`:** The feature only receives callbacks for attributes listed in the element's `static observedAttributes`. Features cannot add to this list after `define()` is called.
 
+### Class-level setup with `static onAssigned`
+
+Some features need one-time class-level setup before any instances are created — for example, installing prototype getter/setters or pre-loading modules. The `static onAssigned` method on the spawn class is called by `assignFeatures` immediately after registration:
+
+```JavaScript
+class RoundaboutFeature {
+    // Called once when assignFeatures processes this feature
+    static async onAssigned(ctr, featureConfig) {
+        // One-time class-level setup: install prototype getter/setters, pre-load modules
+        await makeRoundaboutReady(ctr, featureConfig.customData);
+    }
+
+    constructor(host, ctx, initVals) {
+        // Instance-level setup (runs on first getter access)
+        const [vm, propagator] = roundaboutSync({
+            vm: host,
+            ...ctx.injection.customData,
+        });
+        this._vm = vm;
+        this._propagator = propagator;
+    }
+}
+```
+
+**Usage:**
+
+```JavaScript
+// await is safe — returns undefined if no async onAssigned hooks exist
+await customElements.assignFeatures(MyElement, {
+    roundabout: {
+        spawn: RoundaboutFeature,
+        customData: raConfig
+    }
+});
+
+// Now define — class is fully set up, connectedCallback will be synchronous
+customElements.define('my-element', MyElement);
+```
+
+**How it works:**
+
+- `assignFeatures` checks if the spawn class defines `static onAssigned` (via `Object.hasOwn`).
+- If found, calls `SpawnClass.onAssigned(ctr, featureConfig)` after installing the getter.
+- If `onAssigned` returns a Promise, `assignFeatures` returns a `Promise<void>` that resolves when all async hooks complete.
+- If no `onAssigned` hooks are async (or none exist), `assignFeatures` returns `undefined` (backward compatible — existing code that doesn't `await` still works).
+- Only applies to synchronous spawners (the class must be available at registration time). Async spawners can't define `onAssigned` since the class isn't loaded yet.
+
+**`await` is always safe:**
+
+```JavaScript
+// These are equivalent for sync features (no onAssigned or sync onAssigned):
+customElements.assignFeatures(MyElement, { feature: { spawn: SyncFeature } });
+await customElements.assignFeatures(MyElement, { feature: { spawn: SyncFeature } });
+// Both work — await on undefined is a no-op
+```
+
 ### Roadmap (future phases)
 
 - **Nested features**: Support `?.path?.notation` keys directly in `assignFeatures` (without requiring `PropertyBag`).

package/assignFeatures.js

@@ -383,6 +383,7 @@ export function assignFeatures(ctr, features, featuresRegistry) {
     if (!supportedFeatures) {
         throw new Error(`assignFeatures: ${ctr.name || 'constructor'} does not define static supportedFeatures`);
     }
+    const onAssignedPromises = [];
     for (const key of Object.keys(features)) {
         // 1. Confirm the key is opted-in via supportedFeatures
         if (!(key in supportedFeatures)) {
@@ -401,13 +402,28 @@ export function assignFeatures(ctr, features, featuresRegistry) {
         featuresRegistry.set(ctr, key, features[key]);
         // 5. Install the lazy getter on the prototype
         installFeatureGetter(ctr, key, featuresRegistry);
-        // 6. Install callback forwarding if configured
+        // 6. Install callback forwarding if configured (merge author + consumer)
         const featureConfig = features[key];
-        if (featureConfig.callbackForwarding && featureConfig.callbackForwarding.length > 0) {
-            installCallbackForwarding(ctr, key, featureConfig.callbackForwarding);
+        const optIn = supportedFeatures[key];
+        const authorCallbacks = optIn.callbackForwarding || [];
+        const consumerCallbacks = featureConfig.callbackForwarding || [];
+        // Union of both (author defaults + consumer additions)
+        const allCallbacks = [...new Set([...authorCallbacks, ...consumerCallbacks])];
+        if (allCallbacks.length > 0) {
+            installCallbackForwarding(ctr, key, allCallbacks);
+        }
+        // 7. Call static onAssigned if the spawn class defines it
+        const SpawnClass = featureConfig.spawn;
+        if (SpawnClass && !isAsyncSpawn(SpawnClass) &&
+            Object.hasOwn(SpawnClass, 'onAssigned') &&
+            typeof SpawnClass.onAssigned === 'function') {
+            const result = SpawnClass.onAssigned(ctr, featureConfig);
+            if (result && typeof result.then === 'function') {
+                onAssignedPromises.push(result);
+            }
         }
     }
-    // 6. Install whenFeatureReady method if featuresConfig.lifecycleKeys is configured
+    // 8. Install whenFeatureReady method if featuresConfig.lifecycleKeys is configured
     const featuresConfig = ctr.featuresConfig;
     if (featuresConfig?.lifecycleKeys) {
         const methodName = resolveWhenFeatureReadyName(featuresConfig.lifecycleKeys);
@@ -415,6 +431,11 @@ export function assignFeatures(ctr, features, featuresRegistry) {
             installWhenFeatureReadyMethod(ctr, methodName);
         }
     }
+    // Return a Promise if any onAssigned hooks are async, otherwise undefined
+    if (onAssignedPromises.length > 0) {
+        return Promise.all(onAssignedPromises).then(() => { });
+    }
+    return undefined;
 }
 /**
  * Captures own-properties that shadow feature getters and stores them as initVals.
@@ -520,7 +541,7 @@ if (typeof CustomElementRegistry !== 'undefined') {
     });
     Object.defineProperty(CustomElementRegistry.prototype, 'assignFeatures', {
         value: function (ctr, features) {
-            assignFeatures(ctr, features, this.featuresRegistry);
+            return assignFeatures(ctr, features, this.featuresRegistry);
         },
         writable: true,
         enumerable: false,

package/assignFeatures.ts

@@ -65,6 +65,16 @@ export interface SupportedFeatureConfig {
      * }
      */
     getSharedContext?: (instance: any) => any;
+
+    /**
+     * Lifecycle callbacks that this feature requires.
+     * Serves as the default — the consumer can add more via FeatureConfig.callbackForwarding
+     * but cannot remove these.
+     * 
+     * Supported: 'connectedCallback', 'disconnectedCallback',
+     *            'attributeChangedCallback', 'adoptedCallback'
+     */
+    callbackForwarding?: string[];
 }
 
 /**
@@ -597,7 +607,7 @@ export function assignFeatures(
     ctr: Function,
     features: FeatureConfigsMap,
     featuresRegistry: FeaturesRegistry
-): void {
+): Promise<void> | undefined {
     // Validate that the constructor has static supportedFeatures
     const supportedFeatures: SupportedFeaturesMap | undefined = (ctr as any).supportedFeatures;
 
@@ -607,6 +617,8 @@ export function assignFeatures(
         );
     }
 
+    const onAssignedPromises: Promise<void>[] = [];
+
     for (const key of Object.keys(features)) {
         // 1. Confirm the key is opted-in via supportedFeatures
         if (!(key in supportedFeatures)) {
@@ -636,14 +648,30 @@ export function assignFeatures(
         // 5. Install the lazy getter on the prototype
         installFeatureGetter(ctr, key, featuresRegistry);
 
-        // 6. Install callback forwarding if configured
+        // 6. Install callback forwarding if configured (merge author + consumer)
         const featureConfig = features[key];
-        if (featureConfig.callbackForwarding && featureConfig.callbackForwarding.length > 0) {
-            installCallbackForwarding(ctr, key, featureConfig.callbackForwarding);
+        const optIn = supportedFeatures[key];
+        const authorCallbacks = optIn.callbackForwarding || [];
+        const consumerCallbacks = featureConfig.callbackForwarding || [];
+        // Union of both (author defaults + consumer additions)
+        const allCallbacks = [...new Set([...authorCallbacks, ...consumerCallbacks])];
+        if (allCallbacks.length > 0) {
+            installCallbackForwarding(ctr, key, allCallbacks);
+        }
+
+        // 7. Call static onAssigned if the spawn class defines it
+        const SpawnClass = featureConfig.spawn;
+        if (SpawnClass && !isAsyncSpawn(SpawnClass) && 
+            Object.hasOwn(SpawnClass as any, 'onAssigned') && 
+            typeof (SpawnClass as any).onAssigned === 'function') {
+            const result = (SpawnClass as any).onAssigned(ctr, featureConfig);
+            if (result && typeof result.then === 'function') {
+                onAssignedPromises.push(result);
+            }
         }
     }
 
-    // 6. Install whenFeatureReady method if featuresConfig.lifecycleKeys is configured
+    // 8. Install whenFeatureReady method if featuresConfig.lifecycleKeys is configured
     const featuresConfig: FeaturesClassConfig | undefined = (ctr as any).featuresConfig;
     if (featuresConfig?.lifecycleKeys) {
         const methodName = resolveWhenFeatureReadyName(featuresConfig.lifecycleKeys);
@@ -651,6 +679,12 @@ export function assignFeatures(
             installWhenFeatureReadyMethod(ctr, methodName);
         }
     }
+
+    // Return a Promise if any onAssigned hooks are async, otherwise undefined
+    if (onAssignedPromises.length > 0) {
+        return Promise.all(onAssignedPromises).then(() => {});
+    }
+    return undefined;
 }
 
 /**
@@ -757,7 +791,7 @@ export class PropertyBag {
 declare global {
     interface CustomElementRegistry {
         featuresRegistry: FeaturesRegistry;
-        assignFeatures(ctr: Function, features: FeatureConfigsMap): void;
+        assignFeatures(ctr: Function, features: FeatureConfigsMap): Promise<void> | undefined;
     }
 }
 
@@ -778,8 +812,8 @@ if (typeof CustomElementRegistry !== 'undefined') {
     });
 
     Object.defineProperty(CustomElementRegistry.prototype, 'assignFeatures', {
-        value: function (ctr: Function, features: FeatureConfigsMap): void {
-            assignFeatures(ctr, features, this.featuresRegistry);
+        value: function (ctr: Function, features: FeatureConfigsMap): Promise<void> | undefined {
+            return assignFeatures(ctr, features, this.featuresRegistry);
         },
         writable: true,
         enumerable: false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "assign-gingerly",
-  "version": "0.0.40",
+  "version": "0.0.42",
   "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/assign-gingerly/types.d.ts

@@ -459,4 +459,4 @@ export declare function assignFeatures(
   ctr: Function,
   features: FeatureConfigsMap,
   featuresRegistry: FeaturesRegistry
-): void;
+): Promise<void> | undefined;