assign-gingerly 0.0.54 → 0.0.56

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/markerUtils.js

@@ -0,0 +1,127 @@
+/**
+ * markerUtils.js — Shared utilities for comment marker management.
+ *
+ * Used by lazyLoad, microDataJoin, and future template loop handlers.
+ */
+
+export const MARKER_START_PREFIX = '?start name="';
+export const MARKER_END = '?end';
+
+/**
+ * Find existing start/end comment markers (TreeWalker approach).
+ */
+export function findMarkers(target, name) {
+    const startText = `${MARKER_START_PREFIX}${name}"`;
+    let startMarker = null;
+    let endMarker = null;
+
+    const walker = document.createTreeWalker(target, NodeFilter.SHOW_COMMENT);
+    let node;
+    while ((node = walker.nextNode())) {
+        if (!startMarker && node.data === startText) {
+            startMarker = node;
+        } else if (startMarker && !endMarker && node.data === MARKER_END) {
+            endMarker = node;
+            break;
+        }
+    }
+
+    return [startMarker, endMarker];
+}
+
+/**
+ * Find existing start/end comment markers (XPath approach).
+ */
+export function findMarkersXPath(target, name) {
+    const startText = `${MARKER_START_PREFIX}${name}"`;
+
+    const startResult = document.evaluate(
+        `.//comment()[. = "${startText}"]`,
+        target,
+        null,
+        XPathResult.FIRST_ORDERED_NODE_TYPE,
+        null
+    );
+    const startMarker = startResult.singleNodeValue;
+    if (!startMarker) return [null, null];
+
+    const endResult = document.evaluate(
+        `following-sibling::comment()[. = "${MARKER_END}"][1]`,
+        startMarker,
+        null,
+        XPathResult.FIRST_ORDERED_NODE_TYPE,
+        null
+    );
+    const endMarker = endResult.singleNodeValue;
+
+    return [startMarker, endMarker];
+}
+
+/**
+ * Create start/end markers and insert them into the target.
+ */
+export function createMarkers(target, name, method = 'appendChild') {
+    const startMarker = document.createComment(`${MARKER_START_PREFIX}${name}"`);
+    const endMarker = document.createComment(MARKER_END);
+
+    if (method === 'prepend') {
+        target.prepend(endMarker);
+        target.prepend(startMarker);
+    } else {
+        target.appendChild(startMarker);
+        target.appendChild(endMarker);
+    }
+
+    return [startMarker, endMarker];
+}
+
+/**
+ * Get all nodes between start and end markers.
+ */
+export function getNodesBetweenMarkers(start, end) {
+    const nodes = [];
+    let current = start.nextSibling;
+    while (current && current !== end) {
+        nodes.push(current);
+        current = current.nextSibling;
+    }
+    return nodes;
+}
+
+/**
+ * Find existing start/end comment markers among siblings of an anchor element.
+ * Used for 'after' insertion mode.
+ */
+export function findMarkersSibling(anchor, name) {
+    const startText = `${MARKER_START_PREFIX}${name}"`;
+    let startMarker = null;
+    let endMarker = null;
+
+    let current = anchor.nextSibling;
+    while (current) {
+        if (current.nodeType === Node.COMMENT_NODE) {
+            if (!startMarker && current.data === startText) {
+                startMarker = current;
+            } else if (startMarker && !endMarker && current.data === MARKER_END) {
+                endMarker = current;
+                break;
+            }
+        }
+        current = current.nextSibling;
+    }
+
+    return [startMarker, endMarker];
+}
+
+/**
+ * Create start/end markers as siblings after an anchor element.
+ * Used for 'after' insertion mode.
+ */
+export function createMarkersSibling(anchor, name) {
+    const startMarker = document.createComment(`${MARKER_START_PREFIX}${name}"`);
+    const endMarker = document.createComment(MARKER_END);
+
+    anchor.after(startMarker, endMarker);
+
+    return [startMarker, endMarker];
+}

package/markerUtils.ts

@@ -0,0 +1,162 @@
+/**
+ * markerUtils.ts — Shared utilities for comment marker management.
+ * 
+ * Used by lazyLoad, microDataJoin, and future template loop handlers.
+ * Provides finding, creating, and traversing comment marker pairs.
+ * 
+ * Markers are HTML comment nodes with specific content:
+ * - Start: <!--?start name="markerName"-->
+ * - End:   <!--?end-->
+ */
+
+export const MARKER_START_PREFIX = '?start name="';
+export const MARKER_END = '?end';
+
+/**
+ * Find existing start/end comment markers in a target element (TreeWalker approach).
+ * Searches the subtree of `target` for matching comment nodes.
+ * 
+ * @param target - The element to search within
+ * @param name - The marker name to find
+ * @returns [startMarker, endMarker] or [null, null] if not found
+ */
+export function findMarkers(target: Element | Node, name: string): [Comment | null, Comment | null] {
+    const startText = `${MARKER_START_PREFIX}${name}"`;
+    let startMarker: Comment | null = null;
+    let endMarker: Comment | null = null;
+
+    const walker = document.createTreeWalker(target as Node, NodeFilter.SHOW_COMMENT);
+    let node: Comment | null;
+    while ((node = walker.nextNode() as Comment | null)) {
+        if (!startMarker && node.data === startText) {
+            startMarker = node;
+        } else if (startMarker && !endMarker && node.data === MARKER_END) {
+            endMarker = node;
+            break;
+        }
+    }
+
+    return [startMarker, endMarker];
+}
+
+/**
+ * Find existing start/end comment markers using XPath (alternative approach).
+ * May be faster in large DOMs due to engine-level indexing.
+ * 
+ * @param target - The element to search within
+ * @param name - The marker name to find
+ * @returns [startMarker, endMarker] or [null, null] if not found
+ */
+export function findMarkersXPath(target: Element | Node, name: string): [Comment | null, Comment | null] {
+    const startText = `${MARKER_START_PREFIX}${name}"`;
+
+    const startResult = document.evaluate(
+        `.//comment()[. = "${startText}"]`,
+        target,
+        null,
+        XPathResult.FIRST_ORDERED_NODE_TYPE,
+        null
+    );
+    const startMarker = startResult.singleNodeValue as Comment | null;
+    if (!startMarker) return [null, null];
+
+    // Find the next sibling comment that is the end marker
+    const endResult = document.evaluate(
+        `following-sibling::comment()[. = "${MARKER_END}"][1]`,
+        startMarker,
+        null,
+        XPathResult.FIRST_ORDERED_NODE_TYPE,
+        null
+    );
+    const endMarker = endResult.singleNodeValue as Comment | null;
+
+    return [startMarker, endMarker];
+}
+
+/**
+ * Create start/end markers and insert them into the target.
+ * 
+ * @param target - The element to insert markers into
+ * @param name - The marker name
+ * @param method - 'appendChild' (default) or 'prepend'
+ * @returns [startMarker, endMarker]
+ */
+export function createMarkers(target: Element, name: string, method: string = 'appendChild'): [Comment, Comment] {
+    const startMarker = document.createComment(`${MARKER_START_PREFIX}${name}"`);
+    const endMarker = document.createComment(MARKER_END);
+
+    if (method === 'prepend') {
+        target.prepend(endMarker);
+        target.prepend(startMarker);
+    } else {
+        target.appendChild(startMarker);
+        target.appendChild(endMarker);
+    }
+
+    return [startMarker, endMarker];
+}
+
+/**
+ * Get all nodes between start and end markers.
+ * 
+ * @param start - The start comment marker
+ * @param end - The end comment marker
+ * @returns Array of nodes between the markers (exclusive of markers themselves)
+ */
+export function getNodesBetweenMarkers(start: Comment, end: Comment): Node[] {
+    const nodes: Node[] = [];
+    let current: Node | null = start.nextSibling;
+    while (current && current !== end) {
+        nodes.push(current);
+        current = current.nextSibling;
+    }
+    return nodes;
+}
+
+/**
+ * Find existing start/end comment markers among siblings of an anchor element.
+ * Used for 'after' insertion mode where markers are siblings, not children.
+ * 
+ * @param anchor - The element after which markers were inserted
+ * @param name - The marker name to find
+ * @returns [startMarker, endMarker] or [null, null] if not found
+ */
+export function findMarkersSibling(anchor: Element | Node, name: string): [Comment | null, Comment | null] {
+    const startText = `${MARKER_START_PREFIX}${name}"`;
+    let startMarker: Comment | null = null;
+    let endMarker: Comment | null = null;
+
+    let current: Node | null = anchor.nextSibling;
+    while (current) {
+        if (current.nodeType === Node.COMMENT_NODE) {
+            const comment = current as Comment;
+            if (!startMarker && comment.data === startText) {
+                startMarker = comment;
+            } else if (startMarker && !endMarker && comment.data === MARKER_END) {
+                endMarker = comment;
+                break;
+            }
+        }
+        current = current.nextSibling;
+    }
+
+    return [startMarker, endMarker];
+}
+
+/**
+ * Create start/end markers as siblings after an anchor element.
+ * Used for 'after' insertion mode.
+ * 
+ * @param anchor - The element to insert markers after
+ * @param name - The marker name
+ * @returns [startMarker, endMarker]
+ */
+export function createMarkersSibling(anchor: Element | Node, name: string): [Comment, Comment] {
+    const startMarker = document.createComment(`${MARKER_START_PREFIX}${name}"`);
+    const endMarker = document.createComment(MARKER_END);
+
+    // Insert after the anchor: anchor → startMarker → endMarker
+    (anchor as ChildNode).after(startMarker, endMarker);
+
+    return [startMarker, endMarker];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "assign-gingerly",
-  "version": "0.0.54",
+  "version": "0.0.56",
   "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,34 @@
       "default": "./paths.js",
       "types": "./paths.ts"
     },
+    "./enhanceAll.js": {
+      "default": "./enhanceAll.js",
+      "types": "./enhanceAll.ts"
+    },
+    "./isAllowedImportPath.js": {
+      "default": "./isAllowedImportPath.js",
+      "types": "./isAllowedImportPath.ts"
+    },
+    "./markerUtils.js": {
+      "default": "./markerUtils.js",
+      "types": "./markerUtils.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.