assign-gingerly 0.0.50 → 0.0.52

package/README.md

@@ -3366,6 +3366,65 @@ assignFrom(target, {
 
 For full documentation, see [docs/assignFrom.md](docs/assignFrom.md).
 
+## Protocol Resolution in `resolveValues` and `assignFrom`
+
+`resolveValues` (and by extension `assignFrom`) supports resolving values from external sources via protocol-prefixed strings. This enables declarative references to `globalThis`, `localStorage`, `sessionStorage`, or custom stores.
+
+```JavaScript
+import { resolveValues } from 'assign-gingerly/resolveValues.js';
+
+const result = await resolveValues({
+    baseURL: 'globalThis://myAppConfig?.apiBaseUrl',
+    authToken: 'localStorage://auth?.token',
+    label: '?.title'  // normal path resolution still works
+}, source, {
+    protocols: {
+        globalThis: (key) => globalThis[key],
+        localStorage: (key) => JSON.parse(localStorage.getItem(key) || 'null')
+    }
+});
+```
+
+**How it works:**
+
+1. If a value contains `://` and the part before it matches a key in `protocols`, it's treated as a protocol reference.
+2. The protocol handler is called with the key portion (between `://` and the first `?.`, or end of string).
+3. If a `?.` path follows the key, it's resolved against the handler's result using `resolveValue`.
+4. If the protocol isn't found in the map, the value passes through unchanged (no error).
+
+**Path after protocol key:**
+
+```JavaScript
+// 'globalThis://myConfig?.database?.host'
+// 1. Protocol: 'globalThis'
+// 2. Key: 'myConfig'
+// 3. Handler returns: globalThis['myConfig'] → { database: { host: 'localhost' } }
+// 4. Remaining path: '?.database?.host' → resolves to 'localhost'
+```
+
+**With `assignFrom` and the `"..."` spread key:**
+
+`assignFrom` supports a special `"..."` key that spreads the resolved value into the parent object:
+
+```JavaScript
+import { assignFrom } from 'assign-gingerly/assignFrom.js';
+
+await assignFrom(myForm, {
+    "...": "globalThis://qmywdO1vr0SwyuIe4fvzxQ",
+    path: "api/v2/:operation/:expression",
+    headers: {
+        "...": "globalThis://rPpwNLcYsUOjFcg+N8lmOA"
+    }
+}, {
+    from: source,
+    protocols: { globalThis: (key) => globalThis[key] }
+});
+```
+
+The `"..."` key causes the resolved object to be merged (spread) into the result before passing to `assignGingerly`, rather than being assigned to a property named `"..."`.
+
+**Note:** Both `resolveValues` and `assignFrom` are async (return Promises) to support async protocol handlers (e.g., IndexedDB, fetch). For patterns without protocols, the async overhead is negligible.
+
 ## Custom Assignment with `static assignTo` Protocol
 
 Classes can opt into custom assignment behavior by defining a `static assignTo` method. When `assignGingerly` encounters a property whose current value is an instance of such a class, it delegates the assignment to `assignTo` instead of performing the default merge/replace logic.
@@ -4845,6 +4904,43 @@ It resolves async `fallbackSpawn` implementations from the base class, creates a
 
 For full documentation, see [docs/defineWithFeatures.md](docs/defineWithFeatures.md).
 
+### Resolving async spawns with `resolveAndAssignFeatures`
+
+When defining a custom element via a traditional JS module (rather than declaratively via cede scripts), `resolveAndAssignFeatures` handles the boilerplate of resolving async `fallbackSpawn` implementations before calling `assignFeatures`:
+
+```JavaScript
+import { resolveAndAssignFeatures } from 'assign-gingerly/resolveAndAssignFeatures.js';
+
+export async function wireFeatures(ElementClass, cfg) {
+    const { roundabout } = cfg.features;
+    const { customData, withAttrs } = roundabout;
+
+    await resolveAndAssignFeatures(ElementClass, {
+        timeTicker: { spawn: TimeTicker },  // explicit spawn — used as-is
+        faceUp: {                           // no spawn — resolved from fallbackSpawn
+            callbackForwarding: ['connectedCallback', 'disconnectedCallback']
+        },
+        roundabout: {                       // no spawn — resolved from fallbackSpawn
+            customData,
+            withAttrs,
+            callbackForwarding: ['connectedCallback']
+        }
+    });
+}
+```
+
+**What it does:**
+
+For each feature in the config that doesn't have an explicit `spawn`, it resolves the async `fallbackSpawn` from the class's `static supportedFeatures`, sets it as the spawn, then calls `assignFeatures`. Features with an explicit `spawn` are left untouched.
+
+**When to use it:**
+
+- Defining custom elements via JS modules (the traditional `import` + `define` pattern)
+- When the base class uses async `fallbackSpawn` for lazy loading but you want synchronous feature access after registration
+- As a reusable `wireFeatures` function that multiple element definitions can share
+
+See [time-ticker/wireFeatures.js](https://github.com/bahrus/time-ticker/blob/baseline/wireFeatures.js) for a real-world example.
+
 <details>
 <summary>Catalog of Published Custom Element Features</summary>
 
@@ -4855,6 +4951,7 @@ For full documentation, see [docs/defineWithFeatures.md](docs/defineWithFeatures
 | [face-up](https://www.npmjs.com/package/face-up) | Form Associated Custom Element behavior via ElementInternals | [GitHub](https://github.com/bahrus/face-up) |
 | [roundabout](https://www.npmjs.com/package/roundabout) | Reactive view-model binding with template rendering and computed property orchestration | [GitHub](https://github.com/bahrus/roundabout#using-roundaboutfeature-with-assignfeatures) |
 | [time-ticker](https://www.npmjs.com/package/time-ticker) | Web component that fires events periodically (example of a feature-based component with no code in the class) | [GitHub](https://github.com/bahrus/time-ticker) |
+| [templ-maker](https://www.npmjs.com/package/templ-maker) | Extracts a DOM fragment into a reusable template and clones it per instance (works with cede scripts) | [GitHub](https://github.com/bahrus/templ-maker) |
 
 </details>
 

package/assignFrom.js

@@ -21,10 +21,19 @@
  */
 import { resolveValues } from './resolveValues.js';
 import assignGingerly from './assignGingerly.js';
-export function assignFrom(target, pattern, options) {
-    const resolved = resolveValues(pattern, options.from, {
+export async function assignFrom(target, pattern, options) {
+    const resolved = await resolveValues(pattern, options.from, {
         withMethods: options.withMethods,
-        aka: options.aka
+        aka: options.aka,
+        protocols: options.protocols
     });
+    // Handle "..." spread key — merge resolved value into parent
+    if ('...' in resolved) {
+        const spreadValue = resolved['...'];
+        if (spreadValue && typeof spreadValue === 'object') {
+            Object.assign(resolved, spreadValue);
+        }
+        delete resolved['...'];
+    }
     return assignGingerly(target, resolved, options);
 }

package/assignFrom.ts

@@ -19,22 +19,33 @@
  * }, { from: source });
  * // target is now { color: 'red', text: 'Hello' }
  */
-import { resolveValues } from './resolveValues.js';
+import { resolveValues, ResolveValuesOptions } from './resolveValues.js';
 import assignGingerly, { IAssignGingerlyOptions } from './assignGingerly.js';
 
-export interface AssignFromOptions extends IAssignGingerlyOptions {
+export interface AssignFromOptions extends IAssignGingerlyOptions, ResolveValuesOptions {
   /** Source object to resolve RHS path strings against */
   from: any;
 }
 
-export function assignFrom(
+export async function assignFrom(
   target: any,
   pattern: Record<string, any>,
   options: AssignFromOptions
-): any {
-  const resolved = resolveValues(pattern, options.from, {
+): Promise<any> {
+  const resolved = await resolveValues(pattern, options.from, {
     withMethods: options.withMethods,
-    aka: options.aka
+    aka: options.aka,
+    protocols: options.protocols
   });
+
+  // Handle "..." spread key — merge resolved value into parent
+  if ('...' in resolved) {
+    const spreadValue = resolved['...'];
+    if (spreadValue && typeof spreadValue === 'object') {
+      Object.assign(resolved, spreadValue);
+    }
+    delete resolved['...'];
+  }
+
   return assignGingerly(target, resolved, options);
 }

package/index.js

@@ -12,4 +12,5 @@ export { assignFrom } from './assignFrom.js';
 export { assignFeatures, FeaturesRegistry, captureFeatureInitVals, PropertyBag, suggestFeatureInfo, getFeatureInfoSuggestions } from './assignFeatures.js';
 export { installForwarding } from './installForwarding.js';
 export { defineWithFeatures } from './defineWithFeatures.js';
+export { resolveAndAssignFeatures } from './resolveAndAssignFeatures.js';
 import './object-extension.js';

package/index.ts

@@ -12,4 +12,5 @@ export {assignFrom} from './assignFrom.js';
 export {assignFeatures, FeaturesRegistry, captureFeatureInitVals, PropertyBag, suggestFeatureInfo, getFeatureInfoSuggestions} from './assignFeatures.js';
 export {installForwarding} from './installForwarding.js';
 export {defineWithFeatures} from './defineWithFeatures.js';
+export {resolveAndAssignFeatures} from './resolveAndAssignFeatures.js';
 import './object-extension.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "assign-gingerly",
-  "version": "0.0.50",
+  "version": "0.0.52",
   "description": "This package provides a utility function for carefully merging one object into another.",
   "homepage": "https://github.com/bahrus/assign-gingerly#readme",
   "bugs": {
@@ -68,6 +68,10 @@
       "default": "./defineWithFeatures.js",
       "types": "./defineWithFeatures.ts"
     },
+    "./resolveAndAssignFeatures.js": {
+      "default": "./resolveAndAssignFeatures.js",
+      "types": "./resolveAndAssignFeatures.ts"
+    },
     "./assignFrom.js": {
       "default": "./assignFrom.js",
       "types": "./assignFrom.ts"
@@ -93,7 +97,7 @@
   "devDependencies": {
     "@playwright/test": "1.60.0",
     "spa-ssi": "0.0.27",
-    "@types/node": "25.8.0",
+    "@types/node": "25.9.3",
     "typescript": "6.0.3"
   }
 }

package/resolveAndAssignFeatures.js

@@ -0,0 +1,67 @@
+/**
+ * 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']
+ *     }
+ * });
+ */
+/**
+ * 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.
+ *
+ * @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);
+}

package/resolveAndAssignFeatures.ts

@@ -0,0 +1,79 @@
+/**
+ * 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);
+}

package/resolveValues.js

@@ -25,6 +25,41 @@ function parseCachedPath(path) {
     }
     return parts;
 }
+/**
+ * Resolves a protocol-prefixed value (e.g., 'globalThis://key?.path').
+ *
+ * 1. Extracts the protocol name (before '://')
+ * 2. If the protocol isn't in the protocols map, returns the value unchanged (false positive)
+ * 3. Extracts the key (between '://' and first '?.' or end of string)
+ * 4. Calls the protocol handler with the key
+ * 5. If there's a remaining '?.' path, resolves it against the handler's result
+ */
+async function resolveProtocolValue(value, protocols, options) {
+    // Extract protocol name (before ://)
+    const protoEnd = value.indexOf('://');
+    const protocol = value.substring(0, protoEnd);
+    // Resolve via protocol handler
+    const handler = protocols[protocol];
+    if (!handler)
+        return value; // false flag — coincidentally looks like a protocol
+    const rest = value.substring(protoEnd + 3);
+    // Split at first ?. to separate key from path
+    const pathStart = rest.indexOf('?.');
+    const key = pathStart === -1 ? rest : rest.substring(0, pathStart);
+    const path = pathStart === -1 ? null : rest.substring(pathStart);
+    const resolved = await handler(key);
+    // If there's a remaining path, resolve it against the result
+    if (path) {
+        return resolveValue(path, resolved, options);
+    }
+    return resolved;
+}
+/**
+ * Checks if a string value looks like a protocol reference.
+ */
+function hasProtocol(value) {
+    return value.includes('://');
+}
 /**
  * Navigate a path against a source object, optionally calling methods.
  * Returns the resolved value at the end of the path.
@@ -96,7 +131,7 @@ function navigatePath(source, parts, withMethods) {
  *   aka: { 'q': 'querySelector' }
  * });
  */
-export function resolveValues(pattern, source, options) {
+export async function resolveValues(pattern, source, options) {
     // Build alias map
     const aliasMap = new Map();
     if (options?.aka) {
@@ -110,6 +145,7 @@ export function resolveValues(pattern, source, options) {
             ? options.withMethods
             : new Set(options.withMethods)
         : undefined;
+    const protocols = options?.protocols;
     const result = {};
     for (const [key, value] of Object.entries(pattern)) {
         if (typeof value === 'string' && value.startsWith('?.')) {
@@ -120,6 +156,10 @@ export function resolveValues(pattern, source, options) {
             // Navigate with method support
             result[key] = parts.length === 0 ? source : navigatePath(source, parts, withMethods);
         }
+        else if (typeof value === 'string' && protocols && hasProtocol(value)) {
+            // Protocol-prefixed value — resolve asynchronously
+            result[key] = await resolveProtocolValue(value, protocols, options);
+        }
         else {
             result[key] = value;
         }

package/resolveValues.ts

@@ -13,6 +13,21 @@ export interface ResolveValuesOptions {
    * Substituted before path resolution, matching complete tokens between `?.` delimiters.
    */
   aka?: Record<string, string>;
+
+  /**
+   * Protocol handlers for resolving protocol-prefixed values (e.g., 'globalThis://key').
+   * Each handler receives the key portion and returns the resolved value (sync or async).
+   * 
+   * If a value contains '://' but the protocol isn't in this map, the value passes through unchanged.
+   * If a '?.' appears after the protocol key, the remaining path is resolved against the handler's result.
+   * 
+   * @example
+   * protocols: {
+   *     globalThis: (key) => globalThis[key],
+   *     localStorage: (key) => JSON.parse(localStorage.getItem(key) || 'null')
+   * }
+   */
+  protocols?: Record<string, (key: string) => any | Promise<any>>;
 }
 
 /**
@@ -44,6 +59,51 @@ function parseCachedPath(path: string): string[] {
     return parts;
 }
 
+/**
+ * Resolves a protocol-prefixed value (e.g., 'globalThis://key?.path').
+ * 
+ * 1. Extracts the protocol name (before '://')
+ * 2. If the protocol isn't in the protocols map, returns the value unchanged (false positive)
+ * 3. Extracts the key (between '://' and first '?.' or end of string)
+ * 4. Calls the protocol handler with the key
+ * 5. If there's a remaining '?.' path, resolves it against the handler's result
+ */
+async function resolveProtocolValue(
+    value: string,
+    protocols: Record<string, (key: string) => any | Promise<any>>,
+    options?: ResolveValuesOptions
+): Promise<any> {
+    // Extract protocol name (before ://)
+    const protoEnd = value.indexOf('://');
+    const protocol = value.substring(0, protoEnd);
+
+    // Resolve via protocol handler
+    const handler = protocols[protocol];
+    if (!handler) return value; // false flag — coincidentally looks like a protocol
+
+    const rest = value.substring(protoEnd + 3);
+
+    // Split at first ?. to separate key from path
+    const pathStart = rest.indexOf('?.');
+    const key = pathStart === -1 ? rest : rest.substring(0, pathStart);
+    const path = pathStart === -1 ? null : rest.substring(pathStart);
+
+    const resolved = await handler(key);
+
+    // If there's a remaining path, resolve it against the result
+    if (path) {
+        return resolveValue(path, resolved, options);
+    }
+    return resolved;
+}
+
+/**
+ * Checks if a string value looks like a protocol reference.
+ */
+function hasProtocol(value: string): boolean {
+    return value.includes('://');
+}
+
 /**
  * Navigate a path against a source object, optionally calling methods.
  * Returns the resolved value at the end of the path.
@@ -120,11 +180,11 @@ function navigatePath(
  *   aka: { 'q': 'querySelector' }
  * });
  */
-export function resolveValues(
+export async function resolveValues(
   pattern: Record<string, any>,
   source: any,
   options?: ResolveValuesOptions
-): Record<string, any> {
+): Promise<Record<string, any>> {
   // Build alias map
   const aliasMap = new Map<string, string>();
   if (options?.aka) {
@@ -139,6 +199,8 @@ export function resolveValues(
       ? options.withMethods
       : new Set(options.withMethods)
     : undefined;
+
+  const protocols = options?.protocols;
   
   const result: Record<string, any> = {};
   for (const [key, value] of Object.entries(pattern)) {
@@ -151,6 +213,9 @@ export function resolveValues(
       
       // Navigate with method support
       result[key] = parts.length === 0 ? source : navigatePath(source, parts, withMethods);
+    } else if (typeof value === 'string' && protocols && hasProtocol(value)) {
+      // Protocol-prefixed value — resolve asynchronously
+      result[key] = await resolveProtocolValue(value, protocols, options);
     } else {
       result[key] = value;
     }

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

@@ -184,6 +184,13 @@ export interface AttrConfig<T = unknown, TParserConfig = unknown> {
    * Should make sure it is added to static observedAttribrutes
    */
   sourceOfTruth?: boolean;
+
+  /**
+   * Options to pass to the parser function (e.g., splitStatements behavior).
+   * For named parsers like 'parse-pattern-statements', this is forwarded
+   * as the options argument to the underlying parse function.
+   */
+  parserOptions?: any;
 }
 
 export type AttrPatterns<T = any> = {