assign-gingerly 0.0.63 → 0.0.65

package/resolveValues.js

@@ -6,7 +6,7 @@
  *
  * Re-exports ResolveValuesOptions for backward compatibility.
  */
-import { getValue } from './getValues.js';
+import { getValue, getValues } from './getValues.js';
 // Re-export getValue as resolveValue for backward compatibility
 export { getValue as resolveValue };
 /**
@@ -15,63 +15,6 @@ export { getValue as resolveValue };
 function hasProtocol(value) {
     return value.includes('://');
 }
-/**
- * Apply alias substitutions to a path string.
- */
-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.
- */
-const pathCache = new Map();
-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.
- */
-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;
-}
 /**
  * Resolves a protocol-prefixed value asynchronously.
  */
@@ -94,24 +37,24 @@ async function resolveProtocolValue(value, protocols, options) {
 /**
  * Resolve path strings and protocol references within an array (async).
  */
-async function resolveArray(arr, source, aliasMap, withMethods, protocols, options) {
+async function resolveArray(arr, source, 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(await resolveProtocolValue(item, protocols, options));
+        if (typeof item === 'string') {
+            if (protocols && hasProtocol(item)) {
+                result.push(await resolveProtocolValue(item, protocols, options));
+            }
+            else {
+                result.push(getValue(item, source, options));
+            }
         }
         else if (Array.isArray(item)) {
-            result.push(await resolveArray(item, source, aliasMap, withMethods, protocols, options));
+            result.push(await resolveArray(item, source, protocols, options));
         }
         else if (item && typeof item === 'object') {
             const proto = Object.getPrototypeOf(item);
             if (proto === Object.prototype || proto === null) {
-                result.push(await resolveValues(item, source, options));
+                result.push(options?.protocols ? await resolveValues(item, source, options) : getValues(item, source, options));
             }
             else {
                 result.push(item);
@@ -135,35 +78,24 @@ async function resolveArray(arr, source, aliasMap, withMethods, protocols, optio
  * @returns New object with path strings replaced by resolved values
  */
 export async function resolveValues(pattern, source, options) {
-    const aliasMap = new Map();
-    if (options?.aka) {
-        for (const [alias, target] of Object.entries(options.aka)) {
-            aliasMap.set(alias, target);
-        }
-    }
-    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] = await resolveProtocolValue(value, protocols, options);
+        if (typeof value === 'string') {
+            if (protocols && hasProtocol(value)) {
+                result[key] = await resolveProtocolValue(value, protocols, options);
+            }
+            else {
+                result[key] = getValue(value, source, options);
+            }
         }
         else if (Array.isArray(value)) {
-            result[key] = await resolveArray(value, source, aliasMap, withMethods, protocols, options);
+            result[key] = await resolveArray(value, source, protocols, options);
         }
         else if (typeof value === 'object' && value !== null) {
             const proto = Object.getPrototypeOf(value);
             if (proto === Object.prototype || proto === null) {
-                result[key] = await resolveValues(value, source, options);
+                result[key] = options?.protocols ? await resolveValues(value, source, options) : getValues(value, source, options);
             }
             else {
                 result[key] = value;

package/resolveValues.ts

@@ -7,7 +7,7 @@
  * Re-exports ResolveValuesOptions for backward compatibility.
  */
 
-import { getValue } from './getValues.js';
+import { getValue, getValues } from './getValues.js';
 import type { ResolveValuesOptions } from './types/assign-gingerly/types.js';
 
 export type { ResolveValuesOptions };
@@ -22,65 +22,6 @@ function hasProtocol(value: string): boolean {
     return value.includes('://');
 }
 
-/**
- * Apply alias substitutions to a path string.
- */
-function applyAliases(path: string, aliasMap: Map<string, string>): string {
-    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.
- */
-const pathCache = new Map<string, string[]>();
-
-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.
- */
-function navigatePath(
-    source: any,
-    parts: string[],
-    withMethods: Set<string> | undefined
-): any {
-    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;
-}
 
 /**
  * Resolves a protocol-prefixed value asynchronously.
@@ -115,25 +56,23 @@ async function resolveProtocolValue(
 async function resolveArray(
     arr: any[],
     source: any,
-    aliasMap: Map<string, string>,
-    withMethods: Set<string> | undefined,
     protocols: Record<string, (key: string) => any | Promise<any>> | undefined,
     options?: ResolveValuesOptions
 ): Promise<any[]> {
     const result: any[] = [];
     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(await resolveProtocolValue(item, protocols, options));
+        if (typeof item === 'string') {
+            if (protocols && hasProtocol(item)) {
+                result.push(await resolveProtocolValue(item, protocols, options));
+            } else {
+                result.push(getValue(item, source, options));
+            }
         } else if (Array.isArray(item)) {
-            result.push(await resolveArray(item, source, aliasMap, withMethods, protocols, options));
+            result.push(await resolveArray(item, source, protocols, options));
         } else if (item && typeof item === 'object') {
             const proto = Object.getPrototypeOf(item);
             if (proto === Object.prototype || proto === null) {
-                result.push(await resolveValues(item, source, options));
+                result.push(options?.protocols ? await resolveValues(item, source, options) : getValues(item, source, options));
             } else {
                 result.push(item);
             }
@@ -160,35 +99,22 @@ export async function resolveValues(
     source: any,
     options?: ResolveValuesOptions
 ): Promise<Record<string, any>> {
-    const aliasMap = new Map<string, string>();
-    if (options?.aka) {
-        for (const [alias, target] of Object.entries(options.aka)) {
-            aliasMap.set(alias, target);
-        }
-    }
-
-    const withMethods = options?.withMethods
-        ? options.withMethods instanceof Set
-            ? options.withMethods
-            : new Set(options.withMethods)
-        : undefined;
-
     const protocols = options?.protocols;
 
     const result: Record<string, any> = {};
     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] = await resolveProtocolValue(value, protocols, options);
+        if (typeof value === 'string') {
+            if (protocols && hasProtocol(value)) {
+                result[key] = await resolveProtocolValue(value, protocols, options);
+            } else {
+                result[key] = getValue(value, source, options);
+            }
         } else if (Array.isArray(value)) {
-            result[key] = await resolveArray(value, source, aliasMap, withMethods, protocols, options);
+            result[key] = await resolveArray(value, source, protocols, options);
         } else if (typeof value === 'object' && value !== null) {
             const proto = Object.getPrototypeOf(value);
             if (proto === Object.prototype || proto === null) {
-                result[key] = await resolveValues(value, source, options);
+                result[key] = options?.protocols ? await resolveValues(value, source, options) : getValues(value, source, options);
             } else {
                 result[key] = value;
             }

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

@@ -250,8 +250,21 @@ export type IEnhancementRegistryItem<T = any> = EnhancementConfig<T>;
 export interface IAssignGingerlyOptions {
   registry?: typeof EnhancementRegistry | EnhancementRegistry;
   bypassChecks?: boolean;
+  /**
+   * Method names to call during path evaluation (e.g., for `?.method()` calls)
+   */
   withMethods?: string[] | Set<string>;
+  /**
+   * Alias mappings for property and method names.
+   */
   aka?: Record<string, string>;
+
+  /**
+   * Shorthand for binding method aliases from the source object.
+   * Each entry maps an alias to a method name and is normalized into
+   * the existing withMethods + aka behavior.
+   */
+  akaMethods?: Record<string, string>;
   
   /**
    * AbortSignal for cleaning up reactive subscriptions (@eachTime)
@@ -261,11 +274,117 @@ export interface IAssignGingerlyOptions {
   signal?: AbortSignal;
 }
 
+/**
+ * Options for assignTentatively — reversible assignment with change tracking.
+ * 
+ * Supports a subset of assignGingerly's path features (nested paths, +=, =!, -=)
+ * with the addition of reversal tracking.
+ */
+export interface IAssignTentativelyOptions {
+  /**
+   * Object to accumulate reversal entries into.
+   * If omitted, a new object is created internally.
+   * Pass an existing object to accumulate reversals across multiple calls.
+   * 
+   * The reversal object can be passed to assignGingerly to undo all changes:
+   * @example
+   * const reversal = {};
+   * assignTentatively(obj, { name: 'Bob' }, { reversal });
+   * // Later:
+   * assignGingerly(obj, reversal); // restores name to original value
+   */
+  reversal?: Record<string | symbol, any>;
+
+  /**
+   * Alias mappings for property and method names.
+   * Same semantics as IAssignGingerlyOptions.aka — substituted before path evaluation.
+   */
+  aka?: Record<string, string>;
+}
+
+/**
+ * Options for assignFrom / assignFromAsync.
+ */
+export interface AssignFromOptions {
+  /** Source object to resolve RHS path strings against */
+  from: any;
+
+  /** Protocol handlers (sync or async) */
+  protocols?: Record<string, (key: string) => any | Promise<any>>;
+
+  /** Method names to call during path evaluation */
+  withMethods?: string[] | Set<string>;
+
+  /** Alias mappings for path segments */
+  aka?: Record<string, string>;
+
+  /** AbortSignal for cleanup */
+  signal?: AbortSignal;
+
+  /** 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[];
+
+  /**
+   * Pin 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
+   * - Object value: { path: [...], expect?, fallback? } — child index path + auto-ID + optional validation
+   */
+  pin?: Record<string, string | { qry: string } | { path: number[]; expect?: string; fallback?: boolean }>;
+
+  /**
+   * Positional element references for use with `#[varName]` syntax.
+   * Resolves elements by child index path — no IDs assigned, no caching.
+   */
+  at?: Record<string, number[] | { path: number[]; expect?: string; fallback?: boolean }>;
+
+  /**
+   * Handler implementations scoped to this call.
+   * Key: the `do` name referenced in handler configs.
+   * Value: a class constructor, an import path, or a builtIns.* alias string.
+   */
+  handlers?: Record<string, AssignFromHandlerConstructor | string>;
+
+  /**
+   * Inferred assignments — automatically distribute source values to matching
+   * DOM elements based on structural conventions (itemprop, name, etc.).
+   */
+  infer?: {
+    byItemprop?: string[] | true;
+    '|'?: string[] | true;
+    byName?: string[] | true | { props: string[] | true; outside: string };
+    '@'?: string[] | true | { props: string[] | true; outside: string };
+    beVigilant?: boolean;
+  };
+
+  /**
+   * Bulk enhancement application via EMC JSON configs.
+   */
+  enhance?: Array<{ emc: string; matching?: string; parse?: boolean }>;
+
+  /** Registry for enhancement dependency injection (inherited from IAssignGingerlyOptions) */
+  registry?: any;
+
+  [key: string]: any;
+}
+
 /**
  * Options for synchronous value resolution (getValues / getValue).
  * Extends IAssignGingerlyOptions with synchronous protocol handlers.
  */
 export interface GetValuesOptions extends IAssignGingerlyOptions {
+  /**
+   * Internal root object for special $0 references.
+   * This is used by assignFrom to resolve values relative to the target object.
+   */
+  root?: any;
+
   /**
    * Synchronous protocol handlers for resolving protocol-prefixed values.
    * Each handler receives the key portion and MUST return synchronously.
@@ -285,6 +404,12 @@ export interface GetValuesOptions extends IAssignGingerlyOptions {
  * Same as GetValuesOptions but protocol handlers may return Promises.
  */
 export interface ResolveValuesOptions extends IAssignGingerlyOptions {
+  /**
+   * Internal root object for special $0 references.
+   * This is used by assignFrom to resolve values relative to the target object.
+   */
+  root?: any;
+
   /**
    * 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).
@@ -669,6 +794,20 @@ export interface LazyLoadSwitchResolvedParams extends Omit<LazyLoadResolvedParam
     rhs: any;
 }
 
+export interface FromEachItemConfig {
+    assignToFragment?: Record<string, any>;
+    withOptions?: AssignFromOptions;
+    resolve?: {
+      key?: string;
+    }
+}
+
+export interface ManageTemplateListConfig extends HandlerConfig {
+    do: 'builtIns.manageTemplateList';
+    resolve: ManageTemplateListResolvedParams;
+    fromEachItem: FromEachItemConfig;
+}
+
 /**
  * Resolved parameters received by ManageTemplateListHandler.assign().
  */
@@ -712,3 +851,32 @@ export declare class LazyLoadHandler implements AssignFromHandler {
     assign(lhsTarget: any, resolvedParams: Record<string, any>, options?: any): Promise<void>;
     protected onCloneInserted(nodes: Node[], lhsTarget: Element, resolvedParams: Record<string, any>): Promise<void>;
 }
+
+//#region Event Handler
+
+export interface AssignVector {
+    assignToTarget?: Record<string, any>,
+    assignToSource?: Record<string, any>,
+    assignToLHS?: Record<string, any>,
+    withOptions?: AssignFromOptions,
+    withAssignToTargetOptions?: AssignFromOptions,
+    withAssignToSourceOptions?: AssignFromOptions,
+    withAssignToLHSOptions?: AssignFromOptions,
+}
+
+
+export interface AddEventListenerConfig extends AssignVector  {
+   get?: {
+     abortController?: string | AbortController,
+     on?: string,
+     nudge?: boolean,
+     options?: AddEventListenerOptions,
+   },
+   
+   fromLHS?: AssignVector,
+   fromSource?: AssignVector,
+   fromEvent?: AssignVector,
+   
+   
+}
+//#endregion