assign-gingerly 0.0.54 → 0.0.55

package/isAllowedImportPath.js

@@ -0,0 +1,42 @@
+/**
+ * isAllowedImportPath.ts — Security utility for validating import paths.
+ *
+ * Checks that a path is local (relative, absolute, or bare specifier) and
+ * not a cross-domain URL. Used to prevent untrusted HTML attributes from
+ * triggering imports to arbitrary external domains.
+ *
+ * @example
+ * import { isAllowedImportPath } from 'assign-gingerly/isAllowedImportPath.js';
+ *
+ * isAllowedImportPath('./local.js');           // true
+ * isAllowedImportPath('../parent/file.js');    // true
+ * isAllowedImportPath('/absolute/path.js');    // true
+ * isAllowedImportPath('bare-specifier/mod.js'); // true
+ * isAllowedImportPath('https://evil.com/x.js'); // false
+ * isAllowedImportPath('//cdn.example.com/x.js'); // false
+ */
+/**
+ * Check if an import path is allowed (non-cross-domain).
+ *
+ * Allowed:
+ * - Relative paths: ./foo.js, ../bar.js
+ * - Absolute paths: /path/to/file.js
+ * - Bare specifiers: package-name/file.js, @scope/package/file.js
+ *
+ * Blocked:
+ * - Protocol URLs: https://..., http://..., data:..., etc.
+ * - Protocol-relative: //cdn.example.com/...
+ *
+ * @param path - The import path to validate
+ * @returns true if the path is local/safe, false if cross-domain
+ */
+export function isAllowedImportPath(path) {
+    if (path.startsWith('./') || path.startsWith('../') || path.startsWith('/')) {
+        return true;
+    }
+    if (path.includes('://') || path.startsWith('//')) {
+        return false;
+    }
+    // Bare specifier (no protocol, no //) — allowed
+    return true;
+}

package/isAllowedImportPath.ts

@@ -0,0 +1,53 @@
+/**
+ * isAllowedImportPath.ts — Security utility for validating import paths.
+ * 
+ * Checks that a path is local (relative, absolute, or bare specifier) and
+ * not a cross-domain URL. Used to prevent untrusted HTML attributes from
+ * triggering imports to arbitrary external domains.
+ * 
+ * @example
+ * import { isAllowedImportPath } from 'assign-gingerly/isAllowedImportPath.js';
+ * 
+ * isAllowedImportPath('./local.js');           // true
+ * isAllowedImportPath('../parent/file.js');    // true
+ * isAllowedImportPath('/absolute/path.js');    // true
+ * isAllowedImportPath('bare-specifier/mod.js'); // true
+ * isAllowedImportPath('https://evil.com/x.js'); // false
+ * isAllowedImportPath('//cdn.example.com/x.js'); // false
+ */
+
+/**
+ * Permissions interface for controlling security-sensitive operations.
+ * Passed as the last parameter to assignGingerly, assignFrom, and enhanceAll.
+ * Only trusted script can set these — they are never parsed from HTML attributes.
+ */
+export interface AssignPermissions {
+    /** Allow imports from cross-domain URLs (default: false) */
+    crossDomainImports?: boolean;
+}
+
+/**
+ * Check if an import path is allowed (non-cross-domain).
+ * 
+ * Allowed:
+ * - Relative paths: ./foo.js, ../bar.js
+ * - Absolute paths: /path/to/file.js
+ * - Bare specifiers: package-name/file.js, @scope/package/file.js
+ * 
+ * Blocked:
+ * - Protocol URLs: https://..., http://..., data:..., etc.
+ * - Protocol-relative: //cdn.example.com/...
+ * 
+ * @param path - The import path to validate
+ * @returns true if the path is local/safe, false if cross-domain
+ */
+export function isAllowedImportPath(path: string): boolean {
+    if (path.startsWith('./') || path.startsWith('../') || path.startsWith('/')) {
+        return true;
+    }
+    if (path.includes('://') || path.startsWith('//')) {
+        return false;
+    }
+    // Bare specifier (no protocol, no //) — allowed
+    return true;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "assign-gingerly",
-  "version": "0.0.54",
+  "version": "0.0.55",
   "description": "This package provides a utility function for carefully merging one object into another.",
   "homepage": "https://github.com/bahrus/assign-gingerly#readme",
   "bugs": {
@@ -17,6 +17,8 @@
   "files": [
     "*.js",
     "*.ts",
+    "handlers/**",
+    "inferencer/**",
     "README.md",
     "LICENSE",
     "types/assign-gingerly/types.d.ts"
@@ -100,6 +102,30 @@
       "default": "./paths.js",
       "types": "./paths.ts"
     },
+    "./enhanceAll.js": {
+      "default": "./enhanceAll.js",
+      "types": "./enhanceAll.ts"
+    },
+    "./isAllowedImportPath.js": {
+      "default": "./isAllowedImportPath.js",
+      "types": "./isAllowedImportPath.ts"
+    },
+    "./inferredAssignments.js": {
+      "default": "./inferredAssignments.js",
+      "types": "./inferredAssignments.ts"
+    },
+    "./beVigilant.js": {
+      "default": "./beVigilant.js",
+      "types": "./beVigilant.ts"
+    },
+    "./inferencer/inferencer.js": {
+      "default": "./inferencer/inferencer.js",
+      "types": "./inferencer/inferencer.ts"
+    },
+    "./inferencer/withScopePerimeter.js": {
+      "default": "./inferencer/withScopePerimeter.js",
+      "types": "./inferencer/withScopePerimeter.ts"
+    },
     "./assignFrom.js": {
       "default": "./assignFrom.js",
       "types": "./assignFrom.ts"

package/paths.js

@@ -10,9 +10,41 @@
  */
 const PATH_SYMBOL = Symbol('assign-gingerly-path');
 
+/**
+ * Create a proxy for id-ref paths (#[varName]).
+ */
+function createIdRefProxy(idRef, options) {
+    function handler() {}
+    return new Proxy(handler, {
+        get(_, prop) {
+            if (prop === 'path' || prop === PATH_SYMBOL) {
+                return idRef;
+            }
+            if (typeof prop === 'symbol') return undefined;
+            const chained = `${idRef}?.${String(prop)}`;
+            return createIdRefProxy(chained, options);
+        },
+        apply(_, __, args) {
+            if (args.length > 0) {
+                const arg = args[0];
+                let argStr;
+                if (arg === true) argStr = 'true';
+                else if (arg === false) argStr = 'false';
+                else if (arg && typeof arg === 'object' && PATH_SYMBOL in arg) {
+                    const fullPath = arg[PATH_SYMBOL];
+                    argStr = fullPath.startsWith('?.') ? fullPath.substring(2) : fullPath;
+                }
+                else argStr = String(arg);
+                const chained = `${idRef}?.${argStr}`;
+                return createIdRefProxy(chained, options);
+            }
+            return createIdRefProxy(idRef, options);
+        }
+    });
+}
+
 /**
  * Create a recursive proxy that records property access paths.
- * Supports both property access and method call syntax (via apply trap on function target).
  */
 function createPathProxy(prefix, options) {
     const aliasMap = options?.aka;
@@ -27,6 +59,14 @@ function createPathProxy(prefix, options) {
             if (typeof prop === 'symbol') return undefined;
 
             let segment = String(prop);
+
+            // #-prefix: $['#firstName'] → '#[firstName]' (cached element ref)
+            if (segment.startsWith('#')) {
+                const varName = segment.substring(1);
+                const idRef = `#[${varName}]`;
+                return createIdRefProxy(idRef, options);
+            }
+
             if (aliasMap) {
                 for (const [alias, target] of Object.entries(aliasMap)) {
                     if (target === segment) { segment = alias; break; }
@@ -111,6 +151,14 @@ export function doAssign(...pairs) {
     return { assign: Object.assign({}, ...pairs) };
 }
 
+/**
+ * Compile-time loop expansion: generates one entry per key from a factory function.
+ */
+export function forEachKeyIn(keys, factory, options) {
+    const $ = paths(options);
+    return keys.map(key => factory(key, $));
+}
+
 /**
  * Tagged template literal that splits a template into an array of parts.
  * Path proxy objects are auto-detected and converted to path strings.

package/paths.ts

@@ -53,6 +53,44 @@ export interface PathsOptions {
     withMethods?: string[] | Set<string>;
 }
 
+/**
+ * Create a proxy for id-ref paths (#[varName]).
+ * After the initial #[varName], further property access chains with ?. from the resolved element.
+ * .path returns the #[varName] prefix (optionally with further ?. path).
+ */
+function createIdRefProxy(idRef: string, options?: PathsOptions): any {
+    function handler() {}
+    return new Proxy(handler, {
+        get(_, prop: string | symbol) {
+            if (prop === 'path' || prop === PATH_SYMBOL) {
+                return idRef;
+            }
+            if (typeof prop === 'symbol') return undefined;
+
+            // Chain further path segments after the id ref
+            const chained = `${idRef}?.${String(prop)}`;
+            return createIdRefProxy(chained, options);
+        },
+        apply(_, __, args) {
+            if (args.length > 0) {
+                const arg = args[0];
+                let argStr: string;
+                if (arg === true) argStr = 'true';
+                else if (arg === false) argStr = 'false';
+                else if (arg && typeof arg === 'object' && PATH_SYMBOL in arg) {
+                    const fullPath = arg[PATH_SYMBOL] as string;
+                    argStr = fullPath.startsWith('?.') ? fullPath.substring(2) : fullPath;
+                }
+                else argStr = String(arg);
+
+                const chained = `${idRef}?.${argStr}`;
+                return createIdRefProxy(chained, options);
+            }
+            return createIdRefProxy(idRef, options);
+        }
+    });
+}
+
 /**
  * Create a recursive proxy that records property access paths.
  * Supports both property access and method call syntax (via apply trap on function target).
@@ -74,8 +112,17 @@ function createPathProxy(prefix: string, options?: PathsOptions): any {
             // Ignore symbol access (Symbol.iterator, Symbol.toPrimitive, etc.)
             if (typeof prop === 'symbol') return undefined;
 
-            // Apply reverse alias: if prop matches an alias value, use the alias key
             let segment = String(prop);
+
+            // #-prefix: $['#firstName'] → '#[firstName]' (cached element ref)
+            if (segment.startsWith('#')) {
+                const varName = segment.substring(1);
+                const idRef = `#[${varName}]`;
+                // Return a proxy that starts from this id ref (can chain further with ?.)
+                return createIdRefProxy(idRef, options);
+            }
+
+            // Apply reverse alias: if prop matches an alias value, use the alias key
             if (aliasMap) {
                 for (const [alias, target] of Object.entries(aliasMap)) {
                     if (target === segment) { segment = alias; break; }
@@ -222,6 +269,38 @@ export function smoothOver(value: any): any {
 export function doAssign(...pairs: Record<string, any>[]): { assign: Record<string, any> } {
     return { assign: Object.assign({}, ...pairs) };
 }
+
+/**
+ * Compile-time loop expansion: generates one entry per key from a factory function.
+ * Creates a typed proxy internally — the factory receives both the key and the proxy.
+ * 
+ * @param keys - Array of property names to iterate (type-checked against T)
+ * @param factory - Function that produces a config entry for each key
+ * @param options - Optional PathsOptions (aka, withMethods) for the internal proxy
+ * @returns Array of factory results (one per key) — spread into merges array
+ * 
+ * @example
+ * import { forEachKeyIn, set, doAssign } from 'assign-gingerly/paths.js';
+ * 
+ * interface Person extends HTMLElement { firstName: string; lastName: string; }
+ * 
+ * const merges = [
+ *     ...forEachKeyIn<Person>(['firstName', 'lastName'], (key, $) => ({
+ *         ifKeyIn: [key],
+ *         assignOptions: { withIds: { [key]: { qry: `[name="${key}"]` } } },
+ *         ...doAssign(set($['#' + key]).to($[key]))
+ *     })),
+ * ];
+ */
+export function forEachKeyIn<T>(
+    keys: (keyof T & string)[],
+    factory: (key: keyof T & string, proxy: PathProxy<T>) => any,
+    options?: PathsOptions
+): any[] {
+    const $ = paths<T>(options);
+    return keys.map(key => factory(key, $));
+}
+
 /**
  * Tagged template literal that splits a template into an array of parts.
  * Interleaves static string segments with interpolated values.

package/processHandlerCommands.js

@@ -5,6 +5,7 @@
  */
 import { resolveValues } from './resolveValues.js';
 import { evaluatePathWithMethods } from './assignGingerly.js';
+import { isAllowedImportPath } from './isAllowedImportPath.js';
 /**
  * Map of built-in handler names to their module paths.
  * These are auto-loaded on demand — no explicit import required.
@@ -15,22 +16,17 @@ const BUILT_IN_MAP = {
     'builtIns.join': './handlers/join.js',
     'builtIns.microDataJoin': './handlers/microDataJoin.js',
 };
-/**
- * Check if an import path is allowed (non-cross-domain).
- */
-function isAllowedImportPath(path) {
-    return path.startsWith('./') || path.startsWith('../') || path.startsWith('/')
-        || (!path.includes('://') && !path.startsWith('//'));
-}
 /**
  * Find a handler class in a dynamically imported module.
  * Checks default export first, then searches for the first class with `assign` on prototype.
  */
 function findHandlerInModule(module) {
+    // Check default export first
     if (module.default && typeof module.default === 'function'
         && module.default.prototype && 'assign' in module.default.prototype) {
         return module.default;
     }
+    // Search other exports
     for (const key of Object.keys(module)) {
         const exported = module[key];
         if (typeof exported === 'function' && exported.prototype && 'assign' in exported.prototype) {
@@ -41,6 +37,7 @@ function findHandlerInModule(module) {
 }
 /**
  * Dynamically load a built-in handler by name.
+ * Returns the handler constructor, or undefined if the name isn't a recognized built-in.
  */
 async function loadBuiltIn(name) {
     const path = BUILT_IN_MAP[name];
@@ -52,26 +49,25 @@ async function loadBuiltIn(name) {
 /**
  * Resolve a handler from options.handlers (class constructor or import path).
  */
-async function resolveFromHandlers(name, handlers) {
+async function resolveFromHandlers(name, handlers, permissions) {
     if (!handlers || !(name in handlers))
         return undefined;
     const entry = handlers[name];
+    // Class constructor — use directly
     if (typeof entry === 'function') {
         return entry;
     }
+    // Import path string — validate and dynamically import
     if (typeof entry === 'string') {
-        if (!isAllowedImportPath(entry)) {
-            throw new Error(
-                `assignFrom: handler "${name}" has an invalid import path "${entry}". ` +
-                `Only relative, absolute, or bare specifier paths are allowed (no cross-domain URLs).`
-            );
+        if (!permissions?.crossDomainImports && !isAllowedImportPath(entry)) {
+            throw new Error(`assignFrom: handler "${name}" has an invalid import path "${entry}". ` +
+                `Only relative, absolute, or bare specifier paths are allowed (no cross-domain URLs). ` +
+                `Pass { crossDomainImports: true } in permissions to override.`);
         }
         const module = await import(entry);
         const HandlerClass = findHandlerInModule(module);
         if (!HandlerClass) {
-            throw new Error(
-                `assignFrom: handler "${name}" — module "${entry}" does not export a valid handler class.`
-            );
+            throw new Error(`assignFrom: handler "${name}" — module "${entry}" does not export a valid handler class.`);
         }
         return HandlerClass;
     }
@@ -84,8 +80,9 @@ async function resolveFromHandlers(name, handlers) {
  * @param handlerKeys - Array of keys ending with ' =>'
  * @param pattern - The original pattern object
  * @param options - The assignFrom options
+ * @param handlerRegistry - The registry of handler classes
  */
-export async function processHandlerCommands(target, handlerKeys, pattern, options) {
+export async function processHandlerCommands(target, handlerKeys, pattern, options, permissions) {
     for (const key of handlerKeys) {
         const lhsPath = key.substring(0, key.length - 3); // Remove ' =>'
         const rhs = pattern[key];
@@ -104,6 +101,7 @@ export async function processHandlerCommands(target, handlerKeys, pattern, optio
         if (configs.length === 0)
             continue;
         // Resolve the LHS path, preserving parent + key for return-value assignment.
+        // lhsParent[lhsKey] === lhsTarget (the current value at the path)
         let lhsTarget;
         let lhsParent = undefined;
         let lhsKey = undefined;
@@ -119,13 +117,15 @@ export async function processHandlerCommands(target, handlerKeys, pattern, optio
                 lhsParent = result.target;
                 lhsKey = result.lastKey;
                 lhsTarget = result.target[result.lastKey];
+                // If last key is a method, call it to get the target
                 if (result.isMethod && typeof result.target[result.lastKey] === 'function') {
                     lhsTarget = result.target[result.lastKey].call(result.target);
-                    lhsParent = undefined;
+                    lhsParent = undefined; // Can't assign back to a method call result
                     lhsKey = undefined;
                 }
             }
             else {
+                // Simple path navigation — walk to parent, keep last key
                 if (pathParts.length === 0) {
                     lhsTarget = target;
                 }
@@ -158,7 +158,7 @@ export async function processHandlerCommands(target, handlerKeys, pattern, optio
         // Execute handlers sequentially, sharing the same lhsTarget
         for (const config of configs) {
             // 1. Check options.handlers (local, per-call)
-            let HandlerClass = await resolveFromHandlers(config.do, options.handlers);
+            let HandlerClass = await resolveFromHandlers(config.do, options.handlers, permissions);
             // 2. Fallback to built-in auto-load
             if (!HandlerClass && config.do.startsWith('builtIns.')) {
                 HandlerClass = await loadBuiltIn(config.do);

package/processHandlerCommands.ts

@@ -6,6 +6,8 @@
 
 import { resolveValues } from './resolveValues.js';
 import { evaluatePathWithMethods } from './assignGingerly.js';
+import { isAllowedImportPath } from './isAllowedImportPath.js';
+import type { AssignPermissions } from './isAllowedImportPath.js';
 import type { AssignFromOptions, AssignFromHandlerConstructor } from './assignFrom.js';
 
 /**
@@ -19,14 +21,6 @@ const BUILT_IN_MAP: Record<string, string> = {
     'builtIns.microDataJoin': './handlers/microDataJoin.js',
 };
 
-/**
- * Check if an import path is allowed (non-cross-domain).
- */
-function isAllowedImportPath(path: string): boolean {
-    return path.startsWith('./') || path.startsWith('../') || path.startsWith('/')
-        || (!path.includes('://') && !path.startsWith('//'));
-}
-
 /**
  * Find a handler class in a dynamically imported module.
  * Checks default export first, then searches for the first class with `assign` on prototype.
@@ -63,7 +57,8 @@ async function loadBuiltIn(name: string): Promise<AssignFromHandlerConstructor |
  */
 async function resolveFromHandlers(
     name: string,
-    handlers: Record<string, AssignFromHandlerConstructor | string> | undefined
+    handlers: Record<string, AssignFromHandlerConstructor | string> | undefined,
+    permissions?: AssignPermissions
 ): Promise<AssignFromHandlerConstructor | undefined> {
     if (!handlers || !(name in handlers)) return undefined;
 
@@ -76,10 +71,11 @@ async function resolveFromHandlers(
 
     // Import path string — validate and dynamically import
     if (typeof entry === 'string') {
-        if (!isAllowedImportPath(entry)) {
+        if (!permissions?.crossDomainImports && !isAllowedImportPath(entry)) {
             throw new Error(
                 `assignFrom: handler "${name}" has an invalid import path "${entry}". ` +
-                `Only relative, absolute, or bare specifier paths are allowed (no cross-domain URLs).`
+                `Only relative, absolute, or bare specifier paths are allowed (no cross-domain URLs). ` +
+                `Pass { crossDomainImports: true } in permissions to override.`
             );
         }
         const module = await import(entry);
@@ -108,7 +104,8 @@ export async function processHandlerCommands(
     target: any,
     handlerKeys: string[],
     pattern: Record<string, any>,
-    options: AssignFromOptions
+    options: AssignFromOptions,
+    permissions?: AssignPermissions
 ): Promise<void> {
     for (const key of handlerKeys) {
         const lhsPath = key.substring(0, key.length - 3); // Remove ' =>'
@@ -185,7 +182,7 @@ export async function processHandlerCommands(
         // Execute handlers sequentially, sharing the same lhsTarget
         for (const config of configs) {
             // 1. Check options.handlers (local, per-call)
-            let HandlerClass = await resolveFromHandlers(config.do, options.handlers);
+            let HandlerClass = await resolveFromHandlers(config.do, options.handlers, permissions);
 
             // 2. Fallback to built-in auto-load
             if (!HandlerClass && config.do.startsWith('builtIns.')) {