assign-gingerly 0.0.57 → 0.0.59

package/assignFrom.js

@@ -1,45 +1,35 @@
 /**
- * Resolve RHS path strings against a source object, then assign the
- * resolved values into a target using assignGingerly.
+ * assignFrom.ts — Synchronous assign-from-source function.
  *
- * Combines resolveValues + assignGingerly into a single call.
- * Inherits all assignGingerly options (withMethods, aka, signal, etc.).
+ * Resolves RHS path strings synchronously via getValues, then assigns into the target.
+ * Supports looped substitution, #[x] refs, inferredAssignments, and handleSpreads — all sync.
  *
- * @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) and any assignGingerly options
- * @returns The target object after merging
+ * For async protocol handlers or awaitable handler execution, use assignFromAsync.
  *
- * @example
- * const source = { theme: { color: 'red' }, label: 'Hello' };
- * const target = { color: 'blue', text: '' };
- * assignFrom(target, {
- *   color: '?.theme?.color',
- *   text: '?.label'
- * }, { from: source });
- * // target is now { color: 'red', text: 'Hello' }
+ * Handler commands (` =>`) are fire-and-forget (kicked off asynchronously, not awaited).
  */
-import { resolveValues } from './resolveValues.js';
+import { getValues } from './getValues.js';
 import assignGingerly from './assignGingerly.js';
-/**
- * Check if a key ends with the handler operator ' =>'.
- */
-function isHandlerCommand(key) {
-    return key.endsWith(' =>');
-}
+import { resolveIdVariable, parseIdRef } from './resolveIdRef.js';
+import { processInferredAssignments } from './inferredAssignments.js';
 /**
  * Supported substitution variables and their option keys.
  */
-const SUBSTITUTION_VARS = [
+export const SUBSTITUTION_VARS = [
     { placeholder: '${x}', optionKey: 'where_x_in' },
     { placeholder: '${y}', optionKey: 'where_y_in' },
     { placeholder: '${z}', optionKey: 'where_z_in' },
 ];
+/**
+ * Check if a key ends with the handler operator ' =>'.
+ */
+export function isHandlerCommand(key) {
+    return key.endsWith(' =>');
+}
 /**
  * Recursively substitute a placeholder in all string values of an object.
- * Returns a new object (shallow clone at each level) with substitutions applied.
  */
-function substituteInValue(value, placeholder, replacement) {
+export function substituteInValue(value, placeholder, replacement) {
     if (typeof value === 'string') {
         return value.includes(placeholder) ? value.replaceAll(placeholder, replacement) : value;
     }
@@ -61,7 +51,7 @@ function substituteInValue(value, placeholder, replacement) {
 /**
  * Check if a pattern entry (key + value) contains a given placeholder.
  */
-function entryContainsPlaceholder(key, value, placeholder) {
+export function entryContainsPlaceholder(key, value, placeholder) {
     if (key.includes(placeholder))
         return true;
     return valueContainsPlaceholder(value, placeholder);
@@ -69,7 +59,7 @@ function entryContainsPlaceholder(key, value, placeholder) {
 /**
  * Check if a value (string, object, or array) contains a placeholder.
  */
-function valueContainsPlaceholder(value, placeholder) {
+export function valueContainsPlaceholder(value, placeholder) {
     if (typeof value === 'string')
         return value.includes(placeholder);
     if (Array.isArray(value))
@@ -84,12 +74,8 @@ function valueContainsPlaceholder(value, placeholder) {
 }
 /**
  * Expand looped substitution variables in a pattern.
- * Applies cartesian expansion: x values are expanded first, then y, then z.
- * Each variable multiplies the entries — result count = x.length × y.length × z.length.
- *
- * Returns the expanded pattern (or the original if no substitutions apply).
  */
-function expandSubstitutions(pattern, options) {
+export function expandSubstitutions(pattern, options) {
     let entries = Object.entries(pattern);
     for (const { placeholder, optionKey } of SUBSTITUTION_VARS) {
         const values = options[optionKey];
@@ -98,7 +84,6 @@ function expandSubstitutions(pattern, options) {
         const expanded = [];
         for (const [key, value] of entries) {
             if (entryContainsPlaceholder(key, value, placeholder)) {
-                // Expand this entry for each value in the variable array
                 for (const replacement of values) {
                     const newKey = key.includes(placeholder)
                         ? key.replaceAll(placeholder, replacement)
@@ -108,7 +93,6 @@ function expandSubstitutions(pattern, options) {
                 }
             }
             else {
-                // No placeholder in this entry — pass through
                 expanded.push([key, value]);
             }
         }
@@ -118,14 +102,11 @@ function expandSubstitutions(pattern, options) {
 }
 /**
  * Convert entries to an object, merging duplicate handler (` =>`) keys into arrays.
- * For normal (non-handler) keys, later entries overwrite earlier ones (standard object behavior).
- * For handler keys, duplicate entries are combined into an array (Multiple Handlers pattern).
  */
-function mergeHandlerDuplicates(entries) {
+export function mergeHandlerDuplicates(entries) {
     const result = {};
     for (const [key, value] of entries) {
         if (key.endsWith(' =>') && key in result) {
-            // Duplicate handler key — merge into array
             const existing = result[key];
             if (Array.isArray(existing)) {
                 existing.push(value);
@@ -140,10 +121,31 @@ function mergeHandlerDuplicates(entries) {
     }
     return result;
 }
-export async function assignFrom(target, pattern, options, permissions) {
-    // First: expand looped substitution variables (${x}, ${y}, ${z})
-    const expandedPattern = expandSubstitutions(pattern, options);
-    // Separate handler commands ( =>), #[x] keys, and normal keys
+/**
+ * Recursively walk an object and handle "..." spread keys.
+ */
+export function handleSpreads(obj) {
+    for (const [key, value] of Object.entries(obj)) {
+        if (key !== '...' && typeof value === 'object' && value !== null && !Array.isArray(value)) {
+            const proto = Object.getPrototypeOf(value);
+            if (proto === Object.prototype || proto === null) {
+                obj[key] = handleSpreads(value);
+            }
+        }
+    }
+    if ('...' in obj) {
+        const spreadValue = obj['...'];
+        delete obj['...'];
+        if (spreadValue && typeof spreadValue === 'object') {
+            Object.assign(obj, spreadValue);
+        }
+    }
+    return obj;
+}
+/**
+ * Categorize pattern keys into handler keys, #[x] keys, and normal keys.
+ */
+export function categorizeKeys(expandedPattern) {
     const handlerKeys = [];
     const normalPattern = {};
     const idRefNormalKeys = [];
@@ -164,113 +166,106 @@ export async function assignFrom(target, pattern, options, permissions) {
             normalPattern[key] = expandedPattern[key];
         }
     }
-    // Process normal keys via resolveValues + assignGingerly
+    return { handlerKeys, normalPattern, idRefNormalKeys, idRefHandlerKeys };
+}
+/**
+ * Process #[x] normal keys synchronously.
+ */
+function processIdRefNormalKeys(idRefNormalKeys, expandedPattern, target, options) {
+    if (!options.withIds)
+        return;
+    for (const key of idRefNormalKeys) {
+        const parsed = parseIdRef(key);
+        if (!parsed)
+            continue;
+        const el = resolveIdVariable(parsed.varName, target, options.withIds);
+        if (!el)
+            continue;
+        const value = expandedPattern[key];
+        if (parsed.remainingPath) {
+            const resolvedValue = getValues({ __v: value }, options.from, { withMethods: options.withMethods, aka: options.aka, protocols: options.protocols });
+            assignGingerly(el, { [parsed.remainingPath]: resolvedValue.__v }, options);
+        }
+        else {
+            const resolvedValue = getValues(typeof value === 'object' && value !== null ? value : { __v: value }, options.from, { withMethods: options.withMethods, aka: options.aka, protocols: options.protocols });
+            if (!('__v' in resolvedValue)) {
+                assignGingerly(el, resolvedValue, options);
+            }
+        }
+    }
+}
+/**
+ * Synchronous assignFrom — resolves values, assigns to target, all without awaiting.
+ *
+ * Handler commands (` =>`), beVigilant, and enhance are fire-and-forget (async, non-blocking).
+ * For awaitable handler execution, use assignFromAsync.
+ *
+ * @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
+ * @returns The target object after merging
+ */
+export function assignFrom(target, pattern, options, permissions) {
+    // Expand looped substitution variables
+    const expandedPattern = expandSubstitutions(pattern, options);
+    // Categorize keys
+    const { handlerKeys, normalPattern, idRefNormalKeys, idRefHandlerKeys } = categorizeKeys(expandedPattern);
+    // Process normal keys via getValues (sync) + assignGingerly
     if (Object.keys(normalPattern).length > 0) {
-        const resolved = await resolveValues(normalPattern, options.from, {
+        const resolved = getValues(normalPattern, options.from, {
             withMethods: options.withMethods,
             aka: options.aka,
             protocols: options.protocols
         });
-        // Recursively handle "..." spread keys at all nesting levels
         handleSpreads(resolved);
         assignGingerly(target, resolved, options);
     }
-    // Process #[x] normal keys — resolve element, then apply remaining path + value
-    if (idRefNormalKeys.length > 0 && options.withIds) {
-        const { resolveIdVariable, parseIdRef } = await import('./resolveIdRef.js');
-        for (const key of idRefNormalKeys) {
-            const parsed = parseIdRef(key);
-            if (!parsed)
-                continue;
-            const el = resolveIdVariable(parsed.varName, target, options.withIds);
-            if (!el)
-                continue;
-            const value = expandedPattern[key];
-            if (parsed.remainingPath) {
-                // Resolve the RHS value
-                const resolvedValue = await resolveValues({ __v: value }, options.from, { withMethods: options.withMethods, aka: options.aka, protocols: options.protocols });
-                // Apply remaining path on the resolved element
-                assignGingerly(el, { [parsed.remainingPath]: resolvedValue.__v }, options);
-            }
-            else {
-                // No remaining path — resolve and assign directly to the element
-                const resolvedValue = await resolveValues(typeof value === 'object' && value !== null ? value : { __v: value }, options.from, { withMethods: options.withMethods, aka: options.aka, protocols: options.protocols });
-                if ('__v' in resolvedValue) {
-                    // Single value — can't assign to element root without a path
-                }
-                else {
-                    assignGingerly(el, resolvedValue, options);
-                }
-            }
-        }
+    // Process #[x] normal keys (sync)
+    if (idRefNormalKeys.length > 0) {
+        processIdRefNormalKeys(idRefNormalKeys, expandedPattern, target, options);
     }
-    // Process handler commands ( =>) — dynamically imported only when needed
+    // Process handler commands — fire-and-forget (async)
     if (handlerKeys.length > 0) {
-        const { processHandlerCommands } = await import('./processHandlerCommands.js');
-        await processHandlerCommands(target, handlerKeys, expandedPattern, options, permissions);
+        import('./processHandlerCommands.js').then(({ processHandlerCommands }) => {
+            processHandlerCommands(target, handlerKeys, expandedPattern, options, permissions);
+        });
     }
-    // Process #[x] handler keys — resolve element, then pass to handler processing
+    // Process #[x] handler keys — fire-and-forget (async)
     if (idRefHandlerKeys.length > 0 && options.withIds) {
-        const { resolveIdVariable, parseIdRef } = await import('./resolveIdRef.js');
-        const { processHandlerCommands } = await import('./processHandlerCommands.js');
-        for (const key of idRefHandlerKeys) {
-            const parsed = parseIdRef(key);
-            if (!parsed)
-                continue;
-            const el = resolveIdVariable(parsed.varName, target, options.withIds);
-            if (!el)
-                continue;
-            // Build a synthetic key for processHandlerCommands:
-            // The resolved element becomes the target, remaining path is the LHS
-            const syntheticKey = parsed.remainingPath
-                ? `${parsed.remainingPath} =>`
-                : ' =>';
-            const syntheticPattern = {
-                [syntheticKey]: expandedPattern[key]
-            };
-            await processHandlerCommands(el, [syntheticKey], syntheticPattern, options, permissions);
-        }
+        import('./processHandlerCommands.js').then(({ processHandlerCommands }) => {
+            for (const key of idRefHandlerKeys) {
+                const parsed = parseIdRef(key);
+                if (!parsed)
+                    continue;
+                const el = resolveIdVariable(parsed.varName, target, options.withIds);
+                if (!el)
+                    continue;
+                const syntheticKey = parsed.remainingPath ? `${parsed.remainingPath} =>` : ' =>';
+                const syntheticPattern = { [syntheticKey]: expandedPattern[key] };
+                processHandlerCommands(el, [syntheticKey], syntheticPattern, options, permissions);
+            }
+        });
     }
-    // Process inferred assignments — dynamically imported only when option is present
+    // Process inferred assignments (sync)
     if (options.inferredAssignments) {
-        const { processInferredAssignments } = await import('./inferredAssignments.js');
-        await processInferredAssignments(target, options.from, options.inferredAssignments);
-        // Set up MutationObserver for new matching elements if beVigilant
+        processInferredAssignments(target, options.from, options.inferredAssignments);
+        // beVigilant — fire-and-forget (async)
         if (options.inferredAssignments.beVigilant) {
             if (!options.signal) {
                 throw new Error('assignFrom: inferredAssignments.beVigilant requires options.signal (AbortSignal) for cleanup');
             }
-            const { setupVigilantObserver } = await import('./beVigilant.js');
-            setupVigilantObserver(target, options.from, options.inferredAssignments, options.signal);
+            import('./beVigilant.js').then(({ setupVigilantObserver }) => {
+                setupVigilantObserver(target, options.from, options.inferredAssignments, options.signal);
+            });
         }
     }
-    // Process bulk enhancements — dynamically imported only when option is present
+    // Process bulk enhancements — fire-and-forget (async)
     if (options.enhance && options.enhance.length > 0) {
-        const { enhanceAll } = await import('./enhanceAll.js');
-        await enhanceAll(target, options.enhance, permissions);
+        import('./enhanceAll.js').then(({ enhanceAll }) => {
+            enhanceAll(target, options.enhance, permissions);
+        });
     }
     return target;
 }
-/**
- * Recursively walk an object and handle "..." spread keys.
- * When a "..." key is found, its value (which should be an object after protocol resolution)
- * is spread into the parent, replacing the "..." entry.
- */
-function handleSpreads(obj) {
-    for (const [key, value] of Object.entries(obj)) {
-        if (key !== '...' && typeof value === 'object' && value !== null && !Array.isArray(value)) {
-            const proto = Object.getPrototypeOf(value);
-            if (proto === Object.prototype || proto === null) {
-                obj[key] = handleSpreads(value);
-            }
-        }
-    }
-    if ('...' in obj) {
-        const spreadValue = obj['...'];
-        delete obj['...'];
-        if (spreadValue && typeof spreadValue === 'object') {
-            Object.assign(obj, spreadValue);
-        }
-    }
-    return obj;
-}
+export default assignFrom;