assign-gingerly 0.0.51 → 0.0.53

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>
 

package/assignFrom.js

@@ -21,10 +21,36 @@
  */
 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
     });
+    // Recursively handle "..." spread keys at all nesting levels
+    handleSpreads(resolved);
     return assignGingerly(target, resolved, options);
 }
+/**
+ * Recursively walk an object and handle "..." spread keys.
+ * When a "..." key is found, its value (which should be an object after protocol resolution)
+ * is spread into the parent, replacing the "..." entry.
+ */
+function handleSpreads(obj) {
+    for (const [key, value] of Object.entries(obj)) {
+        if (key !== '...' && typeof value === 'object' && value !== null && !Array.isArray(value)) {
+            const proto = Object.getPrototypeOf(value);
+            if (proto === Object.prototype || proto === null) {
+                obj[key] = handleSpreads(value);
+            }
+        }
+    }
+    if ('...' in obj) {
+        const spreadValue = obj['...'];
+        delete obj['...'];
+        if (spreadValue && typeof spreadValue === 'object') {
+            Object.assign(obj, spreadValue);
+        }
+    }
+    return obj;
+}

package/assignFrom.ts

@@ -19,22 +19,51 @@
  * }, { 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
   });
+
+  // Recursively handle "..." spread keys at all nesting levels
+  handleSpreads(resolved);
+
   return assignGingerly(target, resolved, options);
 }
+
+/**
+ * Recursively walk an object and handle "..." spread keys.
+ * When a "..." key is found, its value (which should be an object after protocol resolution)
+ * is spread into the parent, replacing the "..." entry.
+ */
+function handleSpreads(obj: Record<string, any>): Record<string, any> {
+  for (const [key, value] of Object.entries(obj)) {
+    if (key !== '...' && typeof value === 'object' && value !== null && !Array.isArray(value)) {
+      const proto = Object.getPrototypeOf(value);
+      if (proto === Object.prototype || proto === null) {
+        obj[key] = handleSpreads(value);
+      }
+    }
+  }
+  if ('...' in obj) {
+    const spreadValue = obj['...'];
+    delete obj['...'];
+    if (spreadValue && typeof spreadValue === 'object') {
+      Object.assign(obj, spreadValue);
+    }
+  }
+  return obj;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "assign-gingerly",
-  "version": "0.0.51",
+  "version": "0.0.53",
   "description": "This package provides a utility function for carefully merging one object into another.",
   "homepage": "https://github.com/bahrus/assign-gingerly#readme",
   "bugs": {
@@ -97,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/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,20 @@ 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 if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+            // Recursively resolve nested plain objects (e.g., headers: { "...": "globalThis://key" })
+            // Only recurse into plain objects — skip DOM elements, class instances, etc.
+            const proto = Object.getPrototypeOf(value);
+            if (proto === Object.prototype || proto === null) {
+                result[key] = await resolveValues(value, source, options);
+            } else {
+                result[key] = value;
+            }
+        }
         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,18 @@ 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 if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+      // Recursively resolve nested plain objects (e.g., headers: { "...": "globalThis://key" })
+      // Only recurse into plain objects — skip DOM elements, class instances, etc.
+      const proto = Object.getPrototypeOf(value);
+      if (proto === Object.prototype || proto === null) {
+        result[key] = await resolveValues(value, source, options);
+      } else {
+        result[key] = value;
+      }
     } 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> = {