assign-gingerly 0.0.57 → 0.0.59

package/assignFromAsync.ts

@@ -0,0 +1,240 @@
+/**
+ * Resolve RHS path strings against a source object, then assign the
+ * resolved values into a target using assignGingerly.
+ * 
+ * Combines resolveValues + assignGingerly into a single call.
+ * Inherits all assignGingerly options (withMethods, aka, signal, etc.).
+ * 
+ * @param target - Object to merge resolved values into
+ * @param pattern - Object whose RHS values may contain `?.` path strings
+ * @param options - Options including `from` (source object) and any assignGingerly options
+ * @returns The target object after merging
+ * 
+ * @example
+ * const source = { theme: { color: 'red' }, label: 'Hello' };
+ * const target = { color: 'blue', text: '' };
+ * assignFrom(target, {
+ *   color: '?.theme?.color',
+ *   text: '?.label'
+ * }, { from: source });
+ * // target is now { color: 'red', text: 'Hello' }
+ */
+import { resolveValues } from './resolveValues.js';
+import assignGingerly, { IAssignGingerlyOptions } from './assignGingerly.js';
+import type { AssignPermissions } from './isAllowedImportPath.js';
+import {
+  expandSubstitutions, categorizeKeys, handleSpreads, isHandlerCommand
+} from './assignFrom.js';
+
+export interface AssignFromOptions extends IAssignGingerlyOptions {
+  /** Source object to resolve RHS path strings against */
+  from: any;
+
+  /** Protocol handlers (sync or async) */
+  protocols?: Record<string, (key: string) => any | Promise<any>>;
+
+  /** Loop variable bindings — expand pattern entries containing ${x} */
+  where_x_in?: string[];
+  /** Loop variable bindings — expand pattern entries containing ${y} */
+  where_y_in?: string[];
+  /** Loop variable bindings — expand pattern entries containing ${z} */
+  where_z_in?: string[];
+
+  /**
+   * Cached element references by variable name.
+   * Used with `#[varName]` syntax in LHS keys for fast repeated element access.
+   * 
+   * - String value: existing element ID (uses getElementById)
+   * - Object value: { qry: 'selector' } — finds element via querySelector on target, auto-assigns an ID
+   * 
+   * Elements are cached via WeakRef with getElementById fallback on cache miss.
+   */
+  withIds?: Record<string, string | { qry: string }>;
+
+  /**
+   * Handler implementations scoped to this call.
+   * Key: the `do` name referenced in handler configs.
+   * Value: a class constructor, or an import path to dynamically load one.
+   * 
+   * Import paths must be local (relative, absolute, or bare specifier — no cross-domain URLs).
+   * The module's default export is checked first; otherwise the first exported class
+   * with an `assign` method on its prototype is used.
+   * 
+   * Built-in handlers (builtIns.*) auto-load without needing to be listed here.
+   * 
+   * @example
+   * handlers: {
+   *     'my-list': MyListHandler,                    // class constructor
+   *     'my-chart': './handlers/chart.js',           // dynamic import path
+   *     'vendor-widget': 'some-package/handler.js',  // bare specifier (import map)
+   * }
+   */
+  handlers?: Record<string, AssignFromHandlerConstructor | string>;
+
+  /**
+   * Inferred assignments — automatically distribute source values to matching
+   * DOM elements based on structural conventions (itemprop, name, etc.).
+   * 
+   * Uses the inferencer submodule to determine the correct property for each
+   * matched element (textContent, value, checked, dateTime, ish, etc.).
+   * 
+   * @example
+   * inferredAssignments: {
+   *     byItemprop: ['user', 'name', 'email'],  // or true for all source keys
+   *     beVigilant: true,  // watch for new matching elements (requires signal)
+   * }
+   */
+  inferredAssignments?: {
+    byItemprop?: string[] | true;
+    /** Watch for new matching elements via MutationObserver. Requires options.signal for cleanup. */
+    beVigilant?: boolean;
+  };
+
+  /**
+   * Bulk enhancement application via EMC JSON configs.
+   * Finds matching elements and spawns enhancements on them.
+   * 
+   * Each entry specifies an EMC JSON path and optionally overrides the matching selector.
+   * Enhancements are auto-registered if not already present in the enhancement registry.
+   * 
+   * No scope perimeter is applied — use mount-observer for reactive/scoped enhancement.
+   * 
+   * @example
+   * enhance: [
+   *     { emc: 'be-bound/emc.json', matching: '[name]' },
+   *     { emc: 'be-observant/emc.json', matching: '[itemprop]' },
+   * ]
+   */
+  enhance?: Array<{ emc: string; matching?: string; parse?: boolean }>;
+}
+
+/**
+ * Interface for assignFrom handler classes.
+ * Handlers are invoked when a LHS key ends with ' =>'.
+ */
+export interface AssignFromHandler {
+    assign(lhsTarget: any, resolvedParams: Record<string, any>, options: AssignFromOptions): Promise<void> | void;
+}
+
+export interface AssignFromHandlerConstructor {
+    new (config: any): AssignFromHandler;
+}
+
+// Module cache for processHandlerCommands — avoids await on dynamic import after first call
+let _processHandlerCommands: any;
+
+export async function assignFromAsync(
+  target: any,
+  pattern: Record<string, any>,
+  options: AssignFromOptions,
+  permissions?: AssignPermissions
+): Promise<any> {
+  // First: expand looped substitution variables (${x}, ${y}, ${z})
+  const expandedPattern = expandSubstitutions(pattern, options);
+
+  // Categorize keys
+  const { handlerKeys, normalPattern, idRefNormalKeys, idRefHandlerKeys } = categorizeKeys(expandedPattern);
+
+  // Process normal keys via resolveValues + assignGingerly
+  if (Object.keys(normalPattern).length > 0) {
+    const resolved = await resolveValues(normalPattern, options.from, {
+      withMethods: options.withMethods,
+      aka: options.aka,
+      protocols: options.protocols
+    });
+
+    // Recursively handle "..." spread keys at all nesting levels
+    handleSpreads(resolved);
+
+    assignGingerly(target, resolved, options);
+  }
+
+  // Process #[x] normal keys — resolve element, then apply remaining path + value
+  if (idRefNormalKeys.length > 0 && options.withIds) {
+    const { resolveIdVariable, parseIdRef } = await import('./resolveIdRef.js');
+    for (const key of idRefNormalKeys) {
+      const parsed = parseIdRef(key);
+      if (!parsed) continue;
+
+      const el = resolveIdVariable(parsed.varName, target, options.withIds);
+      if (!el) continue;
+
+      const value = expandedPattern[key];
+      if (parsed.remainingPath) {
+        // Resolve the RHS value
+        const resolvedValue = await resolveValues(
+          { __v: value }, options.from,
+          { withMethods: options.withMethods, aka: options.aka, protocols: options.protocols }
+        );
+        // Apply remaining path on the resolved element
+        assignGingerly(el, { [parsed.remainingPath]: resolvedValue.__v }, options);
+      } else {
+        // No remaining path — resolve and assign directly to the element
+        const resolvedValue = await resolveValues(
+          typeof value === 'object' && value !== null ? value : { __v: value },
+          options.from,
+          { withMethods: options.withMethods, aka: options.aka, protocols: options.protocols }
+        );
+        if ('__v' in resolvedValue) {
+          // Single value — can't assign to element root without a path
+        } else {
+          assignGingerly(el, resolvedValue, options);
+        }
+      }
+    }
+  }
+  // Process handler commands ( =>) — cached after first load to avoid await overhead
+  if (handlerKeys.length > 0) {
+    
+    _processHandlerCommands ??= (await import('./processHandlerCommands.js')).processHandlerCommands;
+    await _processHandlerCommands(target, handlerKeys, expandedPattern, options, permissions);
+  }
+  // Process #[x] handler keys — resolve element, then pass to handler processing
+  if (idRefHandlerKeys.length > 0 && options.withIds) {
+    const { resolveIdVariable, parseIdRef } = await import('./resolveIdRef.js');
+    _processHandlerCommands ??= (await import('./processHandlerCommands.js')).processHandlerCommands;
+
+    for (const key of idRefHandlerKeys) {
+      const parsed = parseIdRef(key);
+      if (!parsed) continue;
+
+      const el = resolveIdVariable(parsed.varName, target, options.withIds);
+      if (!el) continue;
+
+      // Build a synthetic key for processHandlerCommands:
+      // The resolved element becomes the target, remaining path is the LHS
+      const syntheticKey = parsed.remainingPath
+        ? `${parsed.remainingPath} =>`
+        : ' =>';
+
+      const syntheticPattern: Record<string, any> = {
+        [syntheticKey]: expandedPattern[key]
+      };
+
+      await _processHandlerCommands(el, [syntheticKey], syntheticPattern, options, permissions);
+    }
+  }
+
+  // Process inferred assignments — dynamically imported only when option is present
+  if (options.inferredAssignments) {
+    const { processInferredAssignments } = await import('./inferredAssignments.js');
+    await processInferredAssignments(target, options.from, options.inferredAssignments);
+
+    // Set up MutationObserver for new matching elements if beVigilant
+    if (options.inferredAssignments.beVigilant) {
+      if (!options.signal) {
+        throw new Error('assignFrom: inferredAssignments.beVigilant requires options.signal (AbortSignal) for cleanup');
+      }
+      const { setupVigilantObserver } = await import('./beVigilant.js');
+      setupVigilantObserver(target, options.from, options.inferredAssignments, options.signal);
+    }
+  }
+
+  // Process bulk enhancements — dynamically imported only when option is present
+  if (options.enhance && options.enhance.length > 0) {
+    const { enhanceAll } = await import('./enhanceAll.js');
+    await enhanceAll(target, options.enhance, permissions);
+  }
+
+  return target;
+}

package/getValues.js

@@ -0,0 +1,223 @@
+/**
+ * getValues.ts — Synchronous value resolution for path strings.
+ *
+ * The synchronous counterpart to resolveValues. Resolves `?.`-prefixed path
+ * strings against a source object, with support for withMethods, aka aliases,
+ * synchronous protocols, arrays, and nested plain objects.
+ *
+ * For async protocol handlers, use resolveValues instead.
+ *
+ * @example
+ * import { getValues, getValue } from 'assign-gingerly/getValues.js';
+ *
+ * const result = getValues({
+ *     name: '?.user?.name',
+ *     greeting: '?.messages?.hello',
+ *     count: 42
+ * }, source, { withMethods: ['querySelector'], aka: { q: 'querySelector' } });
+ */
+/**
+ * Apply alias substitutions to a path string.
+ * Replaces complete tokens between `?.` delimiters with their aliased values.
+ */
+function applyAliases(path, aliasMap) {
+    if (aliasMap.size === 0)
+        return path;
+    const parts = path.split('?.');
+    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.
+ */
+function navigatePath(source, parts, withMethods) {
+    let current = source;
+    let i = 0;
+    while (i < parts.length) {
+        if (current == null)
+            return current;
+        const part = parts[i];
+        if (withMethods && withMethods.has(part)) {
+            const method = current[part];
+            if (typeof method === 'function') {
+                const nextPart = parts[i + 1];
+                if (nextPart !== undefined && !(withMethods.has(nextPart))) {
+                    current = method.call(current, nextPart);
+                    i += 2;
+                }
+                else {
+                    current = method.call(current);
+                    i++;
+                }
+            }
+            else {
+                current = current[part];
+                i++;
+            }
+        }
+        else {
+            current = current[part];
+            i++;
+        }
+    }
+    return current;
+}
+/**
+ * Checks if a string value looks like a protocol reference.
+ */
+function hasProtocol(value) {
+    return value.includes('://');
+}
+/**
+ * Resolve a protocol-prefixed value synchronously.
+ */
+function getProtocolValue(value, protocols, options) {
+    const protoEnd = value.indexOf('://');
+    const protocol = value.substring(0, protoEnd);
+    const handler = protocols[protocol];
+    if (!handler)
+        return value; // not a recognized protocol
+    const rest = value.substring(protoEnd + 3);
+    const pathStart = rest.indexOf('?.');
+    const key = pathStart === -1 ? rest : rest.substring(0, pathStart);
+    const path = pathStart === -1 ? null : rest.substring(pathStart);
+    const resolved = handler(key);
+    if (path) {
+        return getValue(path, resolved, options);
+    }
+    return resolved;
+}
+/**
+ * Resolve path strings and protocols within an array (synchronous).
+ * Recurses into nested arrays and plain objects.
+ */
+function getArray(arr, source, aliasMap, withMethods, protocols, options) {
+    const result = [];
+    for (const item of arr) {
+        if (typeof item === 'string' && item.startsWith('?.')) {
+            const aliased = applyAliases(item, aliasMap);
+            const parts = parseCachedPath(aliased);
+            result.push(parts.length === 0 ? source : navigatePath(source, parts, withMethods));
+        }
+        else if (typeof item === 'string' && protocols && hasProtocol(item)) {
+            result.push(getProtocolValue(item, protocols, options));
+        }
+        else if (Array.isArray(item)) {
+            result.push(getArray(item, source, aliasMap, withMethods, protocols, options));
+        }
+        else if (item && typeof item === 'object') {
+            const proto = Object.getPrototypeOf(item);
+            if (proto === Object.prototype || proto === null) {
+                result.push(getValues(item, source, options));
+            }
+            else {
+                result.push(item);
+            }
+        }
+        else {
+            result.push(item);
+        }
+    }
+    return result;
+}
+/**
+ * Synchronously resolve RHS path strings in a pattern object against a source object.
+ *
+ * Any value that is a string starting with `?.` is treated as a path
+ * and resolved against the source object. Non-string values and strings
+ * not starting with `?.` pass through unchanged.
+ *
+ * @param pattern - Object whose RHS values may contain `?.` path strings
+ * @param source - Object to resolve paths against
+ * @param options - Optional withMethods, aka, and synchronous protocols
+ * @returns New object with path strings replaced by resolved values
+ */
+export function getValues(pattern, source, options) {
+    // Build alias map
+    const aliasMap = new Map();
+    if (options?.aka) {
+        for (const [alias, target] of Object.entries(options.aka)) {
+            aliasMap.set(alias, target);
+        }
+    }
+    // Build methods set
+    const withMethods = options?.withMethods
+        ? options.withMethods instanceof Set
+            ? 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('?.')) {
+            const aliased = applyAliases(value, aliasMap);
+            const parts = parseCachedPath(aliased);
+            result[key] = parts.length === 0 ? source : navigatePath(source, parts, withMethods);
+        }
+        else if (typeof value === 'string' && protocols && hasProtocol(value)) {
+            result[key] = getProtocolValue(value, protocols, options);
+        }
+        else if (Array.isArray(value)) {
+            result[key] = getArray(value, source, aliasMap, withMethods, protocols, options);
+        }
+        else if (typeof value === 'object' && value !== null) {
+            const proto = Object.getPrototypeOf(value);
+            if (proto === Object.prototype || proto === null) {
+                result[key] = getValues(value, source, options);
+            }
+            else {
+                result[key] = value;
+            }
+        }
+        else {
+            result[key] = value;
+        }
+    }
+    return result;
+}
+/**
+ * Synchronously resolve a single `?.`-delimited path string against a source object.
+ *
+ * @param path - A `?.`-delimited path string (e.g., '?.user?.name')
+ * @param source - Object to resolve the path against
+ * @param options - Optional withMethods and aka
+ * @returns The resolved value, or undefined if any segment is nullish
+ */
+export function getValue(path, source, options) {
+    if (!path.startsWith('?.'))
+        return path;
+    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);
+    }
+    const parts = parseCachedPath(aliased);
+    if (parts.length === 0)
+        return source;
+    const withMethods = options?.withMethods
+        ? options.withMethods instanceof Set
+            ? options.withMethods
+            : new Set(options.withMethods)
+        : undefined;
+    return navigatePath(source, parts, withMethods);
+}