assign-gingerly 0.0.73 → 0.0.75

package/processHandlerCommands.ts

@@ -7,7 +7,7 @@
 import { resolveValues } from './resolveValues.js';
 import { getValues } from './getValues.js';
 import { evaluatePathWithMethods } from './assignGingerly.js';
-import { isAllowedImportPath } from './assignPermissions/isAllowedImportPath.js';
+import { findClassPrototypeInPath } from './utils/findClassPrototypeInPath.js';
 import { buildRestrictedPropSet, redirectRestrictedProp } from './assignPermissions/restrictedProps.js';
 import type { AssignPermissions } from './types/assign-gingerly/types.js';
 import type { AssignFromOptions, AssignFromHandlerConstructor } from './assignFromAsync.js';
@@ -26,23 +26,11 @@ const BUILT_IN_MAP: Record<string, string> = {
 };
 
 /**
- * Find a handler class in a dynamically imported module.
- * Checks default export first, then searches for the first class with `assign` on prototype.
+ * Criteria for locating an assignFrom handler class: must expose an `assign` method
+ * on its prototype.
  */
-function findHandlerInModule(module: any): AssignFromHandlerConstructor | undefined {
-    // Check default export first
-    if (module.default && typeof module.default === 'function'
-        && module.default.prototype && 'assign' in module.default.prototype) {
-        return module.default;
-    }
-    // Search other exports
-    for (const key of Object.keys(module)) {
-        const exported = module[key];
-        if (typeof exported === 'function' && exported.prototype && 'assign' in exported.prototype) {
-            return exported as AssignFromHandlerConstructor;
-        }
-    }
-    return undefined;
+function handlerCriteria(proto: any): boolean {
+    return 'assign' in proto.prototype;
 }
 
 /**
@@ -60,10 +48,9 @@ async function loadBuiltIn(name: string): Promise<AssignFromHandlerConstructor |
     if (cached) return cached;
     const path = BUILT_IN_MAP[name];
     if (!path) return undefined;
-    const module = await import(path);
-    const cls = findHandlerInModule(module);
-    if (cls) handlerCache.set(name, cls);
-    return cls;
+    const cls = await findClassPrototypeInPath(path, handlerCriteria);
+    handlerCache.set(name, cls);
+    return cls as AssignFromHandlerConstructor;
 }
 
 /**
@@ -71,8 +58,7 @@ async function loadBuiltIn(name: string): Promise<AssignFromHandlerConstructor |
  */
 async function resolveFromHandlers(
     name: string,
-    handlers: Record<string, AssignFromHandlerConstructor | string> | undefined,
-    permissions?: AssignPermissions
+    handlers: Record<string, AssignFromHandlerConstructor | string> | undefined
 ): Promise<AssignFromHandlerConstructor | undefined> {
     if (!handlers || !(name in handlers)) return undefined;
 
@@ -90,22 +76,9 @@ async function resolveFromHandlers(
             return loadBuiltIn(entry);
         }
 
-        // Import path string — validate and dynamically import
-        if (!permissions?.crossDomainImports && !isAllowedImportPath(entry)) {
-            throw new Error(
-                `assignFrom: handler "${name}" has an invalid import path "${entry}". ` +
-                `Only same-origin paths or import-map-covered specifiers are allowed. ` +
-                `Pass { crossDomainImports: true } in permissions to override.`
-            );
-        }
-        const module = await import(entry);
-        const HandlerClass = findHandlerInModule(module);
-        if (!HandlerClass) {
-            throw new Error(
-                `assignFrom: handler "${name}" — module "${entry}" does not export a valid handler class.`
-            );
-        }
-        return HandlerClass;
+        // Import path string — validate and extract handler class via shared utility
+        const HandlerClass = await findClassPrototypeInPath(entry, handlerCriteria);
+        return HandlerClass as AssignFromHandlerConstructor;
     }
 
     return undefined;
@@ -204,7 +177,7 @@ export async function processHandlerCommands(
         for (const config of configs) {
             //return; //1.3ms
             // 1. Check options.handlers (local, per-call)
-            let HandlerClass = await resolveFromHandlers(config.do, options.handlers, permissions);
+            let HandlerClass = await resolveFromHandlers(config.do, options.handlers);
             //return; // 1.4
             // 2. Fallback to built-in auto-load
             if (!HandlerClass && config.do.startsWith('builtIns.')) {

package/resolveAndAssignFeatures.js

@@ -1,12 +1,12 @@
 /**
- * resolveAndAssignFeatures - Resolves async fallback spawns then calls assignFeatures.
+ * resolveAndAssignFeatures - Thin wrapper around assignFeatures for backward compatibility.
  *
- * For each feature in the config that doesn't have an explicit `spawn`, resolves
- * the async `fallbackSpawn` from the class's `static supportedFeatures` and sets
- * it as the spawn. Then calls `assignFeatures` with the fully resolved config.
+ * Resolves all configured spawns (including async fallback spawns and string import paths)
+ * and installs feature getters on the class prototype, then delegates to the registry's
+ * assignFeatures implementation.
  *
- * This eliminates the boilerplate of manually resolving async spawns before
- * calling assignFeatures.
+ * This is kept as a convenience entry point for callers that already await this function.
+ * The actual resolution logic lives in assignFeatures.
  *
  * @example
  * import { resolveAndAssignFeatures } from 'assign-gingerly/resolveAndAssignFeatures.js';
@@ -22,46 +22,15 @@
  *     }
  * });
  */
+import { assignFeatures } from './assignFeatures.js';
 /**
- * Determines if a function is an async spawner.
- */
-function isAsyncSpawn(fn) {
-    if (typeof fn !== 'function')
-        return false;
-    if (fn.constructor.name === 'AsyncFunction')
-        return true;
-    if (fn.prototype === undefined)
-        return true;
-    return false;
-}
-/**
- * Resolves async fallback spawns for features that don't have an explicit spawn,
- * then calls assignFeatures on the registry.
+ * Resolves all configured spawns and calls assignFeatures on the registry.
  *
  * @param ElementClass - The custom element class (must have static supportedFeatures)
  * @param featuresConfig - Feature configurations (spawn will be resolved from fallbackSpawn if missing)
  * @param registry - Optional CustomElementRegistry (defaults to global customElements)
  */
 export async function resolveAndAssignFeatures(ElementClass, featuresConfig, registry) {
-    const supportedFeatures = ElementClass.supportedFeatures;
-    if (!supportedFeatures) {
-        throw new Error(`resolveAndAssignFeatures: ${ElementClass.name || 'constructor'} does not define static supportedFeatures`);
-    }
-    // Resolve async fallback spawns in parallel for features without explicit spawn
-    await Promise.all(Object.entries(featuresConfig).map(async ([key, featureConfig]) => {
-        // Skip if spawn is already provided
-        if (featureConfig.spawn)
-            return;
-        const optIn = supportedFeatures[key];
-        if (!optIn?.fallbackSpawn)
-            return;
-        let spawn = optIn.fallbackSpawn;
-        if (isAsyncSpawn(spawn)) {
-            spawn = await spawn();
-        }
-        featureConfig.spawn = spawn;
-    }));
-    // Call assignFeatures on the registry
     const reg = registry || customElements;
-    await reg.assignFeatures(ElementClass, featuresConfig);
+    await assignFeatures(ElementClass, featuresConfig, reg.featuresRegistry);
 }

package/resolveAndAssignFeatures.ts

@@ -1,79 +1,43 @@
-/**
- * resolveAndAssignFeatures - Resolves async fallback spawns then calls assignFeatures.
- * 
- * For each feature in the config that doesn't have an explicit `spawn`, resolves
- * the async `fallbackSpawn` from the class's `static supportedFeatures` and sets
- * it as the spawn. Then calls `assignFeatures` with the fully resolved config.
- * 
- * This eliminates the boilerplate of manually resolving async spawns before
- * calling assignFeatures.
- * 
- * @example
- * import { resolveAndAssignFeatures } from 'assign-gingerly/resolveAndAssignFeatures.js';
- * 
- * await resolveAndAssignFeatures(MyElement, {
- *     roundabout: {
- *         customData: {...},
- *         withAttrs: {...},
- *         callbackForwarding: ['connectedCallback']
- *     },
- *     faceUp: {
- *         callbackForwarding: ['connectedCallback', 'disconnectedCallback']
- *     }
- * });
- */
-
-import { FeatureConfigsMap, SupportedFeaturesMap } from './types/assign-gingerly/types.js';
-
-/**
- * Determines if a function is an async spawner.
- */
-function isAsyncSpawn(fn: any): boolean {
-    if (typeof fn !== 'function') return false;
-    if (fn.constructor.name === 'AsyncFunction') return true;
-    if (fn.prototype === undefined) return true;
-    return false;
-}
-
-/**
- * Resolves async fallback spawns for features that don't have an explicit spawn,
- * then calls assignFeatures on the registry.
- * 
- * @param ElementClass - The custom element class (must have static supportedFeatures)
- * @param featuresConfig - Feature configurations (spawn will be resolved from fallbackSpawn if missing)
- * @param registry - Optional CustomElementRegistry (defaults to global customElements)
- */
-export async function resolveAndAssignFeatures(
-    ElementClass: Function,
-    featuresConfig: FeatureConfigsMap,
-    registry?: any
-): Promise<void> {
-    const supportedFeatures: SupportedFeaturesMap | undefined = (ElementClass as any).supportedFeatures;
-
-    if (!supportedFeatures) {
-        throw new Error(
-            `resolveAndAssignFeatures: ${(ElementClass as any).name || 'constructor'} does not define static supportedFeatures`
-        );
-    }
-
-    // Resolve async fallback spawns in parallel for features without explicit spawn
-    await Promise.all(
-        Object.entries(featuresConfig).map(async ([key, featureConfig]) => {
-            // Skip if spawn is already provided
-            if (featureConfig.spawn) return;
-
-            const optIn = supportedFeatures[key];
-            if (!optIn?.fallbackSpawn) return;
-
-            let spawn = optIn.fallbackSpawn;
-            if (isAsyncSpawn(spawn)) {
-                spawn = await (spawn as () => Promise<any>)();
-            }
-            (featureConfig as any).spawn = spawn;
-        })
-    );
-
-    // Call assignFeatures on the registry
-    const reg = registry || customElements;
-    await reg.assignFeatures(ElementClass, featuresConfig);
-}
+/**
+ * resolveAndAssignFeatures - Thin wrapper around assignFeatures for backward compatibility.
+ *
+ * Resolves all configured spawns (including async fallback spawns and string import paths)
+ * and installs feature getters on the class prototype, then delegates to the registry's
+ * assignFeatures implementation.
+ *
+ * This is kept as a convenience entry point for callers that already await this function.
+ * The actual resolution logic lives in assignFeatures.
+ *
+ * @example
+ * import { resolveAndAssignFeatures } from 'assign-gingerly/resolveAndAssignFeatures.js';
+ *
+ * await resolveAndAssignFeatures(MyElement, {
+ *     roundabout: {
+ *         customData: {...},
+ *         withAttrs: {...},
+ *         callbackForwarding: ['connectedCallback']
+ *     },
+ *     faceUp: {
+ *         callbackForwarding: ['connectedCallback', 'disconnectedCallback']
+ *     }
+ * });
+ */
+
+import { FeatureConfigsMap } from './types/assign-gingerly/types.js';
+import { assignFeatures } from './assignFeatures.js';
+
+/**
+ * Resolves all configured spawns and calls assignFeatures on the registry.
+ *
+ * @param ElementClass - The custom element class (must have static supportedFeatures)
+ * @param featuresConfig - Feature configurations (spawn will be resolved from fallbackSpawn if missing)
+ * @param registry - Optional CustomElementRegistry (defaults to global customElements)
+ */
+export async function resolveAndAssignFeatures(
+    ElementClass: Function,
+    featuresConfig: FeatureConfigsMap,
+    registry?: any
+): Promise<void> {
+    const reg = registry || customElements;
+    await assignFeatures(ElementClass, featuresConfig, reg.featuresRegistry);
+}

package/types/assign-gingerly/types.d.ts

@@ -591,21 +591,6 @@ export interface SupportedFeatureConfig {
     callbackForwarding?: string[];
 }
 
-/**
- * Class-level configuration for the features system.
- * Declared as `static featuresConfig` on the class.
- */
-export interface FeaturesClassConfig {
-    /**
-     * Lifecycle method configuration.
-     * true = install 'whenFeatureReady' method.
-     * Object = custom method name.
-     */
-    lifecycleKeys?: true | {
-        whenFeatureReady?: string;
-    };
-}
-
 /**
  * Configuration for a feature passed to assignFeatures.
  */
@@ -615,7 +600,8 @@ export interface FeatureConfig {
      */
     spawn?:
         | { new(hostElement: any, ctx: FeatureSpawnContext, initVals?: any): any }
-        | (() => Promise<{ new(hostElement: any, ctx: FeatureSpawnContext, initVals?: any): any }>);
+        | (() => Promise<{ new(hostElement: any, ctx: FeatureSpawnContext, initVals?: any): any }>)
+        | string // import path or builtIns.* alias
 
     /** Attribute patterns for parsing element attributes into initVals. */
     withAttrs?: AttrPatterns<any>;

package/utils/findClassPrototypeInPath.js

@@ -0,0 +1,57 @@
+import { isAllowedImportPath } from '../assignPermissions/isAllowedImportPath.js';
+/**
+ * Thrown when a dynamic import path is not covered by the allowed-import policy.
+ */
+export class ImportNotAllowedError extends Error {
+    path;
+    constructor(path) {
+        super(`Import path "${path}" is not allowed.`);
+        this.path = path;
+        this.name = 'ImportNotAllowedError';
+        console.error(`ImportNotAllowedError: ${path}`);
+    }
+}
+/**
+ * Thrown when a module does not export a class that satisfies the required criteria.
+ */
+export class NoMatchingExportError extends Error {
+    path;
+    constructor(path) {
+        super(`Module "${path}" does not export a matching class with a prototype.`);
+        this.path = path;
+        this.name = 'NoMatchingExportError';
+        console.error(`NoMatchingExportError: ${path}`);
+    }
+}
+/**
+ * Base check: value must be a function with a prototype (i.e., a class constructor).
+ */
+function isClassWithPrototype(value) {
+    return typeof value === 'function' && value.prototype !== undefined;
+}
+/**
+ * Dynamically import a module at the given path, validate the path against the
+ * allowed-import policy, and return the first exported class whose prototype passes
+ * the optional criteria check.
+ *
+ * The default export is checked first. If it does not satisfy the checks, all named
+ * exports are scanned. If no matching class is found, a `NoMatchingExportError` is thrown.
+ */
+export async function findClassPrototypeInPath(path, criteria) {
+    if (!isAllowedImportPath(path)) {
+        throw new ImportNotAllowedError(path);
+    }
+    const module = await import(path);
+    const candidates = [
+        module.default,
+        ...Object.values(module).filter((exported) => exported !== module.default),
+    ];
+    for (const exported of candidates) {
+        if (!isClassWithPrototype(exported))
+            continue;
+        if (criteria && !criteria(exported))
+            continue;
+        return exported;
+    }
+    throw new NoMatchingExportError(path);
+}

package/utils/findClassPrototypeInPath.ts

@@ -0,0 +1,62 @@
+import { isAllowedImportPath } from '../assignPermissions/isAllowedImportPath.js';
+
+/**
+ * Thrown when a dynamic import path is not covered by the allowed-import policy.
+ */
+export class ImportNotAllowedError extends Error {
+    constructor(public readonly path: string) {
+        super(`Import path "${path}" is not allowed.`);
+        this.name = 'ImportNotAllowedError';
+        console.error(`ImportNotAllowedError: ${path}`);
+    }
+}
+
+/**
+ * Thrown when a module does not export a class that satisfies the required criteria.
+ */
+export class NoMatchingExportError extends Error {
+    constructor(public readonly path: string) {
+        super(`Module "${path}" does not export a matching class with a prototype.`);
+        this.name = 'NoMatchingExportError';
+        console.error(`NoMatchingExportError: ${path}`);
+    }
+}
+
+/**
+ * Base check: value must be a function with a prototype (i.e., a class constructor).
+ */
+function isClassWithPrototype(value: any): boolean {
+    return typeof value === 'function' && value.prototype !== undefined;
+}
+
+/**
+ * Dynamically import a module at the given path, validate the path against the
+ * allowed-import policy, and return the first exported class whose prototype passes
+ * the optional criteria check.
+ *
+ * The default export is checked first. If it does not satisfy the checks, all named
+ * exports are scanned. If no matching class is found, a `NoMatchingExportError` is thrown.
+ */
+export async function findClassPrototypeInPath<T = any>(
+    path: string,
+    criteria?: (proto: any) => boolean
+): Promise<{ new(): T }> {
+    if (!isAllowedImportPath(path)) {
+        throw new ImportNotAllowedError(path);
+    }
+
+    const module = await import(path);
+
+    const candidates = [
+        module.default,
+        ...Object.values(module).filter((exported: any) => exported !== module.default),
+    ];
+
+    for (const exported of candidates) {
+        if (!isClassWithPrototype(exported)) continue;
+        if (criteria && !criteria(exported)) continue;
+        return exported as { new(): T };
+    }
+
+    throw new NoMatchingExportError(path);
+}

package/utils/isAsyncSpawn.js

@@ -0,0 +1,20 @@
+/**
+ * Determines if a function is an async spawner (returns a Promise<Constructor>)
+ * rather than a synchronous constructor.
+ *
+ * Heuristic:
+ * - AsyncFunction (async () => ...) → async spawner
+ * - Arrow function (no .prototype) → async spawner (assumed to return Promise<Constructor>)
+ * - Class or function declaration (has .prototype) → synchronous constructor
+ */
+export function isAsyncSpawn(fn) {
+    if (typeof fn !== 'function')
+        return false;
+    // Explicit async function
+    if (fn.constructor.name === 'AsyncFunction')
+        return true;
+    // Arrow function or non-constructor function (no .prototype)
+    if (fn.prototype === undefined)
+        return true;
+    return false;
+}

package/utils/isAsyncSpawn.ts

@@ -0,0 +1,17 @@
+/**
+ * Determines if a function is an async spawner (returns a Promise<Constructor>)
+ * rather than a synchronous constructor.
+ *
+ * Heuristic:
+ * - AsyncFunction (async () => ...) → async spawner
+ * - Arrow function (no .prototype) → async spawner (assumed to return Promise<Constructor>)
+ * - Class or function declaration (has .prototype) → synchronous constructor
+ */
+export function isAsyncSpawn(fn: any): boolean {
+    if (typeof fn !== 'function') return false;
+    // Explicit async function
+    if (fn.constructor.name === 'AsyncFunction') return true;
+    // Arrow function or non-constructor function (no .prototype)
+    if (fn.prototype === undefined) return true;
+    return false;
+}