assign-gingerly 0.0.82 → 0.0.83

package/README.md

@@ -100,7 +100,8 @@ assignFrom adds support for:
 3.  Protocol resolution (`globalThis://`, `localStorage://`, custom sync protocols).
 4.  Handler plugins via the ` =>` operator for custom logic (fire-and-forget in sync mode, awaitable in async mode).
 5.  Looped substitution with `where_x_in` / `where_y_in` / `where_z_in` for expanding template patterns into multiple concrete assignments.
-6.  Spread merging via the `"..."` key.
+6.  Dynamic substitutions via the `substitutions` option for injecting runtime string values into path segments. See [docs/substitutions.md](docs/substitutions.md).
+7.  Spread merging via the `"..."` key.
 
 Example:
 

package/assignFrom.js

@@ -49,6 +49,7 @@ function resolveTernaryValue(value, source, options) {
         return getValue(value, source, {
             withMethods: options.withMethods,
             aka: options.aka,
+            substitutions: options.substitutions,
             protocols: options.protocols,
             root: options.root
         });
@@ -61,6 +62,7 @@ function resolveTernaryValue(value, source, options) {
             return getValue(value, source, {
                 withMethods: options.withMethods,
                 aka: options.aka,
+                substitutions: options.substitutions,
                 protocols: options.protocols,
                 root: options.root
             });
@@ -381,7 +383,7 @@ function processIdRefNormalKeys(idRefNormalKeys, expandedPattern, target, option
     const ids = getEffectiveIds(options);
     if (!ids)
         return;
-    const { withMethods, aka, akaMethods, protocols, from } = options;
+    const { withMethods, aka, akaMethods, protocols, from, substitutions } = options;
     for (const key of idRefNormalKeys) {
         const parsed = parseIdRef(key);
         if (!parsed)
@@ -391,11 +393,11 @@ 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, permissionProcessor });
+            const resolvedValue = getValues({ __v: value }, from, { withMethods, aka, akaMethods, substitutions, 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, permissionProcessor });
+            const resolvedValue = getValues(typeof value === 'object' && value !== null ? value : { __v: value }, from, { withMethods, aka, akaMethods, substitutions, protocols, root: target, permissionProcessor });
             if (!('__v' in resolvedValue)) {
                 assignGingerly(el, resolvedValue, options, permissionProcessor);
             }
@@ -458,6 +460,7 @@ export function assignFrom(target, pattern, options, permissionProcessor) {
                                     withMethods: options.withMethods,
                                     aka: options.aka,
                                     akaMethods: options.akaMethods,
+                                    substitutions: options.substitutions,
                                     protocols: options.protocols,
                                     root: target,
                                     permissionProcessor

package/assignFrom.ts

@@ -58,6 +58,7 @@ function resolveTernaryValue(value: any, source: any, options: AssignFromOptions
         return getValue(value, source, {
             withMethods: options.withMethods,
             aka: options.aka,
+            substitutions: options.substitutions,
             protocols: options.protocols,
             root: options.root
         });
@@ -70,6 +71,7 @@ function resolveTernaryValue(value: any, source: any, options: AssignFromOptions
             return getValue(value, source, {
                 withMethods: options.withMethods,
                 aka: options.aka,
+                substitutions: options.substitutions,
                 protocols: options.protocols,
                 root: options.root
             });
@@ -395,7 +397,7 @@ function processIdRefNormalKeys(
   const ids = getEffectiveIds(options);
   if (!ids) return;
 
-  const { withMethods, aka, akaMethods, protocols, from } = options;
+  const { withMethods, aka, akaMethods, protocols, from, substitutions } = options;
   for (const key of idRefNormalKeys) {
     const parsed = parseIdRef(key);
     if (!parsed) continue;
@@ -407,14 +409,14 @@ function processIdRefNormalKeys(
     if (parsed.remainingPath) {
       const resolvedValue = getValues(
         { __v: value }, from,
-        { withMethods, aka, akaMethods, protocols, root: target, permissionProcessor }
+        { withMethods, aka, akaMethods, substitutions, 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, permissionProcessor }
+        { withMethods, aka, akaMethods, substitutions, protocols, root: target, permissionProcessor }
       );
       if (!('__v' in resolvedValue)) {
         assignGingerly(el, resolvedValue, options, permissionProcessor);
@@ -486,6 +488,7 @@ export function assignFrom(
                   withMethods: options.withMethods,
                   aka: options.aka,
                   akaMethods: options.akaMethods,
+                  substitutions: options.substitutions,
                   protocols: options.protocols,
                   root: target,
                   permissionProcessor

package/assignFromAsync.js

@@ -35,6 +35,7 @@ export async function assignFromAsync(target, pattern, options, permissionProces
             withMethods: options.withMethods,
             aka: options.aka,
             akaMethods: options.akaMethods,
+            substitutions: options.substitutions,
             protocols: options.protocols,
             root: target,
             permissionProcessor
@@ -47,7 +48,7 @@ export async function assignFromAsync(target, pattern, options, permissionProces
     if (idRefNormalKeys.length > 0 && (options.pin || options.at)) {
         const ids = { ...options.pin, ...options.at };
         const { resolveIdVariable, parseIdRef } = await import('./resolve/resolveIdRef.js');
-        const { withMethods, aka, akaMethods, protocols, from } = options;
+        const { withMethods, aka, akaMethods, protocols, from, substitutions } = options;
         for (const key of idRefNormalKeys) {
             const parsed = parseIdRef(key);
             if (!parsed)
@@ -58,13 +59,13 @@ export async function assignFromAsync(target, pattern, options, permissionProces
             const value = expandedPattern[key];
             if (parsed.remainingPath) {
                 // Resolve the RHS value
-                const resolvedValue = await resolveValues({ __v: value }, from, { withMethods, aka, akaMethods, protocols, root: el, permissionProcessor });
+                const resolvedValue = await resolveValues({ __v: value }, from, { withMethods, aka, akaMethods, substitutions, protocols, root: el, permissionProcessor });
                 // Apply remaining path on the resolved element
                 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, permissionProcessor });
+                const resolvedValue = await resolveValues(typeof value === 'object' && value !== null ? value : { __v: value }, from, { withMethods, aka, akaMethods, substitutions, protocols, root: el, permissionProcessor });
                 if ('__v' in resolvedValue) {
                     // Single value — can't assign to element root without a path
                 }

package/assignFromAsync.ts

@@ -69,6 +69,7 @@ export async function assignFromAsync(
       withMethods: options.withMethods,
       aka: options.aka,
       akaMethods: options.akaMethods,
+      substitutions: options.substitutions,
       protocols: options.protocols,
       root: target,
       permissionProcessor
@@ -84,7 +85,7 @@ export async function assignFromAsync(
   if (idRefNormalKeys.length > 0 && (options.pin || options.at)) {
     const ids = { ...options.pin, ...options.at };
     const { resolveIdVariable, parseIdRef } = await import('./resolve/resolveIdRef.js');
-    const { withMethods, aka, akaMethods, protocols, from } = options;
+    const { withMethods, aka, akaMethods, protocols, from, substitutions } = options;
     for (const key of idRefNormalKeys) {
       const parsed = parseIdRef(key);
       if (!parsed) continue;
@@ -97,7 +98,7 @@ export async function assignFromAsync(
         // Resolve the RHS value
         const resolvedValue = await resolveValues(
           { __v: value }, from,
-          { withMethods, aka, akaMethods, protocols, root: el, permissionProcessor }
+          { withMethods, aka, akaMethods, substitutions, protocols, root: el, permissionProcessor }
         );
         // Apply remaining path on the resolved element
         assignGingerly(el, { [parsed.remainingPath]: resolvedValue.__v }, options, permissionProcessor);
@@ -106,7 +107,7 @@ export async function assignFromAsync(
         const resolvedValue = await resolveValues(
           typeof value === 'object' && value !== null ? value : { __v: value },
           from,
-          { withMethods, aka, akaMethods, protocols, root: el, permissionProcessor }
+          { withMethods, aka, akaMethods, substitutions, protocols, root: el, permissionProcessor }
         );
         if ('__v' in resolvedValue) {
           // Single value — can't assign to element root without a path

package/inferencer/types/NewHTMLFirstCustomElement.md

@@ -303,13 +303,25 @@ const raConfig = {
     }
 }
 
+// withAttrs configuration for parsing element attributes
+const withAttrs = {
+    base: 'user-counter',
+    count: '${base}-count',
+    _count: {
+        instanceOf: 'Number',
+        valIfNull: 0,
+    },
+    username: '${base}-username',
+};
+
 /** @type {ElMakerConfig<AP>} */
 const features = {
     assignFeatures: {
         roundabout: {
             customData: {
                 raConfig,
-            }
+            },
+            withAttrs
         },
         templateMaker: {}
     }
@@ -361,6 +373,20 @@ const raConfig = {
 };
 ```
 
+## How can I set focus after a delay?
+
+Work is underway to improve the DX a bit, but for now:
+
+```JS
+{
+    delay:10, //milliseconds
+    ifAllOf: ['expanded'],
+    assign: {
+        set($.querySelector('a').focus()).to({}),
+    }
+},
+```
+
 ## Step 8
 
 Run `node el-maker.mjs` (or `npm run build-el-maker` if your `package.json` includes a watch script) to regenerate `el-maker.json`.

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

@@ -267,6 +267,17 @@ export interface IAssignGingerlyOptions {
    */
   aka?: Record<string, string>;
 
+  /**
+   * Value substitutions for path segments.
+   * Each key names a placeholder; the value is a `?.`-delimited path resolved
+   * against the source (`from`) object. The resolved string value replaces any
+   * matching whole path segment in RHS path strings before path evaluation.
+   * 
+   * Substitution values must be strings and must not contain the `?.` sequence,
+   * otherwise an error is thrown.
+   */
+  substitutions?: 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
@@ -357,6 +368,16 @@ export interface AssignFromOptions {
   /** Alias mappings for path segments */
   aka?: Record<string, string>;
 
+  /**
+   * Value substitutions for path segments.
+   * Each key names a placeholder; the value is a `?.`-delimited path resolved
+   * against `from`. The resolved string value replaces any matching whole path
+   * segment in RHS path strings before path evaluation.
+   * 
+   * Substitution values must be strings and must not contain `?.`.
+   */
+  substitutions?: Record<string, string>;
+
   /** AbortSignal for cleanup */
   signal?: AbortSignal;
 

package/inferencer/types/el-maker/types.d.ts

@@ -2,6 +2,7 @@ import {RAConfig} from '../roundabout/types.js';
 import {FontFaceFeatureConfig} from '../font-face-feature/types.js';
 import {CustomData as TSCD} from '../truth-sourcer/types.js';
 import {CustomData as FUCD} from '../face-up/types.js';
+import {AttrPatterns} from '../assign-gingerly/types.js';
 
 export interface ElMakerConfig<AllProps = any, TActions = AllProps> {
     assignFeatures: {
@@ -10,6 +11,7 @@ export interface ElMakerConfig<AllProps = any, TActions = AllProps> {
             customData: {
                 raConfig: RAConfig<AllProps, TActions, TActions>
             }
+            withAttrs: AttrPatterns<AllProps>
         },
         fontMgr?: {
             spawn?: string,

package/inferencer/types/roundabout/types.d.ts

@@ -161,6 +161,13 @@ export interface RAConfig<
     initialPropVals?: Partial<{[key in keyof TProps & string]: unknown}>,
 }
 
+// export interface RoundaboutFeatureConfig<
+//         TProps = unknown, TActions = TProps, ETProps = TProps, 
+//         TCustomData = unknown, TEvents extends string = string>{
+//             RAConfig: RAConfig<TProps, TActions, ETProps, TCustomData, TEvents>,
+            
+// } 
+
 export interface RoundaboutOptions<TProps = unknown, TActions = TProps, ETProps = TProps, EventTypes extends string = string> extends RAConfig<TProps, TActions, ETProps, unknown, EventTypes> {
     vm?: TProps & TActions & RoundaboutReady,
     //for enhanced elements, pass in the container, referenced via $0.

package/inferencer/types/swipe-dismiss/types.d.ts

@@ -0,0 +1,43 @@
+import { FeatureSpawnContext } from "../assign-gingerly/types";
+
+/**
+ * Public properties of the SwipeDismissFeature.
+ * These can be set directly on the feature instance or initialized via attributes.
+ */
+export interface SwipeDismissProps {
+    /** Axis along which the dismiss gesture is measured. */
+    axis: 'x' | 'y';
+    /**
+     * Direction that counts toward dismissal.
+     * 1 = right/down, -1 = left/up.
+     * Set to 'both' to allow swiping in either direction (e.g. toasts/snackbars).
+     */
+    direction: 1 | -1 | 'both';
+    /** Fraction of the panel size that triggers commit. */
+    distanceThreshold: number;
+    /** Velocity threshold in px/ms; a fast flick commits even under distanceThreshold. */
+    velocityThreshold: number;
+    /** CSS selector for the drag handle. Defaults to the host element. */
+    handleSelector: string | null;
+    /** CSS selector for the panel that visually follows the drag. Defaults to the handle. */
+    panelSelector: string | null;
+    /** Called on every pointermove with the current delta and fraction of the threshold. */
+    onProgress: ((deltaPx: number, fraction: number) => void) | null;
+    /** Called when the gesture crosses the commit threshold. */
+    onCommit: (() => void) | null;
+    /** Called when the gesture is released before the commit threshold. */
+    onCancel: (() => void) | null;
+}
+
+/**
+ * Internal state of the feature.
+ */
+export interface AllProps extends SwipeDismissProps {
+    /** WeakRef to the host custom element. */
+    hostRef: WeakRef<Element>;
+}
+
+export type AP = AllProps;
+export type PAP = Partial<AllProps>;
+
+export { FeatureSpawnContext };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "assign-gingerly",
-  "version": "0.0.82",
+  "version": "0.0.83",
   "description": "This package provides a utility function for carefully merging one object into another.",
   "homepage": "https://github.com/bahrus/assign-gingerly#readme",
   "bugs": {

package/processHandlerCommands.js

@@ -171,6 +171,7 @@ export async function processHandlerCommands(target, handlerKeys, pattern, optio
                 resolvedParams = getValues(config.get, options.from, {
                     withMethods: options.withMethods,
                     aka: options.aka,
+                    substitutions: options.substitutions,
                     protocols: options.protocols,
                     root: target
                 });
@@ -180,6 +181,7 @@ export async function processHandlerCommands(target, handlerKeys, pattern, optio
                 const asyncResolved = await resolveValues(config.resolve, options.from, {
                     withMethods: options.withMethods,
                     aka: options.aka,
+                    substitutions: options.substitutions,
                     protocols: options.protocols,
                     root: target
                 });

package/processHandlerCommands.ts

@@ -192,6 +192,7 @@ export async function processHandlerCommands(
                 resolvedParams = getValues(config.get, options.from, {
                     withMethods: options.withMethods,
                     aka: options.aka,
+                    substitutions: options.substitutions,
                     protocols: options.protocols,
                     root: target
                 });
@@ -201,6 +202,7 @@ export async function processHandlerCommands(
                 const asyncResolved = await resolveValues(config.resolve, options.from, {
                     withMethods: options.withMethods,
                     aka: options.aka,
+                    substitutions: options.substitutions,
                     protocols: options.protocols,
                     root: target
                 });

package/resolve/getValues.js

@@ -67,6 +67,45 @@ function applyAliases(path, aliasMap) {
     const substituted = parts.map(part => aliasMap.get(part) ?? part);
     return substituted.join('?.');
 }
+/**
+ * Apply value substitutions to a path string.
+ * Replaces complete tokens between `?.` delimiters with their resolved values.
+ * Substitutions are applied before aliases.
+ */
+function applySubstitutions(path, substitutionMap) {
+    if (!substitutionMap || substitutionMap.size === 0)
+        return path;
+    const parts = path.split('?.');
+    const substituted = parts.map(part => substitutionMap.get(part) ?? part);
+    return substituted.join('?.');
+}
+/**
+ * Resolve substitution values declared in options.substitutions.
+ * Each substitution path is resolved against the source object without
+ * applying substitutions itself, to avoid infinite recursion.
+ * Resolved values must be strings and must not contain `?.`.
+ */
+function resolveSubstitutions(substitutions, source, options) {
+    const map = new Map();
+    if (!substitutions)
+        return map;
+    for (const [name, path] of Object.entries(substitutions)) {
+        // Resolve the substitution path against the source, but do not apply
+        // substitutions to that path. Root references ($0) are also disabled
+        // for substitution paths so values are sourced from `from` only.
+        const resolved = getValue(path, source, options
+            ? { ...options, substitutions: undefined, root: undefined }
+            : undefined);
+        if (typeof resolved !== 'string') {
+            throw new Error(`Substitution '${name}' must resolve to a string, got ${typeof resolved}`);
+        }
+        if (resolved.includes('?.')) {
+            throw new Error(`Substitution '${name}' resolved to a string containing '?.', which would alter the path structure: '${resolved}'`);
+        }
+        map.set(name, resolved);
+    }
+    return map;
+}
 /**
  * Resolve a special root-reference token at the start of a string.
  * '$0' refers to the first argument passed to assignFrom / resolveValues.
@@ -159,12 +198,13 @@ function getProtocolValue(value, protocols, options) {
  * Resolve path strings and protocols within an array (synchronous).
  * Recurses into nested arrays and plain objects.
  */
-function getArray(arr, source, aliasMap, withMethods, protocols, options) {
+function getArray(arr, source, aliasMap, withMethods, protocols, options, substitutionMap) {
     const permissionProcessor = options?.permissionProcessor;
     const result = [];
     for (const item of arr) {
         if (typeof item === 'string' && item.startsWith('?.')) {
-            const aliased = applyAliases(item, aliasMap);
+            const substituted = applySubstitutions(item, substitutionMap);
+            const aliased = applyAliases(substituted, aliasMap);
             const parts = parseCachedPath(aliased);
             result.push(parts.length === 0 ? source : navigatePath(source, parts, withMethods, permissionProcessor));
         }
@@ -174,7 +214,8 @@ function getArray(arr, source, aliasMap, withMethods, protocols, options) {
                 result.push(source);
             }
             else {
-                const aliased = applyAliases(rootRef.path, aliasMap);
+                const substitutedPath = applySubstitutions(rootRef.path, substitutionMap);
+                const aliased = applyAliases(substitutedPath, aliasMap);
                 const normalizedPath = aliased.startsWith('?.') ? aliased : (aliased ? `?.${aliased}` : '?.');
                 const parts = parseCachedPath(normalizedPath);
                 result.push(parts.length === 0 ? rootRef.source : navigatePath(rootRef.source, parts, withMethods, permissionProcessor));
@@ -184,7 +225,7 @@ function getArray(arr, source, aliasMap, withMethods, protocols, options) {
             result.push(getProtocolValue(item, protocols, options));
         }
         else if (Array.isArray(item)) {
-            result.push(getArray(item, source, aliasMap, withMethods, protocols, options));
+            result.push(getArray(item, source, aliasMap, withMethods, protocols, options, substitutionMap));
         }
         else if (item && typeof item === 'object') {
             const proto = Object.getPrototypeOf(item);
@@ -215,12 +256,14 @@ function getArray(arr, source, aliasMap, withMethods, protocols, options) {
  */
 export function getValues(pattern, source, options) {
     const { aliasMap, withMethods } = normalizeAliasOptions(options);
+    const substitutionMap = resolveSubstitutions(options?.substitutions, source, options);
     const protocols = options?.protocols;
     const permissionProcessor = options?.permissionProcessor;
     const result = {};
     for (const [key, value] of Object.entries(pattern)) {
         if (typeof value === 'string' && value.startsWith('?.')) {
-            const aliased = applyAliases(value, aliasMap);
+            const substituted = applySubstitutions(value, substitutionMap);
+            const aliased = applyAliases(substituted, aliasMap);
             const parts = parseCachedPath(aliased);
             result[key] = parts.length === 0 ? source : navigatePath(source, parts, withMethods, permissionProcessor);
         }
@@ -230,7 +273,8 @@ export function getValues(pattern, source, options) {
                 result[key] = source;
             }
             else {
-                const aliased = applyAliases(rootRef.path, aliasMap);
+                const substitutedPath = applySubstitutions(rootRef.path, substitutionMap);
+                const aliased = applyAliases(substitutedPath, aliasMap);
                 const normalizedPath = aliased.startsWith('?.') ? aliased : (aliased ? `?.${aliased}` : '?.');
                 const parts = parseCachedPath(normalizedPath);
                 result[key] = parts.length === 0 ? rootRef.source : navigatePath(rootRef.source, parts, withMethods, permissionProcessor);
@@ -240,7 +284,7 @@ export function getValues(pattern, source, options) {
             result[key] = getProtocolValue(value, protocols, options);
         }
         else if (Array.isArray(value)) {
-            result[key] = getArray(value, source, aliasMap, withMethods, protocols, options);
+            result[key] = getArray(value, source, aliasMap, withMethods, protocols, options, substitutionMap);
         }
         else if (typeof value === 'object' && value !== null) {
             const proto = Object.getPrototypeOf(value);
@@ -274,10 +318,12 @@ export function getValue(path, source, options) {
     else if (!path.startsWith('?.')) {
         return path;
     }
-    let aliased = path;
+    const substitutionMap = resolveSubstitutions(options?.substitutions, source, options);
+    const substituted = applySubstitutions(path, substitutionMap);
+    let aliased = substituted;
     const { aliasMap } = normalizeAliasOptions(options);
     if (aliasMap.size > 0) {
-        aliased = applyAliases(path, aliasMap);
+        aliased = applyAliases(substituted, aliasMap);
     }
     const normalizedPath = aliased.startsWith('?.') ? aliased : (aliased ? `?.${aliased}` : '?.');
     const parts = parseCachedPath(normalizedPath);

package/resolve/getValues.ts

@@ -85,6 +85,58 @@ function applyAliases(path: string, aliasMap: Map<string, string>): string {
     return substituted.join('?.');
 }
 
+/**
+ * Apply value substitutions to a path string.
+ * Replaces complete tokens between `?.` delimiters with their resolved values.
+ * Substitutions are applied before aliases.
+ */
+function applySubstitutions(path: string, substitutionMap?: Map<string, string>): string {
+    if (!substitutionMap || substitutionMap.size === 0) return path;
+    const parts = path.split('?.');
+    const substituted = parts.map(part => substitutionMap.get(part) ?? part);
+    return substituted.join('?.');
+}
+
+/**
+ * Resolve substitution values declared in options.substitutions.
+ * Each substitution path is resolved against the source object without
+ * applying substitutions itself, to avoid infinite recursion.
+ * Resolved values must be strings and must not contain `?.`.
+ */
+function resolveSubstitutions(
+    substitutions: Record<string, string> | undefined,
+    source: any,
+    options: GetValuesOptions | undefined
+): Map<string, string> {
+    const map = new Map<string, string>();
+    if (!substitutions) return map;
+
+    for (const [name, path] of Object.entries(substitutions)) {
+        // Resolve the substitution path against the source, but do not apply
+        // substitutions to that path. Root references ($0) are also disabled
+        // for substitution paths so values are sourced from `from` only.
+        const resolved = getValue(
+            path,
+            source,
+            options
+                ? { ...options, substitutions: undefined, root: undefined }
+                : undefined
+        );
+        if (typeof resolved !== 'string') {
+            throw new Error(
+                `Substitution '${name}' must resolve to a string, got ${typeof resolved}`
+            );
+        }
+        if (resolved.includes('?.')) {
+            throw new Error(
+                `Substitution '${name}' resolved to a string containing '?.', which would alter the path structure: '${resolved}'`
+            );
+        }
+        map.set(name, resolved);
+    }
+    return map;
+}
+
 /**
  * Resolve a special root-reference token at the start of a string.
  * '$0' refers to the first argument passed to assignFrom / resolveValues.
@@ -200,13 +252,15 @@ function getArray(
     aliasMap: Map<string, string>,
     withMethods: Set<string> | undefined,
     protocols: Record<string, (key: string) => any> | undefined,
-    options?: GetValuesOptions
+    options?: GetValuesOptions,
+    substitutionMap?: Map<string, string>
 ): any[] {
     const permissionProcessor = options?.permissionProcessor;
     const result: any[] = [];
     for (const item of arr) {
         if (typeof item === 'string' && item.startsWith('?.')) {
-            const aliased = applyAliases(item, aliasMap);
+            const substituted = applySubstitutions(item, substitutionMap);
+            const aliased = applyAliases(substituted, aliasMap);
             const parts = parseCachedPath(aliased);
             result.push(parts.length === 0 ? source : navigatePath(source, parts, withMethods, permissionProcessor));
         } else if (typeof item === 'string' && item.startsWith('$0')) {
@@ -214,7 +268,8 @@ function getArray(
             if (rootRef === null) {
                 result.push(source);
             } else {
-                const aliased = applyAliases(rootRef.path, aliasMap);
+                const substitutedPath = applySubstitutions(rootRef.path, substitutionMap);
+                const aliased = applyAliases(substitutedPath, aliasMap);
                 const normalizedPath = aliased.startsWith('?.') ? aliased : (aliased ? `?.${aliased}` : '?.');
                 const parts = parseCachedPath(normalizedPath);
                 result.push(parts.length === 0 ? rootRef.source : navigatePath(rootRef.source, parts, withMethods, permissionProcessor));
@@ -222,7 +277,7 @@ function getArray(
         } else if (typeof item === 'string' && protocols && hasProtocol(item)) {
             result.push(getProtocolValue(item, protocols, options));
         } else if (Array.isArray(item)) {
-            result.push(getArray(item, source, aliasMap, withMethods, protocols, options));
+            result.push(getArray(item, source, aliasMap, withMethods, protocols, options, substitutionMap));
         } else if (item && typeof item === 'object') {
             const proto = Object.getPrototypeOf(item);
             if (proto === Object.prototype || proto === null) {
@@ -255,6 +310,7 @@ export function getValues(
     options?: GetValuesOptions
 ): Record<string, any> {
     const { aliasMap, withMethods } = normalizeAliasOptions(options);
+    const substitutionMap = resolveSubstitutions(options?.substitutions, source, options);
 
     const protocols = options?.protocols;
     const permissionProcessor = options?.permissionProcessor;
@@ -262,7 +318,8 @@ export function getValues(
     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 substituted = applySubstitutions(value, substitutionMap);
+            const aliased = applyAliases(substituted, aliasMap);
             const parts = parseCachedPath(aliased);
             result[key] = parts.length === 0 ? source : navigatePath(source, parts, withMethods, permissionProcessor);
         } else if (typeof value === 'string' && value.startsWith('$0')) {
@@ -270,7 +327,8 @@ export function getValues(
             if (rootRef === null) {
                 result[key] = source;
             } else {
-                const aliased = applyAliases(rootRef.path, aliasMap);
+                const substitutedPath = applySubstitutions(rootRef.path, substitutionMap);
+                const aliased = applyAliases(substitutedPath, aliasMap);
                 const normalizedPath = aliased.startsWith('?.') ? aliased : (aliased ? `?.${aliased}` : '?.');
                 const parts = parseCachedPath(normalizedPath);
                 result[key] = parts.length === 0 ? rootRef.source : navigatePath(rootRef.source, parts, withMethods, permissionProcessor);
@@ -278,7 +336,7 @@ export function getValues(
         } else if (typeof value === 'string' && protocols && hasProtocol(value)) {
             result[key] = getProtocolValue(value, protocols, options);
         } else if (Array.isArray(value)) {
-            result[key] = getArray(value, source, aliasMap, withMethods, protocols, options);
+            result[key] = getArray(value, source, aliasMap, withMethods, protocols, options, substitutionMap);
         } else if (typeof value === 'object' && value !== null) {
             const proto = Object.getPrototypeOf(value);
             if (proto === Object.prototype || proto === null) {
@@ -314,10 +372,13 @@ export function getValue(
         return path;
     }
 
-    let aliased = path;
+    const substitutionMap = resolveSubstitutions(options?.substitutions, source, options);
+
+    const substituted = applySubstitutions(path, substitutionMap);
+    let aliased = substituted;
     const { aliasMap } = normalizeAliasOptions(options);
     if (aliasMap.size > 0) {
-        aliased = applyAliases(path, aliasMap);
+        aliased = applyAliases(substituted, aliasMap);
     }
 
     const normalizedPath = aliased.startsWith('?.') ? aliased : (aliased ? `?.${aliased}` : '?.');

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

@@ -267,6 +267,17 @@ export interface IAssignGingerlyOptions {
    */
   aka?: Record<string, string>;
 
+  /**
+   * Value substitutions for path segments.
+   * Each key names a placeholder; the value is a `?.`-delimited path resolved
+   * against the source (`from`) object. The resolved string value replaces any
+   * matching whole path segment in RHS path strings before path evaluation.
+   * 
+   * Substitution values must be strings and must not contain the `?.` sequence,
+   * otherwise an error is thrown.
+   */
+  substitutions?: 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
@@ -357,6 +368,16 @@ export interface AssignFromOptions {
   /** Alias mappings for path segments */
   aka?: Record<string, string>;
 
+  /**
+   * Value substitutions for path segments.
+   * Each key names a placeholder; the value is a `?.`-delimited path resolved
+   * against `from`. The resolved string value replaces any matching whole path
+   * segment in RHS path strings before path evaluation.
+   * 
+   * Substitution values must be strings and must not contain `?.`.
+   */
+  substitutions?: Record<string, string>;
+
   /** AbortSignal for cleanup */
   signal?: AbortSignal;