assign-gingerly 0.0.38 → 0.0.39

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "assign-gingerly",
-  "version": "0.0.38",
+  "version": "0.0.39",
   "description": "This package provides a utility function for carefully merging one object into another.",
   "homepage": "https://github.com/bahrus/assign-gingerly#readme",
   "bugs": {
@@ -60,9 +60,21 @@
       "default": "./resolveValues.js",
       "types": "./resolveValues.ts"
     },
+    "./installForwarding.js": {
+      "default": "./installForwarding.js",
+      "types": "./installForwarding.ts"
+    },
     "./assignFrom.js": {
       "default": "./assignFrom.js",
       "types": "./assignFrom.ts"
+    },
+    "./assignFeatures.js": {
+      "default": "./assignFeatures.js",
+      "types": "./assignFeatures.ts"
+    },
+    "./evaluatePathWithAsyncMethods.js": {
+      "default": "./evaluatePathWithAsyncMethods.js",
+      "types": "./evaluatePathWithAsyncMethods.ts"
     }
   },
   "main": "index.js",
@@ -77,7 +89,7 @@
   "devDependencies": {
     "@playwright/test": "1.59.1",
     "spa-ssi": "0.0.27",
-    "@types/node": "25.6.0",
+    "@types/node": "25.6.2",
     "typescript": "6.0.3"
   }
 }

package/resolveValues.js

@@ -9,6 +9,22 @@ function applyAliases(path, aliasMap) {
     const substituted = parts.map(part => aliasMap.get(part) ?? part);
     return substituted.join('?.');
 }
+/**
+ * Path cache for parsed path strings.
+ * Avoids re-splitting the same path on repeated calls.
+ */
+const pathCache = new Map();
+/**
+ * Parse a `?.`-delimited path string into segments, with caching.
+ */
+function parseCachedPath(path) {
+    let parts = pathCache.get(path);
+    if (!parts) {
+        parts = path.split('?.').filter(p => p.length > 0);
+        pathCache.set(path, parts);
+    }
+    return parts;
+}
 /**
  * Navigate a path against a source object, optionally calling methods.
  * Returns the resolved value at the end of the path.
@@ -99,8 +115,8 @@ export function resolveValues(pattern, source, options) {
         if (typeof value === 'string' && value.startsWith('?.')) {
             // Apply aliases to the RHS path
             const aliased = applyAliases(value, aliasMap);
-            // Parse path: split on '?.' delimiter, filter empties
-            const parts = aliased.split('?.').filter(p => p.length > 0);
+            // Parse path with caching
+            const parts = parseCachedPath(aliased);
             // Navigate with method support
             result[key] = parts.length === 0 ? source : navigatePath(source, parts, withMethods);
         }
@@ -110,3 +126,47 @@ export function resolveValues(pattern, source, options) {
     }
     return result;
 }
+/**
+ * Resolve a single `?.`-delimited path string against a source object.
+ *
+ * This is a lighter-weight alternative to `resolveValues` when you only need
+ * to resolve one path and don't want the overhead of creating wrapper objects.
+ *
+ * @param path - A `?.`-delimited path string (e.g., '?.behaviors?.command')
+ * @param source - Object to resolve the path against
+ * @param options - Optional withMethods and aka for method calls and aliases
+ * @returns The resolved value, or undefined if any segment is nullish
+ *
+ * @example
+ * const value = resolveValue('?.behaviors?.commandBehavior?.command', el);
+ *
+ * @example
+ * const value = resolveValue('?.q?.myEl?.textContent', el, {
+ *   withMethods: ['querySelector'],
+ *   aka: { 'q': 'querySelector' }
+ * });
+ */
+export function resolveValue(path, source, options) {
+    if (!path.startsWith('?.'))
+        return path;
+    // Build alias map
+    let aliased = path;
+    if (options?.aka) {
+        const aliasMap = new Map();
+        for (const [alias, target] of Object.entries(options.aka)) {
+            aliasMap.set(alias, target);
+        }
+        aliased = applyAliases(path, aliasMap);
+    }
+    // Parse path with caching
+    const parts = parseCachedPath(aliased);
+    if (parts.length === 0)
+        return source;
+    // Build methods set
+    const withMethods = options?.withMethods
+        ? options.withMethods instanceof Set
+            ? options.withMethods
+            : new Set(options.withMethods)
+        : undefined;
+    return navigatePath(source, parts, withMethods);
+}

package/resolveValues.ts

@@ -26,6 +26,24 @@ function applyAliases(path: string, aliasMap: Map<string, string>): string {
   return substituted.join('?.');
 }
 
+/**
+ * Path cache for parsed path strings.
+ * Avoids re-splitting the same path on repeated calls.
+ */
+const pathCache = new Map<string, string[]>();
+
+/**
+ * Parse a `?.`-delimited path string into segments, with caching.
+ */
+function parseCachedPath(path: string): string[] {
+    let parts = pathCache.get(path);
+    if (!parts) {
+        parts = path.split('?.').filter(p => p.length > 0);
+        pathCache.set(path, parts);
+    }
+    return parts;
+}
+
 /**
  * Navigate a path against a source object, optionally calling methods.
  * Returns the resolved value at the end of the path.
@@ -128,8 +146,8 @@ export function resolveValues(
       // Apply aliases to the RHS path
       const aliased = applyAliases(value, aliasMap);
       
-      // Parse path: split on '?.' delimiter, filter empties
-      const parts = aliased.split('?.').filter(p => p.length > 0);
+      // Parse path with caching
+      const parts = parseCachedPath(aliased);
       
       // Navigate with method support
       result[key] = parts.length === 0 ? source : navigatePath(source, parts, withMethods);
@@ -139,3 +157,54 @@ export function resolveValues(
   }
   return result;
 }
+
+/**
+ * Resolve a single `?.`-delimited path string against a source object.
+ * 
+ * This is a lighter-weight alternative to `resolveValues` when you only need
+ * to resolve one path and don't want the overhead of creating wrapper objects.
+ * 
+ * @param path - A `?.`-delimited path string (e.g., '?.behaviors?.command')
+ * @param source - Object to resolve the path against
+ * @param options - Optional withMethods and aka for method calls and aliases
+ * @returns The resolved value, or undefined if any segment is nullish
+ * 
+ * @example
+ * const value = resolveValue('?.behaviors?.commandBehavior?.command', el);
+ * 
+ * @example
+ * const value = resolveValue('?.q?.myEl?.textContent', el, {
+ *   withMethods: ['querySelector'],
+ *   aka: { 'q': 'querySelector' }
+ * });
+ */
+export function resolveValue(
+  path: string,
+  source: any,
+  options?: ResolveValuesOptions
+): any {
+  if (!path.startsWith('?.')) return path;
+
+  // Build alias map
+  let aliased = path;
+  if (options?.aka) {
+    const aliasMap = new Map<string, string>();
+    for (const [alias, target] of Object.entries(options.aka)) {
+      aliasMap.set(alias, target);
+    }
+    aliased = applyAliases(path, aliasMap);
+  }
+
+  // Parse path with caching
+  const parts = parseCachedPath(aliased);
+  if (parts.length === 0) return source;
+
+  // Build methods set
+  const withMethods = options?.withMethods
+    ? options.withMethods instanceof Set
+      ? options.withMethods
+      : new Set(options.withMethods)
+    : undefined;
+
+  return navigatePath(source, parts, withMethods);
+}

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

@@ -241,6 +241,18 @@ export interface IAssignGingerlyOptions {
    * When the signal is aborted, all event listeners are automatically removed
    */
   signal?: AbortSignal;
+
+  /**
+   * List of property names that should be treated as async methods.
+   * Works together with withMethods — async methods are awaited before
+   * continuing the chain.
+   * 
+   * The path evaluation for keys containing async methods is fire-and-forget:
+   * assignGingerly remains synchronous and returns immediately.
+   * 
+   * NOTE: Interaction with @each and @eachTime is not yet implemented.
+   */
+  withAsyncMethods?: string[] | Set<string>;
 }
 
 /**
@@ -321,3 +333,130 @@ export interface ElementEnhancement{
   dispose(registryItem: EnhancementConfig | string | symbol): void;
   whenResolved(registryItem: EnhancementConfig | string | symbol, mountCtx?: any): Promise<any>;
 }
+
+/**
+ * Context passed to feature spawn constructors
+ */
+export interface FeatureSpawnContext {
+  /** The feature key (e.g., 'photoTaker') */
+  key: string;
+  /** The SupportedFeatureConfig from static supportedFeatures */
+  optIn: SupportedFeatureConfig;
+  /** The FeatureConfig from assignFeatures */
+  injection: FeatureConfig;
+  /** The features registry reference */
+  featuresRegistry: FeaturesRegistry;
+  /** Shared context from the host element (via getSharedContext callback) */
+  shared?: any;
+}
+
+/**
+ * Configuration for a supported feature slot declared via static supportedFeatures
+ */
+export interface SupportedFeatureConfig {
+  /**
+   * Optional fallback class (or async spawner) to use if no implementation is injected.
+   */
+  fallbackSpawn?: 
+    | { new(hostElement: any, ctx: FeatureSpawnContext, initVals?: any): any }
+    | (() => Promise<{ new(hostElement: any, ctx: FeatureSpawnContext, initVals?: any): any }>);
+
+  /**
+   * Optional runtime shape validation for the spawned instance.
+   * Return true if the instance is valid, false to throw.
+   */
+  validateShape?: (spawnedInstance: any) => boolean;
+
+  /**
+   * Optional callback to provide shared context (e.g., ElementInternals, private state)
+   * to the feature at construction time.
+   * 
+   * Defined in the class body, this callback has access to #private fields.
+   * The returned object is passed to the feature constructor as `ctx.shared`.
+   * 
+   * @param instance - The host element instance
+   * @returns An object containing shared data for the feature
+   */
+  getSharedContext?: (instance: any) => any;
+}
+
+/**
+ * Class-level configuration for the features system.
+ * Declared as `static featuresConfig` on the class.
+ */
+export interface FeaturesClassConfig {
+  /**
+   * Lifecycle method configuration.
+   * 
+   * If set to `true`, installs a method named 'whenFeatureReady' on the prototype.
+   * If set to an object, allows customizing the method name.
+   * 
+   * The installed method accepts a feature key and returns a Promise that resolves
+   * with the feature instance once it's ready (useful for async spawners).
+   * For synchronous spawners, the Promise resolves immediately.
+   * 
+   * Suggested default name: 'whenFeatureReady'
+   */
+  lifecycleKeys?: true | {
+    /** Method name for awaiting feature readiness. Defaults to 'whenFeatureReady'. */
+    whenFeatureReady?: string;
+  };
+}
+
+/**
+ * Configuration for a feature passed to assignFeatures.
+ * The feature equivalent of EnhancementConfig.
+ */
+export interface FeatureConfig {
+  /**
+   * The class to instantiate for this feature, or an async function that
+   * resolves to such a class (for lazy-loading).
+   * 
+   * Synchronous: Constructor receives the host element as its first argument,
+   * a FeatureSpawnContext as second, and optional initVals as third.
+   * 
+   * Asynchronous: A function (arrow or async) that returns a Promise resolving
+   * to a constructor. The getter returns a placeholder object immediately and
+   * instantiates the real class once the Promise resolves.
+   */
+  spawn?: 
+    | { new(hostElement: any, ctx: FeatureSpawnContext, initVals?: any): any }
+    | (() => Promise<{ new(hostElement: any, ctx: FeatureSpawnContext, initVals?: any): any }>);
+
+  /**
+   * Attribute patterns for parsing element attributes into initVals.
+   * Attributes are the "base layer" — programmatic values override them.
+   * Always unprefixed for features (no enh- prefix).
+   */
+  withAttrs?: AttrPatterns<any>;
+
+  /**
+   * Reserved field for custom configuration data.
+   * Not interpreted by the library — available to the feature class
+   * via ctx.injection.customData in the constructor.
+   */
+  customData?: any;
+}
+
+export type SupportedFeaturesMap = Record<string, SupportedFeatureConfig>;
+export type FeatureConfigsMap = Record<string, FeatureConfig>;
+
+/**
+ * Registry for feature configs, keyed by constructor
+ */
+export declare class FeaturesRegistry {
+  has(ctr: Function): boolean;
+  get(ctr: Function): Map<string, FeatureConfig> | undefined;
+  set(ctr: Function, key: string, config: FeatureConfig): void;
+  hasKey(ctr: Function, key: string): boolean;
+}
+
+/**
+ * Core assignFeatures function.
+ * Validates inputs, registers feature configs, and installs lazy getters on the class prototype.
+ */
+export declare function assignFeatures(
+  ctr: Function,
+  features: FeatureConfigsMap,
+  featuresRegistry: FeaturesRegistry
+): void;