assign-gingerly 0.0.53 → 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.53",
+  "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"
@@ -60,6 +62,14 @@
       "default": "./resolveValues.js",
       "types": "./resolveValues.ts"
     },
+    "./resolveIdRef.js": {
+      "default": "./resolveIdRef.js",
+      "types": "./resolveIdRef.ts"
+    },
+    "./transitionHelper.js": {
+      "default": "./transitionHelper.js",
+      "types": "./transitionHelper.ts"
+    },
     "./installForwarding.js": {
       "default": "./installForwarding.js",
       "types": "./installForwarding.ts"
@@ -72,6 +82,50 @@
       "default": "./resolveAndAssignFeatures.js",
       "types": "./resolveAndAssignFeatures.ts"
     },
+    "./handlers/lazyLoad.js": {
+      "default": "./handlers/lazyLoad.js",
+      "types": "./handlers/lazyLoad.ts"
+    },
+    "./handlers/lazyLoadSwitch.js": {
+      "default": "./handlers/lazyLoadSwitch.js",
+      "types": "./handlers/lazyLoadSwitch.ts"
+    },
+    "./handlers/join.js": {
+      "default": "./handlers/join.js",
+      "types": "./handlers/join.ts"
+    },
+    "./handlers/microDataJoin.js": {
+      "default": "./handlers/microDataJoin.js",
+      "types": "./handlers/microDataJoin.ts"
+    },
+    "./paths.js": {
+      "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"
@@ -95,9 +149,9 @@
     "chrome": "npx playwright cr http://localhost:8000"
   },
   "devDependencies": {
-    "@playwright/test": "1.60.0",
+    "@playwright/test": "1.61.1",
     "spa-ssi": "0.0.27",
-    "@types/node": "25.9.3",
+    "@types/node": "26.1.0",
     "typescript": "6.0.3"
   }
 }

package/paths.js

@@ -0,0 +1,231 @@
+/**
+ * paths.js — Typed path proxy and template tags for assignFrom authoring.
+ *
+ * Provides compile-time autocomplete and type safety for `?.`-prefixed path strings.
+ * Supports method call syntax, alias reversal, and batch proxy extraction.
+ */
+
+/**
+ * Symbol used internally to detect path proxy objects.
+ */
+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.
+ */
+function createPathProxy(prefix, options) {
+    const aliasMap = options?.aka;
+
+    function handler() {}
+
+    return new Proxy(handler, {
+        get(_, prop) {
+            if (prop === 'path' || prop === PATH_SYMBOL) {
+                return prefix.length > 0 ? `?.${prefix}` : '?.';
+            }
+            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; }
+                }
+            }
+
+            const newPath = prefix ? `${prefix}?.${segment}` : segment;
+            return createPathProxy(newPath, 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 newPath = prefix ? `${prefix}?.${argStr}` : argStr;
+                return createPathProxy(newPath, options);
+            }
+            return createPathProxy(prefix, options);
+        }
+    });
+}
+
+/**
+ * Create a typed path proxy.
+ */
+export function paths(options) {
+    return createPathProxy('', options);
+}
+
+/**
+ * Create an assignment pair: { [lhs.path]: rhs.path }.
+ */
+export function set(lhs) {
+    const lhsStr = lhs && typeof lhs === 'object' && PATH_SYMBOL in lhs
+        ? lhs[PATH_SYMBOL]
+        : String(lhs);
+    return {
+        to(rhs) {
+            const rhsStr = rhs && typeof rhs === 'object' && PATH_SYMBOL in rhs
+                ? rhs[PATH_SYMBOL]
+                : rhs;
+            return { [lhsStr]: rhsStr };
+        }
+    };
+}
+
+/**
+ * Recursively walk a value and convert any path proxy objects to path strings.
+ */
+export function smoothOver(value) {
+    if (value && typeof value === 'object' && PATH_SYMBOL in value) {
+        return value[PATH_SYMBOL];
+    }
+    if (Array.isArray(value)) {
+        return value.map(smoothOver);
+    }
+    if (value && typeof value === 'object') {
+        const proto = Object.getPrototypeOf(value);
+        if (proto === Object.prototype || proto === null) {
+            const result = {};
+            for (const [k, v] of Object.entries(value)) {
+                result[k] = smoothOver(v);
+            }
+            return result;
+        }
+    }
+    return value;
+}
+
+/**
+ * Merge multiple set(...).to(...) pairs into an { assign: {...} } object.
+ * Spread the result into a merge config.
+ */
+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.
+ */
+export function sp(strings, ...values) {
+    const result = [];
+    for (let i = 0; i < strings.length; i++) {
+        if (strings[i]) result.push(strings[i]);
+        if (i < values.length) {
+            const v = values[i];
+            if (v && typeof v === 'object' && PATH_SYMBOL in v) {
+                result.push(v[PATH_SYMBOL]);
+            }
+            else if (Array.isArray(v)) {
+                result.push(v.map(el =>
+                    el && typeof el === 'object' && PATH_SYMBOL in el ? el[PATH_SYMBOL] : el
+                ));
+            }
+            else {
+                result.push(v);
+            }
+        }
+    }
+    return result;
+}
+
+/**
+ * Extract the last segment from a `?.`-prefixed path string.
+ */
+function extractPropName(pathStr) {
+    const parts = pathStr.split('?.');
+    return parts[parts.length - 1];
+}
+
+/**
+ * Tagged template literal that produces {prop, val} objects for microDataJoin.
+ */
+export function md(strings, ...values) {
+    const result = [];
+    for (let i = 0; i < strings.length; i++) {
+        if (strings[i]) result.push(strings[i]);
+        if (i < values.length) {
+            const v = values[i];
+            if (v && typeof v === 'object' && PATH_SYMBOL in v) {
+                const pathStr = v[PATH_SYMBOL];
+                result.push({ prop: extractPropName(pathStr), val: pathStr });
+            }
+            else if (Array.isArray(v)) {
+                result.push(v.map(el => {
+                    if (el && typeof el === 'object' && PATH_SYMBOL in el) {
+                        const pathStr = el[PATH_SYMBOL];
+                        return { prop: extractPropName(pathStr), val: pathStr };
+                    }
+                    return el;
+                }));
+            }
+            else if (v && typeof v === 'object' && 'prop' in v) {
+                const processed = { ...v };
+                if (processed.val && typeof processed.val === 'object' && PATH_SYMBOL in processed.val) {
+                    processed.val = processed.val[PATH_SYMBOL];
+                }
+                result.push(processed);
+            }
+            else {
+                result.push(v);
+            }
+        }
+    }
+    return result;
+}