assign-gingerly 0.0.41 → 0.0.42

package/README.md

@@ -4723,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)) {
@@ -411,8 +412,18 @@ export function assignFeatures(ctr, features, featuresRegistry) {
         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);
@@ -420,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.
@@ -525,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

@@ -607,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;
 
@@ -617,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)) {
@@ -656,9 +658,20 @@ export function assignFeatures(
         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);
@@ -666,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;
 }
 
 /**
@@ -772,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;
     }
 }
 
@@ -793,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.41",
+  "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;