assign-gingerly 0.0.74 → 0.0.76

package/DX/installForwarding.js

@@ -20,7 +20,7 @@
  * installForwarding(ClubMember);
  * // Now el.command delegates to el.behaviors.commandBehavior.command
  */
-import { resolveValue } from '../resolveValues.js';
+import { resolveValue } from '../resolve/resolveValues.js';
 import assignGingerly from '../assignGingerly.js';
 /**
  * Installs property forwarding on a class prototype based on `static propLinks`.

package/DX/installForwarding.ts

@@ -21,7 +21,7 @@
  * // Now el.command delegates to el.behaviors.commandBehavior.command
  */
 
-import { resolveValue} from '../resolveValues.js';
+import { resolveValue} from '../resolve/resolveValues.js';
 import {ResolveValuesOptions, IAssignGingerlyOptions} from '../types/assign-gingerly/types.js';
 import assignGingerly, {  } from '../assignGingerly.js';
 

package/README.md

@@ -54,6 +54,8 @@ So in our view this package helps fill the void left by not supporting the "is"
 
 Anyway, let's start out detailing the more innocent features of this package / polyfill.
 
+Because the same declarative input can come from sources that aren't fully trusted — HTML attributes, user JSON, remote config — the package also provides an **opt-in permission layer** to block or redirect dangerous property assignments.  See [docs/assign-permissions.md](docs/assign-permissions.md) for how to construct and pass a `PermissionProcessor`.
+
 The three utility functions are:
 
 ## assignGingerly

package/assignFrom.js

@@ -8,9 +8,9 @@
  *
  * Handler commands (` =>`) are fire-and-forget (kicked off asynchronously, not awaited).
  */
-import { getValues, getValue } from './getValues.js';
+import { getValues, getValue } from './resolve/getValues.js';
 import assignGingerly from './assignGingerly.js';
-import { resolveIdVariable, parseIdRef } from './resolveIdRef.js';
+import { resolveIdVariable, parseIdRef } from './resolve/resolveIdRef.js';
 import { processInferredAssignments } from './inferredAssignments.js';
 /**
  * Supported substitution variables and their option keys.
@@ -377,7 +377,7 @@ function getEffectiveIds(options) {
 /**
  * Process #[x] normal keys synchronously.
  */
-function processIdRefNormalKeys(idRefNormalKeys, expandedPattern, target, options, permissions) {
+function processIdRefNormalKeys(idRefNormalKeys, expandedPattern, target, options, permissionProcessor) {
     const ids = getEffectiveIds(options);
     if (!ids)
         return;
@@ -391,13 +391,13 @@ function processIdRefNormalKeys(idRefNormalKeys, expandedPattern, target, option
             continue;
         const value = expandedPattern[key];
         if (parsed.remainingPath) {
-            const resolvedValue = getValues({ __v: value }, from, { withMethods, aka, akaMethods, protocols, root: target });
-            assignGingerly(el, { [parsed.remainingPath]: resolvedValue.__v }, options, permissions);
+            const resolvedValue = getValues({ __v: value }, from, { withMethods, aka, akaMethods, protocols, root: target, permissionProcessor });
+            assignGingerly(el, { [parsed.remainingPath]: resolvedValue.__v }, options, permissionProcessor);
         }
         else {
-            const resolvedValue = getValues(typeof value === 'object' && value !== null ? value : { __v: value }, from, { withMethods, aka, akaMethods, protocols, root: target });
+            const resolvedValue = getValues(typeof value === 'object' && value !== null ? value : { __v: value }, from, { withMethods, aka, akaMethods, protocols, root: target, permissionProcessor });
             if (!('__v' in resolvedValue)) {
-                assignGingerly(el, resolvedValue, options, permissions);
+                assignGingerly(el, resolvedValue, options, permissionProcessor);
             }
         }
     }
@@ -411,15 +411,15 @@ function processIdRefNormalKeys(idRefNormalKeys, expandedPattern, target, option
  * @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)
- * @param permissions - Optional security permissions
+ * @param permissionProcessor - Optional security permissionProcessor
  * @returns The target object after merging
  */
-export function assignFrom(target, pattern, options, permissions) {
+export function assignFrom(target, pattern, options, permissionProcessor) {
     // Expand looped substitution variables
     const expandedPattern = expandSubstitutions(pattern, options);
     // Categorize keys
     const { handlerKeys, normalPattern, idRefNormalKeys, idRefHandlerKeys, ternaryKeys } = categorizeKeys(expandedPattern);
-    const resolveOptions = { ...options, root: target };
+    const resolveOptions = { ...options, root: target, permissionProcessor };
     // Process ?= ternary keys (sync)
     if (ternaryKeys.length > 0) {
         const ternaryResolved = {};
@@ -436,7 +436,7 @@ export function assignFrom(target, pattern, options, permissions) {
             }
         }
         if (Object.keys(ternaryResolved).length > 0) {
-            assignGingerly(target, ternaryResolved, options, permissions);
+            assignGingerly(target, ternaryResolved, options, permissionProcessor);
         }
     }
     // Process normal keys via getValues (sync) + assignGingerly
@@ -459,7 +459,8 @@ export function assignFrom(target, pattern, options, permissions) {
                                     aka: options.aka,
                                     akaMethods: options.akaMethods,
                                     protocols: options.protocols,
-                                    root: target
+                                    root: target,
+                                    permissionProcessor
                                 });
                             }
                             else {
@@ -472,16 +473,16 @@ export function assignFrom(target, pattern, options, permissions) {
         }
         const resolved = getValues(normalPattern, options.from, resolveOptions);
         handleSpreads(resolved);
-        assignGingerly(target, resolved, options, permissions);
+        assignGingerly(target, resolved, options, permissionProcessor);
     }
     // Process #[x] normal keys (sync)
     if (idRefNormalKeys.length > 0) {
-        processIdRefNormalKeys(idRefNormalKeys, expandedPattern, target, options, permissions);
+        processIdRefNormalKeys(idRefNormalKeys, expandedPattern, target, options, permissionProcessor);
     }
     // Process handler commands — fire-and-forget (async)
     if (handlerKeys.length > 0) {
         import('./processHandlerCommands.js').then(({ processHandlerCommands }) => {
-            processHandlerCommands(target, handlerKeys, expandedPattern, options, permissions);
+            processHandlerCommands(target, handlerKeys, expandedPattern, options, permissionProcessor);
         });
     }
     // Process #[x] handler keys — fire-and-forget (async)
@@ -497,7 +498,7 @@ export function assignFrom(target, pattern, options, permissions) {
                     continue;
                 const syntheticKey = parsed.remainingPath ? `${parsed.remainingPath} =>` : ' =>';
                 const syntheticPattern = { [syntheticKey]: expandedPattern[key] };
-                processHandlerCommands(el, [syntheticKey], syntheticPattern, options, permissions);
+                processHandlerCommands(el, [syntheticKey], syntheticPattern, options, permissionProcessor);
             }
         });
     }
@@ -517,7 +518,7 @@ export function assignFrom(target, pattern, options, permissions) {
     // Process bulk enhancements — fire-and-forget (async)
     if (options.enhance && options.enhance.length > 0) {
         import('./enhanceAll.js').then(({ enhanceAll }) => {
-            enhanceAll(target, options.enhance, permissions);
+            enhanceAll(target, options.enhance, permissionProcessor);
         });
     }
     return target;

package/assignFrom.ts

@@ -9,12 +9,11 @@
  * Handler commands (` =>`) are fire-and-forget (kicked off asynchronously, not awaited).
  */
 
-import { getValues, getValue } from './getValues.js';
+import { getValues, getValue } from './resolve/getValues.js';
 import assignGingerly from './assignGingerly.js';
-import { resolveIdVariable, parseIdRef } from './resolveIdRef.js';
+import { resolveIdVariable, parseIdRef } from './resolve/resolveIdRef.js';
 import { processInferredAssignments } from './inferredAssignments.js';
-import type { AssignPermissions } from './types/assign-gingerly/types.js';
-import type { AssignFromOptions, AssignFromHandler, AssignFromHandlerConstructor } from './types/assign-gingerly/types.js';
+import type { PermissionProcessor, AssignFromOptions, AssignFromHandler, AssignFromHandlerConstructor } from './types/assign-gingerly/types.js';
 
 // Re-export types for consumers
 export type { AssignFromOptions, AssignFromHandler, AssignFromHandlerConstructor };
@@ -387,11 +386,11 @@ function getEffectiveIds(options: AssignFromOptions): Record<string, any> | unde
  * Process #[x] normal keys synchronously.
  */
 function processIdRefNormalKeys(
-  idRefNormalKeys: string[],
-  expandedPattern: Record<string, any>,
-  target: any,
-  options: AssignFromOptions,
-  permissions?: AssignPermissions
+  idRefNormalKeys: string[],
+  expandedPattern: Record<string, any>,
+  target: any,
+  options: AssignFromOptions,
+  permissionProcessor?: PermissionProcessor
 ): void {
   const ids = getEffectiveIds(options);
   if (!ids) return;
@@ -408,17 +407,17 @@ function processIdRefNormalKeys(
     if (parsed.remainingPath) {
       const resolvedValue = getValues(
         { __v: value }, from,
-        { withMethods, aka, akaMethods, protocols, root: target }
+        { withMethods, aka, akaMethods, protocols, root: target, permissionProcessor }
       );
-      assignGingerly(el, { [parsed.remainingPath]: resolvedValue.__v }, options, permissions);
+      assignGingerly(el, { [parsed.remainingPath]: resolvedValue.__v }, options, permissionProcessor);
     } else {
       const resolvedValue = getValues(
         typeof value === 'object' && value !== null ? value : { __v: value },
         from,
-        { withMethods, aka, akaMethods, protocols, root: target }
+        { withMethods, aka, akaMethods, protocols, root: target, permissionProcessor }
       );
       if (!('__v' in resolvedValue)) {
-        assignGingerly(el, resolvedValue, options, permissions);
+        assignGingerly(el, resolvedValue, options, permissionProcessor);
       }
     }
   }
@@ -433,14 +432,14 @@ function processIdRefNormalKeys(
  * @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)
- * @param permissions - Optional security permissions
+ * @param permissionProcessor - Optional security permissionProcessor
  * @returns The target object after merging
  */
 export function assignFrom(
   target: any,
   pattern: Record<string, any>,
   options: AssignFromOptions,
-  permissions?: AssignPermissions
+  permissionProcessor?: PermissionProcessor
 ): any {
   // Expand looped substitution variables
   const expandedPattern = expandSubstitutions(pattern, options);
@@ -448,7 +447,7 @@ export function assignFrom(
   // Categorize keys
   const { handlerKeys, normalPattern, idRefNormalKeys, idRefHandlerKeys, ternaryKeys } = categorizeKeys(expandedPattern);
 
-  const resolveOptions = { ...options, root: target } as any;
+  const resolveOptions = { ...options, root: target, permissionProcessor } as any;
 
   // Process ?= ternary keys (sync)
   if (ternaryKeys.length > 0) {
@@ -464,7 +463,7 @@ export function assignFrom(
       }
     }
     if (Object.keys(ternaryResolved).length > 0) {
-      assignGingerly(target, ternaryResolved, options, permissions);
+      assignGingerly(target, ternaryResolved, options, permissionProcessor);
     }
   }
 
@@ -488,7 +487,8 @@ export function assignFrom(
                   aka: options.aka,
                   akaMethods: options.akaMethods,
                   protocols: options.protocols,
-                  root: target
+                  root: target,
+                  permissionProcessor
                 });
               } else {
                 normalPattern[key] = el.id; // bare #[x] → ID string
@@ -502,18 +502,18 @@ export function assignFrom(
     const resolved = getValues(normalPattern, options.from, resolveOptions);
 
     handleSpreads(resolved);
-    assignGingerly(target, resolved, options, permissions);
+    assignGingerly(target, resolved, options, permissionProcessor);
   }
 
   // Process #[x] normal keys (sync)
   if (idRefNormalKeys.length > 0) {
-    processIdRefNormalKeys(idRefNormalKeys, expandedPattern, target, options, permissions);
+    processIdRefNormalKeys(idRefNormalKeys, expandedPattern, target, options, permissionProcessor);
   }
 
   // Process handler commands — fire-and-forget (async)
   if (handlerKeys.length > 0) {
     import('./processHandlerCommands.js').then(({ processHandlerCommands }) => {
-      processHandlerCommands(target, handlerKeys, expandedPattern, options, permissions);
+      processHandlerCommands(target, handlerKeys, expandedPattern, options, permissionProcessor);
     });
   }
 
@@ -528,7 +528,7 @@ export function assignFrom(
         if (!el) continue;
         const syntheticKey = parsed.remainingPath ? `${parsed.remainingPath} =>` : ' =>';
         const syntheticPattern = { [syntheticKey]: expandedPattern[key] };
-        processHandlerCommands(el, [syntheticKey], syntheticPattern, options, permissions);
+        processHandlerCommands(el, [syntheticKey], syntheticPattern, options, permissionProcessor);
       }
     });
   }
@@ -551,7 +551,7 @@ export function assignFrom(
   // Process bulk enhancements — fire-and-forget (async)
   if (options.enhance && options.enhance.length > 0) {
     import('./enhanceAll.js').then(({ enhanceAll }) => {
-      enhanceAll(target, options.enhance!, permissions);
+      enhanceAll(target, options.enhance!, permissionProcessor);
     });
   }
 

package/assignFromAsync.js

@@ -19,12 +19,12 @@
  * }, { from: source });
  * // target is now { color: 'red', text: 'Hello' }
  */
-import { resolveValues } from './resolveValues.js';
+import { resolveValues } from './resolve/resolveValues.js';
 import assignGingerly from './assignGingerly.js';
 import { expandSubstitutions, categorizeKeys, handleSpreads } from './assignFrom.js';
 // Module cache for processHandlerCommands — avoids await on dynamic import after first call
 let _processHandlerCommands;
-export async function assignFromAsync(target, pattern, options, permissions) {
+export async function assignFromAsync(target, pattern, options, permissionProcessor) {
     // First: expand looped substitution variables (${x}, ${y}, ${z})
     const expandedPattern = expandSubstitutions(pattern, options);
     // Categorize keys
@@ -36,16 +36,17 @@ export async function assignFromAsync(target, pattern, options, permissions) {
             aka: options.aka,
             akaMethods: options.akaMethods,
             protocols: options.protocols,
-            root: target
+            root: target,
+            permissionProcessor
         });
         // Recursively handle "..." spread keys at all nesting levels
         handleSpreads(resolved);
-        assignGingerly(target, resolved, options, permissions);
+        assignGingerly(target, resolved, options, permissionProcessor);
     }
     // Process #[x] normal keys — resolve element, then apply remaining path + value
     if (idRefNormalKeys.length > 0 && (options.pin || options.at)) {
         const ids = { ...options.pin, ...options.at };
-        const { resolveIdVariable, parseIdRef } = await import('./resolveIdRef.js');
+        const { resolveIdVariable, parseIdRef } = await import('./resolve/resolveIdRef.js');
         const { withMethods, aka, akaMethods, protocols, from } = options;
         for (const key of idRefNormalKeys) {
             const parsed = parseIdRef(key);
@@ -57,18 +58,18 @@ export async function assignFromAsync(target, pattern, options, permissions) {
             const value = expandedPattern[key];
             if (parsed.remainingPath) {
                 // Resolve the RHS value
-                const resolvedValue = await resolveValues({ __v: value }, from, { withMethods, aka, akaMethods, protocols, root: el });
+                const resolvedValue = await resolveValues({ __v: value }, from, { withMethods, aka, akaMethods, protocols, root: el, permissionProcessor });
                 // Apply remaining path on the resolved element
-                assignGingerly(el, { [parsed.remainingPath]: resolvedValue.__v }, options, permissions);
+                assignGingerly(el, { [parsed.remainingPath]: resolvedValue.__v }, options, permissionProcessor);
             }
             else {
                 // No remaining path — resolve and assign directly to the element
-                const resolvedValue = await resolveValues(typeof value === 'object' && value !== null ? value : { __v: value }, from, { withMethods, aka, akaMethods, protocols, root: el });
+                const resolvedValue = await resolveValues(typeof value === 'object' && value !== null ? value : { __v: value }, from, { withMethods, aka, akaMethods, protocols, root: el, permissionProcessor });
                 if ('__v' in resolvedValue) {
                     // Single value — can't assign to element root without a path
                 }
                 else {
-                    assignGingerly(el, resolvedValue, options, permissions);
+                    assignGingerly(el, resolvedValue, options, permissionProcessor);
                 }
             }
         }
@@ -76,12 +77,12 @@ export async function assignFromAsync(target, pattern, options, permissions) {
     // 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);
+        await _processHandlerCommands(target, handlerKeys, expandedPattern, options, permissionProcessor);
     }
     // Process #[x] handler keys — resolve element, then pass to handler processing
     if (idRefHandlerKeys.length > 0 && (options.pin || options.at)) {
         const ids = { ...options.pin, ...options.at };
-        const { resolveIdVariable, parseIdRef } = await import('./resolveIdRef.js');
+        const { resolveIdVariable, parseIdRef } = await import('./resolve/resolveIdRef.js');
         _processHandlerCommands ??= (await import('./processHandlerCommands.js')).processHandlerCommands;
         for (const key of idRefHandlerKeys) {
             const parsed = parseIdRef(key);
@@ -98,7 +99,7 @@ export async function assignFromAsync(target, pattern, options, permissions) {
             const syntheticPattern = {
                 [syntheticKey]: expandedPattern[key]
             };
-            await _processHandlerCommands(el, [syntheticKey], syntheticPattern, options, permissions);
+            await _processHandlerCommands(el, [syntheticKey], syntheticPattern, options, permissionProcessor);
         }
     }
     // Process inferred assignments — dynamically imported only when option is present
@@ -117,7 +118,7 @@ export async function assignFromAsync(target, pattern, options, permissions) {
     // 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);
+        await enhanceAll(target, options.enhance, permissionProcessor);
     }
     return target;
 }

package/assignFromAsync.ts

@@ -19,11 +19,10 @@
  * }, { from: source });
  * // target is now { color: 'red', text: 'Hello' }
  */
-import { resolveValues } from './resolveValues.js';
+import { resolveValues } from './resolve/resolveValues.js';
 import {IAssignGingerlyOptions} from './types/assign-gingerly/types.js';
 import assignGingerly from './assignGingerly.js';
-import type { AssignPermissions } from './types/assign-gingerly/types.js';
-import type { AssignFromHandler, AssignFromHandlerConstructor } from './types/assign-gingerly/types.js';
+import type { PermissionProcessor, AssignFromHandler, AssignFromHandlerConstructor } from './types/assign-gingerly/types.js';
 import {
   expandSubstitutions, categorizeKeys, handleSpreads, isHandlerCommand
 } from './assignFrom.js';
@@ -56,7 +55,7 @@ export async function assignFromAsync(
   target: any,
   pattern: Record<string, any>,
   options: AssignFromOptions,
-  permissions?: AssignPermissions
+  permissionProcessor?: PermissionProcessor
 ): Promise<any> {
   // First: expand looped substitution variables (${x}, ${y}, ${z})
   const expandedPattern = expandSubstitutions(pattern, options);
@@ -71,19 +70,20 @@ export async function assignFromAsync(
       aka: options.aka,
       akaMethods: options.akaMethods,
       protocols: options.protocols,
-      root: target
+      root: target,
+      permissionProcessor
     });
 
     // Recursively handle "..." spread keys at all nesting levels
     handleSpreads(resolved);
 
-    assignGingerly(target, resolved, options, permissions);
+    assignGingerly(target, resolved, options, permissionProcessor);
   }
 
   // Process #[x] normal keys — resolve element, then apply remaining path + value
   if (idRefNormalKeys.length > 0 && (options.pin || options.at)) {
     const ids = { ...options.pin, ...options.at };
-    const { resolveIdVariable, parseIdRef } = await import('./resolveIdRef.js');
+    const { resolveIdVariable, parseIdRef } = await import('./resolve/resolveIdRef.js');
     const { withMethods, aka, akaMethods, protocols, from } = options;
     for (const key of idRefNormalKeys) {
       const parsed = parseIdRef(key);
@@ -97,21 +97,21 @@ export async function assignFromAsync(
         // Resolve the RHS value
         const resolvedValue = await resolveValues(
           { __v: value }, from,
-          { withMethods, aka, akaMethods, protocols, root: el }
+          { withMethods, aka, akaMethods, protocols, root: el, permissionProcessor }
         );
         // Apply remaining path on the resolved element
-        assignGingerly(el, { [parsed.remainingPath]: resolvedValue.__v }, options, permissions);
+        assignGingerly(el, { [parsed.remainingPath]: resolvedValue.__v }, options, permissionProcessor);
       } else {
         // No remaining path — resolve and assign directly to the element
         const resolvedValue = await resolveValues(
           typeof value === 'object' && value !== null ? value : { __v: value },
           from,
-          { withMethods, aka, akaMethods, protocols, root: el }
+          { withMethods, aka, akaMethods, protocols, root: el, permissionProcessor }
         );
         if ('__v' in resolvedValue) {
           // Single value — can't assign to element root without a path
         } else {
-          assignGingerly(el, resolvedValue, options, permissions);
+          assignGingerly(el, resolvedValue, options, permissionProcessor);
         }
       }
     }
@@ -120,12 +120,12 @@ export async function assignFromAsync(
   if (handlerKeys.length > 0) {
     
     _processHandlerCommands ??= (await import('./processHandlerCommands.js')).processHandlerCommands;
-    await _processHandlerCommands(target, handlerKeys, expandedPattern, options, permissions);
+    await _processHandlerCommands(target, handlerKeys, expandedPattern, options, permissionProcessor);
   }
   // Process #[x] handler keys — resolve element, then pass to handler processing
   if (idRefHandlerKeys.length > 0 && (options.pin || options.at)) {
     const ids = { ...options.pin, ...options.at };
-    const { resolveIdVariable, parseIdRef } = await import('./resolveIdRef.js');
+    const { resolveIdVariable, parseIdRef } = await import('./resolve/resolveIdRef.js');
     _processHandlerCommands ??= (await import('./processHandlerCommands.js')).processHandlerCommands;
 
     for (const key of idRefHandlerKeys) {
@@ -145,7 +145,7 @@ export async function assignFromAsync(
         [syntheticKey]: expandedPattern[key]
       };
 
-      await _processHandlerCommands(el, [syntheticKey], syntheticPattern, options, permissions);
+      await _processHandlerCommands(el, [syntheticKey], syntheticPattern, options, permissionProcessor);
     }
   }
 
@@ -167,7 +167,7 @@ export async function assignFromAsync(
   // 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);
+    await enhanceAll(target, options.enhance, permissionProcessor);
   }
 
   return target;